@enactprotocol/cli 2.1.6 → 2.1.10

package/src/commands/init/index.ts

@@ -26,7 +26,7 @@ const SUPABASE_ANON_KEY =
  * Embedded templates (for single-binary compatibility)
  */
 const TEMPLATES: Record<string, string> = {
-  "tool-enact.md": `---
+  "tool-skill.md": `---
 name: {{TOOL_NAME}}
 description: A simple tool that echoes a greeting
 version: 0.1.0
@@ -74,7 +74,7 @@ Edit this file to create your own tool:
 
   "tool-agents.md": `# Enact Tool Development Guide
 
-Enact tools are containerized, cryptographically-signed executables. Each tool is defined by an \`enact.md\` file (YAML frontmatter + Markdown docs).
+Enact tools are containerized, cryptographically-signed executables. Each tool is defined by a \`SKILL.md\` file (YAML frontmatter + Markdown docs).
 
 ## Quick Reference
 
@@ -85,7 +85,7 @@ Enact tools are containerized, cryptographically-signed executables. Each tool i
 | Dry run | \`enact run ./ --args '{}' --dry-run\` |
 | Sign & publish | \`enact sign ./ && enact publish ./\` |
 
-## enact.md Structure
+## SKILL.md Structure
 
 \`\`\`yaml
 ---
@@ -225,7 +225,7 @@ Tools run in a container with \`/work\` as the working directory. All source fil
 
 ## Secrets
 
-Declare in \`enact.md\`:
+Declare in \`SKILL.md\`:
 \`\`\`yaml
 env:
   API_KEY:
@@ -302,6 +302,7 @@ enact run ./path/to/tool --args '{}'              # Run local tool
 \`\`\`bash
 enact search "pdf extraction"                     # Search registry
 enact get author/category/tool                    # View tool info
+enact learn author/category/tool                  # View tool documentation
 enact install author/category/tool                # Add to project (.enact/tools.json)
 enact install author/category/tool --global       # Add globally
 enact list                                        # List project tools
@@ -314,7 +315,7 @@ enact run tool --args '{}' | jq '.result'
 \`\`\`
 
 ## Creating Local Tools
-Create \`tools/<name>/enact.md\` with:
+Create \`tools/<name>/SKILL.md\` with:
 \`\`\`yaml
 ---
 name: my-tool
@@ -345,6 +346,7 @@ This project uses Enact tools — containerized, signed executables you can run
 \`\`\`bash
 enact run <tool> --args '{"key": "value"}'   # Run a tool
 enact search "keyword"                        # Find tools
+enact learn author/tool                       # View tool documentation
 enact install author/tool                     # Install tool
 enact list                                    # List installed tools
 \`\`\`
@@ -360,7 +362,7 @@ enact run tool --args '{}' | jq '.data'
 \`\`\`
 
 ## Creating Tools
-Create \`enact.md\` in a directory:
+Create \`SKILL.md\` in a directory:
 \`\`\`yaml
 ---
 name: namespace/category/tool
@@ -394,7 +396,7 @@ enact sign ./ && enact publish ./             # Publish
 \`\`\`
 
 ## Secrets
-Declare in enact.md, set via CLI:
+Declare in SKILL.md, set via CLI:
 \`\`\`yaml
 env:
   API_KEY:    # Declared but not set
@@ -430,6 +432,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
  */
@@ -514,24 +540,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 SKILL.md + AGENTS.md for tool development
+  if (isToolMode) {
+    const manifestPath = join(targetDir, "SKILL.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-skill.md", replacements);
+    const agentsContent = loadTemplate("tool-agents.md", replacements);
+
+    // Ensure directory exists
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    // Write SKILL.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 SKILL.md to customize your tool");
+    info("  2. Run 'enact run ./' to test your tool");
+    info("  3. Run 'enact publish' to share your tool");
     return;
   }
 
@@ -545,63 +611,36 @@ 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 learn <tool>' to view docs,");
+  info("and 'enact install <tool>' to add them.");
 }
 
 /**
@@ -613,9 +652,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 (SKILL.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

@@ -3,16 +3,46 @@
  *
  * Display the documentation (enact.md) for a tool.
  * Fetches and displays the raw manifest content for easy reading.
+ *
+ * Security: For tools fetched from the registry, attestation checks are
+ * performed according to the trust policy. This prevents potentially
+ * malicious documentation from being displayed to LLMs or users.
  */
 
-import { createApiClient, getToolInfo, getToolVersion } from "@enactprotocol/api";
-import { loadConfig } from "@enactprotocol/shared";
+import {
+  type AttestationListResponse,
+  createApiClient,
+  getAttestationList,
+  getToolInfo,
+  getToolVersion,
+  verifyAllAttestations,
+} from "@enactprotocol/api";
+import {
+  getMinimumAttestations,
+  getTrustPolicy,
+  getTrustedAuditors,
+  loadConfig,
+  tryResolveTool,
+} from "@enactprotocol/shared";
 import type { Command } from "commander";
 import type { CommandContext, GlobalOptions } from "../../types";
-import { dim, error, formatError, header, json, newline } from "../../utils";
+import {
+  TrustError,
+  confirm,
+  dim,
+  error,
+  formatError,
+  header,
+  info,
+  json,
+  newline,
+  success,
+  symbols,
+} from "../../utils";
 
 interface LearnOptions extends GlobalOptions {
   ver?: string;
+  local?: boolean;
 }
 
 /**
@@ -21,14 +51,76 @@ interface LearnOptions extends GlobalOptions {
 async function learnHandler(
   toolName: string,
   options: LearnOptions,
-  _ctx: CommandContext
+  ctx: CommandContext
 ): Promise<void> {
+  // First, try to resolve locally (project → user → cache)
+  // If the tool is already installed/cached, we trust it
+  const resolution = tryResolveTool(toolName, { startDir: ctx.cwd });
+
+  if (resolution) {
+    // Tool is installed locally - read documentation from the manifest file
+    if (resolution.manifestPath.endsWith(".md")) {
+      const { readFileSync } = await import("node:fs");
+      const content = readFileSync(resolution.manifestPath, "utf-8");
+
+      if (options.json) {
+        json({
+          name: toolName,
+          version: resolution.manifest.version,
+          documentation: content,
+          source: "local",
+        });
+        return;
+      }
+
+      header(`${toolName}@${resolution.manifest.version ?? "local"}`);
+      dim("(installed locally)");
+      newline();
+      console.log(content);
+      return;
+    }
+
+    // Fallback for non-.md manifests
+    if (options.json) {
+      json({
+        name: toolName,
+        version: resolution.manifest.version,
+        documentation: resolution.manifest.doc ?? resolution.manifest.description ?? null,
+        source: "local",
+      });
+      return;
+    }
+
+    header(`${toolName}@${resolution.manifest.version ?? "local"}`);
+    dim("(installed locally)");
+    newline();
+    console.log(
+      resolution.manifest.doc ?? resolution.manifest.description ?? "No documentation available."
+    );
+    return;
+  }
+
+  // If --local flag is set, don't fetch from registry
+  if (options.local) {
+    error(`Tool not found locally: ${toolName}`);
+    dim("The tool is not installed. Remove --local to fetch from registry.");
+    process.exit(1);
+  }
+
+  // Tool not installed - fetch from registry with attestation checks
   const config = loadConfig();
   const registryUrl =
     process.env.ENACT_REGISTRY_URL ??
     config.registry?.url ??
     "https://siikwkfgsmouioodghho.supabase.co/functions/v1";
-  const authToken = config.registry?.authToken;
+
+  // Get auth token - use user token if available, otherwise use anon key for public access
+  let authToken = config.registry?.authToken ?? process.env.ENACT_AUTH_TOKEN;
+  if (!authToken && registryUrl.includes("siikwkfgsmouioodghho.supabase.co")) {
+    authToken =
+      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNpaWt3a2Znc21vdWlvb2RnaGhvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjQ2MTkzMzksImV4cCI6MjA4MDE5NTMzOX0.kxnx6-IPFhmGx6rzNx36vbyhFMFZKP_jFqaDbKnJ_E0";
+  }
+
   const client = createApiClient({
     baseUrl: registryUrl,
     authToken: authToken,
@@ -42,14 +134,139 @@ async function learnHandler(
       version = toolInfo.latestVersion;
     }
 
+    if (!version) {
+      error(`No published versions for ${toolName}`);
+      process.exit(1);
+    }
+
     // Get the version info which includes rawManifest
     const versionInfo = await getToolVersion(client, toolName, version);
 
+    // ========================================
+    // TRUST VERIFICATION - same as run command
+    // ========================================
+    const trustPolicy = getTrustPolicy();
+    const minimumAttestations = getMinimumAttestations();
+    const trustedAuditors = getTrustedAuditors();
+
+    // Fetch attestations from registry
+    const attestationsResponse: AttestationListResponse = await getAttestationList(
+      client,
+      toolName,
+      version
+    );
+    const attestations = attestationsResponse.attestations;
+
+    if (attestations.length === 0) {
+      // No attestations found
+      info(`${symbols.warning} Tool ${toolName}@${version} has no attestations.`);
+
+      if (trustPolicy === "require_attestation") {
+        throw new TrustError(
+          "Trust policy requires attestations. Cannot display documentation from unverified tools."
+        );
+      }
+      if (ctx.isInteractive && trustPolicy === "prompt") {
+        dim("Documentation from unverified tools may contain malicious content.");
+        const proceed = await confirm("View documentation from unverified tool?");
+        if (!proceed) {
+          info("Cancelled.");
+          process.exit(0);
+        }
+      } else if (!ctx.isInteractive && trustPolicy === "prompt") {
+        throw new TrustError(
+          "Cannot display documentation from unverified tools in non-interactive mode."
+        );
+      }
+      // trustPolicy === "allow" - continue without prompting
+    } else {
+      // Verify attestations locally (never trust registry's verification status)
+      const verifiedAuditors = await verifyAllAttestations(
+        client,
+        toolName,
+        version,
+        versionInfo.bundle.hash ?? ""
+      );
+
+      // Check verified auditors against trust config using provider:identity format
+      const trustedVerifiedAuditors = verifiedAuditors
+        .filter((auditor) => trustedAuditors.includes(auditor.providerIdentity))
+        .map((auditor) => auditor.providerIdentity);
+
+      if (trustedVerifiedAuditors.length > 0) {
+        // Check if we meet minimum attestations threshold
+        if (trustedVerifiedAuditors.length < minimumAttestations) {
+          info(
+            `${symbols.warning} Tool ${toolName}@${version} has ${trustedVerifiedAuditors.length} trusted attestation(s), but ${minimumAttestations} required.`
+          );
+          dim(`Trusted attestations: ${trustedVerifiedAuditors.join(", ")}`);
+
+          if (trustPolicy === "require_attestation") {
+            throw new TrustError(
+              `Trust policy requires at least ${minimumAttestations} attestation(s) from trusted identities.`
+            );
+          }
+          if (ctx.isInteractive && trustPolicy === "prompt") {
+            const proceed = await confirm(
+              "View documentation with fewer attestations than required?"
+            );
+            if (!proceed) {
+              info("Cancelled.");
+              process.exit(0);
+            }
+          } else if (!ctx.isInteractive && trustPolicy === "prompt") {
+            throw new TrustError(
+              "Cannot display documentation without meeting minimum attestation requirement in non-interactive mode."
+            );
+          }
+          // trustPolicy === "allow" - continue without prompting
+        } else {
+          // Tool meets or exceeds minimum attestations
+          if (options.verbose) {
+            success(
+              `Tool verified by ${trustedVerifiedAuditors.length} trusted identity(ies): ${trustedVerifiedAuditors.join(", ")}`
+            );
+          }
+        }
+      } else {
+        // Has attestations but none from trusted auditors
+        info(
+          `${symbols.warning} Tool ${toolName}@${version} has ${verifiedAuditors.length} attestation(s), but none from trusted auditors.`
+        );
+
+        if (trustPolicy === "require_attestation") {
+          dim(`Your trusted auditors: ${trustedAuditors.join(", ")}`);
+          dim(`Tool attested by: ${verifiedAuditors.map((a) => a.providerIdentity).join(", ")}`);
+          throw new TrustError(
+            "Trust policy requires attestations from trusted identities. Cannot display documentation."
+          );
+        }
+        if (ctx.isInteractive && trustPolicy === "prompt") {
+          dim(`Attested by: ${verifiedAuditors.map((a) => a.providerIdentity).join(", ")}`);
+          dim(`Your trusted auditors: ${trustedAuditors.join(", ")}`);
+          const proceed = await confirm("View documentation anyway?");
+          if (!proceed) {
+            info("Cancelled.");
+            process.exit(0);
+          }
+        } else if (!ctx.isInteractive && trustPolicy === "prompt") {
+          throw new TrustError(
+            "Cannot display documentation without trusted attestations in non-interactive mode."
+          );
+        }
+        // trustPolicy === "allow" - continue without prompting
+      }
+    }
+
+    // ========================================
+    // Display documentation (trust verified)
+    // ========================================
     if (options.json) {
       json({
         name: toolName,
         version: versionInfo.version,
         documentation: versionInfo.rawManifest ?? null,
+        source: "registry",
       });
       return;
     }
@@ -65,6 +282,10 @@ async function learnHandler(
     newline();
     console.log(versionInfo.rawManifest);
   } catch (err) {
+    if (err instanceof TrustError) {
+      error(err.message);
+      process.exit(1);
+    }
     if (err instanceof Error) {
       if (err.message.includes("not_found") || err.message.includes("404")) {
         error(`Tool not found: ${toolName}`);
@@ -88,7 +309,9 @@ export function configureLearnCommand(program: Command): void {
     .command("learn <tool>")
     .description("Display documentation (enact.md) for a tool")
     .option("--ver <version>", "Show documentation for a specific version")
+    .option("--local", "Only show documentation for locally installed tools")
     .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Show detailed output")
     .action(async (toolName: string, options: LearnOptions) => {
       const ctx: CommandContext = {
         cwd: process.cwd(),

package/src/commands/publish/index.ts

@@ -130,9 +130,16 @@ async function createBundleFromDir(toolDir: string): Promise<Uint8Array> {
 }
 
 /**
- * Load the raw enact.md file content (full documentation with frontmatter)
+ * Load the raw markdown manifest file content (full documentation with frontmatter)
+ * Checks for SKILL.md first (preferred), then falls back to enact.md
  */
-function loadEnactMd(toolDir: string): string | undefined {
+function loadRawManifest(toolDir: string): string | undefined {
+  // Check SKILL.md first (preferred format)
+  const skillMdPath = join(toolDir, "SKILL.md");
+  if (existsSync(skillMdPath)) {
+    return readFileSync(skillMdPath, "utf-8");
+  }
+  // Fall back to enact.md
   const enactMdPath = join(toolDir, "enact.md");
   if (existsSync(enactMdPath)) {
     return readFileSync(enactMdPath, "utf-8");
@@ -299,10 +306,10 @@ async function publishHandler(
     return;
   }
 
-  // Load the full enact.md content (frontmatter + documentation)
-  const enactMdContent = loadEnactMd(toolDir);
-  if (enactMdContent) {
-    info("Found enact.md documentation");
+  // Load the full markdown manifest content (SKILL.md or enact.md)
+  const rawManifestContent = loadRawManifest(toolDir);
+  if (rawManifestContent) {
+    info("Found markdown documentation (SKILL.md or enact.md)");
   }
 
   // Create bundle
@@ -318,7 +325,7 @@ async function publishHandler(
       name: toolName,
       manifest: manifest as unknown as Record<string, unknown>,
       bundle,
-      rawManifest: enactMdContent,
+      rawManifest: rawManifestContent,
     });
   });