@crustjs/core 0.0.8 → 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,98 +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;
-}
-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, 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,459 +1,2 @@
 // @bun
-// src/errors.ts
-class CrustError extends Error {
-  code;
-  details;
-  cause;
-  constructor(code, message, ...details) {
-    super(message);
-    this.name = "CrustError";
-    this.code = code;
-    this.details = details[0];
-  }
-  is(code) {
-    return this.code === code;
-  }
-  withCause(cause) {
-    this.cause = cause;
-    return this;
-  }
-}
-
-// src/command.ts
-function defineCommand(config) {
-  if (!config.meta.name.trim()) {
-    throw new CrustError("DEFINITION", "defineCommand: meta.name is required and must be a non-empty string");
-  }
-  if (config.flags) {
-    for (const [name, def] of Object.entries(config.flags)) {
-      if (name.startsWith("no-")) {
-        const base = name.slice(3);
-        throw new CrustError("DEFINITION", `Flag name "--${name}" must not start with "no-"; define "${base}" instead and use "--no-${base}" at runtime`);
-      }
-      if (def.alias) {
-        const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
-        for (const alias of aliases) {
-          if (alias.startsWith("no-")) {
-            throw new CrustError("DEFINITION", `Alias "--${alias}" on flag "--${name}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`);
-          }
-        }
-      }
-    }
-  }
-  const copy = {
-    ...config,
-    meta: { ...config.meta },
-    ...config.args && {
-      args: config.args.map((def) => ({ ...def }))
-    },
-    flags: config.flags ? Object.fromEntries(Object.entries(config.flags).map(([k, v]) => [k, { ...v }])) : {},
-    subCommands: config.subCommands ? { ...config.subCommands } : {}
-  };
-  return Object.freeze(copy);
-}
-// src/parser.ts
-import {
-  parseArgs as nodeParseArgs
-} from "util";
-function buildParseArgsOptionDescriptor(flagsDef) {
-  const options = {};
-  const aliasToName = {};
-  if (!flagsDef)
-    return { options, aliasToName };
-  const aliasRegistry = new Map;
-  for (const name of Object.keys(flagsDef)) {
-    aliasRegistry.set(name, name);
-  }
-  for (const [name, def] of Object.entries(flagsDef)) {
-    if (name.startsWith("no-")) {
-      const base = name.slice(3);
-      throw new CrustError("DEFINITION", `Flag name "--${name}" must not start with "no-"; define "${base}" instead and use "--no-${base}" at runtime`);
-    }
-    const parseType = def.type === "boolean" ? "boolean" : "string";
-    const opt = { type: parseType };
-    if (def.multiple) {
-      opt.multiple = true;
-    }
-    if (def.alias) {
-      const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
-      for (const alias of aliases) {
-        if (alias.startsWith("no-")) {
-          throw new CrustError("DEFINITION", `Alias "--${alias}" on flag "--${name}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`);
-        }
-        const existing = aliasRegistry.get(alias);
-        if (existing) {
-          throw new CrustError("DEFINITION", `Alias collision: "${alias.length === 1 ? "-" : "--"}${alias}" is used by both "--${existing}" and "--${name}"`);
-        }
-        aliasRegistry.set(alias, name);
-        aliasToName[alias] = name;
-        if (alias.length === 1 && !opt.short) {
-          opt.short = alias;
-        } else {
-          const aliasOpt = { type: parseType };
-          if (def.multiple) {
-            aliasOpt.multiple = true;
-          }
-          options[alias] = aliasOpt;
-        }
-      }
-    }
-    options[name] = opt;
-  }
-  return { options, aliasToName };
-}
-function coerceValue(value, type, label) {
-  if (type === "number") {
-    const num = Number(value);
-    if (Number.isNaN(num)) {
-      throw new CrustError("PARSE", `Expected number for ${label}, got "${value}"`);
-    }
-    return num;
-  }
-  if (type === "boolean") {
-    return value === "true" || value === "1";
-  }
-  return value;
-}
-function applyDefaultOrThrow(def, label) {
-  if (def.default !== undefined)
-    return def.default;
-  if (def.required === true) {
-    throw new CrustError("VALIDATION", `Missing required ${label}`);
-  }
-  return;
-}
-function coerceFlagValue(name, def, parsedValue) {
-  const label = `--${name}`;
-  if (def.multiple && Array.isArray(parsedValue)) {
-    return def.type === "boolean" ? parsedValue.filter((v) => typeof v === "boolean") : parsedValue.map((v) => coerceValue(v, def.type, label));
-  }
-  if (def.type === "boolean") {
-    if (typeof parsedValue === "boolean") {
-      return parsedValue;
-    }
-    throw new CrustError("PARSE", `Expected boolean value for flag "${label}", got ${typeof parsedValue}`);
-  }
-  if (typeof parsedValue === "string") {
-    return coerceValue(parsedValue, def.type, label);
-  }
-  if (parsedValue === true) {
-    return def.default ?? undefined;
-  }
-  return parsedValue;
-}
-function resolveAliases(parsedValues, aliasToName, flagsDef) {
-  const canonical = {};
-  for (const key in parsedValues) {
-    const canonicalName = aliasToName[key] ?? key;
-    if (!(canonicalName in flagsDef))
-      continue;
-    const value = parsedValues[key];
-    const existing = canonical[canonicalName];
-    if (existing !== undefined && Array.isArray(existing) && Array.isArray(value)) {
-      existing.push(...value);
-    } else {
-      canonical[canonicalName] = value;
-    }
-  }
-  return canonical;
-}
-function resolveFlags(flagsDef, parsedValues, aliasToName) {
-  if (!flagsDef)
-    return {};
-  const canonical = resolveAliases(parsedValues, aliasToName, flagsDef);
-  const resolved = {};
-  for (const [name, def] of Object.entries(flagsDef)) {
-    const parsedValue = canonical[name];
-    if (parsedValue !== undefined) {
-      resolved[name] = coerceFlagValue(name, def, parsedValue);
-      continue;
-    }
-    resolved[name] = def.default ?? undefined;
-  }
-  return resolved;
-}
-function validateRequiredFlags(flagsDef, resolvedFlags) {
-  if (!flagsDef)
-    return;
-  for (const [name, def] of Object.entries(flagsDef)) {
-    if (def.required === true && def.default === undefined) {
-      if (resolvedFlags[name] === undefined) {
-        throw new CrustError("VALIDATION", `Missing required flag "--${name}"`);
-      }
-    }
-  }
-}
-function resolveArgs(argsDef, positionals) {
-  if (!argsDef)
-    return {};
-  const resolved = {};
-  let index = 0;
-  for (const def of argsDef) {
-    const { name } = def;
-    const label = `argument "<${name}>"`;
-    if (def.variadic) {
-      const remaining = positionals.slice(index);
-      if (def.required === true && remaining.length === 0) {
-        throw new CrustError("VALIDATION", `Missing required ${label}`);
-      }
-      resolved[name] = def.type === "string" ? remaining : remaining.map((v) => coerceValue(v, def.type, `<${name}>`));
-      index = positionals.length;
-    } else if (index < positionals.length) {
-      resolved[name] = coerceValue(positionals[index], def.type, `<${name}>`);
-      index++;
-    } else {
-      resolved[name] = applyDefaultOrThrow(def, label);
-    }
-  }
-  return resolved;
-}
-function validateCanonicalNegationUsage(argv, flagsDef, aliasToName) {
-  if (!flagsDef)
-    return;
-  for (const arg of argv) {
-    if (arg === "--")
-      return;
-    if (!arg.startsWith("--no-"))
-      continue;
-    const assignmentIndex = arg.indexOf("=");
-    const rawName = assignmentIndex === -1 ? arg.slice("--no-".length) : arg.slice("--no-".length, assignmentIndex);
-    if (!rawName)
-      continue;
-    const canonical = aliasToName[rawName];
-    if (!canonical)
-      continue;
-    if (canonical === rawName)
-      continue;
-    const def = flagsDef[canonical];
-    if (def?.type !== "boolean")
-      continue;
-    throw new CrustError("PARSE", `Cannot negate alias "--no-${rawName}"; use "--no-${canonical}" instead`);
-  }
-}
-function parseArgs(command, argv) {
-  const argsDef = command.args;
-  const flagsDef = command.flags;
-  const { options: parseOptions, aliasToName } = buildParseArgsOptionDescriptor(flagsDef);
-  validateCanonicalNegationUsage(argv, flagsDef, aliasToName);
-  let parsed;
-  try {
-    parsed = nodeParseArgs({
-      args: argv,
-      options: parseOptions,
-      strict: true,
-      allowPositionals: true,
-      allowNegative: true,
-      tokens: true
-    });
-  } catch (error) {
-    if (error instanceof Error) {
-      const unknownMatch = error.message.match(/Unknown option '(.+?)'/);
-      if (unknownMatch) {
-        throw new CrustError("PARSE", `Unknown flag "${unknownMatch[1]}"`).withCause(error);
-      }
-    }
-    throw new CrustError("PARSE", "Failed to parse command arguments").withCause(error);
-  }
-  const rawArgs = [];
-  const preSeparatorPositionals = [];
-  if (parsed.tokens) {
-    let afterSeparator = false;
-    for (const token of parsed.tokens) {
-      if (token.kind === "option-terminator") {
-        afterSeparator = true;
-        continue;
-      }
-      if (token.kind === "positional") {
-        (afterSeparator ? rawArgs : preSeparatorPositionals).push(token.value ?? "");
-      }
-    }
-  } else {
-    preSeparatorPositionals.push(...parsed.positionals);
-  }
-  const resolvedFlags = resolveFlags(flagsDef, parsed.values, aliasToName);
-  const resolvedArgs = resolveArgs(argsDef, preSeparatorPositionals);
-  validateRequiredFlags(flagsDef, resolvedFlags);
-  return {
-    args: resolvedArgs,
-    flags: resolvedFlags,
-    rawArgs
-  };
-}
-// src/router.ts
-function resolveCommand(command, argv) {
-  const path = [command.meta.name];
-  let current = command;
-  let routedArgv = argv;
-  while (routedArgv.length > 0) {
-    const subCommands = current.subCommands;
-    if (!subCommands || Object.keys(subCommands).length === 0) {
-      break;
-    }
-    const candidate = routedArgv[0];
-    if (!candidate || candidate.startsWith("-")) {
-      break;
-    }
-    if (candidate in subCommands) {
-      current = subCommands[candidate];
-      path.push(candidate);
-      routedArgv = routedArgv.slice(1);
-      continue;
-    }
-    if (current.run) {
-      break;
-    }
-    const available = Object.keys(subCommands);
-    throw new CrustError("COMMAND_NOT_FOUND", `Unknown command "${candidate}".`, {
-      input: candidate,
-      available,
-      commandPath: [...path],
-      parentCommand: current
-    });
-  }
-  return {
-    command: current,
-    argv: routedArgv,
-    commandPath: path
-  };
-}
-// src/run.ts
-function createPluginState() {
-  const map = new Map;
-  return {
-    get(key) {
-      return map.get(key);
-    },
-    has(key) {
-      return map.has(key);
-    },
-    set(key, value) {
-      map.set(key, value);
-    },
-    delete(key) {
-      return map.delete(key);
-    }
-  };
-}
-async function runSetupHooks(plugins, context, actions) {
-  for (const plugin of plugins) {
-    if (!plugin.setup)
-      continue;
-    await plugin.setup(context, actions);
-  }
-}
-async function executeCommand(command, parsed) {
-  if (!command.run)
-    return;
-  const context = {
-    args: parsed.args,
-    flags: parsed.flags,
-    rawArgs: parsed.rawArgs,
-    command
-  };
-  try {
-    if (command.preRun) {
-      await command.preRun(context);
-    }
-    await command.run(context);
-  } finally {
-    if (command.postRun) {
-      await command.postRun(context);
-    }
-  }
-}
-async function runMiddlewareChain(plugins, context, terminal) {
-  const stack = plugins.map((plugin) => plugin.middleware).filter((middleware) => Boolean(middleware));
-  let index = -1;
-  const dispatch = async (i) => {
-    if (i <= index) {
-      throw new CrustError("DEFINITION", "Plugin middleware called next() multiple times");
-    }
-    index = i;
-    if (i === stack.length) {
-      await terminal();
-      return;
-    }
-    const middleware = stack[i];
-    if (!middleware) {
-      throw new CrustError("DEFINITION", "Plugin middleware stack is invalid");
-    }
-    await middleware(context, () => dispatch(i + 1));
-  };
-  await dispatch(0);
-}
-async function runCommand(command, options) {
-  const argv = options?.argv ?? process.argv.slice(2);
-  const plugins = options?.plugins ?? [];
-  const actions = {
-    addFlag(target, name, def) {
-      if (!target.flags) {
-        throw new CrustError("DEFINITION", `Cannot add flag "${name}": command "${target.meta.name}" has no flags object.`);
-      }
-      target.flags[name] = def;
-    },
-    addSubCommand(parent, name, subCommand) {
-      if (!name.trim()) {
-        throw new CrustError("DEFINITION", "addSubCommand: name is required and must be a non-empty string");
-      }
-      if (parent.subCommands[name])
-        return;
-      parent.subCommands[name] = subCommand;
-    }
-  };
-  const middlewareContext = {
-    argv: [...argv],
-    rootCommand: command,
-    state: createPluginState(),
-    route: null,
-    input: null
-  };
-  try {
-    await runSetupHooks(plugins, middlewareContext, actions);
-    let parsed;
-    let resolvedCommand;
-    try {
-      const resolved = resolveCommand(command, [...argv]);
-      middlewareContext.route = resolved;
-      parsed = parseArgs(resolved.command, resolved.argv);
-      middlewareContext.input = {
-        args: parsed.args,
-        flags: parsed.flags,
-        rawArgs: parsed.rawArgs
-      };
-      resolvedCommand = resolved.command;
-    } catch (error) {
-      await runMiddlewareChain(plugins, middlewareContext, async () => {
-        throw error;
-      });
-      return;
-    }
-    await runMiddlewareChain(plugins, middlewareContext, async () => {
-      await executeCommand(resolvedCommand, parsed);
-    });
-  } catch (error) {
-    if (error instanceof CrustError) {
-      throw error;
-    }
-    if (error instanceof Error) {
-      throw new CrustError("EXECUTION", error.message).withCause(error);
-    }
-    throw new CrustError("EXECUTION", String(error)).withCause(error);
-  }
-}
-async function runMain(command, options) {
-  try {
-    await runCommand(command, options);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`Error: ${message}`);
-    process.exitCode = 1;
-  }
-}
-export {
-  runMain,
-  runCommand,
-  resolveCommand,
-  parseArgs,
-  defineCommand,
-  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.8",
+	"version": "0.0.10",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",