@enactprotocol/cli 2.1.10 → 2.1.15

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

@@ -39,10 +39,15 @@ import { loadGitignore, shouldIgnore } from "../../utils/ignore";
 const AUTH_NAMESPACE = "enact:auth";
 const ACCESS_TOKEN_KEY = "access_token";
 
+/** Tool visibility levels */
+export type ToolVisibility = "public" | "private" | "unlisted";
+
 interface PublishOptions extends GlobalOptions {
   dryRun?: boolean;
   tag?: string;
   skipAuth?: boolean;
+  public?: boolean;
+  unlisted?: boolean;
 }
 
 /**
@@ -203,10 +208,18 @@ async function publishHandler(
   header(`Publishing ${toolName}@${version}`);
   newline();
 
+  // Determine visibility (private by default for security)
+  const visibility: ToolVisibility = options.public
+    ? "public"
+    : options.unlisted
+      ? "unlisted"
+      : "private";
+
   // Show what we're publishing
   keyValue("Name", toolName);
   keyValue("Version", version);
   keyValue("Description", manifest.description);
+  keyValue("Visibility", visibility);
   if (manifest.tags && manifest.tags.length > 0) {
     keyValue("Tags", manifest.tags.join(", "));
   }
@@ -290,6 +303,7 @@ async function publishHandler(
     info("Would publish to registry:");
     keyValue("Tool", toolName);
     keyValue("Version", version);
+    keyValue("Visibility", visibility);
     keyValue("Source", toolDir);
 
     // Show files that would be bundled
@@ -326,6 +340,7 @@ async function publishHandler(
       manifest: manifest as unknown as Record<string, unknown>,
       bundle,
       rawManifest: rawManifestContent,
+      visibility,
     });
   });
 
@@ -337,10 +352,15 @@ async function publishHandler(
 
   // Success output
   newline();
-  success(`Published ${result.name}@${result.version}`);
+  success(`Published ${result.name}@${result.version} (${visibility})`);
   keyValue("Bundle Hash", result.bundleHash);
   keyValue("Published At", result.publishedAt.toISOString());
   newline();
+  if (visibility === "private") {
+    dim("This tool is private - only you can access it.");
+  } else if (visibility === "unlisted") {
+    dim("This tool is unlisted - accessible via direct link, not searchable.");
+  }
   dim(`Install with: enact install ${toolName}`);
 }
 
@@ -356,6 +376,8 @@ export function configurePublishCommand(program: Command): void {
     .option("-v, --verbose", "Show detailed output")
     .option("--skip-auth", "Skip authentication (for local development)")
     .option("--json", "Output as JSON")
+    .option("--public", "Publish as public (searchable by everyone)")
+    .option("--unlisted", "Publish as unlisted (accessible via direct link, not searchable)")
     .action(async (pathArg: string | undefined, options: PublishOptions) => {
       const resolvedPath = pathArg ?? ".";
       const ctx: CommandContext = {

package/src/commands/visibility/index.ts

@@ -0,0 +1,154 @@
+/**
+ * enact visibility command
+ *
+ * Change the visibility of a published tool.
+ */
+
+import { getSecret } from "@enactprotocol/secrets";
+import { loadConfig } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import {
+  dim,
+  error,
+  extractNamespace,
+  formatError,
+  getCurrentUsername,
+  header,
+  info,
+  json,
+  newline,
+  success,
+} from "../../utils";
+
+/** Auth namespace for token storage */
+const AUTH_NAMESPACE = "enact:auth";
+const ACCESS_TOKEN_KEY = "access_token";
+
+/** Valid visibility levels */
+const VALID_VISIBILITIES = ["public", "private", "unlisted"] as const;
+type Visibility = (typeof VALID_VISIBILITIES)[number];
+
+interface VisibilityOptions extends GlobalOptions {
+  json?: boolean;
+}
+
+/**
+ * Visibility command handler
+ */
+async function visibilityHandler(
+  tool: string,
+  visibility: string,
+  options: VisibilityOptions,
+  _ctx: CommandContext
+): Promise<void> {
+  // Validate visibility value
+  if (!VALID_VISIBILITIES.includes(visibility as Visibility)) {
+    error(`Invalid visibility: ${visibility}`);
+    newline();
+    dim(`Valid values: ${VALID_VISIBILITIES.join(", ")}`);
+    process.exit(1);
+  }
+
+  header(`Changing visibility for ${tool}`);
+  newline();
+
+  // Pre-flight namespace check
+  const currentUsername = await getCurrentUsername();
+  if (currentUsername) {
+    const toolNamespace = extractNamespace(tool);
+    if (toolNamespace !== currentUsername) {
+      error(
+        `Namespace mismatch: Tool namespace "${toolNamespace}" does not match your username "${currentUsername}".`
+      );
+      newline();
+      dim("You can only change visibility for your own tools.");
+      process.exit(1);
+    }
+  }
+
+  // Get registry URL from config or environment
+  const config = loadConfig();
+  const registryUrl =
+    process.env.ENACT_REGISTRY_URL ??
+    config.registry?.url ??
+    "https://siikwkfgsmouioodghho.supabase.co/functions/v1";
+
+  // Get auth token
+  let authToken = await getSecret(AUTH_NAMESPACE, ACCESS_TOKEN_KEY);
+  if (!authToken) {
+    authToken = config.registry?.authToken ?? process.env.ENACT_AUTH_TOKEN ?? null;
+  }
+  if (!authToken) {
+    error("Not authenticated. Please run: enact auth login");
+    process.exit(1);
+  }
+
+  // Make the API request to change visibility
+  const response = await fetch(`${registryUrl}/tools/${tool}/visibility`, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ visibility }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    try {
+      const errorJson = JSON.parse(errorText);
+      error(`Failed to change visibility: ${errorJson.error?.message ?? errorText}`);
+    } catch {
+      error(`Failed to change visibility: ${errorText}`);
+    }
+    process.exit(1);
+  }
+
+  // Parse response (we don't use it but need to consume the body)
+  await response.json();
+
+  // JSON output
+  if (options.json) {
+    json({ tool, visibility, success: true });
+    return;
+  }
+
+  // Success output
+  success(`${tool} is now ${visibility}`);
+  newline();
+
+  if (visibility === "private") {
+    info("This tool is now private - only you can access it.");
+  } else if (visibility === "unlisted") {
+    info("This tool is now unlisted - accessible via direct link, but not searchable.");
+  } else {
+    info("This tool is now public - anyone can find and install it.");
+  }
+}
+
+/**
+ * Configure the visibility command
+ */
+export function configureVisibilityCommand(program: Command): void {
+  program
+    .command("visibility <tool> <visibility>")
+    .description("Change tool visibility (public, private, or unlisted)")
+    .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Show detailed output")
+    .action(async (tool: string, visibility: string, options: VisibilityOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await visibilityHandler(tool, visibility, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -29,11 +29,12 @@ import {
   configureSignCommand,
   configureTrustCommand,
   configureUnyankCommand,
+  configureVisibilityCommand,
   configureYankCommand,
 } from "./commands";
 import { error, formatError } from "./utils";
 
-export const version = "2.1.10";
+export const version = "2.1.15";
 
 // Export types for external use
 export type { GlobalOptions, CommandContext } from "./types";
@@ -78,6 +79,9 @@ async function main() {
   configureYankCommand(program);
   configureUnyankCommand(program);
 
+  // Private tools - visibility management
+  configureVisibilityCommand(program);
+
   // Global error handler - handle Commander's help/version exits gracefully
   program.exitOverride((err) => {
     // Commander throws errors for help, version, and other "exit" scenarios

package/tests/commands/publish.test.ts

@@ -54,6 +54,56 @@ describe("publish command", () => {
       const jsonOpt = opts.find((o) => o.long === "--json");
       expect(jsonOpt).toBeDefined();
     });
+
+    test("has --public option", () => {
+      const program = new Command();
+      configurePublishCommand(program);
+
+      const publishCmd = program.commands.find((cmd) => cmd.name() === "publish");
+      const opts = publishCmd?.options ?? [];
+      const publicOpt = opts.find((o) => o.long === "--public");
+      expect(publicOpt).toBeDefined();
+    });
+
+    test("has --unlisted option", () => {
+      const program = new Command();
+      configurePublishCommand(program);
+
+      const publishCmd = program.commands.find((cmd) => cmd.name() === "publish");
+      const opts = publishCmd?.options ?? [];
+      const unlistedOpt = opts.find((o) => o.long === "--unlisted");
+      expect(unlistedOpt).toBeDefined();
+    });
+  });
+
+  describe("visibility determination", () => {
+    type ToolVisibility = "public" | "private" | "unlisted";
+
+    // Mirrors the logic in publish command
+    const determineVisibility = (options: {
+      public?: boolean;
+      unlisted?: boolean;
+    }): ToolVisibility => {
+      if (options.public) return "public";
+      if (options.unlisted) return "unlisted";
+      return "private"; // Default is private
+    };
+
+    test("defaults to private visibility", () => {
+      expect(determineVisibility({})).toBe("private");
+    });
+
+    test("--public flag sets public visibility", () => {
+      expect(determineVisibility({ public: true })).toBe("public");
+    });
+
+    test("--unlisted flag sets unlisted visibility", () => {
+      expect(determineVisibility({ unlisted: true })).toBe("unlisted");
+    });
+
+    test("--public takes precedence over --unlisted", () => {
+      expect(determineVisibility({ public: true, unlisted: true })).toBe("public");
+    });
   });
 
   describe("manifest file detection", () => {