@fulmenhq/tsfulmen 0.3.2 → 0.4.0

package/dist/chunk-RSLFR4TO.js

@@ -0,0 +1,631 @@
+// src/crucible/foundry/exitCodes.ts
+var exitCodes = {
+  // Standard Exit Codes (0-1)
+  // POSIX standard success and generic failure codes
+  EXIT_SUCCESS: 0,
+  EXIT_FAILURE: 1,
+  // Networking & Port Management (10-19)
+  // Network-related failures (ports, connectivity, etc.)
+  EXIT_PORT_IN_USE: 10,
+  EXIT_PORT_RANGE_EXHAUSTED: 11,
+  EXIT_INSTANCE_ALREADY_RUNNING: 12,
+  EXIT_NETWORK_UNREACHABLE: 13,
+  EXIT_CONNECTION_REFUSED: 14,
+  EXIT_CONNECTION_TIMEOUT: 15,
+  // Configuration & Validation (20-29)
+  // Configuration errors, validation failures, version mismatches
+  EXIT_CONFIG_INVALID: 20,
+  EXIT_MISSING_DEPENDENCY: 21,
+  EXIT_SSOT_VERSION_MISMATCH: 22,
+  EXIT_CONFIG_FILE_NOT_FOUND: 23,
+  EXIT_ENVIRONMENT_INVALID: 24,
+  // Runtime Errors (30-39)
+  // Errors during normal operation (health checks, database, etc.)
+  EXIT_HEALTH_CHECK_FAILED: 30,
+  EXIT_DATABASE_UNAVAILABLE: 31,
+  EXIT_EXTERNAL_SERVICE_UNAVAILABLE: 32,
+  EXIT_RESOURCE_EXHAUSTED: 33,
+  EXIT_OPERATION_TIMEOUT: 34,
+  // Command-Line Usage Errors (40-49)
+  // Invalid arguments, missing required flags, usage errors
+  EXIT_INVALID_ARGUMENT: 40,
+  EXIT_MISSING_REQUIRED_ARGUMENT: 41,
+  EXIT_USAGE: 64,
+  // Permissions & File Access (50-59)
+  // Permission denied, file not found, access errors
+  EXIT_PERMISSION_DENIED: 50,
+  EXIT_FILE_NOT_FOUND: 51,
+  EXIT_DIRECTORY_NOT_FOUND: 52,
+  EXIT_FILE_READ_ERROR: 53,
+  EXIT_FILE_WRITE_ERROR: 54,
+  // Data & Processing Errors (60-69)
+  // Data validation, parsing, transformation failures
+  EXIT_DATA_INVALID: 60,
+  EXIT_PARSE_ERROR: 61,
+  EXIT_TRANSFORMATION_FAILED: 62,
+  EXIT_DATA_CORRUPT: 63,
+  // Security & Authentication (70-79)
+  // Authentication failures, authorization errors, security violations
+  EXIT_AUTHENTICATION_FAILED: 70,
+  EXIT_AUTHORIZATION_FAILED: 71,
+  EXIT_SECURITY_VIOLATION: 72,
+  EXIT_CERTIFICATE_INVALID: 73,
+  // Observability & Monitoring (80-89)
+  // Observability infrastructure failures. Use when observability is CRITICAL to operation (e.g., monitoring agents, telemetry exporters). For workhorses where observability is auxiliary: - Log warning and continue (don't exit) - Emit degraded health status - Only exit if explicitly configured (fail_on_observability_error: true)
+  EXIT_METRICS_UNAVAILABLE: 80,
+  EXIT_TRACING_FAILED: 81,
+  EXIT_LOGGING_FAILED: 82,
+  EXIT_ALERT_SYSTEM_FAILED: 83,
+  EXIT_STRUCTURED_LOGGING_FAILED: 84,
+  // Testing & Validation (91-99)
+  // Test execution outcomes and validation failures. NOTE: Test harnesses MUST use EXIT_SUCCESS (0) for successful test runs per ecosystem conventions (pytest, Go testing, Jest all use 0 for success). Codes in this category are for FAILURES and exceptional conditions only.
+  EXIT_TEST_FAILURE: 91,
+  EXIT_TEST_ERROR: 92,
+  EXIT_TEST_INTERRUPTED: 93,
+  EXIT_TEST_USAGE_ERROR: 94,
+  EXIT_TEST_NO_TESTS_COLLECTED: 95,
+  EXIT_COVERAGE_THRESHOLD_NOT_MET: 96,
+  // Shell & Process Control (124-127)
+  // Exit codes from shell conventions and process control utilities (timeout, exec)
+  EXIT_TIMEOUT: 124,
+  EXIT_TIMEOUT_INTERNAL: 125,
+  EXIT_CANNOT_EXECUTE: 126,
+  EXIT_NOT_FOUND: 127,
+  // Signal-Induced Exits (128-165)
+  // Process terminated by Unix signals (128+N pattern per POSIX). Signal codes follow Linux numbering; macOS/FreeBSD differ for SIGUSR1/SIGUSR2. For full signal semantics, see config/library/foundry/signals.yaml. For signal handling patterns, see docs/standards/library/modules/signal-handling.md.
+  EXIT_SIGNAL_HUP: 129,
+  EXIT_SIGNAL_INT: 130,
+  EXIT_SIGNAL_QUIT: 131,
+  EXIT_SIGNAL_KILL: 137,
+  EXIT_SIGNAL_PIPE: 141,
+  EXIT_SIGNAL_ALRM: 142,
+  EXIT_SIGNAL_TERM: 143,
+  EXIT_SIGNAL_USR1: 138,
+  EXIT_SIGNAL_USR2: 140
+};
+var exitCodeMetadata = {
+  0: {
+    code: 0,
+    name: "EXIT_SUCCESS",
+    description: "Successful execution",
+    context: "Command completed without errors",
+    category: "standard"
+  },
+  1: {
+    code: 1,
+    name: "EXIT_FAILURE",
+    description: "Generic failure (unspecified error)",
+    context: "Use when no more specific exit code applies",
+    category: "standard"
+  },
+  10: {
+    code: 10,
+    name: "EXIT_PORT_IN_USE",
+    description: "Specified port is already in use",
+    context: "Server startup when port unavailable and fail_if_unavailable strategy",
+    category: "networking"
+  },
+  11: {
+    code: 11,
+    name: "EXIT_PORT_RANGE_EXHAUSTED",
+    description: "No available ports in configured range",
+    context: "Server startup when all ports in environment range occupied",
+    category: "networking"
+  },
+  12: {
+    code: 12,
+    name: "EXIT_INSTANCE_ALREADY_RUNNING",
+    description: "Another instance already running on target port",
+    context: "Server startup when PID registry shows active process on port",
+    category: "networking"
+  },
+  13: {
+    code: 13,
+    name: "EXIT_NETWORK_UNREACHABLE",
+    description: "Network destination unreachable",
+    context: "Client connections, health checks, external service validation",
+    category: "networking"
+  },
+  14: {
+    code: 14,
+    name: "EXIT_CONNECTION_REFUSED",
+    description: "Connection refused by remote host",
+    context: "Database connections, API endpoints, upstream services",
+    category: "networking"
+  },
+  15: {
+    code: 15,
+    name: "EXIT_CONNECTION_TIMEOUT",
+    description: "Connection attempt timed out",
+    context: "Slow networks, unresponsive services, firewall blocks",
+    category: "networking"
+  },
+  20: {
+    code: 20,
+    name: "EXIT_CONFIG_INVALID",
+    description: "Configuration file failed validation",
+    context: "Startup validation, schema mismatches, invalid YAML/JSON",
+    category: "configuration",
+    retryHint: "no_retry"
+  },
+  21: {
+    code: 21,
+    name: "EXIT_MISSING_DEPENDENCY",
+    description: "Required dependency not found",
+    context: "Missing binaries, libraries, or runtime requirements",
+    category: "configuration",
+    retryHint: "investigate"
+  },
+  22: {
+    code: 22,
+    name: "EXIT_SSOT_VERSION_MISMATCH",
+    description: "SSOT (Crucible) version incompatible",
+    context: "Helper library detects unsupported Crucible version",
+    category: "configuration",
+    retryHint: "no_retry"
+  },
+  23: {
+    code: 23,
+    name: "EXIT_CONFIG_FILE_NOT_FOUND",
+    description: "Required configuration file not found",
+    context: "Explicitly specified config path doesn't exist",
+    category: "configuration"
+  },
+  24: {
+    code: 24,
+    name: "EXIT_ENVIRONMENT_INVALID",
+    description: "Invalid or unsupported environment specification",
+    context: "Unknown environment name, missing environment config",
+    category: "configuration"
+  },
+  30: {
+    code: 30,
+    name: "EXIT_HEALTH_CHECK_FAILED",
+    description: "Health check endpoint returned non-healthy status",
+    context: "Startup health validation, readiness probes",
+    category: "runtime",
+    retryHint: "retry"
+  },
+  31: {
+    code: 31,
+    name: "EXIT_DATABASE_UNAVAILABLE",
+    description: "Database connection failed or unavailable",
+    context: "Startup connection checks, critical query failures",
+    category: "runtime",
+    retryHint: "retry"
+  },
+  32: {
+    code: 32,
+    name: "EXIT_EXTERNAL_SERVICE_UNAVAILABLE",
+    description: "Required external service unavailable",
+    context: "API dependencies, message queues, cache servers",
+    category: "runtime"
+  },
+  33: {
+    code: 33,
+    name: "EXIT_RESOURCE_EXHAUSTED",
+    description: "System resources exhausted (memory, disk, file descriptors)",
+    context: "Out-of-memory, disk full, too many open files",
+    category: "runtime",
+    retryHint: "investigate"
+  },
+  34: {
+    code: 34,
+    name: "EXIT_OPERATION_TIMEOUT",
+    description: "Operation exceeded timeout threshold",
+    context: "Long-running tasks, async operations, batch processing",
+    category: "runtime",
+    retryHint: "retry"
+  },
+  40: {
+    code: 40,
+    name: "EXIT_INVALID_ARGUMENT",
+    description: "Invalid command-line argument or flag value",
+    context: "Type errors, out-of-range values, malformed input",
+    category: "usage"
+  },
+  41: {
+    code: 41,
+    name: "EXIT_MISSING_REQUIRED_ARGUMENT",
+    description: "Required command-line argument not provided",
+    context: "Missing --config, --port, or other required flags",
+    category: "usage"
+  },
+  64: {
+    code: 64,
+    name: "EXIT_USAGE",
+    description: "Command-line usage error",
+    context: "BSD sysexits.h EX_USAGE - wrong number of arguments, bad syntax",
+    category: "usage",
+    bsdEquivalent: "EX_USAGE"
+  },
+  50: {
+    code: 50,
+    name: "EXIT_PERMISSION_DENIED",
+    description: "Insufficient permissions for operation",
+    context: "File access, port binding (<1024), privileged operations",
+    category: "permissions"
+  },
+  51: {
+    code: 51,
+    name: "EXIT_FILE_NOT_FOUND",
+    description: "Required file not found",
+    context: "Assets, templates, data files (not config - use 23)",
+    category: "permissions"
+  },
+  52: {
+    code: 52,
+    name: "EXIT_DIRECTORY_NOT_FOUND",
+    description: "Required directory not found",
+    context: "State directories, log paths, data directories",
+    category: "permissions"
+  },
+  53: {
+    code: 53,
+    name: "EXIT_FILE_READ_ERROR",
+    description: "Error reading file",
+    context: "Corrupt files, I/O errors, encoding issues",
+    category: "permissions"
+  },
+  54: {
+    code: 54,
+    name: "EXIT_FILE_WRITE_ERROR",
+    description: "Error writing file",
+    context: "Disk full, read-only filesystem, permission errors",
+    category: "permissions"
+  },
+  60: {
+    code: 60,
+    name: "EXIT_DATA_INVALID",
+    description: "Input data failed validation",
+    context: "Schema validation, business rule violations",
+    category: "data"
+  },
+  61: {
+    code: 61,
+    name: "EXIT_PARSE_ERROR",
+    description: "Error parsing input data",
+    context: "Malformed JSON/YAML/XML, syntax errors",
+    category: "data"
+  },
+  62: {
+    code: 62,
+    name: "EXIT_TRANSFORMATION_FAILED",
+    description: "Data transformation or conversion failed",
+    context: "Type conversions, format transformations, encoding changes",
+    category: "data"
+  },
+  63: {
+    code: 63,
+    name: "EXIT_DATA_CORRUPT",
+    description: "Data corruption detected",
+    context: "Checksum failures, integrity violations",
+    category: "data"
+  },
+  70: {
+    code: 70,
+    name: "EXIT_AUTHENTICATION_FAILED",
+    description: "Authentication failed",
+    context: "Invalid credentials, expired tokens, auth service unavailable",
+    category: "security"
+  },
+  71: {
+    code: 71,
+    name: "EXIT_AUTHORIZATION_FAILED",
+    description: "Authorization failed (authenticated but insufficient permissions)",
+    context: "RBAC failures, scope violations, resource access denied",
+    category: "security"
+  },
+  72: {
+    code: 72,
+    name: "EXIT_SECURITY_VIOLATION",
+    description: "Security policy violation detected",
+    context: "Suspicious activity, rate limit exceeded, IP blocklist",
+    category: "security"
+  },
+  73: {
+    code: 73,
+    name: "EXIT_CERTIFICATE_INVALID",
+    description: "TLS/SSL certificate validation failed",
+    context: "Expired certs, untrusted CAs, hostname mismatches",
+    category: "security",
+    bsdEquivalent: "EX_PROTOCOL"
+  },
+  80: {
+    code: 80,
+    name: "EXIT_METRICS_UNAVAILABLE",
+    description: "Metrics endpoint or collection system unavailable",
+    context: "Use for observability-focused tools (Prometheus exporters, StatsD agents).\nWorkhorses SHOULD log warning and continue unless configured to fail-fast.\n",
+    category: "observability"
+  },
+  81: {
+    code: 81,
+    name: "EXIT_TRACING_FAILED",
+    description: "Distributed tracing system unavailable",
+    context: "OTLP exporter failed, Jaeger collector unreachable",
+    category: "observability"
+  },
+  82: {
+    code: 82,
+    name: "EXIT_LOGGING_FAILED",
+    description: "Logging system unavailable or misconfigured",
+    context: "Log aggregator unreachable, log file unwritable",
+    category: "observability"
+  },
+  83: {
+    code: 83,
+    name: "EXIT_ALERT_SYSTEM_FAILED",
+    description: "Alerting system unavailable",
+    context: "PagerDuty API failed, Slack webhook unreachable",
+    category: "observability"
+  },
+  84: {
+    code: 84,
+    name: "EXIT_STRUCTURED_LOGGING_FAILED",
+    description: "Structured logging system unavailable",
+    context: "JSON log aggregator unreachable, log schema validation failed",
+    category: "observability"
+  },
+  91: {
+    code: 91,
+    name: "EXIT_TEST_FAILURE",
+    description: "One or more tests failed",
+    context: "Test assertions failed, expected behavior not met.\nMaps to pytest exit code 1, Go test failure, Jest failure.\n",
+    category: "testing"
+  },
+  92: {
+    code: 92,
+    name: "EXIT_TEST_ERROR",
+    description: "Test execution error (not test failure)",
+    context: "Test setup failed, fixture unavailable, test harness error.\nMaps to pytest exit code 3 (internal error).\n",
+    category: "testing"
+  },
+  93: {
+    code: 93,
+    name: "EXIT_TEST_INTERRUPTED",
+    description: "Test run interrupted by user or system",
+    context: "Ctrl+C during tests, system signal, user cancellation.\nMaps to pytest exit code 2.\n",
+    category: "testing"
+  },
+  94: {
+    code: 94,
+    name: "EXIT_TEST_USAGE_ERROR",
+    description: "Test command usage error",
+    context: "Invalid test arguments, bad configuration.\nMaps to pytest exit code 4.\n",
+    category: "testing"
+  },
+  95: {
+    code: 95,
+    name: "EXIT_TEST_NO_TESTS_COLLECTED",
+    description: "No tests found or all tests skipped",
+    context: "Empty test suite, all tests deselected or skipped.\nMaps to pytest exit code 5.\n",
+    category: "testing"
+  },
+  96: {
+    code: 96,
+    name: "EXIT_COVERAGE_THRESHOLD_NOT_MET",
+    description: "Test coverage below required threshold",
+    context: "Code coverage validation, quality gate failure",
+    category: "testing"
+  },
+  124: {
+    code: 124,
+    name: "EXIT_TIMEOUT",
+    description: "Command timed out before completion",
+    context: "GNU timeout or similar utility terminated command after deadline",
+    category: "shell"
+  },
+  125: {
+    code: 125,
+    name: "EXIT_TIMEOUT_INTERNAL",
+    description: "Timeout utility itself failed",
+    context: "Error in timeout tool before or during command execution (not command failure)",
+    category: "shell"
+  },
+  126: {
+    code: 126,
+    name: "EXIT_CANNOT_EXECUTE",
+    description: "Command found but could not be executed",
+    context: "Permission denied, not executable, exec format error",
+    category: "shell",
+    bsdEquivalent: "EX_NOPERM (partial)"
+  },
+  127: {
+    code: 127,
+    name: "EXIT_NOT_FOUND",
+    description: "Command not found",
+    context: "Executable not found in PATH or specified path does not exist",
+    category: "shell",
+    bsdEquivalent: "EX_UNAVAILABLE (partial)"
+  },
+  129: {
+    code: 129,
+    name: "EXIT_SIGNAL_HUP",
+    description: "Hangup signal (SIGHUP) - config reload via restart",
+    context: "Config reload via restart-based pattern (mandatory schema validation).\nProcess exits with 129, supervisor restarts with new config.\nSee signals.yaml for reload behavior definition.",
+    category: "signals",
+    bsdEquivalent: "128 + 1"
+  },
+  130: {
+    code: 130,
+    name: "EXIT_SIGNAL_INT",
+    description: "Interrupt signal (SIGINT) - user interrupt with Ctrl+C double-tap",
+    context: "Ctrl+C pressed. First tap initiates graceful shutdown, second within 2s forces immediate exit.\nSame exit code (130) for both graceful and force modes.\nSee signals.yaml for double-tap behavior definition.",
+    category: "signals",
+    bsdEquivalent: "128 + 2"
+  },
+  131: {
+    code: 131,
+    name: "EXIT_SIGNAL_QUIT",
+    description: "Quit signal (SIGQUIT) - immediate exit",
+    context: "Ctrl+\\ on Unix, Ctrl+Break on Windows. Immediate termination without cleanup.\nUse for emergency shutdown or debugging (core dumps).",
+    category: "signals",
+    bsdEquivalent: "128 + 3"
+  },
+  137: {
+    code: 137,
+    name: "EXIT_SIGNAL_KILL",
+    description: "Kill signal (SIGKILL)",
+    context: "Forceful termination, non-graceful shutdown (not catchable)",
+    category: "signals",
+    bsdEquivalent: "128 + 9",
+    pythonNote: "Cannot be caught in Python (OS-level)"
+  },
+  141: {
+    code: 141,
+    name: "EXIT_SIGNAL_PIPE",
+    description: "Broken pipe (SIGPIPE) - observe only",
+    context: "Writing to closed pipe/socket. Fulmen default is observe_only (log + graceful exit).\nApplications may override to ignore for network services.\nSee signals.yaml for SIGPIPE handling guidance.",
+    category: "signals",
+    bsdEquivalent: "128 + 13",
+    pythonNote: "Raised as BrokenPipeError exception"
+  },
+  142: {
+    code: 142,
+    name: "EXIT_SIGNAL_ALRM",
+    description: "Alarm signal (SIGALRM) - watchdog timeout",
+    context: "Watchdog timer expired. Treat as timeout-induced exit.\nWatchdog pattern out of scope for v1.0.0 module implementations.",
+    category: "signals",
+    bsdEquivalent: "128 + 14",
+    pythonNote: "Supported by signal module, rarely used in practice"
+  },
+  143: {
+    code: 143,
+    name: "EXIT_SIGNAL_TERM",
+    description: "Termination signal (SIGTERM) - graceful shutdown",
+    context: "Graceful shutdown requested by container orchestrator or process supervisor.\nStandard 30-second timeout for cleanup. Applications run cleanup handlers before exit.\nSee signals.yaml for graceful shutdown behavior definition.",
+    category: "signals",
+    bsdEquivalent: "128 + 15",
+    pythonNote: "Default signal for graceful shutdown"
+  },
+  138: {
+    code: 138,
+    name: "EXIT_SIGNAL_USR1",
+    description: "User-defined signal 1 (SIGUSR1) - custom handler",
+    context: "Application-specific signal (e.g., reopen logs, dump stats, trigger profiling).\nApplications register custom handlers. Exit code 138 on Linux (128+10).\nPlatform differences: macOS/FreeBSD use signal 30 (exit 158), not 10.",
+    category: "signals"
+  },
+  140: {
+    code: 140,
+    name: "EXIT_SIGNAL_USR2",
+    description: "User-defined signal 2 (SIGUSR2) - custom handler",
+    context: "Application-specific signal (e.g., toggle debug mode, rotate credentials).\nApplications register custom handlers. Exit code 140 on Linux (128+12).\nPlatform differences: macOS/FreeBSD use signal 31 (exit 159), not 12.",
+    category: "signals"
+  }
+};
+function getExitCodeInfo(code) {
+  return exitCodeMetadata[code];
+}
+var EXIT_CODES_VERSION = "v1.0.0";
+
+// src/foundry/exit-codes/capabilities.ts
+function supportsSignalExitCodes() {
+  return process.platform !== "win32";
+}
+function getPlatform() {
+  return process.platform;
+}
+function isWindows() {
+  return process.platform === "win32";
+}
+function isPOSIX() {
+  return !isWindows();
+}
+function getPlatformCapabilities() {
+  return {
+    platform: getPlatform(),
+    supportsSignalExitCodes: supportsSignalExitCodes(),
+    isPOSIX: isPOSIX(),
+    isWindows: isWindows()
+  };
+}
+
+// src/foundry/exit-codes/simplified.ts
+var SimplifiedMode = /* @__PURE__ */ ((SimplifiedMode2) => {
+  SimplifiedMode2["BASIC"] = "basic";
+  SimplifiedMode2["SEVERITY"] = "severity";
+  return SimplifiedMode2;
+})(SimplifiedMode || {});
+function mapExitCodeToSimplified(code, mode = "basic" /* BASIC */) {
+  if (code === 0) {
+    return 0;
+  }
+  if (mode === "basic" /* BASIC */) {
+    return 1;
+  }
+  const info = exitCodeMetadata[code];
+  if (!info) {
+    return 3;
+  }
+  if (info.retryHint === "retry") {
+    return 1;
+  }
+  if (info.retryHint === "no_retry") {
+    return 2;
+  }
+  if (info.retryHint === "investigate") {
+    return 3;
+  }
+  switch (info.category) {
+    case "configuration":
+    case "usage":
+      return 2;
+    case "networking":
+    case "runtime":
+      return 1;
+    case "permissions":
+    case "data":
+      return 2;
+    case "security":
+      return 3;
+    case "observability":
+      return 1;
+    case "testing":
+      return 1;
+    case "signals":
+      return 3;
+    default:
+      return 1;
+  }
+}
+function getSimplifiedCodes(mode) {
+  switch (mode) {
+    case "basic" /* BASIC */:
+      return [0, 1];
+    case "severity" /* SEVERITY */:
+      return [0, 1, 2, 3];
+    default:
+      return [0, 1];
+  }
+}
+function getSimplifiedCodeDescription(code, mode) {
+  if (mode === "basic" /* BASIC */) {
+    switch (code) {
+      case 0:
+        return "Success";
+      case 1:
+        return "Failure";
+      default:
+        return "Unknown";
+    }
+  }
+  if (mode === "severity" /* SEVERITY */) {
+    switch (code) {
+      case 0:
+        return "Success";
+      case 1:
+        return "Recoverable error (retry possible)";
+      case 2:
+        return "Configuration error (fix config, don't retry)";
+      case 3:
+        return "Fatal error (investigate required)";
+      default:
+        return "Unknown";
+    }
+  }
+  return "Unknown mode";
+}
+
+export { EXIT_CODES_VERSION, SimplifiedMode, exitCodeMetadata, exitCodes, getExitCodeInfo, getPlatform, getPlatformCapabilities, getSimplifiedCodeDescription, getSimplifiedCodes, isPOSIX, isWindows, mapExitCodeToSimplified, supportsSignalExitCodes };
+//# sourceMappingURL=chunk-RSLFR4TO.js.map
+//# sourceMappingURL=chunk-RSLFR4TO.js.map