npm - @crustjs/core - Versions diffs - 0.3.0 → 0.3.2 - Mend

@crustjs/core 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/context-Cud9frNp.d.ts +2059 -0
package/dist/index.d.ts +3 -1287
package/dist/index.js +2 -1
package/dist/{invocation-CIvHShiW.js → invocation-B17RvTLb.js} +5 -216
package/dist/tooling.d.ts +2 -1
package/dist/tooling.js +2 -1
package/package.json +4 -2
package/dist/artifacts-D8Jlug-a.d.ts +0 -870

package/dist/index.d.ts CHANGED Viewed

@@ -1,1289 +1,5 @@
-import { A as FlagSnapshot, B as IsUnion, C as SectionAudience, D as RunInputPayload, E as ValueType, F as DefNameMembers, G as ExtensionId, H as MergeContext, I as EmptyLiteralNameBrand, J as JsonValue, K as defineExtensionId, L as HasClosedNames, M as ClosedMembers, N as CollisionBrand, O as ArgSnapshot, P as DefName, R as IsClosedName, S as RuntimeCommandSectionInput, T as ValidatedInput, U as MergeProviders, V as LocalValueBrand, W as UnionToIntersection, _ as NamedFlagDef, a as CommandMeta, b as ParsedArgValue, d as InferArgs, f as InferFlags, g as MergeFlags, h as InvocationIO, i as ArgsDef, j as Awaitable, k as CommandSnapshot, l as FlagDef, m as InputFlags, n as resolveArtifactDir, o as CommandSection, p as InputArgs, q as JsonCompatible, r as ArgDef, s as CommandSectionInput, u as FlagsDef, v as NamedFlagsRecord, w as SectionConsumer, x as ParsedFlagValue, y as ParseResult, z as IsStaticTuple } from "./artifacts-D8Jlug-a.js";
-//#region src/validation/args.brands.d.ts
-type ArgNames<A extends readonly object[]> = DefName<A[number]>;
-type DuplicateArgBrand<A, Existing extends string> = CollisionBrand<DefName<A>, Existing, "FIX_DUPLICATE_ARG", "Argument name ", " is already defined">;
-type EmptyArgNameError = {
-  readonly FIX_EMPTY_NAME: "Argument names must be non-empty";
-};
-/** Reject empty argument names, including empty members of a name union. */
-type EmptyArgNameBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptyArgNameError>;
-type EmptyArgDefinitionNameBrand<A> = EmptyArgNameBrand<DefNameMembers<A>>;
-type ArgChecks<A, Existing extends string> = A & DuplicateArgBrand<A, Existing> & LocalValueBrand<A> & EmptyArgDefinitionNameBrand<A>;
-/**
- * Per-arg validation tuple type. Resolves to `A` when the constraints are
- * satisfied: only the last arg is variadic, names are unique, and custom
- * parsers are synchronous. Invalid definitions receive a branded property.
- *
- * Generalized to work with any ordered tuple of object-typed definitions.
- * Uses `readonly object[]` to avoid TypeScript's weak type detection
- * (all-optional constraint rejection).
- *
- * ```
- * Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
- *   but required in type
- *     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
- * ```
- */
-type ValidateVariadicArgs<A extends readonly object[], Existing extends string = never> = A extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Tail extends readonly [unknown, ...unknown[]] ? Head extends {
-  variadic: true;
-} ? readonly [ArgChecks<Head, Existing> & {
-  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
-}, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>] : { [I in keyof A]: ArgChecks<A[I], Existing>; };
-type BrandVariadicPosition<A extends readonly object[]> = { [I in keyof A]: A[I] & {
-  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
-}; };
-type AppendArgsChecks<A extends ArgsDef, NewA extends ArgsDef> = A extends readonly [...unknown[], infer Last] ? Last extends {
-  variadic: true;
-} ? BrandVariadicPosition<ValidateVariadicArgs<NewA, ArgNames<A>>> : ValidateVariadicArgs<NewA, ArgNames<A>> : ValidateVariadicArgs<NewA>;
-/** Conditional collections and uncertain canonical identities cannot promise every alternative output key. */
-type AttachedArgs<A extends ArgsDef> = HasClosedNames<A> extends true ? A : ArgsDef;
-//#endregion
-//#region src/validation/commands.brands.d.ts
-/** Preserve configured aliases; only a genuinely absent field proves an empty set. */
-type AliasesOf<C> = C extends {
-  readonly aliases: infer A extends readonly string[];
-} ? A : "aliases" extends keyof C ? readonly string[] : readonly [];
-type NarrowAliases<A extends readonly string[]> = IsClosedName<A[number]> extends true ? A[number] : never;
-type AliasMembers<A extends readonly string[]> = ClosedMembers<A[number]>;
-type AliasShapeError<Name extends string, Alias extends string> = Alias extends "" ? `Subcommand "${Name}" has an invalid alias: must be a non-empty string` : Alias extends `${string} ${string}` | `${string}\t${string}` | `${string}\n${string}` | `${string}\r${string}` | `${string}\v${string}` | `${string}\f${string}` ? `Subcommand "${Name}" alias "${Alias}" must not contain whitespace` : Alias extends `-${string}` ? `Subcommand "${Name}" alias "${Alias}" must not start with "-" (reserved for flags)` : string extends Name ? never : Alias extends Name ? `Subcommand "${Name}" alias "${Alias}" must not equal its own canonical name` : never;
-type AliasShapeErrors<Name extends string, C> = AliasMembers<AliasesOf<C>> extends (infer Alias) ? Alias extends string ? AliasShapeError<Name, Alias> : never : never;
-type AliasShapeBrand<Name extends string, C> = [AliasShapeErrors<Name, C>] extends [never] ? {} : {
-  readonly FIX_ALIAS_SHAPE: AliasShapeErrors<Name, C>;
-};
-type RootVersionBrand<C> = "version" extends keyof C ? {
-  readonly FIX_ROOT_VERSION: "Command config \"version\" belongs on the root Crust constructor";
-} : {};
-/** Brand command config containing statically known invalid metadata. */
-type ValidateCommandConfig<Name extends string, C> = AliasShapeBrand<Name, C> & RootVersionBrand<C>;
-type EmptyNameError = {
-  readonly FIX_EMPTY_NAME: "Command name must be a non-empty string";
-};
-type TrimWhitespace = " " | "\t" | "\n" | "\r" | "\v" | "\f" | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | "　" | "";
-type BlankName<Name extends string> = Name extends `${TrimWhitespace}${infer Tail}` ? BlankName<Tail> : Name extends "" ? true : false;
-/** Runtime checks own open members; every statically known member is validated, even beside an open one. */
-type CommandNameBrand<Name extends string> = true extends BlankName<ClosedMembers<Name>> ? EmptyNameError : "__proto__" extends ClosedMembers<Name> ? {
-  readonly FIX_RESERVED_NAME: "Command name \"__proto__\" is reserved";
-} : {};
-type DefinitionAliases<D> = CommandDefinitionData<D> extends {
-  readonly _aliases?: infer A extends readonly string[];
-} ? A : readonly string[];
-/** All statically known canonical and alias spellings carried by a command definition. */
-type CommandDefinitionSpellings<D> = D extends unknown ? D extends {
-  name: infer N extends string;
-} ? IsUnion<N> extends true ? never : DefName<D> extends (infer Name extends string) ? [Name] extends [never] ? never : Name | NarrowAliases<DefinitionAliases<D>> : never : never : never;
-type SelfAliasBrand<D> = UnionToIntersection<D extends unknown ? DefNameMembers<D> & AliasMembers<DefinitionAliases<D>> extends (infer Dup extends string) ? [Dup] extends [never] ? {} : {
-  readonly FIX_ALIAS_SHAPE: `Command "${Dup}" must not list its own canonical name as an alias`;
-} : never : never>;
-type CommandCollisionBrand<Spellings extends string, Existing extends string> = CollisionBrand<Spellings, Existing, "FIX_COMMAND_COLLISION", "Command name or alias ", " collides with a sibling command">;
-/**
- * Validate definitions against existing siblings and definitions earlier in
- * the same `.add()` call. Widened names opt out because their spellings are
- * not statically knowable; their literal aliases opt out with them
- * (see {@link CommandDefinitionSpellings}).
- */
-type ValidateCommandDefinitions<Ds extends readonly unknown[], Existing extends string = never> = Ds extends readonly [infer Head, ...infer Tail] ? CommandDefinitionSpellings<Head> extends (infer Spellings extends string) ? readonly [Head & CommandCollisionBrand<Spellings, Existing> & CommandNameBrand<DefNameMembers<Head>> & SelfAliasBrand<Head>, ...ValidateCommandDefinitions<Tail, Existing | Spellings>] : never : Ds;
-type ExtensionCommandDefs<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
-  readonly commands?: infer Cs extends readonly unknown[];
-} ? Cs : readonly [];
-/** An uncertain command collection opens only the child namespace. */
-type ExtensionCommandSpellings<E> = AttachedCommandSpellings<ExtensionCommandDefs<E>>;
-type ExtensionsCommandSpellings<Es extends readonly unknown[]> = IsStaticTuple<Es> extends true ? { [I in keyof Es]: ExtensionCommandSpellings<Es[I]>; }[number] : ExtensionCommandDefs<Es[number]>[number] extends never ? never : string;
-type ExtensionCommandCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionCommandSpellings<E>, Existing, "FIX_COMMAND_COLLISION", "Extension command ", " collides with an existing command">;
-/**
- * Validate each Extension's contributed command spellings against existing
- * root commands and against Extensions earlier in the same `.extend()` call.
- * Runtime preparation resolves collisions last-write-wins, so a statically
- * known collision would silently retype `run()` against a command that
- * dispatch replaces.
- */
-type ValidateExtensionCommands<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionCommandCollisionBrand<H, Existing>, ...ValidateExtensionCommands<T, Existing | ExtensionCommandSpellings<H>>] : Es;
-/** Local metadata checks; unrelated description/version/usage text has no grammar. */
-type SectionTextBrand<S> = S extends {
-  title: infer T extends string;
-  body: infer B extends string;
-} ? true extends BlankName<T> | BlankName<B> ? {
-  readonly FIX_SECTION_TEXT: "Section title/body must be nonblank";
-} : Extract<T, `${string}\r${string}` | `${string}\n${string}`> extends never ? {} : {
-  readonly FIX_SECTION_TEXT: "Section title must be a single line";
-} : {};
-type SectionAudienceBrand<S> = S extends {
-  only: readonly [];
-} | {
-  except: readonly [];
-} ? {
-  readonly FIX_SECTION_AUDIENCE: "Section audience must be nonempty";
-} : {};
-type LocalSectionsBrand<C> = "sections" extends keyof C ? C extends {
-  sections: infer S extends readonly unknown[];
-} ? {
-  readonly sections: { [I in keyof S]: S[I] & UnionToIntersection<SectionTextBrand<S[I]>> & UnionToIntersection<SectionAudienceBrand<S[I]>>; };
-} : {} : {};
-type LocalCommandConfigBrand<N extends string, C> = ValidateCommandConfig<N, C> & LocalSectionsBrand<C>;
-type AttachedCommandSpellings<Ds extends readonly unknown[]> = [Ds] extends [readonly []] ? never : IsStaticTuple<Ds> extends true ? HasClosedNames<Ds> extends true ? false extends { [I in keyof Ds]: IsClosedName<DefinitionAliases<Ds[I]>[number]>; }[number] ? string : CommandDefinitionSpellings<Ds[number]> : string : string;
-//#endregion
-//#region src/validation/contexts.brands.d.ts
-/** Canonical names claimed by more than one instance in the same `.provide()` call. */
-type DuplicateContextNames<Cs extends readonly AnyContextInstance[], Seen extends string = never> = Cs extends readonly [infer Head, ...infer Tail extends readonly AnyContextInstance[]] ? (DefName<Head> & Seen) | DuplicateContextNames<Tail, Seen | DefName<Head>> : never;
-type DuplicateContextBrand<C, Existing extends string> = CollisionBrand<DefName<C>, Existing, "FIX_DUPLICATE_CONTEXT", "Context ", " is already provided on this command path">;
-/**
- * Brand instances whose name is already provided on this builder chain or
- * repeated within the same `.provide()` call. The accumulated Context value
- * map doubles as the name registry (its keys are the provided names), so no
- * separate accumulator is needed. Wrappers generic over the builder type
- * use `any`, which opts out via the
- * `string extends keyof Ctx` guard instead of deferring. Widened names opt
- * out via `DefName`; a parent-provided Context is not in the definition's
- * `Ctx` and therefore cannot be checked at this call site.
- */
-type ValidateContextNames<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Existing extends string = string extends keyof Ctx ? never : keyof Ctx & string, Dups extends string = DuplicateContextNames<Cs>> = { [I in keyof Cs]: Cs[I] & DuplicateContextBrand<Cs[I], Existing | Dups>; };
-type InstanceNames<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? DefName<H> | InstanceNames<T> : never;
-/** Statically known names of an Extension's provided Contexts; widened Extensions opt out. */
-type ExtensionProvidedNames<E> = DefiningOf<E> extends {
-  readonly provides?: infer P extends readonly unknown[];
-} ? InstanceNames<P> : never;
-type ExtensionContextBrand<E, Existing extends string> = CollisionBrand<ExtensionProvidedNames<E>, Existing, "FIX_DUPLICATE_CONTEXT", "Extension-provided Context ", " is already provided on this command path">;
-type ValidateExtensionProvidesWorker<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionContextBrand<H, Existing>, ...ValidateExtensionProvidesWorker<T, Existing | ExtensionProvidedNames<H>>] : Es;
-/**
- * Brand Extensions whose provided Context names replace one already on the
- * command path (or one provided by an earlier Extension in the same call).
- * The resolver is last-write-wins, so a silent replacement would hand actions
- * bound before `.extend()` a value of a different static type.
- */
-type ValidateExtensionProvides<Es extends readonly unknown[], Ctx extends ContextMap> = ValidateExtensionProvidesWorker<Es, string extends keyof Ctx ? never : keyof Ctx & string>;
-type ProvidedDepsOf<C> = IsAny<C> extends true ? {} : IsAny<ContextDepsOf<C>> extends true ? {} : string extends keyof ContextDepsOf<C> ? {} : ContextDepsOf<C>;
-type MissingDependencyBrand<C, Known extends string> = Exclude<keyof ProvidedDepsOf<C> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
-  readonly FIX_MISSING_DEPENDENCY: `Context "${DefName<C>}" uses Context "${Missing}" which is not provided on this command path`;
-} : never;
-type MismatchedDependencyNames<Deps, KnownValues> = keyof Deps extends never ? never : KnownValues extends unknown ? { [K in keyof Deps & keyof KnownValues & string]: IsAny<KnownValues[K]> extends true ? never : IsAny<Deps[K]> extends true ? never : [unknown, string] extends [KnownValues[K], keyof KnownValues] ? never : KnownValues[K] extends Deps[K] ? never : K; }[keyof Deps & keyof KnownValues & string] : never;
-type MismatchedDependencyBrand<C, KnownValues> = MismatchedDependencyNames<ProvidedDepsOf<C>, KnownValues> extends (infer Mismatched extends string) ? [Mismatched] extends [never] ? {} : {
-  readonly FIX_DEPENDENCY_TYPE: `Context "${DefName<C>}" uses Context "${Mismatched}" whose provided value does not satisfy the declared dependency type`;
-} : never;
-/** Brand provided instances whose transitive dependency closure is unsatisfied. */
-type ValidateContextDeps<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Known extends string = (keyof Ctx & string) | DefName<Cs[number]>, KnownValues extends ContextMap = Ctx & ContextsOutput<Cs>> = { [I in keyof Cs]: Cs[I] & MissingDependencyBrand<Cs[I], Known> & MismatchedDependencyBrand<Cs[I], KnownValues>; };
-/** Dependency closure carried by command definitions and Extensions. */
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type DeclaredDepsOf<T> = IsAny<T> extends true ? Record<string, ContextValue> : CommandDefinitionData<DefiningOf<T>> extends {
-  readonly _deps?: infer D extends ContextMap;
-} ? IsAny<D> extends true ? Record<string, ContextValue> : D : {};
-/** Missing-dependency brand shared by `ValidateDeclaredDeps` and inline `.command()`. */
-type MissingDeclaredDependencyBrand<T, Known extends string> = string extends keyof DeclaredDepsOf<T> ? {} : Exclude<keyof DeclaredDepsOf<T> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
-  readonly FIX_MISSING_DEPENDENCY: `Uses Context "${Missing}" which is not provided`;
-} : never;
-/** Brand sealed units whose declared dependencies are absent at a composition site. */
-type ValidateDeclaredDeps<Ctx extends ContextMap, Items extends readonly unknown[]> = { [I in keyof Items]: Items[I] & MissingDeclaredDependencyBrand<Items[I], keyof Ctx & string> & DeclaredDependencyValuesBrand<DeclaredDepsOf<Items[I]>, Ctx>; };
-/** Callback values stay TypeScript-owned, including at dynamic composition. */
-type DeclaredDependencyValuesBrand<Deps, Values> = MismatchedDependencyNames<Deps, Values> extends (infer Names extends string) ? [Names] extends [never] ? {} : {
-  readonly FIX_DEPENDENCY_TYPE: `Provided Context "${Names}" does not satisfy its declared value type`;
-} : never;
-/** Structural provider copies retain their defining name. */
-type KnownContextInstances<Cs extends readonly AnyContextInstance[]> = { [I in keyof Cs]: Cs[I] & Pick<DefiningOf<Cs[I]>, "name">; };
-//#endregion
-//#region src/validation/flags.brands.d.ts
-/** Brand an incoming definition when one of its spellings is already claimed. */
-type ExistingFlagCollisionBrand<F, Existing extends string> = CollisionBrand<DefName<F> | ExtractAllAliases<F>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
-/**
- * Every statically known canonical, short, and long-alias member, including literals
- * beside an open member. Spelling grammar only: collision evidence stays with
- * {@link ExtractAllAliases}, which must not leak literals out of an open domain.
- * Each field is filtered on its own so a `string`-typed field cannot absorb a
- * sibling field's invalid literal before the filter runs.
- */
-type SpellingMembers<F> = DefNameMembers<F> | ClosedMembers<F extends {
-  short: infer S extends string;
-} ? S : never> | ClosedMembers<F extends {
-  aliases: infer A extends readonly string[];
-} ? A[number] : never>;
-/** Reject `__proto__`, which mutates the prototype of plain-object flag registries. */
-type ReservedSpellingBrand<F> = "__proto__" extends SpellingMembers<F> ? {
-  readonly FIX_RESERVED_SPELLING: "Flag spelling \"__proto__\" is reserved";
-} : {};
-type EmptySpellingError = {
-  readonly FIX_EMPTY_SPELLING: "Flag names and aliases must be non-empty strings";
-};
-/** Reject empty flag names, including an empty member of a name union beside an open member. */
-type EmptyFlagSpellingBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptySpellingError>;
-/** Reject empty spellings: their CLI tokens (`--`, `-`) are unparseable, so the flag can never be supplied. */
-type EmptySpellingBrand<F> = "" extends SpellingMembers<F> ? EmptySpellingError : {};
-type RepeatedAliases<Aliases extends readonly string[], Seen extends string> = Aliases extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? (Head & Seen) | RepeatedAliases<Tail, Seen | Head> : never;
-type OwnAliasesBrand<F> = F extends {
-  aliases: infer Aliases extends readonly string[];
-} ? RepeatedAliases<Aliases, ExtractShort<F>> extends (infer Duplicate extends string) ? [Duplicate] extends [never] ? {} : {
-  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
-} : never : {};
-type InvalidShort<S extends string> = S extends `${infer _First}${infer Rest}` ? Rest extends "" ? never : S : S;
-type ShortLengthBrand<F> = F extends {
-  short: infer Short extends string;
-} ? string extends Short ? {} : [InvalidShort<Short>] extends [never] ? {} : {
-  readonly FIX_SHORT_LENGTH: "Short flags must be one character";
-} : {};
-/**
- * Extract the `short` alias literal from a flag definition.
- * Resolves to `never` when the field is absent or its spelling domain is open.
- */
-type ExtractShort<F> = F extends {
-  short: infer S;
-} ? S extends string ? IsClosedName<S> extends true ? S : never : never : never;
-/**
- * Extract alias string literals from the `aliases` array of a flag definition.
- * Resolves to `never` when the field is absent or its element domain is open.
- */
-type ExtractLongAliases<F> = F extends {
-  aliases: infer A;
-} ? A extends readonly string[] ? IsClosedName<A[number]> extends true ? A[number] : never : never : never;
-/**
- * Extract all alias identifiers (short + long) from a flag definition.
- *
- * Generalized to work with any shape; values without `short`/`aliases`
- * fields resolve to `never`.
- *
- * Closed-name proof excludes open domains from literal collision evidence.
- * Attachment separately keeps their spelling namespace open.
- */
-type ExtractAllAliases<F> = ExtractShort<F> | ExtractLongAliases<F>;
-/** All narrowed canonical, short, and long-alias spellings in a flags record. */
-type SpellingsOf<F extends FlagsDef> = string extends keyof F ? never : (keyof F & string) | { [K in keyof F & string]: ExtractAllAliases<F[K]>; }[keyof F & string];
-type NoPrefixBrand<S extends string> = [Extract<S, `no-${string}`>] extends [never] ? {} : {
-  readonly FIX_NO_PREFIX: "Names must not start with no-";
-};
-type ContextOwnedFlags<C> = C extends unknown ? DefiningOf<C> extends {
-  readonly _ownedFlags?: infer OF extends FlagsDef;
-} ? OF : {} : never;
-type ContextFlagCollisionBrand<C, Existing extends string> = CollisionBrand<LocalSpellingsOf<ContextOwnedFlags<C>>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
-/** Declared flag literals carried by an Extension's `_flagDefs` phantom; widened Extensions opt out. */
-type ExtensionFlagDefsOf<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
-  readonly _flagDefs?: infer D extends readonly NamedFlagDef[];
-} ? D : readonly NamedFlagDef[];
-/** All statically known owned-flag spellings across a tuple of Context instances. */
-type ProvidedContextSpellings<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? LocalSpellingsOf<ContextOwnedFlags<H>> | ProvidedContextSpellings<T> : [P[number]] extends [never] ? never : LocalSpellingsOf<ContextOwnedFlags<P[number]>>;
-/** All statically known flag spellings an Extension contributes: declared flags plus provided Context-owned flags. */
-type ExtensionSpellings<E> = AttachedSpellings<ExtensionFlagDefsOf<E>> | ([E] extends [never] ? never : DefiningOf<E> extends {
-  readonly provides?: infer P extends readonly unknown[];
-} ? ProvidedContextSpellings<P> : never);
-type ExtensionFlagCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionSpellings<E>, Existing, "FIX_ALIAS_COLLISION", "Extension flag spelling ", " collides with an existing flag">;
-/**
- * Validate each Extension's contributed flag spellings against accumulated
- * existing spellings and against Extensions earlier in the same `.extend()`
- * call. Extensions must not override application flags: a silent overwrite
- * would retype an already-bound action's flag at parse time.
- */
-type ValidateExtensionFlags<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionFlagCollisionBrand<H, Existing>, ...ValidateExtensionFlags<T, Existing | ExtensionSpellings<H>>] : Es;
-type ShapeSpellings<S> = 0 extends 1 & S ? string : S extends {
-  readonly flags: infer F extends FlagsDef;
-  readonly children: infer C;
-} ? LocalSpellingsOf<F> | TreeSpellings<C> : never;
-/** Every flag spelling reachable in a compile-time command tree (`Record<spelling, CommandShape>`), recursively. */
-type TreeSpellings<Tree> = 0 extends 1 & Tree ? string : string extends keyof Tree ? string : Tree extends object ? { [K in keyof Tree]: ShapeSpellings<Tree[K]>; }[keyof Tree] : never;
-type DefinitionSpellings<D> = CommandDefinitionData<D> extends {
-  readonly _shape?: infer S;
-} ? ShapeSpellings<S> : never;
-/** Flag spellings contributed by a tuple of command definitions. */
-type DefinitionTreeSpellings<Ds extends readonly unknown[]> = DefinitionSpellings<Ds[number]>;
-/**
- * Extension-collision brand over a built command shape. Shared by `.add()`
- * (via {@link ValidateDefinitionFlags}) and inline `.command()`, whose recipe
- * builder exposes a shape instead of a definition tuple.
- */
-type ShapeFlagCollisionBrand<S, Ext extends string> = CollisionBrand<ShapeSpellings<S>, Ext, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with a registered Extension flag">;
-type DefinitionFlagCollisionBrand<D, Ext extends string> = CommandDefinitionData<D> extends {
-  readonly _shape?: infer S;
-} ? ShapeFlagCollisionBrand<S, Ext> : {};
-/**
- * Validate an added definition tree's flag spellings against already-registered
- * Extension flags. Recursive Extension flags inject into every node at prepare
- * time, so a colliding local flag would be silently retyped for its action.
- */
-type ValidateDefinitionFlags<Ds extends readonly unknown[], Ext extends string> = { [I in keyof Ds]: Ds[I] & DefinitionFlagCollisionBrand<Ds[I], Ext>; };
-/** Union of every statically known flag spelling contributed by a tuple of Extensions. */
-type ExtensionsSpellings<Es extends readonly unknown[]> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? ExtensionSpellings<H> | ExtensionsSpellings<T> : ExtensionSpellings<Es[number]> extends never ? never : string;
-/**
- * Validate Context-owned flags against accumulated existing spellings and
- * against instances earlier in the same `.provide(a(), b())` call. Without
- * the batch check a same-call collision silently resolves last-write-wins,
- * and a required flag shadowed by a peer's alias becomes impossible to supply.
- */
-type ProvideChecks<Sp extends string, Cs extends readonly unknown[]> = Cs extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ContextFlagCollisionBrand<H, Sp>, ...ProvideChecks<Sp | LocalSpellingsOf<ContextOwnedFlags<H>>, T>] : Cs;
-/** Whether canonical and alias spellings form a closed, fixed local namespace. */
-type HasClosedFlagSpellings<F> = F extends {
-  name: infer N extends string;
-} ? false extends IsClosedName<N> | ("short" extends keyof F ? F extends {
-  short: infer S extends string;
-} ? IsClosedName<S> : false : true) | ("aliases" extends keyof F ? F extends {
-  aliases: infer A extends readonly string[];
-} ? false extends IsStaticTuple<A> | IsClosedName<A[number]> ? false : true : false : true) ? false : true : false;
-type LocalFlagBrand<F> = UnionToIntersection<F extends unknown ? LocalFlagBranchBrand<F> : never>;
-type LocalFlagBranchBrand<F> = LocalValueBrand<F> & OwnAliasesBrand<F> & ShortLengthBrand<F> & ReservedSpellingBrand<F> & EmptySpellingBrand<F> & NoPrefixBrand<SpellingMembers<F>> & ([DefName<F> & ExtractAllAliases<F>] extends [never] ? {} : {
-  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
-});
-/** Validate provable local fields and destination relations without inventing names for open inputs. */
-type ValidateLocalFlagDefs<Defs extends readonly NamedFlagDef[], Existing extends string> = Defs & UnionToIntersection<LocalFlagTupleChecks<Defs, Existing>>;
-type LocalFlagTupleChecks<Defs extends readonly NamedFlagDef[], Existing extends string, Errors = {}> = Defs extends readonly [infer Head extends NamedFlagDef, ...infer Tail extends readonly NamedFlagDef[]] ? LocalFlagTupleChecks<Tail, Existing | DefName<Head> | ExtractAllAliases<Head>, Errors & LocalFlagBrand<Head> & ExistingFlagCollisionBrand<Head, Existing>> : Defs extends readonly [] ? Errors : Errors & LocalFlagBrand<Defs[number]>;
-/** An open collection is not an empty or guaranteed-present flag record. */
-type KnownNamedFlag<D> = D extends NamedFlagDef ? HasClosedNames<readonly [D]> extends true ? D : never : never;
-type AttachedFlags<Defs extends readonly NamedFlagDef[]> = HasClosedNames<Defs> extends true ? NamedFlagsRecord<Defs> : IsStaticTuple<Defs> extends true ? FlagsDef & NamedFlagsRecord<readonly KnownNamedFlag<Defs[number]>[]> : FlagsDef;
-type AttachedSpellings<Defs extends readonly NamedFlagDef[]> = IsStaticTuple<Defs> extends true ? false extends { [I in keyof Defs]: HasClosedFlagSpellings<Defs[I]>; }[number] ? string : SpellingsOf<NamedFlagsRecord<Defs>> : string;
-type LocalFlagNameBrand<N extends string> = EmptyFlagSpellingBrand<N> & ReservedSpellingBrand<{
-  name: N;
-}> & NoPrefixBrand<N>;
-/** Broad structural builder holders must not default their spelling state to empty. */
-type LocalSpellingsOf<F extends FlagsDef> = string extends keyof F ? string : true extends { [K in keyof F]: HasClosedFlagSpellings<F[K] & {
-  name: K;
-}> extends false ? true : false; }[keyof F] ? string : SpellingsOf<F>;
-//#endregion
-//#region src/command/crust.d.ts
-/**
- * The runtime context object passed to the Command Action defined with
- * `.action()`.
- *
- * Generic parameters:
- * - `A` — positional argument definitions tuple
- * - `F` — the effective (Context-owned + local merged) flag definitions
- */
-interface CrustCommandContext<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Ctx extends ContextMap = {}> extends InvocationIO {
-  /** Resolved positional arguments, keyed by arg name */
-  args: InferArgs<A>;
-  /** Resolved flags, keyed by flag name */
-  flags: InferFlags<F>;
-  /** Lazy Context values available on this command path. */
-  ctx: ContextBag<Ctx>;
-  /** Raw arguments that appeared after the `--` separator */
-  rawArgs: string[];
-  /** Readonly, serializable snapshot of the resolved command */
-  command: CommandSnapshot;
-  /** Readonly snapshot of the application root, including Extension contributions */
-  rootCommand: CommandSnapshot;
-}
-declare const commandProviders: unique symbol;
-/** Compile-time description of one command's programmatic input and action result. */
-interface CommandShape<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Children extends object = {}, Result = unknown, Providers extends Record<string, ContextValue> = Record<string, ContextValue>> {
-  readonly [commandProviders]?: Providers;
-  readonly args: A;
-  readonly flags: F;
-  readonly children: Children;
-  readonly result: Result;
-}
-/** Captured invocation after lifecycle cleanup. */
-type RunOutcome<Result> = {
-  readonly stdout: string;
-  readonly stderr: string;
-} & ({
-  readonly status: "completed";
-  readonly result: Result;
-} | {
-  readonly status: "finished";
-  readonly by: ExtensionId;
-} | {
-  readonly status: "failed";
-  readonly error: unknown;
-});
-/** Compile-time command tree accumulated by `.add()`. */
-type CommandTree = Record<string, CommandShape>;
-/** Every valid path through a command tree, including the root path (`[]`). */
-type CommandPath<Tree extends object, Depth extends readonly unknown[] = readonly []> = Depth["length"] extends 15 ? readonly string[] : string extends keyof Tree ? readonly string[] : readonly [] | { [K in keyof Tree & string]: Tree[K] extends CommandShape ? readonly [K, ...CommandPath<Tree[K]["children"], readonly [...Depth, unknown]>] : never; }[keyof Tree & string];
-type KnownCommandPath<Path extends readonly string[], Tree> = string extends keyof Tree ? Path : IsStaticTuple<Path> extends true ? string extends Path[number] ? never : Path : never;
-/** Resolve the command shape at a typed path. */
-type CommandShapeAt<Shape extends CommandShape, Path extends readonly string[]> = Path extends readonly [infer Head, ...infer Tail extends readonly string[]] ? Head extends keyof Shape["children"] ? Shape["children"][Head] extends (infer Child extends CommandShape) ? CommandShapeAt<Child, Tail> : never : string extends Head ? CommandShape : never : Path extends readonly [] ? Shape : CommandShape;
-type RunSection<Name extends string, Values> = keyof Values extends never ? { [K in Name]?: never; } : {} extends Values ? { [K in Name]?: Values; } : { [K in Name]: Values; };
-/** Structured values bound directly against the selected command's definitions; no argv is produced. */
-type RunInput<Shape extends CommandShape> = RunSection<"args", ArgsDef extends Shape["args"] ? NonNullable<RunInputPayload["args"]> : InputArgs<Shape["args"]>> & RunSection<"flags", FlagsDef extends Shape["flags"] ? NonNullable<RunInputPayload["flags"]> : InputFlags<Shape["flags"]>> & {
-  readonly raw?: readonly string[];
-};
-type CompatibleRunValue<Expected, Actual> = Actual extends Expected ? Actual extends object ? Expected extends unknown ? Actual extends Expected ? Actual & { [K in Exclude<keyof Actual, keyof Expected>]: never; } & { [K in keyof Actual & keyof Expected]: CompatibleRunValue<Expected[K], Actual[K]>; } : never : never : Actual : JsonValue extends Expected ? Actual extends JsonCompatible<Actual> ? Actual : never : Expected extends unknown ? CompatibleRunBranch<Expected, Actual> : never;
-type CompatibleRunBranch<Expected, Actual> = Actual extends Expected ? Actual : Expected extends readonly (infer Item)[] ? JsonValue extends Item ? Actual extends (Expected extends readonly [unknown, ...unknown[]] ? readonly [unknown, ...unknown[]] : readonly unknown[]) ? Actual extends JsonCompatible<Actual> ? Actual : never : never : never : Actual extends object ? string extends keyof Expected ? { [K in keyof Actual]: CompatibleRunValue<Exclude<Expected[K & keyof Expected], undefined>, Actual[K]>; } : { [K in keyof Expected]: K extends keyof Actual ? CompatibleRunValue<Exclude<Expected[K], undefined>, Actual[K]> : Expected[K]; } & { [K in Exclude<keyof Actual, keyof Expected>]: never; } : never;
-type CompatibleRunInput<Shape extends CommandShape, Input> = CompatibleRunValue<RunInput<Shape>, Input>;
-type RunInputArguments<Shape extends CommandShape> = {} extends RunInput<Shape> ? readonly [input?: RunInput<Shape>] : readonly [input: RunInput<Shape>];
-type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<Shape>, io?: Partial<InvocationIO>];
-/**
- * Typed invoker bound to one command in an app, returned by {@link Crust.at}.
- *
- * `run` accepts the same structured input and IO as `Crust.run` with the path
- * already applied, so a handle can be re-exported as a plain typed function.
- */
-interface CommandHandle<Shape extends CommandShape> {
-  /** The typed path this handle was created with (`[]` selects the root). */
-  readonly path: readonly string[];
-  run(...args: RunArguments<Shape>): Promise<RunOutcome<Shape["result"]>>;
-  run<const Input>(input: Input, ...validation: [Input] extends [CompatibleRunInput<Shape, Input>] ? readonly [io?: Partial<InvocationIO>] : readonly [invalidInput: never]): Promise<RunOutcome<Shape["result"]>>;
-}
-/** Static configuration for a reusable command definition. */
-interface CommandConfig extends Omit<CommandMeta, "name" | "sections" | "version"> {
-  /** Plain-text sections rendered after built-in command documentation. */
-  readonly sections?: readonly RuntimeCommandSectionInput[];
-}
-/** Static metadata accepted by the root command constructor. */
-type RootCommandMeta = Pick<CommandMeta, "description" | "version" | "usage"> & {
-  /** Plain-text sections rendered after built-in command documentation. */
-  readonly sections?: readonly RuntimeCommandSectionInput[];
-};
-type AnyCommandDefinitionBuilder = Crust<any, any, any, any, any, any, any, any, any, any, any, "recipe">;
-type CommandRecipe<Builder extends AnyCommandDefinitionBuilder = AnyCommandDefinitionBuilder> = (command: CommandDefinitionBuilder<{}, [], {}, never, never>) => Builder;
-declare const commandDefinitionInternal: unique symbol;
-interface CommandDefinitionInternal {
-  readonly name: string;
-  readonly recipe: (command: AnyCommandDefinitionBuilder) => AnyCommandDefinitionBuilder;
-  readonly meta: Omit<CommandMeta, "name">;
-}
-type CommandInputShape<S extends CommandShape> = {
-  readonly args: S["args"];
-  readonly flags: S["flags"];
-  readonly providers: S[typeof commandProviders];
-  readonly children: { [K in keyof S["children"]]: S["children"][K] extends CommandShape ? CommandInputShape<S["children"][K]> : never; };
-};
-interface CommandDefinition<Name extends string = string, Aliases extends readonly string[] = readonly string[], Shape extends CommandShape = CommandShape, Deps extends ContextMap = {}> {
-  /** The subcommand name this definition is added under */
-  readonly name: Name;
-  /** The same definition under a different name; configured aliases travel with it. */
-  as<const N extends string>(name: N & CommandNameBrand<N> & ValidateCommandConfig<N, {
-    aliases: Aliases;
-  }>): CommandDefinition<N, Aliases, Shape, Deps>;
-  /** @internal */
-  readonly [commandDefinitionInternal]: CommandDefinitionInternal & {
-    readonly _aliases?: Aliases;
-    readonly _shape?: Shape;
-    readonly _deps?: Deps;
-    readonly proof?: [Shape] extends [never] ? unknown : string extends keyof Shape["flags"] | keyof Deps ? unknown : (state: [CommandInputShape<Shape>, Deps]) => void;
-  };
-}
-/** @internal */
-type CommandDefinitionData<D> = D extends {
-  readonly [commandDefinitionInternal]: infer Data;
-} ? Data : D;
-type AppendedArgs<A extends ArgsDef, NewA extends ArgsDef> = readonly [...A, ...AttachedArgs<NewA>];
-/** Configure-only capability of {@link Crust} passed to command recipes. */
-type CommandDefinitionBuilder<Flags extends FlagsDef = {}, A extends ArgsDef = ArgsDef, Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, Result = void, Deps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<never, never, {}, never, Deps, Providers>, Result, {}, string, "recipe">;
-type ShapeOfBuilder<B> = [B] extends [never] ? CommandShape<[], {}, {}, never, {}> : B extends {
-  readonly _recipeTypes: {
-    shape: infer S extends CommandShape;
-  };
-} ? S : never;
-type DepsOfBuilder<B> = UnionToIntersection<B extends {
-  readonly _recipeTypes: {
-    deps: infer Deps extends ContextMap;
-  };
-} ? Deps : {}> extends (infer Merged extends ContextMap) ? Merged : {};
-type DefinitionShapeForSpelling<D, Spelling extends string> = D extends unknown ? CommandDefinitionData<D> extends {
-  readonly _shape?: infer Shape extends CommandShape;
-} ? Spelling extends CommandDefinitionSpellings<D> ? Shape : never : never : never;
-type ShapeWithInheritedFlags<S, CF extends FlagsDef> = keyof CF extends never ? S : S extends CommandShape<infer SA, infer SF, infer SC, infer SR, infer P> ? CommandShape<SA, MergeFlags<CF, SF>, { [K in keyof SC]: ShapeWithInheritedFlags<SC[K], CF>; }, SR, P> : never;
-type DefinitionsTree<Ds extends readonly CommandDefinition<any, any, any, any>[], CtxFlags extends FlagsDef = {}> = string extends AttachedCommandSpellings<Ds> ? Record<string, CommandShape> & KnownDefinitionTree<Ds, CtxFlags> : { [K in CommandDefinitionSpellings<Ds[number]>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<Ds[number], K>, CtxFlags>; };
-type KnownDefinitionTree<Ds extends readonly unknown[], CF extends FlagsDef> = IsUnion<Ds> extends true ? {} : Ds extends readonly [infer H, ...infer T] ? (IsUnion<H> extends true ? {} : { [K in CommandDefinitionSpellings<H>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<H, K>, CF>; }) & KnownDefinitionTree<T, CF> : {};
-type ExtensionCheckAt<Checks, I> = I extends keyof Checks ? Checks[I] : never;
-type ExtensionCommands<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? readonly [...ExtensionCommandDefs<H>, ...ExtensionCommands<T>] : ExtensionCommandDefs<Es[number]>[number] extends never ? readonly [] : readonly CommandDefinition<any, any, any, any>[];
-type ExtensionProviders<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
-  provides?: infer P extends readonly AnyContextInstance[];
-} ? P : [];
-type ExtensionOwnDefs<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
-  _flagDefs?: infer F extends readonly NamedFlagDef[];
-} ? F : [];
-type ExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? AttachedFlags<ExtensionOwnDefs<H>> & ContextsOwnedFlags<ExtensionProviders<H>> & ExtensionFlags<T> : ExtensionOwnDefs<Es[number]>[number] extends never ? keyof ContextsOwnedFlags<ExtensionProviders<Es[number]>> extends never ? {} : FlagsDef : FlagsDef;
-type RecursiveFlagsOf<E> = ExtensionOwnDefs<E>[number] extends never ? {} : true extends { [K in keyof ExtensionOwnDefs<E>]: ExtensionOwnDefs<E>[K] extends (infer D extends NamedFlagDef) ? D extends {
-  readonly recursive: false;
-} ? false : IsClosedName<D["name"]> extends false ? true : IsUnion<D["name"]> extends true ? true : D extends {
-  recursive: infer R;
-} ? boolean extends R ? true : false : false : false; }[number] ? FlagsDef : IsStaticTuple<ExtensionOwnDefs<E>> extends true ? { [D in ExtensionOwnDefs<E>[number] as D extends {
-  readonly recursive: infer R;
-} ? [R] extends [false] ? never : D["name"] : D["name"]]: Omit<D, "name">; } : FlagsDef;
-type RecursiveExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? RecursiveFlagsOf<H> & ContextsOwnedFlags<ExtensionProviders<H>> & RecursiveExtensionFlags<T> : ExtensionFlags<Es>;
-type TreeWithInheritedFlags<Tree, F extends FlagsDef> = { [K in keyof Tree]: ShapeWithInheritedFlags<Tree[K], F>; };
-type ReplacementTree<Tree, D extends CommandDefinition<any, any, any, any>, CF extends FlagsDef> = CommandDefinitionData<D> extends {
-  readonly _aliases?: infer Aliases extends readonly string[];
-} ? IsClosedName<Aliases[number]> extends false ? Record<string, CommandShape> & { [K in D["name"]]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Omit<Tree, CommandDefinitionSpellings<D>> & { [K in CommandDefinitionSpellings<D>]: K extends D["name"] ? ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF> : K extends keyof Tree ? CommandShape : ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Record<string, CommandShape>;
-type ReplacedTree<Tree, Commands extends readonly unknown[], CF extends FlagsDef> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly unknown[]] ? ReplacedTree<IsClosedName<H["name"]> extends false ? Record<string, CommandShape> : true extends IsUnion<H> | IsUnion<H["name"]> ? Record<string, CommandShape> : ReplacementTree<Tree, H, CF>, T, CF> : number extends Commands["length"] ? Record<string, CommandShape> : Tree;
-type ReplacedExtensionTree<Tree, Es extends readonly AnyExtension[], CF extends FlagsDef> = Es extends readonly [infer H extends AnyExtension, ...infer T extends readonly AnyExtension[]] ? ReplacedExtensionTree<ReplacedTree<Tree, ExtensionCommandDefs<H>, CF>, T, CF> : ExtensionCommandDefs<Es[number]>[number] extends never ? Tree : Record<string, CommandShape>;
-type ExtendedTree<Tree, Es extends readonly AnyExtension[], RecursiveFlags extends FlagsDef, InheritedFlags extends FlagsDef> = keyof RecursiveFlags extends never ? ReplacedExtensionTree<Tree, Es, InheritedFlags> : TreeWithInheritedFlags<ReplacedExtensionTree<Tree, Es, InheritedFlags>, RecursiveFlags>;
-/**
- * Define a reusable, inert command under a required name.
- *
- * The recipe runs once per `.add()`, receiving a fresh builder.
- *
- * Static metadata belongs in `config`. Use `.as(name)`
- * to add one definition under a different name; configured aliases travel with it.
- */
-export declare function defineCommand<const Name extends string, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, readonly [], ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
-export declare function defineCommand<const Name extends string, const C extends CommandConfig, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, config: C & LocalCommandConfigBrand<Name, C>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, AliasesOf<C>, ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
-/**
- * Chainable builder for defining CLI commands with full type inference.
- *
- * Generic parameters:
- * - `Flags` — flags defined locally or installed by provided Contexts
- * - `A` — positional argument definitions
- * - `Ctx` — provided Context values
- * - `Sibs` — sibling command names and aliases already registered
- * - `Sp` — accumulated flag spellings used for collision checks
- * - `Tree` — command shapes accumulated by `.add()` for typed `run()`
- * - `CtxFlags` — Context-owned flags accumulated by `.provide()` and recursive
- *   Extension flags accumulated by `.extend()`, inherited by the shapes of
- *   definitions added afterwards
- * - `Result` — awaited return type of this command's action
- * - `Meta` — authored root metadata available to Extension requirements
- * - `Caps` — root application or configure-only recipe capabilities
- *
- * @example
- * ```ts
- * const app = new Crust("my-cli")
- *   .flags({ name: "verbose", type: "boolean", short: "v" })
- *   .args({ name: "file", type: "string", required: true })
- *   .action(({ args, flags }) => {
- *     console.log(args.file, flags.verbose);
- *   });
- * ```
- */
-type CollisionSpellings<Extensions extends string = never, Tree extends string = never, Demands extends ContextMap = {}, Pending extends string = never, RecipeDeps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}, ActionDeps extends ContextMap = {}> = {
-  readonly actionDeps: ActionDeps;
-  readonly pending: Pending;
-  readonly demands: Demands;
-  readonly extension: Extensions;
-  readonly tree: Tree;
-  readonly recipeDeps: RecipeDeps;
-  readonly providers: Providers;
-};
-type AnyCollisionSpellings = {
-  readonly actionDeps?: ContextMap;
-  readonly pending: string;
-  readonly demands: ContextMap;
-  readonly extension: string;
-  readonly tree: string;
-  readonly recipeDeps?: ContextMap;
-  readonly providers?: Record<string, ContextValue>;
-};
-type RecipeDepsOf<S extends AnyCollisionSpellings> = S extends {
-  readonly recipeDeps: infer Deps extends ContextMap;
-} ? Deps : {};
-type ProvidersOf<S extends AnyCollisionSpellings> = S extends {
-  readonly providers: infer Providers extends Record<string, ContextValue>;
-} ? Providers : {};
-/** Obligations of this node's stored action, never inherited by descendants. */
-type ActionDepsOf<S extends AnyCollisionSpellings> = S extends {
-  readonly actionDeps: infer Deps extends ContextMap;
-} ? Deps : {};
-type AfterFlags<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Defs extends readonly NamedFlagDef[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, AttachedFlags<Defs>>, A, Ctx, Sibs, Sp | AttachedSpellings<Defs>, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
-type AfterArgs<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, NewA extends ArgsDef, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, AppendedArgs<A, NewA>, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
-type AfterUse<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Fs extends readonly AnyContextFactory[], Meta extends RootCommandMeta | undefined> = Crust<Flags, A, MergeContext<Ctx, ContextDependencies<Fs>>, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], MergeContext<RecipeDepsOf<CollisionSp>, ContextDependencies<Fs>>, ProvidersOf<CollisionSp>, ActionDepsOf<CollisionSp>>, Result, Meta, string, "recipe">;
-type AfterProvide<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Cs extends readonly AnyContextInstance[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ContextsOwnedFlags<Cs>>, A, MergeProviders<Ctx, ContextsOutput<Cs>>, Sibs, Sp | LocalSpellingsOf<ContextsOwnedFlags<Cs>>, Tree, MergeFlags<CtxFlags, ContextsOwnedFlags<Cs>>, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ContextsOutput<Cs>>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
-type AfterAction<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, R, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, Omit<CollisionSp, "actionDeps"> & {
-  readonly actionDeps: Ctx;
-}, Awaited<R>, Meta, string, Caps>;
-type AfterExtend<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Es extends readonly AnyExtension[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ExtensionFlags<Es>>, A, MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Sibs | ExtensionsCommandSpellings<Es>, Sp | ExtensionsSpellings<Es>, ExtendedTree<Tree, Es, RecursiveExtensionFlags<Es>, CtxFlags>, MergeFlags<CtxFlags, RecursiveExtensionFlags<Es>>, CollisionSpellings<CollisionSp["extension"] | ExtensionsSpellings<Es>, CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, CollisionSp["demands"] & ExtensionDemandValues<Es>, CollisionSp["pending"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ExtensionsProvidesOutput<Es>>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
-type AfterAdd<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Ds extends readonly CommandDefinition<any, any, any, any>[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs | AttachedCommandSpellings<Ds>, Sp, Tree & DefinitionsTree<Ds, CtxFlags>, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"] | DefinitionTreeSpellings<Ds>, CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, ProvidersOf<CollisionSp>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
-type ExtensionDemandValues<Es extends readonly AnyExtension[]> = UnionToIntersection<DefiningOf<Es[number]> extends {
-  readonly _hookDeps?: infer H extends ContextMap;
-} ? H : Record<string, ContextValue>> extends (infer D extends ContextMap) ? D : {};
-type DescendantShapeValuesBrand<S, Deps> = S extends CommandShape ? DeclaredDependencyValuesBrand<Deps, NonNullable<S[typeof commandProviders]>> & DescendantValuesBrand<S["children"], Deps> : {};
-type DescendantValuesBrand<Tree, Deps> = keyof Deps extends never ? {} : UnionToIntersection<Tree extends unknown ? keyof Tree extends never ? {} : { [K in keyof Tree]: DescendantShapeValuesBrand<Tree[K], Deps>; }[keyof Tree] : never>;
-type DefinitionDescendantValuesBrand<Ds extends readonly CommandDefinition<any, any, any, any>[], Deps> = DescendantValuesBrand<DefinitionsTree<Ds>, Deps>;
-type ValidateInlineCommandDeps<Ctx extends ContextMap, B> = MissingDeclaredDependencyBrand<{
-  readonly _deps?: DepsOfBuilder<B>;
-}, keyof Ctx & string> & DeclaredDependencyValuesBrand<DepsOfBuilder<B>, Ctx>;
-/** Completed applications expose inspection and invocation, not authoring after erasure. */
-type AnyCrust = Pick<Crust<FlagsDef, ArgsDef, Record<string, ContextValue>, string, string, CommandTree, FlagsDef, AnyCollisionSpellings, unknown, RootCommandMeta>, "_types" | "run" | "execute" | "snapshot">;
-type DefinedRootMetaKeys<Meta extends RootCommandMeta | undefined> = { [K in RootMetaKey]: [Meta] extends [Required<Pick<RootCommandMeta, K>>] ? K : never; }[RootMetaKey];
-export declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, CollisionSp extends AnyCollisionSpellings = CollisionSpellings, Result = void, const out Meta extends RootCommandMeta | undefined = {}, const Name extends string = string, Caps extends "app" | "recipe" = "app"> {
-  private readonly _contextProof;
-  /** @internal — recipe state, without structural inference through builder methods. */
-  readonly _recipeTypes: {
-    readonly shape: CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>;
-    readonly deps: RecipeDepsOf<CollisionSp>;
-    readonly proof?: (state: [CommandInputShape<CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>>, RecipeDepsOf<CollisionSp>]) => void;
-  };
-  /** Supported type-level seam exposing the application's inferred command types. */
-  readonly _types: {
-    flags: Flags;
-    args: A;
-    ctx: Ctx;
-    tree: Tree;
-    shape: CommandShape<A, Flags, Tree, Result>;
-    readonly rootMeta: Meta;
-    readonly caps: Caps;
-  };
-  /** @internal */
-  _node: CommandNode;
-  /** @internal — Recipe-builder lineage anchor, unique per materialization and preserved by clones */
-  _ancestorOwnedFlags: FlagsDef;
-  /**
-   * Create a new root command builder.
-   *
-   * @param name - The command name.
-   * @param metadata - Optional root description, version, usage, and documentation sections.
-   */
-  constructor(nameInput: (Name & CommandNameBrand<Name>) & ({} extends Meta ? {} : {
-    readonly FIX_ROOT_META: "This root requires metadata";
-  }));
-  constructor(nameInput: Name & CommandNameBrand<Name>, meta: Meta & (undefined | (RootCommandMeta & LocalSectionsBrand<NoInfer<NonNullable<Meta>>> & { [K in Exclude<keyof Meta, RootMetaKey>]: never; })));
-  /** @internal — Clone this builder with a new node, preserving generics. */
-  _clone<Out = this>(nodeOverrides: Partial<CommandNode>): Out;
-  /**
-   * Define local flags for this command from named flag definitions
-   * (created with `defineFlag(name, def)` or written inline as
-   * `{ name: "dry-run", type: "boolean" }`).
-   *
-   * Repeated `.flags()` calls accumulate local flags. Returns a new builder
-   * with the combined local flag types. The original builder is not mutated.
-   *
-   * @param defs - Named flag definitions
-   * @returns A new `Crust` instance with the given flags
-   */
-  flags<const Defs extends readonly NamedFlagDef[], _Union extends this = never>(...defs: ValidateLocalFlagDefs<Defs, Sp>): AfterFlags<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Defs, Meta, Caps>;
-  /**
-   * Define positional arguments for this command; argument order is the
-   * order they are passed (created with `defineArg(name, def)` or written
-   * inline).
-   *
-   * Repeated `.args()` calls append in call order. Returns a new builder with
-   * the combined args types. The original builder is not mutated.
-   *
-   * @param defs - Positional argument definitions, in positional order
-   * @returns A new `Crust` instance with the combined args
-   */
-  args<const NewA extends ArgsDef, _Union extends this = never>(...defs: NewA & AppendArgsChecks<A, NewA>): AfterArgs<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, NewA, Meta, Caps>;
-  /**
-   * Declare Contexts this command consumes without supplying their values.
-   * Factory references are retained while setup stays lazy.
-   */
-  use<const Fs extends readonly [AnyContextFactory, ...AnyContextFactory[]] = never>(this: {
-    readonly _types: {
-      readonly caps: "recipe";
-    };
-  }, ...factories: Fs & DeclaredDependencyValuesBrand<ContextDependencies<Fs>, ProvidersOf<CollisionSp>>): AfterUse<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Fs, Meta>;
-  /**
-   * Attach Contexts — named command dependencies — to this command.
-   *
-   * Contexts are inherited by descendant commands and constructed lazily when
-   * their `ctx` property is accessed. Dependency order within one call does not
-   * affect construction. Disposable values are released in
-   * reverse construction order after post-run hooks. TypeScript rejects known Context-owned flag collisions, including pending
-   * Extension commands. Consuming operations throw `DEFINITION` for actual collisions.
-   *
-   */
-  provide<const Cs extends readonly AnyContextInstance[] = never>(...instances: KnownContextInstances<Cs> & ProvideChecks<Sp | CollisionSp["pending"], Cs> & ValidateContextNames<Caps extends "recipe" ? ProvidersOf<CollisionSp> : Ctx, Cs> & ValidateContextDeps<Ctx, Cs> & DeclaredDependencyValuesBrand<CollisionSp["demands"] & RecipeDepsOf<CollisionSp> & ActionDepsOf<CollisionSp>, ContextsOutput<NoInfer<Cs>>>): AfterProvide<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Cs, Meta, Caps>;
-  /**
-   * Define the Command Action — the function that implements this
-   * command's behavior after its inputs are ready.
-   *
-   * The action receives a {@link CrustCommandContext} with `args` typed from
-   * `.args()` and `flags` typed from the accumulated `Flags`.
-   *
-   * Calling `.action()` again replaces the command behavior and its Context obligations
-   * on the new builder. Later local providers must satisfy the bound Context value types;
-   * descendants may shadow independently. The original builder is not mutated.
-   *
-   * @param action - The Command Action function
-   * @returns A new `Crust` instance with the action registered
-   */
-  action<R>(action: (ctx: NoInfer<CrustCommandContext<A, Flags, Ctx>>) => R): AfterAction<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, R, Meta, Caps>;
-  /**
-   * Register one or more CLI Extensions on the application root.
-   *
-   * Extensions are application-wide: they own the flags and commands they
-   * contribute. Repeated calls accumulate Extensions in registration order,
-   * except that registering an `ExtensionId` again keeps only the last
-   * registration — its contributions and providers replace the earlier ones
-   * and its hooks run once, at the later position. ID deduplication is
-   * runtime-only, so removed paths can remain statically visible and reject
-   * with `COMMAND_NOT_FOUND`. Canonical replacements use the new
-   * shape; open replacements and ambiguous aliases have unknown results.
-   * Required root metadata keys are checked against the constructor's inferred
-   * metadata by TypeScript, not at runtime.
-   * Recipe builders cannot call this root-only method.
-   */
-  extend<const Es extends readonly Extension<any, any, any, any, DefinedRootMetaKeys<Meta>>[], _Union extends this = never>(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, ...extensions: Es & { [I in keyof Es]: (ExtensionCommandDefs<Es[I]> extends ValidateDefinitionFlags<ExtensionCommandDefs<Es[I]>, LocalSpellingsOf<CtxFlags>> ? {} : {
-    readonly FIX_ALIAS_COLLISION: "Extension command flags collide with inherited Context flags";
-  }) & ValidateDeclaredDeps<MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Es>[I] & DeclaredDependencyValuesBrand<CollisionSp["demands"], MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>> & DescendantValuesBrand<Tree, ExtensionDemandValues<Es>> & DefinitionDescendantValuesBrand<ExtensionCommands<Es>, CollisionSp["demands"] & ExtensionDemandValues<Es>> & ExtensionCheckAt<ValidateExtensionFlags<Es, Sp | CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>>, I> & ExtensionCheckAt<ValidateExtensionCommands<Es, Sibs>, I> & ExtensionCheckAt<ValidateExtensionProvides<Es, Ctx>, I>; }): AfterExtend<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Es, Meta, Caps>;
-  /**
-   * Materialize and register inert reusable command definitions, each
-   * under its own carried name (use `.as(name)` to rename).
-   *
-   */
-  add<const Ds extends readonly CommandDefinition<any, any, any, any>[] = never>(...definitions: Ds & ValidateCommandDefinitions<Ds, Sibs> & ValidateDeclaredDeps<Ctx, Ds> & DefinitionDescendantValuesBrand<Ds, CollisionSp["demands"]> & ValidateDefinitionFlags<Ds, CollisionSp["extension"] | LocalSpellingsOf<CtxFlags>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Ds, Meta, Caps>;
-  /**
-   * Define an app-local leaf subcommand inline (root-only sugar for
-   * `.add(defineCommand(name, recipe))`).
-   *
-   * The recipe builder is seeded with the Contexts and Context-owned flags
-   * accumulated on this builder so far — the call site. Contexts provided
-   * after `.command()` are not visible to it, matching the positional runtime
-   * semantics of `.provide()`. Extract to `defineCommand` when a command needs
-   * its own file, reuse, or a package. Recipe builders cannot call this
-   * root-only method.
-   */
-  command<const N extends string, B extends AnyCommandDefinitionBuilder>(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, name: N & CommandNameBrand<N> & CommandCollisionBrand<N, Sibs>, recipe: ((command: CommandDefinitionBuilder<{}, [], Ctx, never, LocalSpellingsOf<CtxFlags>, {}, CtxFlags>) => B & ShapeFlagCollisionBrand<ShapeOfBuilder<B>, CollisionSp["extension"]> & ValidateInlineCommandDeps<Ctx, NoInfer<B>>) & NoInfer<DescendantValuesBrand<{
-    child: ShapeOfBuilder<B>;
-  }, CollisionSp["demands"]>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, readonly [CommandDefinition<N, readonly [], ShapeOfBuilder<B>, DepsOfBuilder<B>>], Meta, Caps>;
-  private _addDefinitions;
-  /**
-   * Prepare a frozen Command Snapshot for tooling such as man-page, skill,
-   * and build generators.
-   *
-   * Materializes Extension contributions and command definitions without
-   * calling Command Actions.
-   */
-  snapshot(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }): Promise<CommandSnapshot>;
-  /**
-   * Programmatically invoke a typed command, quietly capturing its output.
-   * Returns completed, finished, or failed after cleanup without presenting errors.
-   * Use {@link execute} as the streaming terminal adapter.
-   *
-   * @param path - Typed path to the command to invoke (`[]` selects the root)
-   * @param input - Structured argument, flag, and raw values
-   * @param io - Optional `stdout(text)` / `stderr(text)` callbacks, also
-   *             exposed to Command Actions and Extensions
-   */
-  run<const Path extends CommandPath<Tree>>(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, path: Path & KnownCommandPath<Path, Tree>, ...args: RunArguments<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
-  run<const Path extends CommandPath<Tree>, const Input>(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, path: Path & KnownCommandPath<Path, Tree>, input: Input, ...validation: [Input] extends [CompatibleRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, NoInfer<Path>>, Input>] ? readonly [io?: Partial<InvocationIO>] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
-  /**
-   * Bind a typed command path into a reusable {@link CommandHandle}.
-   *
-   * Validates the path eagerly against the prepared command tree, so an
-   * unknown path throws `COMMAND_NOT_FOUND` here rather than on the first
-   * `handle.run()`. The handle is bound to this builder's tree; commands added
-   * afterwards belong to the new builder returned by `.add()`.
-   *
-   * @param path - Typed path to the command to bind (`[]` selects the root)
-   * @throws {CrustError} COMMAND_NOT_FOUND when the path does not name a command
-   */
-  at<const Path extends CommandPath<Tree>>(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, path: Path & KnownCommandPath<Path, Tree>): CommandHandle<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>;
-  /**
-   * Parse `process.argv`, resolve subcommands, run Extension hooks, and
-   * execute the matched Command Action.
-   *
-   * This is the terminal CLI boundary — call it on the root builder. It
-   * renders a failure once (through Extension `onError` hooks, ending in
-   * Core's default renderer), sets `process.exitCode` (`1`, or
-   * `130` for an `AbortError` cancellation), and resolves to the exit code.
-   *
-   * @param options - Optional overrides (e.g. custom `argv` and captured
-   *                   `io` for in-process testing of exit codes and
-   *                   rendered failures)
-   * @returns The terminal exit code (`0`, `1`, or `130` for cancellation)
-   */
-  execute(this: {
-    readonly _types: {
-      readonly caps: "app";
-    };
-  }, options?: {
-    argv?: string[];
-    io?: Partial<InvocationIO>;
-  }): Promise<number>;
-}
-//#endregion
-//#region src/errors.d.ts
-/** A value thrown by user code crossing a Core error boundary. */
-type CaughtError = unknown;
-/** Details for a subcommand token that could not be resolved. */
-interface CommandNotFoundErrorDetails {
-  /** Unrecognized subcommand token. */
-  input: string;
-  /** Canonical names of visible available child commands. */
-  available: string[];
-  /** Canonical path to the command whose child could not be resolved. */
-  commandPath: string[];
-  /** Readonly, serializable snapshot of the parent command. */
-  parentCommand: CommandSnapshot;
-}
-/** Aggregated Standard Schema and required-value validation failures. */
-interface ValidationErrorDetails {
-  /** Issues normalized under `args.<name>` or `flags.<name>`. */
-  issues: readonly {
-    readonly message: string;
-    readonly path: string;
-  }[];
-}
-/** Details for argv syntax or built-in value parsing failures. */
-interface ParseErrorDetails {
-  readonly flag?: string;
-  readonly argument?: string;
-  /** Retained for compatibility; Core no longer populates this field. */
-  readonly value?: string;
-  readonly reason?: string;
-}
-/** Details for runtime recipe, Extension, Context, and documentation failures. */
-interface DefinitionErrorDetails {
-  readonly subject?: "command" | "context" | "extension" | "flag" | "argument";
-  readonly name?: string;
-  readonly reason?: string;
-}
-interface CrustErrorDetailsMap {
-  DEFINITION: DefinitionErrorDetails | undefined;
-  VALIDATION: ValidationErrorDetails | undefined;
-  PARSE: ParseErrorDetails | undefined;
-  COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
-}
-/**
- * All possible error codes emitted by Crust.
- *
- * - `DEFINITION` — Runtime recipe, Extension, Context, or documentation definition failure
- * - `VALIDATION` — Missing required arguments or flags
- * - `PARSE` — Argv parsing failures (unknown flags, type coercion)
- * - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
- *
- * @example
- * ```ts
- * const outcome = await app.run(path, input);
- * if (outcome.status === "failed") {
- *   const err = outcome.error;
- *   if (err instanceof CrustError) {
- *     switch (err.code) {
- *       case "VALIDATION":
- *         console.error(err.message);
- *         showHelp(cmd);
- *         break;
- *       case "PARSE":
- *         console.error(err.message);
- *         break;
- *     }
- *   }
- * }
- * ```
- */
-type CrustErrorCode = keyof CrustErrorDetailsMap;
-type CrustErrorDetails<C extends CrustErrorCode> = CrustErrorDetailsMap[C];
-interface CrustErrorJson<C extends CrustErrorCode> {
-  code: C;
-  message: string;
-  details: CrustErrorDetails<C>;
-}
-/**
- * A typed error for runtime recipe, Extension, Context, documentation, argv, and validation failures.
- *
- * Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
- * failure, enabling programmatic error handling without fragile message parsing.
- *
- * @example
- * ```ts
- * import { CrustError } from "@crustjs/core";
- *
- * const outcome = await app.run(["deploy"], { args: { target: "prod" } });
- * if (outcome.status === "failed") {
- *   const err = outcome.error;
- *   if (err instanceof CrustError) {
- *     console.error(`[${err.code}] ${err.message}`);
- *   }
- * }
- * ```
- */
-export declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Error {
-  /** Machine-readable error code for programmatic handling */
-  readonly code: C;
-  /** Structured payload for programmatic handling */
-  readonly details: CrustErrorDetails<C>;
-  /** Optional wrapped original error/value */
-  override cause?: unknown;
-  constructor(code: C, message: string, ...details: undefined extends CrustErrorDetails<C> ? [] | [CrustErrorDetails<C>] : [CrustErrorDetails<C>]);
-  is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
-  withCause(cause: unknown): this;
-  toJSON(): CrustErrorJson<C>;
-}
-//#endregion
-//#region src/api/extension.d.ts
-declare const finishedBrand: unique symbol;
-/** Opaque token returned by {@link ExtensionContext.finish} to end an invocation successfully. */
-interface Finished {
-  readonly [finishedBrand]: true;
-}
-type InvocationOutcome = {
-  readonly status: "completed";
-} | {
-  readonly status: "finished";
-  readonly by: ExtensionId;
-} | {
-  readonly status: "failed";
-  readonly error: unknown;
-  readonly by?: ExtensionId;
-};
-/** Authored root metadata fields an Extension may require. */
-type RootMetaKey = keyof RootCommandMeta;
-type RootCommandSnapshot<K extends RootMetaKey> = CommandSnapshot & {
-  readonly meta: Readonly<Required<Pick<CommandMeta, K>>>;
-};
-/** One file a build hook produces; `path` is POSIX-relative to the build output directory. */
-interface BuildFile {
-  readonly path: string;
-  readonly content: string | Uint8Array;
-}
-/** Files returned by a build hook; build tooling writes them into the build output directory. */
-type BuildArtifacts = readonly BuildFile[];
-/** Files written for each Extension build hook, in hook execution order. */
-interface BuildReport {
-  readonly extensions: readonly {
-    readonly id: ExtensionId;
-    readonly files: readonly string[];
-  }[];
-}
-/**
- * Build-time context passed to an Extension's artifact generator. It deliberately
- * carries no output directory: build tooling owns that tree, so every shipped file
- * is a returned {@link BuildFile} and the {@link BuildReport} is exact.
- */
-interface ExtensionBuildContext<MetaKeys extends RootMetaKey = never> {
-  /**
-   * Frozen snapshot prepared before this hook starts. It does not include this hook's own
-   * outputs; later-registered hooks receive refreshed snapshots.
-   */
-  readonly snapshot: RootCommandSnapshot<MetaKeys>;
-}
-/**
- * Readonly invocation view passed to Extension hooks.
- *
- * Commands cross this boundary as readonly, serializable
- * {@link CommandSnapshot}s — never as internal command nodes.
- *
- * Examples below assume the `tool deploy api --trace -- --dry-run` invocation.
- */
-interface ExtensionContext<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> extends Readonly<InvocationIO> {
-  /**
-   * Complete argv passed to the application, including routed command names.
-   * For typed `run()` this is the command path only; structured values are never rendered as argv.
-   *
-   * @example `["deploy", "api", "--trace", "--", "--dry-run"]`
-   */
-  readonly argv: readonly string[];
-  /**
-   * Snapshot of the application root, including Extension-contributed flags/commands.
-   *
-   * @example
-   * ```ts
-   * ctx.rootCommand.meta.name; // "tool"
-   * Object.keys(ctx.rootCommand.subCommands); // ["deploy"]
-   * ```
-   */
-  readonly rootCommand: RootCommandSnapshot<MetaKeys>;
-  /**
-   * Snapshot of the resolved command (the root when routing failed).
-   *
-   * @example
-   * ```ts
-   * ctx.command.meta.name; // "deploy"
-   * ctx.command.args; // [{ name: "target", type: "string", required: true }]
-   * ```
-   */
-  readonly command: CommandSnapshot;
-  /**
-   * Canonical names from the application root through the resolved command.
-   *
-   * @example `["tool", "deploy"]`
-   */
-  readonly commandPath: readonly string[];
-  /**
-   * Bound positional values for the resolved command, before validation: parsed from
-   * argv tokens for `execute()`, taken as-is from the structured input for typed `run()`
-   * (URL/JSON values keep their identity).
-   *
-   * @example `{ target: "api" }`
-   */
-  readonly args: Readonly<Record<string, ParsedArgValue>>;
-  /**
-   * Bound own flags plus unknown flags from the resolved command, before validation;
-   * parsed from argv tokens for `execute()`, taken as-is from the structured input for typed `run()`.
-   *
-   * @example `{ trace: true }`
-   */
-  readonly flags: Readonly<InferExtensionFlags<Defs> & Record<string, ParsedFlagValue>>;
-  /**
-   * Positional values that appeared after the `--` separator, or the `raw` array passed to typed `run()`.
-   *
-   * @example `["--dry-run"]`
-   */
-  readonly rawArgs: readonly string[];
-  /** Declared Contexts, constructed lazily on first property access. */
-  readonly ctx: ContextBag<Deps>;
-  /**
-   * End the invocation successfully before validation, Context construction, and the action.
-   *
-   * @example
-   * ```ts
-   * preRun(ctx) {
-   *   if (ctx.flags.help === true) return ctx.finish();
-   * }
-   * ```
-   */
-  readonly finish: () => Finished;
-}
-interface ExtensionHooks<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> {
-  /**
-   * Runs after routing and input binding (argv parsing for `execute()`, structured
-   * binding for typed `run()`), before validation, in `.extend()` order.
-   * Return `ctx.finish()` to end the invocation successfully; later pre-run hooks,
-   * validation, schemas, Contexts, and the Command Action do not run.
-   */
-  readonly preRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>) => Awaitable<void | Finished>;
-  /**
-   * Runs after the invocation settles, in reverse `.extend()` order. This is the
-   * `finally` slot for cleanup and post-run side effects.
-   */
-  readonly postRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>, outcome: InvocationOutcome) => Awaitable<void>;
-  /**
-   * Renders a failure in `execute()` only. Return true when rendered to stop the
-   * chain; falsy values delegate to the next Extension and then Core's renderer.
-   * A hook that throws ends the chain: remaining hooks are skipped and Core's
-   * default renderer reports the original failure.
-   *
-   * Receives the base context: routing or syntax-parse failures render with a
-   * fallback context whose `flags` are empty, so owned-flag inference would lie here.
-   */
-  readonly onError?: (error: CaughtError, ctx: ExtensionContext<[], Deps, MetaKeys>) => Awaitable<boolean | void>;
-}
-/**
- * A flag owned by an Extension. `recursive` (default `true`) contributes the
- * flag to every command in the application; set `false` for a root-only flag.
- */
-type ExtensionFlagDef = FlagDef & {
-  readonly recursive?: boolean;
-};
-/** A named flag definition accepted by {@link defineExtension}. */
-type NamedExtensionFlagDef = NamedFlagDef & {
-  readonly recursive?: boolean;
-};
-type SchemaToken<F> = F extends {
-  type: "boolean";
-} ? boolean : string;
-type InferPreSchemaExtensionFlag<F extends ExtensionFlagDef> = F extends {
-  schema: unknown;
-} ? (F extends {
-  multiple: true;
-} ? never : SchemaToken<F>) | ("multiple" extends keyof F ? true extends F["multiple"] ? SchemaToken<F>[] : never : never) | undefined : F extends {
-  required: true;
-} ? F extends {
-  default: unknown;
-} ? InferFlags<{
-  value: F;
-}>["value"] : InferFlags<{
-  value: F;
-}>["value"] | undefined : InferFlags<{
-  value: F;
-}>["value"];
-type InferExtensionFlag<F> = F extends ExtensionFlagDef ? InferPreSchemaExtensionFlag<F> | ("recursive" extends keyof F ? (false extends F["recursive"] ? undefined : never) : never) : never;
-/** Infer pre-validation hook values; uncertain collections claim no typed ownership. */
-type InferExtensionFlags<Defs extends readonly NamedExtensionFlagDef[]> = IsStaticTuple<Defs> extends true ? HasClosedNames<Defs> extends true ? { [K in keyof NamedFlagsRecord<Defs>]: InferExtensionFlag<NamedFlagsRecord<Defs>[K]>; } : Record<string, ParsedFlagValue> : Record<string, ParsedFlagValue>;
-/** A documentation section an Extension contributes to one command path. */
-type ExtensionSectionContribution = RuntimeCommandSectionInput & {
-  readonly command: readonly string[];
-};
-type CommandDefinitionsDependencies<Commands extends readonly CommandDefinition<any, any, any, any>[]> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly CommandDefinition<any, any, any, any>[]] ? ([H] extends [never] ? {} : DeclaredDepsOf<H>) & CommandDefinitionsDependencies<T> : Commands extends readonly [] ? {} : Record<string, ContextValue>;
-interface ExtensionConfig<Defs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Uses extends readonly AnyContextFactory[] = readonly AnyContextFactory[], Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], MetaKeys extends RootMetaKey = never> {
-  readonly flags?: Defs;
-  readonly commands?: Commands;
-  readonly uses?: Uses;
-  readonly provides?: Provides;
-  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
-  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>;
-  readonly hooks?: ExtensionHooks<Defs, ContextDependencies<Uses>, MetaKeys>;
-}
-type ValidateExtensionConfig<Defs extends readonly NamedExtensionFlagDef[], Provides extends readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[], Uses extends readonly AnyContextFactory[]> = {
-  readonly uses?: Uses;
-  readonly commands?: ValidateCommandDefinitions<Commands>;
-  readonly flags?: ValidateLocalFlagDefs<Defs, ProvidedContextSpellings<Provides>>;
-  readonly provides?: KnownContextInstances<Provides> & ProvideChecks<never, Provides>;
-};
-declare const extensionHookProof: unique symbol;
-interface Extension<Deps extends ContextMap = ContextMap, Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], FlagDefs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], out MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> extends Defining<Extension<Deps, Provides, FlagDefs, Commands, MetaKeys, HookDeps>> {
-  /** @internal Hook demands are distinct from command/provider attachment dependencies. */
-  readonly _hookDeps?: HookDeps;
-  readonly [extensionHookProof]?: (deps: HookDeps) => void;
-  readonly id: ExtensionId;
-  readonly flags?: Readonly<Record<string, ExtensionFlagDef>>;
-  /** @internal — phantom carrying declared flag literals for extend-time collision checks */
-  readonly _flagDefs?: FlagDefs;
-  readonly commands?: Commands;
-  readonly uses: readonly AnyContextFactory[];
-  readonly provides?: Provides;
-  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
-  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>;
-  readonly hooks?: ExtensionHooks<any, Deps, MetaKeys>;
-  readonly _deps?: Deps;
-}
-/** @internal Broad Extension constraint; contravariance requires the full metadata key set. */
-type AnyExtension = Extension<any, any, any, any, RootMetaKey>;
-type ExtensionProvidesOutput<E> = DefiningOf<E> extends Extension<any, infer Provides, any, any, RootMetaKey> ? ContextsOutput<Provides> : {};
-type ExtensionsProvidesOutput<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? MergeProviders<ExtensionProvidesOutput<H>, ExtensionsProvidesOutput<T>> : Es extends readonly [] ? {} : Es[number] extends Extension<any, infer P, any, any, RootMetaKey> ? P[number] extends never ? {} : Record<string, ContextValue> : {};
-/**
- * A callable Extension constructor whose identity is also a section consumer.
- * Contribution parameters default to closed sets. Use `ContextMap`,
- * `readonly AnyContextInstance[]`, `readonly NamedExtensionFlagDef[]`, or
- * `readonly CommandDefinition<any, any, any, any>[]` to keep a namespace open.
- */
-type ExtensionFactory<Args extends readonly unknown[] = [], Deps extends ContextMap = {}, Provides extends readonly AnyContextInstance[] = [], Defs extends readonly NamedExtensionFlagDef[] = [], Commands extends readonly CommandDefinition<any, any, any, any>[] = [], MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> = ((...args: Args) => Extension<Deps, Provides, Defs, Commands, MetaKeys, HookDeps>) & {
-  readonly id: ExtensionId;
-};
-/** Curried Extension definer: explicit metadata keys leave all other types inferred. */
-interface DefineExtensionWith<MetaKeys extends RootMetaKey> {
-  <Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
-  <const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
-}
-/**
- * Define an Extension, or a factory that builds one from config on each call.
- *
- * Extensions apply to the whole application and own the flags and commands
- * they contribute. Factories expose the same identity for section audiences.
- * `defineExtension<"version">()(id, configOrFactory)` declares required root
- * metadata keys without preventing inference of flags, Contexts, or commands.
- */
-export declare function defineExtension<MetaKeys extends RootMetaKey = never>(): DefineExtensionWith<MetaKeys>;
-export declare function defineExtension<Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
-export declare function defineExtension<const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
-//#endregion
-//#region src/parsing/spellings.d.ts
-interface FlagSpelling {
-  canonicalName: string;
-  def: FlagDef;
-  kind: "canonical" | "short" | "alias";
-  negatable: boolean;
-}
-//#endregion
-//#region src/command/node.d.ts
-/** Runtime-erased Command Action; typed builders and run() own the specific result contract. */
-type CommandAction = (ctx: CrustCommandContext) => unknown;
-interface CommandContext {
-  instance: AnyContextInstance;
-  extensionId?: ExtensionId;
-}
-/**
- * Internal representation of a single node in the command tree.
- *
- * Built by the `Crust` builder class; not part of the public API.
- * Each node carries its own local flags, the pre-computed effective
- * (Context-owned + local merged) flags, positional args, subcommands,
- * extensions, and the Command Action.
- */
-interface CommandNode {
-  /** Command metadata (name, description, usage) */
-  meta: CommandMeta;
-  /** Flags defined directly on this command via `.flags()` */
-  localFlags: FlagsDef;
-  /** Accumulated flags owned by Contexts provided on this command path */
-  ownedFlags: FlagsDef;
-  /** Context-owned and local flags merged for parsing */
-  effectiveFlags: FlagsDef;
-  /** Cached canonical/short/alias table for the effective flags. */
-  flagSpellings: Map<string, FlagSpelling>;
-  /** Positional argument definitions */
-  args: ArgsDef;
-  /** Named subcommands keyed by name */
-  subCommands: Record<string, CommandNode>;
-  /** Contexts available to this command in provide order (construction order is pull-driven). */
-  contexts: CommandContext[];
-  /** Declared command demands; validated when recipes are materialized. */
-  demands: readonly AnyContextFactory[];
-  /** Extensions registered via `.extend()` (root builder only) */
-  extensions: Extension[];
-  /** The Command Action */
-  run?: CommandAction;
-}
-//#endregion
-//#region src/api/context.d.ts
-/** Upper bound for phantom name-to-value context maps. */
-type ContextMap = object;
-declare const defining: unique symbol;
-declare const contextProof: unique symbol;
-/** @internal Immutable defining data retained through public structural copies. */
-interface Defining<T> {
-  readonly [defining]: T;
-}
-/** @internal */
-type DefiningOf<T> = T extends Defining<unknown> ? T[typeof defining] : T;
-/**
- * Adapter hook: the Context sources a bag was built from, exposed as a
- * non-enumerable symbol property. Reading it never starts construction.
- */
-export declare const contextSources: unique symbol;
-/** Lazy, invocation-scoped Context values. Reading a property starts construction. */
-type ContextBag<Deps extends ContextMap = {}> = { readonly [K in keyof Deps]: Promise<Deps[K]>; } & {
-  readonly [contextSources]?: readonly (AnyContextFactory | AnyContextInstance)[];
-};
-interface ContextConfig {
-  readonly flags?: readonly NamedFlagDef[];
-  readonly uses?: readonly AnyContextFactory[];
-}
-type ValidateContextConfig<R extends ContextConfig> = {
-  readonly flags?: R["flags"] extends readonly NamedFlagDef[] ? ValidateLocalFlagDefs<R["flags"], never> : "flags" extends keyof R ? {} : never;
-  readonly uses?: R["uses"] extends readonly AnyContextFactory[] ? R["uses"] : "uses" extends keyof R ? {} : never;
-};
-interface ContextSetupInput<OF extends FlagsDef = FlagsDef> extends InvocationIO {
-  readonly flags: InferFlags<OF>;
-  readonly ctx: ContextBag<ContextMap>;
-  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
-}
-interface ContextInstance<Name extends string = string, Value = unknown, OF extends FlagsDef = FlagsDef, Deps extends ContextMap = Record<string, ContextValue>> extends Defining<ContextInstance<Name, Value, OF, Deps>> {
-  readonly [contextProof]?: string extends keyof OF | keyof Deps ? unknown : (state: [OF, Deps]) => void;
-  readonly name: Name;
-  readonly ownedFlags: FlagsDef;
-  /** @internal — declared direct dependency factories */
-  readonly uses: readonly AnyContextFactory[];
-  /** @internal defining factory, for adapters that identify Contexts by factory */
-  readonly factory: AnyContextFactory;
-  setup(input: ContextSetupInput<OF>): Awaitable<Value>;
-  readonly _ownedFlags?: OF;
-  /** @internal — phantom carrying the transitive dependency closure */
-  readonly _deps?: Deps;
-}
-/** @internal Existential registry constraint; never evidence for trusted attachment. */
-type AnyContextInstance = ContextInstance<string, unknown, any, any>;
-/** Whatever a Context setup produces, erased at the runtime registry. */
-type ContextValue = Awaited<ReturnType<AnyContextInstance["setup"]>>;
-interface ContextSetup<Options, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends InvocationIO {
-  readonly options: Options;
-  readonly flags: InferFlags<OF>;
-  readonly ctx: ContextBag<Deps>;
-  /**
-   * Registers cleanup on the invocation's disposal stack: callbacks run after
-   * post-run hooks in reverse registration order. Throws once setup has settled.
-   */
-  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
-}
-interface ContextFactory<Name extends string, Options, Value, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends Defining<ContextFactory<Name, Options, Value, OF, Deps>> {
-  (options: Options): ContextInstance<Name, Value, OF, Deps>;
-  readonly contextName: Name;
-  /** @internal — declared direct dependency factories */
-  readonly uses: readonly AnyContextFactory[];
-  of(value: Value): ContextInstance<Name, Value, OF, {}>;
-  readonly _deps?: Deps;
-}
-type AnyContextFactory = ContextFactory<string, any, any, any, any>;
-type NamedOutput<Name extends string, Value> = IsClosedName<Name> extends false ? Record<string, Awaited<Value>> : IsUnion<Name> extends true ? Record<string, Awaited<Value>> : { [K in Name]: Awaited<Value>; };
-type ContextOutput<C> = C extends AnyContextInstance ? DefiningOf<C> extends ContextInstance<infer Name, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
-type ContextsOutput<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeProviders<ContextOutput<H>, ContextsOutput<T>> : {} : Cs[number] extends never ? {} : Record<string, ContextOutput<Cs[number]> extends (infer O) ? O extends unknown ? O[keyof O] : never : never>;
-type ContextsOwnedFlags<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeFlags<ContextOwnedFlags<H>, ContextsOwnedFlags<T>> : {} : keyof UnionToIntersection<ContextOwnedFlags<Cs[number]>> extends never ? {} : FlagsDef;
-type FactoryOutput<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<infer Name, any, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
-type FactoriesOutput<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryOutput<H> & FactoriesOutput<T> : {};
-type FactoryDeps<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<any, any, any, any, infer Deps> ? Deps : {} : {};
-type FactoriesDeps<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryDeps<H> & FactoriesDeps<T> : {};
-type ContextDependencies<Uses extends readonly AnyContextFactory[]> = IsStaticTuple<Uses> extends true ? FactoriesOutput<Uses> & FactoriesDeps<Uses> : Record<string, ContextValue>;
-type ContextDepsOf<C> = C extends AnyContextInstance ? DefiningOf<C> extends {
-  readonly _deps?: infer Deps extends ContextMap;
-} ? Deps : {} : {};
-type ContextsDependencies<Cs extends readonly AnyContextInstance[]> = Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? ContextDepsOf<H> & ContextsDependencies<T> : {};
-type OwnedFlagsOf<R extends ContextConfig> = R extends {
-  flags: infer F extends readonly NamedFlagDef[];
-} ? AttachedFlags<F> : "flags" extends keyof R ? FlagsDef : {};
-type UsesOf<R extends ContextConfig> = R extends {
-  uses: infer Uses extends readonly AnyContextFactory[];
-} ? Uses : "uses" extends keyof R ? readonly AnyContextFactory[] : readonly [];
-/** Define a named, lazy command dependency. Declared `uses` are exposed on `ctx`. */
-export declare function defineContext<Name extends string, Value, Options = void>(name: Name, setup: (input: ContextSetup<Options>) => Awaitable<Value>): ContextFactory<Name, Options, Value>;
-export declare function defineContext<Name extends string, const R extends ContextConfig, Value, Options = void>(name: Name, config: R & ValidateContextConfig<R> & ContextConfig, setup: (input: ContextSetup<Options, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>) => Awaitable<Value>): ContextFactory<Name, Options, Value, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>;
-type FactoryValueOf<F extends AnyContextFactory> = F extends ContextFactory<any, any, infer Value, any, any> ? Awaited<Value> : never;
-//#endregion
+import { $ as CrustErrorDetailsMap, A as ValueType, At as defineExtensionId, B as ExtensionFlagDef, C as NamedFlagDef, Ct as FlagSnapshot, D as SectionAudience, Dt as LocalValueBrand, E as ParsedFlagValue, Et as EmptyArgNameBrand, F as Extension, G as InvocationOutcome, H as ExtensionSectionContribution, I as ExtensionBuildContext, J as defineExtension, K as NamedExtensionFlagDef, L as ExtensionConfig, M as BuildFile, N as BuildReport, O as SectionConsumer, Ot as MergeContext, P as DefineExtensionWith, Q as CrustErrorDetails, R as ExtensionContext, S as MergeFlags, St as CommandSnapshot, T as ParsedArgValue, Tt as LocalFlagNameBrand, U as Finished, V as ExtensionHooks, W as InferExtensionFlags, X as CrustError, Y as CommandNotFoundErrorDetails, Z as CrustErrorCode, _ as FlagDef, _t as RunInput, a as ContextInstance, at as CommandConfig, b as InputFlags, bt as defineCommand, c as FactoryValueOf, ct as CommandHandle, d as ArgDef, dt as CommandShapeAt, et as CrustErrorJson, f as ArgsDef, ft as CommandTree, gt as RunArguments, h as CommandSectionInput, ht as RootCommandMeta, i as ContextFactory, it as AnyCrust, j as BuildArtifacts, k as ValidatedInput, kt as ExtensionId, l as contextSources, lt as CommandPath, m as CommandSection, mt as CrustCommandContext, n as ContextBag, nt as ParseErrorDetails, o as ContextMap, ot as CommandDefinition, p as CommandMeta, pt as Crust, q as RootMetaKey, r as ContextConfig, rt as ValidationErrorDetails, s as ContextSetup, st as CommandDefinitionBuilder, t as AnyContextFactory, tt as DefinitionErrorDetails, u as defineContext, ut as CommandShape, v as FlagsDef, vt as RunInputArguments, w as ParseResult, wt as LocalFlagBrand, x as InvocationIO, xt as ArgSnapshot, y as InputArgs, yt as RunOutcome, z as ExtensionFactory } from "./context-Cud9frNp.js";
+import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/api/flags.d.ts
 /** Distribute `Omit<_, "name">` over the {@link ArgDef} union. */
 type OmitName<T> = T extends {
@@ -1304,4 +20,4 @@ export declare function defineFlag<const N extends string, const D extends FlagD
 /** Define and own one positional argument; layout belongs to its consuming command. */
 export declare function defineArg<const N extends string, const D extends UnnamedArgDef>(name: N & EmptyArgNameBrand<N>, def: D & LocalValueBrand<D>): Named<N, D>;
 //#endregion
-export { type AnyContextFactory, type AnyCrust, type ArgDef, type ArgSnapshot, type ArgsDef, type BuildArtifacts, type BuildFile, type BuildReport, type CommandConfig, type CommandDefinition, type CommandDefinitionBuilder, type CommandHandle, type CommandMeta, type CommandNotFoundErrorDetails, type CommandPath, type CommandSection, type CommandSectionInput, type CommandShape, type CommandShapeAt, type CommandSnapshot, type CommandTree, type ContextBag, type ContextConfig, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, type CrustCommandContext, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefineExtensionWith, type DefinitionErrorDetails, type Extension, type ExtensionBuildContext, type ExtensionConfig, type ExtensionContext, type ExtensionFactory, type ExtensionFlagDef, type ExtensionHooks, type ExtensionId, type ExtensionSectionContribution, type FactoryValueOf, type Finished, type FlagDef, type FlagSnapshot, type FlagsDef, type InferExtensionFlags, type InputArgs, type InputFlags, type InvocationIO, type InvocationOutcome, type MergeContext, type MergeFlags, type NamedExtensionFlagDef, type NamedFlagDef, type ParseErrorDetails, type ParseResult, type ParsedArgValue, type ParsedFlagValue, type RootCommandMeta, type RootMetaKey, type RunArguments, type RunInput, type RunInputArguments, type RunOutcome, type SectionAudience, type SectionConsumer, type UnnamedArgDef, type ValidatedInput, type ValidationErrorDetails, type ValueType, defineExtensionId, resolveArtifactDir };
+export { type AnyContextFactory, type AnyCrust, type ArgDef, type ArgSnapshot, type ArgsDef, type BuildArtifacts, type BuildFile, type BuildReport, type CommandConfig, type CommandDefinition, type CommandDefinitionBuilder, type CommandHandle, type CommandMeta, type CommandNotFoundErrorDetails, type CommandPath, type CommandSection, type CommandSectionInput, type CommandShape, type CommandShapeAt, type CommandSnapshot, type CommandTree, type ContextBag, type ContextConfig, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, Crust, type CrustCommandContext, CrustError, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefineExtensionWith, type DefinitionErrorDetails, type Extension, type ExtensionBuildContext, type ExtensionConfig, type ExtensionContext, type ExtensionFactory, type ExtensionFlagDef, type ExtensionHooks, type ExtensionId, type ExtensionSectionContribution, type FactoryValueOf, type Finished, type FlagDef, type FlagSnapshot, type FlagsDef, type InferExtensionFlags, type InputArgs, type InputFlags, type InvocationIO, type InvocationOutcome, type MergeContext, type MergeFlags, type NamedExtensionFlagDef, type NamedFlagDef, type ParseErrorDetails, type ParseResult, type ParsedArgValue, type ParsedFlagValue, type RootCommandMeta, type RootMetaKey, type RunArguments, type RunInput, type RunInputArguments, type RunOutcome, type SectionAudience, type SectionConsumer, type UnnamedArgDef, type ValidatedInput, type ValidationErrorDetails, type ValueType, contextSources, defineCommand, defineContext, defineExtension, defineExtensionId, resolveArtifactDir };