fix: subcommand resolution incorrectly consumes flag values (#231)

Co-authored-by: Pooya Parsa <pooya@pi0.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

src/command.ts

@@ -1,3 +1,4 @@
+import { camelCase } from "scule";
 import type { CommandContext, CommandDef, ArgsDef } from "./types.ts";
 import { CLIError, resolveValue } from "./_utils.ts";
 import { parseArgs } from "./args.ts";
@@ -39,7 +40,7 @@ export async function runCommand<T extends ArgsDef = ArgsDef>(
   try {
     const subCommands = await resolveValue(cmd.subCommands);
     if (subCommands && Object.keys(subCommands).length > 0) {
-      const subCommandArgIndex = opts.rawArgs.findIndex((arg) => !arg.startsWith("-"));
+      const subCommandArgIndex = findSubCommandIndex(opts.rawArgs, cmdArgs);
       const subCommandName = opts.rawArgs[subCommandArgIndex];
       if (subCommandName) {
         if (!subCommands[subCommandName]) {
@@ -75,7 +76,8 @@ export async function resolveSubCommand<T extends ArgsDef = ArgsDef>(
 ): Promise<[CommandDef<T>, CommandDef<T>?]> {
   const subCommands = await resolveValue(cmd.subCommands);
   if (subCommands && Object.keys(subCommands).length > 0) {
-    const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
+    const cmdArgs = await resolveValue(cmd.args || {});
+    const subCommandArgIndex = findSubCommandIndex(rawArgs, cmdArgs);
     const subCommandName = rawArgs[subCommandArgIndex]!;
     const subCommand = await resolveValue(subCommands[subCommandName]);
     if (subCommand) {
@@ -84,3 +86,32 @@ export async function resolveSubCommand<T extends ArgsDef = ArgsDef>(
   }
   return [cmd, parent];
 }
+
+// --- internal ---
+
+function findSubCommandIndex(rawArgs: string[], argsDef: ArgsDef): number {
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i]!;
+    if (arg === "--") return -1;
+    if (arg.startsWith("-")) {
+      if (!arg.includes("=") && _isValueFlag(arg, argsDef)) {
+        i++; // skip the flag's value
+      }
+      continue;
+    }
+    return i;
+  }
+  return -1;
+}
+
+function _isValueFlag(flag: string, argsDef: ArgsDef): boolean {
+  const name = flag.replace(/^-{1,2}/, "");
+  const normalized = camelCase(name);
+  for (const [key, def] of Object.entries(argsDef)) {
+    if (def.type !== "string" && def.type !== "enum") continue;
+    if (normalized === camelCase(key)) return true;
+    const aliases = Array.isArray(def.alias) ? def.alias : def.alias ? [def.alias] : [];
+    if (aliases.includes(name)) return true;
+  }
+  return false;
+}

test/main.test.ts

@@ -143,7 +143,141 @@ describe("sub command", () => {
   });
 });
 
+describe("sub command with parent args", () => {
+  it("resolves subcommand when parent has string arg", async () => {
+    const runMock = vi.fn();
+
+    const command = defineCommand({
+      args: {
+        name: { type: "string" },
+      },
+      subCommands: {
+        build: {
+          run: async () => {
+            runMock();
+          },
+        },
+      },
+    });
+
+    await runMain(command, { rawArgs: ["--name", "Citty", "build"] });
+
+    expect(runMock).toHaveBeenCalledOnce();
+  });
+
+  it("resolves subcommand when parent has string arg with = syntax", async () => {
+    const runMock = vi.fn();
+
+    const command = defineCommand({
+      args: {
+        name: { type: "string" },
+      },
+      subCommands: {
+        build: {
+          run: async () => {
+            runMock();
+          },
+        },
+      },
+    });
+
+    await runMain(command, { rawArgs: ["--name=Citty", "build"] });
+
+    expect(runMock).toHaveBeenCalledOnce();
+  });
+
+  it("resolves subcommand when parent has string arg with alias", async () => {
+    const runMock = vi.fn();
+
+    const command = defineCommand({
+      args: {
+        name: { type: "string", alias: "n" },
+      },
+      subCommands: {
+        build: {
+          run: async () => {
+            runMock();
+          },
+        },
+      },
+    });
+
+    await runMain(command, { rawArgs: ["-n", "Citty", "build"] });
+
+    expect(runMock).toHaveBeenCalledOnce();
+  });
+
+  it("resolves subcommand when parent has enum arg", async () => {
+    const runMock = vi.fn();
+
+    const command = defineCommand({
+      args: {
+        env: { type: "enum", options: ["dev", "prod"] },
+      },
+      subCommands: {
+        build: {
+          run: async () => {
+            runMock();
+          },
+        },
+      },
+    });
+
+    await runMain(command, { rawArgs: ["--env", "prod", "build"] });
+
+    expect(runMock).toHaveBeenCalledOnce();
+  });
+
+  it("boolean arg does not consume next token as value", async () => {
+    const runMock = vi.fn();
+
+    const command = defineCommand({
+      args: {
+        verbose: { type: "boolean" },
+      },
+      subCommands: {
+        build: {
+          run: async () => {
+            runMock();
+          },
+        },
+      },
+    });
+
+    await runMain(command, { rawArgs: ["--verbose", "build"] });
+
+    expect(runMock).toHaveBeenCalledOnce();
+  });
+});
+
 describe("resolveSubCommand", () => {
+  it("resolves subcommand with parent string args", async () => {
+    const command = defineCommand({
+      args: {
+        name: { type: "string" },
+      },
+      subCommands: {
+        build: {
+          args: {
+            target: { type: "positional" },
+          },
+        },
+      },
+    });
+
+    const [subCommand] = await commandModule.resolveSubCommand(command, [
+      "--name",
+      "Citty",
+      "build",
+      "prod",
+    ]);
+
+    expect(subCommand).toBeDefined();
+    expect(subCommand.args).toEqual({
+      target: { type: "positional" },
+    });
+  });
+
   it("resolves the sub command", async () => {
     const command = defineCommand({
       subCommands: {