peaks-loop 4.1.21 → 4.1.22

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.21"
4
+ "version": "4.1.22"
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.21",
10
+ "version": "4.1.22",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
@@ -61,10 +61,7 @@
61
61
  "mcpServers": {
62
62
  "peaks": {
63
63
  "command": "peaks",
64
- "args": [
65
- "mcp",
66
- "serve"
67
- ]
64
+ "args": ["mcp", "serve"]
68
65
  }
69
66
  },
70
67
  "skills": [
package/CHANGELOG.md CHANGED
@@ -1,5 +1,114 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何运行时语义、
6
+ **没有**动 mutation 阈值、**没有**碰发布流程;三个代码切片各自只加守卫、**零清单改动**,本切片只做
7
+ **版本锁步 + 生成清单重生成 + 这段 CHANGELOG**。
8
+
9
+ **一句话:`peaks mut` 指向一个**不存在**的 `--test-files` 时,`mut mutants` 过去会**静默回退**到默认发现,
10
+ 为一个从未存在过的文件报出**满分 kill rate**(exit 0)—— 而最初的记录只测了 `run` 与 `asserts`、**漏了
11
+ `mutants`**;这一版三个子命令统一 **exit 1 + 具名码 `MUT_TEST_FILE_NOT_FOUND`**。**
12
+
13
+ ### 1. 缺陷:`peaks mut` 缺失 `--test-files` 路径时的静默回退(三个子命令这一版统一堵上)
14
+
15
+ 同一夹具、同一台机器上的**前后两侧实测**(改前取自 `HEAD` 的隔离树,改后取自本仓库的工作树):
16
+
17
+ | 子命令 | 改前 | 改后 |
18
+ |---|---|---|
19
+ | `mut mutants` | **exit 0、写出了报告、killRate 1、mutantsTotal 2** | **exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告** |
20
+ | `mut run` | exit 1 `MUT_FAILED`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
21
+ | `mut asserts` | exit 1 `UNHANDLED_ERROR`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
22
+
23
+ **"静默回退"不是推测,是可比对的 digest。** 改前 `mut mutants` + 缺失文件写出的报告,digest 与
24
+ `mut mutants` + **一个能用的 glob** 写出的报告**完全相同**(两者都是 `339e74cc…`)—— 缺失的路径被
25
+ Stryker 的文件匹配丢掉,vitest runner 跑了项目自己的默认发现,然后为一个**从未存在过的文件**报出了满分。
26
+ 改后同一个 glob 仍然 exit 0、digest 仍是 `339e74cc…`(能用的 glob 保持能用),而缺失文件一律 exit 1。
27
+
28
+ 改后三个子命令的消息**逐字节相同**,且**只给相对 `--project` 的路径**,并附近邻候选:
29
+
30
+ ```
31
+ Test file not found: tests/does-not-exist.test.ts
32
+ Near-miss candidates:
33
+ - tests/add.test.ts
34
+ ```
35
+
36
+ **快乐路径没变**:有效测试文件下 `mut run` 的报告 digest 改前改后**都是 `96595ff6…`**(`killRate` 1、
37
+ `mutantsTotal` 2)。守卫 `tests/unit/cli/mut-test-file-not-found.test.ts` **15 个用例全绿**。
38
+
39
+ **这一段要更正的是一条"不可复现"的判断。** 最初的记录写的是"缺失 `--test-files` 路径静默回退默认发现、
40
+ 可能报出完美 kill rate"**不可复现** —— 那条判断**只测了 `run` 与 `asserts`**,**漏了 `mutants`**;在
41
+ `mutants` 上它**确实复现**(exit 0 + 满分 kill rate)。本批的三个子命令现在统一成同一个具名码。
42
+
43
+ ### 2. 生成的插件清单:`prettier --check` 从 exit 1 变成 exit 0(本次 bump 没有把形状缺陷带回来)
44
+
45
+ 清单是**受版本控制的生成产物**(`npm run plugin:manifest`),渲染器过去把**每个**数组都展开,
46
+ 所以清单**不是** prettier-clean 的。实测(用仓库自己的 prettier 与仓库自己的 prettier 配置):
47
+
48
+ | | 改前(`HEAD` 的渲染) | 改后(本切片 bump 之后的渲染) |
49
+ |---|---|---|
50
+ | `prettier --check` | **exit 1(不是 prettier-clean)** | **exit 0** |
51
+ | 行数(按换行计数) | 200 | **197** |
52
+ | 行数(按 `split("\n").length`) | 201 | **198** |
53
+
54
+ 唯一的变化是 `"args": ["mcp", "serve"]`(4 行 → 1 行)。改前的清单经 prettier 规范化后的输出,
55
+ sha256 是 `849e6168…`,与**本切片 bump 之前**工作树里那份清单(切片 B 的渲染,版本 4.1.21)
56
+ **逐字节相同** —— 说明新的渲染器产出的正是 prettier 自己的形状。本切片 bump 之后的清单
57
+ sha256 是 `fd087f50…`,同样 prettier-clean。
58
+
59
+ **依赖集不变**:根 manifest 的 `dependencies`(12 项)与 `devDependencies`(19 项)与 bump 前**逐字段相同**
60
+ (本切片实测:五个 manifest 各自只有 `version` 一个键变了);`prettier` 仍在 `devDependencies`、
61
+ **不在** `dependencies`(实测 `prettier in dependencies: false`),发布包的运行时依赖集没有变化。
62
+
63
+ **版本戳在两处**:`metadata.version` 与 `plugins[0].version` 都读 `4.1.22`;连跑两次生成**逐字节相同**
64
+ (sha256 `fd087f50…`)。
65
+
66
+ ### 3. 包入口不变量(只加守卫,**零清单改动**)
67
+
68
+ 根包声明 **1** 个入口(`bin.peaks → ./bin/peaks.js`),`peaks-loop-mut` 声明 **2** 个
69
+ (`exports["."].types`、`exports["."].default`)。守卫 `tests/unit/release/package-entry-points-guard.test.ts`
70
+ **9 passed | 1 skipped**(构建产物在 → 磁盘检查**跑起来**:2 checked、0 skipped)。守卫钉住三条不变量:
71
+ 声明的入口必须落在该包自己的 `files` 白名单里;`main` 与 `exports["."].default` 若同时声明必须一致;
72
+ 根包**不得**把副作用型 CLI 模块声明成库入口。
73
+
74
+ ### 4. 两条必须说准的事(一条"不是缺陷",一条"更正旧判断")
75
+
76
+ **(1)"包缺 `main`"不是缺陷 —— 它不是这次修的东西。** `peaks-loop-mut` 的主入口**已经**由 `exports["."]` 表达
77
+ (`exports["."].default → ./dist/index.js`)。实测(本机 Node v24.12.0):
78
+
79
+ - 一个同时声明 `main` 与 `exports` 的包,被 import 时加载的是 **`exports`** 那个目标(输出 `LOADED:EXPORTS`)
80
+ —— Node 解析 `exports` 优先于 `main`,`main` 被忽略;
81
+ - **`require()` 一个纯 ESM 包在 Node v24.12.0 上是成功的**(实测 `REQUIRE_OK`;`ERR_REQUIRE_ESM`
82
+ 只对 Node < 22.12 成立)。所以诚实的理由是**"冗余且会误导"**,而**不是**"无法 require";
83
+ - 根包则**绝不能**加 `main`/`exports`:`dist/cli/index.js` 在**模块顶层**就
84
+ `program.parseAsync(process.argv)`(`src/cli/index.ts:61`),实测**import 它就会把 CLI 跑起来**
85
+ —— 导入过程中就打出了 CLI 的帮助横幅。
86
+
87
+ **(2)"静默回退不可复现"这条旧判断本身不成立 —— 这一版是真的堵上了。** 它在 `mut mutants` 上**确实复现**
88
+ (exit 0 + 满分 kill rate),缺的只是那次测量里的**第三个子命令**。所以这里不是"没有缺陷",而是
89
+ "缺陷是真的、这一版三个子命令统一堵上了"。
90
+
91
+ ### 5. 版本号本身
92
+
93
+ | 包 | 从 | 到 |
94
+ |---|---|---|
95
+ | `peaks-loop` | 4.1.21 | **4.1.22** |
96
+ | `peaks-loop-shared` | 0.0.110 | 0.0.111 |
97
+ | `peaks-loop-mut` | 0.1.75 | 0.1.76 |
98
+ | `peaks-loop-shared-channel` | 0.0.78 | 0.0.79 |
99
+ | `peaks-loop-internal-runtime` | 0.0.61 | 0.0.62 |
100
+
101
+ 版本号由 `scripts/bump-version.mjs` 产生(不是手打的):根 `4.1.21 → 4.1.22`,四个 workspace 包在同一次
102
+ lockstep 里各 +1,五个 manifest **各自只有 `version` 一个键变了**;`scripts/sync-version.mjs` 把
103
+ `CLI_VERSION` 与 `RUNTIME_VERSION` 写成 `4.1.22`,`node scripts/verify-version-parity.mjs runtime-src`
104
+ **exit 0**。
105
+
106
+ **发布顺序(发版前必须知道)**:`pnpm pack` 会把根包 `workspace:*` 依赖改写成**精确 semver pin**,
107
+ 所以 `peaks-loop@4.1.22` 打包后的 manifest 依赖的是 `peaks-loop-mut@0.1.76`、
108
+ `peaks-loop-shared@0.0.111`、`peaks-loop-shared-channel@0.0.79`、`peaks-loop-internal-runtime@0.0.62`
109
+ (实测:从 tarball 里读出的 `package/package.json`)。这四个版本**在 registry 上都不存在**(实测 `E404`),
110
+ 所以**这四个包必须先发布**,`peaks-loop@4.1.22` 才能被消费者装上;在它们发布之前,根包是不可安装的。
111
+
3
112
  ## 4.1.21 — 2026-10-25(把"返工循环"数对,把"没测过"说出来)
4
113
 
5
114
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改 fail-open 策略、
@@ -13,7 +13,8 @@
13
13
  * toolchain must surface a MACHINE-READABLE error code (for example
14
14
  * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
15
  * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
- * "Cannot find package".
16
+ * "Cannot find package". The same rule now covers a missing `--test-files`
17
+ * path (`MUT_TEST_FILE_NOT_FOUND`).
17
18
  */
18
19
  import { Command } from 'commander';
19
20
  import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
@@ -75,16 +76,15 @@ export declare function mutErrorCode(err: unknown): string;
75
76
  /** The human-readable half of the envelope. */
76
77
  export declare function mutErrorMessage(err: unknown): string;
77
78
  /**
78
- * Emit the failure envelope on stderr and set a non-zero exit code.
79
- * stdout stays reserved for the `--json` payload (R6), so the envelope
80
- * goes to stderr exactly like every other peaks CLI error.
79
+ * Emit the failure envelope on stderr and set a non-zero exit code. Its
80
+ * `data` field carries the machine-readable detail — where an ABSOLUTE path
81
+ * belongs; stdout stays reserved for the `--json` payload (R6).
81
82
  */
82
83
  export declare function emitMutError(io: ProgramIO, err: unknown): void;
83
84
  /**
84
85
  * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
85
86
  * report). One-axis: --session-id required.
86
- */
87
- export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
87
+ */ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
88
88
  /**
89
89
  * `peaks mut mutants` — Stryker only; writes a stub-assertions
90
90
  * mut-report.json. One-axis: --session-id required.
@@ -13,10 +13,11 @@
13
13
  * toolchain must surface a MACHINE-READABLE error code (for example
14
14
  * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
15
  * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
- * "Cannot find package".
16
+ * "Cannot find package". The same rule now covers a missing `--test-files`
17
+ * path (`MUT_TEST_FILE_NOT_FOUND`).
17
18
  */
18
19
  import { Command } from 'commander';
19
- import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
+ import { assertTestFilesUsable, buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
21
  import { printErrorEnvelope } from '../cli-helpers.js';
21
22
  /**
22
23
  * Fallback code for a mutation failure that carries no named code of its
@@ -98,18 +99,27 @@ export function mutErrorMessage(err) {
98
99
  return err instanceof Error ? err.message : String(err);
99
100
  }
100
101
  /**
101
- * Emit the failure envelope on stderr and set a non-zero exit code.
102
- * stdout stays reserved for the `--json` payload (R6), so the envelope
103
- * goes to stderr exactly like every other peaks CLI error.
102
+ * Emit the failure envelope on stderr and set a non-zero exit code. Its
103
+ * `data` field carries the machine-readable detail — where an ABSOLUTE path
104
+ * belongs; stdout stays reserved for the `--json` payload (R6).
104
105
  */
105
106
  export function emitMutError(io, err) {
106
- printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), {}, []);
107
+ const details = err?.details;
108
+ const data = details && typeof details === 'object' ? details : {};
109
+ printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), data, []);
110
+ }
111
+ /**
112
+ * Validate `--test-files` BEFORE any Stryker run, scan or report write: a
113
+ * missing path must fail with the named code, never reach the mutation
114
+ * engine. A PATTERN is accepted here — Stryker expands patterns.
115
+ */
116
+ function assertMutTestFiles(a) {
117
+ assertTestFilesUsable({ project: a.project, testFiles: a.testFiles, allowPatterns: true });
107
118
  }
