@starpak/error 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-present Spak Team
+Copyright (c) 2019-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/codes.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 declare const CODES: {
+    readonly SYNTAX: "SPAK-1001";
+    readonly UNEXPECTED_TOKEN: "SPAK-1002";
+    readonly UNTERMINATED_STRING: "SPAK-1003";
+    readonly TYPE_MISMATCH: "SPAK-1004";
+    readonly POSSIBLY_NIL: "SPAK-1005";
+    readonly UNKNOWN_TYPE: "SPAK-1006";
+    readonly ARGUMENT_MISMATCH: "SPAK-1007";
+    readonly RETURN_MISMATCH: "SPAK-1008";
+    readonly DUPLICATE_DECLARATION: "SPAK-1009";
+    readonly TYPE_ALIAS_CYCLE: "SPAK-1010";
+    readonly MISSING_FIELD: "SPAK-1011";
+    readonly ZERO_BASED_INDEX: "SPAK-1012";
+    readonly BUILD_FAILED: "SPAK-2001";
+    readonly ENTRY_NOT_FOUND: "SPAK-2002";
+    readonly UNKNOWN_TARGET: "SPAK-2003";
+    readonly PAK_MAGIC_INVALID: "SPAK-2004";
+    readonly PAK_VERSION_UNSUPPORTED: "SPAK-2005";
+    readonly PAK_MANIFEST_INVALID: "SPAK-2006";
+    readonly PAK_TRUNCATED: "SPAK-2007";
+    readonly OUTPUT_NOT_WRITABLE: "SPAK-2008";
+    readonly DISK_FULL: "SPAK-2009";
+    readonly MANIFEST_INVALID: "SPAK-3001";
+    readonly DEPENDENCY_MISSING: "SPAK-3002";
+    readonly DEPENDENCY_CYCLE: "SPAK-3003";
+    readonly DUPLICATE_MOD_ID: "SPAK-3004";
+    readonly ENTRY_UNSUPPORTED: "SPAK-3005";
+    readonly SPK_COMPILE_FAILED: "SPAK-3006";
+    readonly VERSION_MISMATCH: "SPAK-3007";
+    readonly UNCAUGHT_EXCEPTION: "SPAK-4001";
+    readonly UNHANDLED_REJECTION: "SPAK-4002";
+    readonly PORT_IN_USE: "SPAK-4003";
+    readonly LISTEN_FAILED: "SPAK-4004";
+    readonly ROUTE_DUPLICATE: "SPAK-4005";
+    readonly HANDLER_THREW: "SPAK-4006";
+    readonly BODY_TOO_LARGE: "SPAK-4007";
+    readonly PERMISSION_UNDECLARED: "SPAK-5001";
+    readonly FS_DENIED: "SPAK-5002";
+    readonly NETWORK_DENIED: "SPAK-5003";
+    readonly CHILD_PROCESS_DENIED: "SPAK-5004";
+    readonly DANGEROUS_API: "SPAK-5005";
+    readonly FS_NOT_FOUND: "SPAK-6001";
+    readonly FS_DENIED_BY_OS: "SPAK-6002";
+    readonly FS_OPERATION_NOT_PERMITTED: "SPAK-6003";
+    readonly FS_NO_SPACE: "SPAK-6004";
+    readonly FS_TOO_MANY_OPEN_FILES: "SPAK-6005";
+    readonly FS_IS_DIRECTORY: "SPAK-6006";
+    readonly FS_RENAME_UNSUPPORTED: "SPAK-6007";
+    readonly NET_CONNECTION_REFUSED: "SPAK-7001";
+    readonly NET_CONNECTION_RESET: "SPAK-7002";
+    readonly NET_TIMEOUT: "SPAK-7003";
+    readonly NET_DNS: "SPAK-7004";
+    readonly NET_TLS: "SPAK-7005";
+    readonly NET_PROXY_AUTH: "SPAK-7006";
+    readonly NET_HTTP_STATUS: "SPAK-7007";
+    readonly NODE_VERSION: "SPAK-8001";
+    readonly NATIVE_MODULE: "SPAK-8002";
+    readonly PLATFORM_UNSUPPORTED: "SPAK-8003";
+    readonly ENCODING: "SPAK-8004";
+    readonly CLOCK_SKEW: "SPAK-8005";
+    readonly MODULE_NOT_FOUND: "SPAK-8006";
+    readonly OUT_OF_MEMORY: "SPAK-9001";
+    readonly STACK_OVERFLOW: "SPAK-9002";
+    readonly NATIVE_CRASH: "SPAK-9003";
+    readonly CORRUPT_PACKAGE: "SPAK-9004";
+    readonly HANDLE_REVOKED: "SPAK-9005";
+    readonly UNKNOWN: "SPAK-9999";
+};
+export type ErrorCode = typeof CODES[keyof typeof CODES];
+/** Numeric part of a code, e.g. `SPAK-4101` → 4101. */
+export declare function codeNumber(code: string): number;
+export declare function isKnownCode(code: string): boolean;
+//# sourceMappingURL=codes.d.ts.map

