create-clis 1.0.0 → 1.2.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 (88) hide show
  1. package/README.md +22 -14
  2. package/README.zh-CN.md +22 -14
  3. package/assets/manifest.json +7 -2
  4. package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +15 -29
  5. package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +6 -12
  6. package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +3 -3
  7. package/assets/template/.github/workflows/ci.yml +69 -7
  8. package/assets/template/.github/workflows/release.yml +23 -23
  9. package/assets/template/.gitignorerc.json +1 -8
  10. package/assets/template/.oxlintrc.json +1 -6
  11. package/assets/template/.prettierignore +0 -1
  12. package/assets/template/.releaserc.json +6 -1
  13. package/assets/template/.vscode/launch.json +1 -1
  14. package/assets/template/.vscode/settings.json +1 -0
  15. package/assets/template/.vscode/tasks.json +45 -0
  16. package/assets/template/AGENTS.md +4 -4
  17. package/assets/template/CONTRIBUTING.md +6 -4
  18. package/assets/template/CONTRIBUTING.zh-CN.md +6 -4
  19. package/assets/template/_gitignore +7 -405
  20. package/assets/template/bunfig.toml +2 -11
  21. package/assets/template/docs/README.md +6 -6
  22. package/assets/template/docs/adrs/README.md +4 -2
  23. package/assets/template/docs/development.md +15 -9
  24. package/assets/template/lefthook.yml +20 -30
  25. package/assets/template/package.json +5 -6
  26. package/assets/template/packages/{{NAME}}/README.md +4 -4
  27. package/assets/template/packages/{{NAME}}/README.zh-CN.md +2 -2
  28. package/assets/template/packages/{{NAME}}/package.json +3 -1
  29. package/assets/template/packages/{{NAME}}/scripts/build.ts +50 -14
  30. package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +140 -15
  31. package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +27 -14
  32. package/assets/template/packages/{{NAME}}/tsconfig.build.json +1 -1
  33. package/assets/template/packages/{{NAME}}-cli/README.md +9 -6
  34. package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +6 -3
  35. package/assets/template/packages/{{NAME}}-cli/bin/bunfig.toml +3 -0
  36. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +43 -21
  37. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +8 -17
  38. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +6 -3
  39. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +189 -107
  40. package/assets/template/packages/{{NAME}}-cli/package.json +3 -2
  41. package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +24 -73
  42. package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +8 -3
  43. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +16 -10
  44. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +8 -52
  45. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +3 -3
  46. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +8 -68
  47. package/assets/template/packages/{{NAME}}-cli/src/cli.ts +51 -11
  48. package/assets/template/scripts/ci.ts +285 -64
  49. package/assets/template/scripts/install-git-hooks.mjs +10 -0
  50. package/assets/template/scripts/install-git-hooks.test.ts +1 -1
  51. package/assets/template/scripts/lib/npm-trust-parse.ts +169 -0
  52. package/assets/template/scripts/lib/release-cli.ts +299 -0
  53. package/assets/template/scripts/lib/release-verify.ts +148 -15
  54. package/assets/template/scripts/lib/workspace.test.ts +63 -1
  55. package/assets/template/scripts/lib/workspace.ts +132 -42
  56. package/assets/template/scripts/lint-dependency-direction.test.ts +131 -0
  57. package/assets/template/scripts/lint-dependency-direction.ts +130 -0
  58. package/assets/template/scripts/lint-doc-examples.test.ts +45 -9
  59. package/assets/template/scripts/lint-doc-examples.ts +227 -50
  60. package/assets/template/scripts/lint-doc-references.test.ts +36 -0
  61. package/assets/template/scripts/lint-doc-references.ts +142 -57
  62. package/assets/template/scripts/lint-doc-shared.ts +26 -23
  63. package/assets/template/scripts/lint-stray-backups.test.ts +3 -1
  64. package/assets/template/scripts/lint-stray-backups.ts +7 -3
  65. package/assets/template/scripts/npm-trust-guard.test.ts +56 -8
  66. package/assets/template/scripts/npm-trust-guard.ts +116 -200
  67. package/assets/template/scripts/safe-install.ts +28 -23
  68. package/assets/template/scripts/transcription/api-harness.ts +28 -206
  69. package/assets/template/scripts/transcription/compare.test.ts +84 -0
  70. package/assets/template/scripts/transcription/compare.ts +4 -4
  71. package/assets/template/scripts/transcription/corpus.ts +9 -3
  72. package/assets/template/scripts/transcription/fixture.ts +2 -4
  73. package/assets/template/scripts/transcription/make-mutants.ts +116 -37
  74. package/assets/template/scripts/transcription/run-conformance.ts +57 -34
  75. package/assets/template/scripts/transcription/validate-coverage.test.ts +11 -14
  76. package/assets/template/scripts/transcription/validate-coverage.ts +8 -10
  77. package/assets/template/scripts/transcription/validate.ts +18 -3
  78. package/assets/template/tsconfig.json +2 -20
  79. package/assets/template/turbo.jsonc +7 -52
  80. package/bin/bunfig.toml +3 -0
  81. package/bin/create-clis.mjs +165 -104
  82. package/dist/create-clis.js +48 -87681
  83. package/dist/manifest.json +3 -3
  84. package/package.json +9 -5
  85. package/assets/template/packages/{{NAME}}/docs/README.md +0 -21
  86. package/assets/template/packages/{{NAME}}-cli/docs/README.md +0 -21
  87. package/bin/create-clis +0 -35
  88. package/bin/create-clis.cmd +0 -32
