release-skill 0.1.1 → 0.1.3

package/bin/release-skill.mjs

@@ -7,7 +7,7 @@ import { parseNodeMajor, meetsMinimum, computeReadinessStatus } from '../src/cor
 
 const execFile = promisify(execFileCb);
 
-const COMMANDS = new Set(['help', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'artifacts']);
+const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'artifacts']);
 
 /**
  * Check if a command is available and get its version.
@@ -113,6 +113,11 @@ async function performEnvironmentChecks() {
  */
 function getCapabilityMaturity() {
   return {
+    setup: {
+      available: true,
+      mode: 'read-only dry-run / confirmed create-once',
+      description: 'Discover first-use facts and create an absent config only after exact setupDigest confirmation',
+    },
     assess: {
       available: true,
       mode: 'read-only',
@@ -125,17 +130,17 @@ function getCapabilityMaturity() {
     },
     publish: {
       available: true,
-      mode: 'controlled production (sandbox-verified)',
+      mode: 'controlled production (protocol-tested; no OS/network sandbox)',
       description: 'Publishes frozen GitHub/npm artifacts and runs configured Claude/Codex consumer checkpoints with approval and exact digest confirmation',
     },
     reconcile: {
       available: true,
-      mode: 'evidence-based recovery (sandbox-verified)',
+      mode: 'evidence-based recovery (protocol-tested; no OS/network sandbox)',
       description: 'Reconcile PARTIAL runs, retry safe missing checkpoints, and stop for human decisions on conflicts',
     },
     verify: {
       available: true,
-      mode: 'fresh consumer verification (sandbox-verified)',
+      mode: 'fresh consumer verification (protocol-tested; no OS/network sandbox)',
       description: 'Recheck remote state, exact npm installation, CLI help, and configured Claude/Codex installs before VERIFIED',
     },
   };
@@ -149,6 +154,7 @@ Usage:
 
 Commands:
   help       Show this help message and exit
+  setup      Discover first-use configuration and gate candidates (dry-run by default)
   assess     Read-only assessment of project release readiness
   prepare    Freeze a release plan (release-skill output to .release-skill/; hooks may do remote ops)
   approve    Record local approval for a frozen release plan
@@ -166,12 +172,17 @@ Options:
   --confirm-production <digest> Confirm the exact production plan digest
   --output <path>  Override prepare/approve output path (non-production only)
   --run-dir <path> Override prepare run directory; production requires one direct child of .release-skill/runs
+  --answers <path> Human-reviewed setup answers JSON
+  --write          Create an absent project.yaml during setup; never overwrites
+  --confirm-setup <digest> Confirm exact setup facts and answers before create
+  --acknowledge-hook-side-effects Acknowledge unsandboxed legacy hook execution
+  --acknowledge-gate-side-effects Acknowledge unsandboxed local verification gate execution
   --json           Output results as JSON
   --version        Show version and exit
   -h, --help       Show this help message and exit
 
 Safety:
-  Safe default: help -> assess -> prepare --offline -> human review.
+  Safe default: help -> setup (when config is absent) -> assess -> prepare --offline -> human review.
   Production happy end: prepare --production -> approve -> publish -> verify.
   prepare copies current public files into a local snapshot; it does not rewrite source files.
   - Default mode is offline (release-skill pipeline does no remote writes)
@@ -185,6 +196,7 @@ Safety:
 
 First safe command:
   release-skill help --json    # Environment check (read-only)
+  release-skill setup --root <path> --json  # First-use discovery (read-only)
   release-skill assess --root <path> --offline --json  # Project assessment`);
 }
 
@@ -245,12 +257,13 @@ if (!command || command === 'help') {
       checks,
       capabilities,
       maturity: {
+        setup: 'read-only by default; create-once requires answers plus exact setupDigest confirmation',
         assess: 'read-only (default); --output writes local report',
-        prepare: 'offline local writes; requires --acknowledge-hook-side-effects when hooks are configured',
+        prepare: 'offline local writes; configured hooks/gates require their explicit side-effect acknowledgements',
         onlinePrepare: 'previous-public-baseline observation available; production mode freezes publish artifacts and fails closed on drift or unknown state',
-        publish: 'GitHub/npm plus configured Claude/Codex consumer checkpoints are sandbox-verified; approval and exact digest confirmation required',
-        reconcile: 'PARTIAL recovery sandbox-verified; remote conflicts require human intervention',
-        verify: 'fresh exact npm and Claude/Codex consumer installation checks are sandbox-verified; success reaches VERIFIED',
+        publish: 'GitHub/npm plus configured Claude/Codex consumer checkpoints are protocol-tested without an OS/network sandbox; approval and exact digest confirmation required',
+        reconcile: 'PARTIAL recovery is protocol-tested without an OS/network sandbox; remote conflicts require human intervention',
+        verify: 'fresh exact npm and Claude/Codex consumer installation checks are protocol-tested without an OS/network sandbox; configured consumer processes require explicit acknowledgement; success reaches VERIFIED',
       },
       recommendations: [],
     };
@@ -309,6 +322,45 @@ if (!COMMANDS.has(command)) {
   process.exit(2);
 }
 
+// --- Setup command routing ---
+if (command === 'setup') {
+  const { setupProject } = await import('../src/commands/setup.mjs');
+  const rootIdx = args.indexOf('--root');
+  const rawRoot = rootIdx !== -1 && args[rootIdx + 1] ? args[rootIdx + 1] : process.cwd();
+  const root = resolve(rawRoot);
+  const answersIdx = args.indexOf('--answers');
+  const answersPath = answersIdx !== -1 && args[answersIdx + 1] ? args[answersIdx + 1] : undefined;
+  const confirmationIdx = args.indexOf('--confirm-setup');
+  const confirmSetup = confirmationIdx !== -1 && args[confirmationIdx + 1]
+    ? args[confirmationIdx + 1]
+    : undefined;
+  const write = args.includes('--write');
+  try {
+    const report = await setupProject({ root, answersPath, write, confirmSetup });
+    if (hasJson) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(`Setup status: ${report.status}`);
+      if (report.setupDigest) console.log(`Setup digest: ${report.setupDigest}`);
+      if (report.configPath) console.log(`Config: ${report.configPath}`);
+      if (report.next) console.log(`Next: ${report.next}`);
+    }
+    process.exit(['READY_TO_WRITE', 'CONFIG_CREATED', 'ALREADY_CONFIGURED'].includes(report.status) ? 0 : 2);
+  } catch (err) {
+    if (hasJson) {
+      console.log(JSON.stringify({
+        error: err.code ?? 'UNKNOWN_ERROR',
+        message: err.message,
+        details: err.details ?? {},
+        exitCode: err.exitCode ?? 1,
+      }));
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exit(err.exitCode ?? 1);
+  }
+}
+
 // --- Assess command routing ---
 if (command === 'assess') {
   const { assessProject } = await import('../src/commands/assess.mjs');
@@ -366,6 +418,7 @@ if (command === 'prepare') {
   }
 
   const hooksAuthorized = args.includes('--acknowledge-hook-side-effects');
+  const verificationGatesAuthorized = args.includes('--acknowledge-gate-side-effects');
   const production = args.includes('--production');
   const outputIdx = args.indexOf('--output');
   const output = outputIdx !== -1 && args[outputIdx + 1] ? resolve(args[outputIdx + 1]) : undefined;
@@ -378,6 +431,7 @@ if (command === 'prepare') {
       version: targetVersion,
       offline,
       hooksAuthorized,
+      verificationGatesAuthorized,
       production,
       output,
       runDir,
@@ -563,6 +617,7 @@ if (command === 'verify') {
   const planPath = planIdx !== -1 && args[planIdx + 1] ? resolve(args[planIdx + 1]) : undefined;
   const runIdx = args.indexOf('--run');
   const runPath = runIdx !== -1 && args[runIdx + 1] ? resolve(args[runIdx + 1]) : undefined;
+  const verificationGatesAuthorized = args.includes('--acknowledge-gate-side-effects');
 
   if (!planPath || !runPath) {
     const msg = 'verify requires --plan <path> and --run <path>';
@@ -587,6 +642,7 @@ if (command === 'verify') {
       sourceRunPath: runPath,
       adapterRegistry: registry,
       root,
+      verificationGatesAuthorized,
     });
 
     if (hasJson) {

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.3",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "repository": {
     "type": "git",
@@ -33,6 +33,7 @@
     "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
     "INSTALL.md",
+    "INSTALL.zh-CN.md",
     "LICENSE",
     "NOTICE",
     "SECURITY.md"
@@ -47,6 +48,7 @@
     "build:adapters": "node scripts/build-adapters.mjs",
     "build:adapters:check": "node scripts/build-adapters.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')\""
   },

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>
@@ -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 remote、旧版 `public-release.json` 和脚本，输出候选、逐单元前序公开基线状态与 `setupDigest`。旧配置只作为不可信迁移事实，其中的 `snapshotCommands` 只成为未授权 gate 候选；它不会把脚本存在解释成用户选择，也不会读取 README 中的自然语言作为命令。
+
+写入要求人工提供完整 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. 脱敏规则