#typescript/src/parse

#typescript/src/parse

Parse pipeline: reserved-flag pre-scan, two-phase global-flag parsing, command-token parsing, env/config/default resolution, and constraint validation. Mirrors Go doParse/extractGlobalFlags/parseCommand (strictcli.go, parse.go) with Python _parse/_parse_global_flags/ _parse_command as the divergence ground truth.

Internal contract: helpers throw ParseError; doParse converts them into "parse-error" outcomes at the two sibling catch boundaries (global-flag parsing without a command prefix, command parsing with the full "app path command" prefix). Help/version/schema/mcp requests are outcome variants, not exceptions; rendering them is help.ts/app-runner territory.

#flagParamName

export function flagParamName(flagName: string): string

Converts a flag name like "dry-run" to its handler-args key "dry_run".

#ConfigLoadResult

export interface ConfigLoadResult

#ConfigProvider

export interface ConfigProvider

Injectable config-values provider. Phase 5 implements file loading and per-flag coercion; the parse pipeline owns precedence and conflict semantics so they are already exact here.

#emptyConfigProvider

export const emptyConfigProvider: ConfigProvider =

#valuesEqualForConflict

export function valuesEqualForConflict(

Conflict-mode equality (pinned by the siblings): scalars exact, plain lists order-sensitive, unique flags order-insensitive multiset equality.

#applyFlagDefault

export function applyFlagDefault(

Resolves the value of a flag that was not provided by CLI, env, or config. Throws ParseError when the flag is required. prefix is "" for command flags and "global " for global flags. A relativeToRoot() marker default resolves through the declared infra roots and reports source "infra" (distinguishable from a plain default); hermetic mode never suppresses it (roots were resolved at construction, with no argv dependency). Exported for invoke.ts (programmatic invocation applies global defaults).

#ParsedCommand

export interface ParsedCommand

#parseCommand

export function parseCommand(

Parses tokens against a resolved command's flags and args. Global flags are also recognized in post-command tokens and returned separately so the caller can merge them with pre-command globals. Throws ParseError.

#validateAndBuildKwargs

export function validateAndBuildKwargs(

Second half of command parsing: mutex enforcement, implies resolution, dependency checks, defaults, choices, custom validation, positional-arg resolution, and kwargs assembly, all on sourced values. Exported for invoke.ts, which feeds it a store populated from pre-typed kwargs.

#ExtractedGlobals

export interface ExtractedGlobals

#extractGlobalFlags

export function extractGlobalFlags(

Scans argv for global flag tokens before the command name. Stops at the first non-flag token (the command name), at "--" (kept in remaining), or at an unknown flag-like token. Resolves env, config, defaults, and choices for global flags. Throws ParseError.

#PreScanResult

export interface PreScanResult

#preScanReservedFlags

export function preScanReservedFlags(

Pre-scan for the framework-owned reserved flags. Two regions, two rulesets (contract §7.2, amended):

• The pre-command region -- before the first non-flag token, before "--" --

recognizes every reserved flag (--dump-schema, --mcp, --config, --hermetic and the quartet). Known global flags and their values are skipped so a global-flag value that looks like a command name does not end it early.

• The command region recognizes ONLY the quartet

(--dry-run/--approve-consequential/--quiet/--verbose), anywhere, exactly like --help/-h. --hermetic/--config/--dump-schema/--mcp stay pre-command-only. See scanCommandRegionQuartet.

The quartet is stripped from argv here and delivered on the Context, never as handler kwargs -- injecting four mandatory parameters into every handler would contradict guard v2, and the Context needs the values for its own output gating regardless.

#reservedFlagsOf

export function reservedFlagsOf(pre: PreScanResult): ReservedFlags

Narrows a pre-scan result to the four Context-delivered flag values.

#HelpTarget

export type HelpTarget =

#ParseOutcome

export type ParseOutcome =

#DoParseDeps

export interface DoParseDeps

#tokensContainHelp

export function tokensContainHelp(tokens: readonly string[]): boolean

Checks if --help or -h appears in tokens before any "--" separator.

#doParse

export function doParse(

Parses argv (without program name) into a ParseOutcome. Exactly one variant applies: help, version, dump-schema, mcp, parse-error, command, or passthrough.

#formatParseErrorOutput

export function formatParseErrorOutput(

Renders the exact two-line stderr surface for a parse error: "error: \ntry ' --help'\n". The prefix is the routed command prefix when available, else the app name.