@crustjs/core 0.5.0 → 0.5.2

package/dist/{context-WQZg1zaQ.d.ts → context-VtqvNs9V.d.ts}

@@ -569,7 +569,7 @@ type RunOutcome<Result> = {
   readonly status: "completed";
   readonly result: Result;
 } | {
-  readonly status: "finished";
+  readonly status: "handled";
   readonly by: ExtensionId;
 } | {
   readonly status: "failed";
@@ -579,12 +579,13 @@ type RunOutcome<Result> = {
 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;
+type CommandPathContinuations<Path extends readonly string[], Tree extends object, Prefix extends readonly string[] = readonly []> = Path extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? readonly [...Prefix, Head] extends CommandPath<Tree> ? CommandPathContinuations<Tail, Tree, readonly [...Prefix, Head]> : Extract<CommandPath<Tree>, readonly [...Prefix, ...string[]]> : Extract<CommandPath<Tree>, readonly [...Prefix, ...string[]]>;
+type KnownCommandPath<Path extends readonly string[], Tree extends object> = string extends keyof Tree ? Path : IsStaticTuple<Path> extends true ? string extends Path[number] ? never : [Path] extends [CommandPath<Tree>] ? Path : CommandPathContinuations<Path, Tree> : number extends Path["length"] ? CommandPath<Tree> : 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; };
+type RunSection<Name extends string, Values> = keyof Values extends 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"]>> & {
+type RunInput<Shape extends CommandShape> = RunSection<"args", ArgsDef extends Shape["args"] ? NonNullable<RunInputPayload["args"]> : InputArgs<Shape["args"]>> & RunSection<"flags", FlagsDef extends Shape["flags"] ? [keyof Shape["flags"]] extends [never] ? {} : 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;
@@ -592,6 +593,14 @@ type CompatibleRunBranch<Expected, Actual> = Actual extends Expected ? Actual :
 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>, options?: InvocationOptions];
