@pablozaiden/terminatui 0.2.0 → 0.3.0-beta-1

package/src/__tests__/helpCore.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test";
+import {
+  formatExamples,
+  formatOptionSchema,
+  formatOptions,
+  formatSubCommands,
+  formatUsage,
+  generateAppHelp,
+  generateCommandHelp,
+} from "../core/help.ts";
+import { Command } from "../core/command.ts";
+import type { OptionSchema } from "../types/command.ts";
+
+class SimpleCommand extends Command<OptionSchema> {
+  readonly name: string;
+  readonly description: string;
+  readonly options: OptionSchema;
+
+  constructor(config: { name: string; description: string; options?: OptionSchema }) {
+    super();
+    this.name = config.name;
+    this.description = config.description;
+    this.options = config.options ?? {};
+  }
+
+  override async execute(): Promise<void> {}
+}
+
+describe("Help Generation (core)", () => {
+  describe("formatUsage", () => {
+    test("formats basic usage and includes tokens", () => {
+      const cmd = new SimpleCommand({
+        name: "parent",
+        description: "Parent",
+        options: { verbose: { type: "boolean", description: "Verbose" } },
+      });
+      cmd.subCommands = [new SimpleCommand({ name: "child", description: "Child" })];
+
+      const usage = formatUsage(cmd, { appName: "myapp" });
+      expect(usage).toContain("myapp");
+      expect(usage).toContain("parent");
+      expect(usage).toContain("[command]");
+      expect(usage).toContain("[options]");
+    });
+  });
+
+  describe("formatSubCommands", () => {
+    test("formats subcommands list", () => {
+      const cmd = new SimpleCommand({ name: "parent", description: "Parent" });
+      cmd.subCommands = [new SimpleCommand({ name: "child", description: "Child command" })];
+
+      const commands = formatSubCommands(cmd);
+      expect(commands).toContain("child");
+      expect(commands).toContain("Child command");
+    });
+
+    test("returns empty for no subcommands", () => {
+      const cmd = new SimpleCommand({ name: "test", description: "Test" });
+      const commands = formatSubCommands(cmd);
+      expect(commands).toBe("");
+    });
+  });
+
+  describe("formatOptions", () => {
+    test("formats options with descriptions", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "Test",
+        options: { verbose: { type: "boolean", description: "Enable verbose" } },
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("--verbose");
+      expect(options).toContain("Enable verbose");
+    });
+
+    test("shows option aliases", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "Test",
+        options: { verbose: { type: "boolean", alias: "v", description: "Verbose" } },
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("-v");
+    });
+
+    test("shows default values", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "Test",
+        options: { count: { type: "number", default: 10, description: "Count" } },
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("10");
+    });
+
+    test("shows required marker", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "Test",
+        options: { name: { type: "string", required: true, description: "Name" } },
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("required");
+    });
+
+    test("shows enum values", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          level: {
+            type: "string",
+            enum: ["low", "high"],
+            description: "Level",
+          },
+        },
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("low");
+      expect(options).toContain("high");
+    });
+
+    test("returns empty for no options", () => {
+      const cmd = new SimpleCommand({ name: "test", description: "Test" });
+      const options = formatOptions(cmd);
+      expect(options).toBe("");
+    });
+  });
+
+  describe("formatExamples", () => {
+    test("formats examples list and empty state", () => {
+      const cmd = new SimpleCommand({ name: "test", description: "Test" });
+      cmd.examples = [{ command: "test --verbose", description: "Run with verbose" }];
+
+      expect(formatExamples(cmd)).toContain("test --verbose");
+      expect(formatExamples(cmd)).toContain("Run with verbose");
+
+      const noExamples = new SimpleCommand({ name: "empty", description: "Empty" });
+      expect(formatExamples(noExamples)).toBe("");
+    });
+  });
+
+  describe("generateCommandHelp", () => {
+    test("includes usage, description, and options section", () => {
+      const cmd = new SimpleCommand({
+        name: "test",
+        description: "A test command for testing",
+        options: { verbose: { type: "boolean", description: "Verbose mode" } },
+      });
+
+      const help = generateCommandHelp(cmd, { appName: "myapp" });
+      expect(help).toContain("Usage:");
+      expect(help).toContain("A test command for testing");
+      expect(help).toContain("Options:");
+      expect(help).toContain("--verbose");
+      expect(help).toContain("--verbose, --no-verbose");
+    });
+  });
+
+  describe("generateAppHelp", () => {
+    test("generates root help with commands", () => {
+      const commands = [new SimpleCommand({ name: "run", description: "Run something" })];
+      const help = generateAppHelp(commands, { appName: "myapp" });
+      expect(help).toContain("Commands:");
+      expect(help).toContain("run");
+    });
+  });
+
+  describe("Global Options section", () => {
+    test("modes via schema and includes mode", () => {
+      const global = formatOptionSchema("Global Options", {
+        "log-level": { type: "string", description: "Minimum log level" },
+        mode: {
+          type: "string",
+          enum: ["opentui", "ink", "cli", "default"],
+          default: "default",
+          description: "Mode",
+        },
+      });
+
+      expect(global).toContain("Global Options");
+      expect(global).toContain("--log-level");
+      expect(global).toContain("--mode");
+      expect(global).toContain("opentui");
+      expect(global).toContain("ink");
+      expect(global).toContain("cli");
+      expect(global).toContain("default");
+      expect(global).toContain("[default: default]");
+    });
+
+    test("generateCommandHelp includes global options when provided", () => {
+      const cmd = new SimpleCommand({ name: "test", description: "Test" });
+      const help = generateCommandHelp(cmd, {
+        appName: "myapp",
+        globalOptionsSchema: {
+          mode: {
+            type: "string",
+            enum: ["opentui", "ink", "cli", "default"],
+            default: "default",
+            description: "Mode",
+          },
+        },
+      });
+
+      expect(help).toContain("Global Options");
+      expect(help).toContain("--mode");
+    });
+
+    test("generateAppHelp includes global options when provided", () => {
+      const commands = [new SimpleCommand({ name: "run", description: "Run something" })];
+      const help = generateAppHelp(commands, {
+        appName: "myapp",
+        globalOptionsSchema: {
+          mode: { type: "string", enum: ["opentui", "ink", "cli", "default"], description: "Mode" },
+        },
+      });
+
+      expect(help).toContain("Global Options");
+      expect(help).toContain("--mode");
+    });
+  });
+});