package/lib/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFR,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,CAAA;AAExD,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/lib/codes.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODES = void 0;
+exports.codeNumber = codeNumber;
+exports.isKnownCode = isKnownCode;
+exports.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',
+    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',
+    // ---- 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',
+    // ---- 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',
+};
+/** Numeric part of a code, e.g. `SPAK-4101` → 4101. */
+function codeNumber(code) {
+    const match = /^SPAK-(\d{4})$/.exec(code);
+    return match ? Number(match[1]) : 0;
+}
+function isKnownCode(code) {
+    return Object.values(exports.CODES).includes(code);
+}
+//# sourceMappingURL=codes.js.map

package/lib/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AA2FH,gCAGC;AAED,kCAEC;AAhGY,QAAA,KAAK,GAAG;IACnB,4EAA4E;IAC5E,MAAM,EAAE,WAAW;IACnB,gBAAgB,EAAE,WAAW;IAC7B,mBAAmB,EAAE,WAAW;IAChC,aAAa,EAAE,WAAW;IAC1B,YAAY,EAAE,WAAW;IACzB,YAAY,EAAE,WAAW;IACzB,iBAAiB,EAAE,WAAW;IAC9B,eAAe,EAAE,WAAW;IAC5B,qBAAqB,EAAE,WAAW;IAClC,gBAAgB,EAAE,WAAW;IAC7B,aAAa,EAAE,WAAW;IAC1B,gBAAgB,EAAE,WAAW;IAE7B,4EAA4E;IAC5E,YAAY,EAAE,WAAW;IACzB,eAAe,EAAE,WAAW;IAC5B,cAAc,EAAE,WAAW;IAC3B,iBAAiB,EAAE,WAAW;IAC9B,uBAAuB,EAAE,WAAW;IACpC,oBAAoB,EAAE,WAAW;IACjC,aAAa,EAAE,WAAW;IAC1B,mBAAmB,EAAE,WAAW;IAChC,SAAS,EAAE,WAAW;IAEtB,4EAA4E;IAC5E,gBAAgB,EAAE,WAAW;IAC7B,kBAAkB,EAAE,WAAW;IAC/B,gBAAgB,EAAE,WAAW;IAC7B,gBAAgB,EAAE,WAAW;IAC7B,iBAAiB,EAAE,WAAW;IAC9B,kBAAkB,EAAE,WAAW;IAC/B,gBAAgB,EAAE,WAAW;IAE7B,4EAA4E;IAC5E,kBAAkB,EAAE,WAAW;IAC/B,mBAAmB,EAAE,WAAW;IAChC,WAAW,EAAE,WAAW;IACxB,aAAa,EAAE,WAAW;IAC1B,eAAe,EAAE,WAAW;IAC5B,aAAa,EAAE,WAAW;IAC1B,cAAc,EAAE,WAAW;IAE3B,4EAA4E;IAC5E,qBAAqB,EAAE,WAAW;IAClC,SAAS,EAAE,WAAW;IACtB,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,WAAW;IACjC,aAAa,EAAE,WAAW;IAE1B,4EAA4E;IAC5E,YAAY,EAAE,WAAW;IACzB,eAAe,EAAE,WAAW;IAC5B,0BAA0B,EAAE,WAAW;IACvC,WAAW,EAAE,WAAW;IACxB,sBAAsB,EAAE,WAAW;IACnC,eAAe,EAAE,WAAW;IAC5B,qBAAqB,EAAE,WAAW;IAElC,4EAA4E;IAC5E,sBAAsB,EAAE,WAAW;IACnC,oBAAoB,EAAE,WAAW;IACjC,WAAW,EAAE,WAAW;IACxB,OAAO,EAAE,WAAW;IACpB,OAAO,EAAE,WAAW;IACpB,cAAc,EAAE,WAAW;IAC3B,eAAe,EAAE,WAAW;IAE5B,4EAA4E;IAC5E,YAAY,EAAE,WAAW;IACzB,aAAa,EAAE,WAAW;IAC1B,oBAAoB,EAAE,WAAW;IACjC,QAAQ,EAAE,WAAW;IACrB,UAAU,EAAE,WAAW;IACvB,gBAAgB,EAAE,WAAW;IAE7B,4EAA4E;IAC5E,aAAa,EAAE,WAAW;IAC1B,cAAc,EAAE,WAAW;IAC3B,YAAY,EAAE,WAAW;IACzB,eAAe,EAAE,WAAW;IAC5B,cAAc,EAAE,WAAW;IAC3B,OAAO,EAAE,WAAW;CACZ,CAAA;AAIV,uDAAuD;AACvD,SAAgB,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzC,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACrC,CAAC;AAED,SAAgB,WAAW,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,aAAK,CAAC,CAAC,QAAQ,CAAC,IAAiB,CAAC,CAAA;AACzD,CAAC"}

