@crustjs/core 0.0.2

package/README.md

@@ -0,0 +1,39 @@
+# @crustjs/core
+
+The core library for the [Crust](https://crust.cyanlabs.co) CLI framework.
+
+Provides command definition, argument/flag parsing, subcommand routing, lifecycle hooks, and a plugin system — with **zero runtime dependencies**.
+
+## Install
+
+```sh
+bun add @crustjs/core
+```
+
+## Quick Example
+
+```ts
+import { defineCommand, runMain } from "@crustjs/core";
+
+const main = defineCommand({
+  meta: { name: "greet", description: "Say hello" },
+  args: [{ name: "name", type: String, default: "world" }],
+  flags: {
+    loud: { type: Boolean, description: "Shout it", alias: "l" },
+  },
+  run({ args, flags }) {
+    const msg = `Hello, ${args.name}!`;
+    console.log(flags.loud ? msg.toUpperCase() : msg);
+  },
+});
+
+runMain(main);
+```
+
+## Documentation
+
+See the full docs at [crust.cyanlabs.co](https://crust.cyanlabs.co).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,460 @@
+/** Maps a constructor function (String, Number, Boolean) to its primitive type */
+type TypeConstructor = StringConstructor | NumberConstructor | BooleanConstructor;
+/**
+* Resolves a constructor function to its corresponding TypeScript primitive type.
+*
+* - `StringConstructor` → `string`
+* - `NumberConstructor` → `number`
+* - `BooleanConstructor` → `boolean`
+*/
+type ResolvePrimitive<T extends TypeConstructor> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : never;
+/**
+* Defines a single positional argument for a CLI command.
+*
+* Args are defined as an ordered tuple so that positional ordering is explicit
+* and the type system can enforce that only the last arg may be variadic.
+*
+* @example
+* ```ts
+* const args = [
+*   { name: "port", type: Number, description: "Port number", default: 3000 },
+*   { name: "name", type: String, required: true },
+*   { name: "files", type: String, variadic: true },
+* ] as const satisfies ArgsDef;
+* ```
+*/
+interface ArgDef<
+	N extends string = string,
+	T extends TypeConstructor = TypeConstructor,
+	D extends ResolvePrimitive<T> | undefined = ResolvePrimitive<T> | undefined,
+	R extends boolean = boolean,
+	V extends boolean = boolean
+> {
+	/** The argument name (used as the key in the parsed result and in help text) */
+	name: N;
+	/** Constructor function indicating the argument's type: `String`, `Number`, or `Boolean` */
+	type: T;
+	/** Human-readable description for help text */
+	description?: string;
+	/** Default value when the argument is not provided */
+	default?: D;
+	/** Whether this argument must be provided (errors if missing) */
+	required?: R;
+	/** Whether this argument collects all remaining positionals into an array */
+	variadic?: V;
+}
+/** Ordered tuple of positional argument definitions */
+type ArgsDef = readonly ArgDef[];
+/**
+* Defines a single named flag for a CLI command.
+*
+* @example
+* ```ts
+* const flags = {
+*   verbose: { type: Boolean, description: "Enable verbose logging", alias: "v" },
+*   port: { type: Number, description: "Port number", default: 3000 },
+* } satisfies FlagsDef;
+* ```
+*/
+interface FlagDef<
+	T extends TypeConstructor = TypeConstructor,
+	R extends boolean = boolean,
+	M extends boolean = boolean
+> {
+	/** Constructor function indicating the flag's type: `String`, `Number`, or `Boolean` */
+	type: T;
+	/** Human-readable description for help text */
+	description?: string;
+	/** Default value when the flag is not provided. Must be an array when `multiple: true`. */
+	default?: M extends true ? ResolvePrimitive<T>[] : ResolvePrimitive<T>;
+	/** Whether this flag must be provided (errors if missing) */
+	required?: R;
+	/** Short alias or array of aliases (e.g. `"v"` or `["v", "V"]`) */
+	alias?: string | string[];
+	/** Whether this flag can be provided multiple times, collecting values into an array */
+	multiple?: M;
+}
+/** Record mapping flag names to their definitions */
+type FlagsDef = Record<string, FlagDef>;
+/** Extract alias string literals from a single FlagDef */
+type ExtractAliases<F extends FlagDef> = F extends {
+	alias: infer A;
+} ? A extends string ? A : A extends readonly string[] ? A[number] : never : never;
+/**
+* Collects all alias literals across a FlagsDef, then intersects with `keyof F`.
+* Resolves to `never` when no alias matches a flag name, or the colliding
+* name(s) when a match exists.
+*/
+type FlagAliasNameCollision<F extends FlagsDef> = { [K in keyof F & string] : ExtractAliases<F[K]> }[keyof F & string] & keyof F;
+/**
+* Collects aliases from every flag *except* flag K.
+* Used to detect alias→alias duplicates across different flags.
+*/
+type AliasesExcluding<
+	F extends FlagsDef,
+	K extends keyof F & string
+> = { [J in Exclude<keyof F & string, K>] : ExtractAliases<F[J]> }[Exclude<keyof F & string, K>];
+/**
+* Resolves to the alias literal(s) that appear in more than one flag's
+* alias list, or `never` when no duplicate aliases exist.
+*/
+type FlagAliasAliasCollision<F extends FlagsDef> = { [K in keyof F & string] : ExtractAliases<F[K]> & AliasesExcluding<F, K> }[keyof F & string];
+/**
+* Compile-time check that no flag alias collides with another flag's name
+* or another flag's alias.
+*
+* - Resolves to `unknown` (no-op intersection) when no collision exists.
+* - Resolves to a descriptive error tuple when a collision is found,
+*   causing a type error on the `flags` property.
+*/
+type CheckFlagAliasCollisions<F extends FlagsDef> = FlagAliasNameCollision<F> extends never ? FlagAliasAliasCollision<F> extends never ? unknown : ["ERROR: Duplicate flag alias across different flags. Colliding alias(es):", FlagAliasAliasCollision<F>] : ["ERROR: Flag alias collides with a flag name. Colliding name(s):", FlagAliasNameCollision<F>];
+/**
+* Checks whether any element in `Init` (all elements except the last) has
+* `variadic: true`. Used by {@link CheckVariadicArgs} to ensure only the
+* last positional arg can be variadic.
+*/
+type InitHasVariadic<T extends readonly ArgDef[]> = T extends readonly [infer Head, ...infer Tail extends readonly ArgDef[]] ? Head extends {
+	variadic: true;
+} ? true : InitHasVariadic<Tail> : false;
+/**
+* Compile-time check that only the last positional arg has `variadic: true`.
+*
+* Since args are now an ordered tuple, we can split it into `[...Init, Last]`
+* and verify that no element in `Init` is variadic.
+*
+* - Resolves to `unknown` (no-op intersection) when the constraint is satisfied.
+* - Resolves to a descriptive error string when a non-last arg is variadic,
+*   causing a type error on the `args` property.
+*/
+type CheckVariadicArgs<A extends ArgsDef> = A extends readonly [...infer Init extends readonly ArgDef[], ArgDef] ? InitHasVariadic<Init> extends true ? "ERROR: Only the last positional argument can be variadic" : unknown : unknown;
+/**
+* Infer the resolved type for a single ArgDef:
+*
+* - **variadic** → `primitive[]`
+* - **required** or **has default** → `primitive` (non-optional)
+* - otherwise → `primitive | undefined`
+*/
+type InferArgValue<A extends ArgDef> = A extends {
+	variadic: true;
+} ? ResolvePrimitive<A["type"]>[] : A extends {
+	required: true;
+} ? ResolvePrimitive<A["type"]> : A extends {
+	default: ResolvePrimitive<A["type"]>;
+} ? ResolvePrimitive<A["type"]> : ResolvePrimitive<A["type"]> | undefined;
+/**
+* Recursively converts an ArgsDef tuple into a named object type.
+*
+* Each element's `name` literal becomes a key, and its value is resolved
+* via {@link InferArgValue}. Uses intersection + `Simplify` to flatten.
+*/
+type InferArgsTuple<A extends readonly ArgDef[]> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? { [K in Head["name"]] : InferArgValue<Head> } & InferArgsTuple<Tail> : {};
+/** Flattens an intersection of objects into a single object type for readability */
+type Simplify<T> = { [K in keyof T] : T[K] };
+/**
+* Maps an ArgsDef tuple to resolved arg types keyed by each arg's `name`.
+*
+* @example
+* ```ts
+* type Result = InferArgs<readonly [
+*   { name: "port"; type: NumberConstructor; default: 3000 },
+*   { name: "name"; type: StringConstructor; required: true },
+*   { name: "files"; type: StringConstructor; variadic: true },
+* ]>;
+* // Result = { port: number; name: string; files: string[] }
+* ```
+*/
+type InferArgs<A> = A extends ArgsDef ? Simplify<InferArgsTuple<A>> : Record<string, never>;
+/**
+* Infer the resolved type for a single FlagDef:
+*
+* - **multiple** → wraps the resolved type in an array
+* - **required** or **has default** → `primitive` (non-optional)
+* - otherwise → `primitive | undefined`
+*/
+type InferFlagValue<F extends FlagDef> = 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 {
+	required: true;
+} ? ResolvePrimitive<F["type"]> : F extends {
+	default: ResolvePrimitive<F["type"]>;
+} ? ResolvePrimitive<F["type"]> : ResolvePrimitive<F["type"]> | undefined;
+/**
+* Maps a full FlagsDef record to resolved flag types.
+*
+* @example
+* ```ts
+* type Result = InferFlags<{
+*   verbose: { type: BooleanConstructor };
+*   port: { type: NumberConstructor, default: 3000 };
+* }>;
+* // Result = { verbose: boolean | undefined; port: number }
+* ```
+*/
+type InferFlags<F> = F extends FlagsDef ? { [K in keyof F] : InferFlagValue<F[K]> } : Record<string, never>;
+/** Metadata describing a CLI command */
+interface CommandMeta {
+	/** The command name (used in help text and routing) */
+	name: string;
+	/** Human-readable description for help text */
+	description?: string;
+	/** Custom usage string (overrides auto-generated usage) */
+	usage?: string;
+}
+/**
+* The result of parsing argv against a command's arg/flag definitions.
+*
+* Generic parameters flow from the command definition to provide
+* strongly-typed `args` and `flags` objects.
+*/
+interface ParseResult<
+	A extends ArgsDef = ArgsDef,
+	F extends FlagsDef = FlagsDef
+> {
+	/** Resolved positional arguments, keyed by arg name */
+	args: InferArgs<A>;
+	/** Resolved flags, keyed by flag name */
+	flags: InferFlags<F>;
+	/** Raw arguments that appeared after the `--` separator */
+	rawArgs: string[];
+}
+/**
+* The runtime context object passed to `preRun()`, `run()`, and `postRun()` hooks.
+*
+* Extends {@link ParseResult} with a back-reference to the resolved command.
+*/
+interface CommandContext<
+	A extends ArgsDef = ArgsDef,
+	F extends FlagsDef = FlagsDef
+> extends ParseResult<A, F> {
+	/** The resolved command that is being executed */
+	command: AnyCommand;
+}
+/** Unified command shape used for both command definitions and resolved commands. */
+interface Command<
+	A extends ArgsDef = ArgsDef,
+	F extends FlagsDef = FlagsDef
+> {
+	/** Command metadata (name, description, usage) */
+	readonly meta: CommandMeta;
+	/** Positional argument definitions */
+	readonly args?: A;
+	/** Flag definitions */
+	readonly flags?: F;
+	/** Named subcommands */
+	readonly subCommands?: Record<string, AnyCommand>;
+	/** Called before `run()` — useful for initialization */
+	preRun?(context: CommandContext<A, F>): void | Promise<void>;
+	/** The main command handler */
+	run?(context: CommandContext<A, F>): void | Promise<void>;
+	/** Called after `run()` (even if it throws) — useful for teardown */
+	postRun?(context: CommandContext<A, F>): void | Promise<void>;
+}
+type AnyCommand = Command<any, any>;
+/**
+* Define a CLI command with full type inference.
+*
+* The returned command object is frozen (immutable) and typed so that
+* `run()`, `preRun()`, and `postRun()` callbacks receive correctly-typed
+* `args` and `flags` based on the definitions provided.
+*
+* @param config - The command definition config object
+* @returns A frozen, readonly Command object
+* @throws {CrustError} `DEFINITION` if `meta.name` is missing or empty
+*
+* @example
+* ```ts
+* const cmd = defineCommand({
+*   meta: { name: "serve", description: "Start dev server" },
+*   args: [
+*     { name: "port", type: Number, description: "Port number", default: 3000 },
+*   ],
+*   flags: {
+*     verbose: { type: Boolean, description: "Enable verbose logging", alias: "v" },
+*   },
+*   run({ args, flags }) {
+*     // args.port is typed as number, flags.verbose is typed as boolean | undefined
+*     console.log(`Starting server on port ${args.port}`);
+*   },
+* });
+* ```
+*/
+declare function defineCommand<
+	const A extends ArgsDef = ArgsDef,
+	const F extends FlagsDef = FlagsDef
+>(config: Command<A, F> & {
+	args?: A & CheckVariadicArgs<A>;
+	flags?: F & CheckFlagAliasCollisions<F>;
+}): Command<A, F>;
+interface CommandNotFoundErrorDetails {
+	input: string;
+	available: string[];
+	commandPath: string[];
+	parentCommand: AnyCommand;
+}
+interface CrustErrorDetailsMap {
+	DEFINITION: undefined;
+	VALIDATION: undefined;
+	PARSE: undefined;
+	EXECUTION: undefined;
+	COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
+}
+/**
+* All possible error codes emitted by Crust.
+*
+* - `DEFINITION` — Invalid command configuration (empty name, alias collision, bad variadic position)
+* - `VALIDATION` — Missing required arguments or flags
+* - `PARSE` — Argv parsing failures (unknown flags, type coercion)
+* - `EXECUTION` — Runtime command/middleware failures
+*
+* @example
+* ```ts
+* try {
+*   parseArgs(cmd, argv);
+* } catch (err) {
+*   if (err instanceof CrustError) {
+*     switch (err.code) {
+*       case "VALIDATION":
+*         console.error(err.message);
+*         showHelp(cmd);
+*         break;
+*       case "PARSE":
+*         console.error(err.message);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+type CrustErrorCode = keyof CrustErrorDetailsMap;
+type CrustErrorDetails<C extends CrustErrorCode> = CrustErrorDetailsMap[C];
+/**
+* A typed error thrown by Crust when command definition or argument parsing fails.
+*
+* Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
+* failure, enabling programmatic error handling without fragile message parsing.
+*
+* @example
+* ```ts
+* import { CrustError, parseArgs } from "@crustjs/core";
+*
+* try {
+*   const result = parseArgs(cmd, process.argv.slice(2));
+* } catch (err) {
+*   if (err instanceof CrustError) {
+*     console.error(`[${err.code}] ${err.message}`);
+*   }
+* }
+* ```
+*/
+declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Error {
+	/** Machine-readable error code for programmatic handling */
+	readonly code: C;
+	/** Structured payload for programmatic handling */
+	readonly details: CrustErrorDetails<C>;
+	/** Optional wrapped original error/value */
+	cause?: unknown;
+	constructor(code: C, message: string, ...details: CrustErrorDetails<C> extends undefined ? [] | [undefined] : [CrustErrorDetails<C>]);
+	is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
+	withCause(cause: unknown): this;
+}
+/**
+* Parse argv against a command's arg/flag definitions.
+*
+* Wraps Node's `util.parseArgs` with Crust's enhanced semantics:
+* positional arg mapping, type coercion, alias expansion, default values,
+* required validation, variadic args, and strict mode.
+*
+* @param command - The command whose arg/flag definitions drive the parsing
+* @param argv - The argv array to parse (typically `process.argv.slice(2)`)
+* @returns Parsed args, flags, and rawArgs (everything after `--`)
+* @throws {CrustError} On unknown flags, missing required args/flags, type coercion failure, or alias collisions
+*/
+declare function parseArgs<
+	A extends ArgsDef = ArgsDef,
+	F extends FlagsDef = FlagsDef
+>(command: Command<A, F>, argv: string[]): ParseResult<A, F>;
+/**
+* The result of resolving a command from an argv array.
+*
+* Contains the resolved (sub)command and argv after subcommand
+* resolution, and the full command path for help text rendering.
+*/
+interface CommandRoute {
+	/** The routed command (may be a subcommand of the original) */
+	command: AnyCommand;
+	/** The argv after subcommand names have been consumed */
+	argv: string[];
+	/** The command path for help text (e.g. ["crust", "generate", "command"]) */
+	commandPath: string[];
+}
+/**
+* Resolve a command from an argv array by walking the subcommand tree.
+*
+* Subcommand matching happens BEFORE flag parsing, so:
+* `crust build --entry src/cli.ts` first resolves "build" as a subcommand,
+* then passes `["--entry", "src/cli.ts"]` to the build command's parser.
+*
+* Resolution rules:
+* 1. If `argv[0]` matches a subcommand key, recurse into that subcommand
+* 2. If no match and the current command has `run()`, return it (args passed to parser)
+* 3. If no match and the current command has NO `run()`, it signals the caller
+*    should show help (the `showHelp` flag is set in the result)
+* 4. Unknown subcommands produce a structured COMMAND_NOT_FOUND error
+*
+* @param command - The root command to resolve from
+* @param argv - The argv array to resolve against
+* @returns The resolved command, argv, and the command path
+* @throws {CrustError} COMMAND_NOT_FOUND when an unknown subcommand is given and the parent has no run()
+*/
+declare function resolveCommand(command: AnyCommand, argv: string[]): CommandRoute;
+interface PluginState {
+	get<T = unknown>(key: string): T | undefined;
+	has(key: string): boolean;
+	set(key: string, value: unknown): void;
+	delete(key: string): boolean;
+}
+interface SetupActions {
+	/**
+	* Inject a flag definition into a command's flags object.
+	*
+	* Use this in plugin `setup()` hooks to register plugin-specific flags
+	* (e.g. `--version`, `--help`) so they are recognized by the parser
+	* and rendered in help text.
+	*
+	* @param command - The command to add the flag to
+	* @param name - The flag name (e.g. "version")
+	* @param def - The flag definition
+	*/
+	addFlag(command: AnyCommand, name: string, def: FlagDef): void;
+}
+/** Shared context fields available in both setup and middleware phases. */
+interface BaseContext {
+	readonly argv: readonly string[];
+	readonly rootCommand: AnyCommand;
+	readonly state: PluginState;
+}
+/** Context passed to plugin `setup()` hooks. */
+interface SetupContext extends BaseContext {}
+/** Context passed to plugin `middleware()` hooks. */
+interface MiddlewareContext extends BaseContext {
+	route: Readonly<CommandRoute> | null;
+	input: ParseResult | null;
+}
+type Next = () => Promise<void>;
+type PluginMiddleware = (context: MiddlewareContext, next: Next) => void | Promise<void>;
+interface CrustPlugin {
+	name?: string;
+	setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
+	middleware?: PluginMiddleware;
+}
+interface RunOptions {
+	argv?: string[];
+	plugins?: CrustPlugin[];
+}
+declare function runCommand(command: AnyCommand, options?: RunOptions): Promise<void>;
+declare function runMain(command: AnyCommand, options?: RunOptions): Promise<void>;
+export { runMain, runCommand, resolveCommand, parseArgs, defineCommand, SetupContext, RunOptions, PluginMiddleware, ParseResult, MiddlewareContext, InferFlags, InferArgs, FlagsDef, FlagDef, CrustPlugin, CrustErrorCode, CrustError, CommandRoute, CommandNotFoundErrorDetails, CommandMeta, CommandContext, Command, ArgsDef, ArgDef, AnyCommand };

package/dist/index.js

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

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@crustjs/core",
+	"version": "0.0.2",
+	"description": "Core library for the Crust CLI framework",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/core"
+	},
+	"homepage": "https://crust.cyanlabs.co",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"command",
+		"framework",
+		"parser",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@crustjs/config": "workspace:*",
+		"bunup": "catalog:"
+	},
+	"peerDependencies": {
+		"typescript": "catalog:"
+	}
+}