import { buildPrimaryEnvVarName, parseSourceValue } from '@agent-device/kernel/source-value'; import { listCliCommandNames } from '@agent-device/command-registry/catalog'; import { GLOBAL_FLAG_KEYS } from '@agent-device/command-registry/flag-groups'; import { getFlagDefinitions } from '@agent-device/command-registry/flag-registry'; import type { FlagDefinition, FlagKey } from '@agent-device/command-registry/flag-types'; import { getCliCommandSchema } from './command-schema.ts'; export type OptionSpec = { key: FlagKey; flagDefinitions: readonly FlagDefinition[]; configurable: boolean; env: { names: readonly string[]; }; supportsCommand(command: string | null): boolean; }; const CONFIG_EXCLUDED_FLAG_KEYS = new Set([ 'config', 'remoteConfig', 'help', 'version', 'batchSteps', 'githubActionsArtifact', // A default must never switch a fill to waiting on stdin. 'textStdin', ]); const ENV_EXCLUDED_FLAG_KEYS = new Set([ 'appsFilter', 'iosSimulatorDeviceSet', 'textStdin', // The proxy lease device spec comes from a flag or `connect proxy`, never ambient environment. 'osVersion', 'imageTag', 'physical', ]); const optionSpecs = buildOptionSpecs(); const optionSpecByKey = new Map(optionSpecs.map((spec) => [spec.key, spec])); export function getOptionSpec(key: FlagKey): OptionSpec | undefined { return optionSpecByKey.get(key); } export function getConfigurableOptionSpecs(command: string | null): OptionSpec[] { return optionSpecs.filter((spec) => spec.configurable && spec.supportsCommand(command)); } export function isFlagSupportedForCommand(key: FlagKey, command: string | null): boolean { return getOptionSpec(key)?.supportsCommand(command) ?? false; } export function parseOptionValueFromSource( spec: OptionSpec, value: unknown, sourceLabel: string, rawKey: string, ): unknown { return parseSourceValue(resolveSourceValueDefinition(spec), value, sourceLabel, rawKey); } function buildOptionSpecs(): OptionSpec[] { const definitionsByKey = new Map(); for (const definition of getFlagDefinitions()) { const existing = definitionsByKey.get(definition.key); if (existing) existing.push(definition); else definitionsByKey.set(definition.key, [definition]); } const supportedCommandsByKey = new Map>(); for (const key of GLOBAL_FLAG_KEYS) { supportedCommandsByKey.set(key, new Set(['*'])); } for (const command of listCliCommandNames()) { const schema = getCliCommandSchema(command); for (const key of [...(schema.allowedFlags ?? []), ...(schema.supportedFlags ?? [])]) { const existing = supportedCommandsByKey.get(key); if (existing && existing.has('*')) continue; if (existing) existing.add(command); else supportedCommandsByKey.set(key, new Set([command])); } } return [...definitionsByKey.entries()] .map(([key, flagDefinitions]) => ({ key, flagDefinitions, configurable: !CONFIG_EXCLUDED_FLAG_KEYS.has(key), env: { names: ENV_EXCLUDED_FLAG_KEYS.has(key) ? [] : [buildPrimaryEnvVarName(key)], }, supportsCommand(command: string | null): boolean { const supported = supportedCommandsByKey.get(key); if (!supported) return false; if (supported.has('*')) return true; if (!command) return false; return supported.has(command); }, })) .sort((left, right) => compareOptionKeys(left.key, right.key)); } /** * Case-insensitive-then-codepoint ordering, matching what `localeCompare` * produces for the ASCII flag-key vocabulary. This runs at module load on * every CLI invocation, and the FIRST `localeCompare` in a process pays ~5ms * of ICU collator initialization — a cost the CLI otherwise never incurs. */ function compareOptionKeys(left: string, right: string): number { const leftLower = left.toLowerCase(); const rightLower = right.toLowerCase(); if (leftLower !== rightLower) return leftLower < rightLower ? -1 : 1; return left < right ? -1 : left > right ? 1 : 0; } function primaryFlagDefinition(spec: OptionSpec): FlagDefinition { const definition = spec.flagDefinitions[0]; if (!definition) { throw new Error(`Missing flag definition for option ${spec.key}`); } return definition; } export function resolveSourceValueDefinition(spec: OptionSpec): FlagDefinition { const explicitValueDefinition = spec.flagDefinitions.find( (definition) => definition.setValue === undefined, ); if (explicitValueDefinition) return explicitValueDefinition; const baseDefinition = primaryFlagDefinition(spec); if (baseDefinition.type === 'enum') { const enumValues = baseDefinition.enumValues ?? spec.flagDefinitions .map((definition) => definition.setValue) .filter((value): value is NonNullable => value !== undefined); return { ...baseDefinition, setValue: undefined, enumValues: enumValues as readonly string[], }; } return baseDefinition; }