@crustjs/core 0.0.17 → 0.0.19

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
 
@@ -16,19 +16,41 @@ bun add @crustjs/core
 import { Crust } from "@crustjs/core";
 
 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 }) => {
-    const msg = `Hello, ${args.name}!`;
-    console.log(flags.loud ? msg.toUpperCase() : msg);
-  });
+	.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 }) => {
+		const msg = `Hello, ${args.name}!`;
+		console.log(flags.loud ? msg.toUpperCase() : msg);
+	});
 
 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

@@ -41,16 +41,39 @@ 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";
 /**
-* Resolves a type literal to its corresponding TypeScript primitive type.
+* Supported type literals for args and flags.
 *
-* - `"string"` → `string`
-* - `"number"` → `number`
-* - `"boolean"` → `boolean`
+* 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 ResolvePrimitive<T extends ValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+type ValueType = BaseValueType | "url" | "path" | "json";
+/**
+* Resolve a {@link ValueType} literal to its runtime TypeScript type.
+*
+* Delegates to `ResolvePrimitive<T>` for the three base types; maps the
+* three formatted types (`"url"`, `"path"`, `"json"`) to `URL`, `string`,
+* and `unknown` respectively.
+*/
+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) */
@@ -82,13 +105,10 @@ interface StringArgDef extends ArgDefBase {
 	/**
 	* Static enum of valid values for this argument.
 	*
-	* `choices` is a **hint for tooling** — it is consumed by shell-completion
-	* plugins (e.g. `@crustjs/plugins/completion`) to emit value candidates
-	* and may be consumed by future opt-in validation. It is **NOT** enforced
-	* at parse time in this version: passing a value outside `choices` does
-	* not throw, the value is still parsed as a string and delivered to your
-	* `run` handler. Validate explicitly inside your handler if you need
-	* runtime rejection today.
+	* 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.
 	*
@@ -96,18 +116,54 @@ interface StringArgDef extends ArgDefBase {
 	* { 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.
@@ -124,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 */
@@ -153,13 +218,10 @@ interface StringFlagDef extends SingleFlagBase {
 	/**
 	* Static enum of valid values for this flag.
 	*
-	* `choices` is a **hint for tooling** — it is consumed by shell-completion
-	* plugins (e.g. `@crustjs/plugins/completion`) to emit value candidates
-	* and may be consumed by future opt-in validation. It is **NOT** enforced
-	* at parse time in this version: passing a value outside `choices` does
-	* not throw, the value is still parsed as a string and delivered to your
-	* `run` handler. Validate explicitly inside your handler if you need
-	* runtime rejection today.
+	* 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.
 	*
@@ -167,12 +229,35 @@ interface StringFlagDef extends SingleFlagBase {
 	* { 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 {
@@ -181,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 {
@@ -195,13 +306,10 @@ interface StringMultiFlagDef extends MultiFlagBase {
 	/**
 	* Static enum of valid values for each occurrence of this flag.
 	*
-	* `choices` is a **hint for tooling** — it is consumed by shell-completion
-	* plugins (e.g. `@crustjs/plugins/completion`) to emit value candidates
-	* and may be consumed by future opt-in validation. It is **NOT** enforced
-	* at parse time in this version: passing a value outside `choices` does
-	* not throw, the value is still parsed as a string and collected into the
-	* array. Validate explicitly inside your handler if you need runtime
-	* rejection today.
+	* 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.
 	*
@@ -209,12 +317,20 @@ interface StringMultiFlagDef extends MultiFlagBase {
 	* { 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 {
@@ -223,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.
@@ -239,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>;
 /**
@@ -467,12 +609,20 @@ type EffectiveFlags<
 * `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;
+} ? ResolveBaseType<A>[] : A extends {
+	required: true;
+} ? ResolveBaseType<A> : A extends {
+	default: unknown;
+} ? ResolveBaseType<A> : ResolveBaseType<A> | undefined : A extends {
 	variadic: true;
-} ? ResolvePrimitive<A["type"]>[] : A extends {
+} ? unknown[] : A extends {
 	required: true;
-} ? ResolvePrimitive<A["type"]> : A extends {
-	default: ResolvePrimitive<A["type"]>;
-} ? ResolvePrimitive<A["type"]> : ResolvePrimitive<A["type"]> | undefined;
+} | {
+	default: unknown;
+} ? unknown : unknown;
 /**
 * Recursively converts an ArgsDef tuple into a named object type.
 *
@@ -504,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.
 *
@@ -1001,6 +1153,7 @@ interface CrustErrorDetailsMap {
 	PARSE: undefined;
 	EXECUTION: undefined;
 	COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
+	CONFIG: undefined;
 }
 /**
 * All possible error codes emitted by Crust.
@@ -1009,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
@@ -1092,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, VALIDATION_FORCE_EXIT_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 K,c as T,d as I,f as B}from"./shared/chunk-w6ydwhzx.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-w4s4rg66.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-w4s4rg66.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};
+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-w4s4rg66.js → chunk-1670njz2.js}

@@ -1,2 +1,2 @@
 // @bun
-import{e as a,f as b,g as c}from"./chunk-w6ydwhzx.js";export{b as validateIncomingAliases,c as validateCommandTree,a as validateAliasString};
+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.17",
+	"version": "0.0.19",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",
@@ -41,6 +41,9 @@
 		"test": "bun test",
 		"publish": "bun publish --no-git-checks || true"
 	},
+	"dependencies": {
+		"@crustjs/utils": "0.0.3"
+	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
 		"bunup": "^0.16.31"

package/dist/shared/chunk-w6ydwhzx.js

@@ -1,3 +0,0 @@
-// @bun
-var j=import.meta.require;class Y extends Error{code;details;cause;constructor(B,J,...H){super(J);this.name="CrustError",this.code=B,this.details=H[0]}is(B){return this.code===B}withCause(B){return this.cause=B,this}}import{parseArgs as F}from"util";function P(B){let J={},H={};if(!B)return{options:J,aliasToName:H};let K=new Map;for(let z of Object.keys(B))K.set(z,z);for(let[z,G]of Object.entries(B)){if(z.startsWith("no-")){let X=z.slice(3);throw new Y("DEFINITION",`Flag "--${z}" must not use "no-" prefix; define "${X}" and negate with "--no-${X}"`)}let Q=G.type==="boolean"?"boolean":"string",W={type:Q};if(G.multiple)W.multiple=!0;if(G.short){if(G.short.startsWith("no-"))throw new Y("DEFINITION",`Short alias "-${G.short}" on "--${z}" must not use "no-" prefix (reserved for negation)`);let X=K.get(G.short);if(X)throw new Y("DEFINITION",`Alias collision: "-${G.short}" is used by both "--${X}" and "--${z}"`);K.set(G.short,z),H[G.short]=z,W.short=G.short}if(G.aliases)for(let X of G.aliases){if(X.startsWith("no-"))throw new Y("DEFINITION",`Alias "--${X}" on "--${z}" must not use "no-" prefix (reserved for negation)`);let Z=K.get(X);if(Z)throw new Y("DEFINITION",`Alias collision: "${X.length===1?"-":"--"}${X}" is used by both "--${Z}" and "--${z}"`);K.set(X,z),H[X]=z;let q={type:Q};if(G.multiple)q.multiple=!0;J[X]=q}J[z]=W}return{options:J,aliasToName:H}}function U(B,J,H){if(J==="number"){let K=Number(B);if(Number.isNaN(K))throw new Y("PARSE",`Expected number for ${H}, got "${B}"`);return K}if(J==="boolean")return B==="true"||B==="1";return B}function S(B,J,H){let K=`--${B}`;if(J.multiple&&Array.isArray(H))return J.type==="boolean"?H.filter((z)=>typeof z==="boolean"):H.map((z)=>U(z,J.type,K));if(J.type==="boolean"){if(typeof H==="boolean")return H;throw new Y("PARSE",`Expected boolean value for flag "${K}", got ${typeof H}`)}if(typeof H==="string")return U(H,J.type,K);if(H===!0)return J.default??void 0;return H}function h(B,J,H){let K={};for(let z in B){let G=J[z]??z;if(!(G in H))continue;let Q=B[z],W=K[G];if(W!==void 0&&Array.isArray(W)&&Array.isArray(Q))W.push(...Q);else K[G]=Q}return K}function R(B,J,H){if(!B)return{};let K=h(J,H,B),z={};for(let[G,Q]of Object.entries(B)){let W=K[G];if(W!==void 0){z[G]=S(G,Q,W);continue}z[G]=Q.default??void 0}return z}function w(B,J){if(!B)return;for(let[H,K]of Object.entries(B))if(K.required===!0&&K.default===void 0){if(J[H]===void 0)throw new Y("VALIDATION",`Missing required flag "--${H}"`)}}function A(B,J){if(!B)return{};let H={},K=0;for(let z of B){let{name:G}=z;if(z.variadic){let Q=J.slice(K);H[G]=z.type==="string"?Q:Q.map((W)=>U(W,z.type,`<${G}>`)),K=J.length}else if(K<J.length)H[G]=U(J[K],z.type,`<${G}>`),K++;else H[G]=z.default??void 0}return H}function k(B,J,H){if(!J)return;for(let K of B){if(K==="--")return;if(!K.startsWith("--no-"))continue;let z=K.indexOf("="),G=z===-1?K.slice(5):K.slice(5,z);if(!G)continue;let Q=H[G];if(!Q)continue;if(Q===G)continue;if(J[Q]?.type!=="boolean")continue;throw new Y("PARSE",`Cannot negate alias "--no-${G}"; use "--no-${Q}" instead`)}}function M(B,J){let{args:H,effectiveFlags:K}=B,{options:z,aliasToName:G}=P(K);k(J,K,G);let Q;try{Q=F({args:J,options:z,strict:!0,allowPositionals:!0,allowNegative:!0,tokens:!0})}catch(_){if(_ instanceof Error){let $=_.message.match(/Unknown option '(.+?)'/);if($)throw new Y("PARSE",`Unknown flag "${$[1]}"`).withCause(_)}throw new Y("PARSE","Failed to parse command arguments").withCause(_)}let W=[],X=[];if(Q.tokens){let _=!1;for(let $ of Q.tokens){if($.kind==="option-terminator"){_=!0;continue}if($.kind==="positional")(_?W:X).push($.value??"")}}else X.push(...Q.positionals);let Z=R(K,Q.values,G);return{args:A(H,X),flags:Z,rawArgs:W}}function I(B,J){let{args:H,effectiveFlags:K}=B,z=J.args,G=J.flags;if(H)for(let Q of H){let{name:W}=Q,X=`argument "<${W}>"`,Z=z[W];if(Q.required===!0&&Q.default===void 0){if(Q.variadic){if(!Array.isArray(Z)||Z.length===0)throw new Y("VALIDATION",`Missing required ${X}`)}else if(Z===void 0)throw new Y("VALIDATION",`Missing required ${X}`)}}w(K,G)}function y(B,J,H){if(typeof B!=="string"||B.length===0)throw new Y("DEFINITION",`Subcommand "${H}" has an invalid alias: must be a non-empty string`);if(/\s/.test(B))throw new Y("DEFINITION",`Subcommand "${H}" alias "${B}" must not contain whitespace`);if(B.startsWith("-"))throw new Y("DEFINITION",`Subcommand "${H}" alias "${B}" must not start with "-" (reserved for flags)`);if(B===J)throw new Y("DEFINITION",`Subcommand "${H}" alias "${B}" must not equal its own canonical name`)}function x(B,J,H){let{canonicalName:K,aliases:z}=B;if(z){let G=new Set;for(let Q of z){if(y(Q,K,H),G.has(Q))throw new Y("DEFINITION",`Subcommand "${H}" lists alias "${Q}" more than once`);G.add(Q)}}for(let[G,Q]of Object.entries(J)){let W=Q.meta.aliases;if(W?.includes(K))throw new Y("DEFINITION",`Subcommand "${H}" canonical name "${K}" collides with alias of sibling "${G}"`);if(!z)continue;for(let X of z){if(X===G)throw new Y("DEFINITION",`Subcommand "${H}" alias "${X}" collides with sibling canonical name "${G}"`);if(W?.includes(X))throw new Y("DEFINITION",`Subcommand "${H}" alias "${X}" collides with alias of sibling "${G}"`)}}}function O(B){switch(B.type){case"number":return"1";case"boolean":return"true";default:return"sample"}}function T(B){let J=[],H=B.effectiveFlags;for(let[z,G]of Object.entries(H)){if(G.required!==!0||G.default!==void 0)continue;if(J.push(`--${z}`),G.type!=="boolean")J.push(O(G))}let K=B.args;if(K)for(let z of K){if(z.required!==!0||z.default!==void 0)continue;J.push(O(z))}return J}function b(B){let J=[{command:B,path:[B.meta.name]}],H=new Set;while(J.length>0){let K=J.pop();if(!K)break;let{command:z,path:G}=K;if(H.has(z))continue;H.add(z);try{let W=M(z,T(z));I(z,W)}catch(W){let X=W instanceof Error?W.message:"Unknown validation error";throw new Y("DEFINITION",`Command "${G.join(" ")}" failed runtime validation: ${X}`).withCause(W)}let Q={};for(let[W,X]of Object.entries(z.subCommands))x({canonicalName:W,aliases:X.meta.aliases},Q,[...G,W].join(" ")),Q[W]=X;for(let[W,X]of Object.entries(z.subCommands))J.push({command:X,path:[...G,W]})}}
-export{j as a,Y as b,M as c,I as d,y as e,x as f,b as g};