@enactprotocol/cli 2.1.5 → 2.1.6

package/src/commands/learn/index.ts

@@ -0,0 +1,107 @@
+/**
+ * enact learn command
+ *
+ * Display the documentation (enact.md) for a tool.
+ * Fetches and displays the raw manifest content for easy reading.
+ */
+
+import { createApiClient, getToolInfo, getToolVersion } from "@enactprotocol/api";
+import { loadConfig } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import { dim, error, formatError, header, json, newline } from "../../utils";
+
+interface LearnOptions extends GlobalOptions {
+  ver?: string;
+}
+
+/**
+ * Learn command handler
+ */
+async function learnHandler(
+  toolName: string,
+  options: LearnOptions,
+  _ctx: CommandContext
+): Promise<void> {
+  const config = loadConfig();
+  const registryUrl =
+    process.env.ENACT_REGISTRY_URL ??
+    config.registry?.url ??
+    "https://siikwkfgsmouioodghho.supabase.co/functions/v1";
+  const authToken = config.registry?.authToken;
+  const client = createApiClient({
+    baseUrl: registryUrl,
+    authToken: authToken,
+  });
+
+  try {
+    // Get the version to fetch - either specified or latest
+    let version = options.ver;
+    if (!version) {
+      const toolInfo = await getToolInfo(client, toolName);
+      version = toolInfo.latestVersion;
+    }
+
+    // Get the version info which includes rawManifest
+    const versionInfo = await getToolVersion(client, toolName, version);
+
+    if (options.json) {
+      json({
+        name: toolName,
+        version: versionInfo.version,
+        documentation: versionInfo.rawManifest ?? null,
+      });
+      return;
+    }
+
+    if (!versionInfo.rawManifest) {
+      error(`No documentation found for ${toolName}@${version}`);
+      dim("This tool may not have an enact.md file.");
+      process.exit(1);
+    }
+
+    // Display the documentation
+    header(`${toolName}@${version}`);
+    newline();
+    console.log(versionInfo.rawManifest);
+  } catch (err) {
+    if (err instanceof Error) {
+      if (err.message.includes("not_found") || err.message.includes("404")) {
+        error(`Tool not found: ${toolName}`);
+        dim("Check the tool name or search with: enact search <query>");
+        process.exit(1);
+      }
+      if (err.message.includes("fetch")) {
+        error("Unable to connect to registry. Check your internet connection.");
+        process.exit(1);
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Configure the learn command
+ */
+export function configureLearnCommand(program: Command): void {
+  program
+    .command("learn <tool>")
+    .description("Display documentation (enact.md) for a tool")
+    .option("--ver <version>", "Show documentation for a specific version")
+    .option("--json", "Output as JSON")
+    .action(async (toolName: string, options: LearnOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await learnHandler(toolName, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/run/index.ts

@@ -61,6 +61,7 @@ import {
 
 interface RunOptions extends GlobalOptions {
   args?: string;
+  inputFile?: string;
   input?: string[];
   timeout?: string;
   noCache?: boolean;
@@ -70,14 +71,46 @@ interface RunOptions extends GlobalOptions {
 
 /**
  * Parse input arguments from various formats
+ *
+ * Priority order (later sources override earlier):
+ * 1. --input-file (JSON file)
+ * 2. --args (inline JSON)
+ * 3. --input (key=value pairs)
+ *
+ * Recommended for agents: Use --args or --input-file with JSON
  */
 function parseInputArgs(
   argsJson: string | undefined,
+  inputFile: string | undefined,
   inputFlags: string[] | undefined
 ): Record<string, unknown> {
   const inputs: Record<string, unknown> = {};
 
-  // Parse --args JSON
+  // Parse --input-file JSON file (loaded first, can be overridden)
+  if (inputFile) {
+    try {
+      const { readFileSync, existsSync } = require("node:fs");
+      const { resolve } = require("node:path");
+      const filePath = resolve(inputFile);
+
+      if (!existsSync(filePath)) {
+        throw new Error(`Input file not found: ${inputFile}`);
+      }
+
+      const content = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(content);
+      if (typeof parsed === "object" && parsed !== null) {
+        Object.assign(inputs, parsed);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("Input file not found")) {
+        throw err;
+      }
+      throw new Error(`Invalid JSON in input file: ${formatError(err)}`);
+    }
+  }
+
+  // Parse --args JSON (overrides file)
   if (argsJson) {
     try {
       const parsed = JSON.parse(argsJson);
@@ -89,7 +122,7 @@ function parseInputArgs(
     }
   }
 
-  // Parse --input key=value pairs
+  // Parse --input key=value pairs (overrides both)
   if (inputFlags) {
     for (const input of inputFlags) {
       const eqIndex = input.indexOf("=");
@@ -501,7 +534,7 @@ async function runHandler(tool: string, options: RunOptions, ctx: CommandContext
   const manifest = resolution.manifest;
 
   // Parse inputs
-  const inputs = parseInputArgs(options.args, options.input);
+  const inputs = parseInputArgs(options.args, options.inputFile, options.input);
 
   // Apply defaults from schema
   const inputsWithDefaults = manifest.inputSchema
@@ -669,8 +702,9 @@ export function configureRunCommand(program: Command): void {
     .command("run")
     .description("Execute a tool with its manifest-defined command")
     .argument("<tool>", "Tool to run (name, path, or '.' for current directory)")
-    .option("-a, --args <json>", "Input arguments as JSON")
-    .option("-i, --input <key=value...>", "Input arguments as key=value pairs")
+    .option("-a, --args <json>", "Input arguments as JSON string (recommended)")
+    .option("-f, --input-file <path>", "Load input arguments from JSON file")
+    .option("-i, --input <key=value...>", "Input arguments as key=value pairs (simple values only)")
     .option("-t, --timeout <duration>", "Execution timeout (e.g., 30s, 5m)")
     .option("--no-cache", "Disable container caching")
     .option("--local", "Only resolve from local sources")

package/src/index.ts

@@ -19,6 +19,7 @@ import {
   configureInitCommand,
   configureInspectCommand,
   configureInstallCommand,
+  configureLearnCommand,
   configureListCommand,
   configurePublishCommand,
   configureReportCommand,
@@ -32,7 +33,7 @@ import {
 } from "./commands";
 import { error, formatError } from "./utils";
 
-export const version = "2.1.5";
+export const version = "2.1.6";
 
 // Export types for external use
 export type { GlobalOptions, CommandContext } from "./types";
@@ -47,7 +48,7 @@ async function main() {
   program
     .name("enact")
     .description("Enact - Verified, portable protocol for AI-executable tools")
-    .version(version);
+    .version(version, "-v, --version", "output the version number");
 
   // Configure all commands
   configureSetupCommand(program);
@@ -63,6 +64,7 @@ async function main() {
   // Registry commands (Phase 8)
   configureSearchCommand(program);
   configureGetCommand(program);
+  configureLearnCommand(program);
   configurePublishCommand(program);
   configureAuthCommand(program);
   configureCacheCommand(program);

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
+    });
+  });
 });