package/src/__tests__/parser.test.ts

@@ -1,268 +1,122 @@
-import { test, expect, describe } from "bun:test";
+import { describe, expect, test } from "bun:test";
 import {
   extractCommandChain,
-  schemaToParseArgsOptions,
   parseOptionValues,
+  schemaToParseArgsOptions,
   validateOptions,
-  parseCliArgs,
 } from "../cli/parser.ts";
 import type { OptionSchema } from "../types/command.ts";
-import { defineCommand } from "../types/command.ts";
-
-describe("extractCommandChain", () => {
-  test("extracts command path with no flags", () => {
-    const result = extractCommandChain(["run", "test"]);
-    expect(result.commands).toEqual(["run", "test"]);
-    expect(result.remaining).toEqual([]);
-  });
-
-  test("separates commands from flags", () => {
-    const result = extractCommandChain(["run", "--verbose", "file.ts"]);
-    expect(result.commands).toEqual(["run"]);
-    expect(result.remaining).toEqual(["--verbose", "file.ts"]);
-  });
-
-  test("handles args starting with flags", () => {
-    const result = extractCommandChain(["--help"]);
-    expect(result.commands).toEqual([]);
-    expect(result.remaining).toEqual(["--help"]);
-  });
-
-  test("handles short flags", () => {
-    const result = extractCommandChain(["run", "-v"]);
-    expect(result.commands).toEqual(["run"]);
-    expect(result.remaining).toEqual(["-v"]);
-  });
-
-  test("handles empty args", () => {
-    const result = extractCommandChain([]);
-    expect(result.commands).toEqual([]);
-    expect(result.remaining).toEqual([]);
-  });
-
-  test("extracts nested command path", () => {
-    const result = extractCommandChain(["config", "set", "--key", "value"]);
-    expect(result.commands).toEqual(["config", "set"]);
-    expect(result.remaining).toEqual(["--key", "value"]);
-  });
-});
-
-describe("schemaToParseArgsOptions", () => {
-  test("converts string option", () => {
-    const schema: OptionSchema = {
-      name: { type: "string", description: "Name" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    expect(result.options!["name"]?.type).toBe("string");
-  });
-
-  test("converts boolean option", () => {
-    const schema: OptionSchema = {
-      verbose: { type: "boolean", description: "Verbose" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    expect(result.options!["verbose"]?.type).toBe("boolean");
-  });
-
-  test("converts alias to short", () => {
-    const schema: OptionSchema = {
-      verbose: { type: "boolean", alias: "v", description: "Verbose" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    expect(result.options!["verbose"]?.short).toBe("v");
-  });
-
-  test("converts array option to multiple", () => {
-    const schema: OptionSchema = {
-      files: { type: "array", description: "Files" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    expect(result.options!["files"]?.multiple).toBe(true);
-  });
-
-  test("includes default values", () => {
-    const schema: OptionSchema = {
-      count: { type: "number", default: 10, description: "Count" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    // parseArgs expects string defaults for non-boolean types
-    expect(result.options!["count"]?.default).toBe("10");
-  });
-
-  test("includes default values for boolean", () => {
-    const schema: OptionSchema = {
-      verbose: { type: "boolean", default: false, description: "Verbose" },
-    };
-    const result = schemaToParseArgsOptions(schema);
-    // Boolean defaults remain as boolean
-    expect(result.options!["verbose"]?.default).toBe(false);
-  });
-});
-
-describe("parseOptionValues", () => {
-  test("passes through string values", () => {
-    const schema: OptionSchema = {
-      name: { type: "string", description: "Name" },
-    };
-    const result = parseOptionValues(schema, { name: "test" });
-    expect(result["name"]).toBe("test");
-  });
-
-  test("coerces number values", () => {
-    const schema: OptionSchema = {
-      count: { type: "number", description: "Count" },
-    };
-    const result = parseOptionValues(schema, { count: "42" });
-    expect(result["count"]).toBe(42);
-  });
 
-  test("coerces boolean values", () => {
-    const schema: OptionSchema = {
-      verbose: { type: "boolean", description: "Verbose" },
-    };
-    const result = parseOptionValues(schema, { verbose: "true" });
-    expect(result["verbose"]).toBe(true);
-  });
-
-  test("applies default values", () => {
-    const schema: OptionSchema = {
-      count: { type: "number", default: 5, description: "Count" },
-    };
-    const result = parseOptionValues(schema, {});
-    expect(result["count"]).toBe(5);
-  });
-
-  test("reads from environment variables", () => {
-    process.env["TEST_VALUE"] = "env-value";
-    const schema: OptionSchema = {
-      value: { type: "string", env: "TEST_VALUE", description: "Value" },
-    };
-    const result = parseOptionValues(schema, {});
-    expect(result["value"]).toBe("env-value");
-    delete process.env["TEST_VALUE"];
-  });
-
-  test("validates enum values", () => {
-    const schema: OptionSchema = {
-      level: {
-        type: "string",
-        enum: ["low", "medium", "high"],
-        description: "Level",
-      },
-    };
-    const result = parseOptionValues(schema, { level: "medium" });
-    expect(result["level"]).toBe("medium");
-  });
-
-  test("throws on invalid enum value", () => {
-    const schema: OptionSchema = {
-      level: {
-        type: "string",
-        enum: ["low", "medium", "high"],
-        description: "Level",
-      },
-    };
-    expect(() => parseOptionValues(schema, { level: "invalid" })).toThrow();
-  });
-});
-
-describe("validateOptions", () => {
-  test("returns empty array for valid options", () => {
-    const schema: OptionSchema = {
-      name: { type: "string", description: "Name" },
-    };
-    const errors = validateOptions(schema, { name: "test" });
-    expect(errors).toEqual([]);
-  });
-
-  test("returns error for missing required option", () => {
-    const schema: OptionSchema = {
-      name: { type: "string", required: true, description: "Name" },
-    };
-    const errors = validateOptions(schema, {} as Record<string, unknown>);
-    expect(errors.length).toBeGreaterThan(0);
-    expect(errors[0]?.type).toBe("missing_required");
-  });
-
-  test("validates number min/max", () => {
-    const schema: OptionSchema = {
-      count: { type: "number", min: 1, max: 10, description: "Count" },
-    };
-    const errors = validateOptions(schema, { count: 0 });
-    expect(errors.length).toBeGreaterThan(0);
-    expect(errors[0]?.type).toBe("validation");
-  });
-});
-
-describe("parseCliArgs", () => {
-  test("parses command name", () => {
-    const cmd = defineCommand({
-      name: "run",
-      description: "Run command",
-      execute: () => {},
-    });
-
-    const result = parseCliArgs({
-      args: ["run"],
-      commands: { run: cmd },
+describe("cli/parser helpers", () => {
+  describe("extractCommandChain", () => {
+    test("splits commands from flags", () => {
+      const cases: Array<{
+        args: string[];
+        expected: { commands: string[]; remaining: string[] };
+      }> = [
+        { args: ["run", "test"], expected: { commands: ["run", "test"], remaining: [] } },
+        {
+          args: ["run", "--verbose", "file.ts"],
+          expected: { commands: ["run"], remaining: ["--verbose", "file.ts"] },
+        },
+        { args: ["--help"], expected: { commands: [], remaining: ["--help"] } },
+        { args: ["run", "-v"], expected: { commands: ["run"], remaining: ["-v"] } },
+        { args: [], expected: { commands: [], remaining: [] } },
+        {
+          args: ["config", "set", "--key", "value"],
+          expected: { commands: ["config", "set"], remaining: ["--key", "value"] },
+        },
+      ];
+
+      for (const c of cases) {
+        expect(extractCommandChain(c.args)).toEqual(c.expected);
+      }
     });
-
-    expect(result.command).toBe(cmd);
-    expect(result.commandPath).toEqual(["run"]);
   });
 
-  test("detects help flag", () => {
-    const cmd = defineCommand({
-      name: "run",
-      description: "Run command",
-      execute: () => {},
-    });
-
-    const result = parseCliArgs({
-      args: ["run", "--help"],
-      commands: { run: cmd },
+  describe("schemaToParseArgsOptions", () => {
+    test("converts OptionSchema to parseArgs config", () => {
+      const schema: OptionSchema = {
+        name: { type: "string", description: "Name" },
+        verbose: { type: "boolean", alias: "v", default: false, description: "Verbose" },
+        files: { type: "array", description: "Files" },
+        count: { type: "number", default: 10, description: "Count" },
+      };
+
+      const result = schemaToParseArgsOptions(schema);
+
+      expect(result.options?.["name"]).toMatchObject({ type: "string" });
+      expect(result.options?.["verbose"]).toMatchObject({
+        type: "boolean",
+        short: "v",
+        default: false,
+      });
+      expect(result.options?.["files"]).toMatchObject({ multiple: true });
+      // parseArgs expects string defaults for non-boolean types
+      expect(result.options?.["count"]).toMatchObject({ type: "string", default: "10" });
     });
-
-    expect(result.showHelp).toBe(true);
   });
 
-  test("detects -h flag", () => {
-    const cmd = defineCommand({
-      name: "run",
-      description: "Run command",
-      execute: () => {},
+  describe("parseOptionValues", () => {
+    test("coerces values, applies defaults, and reads env", () => {
+      process.env["TEST_VALUE"] = "env-value";
+
+      const schema: OptionSchema = {
+        name: { type: "string", description: "Name" },
+        count: { type: "number", default: 5, description: "Count" },
+        verbose: { type: "boolean", description: "Verbose" },
+        value: { type: "string", env: "TEST_VALUE", description: "Value" },
+        level: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+          description: "Level",
+        },
+      };
+
+      const result = parseOptionValues(schema, {
+        name: "test",
+        count: "42",
+        verbose: "true",
+        level: "medium",
+      });
+
+      expect(result["name"]).toBe("test");
+      expect(result["count"]).toBe(42);
+      expect(result["verbose"]).toBe(true);
+      expect(result["value"]).toBe("env-value");
+      expect(result["level"]).toBe("medium");
+
+      delete process.env["TEST_VALUE"];
     });
 
-    const result = parseCliArgs({
-      args: ["run", "-h"],
-      commands: { run: cmd },
-    });
+    test("throws on invalid enum", () => {
+      const schema: OptionSchema = {
+        level: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+          description: "Level",
+        },
+      };
 
-    expect(result.showHelp).toBe(true);
+      expect(() => parseOptionValues(schema, { level: "invalid" })).toThrow();
+    });
   });
 
-  test("returns error for unknown command", () => {
-    const result = parseCliArgs({
-      args: ["unknown"],
-      commands: {},
-    });
+  describe("validateOptions", () => {
+    test("returns errors for missing required and invalid ranges", () => {
+      const schema: OptionSchema = {
+        name: { type: "string", required: true, description: "Name" },
+        count: { type: "number", min: 1, max: 10, description: "Count" },
+      };
 
-    expect(result.error?.type).toBe("unknown_command");
-  });
+      expect(validateOptions(schema, { name: "ok", count: 5 })).toEqual([]);
 
-  test("uses default command if provided", () => {
-    const cmd = defineCommand({
-      name: "default",
-      description: "Default command",
-      execute: () => {},
-    });
+      const missing = validateOptions(schema, {} as Record<string, unknown>);
+      expect(missing.some((e) => e.type === "missing_required" && e.field === "name")).toBe(true);
 
-    const result = parseCliArgs({
-      args: [],
-      commands: { default: cmd },
-      defaultCommand: "default",
+      const tooLow = validateOptions(schema, { name: "ok", count: 0 });
+      expect(tooLow.some((e) => e.type === "validation" && e.field === "count")).toBe(true);
     });
-
-    expect(result.command).toBe(cmd);
   });
 });
+