release-skill 0.1.1 → 0.1.4

package/native/safe-write/prebuilds.json

@@ -1,4 +1,24 @@
 {
-  "comment": "Prebuilt addon manifest. Entries are added when platform-specific build evidence is available. SHA-256 hashes are required for loading prebuilt addons; source-build users must use RELEASE_SKILL_NATIVE_DEV=1.",
-  "prebuilds": {}
+  "comment": "Registered Node-API prebuilds. Each entry is loaded only after path, file identity, exports, and SHA-256 verification.",
+  "prebuilds": {
+    "darwin-arm64": {
+      "path": "prebuilds/darwin-arm64/safe_write.node",
+      "sha256": "a0e39732c359f3faa23715e6d17d8bc5fec5c5b86e0390220e1beb9f5def2d2e",
+      "exports": [
+        "openRoot",
+        "openDir",
+        "readEntry",
+        "readFile",
+        "createTemp",
+        "rename",
+        "abortTemp",
+        "mkdir",
+        "rmdir",
+        "unlink",
+        "chmod",
+        "fsync",
+        "close"
+      ]
+    }
+  }
 }

package/native/safe-write/src/safe_write.cc

@@ -637,7 +637,7 @@ static napi_value OpenDir(napi_env env, napi_callback_info info) {
 }
 
 // ---------------------------------------------------------------------------
