@crustjs/core 0.0.5 → 0.0.7

package/dist/index.d.ts

@@ -128,16 +128,25 @@ interface BooleanMultiFlagDef extends MultiFlagBase {
 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 */
-type ExtractAliases<F extends FlagDef> = F extends {
+/**
+* Extract alias string literals from any value that has an `alias` field.
+*
+* Generalized to work with any shape (`FlagDef`, `FlagSpec`, etc.) —
+* values without an `alias` field resolve to `never`.
+*
+* Includes a `string extends A` guard so non-narrowed aliases (e.g. the
+* broad `string` type from a default generic) resolve to `never` instead
+* of causing false-positive collisions.
+*/
+type ExtractAliases<F> = F extends {
 	alias: infer A;
-} ? A extends string ? A : A extends readonly string[] ? A[number] : never : never;
+} ? A extends string ? string extends A ? never : A : A extends readonly string[] ? string extends A[number] ? never : A[number] : never : never;
 /**
 * Collects aliases from every flag *except* flag K.
 * Used to detect alias→alias duplicates across different flags.
 */
 type AliasesExcluding<
-	F extends FlagsDef,
+	F extends Record<string, unknown>,
 	K extends keyof F & string
 > = { [J in Exclude<keyof F & string, K>] : ExtractAliases<F[J]> }[Exclude<keyof F & string, K>];
 /**
@@ -146,13 +155,16 @@ type AliasesExcluding<
 * or `never` when K's aliases are all unique.
 */
 type CollidingAliases<
-	F extends FlagsDef,
+	F extends Record<string, unknown>,
 	K extends keyof F & string
 > = (ExtractAliases<F[K]> & Exclude<keyof F & string, K>) | (ExtractAliases<F[K]> & AliasesExcluding<F, K>);
 /**
 * Per-flag validation mapped type. Resolves to `F` when no collisions exist.
 * For flags with colliding aliases, adds a branded error property to the
-* specific flag definition, causing a type error on that flag's value:
+* specific flag definition, causing a type error on that flag's value.
+*
+* Generalized to work with any `Record<string, unknown>` shape — core uses
+* it with `FlagsDef`, the validate package uses it with `FlagShape`, etc.
 *
 * ```
 * Property 'FIX_ALIAS_COLLISION' is missing in type '{ type: "string"; alias: "minify" }'
@@ -160,13 +172,50 @@ type CollidingAliases<
 *     '{ readonly FIX_ALIAS_COLLISION: "Alias \"minify\" collides with another flag name or alias" }'.
 * ```
 */
-type ValidateFlagAliases<F extends FlagsDef> = { [K in keyof F & string] : CollidingAliases<F, K> extends never ? F[K] : F[K] & {
+type ValidateFlagAliases<F extends Record<string, unknown>> = { [K in keyof F & string] : CollidingAliases<F, K> extends never ? F[K] : F[K] & {
 	readonly FIX_ALIAS_COLLISION: `Alias "${CollidingAliases<F, K>}" collides with another flag name or alias`;
 } };
 /**
+* Detects whether a single alias literal starts with `"no-"`.
+* Resolves to the offending alias, or `never` when it is clean.
+*/
+type NoPrefixedAlias<A> = A extends `no-${string}` ? A : never;
+/**
+* Collects all `"no-"`-prefixed alias literals from a flag definition.
+* Works with both `alias: "no-foo"` (string) and `alias: ["no-foo", "f"]` (array).
+* Non-narrowed `string` types resolve to `never` to avoid false positives.
+*/
+type NoPrefixedAliases<F> = F extends {
+	alias: infer A;
+} ? A extends string ? string extends A ? never : NoPrefixedAlias<A> : A extends readonly string[] ? string extends A[number] ? never : NoPrefixedAlias<A[number]> : never : never;
+/**
+* Per-flag validation mapped type. Resolves to `F` when no `"no-"` prefixes
+* exist on flag names or aliases. For flags with offending names or aliases,
+* adds a branded error property causing a compile-time type error.
+*
+* The `"no-"` prefix is reserved for boolean flag negation (`--no-flag`).
+* Define only the positive form (e.g. `cache`) and use `--no-cache` at runtime.
+*
+* ```
+* Property 'FIX_NO_PREFIX' is missing in type '{ type: "boolean" }'
+*   but required in type
+*     '{ readonly FIX_NO_PREFIX: "Flag name \"no-cache\" must not start with \"no-\"; define \"cache\" instead and use \"--no-cache\" at runtime" }'.
+* ```
+*/
+type ValidateNoPrefixedFlags<F extends Record<string, unknown>> = { [K in keyof F & string] : K extends `no-${infer Base}` ? F[K] & {
+	readonly FIX_NO_PREFIX: `Flag name "${K}" must not start with "no-"; define "${Base}" instead and use "--no-${Base}" at runtime`;
+} : NoPrefixedAliases<F[K]> extends never ? F[K] : F[K] & {
+	readonly FIX_NO_PREFIX: `Alias "${NoPrefixedAliases<F[K]>}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`;
+} };
+/**
 * 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:
+* `variadic: true`, adds a branded error property to the specific arg.
+*
+* Generalized to work with any ordered tuple of object-typed definitions —
+* core uses it with `ArgsDef`, the validate package uses it with
+* `ArgSpec[]`, etc. Uses `readonly object[]` to avoid TypeScript's weak
+* type detection (all-optional constraint rejection).
 *
 * ```
 * Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
@@ -174,11 +223,11 @@ type ValidateFlagAliases<F extends FlagsDef> = { [K in keyof F & string] : Colli
 *     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
 * ```
 */
-type ValidateVariadicArgs<A extends ArgsDef> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? Tail extends readonly [ArgDef, ...ArgDef[]] ? Head extends {
+type ValidateVariadicArgs<A extends readonly object[]> = A extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Tail extends readonly [unknown, ...unknown[]] ? 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;
+}, ...ValidateVariadicArgs<Tail>] : readonly [Head, ...ValidateVariadicArgs<Tail>] : readonly [Head] : A;
 /**
 * Infer the resolved type for a single ArgDef:
 *
@@ -369,7 +418,7 @@ declare function defineCommand<
 	const F extends FlagsDef = FlagsDef
 >(config: CommandDef<A, F> & {
 	args?: ValidateVariadicArgs<A>;
-	flags?: ValidateFlagAliases<F>;
+	flags?: ValidateNoPrefixedFlags<ValidateFlagAliases<F>>;
 }): Command<A, F>;
 interface CommandNotFoundErrorDetails {
 	input: string;
@@ -377,9 +426,15 @@ interface CommandNotFoundErrorDetails {
 	commandPath: string[];
 	parentCommand: AnyCommand;
 }
+interface ValidationErrorDetails {
+	issues: readonly {
+		readonly message: string;
+		readonly path: string;
+	}[];
+}
 interface CrustErrorDetailsMap {
 	DEFINITION: undefined;
-	VALIDATION: undefined;
+	VALIDATION: ValidationErrorDetails | undefined;
 	PARSE: undefined;
 	EXECUTION: undefined;
 	COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
@@ -439,7 +494,7 @@ declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Erro
 	readonly details: CrustErrorDetails<C>;
 	/** Optional wrapped original error/value */
 	cause?: unknown;
-	constructor(code: C, message: string, ...details: CrustErrorDetails<C> extends undefined ? [] | [undefined] : [CrustErrorDetails<C>]);
+	constructor(code: C, message: string, ...details: undefined extends CrustErrorDetails<C> ? [] | [CrustErrorDetails<C>] : [CrustErrorDetails<C>]);
 	is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
 	withCause(cause: unknown): this;
 }
@@ -539,4 +594,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, CommandDef, CommandContext, Command, ArgsDef, ArgDef, AnyCommand };
+export { runMain, runCommand, resolveCommand, parseArgs, defineCommand, ValueType, ValidateVariadicArgs, ValidateNoPrefixedFlags, ValidateFlagAliases, SetupContext, RunOptions, PluginMiddleware, ParseResult, MiddlewareContext, InferFlags, InferArgs, FlagsDef, FlagDef, CrustPlugin, CrustErrorCode, CrustError, CommandRoute, CommandMeta, CommandDef, CommandContext, Command, ArgsDef, ArgDef, AnyCommand };

