alepha 0.15.1 → 0.15.3

package/src/command/providers/CliProvider.spec.ts

@@ -0,0 +1,1392 @@
+import { Alepha, t } from "alepha";
+import { describe, expect, it } from "vitest";
+import { $command } from "../primitives/$command.ts";
+import { CliProvider } from "./CliProvider.ts";
+
+/**
+ * Test subclass that exposes protected methods for unit testing.
+ */
+class TestCliProvider extends CliProvider {
+  public testParseFlags = this.parseFlags.bind(this);
+  public testParseCommandArgs = this.parseCommandArgs.bind(this);
+  public testParseArgumentValue = this.parseArgumentValue.bind(this);
+  public testParseModeFlag = this.parseModeFlag.bind(this);
+  public testResolveCommand = this.resolveCommand.bind(this);
+  public testRemoveConsumedArgs = this.removeConsumedArgs.bind(this);
+  public testGetFlagConsumedIndices = this.getFlagConsumedIndices.bind(this);
+  public testGenerateArgsUsage = this.generateArgsUsage.bind(this);
+  public testGenerateColoredArgsUsage =
+    this.generateColoredArgsUsage.bind(this);
+  public testGetTypeName = this.getTypeName.bind(this);
+  public testGetTopLevelCommands = this.getTopLevelCommands.bind(this);
+  public testFindParentCommand = this.findParentCommand.bind(this);
+  public testGetCommandPath = this.getCommandPath.bind(this);
+  public testFindCommand = this.findCommand.bind(this);
+  public testFindPreHooks = this.findPreHooks.bind(this);
+  public testFindPostHooks = this.findPostHooks.bind(this);
+  public testGetEnumValues = this.getEnumValues.bind(this);
+  public testFormatFlagDescription = this.formatFlagDescription.bind(this);
+
+  /**
+   * Extract flag definitions from a command's flags schema (for testing printHelp logic).
+   */
+  public testExtractFlagDefs(flagsSchema: any) {
+    return Object.entries(flagsSchema.properties).map(([key, value]) => ({
+      key,
+      schema: value,
+      aliases: [
+        key,
+        ...((value as any).aliases ??
+          ((value as any).alias ? [(value as any).alias] : [])),
+      ],
+      description: (value as any).description,
+    }));
+  }
+
+  /**
+   * Format aliases array into flag string (e.g., "-t, --target").
+   * Sorts by length (shorter first).
+   */
+  public testFormatFlagStr(aliases: string[]): string {
+    return aliases
+      .slice()
+      .sort((a, b) => a.length - b.length)
+      .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
+      .join(", ");
+  }
+}
+
+describe("CliProvider", () => {
+  const createTestCli = () => {
+    const alepha = Alepha.create();
+    return alepha.inject(TestCliProvider);
+  };
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // parseFlags
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("parseFlags", () => {
+    it("should parse boolean flags", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["--verbose"], flagDefs);
+      expect(result.verbose).toBe(true);
+    });
+
+    it("should parse short boolean flags", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["-v"], flagDefs);
+      expect(result.verbose).toBe(true);
+    });
+
+    it("should parse string flags with = syntax", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "name", aliases: ["n", "name"], schema: t.string() },
+      ];
+
+      const result = cli.testParseFlags(["--name=hello"], flagDefs);
+      expect(result.name).toBe("hello");
+    });
+
+    it("should parse string flags with space syntax", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "name", aliases: ["n", "name"], schema: t.string() },
+      ];
+
+      const result = cli.testParseFlags(["--name", "hello"], flagDefs);
+      expect(result.name).toBe("hello");
+    });
+
+    it("should parse JSON object flags", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "config", aliases: ["config"], schema: t.object({}) },
+      ];
+
+      const result = cli.testParseFlags(
+        ["--config", '{"key":"value"}'],
+        flagDefs,
+      );
+      expect(result.config).toEqual({ key: "value" });
+    });
+
+    it("should parse JSON array flags", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "items", aliases: ["items"], schema: t.array(t.string()) },
+      ];
+
+      const result = cli.testParseFlags(["--items", '["a","b"]'], flagDefs);
+      expect(result.items).toEqual(["a", "b"]);
+    });
+
+    it("should throw on unknown flags", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "known", aliases: ["known"], schema: t.boolean() },
+      ];
+
+      expect(() =>
+        cli.testParseFlags(["--unknown", "--known"], flagDefs),
+      ).toThrow("Unknown flag: --unknown");
+    });
+
+    it("should throw on missing required value", () => {
+      const cli = createTestCli();
+      const flagDefs = [{ key: "name", aliases: ["name"], schema: t.string() }];
+
+      expect(() => cli.testParseFlags(["--name"], flagDefs)).toThrow(
+        "requires a value",
+      );
+    });
+
+    it("should throw on invalid JSON", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "config", aliases: ["config"], schema: t.object({}) },
+      ];
+
+      expect(() =>
+        cli.testParseFlags(["--config", "{invalid}"], flagDefs),
+      ).toThrow("Invalid JSON");
+    });
+
+    it("should parse union(boolean, text) flag without value as true", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i"], flagDefs);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag with = value as string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i=1.3.4"], flagDefs);
+      expect(result.image).toBe("1.3.4");
+    });
+
+    it("should parse union(boolean, text) flag with space value as string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["-i", "1.3.4"], flagDefs);
+      expect(result.image).toBe("1.3.4");
+    });
+
+    it("should parse union(boolean, text) flag without value when followed by another flag", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["-i", "-v"], flagDefs);
+      expect(result.image).toBe(true);
+      expect(result.verbose).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag with long form without value", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(["--image"], flagDefs);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) flag at end of argv without value", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testParseFlags(["-v", "-i"], flagDefs);
+      expect(result.verbose).toBe(true);
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) with empty = value as empty string", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      // Note: --image= results in empty string value
+      const result = cli.testParseFlags(["--image="], flagDefs);
+      // Empty string is falsy, so it goes through the "no value" path → true
+      // This is expected behavior - use --image="" if you need empty string
+      expect(result.image).toBe(true);
+    });
+
+    it("should parse union(boolean, text) with value containing special chars", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testParseFlags(
+        ["--image=my-org/my-app:v1.2.3-beta"],
+        flagDefs,
+      );
+      expect(result.image).toBe("my-org/my-app:v1.2.3-beta");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // parseArgumentValue
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("parseArgumentValue", () => {
+    it("should parse string values", () => {
+      const cli = createTestCli();
+      expect(cli.testParseArgumentValue("hello", t.string())).toBe("hello");
+    });
+
+    it("should parse number values", () => {
+      const cli = createTestCli();
+      expect(cli.testParseArgumentValue("42", t.number())).toBe(42);
+      expect(cli.testParseArgumentValue("3.14", t.number())).toBe(3.14);
+    });
+
+    it("should throw on invalid number", () => {
+      const cli = createTestCli();
+      expect(() => cli.testParseArgumentValue("abc", t.number())).toThrow(
+        "Expected number",
+      );
+    });
+
+    it("should parse integer values", () => {
+      const cli = createTestCli();
+      expect(cli.testParseArgumentValue("42", t.integer())).toBe(42);
+    });
+
+    it("should throw on non-integer for integer schema", () => {
+      const cli = createTestCli();
+      expect(() => cli.testParseArgumentValue("3.14", t.integer())).toThrow(
+        "Expected integer",
+      );
+    });
+
+    it("should parse boolean true values", () => {
+      const cli = createTestCli();
+      expect(cli.testParseArgumentValue("true", t.boolean())).toBe(true);
+      expect(cli.testParseArgumentValue("1", t.boolean())).toBe(true);
+    });
+
+    it("should parse boolean false values", () => {
+      const cli = createTestCli();
+      expect(cli.testParseArgumentValue("false", t.boolean())).toBe(false);
+      expect(cli.testParseArgumentValue("0", t.boolean())).toBe(false);
+    });
+
+    it("should throw on invalid boolean", () => {
+      const cli = createTestCli();
+      expect(() => cli.testParseArgumentValue("yes", t.boolean())).toThrow(
+        "Expected boolean",
+      );
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // parseCommandArgs
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("parseCommandArgs", () => {
+    it("should return undefined when no schema", () => {
+      const cli = createTestCli();
+      expect(
+        cli.testParseCommandArgs(["arg"], undefined, true),
+      ).toBeUndefined();
+    });
+
+    it("should parse optional args when present", () => {
+      const cli = createTestCli();
+      const schema = t.optional(t.string());
+      expect(cli.testParseCommandArgs(["hello"], schema, true)).toBe("hello");
+    });
+
+    it("should return undefined for optional args when missing", () => {
+      const cli = createTestCli();
+      const schema = t.optional(t.string());
+      expect(cli.testParseCommandArgs([], schema, true)).toBeUndefined();
+    });
+
+    it("should parse required args", () => {
+      const cli = createTestCli();
+      const schema = t.string();
+      expect(cli.testParseCommandArgs(["hello"], schema, true)).toBe("hello");
+    });
+
+    it("should throw on missing required args", () => {
+      const cli = createTestCli();
+      const schema = t.string();
+      expect(() => cli.testParseCommandArgs([], schema, true)).toThrow(
+        "Missing required argument",
+      );
+    });
+
+    it("should parse tuple args", () => {
+      const cli = createTestCli();
+      const schema = t.tuple([t.string(), t.number()]);
+      const result = cli.testParseCommandArgs(["hello", "42"], schema, true);
+      expect(result).toEqual(["hello", 42]);
+    });
+
+    it("should handle optional tuple items", () => {
+      const cli = createTestCli();
+      const schema = t.tuple([t.string(), t.optional(t.number())]);
+      const result = cli.testParseCommandArgs(["hello"], schema, true);
+      expect(result).toEqual(["hello", undefined]);
+    });
+
+    it("should skip flags when parsing args", () => {
+      const cli = createTestCli();
+      const schema = t.string();
+      const flags = t.object({ verbose: t.optional(t.boolean()) });
+      const result = cli.testParseCommandArgs(
+        ["--verbose", "hello"],
+        schema,
+        true,
+        flags,
+      );
+      expect(result).toBe("hello");
+    });
+
+    it("should skip flag values when parsing args", () => {
+      const cli = createTestCli();
+      const schema = t.string();
+      const flags = t.object({ name: t.optional(t.string()) });
+      const result = cli.testParseCommandArgs(
+        ["--name", "ignored", "actual"],
+        schema,
+        true,
+        flags,
+      );
+      expect(result).toBe("actual");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // parseModeFlag
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("parseModeFlag", () => {
+    it("should parse --mode=value", () => {
+      const cli = createTestCli();
+      expect(cli.testParseModeFlag(["--mode=production"])).toBe("production");
+    });
+
+    it("should parse -m=value", () => {
+      const cli = createTestCli();
+      expect(cli.testParseModeFlag(["-m=staging"])).toBe("staging");
+    });
+
+    it("should parse --mode value", () => {
+      const cli = createTestCli();
+      expect(cli.testParseModeFlag(["--mode", "production"])).toBe(
+        "production",
+      );
+    });
+
+    it("should parse -m value", () => {
+      const cli = createTestCli();
+      expect(cli.testParseModeFlag(["-m", "staging"])).toBe("staging");
+    });
+
+    it("should return undefined when no mode flag", () => {
+      const cli = createTestCli();
+      expect(cli.testParseModeFlag(["--other", "value"])).toBeUndefined();
+    });
+
+    it("should throw when --mode has no value", () => {
+      const cli = createTestCli();
+      expect(() => cli.testParseModeFlag(["--mode"])).toThrow(
+        "requires a value",
+      );
+    });
+
+    it("should throw when --mode followed by another flag", () => {
+      const cli = createTestCli();
+      expect(() => cli.testParseModeFlag(["--mode", "--other"])).toThrow(
+        "requires a value",
+      );
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // resolveCommand
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("resolveCommand", () => {
+    it("should return undefined for empty args", () => {
+      const cli = createTestCli();
+      const result = cli.testResolveCommand([]);
+      expect(result.command).toBeUndefined();
+      expect(result.consumedArgs).toEqual([]);
+    });
+
+    it("should find command by name", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      const result = cli.testResolveCommand(["build"]);
+      expect(result.command?.name).toBe("build");
+      expect(result.consumedArgs).toEqual(["build"]);
+    });
+
+    it("should find command by colon notation", () => {
+      class TestCommands {
+        deployVercel = $command({
+          name: "deploy:vercel",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      const result = cli.testResolveCommand(["deploy:vercel"]);
+      expect(result.command?.name).toBe("deploy:vercel");
+      expect(result.consumedArgs).toEqual(["deploy:vercel"]);
+    });
+
+    it("should return undefined for unknown command", () => {
+      const cli = createTestCli();
+      const result = cli.testResolveCommand(["unknown"]);
+      expect(result.command).toBeUndefined();
+      expect(result.consumedArgs).toEqual([]);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // removeConsumedArgs
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("removeConsumedArgs", () => {
+    it("should remove consumed command args", () => {
+      const cli = createTestCli();
+      const result = cli.testRemoveConsumedArgs(
+        ["build", "--verbose", "extra"],
+        ["build"],
+      );
+      expect(result).toEqual(["--verbose", "extra"]);
+    });
+
+    it("should preserve flags", () => {
+      const cli = createTestCli();
+      const result = cli.testRemoveConsumedArgs(
+        ["--flag", "build", "arg"],
+        ["build"],
+      );
+      expect(result).toEqual(["--flag", "arg"]);
+    });
+
+    it("should remove multiple consumed args", () => {
+      const cli = createTestCli();
+      const result = cli.testRemoveConsumedArgs(
+        ["deploy", "vercel", "--prod"],
+        ["deploy", "vercel"],
+      );
+      expect(result).toEqual(["--prod"]);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getFlagConsumedIndices
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getFlagConsumedIndices", () => {
+    it("should mark flag indices as consumed", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(["--verbose"], flagDefs);
+      expect(result.has(0)).toBe(true);
+    });
+
+    it("should mark flag value indices as consumed", () => {
+      const cli = createTestCli();
+      const flagDefs = [{ key: "name", aliases: ["name"], schema: t.string() }];
+
+      const result = cli.testGetFlagConsumedIndices(
+        ["--name", "value", "arg"],
+        flagDefs,
+      );
+      expect(result.has(0)).toBe(true); // --name
+      expect(result.has(1)).toBe(true); // value
+      expect(result.has(2)).toBe(false); // arg
+    });
+
+    it("should not consume next arg for --flag=value syntax", () => {
+      const cli = createTestCli();
+      const flagDefs = [{ key: "name", aliases: ["name"], schema: t.string() }];
+
+      const result = cli.testGetFlagConsumedIndices(
+        ["--name=value", "arg"],
+        flagDefs,
+      );
+      expect(result.has(0)).toBe(true); // --name=value
+      expect(result.has(1)).toBe(false); // arg
+    });
+
+    it("should consume value for union(boolean, text) when value is provided", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(
+        ["-i", "1.3.4", "arg"],
+        flagDefs,
+      );
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.has(1)).toBe(true); // 1.3.4 (consumed as value)
+      expect(result.has(2)).toBe(false); // arg
+    });
+
+    it("should not consume next arg for union(boolean, text) when next is a flag", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+        { key: "verbose", aliases: ["v", "verbose"], schema: t.boolean() },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(["-i", "-v"], flagDefs);
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.has(1)).toBe(true); // -v (not consumed by -i, but by itself)
+    });
+
+    it("should not consume next arg for union(boolean, text) at end of argv", () => {
+      const cli = createTestCli();
+      const flagDefs = [
+        {
+          key: "image",
+          aliases: ["i", "image"],
+          schema: t.union([t.boolean(), t.text()]),
+        },
+      ];
+
+      const result = cli.testGetFlagConsumedIndices(["-i"], flagDefs);
+      expect(result.has(0)).toBe(true); // -i
+      expect(result.size).toBe(1);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // generateArgsUsage
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("generateArgsUsage", () => {
+    it("should return empty string for no schema", () => {
+      const cli = createTestCli();
+      expect(cli.testGenerateArgsUsage(undefined)).toBe("");
+    });
+
+    it("should generate optional arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.optional(t.string({ title: "path" }));
+      expect(cli.testGenerateArgsUsage(schema)).toBe(" [path]");
+    });
+
+    it("should generate required arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.string({ title: "path" });
+      expect(cli.testGenerateArgsUsage(schema)).toBe(" <path>");
+    });
+
+    it("should generate tuple arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.tuple([t.string(), t.optional(t.number())]);
+      const result = cli.testGenerateArgsUsage(schema);
+      expect(result).toContain("<arg1>");
+      expect(result).toContain("[arg2");
+    });
+
+    it("should include type for numbers", () => {
+      const cli = createTestCli();
+      const schema = t.number({ title: "count" });
+      expect(cli.testGenerateArgsUsage(schema)).toBe(" <count: number>");
+    });
+
+    it("should include type for integers", () => {
+      const cli = createTestCli();
+      const schema = t.integer({ title: "port" });
+      expect(cli.testGenerateArgsUsage(schema)).toBe(" <port: integer>");
+    });
+
+    it("should include type for booleans", () => {
+      const cli = createTestCli();
+      const schema = t.boolean({ title: "force" });
+      expect(cli.testGenerateArgsUsage(schema)).toBe(" <force: boolean>");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getTypeName
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getTypeName", () => {
+    it("should return empty for string", () => {
+      const cli = createTestCli();
+      expect(cli.testGetTypeName(t.string())).toBe("");
+    });
+
+    it("should return ': number' for number", () => {
+      const cli = createTestCli();
+      expect(cli.testGetTypeName(t.number())).toBe(": number");
+    });
+
+    it("should return ': integer' for integer", () => {
+      const cli = createTestCli();
+      expect(cli.testGetTypeName(t.integer())).toBe(": integer");
+    });
+
+    it("should return ': boolean' for boolean", () => {
+      const cli = createTestCli();
+      expect(cli.testGetTypeName(t.boolean())).toBe(": boolean");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // generateColoredArgsUsage
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("generateColoredArgsUsage", () => {
+    it("should return empty string for no schema", () => {
+      const cli = createTestCli();
+      expect(cli.testGenerateColoredArgsUsage(undefined)).toBe("");
+    });
+
+    it("should generate colored optional arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.optional(t.string({ title: "path" }));
+      const result = cli.testGenerateColoredArgsUsage(schema);
+      expect(result).toContain("[path]");
+    });
+
+    it("should generate colored required arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.string({ title: "path" });
+      const result = cli.testGenerateColoredArgsUsage(schema);
+      expect(result).toContain("<path>");
+    });
+
+    it("should generate colored tuple arg usage", () => {
+      const cli = createTestCli();
+      const schema = t.tuple([t.string(), t.optional(t.number())]);
+      const result = cli.testGenerateColoredArgsUsage(schema);
+      expect(result).toContain("<arg1>");
+      expect(result).toContain("[arg2");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // findCommand
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("findCommand", () => {
+    it("should return undefined for unknown command", () => {
+      const cli = createTestCli();
+      expect(cli.testFindCommand("unknown")).toBeUndefined();
+    });
+
+    it("should find command by name", () => {
+      class TestCommands {
+        test = $command({
+          name: "test",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      expect(cli.testFindCommand("test")?.name).toBe("test");
+    });
+
+    it("should find command by alias", () => {
+      class TestCommands {
+        test = $command({
+          name: "test",
+          aliases: ["t"],
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      expect(cli.testFindCommand("t")?.name).toBe("test");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // findPreHooks / findPostHooks
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("findPreHooks", () => {
+    it("should return empty array when no hooks", () => {
+      const cli = createTestCli();
+      expect(cli.testFindPreHooks("build")).toEqual([]);
+    });
+
+    it("should find pre-hooks for command", () => {
+      class TestCommands {
+        preBuild = $command({
+          name: "prebuild",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      expect(cli.testFindPreHooks("build").length).toBe(1);
+    });
+  });
+
+  describe("findPostHooks", () => {
+    it("should return empty array when no hooks", () => {
+      const cli = createTestCli();
+      expect(cli.testFindPostHooks("build")).toEqual([]);
+    });
+
+    it("should find post-hooks for command", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        postBuild = $command({
+          name: "postbuild",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      expect(cli.testFindPostHooks("build").length).toBe(1);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getTopLevelCommands
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getTopLevelCommands", () => {
+    it("should return all commands when no children", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        test = $command({
+          name: "test",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      const topLevel = cli.testGetTopLevelCommands();
+      expect(topLevel.length).toBe(2);
+    });
+
+    it("should exclude child commands", () => {
+      class TestCommands {
+        deployVercel = $command({
+          name: "vercel",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        deploy = $command({
+          name: "deploy",
+          flags: t.object({}),
+          children: [this.deployVercel],
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      const topLevel = cli.testGetTopLevelCommands();
+      expect(topLevel.length).toBe(1);
+      expect(topLevel[0].name).toBe("deploy");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // findParentCommand
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("findParentCommand", () => {
+    it("should return undefined for top-level command", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("build")!;
+
+      expect(cli.testFindParentCommand(cmd)).toBeUndefined();
+    });
+
+    it("should find parent of child command", () => {
+      class TestCommands {
+        deployVercel = $command({
+          name: "vercel",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        deploy = $command({
+          name: "deploy",
+          flags: t.object({}),
+          children: [this.deployVercel],
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const child = cli.testFindCommand("vercel")!;
+
+      expect(cli.testFindParentCommand(child)?.name).toBe("deploy");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getCommandPath
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getCommandPath", () => {
+    it("should return simple name for top-level command", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("build")!;
+
+      expect(cli.testGetCommandPath(cmd)).toBe("build");
+    });
+
+    it("should return full path for nested command", () => {
+      class TestCommands {
+        deployVercel = $command({
+          name: "vercel",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        deploy = $command({
+          name: "deploy",
+          flags: t.object({}),
+          children: [this.deployVercel],
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const child = cli.testFindCommand("vercel")!;
+
+      expect(cli.testGetCommandPath(child)).toBe("deploy vercel");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // printHelp
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("printHelp", () => {
+    it("should print general help when no command provided", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          description: "Build the project",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      // Just verify it doesn't throw
+      expect(() => cli.printHelp()).not.toThrow();
+    });
+
+    it("should print command-specific help", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          description: "Build the project",
+          flags: t.object({
+            watch: t.optional(t.boolean({ description: "Watch for changes" })),
+          }),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("build")!;
+
+      expect(() => cli.printHelp(cmd)).not.toThrow();
+    });
+
+    it("should print help for command with children", () => {
+      class TestCommands {
+        deployVercel = $command({
+          name: "vercel",
+          description: "Deploy to Vercel",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        deploy = $command({
+          name: "deploy",
+          description: "Deploy commands",
+          flags: t.object({}),
+          children: [this.deployVercel],
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("deploy")!;
+
+      expect(() => cli.printHelp(cmd)).not.toThrow();
+    });
+
+    it("should print help for command with env vars", () => {
+      class TestCommands {
+        deploy = $command({
+          name: "deploy",
+          description: "Deploy to production",
+          flags: t.object({}),
+          env: t.object({
+            API_KEY: t.string({ description: "API key for deployment" }),
+            REGION: t.optional(t.string({ description: "Target region" })),
+          }),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("deploy")!;
+
+      expect(() => cli.printHelp(cmd)).not.toThrow();
+    });
+
+    it("should print help for command with mode option", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          description: "Build for environment",
+          flags: t.object({}),
+          mode: "development",
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("build")!;
+
+      expect(() => cli.printHelp(cmd)).not.toThrow();
+    });
+
+    it("should print help for command with args", () => {
+      class TestCommands {
+        greet = $command({
+          name: "greet",
+          description: "Greet someone",
+          flags: t.object({}),
+          args: t.string({ title: "name" }),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+      const cmd = cli.testFindCommand("greet")!;
+
+      expect(() => cli.printHelp(cmd)).not.toThrow();
+    });
+
+    it("should hide commands with hide option in general help", () => {
+      class TestCommands {
+        visible = $command({
+          name: "visible",
+          description: "Visible command",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        hidden = $command({
+          name: "hidden",
+          description: "Hidden command",
+          hide: true,
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      // Just verify it doesn't throw - hidden commands filtered in getTopLevelCommands
+      expect(() => cli.printHelp()).not.toThrow();
+    });
+
+    it("should include flag aliases in help output", () => {
+      const cli = createTestCli();
+
+      const flagsSchema = t.object({
+        target: t.optional(
+          t.enum(["bare", "docker", "vercel"], {
+            aliases: ["t"],
+            description: "Deployment target",
+          }),
+        ),
+        runtime: t.optional(
+          t.enum(["node", "bun"], {
+            alias: "r", // singular alias
+            description: "JavaScript runtime",
+          }),
+        ),
+        verbose: t.optional(
+          t.boolean({
+            description: "Verbose output",
+          }),
+        ),
+      });
+
+      const flagDefs = cli.testExtractFlagDefs(flagsSchema);
+
+      // target should have key + aliases array
+      const targetFlag = flagDefs.find((f) => f.key === "target");
+      expect(targetFlag?.aliases).toContain("target");
+      expect(targetFlag?.aliases).toContain("t");
+      expect(cli.testFormatFlagStr(targetFlag!.aliases)).toBe("-t, --target");
+
+      // runtime should have key + alias (singular)
+      const runtimeFlag = flagDefs.find((f) => f.key === "runtime");
+      expect(runtimeFlag?.aliases).toContain("runtime");
+      expect(runtimeFlag?.aliases).toContain("r");
+      expect(cli.testFormatFlagStr(runtimeFlag!.aliases)).toBe("-r, --runtime");
+
+      // verbose should only have key (no aliases defined)
+      const verboseFlag = flagDefs.find((f) => f.key === "verbose");
+      expect(verboseFlag?.aliases).toEqual(["verbose"]);
+      expect(cli.testFormatFlagStr(verboseFlag!.aliases)).toBe("--verbose");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // getEnumValues
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("getEnumValues", () => {
+    it("should extract values from t.enum schema", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["yarn", "npm", "pnpm", "bun"]);
+
+      const values = cli.testGetEnumValues(schema);
+
+      expect(values).toEqual(["yarn", "npm", "pnpm", "bun"]);
+    });
+
+    it("should return undefined for non-enum schemas", () => {
+      const cli = createTestCli();
+
+      expect(cli.testGetEnumValues(t.string())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.boolean())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.number())).toBeUndefined();
+      expect(cli.testGetEnumValues(t.object({}))).toBeUndefined();
+    });
+
+    it("should return undefined for empty or undefined schema", () => {
+      const cli = createTestCli();
+
+      expect(cli.testGetEnumValues(undefined as any)).toBeUndefined();
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // formatFlagDescription
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("formatFlagDescription", () => {
+    it("should append enum values to description", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["yarn", "npm", "pnpm", "bun"]);
+
+      const result = cli.testFormatFlagDescription(
+        "Package manager to use",
+        schema,
+      );
+
+      expect(result).toContain("Package manager to use");
+      expect(result).toContain("yarn");
+      expect(result).toContain("npm");
+      expect(result).toContain("pnpm");
+      expect(result).toContain("bun");
+    });
+
+    it("should return only enum values when description is empty", () => {
+      const cli = createTestCli();
+      const schema = t.enum(["a", "b", "c"]);
+
+      const result = cli.testFormatFlagDescription(undefined, schema);
+
+      expect(result).toContain("a");
+      expect(result).toContain("b");
+      expect(result).toContain("c");
+    });
+
+    it("should return original description for non-enum schemas", () => {
+      const cli = createTestCli();
+
+      expect(cli.testFormatFlagDescription("A string flag", t.string())).toBe(
+        "A string flag",
+      );
+      expect(cli.testFormatFlagDescription("A boolean flag", t.boolean())).toBe(
+        "A boolean flag",
+      );
+    });
+
+    it("should return empty string when no description and no enum", () => {
+      const cli = createTestCli();
+
+      expect(cli.testFormatFlagDescription(undefined, t.string())).toBe("");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // commands getter
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("commands", () => {
+    it("should return all registered commands", () => {
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+        test = $command({
+          name: "test",
+          flags: t.object({}),
+          handler: async () => {},
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(TestCliProvider);
+
+      expect(cli.commands.length).toBe(2);
+      expect(cli.commands.map((c) => c.name).sort()).toEqual(["build", "test"]);
+    });
+
+    it("should return empty array when no commands", () => {
+      const cli = createTestCli();
+      expect(cli.commands).toEqual([]);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // run (test helper)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  describe("run", () => {
+    it("should execute command with string args", async () => {
+      let capturedFlags: Record<string, unknown> = {};
+
+      class TestCommands {
+        build = $command({
+          name: "build",
+          flags: t.object({
+            watch: t.optional(t.boolean()),
+          }),
+          handler: async ({ flags }) => {
+            capturedFlags = flags;
+          },
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(CliProvider);
+      const cmd = alepha.inject(TestCommands);
+
+      await cli.run(cmd.build, "--watch");
+
+      expect(capturedFlags.watch).toBe(true);
+    });
+
+    it("should execute command with array args", async () => {
+      let capturedFlags: Record<string, unknown> = {};
+
+      class TestCommands {
+        greet = $command({
+          name: "greet",
+          flags: t.object({
+            name: t.optional(t.string()),
+          }),
+          handler: async ({ flags }) => {
+            capturedFlags = flags;
+          },
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(CliProvider);
+      const cmd = alepha.inject(TestCommands);
+
+      await cli.run(cmd.greet, ["--name", "World"]);
+
+      expect(capturedFlags.name).toBe("World");
+    });
+
+    it("should execute command with options object", async () => {
+      let capturedRoot = "";
+
+      class TestCommands {
+        init = $command({
+          name: "init",
+          flags: t.object({}),
+          handler: async ({ root }) => {
+            capturedRoot = root;
+          },
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(CliProvider);
+      const cmd = alepha.inject(TestCommands);
+
+      await cli.run(cmd.init, { root: "/custom/path" });
+
+      expect(capturedRoot).toBe("/custom/path");
+    });
+
+    it("should parse command args", async () => {
+      let capturedArgs: unknown;
+
+      class TestCommands {
+        greet = $command({
+          name: "greet",
+          flags: t.object({}),
+          args: t.string(),
+          handler: async ({ args }) => {
+            capturedArgs = args;
+          },
+        });
+      }
+
+      const alepha = Alepha.create().with(TestCommands);
+      const cli = alepha.inject(CliProvider);
+      const cmd = alepha.inject(TestCommands);
+
+      await cli.run(cmd.greet, "World");
+
+      expect(capturedArgs).toBe("World");
+    });
+  });
+});