@enactprotocol/cli 2.1.7 → 2.1.14

package/src/commands/{get → info}/index.ts

@@ -1,7 +1,7 @@
 /**
- * enact get command
+ * enact info command
  *
- * Show detailed information about a tool from the registry.
+ * Show detailed information about a tool from the registry or local path.
  */
 
 import {
@@ -11,7 +11,7 @@ import {
   getToolInfo,
   getToolVersion,
 } from "@enactprotocol/api";
-import { loadConfig } from "@enactprotocol/shared";
+import { loadConfig, tryResolveTool } from "@enactprotocol/shared";
 import type { Command } from "commander";
 import type { CommandContext, GlobalOptions } from "../../types";
 import {
@@ -26,8 +26,9 @@ import {
   success,
 } from "../../utils";
 
-interface GetOptions extends GlobalOptions {
+interface InfoOptions extends GlobalOptions {
   ver?: string;
+  local?: boolean;
 }
 
 /**
@@ -46,7 +47,7 @@ function formatDate(date: Date): string {
  */
 function displayToolInfo(
   tool: ToolInfo,
-  options: GetOptions,
+  options: InfoOptions,
   rawManifest?: string | undefined
 ): void {
   header(tool.name);
@@ -83,7 +84,7 @@ function displayToolInfo(
 /**
  * Display version-specific info
  */
-function displayVersionInfo(version: ToolVersionInfo, options: GetOptions): void {
+function displayVersionInfo(version: ToolVersionInfo, options: InfoOptions): void {
   header(`${version.name}@${version.version}`);
   newline();
 
@@ -119,13 +120,98 @@ function displayVersionInfo(version: ToolVersionInfo, options: GetOptions): void
 }
 
 /**
- * Get command handler
+ * Display local tool info
  */
-async function getHandler(
+function displayLocalToolInfo(
+  name: string,
+  manifest: Record<string, unknown>,
+  manifestPath: string,
+  options: InfoOptions
+): void {
+  header(name);
+  dim("(local)");
+  newline();
+
+  if (manifest.description) {
+    info(String(manifest.description));
+    newline();
+  }
+
+  keyValue("Version", String(manifest.version ?? "unknown"));
+  if (manifest.license) {
+    keyValue("License", String(manifest.license));
+  }
+  if (manifest.command) {
+    keyValue("Command", String(manifest.command));
+  }
+
+  if (Array.isArray(manifest.tags) && manifest.tags.length > 0) {
+    keyValue("Tags", manifest.tags.join(", "));
+  }
+
+  if (Array.isArray(manifest.authors) && manifest.authors.length > 0) {
+    const authorNames = manifest.authors
+      .map((a: { name?: string }) => a.name ?? "unknown")
+      .join(", ");
+    keyValue("Authors", authorNames);
+  }
+
+  keyValue("Manifest", manifestPath);
+
+  // Show raw manifest when --verbose is used
+  if (options.verbose && manifestPath.endsWith(".md")) {
+    const { readFileSync } = require("node:fs");
+    const content = readFileSync(manifestPath, "utf-8");
+    newline();
+    header("Documentation");
+    newline();
+    console.log(content);
+  }
+}
+
+/**
+ * Info command handler
+ */
+async function infoHandler(
   toolName: string,
-  options: GetOptions,
+  options: InfoOptions,
   ctx: CommandContext
 ): Promise<void> {
+  // First, try to resolve locally if it looks like a path
+  const resolution = tryResolveTool(toolName, { startDir: ctx.cwd });
+
+  if (resolution) {
+    // Tool found locally
+    if (options.json) {
+      json({
+        name: resolution.manifest.name ?? toolName,
+        version: resolution.manifest.version,
+        description: resolution.manifest.description,
+        command: resolution.manifest.command,
+        tags: resolution.manifest.tags,
+        authors: resolution.manifest.authors,
+        source: "local",
+        manifestPath: resolution.manifestPath,
+      });
+      return;
+    }
+
+    displayLocalToolInfo(
+      resolution.manifest.name ?? toolName,
+      resolution.manifest as unknown as Record<string, unknown>,
+      resolution.manifestPath,
+      options
+    );
+    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);
+  }
+
   const config = loadConfig();
   const registryUrl =
     process.env.ENACT_REGISTRY_URL ??
@@ -190,17 +276,18 @@ async function getHandler(
 }
 
 /**
- * Configure the get command
+ * Configure the info command
  */
-export function configureGetCommand(program: Command): void {
+export function configureInfoCommand(program: Command): void {
   program
-    .command("get <tool>")
-    .alias("info")
-    .description("Show detailed information about a tool")
+    .command("info <tool>")
+    .alias("get")
+    .description("Show detailed information about a tool (local path or registry)")
     .option("--ver <version>", "Show info for a specific version")
     .option("-v, --verbose", "Show detailed output")
+    .option("--local", "Only check locally installed tools")
     .option("--json", "Output as JSON")
-    .action(async (toolName: string, options: GetOptions) => {
+    .action(async (toolName: string, options: InfoOptions) => {
       const ctx: CommandContext = {
         cwd: process.cwd(),
         options,
@@ -209,7 +296,7 @@ export function configureGetCommand(program: Command): void {
       };
 
       try {
-        await getHandler(toolName, options, ctx);
+        await infoHandler(toolName, options, ctx);
       } catch (err) {
         error(formatError(err));
         process.exit(1);

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
@@ -543,9 +545,9 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
   const isClaudeMode = options.claude;
   // Default to agent mode if no flag specified
 
-  // Handle --tool mode: create enact.md + AGENTS.md for tool development
+  // Handle --tool mode: create SKILL.md + AGENTS.md for tool development
   if (isToolMode) {
-    const manifestPath = join(targetDir, "enact.md");
+    const manifestPath = join(targetDir, "SKILL.md");
     const agentsPath = join(targetDir, "AGENTS.md");
 
     if (existsSync(manifestPath) && !options.force) {
@@ -571,7 +573,7 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
 
     // Load templates with placeholder replacement
     const replacements = { TOOL_NAME: toolName };
-    const manifestContent = loadTemplate("tool-enact.md", replacements);
+    const manifestContent = loadTemplate("tool-skill.md", replacements);
     const agentsContent = loadTemplate("tool-agents.md", replacements);
 
     // Ensure directory exists
@@ -579,7 +581,7 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
       mkdirSync(targetDir, { recursive: true });
     }
 
-    // Write enact.md
+    // Write SKILL.md
     writeFileSync(manifestPath, manifestContent, "utf-8");
     success(`Created tool manifest: ${manifestPath}`);
 
@@ -593,7 +595,7 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
 
     info("");
     info("Next steps:");
-    info("  1. Edit enact.md to customize your tool");
+    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;
@@ -637,7 +639,8 @@ async function initHandler(options: InitOptions, ctx: CommandContext): Promise<v
 
   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("Run 'enact search <query>' to find tools, 'enact learn <tool>' to view docs,");
+  info("and 'enact install <tool>' to add them.");
 }
 
 /**
@@ -649,7 +652,7 @@ 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 (enact.md + AGENTS.md)")
+    .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")

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(),