create-clis 0.1.0

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.
Files changed (104) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +113 -0
  3. package/README.zh-CN.md +113 -0
  4. package/assets/manifest.json +99 -0
  5. package/assets/template/.editorconfig +12 -0
  6. package/assets/template/.gitattributes +18 -0
  7. package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +86 -0
  8. package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +45 -0
  9. package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +26 -0
  10. package/assets/template/.github/workflows/ci.yml +42 -0
  11. package/assets/template/.github/workflows/release.yml +65 -0
  12. package/assets/template/.gitignorerc.json +21 -0
  13. package/assets/template/.nvmrc +1 -0
  14. package/assets/template/.oxlintrc.json +52 -0
  15. package/assets/template/.prettierignore +11 -0
  16. package/assets/template/.prettierrc +11 -0
  17. package/assets/template/.releaserc.json +17 -0
  18. package/assets/template/.vscode/extensions.json +8 -0
  19. package/assets/template/.vscode/launch.json +13 -0
  20. package/assets/template/.vscode/settings.json +14 -0
  21. package/assets/template/AGENTS.md +25 -0
  22. package/assets/template/CODE_OF_CONDUCT.md +91 -0
  23. package/assets/template/CONTRIBUTING.md +85 -0
  24. package/assets/template/CONTRIBUTING.zh-CN.md +85 -0
  25. package/assets/template/LICENSE +21 -0
  26. package/assets/template/README.md +22 -0
  27. package/assets/template/README.zh-CN.md +22 -0
  28. package/assets/template/SECURITY.md +21 -0
  29. package/assets/template/_gitignore +409 -0
  30. package/assets/template/_npmrc +6 -0
  31. package/assets/template/bunfig.toml +16 -0
  32. package/assets/template/docs/README.md +30 -0
  33. package/assets/template/docs/adrs/README.md +7 -0
  34. package/assets/template/docs/designs/README.md +11 -0
  35. package/assets/template/docs/designs/tech-debt.md +22 -0
  36. package/assets/template/docs/development.md +59 -0
  37. package/assets/template/lefthook.yml +55 -0
  38. package/assets/template/package.json +38 -0
  39. package/assets/template/packages/{{NAME}}/CHANGELOG.md +3 -0
  40. package/assets/template/packages/{{NAME}}/LICENSE +21 -0
  41. package/assets/template/packages/{{NAME}}/README.md +33 -0
  42. package/assets/template/packages/{{NAME}}/README.zh-CN.md +33 -0
  43. package/assets/template/packages/{{NAME}}/docs/README.md +21 -0
  44. package/assets/template/packages/{{NAME}}/package.json +40 -0
  45. package/assets/template/packages/{{NAME}}/scripts/build.ts +82 -0
  46. package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +214 -0
  47. package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +152 -0
  48. package/assets/template/packages/{{NAME}}/src/index.ts +15 -0
  49. package/assets/template/packages/{{NAME}}/tsconfig.build.json +12 -0
  50. package/assets/template/packages/{{NAME}}/tsconfig.json +5 -0
  51. package/assets/template/packages/{{NAME}}-cli/CHANGELOG.md +3 -0
  52. package/assets/template/packages/{{NAME}}-cli/LICENSE +21 -0
  53. package/assets/template/packages/{{NAME}}-cli/README.md +35 -0
  54. package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +35 -0
  55. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +30 -0
  56. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +30 -0
  57. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +23 -0
  58. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +212 -0
  59. package/assets/template/packages/{{NAME}}-cli/docs/README.md +21 -0
  60. package/assets/template/packages/{{NAME}}-cli/package.json +48 -0
  61. package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +141 -0
  62. package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +70 -0
  63. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +444 -0
  64. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +72 -0
  65. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +126 -0
  66. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +81 -0
  67. package/assets/template/packages/{{NAME}}-cli/src/cli.ts +36 -0
  68. package/assets/template/packages/{{NAME}}-cli/tsconfig.json +4 -0
  69. package/assets/template/scripts/ci.ts +163 -0
  70. package/assets/template/scripts/install-git-hooks.mjs +122 -0
  71. package/assets/template/scripts/install-git-hooks.test.ts +418 -0
  72. package/assets/template/scripts/lib/git-env.ts +21 -0
  73. package/assets/template/scripts/lib/release-verify.ts +431 -0
  74. package/assets/template/scripts/lib/tmp-root.ts +17 -0
  75. package/assets/template/scripts/lib/workspace.test.ts +92 -0
  76. package/assets/template/scripts/lib/workspace.ts +100 -0
  77. package/assets/template/scripts/lint-doc-examples.test.ts +129 -0
  78. package/assets/template/scripts/lint-doc-examples.ts +249 -0
  79. package/assets/template/scripts/lint-doc-references.test.ts +158 -0
  80. package/assets/template/scripts/lint-doc-references.ts +308 -0
  81. package/assets/template/scripts/lint-doc-shared.ts +59 -0
  82. package/assets/template/scripts/lint-stray-backups.test.ts +53 -0
  83. package/assets/template/scripts/lint-stray-backups.ts +39 -0
  84. package/assets/template/scripts/npm-trust-guard.test.ts +253 -0
  85. package/assets/template/scripts/npm-trust-guard.ts +533 -0
  86. package/assets/template/scripts/safe-install.ts +39 -0
  87. package/assets/template/scripts/transcription/api-harness.ts +219 -0
  88. package/assets/template/scripts/transcription/compare.ts +421 -0
  89. package/assets/template/scripts/transcription/corpus.ts +208 -0
  90. package/assets/template/scripts/transcription/fixture.ts +290 -0
  91. package/assets/template/scripts/transcription/make-mutants.ts +425 -0
  92. package/assets/template/scripts/transcription/report.ts +86 -0
  93. package/assets/template/scripts/transcription/run-conformance.ts +344 -0
  94. package/assets/template/scripts/transcription/validate-coverage.test.ts +119 -0
  95. package/assets/template/scripts/transcription/validate-coverage.ts +144 -0
  96. package/assets/template/scripts/transcription/validate.ts +366 -0
  97. package/assets/template/tsconfig.json +46 -0
  98. package/assets/template/turbo.jsonc +60 -0
  99. package/bin/create-clis +35 -0
  100. package/bin/create-clis.cmd +32 -0
  101. package/bin/create-clis.mjs +219 -0
  102. package/dist/create-clis.js +87682 -0
  103. package/dist/manifest.json +7 -0
  104. package/package.json +57 -0
