@crustjs/core 0.5.1 → 0.5.2

package/dist/{context-9ee4iljp.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";
@@ -937,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)
@@ -1122,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";
@@ -1245,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.
@@ -2212,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-9ee4iljp.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-CD299Gic.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-CD299Gic.js → invocation-OsKzCgr-.js}

@@ -466,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));
@@ -1194,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)`)
@@ -1740,7 +1740,7 @@ async function dispatch(input, prepared, io, signal, onExtensionContext, onFailu
 		rawArgs: parsed.rawArgs,
 		signal,
 		ctx: resolver.bag(extensions.flatMap((extension) => extension.use)),
-		finish: finishInvocation,
+		handled: handledInvocation,
 		stdout: io.stdout,
 		stderr: io.stderr
 	});
@@ -1767,14 +1767,14 @@ async function dispatch(input, prepared, io, signal, onExtensionContext, onFailu
 	let outcome = { status: "completed" };
 	try {
 		try {
-			for (const extension of extensions) if (await extension.hooks?.preRun?.(extensionContext) === finishInvocation()) {
+			for (const extension of extensions) if (await extension.hooks?.preRun?.(extensionContext) === handledInvocation()) {
 				outcome = {
-					status: "finished",
+					status: "handled",
 					by: extension.id
 				};
 				break;
 			}
-			if (outcome.status !== "finished") result = await terminal();
+			if (outcome.status !== "handled") result = await terminal();
 		} catch (error) {
 			const by = await onFailure?.(error, extensionContext);
 			outcome = {
@@ -1799,8 +1799,8 @@ async function dispatch(input, prepared, io, signal, onExtensionContext, onFailu
 	} finally {
 		await resolver.settle();
 	}
-	return outcome.status === "finished" ? {
-		status: "finished",
+	return outcome.status === "handled" ? {
+		status: "handled",
 		by: outcome.by
 	} : {
 		status: "completed",
@@ -1833,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-9ee4iljp.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-CD299Gic.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.1",
+  "version": "0.5.2",
   "description": "Core library for the Crust CLI framework",
   "type": "module",
   "sideEffects": false,