@enactprotocol/cli 2.1.4 → 2.1.6

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.4",
+  "version": "2.1.6",
   "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.4",
-    "@enactprotocol/execution": "2.1.4",
-    "@enactprotocol/secrets": "2.1.4",
-    "@enactprotocol/shared": "2.1.4",
+    "@enactprotocol/api": "2.1.6",
+    "@enactprotocol/execution": "2.1.6",
+    "@enactprotocol/secrets": "2.1.6",
+    "@enactprotocol/shared": "2.1.6",
     "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

@@ -72,62 +72,220 @@ Edit this file to create your own tool:
 - [Tool Manifest Reference](https://enact.dev/docs/manifest)
 `,
 
-  "tool-agents.md": `# AGENTS.md
+  "tool-agents.md": `# Enact Tool Development Guide
 
-Enact tool: containerized, signed executable. Manifest: \`enact.md\` (YAML frontmatter + Markdown docs).
+Enact tools are containerized, cryptographically-signed executables. Each tool is defined by an \`enact.md\` file (YAML frontmatter + Markdown docs).
 
-## Commands
-\`\`\`bash
-enact run ./ --args '{"name": "Test"}'  # Run locally
-enact run ./ --args '{}' --dry-run      # Preview execution
-enact sign ./ && enact publish ./       # Sign and publish
-\`\`\`
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| 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 ./\` |
 
 ## enact.md Structure
+
 \`\`\`yaml
 ---
-name: {{TOOL_NAME}}        # org/category/tool format
-description: What it does
-version: 1.0.0                    # semver
-from: python:3.12-slim            # pin versions, not :latest
-build: pip install requests       # cached by Dagger
+name: {{TOOL_NAME}}
+description: What the tool does
+version: 1.0.0
+enact: "2.0.0"
+
+from: python:3.12-slim            # Docker image (pin versions, not :latest)
+build: pip install requests       # Build steps (cached by Dagger)
 command: python /work/main.py \${input}
 timeout: 30s
+
 inputSchema:
   type: object
   properties:
-    input: { type: string }
+    input:
+      type: string
+      description: "Input to process"
   required: [input]
+
+outputSchema:
+  type: object
+  properties:
+    result:
+      type: string
+
 env:
-  API_KEY:                        # declare secrets (set via: enact env set API_KEY --secret)
+  API_KEY:
+    description: "External API key"
+    secret: true                  # Set via: enact env set API_KEY --secret
 ---
 # Tool Name
-Documentation here (usage examples, etc.)
+Documentation here.
 \`\`\`
 
+## Field Reference
+
+| Field | Description |
+|-------|-------------|
+| \`name\` | Hierarchical ID: \`org/category/tool\` |
+| \`description\` | What the tool does |
+| \`version\` | Semver version |
+| \`from\` | Docker image |
+| \`build\` | Build commands (string or array, cached) |
+| \`command\` | Shell command with \`\${param}\` substitution |
+| \`timeout\` | Max execution time (e.g., "30s", "5m") |
+| \`inputSchema\` | JSON Schema for inputs |
+| \`outputSchema\` | JSON Schema for outputs |
+| \`env\` | Environment variables and secrets |
+
 ## Parameter Substitution
+
+Enact auto-quotes parameters. **Never manually quote:**
+
+\`\`\`yaml
+# WRONG - causes double-quoting
+command: python /work/main.py "\${input}"
+
+# RIGHT - Enact handles quoting
+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}\` — unquoted (use carefully)
-- **Never manually quote**: \`"\${param}"\` causes double-quoting
+- \`\${param:raw}\` — raw, no quoting (use carefully)
 
 ## Output
-Always output valid JSON when \`outputSchema\` is defined:
+
+Output valid JSON to stdout when \`outputSchema\` is defined:
+
 \`\`\`python
 import json, sys
-print(json.dumps({"result": data}))  # stdout = tool output
-sys.exit(1)  # non-zero = error
+
+try:
+    result = do_work()
+    print(json.dumps({"status": "success", "result": result}))
+except Exception as e:
+    print(json.dumps({"status": "error", "message": str(e)}))
+    sys.exit(1)  # non-zero = error
 \`\`\`
 
-## File Access
-Tool runs in container with \`/work\` as working directory. Source files copied there.
+## Build Steps by Language
+
+**Python:**
+\`\`\`yaml
+from: python:3.12-slim
+build: pip install requests pandas
+\`\`\`
+
+**Node.js:**
+\`\`\`yaml
+from: node:20-alpine
+build:
+  - npm install
+  - npm run build
+\`\`\`
+
+**Rust:**
+\`\`\`yaml
+from: rust:1.83-slim
+build: rustc /work/main.rs -o /work/tool
+command: /work/tool \${input}
+\`\`\`
 
-## Adding Dependencies
-- Python: \`build: pip install package1 package2\`
-- Node: \`build: ["npm install", "npm run build"]\`
-- System: \`build: apt-get update && apt-get install -y libfoo\`
-- Compiled: \`build: rustc /work/main.rs -o /work/tool\`
+**Go:**
+\`\`\`yaml
+from: golang:1.22-alpine
+build: cd /work && go build -o tool main.go
+command: /work/tool \${input}
+\`\`\`
+
+**System packages:**
+\`\`\`yaml
+build: apt-get update && apt-get install -y libfoo-dev
+\`\`\`
 
 Build steps are cached — first run slow, subsequent runs instant.
+
+## File Access
+
+Tools run in a container with \`/work\` as the working directory. All source files are copied there.
+
+## Secrets
+
+Declare in \`enact.md\`:
+\`\`\`yaml
+env:
+  API_KEY:
+    description: "API key for service"
+    secret: true
+\`\`\`
+
+Set before running:
+\`\`\`bash
+enact env set API_KEY --secret --namespace {{TOOL_NAME}}
+\`\`\`
+
+Access in code:
+\`\`\`python
+import os
+api_key = os.environ.get('API_KEY')
+\`\`\`
+
+## LLM Instruction Tools
+
+Tools without a \`command\` field are interpreted by LLMs:
+
+\`\`\`yaml
+---
+name: myorg/ai/reviewer
+description: AI-powered code review
+inputSchema:
+  type: object
+  properties:
+    code: { type: string }
+  required: [code]
+outputSchema:
+  type: object
+  properties:
+    issues: { type: array }
+    score: { type: number }
+---
+# Code Reviewer
+
+You are a senior engineer. Review the code for bugs, style, and security.
+Return JSON: {"issues": [...], "score": 75}
+\`\`\`
+
+## Publishing Checklist
+
+- [ ] \`name\` follows \`namespace/category/tool\` pattern
+- [ ] \`version\` set (semver)
+- [ ] \`description\` is clear and searchable
+- [ ] \`inputSchema\` / \`outputSchema\` defined
+- [ ] \`from\` uses pinned image version
+- [ ] \`timeout\` set appropriately
+- [ ] Tool tested locally with \`enact run ./\`
+
+## Troubleshooting
+
+\`\`\`bash
+enact run ./ --args '{"x": "y"}' --verbose   # Verbose output
+enact run ./ --args '{}' --dry-run             # Preview command
+enact list                                      # List installed tools
+\`\`\`
 `,
 
   "agent-agents.md": `# AGENTS.md

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.4";
+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/init.test.ts

@@ -352,7 +352,7 @@ describe("init command", () => {
       rmSync(testDir, { recursive: true });
     });
 
-    test("AGENTS.md does not contain unnecessary verbosity", async () => {
+    test("AGENTS.md is comprehensive but reasonably sized", async () => {
       const program = new Command();
       program.exitOverride();
       configureInitCommand(program);
@@ -376,9 +376,10 @@ describe("init command", () => {
 
       const content = readFileSync(join(testDir, "AGENTS.md"), "utf-8");
 
-      // Should be concise - check line count is reasonable
+      // Should be comprehensive but not excessive
       const lines = content.split("\n").length;
-      expect(lines).toBeLessThan(100); // Should be concise
+      expect(lines).toBeLessThan(250); // Comprehensive guide under 250 lines
+      expect(lines).toBeGreaterThan(100); // But not too sparse
 
       // Clean up
       rmSync(testDir, { recursive: true });