@enactprotocol/cli 2.0.10 → 2.0.13

package/src/commands/init/templates/agent-agents.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+This project uses Enact tools — containerized, cryptographically-signed executables.
+
+## Running Tools
+```bash
+enact run <tool-name> --args '{"key": "value"}'   # Run installed tool
+enact run ./path/to/tool --args '{}'              # Run local tool
+```
+
+## Finding & Installing Tools
+```bash
+enact search "pdf extraction"                     # Search registry
+enact get author/category/tool                    # View tool info
+enact install author/category/tool                # Add to project (.enact/tools.json)
+enact install author/category/tool --global       # Add globally
+enact list                                        # List project tools
+```
+
+## Tool Output
+Tools output JSON to stdout. Parse with jq or your language's JSON parser:
+```bash
+enact run tool --args '{}' | jq '.result'
+```
+
+## Creating Local Tools
+Create `tools/<name>/enact.md` with:
+```yaml
+---
+name: my-tool
+description: What it does
+command: echo "Hello ${name}"
+inputSchema:
+  type: object
+  properties:
+    name: { type: string }
+---
+# My Tool
+Documentation here.
+```
+Run with: `enact run ./tools/<name> --args '{"name": "World"}'`
+
+## Environment & Secrets
+```bash
+enact env set API_KEY --secret --namespace author/tool  # Set secret
+enact env list                                          # List env vars
+```

package/src/commands/init/templates/claude.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This project uses Enact tools — containerized, signed executables you can run via CLI.
+
+## Quick Reference
+```bash
+enact run <tool> --args '{"key": "value"}'   # Run a tool
+enact search "keyword"                        # Find tools
+enact install author/tool                     # Install tool
+enact list                                    # List installed tools
+```
+
+## Running Tools
+Tools take JSON input and return JSON output:
+```bash
+# Run and capture output
+result=$(enact run author/utils/formatter --args '{"code": "const x=1"}')
+
+# Parse with jq
+enact run tool --args '{}' | jq '.data'
+```
+
+## Creating Tools
+Create `enact.md` in a directory:
+```yaml
+---
+name: namespace/category/tool
+description: Clear description for search
+version: 1.0.0
+from: python:3.12-slim            # Docker image
+build: pip install requests       # Install dependencies (cached)
+command: python /work/main.py ${input}
+inputSchema:
+  type: object
+  properties:
+    input: { type: string, description: "The input to process" }
+  required: [input]
+---
+# Tool Name
+Usage documentation here.
+```
+
+Key points:
+- `${param}` is auto-quoted — never add manual quotes
+- `from:` pin image versions (not `:latest`)
+- `build:` steps are cached by Dagger
+- Output JSON to stdout, errors to stderr
+- Non-zero exit = failure
+
+## Tool Development Workflow
+```bash
+enact run ./ --args '{"input": "test"}'       # Test locally
+enact run ./ --args '{}' --dry-run            # Preview command
+enact sign ./ && enact publish ./             # Publish
+```
+
+## Secrets
+Declare in enact.md, set via CLI:
+```yaml
+env:
+  API_KEY:    # Declared but not set
+```
+```bash
+enact env set API_KEY --secret --namespace author/tool
+```

