@enactprotocol/cli 1.2.13 → 2.0.0

package/src/utils/errors.ts

@@ -0,0 +1,409 @@
+/**
+ * Error handling utilities for CLI
+ *
+ * Provides consistent error handling with helpful suggestions
+ */
+
+import {
+  EXIT_AUTH_ERROR,
+  EXIT_CONFIG,
+  EXIT_CONTAINER_ERROR,
+  EXIT_EXECUTION_ERROR,
+  EXIT_FAILURE,
+  EXIT_MANIFEST_ERROR,
+  EXIT_NETWORK_ERROR,
+  EXIT_NOINPUT,
+  EXIT_NOPERM,
+  EXIT_REGISTRY_ERROR,
+  EXIT_TIMEOUT,
+  EXIT_TOOL_NOT_FOUND,
+  EXIT_TRUST_ERROR,
+  EXIT_USAGE,
+  EXIT_VALIDATION_ERROR,
+} from "./exit-codes";
+import { colors, dim, newline, error as printError, suggest } from "./output";
+
+// ============================================================================
+// Error Classes
+// ============================================================================
+
+/**
+ * Base CLI error with exit code
+ */
+export class CliError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number = EXIT_FAILURE,
+    public readonly suggestion?: string
+  ) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+/**
+ * Tool not found error
+ */
+export class ToolNotFoundError extends CliError {
+  constructor(toolName: string) {
+    super(
+      `Tool not found: ${toolName}`,
+      EXIT_TOOL_NOT_FOUND,
+      "Check the tool name or provide a path to a local tool.\nFor registry tools, use the format: owner/namespace/tool[@version]"
+    );
+    this.name = "ToolNotFoundError";
+  }
+}
+
+/**
+ * Manifest error
+ */
+export class ManifestError extends CliError {
+  constructor(message: string, path?: string) {
+    const fullMessage = path ? `${message} in ${path}` : message;
+    super(
+      fullMessage,
+      EXIT_MANIFEST_ERROR,
+      "Ensure the directory contains a valid enact.yaml or enact.md file."
+    );
+    this.name = "ManifestError";
+  }
+}
+
+/**
+ * Validation error
+ */
+export class ValidationError extends CliError {
+  constructor(message: string, field?: string) {
+    const fullMessage = field ? `Invalid ${field}: ${message}` : message;
+    super(fullMessage, EXIT_VALIDATION_ERROR);
+    this.name = "ValidationError";
+  }
+}
+
+/**
+ * Authentication error
+ */
+export class AuthError extends CliError {
+  constructor(message: string) {
+    super(message, EXIT_AUTH_ERROR, "Run 'enact auth login' to authenticate.");
+    this.name = "AuthError";
+  }
+}
+
+/**
+ * Network error
+ */
+export class NetworkError extends CliError {
+  constructor(message: string) {
+    super(message, EXIT_NETWORK_ERROR, "Check your network connection and try again.");
+    this.name = "NetworkError";
+  }
+}
+
+/**
+ * Registry error
+ */
+export class RegistryError extends CliError {
+  constructor(message: string) {
+    super(
+      message,
+      EXIT_REGISTRY_ERROR,
+      "The registry may be temporarily unavailable. Try again later."
+    );
+    this.name = "RegistryError";
+  }
+}
+
+/**
+ * Trust verification error
+ */
+export class TrustError extends CliError {
+  constructor(message: string) {
+    super(
+      message,
+      EXIT_TRUST_ERROR,
+      "Verify the tool's attestations with 'enact trust check <tool>'"
+    );
+    this.name = "TrustError";
+  }
+}
+
+/**
+ * Timeout error
+ */
+export class TimeoutError extends CliError {
+  constructor(operation: string, timeoutMs: number) {
+    const timeoutSec = Math.round(timeoutMs / 1000);
+    super(
+      `${operation} timed out after ${timeoutSec}s`,
+      EXIT_TIMEOUT,
+      "Try increasing the timeout with --timeout option."
+    );
+    this.name = "TimeoutError";
+  }
+}
+
+/**
+ * Execution error
+ */
+export class ExecutionError extends CliError {
+  constructor(
+    message: string,
+    public readonly stderr?: string
+  ) {
+    super(message, EXIT_EXECUTION_ERROR);
+    this.name = "ExecutionError";
+  }
+}
+
+/**
+ * Container error
+ */
+export class ContainerError extends CliError {
+  constructor(message: string) {
+    super(message, EXIT_CONTAINER_ERROR, "Ensure Docker or another container runtime is running.");
+    this.name = "ContainerError";
+  }
+}
+
+/**
+ * File not found error
+ */
+export class FileNotFoundError extends CliError {
+  constructor(path: string) {
+    super(`File not found: ${path}`, EXIT_NOINPUT);
+    this.name = "FileNotFoundError";
+  }
+}
+
+/**
+ * Permission error
+ */
+export class PermissionError extends CliError {
+  constructor(path: string) {
+    super(`Permission denied: ${path}`, EXIT_NOPERM);
+    this.name = "PermissionError";
+  }
+}
+
+/**
+ * Configuration error
+ */
+export class ConfigError extends CliError {
+  constructor(message: string) {
+    super(message, EXIT_CONFIG, "Check your configuration with 'enact config list'.");
+    this.name = "ConfigError";
+  }
+}
+
+/**
+ * Usage error (invalid arguments)
+ */
+export class UsageError extends CliError {
+  constructor(message: string) {
+    super(message, EXIT_USAGE);
+    this.name = "UsageError";
+  }
+}
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+/**
+ * Handle an error and exit with appropriate code
+ */
+export function handleError(err: unknown, options?: { verbose: boolean }): never {
+  if (err instanceof CliError) {
+    printError(err.message);
+    if (err.suggestion) {
+      suggest(err.suggestion);
+    }
+    if (options?.verbose && err.stack) {
+      newline();
+      dim(err.stack);
+    }
+    process.exit(err.exitCode);
+  }
+
+  // Handle standard errors
+  if (err instanceof Error) {
+    printError(err.message);
+    if (options?.verbose && err.stack) {
+      newline();
+      dim(err.stack);
+    }
+    process.exit(EXIT_FAILURE);
+  }
+
+  // Handle unknown errors
+  printError(String(err));
+  process.exit(EXIT_FAILURE);
+}
+
+/**
+ * Wrap an async function with error handling
+ */
+export function withErrorHandling<T extends unknown[]>(
+  fn: (...args: T) => Promise<void>,
+  options?: { verbose: boolean }
+): (...args: T) => Promise<void> {
+  return async (...args: T) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      handleError(err, options);
+    }
+  };
+}
+
+/**
+ * Categorize an error and return appropriate CliError
+ */
+export function categorizeError(err: unknown): CliError {
+  if (err instanceof CliError) {
+    return err;
+  }
+
+  if (err instanceof Error) {
+    const message = err.message.toLowerCase();
+
+    // Network errors
+    if (
+      message.includes("network") ||
+      message.includes("econnrefused") ||
+      message.includes("enotfound") ||
+      message.includes("etimedout") ||
+      message.includes("fetch failed")
+    ) {
+      return new NetworkError(err.message);
+    }
+
+    // Permission errors
+    if (
+      message.includes("eacces") ||
+      message.includes("permission denied") ||
+      message.includes("eperm")
+    ) {
+      return new PermissionError(err.message);
+    }
+
+    // File not found
+    if (message.includes("enoent") || message.includes("no such file")) {
+      return new FileNotFoundError(err.message);
+    }
+
+    // Timeout
+    if (message.includes("timeout") || message.includes("timed out")) {
+      return new TimeoutError("Operation", 30000);
+    }
+
+    // Authentication
+    if (
+      message.includes("unauthorized") ||
+      message.includes("401") ||
+      message.includes("authentication")
+    ) {
+      return new AuthError(err.message);
+    }
+
+    // Return generic CliError
+    return new CliError(err.message);
+  }
+
+  return new CliError(String(err));
+}
+
+// ============================================================================
+// Error Messages with Actions
+// ============================================================================
+
+/**
+ * Common error messages with actionable suggestions
+ */
+export const ErrorMessages = {
+  toolNotFound: (name: string) => ({
+    message: `Tool "${name}" not found`,
+    suggestions: [
+      "Check the tool name spelling",
+      `Search for tools: ${colors.command("enact search <query>")}`,
+      `Install from path: ${colors.command("enact install ./path/to/tool")}`,
+    ],
+  }),
+
+  notAuthenticated: () => ({
+    message: "You are not authenticated",
+    suggestions: [
+      `Log in: ${colors.command("enact auth login")}`,
+      `Check status: ${colors.command("enact auth status")}`,
+    ],
+  }),
+
+  manifestNotFound: (dir: string) => ({
+    message: `No manifest found in ${dir}`,
+    suggestions: [
+      `Create a manifest: ${colors.command("enact init")}`,
+      "Ensure the directory contains enact.yaml or enact.md",
+    ],
+  }),
+
+  invalidManifest: (errors: string[]) => ({
+    message: "Invalid manifest",
+    suggestions: [
+      "Fix the following errors:",
+      ...errors.map((e) => `  ${colors.error("•")} ${e}`),
+      `Validate manifest: ${colors.command("enact validate")}`,
+    ],
+  }),
+
+  registryUnavailable: () => ({
+    message: "Registry is unavailable",
+    suggestions: [
+      "Check your internet connection",
+      `Verify registry URL: ${colors.command("enact config get registry.url")}`,
+      "Try again later",
+    ],
+  }),
+
+  containerRuntimeNotFound: () => ({
+    message: "No container runtime found",
+    suggestions: [
+      "Install Docker: https://docs.docker.com/get-docker/",
+      "Or install Podman: https://podman.io/getting-started/installation",
+      "Ensure the runtime is running",
+    ],
+  }),
+
+  trustVerificationFailed: (tool: string) => ({
+    message: `Trust verification failed for "${tool}"`,
+    suggestions: [
+      "The tool has no valid attestations",
+      `Add a trusted publisher: ${colors.command("enact trust add <identity>")}`,
+      `Check attestations: ${colors.command(`enact trust check ${tool}`)}`,
+    ],
+  }),
+
+  executionFailed: (tool: string, exitCode: number) => ({
+    message: `Tool "${tool}" failed with exit code ${exitCode}`,
+    suggestions: [
+      "Check tool logs for details",
+      "Verify input parameters",
+      `Run with verbose output: ${colors.command("enact run --verbose")}`,
+    ],
+  }),
+};
+
+/**
+ * Print an error with actionable suggestions
+ */
+export function printErrorWithSuggestions(errorInfo: {
+  message: string;
+  suggestions: string[];
+}): void {
+  printError(errorInfo.message);
+  newline();
+  for (const suggestion of errorInfo.suggestions) {
+    console.log(`  ${colors.dim("•")} ${suggestion}`);
+  }
+}

