@enactprotocol/cli 2.1.5 → 2.1.7

package/tests/commands/init.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
 import { configureInitCommand } from "../../src/commands/init";
@@ -107,7 +107,59 @@ describe("init command", () => {
       }
     });
 
-    test("default mode creates enact.md", async () => {
+    test("default mode creates AGENTS.md for tool consumers", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const agentsPath = join(testDir, "AGENTS.md");
+      expect(existsSync(agentsPath)).toBe(true);
+
+      const content = readFileSync(agentsPath, "utf-8");
+      expect(content).toContain("enact search");
+      expect(content).toContain("enact install");
+      expect(content).toContain("Finding & Installing Tools");
+
+      // Should NOT create enact.md in default mode
+      const manifestPath = join(testDir, "enact.md");
+      expect(existsSync(manifestPath)).toBe(false);
+    });
+
+    test("default mode creates .enact/tools.json", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const toolsJsonPath = join(testDir, ".enact", "tools.json");
+      expect(existsSync(toolsJsonPath)).toBe(true);
+
+      const content = JSON.parse(readFileSync(toolsJsonPath, "utf-8"));
+      expect(content).toEqual({ tools: {} });
+    });
+
+    test("--tool mode creates enact.md", async () => {
       const program = new Command();
       program.exitOverride(); // Prevent process.exit
       configureInitCommand(program);
@@ -117,7 +169,7 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "test/my-tool"]);
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/my-tool"]);
       } catch {
         // Command may throw due to exitOverride
       } finally {
@@ -133,7 +185,7 @@ describe("init command", () => {
       expect(content).toContain("command:");
     });
 
-    test("default mode creates AGENTS.md for tool development", async () => {
+    test("--tool mode creates AGENTS.md for tool development", async () => {
       const program = new Command();
       program.exitOverride();
       configureInitCommand(program);
@@ -142,7 +194,7 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "test/my-tool"]);
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/my-tool"]);
       } catch {
         // Command may throw due to exitOverride
       } finally {
@@ -215,6 +267,134 @@ describe("init command", () => {
       expect(existsSync(join(testDir, "AGENTS.md"))).toBe(false);
     });
 
+    test("--agent mode creates .enact/tools.json", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--agent"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const toolsJsonPath = join(testDir, ".enact", "tools.json");
+      expect(existsSync(toolsJsonPath)).toBe(true);
+
+      const content = JSON.parse(readFileSync(toolsJsonPath, "utf-8"));
+      expect(content).toEqual({ tools: {} });
+    });
+
+    test("--claude mode creates .enact/tools.json", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--claude"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const toolsJsonPath = join(testDir, ".enact", "tools.json");
+      expect(existsSync(toolsJsonPath)).toBe(true);
+
+      const content = JSON.parse(readFileSync(toolsJsonPath, "utf-8"));
+      expect(content).toEqual({ tools: {} });
+    });
+
+    test("--agent mode with --force overwrites existing .enact/tools.json", async () => {
+      // Create existing .enact/tools.json with some content
+      const enactDir = join(testDir, ".enact");
+      mkdirSync(enactDir, { recursive: true });
+      const toolsJsonPath = join(enactDir, "tools.json");
+      const existingContent = { tools: { "some/tool": "1.0.0" } };
+      writeFileSync(toolsJsonPath, JSON.stringify(existingContent));
+
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--agent", "--force"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const content = JSON.parse(readFileSync(toolsJsonPath, "utf-8"));
+      expect(content).toEqual({ tools: {} });
+    });
+
+    test("--agent mode preserves existing .enact/tools.json without --force", async () => {
+      // Create existing .enact/tools.json with some content
+      const enactDir = join(testDir, ".enact");
+      mkdirSync(enactDir, { recursive: true });
+      const toolsJsonPath = join(enactDir, "tools.json");
+      const existingContent = { tools: { "some/tool": "1.0.0" } };
+      writeFileSync(toolsJsonPath, JSON.stringify(existingContent));
+
+      // Also create AGENTS.md so the command doesn't fail early
+      writeFileSync(join(testDir, "AGENTS.md"), "existing");
+
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        // Without --force, AGENTS.md check will fail and return early
+        // So we need to test with --force on AGENTS.md but not tools.json
+        // Actually the --force flag applies to both, so let's just verify
+        // tools.json is preserved when it exists and no --force
+        await program.parseAsync(["node", "test", "init", "--agent"]);
+      } catch {
+        // Command may throw due to exitOverride or warning about existing file
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      // tools.json should be preserved since AGENTS.md existed and no --force was used
+      const content = JSON.parse(readFileSync(toolsJsonPath, "utf-8"));
+      expect(content).toEqual(existingContent);
+    });
+
+    test("--tool mode does NOT create .enact/tools.json", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/my-tool"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const toolsJsonPath = join(testDir, ".enact", "tools.json");
+      expect(existsSync(toolsJsonPath)).toBe(false);
+    });
+
     test("enact.md contains valid YAML frontmatter", async () => {
       const program = new Command();
       program.exitOverride();
@@ -224,7 +404,14 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "myorg/utils/greeter"]);
+        await program.parseAsync([
+          "node",
+          "test",
+          "init",
+          "--tool",
+          "--name",
+          "myorg/utils/greeter",
+        ]);
       } catch {
         // Command may throw due to exitOverride
       } finally {
@@ -255,7 +442,7 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/tool"]);
       } catch {
         // Command may throw due to exitOverride
       } finally {
@@ -299,16 +486,16 @@ describe("init command", () => {
   });
 
   describe("option conflicts", () => {
-    test("--tool is the default when no mode specified", () => {
+    test("--agent is the default when no mode specified", () => {
       const program = new Command();
       configureInitCommand(program);
 
       const initCmd = program.commands.find((cmd) => cmd.name() === "init");
       const opts = initCmd?.options ?? [];
-      const toolOpt = opts.find((o) => o.long === "--tool");
+      const agentOpt = opts.find((o) => o.long === "--agent");
 
       // Description should indicate it's the default
-      expect(toolOpt?.description).toContain("default");
+      expect(agentOpt?.description).toContain("default");
     });
   });
 
@@ -328,7 +515,7 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/tool"]);
       } catch {
         // Command may throw due to exitOverride
       } finally {
@@ -367,7 +554,7 @@ describe("init command", () => {
       process.chdir(testDir);
 
       try {
-        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+        await program.parseAsync(["node", "test", "init", "--tool", "--name", "test/tool"]);
       } catch {
         // Command may throw due to exitOverride
       } finally {

package/tests/commands/learn.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Tests for the learn command
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { ToolVersionInfo } from "@enactprotocol/api";
+import { Command } from "commander";
+import { configureLearnCommand } from "../../src/commands/learn";
+
+describe("learn command", () => {
+  describe("command configuration", () => {
+    test("configures learn command on program", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      expect(learnCmd).toBeDefined();
+    });
+
+    test("has correct description", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      expect(learnCmd?.description()).toBe("Display documentation (enact.md) for a tool");
+    });
+
+    test("accepts tool argument", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      const args = learnCmd?.registeredArguments ?? [];
+      expect(args.length).toBeGreaterThan(0);
+      expect(args[0]?.name()).toBe("tool");
+    });
+
+    test("has --ver option for specifying version", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      const opts = learnCmd?.options ?? [];
+      const verOpt = opts.find((o) => o.long === "--ver");
+      expect(verOpt).toBeDefined();
+    });
+
+    test("has --json option", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      const opts = learnCmd?.options ?? [];
+      const jsonOpt = opts.find((o) => o.long === "--json");
+      expect(jsonOpt).toBeDefined();
+    });
+
+    test("does not have --verbose option (always shows full docs)", () => {
+      const program = new Command();
+      configureLearnCommand(program);
+
+      const learnCmd = program.commands.find((cmd) => cmd.name() === "learn");
+      const opts = learnCmd?.options ?? [];
+      const verboseOpt = opts.find((o) => o.long === "--verbose");
+      expect(verboseOpt).toBeUndefined();
+    });
+  });
+
+  describe("tool name parsing", () => {
+    test("parses simple tool name", () => {
+      const toolName = "my-tool";
+      expect(toolName).not.toContain("@");
+      expect(toolName).not.toContain("/");
+    });
+
+    test("parses namespaced tool name", () => {
+      const toolName = "enact/context7/docs";
+      const parts = toolName.split("/");
+      expect(parts[0]).toBe("enact");
+      expect(parts[1]).toBe("context7");
+      expect(parts[2]).toBe("docs");
+    });
+
+    test("parses scoped tool name", () => {
+      const toolName = "@org/my-tool";
+      expect(toolName.startsWith("@")).toBe(true);
+      const parts = toolName.slice(1).split("/");
+      expect(parts[0]).toBe("org");
+      expect(parts[1]).toBe("my-tool");
+    });
+  });
+
+  describe("documentation content", () => {
+    test("ToolVersionInfo type includes rawManifest field for enact.md content", () => {
+      const mockVersion: ToolVersionInfo = {
+        name: "test/tool",
+        version: "1.0.0",
+        description: "Test tool",
+        license: "MIT",
+        yanked: false,
+        manifest: { enact: "2.0.0" },
+        rawManifest: "---\nenact: 2.0.0\n---\n# Test Tool\n\nThis is a test tool.",
+        bundle: {
+          hash: "sha256:abc123",
+          size: 1024,
+          downloadUrl: "https://example.com/bundle.tar.gz",
+        },
+        attestations: [],
+        publishedBy: { username: "testuser" },
+        publishedAt: new Date(),
+        downloads: 100,
+      };
+
+      expect(mockVersion.rawManifest).toBeDefined();
+      expect(mockVersion.rawManifest).toContain("# Test Tool");
+    });
+
+    test("ToolVersionInfo allows undefined rawManifest", () => {
+      const mockVersion: ToolVersionInfo = {
+        name: "test/tool",
+        version: "1.0.0",
+        description: "Test tool",
+        license: "MIT",
+        yanked: false,
+        manifest: { enact: "2.0.0" },
+        // rawManifest is optional - not provided
+        bundle: {
+          hash: "sha256:abc123",
+          size: 1024,
+          downloadUrl: "https://example.com/bundle.tar.gz",
+        },
+        attestations: [],
+        publishedBy: { username: "testuser" },
+        publishedAt: new Date(),
+        downloads: 100,
+      };
+
+      expect(mockVersion.rawManifest).toBeUndefined();
+    });
+
+    test("enact.md content should contain frontmatter and markdown", () => {
+      const enactMdContent = `---
+enact: 2.0.0
+name: test/tool
+version: 1.0.0
+---
+
+# Test Tool
+
+Documentation here.`;
+
+      // Verify frontmatter is present
+      expect(enactMdContent).toContain("---");
+      expect(enactMdContent).toContain("enact: 2.0.0");
+
+      // Verify markdown content
+      expect(enactMdContent).toContain("# Test Tool");
+      expect(enactMdContent).toContain("Documentation here.");
+    });
+
+    test("documentation includes parameter descriptions", () => {
+      const enactMdContent = `---
+enact: 2.0.0
+name: enact/context7/docs
+version: 1.0.0
+inputSchema:
+  type: object
+  properties:
+    library_name:
+      type: string
+      description: The name of the library to fetch documentation for
+---
+
+# Context7 Documentation Fetcher
+
+Fetches up-to-date documentation for any library.
+
+## Parameters
+
+- **library_name** (required): The name of the library to fetch documentation for
+`;
+
+      expect(enactMdContent).toContain("library_name");
+      expect(enactMdContent).toContain("Parameters");
+      expect(enactMdContent).toContain("required");
+    });
+
+    test("documentation includes usage examples", () => {
+      const enactMdContent = `---
+enact: 2.0.0
+name: test/tool
+---
+
+# Test Tool
+
+## Usage
+
+\`\`\`bash
+enact run test/tool --input '{"query": "hello"}'
+\`\`\`
+`;
+
+      expect(enactMdContent).toContain("## Usage");
+      expect(enactMdContent).toContain("enact run");
+    });
+  });
+
+  describe("JSON output format", () => {
+    test("JSON output includes name, version, and documentation", () => {
+      const jsonOutput = {
+        name: "enact/context7/docs",
+        version: "1.0.1",
+        documentation: "---\nenact: 2.0.0\n---\n# Context7 Docs\n\nFetches documentation.",
+      };
+
+      expect(jsonOutput.name).toBe("enact/context7/docs");
+      expect(jsonOutput.version).toBe("1.0.1");
+      expect(jsonOutput.documentation).toContain("# Context7 Docs");
+    });
+
+    test("JSON output handles missing documentation", () => {
+      const jsonOutput = {
+        name: "test/tool",
+        version: "1.0.0",
+        documentation: null,
+      };
+
+      expect(jsonOutput.documentation).toBeNull();
+    });
+  });
+});

package/tests/commands/run.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
 import { configureRunCommand } from "../../src/commands/run";
@@ -71,6 +71,16 @@ describe("run command", () => {
       expect(inputOpt).toBeDefined();
     });
 
+    test("has --input-file option for JSON file input", () => {
+      const program = new Command();
+      configureRunCommand(program);
+
+      const runCmd = program.commands.find((cmd) => cmd.name() === "run");
+      const opts = runCmd?.options ?? [];
+      const inputFileOpt = opts.find((o) => o.long === "--input-file");
+      expect(inputFileOpt).toBeDefined();
+    });
+
     test("has --timeout option", () => {
       const program = new Command();
       configureRunCommand(program);
@@ -228,4 +238,63 @@ describe("run command", () => {
       expect(parseTimeout("30")).toBe(30000);
     });
   });
+
+  describe("input file handling", () => {
+    test("JSON input file can be parsed", () => {
+      // Create a test JSON file
+      const inputFilePath = join(FIXTURES_DIR, "test-inputs.json");
+      const inputData = { name: "Alice", count: 5, nested: { key: "value" } };
+      writeFileSync(inputFilePath, JSON.stringify(inputData));
+
+      // Verify the file can be read and parsed
+      const content = require("node:fs").readFileSync(inputFilePath, "utf-8");
+      const parsed = JSON.parse(content);
+
+      expect(parsed.name).toBe("Alice");
+      expect(parsed.count).toBe(5);
+      expect(parsed.nested.key).toBe("value");
+    });
+
+    test("JSON input file with optional params can omit them", () => {
+      // This is the recommended pattern for optional params
+      const inputFilePath = join(FIXTURES_DIR, "optional-inputs.json");
+      // Only required param provided, optional params omitted
+      const inputData = { name: "Alice" };
+      writeFileSync(inputFilePath, JSON.stringify(inputData));
+
+      const content = require("node:fs").readFileSync(inputFilePath, "utf-8");
+      const parsed = JSON.parse(content);
+
+      expect(parsed.name).toBe("Alice");
+      expect(parsed.greeting).toBeUndefined();
+    });
+
+    test("JSON input file with explicit empty values", () => {
+      // User can explicitly set empty values for optional params
+      const inputFilePath = join(FIXTURES_DIR, "explicit-empty.json");
+      const inputData = { name: "Alice", prefix: "", suffix: null };
+      writeFileSync(inputFilePath, JSON.stringify(inputData));
+
+      const content = require("node:fs").readFileSync(inputFilePath, "utf-8");
+      const parsed = JSON.parse(content);
+
+      expect(parsed.name).toBe("Alice");
+      expect(parsed.prefix).toBe("");
+      expect(parsed.suffix).toBeNull();
+    });
+
+    test("input priority: --input overrides --args overrides --input-file", () => {
+      // Simulate the merge logic from parseInputArgs
+      const fromFile = { a: "file", b: "file", c: "file" };
+      const fromArgs = { b: "args", c: "args" };
+      const fromInput = { c: "input" };
+
+      // Merge in order: file -> args -> input
+      const merged = { ...fromFile, ...fromArgs, ...fromInput };
+
+      expect(merged.a).toBe("file"); // Only from file
+      expect(merged.b).toBe("args"); // Overridden by args
+      expect(merged.c).toBe("input"); // Overridden by input
+    });
+  });
 });