@starpak/error 0.0.0-stage → 0.1.4

package/lib/format.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Spak Error - renderers
+ *
+ * One `ErrorInfo` → four surfaces: terminal text, JSON (CI/logs), HTML
+ * (Spak OS panel) and Markdown (docs/issues).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = format;
+exports.exitCodeFor = exitCodeFor;
+const ANSI = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    red: '\u001b[31m',
+    yellow: '\u001b[33m',
+    cyan: '\u001b[36m',
+    magenta: '\u001b[35m',
+};
+const SEVERITY_COLOR = {
+    info: ANSI.cyan,
+    warning: ANSI.yellow,
+    error: ANSI.red,
+    fatal: ANSI.magenta,
+};
+const SEVERITY_CSS = {
+    info: '#2f81f7',
+    warning: '#d29922',
+    error: '#f85149',
+    fatal: '#a371f7',
+};
+function paint(text, color, enabled) {
+    return enabled ? `${color}${text}${ANSI.reset}` : text;
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function location(info, file) {
+    if (info.where)
+        return file ? `${file}:${info.where}` : info.where;
+    if (file)
+        return file;
+    return undefined;
+}
+function format(info, kind = 'text', options = {}) {
+    switch (kind) {
+        case 'json':
+            return formatJson(info);
+        case 'html':
+            return formatHtml(info);
+        case 'markdown':
+            return formatMarkdown(info);
+        default:
+            return formatText(info, options);
+    }
+}
+function formatText(info, options) {
+    const color = options.color ?? Boolean(process.stdout.isTTY);
+    const tone = SEVERITY_COLOR[info.severity] ?? ANSI.red;
+    const label = paint(info.severity, tone, color);
+    const lines = [];
+    lines.push(`${label}${paint(`[${info.code}]`, ANSI.dim, color)} ${paint(info.title, ANSI.bold, color)}`);
+    if (info.message && info.message !== info.title) {
+        lines.push(`  ${info.message}`);
+    }
+    const where = location(info, options.file);
+    if (where)
+        lines.push(`  ${paint('-->', ANSI.cyan, color)} ${where}`);
+    lines.push(`  ${paint('为什么', ANSI.dim, color)}：${info.why}`);
+    if (info.fix.length) {
+        lines.push(`  ${paint('怎么改', ANSI.dim, color)}：`);
+        info.fix.forEach((step, index) => lines.push(`   ${index + 1}. ${step}`));
+    }
+    if (info.docs)
+        lines.push(`  ${paint('文档', ANSI.dim, color)}：${info.docs}`);
+    if (info.cause?.stack) {
+        const first = info.cause.stack.split('\n').slice(0, 3).join('\n    ');
+        lines.push(`  ${paint('原始错误', ANSI.dim, color)}：\n    ${first}`);
+    }
+    return lines.join('\n');
+}
+function formatJson(info) {
+    return JSON.stringify({
+        code: info.code,
+        title: info.title,
+        severity: info.severity,
+        category: info.category,
+        message: info.message,
+        where: info.where,
+        why: info.why,
+        fix: info.fix,
+        docs: info.docs,
+        ui: info.ui,
+        context: info.context,
+        cause: info.cause
+            ? { name: info.cause.name, message: info.cause.message, stack: info.cause.stack }
+            : undefined,
+    }, null, 2);
+}
+function formatHtml(info) {
+    const color = info.ui?.color ?? SEVERITY_CSS[info.severity] ?? SEVERITY_CSS.error;
+    const actions = (info.ui?.actions ?? []).map(action => `      <button type="button" class="spak-error-action">${escapeHtml(action)}</button>`).join('\n');
+    const steps = info.fix.map(step => `      <li>${escapeHtml(step)}</li>`).join('\n');
+    return `<section class="spak-error" data-code="${escapeHtml(info.code)}" data-severity="${escapeHtml(info.severity)}" style="--spak-error-color:${color}">
+  <header>
+    <span class="spak-error-icon">${escapeHtml(info.ui?.icon ?? '!')}</span>
+    <h2>${escapeHtml(info.title)}</h2>
+    <code>${escapeHtml(info.code)}</code>
+  </header>
+  <p class="spak-error-message">${escapeHtml(info.message)}</p>
+  ${info.where ? `<p class="spak-error-where">${escapeHtml(info.where)}</p>` : ''}
+  <p class="spak-error-why"><strong>为什么：</strong>${escapeHtml(info.why)}</p>
+  <div class="spak-error-fix">
+    <strong>怎么改：</strong>
+    <ol>
+${steps}
+    </ol>
+  </div>
+${actions ? `  <footer>\n${actions}\n  </footer>` : ''}
+</section>`;
+}
+function formatMarkdown(info) {
+    const lines = [];
+    lines.push(`### ${info.code} · ${info.title}`);
+    lines.push('');
+    lines.push(`**严重程度**：${info.severity}　**分类**：${info.category}`);
+    if (info.where)
+        lines.push(`**位置**：\`${info.where}\``);
+    lines.push('');
+    if (info.message && info.message !== info.title) {
+        lines.push(info.message);
+        lines.push('');
+    }
+    lines.push(`**为什么**：${info.why}`);
+    lines.push('');
+    lines.push('**怎么改**：');
+    info.fix.forEach((step, index) => lines.push(`${index + 1}. ${step}`));
+    if (info.docs) {
+        lines.push('');
+        lines.push(`**文档**：${info.docs}`);
+    }
+    if (info.cause) {
+        lines.push('');
+        lines.push('<details><summary>原始错误</summary>');
+        lines.push('');
+        lines.push('```');
+        lines.push(`${info.cause.name}: ${info.cause.message}`);
+        if (info.cause.stack)
+            lines.push(info.cause.stack);
+        lines.push('```');
+        lines.push('');
+        lines.push('</details>');
+    }
+    return lines.join('\n');
+}
+/** Exit code convention: fatal/error → 1, warning/info → 0. */
+function exitCodeFor(info) {
+    return info.severity === 'fatal' || info.severity === 'error' ? 1 : 0;
+}
+//# sourceMappingURL=format.js.map

package/lib/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Spak Error - Public API
+ *
+ * Every error has a stable code, an actionable explanation and four renderers.
+ */
+export { CODES, codeNumber, isKnownCode } from './codes';
+export type { ErrorCode } from './codes';
+export { DEFINITIONS, allDefinitions, getDefinition, isFatal } from './definitions';
+export type { Category, ErrorDefinition, ErrorUI, Severity } from './definitions';
+export { SpakError, describe, fromDiagnostic, isSpakError } from './error';
+export type { ErrorContext, ErrorInfo, SpakErrorOptions } from './error';
+export { ERRNO_MAP, fromNative } from './native';
+export type { NativeOptions } from './native';
+export { exitCodeFor, format } from './format';
+export type { FormatKind, FormatOptions } from './format';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACnF,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAEjF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1E,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAExE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAChD,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA"}

package/lib/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Spak Error - Public API
+ *
+ * Every error has a stable code, an actionable explanation and four renderers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = exports.exitCodeFor = exports.fromNative = exports.ERRNO_MAP = exports.isSpakError = exports.fromDiagnostic = exports.describe = exports.SpakError = exports.isFatal = exports.getDefinition = exports.allDefinitions = exports.DEFINITIONS = exports.isKnownCode = exports.codeNumber = exports.CODES = void 0;
+var codes_1 = require("./codes");
+Object.defineProperty(exports, "CODES", { enumerable: true, get: function () { return codes_1.CODES; } });
+Object.defineProperty(exports, "codeNumber", { enumerable: true, get: function () { return codes_1.codeNumber; } });
+Object.defineProperty(exports, "isKnownCode", { enumerable: true, get: function () { return codes_1.isKnownCode; } });
+var definitions_1 = require("./definitions");
+Object.defineProperty(exports, "DEFINITIONS", { enumerable: true, get: function () { return definitions_1.DEFINITIONS; } });
+Object.defineProperty(exports, "allDefinitions", { enumerable: true, get: function () { return definitions_1.allDefinitions; } });
+Object.defineProperty(exports, "getDefinition", { enumerable: true, get: function () { return definitions_1.getDefinition; } });
+Object.defineProperty(exports, "isFatal", { enumerable: true, get: function () { return definitions_1.isFatal; } });
+var error_1 = require("./error");
+Object.defineProperty(exports, "SpakError", { enumerable: true, get: function () { return error_1.SpakError; } });
+Object.defineProperty(exports, "describe", { enumerable: true, get: function () { return error_1.describe; } });
+Object.defineProperty(exports, "fromDiagnostic", { enumerable: true, get: function () { return error_1.fromDiagnostic; } });
+Object.defineProperty(exports, "isSpakError", { enumerable: true, get: function () { return error_1.isSpakError; } });
+var native_1 = require("./native");
+Object.defineProperty(exports, "ERRNO_MAP", { enumerable: true, get: function () { return native_1.ERRNO_MAP; } });
+Object.defineProperty(exports, "fromNative", { enumerable: true, get: function () { return native_1.fromNative; } });
+var format_1 = require("./format");
+Object.defineProperty(exports, "exitCodeFor", { enumerable: true, get: function () { return format_1.exitCodeFor; } });
+Object.defineProperty(exports, "format", { enumerable: true, get: function () { return format_1.format; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,iCAAwD;AAA/C,8FAAA,KAAK,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,oGAAA,WAAW,OAAA;AAGvC,6CAAmF;AAA1E,0GAAA,WAAW,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,4GAAA,aAAa,OAAA;AAAE,sGAAA,OAAO,OAAA;AAG5D,iCAA0E;AAAjE,kGAAA,SAAS,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,uGAAA,cAAc,OAAA;AAAE,oGAAA,WAAW,OAAA;AAGzD,mCAAgD;AAAvC,mGAAA,SAAS,OAAA;AAAE,oGAAA,UAAU,OAAA;AAG9B,mCAA8C;AAArC,qGAAA,WAAW,OAAA;AAAE,gGAAA,MAAM,OAAA"}

package/lib/native.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Spak Error - native error mapping
+ *
+ * Turns `errno` codes and well-known crash messages into Spak errors while
+ * keeping the original error as `cause`.
+ */
+import { SpakError } from './error';
+/** POSIX/Node errno → Spak code. */
+export declare const ERRNO_MAP: Record<string, string>;
+export interface NativeOptions {
+    where?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Normalise any thrown value into a `SpakError`.
+ * Unknown shapes still produce an error (SPAK-9999) with the original cause.
+ */
+export declare function fromNative(error: unknown, options?: NativeOptions): SpakError;
+export { ERRNO_MAP as ERRNO_TO_SPAK };
+//# sourceMappingURL=native.d.ts.map

package/lib/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAe,MAAM,SAAS,CAAA;AAEhD,oCAAoC;AACpC,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoC5C,CAAA;AAgBD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,SAAS,CAiCjF;AAED,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,CAAA"}

package/lib/native.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Spak Error - native error mapping
+ *
+ * Turns `errno` codes and well-known crash messages into Spak errors while
+ * keeping the original error as `cause`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERRNO_TO_SPAK = exports.ERRNO_MAP = void 0;
+exports.fromNative = fromNative;
+const codes_1 = require("./codes");
+const error_1 = require("./error");
+/** POSIX/Node errno → Spak code. */
+exports.ERRNO_MAP = {
+    ENOENT: codes_1.CODES.FS_NOT_FOUND,
+    ENOTDIR: codes_1.CODES.FS_NOT_FOUND,
+    EACCES: codes_1.CODES.FS_DENIED_BY_OS,
+    EPERM: codes_1.CODES.FS_OPERATION_NOT_PERMITTED,
+    ENOSPC: codes_1.CODES.FS_NO_SPACE,
+    EMFILE: codes_1.CODES.FS_TOO_MANY_OPEN_FILES,
+    ENFILE: codes_1.CODES.FS_TOO_MANY_OPEN_FILES,
+    EISDIR: codes_1.CODES.FS_IS_DIRECTORY,
+    EROFS: codes_1.CODES.FS_DENIED_BY_OS,
+    EBADF: codes_1.CODES.HANDLE_REVOKED,
+    EADDRINUSE: codes_1.CODES.PORT_IN_USE,
+    EADDRNOTAVAIL: codes_1.CODES.LISTEN_FAILED,
+    EACCES_LISTEN: codes_1.CODES.LISTEN_FAILED,
+    ECONNREFUSED: codes_1.CODES.NET_CONNECTION_REFUSED,
+    ECONNRESET: codes_1.CODES.NET_CONNECTION_RESET,
+    ECONNABORTED: codes_1.CODES.NET_CONNECTION_RESET,
+    EPIPE: codes_1.CODES.NET_CONNECTION_RESET,
+    ETIMEDOUT: codes_1.CODES.NET_TIMEOUT,
+    ESOCKETTIMEDOUT: codes_1.CODES.NET_TIMEOUT,
+    ENOTFOUND: codes_1.CODES.NET_DNS,
+    EAI_AGAIN: codes_1.CODES.NET_DNS,
+    ERR_TLS_CERT_ALTNAME_INVALID: codes_1.CODES.NET_TLS,
+    ERR_SSL_WRONG_VERSION_NUMBER: codes_1.CODES.NET_TLS,
+    DEPTH_ZERO_SELF_SIGNED_CERT: codes_1.CODES.NET_TLS,
+    UNABLE_TO_VERIFY_LEAF_SIGNATURE: codes_1.CODES.NET_TLS,
+    SELF_SIGNED_CERT_IN_CHAIN: codes_1.CODES.NET_TLS,
+    MODULE_NOT_FOUND: codes_1.CODES.MODULE_NOT_FOUND,
+    ERR_MODULE_NOT_FOUND: codes_1.CODES.MODULE_NOT_FOUND,
+    ERR_REQUIRE_ESM: codes_1.CODES.MODULE_NOT_FOUND,
+    ERR_PACKAGE_PATH_NOT_EXPORTED: codes_1.CODES.MODULE_NOT_FOUND,
+    ERR_INVALID_ARG_TYPE: codes_1.CODES.BUILD_FAILED,
+};
+exports.ERRNO_TO_SPAK = exports.ERRNO_MAP;
+/** Message patterns for failures that have no errno (crashes, engine errors). */
+const MESSAGE_MAP = [
+    { pattern: /JavaScript heap out of memory/i, code: codes_1.CODES.OUT_OF_MEMORY },
+    { pattern: /Maximum call stack size exceeded/i, code: codes_1.CODES.STACK_OVERFLOW },
+    { pattern: /Segmentation fault|core dumped|double free|invalid pointer|bus error/i, code: codes_1.CODES.NATIVE_CRASH },
+    { pattern: /Unexpected token .* in JSON|is not valid JSON|JSON at position/i, code: codes_1.CODES.PAK_MANIFEST_INVALID },
+    { pattern: /\.l2s\.|FUSE|rename .*ENOENT/i, code: codes_1.CODES.FS_RENAME_UNSUPPORTED },
+    { pattern: /socket hang up/i, code: codes_1.CODES.NET_CONNECTION_RESET },
+    { pattern: /self-signed certificate|certificate has expired|unable to verify/i, code: codes_1.CODES.NET_TLS },
+    { pattern: /basic auth|proxy authentication/i, code: codes_1.CODES.NET_PROXY_AUTH },
+    { pattern: /Cannot find module/i, code: codes_1.CODES.MODULE_NOT_FOUND },
+    { pattern: /EACCES.*listen|permission denied.*:?\d{2,5}/i, code: codes_1.CODES.LISTEN_FAILED },
+];
+/**
+ * Normalise any thrown value into a `SpakError`.
+ * Unknown shapes still produce an error (SPAK-9999) with the original cause.
+ */
+function fromNative(error, options = {}) {
+    if ((0, error_1.isSpakError)(error))
+        return error;
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const errno = typeof error?.code === 'string'
+        ? String(error.code)
+        : undefined;
+    const message = cause.message ?? '';
+    const context = { ...options.context };
+    if (errno)
+        context.errno = errno;
+    if (errno) {
+        const direct = exports.ERRNO_MAP[errno];
+        if (direct) {
+            // Listen failures share EACCES with file access; the syscall tells them apart.
+            const syscall = String(error?.syscall ?? '');
+            if (errno === 'EACCES' && syscall === 'listen') {
+                return new error_1.SpakError(codes_1.CODES.LISTEN_FAILED, { cause, message, where: options.where, context });
+            }
+            if (errno === 'ENOENT' && /\.l2s\.|tmp_obj_|\.git\/objects/.test(message)) {
+                return new error_1.SpakError(codes_1.CODES.FS_RENAME_UNSUPPORTED, { cause, message, where: options.where, context });
+            }
+            return new error_1.SpakError(direct, { cause, message, where: options.where, context });
+        }
+    }
+    for (const entry of MESSAGE_MAP) {
+        if (entry.pattern.test(message)) {
+            return new error_1.SpakError(entry.code, { cause, message, where: options.where, context });
+        }
+    }
+    return new error_1.SpakError(codes_1.CODES.UNKNOWN, { cause, message, where: options.where, context });
+}
+//# sourceMappingURL=native.js.map

package/lib/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@starpak/error",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Spak Error - error codes, guidance and terminal/JSON/HTML/Markdown renderers",
+  "version": "0.1.4",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "author": "Spak Team",
+  "license": "MIT",
+  "dependencies": {}
 }

package/src/codes.ts

@@ -0,0 +1,115 @@
+/**
+ * Spak Error - stable error codes
+ *
+ * Naming: `SPAK-<domain><serial>` — 1xxx language, 2xxx build, 3xxx mod/app,
+ * 4xxx runtime, 5xxx permission, 6xxx filesystem, 7xxx network, 8xxx env,
+ * 9xxx fatal. Codes never get reused; retired codes stay reserved.
+ */
+
+export const CODES = {
+  // ---- 1xxx language ------------------------------------------------------
+  SYNTAX: 'SPAK-1001',
+  UNEXPECTED_TOKEN: 'SPAK-1002',
+  UNTERMINATED_STRING: 'SPAK-1003',
+  TYPE_MISMATCH: 'SPAK-1004',
+  POSSIBLY_NIL: 'SPAK-1005',
+  UNKNOWN_TYPE: 'SPAK-1006',
+  ARGUMENT_MISMATCH: 'SPAK-1007',
+  RETURN_MISMATCH: 'SPAK-1008',
+  DUPLICATE_DECLARATION: 'SPAK-1009',
+  TYPE_ALIAS_CYCLE: 'SPAK-1010',
+  MISSING_FIELD: 'SPAK-1011',
+  ZERO_BASED_INDEX: 'SPAK-1012',
+
+  // ---- 2xxx build ---------------------------------------------------------
+  BUILD_FAILED: 'SPAK-2001',
+  ENTRY_NOT_FOUND: 'SPAK-2002',
+  UNKNOWN_TARGET: 'SPAK-2003',
+  PAK_MAGIC_INVALID: 'SPAK-2004',
+  PAK_VERSION_UNSUPPORTED: 'SPAK-2005',
+  PAK_MANIFEST_INVALID: 'SPAK-2006',
+  PAK_TRUNCATED: 'SPAK-2007',
+  INTEGRITY_MISMATCH: 'SPAK-2010',
+  OUTPUT_NOT_WRITABLE: 'SPAK-2008',
+  DISK_FULL: 'SPAK-2009',
+
+  // ---- 3xxx mods / apps ---------------------------------------------------
+  MANIFEST_INVALID: 'SPAK-3001',
+  DEPENDENCY_MISSING: 'SPAK-3002',
+  DEPENDENCY_CYCLE: 'SPAK-3003',
+  DUPLICATE_MOD_ID: 'SPAK-3004',
+  ENTRY_UNSUPPORTED: 'SPAK-3005',
+  SPK_COMPILE_FAILED: 'SPAK-3006',
+  VERSION_MISMATCH: 'SPAK-3007',
+  CONFIG_INVALID: 'SPAK-3008',
+  INSTALL_FAILED: 'SPAK-3009',
+  SIGNATURE_INVALID: 'SPAK-3010',
+
+  // ---- 4xxx runtime -------------------------------------------------------
+  UNCAUGHT_EXCEPTION: 'SPAK-4001',
+  UNHANDLED_REJECTION: 'SPAK-4002',
+  PORT_IN_USE: 'SPAK-4003',
+  LISTEN_FAILED: 'SPAK-4004',
+  ROUTE_DUPLICATE: 'SPAK-4005',
+  HANDLER_THREW: 'SPAK-4006',
+  BODY_TOO_LARGE: 'SPAK-4007',
+  UNKNOWN_COMMAND: 'SPAK-4008',
+  MISSING_ARGUMENT: 'SPAK-4009',
+  INVALID_OPTION: 'SPAK-4010',
+  SERVICE_STOP_FAILED: 'SPAK-4011',
+  INVALID_PATH: 'SPAK-4012',
+  AUTH_FAILED: 'SPAK-4013',
+
+  // ---- 5xxx permission ----------------------------------------------------
+  PERMISSION_UNDECLARED: 'SPAK-5001',
+  FS_DENIED: 'SPAK-5002',
+  NETWORK_DENIED: 'SPAK-5003',
+  CHILD_PROCESS_DENIED: 'SPAK-5004',
+  DANGEROUS_API: 'SPAK-5005',
+
+  // ---- 6xxx filesystem ----------------------------------------------------
+  FS_NOT_FOUND: 'SPAK-6001',
+  FS_DENIED_BY_OS: 'SPAK-6002',
+  FS_OPERATION_NOT_PERMITTED: 'SPAK-6003',
+  FS_NO_SPACE: 'SPAK-6004',
+  FS_TOO_MANY_OPEN_FILES: 'SPAK-6005',
+  FS_IS_DIRECTORY: 'SPAK-6006',
+  FS_RENAME_UNSUPPORTED: 'SPAK-6007',
+
+  // ---- 7xxx network -------------------------------------------------------
+  NET_CONNECTION_REFUSED: 'SPAK-7001',
+  NET_CONNECTION_RESET: 'SPAK-7002',
+  NET_TIMEOUT: 'SPAK-7003',
+  NET_DNS: 'SPAK-7004',
+  NET_TLS: 'SPAK-7005',
+  NET_PROXY_AUTH: 'SPAK-7006',
+  NET_HTTP_STATUS: 'SPAK-7007',
+
+  // ---- 8xxx environment ---------------------------------------------------
+  NODE_VERSION: 'SPAK-8001',
+  NATIVE_MODULE: 'SPAK-8002',
+  PLATFORM_UNSUPPORTED: 'SPAK-8003',
+  ENCODING: 'SPAK-8004',
+  CLOCK_SKEW: 'SPAK-8005',
+  MODULE_NOT_FOUND: 'SPAK-8006',
+
+  // ---- 9xxx fatal ---------------------------------------------------------
+  OUT_OF_MEMORY: 'SPAK-9001',
+  STACK_OVERFLOW: 'SPAK-9002',
+  NATIVE_CRASH: 'SPAK-9003',
+  CORRUPT_PACKAGE: 'SPAK-9004',
+  HANDLE_REVOKED: 'SPAK-9005',
+  UNKNOWN: 'SPAK-9999',
+} as const
+
+export type ErrorCode = typeof CODES[keyof typeof CODES]
+
+/** Numeric part of a code, e.g. `SPAK-4101` → 4101. */
+export function codeNumber(code: string): number {
+  const match = /^SPAK-(\d{4})$/.exec(code)
+  return match ? Number(match[1]) : 0
+}
+
+export function isKnownCode(code: string): boolean {
+  return Object.values(CODES).includes(code as ErrorCode)
+}