package/lib/definitions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Spak Error - error definitions
+ *
+ * Every code must answer: 哪里错 → 为什么 → 怎么改. Keep `why` and `fix`
+ * actionable; `ui` is what the Spak OS error panel renders.
+ */
+export type Severity = 'info' | 'warning' | 'error' | 'fatal';
+export type Category = 'language' | 'build' | 'mod' | 'runtime' | 'permission' | 'fs' | 'network' | 'env' | 'fatal';
+export interface ErrorUI {
+    icon?: string;
+    color?: string;
+    /** One-click actions shown by the OS panel. */
+    actions?: string[];
+}
+export interface ErrorDefinition {
+    code: string;
+    title: string;
+    severity: Severity;
+    category: Category;
+    why: string;
+    fix: string[];
+    docs?: string;
+    ui?: ErrorUI;
+    related?: string[];
+}
+export declare const DEFINITIONS: Record<string, ErrorDefinition>;
+export declare function getDefinition(code: string): ErrorDefinition | undefined;
+export declare function allDefinitions(): ErrorDefinition[];
+/** Codes that only warn; used by `format` to pick colors and exit codes. */
+export declare function isFatal(code: string): boolean;
+//# sourceMappingURL=definitions.d.ts.map

package/lib/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAC7D,MAAM,MAAM,QAAQ,GAChB,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,GACxC,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,CAAA;AAErD,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,QAAQ,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAoKD,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAEvD,CAAA;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEvE;AAED,wBAAgB,cAAc,IAAI,eAAe,EAAE,CAElD;AAED,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7C"}

