@runa-ai/runa-cli 0.5.72 → 0.7.0

package/dist/chunk-JQXOVCOP.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+import { createRequire } from 'module';
+import { init_esm_shims } from './chunk-VRXHCR5K.js';
+import { CLIError } from '@runa-ai/runa';
+
+createRequire(import.meta.url);
+
+// src/errors/catalog.ts
+init_esm_shims();
+
+// src/errors/exit-codes.ts
+init_esm_shims();
+var EXIT_CODES = {
+  GENERAL_ERROR: 1,
+  USAGE_ERROR: 2,
+  CONFIG_ERROR: 3,
+  AUTH_ERROR: 4,
+  NETWORK_ERROR: 5,
+  DATABASE_ERROR: 6,
+  EXTERNAL_TOOL_ERROR: 7,
+  GIT_ERROR: 8,
+  BUILD_ERROR: 9,
+  TEST_ERROR: 10
+};
+
+// src/errors/catalog.ts
+var ERROR_CATALOG = {
+  // ════════════════════════════════════════════════════
+  // Configuration Errors (Exit Code: 3)
+  // ════════════════════════════════════════════════════
+  CONFIG_NOT_FOUND: {
+    code: "ERR_RUNA_CONFIG_NOT_FOUND",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Configuration file not found",
+    template: "Configuration file not found: {path}",
+    suggestions: ["Run: runa init", "Ensure you are in a runa project directory"],
+    docUrl: "https://runa.dev/docs/errors/config-not-found"
+  },
+  CONFIG_INVALID: {
+    code: "ERR_RUNA_CONFIG_INVALID",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Invalid configuration",
+    template: "Invalid runa.config.ts: {reason}",
+    suggestions: ["Check runa.config.ts syntax", "Run: runa validate"],
+    docUrl: "https://runa.dev/docs/errors/config-invalid"
+  },
+  CONFIG_SCHEMA_MISMATCH: {
+    code: "ERR_RUNA_CONFIG_SCHEMA_MISMATCH",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Configuration schema mismatch",
+    template: "Configuration schema mismatch: {field} - {expected} expected, got {actual}",
+    suggestions: ["Run: runa upgrade", "Check CHANGELOG for breaking changes"],
+    docUrl: "https://runa.dev/docs/errors/config-schema"
+  },
+  ENV_FILE_NOT_FOUND: {
+    code: "ERR_RUNA_ENV_FILE_NOT_FOUND",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Environment file not found",
+    template: "Environment file not found: {path}",
+    suggestions: ["Run: runa env pull", "Run: runa env setup"],
+    docUrl: "https://runa.dev/docs/errors/env-file"
+  },
+  ENV_KEY_MISSING: {
+    code: "ERR_RUNA_ENV_KEY_MISSING",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Environment decryption key missing",
+    template: "Decryption key not found for {env} environment",
+    suggestions: ["Run: runa env pull", "Ensure .env.keys exists (gitignored)"],
+    docUrl: "https://runa.dev/docs/errors/env-key"
+  },
+  ENV_VAR_MISSING: {
+    code: "ERR_RUNA_ENV_VAR_MISSING",
+    exitCode: EXIT_CODES.CONFIG_ERROR,
+    title: "Required environment variable missing",
+    template: "Required environment variable not set: {varName}",
+    suggestions: (params) => [
+      `Set ${params.varName} in your environment`,
+      "Run: runa env pull",
+      "Check .env.development file"
+    ],
+    docUrl: "https://runa.dev/docs/errors/env-var"
+  },
+  // ════════════════════════════════════════════════════
+  // Authentication Errors (Exit Code: 4)
+  // ════════════════════════════════════════════════════
+  GITHUB_AUTH_REQUIRED: {
+    code: "ERR_RUNA_GITHUB_AUTH_REQUIRED",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "GitHub authentication required",
+    template: "GitHub authentication is required for this operation",
+    suggestions: ["Run: gh auth login", "Set GH_TOKEN or GITHUB_TOKEN environment variable"],
+    docUrl: "https://runa.dev/docs/errors/github-auth"
+  },
+  GITHUB_AUTH_FAILED: {
+    code: "ERR_RUNA_GITHUB_AUTH_FAILED",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "GitHub authentication failed",
+    template: "GitHub authentication failed: {reason}",
+    suggestions: [
+      "Run: gh auth logout && gh auth login",
+      "Check token permissions (read:packages required)"
+    ],
+    docUrl: "https://runa.dev/docs/errors/github-auth"
+  },
+  VERCEL_AUTH_REQUIRED: {
+    code: "ERR_RUNA_VERCEL_AUTH_REQUIRED",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "Vercel authentication required",
+    template: "Vercel authentication is required for this operation",
+    suggestions: ["Run: vercel login", "Set VERCEL_TOKEN environment variable"],
+    docUrl: "https://runa.dev/docs/errors/vercel-auth"
+  },
+  SUPABASE_AUTH_REQUIRED: {
+    code: "ERR_RUNA_SUPABASE_AUTH_REQUIRED",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "Supabase authentication required",
+    template: "Supabase authentication is required for this operation",
+    suggestions: ["Run: supabase login", "Check Supabase access token"],
+    docUrl: "https://runa.dev/docs/errors/supabase-auth"
+  },
+  AUTH_TOKEN_MISSING: {
+    code: "ERR_RUNA_AUTH_TOKEN_MISSING",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "Authentication token missing",
+    template: "{tokenName} is required for this operation",
+    suggestions: (params) => [
+      `Set ${params.tokenName} environment variable`,
+      "Check CI/CD secrets configuration"
+    ],
+    docUrl: "https://runa.dev/docs/errors/auth-token"
+  },
+  LICENSE_UNAUTHORIZED: {
+    code: "ERR_RUNA_LICENSE_UNAUTHORIZED",
+    exitCode: EXIT_CODES.AUTH_ERROR,
+    title: "CI access not authorized",
+    template: 'Organization "{owner}" is not authorized to use runa CI',
+    suggestions: [
+      "Install GitHub App: https://github.com/apps/runa-app",
+      "Contact runa admin for approval",
+      "Local development is not affected"
+    ],
+    docUrl: "https://runa.dev/docs/errors/license-unauthorized"
+  },
+  // ════════════════════════════════════════════════════
+  // Network Errors (Exit Code: 5)
+  // ════════════════════════════════════════════════════
+  NETWORK_TIMEOUT: {
+    code: "ERR_RUNA_NETWORK_TIMEOUT",
+    exitCode: EXIT_CODES.NETWORK_ERROR,
+    title: "Network request timeout",
+    template: "Request to {url} timed out after {timeout}ms",
+    suggestions: [
+      "Check your internet connection",
+      "Try again later",
+      "Check if the service is available"
+    ],
+    docUrl: "https://runa.dev/docs/errors/network"
+  },
+  NETWORK_CONNECTION_REFUSED: {
+    code: "ERR_RUNA_NETWORK_CONNECTION_REFUSED",
+    exitCode: EXIT_CODES.NETWORK_ERROR,
+    title: "Connection refused",
+    template: "Connection to {host}:{port} refused",
+    suggestions: (params) => [
+      `Ensure service is running on port ${params.port}`,
+      "Check firewall settings",
+      "Verify the host address is correct"
+    ],
+    docUrl: "https://runa.dev/docs/errors/network"
+  },
+  API_REQUEST_FAILED: {
+    code: "ERR_RUNA_API_REQUEST_FAILED",
+    exitCode: EXIT_CODES.NETWORK_ERROR,
+    title: "API request failed",
+    template: "API request to {endpoint} failed: {status} {statusText}",
+    suggestions: [
+      "Check API endpoint availability",
+      "Verify authentication credentials",
+      "Try again later"
+    ],
+    docUrl: "https://runa.dev/docs/errors/api"
+  },
+  // ════════════════════════════════════════════════════
+  // Database Errors (Exit Code: 6)
+  // ════════════════════════════════════════════════════
+  DATABASE_CONNECTION_FAILED: {
+    code: "ERR_RUNA_DATABASE_CONNECTION_FAILED",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Database connection failed",
+    template: "Failed to connect to database: {reason}",
+    suggestions: [
+      "Run: runa check --scope db",
+      "Ensure Docker is running: docker ps",
+      "Run: supabase start"
+    ],
+    docUrl: "https://runa.dev/docs/errors/database"
+  },
+  DATABASE_URL_MISSING: {
+    code: "ERR_RUNA_DATABASE_URL_MISSING",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Database URL not configured",
+    template: "DATABASE_URL is not set for {env} environment",
+    suggestions: ["Run: runa env pull", "Set DATABASE_URL in .env.{env}"],
+    docUrl: "https://runa.dev/docs/errors/database-url"
+  },
+  DATABASE_SCHEMA_SYNC_FAILED: {
+    code: "ERR_RUNA_DATABASE_SCHEMA_SYNC_FAILED",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Schema synchronization failed",
+    template: "Failed to sync database schema: {reason}",
+    suggestions: [
+      "Run: runa db sync --check (preview changes)",
+      "Check SQL syntax in supabase/schemas/",
+      "Run: runa check --verbose"
+    ],
+    docUrl: "https://runa.dev/docs/errors/schema-sync"
+  },
+  DATABASE_SEED_FAILED: {
+    code: "ERR_RUNA_DATABASE_SEED_FAILED",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Database seeding failed",
+    template: "Failed to apply seeds: {reason}",
+    suggestions: [
+      "Check seed file syntax",
+      "Run: runa db sync (sync schema first)",
+      "Check foreign key constraints"
+    ],
+    docUrl: "https://runa.dev/docs/errors/seed"
+  },
+  DATABASE_MIGRATION_HAZARD: {
+    code: "ERR_RUNA_DATABASE_MIGRATION_HAZARD",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Dangerous migration detected",
+    template: "pg-schema-diff detected hazardous changes: {hazards}",
+    suggestions: [
+      "Review the migration plan carefully",
+      "Use --auto-approve only if changes are intentional",
+      "Backup data before applying destructive changes"
+    ],
+    docUrl: "https://runa.dev/docs/errors/migration-hazard"
+  },
+  DATABASE_QUERY_FAILED: {
+    code: "ERR_RUNA_DATABASE_QUERY_FAILED",
+    exitCode: EXIT_CODES.DATABASE_ERROR,
+    title: "Database query failed",
+    template: "Query failed on {table}: {reason}",
+    suggestions: ["Check table existence", "Verify column names", "Check RLS policies"],
+    docUrl: "https://runa.dev/docs/errors/query"
+  },
+  // ════════════════════════════════════════════════════
+  // External Tool Errors (Exit Code: 7)
+  // ════════════════════════════════════════════════════
+  DOCKER_NOT_RUNNING: {
+    code: "ERR_RUNA_DOCKER_NOT_RUNNING",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "Docker is not running",
+    template: "Docker daemon is not running or not accessible",
+    suggestions: [
+      "Start Colima: colima start --cpu 4 --memory 8 --disk 60 --vm-type vz --mount-type virtiofs",
+      "Install Colima: brew install colima docker"
+    ],
+    docUrl: "https://runa.dev/docs/errors/docker"
+  },
+  DOCKER_DESKTOP_FORBIDDEN: {
+    code: "ERR_RUNA_DOCKER_DESKTOP_FORBIDDEN",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "Docker Desktop is not supported",
+    template: "Docker Desktop is not supported. runa requires Colima.",
+    suggestions: [
+      "Install Colima: brew install colima docker",
+      "Start Colima: colima start --cpu 4 --memory 8 --disk 60 --vm-type vz --mount-type virtiofs"
+    ],
+    docUrl: "https://runa.dev/docs/errors/docker"
+  },
+  TOOL_NOT_FOUND: {
+    code: "ERR_RUNA_TOOL_NOT_FOUND",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "Required tool not found",
+    template: "{tool} is not installed or not in PATH",
+    suggestions: (params) => {
+      const installCommands = {
+        supabase: "brew install supabase/tap/supabase",
+        vercel: "pnpm add -g vercel",
+        gh: "brew install gh",
+        docker: "Install Colima: brew install colima docker",
+        dotenvx: "pnpm add -g @dotenvx/dotenvx",
+        "pg-schema-diff": "brew install pg-schema-diff"
+      };
+      return [
+        `Install ${params.tool}: ${installCommands[params.tool] || `Check ${params.tool} installation docs`}`,
+        "Ensure the tool is in your PATH"
+      ];
+    },
+    docUrl: "https://runa.dev/docs/errors/tool-not-found"
+  },
+  TOOL_EXECUTION_FAILED: {
+    code: "ERR_RUNA_TOOL_EXECUTION_FAILED",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "External tool execution failed",
+    template: "{tool} command failed: {reason}",
+    suggestions: (params) => [
+      `Check ${params.tool} logs for details`,
+      `Run: ${params.tool} --version (verify installation)`,
+      "Check command arguments"
+    ],
+    docUrl: "https://runa.dev/docs/errors/tool-failed"
+  },
+  PORT_IN_USE: {
+    code: "ERR_RUNA_PORT_IN_USE",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "Port already in use",
+    template: "Port {port} is already in use",
+    suggestions: (params) => [
+      `Find process: lsof -i :${params.port}`,
+      `Kill process: kill -9 $(lsof -t -i:${params.port})`,
+      "Use a different port"
+    ],
+    docUrl: "https://runa.dev/docs/errors/port"
+  },
+  SUPABASE_CLI_ERROR: {
+    code: "ERR_RUNA_SUPABASE_CLI_ERROR",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "Supabase CLI error",
+    template: "Supabase CLI error: {reason}",
+    suggestions: [
+      "Run: supabase status",
+      "Run: supabase stop && supabase start",
+      "Check Docker container logs: docker logs supabase_db_*"
+    ],
+    docUrl: "https://runa.dev/docs/errors/supabase-cli"
+  },
+  PG_SCHEMA_DIFF_ERROR: {
+    code: "ERR_RUNA_PG_SCHEMA_DIFF_ERROR",
+    exitCode: EXIT_CODES.EXTERNAL_TOOL_ERROR,
+    title: "pg-schema-diff error",
+    template: "pg-schema-diff failed: {reason}",
+    suggestions: [
+      "Check SQL syntax in supabase/schemas/",
+      "Run: pg-schema-diff --help",
+      "Verify database connection"
+    ],
+    docUrl: "https://runa.dev/docs/errors/pg-schema-diff"
+  },
+  // ════════════════════════════════════════════════════
+  // Git Errors (Exit Code: 8)
+  // ════════════════════════════════════════════════════
+  GIT_DIRTY_WORKING_TREE: {
+    code: "ERR_RUNA_GIT_DIRTY_WORKING_TREE",
+    exitCode: EXIT_CODES.GIT_ERROR,
+    title: "Uncommitted changes detected",
+    template: "Working tree has uncommitted changes",
+    suggestions: [
+      "Commit your changes: git add . && git commit",
+      "Stash changes: git stash",
+      "Discard changes: git checkout ."
+    ],
+    docUrl: "https://runa.dev/docs/errors/git"
+  },
+  GIT_NOT_ON_BRANCH: {
+    code: "ERR_RUNA_GIT_NOT_ON_BRANCH",
+    exitCode: EXIT_CODES.GIT_ERROR,
+    title: "Not on a branch",
+    template: "Not on a branch (detached HEAD at {commit})",
+    suggestions: [
+      "Checkout a branch: git checkout main",
+      "Create a new branch: git checkout -b feature/name"
+    ],
+    docUrl: "https://runa.dev/docs/errors/git"
+  },
+  GIT_PUSH_FAILED: {
+    code: "ERR_RUNA_GIT_PUSH_FAILED",
+    exitCode: EXIT_CODES.GIT_ERROR,
+    title: "Git push failed",
+    template: "Failed to push to {remote}/{branch}: {reason}",
+    suggestions: [
+      "Pull latest changes: git pull --rebase",
+      "Check remote permissions",
+      "Verify branch protection rules"
+    ],
+    docUrl: "https://runa.dev/docs/errors/git"
+  },
+  // ════════════════════════════════════════════════════
+  // Build Errors (Exit Code: 9)
+  // ════════════════════════════════════════════════════
+  TYPE_CHECK_FAILED: {
+    code: "ERR_RUNA_TYPE_CHECK_FAILED",
+    exitCode: EXIT_CODES.BUILD_ERROR,
+    title: "TypeScript type check failed",
+    template: "Type check failed with {errorCount} error(s)",
+    suggestions: [
+      "Run: runa check --verbose (diagnose environment)",
+      "Run: runa db sync (if schema types missing)",
+      "Run: pnpm type-check (see all errors)"
+    ],
+    docUrl: "https://runa.dev/docs/errors/type-check"
+  },
+  LINT_FAILED: {
+    code: "ERR_RUNA_LINT_FAILED",
+    exitCode: EXIT_CODES.BUILD_ERROR,
+    title: "Lint check failed",
+    template: "Lint check failed with {errorCount} error(s)",
+    suggestions: [
+      "Run: pnpm lint --fix (auto-fix)",
+      "Run: runa check --verbose (diagnose environment)",
+      "Check biome.json configuration"
+    ],
+    docUrl: "https://runa.dev/docs/errors/lint"
+  },
+  BUILD_FAILED: {
+    code: "ERR_RUNA_BUILD_FAILED",
+    exitCode: EXIT_CODES.BUILD_ERROR,
+    title: "Build failed",
+    template: "Build failed for {package}: {reason}",
+    suggestions: [
+      "Run: runa build --clean",
+      "Check build logs for details",
+      "Run: runa check --verbose"
+    ],
+    docUrl: "https://runa.dev/docs/errors/build"
+  },
+  TURBO_CACHE_ERROR: {
+    code: "ERR_RUNA_TURBO_CACHE_ERROR",
+    exitCode: EXIT_CODES.BUILD_ERROR,
+    title: "Turbo cache error",
+    template: "Turbo cache error: {reason}",
+    suggestions: ["Clear cache: pnpm turbo clean", "Run: runa build --clean", "Check disk space"],
+    docUrl: "https://runa.dev/docs/errors/turbo"
+  },
+  // ════════════════════════════════════════════════════
+  // Test Errors (Exit Code: 10)
+  // ════════════════════════════════════════════════════
+  TEST_FAILED: {
+    code: "ERR_RUNA_TEST_FAILED",
+    exitCode: EXIT_CODES.TEST_ERROR,
+    title: "Tests failed",
+    template: "Tests failed: {passed} passed, {failed} failed",
+    suggestions: [
+      "Run: runa test --verbose",
+      "Check test output for details",
+      "Run: runa test --layer {layer} for specific layer"
+    ],
+    docUrl: "https://runa.dev/docs/errors/test"
+  },
+  TEST_TIMEOUT: {
+    code: "ERR_RUNA_TEST_TIMEOUT",
+    exitCode: EXIT_CODES.TEST_ERROR,
+    title: "Test timeout",
+    template: "Test timed out after {timeout}ms: {testName}",
+    suggestions: [
+      "Increase test timeout",
+      "Check for infinite loops or hanging promises",
+      "Run test in isolation"
+    ],
+    docUrl: "https://runa.dev/docs/errors/test-timeout"
+  },
+  // ════════════════════════════════════════════════════
+  // Usage Errors (Exit Code: 2)
+  // ════════════════════════════════════════════════════
+  INVALID_ARGUMENT: {
+    code: "ERR_RUNA_INVALID_ARGUMENT",
+    exitCode: EXIT_CODES.USAGE_ERROR,
+    title: "Invalid argument",
+    template: "Invalid argument: {argument} - {reason}",
+    suggestions: ["Run: runa {command} --help", "Check argument format"],
+    docUrl: "https://runa.dev/docs/errors/usage"
+  },
+  MISSING_ARGUMENT: {
+    code: "ERR_RUNA_MISSING_ARGUMENT",
+    exitCode: EXIT_CODES.USAGE_ERROR,
+    title: "Missing required argument",
+    template: "Missing required argument: {argument}",
+    suggestions: (params) => [`Provide --${params.argument}`, `Run: runa ${params.command} --help`],
+    docUrl: "https://runa.dev/docs/errors/usage"
+  },
+  INVALID_MODE: {
+    code: "ERR_RUNA_INVALID_MODE",
+    exitCode: EXIT_CODES.USAGE_ERROR,
+    title: "Invalid mode",
+    template: "Invalid mode: {mode}. Valid modes: {validModes}",
+    suggestions: (params) => [`Use one of: ${params.validModes}`, "Run: runa {command} --help"],
+    docUrl: "https://runa.dev/docs/errors/usage"
+  },
+  // ════════════════════════════════════════════════════
+  // General Errors (Exit Code: 1)
+  // ════════════════════════════════════════════════════
+  INTERNAL_ERROR: {
+    code: "ERR_RUNA_INTERNAL_ERROR",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "Internal error",
+    template: "An internal error occurred: {reason}",
+    suggestions: [
+      "This may be a bug. Please report at: https://github.com/anthropics/runa/issues",
+      "Include the full error message and stack trace"
+    ],
+    docUrl: "https://runa.dev/docs/errors/internal"
+  },
+  OPERATION_CANCELLED: {
+    code: "ERR_RUNA_OPERATION_CANCELLED",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "Operation cancelled",
+    template: "Operation was cancelled by user",
+    suggestions: [
+      "Re-run the command when ready",
+      "Use --force to skip confirmations (if supported)"
+    ]
+  },
+  MACHINE_NO_OUTPUT: {
+    code: "ERR_RUNA_MACHINE_NO_OUTPUT",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "State machine completed without output",
+    template: "State machine completed without producing output",
+    suggestions: ["This may be a bug. Please report it.", "Check machine configuration"],
+    docUrl: "https://runa.dev/docs/errors/machine"
+  },
+  TEMPLATES_NOT_FOUND: {
+    code: "ERR_RUNA_TEMPLATES_NOT_FOUND",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "Templates package not found",
+    template: "Templates package not found: {reason}",
+    suggestions: [
+      "Ensure @runa-ai/runa-templates is published",
+      "Check GitHub Packages authentication",
+      "Run: gh auth status"
+    ],
+    docUrl: "https://runa.dev/docs/errors/templates"
+  },
+  FILE_NOT_FOUND: {
+    code: "ERR_RUNA_FILE_NOT_FOUND",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "File not found",
+    template: "File not found: {path}",
+    suggestions: ["Check file path", "Ensure file exists"]
+  },
+  SCRIPT_NOT_FOUND: {
+    code: "ERR_RUNA_SCRIPT_NOT_FOUND",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "Script not found",
+    template: "Script not found: {path}",
+    suggestions: ["Check script path", "Ensure script exists in packages/database/scripts/"],
+    docUrl: "https://runa.dev/docs/errors/script"
+  },
+  HOTFIX_NOT_FOUND: {
+    code: "ERR_RUNA_HOTFIX_NOT_FOUND",
+    exitCode: EXIT_CODES.GENERAL_ERROR,
+    title: "No active hotfix found",
+    template: "No active hotfix found",
+    suggestions: ["Run: runa hotfix create <name>", "Check: runa hotfix status"],
+    docUrl: "https://runa.dev/docs/errors/hotfix"
+  },
+  HOTFIX_INVALID_NAME: {
+    code: "ERR_RUNA_HOTFIX_INVALID_NAME",
+    exitCode: EXIT_CODES.USAGE_ERROR,
+    title: "Invalid hotfix name",
+    template: "Invalid hotfix name: {name}. Use alphanumeric characters and hyphens only.",
+    suggestions: ["Example: hotfix-123", "Example: fix-login-bug"],
+    docUrl: "https://runa.dev/docs/errors/hotfix"
+  }
+};
+function createError(errorCode, params = {}) {
+  const definition = ERROR_CATALOG[errorCode];
+  const message = interpolateTemplate(definition.template, params);
+  const suggestions = typeof definition.suggestions === "function" ? definition.suggestions(params) : definition.suggestions;
+  const docUrl = "docUrl" in definition ? definition.docUrl : void 0;
+  const allSuggestions = docUrl ? [...suggestions, `Docs: ${docUrl}`] : suggestions;
+  return new CLIError(message, definition.code, allSuggestions, void 0, definition.exitCode);
+}
+function interpolateTemplate(template, params) {
+  return template.replace(/\{(\w+)\}/g, (_, key) => {
+    const value = params[key];
+    return value !== void 0 ? String(value) : `{${key}}`;
+  });
+}
+
+export { ERROR_CATALOG, createError };

