@crustjs/core 0.0.6 → 0.0.7

package/dist/index.d.ts

@@ -176,6 +176,38 @@ type ValidateFlagAliases<F extends Record<string, unknown>> = { [K in keyof F &
 	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.
@@ -386,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;
@@ -562,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, ValidateVariadicArgs, ValidateFlagAliases, 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.6",
+	"version": "0.0.7",
 	"description": "Core library for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",