@crustjs/core 0.0.16 → 0.0.18

package/README.md

@@ -2,7 +2,7 @@
 
 The core library for the [Crust](https://crustjs.com) CLI framework.
 
-Provides command definition, argument/flag parsing, subcommand routing, lifecycle hooks, and a plugin system — with **zero runtime dependencies**.
+Provides command definition, argument/flag parsing, subcommand routing, lifecycle hooks, and a plugin system.
 
 ## Install
 
@@ -29,6 +29,28 @@ const app = new Crust("greet")
 app.execute();
 ```
 
+## Built-in value types
+
+Flags and positional arguments support six built-in `type` literals:
+
+- `"string"`  — raw string token
+- `"number"`  — coerced via `Number(raw)`
+- `"boolean"` — toggle (`--flag` / `--no-flag`)
+- `"url"`     — `new URL(raw)` → `URL` instance
+- `"path"`    — `~` expanded, resolved to an absolute `string`
+- `"json"`    — `JSON.parse(raw)` → `unknown`
+
+For formats that aren't built in, attach a synchronous `parse` to a `type: "string"` flag or arg. The inferred type flows from `ReturnType<parse>`:
+
+```ts
+flags: {
+  port: { type: "string", parse: (s) => Number(s), default: "3000" },
+}
+// flags.port: number
+```
+
+See the [Types](https://crustjs.com/docs/guide/types) guide for the full contract, error modes, and copy-paste recipes.
+
 ## Documentation
 
 See the full docs at [crustjs.com](https://crustjs.com).

package/dist/index.d.ts

@@ -21,10 +21,19 @@ interface CommandRoute {
 *
 * 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
+* 2. If `argv[0]` matches a sibling's `meta.aliases` entry, recurse into
+*    that sibling and record the **canonical** name in `commandPath`
+* 3. If no match and the current command has `run()`, return it (args passed to parser)
+* 4. 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
+* 5. Unknown subcommands produce a structured COMMAND_NOT_FOUND error whose
+*    `details.available` lists the canonical sibling names (aliases are
+*    discoverable via `details.parentCommand.subCommands[name].meta.aliases`)
+*
+* Implementation: linear scan over siblings on miss. Command trees are small
+* and resolution runs once per invocation, so the cost is negligible compared
+* to building/freezing a parallel alias→canonical map. The scan does NOT
+* mutate `CommandNode`.
 *
 * @param command - The root command to resolve from
 * @param argv - The argv array to resolve against
@@ -32,25 +41,60 @@ interface CommandRoute {
 * @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";
+import { BaseValueType, ResolvePrimitive } from "@crustjs/utils";
+/**
+* Supported type literals for args and flags.
+*
+* Extends `BaseValueType` (`"string" | "number" | "boolean"`) with three
+* formatted built-ins:
+*
+* - `"url"`  — the raw value is parsed via `new URL()` into a {@link URL}
+* - `"path"` — the raw value is expanded (`~`) and resolved against
+*              `process.cwd()` into an absolute `string`
+* - `"json"` — the raw value is parsed via `JSON.parse()` into `unknown`
+*/
+type ValueType = BaseValueType | "url" | "path" | "json";
 /**
-* Resolves a type literal to its corresponding TypeScript primitive type.
+* Resolve a {@link ValueType} literal to its runtime TypeScript type.
 *
-* - `"string"` → `string`
-* - `"number"` → `number`
-* - `"boolean"` → `boolean`
+* Delegates to `ResolvePrimitive<T>` for the three base types; maps the
+* three formatted types (`"url"`, `"path"`, `"json"`) to `URL`, `string`,
+* and `unknown` respectively.
 */
-type ResolvePrimitive<T extends ValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+type Resolve<T extends ValueType> = T extends BaseValueType ? ResolvePrimitive<T> : T extends "url" ? URL : T extends "path" ? string : T extends "json" ? unknown : never;
+/**
+* Resolve the inferred runtime type for a flag/arg definition.
+*
+* When the def declares a `parse` escape hatch (only allowed on `"string"`
+* variants), the inferred type is `ReturnType<typeof parse>`. Otherwise it
+* delegates to {@link Resolve} on the declared `type`.
+*/
+type ResolveBaseType<F> = F extends {
+	parse: (raw: string) => infer R;
+} ? R : F extends {
+	type: infer T extends ValueType;
+} ? Resolve<T> : never;
 /** Shared fields present on every positional argument definition */
 interface ArgDefBase {
 	/** The argument name (used as the key in the parsed result and in help text) */
 	name: string;
 	/** Human-readable description for help text */
 	description?: string;
-	/** When `true`, the parser throws if the argument is not provided */
+	/**
+	* When `true`, the parser throws if the argument is not provided.
+	*
+	* For variadic args, this means the array cannot be empty — the runtime
+	* value is still `T[]`, just rejected when it has length 0.
+	*/
 	required?: true;
-	/** When `true`, collects all remaining positional values into an array */
+	/**
+	* When `true`, collects all remaining positional values into an array.
+	*
+	* The inferred TypeScript type is always `T[]` — never `T[] | undefined` —
+	* regardless of `required` or `default`. `required` only controls whether
+	* an empty array fails validation; it does not change the runtime shape
+	* or the inferred type.
+	*/
 	variadic?: true;
 }
 /** A positional argument whose value is a string */
@@ -58,18 +102,68 @@ interface StringArgDef extends ArgDefBase {
 	type: "string";
 	/** Default string value when the argument is not provided */
 	default?: string;
+	/**
+	* Static enum of valid values for this argument.
+	*
+	* Validated at parse time before `parse` runs. Passing a value outside
+	* `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+	* is applied. Also consumed by shell-completion plugins
+	* (e.g. `@crustjs/plugins/completion`) to emit value candidates.
+	*
+	* Only available on string-typed args; not supported on number/boolean.
+	*
+	* @example
+	* { name: "target", type: "string", choices: ["browser", "bun", "node"] }
+	*/
+	choices?: readonly string[];
+	/**
+	* Custom synchronous parser for the raw argv string. Runs per element
+	* for variadic args. See {@link StringFlagDef.parse} for full semantics.
+	*
+	* @example
+	* { name: "port", type: "string", parse: (s) => Number(s) }
+	*/
+	parse?: (raw: string) => unknown;
 }
 /** A positional argument whose value is a number */
 interface NumberArgDef extends ArgDefBase {
 	type: "number";
 	/** Default number value when the argument is not provided */
 	default?: number;
+	/** Not supported on number args — use `type: "string"` with `parse`. */
+	parse?: never;
 }
 /** A positional argument whose value is a boolean */
 interface BooleanArgDef extends ArgDefBase {
 	type: "boolean";
 	/** Default boolean value when the argument is not provided */
 	default?: boolean;
+	/** Not supported on boolean args — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A positional argument whose value is a {@link URL} */
+interface UrlArgDef extends ArgDefBase {
+	type: "url";
+	/** Default URL value when the argument is not provided */
+	default?: URL;
+	/** Not supported on url args — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A positional argument whose value is an absolute filesystem path */
+interface PathArgDef extends ArgDefBase {
+	type: "path";
+	/** Default path string when the argument is not provided */
+	default?: string;
+	/** Not supported on path args — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A positional argument whose value is JSON parsed to `unknown` */
+interface JsonArgDef extends ArgDefBase {
+	type: "json";
+	/** Default parsed JSON value when the argument is not provided */
+	default?: unknown;
+	/** Not supported on json args — use `type: "string"` with `parse`. */
+	parse?: never;
 }
 /**
 * Defines a single positional argument for a CLI command.
@@ -86,7 +180,16 @@ interface BooleanArgDef extends ArgDefBase {
 * ] as const satisfies ArgsDef;
 * ```
 */
-type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef;
+interface RawArgDef extends ArgDefBase {
+	/** Optional parser hint. Omit for raw schema-backed validation. */
+	type?: never;
+	/** Raw default value when the argument is not provided */
+	default?: unknown;
+	choices?: readonly string[];
+	/** Not supported on raw args — schema validators own the transform. */
+	parse?: never;
+}
+type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef | UrlArgDef | PathArgDef | JsonArgDef | RawArgDef;
 /** Ordered tuple of positional argument definitions */
 type ArgsDef = readonly ArgDef[];
 /** Shared fields present on every flag definition */
@@ -112,12 +215,49 @@ interface StringFlagDef extends SingleFlagBase {
 	type: "string";
 	/** Default string value */
 	default?: string;
+	/**
+	* Static enum of valid values for this flag.
+	*
+	* Validated at parse time before `parse` runs. Passing a value outside
+	* `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+	* is applied. Also consumed by shell-completion plugins
+	* (e.g. `@crustjs/plugins/completion`) to emit value candidates.
+	*
+	* Only available on string-typed flags; not supported on number/boolean.
+	*
+	* @example
+	* { type: "string", choices: ["browser", "bun", "node"] }
+	*/
+	choices?: readonly string[];
+	/**
+	* Custom synchronous parser for the raw argv string.
+	*
+	* Receives the raw token as it appeared on the command line (after
+	* `choices` validation, when present) and returns the resolved value
+	* that flows to the `run` handler. The return type is inferred and
+	* becomes the flag's runtime type.
+	*
+	* Constraints:
+	* - Synchronous only. `async` parsers are rejected at command setup
+	*   with `CrustError("CONFIG", …)`.
+	* - Only allowed on `type: "string"` (single + multi) and string args.
+	*   `parse?: never` on every non-string variant prevents misuse at
+	*   compile time.
+	* - When `default` is set and argv is absent, `parse(String(default))`
+	*   runs so the runtime value matches the inferred type.
+	*
+	* @example
+	* { type: "string", parse: (s) => Number(s) }
+	*/
+	parse?: (raw: string) => unknown;
 }
 /** A single-value number flag */
 interface NumberFlagDef extends SingleFlagBase {
 	type: "number";
 	/** Default number value */
 	default?: number;
+	/** Not supported on number flags — use `type: "string"` with `parse`. */
+	parse?: never;
 }
 /** A single-value boolean flag */
 interface BooleanFlagDef extends SingleFlagBase {
@@ -126,6 +266,32 @@ interface BooleanFlagDef extends SingleFlagBase {
 	default?: boolean;
 	/** When `true`, hide the generated `--no-{name}` help label */
 	noNegate?: true;
+	/** Not supported on boolean flags — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A single-value URL flag (parsed via `new URL()`) */
+interface UrlFlagDef extends SingleFlagBase {
+	type: "url";
+	/** Default URL value */
+	default?: URL;
+	/** Not supported on url flags — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A single-value path flag (expanded `~` + resolved against `process.cwd()`) */
+interface PathFlagDef extends SingleFlagBase {
+	type: "path";
+	/** Default path string value */
+	default?: string;
+	/** Not supported on path flags — use `type: "string"` with `parse`. */
+	parse?: never;
+}
+/** A single-value JSON flag (parsed via `JSON.parse()` to `unknown`) */
+interface JsonFlagDef extends SingleFlagBase {
+	type: "json";
+	/** Default parsed JSON value */
+	default?: unknown;
+	/** Not supported on json flags — use `type: "string"` with `parse`. */
+	parse?: never;
 }
 /** Base for multi-value flags — `multiple` is required as `true` */
 interface MultiFlagBase extends FlagDefBase {
@@ -137,12 +303,34 @@ interface StringMultiFlagDef extends MultiFlagBase {
 	type: "string";
 	/** Default string array value */
 	default?: string[];
+	/**
+	* Static enum of valid values for each occurrence of this flag.
+	*
+	* Each element is validated at parse time before `parse` runs. Passing
+	* a value outside `choices` throws `CrustError("PARSE", …)` before any
+	* `parse` transform is applied. Also consumed by shell-completion
+	* plugins (e.g. `@crustjs/plugins/completion`) to emit value candidates.
+	*
+	* Only available on string-typed multi-flags; not supported on number/boolean.
+	*
+	* @example
+	* { type: "string", multiple: true, choices: ["unit", "integration"] }
+	*/
+	choices?: readonly string[];
+	/**
+	* Custom synchronous per-element parser for each raw argv string.
+	* See {@link StringFlagDef.parse} for full semantics. Runs once per
+	* occurrence; the resolved value is `ReturnType<typeof parse>[]`.
+	*/
+	parse?: (raw: string) => unknown;
 }
 /** A multi-value number flag (collects repeated values into an array) */
 interface NumberMultiFlagDef extends MultiFlagBase {
 	type: "number";
 	/** Default number array value */
 	default?: number[];
+	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
+	parse?: never;
 }
 /** A multi-value boolean flag (collects repeated values into an array) */
 interface BooleanMultiFlagDef extends MultiFlagBase {
@@ -151,6 +339,32 @@ interface BooleanMultiFlagDef extends MultiFlagBase {
 	default?: boolean[];
 	/** When `true`, hide the generated `--no-{name}` help label */
 	noNegate?: true;
+	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
+	parse?: never;
+}
+/** A multi-value URL flag (collects repeated URL values into an array) */
+interface UrlMultiFlagDef extends MultiFlagBase {
+	type: "url";
+	/** Default URL array value */
+	default?: URL[];
+	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
+	parse?: never;
+}
+/** A multi-value path flag (collects repeated path strings into an array) */
+interface PathMultiFlagDef extends MultiFlagBase {
+	type: "path";
+	/** Default path array value */
+	default?: string[];
+	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
+	parse?: never;
+}
+/** A multi-value JSON flag (collects repeated parsed JSON values) */
+interface JsonMultiFlagDef extends MultiFlagBase {
+	type: "json";
+	/** Default parsed JSON array value */
+	default?: unknown[];
+	/** Not supported — use `type: "string"`, `multiple: true`, with `parse`. */
+	parse?: never;
 }
 /**
 * Defines a single named flag for a CLI command.
@@ -167,7 +381,7 @@ interface BooleanMultiFlagDef extends MultiFlagBase {
 * } satisfies FlagsDef;
 * ```
 */
-type FlagDef = StringFlagDef | NumberFlagDef | BooleanFlagDef | StringMultiFlagDef | NumberMultiFlagDef | BooleanMultiFlagDef;
+type FlagDef = StringFlagDef | NumberFlagDef | BooleanFlagDef | UrlFlagDef | PathFlagDef | JsonFlagDef | StringMultiFlagDef | NumberMultiFlagDef | BooleanMultiFlagDef | UrlMultiFlagDef | PathMultiFlagDef | JsonMultiFlagDef;
 /** Record mapping flag names to their definitions */
 type FlagsDef = Record<string, FlagDef>;
 /**
@@ -385,17 +599,30 @@ type EffectiveFlags<
 /**
 * Infer the resolved type for a single ArgDef:
 *
-* - **variadic** → `primitive[]`
+* - **variadic** → `primitive[]` (always an array, never `undefined`,
+*   regardless of `required` or `default`)
 * - **required** or **has default** → `primitive` (non-optional)
 * - otherwise → `primitive | undefined`
+*
+* The variadic branch is checked first and takes precedence. Combining
+* `variadic: true` with `required: true` keeps the inferred type as `T[]`;
+* `required` only gates empty-array validation, not the type.
 */
 type InferArgValue<A extends ArgDef> = A extends {
+	type: infer _T extends ValueType;
+} ? A extends {
 	variadic: true;
-} ? ResolvePrimitive<A["type"]>[] : A extends {
+} ? ResolveBaseType<A>[] : A extends {
 	required: true;
-} ? ResolvePrimitive<A["type"]> : A extends {
-	default: ResolvePrimitive<A["type"]>;
-} ? ResolvePrimitive<A["type"]> : ResolvePrimitive<A["type"]> | undefined;
+} ? ResolveBaseType<A> : A extends {
+	default: unknown;
+} ? ResolveBaseType<A> : ResolveBaseType<A> | undefined : A extends {
+	variadic: true;
+} ? unknown[] : A extends {
+	required: true;
+} | {
+	default: unknown;
+} ? unknown : unknown;
 /**
 * Recursively converts an ArgsDef tuple into a named object type.
 *
@@ -427,16 +654,18 @@ type InferArgs<A> = A extends ArgsDef ? Simplify<InferArgsTuple<A>> : Record<str
 * - otherwise → `primitive | undefined`
 */
 type InferFlagValue<F extends FlagDef> = F extends {
+	type: infer _T extends ValueType;
+} ? F extends {
 	multiple: true;
 } ? F extends {
 	required: true;
-} ? ResolvePrimitive<F["type"]>[] : F extends {
-	default: ResolvePrimitive<F["type"]>[];
-} ? ResolvePrimitive<F["type"]>[] : ResolvePrimitive<F["type"]>[] | undefined : F extends {
+} ? ResolveBaseType<F>[] : F extends {
+	default: readonly unknown[];
+} ? ResolveBaseType<F>[] : ResolveBaseType<F>[] | undefined : F extends {
 	required: true;
-} ? ResolvePrimitive<F["type"]> : F extends {
-	default: ResolvePrimitive<F["type"]>;
-} ? ResolvePrimitive<F["type"]> : ResolvePrimitive<F["type"]> | undefined;
+} ? ResolveBaseType<F> : F extends {
+	default: unknown;
+} ? ResolveBaseType<F> : ResolveBaseType<F> | undefined : never;
 /**
 * Maps a full FlagsDef record to resolved flag types.
 *
@@ -458,6 +687,65 @@ interface CommandMeta {
 	description?: string;
 	/** Custom usage string (overrides auto-generated usage) */
 	usage?: string;
+	/**
+	* Alternative names that resolve to the same command.
+	*
+	* Each entry is a sibling-level alternative for `name`. For example,
+	* `meta: { name: "issue", aliases: ["issues", "i"] }` makes `cli issue`,
+	* `cli issues`, and `cli i` all route to the same command node.
+	*
+	* **Conflict policy.** Alias strings must not collide with this command's
+	* own canonical `name`, with any sibling's `name`, or with any sibling's
+	* own alias. Collisions throw a `CrustError("DEFINITION", …)` at
+	* registration time (or during `validateCommandTree` for plugin-installed
+	* subcommands). Each alias must also be a non-empty string with no
+	* whitespace and must not start with `-`.
+	*
+	* **Display contract.** Help output renders the canonical name with
+	* aliases inline as `name (a, b, c)`. The canonical `name` is what
+	* appears in `commandPath`, error messages, and suggestions from
+	* `didYouMeanPlugin` — it does not depend on which alias the user typed.
+	*
+	* @example
+	* meta: { name: "issue", aliases: ["issues", "i"] }
+	*/
+	aliases?: readonly string[];
+	/**
+	* When `true`, omit this command from every tooling surface that
+	* enumerates the command tree for users:
+	*
+	* - `helpPlugin` rendered output (subcommand list + USAGE token)
+	* - `@crustjs/man` generated man pages (`SUBCOMMANDS` section)
+	* - `completionPlugin` candidate lists (recursively — hidden
+	*   subcommands and their descendants never appear in generated
+	*   bash/zsh/fish scripts)
+	* - `didYouMeanPlugin` typo suggestions and "Available commands"
+	*   list (so internal names never surface in error UX)
+	* - `skillPlugin` manifests
+	*
+	* The command is **only hidden from listings**: routing in
+	* `@crustjs/core` does not consult `meta.hidden`, so it stays fully
+	* invocable by direct name (or alias). The intended use case is
+	* internal/runtime commands like a `__complete` shell-completion
+	* entrypoint. Marking a user-facing command `hidden` is supported but
+	* unusual.
+	*
+	* **Scope: commands only.** There is no analogous `hidden` field on
+	* `FlagDef` or `ArgDef`; flags and positional arguments always surface
+	* in help, completion, and man output. If you need a flag that does
+	* not advertise itself, the workaround is to register it through a
+	* plugin's `setup()` hook without describing it (omit `description`),
+	* which suppresses its description body but still lists the spelling
+	* — there is intentionally no full hide mechanism at the flag layer.
+	*
+	* Tooling contract: any renderer or generator that walks
+	* `subCommands` to produce a user-facing listing should skip nodes
+	* where `meta.hidden === true`.
+	*
+	* @example
+	* meta: { name: "__complete", hidden: true, description: "Internal" }
+	*/
+	hidden?: boolean;
 }
 /**
 * The result of parsing argv against a command's arg/flag definitions.
@@ -587,11 +875,30 @@ interface CrustCommandContext<
 * Build-time validation protocol.
 *
 * `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.
+* `CRUST_INTERNAL_VALIDATE_ONLY=1` (and the companion
+* {@link VALIDATION_FORCE_EXIT_ENV}=`1`). When `.execute()` detects
+* `VALIDATION_MODE_ENV` it runs the validation pipeline and surfaces errors
+* via stderr and `process.exitCode`.
+*
+* Process termination is opt-in via {@link VALIDATION_FORCE_EXIT_ENV} so
+* that in-process callers (tests, embedders) that set only this env get
+* the validation result without having their host process killed.
 */
 declare const VALIDATION_MODE_ENV = "CRUST_INTERNAL_VALIDATE_ONLY";
 /**
+* Companion to {@link VALIDATION_MODE_ENV}. When set to `"1"` _alongside_
+* `VALIDATION_MODE_ENV`, `.execute()` calls `process.exit()` after the
+* validation pipeline completes — ensuring any code that follows
+* `await app.execute()` in the user's entrypoint does not run during
+* `crust build`'s pre-compile validation subprocess.
+*
+* Without this flag, `.execute()` only sets `process.exitCode` and returns,
+* matching the rest of `.execute()`'s error handling. This is the path
+* in-process callers (tests that toggle `VALIDATION_MODE_ENV`, programmatic
+* embedders) take so the host event loop is not terminated.
+*/
+declare const VALIDATION_FORCE_EXIT_ENV = "CRUST_INTERNAL_VALIDATE_FORCE_EXIT";
+/**
 * Chainable builder for defining CLI commands with full type inference.
 *
 * Generic parameters:
@@ -649,14 +956,20 @@ declare class Crust<
 	* Set metadata (description, usage) for this command.
 	*
 	* The command name is already set by the builder source (constructor,
-	* `.sub()`, or the child builder passed into `.command(name, cb)`), so
-	* only `description` and `usage` can be provided here.
+	* `.sub()`, or the child builder passed into `.command(name, cb)`).
+	* Provide `description`, `usage`, and/or `aliases` here.
 	*
 	* Returns a new builder with updated metadata. The original builder
 	* is not mutated.
 	*
-	* @param meta - Metadata fields to set (description, usage)
+	* @param meta - Metadata fields to set (description, usage, aliases)
 	* @returns A new `Crust` instance with updated metadata
+	* @example
+	* ```ts
+	* .command("issue", (cmd) =>
+	*   cmd.meta({ aliases: ["issues", "i"] }).run(() => {})
+	* )
+	* ```
 	*/
 	meta(meta: Omit<CommandMeta, "name">): Crust<Inherited, Local, A, Eff>;
 	/**
@@ -840,6 +1153,7 @@ interface CrustErrorDetailsMap {
 	PARSE: undefined;
 	EXECUTION: undefined;
 	COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
+	CONFIG: undefined;
 }
 /**
 * All possible error codes emitted by Crust.
@@ -848,6 +1162,8 @@ interface CrustErrorDetailsMap {
 * - `VALIDATION` — Missing required arguments or flags
 * - `PARSE` — Argv parsing failures (unknown flags, type coercion)
 * - `EXECUTION` — Runtime command/middleware failures
+* - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
+* - `CONFIG` — Unsupported command/flag definition surfaced at setup time (e.g. async `parse`)
 *
 * @example
 * ```ts
@@ -931,4 +1247,4 @@ declare function parseArgs<
 * @throws {CrustError} On missing required args or flags
 */
 declare function validateParsed(command: CommandNode, parsed: ParseResult): void;
-export { validateParsed, resolveCommand, parseArgs, 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 };
+export { validateParsed, resolveCommand, parseArgs, ValueType, ValidateVariadicArgs, ValidateNoPrefixedFlags, ValidateFlagAliases, ValidateCrossCollisions, VALIDATION_MODE_ENV, VALIDATION_FORCE_EXIT_ENV, SetupContext, SetupActions, ResolveBaseType, Resolve, 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 O,b as G,c as L,d as S}from"./shared/chunk-vt64gs69.js";function T(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 D(j,q){let J=[j.meta.name],Q=j,$=q;while($.length>0){let K=Q.subCommands;if(!K||Object.keys(K).length===0)break;let Z=$[0];if(!Z||Z.startsWith("-"))break;if(Z in K&&K[Z]){Q=K[Z],J.push(Z),$=$.slice(1);continue}if(Q.run)break;let H=Object.keys(K);throw new G("COMMAND_NOT_FOUND",`Unknown command "${Z}".`,{input:Z,available:H,commandPath:[...J],parentCommand:Q})}return{command:Q,argv:$,commandPath:J}}function N(j){for(let[q,J]of Object.entries(j)){if(q.startsWith("no-")){let Q=q.slice(3);throw new G("DEFINITION",`Flag "--${q}" must not use "no-" prefix; define "${Q}" and negate with "--no-${Q}"`)}if(J.short?.startsWith("no-"))throw new G("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 G("DEFINITION",`Alias "--${Q}" on "--${q}" must not use "no-" prefix (reserved for negation)`)}}}var w="CRUST_INTERNAL_VALIDATE_ONLY",P=130,v="__CRUST_VALIDATE_RESULT__";function x(){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 B(j){if(!(j instanceof Error))return!1;return j.name==="CancelledError"}function b(j,q){j.effectiveFlags=z(q,j.localFlags);for(let J of Object.values(j.subCommands))b(J,j.effectiveFlags)}function y(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 G("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}b(Q,q.effectiveFlags),q.subCommands[J]=Q}}}async function A(j,q,J){for(let Q of j){if(!Q.setup)continue;await Q.setup(q,J)}}async function F(j,q,J){let Q=j.map((Z)=>Z.middleware).filter((Z)=>Boolean(Z)),$=-1,K=async(Z)=>{if(Z<=$)throw new G("DEFINITION","Plugin middleware called next() multiple times");if($=Z,Z===Q.length){await J();return}let H=Q[Z];if(!H)throw new G("DEFINITION","Plugin middleware stack is invalid");await H(q,()=>K(Z+1))};await K(0)}function I(j){let q=[...j.plugins];for(let J of Object.values(j.subCommands))q.push(...I(J));return q}function k(j){let q={};for(let[J,Q]of Object.entries(j))q[J]={...Q,aliases:Q.aliases?[...Q.aliases]:void 0};return q}function h(j){let q={};for(let[J,Q]of Object.entries(j.subCommands))q[J]=h(Q);return{meta:{...j.meta},localFlags:k(j.localFlags),effectiveFlags:k(j.effectiveFlags),args:j.args?j.args.map((J)=>({...J})):void 0,subCommands:q,plugins:[...j.plugins],preRun:j.preRun,run:j.run,postRun:j.postRun}}function _(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))_(q);Object.freeze(j.subCommands)}class R{_node;_inheritedFlags;constructor(j){if(!j.trim())throw new G("DEFINITION","meta.name must be a non-empty string");this._node=T(j),this._inheritedFlags={}}static _createChild(j,q){let J=new R(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){N(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 G("DEFINITION","Subcommand name must be a non-empty string");let q=z(this._inheritedFlags,this._node.localFlags);return R._createChild(j,q)}command(j,q){if(typeof j==="string"){let K=j;if(!q)throw new G("DEFINITION","command(name, cb) requires a callback");if(!K.trim())throw new G("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[K])throw new G("DEFINITION",`Subcommand "${K}" is already registered`);let Z=z(this._inheritedFlags,this._node.localFlags),H=R._createChild(K,Z),X=q(H),W={...X._node,effectiveFlags:z(X._inheritedFlags,X._node.localFlags)};return this._clone({subCommands:{...this._node.subCommands,[K]:W}})}let J=j,Q=J._node.meta.name;if(!Q.trim())throw new G("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[Q])throw new G("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 prepareCommandTree(j){let q=j?.argv??[],J=h(this._node),Q=I(J),$=[],K=x(),Z={argv:[...q],rootCommand:J,state:K},H=y($);try{await A(Q,Z,H)}catch(W){if(B(W))throw W;if(W instanceof G)throw W;if(W instanceof Error)throw W;throw new G("DEFINITION",String(W))}_(J);let{validateCommandTree:X}=await import("./shared/chunk-5apf3vnv.js");return X(J),{root:J,warnings:$}}async execute(j){let q=j?.argv??process.argv.slice(2),J=this._node,Q=I(J),$=[],K=x(),Z={argv:[...q],rootCommand:J,state:K},H=y($);try{await A(Q,Z,H)}catch(W){if(B(W)){process.exitCode=P;return}if(W instanceof G){console.error(`Error: ${W.message}`),process.exitCode=1;return}let U=W instanceof Error?W.message:String(W);console.error(`Error: ${U}`),process.exitCode=1;return}if(_(J),process.env[w]==="1"){let W=(async()=>{try{let{validateCommandTree:U}=await import("./shared/chunk-5apf3vnv.js");U(J);for(let Y of $)console.warn(`Warning: ${Y}`);return{ok:!0}}catch(U){let Y=U instanceof Error?U.message:String(U);return console.error(Y),process.exitCode=1,{ok:!1,error:U}}})();return globalThis[v]=W,await W,process.exit(process.exitCode??0)}for(let W of $)console.warn(`Warning: ${W}`);let X={argv:[...q],rootCommand:J,state:K,route:null,input:null};try{let W,U;try{let Y=D(J,[...q]);X.route=Y,W=Y.command,U=L(W,Y.argv),X.input=U}catch(Y){await F(Q,X,async()=>{throw Y});return}await F(Q,X,async()=>{if(S(W,U),!W.run)return;let Y={args:U.args,flags:U.flags,rawArgs:U.rawArgs,command:W},V;try{if(W.preRun)await W.preRun(Y);await W.run(Y)}catch(M){V=M}if(W.postRun)try{await W.postRun(Y)}catch(M){if(!V)V=M;else console.error(`Error in postRun: ${M instanceof Error?M.message:String(M)}`)}if(V)throw V})}catch(W){if(B(W)){process.exitCode=P;return}if(W instanceof G){console.error(`Error: ${W.message}`),process.exitCode=1;return}if(W instanceof Error){let U=new G("EXECUTION",W.message).withCause(W);console.error(`Error: ${U.message}`),process.exitCode=1;return}console.error(`Error: ${String(W)}`),process.exitCode=1}}}export{S as validateParsed,D as resolveCommand,L as parseArgs,w as VALIDATION_MODE_ENV,G as CrustError,R as Crust};
+import{a as O,b as K,c as T,d as I,f as B}from"./shared/chunk-q8y07jw2.js";function P(j){return{meta:{name:j},localFlags:{},effectiveFlags:{},args:void 0,subCommands:{},plugins:[],preRun:void 0,run:void 0,postRun:void 0}}function X(j,J){let q={};for(let[Q,Z]of Object.entries(j))if(Z.inherit===!0)q[Q]=Z;for(let[Q,Z]of Object.entries(J))q[Q]=Z;return q}function E(j,J){for(let[q,Q]of Object.entries(j)){let Z=Q.meta.aliases;if(!Z)continue;if(Z.includes(J))return{canonicalName:q,node:Q}}return null}function D(j,J){let q=[j.meta.name],Q=j,Z=J;while(Z.length>0){let $=Q.subCommands;if(!$||Object.keys($).length===0)break;let G=Z[0];if(!G||G.startsWith("-"))break;if(G in $&&$[G]){Q=$[G],q.push(G),Z=Z.slice(1);continue}let H=E($,G);if(H){Q=H.node,q.push(H.canonicalName),Z=Z.slice(1);continue}if(Q.run)break;throw new K("COMMAND_NOT_FOUND",`Unknown command "${G}".`,{input:G,available:Object.keys($),commandPath:[...q],parentCommand:Q})}return{command:Q,argv:Z,commandPath:q}}function f(j){for(let[J,q]of Object.entries(j)){if(J.startsWith("no-")){let Q=J.slice(3);throw new K("DEFINITION",`Flag "--${J}" must not use "no-" prefix; define "${Q}" and negate with "--no-${Q}"`)}if(q.short?.startsWith("no-"))throw new K("DEFINITION",`Short alias "-${q.short}" on "--${J}" must not use "no-" prefix (reserved for negation)`);if(q.aliases){for(let Q of q.aliases)if(Q.startsWith("no-"))throw new K("DEFINITION",`Alias "--${Q}" on "--${J}" must not use "no-" prefix (reserved for negation)`)}}}var N="CRUST_INTERNAL_VALIDATE_ONLY",b="CRUST_INTERNAL_VALIDATE_FORCE_EXIT",x=130,C="__CRUST_VALIDATE_RESULT__";function k(){let j=new Map;return{get(J){return j.get(J)},has(J){return j.has(J)},set(J,q){j.set(J,q)},delete(J){return j.delete(J)}}}function L(j){if(!(j instanceof Error))return!1;return j.name==="CancelledError"}function h(j,J){j.effectiveFlags=X(J,j.localFlags);for(let q of Object.values(j.subCommands))h(q,j.effectiveFlags)}function y(j){return{addFlag(J,q,Q){if(q in J.effectiveFlags)j?.push(`Plugin flag "--${q}" on "${J.meta.name}" overrides existing flag`);J.effectiveFlags[q]=Q},addSubCommand(J,q,Q){if(!q.trim())throw new K("DEFINITION","addSubCommand: name must be a non-empty string");if(J.subCommands[q]){j?.push(`Plugin subcommand "${q}" on "${J.meta.name}" skipped (already exists)`);return}try{B({canonicalName:q,aliases:Q.meta.aliases},J.subCommands,q)}catch(Z){let $=Z instanceof Error?Z.message:String(Z);j?.push(`Plugin subcommand "${q}" on "${J.meta.name}" skipped: ${$}`);return}h(Q,J.effectiveFlags),J.subCommands[q]=Q}}}async function F(j,J,q){for(let Q of j){if(!Q.setup)continue;await Q.setup(J,q)}}async function A(j,J,q){let Q=j.map((G)=>G.middleware).filter((G)=>Boolean(G)),Z=-1,$=async(G)=>{if(G<=Z)throw new K("DEFINITION","Plugin middleware called next() multiple times");if(Z=G,G===Q.length){await q();return}let H=Q[G];if(!H)throw new K("DEFINITION","Plugin middleware stack is invalid");await H(J,()=>$(G+1))};await $(0)}function S(j){let J=[...j.plugins];for(let q of Object.values(j.subCommands))J.push(...S(q));return J}function w(j){let J={};for(let[q,Q]of Object.entries(j))J[q]={...Q,aliases:Q.aliases?[...Q.aliases]:void 0};return J}function v(j){let J={};for(let[q,Q]of Object.entries(j.subCommands))J[q]=v(Q);return{meta:{...j.meta},localFlags:w(j.localFlags),effectiveFlags:w(j.effectiveFlags),args:j.args?j.args.map((q)=>({...q})):void 0,subCommands:J,plugins:[...j.plugins],preRun:j.preRun,run:j.run,postRun:j.postRun}}function _(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 J of Object.values(j.subCommands))_(J);Object.freeze(j.subCommands)}class M{_node;_inheritedFlags;constructor(j){if(!j.trim())throw new K("DEFINITION","meta.name must be a non-empty string");this._node=P(j),this._inheritedFlags={}}static _createChild(j,J){let q=new M(j);return q._inheritedFlags=J,q}_clone(j){let J=Object.create(Object.getPrototypeOf(this)),q={...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 J._node=q,J._inheritedFlags=this._inheritedFlags,J}meta(j){return this._clone({meta:{...this._node.meta,...j}})}flags(j){f(j);let J={};for(let[q,Q]of Object.entries(j))J[q]={...Q};return this._clone({localFlags:J,effectiveFlags:X(this._inheritedFlags,J)})}args(j){let J=j.map((q)=>({...q}));return this._clone({args:J})}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 K("DEFINITION","Subcommand name must be a non-empty string");let J=X(this._inheritedFlags,this._node.localFlags);return M._createChild(j,J)}command(j,J){if(typeof j==="string"){let $=j;if(!J)throw new K("DEFINITION","command(name, cb) requires a callback");if(!$.trim())throw new K("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[$])throw new K("DEFINITION",`Subcommand "${$}" is already registered`);let G=X(this._inheritedFlags,this._node.localFlags),H=M._createChild($,G),z=J(H);B({canonicalName:$,aliases:z._node.meta.aliases},this._node.subCommands,$);let W={...z._node,effectiveFlags:X(z._inheritedFlags,z._node.localFlags)};return this._clone({subCommands:{...this._node.subCommands,[$]:W}})}let q=j,Q=q._node.meta.name;if(!Q.trim())throw new K("DEFINITION","Subcommand name must be a non-empty string");if(this._node.subCommands[Q])throw new K("DEFINITION",`Subcommand "${Q}" is already registered`);B({canonicalName:Q,aliases:q._node.meta.aliases},this._node.subCommands,Q);let Z={...q._node,effectiveFlags:X(q._inheritedFlags,q._node.localFlags)};return this._clone({subCommands:{...this._node.subCommands,[Q]:Z}})}async prepareCommandTree(j){let J=j?.argv??[],q=v(this._node),Q=S(q),Z=[],$=k(),G={argv:[...J],rootCommand:q,state:$},H=y(Z);try{await F(Q,G,H)}catch(W){if(L(W))throw W;if(W instanceof K)throw W;if(W instanceof Error)throw W;throw new K("DEFINITION",String(W))}_(q);let{validateCommandTree:z}=await import("./shared/chunk-1670njz2.js");return z(q),{root:q,warnings:Z}}async execute(j){let J=j?.argv??process.argv.slice(2),q=this._node,Q=S(q),Z=[],$=k(),G={argv:[...J],rootCommand:q,state:$},H=y(Z);try{await F(Q,G,H)}catch(W){if(L(W)){process.exitCode=x;return}if(W instanceof K){console.error(`Error: ${W.message}`),process.exitCode=1;return}let U=W instanceof Error?W.message:String(W);console.error(`Error: ${U}`),process.exitCode=1;return}if(_(q),process.env[N]==="1"){let W=(async()=>{try{let{validateCommandTree:U}=await import("./shared/chunk-1670njz2.js");U(q);for(let Y of Z)console.warn(`Warning: ${Y}`);return{ok:!0}}catch(U){let Y=U instanceof Error?U.message:String(U);return console.error(Y),process.exitCode=1,{ok:!1,error:U}}})();if(globalThis[C]=W,await W,process.env[b]==="1")return process.exit(process.exitCode??0);return}for(let W of Z)console.warn(`Warning: ${W}`);let z={argv:[...J],rootCommand:q,state:$,route:null,input:null};try{let W,U;try{let Y=D(q,[...J]);z.route=Y,W=Y.command,U=T(W,Y.argv),z.input=U}catch(Y){await A(Q,z,async()=>{throw Y});return}await A(Q,z,async()=>{if(I(W,U),!W.run)return;let Y={args:U.args,flags:U.flags,rawArgs:U.rawArgs,command:W},R;try{if(W.preRun)await W.preRun(Y);await W.run(Y)}catch(V){R=V}if(W.postRun)try{await W.postRun(Y)}catch(V){if(!R)R=V;else console.error(`Error in postRun: ${V instanceof Error?V.message:String(V)}`)}if(R)throw R})}catch(W){if(L(W)){process.exitCode=x;return}if(W instanceof K){console.error(`Error: ${W.message}`),process.exitCode=1;return}if(W instanceof Error){let U=new K("EXECUTION",W.message).withCause(W);console.error(`Error: ${U.message}`),process.exitCode=1;return}console.error(`Error: ${String(W)}`),process.exitCode=1}}}export{I as validateParsed,D as resolveCommand,T as parseArgs,N as VALIDATION_MODE_ENV,b as VALIDATION_FORCE_EXIT_ENV,K as CrustError,M as Crust};

package/dist/shared/chunk-1670njz2.js

@@ -0,0 +1,2 @@
+// @bun
+import{e as a,f as b,g as c}from"./chunk-q8y07jw2.js";export{b as validateIncomingAliases,c as validateCommandTree,a as validateAliasString};

package/dist/shared/chunk-q8y07jw2.js

@@ -0,0 +1,3 @@
+// @bun
+var f=import.meta.require;class Y extends Error{code;details;cause;constructor(H,K,...z){super(K);this.name="CrustError",this.code=H,this.details=z[0]}is(H){return this.code===H}withCause(H){return this.cause=H,this}}import{parseArgs as L}from"util";import{coerceBooleanString as x,tryCoerceNumber as y}from"@crustjs/utils";import{homedir as k}from"os";import{resolve as T}from"path";function R(H){try{return new URL(H)}catch{let z=/^[a-z][a-z0-9+.-]*:/i.test(H)?"":" (missing protocol \u2014 e.g. https://example.com)";throw new Y("PARSE",`Invalid URL "${H}"${z}`)}}function J(H){if(H==="")throw new Y("PARSE","Path cannot be empty");let K=H.replace(/^~(?=\/|$)/,k());return T(process.cwd(),K)}function O(H){try{return JSON.parse(H)}catch(K){let z=K instanceof Error?K.message:String(K);throw new Y("PARSE",`Invalid JSON: ${z}. Tip: wrap JSON in single quotes on the command line, e.g. --flag '{"k":1}'`)}}function w(H){let K={},z={};if(!H)return{options:K,aliasToName:z};let $=new Map;for(let Q of Object.keys(H))$.set(Q,Q);for(let[Q,Z]of Object.entries(H)){if(Q.startsWith("no-")){let X=Q.slice(3);throw new Y("DEFINITION",`Flag "--${Q}" must not use "no-" prefix; define "${X}" and negate with "--no-${X}"`)}if(!E.has(Z.type))throw new Y("DEFINITION",`Flag "--${Q}" must declare a parser type ("string", "number", "boolean", "url", "path", or "json")`);let B=Z.type==="boolean"?"boolean":"string",W={type:B};if(Z.multiple)W.multiple=!0;if(Z.short){if(Z.short.startsWith("no-"))throw new Y("DEFINITION",`Short alias "-${Z.short}" on "--${Q}" must not use "no-" prefix (reserved for negation)`);let X=$.get(Z.short);if(X)throw new Y("DEFINITION",`Alias collision: "-${Z.short}" is used by both "--${X}" and "--${Q}"`);$.set(Z.short,Q),z[Z.short]=Q,W.short=Z.short}if(Z.aliases)for(let X of Z.aliases){if(X.startsWith("no-"))throw new Y("DEFINITION",`Alias "--${X}" on "--${Q}" must not use "no-" prefix (reserved for negation)`);let G=$.get(X);if(G)throw new Y("DEFINITION",`Alias collision: "${X.length===1?"-":"--"}${X}" is used by both "--${G}" and "--${Q}"`);$.set(X,Q),z[X]=Q;let M={type:B};if(Z.multiple)M.multiple=!0;K[X]=M}K[Q]=W}return{options:K,aliasToName:z}}var E=new Set(["string","number","boolean","url","path","json"]);function F(H,K,z){if(K==="number"){let $=y(H);if($===void 0)throw new Y("PARSE",`Expected number for ${z}, got "${H}"`);return $}if(K==="boolean")return x(H);if(K==="url")return R(H);if(K==="path")return J(H);if(K==="json")return O(H);return H}function I(H,K,z){if(!K.includes(H))throw new Y("PARSE",`Invalid value "${H}" for ${z}. Expected one of: ${K.join(", ")}`)}function _(H,K,z,$){try{return H(K)}catch(Q){let Z=$===void 0?z:`${z} element [${$}]`,B=Q instanceof Error?Q.message:String(Q);throw new Y("PARSE",`Failed to parse ${Z}: ${B}`).withCause(Q)}}function P(H,K){let{default:z,choices:$,parse:Q}=H;if(z===void 0)return;if($)if(Array.isArray(z))for(let Z of z)I(String(Z),$,K);else I(String(z),$,K);if(Q){if(Array.isArray(z))return z.map((Z,B)=>_(Q,String(Z),K,B));return _(Q,String(z),K)}if(H.type==="path"){if(Array.isArray(z))return z.map((Z)=>J(String(Z)));return J(String(z))}return z}function N(H,K){if(H)for(let[z,$]of Object.entries(H)){let Q=$.parse;if(Q&&Q.constructor.name==="AsyncFunction")throw new Y("CONFIG",`Async parse not supported for flag --${z}. Use a sync parser; do async work in run().`)}if(K)for(let z of K){let $=z.parse;if($&&$.constructor.name==="AsyncFunction")throw new Y("CONFIG",`Async parse not supported for argument <${z.name}>. Use a sync parser; do async work in run().`)}}function h(H,K,z){let $=`--${H}`,Q=K.choices,Z=K.parse;if(K.multiple&&Array.isArray(z)){if(K.type==="boolean")return z.filter((B)=>typeof B==="boolean");return z.map((B,W)=>{if(Q)I(B,Q,$);if(Z)return _(Z,B,$,W);return F(B,K.type,$)})}if(K.type==="boolean"){if(typeof z==="boolean")return z;throw new Y("PARSE",`Expected boolean value for flag "${$}", got ${typeof z}`)}if(typeof z==="string"){if(Q)I(z,Q,$);if(Z)return _(Z,z,$);return F(z,K.type,$)}throw new Y("PARSE",`Internal: unexpected value shape for flag "${$}" (got ${typeof z})`)}function C(H,K,z){let $={};for(let Q in H){let Z=K[Q]??Q;if(!(Z in z))continue;let B=H[Q],W=$[Z];if(W!==void 0&&Array.isArray(W)&&Array.isArray(B))W.push(...B);else $[Z]=B}return $}function V(H,K,z){if(!H)return{};let $=C(K,z,H),Q={};for(let[Z,B]of Object.entries(H)){let W=$[Z];if(W!==void 0){Q[Z]=h(Z,B,W);continue}Q[Z]=P(B,`--${Z}`)}return Q}function D(H,K){if(!H)return;for(let[z,$]of Object.entries(H))if($.required===!0&&$.default===void 0){if(K[z]===void 0)throw new Y("VALIDATION",`Missing required flag "--${z}"`)}}function b(H,K){if(!H)return{};let z={},$=0;for(let Q of H){let{name:Z}=Q,B=`<${Z}>`,W=Q.choices,X=Q.parse,G=(M,U)=>{if(W)I(M,W,B);if(X)return _(X,M,B,U);return Q.type===void 0?M:F(M,Q.type,B)};if(Q.variadic){let M=K.slice($);z[Z]=M.map((U,q)=>G(U,q)),$=K.length}else if($<K.length)z[Z]=G(K[$]),$++;else z[Z]=P(Q,B)}return z}function v(H,K,z){if(!K)return;for(let $ of H){if($==="--")return;if(!$.startsWith("--no-"))continue;let Q=$.indexOf("="),Z=Q===-1?$.slice(5):$.slice(5,Q);if(!Z)continue;let B=z[Z];if(!B)continue;if(B===Z)continue;if(K[B]?.type!=="boolean")continue;throw new Y("PARSE",`Cannot negate alias "--no-${Z}"; use "--no-${B}" instead`)}}function S(H,K){let{args:z,effectiveFlags:$}=H;N($,z);let{options:Q,aliasToName:Z}=w($);v(K,$,Z);let B;try{B=L({args:K,options:Q,strict:!0,allowPositionals:!0,allowNegative:!0,tokens:!0})}catch(U){if(U instanceof Error){let q=U.message.match(/Unknown option '(.+?)'/);if(q)throw new Y("PARSE",`Unknown flag "${q[1]}"`).withCause(U)}throw new Y("PARSE","Failed to parse command arguments").withCause(U)}let W=[],X=[];if(B.tokens){let U=!1;for(let q of B.tokens){if(q.kind==="option-terminator"){U=!0;continue}if(q.kind==="positional")(U?W:X).push(q.value??"")}}else X.push(...B.positionals);let G=V($,B.values,Z);return{args:b(z,X),flags:G,rawArgs:W}}function A(H,K){let{args:z,effectiveFlags:$}=H,Q=K.args,Z=K.flags;if(z)for(let B of z){let{name:W}=B,X=`argument "<${W}>"`,G=Q[W];if(B.required===!0&&B.default===void 0){if(B.variadic){if(!Array.isArray(G)||G.length===0)throw new Y("VALIDATION",`Missing required ${X}`)}else if(G===void 0)throw new Y("VALIDATION",`Missing required ${X}`)}}D($,Z)}function p(H,K,z){if(typeof H!=="string"||H.length===0)throw new Y("DEFINITION",`Subcommand "${z}" has an invalid alias: must be a non-empty string`);if(/\s/.test(H))throw new Y("DEFINITION",`Subcommand "${z}" alias "${H}" must not contain whitespace`);if(H.startsWith("-"))throw new Y("DEFINITION",`Subcommand "${z}" alias "${H}" must not start with "-" (reserved for flags)`);if(H===K)throw new Y("DEFINITION",`Subcommand "${z}" alias "${H}" must not equal its own canonical name`)}function g(H,K,z){let{canonicalName:$,aliases:Q}=H;if(Q){let Z=new Set;for(let B of Q){if(p(B,$,z),Z.has(B))throw new Y("DEFINITION",`Subcommand "${z}" lists alias "${B}" more than once`);Z.add(B)}}for(let[Z,B]of Object.entries(K)){let W=B.meta.aliases;if(W?.includes($))throw new Y("DEFINITION",`Subcommand "${z}" canonical name "${$}" collides with alias of sibling "${Z}"`);if(!Q)continue;for(let X of Q){if(X===Z)throw new Y("DEFINITION",`Subcommand "${z}" alias "${X}" collides with sibling canonical name "${Z}"`);if(W?.includes(X))throw new Y("DEFINITION",`Subcommand "${z}" alias "${X}" collides with alias of sibling "${Z}"`)}}}function j(H){let K=H.choices;if(K!==void 0&&K.length>0)return K[0];switch(H.type){case"number":return"1";case"boolean":return"true";case"url":return"https://example.com";case"json":return"null";default:return"sample"}}function m(H){let K=[],z=H.effectiveFlags;for(let[Q,Z]of Object.entries(z)){if(Z.required!==!0||Z.default!==void 0)continue;if(K.push(`--${Q}`),Z.type!=="boolean")K.push(j(Z))}let $=H.args;if($)for(let Q of $){if(Q.required!==!0||Q.default!==void 0)continue;K.push(j(Q))}return K}function Hz(H){let K=[{command:H,path:[H.meta.name]}],z=new Set;while(K.length>0){let $=K.pop();if(!$)break;let{command:Q,path:Z}=$;if(z.has(Q))continue;z.add(Q);try{let W=S(Q,m(Q));A(Q,W)}catch(W){let X=W instanceof Error?W.message:"Unknown validation error";throw new Y("DEFINITION",`Command "${Z.join(" ")}" failed runtime validation: ${X}`).withCause(W)}let B={};for(let[W,X]of Object.entries(Q.subCommands))g({canonicalName:W,aliases:X.meta.aliases},B,[...Z,W].join(" ")),B[W]=X;for(let[W,X]of Object.entries(Q.subCommands))K.push({command:X,path:[...Z,W]})}}
+export{f as a,Y as b,S as c,A as d,p as e,g as f,Hz as g};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/core",
-	"version": "0.0.16",
+	"version": "0.0.18",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",
@@ -41,11 +41,14 @@
 		"test": "bun test",
 		"publish": "bun publish --no-git-checks || true"
 	},
+	"dependencies": {
+		"@crustjs/utils": "0.0.2"
+	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
 		"bunup": "^0.16.31"
 	},
 	"peerDependencies": {
-		"typescript": "^6.0.2"
+		"typescript": "^6.0.3"
 	}
 }

package/dist/shared/chunk-5apf3vnv.js

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

package/dist/shared/chunk-vt64gs69.js

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