@enactprotocol/cli 1.2.8 → 2.0.0

package/src/commands/get/index.ts

@@ -0,0 +1,198 @@
+/**
+ * enact get command
+ *
+ * Show detailed information about a tool from the registry.
+ */
+
+import {
+  type ToolInfo,
+  type ToolVersionInfo,
+  createApiClient,
+  getToolInfo,
+  getToolVersion,
+} from "@enactprotocol/api";
+import { loadConfig } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import {
+  dim,
+  error,
+  formatError,
+  header,
+  info,
+  json,
+  keyValue,
+  newline,
+  success,
+} from "../../utils";
+
+interface GetOptions extends GlobalOptions {
+  version?: string;
+}
+
+/**
+ * Format a date for display
+ */
+function formatDate(date: Date): string {
+  return date.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/**
+ * Display tool info
+ */
+function displayToolInfo(tool: ToolInfo, options: GetOptions): void {
+  header(tool.name);
+  newline();
+
+  info(tool.description);
+  newline();
+
+  keyValue("Latest Version", tool.latestVersion);
+  keyValue("License", tool.license);
+  keyValue("Created", formatDate(tool.createdAt));
+  keyValue("Updated", formatDate(tool.updatedAt));
+
+  if (tool.tags.length > 0) {
+    keyValue("Tags", tool.tags.join(", "));
+  }
+
+  if (tool.author) {
+    keyValue("Author", tool.author.username);
+  }
+
+  newline();
+  keyValue("Available Versions", tool.versions.join(", "));
+
+  if (options.verbose) {
+    newline();
+    dim("Use --version <ver> to see version-specific details");
+  }
+}
+
+/**
+ * Display version-specific info
+ */
+function displayVersionInfo(version: ToolVersionInfo): void {
+  header(`${version.name}@${version.version}`);
+  newline();
+
+  info(version.description);
+  newline();
+
+  keyValue("Version", version.version);
+  keyValue("License", version.license);
+  if (version.bundle) {
+    keyValue("Bundle Hash", version.bundle.hash);
+    keyValue("Bundle Size", `${(version.bundle.size / 1024).toFixed(1)} KB`);
+  }
+
+  if (version.yanked) {
+    newline();
+    dim(`⚠ This version is yanked${version.yankReason ? `: ${version.yankReason}` : ""}`);
+    if (version.yankReplacement) {
+      dim(`  Recommended: ${version.yankReplacement}`);
+    }
+  }
+
+  if (version.manifest) {
+    newline();
+    dim("Manifest:");
+    console.log(JSON.stringify(version.manifest, null, 2));
+  }
+}
+
+/**
+ * Get command handler
+ */
+async function getHandler(
+  toolName: string,
+  options: GetOptions,
+  ctx: CommandContext
+): Promise<void> {
+  const config = loadConfig();
+  const registryUrl =
+    process.env.ENACT_REGISTRY_URL ??
+    config.registry?.url ??
+    "https://siikwkfgsmouioodghho.supabase.co/functions/v1";
+  const authToken = config.registry?.authToken;
+  const client = createApiClient({
+    baseUrl: registryUrl,
+    authToken: authToken,
+  });
+
+  if (ctx.options.verbose) {
+    info(`Fetching info for: ${toolName}`);
+  }
+
+  try {
+    if (options.version) {
+      // Get specific version info
+      const versionInfo = await getToolVersion(client, toolName, options.version);
+
+      if (options.json) {
+        json(versionInfo);
+        return;
+      }
+
+      displayVersionInfo(versionInfo);
+    } else {
+      // Get general tool info
+      const toolInfo = await getToolInfo(client, toolName);
+
+      if (options.json) {
+        json(toolInfo);
+        return;
+      }
+
+      displayToolInfo(toolInfo, options);
+    }
+
+    newline();
+    success(`Install with: enact install ${toolName}`);
+  } catch (err) {
+    if (err instanceof Error) {
+      if (err.message.includes("not_found") || err.message.includes("404")) {
+        error(`Tool not found: ${toolName}`);
+        dim("Check the tool name or search with: enact search <query>");
+        process.exit(1);
+      }
+      if (err.message.includes("fetch")) {
+        error("Unable to connect to registry. Check your internet connection.");
+        process.exit(1);
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Configure the get command
+ */
+export function configureGetCommand(program: Command): void {
+  program
+    .command("get <tool>")
+    .alias("info")
+    .description("Show detailed information about a tool")
+    .option("-V, --version <version>", "Show info for a specific version")
+    .option("-v, --verbose", "Show detailed output")
+    .option("--json", "Output as JSON")
+    .action(async (toolName: string, options: GetOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await getHandler(toolName, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/index.ts

@@ -0,0 +1,30 @@
+/**
+ * CLI Commands Index
+ *
+ * Exports all command configuration functions.
+ */
+
+export { configureSetupCommand } from "./setup";
+export { configureRunCommand } from "./run";
+export { configureExecCommand } from "./exec";
+export { configureInstallCommand } from "./install";
+export { configureListCommand } from "./list";
+export { configureEnvCommand } from "./env";
+export { configureTrustCommand } from "./trust";
+export { configureConfigCommand } from "./config";
+
+// Registry commands (Phase 8)
+export { configureSearchCommand } from "./search";
+export { configureGetCommand } from "./get";
+export { configurePublishCommand } from "./publish";
+export { configureAuthCommand } from "./auth";
+export { configureCacheCommand } from "./cache";
+
+// CLI solidification commands (Phase 9)
+export { configureSignCommand } from "./sign";
+export { configureReportCommand } from "./report";
+export { configureInspectCommand } from "./inspect";
+
+// API v2 migration commands
+export { configureYankCommand } from "./yank";
+export { configureUnyankCommand } from "./unyank";

package/src/commands/inspect/index.ts

@@ -0,0 +1,264 @@
+/**
+ * enact inspect command
+ *
+ * Open a tool's page in the browser for inspection/review.
+ * Use --download to download locally for deeper code review.
+ * This allows reviewers to examine tool code before trusting it.
+ */
+
+import { mkdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createApiClient, downloadBundle, getToolInfo } from "@enactprotocol/api";
+import { getCacheDir, loadConfig, pathExists } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import {
+  EXIT_FAILURE,
+  RegistryError,
+  colors,
+  confirm,
+  dim,
+  error,
+  formatError,
+  handleError,
+  info,
+  json,
+  keyValue,
+  newline,
+  success,
+  symbols,
+  withSpinner,
+} from "../../utils";
+
+interface InspectOptions extends GlobalOptions {
+  output?: string;
+  force?: boolean;
+  download?: boolean;
+}
+
+/**
+ * Parse tool@version syntax
+ */
+function parseToolSpec(spec: string): { name: string; version: string | undefined } {
+  const match = spec.match(/^(@[^@/]+\/[^@]+|[^@]+)(?:@(.+))?$/);
+  if (match?.[1]) {
+    return {
+      name: match[1],
+      version: match[2],
+    };
+  }
+  return { name: spec, version: undefined };
+}
+
+/**
+ * Format bytes to human-readable string
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${(bytes / k ** i).toFixed(1)} ${sizes[i]}`;
+}
+
+/**
+ * Extract a tar.gz bundle to a directory
+ */
+async function extractBundle(bundleData: ArrayBuffer, destPath: string): Promise<void> {
+  const tempFile = join(getCacheDir(), `inspect-${Date.now()}.tar.gz`);
+  mkdirSync(dirname(tempFile), { recursive: true });
+  writeFileSync(tempFile, Buffer.from(bundleData));
+
+  mkdirSync(destPath, { recursive: true });
+
+  const proc = Bun.spawn(["tar", "-xzf", tempFile, "-C", destPath], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const exitCode = await proc.exited;
+
+  try {
+    unlinkSync(tempFile);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`Failed to extract bundle: ${stderr}`);
+  }
+}
+
+/**
+ * Inspect command handler
+ */
+async function inspectHandler(
+  toolSpec: string,
+  options: InspectOptions,
+  ctx: CommandContext
+): Promise<void> {
+  const { name: toolName, version } = parseToolSpec(toolSpec);
+
+  const config = loadConfig();
+  const registryUrl = config.registry?.url ?? "https://registry.enact.tools";
+
+  // Default behavior: open in browser
+  // Use --download to download locally instead
+  if (!options.download) {
+    const toolUrl = version
+      ? `${registryUrl}/tools/${toolName}/v/${version}`
+      : `${registryUrl}/tools/${toolName}`;
+
+    info(`Opening ${toolName} in browser...`);
+
+    // Open URL in default browser
+    const openCmd =
+      process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+
+    const proc = Bun.spawn([openCmd, toolUrl], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    await proc.exited;
+
+    if (options.json) {
+      json({ opened: true, url: toolUrl });
+    } else {
+      success(`Opened: ${toolUrl}`);
+    }
+    return;
+  }
+
+  const client = createApiClient({
+    baseUrl: registryUrl,
+    authToken: config.registry?.authToken,
+  });
+
+  // Determine target version
+  let targetVersion = version;
+
+  try {
+    if (!targetVersion) {
+      const metadata = await withSpinner(
+        `Fetching ${toolName} info...`,
+        async () => getToolInfo(client, toolName),
+        `${symbols.success} Found ${toolName}`
+      );
+      targetVersion = metadata.latestVersion;
+    }
+  } catch (err) {
+    throw new RegistryError(`Failed to fetch tool info: ${formatError(err)}`);
+  }
+
+  // Determine output directory
+  const outputDir = options.output
+    ? resolve(ctx.cwd, options.output)
+    : resolve(ctx.cwd, toolName.split("/").pop() ?? toolName);
+
+  // Check if output already exists
+  if (pathExists(outputDir) && !options.force) {
+    if (ctx.isInteractive) {
+      const shouldOverwrite = await confirm(`Directory ${outputDir} already exists. Overwrite?`);
+      if (!shouldOverwrite) {
+        info("Inspection cancelled.");
+        return;
+      }
+      rmSync(outputDir, { recursive: true, force: true });
+    } else {
+      error(`Directory ${outputDir} already exists. Use --force to overwrite.`);
+      process.exit(EXIT_FAILURE);
+    }
+  }
+
+  // Download bundle (no trust verification - this is for inspection)
+  let bundleResult: { data: ArrayBuffer; hash: string; size: number };
+  try {
+    bundleResult = await withSpinner(
+      `Downloading ${toolName}@${targetVersion}...`,
+      async () =>
+        downloadBundle(client, {
+          name: toolName,
+          version: targetVersion!,
+          verify: true,
+        }),
+      `${symbols.success} Downloaded`
+    );
+  } catch (err) {
+    throw new RegistryError(`Failed to download bundle: ${formatError(err)}`);
+  }
+
+  // Extract to output directory
+  try {
+    await withSpinner(
+      "Extracting...",
+      async () => extractBundle(bundleResult.data, outputDir),
+      `${symbols.success} Extracted`
+    );
+  } catch (err) {
+    throw new RegistryError(`Failed to extract bundle: ${formatError(err)}`);
+  }
+
+  // Output result
+  if (options.json) {
+    json({
+      inspected: true,
+      tool: toolName,
+      version: targetVersion,
+      location: outputDir,
+      hash: bundleResult.hash,
+      size: bundleResult.size,
+    });
+    return;
+  }
+
+  newline();
+  keyValue("Tool", toolName);
+  keyValue("Version", targetVersion ?? "unknown");
+  keyValue("Location", outputDir);
+  keyValue("Size", formatBytes(bundleResult.size));
+  keyValue("Hash", `${bundleResult.hash.substring(0, 20)}...`);
+  newline();
+
+  success(`Downloaded ${colors.bold(toolName)}@${targetVersion} for inspection`);
+  newline();
+
+  info("Next steps:");
+  dim(`  cd ${outputDir}`);
+  dim("  # Review the code, run security scans, test it");
+  dim("  # If it passes review, sign it:");
+  dim("  enact sign .");
+  dim("  # Or report issues:");
+  dim(`  enact report ${toolName}@${targetVersion} --reason "description"`);
+}
+
+/**
+ * Configure the inspect command
+ */
+export function configureInspectCommand(program: Command): void {
+  program
+    .command("inspect <tool[@version]>")
+    .description("Open a tool's page in browser for inspection (use --download to save locally)")
+    .option("-d, --download", "Download tool locally instead of opening in browser")
+    .option(
+      "-o, --output <path>",
+      "Output directory for download (default: tool name in current directory)"
+    )
+    .option("-f, --force", "Overwrite existing directory when downloading")
+    .option("-v, --verbose", "Show detailed output")
+    .option("--json", "Output result as JSON")
+    .action(async (toolSpec: string, options: InspectOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await inspectHandler(toolSpec, options, ctx);
+      } catch (err) {
+        handleError(err, options.verbose ? { verbose: true } : undefined);
+      }
+    });
+}

package/src/commands/install/README.md

@@ -0,0 +1,146 @@
+# enact install
+
+Install a tool to the project or user directory.
+
+## Synopsis
+
+```bash
+enact install [tool] [options]
+```
+
+## Description
+
+The `install` command copies a tool to either the project's `.enact/tools/` directory (default) or the user's `~/.enact/tools/` directory (with `--global`). This makes the tool available for execution without specifying the full path.
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `[tool]` | Tool to install. Can be a tool name, path, `.` for current directory, or omitted to install from `tools.json` |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Install to user directory (`~/.enact/tools/`) instead of project |
+| `-f, --force` | Overwrite existing installation without prompting |
+| `-v, --verbose` | Show detailed output |
+| `--json` | Output result as JSON |
+
+## Installation Scopes
+
+### Project Scope (Default)
+
+```bash
+enact install alice/utils/greeter
+```
+
+Installs to `.enact/tools/alice/utils/greeter/` in your project. This is ideal for:
+- Tools specific to a project
+- Team collaboration (commit `.enact/tools.json`)
+- Reproducible builds
+
+### Global Scope
+
+```bash
+enact install alice/utils/greeter --global
+```
+
+Installs to `~/.enact/tools/alice/utils/greeter/`. This is ideal for:
+- Tools you use across multiple projects
+- Personal utility tools
+- System-wide availability
+
+## Examples
+
+### Install from registry (future)
+
+```bash
+# Install to project
+enact install alice/utils/greeter
+
+# Install globally
+enact install alice/utils/greeter --global
+```
+
+### Install from local path
+
+```bash
+# Install current directory as a tool
+enact install .
+
+# Install from a specific path
+enact install ./my-tools/greeter
+
+# Install with absolute path
+enact install /path/to/tool
+```
+
+### Install all project tools
+
+```bash
+# Install all tools defined in .enact/tools.json
+enact install
+```
+
+### Force reinstall
+
+```bash
+# Overwrite existing installation
+enact install alice/utils/greeter --force
+```
+
+## Tool Resolution
+
+When installing by name, the command searches for the tool in this order:
+
+1. Project tools (`.enact/tools/`)
+2. User tools (`~/.enact/tools/`)
+3. Cache (`~/.enact/cache/`)
+4. Registry (future)
+
+## Directory Structure
+
+After installation, tools are organized by their namespaced name:
+
+```
+.enact/tools/
+├── alice/
+│   └── utils/
+│       └── greeter/
+│           ├── enact.md
+│           └── ...
+└── EnactProtocol/
+    └── pdf-extract/
+        ├── enact.yaml
+        └── ...
+```
+
+## tools.json
+
+The `.enact/tools.json` file tracks project dependencies:
+
+```json
+{
+  "tools": {
+    "alice/utils/greeter": "^1.0.0",
+    "EnactProtocol/pdf-extract": "2.1.0"
+  }
+}
+```
+
+Running `enact install` without arguments installs all tools from this file.
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Successful installation |
+| `1` | Installation failed |
+| `3` | Tool not found |
+
+## See Also
+
+- [enact list](../list/README.md) - List installed tools
+- [enact run](../run/README.md) - Execute tools
+- [enact search](../search/README.md) - Search for tools (future)