@@ -1,23 +1,11 @@
1
1
  # Git 钩子门禁 (lefthook)
2
2
  #
3
3
  # 分层策略:
4
- # pre-commit 增量门禁: prettier / oxlint 只扫暂存文件; type-check 例外,
5
- # 不传 {staged_files}, 跑全项目 tsc --noEmit; prettier 格式化后
6
- # 自动重暂存
4
+ # pre-commit 增量门禁: bun fmt / oxlint 只扫暂存文件; type-check 例外,
5
+ # 不传 {staged_files}, 跑全项目 typecheck (覆盖各包与根 scripts/);
6
+ # bun fmt 格式化后自动重暂存
7
7
  # pre-push 全量门禁: rebase / merge / cherry-pick 重放提交不触发 pre-commit,
8
- # base 的改动会让本次提交产生「语义冲突」(如 import 失配),
9
8
  # push 是代码外流的唯一必经闸门, 在此全量只读兜底
10
- #
11
- # 注意 {staged_files} 模板只在 pre-commit 阶段成立, push 阶段没有暂存区概念,
12
- # 因此 pre-push 一律只读: prettier 用 --check 而非 --write, 不设 stage_fixed
13
- # (--write 在 push 阶段是纯副作用: 改动进不了正在推送的提交, 只在本地凭空多出
14
- # 未提交改动)。
15
- #
16
- # 执行链的 lefthook 取用: 官方生成的钩子模板探测链不含 bunx, 且默认「找不到即
17
- # 静默放行」(门禁悄悄失效); 这里用官方两个配置键补齐 —— lefthook: 指定经 bunx
18
- # 取 pin 版 (无全局 lefthook 的机器也能跑, 与 LEFTHOOK_BIN / PATH 的优先级由
19
- # 模板决定), assert_lefthook_installed: true 让整链失败时退非零而非静默通过。
20
- # 依据见 ADR 0005 决策第 1 条。
21
9
 
22
10
  lefthook: bunx lefthook@2.1.14
23
11
  assert_lefthook_installed: true
@@ -25,31 +13,33 @@ assert_lefthook_installed: true
25
13
  pre-commit:
26
14
  parallel: false
27
15
  commands:
28
- # TypeScript 类型检查 (两包, 经 turbo 编排): 不传 {staged_files}, 天然全项目执行
16
+ # TypeScript 类型检查 (全仓包 + 根 scripts/, 单源复用根 package.json typecheck)
29
17
  type-check:
30
- glob: '*.{ts,tsx,mts,mjs}'
31
- run: bunx turbo run typecheck
18
+ glob: '*.{ts,tsx,mts,mjs,js,cjs}'
19
+ run: bun run typecheck
32
20
 
33
- # JS/TS (含 .mts / .mjs): prettier 格式化后自动重暂存, 再 oxlint
34
- prettier-js:
35
- glob: '*.{ts,tsx,mts,mjs}'
36
- run: bunx prettier --write --log-level error {staged_files}
21
+ # JS/TS (含 .mts / .mjs / .js / .cjs): bun fmt 格式化后自动重暂存, 再 oxlint
22
+ fmt-js:
23
+ glob: '*.{ts,tsx,mts,mjs,js,cjs}'
24
+ run: bun fmt --log-level=error --no-error-on-unmatched-pattern {staged_files}
37
25
  stage_fixed: true
38
26
 
27
+ # --no-error-on-unmatched-pattern: 暂存文件若全落在 .oxlintrc.json 的
28
+ # ignorePatterns 内 (如各包的模板源码空间), oxlint 收不到可检文件,
29
+ # 默认以空集错误退出 1 并拦死提交。该旗标把这种情形视为无需检查。
39
30
  oxlint:
40
- glob: '*.{ts,tsx,mts,mjs}'
41
- run: bunx oxlint {staged_files}
31
+ glob: '*.{ts,tsx,mts,mjs,js,cjs}'
32
+ run: bun x --no-install oxlint --no-error-on-unmatched-pattern {staged_files}
42
33
 
