@enactprotocol/cli 2.0.9 → 2.0.11

package/src/commands/init/index.ts

@@ -4,8 +4,9 @@
  * Create a basic tool template in the current directory.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getSecret } from "@enactprotocol/secrets";
 import type { Command } from "commander";
 import type { CommandContext, GlobalOptions } from "../../types";
@@ -22,9 +23,32 @@ const SUPABASE_ANON_KEY =
   process.env.SUPABASE_ANON_KEY ??
   "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNpaWt3a2Znc21vdWlvb2RnaGhvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjQ2MTkzMzksImV4cCI6MjA4MDE5NTMzOX0.kxnx6-IPFhmGx6rzNx36vbyhFMFZKP_jFqaDbKnJ_E0";
 
+/** Get the templates directory path */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, "templates");
+
 interface InitOptions extends GlobalOptions {
   name?: string;
   force?: boolean;
+  tool?: boolean;
+  agent?: boolean;
+  claude?: boolean;
+}
+
+/**
+ * Load a template file and replace placeholders
+ */
+function loadTemplate(templateName: string, replacements: Record<string, string> = {}): string {
+  const templatePath = join(TEMPLATES_DIR, templateName);
+  let content = readFileSync(templatePath, "utf-8");
+
+  // Replace all {{PLACEHOLDER}} patterns
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+
+  return content;
 }
 
 /**
@@ -105,65 +129,52 @@ async function getCurrentUsername(): Promise<string | null> {
   }
 }
 
-/**
- * Generate the tool template content
- */
-function generateToolTemplate(toolName: string): string {
-  return `---
-name: ${toolName}
-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}!"
----
-
-# ${toolName}
-
-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)
-`;
-}
-
 /**
  * Init command handler
  */
 async function initHandler(options: InitOptions, ctx: CommandContext): Promise<void> {
   const targetDir = ctx.cwd;
+
+  // Determine mode: --agent, --claude, or --tool (default)
+  const isAgentMode = options.agent;
+  const isClaudeMode = options.claude;
+  // Default to tool mode if no flag specified
+
+  // Handle --agent mode: create AGENTS.md for projects using Enact tools
+  if (isAgentMode) {
+    const agentsPath = join(targetDir, "AGENTS.md");
+    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}`);
+    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.");
+    return;
+  }
+
+  // Handle --claude mode: create CLAUDE.md
+  if (isClaudeMode) {
+    const claudePath = join(targetDir, "CLAUDE.md");
+    if (existsSync(claudePath) && !options.force) {
+      warning(`CLAUDE.md already exists at: ${claudePath}`);
+      info("Use --force to overwrite");
+      return;
+    }
+    writeFileSync(claudePath, loadTemplate("claude.md"), "utf-8");
+    success(`Created CLAUDE.md: ${claudePath}`);
+    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");
+  const agentsPath = join(targetDir, "AGENTS.md");
 
-  // Check if manifest already exists
   if (existsSync(manifestPath) && !options.force) {
     warning(`Tool manifest already exists at: ${manifestPath}`);
     info("Use --force to overwrite");
@@ -185,17 +196,28 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
     }
   }
 
-  // Generate and write the template
-  const content = generateToolTemplate(toolName);
+  // 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 });
   }
 
-  writeFileSync(manifestPath, content, "utf-8");
+  // 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)");
+  }
 
-  success(`Created tool template: ${manifestPath}`);
   info("");
   info("Next steps:");
   info("  1. Edit enact.md to customize your tool");
@@ -209,9 +231,12 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
 export function configureInitCommand(program: Command): void {
   program
     .command("init")
-    .description("Create a new tool template in the current directory")
-    .option("-n, --name <name>", "Tool name (default: username/my-tool or my-tool)")
-    .option("-f, --force", "Overwrite existing enact.md file")
+    .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("-v, --verbose", "Show detailed output")
     .action(async (options: InitOptions) => {
       const ctx: CommandContext = {

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.9";
+export const version = "2.0.11";
 
 // Export types for external use
 export type { GlobalOptions, CommandContext } from "./types";