@enactprotocol/cli 2.1.5 → 2.1.7

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enactprotocol/cli",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "Command-line interface for Enact - the npm for AI tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,10 +34,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@enactprotocol/api": "2.1.5",
-    "@enactprotocol/execution": "2.1.5",
-    "@enactprotocol/secrets": "2.1.5",
-    "@enactprotocol/shared": "2.1.5",
+    "@enactprotocol/api": "2.1.7",
+    "@enactprotocol/execution": "2.1.7",
+    "@enactprotocol/secrets": "2.1.7",
+    "@enactprotocol/shared": "2.1.7",
     "commander": "^12.1.0",
     "picocolors": "^1.1.1"
   },

package/src/commands/index.ts

@@ -17,6 +17,7 @@ export { configureConfigCommand } from "./config";
 // Registry commands (Phase 8)
 export { configureSearchCommand } from "./search";
 export { configureGetCommand } from "./get";
+export { configureLearnCommand } from "./learn";
 export { configurePublishCommand } from "./publish";
 export { configureAuthCommand } from "./auth";
 export { configureCacheCommand } from "./cache";

package/src/commands/init/index.ts

@@ -80,8 +80,8 @@ Enact tools are containerized, cryptographically-signed executables. Each tool i
 
 | Task | Command |
 |------|---------|
-| Run local tool | \`enact run ./ --input "key=value"\` |
 | Run with JSON | \`enact run ./ --args '{"key": "value"}'\` |
+| Run from file | \`enact run ./ --input-file inputs.json\` |
 | Dry run | \`enact run ./ --args '{}' --dry-run\` |
 | Sign & publish | \`enact sign ./ && enact publish ./\` |
 
@@ -149,6 +149,20 @@ command: python /work/main.py "\${input}"
 command: python /work/main.py \${input}
 \`\`\`
 
+**Optional params:** Missing optional params become empty strings. Always provide defaults:
+\`\`\`yaml
+inputSchema:
+  properties:
+    greeting: 
+      type: string
+      default: "Hello"  # Recommended for optional params
+\`\`\`
+
+Or handle empty in shell:
+\`\`\`yaml
+command: "echo \${greeting:-Hello} \${name}"
+\`\`\`
+
 Modifiers:
 - \`\${param}\` — auto-quoted (handles spaces, JSON, special chars)
 - \`\${param:raw}\` — raw, no quoting (use carefully)
@@ -268,9 +282,9 @@ Return JSON: {"issues": [...], "score": 75}
 ## Troubleshooting
 
 \`\`\`bash
-enact run ./ --input "x=y" --verbose   # Verbose output
-enact run ./ --args '{}' --dry-run     # Preview command
-enact list                              # List installed tools
+enact run ./ --args '{"x": "y"}' --verbose   # Verbose output
+enact run ./ --args '{}' --dry-run             # Preview command
+enact list                                      # List installed tools
 \`\`\`
 `,
 
@@ -416,6 +430,30 @@ function loadTemplate(templateName: string, replacements: Record<string, string>
   return content;
 }
 
+/**
+ * Create .enact/tools.json for project tool tracking
+ */
+function createEnactProjectDir(targetDir: string, force: boolean): boolean {
+  const enactDir = join(targetDir, ".enact");
+  const toolsJsonPath = join(enactDir, "tools.json");
+
+  // Check if tools.json already exists
+  if (existsSync(toolsJsonPath) && !force) {
+    info(".enact/tools.json already exists, skipping");
+    return false;
+  }
+
+  // Create .enact directory if it doesn't exist
+  if (!existsSync(enactDir)) {
+    mkdirSync(enactDir, { recursive: true });
+  }
+
+  // Write empty tools.json
+  const toolsJson = { tools: {} };
+  writeFileSync(toolsJsonPath, `${JSON.stringify(toolsJson, null, 2)}\n`, "utf-8");
+  return true;
+}
+
 /**
  * Get the current logged-in username
  */