108
119
  /**
109
120
  * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
110
121
  * report). One-axis: --session-id required.
111
- */
112
- export function buildMutRunCommand(invokeStryker, io) {
122
+ */ export function buildMutRunCommand(invokeStryker, io) {
113
123
  return new Command('run')
114
124
  .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
115
125
  .requiredOption('--project <path>', 'project root')
@@ -121,6 +131,7 @@ export function buildMutRunCommand(invokeStryker, io) {
121
131
  .option('--json', 'machine-readable output', false)
122
132
  .action(async (a) => {
123
133
  try {
134
+ assertMutTestFiles(a);
124
135
  const { mutation } = await runMutation({
125
136
  project: a.project,
126
137
  testFiles: a.testFiles,
@@ -172,6 +183,7 @@ export function buildMutMutantsCommand(invokeStryker, io) {
172
183
  .option('--json', 'machine-readable output', false)
173
184
  .action(async (a) => {
174
185
  try {
186
+ assertMutTestFiles(a);
175
187
  const { mutation } = await runMutation({
176
188
  project: a.project,
177
189
  testFiles: a.testFiles,
@@ -213,24 +225,30 @@ export function buildMutAssertsCommand(io) {
213
225
  .requiredOption('--out <path>', 'output path for mut-report.json')
214
226
  .option('--json', 'machine-readable output', false)
215
227
  .action(async (a) => {
216
- const assertions = await scanAssertions({
217
- project: a.project,
218
- testFiles: a.testFiles
219
- });
220
- const report = await buildMutReport({
221
- inputSig: a.inputSig,
222
- out: a.out,
223
- mutation: emptyMutation(),
224
- assertions
225
- });
226
- emitSummary(io, a.json, {
227
- ok: true,
228
- sha256: report.sha256,
229
- passed: report.thresholds.passed,
230
- path: a.out
231
- });
232
- if (!report.thresholds.passed) {
233
- process.exitCode = 1;
228
+ try {
229
+ assertMutTestFiles(a);
230
+ const assertions = await scanAssertions({
231
+ project: a.project,
232
+ testFiles: a.testFiles
233
+ });
234
+ const report = await buildMutReport({
235
+ inputSig: a.inputSig,
236
+ out: a.out,
237
+ mutation: emptyMutation(),
238
+ assertions
239
+ });
240
+ emitSummary(io, a.json, {
241
+ ok: true,
242
+ sha256: report.sha256,
243
+ passed: report.thresholds.passed,
244
+ path: a.out
245
+ });
246
+ if (!report.thresholds.passed) {
247
+ process.exitCode = 1;
248
+ }
249
+ }
250
+ catch (err) {
251
+ emitMutError(io, err);
234
252
  }
235
253
  });
236
254
  }
@@ -0,0 +1,20 @@
1
+ /** The two knobs of prettier's JSON layout a render can depend on. */
2
+ export interface JsonLayoutOptions {
3
+ /** prettier's `printWidth` — the column budget one printed line may use. */
4
+ readonly printWidth: number;
5
+ /** prettier's `tabWidth` — how many spaces one indentation level is. */
6
+ readonly tabWidth: number;
7
+ }
8
+ /**
9
+ * prettier's own defaults, used when the repository's config says nothing about a
10
+ * knob. They are prettier's, not this repository's: the config file is the one
11
+ * source of truth for the numbers, and a second copy of them here would be a
12
+ * second decision.
13
+ */
14
+ export declare const DEFAULT_JSON_LAYOUT: JsonLayoutOptions;
15
+ /**
16
+ * Render a JSON value in the layout prettier produces for JSON, newline-terminated.
17
+ *
18
+ * The output is a prettier FIXED POINT: formatting it again returns it unchanged.
19
+ */
20
+ export declare function renderJsonDocument(value: unknown, options?: JsonLayoutOptions): string;
@@ -0,0 +1,195 @@
1
+ // src/services/distribution/json-layout.ts
2
+ //
3
+ // WHY THIS FILE EXISTS. `.claude-plugin/marketplace.json` is a GENERATED artifact
4
+ // and it SHIPS (the root `package.json#files` allowlist names `.claude-plugin/**`),
5
+ // so its bytes are a published surface. The renderer used to emit it with
6
+ // `JSON.stringify(manifest, null, 2)`, which expands EVERY array regardless of
7
+ // width — so the artifact was not prettier-clean, and `npm run format:check` could
8
+ // not see it: that script covers `src|tests|packages|scripts` × `ts,mts,mjs,js` and
9
+ // no `.json` at all. Nothing asserted the property until a guard did.
10
+ //
11
+ // THE RULE IS PRETTIER'S, AND IT IS REPLICATED HERE WITHOUT PRETTIER. `prettier`
12
+ // is a devDependency. The root `package.json#files` allowlist also names
13
+ // `dist/**/*.js`, so `dist/services/distribution/plugin-manifest.js` — and this
14
+ // module beside it — SHIP to consumers. A static `import 'prettier'` from any
15
+ // module under `src/**` would put an undeclared dependency into every consumer
16
+ // install and fail with `ERR_MODULE_NOT_FOUND` — the same defect class as the
17
+ // 4.1.18→4.1.20 packaging break. A lazy `await import('prettier')` would not fail
18
+ // at import time, but it would still make the SHIPPED renderer's output depend on a
19
+ // package the published manifest does not declare. So the shape is computed here,
20
+ // with ZERO dependencies, and the shape does not drift when prettier is upgraded.
21
+ //
22
+ // THE TWO RULES, AS PRETTIER APPLIES THEM TO JSON.
23
+ //
24
+ // 1. OBJECTS. prettier keeps an object expanded when the source has a newline
25
+ // between `{` and its first key, and collapses it otherwise. This renderer
26
+ // always emits the newline, so every object is expanded — and prettier, reading
27
+ // that newline, keeps it expanded. The render is therefore a FIXED POINT of
28
+ // prettier, which is the property the guard asserts.
29
+ //
30
+ // 2. ARRAYS. prettier prints an array on ONE line when it fits the print width,
31
+ // and breaks it one element per line when it does not. On top of that it has
32
+ // one forced-break rule: an array with more than one element where EVERY
33
+ // element is an object or an array, all of the same kind, and each holding
34
+ // more than one member, breaks even when it would fit.
35
+ //
36
+ // The width is measured the way prettier measures it: the printed line, from its
37
+ // indentation through the value and the separator that follows it, must fit inside
38
+ // `printWidth`. A value therefore knows the column it starts at, the text already
39
+ // on its line, and the text that follows it before the next break.
40
+ //
41
+ // MEASURED, NOT ASSUMED. This rule was differential-tested against the installed
42
+ // prettier over 3000 generated manifests: the render equalled
43
+ // `prettier.format(JSON.stringify(value, null, 2))` in 3000 of 3000 cases, and
44
+ // `prettier.format(render(value)) === render(value)` in 3000 of 3000. The guard
45
+ // that keeps the property is
46
+ // `tests/unit/services/distribution/plugin-manifest-prettier-clean.test.ts`.
47
+ /**
48
+ * prettier's own defaults, used when the repository's config says nothing about a
49
+ * knob. They are prettier's, not this repository's: the config file is the one
50
+ * source of truth for the numbers, and a second copy of them here would be a
51
+ * second decision.
52
+ */
53
+ export const DEFAULT_JSON_LAYOUT = { printWidth: 80, tabWidth: 2 };
54
+ function isPrimitive(value) {
55
+ return value === null || typeof value !== 'object';
56
+ }
57
+ function isJsonArray(value) {
58
+ return Array.isArray(value);
59
+ }
60
+ function isJsonObject(value) {
61
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
62
+ }
63
+ /** One JSON literal. `undefined` is not a JSON value, so it reads as `null`. */
64
+ function literal(value) {
65
+ return JSON.stringify(value) ?? 'null';
66
+ }
67
+ /**
68
+ * prettier's forced-break rule for arrays. An array breaks even when it would fit
69
+ * when it holds more than one element, every element is an object or an array, all
70
+ * of them are the same kind, and each one holds more than one member.
71
+ */
72
+ function forcesBreak(elements) {
73
+ if (elements.length <= 1)
74
+ return false;
75
+ return elements.every((element, index, all) => {
76
+ const next = all[index + 1];
77
+ if (isJsonArray(element)) {
78
+ if (next !== undefined && !isJsonArray(next))
79
+ return false;
80
+ return element.length > 1;
81
+ }
82
+ if (isJsonObject(element)) {
83
+ if (next !== undefined && !isJsonObject(next))
84
+ return false;
85
+ return Object.keys(element).length > 1;
86
+ }
87
+ return false;
88
+ });
89
+ }
90
+ /**
91
+ * A non-empty object anywhere below this value forces every enclosing array to
92
+ * break: this renderer always expands an object, and an expanded member breaks the
93
+ * group that holds it.
94
+ */
95
+ function containsObject(value) {
96
+ if (isPrimitive(value))
97
+ return false;
98
+ if (isJsonArray(value))
99
+ return value.some(containsObject);
100
+ if (isJsonObject(value))
101
+ return Object.keys(value).length > 0;
102
+ return false;
103
+ }
104
+ /** A forced-break array anywhere below this value breaks every enclosing array. */
105
+ function containsForcedBreak(value) {
106
+ if (isPrimitive(value))
107
+ return false;
108
+ if (isJsonArray(value))
109
+ return forcesBreak(value) || value.some(containsForcedBreak);
110
+ return false;
111
+ }
112
+ /** The one-line rendering of a value — the width an enclosing array measures. */
113
+ function flatText(value) {
114
+ if (isPrimitive(value))
115
+ return literal(value);
116
+ if (isJsonArray(value))
117
+ return `[${value.map(flatText).join(', ')}]`;
118
+ if (!isJsonObject(value))
119
+ return 'null';
120
+ const keys = Object.keys(value);
121
+ if (keys.length === 0)
122
+ return '{}';
123
+ const members = keys.map((key) => `${JSON.stringify(key)}: ${flatText(value[key])}`);
124
+ return `{ ${members.join(', ')} }`;
125
+ }
126
+ function renderValue(value, context) {
127
+ if (isPrimitive(value))
128
+ return literal(value);
129
+ if (isJsonArray(value))
130
+ return renderArray(value, context);
131
+ if (isJsonObject(value))
132
+ return renderObject(value, context);
133
+ return literal(value);
134
+ }
135
+ /** One array, either on one line or one element per line. */
136
+ function renderArray(elements, context) {
137
+ if (elements.length === 0)
138
+ return '[]';
139
+ const flat = `[${elements.map(flatText).join(', ')}]`;
140
+ const fits = context.indent + context.prefixWidth + flat.length + context.suffixWidth <=
141
+ context.options.printWidth;
142
+ const breakable = forcesBreak(elements) || containsObject(elements) || containsForcedBreak(elements);
143
+ if (fits && !breakable)
144
+ return flat;
145
+ const inner = context.indent + context.options.tabWidth;
146
+ const pad = ' '.repeat(inner);
147
+ const body = elements
148
+ .map((element, index) => {
149
+ const child = {
150
+ options: context.options,
151
+ indent: inner,
152
+ prefixWidth: 0,
153
+ suffixWidth: index === elements.length - 1 ? 0 : 1
154
+ };
155
+ return pad + renderValue(element, child);
156
+ })
157
+ .join(',\n');
158
+ return `[\n${body}\n${' '.repeat(context.indent)}]`;
159
+ }
160
+ /** One object, always expanded — the newline after `{` is what keeps it so. */
161
+ function renderObject(value, context) {
162
+ const keys = Object.keys(value);
163
+ if (keys.length === 0)
164
+ return '{}';
165
+ const inner = context.indent + context.options.tabWidth;
166
+ const pad = ' '.repeat(inner);
167
+ const body = keys
168
+ .map((key, index) => {
169
+ const keyText = JSON.stringify(key);
170
+ const child = {
171
+ options: context.options,
172
+ indent: inner,
173
+ // the `": "` that follows the key
174
+ prefixWidth: keyText.length + 2,
175
+ suffixWidth: index === keys.length - 1 ? 0 : 1
176
+ };
177
+ return `${pad}${keyText}: ${renderValue(value[key], child)}`;
178
+ })
179
+ .join(',\n');
180
+ return `{\n${body}\n${' '.repeat(context.indent)}}`;
181
+ }
182
+ /**
183
+ * Render a JSON value in the layout prettier produces for JSON, newline-terminated.
184
+ *
185
+ * The output is a prettier FIXED POINT: formatting it again returns it unchanged.
186
+ */
187
+ export function renderJsonDocument(value, options = DEFAULT_JSON_LAYOUT) {
188
+ const text = renderValue(value, {
189
+ options,
190
+ indent: 0,
191
+ prefixWidth: 0,
192
+ suffixWidth: 0
193
+ });
194
+ return `${text}\n`;
195
+ }
@@ -1,4 +1,5 @@
1
1
  import { type SkillMetadata } from '../skills/skill-registry.js';
2
+ import { type JsonLayoutOptions } from './json-layout.js';
2
3
  /** Where the generator writes, relative to the package root. */
3
4
  export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
4
5
  /**
@@ -20,6 +21,16 @@ interface PackageManifest {
20
21
  } | string;
21
22
  readonly license?: string;
22
23
  readonly keywords?: readonly string[];
24
+ /**
25
+ * The repository's own prettier config — the source of truth for the layout the
26
+ * artifact is rendered in. Read from the SAME package.json the plugin-level
27
+ * fields come from, so the render and the check that guards it cannot disagree
28
+ * about the width.
29
+ */
30
+ readonly prettier?: {
31
+ readonly printWidth?: number;
32
+ readonly tabWidth?: number;
33
+ };
23
34
  }
24
35
  /** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
25
36
  interface PluginSkillEntry {
@@ -78,8 +89,26 @@ export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readon
78
89
  * caller that must fail loudly on an unreadable SKILL.md can do so once.
79
90
  */
80
91
  export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
81
- /** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
82
- export declare function serializePluginManifest(manifest: GeneratedPluginManifest): string;
92
+ /**
93
+ * The layout the repository's own prettier config asks for, read from the ROOT
94
+ * package.json. Exported so the guard that checks the artifact resolves the layout
95
+ * the same way the renderer does — two resolutions would be two decisions.
96
+ */
97
+ export declare function repositoryJsonLayout(): JsonLayoutOptions;
98
+ /**
99
+ * The artifact's bytes, newline-terminated — the same serialization contract as the
100
+ * whitelist, in the layout prettier produces for JSON.
101
+ *
102
+ * `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
103
+ * regardless of width, so the committed artifact was not prettier-clean. The shape
104
+ * is now computed by `json-layout.ts`, which implements prettier's JSON rules with
105
+ * ZERO dependencies — `prettier` is a devDependency, and this module ships to
106
+ * consumers inside `dist/**`, so it must not depend on it.
107
+ *
108
+ * The default layout is the repository's own, read from the root `package.json`;
109
+ * a caller rendering for another root passes the layout it resolved there.
110
+ */
111
+ export declare function serializePluginManifest(manifest: GeneratedPluginManifest, options?: JsonLayoutOptions): string;
83
112
  /** Absolute path of the committed artifact for a package root. */
84
113
  export declare function pluginManifestPath(root?: string): string;
85
114
  /**
@@ -28,6 +28,7 @@ import { readFileSync } from 'node:fs';
28
28
  import { dirname, join, relative } from 'node:path';
29
29
  import { repoRoot } from 'peaks-loop-shared/paths';
30
30
  import { loadSkillRegistry } from '../skills/skill-registry.js';
31
+ import { DEFAULT_JSON_LAYOUT, renderJsonDocument } from './json-layout.js';
31
32
  /** Where the generator writes, relative to the package root. */
32
33
  export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
33
34
  /**
@@ -97,9 +98,43 @@ export function generatePluginManifest(manifest, skills) {
97
98
  ]
98
99
  };
99
100
  }
100
- /** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
101
- export function serializePluginManifest(manifest) {
102
- return `${JSON.stringify(manifest, null, 2)}\n`;
101
+ /**
102
+ * The layout the repository's own prettier config asks for.
103
+ *
104
+ * The config file is the ONE source of truth for `printWidth`; a second copy of the
105
+ * number here would be a second decision, and the artifact would drift from the
106
+ * tool that checks it the first time either moved. Absent config falls back to
107
+ * prettier's own defaults.
108
+ */
109
+ function jsonLayoutOf(manifest) {
110
+ return {
111
+ printWidth: manifest.prettier?.printWidth ?? DEFAULT_JSON_LAYOUT.printWidth,
112
+ tabWidth: manifest.prettier?.tabWidth ?? DEFAULT_JSON_LAYOUT.tabWidth
113
+ };
114
+ }
115
+ /**
116
+ * The layout the repository's own prettier config asks for, read from the ROOT
117
+ * package.json. Exported so the guard that checks the artifact resolves the layout
118
+ * the same way the renderer does — two resolutions would be two decisions.
119
+ */
120
+ export function repositoryJsonLayout() {
121
+ return jsonLayoutOf(loadPackageManifest());
122
+ }
123
+ /**
124
+ * The artifact's bytes, newline-terminated — the same serialization contract as the
125
+ * whitelist, in the layout prettier produces for JSON.
126
+ *
127
+ * `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
128
+ * regardless of width, so the committed artifact was not prettier-clean. The shape
129
+ * is now computed by `json-layout.ts`, which implements prettier's JSON rules with
130
+ * ZERO dependencies — `prettier` is a devDependency, and this module ships to
131
+ * consumers inside `dist/**`, so it must not depend on it.
132
+ *
133
+ * The default layout is the repository's own, read from the root `package.json`;
134
+ * a caller rendering for another root passes the layout it resolved there.
135
+ */
136
+ export function serializePluginManifest(manifest, options = repositoryJsonLayout()) {
137
+ return renderJsonDocument(manifest, options);
103
138
  }
104
139
  /** Absolute path of the committed artifact for a package root. */
105
140
  export function pluginManifestPath(root = repoRoot) {
@@ -122,5 +157,6 @@ export async function renderPluginManifest(root = repoRoot) {
122
157
  const named = skills.failures.map((failure) => failure.skillPath).join(', ');
123
158
  throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
124
159
  }
125
- return serializePluginManifest(generatePluginManifest(loadPackageManifest(root), skills.skills));
160
+ const pkg = loadPackageManifest(root);
161
+ return serializePluginManifest(generatePluginManifest(pkg, skills.skills), jsonLayoutOf(pkg));
126
162
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.21",
3
+ "version": "4.1.22",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -132,10 +132,10 @@
132
132
  "picomatch": "4.0.7",
133
133
  "yaml": "^2.9.1",
134
134
  "zod": "^4.6.7",
135
- "peaks-loop-mut": "0.1.75",
136
- "peaks-loop-internal-runtime": "0.0.61",
137
- "peaks-loop-shared": "0.0.110",
138
- "peaks-loop-shared-channel": "0.0.78"
135
+ "peaks-loop-internal-runtime": "0.0.62",
136
+ "peaks-loop-mut": "0.1.76",
137
+ "peaks-loop-shared": "0.0.111",
138
+ "peaks-loop-shared-channel": "0.0.79"
139
139
  },
140
140
  "devDependencies": {
141
141
  "@changesets/cli": "2.31.1",