peaks-loop 4.1.19 → 4.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.19"
4
+ "version": "4.1.20"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.1.19",
10
+ "version": "4.1.20",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,135 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.20 — 2026-10-25(从 4.1.18 起装不上的根包,修好了)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
6
+ 没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
7
+ 改的是**根包自己的打包白名单**(§1–§2)、**消费者能看到的说法**(§3–§4)与**版本号本身**(§5)。
8
+
9
+ **一句话:`npm i -g peaks-loop` 从 4.1.18 起就是装不上的。这一版把它修好了。**
10
+
11
+ ### 1. 缺陷:白名单少了一行,于是整个安装死在 postinstall
12
+
13
+ 根包的 `package.json#files` 是**白名单** —— 只有被它点名的文件才会进 tarball。
14
+ `scripts/install-skills-bundles.mjs`(**在包里**)import 了 `./canonical-store-report.mjs`,
15
+ 而后者**不在白名单里**,于是 npm 发出去的是**一个没有同伙的 import 方**。
16
+
17
+ Node 的 ESM 加载器在跑任何代码之前就要把整张模块图解析完,所以这不是"少了个功能",
18
+ 是**图连不上**,安装死在 `postinstall`,CLI 根本轮不到上场:
19
+
20
+ ```
21
+ npm error Error [ERR_MODULE_NOT_FOUND]: Cannot find module
22
+ '.../node_modules/peaks-loop/scripts/canonical-store-report.mjs'
23
+ imported from .../node_modules/peaks-loop/scripts/install-skills-bundles.mjs
24
+ ```
25
+
26
+ **根因提交**是 `12c71e55`("fix(gates): a surface must not say what the code does not do")。
27
+ 那一个提交在 `scripts/` 下**新增了 3 个** canonical-store 脚本(`canonical-store-fs.mjs`、
28
+ `canonical-store-marker.mjs`、`canonical-store-report.mjs`),给 importer 接上了其中的**第三个**,
29
+ 而白名单**只加了那 3 个里的 2 个** —— 漏掉的正是 `-report`。该提交落在 `v4.1.17` 与 `v4.1.18`
30
+ 之间(`git merge-base --is-ancestor` 实测:在 `v4.1.18`/`v4.1.19` 之内,在 `v4.1.16`/`v4.1.17` 之外)。
31
+
32
+ ### 2. 实测证据(每个数字都来自本次实测)
33
+
34
+ **两个互相独立的方法**,同一个结论:
35
+
36
+ | 方法 | 4.1.17 | 4.1.18 | 4.1.19 |
37
+ |---|---|---|---|
38
+ | **真实 `npm install`**(隔离 prefix + 隔离 HOME) | **exit 0**,`added 127 packages in 10s` | **exit 1**,`ERR_MODULE_NOT_FOUND` | **exit 1**,`ERR_MODULE_NOT_FOUND` |
39
+ | **静态解析已发布 tarball**(`scripts/*.mjs` 数 / 本地相对 import 数 / **未命中**的目标数) | 16 / 24 / **0** | 18 / 27 / **1** | 18 / 27 / **1** |
40
+
41
+ 那个"**1**"在 4.1.18 与 4.1.19 里是**同一个**目标:`install-skills-bundles.mjs -> ./canonical-store-report.mjs`。
42
+ **4.1.19 tarball 里所有已发布脚本的本地相对 import 全被枚举过一遍,未命中的只有这一个** ——
43
+ 其余没进包的 `scripts/*.mjs` 都是本就不该进包的 dev / build / 测试脚本。
44
+
45
+ **不是 4.1.19 那一批引入的**:`v4.1.18` 与 `v4.1.19` 之间,`package.json#files` 的脚本条目
46
+ **增 0 减 0**,importer 的 blob 哈希**完全相同**(`05e80b3da11df0fee5f870fa3285a0fe153d0ff3`)。
47
+ 4.1.19 是**继承**了这个缺陷,不是**造成**了它。
48
+
49
+ **修好之后的实测**(不只是"打包内容看着对",是**真的装得上、跑得起来**):
50
+
51
+ - 把修好的树 `pnpm pack` 出来的 tarball 里,`scripts/*.mjs` 共 **19** 个,
52
+ `scripts/canonical-store-report.mjs` **在包里**,已发布脚本的本地相对 import **未命中 0 个**。
53
+ - **真实安装**:把那个 tarball 装进一个隔离的 prefix(`HOME`、`PEAKS_CLAUDE_SKILLS_DIR`、
54
+ `PEAKS_CLAUDE_AGENTS_DIR` 全部指到临时目录),`npm install` **退出 0**
55
+ (`added 293 packages in 40s`),**没有** `ERR_MODULE_NOT_FOUND`,postinstall 跑完。
56
+ - **装完就能用**:装好的包里 `peaks --version` 打出 **4.1.20**(退出 0),
57
+ `peaks mut --help` 打出完整命令树(退出 0)。
58
+ - 说明一句方法上的诚实:这 4 个 workspace 子包在本次版本里是**新版本号**,registry 上**还没有**
59
+ (实测 `npm view peaks-loop-mut@0.1.74` → **404**),所以端到端安装里这 4 个内部依赖是用
60
+ **本树自己打出来的 tarball**(`file:` spec)解析的,其余依赖全部走 registry。
61
+ 这正是发布流程"先发子包、后发根包"之后的拓扑;**打包白名单这件事本身**由上面的 tarball
62
+ 内容测量直接回答。
63
+
64
+ ### 3. 修法:一行白名单 + 一个防回归守卫
65
+
66
+ **修法就是一行** —— 根 `package.json#files` 里加一条 `"scripts/canonical-store-report.mjs",`,
67
+ `files` 的其余部分**一字未动**。白名单**没有**被放宽成整个 `scripts/`:那些 dev / build / 测试
68
+ 脚本是**故意**不进包的,放宽会把它们一起发出去。
69
+
70
+ **现在有了防回归守卫**:`tests/unit/release/packaging-shipped-scripts-import-guard.test.ts`
71
+ (**13** 个用例)。它**静态**地读根 manifest 的白名单,取出 `scripts/*.mjs` 条目作为**已发布脚本集**,
72
+ 解析每个已发布脚本的本地相对 import,断言**每个被 import 的目标也在已发布集里**。
73
+ **不联网、不查 registry、不做真实 `npm install`**。
74
+
75
+ 它守的是"**已发布脚本之间的**本地相对 import",**不会**要求 dev / build / 测试脚本进包。
76
+ 而且它被证明**真的会红**:临时把那一行从 `files` 里去掉 → 守卫 **exit 1**(`4 failed | 9 passed (13)`);
77
+ 逐字节还原(sha256 比对一致)→ 再跑 → **exit 0**(`13 passed (13)`)。**只看到绿不算验证过。**
78
+
79
+ 守卫在修好的树上的数字:**已发布脚本条目 19 个**,**检查的本地相对 import 27 个**,**未命中 0 个**。
80
+
81
+ ### 4. 顺手拆掉的一颗雷:`main` 指向了不在白名单里的文件
82
+
83
+ 工作树里根 `package.json` 带着 4 处**与本次缺陷无关**的改动(`repository.url`、`bin.peaks`,
84
+ 以及新增的 `main`、`directories`)。其中 **`main: "stryker.conf.js"`** 是一颗雷:
85
+ `stryker.conf.js` **不在 `files` 白名单里**,所以它**不会**进 tarball ——
86
+ 而 `main` 正是消费者 `import 'peaks-loop'` 解析到的入口。
87
+ 留着它,就等于**修好一个"装得上"的包,再塞一个"装上了但主入口用不了"的坑**。
88
+ 这 4 处已全部**还原成 `HEAD` 的原值**(`main` 与 `directories` 直接删掉)。
89
+
90
+ **成因是查出来的,不是猜的**:`npm pkg fix` 会把 `repository.url` 归一化成 `git+https://` 形式、
91
+ 把 `bin` 的 `./` 前缀去掉;`npm pkg set` 会写入 `main` 与 `directories`。
92
+ 而**本次用的版本锁步脚本不会**(实测:跑一次 `scripts/bump-version.mjs`,这 4 个字段
93
+ **0 个**被改动)。
94
+
95
+ ### 5. 版本号与发布含义
96
+
97
+ - 根包 `peaks-loop` **4.1.19 → 4.1.20**。`packages/` 下**实际只有 4 个**可发布 workspace 包,
98
+ 由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
99
+
100
+ | 包 | 改前 | 改后 |
101
+ | ----------------------------- | ------- | ---------- |
102
+ | `peaks-loop`(根) | 4.1.19 | **4.1.20** |
103
+ | `peaks-loop-mut` | 0.1.73 | **0.1.74** |
104
+ | `peaks-loop-shared` | 0.0.108 | 0.0.109 |
105
+ | `peaks-loop-shared-channel` | 0.0.76 | 0.0.77 |
106
+ | `peaks-loop-internal-runtime` | 0.0.59 | 0.0.60 |
107
+
108
+ - 两个**受版本控制**的版本戳同步为 4.1.20:`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION`
109
+ 与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。
110
+ - **版本字段一个都没手改**:全部由 `scripts/bump-version.mjs --to 4.1.20` 与 `scripts/sync-version.mjs`
111
+ 产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**;根 manifest 相对 `HEAD`
112
+ 只多两处 —— `version` 与 `files` 里的那一行。
113
+ - **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.20` + push,由发布流程发包。
114
+ **本次不打 tag、不发布、不提交。**
115
+
116
+ ### 6. 验证
117
+
118
+ - `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(`RUNTIME_VERSION=4.1.20`)。
119
+ - `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
120
+ sha256 前后同为 `7f60e065a8df3a63d7b03a2fc8f91db9628362387997fc77655c8c75ef46cc72`,
121
+ `git diff pnpm-lock.yaml` 为**空**。workspace 包在锁文件里是 `link:` 引用(**不记版本号**),
122
+ 所以版本号变动**不需要**动锁文件。
123
+ - 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
124
+ - 新守卫 `tests/unit/release/packaging-shipaged-scripts-import-guard.test.ts`:
125
+ **13 passed (13)**;去掉那一行白名单则 **4 failed | 9 passed (13)**,逐字节还原后回到全绿。
126
+ - **端到端**:修好的树 `pnpm pack` → 隔离 prefix 里 `npm install` **退出 0**
127
+ (`added 293 packages in 40s`)、**无** `ERR_MODULE_NOT_FOUND`;装好的包里
128
+ `peaks --version` 打出 **4.1.20**,`peaks mut --help` 退出 **0**。
129
+ - `.claude-plugin/marketplace.json` 由 `npm run plugin:manifest` 重生成,**跑两次逐字节相同**。
130
+ - `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
131
+ `eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对本次改动的文件 **0 findings**。
132
+
3
133
  ## 4.1.19 — 2026-10-24(`peaks mut` 在真实用户机器上**真的能跑**)
4
134
 
5
135
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.19",
3
+ "version": "4.1.20",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -87,6 +87,7 @@
87
87
  "scripts/canonical-store-marker.mjs",
88
88
  "scripts/canonical-store-link.mjs",
89
89
  "scripts/canonical-store-prune.mjs",
90
+ "scripts/canonical-store-report.mjs",
90
91
  "scripts/watch.mjs",
91
92
  "scripts/watch-tree.mjs",
92
93
  "skills/**",
@@ -131,10 +132,10 @@
131
132
  "picomatch": "4.0.7",
132
133
  "yaml": "^2.9.1",
133
134
  "zod": "^4.6.7",
134
- "peaks-loop-internal-runtime": "0.0.59",
135
- "peaks-loop-shared": "0.0.108",
136
- "peaks-loop-shared-channel": "0.0.76",
137
- "peaks-loop-mut": "0.1.73"
135
+ "peaks-loop-internal-runtime": "0.0.60",
136
+ "peaks-loop-mut": "0.1.74",
137
+ "peaks-loop-shared": "0.0.109",
138
+ "peaks-loop-shared-channel": "0.0.77"
138
139
  },
139
140
  "devDependencies": {
140
141
  "@changesets/cli": "2.31.1",
@@ -0,0 +1,84 @@
1
+ #!/usr/bin/env node
2
+ //
3
+ // THE STORE'S OWN ROWS — the canonical store's entries that the package does NOT ship.
4
+ //
5
+ // WHY THIS MODULE EXISTS. The report the sync command shows used to be built from the
6
+ // PACKAGE's skill list alone: one row per skill peaks-loop ships. That is the
7
+ // package's slice of the store, not the store. A skill the USER put in the store —
8
+ // their own copy, with no sidecar, which peaks-loop never overwrites — was invisible
9
+ // in the report that claims to describe the store: the report said "0 unmanaged"
10
+ // while their skill sat there.
11
+ //
12
+ // The rows here close that gap. Every entry in the store that the package does not
13
+ // ship gets a row:
14
+ //
15
+ // - an entry with NO sidecar is the USER's own → `unmanaged`. It is never
16
+ // overwritten and never pruned, and the report says so.
17
+ // - an entry WITH our sidecar is ours, and this release does not ship it any more
18
+ // → `retired`. A real run removes it; a dry run says what it would remove.
19
+ //
20
+ // THE ROWS ARE ABOUT THE STORE, so the states are the store's: an entry this module
21
+ // reports is never `current` and never `stale` — those two belong to the package's
22
+ // own skills, which the install loop reports.
23
+ //
24
+ // THE ROOT MUST MATCH THE STORE THE COPIES LAND IN. That root is resolved by
25
+ // `resolveKindRoot` with NO `root` option, exactly as `ensureCanonicalCopy` resolves
26
+ // it, so the two always name the same directory.
27
+
28
+ import { existsSync, readdirSync } from 'node:fs';
29
+ import { join } from 'node:path';
30
+
31
+ import {
32
+ MANAGED_MARKER_SUFFIX,
33
+ isManagedEntry,
34
+ readManagedMarker,
35
+ resolveKindRoot
36
+ } from './canonical-store.mjs';
37
+
38
+ /** The scratch prefix the store's atomic writes use; never an asset name. */
39
+ const TEMP_PREFIX = '.peaks-tmp-';
40
+
41
+ /**
42
+ * Every store entry the package does not ship, as report rows.
43
+ *
44
+ * @param {{ kind: string, knownNames: readonly string[], dryRun?: boolean }} options
45
+ * @returns {Array<{ name: string, state: string, action: string, version: string | null, reason: string | null }>}
46
+ */
47
+ export function collectStoreOnlyEntries(options) {
48
+ const { kind, knownNames } = options;
49
+ const dryRun = options.dryRun === true;
50
+ // The SAME resolution `ensureCanonicalCopy` uses: no `root` option, so the
51
+ // canonical root is `$PEAKS_HOME` or `~/.peaks` — the store the copies land in.
52
+ const kindRoot = resolveKindRoot(kind, {});
53
+ if (!existsSync(kindRoot)) return [];
54
+
55
+ const known = new Set(knownNames);
56
+ const rows = [];
57
+ for (const name of readdirSync(kindRoot).sort()) {
58
+ // A sidecar is not an entry, and a scratch file is not an entry either.
59
+ if (name.endsWith(MANAGED_MARKER_SUFFIX)) continue;
60
+ if (name.startsWith(TEMP_PREFIX)) continue;
61
+ // The package's own skills already have a row: the install loop reported them.
62
+ if (known.has(name)) continue;
63
+
64
+ const entryPath = join(kindRoot, name);
65
+ if (!isManagedEntry(entryPath)) {
66
+ rows.push({
67
+ name,
68
+ state: 'unmanaged',
69
+ action: 'unmanaged',
70
+ version: null,
71
+ reason: null
72
+ });
73
+ continue;
74
+ }
75
+ rows.push({
76
+ name,
77
+ state: 'retired',
78
+ action: dryRun ? 'planned' : 'pruned',
79
+ version: readManagedMarker(entryPath)?.version ?? null,
80
+ reason: 'retired'
81
+ });
82
+ }
83
+ return rows;
84
+ }