-// readEntry(handle, name) -> { type, size, mode } | null
+// readEntry(handle, name) -> { type, size, mode, dev, ino, nlink } | null
 // ---------------------------------------------------------------------------
 
 static napi_value ReadEntry(napi_env env, napi_callback_info info) {
@@ -683,17 +683,26 @@ static napi_value ReadEntry(napi_env env, napi_callback_info info) {
   else if (S_ISCHR(st.st_mode)) type = "char-device";
   else if (S_ISSOCK(st.st_mode)) type = "socket";
 
-  napi_value type_val, size_val, mode_val;
+  napi_value type_val, size_val, mode_val, dev_val, ino_val, nlink_val;
   NAPI_CHECK(napi_create_string_utf8(env, type, NAPI_AUTO_LENGTH, &type_val));
   NAPI_CHECK(
       napi_create_int64(env, static_cast<int64_t>(st.st_size), &size_val));
   NAPI_CHECK(
       napi_create_int32(env, static_cast<int32_t>(st.st_mode & 07777),
                         &mode_val));
+  NAPI_CHECK(
+      napi_create_int64(env, static_cast<int64_t>(st.st_dev), &dev_val));
+  NAPI_CHECK(
+      napi_create_int64(env, static_cast<int64_t>(st.st_ino), &ino_val));
+  NAPI_CHECK(
+      napi_create_int64(env, static_cast<int64_t>(st.st_nlink), &nlink_val));
 
   NAPI_CHECK(napi_set_named_property(env, result, "type", type_val));
   NAPI_CHECK(napi_set_named_property(env, result, "size", size_val));
   NAPI_CHECK(napi_set_named_property(env, result, "mode", mode_val));
+  NAPI_CHECK(napi_set_named_property(env, result, "dev", dev_val));
+  NAPI_CHECK(napi_set_named_property(env, result, "ino", ino_val));
+  NAPI_CHECK(napi_set_named_property(env, result, "nlink", nlink_val));
   return result;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "repository": {
     "type": "git",
@@ -27,18 +27,20 @@
     "schemas/",
     "native/",
     "!native/safe-write/build/",
+    "scripts/build-bundle.mjs",
     "README.md",
     "README.zh-CN.md",
     "CHANGELOG.md",
     "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
     "INSTALL.md",
+    "INSTALL.zh-CN.md",
     "LICENSE",
     "NOTICE",
     "SECURITY.md"
   ],
   "scripts": {
-    "build": "node --check src/**/*.mjs",
+    "build": "node --check src/**/*.mjs && node scripts/build-bundle.mjs",
     "test": "node --test test/*.test.mjs",
     "test:no-dogfood": "node --test $(ls test/*.test.mjs | grep -v -E 'dogfood|artifacts-safe-fs-native-seam')",
     "typecheck": "node --check src/**/*.mjs bin/*.mjs",
@@ -46,7 +48,10 @@
     "sync:skills:check": "node scripts/sync-skills.mjs --check",
     "build:adapters": "node scripts/build-adapters.mjs",
     "build:adapters:check": "node scripts/build-adapters.mjs --check",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "build:bundle:check": "node scripts/build-bundle.mjs --check",
     "native:build": "node-gyp rebuild --directory native/safe-write",
+    "native:package-current": "node scripts/package-native-prebuild.mjs",
     "native:build:test": "GYP_DEFINES='test_seam=1' node-gyp rebuild --directory native/safe-write",
     "native:test": "npm run native:build:test && node --expose-gc --test test/artifacts-safe-fs-native-seam.test.mjs && npm run native:build && RELEASE_SKILL_NATIVE_DEV=1 node --test test/artifacts-safe-fs.test.mjs test/artifacts-transaction-native.test.mjs && node --input-type=module -e \"import {createRequire} from 'node:module';const a=createRequire(import.meta.url)('./native/safe-write/build/Release/safe_write.node');const k=Object.keys(a).sort();const e=['abortTemp','chmod','close','createTemp','fsync','mkdir','openDir','openRoot','readEntry','readFile','rename','rmdir','unlink'];if(k.length!==e.length||k.some((v,i)=>v!==e[i])){console.error('Production exports mismatch:',k);process.exit(1)}console.log('Production exports verified:',k.length,'functions')\""
   },
@@ -58,6 +63,7 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
+    "esbuild": "0.25.8",
     "node-gyp": "12.3.0"
   },
   "engines": {

package/references/02-project-config.md

@@ -30,6 +30,10 @@ releaseUnits:               # 发布单元数组，至少 1 个
   - id: <string>            # 唯一标识
     source: <string>        # 源码相对路径（相对项目根目录）
     publicRepo: <string>    # 公开仓库 owner/repo
+    production:
+      githubHost: github.com
+      branchTemplate: <string>
+      branchStrategy: create-release-branch # 或 advance-existing-branch / initialize-default-branch
     version:
       source: <string>      # 版本来源，如 "package.json"
       tagTemplate: <string> # tag 模板，如 "artifact-graph-v{version}"
@@ -46,6 +50,17 @@ releaseUnits:               # 发布单元数组，至少 1 个
       mode: none            # none | bound
       # bound 时还必须提供 repo/ref/commit，可选 tree/manifestDigest
 
+verificationGates:         # 可选；定义会进入冻结计划摘要
+  - id: <stable-id>
+    phase: snapshot-verify # 或 consumer-verify
+    scope:
+      unit: <release-unit-id>
+      # consumer-verify 还必须填写 distribution
+    command: [<executable>, <arg>]
+    cwd: .
+    timeoutMs: 30000
+    envAllowlist: []
+
 hooks:                      # 可选，命令 hooks
   docs: <hook>
   build: <hook>
@@ -62,7 +77,7 @@ policy:                     # 可选，安全策略
 
 ## 3. 公开源码镜像与分发包
 
-`releaseUnits[].publicFiles` 定义 GitHub 公开源码镜像的显式、闭世界 allowlist。每个映射都必须可审阅；未列出的文件不会因为目录扫描、模板重生成或历史惯例而被自动加入。`releaseUnits[].requiredPublicFiles` 只约束同一发布单元，不能借用其他单元的目标路径。
+`releaseUnits[].publicFiles` 定义 GitHub 公开源码镜像的显式、闭世界 allowlist。每个映射都必须可审阅；未列出的文件不会因为目录扫描、模板重生成或历史惯例而被自动加入。`sourceScope` 默认为 `unit`，此时 `from` 必须位于 `releaseUnits[].source` 内；只有历史共享许可证、公共文档或工作流等明确的工作空间级来源才可写 `sourceScope: workspace`，其路径仍必须受工作空间根目录的词法、realpath 和无符号链接校验约束。`releaseUnits[].requiredPublicFiles` 只约束同一发布单元，不能借用其他单元的目标路径。
 
 公开源码镜像与 distribution pack 是两条不同边界：前者决定公开仓库快照，后者由 npm `files`、插件 manifest 等渠道合同决定安装内容。发布前必须分别冻结、比较并验证两条边界；distribution pack 中的必需路径必须由该发布单元的公开映射覆盖。
 
@@ -90,6 +105,14 @@ human-owned 权威源，然后重新 prepare、审阅并 approve；后续环节
 
 旧的 `policy.requiredPublicFiles` 已不支持。加载器必须返回 `CONFIG_INVALID`，并引导迁移到各自的 `releaseUnits[].requiredPublicFiles`。
 
+### 3.2 公开分支策略
+
+- `create-release-branch`：目标分支必须不存在；创建独立 release 分支，冻结提交没有父提交。
+- `advance-existing-branch`：目标分支必须与 `previousPublicBaseline` 的精确提交一致；冻结提交以它为唯一父提交，publish 仅允许普通 fast-forward push。并发漂移或非快进时失败关闭，不使用 force。
+- `initialize-default-branch`：目标标准分支必须不存在，冻结提交以当前公开基线为父提交；只有同时声明 `setAsDefaultBranch: true` 和 `expectedCurrentDefaultBranch` 时，计划才会增加显式 `set-default-branch` action。切换失败进入 PARTIAL，可由 reconcile 依据旧/新/第三方状态恢复或转人工。
+
+已有公开仓不得使用 `mode: none` 伪装成首次发布。示例中的 commit 只是校准时点证据；每轮 production prepare 都必须在线重观测。
+
 ---
 
 ## 4. Hooks 参数约束
@@ -121,6 +144,32 @@ hooks:
     envAllowlist: [CI]
 ```
 
+### 4.1 分阶段验证 gate
+
+`verificationGates` 是项目个性化校验的受控扩展点，不是另一套发布流程：
+
+| 字段 | 约束 |
+|---|---|
+| `id` | 全局唯一、稳定，匹配 `^[a-z0-9][a-z0-9._-]*$` |
+| `phase` | `snapshot-verify` 或 `consumer-verify` |
+| `scope.unit` | 必须引用现有发布单元 |
+| `scope.distribution` | consumer 阶段必填，且必须是该单元真实声明的渠道 |
+| `command` | `execFile` 风格字符串数组；禁止 shell 字符串 |
+| `cwd` | 相对执行根，不允许路径逃逸或符号链接分量 |
+| `timeoutMs` | 1000 至 7200000 |
+| `envAllowlist` | 仅显式变量；其他凭证和环境变量不转发 |
+| `expectedJson` | 可选；stdout 必须为 JSON 且递归包含这些字段 |
+
+`snapshot-verify` 获得冻结公开快照的一次性可写副本；副本销毁后重新摘要原快照，失败时还没有远端写入。`consumer-verify` 只在精确 npm 或 Claude/Codex 隔离安装成功后，从安装根执行；结果摘要进入 verify run，失败不得达到 VERIFIED。
+
+gate 与 legacy hook 都是无网络沙箱的本地进程，必须显式确认副作用。release-skill 会限制环境、路径、超时和证据输出，但不能替项目保证其命令不会写文件或访问网络。Git push、tag、默认分支、GitHub Release 和 npm publish 只能是冻结计划里的 adapter action，不能注册为 hook/gate。
+
+### 4.2 首次接入 setup
+
+`release-skill setup --root <path> --json` 默认只读，扫描工作区、包与插件 manifest、逐单元 Git 权威、旧版 `public-release.json` 和脚本，输出候选、完整 `recommendedAnswers`、结构化冲突/假设和 `setupDigest`。旧配置只作为不可信迁移事实，其中的 `snapshotCommands` 只成为未授权 gate 候选；它不会把脚本存在解释成用户选择，也不会读取 README 中的自然语言作为命令。报告可能包含大量精确映射，Agent 应先把完整 JSON 落到系统临时文件，只读取紧凑摘要，并机械提取 `recommendedAnswers`，不得在上下文中重新生成。
+
+写入要求人工提供完整 answers JSON，再次 dry-run，并使用同一摘要执行 `--write --confirm-setup <setupDigest>`。写入只允许首次原子创建 `.release-skill/project.yaml`；已有配置返回 `ALREADY_CONFIGURED`/`CONFIG_EXISTS`，由人工增量编辑。事实漂移返回 `SETUP_DIGEST_MISMATCH`。没有远端渠道的项目返回 `LOCAL_ONLY_DETECTED`，不得宣称 production-ready。
+
 ---
 
 ## 5. Profile（规划中）
@@ -201,9 +250,11 @@ profile 是预设的默认配置模板，提供常见发布拓扑的开箱配置
 5. `releaseUnits` 至少包含 1 个元素。
 6. 每个 `releaseUnit.id` 全局唯一。
 7. 每个 `releaseUnit.source` 路径在项目中存在。
-8. 所有 hook 的 `command` 为数组且第一个元素非空。
-9. 所有 hook 的 `cwd` 不包含绝对路径前缀和 `..`。
-10. 所有路径字段不包含 `<project-root>/` 前缀。
+8. 所有 hook/gate 的 `command` 为数组且第一个元素非空。
+9. 所有 hook/gate 的 `cwd` 不包含绝对路径前缀和 `..`。
+10. gate id 唯一，unit/distribution scope 引用真实配置。
+11. 分支推进策略使用 bound 基线；默认分支初始化具备显式旧/新分支断言。
+12. 所有路径字段不包含 `<project-root>/` 前缀。
 
 验证失败返回 `CONFIG_INVALID` 错误码，附带具体失败原因。
 

package/references/05-evidence-and-errors.md

@@ -1,12 +1,12 @@
 # 05 -- 证据与错误
 
-本文档定义 release-skill 的 9 类稳定错误码、JSON/JSONL 事件格式、脱敏规则和证据目录结构。状态机见 `01-state-machine.md`，配置约束见 `02-project-config.md`。
+本文档定义 release-skill 的稳定错误码、JSON/JSONL 事件格式、脱敏规则和证据目录结构。状态机见 `01-state-machine.md`，配置约束见 `02-project-config.md`。
 
 ---
 
 ## 1. 稳定错误码
 
-以下 9 个错误码覆盖 release-skill 全部可恢复和不可恢复错误场景。错误码在所有版本间保持稳定，不得重命名或删除。
+以下列出用户最常遇到的稳定错误码。实现中的完整列表由 `src/core/errors.mjs` 维护；已发布错误码不得重命名或删除。
 
 | 错误码 | 含义 | 触发场景 | 典型恢复 |
 |---|---|---|---|
@@ -19,6 +19,8 @@
 | `HOOK_TIMEOUT` | 项目 hook 执行超时 | hook 运行时间超过 `timeoutMs` 配置 | 增加超时值或优化 hook 执行效率 |
 | `PARTIAL_RELEASE` | 发布部分成功 | 至少一个外部检查点成功但后续检查点失败 | 使用 `reconcile` 从检查点恢复 |
 | `POST_PUBLISH_VERIFY_FAILED` | 发布后验证未通过 | 安装测试失败、泄漏审计未通过、provenance 验证失败 | 检查失败原因，可能需要人工干预 |
+| `SETUP_DIGEST_MISMATCH` | setup 事实或答案已漂移 | dry-run 后 README/package/manifest/remote/answers 发生变化，或确认摘要错误 | 重新运行 setup dry-run、审阅并确认新摘要 |
+| `CONFIG_EXISTS` | setup 目标配置已经存在 | 写入模式试图创建已有 `.release-skill/project.yaml` | 不覆盖；运行 assess 并人工增量编辑 |
 
 ---
 
@@ -86,6 +88,8 @@
 | `stdout` | 标准输出引用（脱敏后存储，见第 4 节） |
 | `stderr` | 标准错误引用（脱敏后存储，见第 4 节） |
 
+验证 gate 不保存原始 stdout/stderr；证据仅记录命令数组、相对 cwd、时间、exit code、字节数、SHA-256 摘要和结构化裁决，避免把项目命令输出中的凭证复制进证据。
+
 ---
 
 ## 4. 脱敏规则