package/lib/definitions.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Spak Error - error definitions
+ *
+ * Every code must answer: 哪里错 → 为什么 → 怎么改. Keep `why` and `fix`
+ * actionable; `ui` is what the Spak OS error panel renders.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFINITIONS = void 0;
+exports.getDefinition = getDefinition;
+exports.allDefinitions = allDefinitions;
+exports.isFatal = isFatal;
+const codes_1 = require("./codes");
+const D = (code, title, severity, category, why, fix, extra = {}) => ({ code, title, severity, category, why, fix, ...extra });
+const LIST = [
+    // ---------------- 1xxx language ----------------
+    D(codes_1.CODES.SYNTAX, '语法错误', 'error', 'language', '源码不符合 Spak 语法，解析器在报错位置无法继续。', ['看报错列出的行与列，重点检查该位置前一个 token', '用 `spm run <file>` 复现，最小化到能触发错误的最短代码']),
+    D(codes_1.CODES.UNEXPECTED_TOKEN, '意外的 token', 'error', 'language', '在只能出现特定 token 的位置出现了别的符号，常见于漏写 `end`、多写逗号。', ['检查该块是否缺少 `end`', '检查上一行是否多写 `)`、`,` 或 `then`'], { related: [codes_1.CODES.SYNTAX] }),
+    D(codes_1.CODES.UNTERMINATED_STRING, '字符串没有闭合', 'error', 'language', '字符串缺少结束引号，或跨行字符串没有使用 `"""`。', ['补齐引号', '多行文本请用 `"""..."""`']),
+    D(codes_1.CODES.TYPE_MISMATCH, '类型不匹配', 'error', 'language', '注解声明的类型与实际值的类型不一致。', ['看两侧类型，确认是值写错还是注解写错', '需要字符串时用 `tostring(x)` 或 `f"{x}"`']),
+    D(codes_1.CODES.POSSIBLY_NIL, '可能为 nil', 'error', 'language', '值来自可空类型，使用前没有收窄。', ['用 `if x then` 收窄', '或用 `x ?? 默认值` 提供兜底']),
+    D(codes_1.CODES.UNKNOWN_TYPE, '未知类型名', 'error', 'language', '注解引用了不存在的类型或没写 `type` 别名。', ['检查拼写与大小写', '先 `type X = {...}` 声明再使用'], { related: [codes_1.CODES.TYPE_ALIAS_CYCLE] }),
+    D(codes_1.CODES.ARGUMENT_MISMATCH, '参数数量或类型不符', 'error', 'language', '调用处传入的实参与函数声明的形参对不上。', ['核对函数签名', '可变参数用 `...` 接收']),
+    D(codes_1.CODES.RETURN_MISMATCH, '返回值与注解不符', 'error', 'language', '函数声明了返回类型，但实际返回了别的类型。', ['检查所有 `return` 分支', '没有返回值时把返回类型改成 `nil` 或不写']),
+    D(codes_1.CODES.DUPLICATE_DECLARATION, '重复声明', 'error', 'language', '同一作用域里同名绑定被声明了两次。', ['改掉其中一个名字', '确实要覆盖就先赋值而不是重新声明']),
+    D(codes_1.CODES.TYPE_ALIAS_CYCLE, '类型别名循环', 'error', 'language', '类型别名直接或间接引用了自己，无法展开。', ['打断循环：至少一处使用具体类型（如 `[T]` 或 `{k: v}`）']),
+    D(codes_1.CODES.MISSING_FIELD, '字段不存在', 'error', 'language', '访问了记录类型上不存在的字段。', ['检查字段拼写', '先给对象补上该字段，或把类型放宽为 `any`']),
+    D(codes_1.CODES.ZERO_BASED_INDEX, '1 基索引误用', 'error', 'language', 'Spak 的序列下标从 1 开始，`list[0]` 取不到元素。', ['把 `list[0]` 改成 `list[1]`', '遍历优先用 `for x in list` 而不是手写下标']),
+    // ---------------- 2xxx build ----------------
+    D(codes_1.CODES.BUILD_FAILED, '构建失败', 'error', 'build', '打包器（esbuild/SEA/容器封装）在某个阶段返回了错误。', ['看构建日志里的第一条错误，后面通常是连锁反应', '`spm build` 加 `--target` 明确目标']),
+    D(codes_1.CODES.ENTRY_NOT_FOUND, '入口文件不存在', 'error', 'build', '清单里的 `entry`（或默认 `index.ts`）在目录里找不到。', ['检查 `mod.json` / `spak.app.json` 的 `entry` 路径', '确认文件大小写与扩展名一致']),
+    D(codes_1.CODES.UNKNOWN_TARGET, '未知构建目标', 'error', 'build', '`--target` 传了当前构建器不支持的名字。', ['可用目标：node / server / app / web / gal', '`spm build --help` 查看当次构建器支持列表']),
+    D(codes_1.CODES.PAK_MAGIC_INVALID, '不是有效的 SPAK 包', 'error', 'build', '文件头不是 `SPAK`，可能不是包或下载被截断。', ['确认文件来源', '重新下载；必要时用 `parsePak` 校验']),
+    D(codes_1.CODES.PAK_VERSION_UNSUPPORTED, '包版本不支持', 'error', 'build', '容器版本高于当前运行时能读的版本。', ['升级 Spak 运行时', '或让打包方使用 v2 格式']),
+    D(codes_1.CODES.PAK_MANIFEST_INVALID, '包清单损坏', 'error', 'build', '容器里的 manifest 不是合法 JSON 或缺少必填字段。', ['重新打包', '检查打包脚本是否写入了空清单']),
+    D(codes_1.CODES.PAK_TRUNCATED, '包被截断', 'error', 'build', '文件长度小于 manifest 声明的长度，传输不完整。', ['重新下载', '校验文件大小与哈希']),
+    D(codes_1.CODES.OUTPUT_NOT_WRITABLE, '输出目录不可写', 'error', 'build', '目标目录不存在或当前用户没有写权限。', ['换到有写权限的目录', '检查挂载点是否只读']),
+    D(codes_1.CODES.DISK_FULL, '磁盘空间不足', 'error', 'build', '写入产物时文件系统返回 ENOSPC。', ['清理 `dist/`、缓存与旧版本产物', '换更大的磁盘或挂载点']),
+    // ---------------- 3xxx mods / apps ----------------
+    D(codes_1.CODES.MANIFEST_INVALID, '清单字段非法', 'error', 'mod', '`mod.json` / `spak.app.json` 缺字段或类型不对。', ['按文档补齐 id / name / version / entry', '错误信息会指出具体字段名']),
+    D(codes_1.CODES.DEPENDENCY_MISSING, '依赖缺失', 'error', 'mod', '`requires` 里声明的模组没有被安装或 id 拼错。', ['`spm mod add <id>` 安装依赖', '检查依赖 id 是否与对方 `mod.json` 一致']),
+    D(codes_1.CODES.DEPENDENCY_CYCLE, '循环依赖', 'error', 'mod', '模组之间互相依赖，无法确定装载顺序。', ['把公共部分抽成第三个模组', '打断其中一条 `requires`']),
+    D(codes_1.CODES.DUPLICATE_MOD_ID, '模组 id 重复', 'error', 'mod', '两个目录声明了同一个 id。', ['改掉其中一个 id', '删掉旧版本残留目录']),
+    D(codes_1.CODES.ENTRY_UNSUPPORTED, '入口类型不支持', 'error', 'mod', '入口扩展名不在支持列表内。', ['支持 .spk / .js / .mjs / .cjs', '把入口改成 `index.spk` 或编译为 `.mjs`']),
+    D(codes_1.CODES.SPK_COMPILE_FAILED, '模组 .spk 编译失败', 'error', 'mod', '模组源码没通过类型检查或代码生成。', ['按诊断修源码', '先用 `spm run <file>` 单独跑通']),
+    D(codes_1.CODES.VERSION_MISMATCH, '版本不兼容', 'error', 'mod', '模组要求的 SDK / OS 版本与当前宿主不符。', ['升级宿主或降低模组要求', '检查 `sdk` / `os.min` 字段']),
+    // ---------------- 4xxx runtime ----------------
+    D(codes_1.CODES.UNCAUGHT_EXCEPTION, '未捕获异常', 'fatal', 'runtime', '异常逃出了所有 try/catch，进程即将退出。', ['按堆栈定位第一行业务代码', '在该层加 `try/catch` 并给出可读错误']),
+    D(codes_1.CODES.UNHANDLED_REJECTION, '未处理的 Promise 拒绝', 'fatal', 'runtime', '异步调用失败但没有任何 catch。', ['给 Promise 加 `.catch()` 或用 `try/await`', '加全局 `process.on("unhandledRejection")` 兜底上报']),
+    D(codes_1.CODES.PORT_IN_USE, '端口已被占用', 'error', 'runtime', '另一个进程已经监听该端口。', ['换端口（`spak.config.yml` 的 `server.port`）', '或结束占用进程：`lsof -i :<port>`']),
+    D(codes_1.CODES.LISTEN_FAILED, '监听失败', 'error', 'runtime', '地址不可用、权限不足或端口被系统保留。', ['改用 `0.0.0.0` 或 `127.0.0.1`', '小于 1024 的端口需要额外权限']),
+    D(codes_1.CODES.ROUTE_DUPLICATE, '路由重复注册', 'warning', 'runtime', '同一 method + path 被注册两次，后注册的会覆盖前者。', ['合并处理函数', '给不同模组的路由加前缀']),
+    D(codes_1.CODES.HANDLER_THREW, '请求处理函数抛错', 'error', 'runtime', '路由 handler 内部异常，已返回 500。', ['看服务日志里的原始堆栈', '把可能失败的 IO 放进 try/catch']),
+    D(codes_1.CODES.BODY_TOO_LARGE, '请求体过大', 'warning', 'runtime', '请求体超过 1 MB 上限，已被拒绝（413）。', ['改传文件而不是塞进 JSON', '或调大宿主的上限配置']),
+    // ---------------- 5xxx permission ----------------
+    D(codes_1.CODES.PERMISSION_UNDECLARED, '权限未声明', 'error', 'permission', '调用了清单里没有声明的能力。', ['在 `permissions` 里显式声明（fs / network / childProcess）', '最小权限原则：只开需要的']),
+    D(codes_1.CODES.FS_DENIED, '文件访问被拒绝', 'error', 'permission', '模组/应用没有 fs 权限，或只读却尝试写入。', ['申请 `fs: read` 或 `fs: write`', '把要读的文件放进允许的目录']),
+    D(codes_1.CODES.NETWORK_DENIED, '网络访问被拒绝', 'error', 'permission', '清单没有开启网络，或只允许 localhost。', ['声明 `network: localhost` 或 `all`', '避免在启动阶段发起外网请求']),
+    D(codes_1.CODES.CHILD_PROCESS_DENIED, '子进程被禁止', 'error', 'permission', '清单的 `childProcess` 为 false。', ['改用内置能力实现', '确实需要就声明 `childProcess: true` 并说明原因']),
+    D(codes_1.CODES.DANGEROUS_API, '危险 API 调用', 'fatal', 'permission', '调用了沙箱明确禁止的接口（eval / 动态执行 / 原生模块）。', ['换成安全替代实现', '如确需使用，走宿主提供的受控接口']),
+    // ---------------- 6xxx filesystem ----------------
+    D(codes_1.CODES.FS_NOT_FOUND, '文件或目录不存在', 'error', 'fs', '路径拼错、文件被删，或工作目录不是预期的那个。', ['打印 `process.cwd()` 与绝对路径确认', '用 `fs.existsSync` 先判断再读']),
+    D(codes_1.CODES.FS_DENIED_BY_OS, '权限不足（EACCES/EPERM）', 'error', 'fs', '当前用户对目标路径没有读/写/执行权限。', ['检查文件 mode 与属主', '换有权限的目录，或提升权限后再试']),
+    D(codes_1.CODES.FS_OPERATION_NOT_PERMITTED, '操作不被允许（EPERM）', 'error', 'fs', '文件系统或安全策略禁止该操作（如 chmod/chown）。', ['避免对挂载盘做权限变更', '改用复制到本地盘再操作']),
+    D(codes_1.CODES.FS_NO_SPACE, '磁盘已满（ENOSPC）', 'fatal', 'fs', '写入时空间耗尽，进程可能已产生半个文件。', ['清理临时目录与旧产物', '检查是否写进了内存盘']),
+    D(codes_1.CODES.FS_TOO_MANY_OPEN_FILES, '打开文件过多（EMFILE）', 'error', 'fs', '文件句柄泄漏，或超过 `ulimit -n`。', ['确保每个 open 都有 close', '批量处理时分批并复用句柄']),
+    D(codes_1.CODES.FS_IS_DIRECTORY, '目标是目录（EISDIR）', 'error', 'fs', '把目录当成文件读取或覆盖。', ['先 `stat` 判断类型', '目录操作用 `readdir` 而不是 `readFile`']),
+    D(codes_1.CODES.FS_RENAME_UNSUPPORTED, '重命名/原子写失败（FUSE）', 'error', 'fs', '在 Android FUSE 挂载盘上，重命名会残留 `.l2s.tmp_*` 并报 ENOENT。', ['把 git 仓库/.git 或构建产物放到本地盘', '避免在挂载盘上做原子写与符号链接']),
+    // ---------------- 7xxx network ----------------
+    D(codes_1.CODES.NET_CONNECTION_REFUSED, '连接被拒绝', 'error', 'network', '目标端口没有服务在监听，或防火墙直接拒绝。', ['确认服务已启动并监听该端口', '检查地址是否写成了内网/回环']),
+    D(codes_1.CODES.NET_CONNECTION_RESET, '连接被重置', 'error', 'network', '对端或中间设备主动断开（常见于被墙/代理超时）。', ['重试并退避', '换镜像/代理；检查 TLS 版本']),
+    D(codes_1.CODES.NET_TIMEOUT, '请求超时', 'error', 'network', '在超时时间内没有收到完整响应。', ['调大超时并加分类重试', '先测同域名的小请求定位是网络还是服务慢']),
+    D(codes_1.CODES.NET_DNS, '域名解析失败', 'error', 'network', '域名不存在或 DNS 不可用。', ['`nslookup` 验证域名', '换 DNS 或临时用 IP']),
+    D(codes_1.CODES.NET_TLS, 'TLS 握手失败', 'error', 'network', '证书链、协议版本或系统时间不正确。', ['检查系统时间', '更新 CA 证书；企业代理需额外信任根证书']),
+    D(codes_1.CODES.NET_PROXY_AUTH, '代理认证失败', 'error', 'network', '代理要求凭据，或凭据已过期。', ['更新代理用户名/密码或 token', '确认 `HTTP(S)_PROXY` 环境变量正确']),
+    D(codes_1.CODES.NET_HTTP_STATUS, 'HTTP 状态码异常', 'error', 'network', '对端返回 4xx/5xx。', ['先看响应体里的错误信息', '4xx 查请求参数，5xx 看对端日志']),
+    // ---------------- 8xxx environment ----------------
+    D(codes_1.CODES.NODE_VERSION, 'Node 版本不满足要求', 'error', 'env', '当前运行时低于所需版本（构建目标为 node24）。', ['升级 Node 到 24+', '或把构建目标降到你实际运行的版本']),
+    D(codes_1.CODES.NATIVE_MODULE, '原生模块加载失败', 'error', 'env', 'ABI 不匹配、缺少系统库，或挂载盘无法 mmap。', ['用对应 Node 版本重新编译', '装缺失的 .so；避免从 FUSE 盘加载 .node']),
+    D(codes_1.CODES.PLATFORM_UNSUPPORTED, '平台不支持', 'error', 'env', '目标平台不在当前构建器支持列表内。', ['查看 `docs/spak-os.md` 的支持矩阵', '用交叉构建或换平台']),
+    D(codes_1.CODES.ENCODING, '编码/终端问题', 'warning', 'env', '输出包含终端无法显示的字符，或文件不是 UTF-8。', ['统一用 UTF-8', '`LANG=C.UTF-8` 后再运行']),
+    D(codes_1.CODES.CLOCK_SKEW, '系统时间偏移', 'warning', 'env', '本机时间与服务器差距过大，导致证书/签名校验失败。', ['开启自动对时', '检查时区设置']),
+    D(codes_1.CODES.MODULE_NOT_FOUND, '模块找不到（MODULE_NOT_FOUND）', 'error', 'env', 'import/require 的包没有安装，或路径解析到了工作区之外。', ['`pnpm install` 补齐依赖', '检查包名拼写与 `exports` 映射', '相对路径要用 `./` 开头']),
+    // ---------------- 9xxx fatal ----------------
+    D(codes_1.CODES.OUT_OF_MEMORY, '内存耗尽', 'fatal', 'fatal', '堆内存超过 V8 上限，进程被终止。', ['定位大对象/无限累积的数组', '临时用 `--max-old-space-size=4096` 顶住，再修根因']),
+    D(codes_1.CODES.STACK_OVERFLOW, '调用栈溢出', 'fatal', 'fatal', '无限递归或循环引用触发深度遍历。', ['找递归出口', '深树结构改用显式栈遍历']),
+    D(codes_1.CODES.NATIVE_CRASH, '原生崩溃/段错误', 'fatal', 'fatal', '原生插件或运行时自身崩溃，JS 层 catch 不到。', ['用最小复现定位是哪个 addon', '禁用可疑原生模块后重试']),
+    D(codes_1.CODES.CORRUPT_PACKAGE, '包数据损坏', 'fatal', 'fatal', '`.app` / `.pak` 内容与清单不一致或校验失败。', ['重新下载并核对哈希', '不要手工改包内文件']),
+    D(codes_1.CODES.HANDLE_REVOKED, '句柄中途失效', 'fatal', 'fatal', '文件/网络句柄被外部关闭（权限撤销、设备拔出）。', ['捕获 EBADF 并重建句柄', '不要把句柄长期跨作用域缓存']),
+    D(codes_1.CODES.UNKNOWN, '未识别的错误', 'error', 'fatal', '错误不匹配任何已知模式。', ['保留完整堆栈与复现步骤', '附上 `spm -v` 与系统信息再反馈']),
+];
+exports.DEFINITIONS = Object.fromEntries(LIST.map(definition => [definition.code, definition]));
+function getDefinition(code) {
+    return exports.DEFINITIONS[code];
+}
+function allDefinitions() {
+    return Object.values(exports.DEFINITIONS);
+}
+/** Codes that only warn; used by `format` to pick colors and exit codes. */
+function isFatal(code) {
+    const definition = getDefinition(code);
+    return definition?.severity === 'fatal';
+}
+//# sourceMappingURL=definitions.js.map

