@starpak/error 0.0.0-stage → 0.1.0

package/src/definitions.ts

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

package/src/error.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { CODES } from './codes'
+import { DEFINITIONS, getDefinition, 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
+}
+
+const FALLBACK = DEFINITIONS[CODES.UNKNOWN]
+
+function asError(cause: unknown): Error | undefined {
+  if (!cause) return undefined
+  if (cause instanceof Error) return cause
+  return new Error(String(cause))
+}
+
+export class SpakError extends Error {
+  readonly code: string
+  readonly definition: ErrorDefinition
+  readonly where?: string
+  readonly context?: ErrorContext
+  readonly cause?: Error
+
+  constructor(code: string, options: SpakErrorOptions = {}) {
+    const definition = 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(): Severity {
+    return this.definition.severity
+  }
+
+  get fix(): string[] {
+    return this.definition.fix
+  }
+
+  toInfo(): ErrorInfo {
+    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,
+    }
+  }
+}
+
+export function isSpakError(value: unknown): value is SpakError {
+  return value instanceof SpakError
+}
+
+/** Build an `ErrorInfo` for a definition without throwing. */
+export function describe(code: string, options: { where?: string, context?: ErrorContext, message?: string } = {}): ErrorInfo {
+  return new SpakError(code, options).toInfo()
+}
+
+/** Language diagnostics → Spak errors. Keeps the original position. */
+export function fromDiagnostic(diagnostic: {
+  code: string
+  message: string
+  loc?: { line: number, column: number }
+}): SpakError {
+  const mapping: Record<string, string> = {
+    E001: CODES.TYPE_MISMATCH,
+    E002: CODES.POSSIBLY_NIL,
+    E003: CODES.UNKNOWN_TYPE,
+    E004: CODES.ARGUMENT_MISMATCH,
+    E005: CODES.RETURN_MISMATCH,
+    E006: CODES.TYPE_ALIAS_CYCLE,
+    E007: CODES.MISSING_FIELD,
+    W001: CODES.UNKNOWN,
+    W002: CODES.UNKNOWN,
+    W003: CODES.UNKNOWN,
+  }
+  const code = mapping[diagnostic.code] ?? 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 } })
+}

package/src/format.ts

@@ -0,0 +1,183 @@
+/**
+ * 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
+}
+
+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: Record<string, string> = {
+  info: ANSI.cyan,
+  warning: ANSI.yellow,
+  error: ANSI.red,
+  fatal: ANSI.magenta,
+}
+
+const SEVERITY_CSS: Record<string, string> = {
+  info: '#2f81f7',
+  warning: '#d29922',
+  error: '#f85149',
+  fatal: '#a371f7',
+}
+
+function paint(text: string, color: string, enabled: boolean): string {
+  return enabled ? `${color}${text}${ANSI.reset}` : text
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function location(info: ErrorInfo, file?: string): string | undefined {
+  if (info.where) return file ? `${file}:${info.where}` : info.where
+  if (file) return file
+  return undefined
+}
+
+export function format(info: ErrorInfo, kind: FormatKind = 'text', options: FormatOptions = {}): string {
+  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: ErrorInfo, options: FormatOptions): string {
+  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: string[] = []
+
+  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: ErrorInfo): string {
+  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: ErrorInfo): string {
+  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: ErrorInfo): string {
+  const lines: string[] = []
+  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. */
+export function exitCodeFor(info: ErrorInfo): number {
+  return info.severity === 'fatal' || info.severity === 'error' ? 1 : 0
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 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'

package/src/native.ts

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

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.