@crustjs/core 0.0.9 → 0.0.10

package/README.md

@@ -13,21 +13,20 @@ bun add @crustjs/core
 ## Quick Example
 
 ```ts
-import { defineCommand, runMain } from "@crustjs/core";
+import { Crust } from "@crustjs/core";
 
-const main = defineCommand({
-  meta: { name: "greet", description: "Say hello" },
-  args: [{ name: "name", type: "string", default: "world" }],
-  flags: {
+const app = new Crust("greet")
+  .meta({ description: "Say hello" })
+  .args([{ name: "name", type: "string", default: "world" }] as const)
+  .flags({
     loud: { type: "boolean", description: "Shout it", alias: "l" },
-  },
-  run({ args, flags }) {
+  })
+  .run(({ args, flags }) => {
     const msg = `Hello, ${args.name}!`;
     console.log(flags.loud ? msg.toUpperCase() : msg);
-  },
-});
+  });
 
-runMain(main);
+app.execute();
 ```
 
 ## Documentation

package/dist/index.d.ts

@@ -1,3 +1,37 @@
+/**
+* The result of resolving a command from an argv array.
+*
+* Contains the resolved (sub)command and argv after subcommand
+* resolution, and the full command path for help text rendering.
+*/
+interface CommandRoute {
+	/** The routed command (may be a subcommand of the original) */
+	command: CommandNode;
+	/** The argv after subcommand names have been consumed */
+	argv: string[];
+	/** The command path for help text (e.g. ["crust", "generate", "command"]) */
+	commandPath: string[];
+}
+/**
+* Resolve a command from an argv array by walking the subcommand tree.
+*
+* Subcommand matching happens BEFORE flag parsing, so:
+* `crust build --entry src/cli.ts` first resolves "build" as a subcommand,
+* then passes `["--entry", "src/cli.ts"]` to the build command's parser.
+*
+* Resolution rules:
+* 1. If `argv[0]` matches a subcommand key, recurse into that subcommand
+* 2. If no match and the current command has `run()`, return it (args passed to parser)
+* 3. If no match and the current command has NO `run()`, it signals the caller
+*    should show help (the `showHelp` flag is set in the result)
+* 4. Unknown subcommands produce a structured COMMAND_NOT_FOUND error
+*
+* @param command - The root command to resolve from
+* @param argv - The argv array to resolve against
+* @returns The resolved command, argv, and the command path
+* @throws {CrustError} COMMAND_NOT_FOUND when an unknown subcommand is given and the parent has no run()
+*/
+declare function resolveCommand(command: CommandNode, argv: string[]): CommandRoute;
 /** Supported type literals for args and flags */
 type ValueType = "string" | "number" | "boolean";
 /**
@@ -59,10 +93,14 @@ type ArgsDef = readonly ArgDef[];
 interface FlagDefBase {
 	/** Human-readable description for help text */
 	description?: string;
-	/** Short alias or array of aliases (e.g. `"v"` or `["v", "V"]`) */
-	alias?: string | string[];
+	/** Single-character short alias (e.g. `"v"` → `-v`) */
+	short?: string;
+	/** Additional long aliases (e.g. `["out"]` → `--out`) */
+	aliases?: string[];
 	/** When `true`, the parser throws if the flag is not provided */
 	required?: true;
