@crustjs/core 0.3.2 → 0.3.4

package/dist/{context-Cud9frNp.d.ts → context-BPR700gY.d.ts}

@@ -536,6 +536,12 @@ interface CrustCommandContext<A extends ArgsDef = ArgsDef, F extends FlagsDef =
   ctx: ContextBag<Ctx>;
   /** Raw arguments that appeared after the `--` separator */
   rawArgs: string[];
+  /**
+   * Aborted when the caller cancels the invocation (`execute({ signal })`,
+   * `run(path, input, { signal })`, or the first `SIGINT` under `execute()`);
+   * see `ExecuteOptions.signal` for how the abort reason maps to the exit code.
+   */
+  signal: AbortSignal;
   /** Readonly, serializable snapshot of the resolved command */
   command: CommandSnapshot;
   /** Readonly snapshot of the application root, including Extension contributions */
@@ -580,18 +586,18 @@ type CompatibleRunValue<Expected, Actual> = Actual extends Expected ? Actual ext
 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>];
+type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<Shape>, options?: InvocationOptions];
 /**
  * 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.
+ * `run` accepts the same structured input and options 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"]>>;
+  run<const Input>(input: Input, ...validation: [Input] extends [CompatibleRunInput<Shape, Input>] ? readonly [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<Shape["result"]>>;
 }
 /** Static configuration for a reusable command definition. */
 interface CommandConfig extends Omit<CommandMeta, "name" | "sections" | "version"> {
@@ -924,8 +930,9 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    *
    * @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
+   * @param options - Optional `stdout(text)` / `stderr(text)` callbacks (also
+   *                  exposed to Command Actions and Extensions) and an
+   *                  `AbortSignal` that cancels the invocation
    */
   run<const Path extends CommandPath<Tree>>(this: {
     readonly _types: {
@@ -936,7 +943,7 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
     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"]>>;
+  }, path: Path & KnownCommandPath<Path, Tree>, input: Input, ...validation: [Input] extends [CompatibleRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, NoInfer<Path>>, Input>] ? readonly [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
   /**
    * Bind a typed command path into a reusable {@link CommandHandle}.
    *
@@ -962,19 +969,16 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    * 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)
+   * @param options - Optional overrides: custom `argv` and captured `io` for
+   *                   in-process testing of exit codes and rendered failures,
+   *                   and a caller `signal` that cancels the invocation
    * @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>;
+  }, options?: ExecuteOptions): Promise<number>;
 }
 //#endregion
 //#region src/errors.d.ts
@@ -1195,6 +1199,12 @@ interface ExtensionContext<Defs extends readonly NamedExtensionFlagDef[] = [], D
    * @example `["--dry-run"]`
    */
   readonly rawArgs: readonly string[];
+  /**
+   * Aborted when the caller cancels the invocation (`execute({ signal })`,
+   * `run(path, input, { signal })`, or the first `SIGINT` under `execute()`);
+   * see `ExecuteOptions.signal` for how the abort reason maps to the exit code.
+   */
+  readonly signal: AbortSignal;
   /** Declared Contexts, constructed lazily on first property access. */
   readonly ctx: ContextBag<Deps>;
   /**
@@ -1333,11 +1343,17 @@ declare function defineExtension<Args extends readonly unknown[], const Defs ext
 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
+/**
+ * One spelling of an effective flag. Entries are immutable and `def` is the
+ * same object as `node.effectiveFlags[canonicalName]`, so node clones may
+ * share entries and only copy the Map container. Writers (`registerFlag`)
+ * always create fresh entries; never mutate one in place.
+ */
 interface FlagSpelling {
-  canonicalName: string;
-  def: FlagDef;
-  kind: "canonical" | "short" | "alias";
-  negatable: boolean;
+  readonly canonicalName: string;
+  readonly def: FlagDef;
+  readonly kind: "canonical" | "short" | "alias";
+  readonly negatable: boolean;
 }
 //#endregion
 //#region src/command/node.d.ts
@@ -1396,6 +1412,29 @@ interface InvocationIO {
   /** Write a line of diagnostic output (injectable text callback) */
   stderr: (text: string) => void;
 }
+/** Caller options for one programmatic `run()` invocation: IO callbacks plus cancellation. */
+interface InvocationOptions extends Partial<InvocationIO> {
+  /** Aborting it aborts the invocation's `ctx.signal` with the same reason. */
+  signal?: AbortSignal;
+}
+/**
+ * Caller options for the terminal `execute()` boundary. While an invocation
+ * runs, the first `SIGINT` (Ctrl-C) aborts its `ctx.signal` with an `AbortError`
+ * and a second `SIGINT` terminates unless another listener owns the signal.
+ */
+interface ExecuteOptions {
+  /** Arguments to parse; defaults to `process.argv.slice(2)`. */
+  argv?: string[];
+  /** Captured `stdout(text)` / `stderr(text)` callbacks (e.g. in-process tests). */
+  io?: Partial<InvocationIO>;
+  /**
+   * Caller-owned cancellation; aborting it aborts the invocation's `ctx.signal`
+   * with the same reason. If work throws that reason, an `AbortError` exits `130`
+   * and other errors exit `1`. Effect signal interruption instead becomes an
+   * `AbortError`, regardless of the caller's reason.
+   */
+  signal?: AbortSignal;
+}
 /**
  * Supported type literals for args and flags.
  *
@@ -1992,6 +2031,7 @@ type ValidateContextConfig<R extends ContextConfig> = {
   readonly uses?: R["uses"] extends readonly AnyContextFactory[] ? R["uses"] : "uses" extends keyof R ? {} : never;
 };
 interface ContextSetupInput<OF extends FlagsDef = FlagsDef> extends InvocationIO {
+  readonly signal: AbortSignal;
   readonly flags: InferFlags<OF>;
   readonly ctx: ContextBag<ContextMap>;
   readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
@@ -2015,6 +2055,8 @@ type AnyContextInstance = ContextInstance<string, unknown, any, any>;
 type ContextValue = Awaited<ReturnType<AnyContextInstance["setup"]>>;
 interface ContextSetup<Options, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends InvocationIO {
   readonly options: Options;
+  /** The invocation's cancellation signal; pass it to cancellable setup work. */
+  readonly signal: AbortSignal;
   readonly flags: InferFlags<OF>;
   readonly ctx: ContextBag<Deps>;
   /**
@@ -2056,4 +2098,4 @@ declare function defineContext<Name extends string, Value, Options = void>(name:
 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
-export { CrustErrorDetailsMap as $, ValueType as A, defineExtensionId as At, ExtensionFlagDef as B, NamedFlagDef as C, FlagSnapshot as Ct, SectionAudience as D, LocalValueBrand as Dt, ParsedFlagValue as E, EmptyArgNameBrand as Et, Extension as F, InvocationOutcome as G, ExtensionSectionContribution as H, ExtensionBuildContext as I, defineExtension as J, NamedExtensionFlagDef as K, ExtensionConfig as L, BuildFile as M, BuildReport as N, SectionConsumer as O, MergeContext as Ot, DefineExtensionWith as P, CrustErrorDetails as Q, ExtensionContext as R, MergeFlags as S, CommandSnapshot as St, ParsedArgValue as T, LocalFlagNameBrand as Tt, Finished as U, ExtensionHooks as V, InferExtensionFlags as W, CrustError as X, CommandNotFoundErrorDetails as Y, CrustErrorCode as Z, FlagDef as _, RunInput as _t, ContextInstance as a, CommandConfig as at, InputFlags as b, defineCommand as bt, FactoryValueOf as c, CommandHandle as ct, ArgDef as d, CommandShapeAt as dt, CrustErrorJson as et, ArgsDef as f, CommandTree as ft, DeclaredDefault as g, RunArguments as gt, CommandSectionInput as h, RootCommandMeta as ht, ContextFactory as i, AnyCrust as it, BuildArtifacts as j, ValidatedInput as k, ExtensionId as kt, contextSources as l, CommandPath as lt, CommandSection as m, CrustCommandContext as mt, ContextBag as n, ParseErrorDetails as nt, ContextMap as o, CommandDefinition as ot, CommandMeta as p, Crust as pt, RootMetaKey as q, ContextConfig as r, ValidationErrorDetails as rt, ContextSetup as s, CommandDefinitionBuilder as st, AnyContextFactory as t, DefinitionErrorDetails as tt, defineContext as u, CommandShape as ut, FlagsDef as v, RunInputArguments as vt, ParseResult as w, LocalFlagBrand as wt, InvocationIO as x, ArgSnapshot as xt, InputArgs as y, RunOutcome as yt, ExtensionFactory as z };
+export { CrustErrorCode as $, SectionConsumer as A, MergeContext as At, ExtensionContext as B, InvocationOptions as C, ArgSnapshot as Ct, ParsedArgValue as D, LocalFlagNameBrand as Dt, ParseResult as E, LocalFlagBrand as Et, BuildReport as F, Finished as G, ExtensionFlagDef as H, DefineExtensionWith as I, NamedExtensionFlagDef as J, InferExtensionFlags as K, Extension as L, ValueType as M, defineExtensionId as Mt, BuildArtifacts as N, ParsedFlagValue as O, EmptyArgNameBrand as Ot, BuildFile as P, CrustError as Q, ExtensionBuildContext as R, InvocationIO as S, defineCommand as St, NamedFlagDef as T, FlagSnapshot as Tt, ExtensionHooks as U, ExtensionFactory as V, ExtensionSectionContribution as W, defineExtension as X, RootMetaKey as Y, CommandNotFoundErrorDetails as Z, ExecuteOptions as _, RootCommandMeta as _t, ContextInstance as a, ValidationErrorDetails as at, InputArgs as b, RunInputArguments as bt, FactoryValueOf as c, CommandDefinition as ct, ArgDef as d, CommandPath as dt, CrustErrorDetails as et, ArgsDef as f, CommandShape as ft, DeclaredDefault as g, CrustCommandContext as gt, CommandSectionInput as h, Crust as ht, ContextFactory as i, ParseErrorDetails as it, ValidatedInput as j, ExtensionId as jt, SectionAudience as k, LocalValueBrand as kt, contextSources as l, CommandDefinitionBuilder as lt, CommandSection as m, CommandTree as mt, ContextBag as n, CrustErrorJson as nt, ContextMap as o, AnyCrust as ot, CommandMeta as p, CommandShapeAt as pt, InvocationOutcome as q, ContextConfig as r, DefinitionErrorDetails as rt, ContextSetup as s, CommandConfig as st, AnyContextFactory as t, CrustErrorDetailsMap as tt, defineContext as u, CommandHandle as ut, FlagDef as v, RunArguments as vt, MergeFlags as w, CommandSnapshot as wt, InputFlags as x, RunOutcome as xt, FlagsDef as y, RunInput as yt, ExtensionConfig as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { $ as CrustErrorCode, A as SectionConsumer, At as MergeContext, B as ExtensionContext, C as InvocationOptions, Ct as ArgSnapshot, D as ParsedArgValue, Dt as LocalFlagNameBrand, E as ParseResult, Et as LocalFlagBrand, F as BuildReport, G as Finished, H as ExtensionFlagDef, I as DefineExtensionWith, J as NamedExtensionFlagDef, K as InferExtensionFlags, L as Extension, M as ValueType, Mt as defineExtensionId, N as BuildArtifacts, O as ParsedFlagValue, Ot as EmptyArgNameBrand, P as BuildFile, Q as CrustError, R as ExtensionBuildContext, S as InvocationIO, St as defineCommand, T as NamedFlagDef, Tt as FlagSnapshot, U as ExtensionHooks, V as ExtensionFactory, W as ExtensionSectionContribution, X as defineExtension, Y as RootMetaKey, Z as CommandNotFoundErrorDetails, _ as ExecuteOptions, _t as RootCommandMeta, a as ContextInstance, at as ValidationErrorDetails, b as InputArgs, bt as RunInputArguments, c as FactoryValueOf, ct as CommandDefinition, d as ArgDef, dt as CommandPath, et as CrustErrorDetails, f as ArgsDef, ft as CommandShape, gt as CrustCommandContext, h as CommandSectionInput, ht as Crust, i as ContextFactory, it as ParseErrorDetails, j as ValidatedInput, jt as ExtensionId, k as SectionAudience, kt as LocalValueBrand, l as contextSources, lt as CommandDefinitionBuilder, m as CommandSection, mt as CommandTree, n as ContextBag, nt as CrustErrorJson, o as ContextMap, ot as AnyCrust, p as CommandMeta, pt as CommandShapeAt, q as InvocationOutcome, r as ContextConfig, rt as DefinitionErrorDetails, s as ContextSetup, st as CommandConfig, t as AnyContextFactory, tt as CrustErrorDetailsMap, u as defineContext, ut as CommandHandle, v as FlagDef, vt as RunArguments, w as MergeFlags, wt as CommandSnapshot, x as InputFlags, xt as RunOutcome, y as FlagsDef, yt as RunInput, z as ExtensionConfig } from "./context-BPR700gY.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/api/flags.d.ts
 /** Distribute `Omit<_, "name">` over the {@link ArgDef} union. */
@@ -20,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, 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 };
+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 ExecuteOptions, 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 InvocationOptions, 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 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { S as CrustError, _ as defineContext, a as runInvocation, b as normalizeArg, d as installExtensionContexts, f as validateCommandSections, g as contextSources, h as defineExtension, i as resolveTypedPath, m as registerFlag, n as executeInvocation, o as snapshotCommand, p as createCommandNode, r as prepareInvocation, u as cloneCommandNode, v as definingOf, x as normalizeFlag, y as validateContextAvailability } from "./invocation-B17RvTLb.js";
+import { C as CrustError, S as normalizeFlag, _ as contextSources, a as runInvocation, b as validateContextAvailability, d as cloneFlagRegistry, f as installExtensionContexts, g as defineExtension, h as registerFlag, i as resolveTypedPath, m as createCommandNode, n as executeInvocation, o as snapshotCommand, p as validateCommandSections, r as prepareInvocation, u as cloneCommandNode, v as defineContext, x as normalizeArg, y as definingOf } from "./invocation-BaWf5POY.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/identity.ts
 /** Mint an Extension identity from any non-blank, trimmed string. */
@@ -121,18 +121,14 @@ var Crust = class {
 	_clone(nodeOverrides) {
 		const cloned = Object.create(Object.getPrototypeOf(this));
 		cloned._node = {
-			...cloneCommandNode({
-				...this._node,
-				subCommands: {}
-			}),
-			subCommands: { ...this._node.subCommands },
+			...this._node,
 			...nodeOverrides
 		};
 		cloned._ancestorOwnedFlags = this._ancestorOwnedFlags;
 		return cloned;
 	}
 	flags(...defs) {
-		const cloned = this._clone({});
+		const cloned = this._clone(cloneFlagRegistry(this._node));
 		for (const def of defs) {
 			const { name, ...rest } = def;
 			registerFlag(cloned._node, name, rest, "local");
@@ -163,7 +159,10 @@ var Crust = class {
 	provide(...inputs) {
 		const instances = inputs.map(definingOf);
 		validateContextAvailability([...this._node.contexts.map(({ instance }) => instance), ...instances], instances);
-		const cloned = this._clone({ contexts: [...this._node.contexts, ...instances.map((instance) => ({ instance }))] });
+		const cloned = this._clone({
+			...cloneFlagRegistry(this._node),
+			contexts: [...this._node.contexts, ...instances.map((instance) => ({ instance }))]
+		});
 		for (const instance of instances) for (const [name, definition] of Object.entries(instance.ownedFlags)) registerFlag(cloned._node, name, definition, "owned");
 		return cloned;
 	}
@@ -220,11 +219,11 @@ var Crust = class {
 	}
 	async run(path, ...args) {
 		const structuredInput = args[0] ?? {};
-		const io = args[1];
+		const options = args[1];
 		return await runInvocation(this._node, {
 			path,
 			input: structuredInput
-		}, io, materializeCommandDefinition);
+		}, options, materializeCommandDefinition);
 	}
 	at(path) {
 		resolveTypedPath(prepareInvocation(this._node, materializeCommandDefinition).rootNode, path);
@@ -234,11 +233,11 @@ var Crust = class {
 			path: boundPath,
 			async run(...args) {
 				const structuredInput = args[0] ?? {};
-				const io = args[1];
+				const options = args[1];
 				return await runInvocation(node, {
 					path: boundPath,
 					input: structuredInput
-				}, io, materializeCommandDefinition);
+				}, options, materializeCommandDefinition);
 			}
 		};
 	}

package/dist/{invocation-B17RvTLb.js → invocation-BaWf5POY.js}

@@ -234,6 +234,7 @@ var FallbackAsyncDisposableStack = class {
 		this.#entries.push(onDisposeAsync);
 	}
 	async [Symbol.asyncDispose]() {
+		if (this.#disposed) return;
 		this.#disposed = true;
 		const errors = [];
 		for (let index = this.#entries.length - 1; index >= 0; index--) try {
@@ -260,11 +261,12 @@ function registerDisposable(value, disposal, registered) {
 	disposal.use(value);
 }
 /** Internal lazy invocation container. Public consumers receive scoped Context bags. */
-function createContextResolver(contexts, io, disposal) {
+function createContextResolver(contexts, io, disposal, signal) {
 	const byName = new Map(contexts.map((context) => [context.name, context]));
 	const entries = /* @__PURE__ */ new Map();
 	const registered = /* @__PURE__ */ new WeakSet();
 	let validatedFlags;
+	let constructing = true;
 	let disposed = false;
 	disposal.defer(() => {
 		disposed = true;
@@ -310,6 +312,11 @@ function createContextResolver(contexts, io, disposal) {
 			name,
 			reason: "missing-context"
 		}));
+		if (!constructing && !entries.has(name)) return handledRejection(new CrustError("DEFINITION", `Context "${name}" cannot be constructed during invocation cleanup. Read it while setting up the Context whose cleanup needs it.`, {
+			subject: "context",
+			name,
+			reason: "context-during-disposal"
+		}));
 		if (validatedFlags === void 0 && Object.keys(context.ownedFlags).length > 0) return handledRejection(new CrustError("DEFINITION", `Context "${name}" owns flags and cannot be pulled before flag validation${originSuffix}. Pull it from an action or a postRun hook after a validated invocation.`, {
 			subject: "context",
 			name,
@@ -334,6 +341,7 @@ function createContextResolver(contexts, io, disposal) {
 					const ownedFlags = Object.fromEntries(Object.keys(context.ownedFlags).map((flag) => [flag, validatedFlags?.[flag]]));
 					const value = await context.setup({
 						...io,
+						signal,
 						flags: ownedFlags,
 						ctx: makeBag(context.uses, current),
 						defer(cleanup) {
@@ -390,7 +398,10 @@ function createContextResolver(contexts, io, disposal) {
 		async settle() {
 			for (;;) {
 				const pending = [...entries.values()].filter((entry) => !entry.settled);
-				if (pending.length === 0) return;
+				if (pending.length === 0) {
+					constructing = false;
+					return;
+				}
 				await Promise.allSettled(pending.map((entry) => entry.promise));
 			}
 		}
@@ -496,6 +507,15 @@ function applyExtensionFlags(root, extension) {
 		injectExtensionFlag(root, name, def, recursive);
 	}
 }
+/** Copy the flag registry so `registerFlag` on the copy leaves `node` untouched. */
+function cloneFlagRegistry(node) {
+	return {
+		localFlags: { ...node.localFlags },
+		ownedFlags: { ...node.ownedFlags },
+		effectiveFlags: { ...node.effectiveFlags },
+		flagSpellings: new Map(node.flagSpellings)
+	};
+}
 /** Deep-clone a command subtree without mutating the builder graph. */
 function cloneCommandNode(node) {
 	const subCommands = {};
@@ -503,13 +523,7 @@ function cloneCommandNode(node) {
 	return {
 		...node,
 		meta: { ...node.meta },
-		localFlags: { ...node.localFlags },
-		ownedFlags: { ...node.ownedFlags },
-		effectiveFlags: { ...node.effectiveFlags },
-		flagSpellings: new Map([...node.flagSpellings].map(([spelling, entry]) => [spelling, {
-			...entry,
-			def: node.effectiveFlags[entry.canonicalName]
-		}])),
+		...cloneFlagRegistry(node),
 		args: [...node.args],
 		subCommands,
 		contexts: node.contexts.map((context) => ({ ...context })),
@@ -674,14 +688,11 @@ function coerceJson(raw) {
 function buildParseArgsOptionDescriptor(spellings) {
 	const options = {};
 	for (const [spelling, entry] of spellings) {
+		if (entry.kind === "short") continue;
 		const descriptor = { type: entry.def.type === "boolean" ? "boolean" : "string" };
 		if (entry.def.multiple) descriptor.multiple = true;
-		if (entry.kind === "canonical") {
-			if (entry.def.short) descriptor.short = entry.def.short;
-			options[spelling] = descriptor;
-			continue;
-		}
-		if (entry.kind === "alias") options[spelling] = descriptor;
+		if (entry.kind === "canonical" && entry.def.short) descriptor.short = entry.def.short;
+		options[spelling] = descriptor;
 	}
 	return options;
 }
@@ -1405,10 +1416,35 @@ function _usingCtx() {
 }
 //#endregion
 //#region src/command/invocation.ts
-/** Terminal defaults: line-oriented writes to the process streams. */
+const ignoreStreamError = () => {};
+/**
+* Line-oriented write to a process stream, with `console.log`'s error tolerance: a
+* downstream that closed early (`cli | head`) surfaces as EPIPE, synchronously or as a
+* later `error` event, and must not crash the CLI. Mirrors Node's Console
+* (`ignoreErrors: true`): a noop listener absorbs the event when nobody else listens.
+*/
+function writeLine(stream, text) {
+	const absorb = () => {
+		if (stream.listenerCount("error") === 0) stream.once("error", ignoreStreamError);
+	};
+	try {
+		absorb();
+		stream.write(`${text}\n`, (error) => {
+			if (error) absorb();
+		});
+	} catch {} finally {
+		stream.removeListener("error", ignoreStreamError);
+	}
+}
+/**
+* Terminal defaults: stream writes rather than `console.log`. Once anything materializes
+* `process.stdout` (a platform layer, a color library probing `isTTY`), Bun's native
+* console writer silently drops output past the 64 KiB pipe buffer at exit
+* (oven-sh/bun#36419); the stream writer flushes it.
+*/
 const DEFAULT_IO = {
-	stdout: (text) => console.log(text),
-	stderr: (text) => console.error(text)
+	stdout: (text) => writeLine(process.stdout, text),
+	stderr: (text) => writeLine(process.stderr, text)
 };
 /**
 * Snapshot subprocess protocol used by first-party build tooling.
@@ -1417,6 +1453,9 @@ const DEFAULT_IO = {
 * validates its documentation sections, optionally runs Extension build hooks when the
 * build output directory is set, writes its final JSON snapshot and Build Report, and exits
 * without dispatching a Command Action. In-process callers use `Crust.snapshot()`.
+*
+* Only source entries run by `crust build` honor it: finished Bun/Node bundles carry
+* `process.env.CRUST_INTERNAL_BUILD === "1"` as a literal and compile the protocol out.
 */
 const SNAPSHOT_PATH_ENV = "CRUST_INTERNAL_SNAPSHOT_PATH";
 const EXIT_CODE_CANCELLED = 130;
@@ -1424,6 +1463,72 @@ function isAbortError(error) {
 	if (!(error instanceof Error)) return false;
 	return error.name === "AbortError";
 }
+/**
+* Structural: Node 22 bundles down-level `await using` to a plain `Error`
+* carrying `error`/`suppressed`, so `instanceof SuppressedError` cannot be used.
+*/
+function isSuppressedError(error) {
+	return isObjectLike(error) && "error" in error && "suppressed" in error && error.name === "SuppressedError";
+}
+function isObjectLike(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* One `label: message` line per underlying failure. `SuppressedError` chains and
+* `AggregateError`s contribute their members, not their own boilerplate message,
+* so a disposal failure never renders as a bare `Error: `.
+*/
+function describeFailure(error, label = "Error") {
+	const messages = [];
+	const seen = /* @__PURE__ */ new Set();
+	let remaining = 256;
+	let truncated = false;
+	const visitMember = (read) => {
+		if (truncated) return;
+		if (remaining === 0) {
+			truncated = true;
+			messages.push("[additional failures omitted]");
+			return;
+		}
+		remaining--;
+		let member;
+		try {
+			member = read();
+		} catch {
+			messages.push("[unreadable failure]");
+			return;
+		}
+		visit(member);
+	};
+	const visit = (value) => {
+		try {
+			if (isObjectLike(value)) {
+				if (seen.has(value)) return;
+				seen.add(value);
+			}
+			const before = messages.length;
+			if (isSuppressedError(value)) {
+				visitMember(() => value.error);
+				visitMember(() => value.suppressed);
+				if (messages.length > before) return;
+			} else if (value instanceof AggregateError) {
+				const members = value.errors;
+				if (Array.isArray(members)) {
+					for (let index = 0; index < members.length; index++) {
+						visitMember(() => members[index]);
+						if (truncated) break;
+					}
+					if (messages.length > before) return;
+				}
+			}
+			messages.push(String(value instanceof Error && value.message || value));
+		} catch {
+			messages.push("[unreadable failure]");
+		}
+	};
+	visitMember(() => error);
+	return messages.map((message) => `${label}: ${message}`).join("\n");
+}
 function freezeTree(node) {
 	Object.freeze(node);
 	Object.freeze(node.localFlags);
@@ -1462,8 +1567,10 @@ function buildExtensionTree(node, materializeCommandDefinition) {
 }
 /** Evaluate Extension section callbacks against current state and freeze the tree. */
 function applySectionsAndFreeze(rootNode, extensions) {
-	const authoredSnapshot = snapshotCommand(rootNode);
-	for (const extension of extensions) applyExtensionSections(rootNode, extension, authoredSnapshot);
+	if (extensions.some((extension) => extension.sections !== void 0)) {
+		const authoredSnapshot = snapshotCommand(rootNode);
+		for (const extension of extensions) applyExtensionSections(rootNode, extension, authoredSnapshot);
+	}
 	freezeTree(rootNode);
 	return rootNode;
 }
@@ -1508,7 +1615,7 @@ function resolveStructuredInput(root, path, input) {
 	};
 }
 /** Resolve, parse, and run one invocation without rendering failures. */
-async function dispatch(input, prepared, io, onExtensionContext, onFailure) {
+async function dispatch(input, prepared, io, signal, onExtensionContext, onFailure) {
 	try {
 		var _usingCtx$1 = _usingCtx();
 		const { rootNode, extensions } = prepared;
@@ -1516,16 +1623,19 @@ async function dispatch(input, prepared, io, onExtensionContext, onFailure) {
 		const resolvedNode = route.command;
 		const disposal = _usingCtx$1.a(new DisposalStack());
 		const contexts = resolvedNode.contexts.map(({ instance }) => instance);
-		const resolver = createContextResolver(contexts, io, disposal);
+		const resolver = createContextResolver(contexts, io, disposal, signal);
 		const rootSnapshot = snapshotCommand(rootNode);
+		let commandSnapshot = rootSnapshot;
+		for (const name of route.commandPath.slice(1)) commandSnapshot = commandSnapshot.subCommands[name];
 		const extensionContext = Object.freeze({
 			argv: [...argv],
 			rootCommand: rootSnapshot,
-			command: resolvedNode === rootNode ? rootSnapshot : snapshotCommand(resolvedNode),
+			command: commandSnapshot,
 			commandPath: Object.freeze([...route.commandPath]),
 			args: parsed.args,
 			flags: parsed.flags,
 			rawArgs: parsed.rawArgs,
+			signal,
 			ctx: resolver.bag(extensions.flatMap((extension) => extension.uses ?? [])),
 			finish: finishInvocation,
 			stdout: io.stdout,
@@ -1542,6 +1652,7 @@ async function dispatch(input, prepared, io, onExtensionContext, onFailure) {
 				flags: validated.flags,
 				ctx: resolver.bag(contexts),
 				rawArgs: parsed.rawArgs,
+				signal,
 				command: extensionContext.command,
 				rootCommand: rootSnapshot,
 				stdout: io.stdout,
@@ -1599,11 +1710,10 @@ async function dispatch(input, prepared, io, onExtensionContext, onFailure) {
 	}
 }
 /** Render one failure through Extension onError hooks, ending in Core's default renderer. */
-async function renderFailure(error, argv, prepared, io, extensionContext, silentDefault = false) {
+async function renderFailure(error, argv, prepared, io, signal, extensionContext, silentDefault = false) {
 	const renderDefault = () => {
 		if (silentDefault) return;
-		const message = error instanceof Error ? error.message : String(error);
-		io.stderr(`Error: ${message}`);
+		io.stderr(describeFailure(error));
 	};
 	function unavailable(property) {
 		return Promise.reject(new CrustError("DEFINITION", `Context "${String(property)}" cannot be pulled from onError because invocation Contexts have already been disposed.`, {
@@ -1613,19 +1723,24 @@ async function renderFailure(error, argv, prepared, io, extensionContext, silent
 		}));
 	}
 	const unavailableContext = new Proxy({}, { get: (_, property) => property === "then" || isSymbol(property) ? void 0 : unavailable(property) });
-	const context = extensionContext ?? Object.freeze({
-		argv: [...argv],
-		rootCommand: snapshotCommand(prepared.rootNode),
-		command: snapshotCommand(prepared.rootNode),
-		commandPath: Object.freeze([prepared.rootNode.meta.name]),
-		args: Object.freeze({}),
-		flags: Object.freeze({}),
-		rawArgs: [],
-		finish: finishInvocation,
-		stdout: io.stdout,
-		stderr: io.stderr,
-		ctx: unavailableContext
-	});
+	let context = extensionContext;
+	if (!context) {
+		const rootSnapshot = snapshotCommand(prepared.rootNode);
+		context = Object.freeze({
+			argv: [...argv],
+			rootCommand: rootSnapshot,
+			command: rootSnapshot,
+			commandPath: Object.freeze([prepared.rootNode.meta.name]),
+			args: Object.freeze({}),
+			flags: Object.freeze({}),
+			rawArgs: [],
+			signal,
+			finish: finishInvocation,
+			stdout: io.stdout,
+			stderr: io.stderr,
+			ctx: unavailableContext
+		});
+	}
 	try {
 		for (const extension of prepared.extensions) if (await extension.hooks?.onError?.(error, context)) return extension.id;
 	} catch {}
@@ -1636,11 +1751,11 @@ function hasInjectedIO(io) {
 	return io !== void 0 && Object.keys(io).length > 0;
 }
 /** Quiet programmatic boundary: capture output and the failure escaping the complete lifecycle. */
-async function runInvocation(node, input, io, materializeCommandDefinition) {
+async function runInvocation(node, input, options, materializeCommandDefinition) {
 	const stdout = [];
 	const stderr = [];
 	try {
-		const sinks = { ...io };
+		const { signal = new AbortController().signal, ...sinks } = options ?? {};
 		const resolvedIO = {
 			stdout(text) {
 				stdout.push(text);
@@ -1653,7 +1768,7 @@ async function runInvocation(node, input, io, materializeCommandDefinition) {
 		};
 		return {
 			...await withAmbientTerminalIO(resolvedIO, async () => {
-				return await dispatch(input, prepareInvocation(node, materializeCommandDefinition), resolvedIO);
+				return await dispatch(input, prepareInvocation(node, materializeCommandDefinition), resolvedIO, signal);
 			}),
 			stdout: stdout.join("\n"),
 			stderr: stderr.join("\n")
@@ -1674,7 +1789,9 @@ async function executeInvocation(node, options, materializeCommandDefinition) {
 		...DEFAULT_IO,
 		...options?.io
 	};
-	const snapshotPath = process.env[SNAPSHOT_PATH_ENV];
+	const controller = new AbortController();
+	const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+	const snapshotPath = process.env.CRUST_INTERNAL_BUILD === "1" ? void 0 : process.env[SNAPSHOT_PATH_ENV];
 	if (snapshotPath) {
 		try {
 			const base = buildExtensionTree(node, materializeCommandDefinition);
@@ -1734,35 +1851,52 @@ async function executeInvocation(node, options, materializeCommandDefinition) {
 				process.exitCode = EXIT_CODE_CANCELLED;
 				return EXIT_CODE_CANCELLED;
 			}
-			const message = error instanceof Error ? error.message : String(error);
-			io.stderr(`Error: ${message}`);
+			io.stderr(describeFailure(error));
 			process.exitCode = 1;
 			return 1;
 		}
+		const onSigint = () => {
+			if (!controller.signal.aborted) {
+				controller.abort(new DOMException("Interrupted by SIGINT.", "AbortError"));
+				return;
+			}
+			process.removeListener("SIGINT", onSigint);
+			if (process.listenerCount("SIGINT") === 0) process.kill(process.pid, "SIGINT");
+		};
+		process.on("SIGINT", onSigint);
 		let extensionContext;
 		let renderedInDispatch = false;
+		let renderedError;
 		try {
-			await dispatch({ argv }, prepared, io, (context) => {
+			await dispatch({ argv }, prepared, io, signal, (context) => {
 				extensionContext = context;
 			}, async (error, context) => {
 				renderedInDispatch = true;
+				renderedError = error;
 				const cancelled = isAbortError(error);
 				process.exitCode = cancelled ? EXIT_CODE_CANCELLED : 1;
-				return renderFailure(error, argv, prepared, io, context, cancelled);
+				return renderFailure(error, argv, prepared, io, signal, context, cancelled);
 			});
 		} catch (error) {
+			let cleanupFailure;
+			try {
+				if (renderedInDispatch && !Object.is(error, renderedError) && isSuppressedError(error) && Object.is(error.suppressed, renderedError)) cleanupFailure = { error: error.error };
+			} catch {}
+			if (cleanupFailure) io.stderr(describeFailure(cleanupFailure.error, "Cleanup failed"));
 			if (isAbortError(error)) {
-				if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, extensionContext, true);
+				if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, signal, extensionContext, true);
 				process.exitCode = EXIT_CODE_CANCELLED;
 				return EXIT_CODE_CANCELLED;
 			}
 			process.exitCode = 1;
-			if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, extensionContext);
+			if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, signal, extensionContext);
 			return 1;
+		} finally {
+			process.removeListener("SIGINT", onSigint);
 		}
 		return 0;
 	};
 	return await (hasInjectedIO(options?.io) ? withAmbientTerminalIO(io, invoke) : invoke());
 }
 //#endregion
-export { CrustError as S, defineContext as _, runInvocation as a, normalizeArg as b, sectionsFor as c, installExtensionContexts as d, validateCommandSections as f, contextSources as g, defineExtension as h, resolveTypedPath as i, visibleSectionsFor as l, registerFlag as m, executeInvocation as n, snapshotCommand as o, createCommandNode as p, prepareInvocation as r, isListed as s, SNAPSHOT_PATH_ENV as t, cloneCommandNode as u, definingOf as v, normalizeFlag as x, validateContextAvailability as y };
+export { CrustError as C, normalizeFlag as S, contextSources as _, runInvocation as a, validateContextAvailability as b, sectionsFor as c, cloneFlagRegistry as d, installExtensionContexts as f, defineExtension as g, registerFlag as h, resolveTypedPath as i, visibleSectionsFor as l, createCommandNode as m, executeInvocation as n, snapshotCommand as o, validateCommandSections as p, prepareInvocation as r, isListed as s, SNAPSHOT_PATH_ENV as t, cloneCommandNode as u, defineContext as v, normalizeArg as x, definingOf as y };

package/dist/tooling.d.ts

@@ -1,4 +1,4 @@
-import { Ct as FlagSnapshot, St as CommandSnapshot, g as DeclaredDefault, kt as ExtensionId, m as CommandSection } from "./context-Cud9frNp.js";
+import { Tt as FlagSnapshot, g as DeclaredDefault, jt as ExtensionId, m as CommandSection, wt as CommandSnapshot } from "./context-BPR700gY.js";
 import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
 //#region src/command/invocation.d.ts
 /**
@@ -8,6 +8,9 @@ import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
  * validates its documentation sections, optionally runs Extension build hooks when the
  * build output directory is set, writes its final JSON snapshot and Build Report, and exits
  * without dispatching a Command Action. In-process callers use `Crust.snapshot()`.
+ *
+ * Only source entries run by `crust build` honor it: finished Bun/Node bundles carry
+ * `process.env.CRUST_INTERNAL_BUILD === "1"` as a literal and compile the protocol out.
  */
 export declare const SNAPSHOT_PATH_ENV = "CRUST_INTERNAL_SNAPSHOT_PATH";
 //#endregion

package/dist/tooling.js

@@ -1,4 +1,4 @@
-import { c as sectionsFor, l as visibleSectionsFor, s as isListed, t as SNAPSHOT_PATH_ENV } from "./invocation-B17RvTLb.js";
+import { c as sectionsFor, l as visibleSectionsFor, s as isListed, t as SNAPSHOT_PATH_ENV } from "./invocation-BaWf5POY.js";
 import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
 //#region src/command/documentation.ts
 function isNonFiniteNumber(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/core",
-	"version": "0.3.2",
+	"version": "0.3.4",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"sideEffects": false,