@crustjs/core 0.0.19 → 0.2.0

package/dist/types-DjMHz7M6.d.ts

@@ -0,0 +1,828 @@
+//#region ../utils/src/json.d.ts
+/** Any value representable in a JSON document. */
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | JsonObject;
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+/** Preserve a type when all of its properties are recursively JSON-compatible. */
+type JsonCompatible<T> = T extends JsonValue ? T : T extends ((...arguments_: never[]) => void) ? never : T extends readonly unknown[] ? { [K in keyof T]: JsonCompatible<T[K]>; } : T extends object ? { [K in keyof T]: JsonCompatible<T[K]>; } : never;
+//#endregion
+//#region ../utils/src/primitive.d.ts
+/** Supported primitive type literals shared by Crust packages. */
+type BaseValueType = "string" | "number" | "boolean";
+//#endregion
+//#region ../utils/src/schema.d.ts
+/** The Standard Typed types interface. */
+interface StandardSchemaTypes<Input = unknown, Output = Input> {
+  /** The input type of the schema. */
+  readonly input: Input;
+  /** The output type of the schema. */
+  readonly output: Output;
+}
+/** The result interface if validation succeeds. */
+interface StandardSchemaSuccessResult<Output> {
+  /** The typed output value. */
+  readonly value: Output;
+  /** A falsy value for `issues` indicates success. */
+  readonly issues?: undefined;
+}
+/** The result interface if validation fails. */
+interface StandardSchemaFailureResult {
+  /** The issues of failed validation. */
+  readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+/** The result interface of the validate function. */
+type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
+/** The issue interface of the failure output. */
+interface StandardSchemaIssue {
+  /** The error message of the issue. */
+  readonly message: string;
+  /** The path of the issue, if any. */
+  readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
+}
+/** The path segment interface of the issue. */
+interface StandardSchemaPathSegment {
+  /** The key representing a path segment. */
+  readonly key: PropertyKey;
+}
+/** The Standard Schema properties interface. */
+interface StandardSchemaProps<Input = unknown, Output = Input> {
+  /** The version number of the standard. */
+  readonly version: 1;
+  /** The vendor name of the schema library. */
+  readonly vendor: string;
+  /** Inferred types associated with the schema. */
+  readonly types?: StandardSchemaTypes<Input, Output> | undefined;
+  /** Validates unknown input values. */
+  readonly validate: (value: StandardSchemaTypes["input"]) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+}
+/**
+ * A Standard Schema-compatible schema object.
+ *
+ * Any schema library implementing the Standard Schema v1 spec
+ * (Zod, Effect, Valibot, ArkType, etc.) produces objects matching this type.
+ */
+type StandardSchema<Input = unknown, Output = Input> = {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaProps<Input, Output>;
+};
+/** Infer the output type produced by a Standard Schema on success. */
+type InferOutput<S extends StandardSchema> = NonNullable<S["~standard"]["types"]>["output"];
+//#endregion
+//#region src/identity.d.ts
+declare const brand: unique symbol;
+/** Stable identity shared by Extensions and documentation section renderers. */
+type ExtensionId = string & {
+  readonly [brand]: true;
+};
+/** Mint an Extension identity from any non-blank, trimmed string. */
+declare function defineExtensionId(id: string): ExtensionId;
+//#endregion
+//#region src/validation/shared.d.ts
+type Awaitable<T> = T | Promise<T>;
+type Simplify<T> = { [K in keyof T]: T[K]; };
+type MergeContext<A, B> = A & B;
+/** Provider replacement is last-write-wins; an open name may leave any earlier value in place. */
+type MergeProviders<A, B> = keyof A extends never ? B : keyof B extends never ? A : string extends keyof B ? Record<string, A[keyof A] | B[string]> : [keyof A & keyof B] extends [never] ? A & B : Omit<A, keyof B> & B;
+/**
+ * Extract the narrowed canonical `name` literal from a definition.
+ * Open name domains carry no spelling proof; attachment must retain
+ * their uncertainty rather than treating this absence as an empty namespace.
+ */
+type DefName<T> = T extends {
+  name: infer N extends string;
+} ? IsClosedName<N> extends true ? N : never : never;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+/**
+ * `true` only for a single statically known fixed-length tuple whose members
+ * are not unions. A conditionally assembled collection (`cond ? [a] : [b]` or
+ * `[cond ? a : b]`) infers as a union at the tuple or member level, and a
+ * variable-length array (`const xs: (typeof a)[]`) may be empty or partially
+ * populated at runtime; such contributions must stay runtime-only.
+ */
+type IsStaticTuple<Cs extends readonly unknown[]> = number extends Cs["length"] ? false : IsUnion<Cs> extends true ? false : true extends { [I in keyof Cs]: IsUnion<Cs[I]>; }[number] ? false : true;
+/** Whether a fixed tuple has one closed canonical name per slot. */
+type HasClosedNames<Ds extends readonly unknown[]> = number extends Ds["length"] ? false : IsUnion<Ds> extends true ? false : false extends { [I in keyof Ds]: Ds[I] extends {
+  name: infer N extends string;
+} ? IsUnion<N> extends true ? false : IsClosedName<N> : false; }[number] ? false : true;
+/** Brand statically known spelling collisions while allowing open names. */
+type CollisionBrand<S extends string, Existing extends string, Key extends string, Before extends string, After extends string> = string extends S | Existing ? {} : [S & Existing] extends [never] ? {} : { readonly [K in Key]: `${Before}"${S & Existing}"${After}`; };
+/** Brand a statically known empty literal while allowing widened and generic names. */
+type EmptyLiteralNameBrand<Name extends string, Err> = IsClosedName<Name> extends true ? ("" extends Name ? Err : {}) : {};
+/**
+ * Brand a definition whose custom parser can return a Promise — parse results
+ * are consumed synchronously during argv parsing. `Extract` keeps the check
+ * union-aware (a sometimes-async `cond ? Promise.resolve(x) : x` parser is
+ * caught) while `any`-returning parsers stay unbranded.
+ */
+type AsyncParseBrand<T> = T extends {
+  parse?: (...args: never[]) => infer R;
+} ? Extract<R, Promise<unknown>> extends never ? {} : {
+  readonly FIX_ASYNC_PARSE: "parse must be synchronous; do async work in run()";
+} : {};
+/** Brand literal defaults that fall outside a literal `choices` tuple. */
+type DefaultWithinChoicesBrand<T> = T extends {
+  choices: readonly (infer Choice extends string)[];
+  default: infer Default;
+} ? string extends Choice ? {} : Default extends readonly string[] ? string extends Default[number] ? {} : Exclude<Default[number], Choice> extends never ? {} : {
+  readonly FIX_DEFAULT_CHOICE: "default must be one of choices";
+} : Default extends string ? string extends Default ? {} : Exclude<Default, Choice> extends never ? {} : {
+  readonly FIX_DEFAULT_CHOICE: "default must be one of choices";
+} : {} : {};
+/** Finite literal domains have required record keys; infinite templates and branded strings do not.
+ * Distribute first so a finite union member cannot hide an open member's index signature.
+ */
+type IsClosedName<N extends string> = false extends (N extends unknown ? ({} extends Record<N, true> ? false : true) : never) ? false : true;
+/** Reject independently provable invalid local values, including members of uncertain definitions. */
+type LocalValueBrand<T> = UnionToIntersection<T extends unknown ? AsyncParseBrand<T> & DefaultWithinChoicesBrand<T> : never>;
+//#endregion
+//#region src/command/snapshot.d.ts
+/**
+ * Serializable projection of a positional argument definition.
+ *
+ * Carries everything help/man/tooling surfaces need; `parse` functions and
+ * schemas never cross the boundary.
+ *
+ * Fields with `undefined` values are dropped entirely (see `freezeCompact`),
+ * so absent means "not declared".
+ *
+ * @example
+ * For `{ name: "port", type: "number", default: 3000 }`:
+ * ```ts
+ * { name: "port", type: "number", default: 3000 }
+ * // `required`/`variadic` keys absent — not declared on the def
+ * ```
+ */
+interface ArgSnapshot {
+  /** Argument name as defined, e.g. `"file"`. */
+  readonly name: string;
+  /** Value type (`"string"`, `"number"`, …); absent for schema-backed args. */
+  readonly type?: ValueType;
+  /** Human-readable description for help text. */
+  readonly description?: string;
+  /** `true` when parsing fails if the argument is missing. */
+  readonly required?: boolean;
+  /** `true` when the argument collects all remaining positionals into an array. */
+  readonly variadic?: boolean;
+  /** Static enum of accepted values, e.g. `["json", "text"]`. */
+  readonly choices?: readonly string[];
+  /** Declared default value; `URL` defaults are serialized to their `href` string. */
+  readonly default?: unknown;
+}
+/**
+ * Serializable projection of a flag definition. The flag's canonical name is
+ * the key it sits under in {@link CommandSnapshot.flags}, not a field here.
+ *
+ * @example
+ * For `{ verbose: { type: "boolean", short: "v", default: false } }`:
+ * ```ts
+ * snapshot.flags.verbose
+ * // => { type: "boolean", short: "v", default: false, negatable: true }
+ * ```
+ */
+interface FlagSnapshot {
+  /** Value type, e.g. `"boolean"`, `"string"`, `"number"`. */
+  readonly type: ValueType;
+  /** Human-readable description for help text. */
+  readonly description?: string;
+  /** Single-character short alias without the dash, e.g. `"v"` for `-v`. */
+  readonly short?: string;
+  /** Additional aliases without dashes; one-character aliases accept one or two dashes. */
+  readonly aliases?: readonly string[];
+  /** `true` when parsing fails if the flag is not provided. */
+  readonly required?: boolean;
+  /** `true` when the flag can repeat and collects values into an array. */
+  readonly multiple?: boolean;
+  /** `true` when the flag accepts generated `--no-<name>` spellings. */
+  readonly negatable: boolean;
+  /** `true` when a boolean flag opted out of the `--no-<name>` spelling. */
+  readonly noNegate?: boolean;
+  /** Static enum of accepted values, e.g. `["debug", "info", "error"]`. */
+  readonly choices?: readonly string[];
+  /** Declared default value; `URL` defaults are serialized to their `href` string. */
+  readonly default?: unknown;
+}
+/**
+ * A readonly, serializable description of a command, exposed across public
+ * API boundaries (Command Action context, Extension hooks, and
+ * `COMMAND_NOT_FOUND` error details) instead of internal command nodes.
+ *
+ * `flags` contains the effective (Context-owned + local merged) flags — the same
+ * set the parser accepts for the command.
+ *
+ * @example
+ * ```ts
+ * defineCommand("add", (cmd) =>
+ *   cmd
+ *     .args({ name: "name", type: "string", required: true })
+ *     .flags({ name: "force", type: "boolean", short: "f" })
+ *     .action(() => {}),
+ * );
+ * // snapshots to:
+ * // {
+ * //   meta: { name: "add" },
+ * //   hasAction: true,
+ * //   args: [{ name: "name", type: "string", required: true }],
+ * //   flags: { force: { type: "boolean", short: "f", negatable: true } },
+ * //   subCommands: {},
+ * // }
+ * ```
+ */
+interface CommandSnapshot {
+  /** Command metadata, including routing and presentation options. */
+  readonly meta: Readonly<CommandMeta>;
+  /** Whether the command defines a Command Action */
+  readonly hasAction: boolean;
+  /** Positional argument snapshots in declaration order. */
+  readonly args: readonly ArgSnapshot[];
+  /** Effective flags keyed by canonical flag name. */
+  readonly flags: Readonly<Record<string, FlagSnapshot>>;
+  /** Direct subcommand snapshots keyed by canonical name (includes hidden ones). */
+  readonly subCommands: Readonly<Record<string, CommandSnapshot>>;
+}
+//#endregion
+//#region src/parsing/parser.d.ts
+type RunInputValue = URL | JsonValue | readonly RunInputValue[];
+interface RunInputPayload {
+  readonly args?: Readonly<Record<string, RunInputValue | undefined>>;
+  readonly flags?: Readonly<Record<string, RunInputValue | undefined>>;
+  readonly raw?: readonly string[];
+}
+//#endregion
+//#region src/types.d.ts
+/** Injectable output callbacks threaded through one invocation. */
+interface InvocationIO {
+  /** Write a line of standard output (injectable text callback) */
+  stdout: (text: string) => void;
+  /** Write a line of diagnostic output (injectable text callback) */
+  stderr: (text: string) => void;
+}
+/**
+ * Supported type literals for args and flags.
+ *
+ * Extends `BaseValueType` (`"string" | "number" | "boolean"`) with three
+ * formatted built-ins:
+ *
+ * - `"url"`  — the raw value is parsed via `new URL()` into a {@link URL}
+ * - `"path"` — the raw value is expanded (`~`) and resolved against
+ *              `process.cwd()` into an absolute `string`
+ * - `"json"` — the raw value is parsed via `JSON.parse()` into `unknown`
+ */
+type ValueType = BaseValueType | "url" | "path" | "json";
+/** Resolve a {@link ValueType} literal to its runtime TypeScript type. */
+type Resolve<T extends ValueType> = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  url: URL;
+  path: string;
+  json: unknown;
+}[T];
+/**
+ * Resolve the inferred runtime type for a flag/arg definition.
+ *
+ * When the def declares a `parse` escape hatch (only allowed on `"string"`
+ * variants), the inferred type is `ReturnType<typeof parse>`. Optional parsers
+ * also retain the unparsed output branch. String defs
+ * with a literal `choices` tuple narrow to the union of those literals.
+ * Otherwise it delegates to {@link Resolve} on the declared `type`.
+ */
+type ResolveBaseType<F> = "parse" extends keyof F ? F["parse"] extends (infer Parse) ? Parse extends ((raw: string) => infer R) ? R : ResolveUnparsedType<F> : never : ResolveUnparsedType<F>;
+type ResolveUnparsedType<F> = F extends {
+  type: "string";
+  choices: readonly (infer C extends string)[];
+} ? C : F extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never;
+/** Shared fields present on every positional argument definition */
+interface ArgDefBase {
+  /** The argument name (used as the key in the parsed result and in help text) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /**
+   * When `true`, the parser throws if the argument is not provided.
+   *
+   * For variadic args without a default, the validated output is a nonempty tuple.
+   */
+  required?: true;
+  /** Not supported with core value options — see {@link SchemaArgDef} */
+  schema?: never;
+  /**
+   * When `true`, collects all remaining positional values into an array.
+   *
+   * The validated output is always an array, never `undefined`.
+   * Required core variadics without defaults infer `[T, ...T[]]` after
+   * required validation; other core variadics infer `T[]`.
+   */
+  variadic?: true;
+}
+/** A positional argument whose value is a string */
+interface StringArgDef<ParseOutput = unknown> extends ArgDefBase {
+  type: "string";
+  /** Default string value when the argument is not provided */
+  default?: string;
+  /**
+   * Static enum of valid values for this argument.
+   *
+   * Checked for argv and structured invocation input before `parse` runs.
+   * Typed input also proves membership statically. Passing a value outside
+   * `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+   * is applied. Also consumed by shell-completion extensions
+   * (e.g. `@crustjs/extensions`) to emit value candidates.
+   *
+   * Only available on string-typed args; not supported on number/boolean.
+   *
+   * @example
+   * { name: "target", type: "string", choices: ["browser", "bun", "node"] }
+   */
+  choices?: readonly string[];
+  /**
+   * Custom synchronous parser for the raw argv string. Runs after `choices`
+   * validation and per element for variadic args. Its return type becomes the
+   * argument's inferred runtime type; declared defaults are parsed too.
+   *
+   * @example
+   * { name: "port", type: "string", parse: (s) => Number(s) }
+   */
+  parse?: (raw: string) => ParseOutput;
+}
+/** A positional argument whose value is a number */
+interface NumberArgDef extends ArgDefBase {
+  type: "number";
+  choices?: never;
+  /** Default number value when the argument is not provided */
+  default?: number;
+  /** Not supported on number args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is a boolean */
+interface BooleanArgDef extends ArgDefBase {
+  type: "boolean";
+  choices?: never;
+  /** Default boolean value when the argument is not provided */
+  default?: boolean;
+  /** Not supported on boolean args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is a {@link URL} */
+interface UrlArgDef extends ArgDefBase {
+  type: "url";
+  choices?: never;
+  /** Default URL value when the argument is not provided */
+  default?: URL;
+  /** Not supported on url args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is an absolute filesystem path */
+interface PathArgDef extends ArgDefBase {
+  type: "path";
+  choices?: never;
+  /** Default path string when the argument is not provided */
+  default?: string;
+  /** Not supported on path args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is JSON parsed to `unknown` */
+interface JsonArgDef extends ArgDefBase {
+  type: "json";
+  choices?: never;
+  /** Default parsed JSON value when the argument is not provided */
+  default?: unknown;
+  /** Not supported on json args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/**
+ * A positional argument validated by a Standard Schema (exclusive mode).
+ *
+ * The schema receives the raw string token (`string | undefined` when the
+ * argument is absent; `string[]` for variadic args) and exclusively owns
+ * coercion, defaults, requiredness, choices, and validation. Its inferred
+ * output type reaches the Command Action. Core value options (`type`,
+ * `default`, `required`, `choices`, `parse`) cannot be mixed in.
+ */
+interface SchemaArgDef {
+  /** The argument name (used as the key in the parsed result and in help text) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /** When `true`, collects all remaining raw tokens into a `string[]` for the schema */
+  variadic?: true;
+  /** Standard Schema that owns coercion, defaults, requiredness, and validation */
+  schema: StandardSchema;
+  type?: never;
+  required?: never;
+  default?: never;
+  choices?: never;
+  parse?: never;
+}
+/**
+ * Defines a single positional argument for a CLI command.
+ *
+ * Discriminated by `type` for type-safe `default` values. Boolean toggle
+ * fields (`required`, `variadic`) only accept `true`.
+ *
+ * @example
+ * ```ts
+ * const args = [
+ *   { name: "port", type: "number", description: "Port number", default: 3000 },
+ *   { name: "name", type: "string", required: true },
+ *   { name: "files", type: "string", variadic: true },
+ * ] as const satisfies ArgsDef;
+ * ```
+ */
+type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef | UrlArgDef | PathArgDef | JsonArgDef | SchemaArgDef;
+/** Ordered tuple of positional argument definitions */
+type ArgsDef = readonly ArgDef[];
+/** Shared fields present on every flag definition */
+interface FlagDefBase {
+  /** Human-readable description for help text */
+  description?: string;
+  /** Single-character short alias (e.g. `"v"` → `-v`) */
+  short?: string;
+  /** Additional aliases (e.g. `["out"]` → `--out`); one-character aliases also accept one dash. */
+  aliases?: readonly string[];
+  /** When `true`, the parser throws if the flag is not provided */
+  required?: true;
+  /** Not supported with core value options — see {@link SchemaStringFlagDef} */
+  schema?: never;
+}
+/** Base for single-value flags — `multiple` must be omitted */
+interface SingleFlagBase extends FlagDefBase {
+  /** Must be omitted for single-value flags — set to `true` for multi-value */
+  multiple?: never;
+}
+/** Base for multi-value flags — `multiple` is required as `true` */
+interface MultiFlagBase extends FlagDefBase {
+  /** Collect repeated values into an array */
+  multiple: true;
+}
+type StringFlagFields<Default, ParseOutput> = {
+  /** Default string value, or string array for a multi-value flag. */
+  default?: Default;
+  /**
+   * Static enum of valid values for this flag.
+   *
+   * Checked for argv and structured invocation input before `parse` runs.
+   * Typed input also proves membership statically. Passing a value outside
+   * `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+   * is applied. Also consumed by shell-completion extensions.
+   */
+  choices?: readonly string[];
+  /**
+   * Custom synchronous parser for the raw argv string. For multi-value
+   * flags it runs once per occurrence. The return type becomes the flag's
+   * inferred runtime value type.
+   */
+  parse?: (raw: string) => ParseOutput;
+  noNegate?: never;
+};
+type TypedFlagFields<T extends Exclude<ValueType, "string">, Default> = {
+  /** Default value, or value array for a multi-value flag. */
+  default?: Default;
+  choices?: never;
+  /** Only boolean flags support generated-negation opt-out. */
+  noNegate?: T extends "boolean" ? true : never;
+  /** Use `type: "string"` with `parse` for custom parsing. */
+  parse?: never;
+};
+type CoreFlagFields<T extends ValueType, Default, ParseOutput> = T extends "string" ? StringFlagFields<Default, ParseOutput> : T extends Exclude<ValueType, "string"> ? TypedFlagFields<T, Default> : never;
+/** A single-value core flag for the declared value type. */
+type TypedFlagDef<T extends ValueType, ParseOutput = unknown> = SingleFlagBase & {
+  type: T;
+} & CoreFlagFields<T, Resolve<T>, ParseOutput>;
+/** A repeatable core flag for the declared value type. */
+type TypedMultiFlagDef<T extends ValueType, ParseOutput = unknown> = MultiFlagBase & {
+  type: T;
+} & CoreFlagFields<T, readonly Resolve<T>[], ParseOutput>;
+/** Shared fields for schema-backed flags (exclusive mode) */
+interface SchemaFlagBase extends Omit<FlagDefBase, "schema" | "required"> {
+  /** Standard Schema that owns coercion, defaults, requiredness, and validation */
+  schema: StandardSchema;
+  required?: never;
+  default?: never;
+  choices?: never;
+  parse?: never;
+}
+/**
+ * A schema-backed flag that consumes a value token (`--flag value`).
+ * The schema receives the raw string (`string | undefined`, or
+ * `string[] | undefined` with `multiple: true`) and exclusively owns coercion,
+ * defaults, requiredness, and validation. `type` declares token consumption only.
+ */
+interface SchemaStringFlagDef extends SchemaFlagBase {
+  type: "string";
+  /** When `true`, the schema receives `string[]` when present, or `undefined` when omitted. */
+  multiple?: true;
+  noNegate?: never;
+}
+/**
+ * A schema-backed toggle flag (no value token). The schema receives the raw
+ * `boolean | undefined` (or `boolean[] | undefined` with `multiple: true`).
+ */
+interface SchemaBooleanFlagDef extends SchemaFlagBase {
+  type: "boolean";
+  /** When `true`, the schema receives `boolean[]` when present, or `undefined` when omitted. */
+  multiple?: true;
+  /** When `true`, reject `--no-{name}` (and negated aliases) at parse time and hide the generated help label */
+  noNegate?: true;
+}
+/**
+ * Defines a single named flag for a CLI command.
+ *
+ * Discriminated by `type` and `multiple` for type-safe `default` values.
+ * Boolean toggle fields (`required`, `multiple`) only accept `true`.
+ *
+ * @example
+ * ```ts
+ * const flags = {
+ *   verbose: { type: "boolean", description: "Enable verbose logging", short: "v" },
+ *   port: { type: "number", description: "Port number", default: 3000 },
+ *   files: { type: "string", multiple: true, default: ["index.ts"] },
+ * } satisfies FlagsDef;
+ * ```
+ */
+type FlagDef = { [T in ValueType]: TypedFlagDef<T> | TypedMultiFlagDef<T>; }[ValueType] | SchemaStringFlagDef | SchemaBooleanFlagDef;
+/** Record mapping flag names to their definitions */
+type FlagsDef = Record<string, FlagDef>;
+/**
+ * A flag definition that carries its own name — the authoring shape
+ * produced by `defineFlag(name, def)` or written inline as an object
+ * literal (`{ name: "dry-run", type: "boolean" }`) and attached with the
+ * variadic `.flags(...defs)`.
+ */
+type NamedFlagDef = FlagDef & {
+  readonly name: string;
+};
+/**
+ * Derive the internal `FlagsDef` record from a tuple of named flag
+ * definitions: each definition's `name` literal becomes a key, its value
+ * the definition without `name`.
+ *
+ * The `extends infer R extends FlagsDef` step defers evaluation so the
+ * result satisfies `FlagsDef` in generic positions.
+ */
+type FlagWithoutName<D> = D extends unknown ? Omit<D, "name"> : never;
+type NamedFlagsRecord<Defs extends readonly NamedFlagDef[]> = { [K in Defs[number]["name"]]: FlagWithoutName<Extract<Defs[number], {
+  name: K;
+}>>; } extends (infer R extends FlagsDef) ? R : never;
+/**
+ * Merges two flag sets as a flat intersection.
+ *
+ * Statically known shared keys are branded at compile time (`DuplicateNameBrand`,
+ * `ExistingFlagCollisionBrand`, `ProvideChecks`). A plain intersection stays
+ * flat in the checker — chained `.flags()`/`.provide()` calls cost constant
+ * instantiation depth, where per-call merge layers (mapped type or
+ * `Simplify<Omit & …>`) nested and hit TS2589 at ~47 / ~31 chained calls.
+ */
+type MergeFlags<Base extends FlagsDef, Override extends FlagsDef> = Base & Override;
+/**
+ * Infer the resolved type for a single ArgDef:
+ *
+ * - **variadic** → `[primitive, ...primitive[]]` when required without a default,
+ *   otherwise `primitive[]` (always an array, never `undefined`)
+ * - **required** or **has default** → `primitive` (non-optional)
+ * - otherwise → `primitive | undefined`
+ *
+ * Required core variadics without defaults resolve to nonempty tuples.
+ * Schema-backed and default-backed arguments retain their own output contracts.
+ */
+type InferArgValue<A extends ArgDef> = A extends {
+  schema: infer S extends StandardSchema;
+} ? InferOutput<S> : A extends {
+  variadic: true;
+} ? A extends {
+  required: true;
+  default?: never;
+} ? [ResolveBaseType<A>, ...ResolveBaseType<A>[]] : ResolveBaseType<A>[] : ("variadic" extends keyof A ? true extends A["variadic"] ? ResolveBaseType<A>[] : never : never) | (A extends {
+  required: true;
+} ? ResolveBaseType<A> : A extends {
+  default: infer Default;
+} ? undefined extends Default ? ResolveBaseType<A> | undefined : ResolveBaseType<A> : ResolveBaseType<A> | undefined);
+type DuplicateArgNames<A extends readonly ArgDef[], Seen extends string = never> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? (Head["name"] & Seen) | DuplicateArgNames<Tail, Seen | Head["name"]> : never;
+type InferDuplicateArgs<A extends readonly ArgDef[]> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? { [K in Head["name"]]: InferArgValue<Head>; } & InferDuplicateArgs<Tail> : {};
+/**
+ * Convert a literal ArgsDef tuple into resolved values keyed by argument name.
+ *
+ * Tuples with rest elements (`number extends A["length"]`) opt out to `{}`;
+ * the builder only produces fixed tuples. Unions of tuples distribute through
+ * `InferArgs`'s naked conditional, so each member is inferred separately.
+ */
+type InferArgsTuple<A extends readonly ArgDef[]> = number extends A["length"] ? {} : [DuplicateArgNames<A>] extends [never] ? { [D in A[number] as D["name"]]: InferArgValue<D>; } : InferDuplicateArgs<A>;
+/**
+ * Maps an ArgsDef tuple to resolved arg types keyed by each arg's `name`.
+ *
+ * @example
+ * ```ts
+ * type Result = InferArgs<readonly [
+ *   { name: "port"; type: "number"; default: 3000 },
+ *   { name: "name"; type: "string"; required: true },
+ *   { name: "files"; type: "string"; variadic: true },
+ * ]>;
+ * // Result = { port: number; name: string; files: string[] }
+ * ```
+ */
+type InferArgs<A> = A extends ArgsDef ? Simplify<InferArgsTuple<A>> : Record<string, never>;
+/**
+ * Infer the resolved type for a single FlagDef:
+ *
+ * - **multiple** → wraps the resolved type in an array
+ * - **required** or **has default** → `primitive` (non-optional)
+ * - otherwise → `primitive | undefined`
+ */
+type InferFlagValue<F extends FlagDef> = F extends {
+  schema: infer S extends StandardSchema;
+} ? InferOutput<S> : F extends {
+  multiple: true;
+} ? F extends {
+  required: true;
+} ? ResolveBaseType<F>[] : F extends {
+  default: readonly unknown[];
+} ? ResolveBaseType<F>[] : ResolveBaseType<F>[] | undefined : F extends {
+  required: true;
+} ? ResolveBaseType<F> : F extends {
+  default: infer Default;
+} ? undefined extends Default ? ResolveBaseType<F> | undefined : ResolveBaseType<F> : ResolveBaseType<F> | undefined;
+/**
+ * Maps a full FlagsDef record to resolved flag types.
+ *
+ * @example
+ * ```ts
+ * type Result = InferFlags<{
+ *   verbose: { type: "boolean" };
+ *   port: { type: "number", default: 3000 };
+ * }>;
+ * // Result = { verbose: boolean | undefined; port: number }
+ * ```
+ */
+type InferFlags<F> = F extends FlagsDef ? { [K in keyof F]: InferFlagValue<F[K]>; } : Record<string, never>;
+type InputBaseValue<D> = true extends IsUnion<D> | IsUnion<D[keyof D & "type"]> ? never : D extends {
+  type: "boolean";
+} ? "noNegate" extends keyof D ? true extends D["noNegate"] ? true : boolean : boolean : D extends {
+  schema: StandardSchema;
+} ? D extends {
+  type: "boolean";
+} ? boolean : string : D extends {
+  type: "json";
+} ? JsonValue : "choices" extends keyof D ? Exclude<D["choices"], undefined> extends (infer Choices extends readonly string[]) ? [Choices] extends [never] ? D extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never : IsStaticTuple<Choices> extends true ? IsClosedName<Choices[number]> extends true ? Choices[number] : never : never : never : D extends {
+  parse: (raw: string) => infer _ParseOutput;
+} ? string : D extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never;
+type InputArgValue<D extends ArgDef, Value = InputBaseValue<D>> = [Value] extends [never] ? never : D extends {
+  variadic: true;
+} ? RequiredArgNames<[D]> extends never ? Value[] : [Value, ...Value[]] : "variadic" extends keyof D ? true extends D["variadic"] ? never : Value : Value;
+type InputFlagValue<D, Value = InputBaseValue<D>> = [Value] extends [never] ? never : D extends {
+  multiple: true;
+} ? Value[] : "multiple" extends keyof D ? true extends D["multiple"] ? never : Value : Value;
+type RequiredArgNames<A extends ArgsDef> = A[number] extends (infer D) ? D extends {
+  name: infer N extends string;
+} ? "required" extends keyof D ? true extends D["required"] ? D extends {
+  default: infer Default;
+} ? undefined extends Default ? N : never : N : never : never : never : never;
+type InputArgsPrefixes<Remaining extends ArgsDef, Supplied = {}, Prefixes = never> = Remaining extends readonly [infer Head extends ArgDef, ...infer Tail extends ArgsDef] ? InputArgsPrefixes<Tail, Supplied & { [K in Head["name"]]: InputArgValue<Head>; }, Prefixes | (RequiredArgNames<Remaining> extends never ? Simplify<Supplied & { [D in Remaining[number] as D["name"]]?: never; }> : never)> : Prefixes | Simplify<Supplied>;
+/** Supplied positional values form a prefix; defaults do not fill input gaps. */
+type InputArgs<A extends ArgsDef> = number extends A["length"] ? never : IsUnion<A> extends true ? never : IsClosedName<A[number]["name"]> extends true ? InputArgsPrefixes<A> : never;
+type RequiredFlagName<D, K> = D extends unknown ? "required" extends keyof D ? true extends D["required"] ? D extends {
+  default: infer Default;
+} ? undefined extends Default ? K : never : K : never : never : never;
+type RequiredFlagNames<F extends FlagsDef> = { [K in keyof F]-?: RequiredFlagName<F[K], K>; }[keyof F];
+/** Flag values accepted by typed programmatic invocation before parsing/validation. */
+type KnownFlags<F extends FlagsDef> = { [K in keyof F as string extends K ? never : K]: F[K]; };
+type InputFlags<F extends FlagsDef> = IsUnion<F> extends true ? never : Simplify<{ [K in RequiredFlagNames<KnownFlags<F>>]-?: InputFlagValue<KnownFlags<F>[K]>; } & { [K in Exclude<keyof KnownFlags<F>, RequiredFlagNames<KnownFlags<F>>>]?: InputFlagValue<KnownFlags<F>[K]>; }> & (string extends keyof F ? NonNullable<RunInputPayload["flags"]> : {});
+type SectionConsumer = ExtensionId | {
+  readonly id: ExtensionId;
+};
+type Audience<C> = {
+  readonly only: C;
+  readonly except?: never;
+} | {
+  readonly except: C;
+  readonly only?: never;
+} | {
+  readonly only?: never;
+  readonly except?: never;
+};
+type SectionAudience = Audience<readonly [SectionConsumer, ...SectionConsumer[]]>;
+type SectionContent = {
+  readonly title: string;
+  readonly body: string;
+};
+/** A plain-text documentation section accepted from command and Extension authors. */
+type CommandSectionInput = SectionContent & SectionAudience;
+/** Typed dynamic audiences may be empty until their consuming operation checks them. */
+type RuntimeCommandSectionInput = SectionContent & Audience<readonly SectionConsumer[]>;
+/** A validated documentation section rendered after built-in command documentation. */
+type CommandSection = SectionContent & Audience<readonly [ExtensionId, ...ExtensionId[]]>;
+/** Metadata describing a CLI command */
+interface CommandMeta {
+  /** The command name (used in help text and routing) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /** Application version exposed to Extensions and tooling on the root command. */
+  version?: string;
+  /** Custom usage string (overrides auto-generated usage) */
+  usage?: string;
+  /** Plain-text sections rendered after built-in command documentation. */
+  sections?: readonly CommandSection[];
+  /**
+   * Alternative names that resolve to the same command.
+   *
+   * Each entry is a sibling-level alternative for `name`. For example,
+   * `defineCommand("issue", { aliases: ["issues", "i"] }, recipe)` makes
+   * `cli issue`, `cli issues`, and `cli i` all route to the same command node.
+   *
+   * **Conflict policy.** Alias strings must not collide with this command's
+   * own canonical `name`, with any sibling's `name`, or with any sibling's
+   * own alias. TypeScript reports statically known collisions. Each alias
+   * must also be a non-empty string with no
+   * whitespace and must not start with `-`.
+   *
+   * **Display contract.** Help output renders the canonical name with
+   * aliases inline as `name (a, b, c)`. The canonical `name` is what
+   * appears in `commandPath`, error messages, and suggestions from
+   * `didYouMean` — it does not depend on which alias the user typed.
+   *
+   * @example
+   * defineCommand("issue", { aliases: ["issues", "i"] }, recipe)
+   */
+  aliases?: readonly string[];
+  /**
+   * When `true`, omit this command from every tooling surface that
+   * enumerates the command tree for users:
+   *
+   * - `help` rendered output (subcommand list + USAGE token)
+   * - `@crustjs/man` generated man pages (`SUBCOMMANDS` section)
+   * - `completion` candidate lists (recursively — hidden
+   *   subcommands and their descendants never appear in generated
+   *   bash/zsh/fish scripts)
+   * - `didYouMean` typo suggestions and "Available commands"
+   *   list (so internal names never surface in error UX)
+   * - `skill` manifests
+   *
+   * The command is **only hidden from listings**: routing in
+   * `@crustjs/core` does not consult `meta.hidden`, so it stays fully
+   * invocable by direct name (or alias). The intended use case is
+   * internal/runtime commands like a `__complete` shell-completion
+   * entrypoint. Marking a user-facing command `hidden` is supported but
+   * unusual.
+   *
+   * **Scope: commands only.** There is no analogous `hidden` field on
+   * `FlagDef` or `ArgDef`; flags and positional arguments always surface
+   * in help, completion, and man output. If you need a flag that does
+   * not advertise itself, the workaround is to register it as an Extension
+   * flags entry without a description (omit `description`),
+   * which suppresses its description body but still lists the spelling
+   * — there is intentionally no full hide mechanism at the flag layer.
+   *
+   * Tooling contract: any renderer or generator that walks
+   * `subCommands` to produce a user-facing listing should skip nodes
+   * where `meta.hidden === true`.
+   *
+   * @example
+   * meta: { name: "__complete", hidden: true, description: "Internal" }
+   */
+  hidden?: boolean;
+}
+/** Raw token shapes a Standard Schema receives before it runs. */
+type RawSchemaFlagInput = string | boolean | readonly (string | boolean)[] | undefined;
+/** One flag value after syntax parsing and before required/schema validation. */
+type RawFlagValue<D extends FlagDef> = D extends {
+  schema: StandardSchema;
+} ? RawSchemaFlagInput : InferFlagValue<D> | undefined;
+/** Positional counterpart of {@link RawFlagValue}. */
+type RawArgValue<D extends ArgDef> = D extends {
+  schema: StandardSchema;
+} ? D extends {
+  variadic: true;
+} ? string[] : string | undefined : D extends {
+  variadic: true;
+} ? ResolveBaseType<D>[] | undefined : InferArgValue<D> | undefined;
+/** Runtime-erased syntax-parsed flag value. */
+type ParsedFlagValue = RawFlagValue<FlagDef>;
+/** Runtime-erased syntax-parsed positional value. */
+type ParsedArgValue = RawArgValue<ArgDef>;
+type RawParsedFlags<F extends FlagsDef> = { [K in keyof F]: RawFlagValue<F[K]>; };
+type RawParsedArgs<A extends ArgsDef> = number extends A["length"] ? Record<string, ParsedArgValue> : { [D in A[number] as D["name"]]: RawArgValue<D>; };
+/** A declared default on any argument or flag definition. */
+type DeclaredDefault = (ArgDef | FlagDef)["default"];
+/** Syntax-parsed input, before required and Standard Schema validation. */
+interface ParseResult<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef> {
+  args: RawParsedArgs<A>;
+  flags: RawParsedFlags<F>;
+  /** Positionals before `--` that were not consumed by a declared argument. */
+  excessArgs: string[];
+  /** Arguments after the `--` separator. */
+  rawArgs: string[];
+}
+/** Fully validated input returned by the schema boundary. */
+interface ValidatedInput<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef> {
+  args: InferArgs<A>;
+  flags: InferFlags<F>;
+}
+//#endregion
+export { CollisionBrand as A, UnionToIntersection as B, ValidatedInput as C, CommandSnapshot as D, ArgSnapshot as E, IsStaticTuple as F, defineExtensionId as H, IsUnion as I, LocalValueBrand as L, EmptyLiteralNameBrand as M, HasClosedNames as N, FlagSnapshot as O, IsClosedName as P, MergeContext as R, SectionConsumer as S, RunInputPayload as T, JsonCompatible as U, ExtensionId as V, JsonValue as W, ParseResult as _, CommandSectionInput as a, RuntimeCommandSectionInput as b, FlagsDef as c, InputArgs as d, InputFlags as f, NamedFlagsRecord as g, NamedFlagDef as h, CommandSection as i, DefName as j, Awaitable as k, InferArgs as l, MergeFlags as m, ArgsDef as n, DeclaredDefault as o, InvocationIO as p, CommandMeta as r, FlagDef as s, ArgDef as t, InferFlags as u, ParsedArgValue as v, ValueType as w, SectionAudience as x, ParsedFlagValue as y, MergeProviders as z };