43
- # 非 JS/TS: 仅 prettier 格式化
44
- prettier-other:
45
- glob: '*.{md,mdx,json,yaml,yml}'
46
- run: bunx prettier --write --log-level error {staged_files}
34
+ # 非 JS/TS: 仅 bun fmt 格式化
35
+ fmt-other:
36
+ glob: '*.{md,mdx,json,jsonc,yaml,yml}'
37
+ run: bun fmt --log-level=error --no-error-on-unmatched-pattern {staged_files}
47
38
  stage_fixed: true
48
39
 
49
40
  pre-push:
50
41
  parallel: false
51
42
  commands:
52
- # 全量预演 (验证组 + 验收组): 步骤集合的单一事实来源在 scripts/ci.ts,
53
- # 与 CI 的两个 job 及 Release 的 verify job 同集合, 此处不再逐项枚举
43
+ # 全量预演 (验证组 + 验收组): 步骤集合的单一事实来源在 scripts/ci.ts
54
44
  ci:
55
45
  run: bun run ci
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "{{NAME}}-monorepo",
3
3
  "private": true,
4
- "packageManager": "bun@1.4.2",
4
+ "packageManager": "bun@1.4.5",
5
5
  "author": "{{OWNER}} (https://github.com/{{OWNER}})",
6
6
  "license": "MIT",
7
7
  "type": "module",
@@ -15,10 +15,11 @@
15
15
  "safe-install": "bun scripts/safe-install.ts",
16
16
  "prepare": "node scripts/install-git-hooks.mjs || exit 0",
17
17
  "build": "turbo run build",
18
- "typecheck": "turbo run typecheck && tsc --noEmit",
18
+ "typecheck": "turbo run typecheck && bun check",
19
19
  "lint": "oxlint",
20
20
  "lint:fix": "oxlint --fix",
21
- "format": "prettier --write .",
21
+ "format": "bun fmt",
22
+ "format-check": "bun fmt --check",
22
23
  "test": "turbo run test && bun test scripts/",
23
24
  "conformance": "bun scripts/transcription/run-conformance.ts",
24
25
  "ci": "bun scripts/ci.ts"
@@ -27,10 +28,8 @@
27
28
  "@lidofinance/multi-semantic-release": "1.0.3",
28
29
  "@semantic-release/changelog": "7.0.0",
29
30
  "@semantic-release/git": "11.0.1",
30
- "@trivago/prettier-plugin-sort-imports": "6.0.2",
31
- "@types/bun": "1.4.2",
31
+ "@types/bun": "1.4.4",
32
32
  "oxlint": "1.85.0",
33
- "prettier": "3.9.9",
34
33
  "semantic-release": "25.0.9",
35
34
  "turbo": "2.11.5",
36
35
  "typescript": "7.0.2"
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- 模板骨架: 示例包的可编程 API 是一个 greet 占位实现; 换成自己的领域逻辑后, 同步本节与包内文档。 -->
4
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)).
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]({{REPO_URL}}/blob/main/packages/{{NAME}}-cli/README.md)).
6
6
 
7
7
  ## Install
8
8
 
@@ -21,13 +21,13 @@ console.log(greet({ who: 'world' })); // Hello, world!
21
21
  ## Development
22
22
 
23
23
  ```shell
24
- # 类型检查与测试 (在包目录内)
24
+ # Typecheck and test (inside the package directory)
25
25
  bun run typecheck && bun run test
26
26
 
27
- # 打包发布产物 (dist/) 并跑发布自证闸门 (自证要求干净工作树)
27
+ # Bundle release artifacts (dist/) and run the pre-release gate (requires a clean git tree)
28
28
  bun run build && bun run verify:release
29
29
  ```
30
30
 
31
31
  ## Documentation
32
32
 
33
- - [Package docs](docs/README.md): the package-level entry (designs and ADRs).
33
+ - [Repository docs]({{REPO_URL}}/blob/main/docs/README.md): repository-level governance, designs, and development guide; create `docs/` inside this package on demand once package-specific designs or ADRs exist.
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- 模板骨架: 示例包的可编程 API 是一个 greet 占位实现; 换成自己的领域逻辑后, 同步本节与包内文档。 -->
4
4
 
5
- 本集合仓的可编程 API 包: 示例实现换成自己的领域逻辑即可; 命令行面在同级 CLI 包 ([{{SCOPE}}/{{NAME}}-cli](../{{NAME}}-cli/README.zh-CN.md))。
5
+ 本集合仓的可编程 API 包: 示例实现换成自己的领域逻辑即可; 命令行面在同级 CLI 包 ([{{SCOPE}}/{{NAME}}-cli]({{REPO_URL}}/blob/main/packages/{{NAME}}-cli/README.zh-CN.md))。
6
6
 
