#typescript/src/factories

#typescript/src/factories

Declaration factories: flag and arg descriptors, dependency descriptors, and command carriers, all built through const-typed option objects. The const type parameters preserve literal names and exact option-object types without as const at call sites.

Validation runs at construction time, mirroring the siblings (Go validateFlagConfig / Python Flag.__post_init__ run when the flag value is built, and buildAndValidateCommand runs at registration). Messages are byte-identical to the siblings; where Go and Python disagree, the Python implementation is the captured ground truth (see tests/registration.test.ts). App-context checks (global-flag collisions, env prefixes) live in app.ts.

#pyRepr

export function pyRepr(v: unknown): string

Python repr() for the value kinds that appear in registration errors. bigint is the TS int type (repr like a Python int); number is the TS float type (integral values render with a trailing .0, like a Python float).

#pyTypeName

export function pyTypeName(v: unknown): string

strictcli type name of a runtime value (str/bool/int/float vocabulary).

#ElementOf

export type ElementOf<Out> = Out extends readonly (infer E)[] ? E : Out

Extracts the element type from a list output type, or returns the type itself for scalars/dicts.

#ConflictMode

export type ConflictMode = "cli-wins" | "error"

How to resolve a flag set in both CLI args and config: "cli-wins" keeps the CLI value, "error" rejects the conflict.

#FlagOpts

export type FlagOpts<Out, S extends Schema> =

Per-carrier option surface. Inapplicable options are never-typed so they cannot be provided at all: negatable is bool-only; choices exclude bool and dict; envSeparator/repeatable/unique are list-only (list carriers are the only repeatable flags in TS -- scalar repeatable: true does not exist).

#FlagDef

export interface FlagDef<

A fully typed flag descriptor produced by the flag() factory.

#AnyFlag

export interface AnyFlag

Structural supertype of every FlagDef instantiation. Deliberately loose on opts (exact option types vary per flag) so concrete defs assign without variance traps.

#FlagOptsView

export interface FlagOptsView

Runtime view of a flag's options. The generic option surface narrows inapplicable options to never per carrier; validation reads them uniformly through this widened shape.

#flagOpts

export function flagOpts(f: AnyFlag): FlagOptsView

Widened options of a flag descriptor, for runtime validation and parsing.

#schemaKind

export function schemaKind(schema: Schema): "scalar" | "list" | "dict"

Structural kind of a schema string (also used by env.ts/parse-side modules).

#elemSchemaOf

export function elemSchemaOf(carrier: Carrier<unknown, Schema>): ScalarSchema

Element schema of a carrier: the item/value schema for compounds, the schema itself for scalars.

#RESERVED_FRAMEWORK_FLAG_NAMES