package/src/commands/init/templates/tool-agents.md

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+Enact tool: containerized, signed executable. Manifest: `enact.md` (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
+```
+
+## 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
+command: python /work/main.py ${input}
+timeout: 30s
+inputSchema:
+  type: object
+  properties:
+    input: { type: string }
+  required: [input]
+env:
+  API_KEY:                        # declare secrets (set via: enact env set API_KEY --secret)
+---
+# Tool Name
+Documentation here (usage examples, etc.)
+```
+
+## Parameter Substitution
+- `${param}` — auto-quoted (handles spaces, JSON, special chars)
+- `${param:raw}` — unquoted (use carefully)
+- **Never manually quote**: `"${param}"` causes double-quoting
+
+## Output
+Always output valid JSON when `outputSchema` is defined:
+```python
+import json, sys
+print(json.dumps({"result": data}))  # stdout = tool output
+sys.exit(1)  # non-zero = error
+```
+
+## File Access
+Tool runs in container with `/work` as working directory. Source files copied there.
+
+## 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`
+
+Build steps are cached — first run slow, subsequent runs instant.

package/src/commands/init/templates/tool-enact.md

@@ -0,0 +1,44 @@
+---
+name: {{TOOL_NAME}}
+description: A simple tool that echoes a greeting
+version: 0.1.0
+enact: "2.0"
+
+from: alpine:latest
+
+inputSchema:
+  type: object
+  properties:
+    name:
+      type: string
+      description: Name to greet
+      default: World
+  required: []
+
+command: |
+  echo "Hello, ${name}!"
+---
+
+# {{TOOL_NAME}}
+
+A simple greeting tool created with `enact init`.
+
+## Usage
+
+```bash
+enact run ./ --args '{"name": "Alice"}'
+```
+
+## Customization
+
+Edit this file to create your own tool:
+
+1. Update the `name` and `description` in the frontmatter
+2. Modify the `inputSchema` to define your tool's inputs
+3. Change the `command` to run your desired shell commands
+4. Update this documentation section
+
+## Learn More
+
+- [Enact Documentation](https://enact.dev/docs)
+- [Tool Manifest Reference](https://enact.dev/docs/manifest)

package/src/index.ts

@@ -32,7 +32,7 @@ import {
 } from "./commands";
 import { error, formatError } from "./utils";
 
-export const version = "2.0.10";
+export const version = "2.0.13";
 
 // Export types for external use
 export type { GlobalOptions, CommandContext } from "./types";

package/tests/commands/init.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Tests for the init command
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { configureInitCommand } from "../../src/commands/init";
+
+describe("init command", () => {
+  describe("command configuration", () => {
+    test("configures init command on program", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      expect(initCmd).toBeDefined();
+    });
+
+    test("has correct description", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      expect(initCmd?.description()).toBe("Initialize Enact in the current directory");
+    });
+
+    test("has --name option", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      const opts = initCmd?.options ?? [];
+      const nameOpt = opts.find((o) => o.long === "--name");
+      expect(nameOpt).toBeDefined();
+      expect(nameOpt?.short).toBe("-n");
+    });
+
+    test("has --force option", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      const opts = initCmd?.options ?? [];
+      const forceOpt = opts.find((o) => o.long === "--force");
+      expect(forceOpt).toBeDefined();
+      expect(forceOpt?.short).toBe("-f");
+    });
+
+    test("has --tool option", () => {
+      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");
+      expect(toolOpt).toBeDefined();
+    });
+
+    test("has --agent option", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      const opts = initCmd?.options ?? [];
+      const agentOpt = opts.find((o) => o.long === "--agent");
+      expect(agentOpt).toBeDefined();
+    });
+
+    test("has --claude option", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      const opts = initCmd?.options ?? [];
+      const claudeOpt = opts.find((o) => o.long === "--claude");
+      expect(claudeOpt).toBeDefined();
+    });
+
+    test("has --verbose option", () => {
+      const program = new Command();
+      configureInitCommand(program);
+
+      const initCmd = program.commands.find((cmd) => cmd.name() === "init");
+      const opts = initCmd?.options ?? [];
+      const verboseOpt = opts.find((o) => o.long === "--verbose");
+      expect(verboseOpt).toBeDefined();
+    });
+  });
+
+  describe("file generation", () => {
+    const testDir = join(import.meta.dir, ".test-init-temp");
+
+    beforeEach(() => {
+      // Clean up before each test
+      if (existsSync(testDir)) {
+        rmSync(testDir, { recursive: true });
+      }
+      mkdirSync(testDir, { recursive: true });
+    });
+
+    afterEach(() => {
+      // Clean up after each test
+      if (existsSync(testDir)) {
+        rmSync(testDir, { recursive: true });
+      }
+    });
+
+    test("default mode creates enact.md", async () => {
+      const program = new Command();
+      program.exitOverride(); // Prevent process.exit
+      configureInitCommand(program);
+
+      // Change to test directory and run init
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "test/my-tool"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const manifestPath = join(testDir, "enact.md");
+      expect(existsSync(manifestPath)).toBe(true);
+
+      const content = readFileSync(manifestPath, "utf-8");
+      expect(content).toContain("name: test/my-tool");
+      expect(content).toContain("description:");
+      expect(content).toContain("command:");
+    });
+
+    test("default mode creates AGENTS.md for tool development", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "test/my-tool"]);
+      } 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 run");
+      expect(content).toContain("enact.md");
+      expect(content).toContain("Parameter Substitution");
+    });
+
+    test("--agent 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", "--agent"]);
+      } 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 agent mode
+      const manifestPath = join(testDir, "enact.md");
+      expect(existsSync(manifestPath)).toBe(false);
+    });
+
+    test("--claude mode creates CLAUDE.md", 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 claudePath = join(testDir, "CLAUDE.md");
+      expect(existsSync(claudePath)).toBe(true);
+
+      const content = readFileSync(claudePath, "utf-8");
+      expect(content).toContain("enact run");
+      expect(content).toContain("enact search");
+
+      // Should NOT create enact.md or AGENTS.md in claude mode
+      expect(existsSync(join(testDir, "enact.md"))).toBe(false);
+      expect(existsSync(join(testDir, "AGENTS.md"))).toBe(false);
+    });
+
+    test("enact.md contains valid YAML frontmatter", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "myorg/utils/greeter"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const content = readFileSync(join(testDir, "enact.md"), "utf-8");
+
+      // Check frontmatter structure
+      expect(content.startsWith("---")).toBe(true);
+      expect(content).toContain("name: myorg/utils/greeter");
+      expect(content).toContain("version:");
+      expect(content).toContain("from:");
+      expect(content).toContain("inputSchema:");
+      expect(content).toContain("command:");
+
+      // Check it has closing frontmatter and markdown body
+      const parts = content.split("---");
+      expect(parts.length).toBeGreaterThanOrEqual(3); // empty, frontmatter, body
+    });
+
+    test("AGENTS.md for tools contains development instructions", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const content = readFileSync(join(testDir, "AGENTS.md"), "utf-8");
+
+      // Should contain tool development-specific content
+      expect(content).toContain("enact sign");
+      expect(content).toContain("enact publish");
+      expect(content).toContain("${param}");
+      expect(content).toContain("build:");
+      expect(content).toContain("/work");
+    });
+
+    test("AGENTS.md for agent projects contains usage instructions", 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 content = readFileSync(join(testDir, "AGENTS.md"), "utf-8");
+
+      // Should contain consumer-focused content
+      expect(content).toContain("enact search");
+      expect(content).toContain("enact install");
+      expect(content).toContain("enact list");
+      expect(content).toContain(".enact/tools.json");
+    });
+  });
+
+  describe("option conflicts", () => {
+    test("--tool 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");
+
+      // Description should indicate it's the default
+      expect(toolOpt?.description).toContain("default");
+    });
+  });
+
+  describe("template content quality", () => {
+    test("tool template has all required manifest fields", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const testDir = join(import.meta.dir, ".test-init-quality");
+      if (existsSync(testDir)) {
+        rmSync(testDir, { recursive: true });
+      }
+      mkdirSync(testDir, { recursive: true });
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const content = readFileSync(join(testDir, "enact.md"), "utf-8");
+
+      // Required fields per spec
+      expect(content).toContain("name:");
+      expect(content).toContain("description:");
+
+      // Recommended fields
+      expect(content).toContain("version:");
+      expect(content).toContain("enact:");
+      expect(content).toContain("from:");
+      expect(content).toContain("inputSchema:");
+      expect(content).toContain("command:");
+
+      // Clean up
+      rmSync(testDir, { recursive: true });
+    });
+
+    test("AGENTS.md does not contain unnecessary verbosity", async () => {
+      const program = new Command();
+      program.exitOverride();
+      configureInitCommand(program);
+
+      const testDir = join(import.meta.dir, ".test-init-verbosity");
+      if (existsSync(testDir)) {
+        rmSync(testDir, { recursive: true });
+      }
+      mkdirSync(testDir, { recursive: true });
+
+      const originalCwd = process.cwd();
+      process.chdir(testDir);
+
+      try {
+        await program.parseAsync(["node", "test", "init", "--name", "test/tool"]);
+      } catch {
+        // Command may throw due to exitOverride
+      } finally {
+        process.chdir(originalCwd);
+      }
+
+      const content = readFileSync(join(testDir, "AGENTS.md"), "utf-8");
+
+      // Should be concise - check line count is reasonable
+      const lines = content.split("\n").length;
+      expect(lines).toBeLessThan(100); // Should be concise
+
+      // Clean up
+      rmSync(testDir, { recursive: true });
+    });
+  });
+});