@crustjs/core 0.0.3 → 0.0.4

package/README.md

@@ -17,9 +17,9 @@ import { defineCommand, runMain } from "@crustjs/core";
 
 const main = defineCommand({
   meta: { name: "greet", description: "Say hello" },
-  args: [{ name: "name", type: String, default: "world" }],
+  args: [{ name: "name", type: "string", default: "world" }],
   flags: {
-    loud: { type: Boolean, description: "Shout it", alias: "l" },
+    loud: { type: "boolean", description: "Shout it", alias: "l" },
   },
   run({ args, flags }) {
     const msg = `Hello, ${args.name}!`;

package/dist/index.d.ts

@@ -1,79 +1,131 @@
-/** Maps a constructor function (String, Number, Boolean) to its primitive type */
-type TypeConstructor = StringConstructor | NumberConstructor | BooleanConstructor;
+/** Supported type literals for args and flags */
+type ValueType = "string" | "number" | "boolean";
 /**
-* Resolves a constructor function to its corresponding TypeScript primitive type.
+* Resolves a type literal to its corresponding TypeScript primitive type.
 *
-* - `StringConstructor` → `string`
-* - `NumberConstructor` → `number`
-* - `BooleanConstructor` → `boolean`
+* - `"string"` → `string`
+* - `"number"` → `number`
+* - `"boolean"` → `boolean`
 */
-type ResolvePrimitive<T extends TypeConstructor> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : never;
+type ResolvePrimitive<T extends ValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : 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 */
+	required?: true;
+	/** When `true`, collects all remaining positional values into an array */
+	variadic?: true;
+}
+/** A positional argument whose value is a string */
+interface StringArgDef extends ArgDefBase {
+	type: "string";
+	/** Default string value when the argument is not provided */
+	default?: string;
+}
+/** 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;
+}
+/** 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;
+}
 /**
 * 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.
+* Discriminated by `type` for type-safe `default` values. Boolean toggle
+* fields (`required`, `variadic`) only accept `true`.
 *
 * @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 },
+*   { 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;
+type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef;
+/** Ordered tuple of positional argument definitions */
+type ArgsDef = readonly ArgDef[];
+/** Shared fields present on every flag definition */
+interface FlagDefBase {
 	/** 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;
+	/** Short alias or array of aliases (e.g. `"v"` or `["v", "V"]`) */
+	alias?: string | string[];
+	/** When `true`, the parser throws if the flag is not provided */
+	required?: true;
+}
+/** Base for single-value flags — `multiple` must be omitted */
+interface SingleFlagBase extends FlagDefBase {
+	/** Must be omitted for single-value flags — set to `true` for multi-value */
+	multiple?: never;
+}
+/** A single-value string flag */
+interface StringFlagDef extends SingleFlagBase {
+	type: "string";
+	/** Default string value */
+	default?: string;
+}
+/** A single-value number flag */
+interface NumberFlagDef extends SingleFlagBase {
+	type: "number";
+	/** Default number value */
+	default?: number;
+}
+/** A single-value boolean flag */
+interface BooleanFlagDef extends SingleFlagBase {
+	type: "boolean";
+	/** Default boolean value */
+	default?: boolean;
+}
+/** Base for multi-value flags — `multiple` is required as `true` */
+interface MultiFlagBase extends FlagDefBase {
+	/** Collect repeated values into an array */
+	multiple: true;
+}
+/** A multi-value string flag (collects repeated values into an array) */
+interface StringMultiFlagDef extends MultiFlagBase {
+	type: "string";
+	/** Default string array value */
+	default?: string[];
+}
+/** A multi-value number flag (collects repeated values into an array) */
+interface NumberMultiFlagDef extends MultiFlagBase {
+	type: "number";
+	/** Default number array value */
+	default?: number[];
+}
+/** A multi-value boolean flag (collects repeated values into an array) */
+interface BooleanMultiFlagDef extends MultiFlagBase {
+	type: "boolean";
+	/** Default boolean array value */
+	default?: boolean[];
 }
-/** Ordered tuple of positional argument definitions */
-type ArgsDef = readonly ArgDef[];
 /**
 * Defines a single named flag for a CLI command.
 *
+* Discriminated by `type` and `multiple` for type-safe `default` values.
+* Boolean toggle fields (`required`, `multiple`) only accept `true`.
+*
 * @example
 * ```ts
 * const flags = {
-*   verbose: { type: Boolean, description: "Enable verbose logging", alias: "v" },
-*   port: { type: Number, description: "Port number", default: 3000 },
+*   verbose: { type: "boolean", description: "Enable verbose logging", alias: "v" },
+*   port: { type: "number", description: "Port number", default: 3000 },
+*   files: { type: "string", multiple: true, default: ["index.ts"] },
 * } 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;
-}
+type FlagDef = StringFlagDef | NumberFlagDef | BooleanFlagDef | StringMultiFlagDef | NumberMultiFlagDef | BooleanMultiFlagDef;
 /** Record mapping flag names to their definitions */
 type FlagsDef = Record<string, FlagDef>;
 /** Extract alias string literals from a single FlagDef */
@@ -81,12 +133,6 @@ 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.
 */
@@ -95,38 +141,44 @@ type AliasesExcluding<
 	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.
+* Per-flag collision detection: resolves to the alias literal(s) of flag K
+* that collide with another flag's name or another flag's alias,
+* or `never` when K's aliases are all unique.
 */
-type FlagAliasAliasCollision<F extends FlagsDef> = { [K in keyof F & string] : ExtractAliases<F[K]> & AliasesExcluding<F, K> }[keyof F & string];
+type CollidingAliases<
+	F extends FlagsDef,
+	K extends keyof F & string
+> = (ExtractAliases<F[K]> & Exclude<keyof F & string, K>) | (ExtractAliases<F[K]> & AliasesExcluding<F, K>);
 /**
-* Compile-time check that no flag alias collides with another flag's name
-* or another flag's alias.
+* Per-flag validation mapped type. Resolves to `F` when no collisions exist.
+* For flags with colliding aliases, adds a branded error property to the
+* specific flag definition, causing a type error on that flag's value:
 *
-* - 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.
+* ```
+* Property 'FIX_ALIAS_COLLISION' is missing in type '{ type: "string"; alias: "minify" }'
+*   but required in type
+*     '{ readonly FIX_ALIAS_COLLISION: "Alias \"minify\" collides with another flag name or alias" }'.
+* ```
 */
-type InitHasVariadic<T extends readonly ArgDef[]> = T extends readonly [infer Head, ...infer Tail extends readonly ArgDef[]] ? Head extends {
-	variadic: true;
-} ? true : InitHasVariadic<Tail> : false;
+type ValidateFlagAliases<F extends FlagsDef> = { [K in keyof F & string] : CollidingAliases<F, K> extends never ? F[K] : F[K] & {
+	readonly FIX_ALIAS_COLLISION: `Alias "${CollidingAliases<F, K>}" collides with another flag name or alias`;
+} };
 /**
-* 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.
+* Per-arg validation tuple type. Resolves to `A` when the constraint is
+* satisfied (only the last arg is variadic). For non-last args that have
+* `variadic: true`, adds a branded error property to the specific arg:
 *
-* - 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.
+* ```
+* Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
+*   but required in type
+*     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
+* ```
 */
-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;
+type ValidateVariadicArgs<A extends ArgsDef> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? Tail extends readonly [ArgDef, ...ArgDef[]] ? Head extends {
+	variadic: true;
+} ? readonly [Head & {
+	readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
+}, ...ValidateVariadicArgs<readonly [...Tail]>] : readonly [Head, ...ValidateVariadicArgs<readonly [...Tail]>] : readonly [Head] : A;
 /**
 * Infer the resolved type for a single ArgDef:
 *
@@ -156,9 +208,9 @@ type Simplify<T> = { [K in keyof T] : T[K] };
 * @example
 * ```ts
 * type Result = InferArgs<readonly [
-*   { name: "port"; type: NumberConstructor; default: 3000 },
-*   { name: "name"; type: StringConstructor; required: true },
-*   { name: "files"; type: StringConstructor; variadic: true },
+*   { name: "port"; type: "number"; default: 3000 },
+*   { name: "name"; type: "string"; required: true },
+*   { name: "files"; type: "string"; variadic: true },
 * ]>;
 * // Result = { port: number; name: string; files: string[] }
 * ```
@@ -188,8 +240,8 @@ type InferFlagValue<F extends FlagDef> = F extends {
 * @example
 * ```ts
 * type Result = InferFlags<{
-*   verbose: { type: BooleanConstructor };
-*   port: { type: NumberConstructor, default: 3000 };
+*   verbose: { type: "boolean" };
+*   port: { type: "number", default: 3000 };
 * }>;
 * // Result = { verbose: boolean | undefined; port: number }
 * ```
@@ -233,7 +285,37 @@ interface CommandContext<
 	/** The resolved command that is being executed */
 	command: AnyCommand;
 }
-/** Unified command shape used for both command definitions and resolved commands. */
+/**
+* Configuration object accepted by `defineCommand()`.
+*
+* Identical shape to {@link Command} but uses `NoInfer` on lifecycle-hook
+* parameters so TypeScript infers `A` and `F` solely from the `args` / `flags`
+* data properties — not from callbacks. This ensures full contextual typing
+* (e.g. `description` is `string`, not `any`) when writing command definitions.
+*
+* Compile-time validation for variadic args and flag alias collisions is
+* enforced via parameter-level intersection in `defineCommand()`.
+*/
+interface CommandDef<
+	A extends ArgsDef = ArgsDef,
+	F extends FlagsDef = FlagsDef
+> {
+	/** Command metadata (name, description, usage) */
+	meta: CommandMeta;
+	/** Positional argument definitions */
+	args?: A;
+	/** Flag definitions */
+	flags?: F;
+	/** Named subcommands */
+	subCommands?: Record<string, AnyCommand>;
+	/** Called before `run()` — useful for initialization */
+	preRun?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+	/** The main command handler */
+	run?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+	/** Called after `run()` (even if it throws) — useful for teardown */
+	postRun?(context: CommandContext<NoInfer<A>, NoInfer<F>>): void | Promise<void>;
+}
+/** Frozen command object returned by `defineCommand()` and used at runtime. */
 interface Command<
 	A extends ArgsDef = ArgsDef,
 	F extends FlagsDef = FlagsDef
@@ -270,10 +352,10 @@ type AnyCommand = Command<any, any>;
 * const cmd = defineCommand({
 *   meta: { name: "serve", description: "Start dev server" },
 *   args: [
-*     { name: "port", type: Number, description: "Port number", default: 3000 },
+*     { name: "port", type: "number", description: "Port number", default: 3000 },
 *   ],
 *   flags: {
-*     verbose: { type: Boolean, description: "Enable verbose logging", alias: "v" },
+*     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
@@ -285,9 +367,9 @@ type AnyCommand = Command<any, any>;
 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>;
+>(config: CommandDef<A, F> & {
+	args?: ValidateVariadicArgs<A>;
+	flags?: ValidateFlagAliases<F>;
 }): Command<A, F>;
 interface CommandNotFoundErrorDetails {
 	input: string;
@@ -457,4 +539,4 @@ interface RunOptions {
 }
 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 };
+export { runMain, runCommand, resolveCommand, parseArgs, defineCommand, SetupContext, RunOptions, PluginMiddleware, ParseResult, MiddlewareContext, InferFlags, InferArgs, FlagsDef, FlagDef, CrustPlugin, CrustErrorCode, CrustError, CommandRoute, CommandNotFoundErrorDetails, CommandMeta, CommandDef, CommandContext, Command, ArgsDef, ArgDef, AnyCommand };

package/dist/index.js

@@ -51,7 +51,7 @@ function buildParseArgsOptionDescriptor(flagsDef) {
     aliasRegistry.set(name, name);
   }
   for (const [name, def] of Object.entries(flagsDef)) {
-    const parseType = def.type === Boolean ? "boolean" : "string";
+    const parseType = def.type === "boolean" ? "boolean" : "string";
     const opt = { type: parseType };
     if (def.multiple) {
       opt.multiple = true;
@@ -61,7 +61,7 @@ function buildParseArgsOptionDescriptor(flagsDef) {
       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}"`);
+          throw new CrustError("DEFINITION", `Alias collision: "${alias.length === 1 ? "-" : "--"}${alias}" is used by both "--${existing}" and "--${name}"`);
         }
         aliasRegistry.set(alias, name);
         aliasToName[alias] = name;
@@ -81,14 +81,14 @@ function buildParseArgsOptionDescriptor(flagsDef) {
   return { options, aliasToName };
 }
 function coerceValue(value, type, label) {
-  if (type === Number) {
+  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) {
+  if (type === "boolean") {
     return value === "true" || value === "1";
   }
   return value;
@@ -104,9 +104,9 @@ function applyDefaultOrThrow(def, label) {
 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));
+    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) {
+  if (def.type === "boolean") {
     return typeof parsedValue === "boolean" ? parsedValue : Boolean(parsedValue);
   }
   if (typeof parsedValue === "string") {
@@ -172,7 +172,7 @@ function resolveArgs(argsDef, positionals) {
       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;
+      resolved[name] = def.type === "string" ? remaining : remaining.map((v) => coerceValue(v, def.type, `<${name}>`));
       index = positionals.length;
     } else if (index < positionals.length) {
       resolved[name] = coerceValue(positionals[index], def.type, `<${name}>`);

package/package.json

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