package/src/utils/exit-codes.ts

@@ -0,0 +1,159 @@
+/**
+ * Exit codes for CLI commands
+ *
+ * Standardized exit codes following Unix conventions:
+ * - 0: Success
+ * - 1: General error
+ * - 2: Misuse of shell command (invalid args)
+ * - 64-78: BSD sysexits.h codes
+ * - 128+: Signal-based exits
+ *
+ * @see https://www.freebsd.org/cgi/man.cgi?query=sysexits
+ */
+
+/** Success - command completed successfully */
+export const EXIT_SUCCESS = 0;
+
+/** General error - unspecified failure */
+export const EXIT_FAILURE = 1;
+
+/** Usage error - invalid command line arguments */
+export const EXIT_USAGE = 2;
+
+/** Data error - input data was incorrect */
+export const EXIT_DATAERR = 65;
+
+/** No input - input file did not exist or was not readable */
+export const EXIT_NOINPUT = 66;
+
+/** No user - user does not exist */
+export const EXIT_NOUSER = 67;
+
+/** No host - host does not exist */
+export const EXIT_NOHOST = 68;
+
+/** Service unavailable - a required service is unavailable */
+export const EXIT_UNAVAILABLE = 69;
+
+/** Software error - internal error */
+export const EXIT_SOFTWARE = 70;
+
+/** OS error - system error */
+export const EXIT_OSERR = 71;
+
+/** OS file - system file missing or not creatable */
+export const EXIT_OSFILE = 72;
+
+/** Can't create - output file cannot be created */
+export const EXIT_CANTCREAT = 73;
+
+/** I/O error - input/output error */
+export const EXIT_IOERR = 74;
+
+/** Temp failure - temporary failure, try again */
+export const EXIT_TEMPFAIL = 75;
+
+/** Protocol error - remote error in protocol */
+export const EXIT_PROTOCOL = 76;
+
+/** No permission - permission denied */
+export const EXIT_NOPERM = 77;
+
+/** Configuration error - configuration error */
+export const EXIT_CONFIG = 78;
+
+// ============================================================================
+// Enact-specific exit codes (100-119)
+// ============================================================================
+
+/** Tool not found */
+export const EXIT_TOOL_NOT_FOUND = 100;
+
+/** Manifest error - invalid or missing manifest */
+export const EXIT_MANIFEST_ERROR = 101;
+
+/** Execution error - tool execution failed */
+export const EXIT_EXECUTION_ERROR = 102;
+
+/** Timeout error - operation timed out */
+export const EXIT_TIMEOUT = 103;
+
+/** Trust error - trust verification failed */
+export const EXIT_TRUST_ERROR = 104;
+
+/** Registry error - registry communication failed */
+export const EXIT_REGISTRY_ERROR = 105;
+
+/** Authentication error - not authenticated or token expired */
+export const EXIT_AUTH_ERROR = 106;
+
+/** Validation error - input validation failed */
+export const EXIT_VALIDATION_ERROR = 107;
+
+/** Network error - network communication failed */
+export const EXIT_NETWORK_ERROR = 108;
+
+/** Container error - container runtime error */
+export const EXIT_CONTAINER_ERROR = 109;
+
+// ============================================================================
+// Exit code descriptions
+// ============================================================================
+
+const EXIT_CODE_DESCRIPTIONS: Record<number, string> = {
+  [EXIT_SUCCESS]: "Success",
+  [EXIT_FAILURE]: "General error",
+  [EXIT_USAGE]: "Invalid command line arguments",
+  [EXIT_DATAERR]: "Input data was incorrect",
+  [EXIT_NOINPUT]: "Input file not found or not readable",
+  [EXIT_NOUSER]: "User not found",
+  [EXIT_NOHOST]: "Host not found",
+  [EXIT_UNAVAILABLE]: "Service unavailable",
+  [EXIT_SOFTWARE]: "Internal software error",
+  [EXIT_OSERR]: "System error",
+  [EXIT_OSFILE]: "System file missing",
+  [EXIT_CANTCREAT]: "Cannot create output file",
+  [EXIT_IOERR]: "I/O error",
+  [EXIT_TEMPFAIL]: "Temporary failure, try again",
+  [EXIT_PROTOCOL]: "Protocol error",
+  [EXIT_NOPERM]: "Permission denied",
+  [EXIT_CONFIG]: "Configuration error",
+  [EXIT_TOOL_NOT_FOUND]: "Tool not found",
+  [EXIT_MANIFEST_ERROR]: "Manifest error",
+  [EXIT_EXECUTION_ERROR]: "Tool execution failed",
+  [EXIT_TIMEOUT]: "Operation timed out",
+  [EXIT_TRUST_ERROR]: "Trust verification failed",
+  [EXIT_REGISTRY_ERROR]: "Registry error",
+  [EXIT_AUTH_ERROR]: "Authentication error",
+  [EXIT_VALIDATION_ERROR]: "Validation error",
+  [EXIT_NETWORK_ERROR]: "Network error",
+  [EXIT_CONTAINER_ERROR]: "Container runtime error",
+};
+
+/**
+ * Get description for an exit code
+ */
+export function getExitCodeDescription(code: number): string {
+  return EXIT_CODE_DESCRIPTIONS[code] ?? `Unknown error (code ${code})`;
+}
+
+/**
+ * Exit with a specific code
+ */
+export function exit(code: number): never {
+  process.exit(code);
+}
+
+/**
+ * Exit with success
+ */
+export function exitSuccess(): never {
+  process.exit(EXIT_SUCCESS);
+}
+
+/**
+ * Exit with failure
+ */
+export function exitFailure(): never {
+  process.exit(EXIT_FAILURE);
+}

