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,33 @@
1
+ # {{SCOPE}}/{{NAME}}
2
+
3
+ <!-- 模板骨架: 示例包的可编程 API 是一个 greet 占位实现; 换成自己的领域逻辑后, 同步本节与包内文档。 -->
4
+
5
+ The programmable API package of this collection: replace the example implementation with your own domain logic. The command-line surface lives in the sibling CLI package ([{{SCOPE}}/{{NAME}}-cli](../{{NAME}}-cli/README.md)).
6
+
7
+ ## Install
8
+
9
+ ```shell
10
+ bun add {{SCOPE}}/{{NAME}}
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { greet } from '{{SCOPE}}/{{NAME}}';
17
+
18
+ console.log(greet({ who: 'world' })); // Hello, world!
19
+ ```
20
+
21
+ ## Development
22
+
23
+ ```shell
24
+ # 类型检查与测试 (在包目录内)
25
+ bun run typecheck && bun run test
26
+
27
+ # 打包发布产物 (dist/) 并跑发布自证闸门 (自证要求干净工作树)
28
+ bun run build && bun run verify:release
29
+ ```
30
+
31
+ ## Documentation
32
+
33
+ - [Package docs](docs/README.md): the package-level entry (designs and ADRs).
@@ -0,0 +1,33 @@
1
+ # {{SCOPE}}/{{NAME}}
2
+
3
+ <!-- 模板骨架: 示例包的可编程 API 是一个 greet 占位实现; 换成自己的领域逻辑后, 同步本节与包内文档。 -->
4
+
5
+ 本集合仓的可编程 API 包: 示例实现换成自己的领域逻辑即可; 命令行面在同级 CLI 包 ([{{SCOPE}}/{{NAME}}-cli](../{{NAME}}-cli/README.zh-CN.md))。
6
+
7
+ ## 安装
8
+
9
+ ```shell
10
+ bun add {{SCOPE}}/{{NAME}}
11
+ ```
12
+
13
+ ## 用法
14
+
15
+ ```ts
16
+ import { greet } from '{{SCOPE}}/{{NAME}}';
17
+
18
+ console.log(greet({ who: 'world' })); // Hello, world!
19
+ ```
20
+
21
+ ## 开发
22
+
23
+ ```shell
24
+ # 类型检查与测试 (在包目录内)
25
+ bun run typecheck && bun run test
26
+
27
+ # 打包发布产物 (dist/) 并跑发布自证闸门 (自证要求干净工作树)
28
+ bun run build && bun run verify:release
29
+ ```
30
+
31
+ ## 文档
32
+
33
+ - [包级文档入口](docs/README.md): 包内设计与包级 ADR 的登记入口。
@@ -0,0 +1,21 @@
1
+ # {{SCOPE}}/{{NAME}} (API 包) 文档
2
+
3
+ > 文档类型: 包级文档入口
4
+
5
+ `{{SCOPE}}/{{NAME}}` 是示例包的可编程 API: 换成自己的领域逻辑后, 在此登记包内文档与包级 ADR。使用面见[包 README](../README.md)。
6
+
7
+ ## 包内文档
8
+
9
+ | 文档 | 一句话 |
10
+ | -------- | ------------------------------------ |
11
+ | (待登记) | 新项目在这里登记包级设计文档的第一篇 |
12
+
13
+ ## 包级 ADR
14
+
15
+ | 编号 | 标题 |
16
+ | -------- | ----------------------------- |
17
+ | (待登记) | 包级 ADR 与仓库级共用一套编号 |
18
+
19
+ ## 仓库级关联
20
+
21
+ - [仓库文档索引](../../../docs/README.md) / [设计文档索引](../../../docs/designs/README.md)。
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "{{SCOPE}}/{{NAME}}",
3
+ "version": "0.0.0",
4
+ "description": "The programmable API package of this collection: replace the greet example with your own domain logic. 本集合仓的可编程 API 示例包。",
5
+ "author": "{{OWNER}} (https://github.com/{{OWNER}})",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+{{REPO_URL}}.git"
10
+ },
11
+ "homepage": "{{REPO_URL}}#readme",
12
+ "bugs": {
13
+ "url": "{{REPO_URL}}/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "default": "./dist/index.js"
21
+ }
22
+ },
23
+ "files": [
24
+ "dist"
25
+ ],
26
+ "engines": {
27
+ "node": ">=22.18.0"
28
+ },
29
+ "publishConfig": {
30
+ "access": "public",
31
+ "registry": "https://registry.npmjs.org/"
32
+ },
33
+ "scripts": {
34
+ "build": "bun scripts/build.ts",
35
+ "typecheck": "tsc --noEmit",
36
+ "test": "bun test",
37
+ "verify:release": "bun scripts/verify-release.ts",
38
+ "prepublishOnly": "npm run build && npm run verify:release"
39
+ }
40
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * API 包构建脚本: 清产物 → bun build 出 JS → tsc 出类型声明 → d.ts specifier 后处理。
3
+ * 与 CLI 包 scripts/ 同风格 (bun 直跑, 失败非零退出); 是发布闸门 (prepublishOnly) 的第一步。
4
+ *
5
+ * 为什么有第 4 步 (d.ts 后处理): 源码 import 一律带 '.ts' 扩展 (allowImportingTsExtensions,
6
+ * bun 直跑 TS 的写法), tsc 的 declaration emit 会把 './x.ts' 原样写进 .d.ts, 而消费方 TS
7
+ * (未开 allowImportingTsExtensions) 解析不了这种 specifier; typescript 7.0.2 的
8
+ * rewriteRelativeImportExtensions 在本配置的 declaration emit 下实测未生效, 故在产物层
9
+ * 确定性改写为 '.js' (只动相对 specifier 两处形态, 不触其余文本; 幂等)。
10
+ */
11
+ import { spawnSync } from 'node:child_process';
12
+ import { createHash } from 'node:crypto';
13
+ import { readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
14
+ import { join } from 'node:path';
15
+
16
+ const ROOT = join(import.meta.dir, '..');
17
+ const DIST = join(ROOT, 'dist');
18
+
19
+ // 1. 清产物: 整目录重建, 防上一轮构建的残留文件混进发布包 (files 白名单整目录进包)
20
+ rmSync(DIST, { recursive: true, force: true });
21
+
22
+ // 2. JS 产物: 单文件 bundle, node 目标 (标准 ESM, bun 与 node 双运行时均可)
23
+ const bundle = spawnSync(
24
+ 'bun',
25
+ [
26
+ 'build',
27
+ join(ROOT, 'src/index.ts'),
28
+ '--target=node',
29
+ `--outfile=${join(DIST, 'index.js')}`,
30
+ ],
31
+ { stdio: 'inherit' },
32
+ );
33
+ if (bundle.status !== 0) process.exit(bundle.status ?? 1);
34
+
35
+ // 3. 类型声明: 独立 tsconfig (emitDeclarationOnly; 测试 / smoke / fixtures 已在 exclude)
36
+ const types = spawnSync(
37
+ 'bunx',
38
+ ['tsc', '-p', join(ROOT, 'tsconfig.build.json')],
39
+ {
40
+ stdio: 'inherit',
41
+ },
42
+ );
43
+ if (types.status !== 0) process.exit(types.status ?? 1);
44
+
45
+ // 4. d.ts specifier 后处理 (理由见文件头)
46
+ for (const file of readdirSync(DIST)) {
47
+ if (!file.endsWith('.d.ts')) continue;
48
+ const path = join(DIST, file);
49
+ const before = readFileSync(path, 'utf8');
50
+ const after = before
51
+ .replace(/(from\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3')
52
+ .replace(/(import\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3');
53
+ if (after !== before) writeFileSync(path, after);
54
+ }
55
+
56
+ // 5. 自证清单: 记录入口产物摘要与 git 事实, 发布闸门据此核对「产物出自本提交」。
57
+ // 非 git 检出时如实记 null (不拒绝构建); 是否放行发布是 verify 的职责, 构建侧不越权。
58
+ const gitText = (args: string[]): string | null => {
59
+ const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
60
+ return result.status === 0 ? result.stdout.trim() : null;
61
+ };
62
+ const head = gitText(['rev-parse', 'HEAD']);
63
+ const status = gitText(['status', '--porcelain']);
64
+ writeFileSync(
65
+ join(DIST, 'manifest.json'),
66
+ `${JSON.stringify(
67
+ {
68
+ schemaVersion: 1,
69
+ entry: 'index.js',
70
+ entrySha256: createHash('sha256')
71
+ .update(readFileSync(join(DIST, 'index.js')))
72
+ .digest('hex'),
73
+ commit: head,
74
+ dirty: status === null ? null : status.length > 0,
75
+ builtAt: new Date().toISOString(),
76
+ },
77
+ null,
78
+ 2,
79
+ )}\n`,
80
+ );
81
+
82
+ process.exit(0);
@@ -0,0 +1,214 @@
1
+ /**
2
+ * 发布闸门的单元测试 (物理闸门自身的测试义务, 走标准断言):
3
+ * judgeRelease 纯函数逐分支覆盖 + collectFacts 的临时仓库集成采集。
4
+ */
5
+ import { afterEach, describe, expect, test } from 'bun:test';
6
+
7
+ import { spawnSync } from 'node:child_process';
8
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
9
+ import { tmpdir } from 'node:os';
10
+ import { join } from 'node:path';
11
+
12
+ import {
13
+ PACK_FILES_EXPECTED,
14
+ type VerifyFacts,
15
+ collectFacts,
16
+ judgeRelease,
17
+ } from './verify-release.ts';
18
+
19
+ const SHA = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
20
+ const HEAD = '0123456789abcdef0123456789abcdef01234567';
21
+
22
+ const cleanDist = () => ({
23
+ entryExists: true,
24
+ entrySize: 26,
25
+ entrySha256: SHA,
26
+ manifestExists: true,
27
+ manifest: {
28
+ schemaVersion: 1,
29
+ entry: 'index.js',
30
+ entrySha256: SHA,
31
+ commit: HEAD,
32
+ dirty: false,
33
+ builtAt: '2026-09-29T00:00:00.000Z',
34
+ } as Record<string, unknown> | null,
35
+ manifestIssue: null as string | null,
36
+ });
37
+
38
+ const validFacts = (): VerifyFacts => ({
39
+ gitStatus: '',
40
+ gitHead: HEAD,
41
+ dist: cleanDist(),
42
+ dtsTsSpecifierHits: [],
43
+ pack: { files: [...PACK_FILES_EXPECTED], issue: null },
44
+ });
45
+
46
+ describe('judgeRelease 判定链', () => {
47
+ test('四要素齐备放行', () => {
48
+ const verdict = judgeRelease(validFacts());
49
+ expect(verdict.ok).toBe(true);
50
+ if (verdict.ok) {
51
+ expect(verdict.commit).toBe(HEAD);
52
+ expect(verdict.sha256).toBe(SHA);
53
+ }
54
+ });
55
+
56
+ test('非 git 检出 / 脏工作树分别拒绝', () => {
57
+ const notGit = judgeRelease({ ...validFacts(), gitStatus: null });
58
+ expect(notGit.ok).toBe(false);
59
+ if (!notGit.ok) expect(notGit.reason).toContain('读不到 git 状态');
60
+
61
+ const dirty = judgeRelease({
62
+ ...validFacts(),
63
+ gitStatus: ' M packages/x/src/a.ts\n?? scratch.md',
64
+ });
65
+ expect(dirty.ok).toBe(false);
66
+ if (!dirty.ok)
67
+ expect(dirty.reason).toContain('工作树不干净 (未提交改动 2 项');
68
+ });
69
+
70
+ test('清单缺失 / 形状病灶 / 构建时脏 分别拒绝', () => {
71
+ const missing = judgeRelease({
72
+ ...validFacts(),
73
+ dist: { ...cleanDist(), manifestExists: false, manifest: null },
74
+ });
75
+ expect(missing.ok).toBe(false);
76
+ if (!missing.ok) expect(missing.reason).toContain('产物清单缺失');
77
+
78
+ // 形状病灶在采集层落错 (readManifest), 判定层读 manifestIssue 报出
79
+ const badSchema = judgeRelease({
80
+ ...validFacts(),
81
+ dist: {
82
+ ...cleanDist(),
83
+ manifest: null,
84
+ manifestIssue: '清单 schemaVersion 不受支持 (期望 1)',
85
+ },
86
+ });
87
+ expect(badSchema.ok).toBe(false);
88
+ if (!badSchema.ok) expect(badSchema.reason).toContain('schemaVersion');
89
+
90
+ // dirty 非 false (含未知 null) 一律拒: 产物无法自证出自干净构建
91
+ const dirtyBuild = judgeRelease({
92
+ ...validFacts(),
93
+ dist: {
94
+ ...cleanDist(),
95
+ manifest: { ...cleanDist().manifest!, dirty: null },
96
+ },
97
+ });
98
+ expect(dirtyBuild.ok).toBe(false);
99
+ if (!dirtyBuild.ok) expect(dirtyBuild.reason).toContain('脏工作树构建');
100
+ });
101
+
102
+ test('产物非本提交构建 / 摘要不符 / index.js 缺失 分别拒绝', () => {
103
+ const otherCommit = judgeRelease({
104
+ ...validFacts(),
105
+ dist: {
106
+ ...cleanDist(),
107
+ manifest: { ...cleanDist().manifest!, commit: 'f'.repeat(40) },
108
+ },
109
+ });
110
+ expect(otherCommit.ok).toBe(false);
111
+ if (!otherCommit.ok)
112
+ expect(otherCommit.reason).toContain('不是本次提交构建');
113
+
114
+ const swapped = judgeRelease({
115
+ ...validFacts(),
116
+ dist: { ...cleanDist(), entrySha256: 'f'.repeat(64) },
117
+ });
118
+ expect(swapped.ok).toBe(false);
119
+ if (!swapped.ok) expect(swapped.reason).toContain('产物摘要与清单记录不符');
120
+
121
+ const noEntry = judgeRelease({
122
+ ...validFacts(),
123
+ dist: {
124
+ ...cleanDist(),
125
+ entryExists: false,
126
+ entrySize: 0,
127
+ entrySha256: null,
128
+ },
129
+ });
130
+ expect(noEntry.ok).toBe(false);
131
+ if (!noEntry.ok) expect(noEntry.reason).toContain('产物缺失');
132
+ });
133
+
134
+ test('d.ts 残留 .ts specifier / pack 采集失败 / 白名单不符 分别拒绝', () => {
135
+ const dts = judgeRelease({
136
+ ...validFacts(),
137
+ dtsTsSpecifierHits: ['index.d.ts', 'codes.d.ts'],
138
+ });
139
+ expect(dts.ok).toBe(false);
140
+ if (!dts.ok) expect(dts.reason).toContain('index.d.ts, codes.d.ts');
141
+
142
+ const noPack = judgeRelease({
143
+ ...validFacts(),
144
+ pack: { files: null, issue: 'npm pack 跑不起来' },
145
+ });
146
+ expect(noPack.ok).toBe(false);
147
+ if (!noPack.ok) expect(noPack.reason).toContain('采不到');
148
+
149
+ const extra = judgeRelease({
150
+ ...validFacts(),
151
+ pack: { files: [...PACK_FILES_EXPECTED, 'dist/secret.env'], issue: null },
152
+ });
153
+ expect(extra.ok).toBe(false);
154
+ if (!extra.ok) expect(extra.reason).toContain('多出 dist/secret.env');
155
+
156
+ const missing = judgeRelease({
157
+ ...validFacts(),
158
+ pack: {
159
+ files: PACK_FILES_EXPECTED.filter((file) => file !== 'dist/index.js'),
160
+ issue: null,
161
+ },
162
+ });
163
+ expect(missing.ok).toBe(false);
164
+ if (!missing.ok) expect(missing.reason).toContain('缺少 dist/index.js');
165
+ });
166
+ });
167
+
168
+ describe('collectFacts 集成采集', () => {
169
+ const dirs: string[] = [];
170
+ afterEach(() => {
171
+ for (const dir of dirs.splice(0))
172
+ rmSync(dir, { recursive: true, force: true });
173
+ });
174
+
175
+ test('临时仓库: git 事实 / 清单 / 摘要 / d.ts 复查 / pack 清单逐项落地', () => {
176
+ const root = mkdtempSync(join(tmpdir(), 'sweep-verify-'));
177
+ dirs.push(root);
178
+ const git = (args: string[]) =>
179
+ spawnSync('git', args, { cwd: root, encoding: 'utf8' });
180
+ git(['init', '-q']);
181
+ writeFileSync(
182
+ join(root, 'package.json'),
183
+ JSON.stringify({
184
+ name: 'probe-verify-pkg',
185
+ version: '0.0.1',
186
+ files: ['dist'],
187
+ }),
188
+ );
189
+ mkdirSync(join(root, 'dist'));
190
+ writeFileSync(join(root, 'dist/index.js'), 'export const x = 1;\n');
191
+ writeFileSync(
192
+ join(root, 'dist/index.d.ts'),
193
+ "export { x } from './index.js';\n",
194
+ );
195
+ writeFileSync(join(root, 'dist/bad.d.ts'), "export { y } from './y.ts';\n");
196
+ git(['add', '-A']);
197
+ git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']);
198
+
199
+ const facts = collectFacts(root);
200
+ expect(facts.gitStatus).toBe('');
201
+ expect(facts.gitHead).toMatch(/^[0-9a-f]{40}$/);
202
+ expect(facts.dist.manifest).toBeNull();
203
+ expect(facts.dist.entrySha256).toMatch(/^[0-9a-f]{64}$/);
204
+ expect(facts.dtsTsSpecifierHits).toEqual(['bad.d.ts']);
205
+ expect(facts.pack.files).toEqual(
206
+ [
207
+ 'dist/bad.d.ts',
208
+ 'dist/index.d.ts',
209
+ 'dist/index.js',
210
+ 'package.json',
211
+ ].sort(),
212
+ );
213
+ });
214
+ });
@@ -0,0 +1,152 @@
1
+ /**
2
+ * 发布侧闸门 (API 包): 共享判定库 (scripts/lib/release-verify.ts, 与 CLI 包同源, 结构对称)
3
+ * + API 专属项 —— d.ts specifier 复查 (消费方 TS 解析的硬前提)。
4
+ *
5
+ * 判定序: 检出可信 (git 可读 / 有提交 / 工作树干净) → 产物就位 (存在 / 非空 / 可读) →
6
+ * 清单与提交、产物对账 → d.ts 复查 (专属) → 面包白名单。
7
+ *
8
+ * 由 package.json 的 prepublishOnly (`npm run build && npm run verify:release`) 在构建后调用,
9
+ * 手动复核即 `bun run verify:release`。
10
+ *
11
+ * 模板骨架: 替换示例实现时, 须同步 PACK_FILES_EXPECTED 与 dist 实际产物 (本仓的判定链测试
12
+ * scripts/verify-release.test.ts 是快照资产, 导出面保持不变即可继续覆盖判定).
13
+ *
14
+ * 用法: bun scripts/verify-release.ts
15
+ * 退出码: 0 通过; 1 拒绝 (原因与处置见 stderr)
16
+ */
17
+ import { readFileSync, readdirSync } from 'node:fs';
18
+ import { join, resolve } from 'node:path';
19
+
20
+ import {
21
+ type ReleaseFacts,
22
+ type ReleaseVerdict,
23
+ type VerifyProfile,
24
+ judgeRelease as judgeReleaseCommon,
25
+ normalizeCommit,
26
+ readDistState,
27
+ readGitText,
28
+ readPackFiles,
29
+ } from '../../../scripts/lib/release-verify.ts';
30
+
31
+ export const PACKAGE_ROOT = resolve(import.meta.dir, '..');
32
+
33
+ /**
34
+ * 发行面包的期望文件集: files 白名单 (dist) 的物化 + npm 强制包含项 (README / LICENSE /
35
+ * package.json)。增删产物文件 (如新增源模块的 .d.ts) 须同步本表, 闸门拒绝时会指出差集。
36
+ */
37
+ export const PACK_FILES_EXPECTED: readonly string[] = [
38
+ 'LICENSE',
39
+ 'README.md',
40
+ 'README.zh-CN.md',
41
+ 'package.json',
42
+ 'dist/index.d.ts',
43
+ 'dist/index.js',
44
+ 'dist/manifest.json',
45
+ ];
46
+
47
+ /** API 侧闸门坐标 (差异面收口) */
48
+ const PROFILE: VerifyProfile = {
49
+ entryFile: 'index.js',
50
+ manifestFile: 'manifest.json',
51
+ shaField: 'entrySha256',
52
+ schemaVersion: 1,
53
+ packExpected: PACK_FILES_EXPECTED,
54
+ };
55
+
56
+ /** 构建侧写下的自证清单 (scripts/build.ts 第 5 步; 字段契约见该处) */
57
+ export interface DistManifest {
58
+ schemaVersion: number;
59
+ entry: string;
60
+ entrySha256: string;
61
+ commit: string | null;
62
+ dirty: boolean | null;
63
+ builtAt: string;
64
+ }
65
+
66
+ /** 判定所需的全部事实 (采集纯读取; 测试可注入构造的现场) */
67
+ export type VerifyFacts = ReleaseFacts & {
68
+ /** 含 '.ts' specifier 残留的 d.ts 文件名; 空数组即干净 */
69
+ dtsTsSpecifierHits: string[];
70
+ };
71
+
72
+ export type VerifyVerdict = ReleaseVerdict;
73
+
74
+ /** d.ts specifier 残留检查: 后处理 (build.ts 第 4 步) 失效或手工产物混入的确定性信号 */
75
+ const dtsHits = (distDir: string): string[] => {
76
+ const hits: string[] = [];
77
+ try {
78
+ for (const file of readdirSync(distDir)) {
79
+ if (!file.endsWith('.d.ts')) continue;
80
+ const text = readFileSync(join(distDir, file), 'utf8');
81
+ if (
82
+ /from\s+['"]\.[^'"]+\.ts['"]/.test(text) ||
83
+ /import\s+['"]\.[^'"]+\.ts['"]/.test(text)
84
+ )
85
+ hits.push(file);
86
+ }
87
+ } catch {
88
+ // dist 不在: 产物缺失由判定层统一报出, 此处保持空集
89
+ }
90
+ return hits;
91
+ };
92
+
93
+ /**
94
+ * 采事实: 两条只读 git 命令 + 读 dist 产物与清单 + d.ts 复查 + 一次只读的 npm pack。
95
+ * 外部副作用:无 (全部只读)。
96
+ */
97
+ export const collectFacts = (root: string): VerifyFacts => {
98
+ const distDir = join(root, 'dist');
99
+ return {
100
+ gitStatus: readGitText(root, ['status', '--porcelain']),
101
+ gitHead: normalizeCommit(readGitText(root, ['rev-parse', 'HEAD'])),
102
+ dist: readDistState(distDir, PROFILE),
103
+ dtsTsSpecifierHits: dtsHits(distDir),
104
+ pack: readPackFiles(root),
105
+ };
106
+ };
107
+
108
+ /**
109
+ * 判定 (纯函数): 委托共享库按统一判定序执行; API 专属项 (d.ts 残留) 作为扩展判定注入
110
+ * (位于产物链检查之后、面包白名单之前)。
111
+ */
112
+ export const judgeRelease = (facts: VerifyFacts): VerifyVerdict =>
113
+ judgeReleaseCommon(facts, PROFILE, () =>
114
+ facts.dtsTsSpecifierHits.length > 0
115
+ ? `d.ts 残留 '.ts' specifier (消费方 TS 解析不了): ${facts.dtsTsSpecifierHits.join(', ')}; 检查 build 的 d.ts 后处理`
116
+ : null,
117
+ );
118
+
119
+ /** 输出面 (注入以便测试捕获; CLI 直写 process) */
120
+ export interface ReleaseIo {
121
+ out: (line: string) => void;
122
+ err: (line: string) => void;
123
+ }
124
+
125
+ /** 跑一次发布前置校验: 采事实 → judgeRelease → 输出结论与退出码 */
126
+ export const verifyRelease = (
127
+ root: string,
128
+ io: ReleaseIo,
129
+ facts: VerifyFacts = collectFacts(root),
130
+ ): number => {
131
+ const verdict = judgeRelease(facts);
132
+ if (verdict.ok) {
133
+ io.out(
134
+ `发布前置校验通过: 提交 ${verdict.commit.slice(0, 7)} · 产物摘要 ${verdict.sha256.slice(0, 7)}`,
135
+ );
136
+ return 0;
137
+ }
138
+ io.err(`发布前置校验未通过: ${verdict.reason}`);
139
+ io.err(
140
+ ' 处置: 工作树不干净就提交或 stash 后重新构建再发 (bun run build 会同时写产物与清单);' +
141
+ ' 发行面包内文件与白名单不符就清掉多余文件或同步 PACK_FILES_EXPECTED。',
142
+ );
143
+ return 1;
144
+ };
145
+
146
+ // 被测试 import 时不得跑入口 (只有直接运行才落退出码)
147
+ if (import.meta.main) {
148
+ process.exitCode = verifyRelease(PACKAGE_ROOT, {
149
+ out: (line) => process.stdout.write(`${line}\n`),
150
+ err: (line) => process.stderr.write(`${line}\n`),
151
+ });
152
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * 示例包入口 (模板骨架): 展示最小可用的可编程 API 形状 —— 具名导出 + 参数对象 + 文档注释。
3
+ *
4
+ * 生成后的项目应把它替换为自己的领域实现 (并同步包 README 与包级文档)。
5
+ * 注意: 模板内的代码标识符避开与占位词汇同名的插值形态, 防生成期变量替换误伤。
6
+ */
7
+
8
+ /** 问候选项 */
9
+ export interface GreetOptions {
10
+ /** 要问候的名字 */
11
+ who: string;
12
+ }
13
+
14
+ /** 生成一句问候语 (示例实现, 无外部依赖) */
15
+ export const greet = ({ who }: GreetOptions): string => `Hello, ${who}!`;
@@ -0,0 +1,12 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": {
4
+ "noEmit": false,
5
+ "emitDeclarationOnly": true,
6
+ "declaration": true,
7
+ "rootDir": "src",
8
+ "outDir": "dist"
9
+ },
10
+ "include": ["src"],
11
+ "exclude": ["src/**/*.test.ts", "src/**/*smoke.ts", "src/fixtures.ts"]
12
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "extends": "../../tsconfig.json",
3
+ // 示例包只含 src; 需要额外目录 (如本地基准 / 脚本) 时自行补进 include 面
4
+ "include": ["src"]
5
+ }
@@ -0,0 +1,3 @@
1
+ # Changelog
2
+
3
+ All notable changes to this package are documented in this file. Entries are written by the release chain (semantic-release) on the first release.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 {{OWNER}}
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,35 @@
1
+ # {{SCOPE}}/{{NAME}}-cli
2
+
3
+ <!-- 模板骨架: 示例命令是 {{BIN_NAME}} --name <名字>; 换成自己的命令后, 同步本节与包内文档。 -->
4
+
5
+ The command-line tool of this collection: a thin shell over the API package ([{{SCOPE}}/{{NAME}}](../{{NAME}}/README.md)), where the domain logic lives.
6
+
7
+ ## Install
8
+
9
+ ```shell
10
+ npm install -g {{SCOPE}}/{{NAME}}-cli
11
+ ```
12
+
13
+ ## Usage
14
+
15
+ ```shell
16
+ # 打印一句问候 (示例)
17
+ {{BIN_NAME}} --name world
18
+
19
+ # 查看命令帮助
20
+ {{BIN_NAME}} --help
21
+ ```
22
+
23
+ ## Development
24
+
25
+ ```shell
26
+ # 类型检查与测试 (在包目录内)
27
+ bun run typecheck && bun run test
28
+
29
+ # 打包发布产物 (dist/) 并跑发布自证闸门 (自证要求干净工作树)
30
+ bun run build && bun run verify:release
31
+ ```
32
+
33
+ ## Documentation
34
+
35
+ - [Package docs](docs/README.md): the package-level entry (designs and ADRs).