@crustjs/core 0.0.6 → 0.0.8

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.
@@ -343,8 +375,8 @@ interface Command<
 	readonly args?: A;
 	/** Flag definitions */
 	readonly flags?: F;
-	/** Named subcommands */
-	readonly subCommands?: Record<string, AnyCommand>;
+	/** Named subcommands (always initialized, may be empty) */
+	readonly subCommands: Record<string, AnyCommand>;
 	/** Called before `run()` — useful for initialization */
 	preRun?(context: CommandContext<A, F>): void | Promise<void>;
 	/** The main command handler */
@@ -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;
@@ -535,6 +567,19 @@ interface SetupActions {
 	* @param def - The flag definition
 	*/
 	addFlag(command: AnyCommand, name: string, def: FlagDef): void;
+	/**
+	* Inject a subcommand into a command's `subCommands` record.
+	*
+	* Use this in plugin `setup()` hooks to register plugin-provided commands
+	* (e.g. a "skill" management command). If the parent already has a
+	* subcommand with the same name (user-defined), the call is silently
+	* skipped — user definitions always take priority over plugin injections.
+	*
+	* @param parent - The parent command to add the subcommand to
+	* @param name - The subcommand name (used for routing)
+	* @param command - The subcommand to register
+	*/
+	addSubCommand(parent: AnyCommand, name: string, command: AnyCommand): void;
 }
 /** Shared context fields available in both setup and middleware phases. */
 interface BaseContext {
@@ -562,4 +607,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, SetupActions, 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 },
@@ -31,9 +47,7 @@ function defineCommand(config) {
       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 }
-    }
+    subCommands: config.subCommands ? { ...config.subCommands } : {}
   };
   return Object.freeze(copy);
 }
@@ -51,6 +65,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 +77,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 +125,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 +207,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 +249,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 = [];
@@ -342,6 +390,14 @@ async function runCommand(command, options) {
         throw new CrustError("DEFINITION", `Cannot add flag "${name}": command "${target.meta.name}" has no flags object.`);
       }
       target.flags[name] = def;
+    },
+    addSubCommand(parent, name, subCommand) {
+      if (!name.trim()) {
+        throw new CrustError("DEFINITION", "addSubCommand: name is required and must be a non-empty string");
+      }
+      if (parent.subCommands[name])
+        return;
+      parent.subCommands[name] = subCommand;
     }
   };
   const middlewareContext = {

package/package.json

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