package/src/utils/ignore.ts

@@ -0,0 +1,147 @@
+/**
+ * File ignore utilities for bundling
+ *
+ * Provides gitignore-style pattern matching and default ignore lists
+ * to prevent sensitive files from being included in tool bundles.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Files/patterns that should never be included in bundles */
+export const ALWAYS_IGNORE = [
+  // Environment and secrets
+  ".env",
+  ".env.local",
+  ".env.development",
+  ".env.production",
+  ".env.*.local",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+
+  // Version control
+  ".git",
+  ".gitignore",
+  ".gitattributes",
+
+  // IDE/Editor
+  ".vscode",
+  ".idea",
+  "*.swp",
+  "*.swo",
+  "*~",
+
+  // OS files
+  ".DS_Store",
+  "Thumbs.db",
+  "desktop.ini",
+
+  // Dependencies
+  "node_modules",
+  "vendor",
+  "__pycache__",
+  "*.pyc",
+  ".venv",
+  "venv",
+
+  // Build artifacts
+  "dist",
+  "build",
+  "out",
+  "target",
+  "*.log",
+];
+
+/**
+ * Load and parse a .gitignore file from a directory
+ */
+export function loadGitignore(toolDir: string): string[] {
+  const gitignorePath = join(toolDir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    return [];
+  }
+
+  const content = readFileSync(gitignorePath, "utf-8");
+  return parseGitignoreContent(content);
+}
+
+/**
+ * Parse gitignore content string into patterns
+ */
+export function parseGitignoreContent(content: string): string[] {
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"));
+}
+
+/**
+ * Check if a path matches a gitignore-style pattern
+ */
+export function matchesPattern(relativePath: string, pattern: string): boolean {
+  // Handle negation patterns (we don't support re-including for now)
+  if (pattern.startsWith("!")) {
+    return false;
+  }
+
+  // Normalize pattern
+  let normalizedPattern = pattern;
+
+  // Handle directory-specific patterns (ending with /)
+  const isDirPattern = pattern.endsWith("/");
+  if (isDirPattern) {
+    normalizedPattern = pattern.slice(0, -1);
+  }
+
+  // Handle patterns starting with /
+  const isRooted = pattern.startsWith("/");
+  if (isRooted) {
+    normalizedPattern = normalizedPattern.slice(1);
+  }
+
+  // Simple glob matching
+  const regexPattern = normalizedPattern
+    .replace(/\./g, "\\.")
+    .replace(/\*\*/g, "<<<GLOBSTAR>>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<<GLOBSTAR>>>/g, ".*")
+    .replace(/\?/g, ".");
+
+  const regex = isRooted
+    ? new RegExp(`^${regexPattern}($|/)`)
+    : new RegExp(`(^|/)${regexPattern}($|/)`);
+
+  return regex.test(relativePath);
+}
+
+/**
+ * Check if a file should be ignored based on patterns
+ */
+export function shouldIgnore(
+  relativePath: string,
+  fileName: string,
+  ignorePatterns: string[] = []
+): boolean {
+  // Always skip hidden files (starting with .)
+  if (fileName.startsWith(".")) {
+    return true;
+  }
+
+  // Check against always-ignore list
+  for (const pattern of ALWAYS_IGNORE) {
+    if (matchesPattern(relativePath, pattern) || matchesPattern(fileName, pattern)) {
+      return true;
+    }
+  }
+
+  // Check against gitignore patterns
+  for (const pattern of ignorePatterns) {
+    if (matchesPattern(relativePath, pattern)) {
+      return true;
+    }
+  }
+
+  return false;
+}