export const RESERVED_FRAMEWORK_FLAG_NAMES: ReadonlySet<string> = new Set([

The four flag names the effects regime reserves for the framework. The ban is UNCONDITIONAL and applies at every level -- command flags, flag-set flags, mutex-group flags and app global flags -- because the framework extracts them in the position-aware pre-scan and delivers them on the Context.

Declared here rather than in app.ts so factories.ts can enforce the ban without importing app.ts (which imports this module); app.ts folds this set into its own RESERVED_GLOBAL_FLAG_NAMES.

The four have NO short forms, so short-flag names are unaffected.

#BANNED_FLAG_NAMES

export const BANNED_FLAG_NAMES: ReadonlySet<string> = new Set(["yes"])

Names the framework refuses outright without owning a flag of that name.

yes is here because --approve-consequential replaced --yes (contract §7.1) and a private --yes would restate it in a spelling that IS muscle memory -- exactly what the rename removed.

#RESERVED_CONSENT_PARAM_NAME

export const RESERVED_CONSENT_PARAM_NAME = "approve_consequential"

The programmatic consent PARAMETER name, reserved on both the flag surface and the arg surface at every level.

TS kwargs are an options object, so a parameter of this name cannot shadow CallOptions.approveConsequential the way Python's keyword-only consent parameter would -- but the name is framework vocabulary in every implementation (app.call, Tool.execute, the MCP tools/call param), and a command must mean the same thing on every channel and in every language. RESERVED_FRAMEWORK_FLAG_NAMES covers the FLAG spelling approve-consequential; this covers the underscore spelling the parameter surface uses, and it is the one reserved name that reaches positional args.

#flag

export function flag<

Creates a flag descriptor for use in defineCommand(). Validates the flag configuration at construction time (help text, default type, choices, etc.).

#ArgOpts

export type ArgOpts<Out, S extends ScalarSchema> =

Args take scalar carriers only; a variadic arg collects Out[] (the list-arg shape from the siblings is expressed as scalar carrier + variadic: true). default is only meaningful with required: false (required is the arg default, matching the siblings).

#ArgDef

export interface ArgDef<

A fully typed positional argument descriptor produced by the arg() factory.

#AnyArg

export interface AnyArg

Structural supertype of every ArgDef instantiation.

#ArgOptsView

export interface ArgOptsView

Runtime view of an arg's options (see FlagOptsView).

#arg

export function arg<

Creates a positional argument descriptor for use in defineCommand(). Args take scalar carriers only; variadic args (variadic: true) collect an array.

#FlagSet

export interface FlagSet<N extends string, F extends FlagMap>

A named group of flags that can be shared across multiple commands.

#AnyFlagSet

export interface AnyFlagSet

Structural supertype of every FlagSet instantiation.

#flagSet

export function flagSet<const N extends string, const F extends FlagMap>(

Creates a named flag set for sharing flags across commands.

#MutexGroup

export interface MutexGroup<F extends FlagMap>

A group of mutually exclusive flags -- at most one may be provided per invocation.

#AnyMutexGroup

export interface AnyMutexGroup

Structural supertype of every MutexGroup instantiation.

#mutexGroup

export function mutexGroup<const F extends FlagMap>(flags: F): MutexGroup<F>

Creates a mutex group: at most one of the given flags may be provided.

#CoRequired

export interface CoRequired

Constraint: the listed flags must all be provided together or all be absent.

#coRequired

export function coRequired(flags: readonly string[]): CoRequired

Creates a co-required constraint: all listed flags must appear together.

#Requires

export interface Requires

Constraint: when flag is provided, dependsOn must also be provided.

#requires

export function requires(spec:

Creates a one-way dependency: flag requires dependsOn to also be set.

#Implies

export interface Implies

Constraint: when flag is provided, implies is automatically set to value. Both must be bool flags.

#implies

export function implies(spec:

Creates an implication: when flag is set, auto-sets implies to value. Both must be bool flags.

#Dependency

export type Dependency = CoRequired | Requires | Implies

Union of all inter-flag dependency constraint types.

#FlagMap

export type FlagMap = Readonly<Record<string, AnyFlag>>

A keyed map of flags where the key is the underscore form of the flag name (also the handler arg key).

#Handler

export type Handler<

A command handler function receiving typed args and a Context.

C is the classification-narrowed context type: defineReadOnlyCommand binds it to ReadOnlyContext (whose effects exposes only run), and defineMutatingCommand to the full MutatingContext. A .write() inside a read-only command is therefore a COMPILE error, on top of the runtime seal every implementation carries regardless (plain-JS consumers bypass the type system entirely).

#CommandDef

export interface CommandDef<

A fully validated command descriptor produced by the twin factories.

#AnyCommand

export interface AnyCommand

Structural supertype of every CommandDef instantiation.

#ReadOnlyCommandSpec

export interface ReadOnlyCommandSpec<

Configuration passed to defineReadOnlyCommand(). Identical to MutatingCommandSpec except for the context type the handler's ctx parameter is narrowed to (§2.4).

#MutatingCommandSpec

export interface MutatingCommandSpec<

Configuration passed to defineMutatingCommand().

#validateGrants

export function validateGrants(

Validates a command's grant declarations at registration time.

#validateDryRunDeclaration

export function validateDryRunDeclaration(

The three registration-time guards on the dry-run declaration, shared by the ordinary and passthrough builders so both surfaces reject the same shapes with the same messages.

#validateForwarding

export function validateForwarding(

Validates a declared-forwarding declaration at registration time.

#validateAndDedupTags

export function validateAndDedupTags(

Validates tag names and removes duplicates, preserving order.

#defineReadOnlyCommand

export function defineReadOnlyCommand<

Creates a read_only command descriptor with typed flags, args, flag sets, mutex groups, and dependencies. Validates all constraints at construction time.

A read_only command never prompts (§8) and cannot be declared consequential; calling any mutating member of the effects handle is a hard error at call time. Its handler's ctx is narrowed to ReadOnlyContext, so ctx.effects.write(...) does not compile.

#defineMutatingCommand

export function defineMutatingCommand<

Creates a mutating command descriptor with typed flags, args, flag sets, mutex groups, and dependencies. Validates all constraints at construction time.

A mutating command participates in dry mode and may call every member of the effects handle. It does NOT prompt unless it also declares consequential: true (§8.1).

#PassthroughArgs

export interface PassthroughArgs

Arguments passed to a passthrough command handler: the command name, raw args, and global flag values.

#PassthroughHandler

export type PassthroughHandler<C = MutatingContext> = (

Handler function for passthrough commands (receives raw args, no parsing).

#PassthroughDef

export interface PassthroughDef<N extends string, C = MutatingContext>

A passthrough command descriptor produced by the passthrough twins.

#readOnlyPassthrough

export function readOnlyPassthrough<const N extends string>(

Creates a read_only passthrough command that bypasses all flag/arg parsing. The handler receives the raw argument list and global flag values, and never prompts. It cannot be declared consequential.

#mutatingPassthrough

export function mutatingPassthrough<const N extends string>(

Creates a mutating passthrough command that bypasses all flag/arg parsing.

A mutating passthrough is NOT exempt from the confirm protocol when it declares consequential: true: that its args are opaque to the framework is a reason to confirm, not a reason to skip -- the framework knows less about what is about to happen, not more.

#DeprecatedDef

export interface DeprecatedDef<N extends string>

A deprecated command descriptor produced by the deprecated() factory.

#deprecated

export function deprecated<const N extends string>(

Creates a deprecated command entry that prints a message to stderr and exits 1 when invoked.