package/lib/definitions.js.map

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

package/lib/error.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Spak Error - error class and normalization
+ *
+ * `SpakError` always carries a code, its definition, and the original cause.
+ * `toInfo()` is the single shape every renderer consumes.
+ */
+import { type Category, type ErrorDefinition, type ErrorUI, type Severity } from './definitions';
+export interface ErrorContext {
+    [key: string]: unknown;
+}
+export interface ErrorInfo {
+    code: string;
+    title: string;
+    severity: Severity;
+    category: Category;
+    why: string;
+    fix: string[];
+    docs?: string;
+    ui?: ErrorUI;
+    /** Human message for this occurrence (falls back to the definition title). */
+    message: string;
+    /** Where it happened: file:line:col, module id, route, etc. */
+    where?: string;
+    context?: ErrorContext;
+    cause?: Error;
+}
+export interface SpakErrorOptions {
+    cause?: unknown;
+    where?: string;
+    context?: ErrorContext;
+    /** Occurrence-specific message; the definition title is used when omitted. */
+    message?: string;
+}
+export declare class SpakError extends Error {
+    readonly code: string;
+    readonly definition: ErrorDefinition;
+    readonly where?: string;
+    readonly context?: ErrorContext;
+    readonly cause?: Error;
+    constructor(code: string, options?: SpakErrorOptions);
+    get severity(): Severity;
+    get fix(): string[];
+    toInfo(): ErrorInfo;
+}
+export declare function isSpakError(value: unknown): value is SpakError;
+/** Build an `ErrorInfo` for a definition without throwing. */
+export declare function describe(code: string, options?: {
+    where?: string;
+    context?: ErrorContext;
+    message?: string;
+}): ErrorInfo;
+/** Language diagnostics → Spak errors. Keeps the original position. */
+export declare function fromDiagnostic(diagnostic: {
+    code: string;
+    message: string;
+    loc?: {
+        line: number;
+        column: number;
+    };
+}): SpakError;
+//# sourceMappingURL=error.d.ts.map