package/dist/chunk-KE6QJBZG.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { createRequire } from 'module';
+import { createSuccessEnvelopeSchema, CLI_CONTRACT_VERSION, writeJsonEnvelope, markJsonEmitted } from './chunk-WJXC4MVY.js';
+import { getOutputFormatFromEnv } from './chunk-HKUWEGUX.js';
+import { init_esm_shims } from './chunk-VRXHCR5K.js';
+
+createRequire(import.meta.url);
+
+// src/cli/json-output.ts
+init_esm_shims();
+function getCommandPath(cmd) {
+  const parts = [];
+  let cur = cmd;
+  while (cur) {
+    const name = cur.name?.();
+    if (name && name !== "runa") parts.unshift(name);
+    cur = cur.parent ?? null;
+  }
+  return parts.length > 0 ? `runa ${parts.join(" ")}` : "runa";
+}
+function emitJsonSuccess(cmd, dataSchema, data) {
+  if (getOutputFormatFromEnv() !== "json") return;
+  const payload = {
+    version: CLI_CONTRACT_VERSION,
+    ok: true,
+    command: getCommandPath(cmd),
+    data
+  };
+  const schema = createSuccessEnvelopeSchema(dataSchema);
+  const parsed = schema.parse(payload);
+  process.env.RUNA_JSON_EMITTING = "true";
+  try {
+    writeJsonEnvelope(`${JSON.stringify(parsed)}
+`);
+  } finally {
+    process.env.RUNA_JSON_EMITTING = "false";
+  }
+  markJsonEmitted();
+}
+
+export { emitJsonSuccess };