@@ -500,24 +538,64 @@ async function getCurrentUsername(): Promise<string | null> {
 async function initHandler(options: InitOptions, ctx: CommandContext): Promise<void> {
   const targetDir = ctx.cwd;
 
-  // Determine mode: --agent, --claude, or --tool (default)
-  const isAgentMode = options.agent;
+  // Determine mode: --tool, --claude, or --agent (default)
+  const isToolMode = options.tool;
   const isClaudeMode = options.claude;
-  // Default to tool mode if no flag specified
+  // Default to agent mode if no flag specified
 
-  // Handle --agent mode: create AGENTS.md for projects using Enact tools
-  if (isAgentMode) {
+  // Handle --tool mode: create enact.md + AGENTS.md for tool development
+  if (isToolMode) {
+    const manifestPath = join(targetDir, "enact.md");
     const agentsPath = join(targetDir, "AGENTS.md");
-    if (existsSync(agentsPath) && !options.force) {
-      warning(`AGENTS.md already exists at: ${agentsPath}`);
+
+    if (existsSync(manifestPath) && !options.force) {
+      warning(`Tool manifest already exists at: ${manifestPath}`);
       info("Use --force to overwrite");
       return;
     }
-    writeFileSync(agentsPath, loadTemplate("agent-agents.md"), "utf-8");
-    success(`Created AGENTS.md: ${agentsPath}`);
+
+    // Get username for the tool name
+    let toolName = options.name;
+
+    if (!toolName) {
+      const username = await getCurrentUsername();
+      if (username) {
+        toolName = `${username}/my-tool`;
+        info(`Using logged-in username: ${username}`);
+      } else {
+        toolName = "my-tool";
+        info("Not logged in - using generic tool name");
+        info("Run 'enact auth login' to use your username in tool names");
+      }
+    }
+
+    // Load templates with placeholder replacement
+    const replacements = { TOOL_NAME: toolName };
+    const manifestContent = loadTemplate("tool-enact.md", replacements);
+    const agentsContent = loadTemplate("tool-agents.md", replacements);
+
+    // Ensure directory exists
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    // Write enact.md
+    writeFileSync(manifestPath, manifestContent, "utf-8");
+    success(`Created tool manifest: ${manifestPath}`);
+
+    // Write AGENTS.md (only if it doesn't exist or --force is used)
+    if (!existsSync(agentsPath) || options.force) {
+      writeFileSync(agentsPath, agentsContent, "utf-8");
+      success(`Created AGENTS.md: ${agentsPath}`);
+    } else {
+      info("AGENTS.md already exists, skipping (use --force to overwrite)");
+    }
+
     info("");
-    info("This file helps AI agents understand how to use Enact tools in your project.");
-    info("Run 'enact search <query>' to find tools, 'enact install <tool>' to add them.");
+    info("Next steps:");
+    info("  1. Edit enact.md to customize your tool");
+    info("  2. Run 'enact run ./' to test your tool");
+    info("  3. Run 'enact publish' to share your tool");
     return;
   }
 
@@ -531,63 +609,35 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
     }
     writeFileSync(claudePath, loadTemplate("claude.md"), "utf-8");
     success(`Created CLAUDE.md: ${claudePath}`);
+
+    // Create .enact/tools.json
+    if (createEnactProjectDir(targetDir, options.force ?? false)) {
+      success("Created .enact/tools.json");
+    }
+
     info("");
     info("This file helps Claude understand how to use Enact tools in your project.");
     return;
   }
 
-  // Handle --tool mode (default): create enact.md + AGENTS.md for tool development
-  const manifestPath = join(targetDir, "enact.md");
+  // Handle default (agent) mode: create AGENTS.md for projects using Enact tools
   const agentsPath = join(targetDir, "AGENTS.md");
-
-  if (existsSync(manifestPath) && !options.force) {
-    warning(`Tool manifest already exists at: ${manifestPath}`);
+  if (existsSync(agentsPath) && !options.force) {
+    warning(`AGENTS.md already exists at: ${agentsPath}`);
     info("Use --force to overwrite");
     return;
   }
+  writeFileSync(agentsPath, loadTemplate("agent-agents.md"), "utf-8");
+  success(`Created AGENTS.md: ${agentsPath}`);
 
-  // Get username for the tool name
-  let toolName = options.name;
-
-  if (!toolName) {
-    const username = await getCurrentUsername();
-    if (username) {
-      toolName = `${username}/my-tool`;
-      info(`Using logged-in username: ${username}`);
-    } else {
-      toolName = "my-tool";
-      info("Not logged in - using generic tool name");
-      info("Run 'enact auth login' to use your username in tool names");
-    }
-  }
-
-  // Load templates with placeholder replacement
-  const replacements = { TOOL_NAME: toolName };
-  const manifestContent = loadTemplate("tool-enact.md", replacements);
-  const agentsContent = loadTemplate("tool-agents.md", replacements);
-
-  // Ensure directory exists
-  if (!existsSync(targetDir)) {
-    mkdirSync(targetDir, { recursive: true });
-  }
-
-  // Write enact.md
-  writeFileSync(manifestPath, manifestContent, "utf-8");
-  success(`Created tool manifest: ${manifestPath}`);
-
-  // Write AGENTS.md (only if it doesn't exist or --force is used)
-  if (!existsSync(agentsPath) || options.force) {
-    writeFileSync(agentsPath, agentsContent, "utf-8");
-    success(`Created AGENTS.md: ${agentsPath}`);
-  } else {
-    info("AGENTS.md already exists, skipping (use --force to overwrite)");
+  // Create .enact/tools.json
+  if (createEnactProjectDir(targetDir, options.force ?? false)) {
+    success("Created .enact/tools.json");
   }
 
   info("");
-  info("Next steps:");
-  info("  1. Edit enact.md to customize your tool");
-  info("  2. Run 'enact run ./' to test your tool");
-  info("  3. Run 'enact publish' to share your tool");
+  info("This file helps AI agents understand how to use Enact tools in your project.");
+  info("Run 'enact search <query>' to find tools, 'enact install <tool>' to add them.");
 }
 
 /**
@@ -599,9 +649,9 @@ export function configureInitCommand(program: Command): void {
     .description("Initialize Enact in the current directory")
     .option("-n, --name <name>", "Tool name (default: username/my-tool)")
     .option("-f, --force", "Overwrite existing files")
-    .option("--tool", "Create a new Enact tool (default)")
-    .option("--agent", "Create AGENTS.md for projects that use Enact tools")
-    .option("--claude", "Create CLAUDE.md with Claude-specific instructions")
+    .option("--tool", "Create a new Enact tool (enact.md + AGENTS.md)")
+    .option("--agent", "Create AGENTS.md + .enact/tools.json (default)")
+    .option("--claude", "Create CLAUDE.md + .enact/tools.json")
     .option("-v, --verbose", "Show detailed output")
     .action(async (options: InitOptions) => {
       const ctx: CommandContext = {

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.7";
 
 // 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);