@@ -0,0 +1,444 @@
1
+ /**
2
+ * 发布前置闸门 (verify-release.ts) 的行为钉住: 三态 (干净通过 / 脏拒绝 / 产物缺失拒绝) 全跑在
3
+ * 临时 git 检出上, 判定所依据的 git 事实来自真命令, 而非「跑测试那一刻当前工作树恰好脏还是净」
4
+ * (本仓库平时就是脏树, 正因如此不能拿它当夹具)。
5
+ * 端到端不便造的畸形现场 (零字节产物 / 清单 JSON 损坏 / schemaVersion 不受支持等) 走注入事实的
6
+ * 字段级用例: judgeRelease 是纯函数, 事实输入可完全摆布。
7
+ * 发行面清单 (npm pack 输出) 同理注入, 端到端用例因而一次 npm 都不跑; 白名单与真实 npm 行为的
8
+ * 对齐由文末「真实 npm 对齐」组在本仓库上实跑一次钉住 (防仓库根杂质复发); 该组在无 dist/ 的
9
+ * 未构建态注册期 skip 并播报 (bun:test 无运行时 skip), 免得「还没构建」被误报成发行面回归。
10
+ */
11
+ import { describe, expect, test } from 'bun:test';
12
+
13
+ import { existsSync } from 'node:fs';
14
+ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
15
+ import { join } from 'node:path';
16
+
17
+ import {
18
+ CLI_FILE,
19
+ type DistState,
20
+ MANIFEST_FILE,
21
+ PACKAGE_ROOT,
22
+ PACK_FILES_EXPECTED,
23
+ type PackFacts,
24
+ type ReleaseFacts,
25
+ collectGitFacts,
26
+ judgePackFiles,
27
+ judgeRelease,
28
+ parsePackFiles,
29
+ readPackFiles,
30
+ sha256File,
31
+ } from './release-artifact.ts';
32
+ import { makeTempDir, makeTempRepo } from './release.fixtures.ts';
33
+ import { type ReleaseIo, verifyRelease } from './verify-release.ts';
34
+ import { writeDistManifest } from './write-dist-manifest.ts';
35
+
36
+ /** 注入一个「与白名单相符」的发行面事实: 判定链要走完 pack 检查, 但单测不必真跑 npm */
37
+ const PACK_OK: PackFacts = { files: [...PACK_FILES_EXPECTED], issue: null };
38
+
39
+ /** 捕获闸门输出 (既为断言文案, 也不让测试输出变成噪音) */
40
+ const capture = (): { io: ReleaseIo; out: string[]; err: string[] } => {
41
+ const out: string[] = [];
42
+ const err: string[] = [];
43
+ return {
44
+ io: {
45
+ out: (line) => {
46
+ out.push(line);
47
+ },
48
+ err: (line) => {
49
+ err.push(line);
50
+ },
51
+ },
52
+ out,
53
+ err,
54
+ };
55
+ };
56
+
57
+ /** 在检出内造产物与清单: 走真实写入路径, git 事实取自该检出的真实 git */
58
+ const stageArtifact = async (root: string): Promise<void> => {
59
+ await mkdir(join(root, 'dist'), { recursive: true });
60
+ const cliPath = join(root, 'dist', CLI_FILE);
61
+ await writeFile(cliPath, "console.log('hi');\n");
62
+ const manifest = writeDistManifest(
63
+ join(root, 'dist'),
64
+ collectGitFacts(root),
65
+ '2026-09-26T00:00:00.000Z',
66
+ );
67
+ expect(manifest).not.toBeNull();
68
+ expect(manifest?.cliSha256).toBe(sha256File(cliPath));
69
+ };
70
+
71
+ /** 改写清单字段 (绕开写入路径, 造出「清单与事实不符」的现场) */
72
+ const patchManifest = async (
73
+ root: string,
74
+ patch: Record<string, unknown>,
75
+ ): Promise<void> => {
76
+ const path = join(root, 'dist', MANIFEST_FILE);
77
+ const current = JSON.parse(await readFile(path, 'utf8')) as Record<
78
+ string,
79
+ unknown
80
+ >;
81
+ await writeFile(path, JSON.stringify({ ...current, ...patch }));
82
+ };
83
+
84
+ describe('发布前置闸门 · 临时检出端到端', () => {
85
+ test('干净检出 + 本提交产物 + 清单自洽 → 通过 (退出码 0)', async () => {
86
+ const repo = await makeTempRepo('sweep-lab-release-ok-');
87
+ try {
88
+ await stageArtifact(repo.root);
89
+ const { io, out, err } = capture();
90
+
91
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(0);
92
+ expect(out.join('\n')).toContain('发布前置校验通过');
93
+ expect(err).toEqual([]);
94
+ } finally {
95
+ await repo.cleanup();
96
+ }
97
+ });
98
+
99
+ test('工作树脏 → 拒绝 (退出码 1, 拒绝原因带未提交改动条数)', async () => {
100
+ const repo = await makeTempRepo('sweep-lab-release-dirty-');
101
+ try {
102
+ await stageArtifact(repo.root);
103
+ await writeFile(join(repo.root, 'workspace.txt'), '半成品\n');
104
+ const { io, out, err } = capture();
105
+
106
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(1);
107
+ expect(err.join('\n')).toContain(
108
+ '工作树不干净 (未提交改动 1 项: workspace.txt)',
109
+ );
110
+ expect(out).toEqual([]);
111
+ } finally {
112
+ await repo.cleanup();
113
+ }
114
+ });
115
+
116
+ test('产物缺失 → 拒绝 (退出码 1)', async () => {
117
+ const repo = await makeTempRepo('sweep-lab-release-nocli-');
118
+ try {
119
+ await stageArtifact(repo.root);
120
+ await rm(join(repo.root, 'dist', CLI_FILE));
121
+ const { io, err } = capture();
122
+
123
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(1);
124
+ expect(err.join('\n')).toContain('产物缺失');
125
+ } finally {
126
+ await repo.cleanup();
127
+ }
128
+ });
129
+
130
+ test('产物被替换 (摘要不符) → 拒绝', async () => {
131
+ const repo = await makeTempRepo('sweep-lab-release-swapped-');
132
+ try {
133
+ await stageArtifact(repo.root);
134
+ await writeFile(
135
+ join(repo.root, 'dist', CLI_FILE),
136
+ "console.log('swapped');\n",
137
+ );
138
+ const { io, err } = capture();
139
+
140
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(1);
141
+ expect(err.join('\n')).toContain('产物摘要与清单记录不符');
142
+ } finally {
143
+ await repo.cleanup();
144
+ }
145
+ });
146
+
147
+ test('清单记录的是脏构建 → 拒绝', async () => {
148
+ const repo = await makeTempRepo('sweep-lab-release-dirtybuild-');
149
+ try {
150
+ await stageArtifact(repo.root);
151
+ await patchManifest(repo.root, { dirty: true });
152
+ const { io, err } = capture();
153
+
154
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(1);
155
+ expect(err.join('\n')).toContain('脏工作树构建');
156
+ } finally {
157
+ await repo.cleanup();
158
+ }
159
+ });
160
+
161
+ test('清单记录的提交与 HEAD 不一致 (构建后又有新提交) → 拒绝', async () => {
162
+ const repo = await makeTempRepo('sweep-lab-release-stale-');
163
+ try {
164
+ await stageArtifact(repo.root);
165
+ await patchManifest(repo.root, { commit: 'f'.repeat(40) });
166
+ const { io, err } = capture();
167
+
168
+ expect(verifyRelease(repo.root, io, PACK_OK)).toBe(1);
169
+ expect(err.join('\n')).toContain('不一致');
170
+ } finally {
171
+ await repo.cleanup();
172
+ }
173
+ });
174
+
175
+ test('非 git 目录 → 拒绝 (读不到 git 状态)', async () => {
176
+ const temp = await makeTempDir('sweep-lab-release-nogit-');
177
+ try {
178
+ const { io, err } = capture();
179
+
180
+ expect(verifyRelease(temp.root, io, PACK_OK)).toBe(1);
181
+ expect(err.join('\n')).toContain('读不到 git 状态');
182
+ } finally {
183
+ await temp.cleanup();
184
+ }
185
+ });
186
+ });
187
+
188
+ describe('发布前置闸门 · 字段级判定 (注入事实)', () => {
189
+ const CLEAN_COMMIT = 'a2109d7f'.repeat(5);
190
+ const CLEAN_SHA = '9f2c47ab'.repeat(8);
191
+ const cleanManifest = {
192
+ schemaVersion: 1,
193
+ commit: CLEAN_COMMIT,
194
+ dirty: false,
195
+ cliSha256: CLEAN_SHA,
196
+ builtAt: '2026-09-26T00:00:00.000Z',
197
+ };
198
+ const cleanDist: DistState = {
199
+ entryExists: true,
200
+ entrySize: 17,
201
+ entrySha256: CLEAN_SHA,
202
+ manifestExists: true,
203
+ manifest: cleanManifest,
204
+ manifestIssue: null,
205
+ };
206
+ const cleanFacts: ReleaseFacts = {
207
+ gitStatus: '',
208
+ gitHead: CLEAN_COMMIT,
209
+ dist: cleanDist,
210
+ pack: PACK_OK,
211
+ };
212
+
213
+ test('干净事实 → 通过并交出被判定的提交与摘要', () => {
214
+ const verdict = judgeRelease(cleanFacts);
215
+
216
+ expect(verdict.ok).toBe(true);
217
+ if (verdict.ok) {
218
+ expect(verdict.commit).toBe(CLEAN_COMMIT);
219
+ expect(verdict.sha256).toBe(CLEAN_SHA);
220
+ }
221
+ });
222
+
223
+ const rejectCases: Array<{
224
+ name: string;
225
+ facts: ReleaseFacts;
226
+ reason: string;
227
+ }> = [
228
+ {
229
+ name: 'git 状态读不到',
230
+ facts: { ...cleanFacts, gitStatus: null },
231
+ reason: '读不到 git 状态',
232
+ },
233
+ {
234
+ name: 'HEAD 读不到',
235
+ facts: { ...cleanFacts, gitHead: null },
236
+ reason: '读不到 HEAD',
237
+ },
238
+ {
239
+ name: '工作树脏 (改动条数进拒绝原因)',
240
+ facts: { ...cleanFacts, gitStatus: ' M workspace.txt\n?? draft.md\n' },
241
+ reason: '未提交改动 2 项',
242
+ },
243
+ {
244
+ name: '工作树脏 (路径预览逐条列出, 超三条以省略号收敛)',
245
+ facts: {
246
+ ...cleanFacts,
247
+ gitStatus: ' M a.txt\n?? b.txt\n M c.txt\n?? d.txt\n',
248
+ },
249
+ reason: '未提交改动 4 项: a.txt, b.txt, c.txt …',
250
+ },
251
+ {
252
+ name: '产物缺失',
253
+ facts: {
254
+ ...cleanFacts,
255
+ dist: {
256
+ ...cleanDist,
257
+ entryExists: false,
258
+ entrySize: 0,
259
+ entrySha256: null,
260
+ },
261
+ },
262
+ reason: '产物缺失',
263
+ },
264
+ {
265
+ name: '产物零字节',
266
+ facts: {
267
+ ...cleanFacts,
268
+ dist: { ...cleanDist, entrySize: 0, entrySha256: null },
269
+ },
270
+ reason: '产物为空',
271
+ },
272
+ {
273
+ name: '产物读不出 (摘要算不出)',
274
+ facts: { ...cleanFacts, dist: { ...cleanDist, entrySha256: null } },
275
+ reason: '产物不可读',
276
+ },
277
+ {
278
+ name: '清单缺失',
279
+ facts: {
280
+ ...cleanFacts,
281
+ dist: { ...cleanDist, manifestExists: false, manifest: null },
282
+ },
283
+ reason: '产物清单缺失',
284
+ },
285
+ {
286
+ name: '清单不可用 (JSON 损坏, 病灶原样带上)',
287
+ facts: {
288
+ ...cleanFacts,
289
+ dist: {
290
+ ...cleanDist,
291
+ manifest: null,
292
+ manifestIssue: '清单不是合法 JSON',
293
+ },
294
+ },
295
+ reason: '清单不可用: 清单不是合法 JSON',
296
+ },
297
+ {
298
+ name: '清单记录脏构建',
299
+ facts: {
300
+ ...cleanFacts,
301
+ dist: { ...cleanDist, manifest: { ...cleanManifest, dirty: true } },
302
+ },
303
+ reason: '脏工作树构建',
304
+ },
305
+ {
306
+ name: '清单提交与 HEAD 不一致',
307
+ facts: {
308
+ ...cleanFacts,
309
+ dist: {
310
+ ...cleanDist,
311
+ manifest: { ...cleanManifest, commit: 'b'.repeat(40) },
312
+ },
313
+ },
314
+ reason: '不一致',
315
+ },
316
+ {
317
+ name: '摘要与清单记录不符',
318
+ facts: {
319
+ ...cleanFacts,
320
+ dist: { ...cleanDist, entrySha256: 'c'.repeat(64) },
321
+ },
322
+ reason: '摘要与清单记录不符',
323
+ },
324
+ {
325
+ name: '发行面清单采不到 (该检查需要 npm)',
326
+ facts: {
327
+ ...cleanFacts,
328
+ pack: { files: null, issue: 'npm pack 跑不起来 (需要 npm)' },
329
+ },
330
+ reason: '该项检查需要 npm',
331
+ },
332
+ {
333
+ name: '发行面包内多出文件 (如仓库根备份被 npm 一并收进包)',
334
+ facts: {
335
+ ...cleanFacts,
336
+ pack: {
337
+ files: [...PACK_FILES_EXPECTED, 'README.md.20260924_181433.modified'],
338
+ issue: null,
339
+ },
340
+ },
341
+ reason: '多出 README.md.20260924_181433.modified',
342
+ },
343
+ {
344
+ name: '发行面包内缺少文件',
345
+ facts: {
346
+ ...cleanFacts,
347
+ pack: {
348
+ files: PACK_FILES_EXPECTED.filter((path) => path !== 'dist/cli.js'),
349
+ issue: null,
350
+ },
351
+ },
352
+ reason: '缺少 dist/cli.js',
353
+ },
354
+ {
355
+ name: '发行面包内一多一少 (两向差异并列列出)',
356
+ facts: {
357
+ ...cleanFacts,
358
+ pack: {
359
+ files: [
360
+ ...PACK_FILES_EXPECTED.filter((path) => path !== 'LICENSE'),
361
+ 'extra.txt',
362
+ ],
363
+ issue: null,
364
+ },
365
+ },
366
+ reason: '多出 extra.txt; 缺少 LICENSE',
367
+ },
368
+ ];
369
+
370
+ for (const item of rejectCases) {
371
+ test(`拒绝: ${item.name}`, () => {
372
+ const verdict = judgeRelease(item.facts);
373
+
374
+ expect(verdict.ok).toBe(false);
375
+ if (!verdict.ok) expect(verdict.reason).toContain(item.reason);
376
+ });
377
+ }
378
+ });
379
+
380
+ describe('发行面白名单 · 注入式 (喂假 pack 输出, 一次 npm 都不跑)', () => {
381
+ test('解析 npm pack --json 的输出: 取首个元素的 files[].path', () => {
382
+ const raw = JSON.stringify([
383
+ {
384
+ filename: '{{OWNER}}-{{NAME}}-0.3.0.tgz',
385
+ files: [
386
+ { path: 'LICENSE', size: 1063 },
387
+ { path: 'dist/cli.js', size: 51965 },
388
+ ],
389
+ },
390
+ ]);
391
+
392
+ expect(parsePackFiles(raw)).toEqual(['LICENSE', 'dist/cli.js']);
393
+ });
394
+
395
+ test('输出非 JSON / 结构不符 → null (不猜结构, 交由采集层落 issue)', () => {
396
+ expect(parsePackFiles('not json at all')).toBeNull();
397
+ expect(parsePackFiles('{"files":[]}')).toBeNull();
398
+ expect(parsePackFiles('[]')).toBeNull();
399
+ expect(parsePackFiles('[{"files":[{"nopath":1}]}]')).toBeNull();
400
+ expect(parsePackFiles('[{"files":[{"path":""}]}]')).toBeNull();
401
+ });
402
+
403
+ test('集合相等 → 通过 (与顺序无关)', () => {
404
+ expect(judgePackFiles([...PACK_FILES_EXPECTED].reverse()).ok).toBe(true);
405
+ });
406
+
407
+ test('差异路径剔控制字符 (路径来自 npm 输出, 属低信任输入)', () => {
408
+ const verdict = judgePackFiles([
409
+ ...PACK_FILES_EXPECTED,
410
+ 'bad\u001b[31m.txt',
411
+ ]);
412
+
413
+ expect(verdict.ok).toBe(false);
414
+ if (!verdict.ok) expect(verdict.reason).toContain('bad?[31m.txt');
415
+ });
416
+ });
417
+
418
+ /**
419
+ * 真实 npm 对齐的注册门控: 工作树无 dist/ = 未构建的合法态 (safe-install 清产物后尚未重构建即如此),
420
+ * 此时 pack 清单必然缺 dist/cli.js 与 dist/manifest.json, 属「还没构建」而非「发行面杂质回归」。
421
+ * 注册期判定 skip 并播报原因; dist 在场则全程维持原有全清单断言, 不削弱真问题抓取力。
422
+ */
423
+ const hasDist = existsSync(join(PACKAGE_ROOT, 'dist'));
424
+
425
+ if (!hasDist) {
426
+ console.warn(
427
+ '[Skip] 工作树无构建产物 (先 bun run build); 本用例守护发行面杂质回归',
428
+ );
429
+ }
430
+
431
+ describe('发行面白名单 · 真实 npm 对齐 (本仓库实测)', () => {
432
+ test.skipIf(!hasDist)(
433
+ '本仓库工作树的 pack 清单与白名单逐项一致 (包根杂质复发的常驻回归)',
434
+ () => {
435
+ const facts = readPackFiles(PACKAGE_ROOT);
436
+
437
+ // 采不到即失败并显示 issue (如「需要 npm」), 不静默跳过: 该项是发行面唯一的真实对齐证据
438
+ expect(facts.issue).toBeNull();
439
+ const verdict = judgePackFiles(facts.files ?? []);
440
+ // 断言携带 reason 而非裸 false: 失败时测试输出直接给出差异清单, 一眼看清是多出还是缺少
441
+ expect(verdict.ok ? '' : verdict.reason).toBe('');
442
+ },
443
+ );
444
+ });
@@ -0,0 +1,72 @@
1
+ /**
2
+ * 发布侧闸门: 只有「干净检出 + 本提交构建的产物 + 清单自洽 + 发行面包内文件与白名单相符」
3
+ * 四者齐备才放行发布。
4
+ *
5
+ * 由 package.json 的 prepublishOnly (`npm run build && npm run verify:release`) 在构建后调用,
6
+ * 手动复核即 `bun run verify:release`。分工: 事实采集 (含发行面清单, 跑一次只读的 npm pack) 与
7
+ * 判定都在 release-artifact.ts (判定是纯函数, 事实可注入), 本文件只负责坐标 (PACKAGE_ROOT) 与
8
+ * 输出面 (文案 + 退出码)。
9
+ *
10
+ * 用法: bun scripts/verify-release.ts
11
+ * 退出码: 0 通过; 1 拒绝 (原因与处置见 stderr)
12
+ */
13
+ import { join } from 'node:path';
14
+
15
+ import {
16
+ PACKAGE_ROOT,
17
+ type PackFacts,
18
+ type ReleaseFacts,
19
+ judgeRelease,
20
+ normalizeCommit,
21
+ readDistState,
22
+ readGitText,
23
+ readPackFiles,
24
+ shortHash,
25
+ } from './release-artifact.ts';
26
+
27
+ /** 输出面 (注入以便测试捕获; CLI 直写 process) */
28
+ export interface ReleaseIo {
29
+ out: (line: string) => void;
30
+ err: (line: string) => void;
31
+ }
32
+
33
+ /**
34
+ * 跑一次发布前置校验: 采事实 (git 状态 / HEAD + dist 现状 + 发行面包内清单) → judgeRelease →
35
+ * 输出结论。
36
+ * root 是包根 (默认 PACKAGE_ROOT; 测试注入临时仓库, 判定因此不依赖当前工作树状态)。
37
+ * packFacts 默认现场采集 (跑一次只读的 npm pack, 需要 npm); 测试注入假清单以摆脱 npm 依赖。
38
+ * 外部副作用:只读 (两条只读 git 命令 + 读 dist/ 下的产物与清单 + 一次 npm pack --dry-run)。
39
+ */
40
+ export const verifyRelease = (
41
+ root: string,
42
+ io: ReleaseIo,
43
+ packFacts: PackFacts = readPackFiles(root),
44
+ ): number => {
45
+ const facts: ReleaseFacts = {
46
+ gitStatus: readGitText(root, ['status', '--porcelain']),
47
+ gitHead: normalizeCommit(readGitText(root, ['rev-parse', 'HEAD'])),
48
+ dist: readDistState(join(root, 'dist')),
49
+ pack: packFacts,
50
+ };
51
+ const verdict = judgeRelease(facts);
52
+ if (verdict.ok) {
53
+ io.out(
54
+ `发布前置校验通过: 提交 ${shortHash(verdict.commit)} · 产物摘要 ${shortHash(verdict.sha256)}`,
55
+ );
56
+ return 0;
57
+ }
58
+ io.err(`发布前置校验未通过: ${verdict.reason}`);
59
+ io.err(
60
+ ' 处置: 工作树不干净就提交或 stash 后重新构建再发 (npm run build 会同时写产物与清单);' +
61
+ ' 发行面包内文件与白名单不符就清掉仓库根的多余文件 (如备份移出仓库), 或同步白名单常量。',
62
+ );
63
+ return 1;
64
+ };
65
+
66
+ // 被测试 import 时不得跑入口 (只有直接运行才落退出码)
67
+ if (import.meta.main) {
68
+ process.exitCode = verifyRelease(PACKAGE_ROOT, {
69
+ out: (line) => process.stdout.write(`${line}\n`),
70
+ err: (line) => process.stderr.write(`${line}\n`),
71
+ });
72
+ }
@@ -0,0 +1,126 @@
1
+ /**
2
+ * 构建侧清单写入 (write-dist-manifest.ts) 与 git 事实采集 (collectGitFacts) 的行为钉住。
3
+ * 清单字段是三方契约 (构建侧写 / 发布闸门读 / npm 启动器读), 故连字段值一并钉死;
4
+ * 采集口径用真 git 检出验 (打桩验不出「porcelain 空输出 = 干净」这条口径)。
5
+ */
6
+ import { describe, expect, test } from 'bun:test';
7
+
8
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
9
+ import { readFile, writeFile } from 'node:fs/promises';
10
+ import { join } from 'node:path';
11
+
12
+ import {
13
+ CLI_FILE,
14
+ type DistManifest,
15
+ MANIFEST_FILE,
16
+ collectGitFacts,
17
+ sha256File,
18
+ } from './release-artifact.ts';
19
+ import { makeTempDir, makeTempRepo, runGit } from './release.fixtures.ts';
20
+ import { writeDistManifest } from './write-dist-manifest.ts';
21
+
22
+ const FIXED_TIME = '2026-09-26T00:00:00.000Z';
23
+ const COMMIT = 'a2109d7f'.repeat(5);
24
+
25
+ /** 临时产物目录 (同步建目录便于用例内直接写文件) */
26
+ const makeDistDir = async (): Promise<{
27
+ distDir: string;
28
+ cleanup: () => Promise<void>;
29
+ }> => {
30
+ const temp = await makeTempDir('sweep-lab-manifest-');
31
+ const distDir = join(temp.root, 'dist');
32
+ mkdirSync(distDir, { recursive: true });
33
+ return { distDir, cleanup: temp.cleanup };
34
+ };
35
+
36
+ describe('产物清单写入', () => {
37
+ test('写入清单: 形状与摘要钉住 (摘要取产物实测值)', async () => {
38
+ const dist = await makeDistDir();
39
+ try {
40
+ writeFileSync(join(dist.distDir, CLI_FILE), "console.log('hi');\n");
41
+
42
+ const manifest = writeDistManifest(
43
+ dist.distDir,
44
+ { commit: COMMIT, dirty: false },
45
+ FIXED_TIME,
46
+ );
47
+ if (manifest === null) throw new Error('清单应已写入, 实际返回 null');
48
+
49
+ expect(manifest).toEqual({
50
+ schemaVersion: 1,
51
+ commit: COMMIT,
52
+ dirty: false,
53
+ cliSha256: sha256File(join(dist.distDir, CLI_FILE)),
54
+ builtAt: FIXED_TIME,
55
+ });
56
+ const onDisk = JSON.parse(
57
+ await readFile(join(dist.distDir, MANIFEST_FILE), 'utf8'),
58
+ ) as DistManifest;
59
+ expect(onDisk).toEqual(manifest);
60
+ } finally {
61
+ await dist.cleanup();
62
+ }
63
+ });
64
+
65
+ test('产物缺失 → 返回 null, 不落清单', async () => {
66
+ const dist = await makeDistDir();
67
+ try {
68
+ expect(
69
+ writeDistManifest(
70
+ dist.distDir,
71
+ { commit: null, dirty: null },
72
+ FIXED_TIME,
73
+ ),
74
+ ).toBeNull();
75
+ expect(existsSync(join(dist.distDir, MANIFEST_FILE))).toBe(false);
76
+ } finally {
77
+ await dist.cleanup();
78
+ }
79
+ });
80
+
81
+ test('产物零字节 → 返回 null (空产物不算产物)', async () => {
82
+ const dist = await makeDistDir();
83
+ try {
84
+ writeFileSync(join(dist.distDir, CLI_FILE), '');
85
+
86
+ expect(
87
+ writeDistManifest(
88
+ dist.distDir,
89
+ { commit: null, dirty: null },
90
+ FIXED_TIME,
91
+ ),
92
+ ).toBeNull();
93
+ expect(existsSync(join(dist.distDir, MANIFEST_FILE))).toBe(false);
94
+ } finally {
95
+ await dist.cleanup();
96
+ }
97
+ });
98
+
99
+ test('非 git 检出: 事实如实落 null (不假装有提交)', async () => {
100
+ const temp = await makeTempDir('sweep-lab-nogit-');
101
+ try {
102
+ expect(collectGitFacts(temp.root)).toEqual({ commit: null, dirty: null });
103
+ } finally {
104
+ await temp.cleanup();
105
+ }
106
+ });
107
+
108
+ test('真实检出: 干净时采到提交与净状态, 改动后转脏', async () => {
109
+ const repo = await makeTempRepo('sweep-lab-facts-');
110
+ try {
111
+ expect(collectGitFacts(repo.root)).toEqual({
112
+ commit: runGit(repo.root, ['rev-parse', 'HEAD']).trim(),
113
+ dirty: false,
114
+ });
115
+
116
+ await writeFile(join(repo.root, 'workspace.txt'), '改过\n');
117
+
118
+ expect(collectGitFacts(repo.root)).toEqual({
119
+ commit: runGit(repo.root, ['rev-parse', 'HEAD']).trim(),
120
+ dirty: true,
121
+ });
122
+ } finally {
123
+ await repo.cleanup();
124
+ }
125
+ });
126
+ });