7
7
  ## 安装
8
8
 
@@ -30,4 +30,4 @@ bun run build && bun run verify:release
30
30
 
31
31
  ## 文档
32
32
 
33
- - [包级文档入口](docs/README.md): 包内设计与包级 ADR 的登记入口。
33
+ - [仓库文档索引]({{REPO_URL}}/blob/main/docs/README.md): 仓库级治理、设计与开发指南; 本包存在专属设计或包级 ADR 时再按需在本包下创建 `docs/` 目录。
@@ -14,6 +14,8 @@
14
14
  },
15
15
  "type": "module",
16
16
  "sideEffects": false,
17
+ "main": "./dist/index.js",
18
+ "types": "./dist/index.d.ts",
17
19
  "exports": {
18
20
  ".": {
19
21
  "types": "./dist/index.d.ts",
@@ -32,7 +34,7 @@
32
34
  },
33
35
  "scripts": {
34
36
  "build": "bun scripts/build.ts",
35
- "typecheck": "tsc --noEmit",
37
+ "typecheck": "bun check",
36
38
  "test": "bun test",
37
39
  "verify:release": "bun scripts/verify-release.ts",
38
40
  "prepublishOnly": "npm run build && npm run verify:release"
@@ -1,21 +1,36 @@
1
1
  /**
2
- * API 包构建脚本: 清产物 → bun build 出 JS → tsc 出类型声明 → d.ts specifier 后处理。
2
+ * API 包构建脚本: 清产物 → bun build 出 JS → tsc 出类型声明 → d.ts specifier 后处理 → 自证清单。
3
3
  * 与 CLI 包 scripts/ 同风格 (bun 直跑, 失败非零退出); 是发布闸门 (prepublishOnly) 的第一步。
4
4
  *
5
5
  * 为什么有第 4 步 (d.ts 后处理): 源码 import 一律带 '.ts' 扩展 (allowImportingTsExtensions,
6
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 两处形态, 不触其余文本; 幂等)。
7
+ * (未开 allowImportingTsExtensions) 解析不了这种 specifier; 故在产物层确定性改写为 '.js'
8
+ * (只动相对 specifier 形态, 不触其余文本; 幂等)。
10
9
  */
11
10
  import { spawnSync } from 'node:child_process';
12
11
  import { createHash } from 'node:crypto';
13
12
  import { readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
14
13
  import { join } from 'node:path';
15
14
 
15
+ import { cleanGitEnv } from '../../../scripts/lib/git-env.ts';
16
+
16
17
  const ROOT = join(import.meta.dir, '..');
17
18
  const DIST = join(ROOT, 'dist');
18
19
 
20
+ /** 非公开内部实现模块产出的 .d.ts (不被 index.d.ts 链引用时可在此登记清理出发行面) */
21
+ const INTERNAL_DTS_FILES: readonly string[] = [];
22
+
23
+ /** 递归收集目录下全部 .d.ts 文件的绝对路径 */
24
+ function collectDtsFiles(dir: string): string[] {
25
+ const out: string[] = [];
26
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
27
+ const abs = join(dir, entry.name);
28
+ if (entry.isDirectory()) out.push(...collectDtsFiles(abs));
29
+ else if (entry.isFile() && entry.name.endsWith('.d.ts')) out.push(abs);
30
+ }
31
+ return out;
32
+ }
33
+
19
34
  // 1. 清产物: 整目录重建, 防上一轮构建的残留文件混进发布包 (files 白名单整目录进包)
20
35
  rmSync(DIST, { recursive: true, force: true });
21
36
 
@@ -32,31 +47,52 @@ const bundle = spawnSync(
32
47
  );
33
48
  if (bundle.status !== 0) process.exit(bundle.status ?? 1);
34
49
 
35
- // 3. 类型声明: 独立 tsconfig (emitDeclarationOnly; 测试 / smoke / fixtures 已在 exclude)
50
+ // 3. 类型声明: 独立 tsconfig (emitDeclarationOnly; 测试 / smoke 已在 exclude)
36
51
  const types = spawnSync(
37
- 'bunx',
38
- ['tsc', '-p', join(ROOT, 'tsconfig.build.json')],
52
+ 'bun',
53
+ ['x', '--no-install', 'tsc', '-p', join(ROOT, 'tsconfig.build.json')],
39
54
  {
40
55
  stdio: 'inherit',
41
56
  },
42
57
  );
43
58
  if (types.status !== 0) process.exit(types.status ?? 1);
44
59
 
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);
60
+ // 3.5 清理内部实现 .d.ts (按需在 INTERNAL_DTS_FILES 登记不对外暴露的内部模块声明)
61
+ for (const file of INTERNAL_DTS_FILES) {
62
+ rmSync(join(DIST, file), { force: true });
63
+ }
64
+
65
+ // 4. d.ts specifier 后处理 (递归覆盖 dist/ 全树, 匹配 from / import / import('...') 三种形态)
66
+ const dtsFiles = collectDtsFiles(DIST);
67
+ const internalStems = INTERNAL_DTS_FILES.map((file) =>
68
+ file.slice(0, -'.d.ts'.length),
69
+ );
70
+ for (const path of dtsFiles) {
49
71
  const before = readFileSync(path, 'utf8');
50
72
  const after = before
51
73
  .replace(/(from\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3')
52
- .replace(/(import\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3');
74
+ .replace(/(import\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3')
75
+ .replace(/(import\(\s*['"])(\.[^'"]+)\.ts(['"]\s*\))/g, '$1$2.js$3');
53
76
  if (after !== before) writeFileSync(path, after);
77
+ // 防御自检: 确认剩余公开 .d.ts 未引用任何已被清理的内部模块
78
+ for (const stem of internalStems) {
79
+ if (new RegExp(`['"]\\./${stem}\\.(?:js|ts)['"]`).test(after)) {
80
+ process.stderr.write(
81
+ `构建失败: ${path} 仍引用了被排除的内部模块 ${stem}\n`,
82
+ );
83
+ process.exit(1);
84
+ }
85
+ }
54
86
  }
55
87
 
56
88
  // 5. 自证清单: 记录入口产物摘要与 git 事实, 发布闸门据此核对「产物出自本提交」。
57
- // 非 git 检出时如实记 null (不拒绝构建); 是否放行发布是 verify 的职责, 构建侧不越权。
89
+ // 非 git 检出时如实记 null (不拒绝构建); env 经 cleanGitEnv 防 git 钩子坐标劫持。
58
90
  const gitText = (args: string[]): string | null => {
59
- const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
91
+ const result = spawnSync('git', args, {
92
+ cwd: ROOT,
93
+ encoding: 'utf8',
94
+ env: cleanGitEnv(),
95
+ });
60
96
  return result.status === 0 ? result.stdout.trim() : null;
61
97
  };
62
98
  const head = gitText(['rev-parse', 'HEAD']);
@@ -9,11 +9,14 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
9
9
  import { tmpdir } from 'node:os';
10
10
  import { join } from 'node:path';
11
11
 
12
+ import { cleanGitEnv } from '../../../scripts/lib/git-env.ts';
13
+ import { resolveNpmCommand } from '../../../scripts/lib/release-verify.ts';
12
14
  import {
13
15
  PACK_FILES_EXPECTED,
14
16
  type VerifyFacts,
15
17
  collectFacts,
16
18
  judgeRelease,
19
+ verifyRelease,
17
20
  } from './verify-release.ts';
18
21
 
19
22
  const SHA = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
@@ -163,20 +166,42 @@ describe('judgeRelease 判定链', () => {
163
166
  expect(missing.ok).toBe(false);
164
167
  if (!missing.ok) expect(missing.reason).toContain('缺少 dist/index.js');
165
168
  });
169
+ test('verifyRelease: 放行输出使用 12 位 shortHash 对齐共享库', () => {
170
+ const out: string[] = [];
171
+ const err: string[] = [];
172
+ const code = verifyRelease(
173
+ '/unused',
174
+ { out: (line) => out.push(line), err: (line) => err.push(line) },
175
+ validFacts(),
176
+ );
177
+ expect(code).toBe(0);
178
+ expect(err).toEqual([]);
179
+ expect(out[0]).toContain(HEAD.slice(0, 12));
180
+ expect(out[0]).toContain(SHA.slice(0, 12));
181
+ });
166
182
  });
167
183
 
168
184
  describe('collectFacts 集成采集', () => {
169
185
  const dirs: string[] = [];
170
186
  afterEach(() => {
171
187
  for (const dir of dirs.splice(0))
172
- rmSync(dir, { recursive: true, force: true });
188
+ rmSync(dir, {
189
+ recursive: true,
190
+ force: true,
191
+ maxRetries: 5,
192
+ retryDelay: 100,
193
+ });
173
194
  });
174
195
 
175
- test('临时仓库: git 事实 / 清单 / 摘要 / d.ts 复查 / pack 清单逐项落地', () => {
176
- const root = mkdtempSync(join(tmpdir(), 'sweep-verify-'));
196
+ test('临时仓库: git 事实 / 清单 / 摘要 / 递归 d.ts 复查 (含 import 类型查询) / pack 清单逐项落地', () => {
197
+ const root = mkdtempSync(join(tmpdir(), 'pkg-verify-'));
177
198
  dirs.push(root);
178
199
  const git = (args: string[]) =>
179
- spawnSync('git', args, { cwd: root, encoding: 'utf8' });
200
+ spawnSync('git', args, {
201
+ cwd: root,
202
+ encoding: 'utf8',
203
+ env: cleanGitEnv(),
204
+ });
180
205
  git(['init', '-q']);
181
206
  writeFileSync(
182
207
  join(root, 'package.json'),
@@ -186,29 +211,129 @@ describe('collectFacts 集成采集', () => {
186
211
  files: ['dist'],
187
212
  }),
188
213
  );
189
- mkdirSync(join(root, 'dist'));
214
+ mkdirSync(join(root, 'dist/nested'), { recursive: true });
190
215
  writeFileSync(join(root, 'dist/index.js'), 'export const x = 1;\n');
191
216
  writeFileSync(
192
217
  join(root, 'dist/index.d.ts'),
193
218
  "export { x } from './index.js';\n",
194
219
  );
195
220
  writeFileSync(join(root, 'dist/bad.d.ts'), "export { y } from './y.ts';\n");
221
+ writeFileSync(
222
+ join(root, 'dist/nested/query.d.ts'),
223
+ "export type Q = import('../y.ts').Y;\n",
224
+ );
196
225
  git(['add', '-A']);
197
226
  git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']);
198
227
 
199
- const facts = collectFacts(root);
228
+ const skipPack = process.env.CI_SKIP_PACK_TEST === '1';
229
+ const facts = collectFacts(
230
+ root,
231
+ skipPack ? { files: [], issue: null } : undefined,
232
+ );
200
233
  expect(facts.gitStatus).toBe('');
201
234
  expect(facts.gitHead).toMatch(/^[0-9a-f]{40}$/);
202
235
  expect(facts.dist.manifest).toBeNull();
203
236
  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
- );
237
+ expect(facts.dtsTsSpecifierHits).toEqual(['bad.d.ts', 'nested/query.d.ts']);
238
+ if (!skipPack) {
239
+ expect(facts.pack.files).toEqual(
240
+ [
241
+ 'dist/bad.d.ts',
242
+ 'dist/index.d.ts',
243
+ 'dist/index.js',
244
+ 'dist/nested/query.d.ts',
245
+ 'package.json',
246
+ ].sort(),
247
+ );
248
+ }
249
+ }, 30_000);
250
+ });
251
+
252
+ describe('resolveNpmCommand 跨平台调用推导', () => {
253
+ const args = ['pack', '--dry-run', '--json', '--ignore-scripts'];
254
+
255
+ test('POSIX 直接调 npm', () => {
256
+ expect(resolveNpmCommand(args, 'linux', {})).toEqual({
257
+ command: 'npm',
258
+ args,
259
+ });
260
+ });
261
+
262
+ test('Windows 优先走 npm_execpath 的 npm-cli.js', () => {
263
+ const cli = 'C:\\nodejs\\node_modules\\npm\\bin\\npm-cli.js';
264
+ expect(
265
+ resolveNpmCommand(args, 'win32', { npm_execpath: cli }, (p) => p === cli),
266
+ ).toEqual({
267
+ command: 'node',
268
+ args: [cli, ...args],
269
+ });
270
+ });
271
+
272
+ test('Windows 从 PATH 解析 node.exe + npm-cli.js 绕开 .cmd 批处理壳层', () => {
273
+ const nodeDir = 'C:\\Program Files\\nodejs';
274
+ const npmCli = `${nodeDir}\\node_modules\\npm\\bin\\npm-cli.js`;
275
+ const nodeExe = `${nodeDir}\\node.exe`;
276
+ const existing = new Set([npmCli, nodeExe]);
277
+ expect(
278
+ resolveNpmCommand(
279
+ args,
280
+ 'win32',
281
+ { Path: `C:\\Windows;"${nodeDir}"` },
282
+ (p) => existing.has(p),
283
+ ),
284
+ ).toEqual({
285
+ command: nodeExe,
286
+ args: [npmCli, ...args],
287
+ });
288
+ });
289
+
290
+ test('Windows 找不到 npm-cli.js 时回退 ComSpec /d /s /c 单串命令并开启逐字参数透传', () => {
291
+ expect(
292
+ resolveNpmCommand(
293
+ args,
294
+ 'win32',
295
+ { PATH: 'C:\\Windows', ComSpec: 'C:\\Windows\\System32\\cmd.exe' },
296
+ () => false,
297
+ ),
298
+ ).toEqual({
299
+ command: 'C:\\Windows\\System32\\cmd.exe',
300
+ args: [
301
+ '/d',
302
+ '/s',
303
+ '/c',
304
+ '""npm.cmd" pack --dry-run --json --ignore-scripts"',
305
+ ],
306
+ windowsVerbatimArguments: true,
307
+ });
308
+ });
309
+
310
+ test('Windows 回退批处理安全保护含空格/括号/元字符的路径并拒绝引号与换行注入', () => {
311
+ const alwaysExists = () => true;
312
+ const neverExists = () => false;
313
+ expect(
314
+ resolveNpmCommand(
315
+ ['pack', '--cache', 'C:\\Program Files (x86)\\cache&100%'],
316
+ 'win32',
317
+ { PATH: '/usr/bin;relative\\dir', ComSpec: 'cmd.exe' },
318
+ alwaysExists,
319
+ ),
320
+ ).toEqual({
321
+ command: 'cmd.exe',
322
+ args: [
323
+ '/d',
324
+ '/s',
325
+ '/c',
326
+ '""npm.cmd" pack --cache "C:\\Program Files (x86)\\cache&100"^^^%"',
327
+ ],
328
+ windowsVerbatimArguments: true,
329
+ });
330
+ expect(() =>
331
+ resolveNpmCommand(
332
+ ['pack', 'bad"arg'],
333
+ 'win32',
334
+ { PATH: 'C:\\Windows' },
335
+ neverExists,
336
+ ),
337
+ ).toThrow(/不可安全转义/);
213
338
  });
214
339
  });
@@ -18,6 +18,7 @@ import { readFileSync, readdirSync } from 'node:fs';
18
18
  import { join, resolve } from 'node:path';
19
19
 
20
20
  import {
21
+ type PackFacts,
21
22
  type ReleaseFacts,
22
23
  type ReleaseVerdict,
23
24
  type VerifyProfile,
@@ -26,6 +27,7 @@ import {
26
27
  readDistState,
27
28
  readGitText,
28
29
  readPackFiles,
30
+ shortHash,
29
31
  } from '../../../scripts/lib/release-verify.ts';
30
32
 
31
33
  export const PACKAGE_ROOT = resolve(import.meta.dir, '..');
@@ -71,37 +73,48 @@ export type VerifyFacts = ReleaseFacts & {
71
73
 
72
74
  export type VerifyVerdict = ReleaseVerdict;
73
75
 
74
- /** d.ts specifier 残留检查: 后处理 (build.ts 第 4 步) 失效或手工产物混入的确定性信号 */
76
+ /** 匹配残留相对 .ts specifier: from '...' / import '...' / import('./...ts') */
77
+ const DTS_TS_SPECIFIER_RE =
78
+ /(?:from\s+['"]|import\s+['"]|import\(\s*['"])\.[^'"]+\.ts['"]/;
79
+
80
+ /** d.ts specifier 残留检查: 递归扫描 dist/ 全树 (后处理失效或手工产物混入的确定性信号) */
75
81
  const dtsHits = (distDir: string): string[] => {
76
82
  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);
83
+ const walk = (dir: string, prefix: string): void => {
84
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
85
+ const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
86
+ const abs = join(dir, entry.name);
87
+ if (entry.isDirectory()) {
88
+ walk(abs, rel);
89
+ } else if (entry.isFile() && entry.name.endsWith('.d.ts')) {
90
+ const text = readFileSync(abs, 'utf8');
91
+ if (DTS_TS_SPECIFIER_RE.test(text)) hits.push(rel);
92
+ }
86
93
  }
94
+ };
95
+ try {
96
+ walk(distDir, '');
87
97
  } catch {
88
98
  // dist 不在: 产物缺失由判定层统一报出, 此处保持空集
89
99
  }
90
- return hits;
100
+ return hits.sort();
91
101
  };
92
102
 
93
103
  /**
94
104
  * 采事实: 两条只读 git 命令 + 读 dist 产物与清单 + d.ts 复查 + 一次只读的 npm pack。
95
105
  * 外部副作用:无 (全部只读)。
96
106
  */
97
- export const collectFacts = (root: string): VerifyFacts => {
107
+ export const collectFacts = (
108
+ root: string,
109
+ packOverride?: PackFacts,
110
+ ): VerifyFacts => {
98
111
  const distDir = join(root, 'dist');
99
112
  return {
100
113
  gitStatus: readGitText(root, ['status', '--porcelain']),
101
114
  gitHead: normalizeCommit(readGitText(root, ['rev-parse', 'HEAD'])),
102
115
  dist: readDistState(distDir, PROFILE),
103
116
  dtsTsSpecifierHits: dtsHits(distDir),
104
- pack: readPackFiles(root),
117
+ pack: packOverride ?? readPackFiles(root),
105
118
  };
106
119
  };
107
120
 
@@ -131,7 +144,7 @@ export const verifyRelease = (
131
144
  const verdict = judgeRelease(facts);
132
145
  if (verdict.ok) {
133
146
  io.out(
134
- `发布前置校验通过: 提交 ${verdict.commit.slice(0, 7)} · 产物摘要 ${verdict.sha256.slice(0, 7)}`,
147
+ `发布前置校验通过: 提交 ${shortHash(verdict.commit)} · 产物摘要 ${shortHash(verdict.sha256)}`,
135
148
  );
136
149
  return 0;
137
150
  }
@@ -8,5 +8,5 @@
8
8
  "outDir": "dist"
9
9
  },
10
10
  "include": ["src"],
11
- "exclude": ["src/**/*.test.ts", "src/**/*smoke.ts", "src/fixtures.ts"]
11
+ "exclude": ["src/**/*.test.ts", "src/**/*smoke.ts"]
12
12
  }
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- 模板骨架: 示例命令是 {{BIN_NAME}} --name <名字>; 换成自己的命令后, 同步本节与包内文档。 -->
4
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.
5
+ The command-line tool of this collection: a thin shell over the API package ([{{SCOPE}}/{{NAME}}]({{REPO_URL}}/blob/main/packages/{{NAME}}/README.md)), where the domain logic lives.
6
6
 
7
7
  ## Install
8
8
 
@@ -13,23 +13,26 @@ npm install -g {{SCOPE}}/{{NAME}}-cli
13
13
  ## Usage
14
14
 
15
15
  ```shell
16
- # 打印一句问候 (示例)
16
+ # Print a greeting (example)
17
17
  {{BIN_NAME}} --name world
18
18
 
19
- # 查看命令帮助
19
+ # Print CLI version (also -V)
20
+ {{BIN_NAME}} --version
21
+
22
+ # Show CLI help (also -h)
20
23
  {{BIN_NAME}} --help
21
24
  ```
22
25
 
23
26
  ## Development
24
27
 
25
28
  ```shell
26
- # 类型检查与测试 (在包目录内)
29
+ # Typecheck and test (inside the package directory)
27
30
  bun run typecheck && bun run test
28
31
 
29
- # 打包发布产物 (dist/) 并跑发布自证闸门 (自证要求干净工作树)
32
+ # Bundle release artifacts (dist/) and run the pre-release gate (requires a clean git tree)
30
33
  bun run build && bun run verify:release
31
34
  ```
32
35
 
33
36
  ## Documentation
34
37
 
35
- - [Package docs](docs/README.md): the package-level entry (designs and ADRs).
38
+ - [Repository docs]({{REPO_URL}}/blob/main/docs/README.md): repository-level governance, designs, and development guide; create `docs/` inside this package on demand once package-specific CLI surface designs exist.
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- 模板骨架: 示例命令是 {{BIN_NAME}} --name <名字>; 换成自己的命令后, 同步本节与包内文档。 -->
4
4
 
5
- 本集合仓的命令行工具: API 包 ([{{SCOPE}}/{{NAME}}](../{{NAME}}/README.zh-CN.md)) 的薄壳, 领域逻辑在 API 包里。
5
+ 本集合仓的命令行工具: API 包 ([{{SCOPE}}/{{NAME}}]({{REPO_URL}}/blob/main/packages/{{NAME}}/README.zh-CN.md)) 的薄壳, 领域逻辑在 API 包里。
6
6
 
7
7
  ## 安装
8
8
 
@@ -16,7 +16,10 @@ npm install -g {{SCOPE}}/{{NAME}}-cli
16
16
  # 打印一句问候 (示例)
17
17
  {{BIN_NAME}} --name world
18
18
 
19
- # 查看命令帮助
19
+ # 查看命令版本号 (亦可 -V)
20
+ {{BIN_NAME}} --version
21
+
22
+ # 查看命令帮助 (亦可 -h)
20
23
  {{BIN_NAME}} --help
21
24
  ```
22
25
 
@@ -32,4 +35,4 @@ bun run build && bun run verify:release
32
35
 
33
36
  ## 文档
34
37
 
35
- - [包级文档入口](docs/README.md): 包内设计与包级 ADR 的登记入口。
38
+ - [仓库文档索引]({{REPO_URL}}/blob/main/docs/README.md): 仓库级治理、设计与开发指南; 本包存在专属 CLI 命令面设计时再按需在本包下创建 `docs/` 目录。
@@ -0,0 +1,3 @@
1
+ # CLI 启动器隔离配置: 禁止自动加载当前工作目录的 bunfig.toml (防 preload 劫持与坏配置崩溃) 与 .env
2
+ preload = []
3
+ env = false