+type KeysOf<T> = T extends unknown ? keyof T : never;
+type UnknownRunKeys<Actual, Known> = { [K in keyof Actual as string extends K ? never : number extends K ? never : K extends Known ? never : K]: Actual[K] extends undefined ? Actual[K] : never; };
+type ClosedRunInput<Shape extends CommandShape, Input> = Input extends unknown ? UnknownRunKeys<Input, keyof RunInput<Shape>> & { [K in keyof Input as K extends ("args" | "flags") & keyof RunInput<Shape> ? K : never]: UnknownRunKeys<NonNullable<Input[K]>, KeysOf<NonNullable<RunInput<Shape>[K & keyof RunInput<Shape>]>>>; } : never;
+type CheckedRunInput<Shape extends CommandShape, Input> = [Input] extends [ClosedRunInput<Shape, Input>] ? NonNullable<RunInputArguments<Shape>[0]> : Input & NoInfer<ClosedRunInput<Shape, Input>>;
+type OmittableRunInput<Shape extends CommandShape> = {} extends RunInput<Shape> ? undefined : never;
+type RunWithoutInputThis<Shape extends CommandShape, This> = [Shape] extends [never] ? This : {} extends RunInput<Shape> ? This : This & {
+  readonly FIX_MISSING_INPUT: "Pass the command's required arguments or flags";
+};
 /**
  * Typed invoker bound to one command in an app, returned by {@link Crust.at}.
  *
@@ -601,7 +610,8 @@ type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<S
 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(this: RunWithoutInputThis<Shape, unknown>): Promise<RunOutcome<Shape["result"]>>;
+  run<const Input extends RunInput<Shape> | OmittableRunInput<Shape> = RunInput<Shape>>(input: CheckedRunInput<Shape, Input> | OmittableRunInput<Shape>, options?: InvocationOptions): 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. */
@@ -899,21 +909,17 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    */
   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))`).
+   * Define a subcommand inline (sugar for `.add(defineCommand(name, recipe))`),
+   * on the root or inside another command's 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.
+   * accumulated on this builder so far — the call site. In a recipe, those are
+   * its `.use()` and `.provide()` Contexts. 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
+   * or reuse.
    */
-  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<{
+  command<const N extends string, B extends AnyCommandDefinitionBuilder>(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;
@@ -931,7 +937,7 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
   }): Promise<CommandSnapshot>;
   /**
    * Programmatically invoke a typed command, quietly capturing its output.
-   * Returns completed, finished, or failed after cleanup without presenting errors.
+   * Returns completed, handled, 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)
@@ -940,16 +946,21 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    *                  exposed to Command Actions and Extensions) and an
    *                  `AbortSignal` that cancels the invocation
    */
-  run<const Path extends CommandPath<Tree>>(this: {
+  run<const Path extends readonly string[]>(this: RunWithoutInputThis<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>, {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }>, path: KnownCommandPath<Path, Tree>): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends readonly string[], const Input extends RunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>> | OmittableRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>> = RunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>>(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: {
+  }, path: KnownCommandPath<Path, Tree>, input: CheckedRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>, Input> | OmittableRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>, options?: InvocationOptions): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends readonly string[], 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 [options?: InvocationOptions] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  }, 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}.
    *
@@ -961,11 +972,11 @@ declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx ext
    * @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: {
+  at<const Path extends readonly string[]>(this: {
     readonly _types: {
       readonly caps: "app";
     };
-  }, path: Path & KnownCommandPath<Path, Tree>): CommandHandle<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, 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.
@@ -1111,15 +1122,15 @@ declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Erro
 }
 //#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;
+declare const handledBrand: unique symbol;
+/** Opaque token returned by {@link ExtensionContext.handled} to end an invocation successfully. */
+interface Handled {
+  readonly [handledBrand]: true;
 }
 type InvocationOutcome = {
   readonly status: "completed";
 } | {
-  readonly status: "finished";
+  readonly status: "handled";
   readonly by: ExtensionId;
 } | {
   readonly status: "failed";
@@ -1234,20 +1245,20 @@ interface ExtensionContext<Defs extends readonly NamedExtensionFlagDef[] = [], D
    * @example
    * ```ts
    * preRun(ctx) {
-   *   if (ctx.flags.help === true) return ctx.finish();
+   *   if (ctx.flags.help === true) return ctx.handled();
    * }
    * ```
    */
-  readonly finish: () => Finished;
+  readonly handled: () => Handled;
 }
 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,
+   * Return `ctx.handled()` 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>;
+  readonly preRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>) => Awaitable<void | Handled>;
   /**
    * Runs after the invocation settles, in reverse `.extend()` order. This is the
    * `finally` slot for cleanup and post-run side effects.
@@ -2201,4 +2212,4 @@ interface ContextBuilder<Name extends string, Use extends readonly AnyContextFac
 declare function defineContext<Name extends string>(name: Name): ContextBuilder<Name>;
 type FactoryValueOf<F extends AnyContextFactory> = F extends ContextFactory<any, any, infer Value, any, any> ? Awaited<Value> : never;
 //#endregion
-export { CrustError as $, SectionConsumer as A, LocalFlagNameBrand as At, ExtensionBuilder as B, InvocationOptions as C, RunInputArguments as Ct, ParsedArgValue as D, CommandSnapshot as Dt, ParseResult as E, ArgSnapshot as Et, BuildArtifacts as F, defineExtensionId as Ft, ExtensionSectionContribution as G, ExtensionFactory as H, BuildFile as I, InvocationOutcome as J, Finished as K, BuildReport as L, ValueType as M, LocalValueBrand as Mt, FlagEnvironment as N, MergeContext as Nt, ParsedFlagValue as O, FlagSnapshot as Ot, parseFlagValues as P, ExtensionId as Pt, CommandNotFoundErrorDetails as Q, Extension as R, InvocationIO as S, RunInput as St, NamedFlagDef as T, defineCommand as Tt, ExtensionFlagDef as U, ExtensionContext as V, ExtensionHooks as W, RootMetaKey as X, NamedExtensionFlagDef as Y, defineExtension as Z, ExecuteOptions as _, CommandTree as _t, ContextInstance as a, EnvErrorDetails as at, InputArgs as b, RootCommandMeta as bt, FactoryValueOf as c, ValidationErrorDetails as ct, ArgDef as d, CommandDefinition as dt, CrustErrorCode as et, ArgsDef as f, CommandDefinitionBuilder as ft, DeclaredDefault as g, CommandShapeAt as gt, CommandSectionInput as h, CommandShape as ht, ContextFactory as i, DefinitionErrorDetails as it, ValidatedInput as j, EmptyArgNameBrand as jt, SectionAudience as k, LocalFlagBrand as kt, contextSources as l, AnyCrust as lt, CommandSection as m, CommandPath as mt, ContextBag as n, CrustErrorDetailsMap as nt, ContextMap as o, EnvIssue as ot, CommandMeta as p, CommandHandle as pt, InferExtensionFlags as q, ContextBuilder as r, CrustErrorJson as rt, ContextSetup as s, ParseErrorDetails as st, AnyContextFactory as t, CrustErrorDetails as tt, defineContext as u, CommandConfig as ut, FlagDef as v, Crust as vt, MergeFlags as w, RunOutcome as wt, InputFlags as x, RunArguments as xt, FlagsDef as y, CrustCommandContext as yt, ExtensionBuildContext as z };
+export { CrustError as $, SectionConsumer as A, LocalFlagNameBrand as At, ExtensionBuilder as B, InvocationOptions as C, RunInputArguments as Ct, ParsedArgValue as D, CommandSnapshot as Dt, ParseResult as E, ArgSnapshot as Et, BuildArtifacts as F, defineExtensionId as Ft, ExtensionSectionContribution as G, ExtensionFactory as H, BuildFile as I, InvocationOutcome as J, Handled as K, BuildReport as L, ValueType as M, LocalValueBrand as Mt, FlagEnvironment as N, MergeContext as Nt, ParsedFlagValue as O, FlagSnapshot as Ot, parseFlagValues as P, ExtensionId as Pt, CommandNotFoundErrorDetails as Q, Extension as R, InvocationIO as S, RunInput as St, NamedFlagDef as T, defineCommand as Tt, ExtensionFlagDef as U, ExtensionContext as V, ExtensionHooks as W, RootMetaKey as X, NamedExtensionFlagDef as Y, defineExtension as Z, ExecuteOptions as _, CommandTree as _t, ContextInstance as a, EnvErrorDetails as at, InputArgs as b, RootCommandMeta as bt, FactoryValueOf as c, ValidationErrorDetails as ct, ArgDef as d, CommandDefinition as dt, CrustErrorCode as et, ArgsDef as f, CommandDefinitionBuilder as ft, DeclaredDefault as g, CommandShapeAt as gt, CommandSectionInput as h, CommandShape as ht, ContextFactory as i, DefinitionErrorDetails as it, ValidatedInput as j, EmptyArgNameBrand as jt, SectionAudience as k, LocalFlagBrand as kt, contextSources as l, AnyCrust as lt, CommandSection as m, CommandPath as mt, ContextBag as n, CrustErrorDetailsMap as nt, ContextMap as o, EnvIssue as ot, CommandMeta as p, CommandHandle as pt, InferExtensionFlags as q, ContextBuilder as r, CrustErrorJson as rt, ContextSetup as s, ParseErrorDetails as st, AnyContextFactory as t, CrustErrorDetails as tt, defineContext as u, CommandConfig as ut, FlagDef as v, Crust as vt, MergeFlags as w, RunOutcome as wt, InputFlags as x, RunArguments as xt, FlagsDef as y, CrustCommandContext as yt, ExtensionBuildContext as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CrustError, A as SectionConsumer, At as LocalFlagNameBrand, B as ExtensionBuilder, C as InvocationOptions, Ct as RunInputArguments, D as ParsedArgValue, Dt as CommandSnapshot, E as ParseResult, Et as ArgSnapshot, F as BuildArtifacts, Ft as defineExtensionId, G as ExtensionSectionContribution, H as ExtensionFactory, I as BuildFile, J as InvocationOutcome, K as Finished, L as BuildReport, M as ValueType, Mt as LocalValueBrand, Nt as MergeContext, O as ParsedFlagValue, Ot as FlagSnapshot, Pt as ExtensionId, Q as CommandNotFoundErrorDetails, R as Extension, S as InvocationIO, St as RunInput, T as NamedFlagDef, Tt as defineCommand, U as ExtensionFlagDef, V as ExtensionContext, W as ExtensionHooks, X as RootMetaKey, Y as NamedExtensionFlagDef, Z as defineExtension, _ as ExecuteOptions, _t as CommandTree, a as ContextInstance, at as EnvErrorDetails, b as InputArgs, bt as RootCommandMeta, c as FactoryValueOf, ct as ValidationErrorDetails, d as ArgDef, dt as CommandDefinition, et as CrustErrorCode, f as ArgsDef, ft as CommandDefinitionBuilder, gt as CommandShapeAt, h as CommandSectionInput, ht as CommandShape, i as ContextFactory, it as DefinitionErrorDetails, j as ValidatedInput, jt as EmptyArgNameBrand, k as SectionAudience, kt as LocalFlagBrand, l as contextSources, lt as AnyCrust, m as CommandSection, mt as CommandPath, n as ContextBag, nt as CrustErrorDetailsMap, o as ContextMap, ot as EnvIssue, p as CommandMeta, pt as CommandHandle, q as InferExtensionFlags, r as ContextBuilder, rt as CrustErrorJson, s as ContextSetup, st as ParseErrorDetails, t as AnyContextFactory, tt as CrustErrorDetails, u as defineContext, ut as CommandConfig, v as FlagDef, vt as Crust, w as MergeFlags, wt as RunOutcome, x as InputFlags, xt as RunArguments, y as FlagsDef, yt as CrustCommandContext, z as ExtensionBuildContext } from "./context-WQZg1zaQ.js";
+import { $ as CrustError, A as SectionConsumer, At as LocalFlagNameBrand, B as ExtensionBuilder, C as InvocationOptions, Ct as RunInputArguments, D as ParsedArgValue, Dt as CommandSnapshot, E as ParseResult, Et as ArgSnapshot, F as BuildArtifacts, Ft as defineExtensionId, G as ExtensionSectionContribution, H as ExtensionFactory, I as BuildFile, J as InvocationOutcome, K as Handled, L as BuildReport, M as ValueType, Mt as LocalValueBrand, Nt as MergeContext, O as ParsedFlagValue, Ot as FlagSnapshot, Pt as ExtensionId, Q as CommandNotFoundErrorDetails, R as Extension, S as InvocationIO, St as RunInput, T as NamedFlagDef, Tt as defineCommand, U as ExtensionFlagDef, V as ExtensionContext, W as ExtensionHooks, X as RootMetaKey, Y as NamedExtensionFlagDef, Z as defineExtension, _ as ExecuteOptions, _t as CommandTree, a as ContextInstance, at as EnvErrorDetails, b as InputArgs, bt as RootCommandMeta, c as FactoryValueOf, ct as ValidationErrorDetails, d as ArgDef, dt as CommandDefinition, et as CrustErrorCode, f as ArgsDef, ft as CommandDefinitionBuilder, gt as CommandShapeAt, h as CommandSectionInput, ht as CommandShape, i as ContextFactory, it as DefinitionErrorDetails, j as ValidatedInput, jt as EmptyArgNameBrand, k as SectionAudience, kt as LocalFlagBrand, l as contextSources, lt as AnyCrust, m as CommandSection, mt as CommandPath, n as ContextBag, nt as CrustErrorDetailsMap, o as ContextMap, ot as EnvIssue, p as CommandMeta, pt as CommandHandle, q as InferExtensionFlags, r as ContextBuilder, rt as CrustErrorJson, s as ContextSetup, st as ParseErrorDetails, t as AnyContextFactory, tt as CrustErrorDetails, u as defineContext, ut as CommandConfig, v as FlagDef, vt as Crust, w as MergeFlags, wt as RunOutcome, x as InputFlags, xt as RunArguments, y as FlagsDef, yt as CrustCommandContext, z as ExtensionBuildContext } from "./context-VtqvNs9V.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 ContextBuilder, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, Crust, type CrustCommandContext, CrustError, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefinitionErrorDetails, type EnvErrorDetails, type EnvIssue, type ExecuteOptions, type Extension, type ExtensionBuildContext, type ExtensionBuilder, 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 };
+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 ContextBuilder, type ContextFactory, type ContextInstance, type ContextMap, type ContextSetup, Crust, type CrustCommandContext, CrustError, type CrustErrorCode, type CrustErrorDetails, type CrustErrorDetailsMap, type CrustErrorJson, type DefinitionErrorDetails, type EnvErrorDetails, type EnvIssue, type ExecuteOptions, type Extension, type ExtensionBuildContext, type ExtensionBuilder, type ExtensionContext, type ExtensionFactory, type ExtensionFlagDef, type ExtensionHooks, type ExtensionId, type ExtensionSectionContribution, type FactoryValueOf, type FlagDef, type FlagSnapshot, type FlagsDef, type Handled, 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 { C as normalizeFlag, S as normalizeArg, _ as validateContextAvailability, a as runInvocation, b as validateCommandSections, c as cloneCommandNode, d as createCommandNode, f as registerFlag, g as definingOf, h as defineContext, i as resolveTypedPath, l as cloneFlagRegistry, m as contextSources, n as executeInvocation, o as snapshotCommand, p as defineExtension, r as prepareInvocation, u as installExtensionContexts, w as CrustError } from "./invocation-ljkrw2dt.js";
+import { C as normalizeFlag, S as normalizeArg, _ as validateContextAvailability, a as runInvocation, b as validateCommandSections, c as cloneCommandNode, d as createCommandNode, f as registerFlag, g as definingOf, h as defineContext, i as resolveTypedPath, l as cloneFlagRegistry, m as contextSources, n as executeInvocation, o as snapshotCommand, p as defineExtension, r as prepareInvocation, u as installExtensionContexts, w as CrustError } from "./invocation-OsKzCgr-.js";
 import { resolveArtifactDir } from "@crustjs/utils/artifacts";
 //#region src/identity.ts
 /** Mint an Extension identity from any non-blank, trimmed string. */

package/dist/{invocation-ljkrw2dt.js → invocation-OsKzCgr-.js}

@@ -307,54 +307,6 @@ function createContextFactory(name, use, ownedFlags, sections, setup) {
 function defineContext(name) {
 	return createContextBuilder(name, Object.freeze([]), Object.freeze({}), Object.freeze([]));
 }
-function isDisposeCallback(value) {
-	return typeof value === "function";
-}
-/**
-* Minimal `AsyncDisposableStack` stand-in for runtimes without the global
-* (Node 22): LIFO disposal of used resources and deferred callbacks,
-* preferring `Symbol.asyncDispose` over `Symbol.dispose`.
-*
-* ponytail: multiple disposal errors aggregate as `AggregateError` instead of
-* the native `SuppressedError` chain; delete this class when Node 22 leaves
-* the support floor.
-*
-* @internal Exported for unit testing and invocation wiring.
-*/
-var FallbackAsyncDisposableStack = class {
-	#entries = [];
-	#disposed = false;
-	#assertPending() {
-		if (this.#disposed) throw new ReferenceError("AsyncDisposableStack is already disposed");
-	}
-	use(value) {
-		this.#assertPending();
-		const dispose = hasAsyncDispose(value) ? value[Symbol.asyncDispose] : value[Symbol.dispose];
-		this.#entries.push(() => dispose.call(value));
-		return value;
-	}
-	defer(onDisposeAsync) {
-		this.#assertPending();
-		if (!isDisposeCallback(onDisposeAsync)) throw new TypeError("defer callback is not callable");
-		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 {
-			await this.#entries[index]();
-		} catch (error) {
-			errors.push(error);
-		}
-		if (errors.length === 1) throw errors[0];
-		if (errors.length > 1) throw new AggregateError(errors, "Disposal failed");
-	}
-};
-const DisposalStack = globalThis.AsyncDisposableStack ?? FallbackAsyncDisposableStack;
-function hasAsyncDispose(value) {
-	return typeof value[Symbol.asyncDispose] === "function";
-}
 function isDisposableValue(value) {
 	if (value === null || typeof value !== "object" && typeof value !== "function") return false;
 	const candidate = value;
@@ -514,10 +466,10 @@ function createContextResolver(contexts, io, disposal, signal) {
 }
 //#endregion
 //#region src/api/extension.ts
-const FINISHED = Object.freeze({ [Symbol("crust.finished")]: true });
+const HANDLED = Object.freeze({ [Symbol("crust.handled")]: true });
 /** @internal */
-function finishInvocation() {
-	return FINISHED;
+function handledInvocation() {
+	return HANDLED;
 }
 function createExtension(state) {
 	const flags = Object.freeze(toFlagsRecord(state.flags));
@@ -1242,7 +1194,7 @@ function bind(command, positionals, flagValues, coerceArg, coerceFlag) {
 *
 * This is a pure parse+coerce function — it never throws for missing required
 * values. Use {@link validateParsed} to enforce required constraints after
-* extensions have had a chance to finish an invocation (e.g. `--help`).
+* extensions have had a chance to handle an invocation (e.g. `--help`).
 *
 * @param command - The command whose arg/flag definitions drive the parsing
 * @param argv - The argv array to parse (typically `process.argv.slice(2)`)
@@ -1565,62 +1517,6 @@ function resolveCommand(command, argv) {
 	};
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.150.0/helpers/esm/usingCtx.js
-function _usingCtx() {
-	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
-		var n = Error();
-		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
-	}, e = {}, n = [];
-	function using(r, e) {
-		if (null != e) {
-			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
-			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
-			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
-			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
-			t && (o = function o() {
-				try {
-					t.call(e);
-				} catch (r) {
-					return Promise.reject(r);
-				}
-			}), n.push({
-				v: e,
-				d: o,
-				a: r
-			});
-		} else r && n.push({
-			d: e,
-			a: r
-		});
-		return e;
-	}
-	return {
-		e,
-		u: using.bind(null, !1),
-		a: using.bind(null, !0),
-		d: function d() {
-			var o, t = this.e, s = 0;
-			function next() {
-				for (; o = n.pop();) try {
-					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
-					if (o.d) {
-						var r = o.d.call(o.v);
-						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
-					} else s |= 1;
-				} catch (r) {
-					return err(r);
-				}
-				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
-				if (t !== e) throw t;
-			}
-			function err(n) {
-				return t = t !== e ? new r(n, t) : n, next();
-			}
-			return next();
-		}
-	};
-}
-//#endregion
 //#region src/command/invocation.ts
 const ignoreStreamError = () => {};
 /**
@@ -1672,7 +1568,7 @@ function isAbortError(error) {
 	return error.name === "AbortError";
 }
 /**
-* Structural: Node 22 bundles down-level `await using` to a plain `Error`
+* Structural: down-level bundles can implement `await using` with a plain `Error`
 * carrying `error`/`suppressed`, so `instanceof SuppressedError` cannot be used.
 */
 function isSuppressedError(error) {
@@ -1825,98 +1721,91 @@ function resolveStructuredInput(root, path, input) {
 }
 /** Resolve, parse, and run one invocation without rendering failures. */
 async function dispatch(input, prepared, io, signal, onExtensionContext, onFailure) {
-	try {
-		var _usingCtx$1 = _usingCtx();
-		const { rootNode, extensions } = prepared;
-		const { argv, route, parsed } = "argv" in input ? resolveArgvInput(rootNode, input.argv) : resolveStructuredInput(rootNode, input.path, input.input);
-		const resolvedNode = route.command;
-		const disposal = _usingCtx$1.a(new DisposalStack());
-		const contexts = resolvedNode.contexts.map(({ instance }) => instance);
-		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: commandSnapshot,
-			commandPath: Object.freeze([...route.commandPath]),
-			args: parsed.args,
-			flags: parsed.flags,
+	const { rootNode, extensions } = prepared;
+	const { argv, route, parsed } = "argv" in input ? resolveArgvInput(rootNode, input.argv) : resolveStructuredInput(rootNode, input.path, input.input);
+	const resolvedNode = route.command;
+	await using disposal = new AsyncDisposableStack();
+	const contexts = resolvedNode.contexts.map(({ instance }) => instance);
+	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: commandSnapshot,
+		commandPath: Object.freeze([...route.commandPath]),
+		args: parsed.args,
+		flags: parsed.flags,
+		rawArgs: parsed.rawArgs,
+		signal,
+		ctx: resolver.bag(extensions.flatMap((extension) => extension.use)),
+		handled: handledInvocation,
+		stdout: io.stdout,
+		stderr: io.stderr
+	});
+	onExtensionContext?.(extensionContext);
+	const terminal = async () => {
+		validateParsed(resolvedNode, parsed);
+		const validated = await applySchemas(resolvedNode, parsed);
+		resolver.setValidatedFlags(validated.flags);
+		if (!resolvedNode.run) return;
+		const context = {
+			args: validated.args,
+			flags: validated.flags,
+			ctx: resolver.bag(contexts),
 			rawArgs: parsed.rawArgs,
 			signal,
-			ctx: resolver.bag(extensions.flatMap((extension) => extension.use)),
-			finish: finishInvocation,
+			command: extensionContext.command,
+			rootCommand: rootSnapshot,
 			stdout: io.stdout,
 			stderr: io.stderr
-		});
-		onExtensionContext?.(extensionContext);
-		const terminal = async () => {
-			validateParsed(resolvedNode, parsed);
-			const validated = await applySchemas(resolvedNode, parsed);
-			resolver.setValidatedFlags(validated.flags);
-			if (!resolvedNode.run) return;
-			const context = {
-				args: validated.args,
-				flags: validated.flags,
-				ctx: resolver.bag(contexts),
-				rawArgs: parsed.rawArgs,
-				signal,
-				command: extensionContext.command,
-				rootCommand: rootSnapshot,
-				stdout: io.stdout,
-				stderr: io.stderr
-			};
-			return await resolvedNode.run(context);
 		};
-		let result;
-		let outcome = { status: "completed" };
+		return await resolvedNode.run(context);
+	};
+	let result;
+	let outcome = { status: "completed" };
+	try {
 		try {
-			try {
-				for (const extension of extensions) if (await extension.hooks?.preRun?.(extensionContext) === finishInvocation()) {
-					outcome = {
-						status: "finished",
-						by: extension.id
-					};
-					break;
-				}
-				if (outcome.status !== "finished") result = await terminal();
-			} catch (error) {
-				const by = await onFailure?.(error, extensionContext);
+			for (const extension of extensions) if (await extension.hooks?.preRun?.(extensionContext) === handledInvocation()) {
 				outcome = {
-					status: "failed",
-					error,
-					...by === void 0 ? {} : { by }
+					status: "handled",
+					by: extension.id
 				};
+				break;
 			}
-			Object.freeze(outcome);
-			let postRunFailed = false;
-			let postRunError;
-			for (const extension of extensions.toReversed()) try {
-				await extension.hooks?.postRun?.(extensionContext, outcome);
-			} catch (error) {
-				if (outcome.status !== "failed" && !postRunFailed) {
-					postRunFailed = true;
-					postRunError = error;
-				}
+			if (outcome.status !== "handled") result = await terminal();
+		} catch (error) {
+			const by = await onFailure?.(error, extensionContext);
+			outcome = {
+				status: "failed",
+				error,
+				...by === void 0 ? {} : { by }
+			};
+		}
+		Object.freeze(outcome);
+		let postRunFailed = false;
+		let postRunError;
+		for (const extension of extensions.toReversed()) try {
+			await extension.hooks?.postRun?.(extensionContext, outcome);
+		} catch (error) {
+			if (outcome.status !== "failed" && !postRunFailed) {
+				postRunFailed = true;
+				postRunError = error;
 			}
-			if (outcome.status === "failed") throw outcome.error;
-			if (postRunFailed) throw postRunError;
-		} finally {
-			await resolver.settle();
 		}
-		return outcome.status === "finished" ? {
-			status: "finished",
-			by: outcome.by
-		} : {
-			status: "completed",
-			result
-		};
-	} catch (_) {
-		_usingCtx$1.e = _;
+		if (outcome.status === "failed") throw outcome.error;
+		if (postRunFailed) throw postRunError;
 	} finally {
-		await _usingCtx$1.d();
+		await resolver.settle();
 	}
+	return outcome.status === "handled" ? {
+		status: "handled",
+		by: outcome.by
+	} : {
+		status: "completed",
+		result
+	};
 }
 /** Render one failure through Extension onError hooks, ending in Core's default renderer. */
 async function renderFailure(error, argv, prepared, io, signal, extensionContext, silentDefault = false) {
@@ -1944,7 +1833,7 @@ async function renderFailure(error, argv, prepared, io, signal, extensionContext
 			flags: Object.freeze({}),
 			rawArgs: [],
 			signal,
-			finish: finishInvocation,
+			handled: handledInvocation,
 			stdout: io.stdout,
 			stderr: io.stderr,
 			ctx: unavailableContext

package/dist/tooling.d.ts

@@ -1,4 +1,4 @@
-import { Dt as CommandSnapshot, N as FlagEnvironment, Ot as FlagSnapshot, P as parseFlagValues, Pt as ExtensionId, g as DeclaredDefault, m as CommandSection } from "./context-WQZg1zaQ.js";
+import { Dt as CommandSnapshot, N as FlagEnvironment, Ot as FlagSnapshot, P as parseFlagValues, Pt as ExtensionId, g as DeclaredDefault, m as CommandSection } from "./context-VtqvNs9V.js";
 import { BUILD_OUT_DIR_ENV } from "@crustjs/utils/artifacts";
 //#region src/command/invocation.d.ts
 /**

package/dist/tooling.js

@@ -1,4 +1,4 @@
-import { s as parseFlagValues, t as SNAPSHOT_PATH_ENV, v as isListed, x as visibleSectionsFor, y as sectionsFor } from "./invocation-ljkrw2dt.js";
+import { s as parseFlagValues, t as SNAPSHOT_PATH_ENV, v as isListed, x as visibleSectionsFor, y as sectionsFor } from "./invocation-OsKzCgr-.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.5.0",
+  "version": "0.5.2",
   "description": "Core library for the Crust CLI framework",
   "type": "module",
   "sideEffects": false,
@@ -41,11 +41,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@crustjs/utils": "^0.2.0"
+    "@crustjs/utils": "^0.2.1"
   },
   "devDependencies": {
     "@crustjs/config": "0.0.0",
-    "vite-plus": "1.0.0-rc.0"
+    "vite-plus": "1.0.0"
   },
   "peerDependencies": {
     "typescript": "^7.0.0"
@@ -57,7 +57,7 @@
   },
   "engines": {
     "bun": ">=1.4.0",
-    "node": ">=22",
+    "node": ">=24",
     "deno": ">=2.8"
   },
   "scripts": {