@enactprotocol/cli 2.1.14 → 2.1.17

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

@@ -0,0 +1,218 @@
+/**
+ * AGENTS.md template for tool development
+ */
+export const toolAgentsTemplate = `# Enact Tool Development Guide
+
+Enact tools are containerized, cryptographically-signed executables. Each tool is defined by a \`SKILL.md\` file (YAML frontmatter + Markdown docs).
+
+## 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 ./\` |
+
+## SKILL.md Structure
+
+\`\`\`yaml
+---
+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
+      description: "Input to process"
+  required: [input]
+
+outputSchema:
+  type: object
+  properties:
+    result:
+      type: string
+
+env:
+  API_KEY:
+    description: "External API key"
+    secret: true                  # Set via: enact env set API_KEY --secret
+---
+# Tool Name
+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}\` — raw, no quoting (use carefully)
+
+## Output
+
+Output valid JSON to stdout when \`outputSchema\` is defined:
+
+\`\`\`python
+import json, sys
+
+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
+\`\`\`
+
+## 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}
+\`\`\`
+
+**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 \`SKILL.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
+\`\`\`
+`;

package/src/commands/init/templates/tool-skill.ts

@@ -0,0 +1,75 @@
+/**
+ * SKILL.md template for new tool creation
+ */
+export const toolSkillTemplate = `---
+name: {{TOOL_NAME}}
+description: A simple tool that echoes a greeting
+version: 0.1.0
+enact: "2.0"
+
+from: python:3.12-slim
+
+# Install dependencies (cached by Dagger)
+build: |
+  pip install requests
+
+# Environment variables (optional)
+# env:
+#   API_KEY:
+#     secret: true
+#     description: "Your API key"
+
+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. Change the \`from\` image to match your runtime (python, node, rust, etc.)
+3. Add dependencies in the \`build\` section (pip install, npm install, etc.)
+4. Uncomment and configure \`env\` for secrets/API keys
+5. Modify the \`inputSchema\` to define your tool's inputs
+6. Change the \`command\` to run your script or shell commands
+7. Update this documentation section
+
+## Environment Variables
+
+To use secrets, uncomment the \`env\` section above, then set the value:
+
+\`\`\`bash
+enact env set API_KEY --secret --namespace {{TOOL_NAME}}
+\`\`\`
+
+Access in your code:
+\`\`\`python
+import os
+api_key = os.environ.get('API_KEY')
+\`\`\`
+
+## Learn More
+
+- [Enact Documentation](https://enact.dev/docs)
+- [Tool Manifest Reference](https://enact.dev/docs/manifest)
+`;

package/src/commands/publish/index.ts

@@ -2,6 +2,7 @@
  * enact publish command
  *
  * Publish a tool to the Enact registry using v2 multipart upload.
+ * Supports pre-signed attestations via manifest-based signing.
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -16,9 +17,16 @@ import {
   loadManifestFromDir,
   validateManifest,
 } from "@enactprotocol/shared";