package/lib/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE5H,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,QAAQ,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAUD,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAWxD,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,GAAG,IAAI,MAAM,EAAE,CAElB;IAED,MAAM,IAAI,SAAS;CAiBpB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAE5H;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,UAAU,EAAE;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACvC,GAAG,SAAS,CAgBZ"}

package/lib/error.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Spak Error - error class and normalization
+ *
+ * `SpakError` always carries a code, its definition, and the original cause.
+ * `toInfo()` is the single shape every renderer consumes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpakError = void 0;
+exports.isSpakError = isSpakError;
+exports.describe = describe;
+exports.fromDiagnostic = fromDiagnostic;
+const codes_1 = require("./codes");
+const definitions_1 = require("./definitions");
+const FALLBACK = definitions_1.DEFINITIONS[codes_1.CODES.UNKNOWN];
+function asError(cause) {
+    if (!cause)
+        return undefined;
+    if (cause instanceof Error)
+        return cause;
+    return new Error(String(cause));
+}
+class SpakError extends Error {
+    code;
+    definition;
+    where;
+    context;
+    cause;
+    constructor(code, options = {}) {
+        const definition = (0, definitions_1.getDefinition)(code) ?? FALLBACK;
+        super(options.message ?? definition.title);
+        this.name = 'SpakError';
+        this.code = definition.code;
+        this.definition = definition;
+        this.where = options.where;
+        this.context = options.context;
+        this.cause = asError(options.cause);
+    }
+    get severity() {
+        return this.definition.severity;
+    }
+    get fix() {
+        return this.definition.fix;
+    }
+    toInfo() {
+        const definition = this.definition;
+        return {
+            code: definition.code,
+            title: definition.title,
+            severity: definition.severity,
+            category: definition.category,
+            why: definition.why,
+            fix: definition.fix,
+            docs: definition.docs,
+            ui: definition.ui,
+            message: this.message,
+            where: this.where,
+            context: this.context,
+            cause: this.cause,
+        };
+    }
+}
+exports.SpakError = SpakError;
+function isSpakError(value) {
+    return value instanceof SpakError;
+}
+/** Build an `ErrorInfo` for a definition without throwing. */
+function describe(code, options = {}) {
+    return new SpakError(code, options).toInfo();
+}
+/** Language diagnostics → Spak errors. Keeps the original position. */
+function fromDiagnostic(diagnostic) {
+    const mapping = {
+        E001: codes_1.CODES.TYPE_MISMATCH,
+        E002: codes_1.CODES.POSSIBLY_NIL,
+        E003: codes_1.CODES.UNKNOWN_TYPE,
+        E004: codes_1.CODES.ARGUMENT_MISMATCH,
+        E005: codes_1.CODES.RETURN_MISMATCH,
+        E006: codes_1.CODES.TYPE_ALIAS_CYCLE,
+        E007: codes_1.CODES.MISSING_FIELD,
+        W001: codes_1.CODES.UNKNOWN,
+        W002: codes_1.CODES.UNKNOWN,
+        W003: codes_1.CODES.UNKNOWN,
+    };
+    const code = mapping[diagnostic.code] ?? codes_1.CODES.UNKNOWN;
+    const where = diagnostic.loc ? `line ${diagnostic.loc.line}:${diagnostic.loc.column}` : undefined;
+    return new SpakError(code, { message: diagnostic.message, where, context: { diagnostic: diagnostic.code } });
+}
+//# sourceMappingURL=error.js.map

package/lib/error.js.map

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

package/lib/format.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Spak Error - renderers
+ *
+ * One `ErrorInfo` → four surfaces: terminal text, JSON (CI/logs), HTML
+ * (Spak OS panel) and Markdown (docs/issues).
+ */
+import type { ErrorInfo } from './error';
+export type FormatKind = 'text' | 'json' | 'html' | 'markdown';
+export interface FormatOptions {
+    /** ANSI colors in `text`; defaults to TTY detection. */
+    color?: boolean;
+    /** Prefix for the location line, e.g. a file path. */
+    file?: string;
+}
+export declare function format(info: ErrorInfo, kind?: FormatKind, options?: FormatOptions): string;
+/** Exit code convention: fatal/error → 1, warning/info → 0. */
+export declare function exitCodeFor(info: ErrorInfo): number;
+//# sourceMappingURL=format.d.ts.map

package/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9D,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AA4CD,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,UAAmB,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAWtG;AA4GD,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEnD"}