package/dist/index.js

@@ -24,6 +24,22 @@ function defineCommand(config) {
   if (!config.meta.name.trim()) {
     throw new CrustError("DEFINITION", "defineCommand: meta.name is required and must be a non-empty string");
   }
+  if (config.flags) {
+    for (const [name, def] of Object.entries(config.flags)) {
+      if (name.startsWith("no-")) {
+        const base = name.slice(3);
+        throw new CrustError("DEFINITION", `Flag name "--${name}" must not start with "no-"; define "${base}" instead and use "--no-${base}" at runtime`);
+      }
+      if (def.alias) {
+        const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
+        for (const alias of aliases) {
+          if (alias.startsWith("no-")) {
+            throw new CrustError("DEFINITION", `Alias "--${alias}" on flag "--${name}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`);
+          }
+        }
+      }
+    }
+  }
   const copy = {
     ...config,
     meta: { ...config.meta },
@@ -51,6 +67,10 @@ function buildParseArgsOptionDescriptor(flagsDef) {
     aliasRegistry.set(name, name);
   }
   for (const [name, def] of Object.entries(flagsDef)) {
+    if (name.startsWith("no-")) {
+      const base = name.slice(3);
+      throw new CrustError("DEFINITION", `Flag name "--${name}" must not start with "no-"; define "${base}" instead and use "--no-${base}" at runtime`);
+    }
     const parseType = def.type === "boolean" ? "boolean" : "string";
     const opt = { type: parseType };
     if (def.multiple) {
@@ -59,6 +79,9 @@ function buildParseArgsOptionDescriptor(flagsDef) {
     if (def.alias) {
       const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
       for (const alias of aliases) {
+        if (alias.startsWith("no-")) {
+          throw new CrustError("DEFINITION", `Alias "--${alias}" on flag "--${name}" must not start with "no-"; the "no-" prefix is reserved for boolean negation`);
+        }
         const existing = aliasRegistry.get(alias);
         if (existing) {
           throw new CrustError("DEFINITION", `Alias collision: "${alias.length === 1 ? "-" : "--"}${alias}" is used by both "--${existing}" and "--${name}"`);
@@ -104,10 +127,13 @@ 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.filter((v) => typeof v === "boolean") : parsedValue.map((v) => coerceValue(v, def.type, label));
   }
   if (def.type === "boolean") {
-    return typeof parsedValue === "boolean" ? parsedValue : Boolean(parsedValue);
+    if (typeof parsedValue === "boolean") {
+      return parsedValue;
+    }
+    throw new CrustError("PARSE", `Expected boolean value for flag "${label}", got ${typeof parsedValue}`);
   }
   if (typeof parsedValue === "string") {
     return coerceValue(parsedValue, def.type, label);
@@ -183,10 +209,34 @@ function resolveArgs(argsDef, positionals) {
   }
   return resolved;
 }
+function validateCanonicalNegationUsage(argv, flagsDef, aliasToName) {
+  if (!flagsDef)
+    return;
+  for (const arg of argv) {
+    if (arg === "--")
+      return;
+    if (!arg.startsWith("--no-"))
+      continue;
+    const assignmentIndex = arg.indexOf("=");
+    const rawName = assignmentIndex === -1 ? arg.slice("--no-".length) : arg.slice("--no-".length, assignmentIndex);
+    if (!rawName)
+      continue;
+    const canonical = aliasToName[rawName];
+    if (!canonical)
+      continue;
+    if (canonical === rawName)
+      continue;
+    const def = flagsDef[canonical];
+    if (def?.type !== "boolean")
+      continue;
+    throw new CrustError("PARSE", `Cannot negate alias "--no-${rawName}"; use "--no-${canonical}" instead`);
+  }
+}
 function parseArgs(command, argv) {
   const argsDef = command.args;
   const flagsDef = command.flags;
   const { options: parseOptions, aliasToName } = buildParseArgsOptionDescriptor(flagsDef);
+  validateCanonicalNegationUsage(argv, flagsDef, aliasToName);
   let parsed;
   try {
     parsed = nodeParseArgs({
@@ -201,10 +251,10 @@ function parseArgs(command, argv) {
     if (error instanceof Error) {
       const unknownMatch = error.message.match(/Unknown option '(.+?)'/);
       if (unknownMatch) {
-        throw new CrustError("PARSE", `Unknown flag "${unknownMatch[1]}"`);
+        throw new CrustError("PARSE", `Unknown flag "${unknownMatch[1]}"`).withCause(error);
       }
     }
-    throw error;
+    throw new CrustError("PARSE", "Failed to parse command arguments").withCause(error);
   }
   const rawArgs = [];
   const preSeparatorPositionals = [];

package/package.json

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