+import {
+  type ChecksumManifest,
+  type SigstoreBundle,
+  parseChecksumManifest,
+  verifyChecksumManifest,
+} from "@enactprotocol/trust";
 import type { Command } from "commander";
 import type { CommandContext, GlobalOptions } from "../../types";
 import {
+  confirm,
   dim,
   error,
   extractNamespace,
@@ -208,6 +216,88 @@ async function publishHandler(
   header(`Publishing ${toolName}@${version}`);
   newline();
 
+  // Check for pre-signed attestation (manifest-based signing)
+  const checksumManifestPath = join(toolDir, ".enact-manifest.json");
+  const sigstoreBundlePath = join(toolDir, ".sigstore-bundle.json");
+
+  let checksumManifest: ChecksumManifest | undefined;
+  let sigstoreBundle: SigstoreBundle | undefined;
+  let hasPreSignedAttestation = false;
+
+  if (existsSync(checksumManifestPath) && existsSync(sigstoreBundlePath)) {
+    info("Found pre-signed attestation files");
+
+    try {
+      // Load and parse the checksum manifest
+      const manifestContent = readFileSync(checksumManifestPath, "utf-8");
+      checksumManifest = parseChecksumManifest(manifestContent);
+
+      // Load the sigstore bundle
+      const bundleContent = readFileSync(sigstoreBundlePath, "utf-8");
+      sigstoreBundle = JSON.parse(bundleContent) as SigstoreBundle;
+
+      // Verify the checksum manifest matches current files
+      const ignorePatterns = loadGitignore(toolDir);
+      const verification = await verifyChecksumManifest(toolDir, checksumManifest, {
+        ignorePatterns,
+      });
+
+      if (!verification.valid) {
+        newline();
+        warning("Pre-signed attestation is outdated - files have changed since signing:");
+        if (verification.modifiedFiles?.length) {
+          for (const file of verification.modifiedFiles) {
+            dim(`  • Modified: ${file}`);
+          }
+        }
+        if (verification.missingFiles?.length) {
+          for (const file of verification.missingFiles) {
+            dim(`  • Missing: ${file}`);
+          }
+        }
+        if (verification.extraFiles?.length) {
+          for (const file of verification.extraFiles) {
+            dim(`  • New file: ${file}`);
+          }
+        }
+        newline();
+
+        if (ctx.isInteractive) {
+          const continueWithoutAttestation = await confirm(
+            "Continue publishing without the pre-signed attestation?",
+            false
+          );
+          if (!continueWithoutAttestation) {
+            info("Publishing cancelled. Please re-sign with 'enact sign .' after making changes.");
+            return;
+          }
+          // Clear the attestation since it's outdated
+          checksumManifest = undefined;
+          sigstoreBundle = undefined;
+        } else {
+          error("Pre-signed attestation does not match current files.");
+          dim(
+            "Please re-sign with 'enact sign .' or remove .enact-manifest.json and .sigstore-bundle.json"
+          );
+          process.exit(1);
+        }
+      } else {
+        hasPreSignedAttestation = true;
+        keyValue("Attestation", "Pre-signed (valid)");
+        keyValue("Manifest hash", `${checksumManifest.manifestHash.digest.slice(0, 16)}...`);
+        keyValue("Files in attestation", String(checksumManifest.files.length));
+      }
+    } catch (err) {
+      warning("Failed to load pre-signed attestation:");
+      if (err instanceof Error) {
+        dim(`  ${err.message}`);
+      }
+      dim("Continuing without attestation...");
+      checksumManifest = undefined;
+      sigstoreBundle = undefined;
+    }
+  }
+
   // Determine visibility (private by default for security)
   const visibility: ToolVisibility = options.public
     ? "public"
@@ -341,12 +431,22 @@ async function publishHandler(
       bundle,
       rawManifest: rawManifestContent,
       visibility,
+      // Include pre-signed attestation if available (cast to Record for API compatibility)
+      checksumManifest: hasPreSignedAttestation
+        ? (checksumManifest as unknown as Record<string, unknown>)
+        : undefined,
+      sigstoreBundle: hasPreSignedAttestation
+        ? (sigstoreBundle as unknown as Record<string, unknown>)
+        : undefined,
     });
   });
 
   // JSON output
   if (options.json) {
-    json(result);
+    json({
+      ...result,
+      hasAttestation: hasPreSignedAttestation,
+    });
     return;
   }
 
@@ -355,6 +455,9 @@ async function publishHandler(
   success(`Published ${result.name}@${result.version} (${visibility})`);
   keyValue("Bundle Hash", result.bundleHash);
   keyValue("Published At", result.publishedAt.toISOString());
+  if (hasPreSignedAttestation) {
+    keyValue("Attestation", "Included (pre-signed)");
+  }
   newline();
   if (visibility === "private") {
     dim("This tool is private - only you can access it.");
@@ -362,6 +465,13 @@ async function publishHandler(
     dim("This tool is unlisted - accessible via direct link, not searchable.");
   }
   dim(`Install with: enact install ${toolName}`);
+
+  if (!hasPreSignedAttestation) {
+    newline();
+    info("Tip: Sign your tool before publishing for verified attestations:");
+    dim(`  1. enact sign ${pathArg}    # Create pre-signed attestation`);
+    dim(`  2. enact publish ${pathArg}  # Publish with attestation`);
+  }
 }
 
 /**