+	/** When `true`, the flag is inherited by subcommands */
+	inherit?: true;
 }
 /** Base for single-value flags — `multiple` must be omitted */
 interface SingleFlagBase extends FlagDefBase {
@@ -119,7 +157,7 @@ interface BooleanMultiFlagDef extends MultiFlagBase {
 * @example
 * ```ts
 * const flags = {
-*   verbose: { type: "boolean", description: "Enable verbose logging", alias: "v" },
+*   verbose: { type: "boolean", description: "Enable verbose logging", short: "v" },
 *   port: { type: "number", description: "Port number", default: 3000 },
 *   files: { type: "string", multiple: true, default: ["index.ts"] },
 * } satisfies FlagsDef;
@@ -129,18 +167,32 @@ type FlagDef = StringFlagDef | NumberFlagDef | BooleanFlagDef | StringMultiFlagD
 /** Record mapping flag names to their definitions */
 type FlagsDef = Record<string, FlagDef>;
 /**
-* Extract alias string literals from any value that has an `alias` field.
+* Extract the `short` alias literal from a flag definition.
+* Resolves to `never` when no `short` field exists or when the type
+* is the broad `string` (not a narrowed literal).
+*/
+type ExtractShort<F> = F extends {
+	short: infer S;
+} ? S extends string ? string extends S ? never : S : never : never;
+/**
+* Extract alias string literals from the `aliases` array of a flag definition.
+* Resolves to `never` when no `aliases` field exists or when the element type
+* is the broad `string` (not narrowed literals).
+*/
+type ExtractLongAliases<F> = F extends {
+	aliases: infer A;
+} ? A extends readonly string[] ? string extends A[number] ? never : A[number] : never : never;
+/**
+* Extract all alias identifiers (short + long) from a flag definition.
 *
 * Generalized to work with any shape (`FlagDef`, `FlagSpec`, etc.) —
-* values without an `alias` field resolve to `never`.
+* values without `short`/`aliases` fields resolve to `never`.
 *
-* Includes a `string extends A` guard so non-narrowed aliases (e.g. the
+* Includes `string extends ...` guards so non-narrowed types (e.g. the
 * broad `string` type from a default generic) resolve to `never` instead
 * of causing false-positive collisions.
 */
-type ExtractAliases<F> = F extends {
-	alias: infer A;
-} ? A extends string ? string extends A ? never : A : A extends readonly string[] ? string extends A[number] ? never : A[number] : never : never;
+type ExtractAllAliases<F> = ExtractShort<F> | ExtractLongAliases<F>;
 /**
 * Collects aliases from every flag *except* flag K.
 * Used to detect alias→alias duplicates across different flags.
@@ -148,7 +200,7 @@ type ExtractAliases<F> = F extends {
 type AliasesExcluding<
 	F extends Record<string, unknown>,
 	K extends keyof F & string
-> = { [J in Exclude<keyof F & string, K>] : ExtractAliases<F[J]> }[Exclude<keyof F & string, K>];
+> = { [J in Exclude<keyof F & string, K>] : ExtractAllAliases<F[J]> }[Exclude<keyof F & string, K>];
 /**
 * Per-flag collision detection: resolves to the alias literal(s) of flag K
 * that collide with another flag's name or another flag's alias,
@@ -157,7 +209,7 @@ type AliasesExcluding<
 type CollidingAliases<
 	F extends Record<string, unknown>,
 	K extends keyof F & string
-> = (ExtractAliases<F[K]> & Exclude<keyof F & string, K>) | (ExtractAliases<F[K]> & AliasesExcluding<F, K>);
+> = (ExtractAllAliases<F[K]> & Exclude<keyof F & string, K>) | (ExtractAllAliases<F[K]> & AliasesExcluding<F, K>);
 /**
 * Per-flag validation mapped type. Resolves to `F` when no collisions exist.
 * For flags with colliding aliases, adds a branded error property to the
@@ -167,30 +219,74 @@ type CollidingAliases<
 * it with `FlagsDef`, the validate package uses it with `FlagShape`, etc.
 *
 * ```
-* Property 'FIX_ALIAS_COLLISION' is missing in type '{ type: "string"; alias: "minify" }'
+* Property 'FIX_ALIAS_COLLISION' is missing in type '{ type: "string"; short: "m" }'
 *   but required in type
-*     '{ readonly FIX_ALIAS_COLLISION: "Alias \"minify\" collides with another flag name or alias" }'.
+*     '{ readonly FIX_ALIAS_COLLISION: "Alias \"m\" collides with another flag name or alias" }'.
 * ```
 */
 type ValidateFlagAliases<F extends Record<string, unknown>> = { [K in keyof F & string] : CollidingAliases<F, K> extends never ? F[K] : F[K] & {
 	readonly FIX_ALIAS_COLLISION: `Alias "${CollidingAliases<F, K>}" collides with another flag name or alias`;
 } };
 /**
+* Collects aliases from inherited flags, excluding those whose keys the
+* child overrides (intentional override — child redefines a flag by name).
+*/
+type InheritedAliasesExcluding<
+	I extends Record<string, unknown>,
+	OverrideKeys extends string
+> = { [K in Exclude<keyof I & string, OverrideKeys>] : ExtractAllAliases<I[K]> }[Exclude<keyof I & string, OverrideKeys>];
+/**
+* Per-flag cross-collision detection between a child flag K (from local
+* flags F) and the inherited flag set I. Resolves to the colliding
+* identifier, or `never` when no collision exists.
+*
+* Detects three collision classes:
+* 1. Child alias → inherited flag name
+* 2. Child alias → inherited flag alias
+* 3. Child flag name → inherited flag alias
+*
+* Intentional name overrides (child defines a flag with the same key as
+* an inherited flag) are excluded — those are handled by `MergeFlags`.
+*/
+type CrossCollision<
+	I extends Record<string, unknown>,
+	F extends Record<string, unknown>,
+	K extends keyof F & string
+> = (ExtractAllAliases<F[K]> & Exclude<keyof I & string, keyof F & string>) | (ExtractAllAliases<F[K]> & InheritedAliasesExcluding<I, keyof F & string>) | (K & InheritedAliasesExcluding<I, keyof F & string>);
+/**
+* Per-flag validation mapped type for cross-collisions between inherited
+* and local flags. Resolves to `F` when no collisions exist.
+*
+* When `Inherited` is the wide `FlagsDef` type (root commands with no
+* parent), the validation is skipped to avoid false positives since
+* `keyof FlagsDef` is `string`.
+*
+* ```
+* Property 'FIX_INHERITED_COLLISION' is missing in type '{ type: "string"; aliases: ["verbose"] }'
+*   but required in type
+*     '{ readonly FIX_INHERITED_COLLISION: "\"verbose\" collides with inherited flag" }'.
+* ```
+*/
+type ValidateCrossCollisions<
+	I extends Record<string, unknown>,
+	F extends Record<string, unknown>
+> = string extends keyof I ? F : { [K in keyof F & string] : CrossCollision<I, F, K> extends never ? F[K] : F[K] & {
+	readonly FIX_INHERITED_COLLISION: `"${CrossCollision<I, F, K> & string}" collides with inherited flag`;
+} };
+/**
 * Detects whether a single alias literal starts with `"no-"`.
 * Resolves to the offending alias, or `never` when it is clean.
 */
 type NoPrefixedAlias<A> = A extends `no-${string}` ? A : never;
 /**
 * Collects all `"no-"`-prefixed alias literals from a flag definition.
-* Works with both `alias: "no-foo"` (string) and `alias: ["no-foo", "f"]` (array).
+* Checks both `short` and `aliases` fields.
 * Non-narrowed `string` types resolve to `never` to avoid false positives.
 */
-type NoPrefixedAliases<F> = F extends {
-	alias: infer A;
-} ? A extends string ? string extends A ? never : NoPrefixedAlias<A> : A extends readonly string[] ? string extends A[number] ? never : NoPrefixedAlias<A[number]> : never : never;
+type NoPrefixedAliases<F> = NoPrefixedAlias<ExtractShort<F>> | NoPrefixedAlias<ExtractLongAliases<F>>;
 /**
 * Per-flag validation mapped type. Resolves to `F` when no `"no-"` prefixes
-* exist on flag names or aliases. For flags with offending names or aliases,
+* exist on flag names, short aliases, or long aliases. For flags with offending values,
 * adds a branded error property causing a compile-time type error.
 *
 * The `"no-"` prefix is reserved for boolean flag negation (`--no-flag`).
@@ -229,6 +325,60 @@ type ValidateVariadicArgs<A extends readonly object[]> = A extends readonly [inf
 	readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
 }, ...ValidateVariadicArgs<Tail>] : readonly [Head, ...ValidateVariadicArgs<Tail>] : readonly [Head] : A;
 /**
+* Picks only the flags from `F` that have `inherit: true`.
+*
+* Flags without `inherit` (or with `inherit` omitted) are excluded.
+*
+* @example
+* ```ts
+* type Flags = {
+*   verbose: { type: "boolean"; inherit: true };
+*   port: { type: "number" };
+* };
+* type Result = InheritableFlags<Flags>;
+* // Result = { verbose: { type: "boolean"; inherit: true } }
+* ```
+*/
+type InheritableFlags<F extends FlagsDef> = { [K in keyof F as F[K] extends {
+	inherit: true;
+} ? K : never] : F[K] };
+/**
+* Merges parent flags with local flags, where local keys override parent keys.
+*
+* @example
+* ```ts
+* type Parent = { verbose: { type: "boolean" }; port: { type: "number" } };
+* type Local = { port: { type: "string" } };
+* type Result = MergeFlags<Parent, Local>;
+* // Result = { verbose: { type: "boolean" }; port: { type: "string" } }
+* ```
+*/
+type MergeFlags<
+	Parent extends FlagsDef,
+	Local extends FlagsDef
+> = Simplify<Omit<Parent, keyof Local> & Local>;
+/**
+* Computes the effective flags for a command by filtering the inherited flags
+* (only those with `inherit: true`) and merging them with local flags.
+*
+* Local flags override inherited flags with the same key.
+*
+* @example
+* ```ts
+* type Inherited = {
+*   verbose: { type: "boolean"; inherit: true };
+*   port: { type: "number" };
+* };
+* type Local = { output: { type: "string" } };
+* type Result = EffectiveFlags<Inherited, Local>;
+* // Result = { verbose: { type: "boolean"; inherit: true }; output: { type: "string" } }
+* ```
+*/
+type EffectiveFlags<
+	Inherited extends FlagsDef,
+	Local extends FlagsDef
+> = MergeFlags<InheritableFlags<Inherited>, Local>;
+/**
 * Infer the resolved type for a single ArgDef:
 *
 * - **variadic** → `primitive[]`
@@ -322,109 +472,351 @@ interface ParseResult<
 	/** Raw arguments that appeared after the `--` separator */
 	rawArgs: string[];
 }
-/**
-* The runtime context object passed to `preRun()`, `run()`, and `postRun()` hooks.
-*
-* Extends {@link ParseResult} with a back-reference to the resolved command.
-*/
-interface CommandContext<
-	A extends ArgsDef = ArgsDef,
-	F extends FlagsDef = FlagsDef
-> extends ParseResult<A, F> {
-	/** The resolved command that is being executed */
-	command: AnyCommand;
+interface PluginState {
+	get<T = unknown>(key: string): T | undefined;
+	has(key: string): boolean;
+	set(key: string, value: unknown): void;
+	delete(key: string): boolean;
+}
+/** A command target accepted by SetupActions */
+type CommandTarget = CommandNode;
+interface SetupActions {
+	/**
+	* Inject a flag definition into a command's flags object.
+	*
+	* Use this in plugin `setup()` hooks to register plugin-specific flags
+	* (e.g. `--version`, `--help`) so they are recognized by the parser
+	* and rendered in help text.
+	*
+	* The flag is added to `effectiveFlags` only — `localFlags` is left
+	* unchanged to distinguish user-defined flags from plugin-injected ones.
+	*
+	* @param command - The command node to add the flag to
+	* @param name - The flag name (e.g. "version")
+	* @param def - The flag definition
+	*/
+	addFlag(command: CommandTarget, name: string, def: FlagDef): void;
+	/**
+	* Inject a subcommand into a command's `subCommands` record.
+	*
+	* Use this in plugin `setup()` hooks to register plugin-provided commands
+	* (e.g. a "skill" management command). If the parent already has a
+	* subcommand with the same name (user-defined), the call is silently
+	* skipped — user definitions always take priority over plugin injections.
+	*
+	* @param parent - The parent command node to add the subcommand to
+	* @param name - The subcommand name (used for routing)
+	* @param command - The subcommand node to register
+	*/
+	addSubCommand(parent: CommandTarget, name: string, command: CommandTarget): void;
+}
+/** Shared context fields available in both setup and middleware phases. */
+interface BaseContext {
+	readonly argv: readonly string[];
+	readonly rootCommand: CommandNode;
+	readonly state: PluginState;
+}
+/** Context passed to plugin `setup()` hooks. */
+interface SetupContext extends BaseContext {}
+/** Context passed to plugin `middleware()` hooks. */
+interface MiddlewareContext extends BaseContext {
+	route: Readonly<CommandRoute> | null;
+	input: ParseResult | null;
+}
+type Next = () => Promise<void>;
+type PluginMiddleware = (context: MiddlewareContext, next: Next) => void | Promise<void>;
+interface CrustPlugin {
+	name?: string;
+	setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
+	middleware?: PluginMiddleware;
 }
 /**
-* Configuration object accepted by `defineCommand()`.
+* Internal representation of a single node in the command tree.
 *
-* Identical shape to {@link Command} but uses `NoInfer` on lifecycle-hook
-* parameters so TypeScript infers `A` and `F` solely from the `args` / `flags`
-* data properties — not from callbacks. This ensures full contextual typing
-* (e.g. `description` is `string`, not `any`) when writing command definitions.
-*
-* Compile-time validation for variadic args and flag alias collisions is
-* enforced via parameter-level intersection in `defineCommand()`.
+* Built by the `Crust` builder class; not part of the public API.
+* Each node carries its own local flags, the pre-computed effective
+* (inherited + local merged) flags, positional args, subcommands,
+* plugins, and lifecycle handlers.
 */
-interface CommandDef<
-	A extends ArgsDef = ArgsDef,
-	F extends FlagsDef = FlagsDef
-> {
+interface CommandNode {
 	/** Command metadata (name, description, usage) */
 	meta: CommandMeta;
+	/** Flags defined directly on this command via `.flags()` */
+	localFlags: FlagsDef;
+	/** Inherited flags merged with local flags (used by the parser) */
+	effectiveFlags: FlagsDef;
 	/** Positional argument definitions */
-	args?: A;
-	/** Flag definitions */
-	flags?: F;
-	/** Named subcommands */
-	subCommands?: Record<string, AnyCommand>;
+	args: ArgsDef | undefined;
+	/** Named subcommands keyed by name */
+	subCommands: Record<string, CommandNode>;
+	/** Plugins registered via `.use()` */
+	plugins: CrustPlugin[];
 	/** Called before `run()` — useful for initialization */
-	preRun?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+	preRun?: (ctx: unknown) => void | Promise<void>;
 	/** The main command handler */
-	run?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+	run?: (ctx: unknown) => void | Promise<void>;
 	/** Called after `run()` (even if it throws) — useful for teardown */
-	postRun?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+	postRun?: (ctx: unknown) => void | Promise<void>;
 }
-/** Frozen command object returned by `defineCommand()` and used at runtime. */
-interface Command<
+/**
+* Creates a new `CommandNode` with all fields initialized to defaults.
+*
+* @param name - The command name.
+* @returns A fresh `CommandNode` with empty flags, no args, no subcommands,
+*          no plugins, and no lifecycle handlers.
+*/
+declare function createCommandNode(name: string): CommandNode;
+/**
+* Merges inherited flags (only those with `inherit: true`) with local flags.
+*
+* Local flags override inherited flags with the same key. Non-inheritable
+* flags from the parent are excluded entirely.
+*
+* This is the runtime counterpart of the `EffectiveFlags` utility type.
+*
+* @param inherited - The parent's effective flags (or any FlagsDef).
+* @param local - The current command's locally-defined flags.
+* @returns A new `FlagsDef` containing inherited+local merged flags.
+*/
+declare function computeEffectiveFlags(inherited: FlagsDef, local: FlagsDef): FlagsDef;
+/**
+* The runtime context object passed to `preRun()`, `run()`, and `postRun()`
+* lifecycle hooks on the `Crust` builder.
+*
+* Generic parameters:
+* - `A` — positional argument definitions tuple
+* - `F` — the effective (inherited + local merged) flag definitions
+*/
+interface CrustCommandContext<
 	A extends ArgsDef = ArgsDef,
 	F extends FlagsDef = FlagsDef
 > {
-	/** Command metadata (name, description, usage) */
-	readonly meta: CommandMeta;
-	/** Positional argument definitions */
-	readonly args?: A;
-	/** Flag definitions */
-	readonly flags?: F;
-	/** Named subcommands (always initialized, may be empty) */
-	readonly subCommands: Record<string, AnyCommand>;
-	/** Called before `run()` — useful for initialization */
-	preRun?(context: CommandContext<A, F>): void | Promise<void>;
-	/** The main command handler */
-	run?(context: CommandContext<A, F>): void | Promise<void>;
-	/** Called after `run()` (even if it throws) — useful for teardown */
-	postRun?(context: CommandContext<A, F>): void | Promise<void>;
+	/** Resolved positional arguments, keyed by arg name */
+	args: InferArgs<A>;
+	/** Resolved flags, keyed by flag name */
+	flags: InferFlags<F>;
+	/** Raw arguments that appeared after the `--` separator */
+	rawArgs: string[];
+	/** The resolved command node that is being executed */
+	command: CommandNode;
 }
-type AnyCommand = Command<any, any>;
 /**
-* Define a CLI command with full type inference.
+* Build-time validation protocol.
 *
-* The returned command object is frozen (immutable) and typed so that
-* `run()`, `preRun()`, and `postRun()` callbacks receive correctly-typed
-* `args` and `flags` based on the definitions provided.
+* `crust build` spawns the user's entrypoint as a subprocess with
+* `CRUST_INTERNAL_VALIDATE_ONLY=1`. When `.execute()` detects this env flag
+* it runs validation, surfaces errors via stderr/exitCode, then force-exits.
+*/
+declare const VALIDATION_MODE_ENV = "CRUST_INTERNAL_VALIDATE_ONLY";
+/**
+* Chainable builder for defining CLI commands with full type inference.
 *
-* @param config - The command definition config object
-* @returns A frozen, readonly Command object
-* @throws {CrustError} `DEFINITION` if `meta.name` is missing or empty
+* Generic parameters:
+* - `Inherited` — flags inherited from a parent command (populated by `.command()`)
+* - `Local` — flags defined on this command via `.flags()`
+* - `A` — positional argument definitions
 *
 * @example
 * ```ts
-* const cmd = defineCommand({
-*   meta: { name: "serve", description: "Start dev server" },
-*   args: [
-*     { name: "port", type: "number", description: "Port number", default: 3000 },
-*   ],
-*   flags: {
-*     verbose: { type: "boolean", description: "Enable verbose logging", alias: "v" },
-*   },
-*   run({ args, flags }) {
-*     // args.port is typed as number, flags.verbose is typed as boolean | undefined
-*     console.log(`Starting server on port ${args.port}`);
-*   },
-* });
+* const app = new Crust("my-cli")
+*   .flags({
+*     verbose: { type: "boolean", short: "v", inherit: true },
+*   })
+*   .args([{ name: "file", type: "string", required: true }])
+*   .run(({ args, flags }) => {
+*     console.log(args.file, flags.verbose);
+*   });
 * ```
 */
-declare function defineCommand<
-	const A extends ArgsDef = ArgsDef,
-	const F extends FlagsDef = FlagsDef
->(config: CommandDef<A, F> & {
-	args?: ValidateVariadicArgs<A>;
-	flags?: ValidateNoPrefixedFlags<ValidateFlagAliases<F>>;
-}): Command<A, F>;
+declare class Crust<
+	Inherited extends FlagsDef = FlagsDef,
+	Local extends FlagsDef = FlagsDef,
+	A extends ArgsDef = ArgsDef
+> {
+	/** @internal — Phantom property exposing generic parameters for type-level testing */
+	readonly _types: {
+		inherited: Inherited;
+		local: Local;
+		args: A;
+	};
+	/** @internal */
+	readonly _node: CommandNode;
+	/** @internal — The inherited flags record (runtime counterpart of Inherited generic) */
+	readonly _inheritedFlags: FlagsDef;
+	/**
+	* Create a new root or standalone command builder.
+	*
+	* @param name - The command name.
+	* @throws {CrustError} `DEFINITION` if name is empty or whitespace-only
+	*/
+	constructor(name: string);
+	/**
+	* @internal — Create a child builder with pre-populated inherited flags.
+	* Used by `.command()` to propagate parent flags to the child.
+	*/
+	static _createChild<I extends FlagsDef>(name: string, inheritedFlags: FlagsDef): Crust<I, {}, []>;
+	/**
+	* @internal — Clone this builder with a new node, preserving generics.
+	*/
+	private _clone;
+	/**
+	* Set metadata (description, usage) for this command.
+	*
+	* The command name is already set via the constructor or `.command()`,
+	* so only `description` and `usage` can be provided here.
+	*
+	* Returns a new builder with updated metadata. The original builder
+	* is not mutated.
+	*
+	* @param meta - Metadata fields to set (description, usage)
+	* @returns A new `Crust` instance with updated metadata
+	*/
+	meta(meta: Omit<CommandMeta, "name">): Crust<Inherited, Local, A>;
+	/**
+	* Define local flags for this command.
+	*
+	* Returns a new builder with updated local flag types. The original
+	* builder is not mutated.
+	*
+	* @param defs - Flag definitions record
+	* @returns A new `Crust` instance with the given flags
+	* @throws {CrustError} `DEFINITION` if flag names/aliases violate constraints
+	*/
+	flags<const F extends FlagsDef>(defs: F & ValidateNoPrefixedFlags<ValidateFlagAliases<F>> & ValidateCrossCollisions<Inherited, F>): Crust<Inherited, F, A>;
+	/**
+	* Define positional arguments for this command.
+	*
+	* Returns a new builder with updated args types. The original
+	* builder is not mutated.
+	*
+	* @param defs - Ordered tuple of positional argument definitions
+	* @returns A new `Crust` instance with the given args
+	*/
+	args<const NewA extends ArgsDef>(defs: NewA & ValidateVariadicArgs<NewA>): Crust<Inherited, Local, NewA>;
+	/**
+	* Set the main command handler.
+	*
+	* The handler receives a {@link CrustCommandContext} with `args` typed from
+	* `.args()` and `flags` typed as `EffectiveFlags<Inherited, Local>` (inherited
+	* flags merged with local flags).
+	*
+	* Returns a new builder with the handler stored. The original builder is
+	* not mutated.
+	*
+	* @param handler - The main command handler function
+	* @returns A new `Crust` instance with the handler registered
+	*/
+	run(handler: (ctx: NoInfer<CrustCommandContext<A, EffectiveFlags<Inherited, Local>>>) => void | Promise<void>): Crust<Inherited, Local, A>;
+	/**
+	* Set the pre-run lifecycle hook.
+	*
+	* Called before `run()` — useful for initialization and setup.
+	* Receives the same {@link CrustCommandContext} as `run()`.
+	*
+	* @param handler - The pre-run handler function
+	* @returns A new `Crust` instance with the preRun handler registered
+	*/
+	preRun(handler: (ctx: NoInfer<CrustCommandContext<A, EffectiveFlags<Inherited, Local>>>) => void | Promise<void>): Crust<Inherited, Local, A>;
+	/**
+	* Set the post-run lifecycle hook.
+	*
+	* Called after `run()` (even if it throws) — useful for teardown and cleanup.
+	* Receives the same {@link CrustCommandContext} as `run()`.
+	*
+	* @param handler - The post-run handler function
+	* @returns A new `Crust` instance with the postRun handler registered
+	*/
+	postRun(handler: (ctx: NoInfer<CrustCommandContext<A, EffectiveFlags<Inherited, Local>>>) => void | Promise<void>): Crust<Inherited, Local, A>;
+	/**
+	* Register a plugin on this command.
+	*
+	* Plugins are collected during `.execute()` and their `setup()` hooks
+	* receive `SetupContext` and `SetupActions`. Middleware hooks run in
+	* registration order.
+	*
+	* Returns a new builder with the plugin appended. The original builder
+	* is not mutated.
+	*
+	* @param plugin - The plugin to register
+	* @returns A new `Crust` instance with the plugin registered
+	*/
+	use(plugin: CrustPlugin): Crust<Inherited, Local, A>;
+	/**
+	* Create a subcommand builder pre-typed with this command's inheritable flags.
+	*
+	* This is the factory method for the file-splitting pattern. The returned
+	* builder carries this command's effective flags (filtered for `inherit: true`)
+	* as its `Inherited` generic, enabling full type inference in split files
+	* without needing `Crust<any, any, any>`.
+	*
+	* Register the resulting builder with `.command(builder)` on the parent.
+	*
+	* @param name - Subcommand name (must be non-empty)
+	* @returns A new `Crust` builder pre-typed with inherited flags
+	* @throws {CrustError} `DEFINITION` if name is empty or whitespace-only
+	*
+	* @example
+	* ```ts
+	* // shared.ts
+	* const app = new Crust("my-cli")
+	*   .flags({ verbose: { type: "boolean", inherit: true } });
+	*
+	* // commands/deploy.ts
+	* const deployCmd = app.sub("deploy")
+	*   .flags({ env: { type: "string", required: true } })
+	*   .run(({ flags }) => {
+	*     flags.verbose; // boolean | undefined  — typed!
+	*     flags.env;     // string               — typed!
+	*   });
+	*
+	* // cli.ts
+	* app.command(deployCmd).execute();
+	* ```
+	*/
+	sub<N extends string>(name: N): Crust<EffectiveFlags<Inherited, Local>, {}, []>;
+	/**
+	* Register a named subcommand via inline callback.
+	*
+	* The callback receives a fresh `Crust` builder pre-typed with this
+	* command's effective inheritable flags, enabling TypeScript contextual
+	* typing to flow inherited flag types into subcommand definitions.
+	*
+	* @param name - Subcommand name (must be non-empty, unique among siblings)
+	* @param cb - Callback that receives a child builder and returns the configured builder
+	* @returns A new `Crust` instance with the subcommand registered
+	* @throws {CrustError} `DEFINITION` if name is empty or already registered
+	*/
+	command<N extends string>(name: N, cb: (cmd: Crust<EffectiveFlags<Inherited, Local>, {}, []>) => Crust<any, any, any>): Crust<Inherited, Local, A>;
+	/**
+	* Register a pre-built subcommand builder (from `.sub()`).
+	*
+	* The builder's name (from its constructor or `.sub()`) is used as the
+	* subcommand name. This is the complement to `.sub()` for the
+	* file-splitting pattern.
+	*
+	* @param builder - A pre-configured `Crust` builder instance
+	* @returns A new `Crust` instance with the subcommand registered
+	* @throws {CrustError} `DEFINITION` if builder name is empty or already registered
+	*/
+	command(builder: Crust<any, any, any>): Crust<Inherited, Local, A>;
+	/**
+	* Parse `process.argv`, resolve subcommands, run plugins and middleware,
+	* and execute the matched command handler.
+	*
+	* This is the entry point for CLI execution — call it on the root builder.
+	*
+	* @param options - Optional overrides (e.g. custom `argv` for testing)
+	* @returns A promise that resolves when execution completes
+	*/
+	execute(options?: {
+		argv?: string[];
+	}): Promise<void>;
+}
 interface CommandNotFoundErrorDetails {
 	input: string;
 	available: string[];
 	commandPath: string[];
-	parentCommand: AnyCommand;
+	parentCommand: CommandNode;
 }
 interface ValidationErrorDetails {
 	issues: readonly {
@@ -513,109 +905,5 @@ declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Erro
 declare function parseArgs<
 	A extends ArgsDef = ArgsDef,
 	F extends FlagsDef = FlagsDef
->(command: Command<A, F>, argv: string[]): ParseResult<A, F>;
-/**
-* The result of resolving a command from an argv array.
-*
-* Contains the resolved (sub)command and argv after subcommand
-* resolution, and the full command path for help text rendering.
-*/
-interface CommandRoute {
-	/** The routed command (may be a subcommand of the original) */
-	command: AnyCommand;
-	/** The argv after subcommand names have been consumed */
-	argv: string[];
-	/** The command path for help text (e.g. ["crust", "generate", "command"]) */
-	commandPath: string[];
-}
-/**
-* Resolve a command from an argv array by walking the subcommand tree.
-*
-* Subcommand matching happens BEFORE flag parsing, so:
-* `crust build --entry src/cli.ts` first resolves "build" as a subcommand,
-* then passes `["--entry", "src/cli.ts"]` to the build command's parser.
-*
-* Resolution rules:
-* 1. If `argv[0]` matches a subcommand key, recurse into that subcommand
-* 2. If no match and the current command has `run()`, return it (args passed to parser)
-* 3. If no match and the current command has NO `run()`, it signals the caller
-*    should show help (the `showHelp` flag is set in the result)
-* 4. Unknown subcommands produce a structured COMMAND_NOT_FOUND error
-*
-* @param command - The root command to resolve from
-* @param argv - The argv array to resolve against
-* @returns The resolved command, argv, and the command path
-* @throws {CrustError} COMMAND_NOT_FOUND when an unknown subcommand is given and the parent has no run()
-*/
-declare function resolveCommand(command: AnyCommand, argv: string[]): CommandRoute;
-interface PluginState {
-	get<T = unknown>(key: string): T | undefined;
-	has(key: string): boolean;
-	set(key: string, value: unknown): void;
-	delete(key: string): boolean;
-}
-interface SetupActions {
-	/**
-	* Inject a flag definition into a command's flags object.
-	*
-	* Use this in plugin `setup()` hooks to register plugin-specific flags
-	* (e.g. `--version`, `--help`) so they are recognized by the parser
-	* and rendered in help text.
-	*
-	* @param command - The command to add the flag to
-	* @param name - The flag name (e.g. "version")
-	* @param def - The flag definition
-	*/
-	addFlag(command: AnyCommand, name: string, def: FlagDef): void;
-	/**
-	* Inject a subcommand into a command's `subCommands` record.
-	*
-	* Use this in plugin `setup()` hooks to register plugin-provided commands
-	* (e.g. a "skill" management command). If the parent already has a
-	* subcommand with the same name (user-defined), the call is silently
-	* skipped — user definitions always take priority over plugin injections.
-	*
-	* @param parent - The parent command to add the subcommand to
-	* @param name - The subcommand name (used for routing)
-	* @param command - The subcommand to register
-	*/
-	addSubCommand(parent: AnyCommand, name: string, command: AnyCommand): void;
-}
-/** Shared context fields available in both setup and middleware phases. */
-interface BaseContext {
-	readonly argv: readonly string[];
-	readonly rootCommand: AnyCommand;
-	readonly state: PluginState;
-}
-/** Context passed to plugin `setup()` hooks. */
-interface SetupContext extends BaseContext {}
-/** Context passed to plugin `middleware()` hooks. */
-interface MiddlewareContext extends BaseContext {
-	route: Readonly<CommandRoute> | null;
-	input: ParseResult | null;
-}
-type Next = () => Promise<void>;
-type PluginMiddleware = (context: MiddlewareContext, next: Next) => void | Promise<void>;
-interface CrustPlugin {
-	name?: string;
-	setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
-	middleware?: PluginMiddleware;
-}
-/**
-* Build-time validation protocol.
-*
-* `crust build` spawns the user's entrypoint as a subprocess with
-* `CRUST_INTERNAL_VALIDATE_ONLY=1`. When `runMain` detects this env flag it
-* runs validation, surfaces errors via stderr/exitCode, then force-exits.
-*
-* `VALIDATION_RESULT_GLOBAL_KEY` stores the result on `globalThis` for
-* in-process consumers (tests that call `runMain` directly).
-*/
-declare const VALIDATION_MODE_ENV = "CRUST_INTERNAL_VALIDATE_ONLY";
-interface RunOptions {
-	argv?: string[];
-	plugins?: CrustPlugin[];
-}
-declare function runCommand(command: AnyCommand, options?: RunOptions): Promise<void>;
-declare function runMain(command: AnyCommand, options?: RunOptions): Promise<void>;
-export { runMain, runCommand, resolveCommand, parseArgs, defineCommand, ValueType, ValidateVariadicArgs, ValidateNoPrefixedFlags, ValidateFlagAliases, VALIDATION_MODE_ENV, SetupContext, SetupActions, RunOptions, PluginMiddleware, ParseResult, MiddlewareContext, InferFlags, InferArgs, FlagsDef, FlagDef, CrustPlugin, CrustErrorCode, CrustError, CommandRoute, CommandMeta, CommandDef, CommandContext, Command, ArgsDef, ArgDef, AnyCommand };
+>(command: CommandNode, argv: string[]): ParseResult<A, F>;
+export { resolveCommand, parseArgs, createCommandNode, computeEffectiveFlags, ValueType, ValidateVariadicArgs, ValidateNoPrefixedFlags, ValidateFlagAliases, ValidateCrossCollisions, VALIDATION_MODE_ENV, SetupContext, SetupActions, PluginMiddleware, ParseResult, MiddlewareContext, MergeFlags, InheritableFlags, InferFlags, InferArgs, FlagsDef, FlagDef, EffectiveFlags, CrustPlugin, CrustErrorCode, CrustError, CrustCommandContext, Crust, CommandRoute, CommandNode, CommandMeta, ArgsDef, ArgDef };

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-import{a as K,b as I,c as W}from"./shared/chunk-36287c08.js";function G(D){if(!D.meta.name.trim())throw new I("DEFINITION","meta.name must be a non-empty string");if(D.flags)for(let[F,M]of Object.entries(D.flags)){if(F.startsWith("no-")){let P=F.slice(3);throw new I("DEFINITION",`Flag "--${F}" must not use "no-" prefix; define "${P}" and negate with "--no-${P}"`)}if(M.alias){let P=Array.isArray(M.alias)?M.alias:[M.alias];for(let q of P)if(q.startsWith("no-"))throw new I("DEFINITION",`Alias "--${q}" on "--${F}" must not use "no-" prefix (reserved for negation)`)}}let V={...D,meta:{...D.meta},...D.args&&{args:D.args.map((F)=>({...F}))},flags:D.flags?Object.fromEntries(Object.entries(D.flags).map(([F,M])=>[F,{...M}])):{},subCommands:D.subCommands?{...D.subCommands}:{}};return Object.freeze(V)}function Q(D,V){let F=[D.meta.name],M=D,P=V;while(P.length>0){let q=M.subCommands;if(!q||Object.keys(q).length===0)break;let R=P[0];if(!R||R.startsWith("-"))break;if(R in q){M=q[R],F.push(R),P=P.slice(1);continue}if(M.run)break;let J=Object.keys(q);throw new I("COMMAND_NOT_FOUND",`Unknown command "${R}".`,{input:R,available:J,commandPath:[...F],parentCommand:M})}return{command:M,argv:P,commandPath:F}}var Z="CRUST_INTERNAL_VALIDATE_ONLY",O="__CRUST_VALIDATE_RESULT__";function $(){let D=new Map;return{get(V){return D.get(V)},has(V){return D.has(V)},set(V,F){D.set(V,F)},delete(V){return D.delete(V)}}}async function j(D,V,F){for(let M of D){if(!M.setup)continue;await M.setup(V,F)}}function z(D){return{addFlag(V,F,M){if(!V.flags)throw new I("DEFINITION",`Cannot add flag "${F}": "${V.meta.name}" has no flags object`);if(F in V.flags)D?.push(`Plugin flag "--${F}" on "${V.meta.name}" overrides existing flag`);V.flags[F]=M},addSubCommand(V,F,M){if(!F.trim())throw new I("DEFINITION","addSubCommand: name must be a non-empty string");if(V.subCommands[F]){D?.push(`Plugin subcommand "${F}" on "${V.meta.name}" skipped (already exists)`);return}V.subCommands[F]=M}}}async function Y(D,V){let F=V?.argv??process.argv.slice(2),M=V?.plugins??[],P=[],q={argv:[...F],rootCommand:D,state:$()};await j(M,q,z(P));let{validateCommandTree:R}=await import("./shared/chunk-n6bfy2wh.js");R(D);for(let J of P)console.warn(`Warning: ${J}`)}async function y(D,V){if(!D.run)return;let F={args:V.args,flags:V.flags,rawArgs:V.rawArgs,command:D};try{if(D.preRun)await D.preRun(F);await D.run(F)}finally{if(D.postRun)await D.postRun(F)}}async function X(D,V,F){let M=D.map((R)=>R.middleware).filter((R)=>Boolean(R)),P=-1,q=async(R)=>{if(R<=P)throw new I("DEFINITION","Plugin middleware called next() multiple times");if(P=R,R===M.length){await F();return}let J=M[R];if(!J)throw new I("DEFINITION","Plugin middleware stack is invalid");await J(V,()=>q(R+1))};await q(0)}async function B(D,V){let F=V?.argv??process.argv.slice(2),M=V?.plugins??[],P=z(),q={argv:[...F],rootCommand:D,state:$(),route:null,input:null};try{await j(M,q,P);let R,J;try{let N=Q(D,[...F]);q.route=N,R=W(N.command,N.argv),q.input={args:R.args,flags:R.flags,rawArgs:R.rawArgs},J=N.command}catch(N){await X(M,q,async()=>{throw N});return}await X(M,q,async()=>{await y(J,R)})}catch(R){if(R instanceof I)throw R;if(R instanceof Error)throw new I("EXECUTION",R.message).withCause(R);throw new I("EXECUTION",String(R)).withCause(R)}}async function H(D,V){if(process.env[Z]==="1"){let F=(async()=>{try{return await Y(D,V),{ok:!0}}catch(M){let P=M instanceof Error?M.message:String(M);return console.error(P),process.exitCode=1,{ok:!1,error:M}}})();return globalThis[O]=F,await F,process.exit(process.exitCode??0)}try{await B(D,V)}catch(F){let M=F instanceof Error?F.message:String(F);console.error(`Error: ${M}`),process.exitCode=1}}export{H as runMain,B as runCommand,Q as resolveCommand,W as parseArgs,G as defineCommand,Z as VALIDATION_MODE_ENV,I as CrustError};
+import{a as P,b as Z,c as _}from"./shared/chunk-stffrp66.js";function I(j){return{meta:{name:j},localFlags:{},effectiveFlags:{},args:void 0,subCommands:{},plugins:[],preRun:void 0,run:void 0,postRun:void 0}}function z(j,q){let J={};for(let[Q,$]of Object.entries(j))if($.inherit===!0)J[Q]=$;for(let[Q,$]of Object.entries(q))J[Q]=$;return J}function R(j,q){let J=[j.meta.name],Q=j,$=q;while($.length>0){let G=Q.subCommands;if(!G||Object.keys(G).length===0)break;let X=$[0];if(!X||X.startsWith("-"))break;if(X in G&&G[X]){Q=G[X],J.push(X),$=$.slice(1);continue}if(Q.run)break;let U=Object.keys(G);throw new Z("COMMAND_NOT_FOUND",`Unknown command "${X}".`,{input:X,available:U,commandPath:[...J],parentCommand:Q})}return{command:Q,argv:$,commandPath:J}}function F(j){for(let[q,J]of Object.entries(j)){if(q.startsWith("no-")){let Q=q.slice(3);throw new Z("DEFINITION",`Flag "--${q}" must not use "no-" prefix; define "${Q}" and negate with "--no-${Q}"`)}if(J.short?.startsWith("no-"))throw new Z("DEFINITION",`Short alias "-${J.short}" on "--${q}" must not use "no-" prefix (reserved for negation)`);if(J.aliases){for(let Q of J.aliases)if(Q.startsWith("no-"))throw new Z("DEFINITION",`Alias "--${Q}" on "--${q}" must not use "no-" prefix (reserved for negation)`)}}}var S="CRUST_INTERNAL_VALIDATE_ONLY",O="__CRUST_VALIDATE_RESULT__";function y(){let j=new Map;return{get(q){return j.get(q)},has(q){return j.has(q)},set(q,J){j.set(q,J)},delete(q){return j.delete(q)}}}function A(j){return{addFlag(q,J,Q){if(J in q.effectiveFlags)j?.push(`Plugin flag "--${J}" on "${q.meta.name}" overrides existing flag`);q.effectiveFlags[J]=Q},addSubCommand(q,J,Q){if(!J.trim())throw new Z("DEFINITION","addSubCommand: name must be a non-empty string");if(q.subCommands[J]){j?.push(`Plugin subcommand "${J}" on "${q.meta.name}" skipped (already exists)`);return}q.subCommands[J]=Q}}}async function x(j,q,J){for(let Q of j){if(!Q.setup)continue;await Q.setup(q,J)}}async function L(j,q,J){let Q=j.map((X)=>X.middleware).filter((X)=>Boolean(X)),$=-1,G=async(X)=>{if(X<=$)throw new Z("DEFINITION","Plugin middleware called next() multiple times");if($=X,X===Q.length){await J();return}let U=Q[X];if(!U)throw new Z("DEFINITION","Plugin middleware stack is invalid");await U(q,()=>G(X+1))};await G(0)}function T(j){let q=[...j.plugins];for(let J of Object.values(j.subCommands))q.push(...T(J));return q}function B(j){if(Object.freeze(j),Object.freeze(j.localFlags),Object.freeze(j.effectiveFlags),Object.freeze(j.meta),Object.freeze(j.plugins),j.args)Object.freeze(j.args);for(let q of Object.values(j.subCommands))B(q);Object.freeze(j.subCommands)}class V{_node;_inheritedFlags;constructor(j){if(!j.trim())throw new Z("DEFINITION","meta.name must be a non-empty string");this._node=I(j),this._inheritedFlags={}}static _createChild(j,q){let J=new V(j);return J._inheritedFlags=q,J}_clone(j){let q=Object.create(Object.getPrototypeOf(this)),J={...this._node,localFlags:{...this._node.localFlags},effectiveFlags:{...this._node.effectiveFlags},subCommands:{...this._node.subCommands},plugins:[...this._node.plugins],meta:{...this._node.meta},args:this._node.args?[...this._node.args]:void 0,...j};return q._node=J,q._inheritedFlags=this._inheritedFlags,q}meta(j){return this._clone({meta:{...this._node.meta,...j}})}flags(j){F(j);let q={};for(let[J,Q]of Object.entries(j))q[J]={...Q};return this._clone({localFlags:q,effectiveFlags:z(this._inheritedFlags,q)})}args(j){let q=j.map((J)=>({...J}));return this._clone({args:q})}run(j){return this._clone({run:j})}preRun(j){return this._clone({preRun:j})}postRun(j){return this._clone({postRun:j})}use(j){return this._clone({plugins:[...this._node.plugins,j]})}sub(j){if(!j.trim())throw new Z("DEFINITION","Subcommand name must be a non-empty string");let q=z(this._inheritedFlags,this._node.localFlags);return V._createChild(j,q)}command(j,q){if(typeof j==="string"){let G=j;if(!q)throw new Z("DEFINITION","command(name, cb) requires a callback");if(!G.trim())throw new Z("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[G])throw new Z("DEFINITION",`Subcommand "${G}" is already registered`);let X=z(this._inheritedFlags,this._node.localFlags),U=V._createChild(G,X),Y=q(U),W={...Y._node,effectiveFlags:z(Y._inheritedFlags,Y._node.localFlags)};return this._clone({subCommands:{...this._node.subCommands,[G]:W}})}let J=j,Q=J._node.meta.name;if(!Q.trim())throw new Z("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[Q])throw new Z("DEFINITION",`Subcommand "${Q}" is already registered`);let $={...J._node,effectiveFlags:z(J._inheritedFlags,J._node.localFlags)};return this._clone({subCommands:{...this._node.subCommands,[Q]:$}})}async execute(j){let q=j?.argv??process.argv.slice(2),J=this._node,Q=T(J),$=[],G=y(),X={argv:[...q],rootCommand:J,state:G},U=A($);try{await x(Q,X,U)}catch(W){if(W instanceof Z){console.error(`Error: ${W.message}`),process.exitCode=1;return}let H=W instanceof Error?W.message:String(W);console.error(`Error: ${H}`),process.exitCode=1;return}if(B(J),process.env[S]==="1"){let W=(async()=>{try{let{validateCommandTree:H}=await import("./shared/chunk-hzhxdeqq.js");H(J);for(let K of $)console.warn(`Warning: ${K}`);return{ok:!0}}catch(H){let K=H instanceof Error?H.message:String(H);return console.error(K),process.exitCode=1,{ok:!1,error:H}}})();return globalThis[O]=W,await W,process.exit(process.exitCode??0)}for(let W of $)console.warn(`Warning: ${W}`);let Y={argv:[...q],rootCommand:J,state:G,route:null,input:null};try{let W,H;try{let K=R(J,[...q]);Y.route=K,W=K.command,H=_(W,K.argv),Y.input=H}catch(K){await L(Q,Y,async()=>{throw K});return}await L(Q,Y,async()=>{if(!W.run)return;let K={args:H.args,flags:H.flags,rawArgs:H.rawArgs,command:W},M;try{if(W.preRun)await W.preRun(K);await W.run(K)}catch(D){M=D}if(W.postRun)try{await W.postRun(K)}catch(D){if(!M)M=D;else console.error(`Error in postRun: ${D instanceof Error?D.message:String(D)}`)}if(M)throw M})}catch(W){if(W instanceof Z){console.error(`Error: ${W.message}`),process.exitCode=1;return}if(W instanceof Error){let H=new Z("EXECUTION",W.message).withCause(W);console.error(`Error: ${H.message}`),process.exitCode=1;return}console.error(`Error: ${String(W)}`),process.exitCode=1}}}export{R as resolveCommand,_ as parseArgs,I as createCommandNode,z as computeEffectiveFlags,S as VALIDATION_MODE_ENV,Z as CrustError,V as Crust};

package/dist/shared/chunk-hzhxdeqq.js

@@ -0,0 +1,2 @@
+// @bun
+import{b as P,c as Q}from"./chunk-stffrp66.js";function M(B){switch(B.type){case"number":return"1";case"boolean":return"true";default:return"sample"}}function S(B){let z=[],K=B.effectiveFlags;for(let[j,G]of Object.entries(K)){if(G.required!==!0||G.default!==void 0)continue;if(z.push(`--${j}`),G.type!=="boolean")z.push(M(G))}let H=B.args;if(H)for(let j of H){if(j.required!==!0||j.default!==void 0)continue;z.push(M(j))}return z}function Y(B){let z=[{command:B,path:[B.meta.name]}],K=new Set;while(z.length>0){let H=z.pop();if(!H)break;let{command:j,path:G}=H;if(K.has(j))continue;K.add(j);try{Q(j,S(j))}catch(J){let L=J instanceof Error?J.message:"Unknown validation error";throw new P("DEFINITION",`Command "${G.join(" ")}" failed runtime validation: ${L}`).withCause(J)}for(let[J,L]of Object.entries(j.subCommands))z.push({command:L,path:[...G,J]})}}export{Y as validateCommandTree};

package/dist/shared/chunk-stffrp66.js

@@ -0,0 +1,3 @@
+// @bun
+var A=import.meta.require;class W extends Error{code;details;cause;constructor(z,H,...J){super(H);this.name="CrustError",this.code=z,this.details=J[0]}is(z){return this.code===z}withCause(z){return this.cause=z,this}}import{parseArgs as q}from"util";function U(z){let H={},J={};if(!z)return{options:H,aliasToName:J};let B=new Map;for(let j of Object.keys(z))B.set(j,j);for(let[j,G]of Object.entries(z)){if(j.startsWith("no-")){let L=j.slice(3);throw new W("DEFINITION",`Flag "--${j}" must not use "no-" prefix; define "${L}" and negate with "--no-${L}"`)}let K=G.type==="boolean"?"boolean":"string",Q={type:K};if(G.multiple)Q.multiple=!0;if(G.short){if(G.short.startsWith("no-"))throw new W("DEFINITION",`Short alias "-${G.short}" on "--${j}" must not use "no-" prefix (reserved for negation)`);let L=B.get(G.short);if(L)throw new W("DEFINITION",`Alias collision: "-${G.short}" is used by both "--${L}" and "--${j}"`);B.set(G.short,j),J[G.short]=j,Q.short=G.short}if(G.aliases)for(let L of G.aliases){if(L.startsWith("no-"))throw new W("DEFINITION",`Alias "--${L}" on "--${j}" must not use "no-" prefix (reserved for negation)`);let Z=B.get(L);if(Z)throw new W("DEFINITION",`Alias collision: "${L.length===1?"-":"--"}${L}" is used by both "--${Z}" and "--${j}"`);B.set(L,j),J[L]=j;let _={type:K};if(G.multiple)_.multiple=!0;H[L]=_}H[j]=Q}return{options:H,aliasToName:J}}function $(z,H,J){if(H==="number"){let B=Number(z);if(Number.isNaN(B))throw new W("PARSE",`Expected number for ${J}, got "${z}"`);return B}if(H==="boolean")return z==="true"||z==="1";return z}function I(z,H){if(z.default!==void 0)return z.default;if(z.required===!0)throw new W("VALIDATION",`Missing required ${H}`);return}function M(z,H,J){let B=`--${z}`;if(H.multiple&&Array.isArray(J))return H.type==="boolean"?J.filter((j)=>typeof j==="boolean"):J.map((j)=>$(j,H.type,B));if(H.type==="boolean"){if(typeof J==="boolean")return J;throw new W("PARSE",`Expected boolean value for flag "${B}", got ${typeof J}`)}if(typeof J==="string")return $(J,H.type,B);if(J===!0)return H.default??void 0;return J}function h(z,H,J){let B={};for(let j in z){let G=H[j]??j;if(!(G in J))continue;let K=z[j],Q=B[G];if(Q!==void 0&&Array.isArray(Q)&&Array.isArray(K))Q.push(...K);else B[G]=K}return B}function P(z,H,J){if(!z)return{};let B=h(H,J,z),j={};for(let[G,K]of Object.entries(z)){let Q=B[G];if(Q!==void 0){j[G]=M(G,K,Q);continue}j[G]=K.default??void 0}return j}function S(z,H){if(!z)return;for(let[J,B]of Object.entries(z))if(B.required===!0&&B.default===void 0){if(H[J]===void 0)throw new W("VALIDATION",`Missing required flag "--${J}"`)}}function O(z,H){if(!z)return{};let J={},B=0;for(let j of z){let{name:G}=j,K=`argument "<${G}>"`;if(j.variadic){let Q=H.slice(B);if(j.required===!0&&Q.length===0)throw new W("VALIDATION",`Missing required ${K}`);J[G]=j.type==="string"?Q:Q.map((L)=>$(L,j.type,`<${G}>`)),B=H.length}else if(B<H.length)J[G]=$(H[B],j.type,`<${G}>`),B++;else J[G]=I(j,K)}return J}function R(z,H,J){if(!H)return;for(let B of z){if(B==="--")return;if(!B.startsWith("--no-"))continue;let j=B.indexOf("="),G=j===-1?B.slice(5):B.slice(5,j);if(!G)continue;let K=J[G];if(!K)continue;if(K===G)continue;if(H[K]?.type!=="boolean")continue;throw new W("PARSE",`Cannot negate alias "--no-${G}"; use "--no-${K}" instead`)}}function E(z,H){let{args:J,effectiveFlags:B}=z,{options:j,aliasToName:G}=U(B);R(H,B,G);let K;try{K=q({args:H,options:j,strict:!0,allowPositionals:!0,allowNegative:!0,tokens:!0})}catch(X){if(X instanceof Error){let Y=X.message.match(/Unknown option '(.+?)'/);if(Y)throw new W("PARSE",`Unknown flag "${Y[1]}"`).withCause(X)}throw new W("PARSE","Failed to parse command arguments").withCause(X)}let Q=[],L=[];if(K.tokens){let X=!1;for(let Y of K.tokens){if(Y.kind==="option-terminator"){X=!0;continue}if(Y.kind==="positional")(X?Q:L).push(Y.value??"")}}else L.push(...K.positionals);let Z=P(B,K.values,G),_=O(J,L);return S(B,Z),{args:_,flags:Z,rawArgs:Q}}
+export{A as a,W as b,E as c};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/core",
-	"version": "0.0.9",
+	"version": "0.0.10",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",

package/dist/shared/chunk-36287c08.js

@@ -1,3 +0,0 @@
-// @bun
-var A=import.meta.require;class W extends Error{code;details;cause;constructor(j,G,...H){super(G);this.name="CrustError",this.code=j,this.details=H[0]}is(j){return this.code===j}withCause(j){return this.cause=j,this}}import{parseArgs as q}from"util";function U(j){let G={},H={};if(!j)return{options:G,aliasToName:H};let z=new Map;for(let B of Object.keys(j))z.set(B,B);for(let[B,J]of Object.entries(j)){if(B.startsWith("no-")){let X=B.slice(3);throw new W("DEFINITION",`Flag "--${B}" must not use "no-" prefix; define "${X}" and negate with "--no-${X}"`)}let K=J.type==="boolean"?"boolean":"string",L={type:K};if(J.multiple)L.multiple=!0;if(J.alias){let X=Array.isArray(J.alias)?J.alias:[J.alias];for(let Q of X){if(Q.startsWith("no-"))throw new W("DEFINITION",`Alias "--${Q}" on "--${B}" must not use "no-" prefix (reserved for negation)`);let _=z.get(Q);if(_)throw new W("DEFINITION",`Alias collision: "${Q.length===1?"-":"--"}${Q}" is used by both "--${_}" and "--${B}"`);if(z.set(Q,B),H[Q]=B,Q.length===1&&!L.short)L.short=Q;else{let Y={type:K};if(J.multiple)Y.multiple=!0;G[Q]=Y}}}G[B]=L}return{options:G,aliasToName:H}}function $(j,G,H){if(G==="number"){let z=Number(j);if(Number.isNaN(z))throw new W("PARSE",`Expected number for ${H}, got "${j}"`);return z}if(G==="boolean")return j==="true"||j==="1";return j}function I(j,G){if(j.default!==void 0)return j.default;if(j.required===!0)throw new W("VALIDATION",`Missing required ${G}`);return}function M(j,G,H){let z=`--${j}`;if(G.multiple&&Array.isArray(H))return G.type==="boolean"?H.filter((B)=>typeof B==="boolean"):H.map((B)=>$(B,G.type,z));if(G.type==="boolean"){if(typeof H==="boolean")return H;throw new W("PARSE",`Expected boolean value for flag "${z}", got ${typeof H}`)}if(typeof H==="string")return $(H,G.type,z);if(H===!0)return G.default??void 0;return H}function R(j,G,H){let z={};for(let B in j){let J=G[B]??B;if(!(J in H))continue;let K=j[B],L=z[J];if(L!==void 0&&Array.isArray(L)&&Array.isArray(K))L.push(...K);else z[J]=K}return z}function h(j,G,H){if(!j)return{};let z=R(G,H,j),B={};for(let[J,K]of Object.entries(j)){let L=z[J];if(L!==void 0){B[J]=M(J,K,L);continue}B[J]=K.default??void 0}return B}function P(j,G){if(!j)return;for(let[H,z]of Object.entries(j))if(z.required===!0&&z.default===void 0){if(G[H]===void 0)throw new W("VALIDATION",`Missing required flag "--${H}"`)}}function S(j,G){if(!j)return{};let H={},z=0;for(let B of j){let{name:J}=B,K=`argument "<${J}>"`;if(B.variadic){let L=G.slice(z);if(B.required===!0&&L.length===0)throw new W("VALIDATION",`Missing required ${K}`);H[J]=B.type==="string"?L:L.map((X)=>$(X,B.type,`<${J}>`)),z=G.length}else if(z<G.length)H[J]=$(G[z],B.type,`<${J}>`),z++;else H[J]=I(B,K)}return H}function O(j,G,H){if(!G)return;for(let z of j){if(z==="--")return;if(!z.startsWith("--no-"))continue;let B=z.indexOf("="),J=B===-1?z.slice(5):z.slice(5,B);if(!J)continue;let K=H[J];if(!K)continue;if(K===J)continue;if(G[K]?.type!=="boolean")continue;throw new W("PARSE",`Cannot negate alias "--no-${J}"; use "--no-${K}" instead`)}}function x(j,G){let{args:H,flags:z}=j,{options:B,aliasToName:J}=U(z);O(G,z,J);let K;try{K=q({args:G,options:B,strict:!0,allowPositionals:!0,allowNegative:!0,tokens:!0})}catch(Y){if(Y instanceof Error){let Z=Y.message.match(/Unknown option '(.+?)'/);if(Z)throw new W("PARSE",`Unknown flag "${Z[1]}"`).withCause(Y)}throw new W("PARSE","Failed to parse command arguments").withCause(Y)}let L=[],X=[];if(K.tokens){let Y=!1;for(let Z of K.tokens){if(Z.kind==="option-terminator"){Y=!0;continue}if(Z.kind==="positional")(Y?L:X).push(Z.value??"")}}else X.push(...K.positionals);let Q=h(z,K.values,J),_=S(H,X);return P(z,Q),{args:_,flags:Q,rawArgs:L}}
-export{A as a,W as b,x as c};

package/dist/shared/chunk-n6bfy2wh.js

@@ -1,2 +0,0 @@
-// @bun
-import{b as G,c as H}from"./chunk-36287c08.js";function F(j){switch(j.type){case"number":return"1";case"boolean":return"true";default:return"sample"}}function I(j){let q=[];if(j.flags)for(let[w,x]of Object.entries(j.flags)){if(x.required!==!0||x.default!==void 0)continue;if(q.push(`--${w}`),x.type!=="boolean")q.push(F(x))}if(j.args)for(let w of j.args){if(w.required!==!0||w.default!==void 0)continue;q.push(F(w))}return q}function L(j){let q=[{command:j,path:[j.meta.name]}],w=new Set;while(q.length>0){let x=q.pop();if(!x)break;let{command:y,path:D}=x;if(w.has(y))continue;w.add(y);try{H(y,I(y))}catch(z){let B=z instanceof Error?z.message:"Unknown validation error";throw new G("DEFINITION",`Command "${D.join(" ")}" failed runtime validation: ${B}`).withCause(z)}for(let[z,B]of Object.entries(y.subCommands))q.push({command:B,path:[...D,z]})}}export{L as validateCommandTree};