create-clis 1.0.0 → 1.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 (87) 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 +6 -6
  34. package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +2 -2
  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/scripts/ci.ts +285 -64
  48. package/assets/template/scripts/install-git-hooks.mjs +10 -0
  49. package/assets/template/scripts/install-git-hooks.test.ts +1 -1
  50. package/assets/template/scripts/lib/npm-trust-parse.ts +169 -0
  51. package/assets/template/scripts/lib/release-cli.ts +299 -0
  52. package/assets/template/scripts/lib/release-verify.ts +148 -15
  53. package/assets/template/scripts/lib/workspace.test.ts +63 -1
  54. package/assets/template/scripts/lib/workspace.ts +132 -42
  55. package/assets/template/scripts/lint-dependency-direction.test.ts +131 -0
  56. package/assets/template/scripts/lint-dependency-direction.ts +130 -0
  57. package/assets/template/scripts/lint-doc-examples.test.ts +45 -9
  58. package/assets/template/scripts/lint-doc-examples.ts +227 -50
  59. package/assets/template/scripts/lint-doc-references.test.ts +36 -0
  60. package/assets/template/scripts/lint-doc-references.ts +142 -57
  61. package/assets/template/scripts/lint-doc-shared.ts +26 -23
  62. package/assets/template/scripts/lint-stray-backups.test.ts +3 -1
  63. package/assets/template/scripts/lint-stray-backups.ts +7 -3
  64. package/assets/template/scripts/npm-trust-guard.test.ts +56 -8
  65. package/assets/template/scripts/npm-trust-guard.ts +116 -200
  66. package/assets/template/scripts/safe-install.ts +28 -23
  67. package/assets/template/scripts/transcription/api-harness.ts +28 -206
  68. package/assets/template/scripts/transcription/compare.test.ts +84 -0
  69. package/assets/template/scripts/transcription/compare.ts +4 -4
  70. package/assets/template/scripts/transcription/corpus.ts +9 -3
  71. package/assets/template/scripts/transcription/fixture.ts +2 -4
  72. package/assets/template/scripts/transcription/make-mutants.ts +116 -37
  73. package/assets/template/scripts/transcription/run-conformance.ts +57 -34
  74. package/assets/template/scripts/transcription/validate-coverage.test.ts +11 -14
  75. package/assets/template/scripts/transcription/validate-coverage.ts +8 -10
  76. package/assets/template/scripts/transcription/validate.ts +18 -3
  77. package/assets/template/tsconfig.json +2 -20
  78. package/assets/template/turbo.jsonc +7 -52
  79. package/bin/bunfig.toml +3 -0
  80. package/bin/create-clis.mjs +165 -104
  81. package/dist/create-clis.js +48 -87681
  82. package/dist/manifest.json +3 -3
  83. package/package.json +9 -5
  84. package/assets/template/packages/{{NAME}}/docs/README.md +0 -21
  85. package/assets/template/packages/{{NAME}}-cli/docs/README.md +0 -21
  86. package/bin/create-clis +0 -35
  87. package/bin/create-clis.cmd +0 -32
package/README.md CHANGED
@@ -1,13 +1,12 @@
1
1
  # create-clis
2
2
 
3
3
  [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/create-clis)](https://www.npmjs.com/package/create-clis)
4
5
 
5
6
  **English** | [中文](README.zh-CN.md)
6
7
 
7
8
  Scaffold a standalone clis collection repository from the clis skeleton snapshot: capability tiers, generic vocabulary, and a green CI out of the box.
8
9
 
9
- > Status: not on the npm registry yet; the npm badges land with the first published version.
10
-
11
10
  ## Requirements
12
11
 
13
12
  - **Runtime**: any recent bun, or node 22.18.0 or newer (the floor is the package's `engines` declaration).
@@ -26,11 +25,18 @@ pnpm create clis
26
25
  # bun: bun create clis is bunx create-clis
27
26
  bun create clis
28
27
 
28
+ # deno: deno create follows npm's create- convention (npm:clis resolves to create-clis)
29
+ deno create npm:clis
30
+
29
31
  # or call the package directly
30
32
  bunx create-clis
33
+ npx create-clis
34
+
35
+ # yarn Berry has no create convention; dlx is the equivalent
36
+ yarn dlx create-clis
31
37
  ```
32
38
 
33
- The four entry points are equivalent. The target directory defaults to a subdirectory of the current directory named after the project:
39
+ These entry points are equivalent. The target directory defaults to a subdirectory of the current directory named after the project:
34
40
 
35
41
  ```shell
36
42
  # interactive: pass the target directory; the rest are asked one by one
@@ -65,7 +71,9 @@ The remaining flags:
65
71
  - **`--no-git`**: skip `git init` (runs by default);
66
72
  - **`--no-install`**: skip dependency install (runs by default);
67
73
  - **`--yes`**: all defaults, zero interaction;
68
- - **`--help`**: print help.
74
+ - **`-V`, `--version`**: print version;
75
+ - **`-h`, `--help`**: print help;
76
+ - **`create-clis update [--check] [--pm <pm>] [--registry <url>] [--force]`**: when installed globally via bun / npm / pnpm / yarn / volta, detect the active package manager and self-update (or inspect the latest version with `--check`).
69
77
 
70
78
  Under `npm create`, flags go after `--` (`npm create clis -- --tier core`); npm strips that `--`, which is standard npm behavior the generator does not have to handle. Values are validated the moment they are collected (kebab-case name, command-safe bin name, well-formed scope, owner, and repo URL), failing on the spot with the reason.
71
79
 
@@ -73,11 +81,11 @@ Under `npm create`, flags go after `--` (`npm create clis -- --tier core`); npm
73
81
 
74
82
  `--tier` takes `core`, `standard`, or `full`; the default is `standard`. The tiers subtract: `full` is the complete box, `standard` is `full` minus the enhanced tier, and `core` is `standard` minus the standard tier.
75
83
 
76
- - **core**: the engineering skeleton and release closure every repo in the collection carries (the layer without which the repo has not been finished);
77
- - **standard** (default): adds the standard-tier equipment: the multi-package split (tool + library), the test setup, and the tech-debt ledger;
78
- - **full**: adds the enhanced tier on top: the transcription conformance kit (behavior contracts + a golden corpus + a deterministic verifier + mutation self-check) and its ledger reconciliation gate (`lint:coverage`). Only the mechanism ships; the contract, coverage table, and corpus under `docs/sweep/protocol/` are content to fill in. Until you fill them, `bun run ci` stays red on `lint:coverage` and `conformance:bun` / `conformance:node`: a fresh full-tier project is not green out of the box (core and standard are).
84
+ - **core**: the two-package engineering skeleton (tool + library), test runner, and release closure every repo in the collection carries (the layer without which the repo has not been finished);
85
+ - **standard** (default): adds the standard-tier governance equipment on top of `core`: the dependency-direction gate (`lint:deps`, plus its unit tests) and the tech-debt ledger (`docs/designs/tech-debt.md`);
86
+ - **full**: adds the enhanced tier on top: the transcription conformance kit (behavior contracts + a golden corpus + a deterministic verifier + mutation self-check) and its ledger reconciliation gate (`lint:coverage`). Only the mechanism ships; the contract, coverage table, and corpus under `packages/<name>/docs/protocol/` are content to fill in. Until you fill them, `bun run ci` stays red on `lint:coverage` and `conformance:bun` / `conformance:node` (`typecheck` stays green): a fresh full-tier project is not green out of the box (core and standard are).
79
87
 
80
- Two notes on shape. Every generated repo comes out in the two-package collection form (tool + library); the generator does not produce single-package repos, so prune one package by hand if that is what you want. And the tier is a packing list, not a stored field: nothing in the generated repo records it, so later upgrades or downgrades are manual, file-by-file affairs (the pruning rules are in [capability-tiers.md](../../docs/designs/capability-tiers.md)).
88
+ Two notes on shape. Every generated repo comes out in the two-package collection form (tool + library); the generator does not produce single-package repos, so prune one package by hand if that is what you want. And the tier is a packing list, not a stored field: nothing in the generated repo records it, so later upgrades or downgrades are manual, file-by-file affairs (the pruning rules are in [capability-tiers.md](https://github.com/iyowei/clis/blob/main/docs/designs/capability-tiers.md)).
81
89
 
82
90
  ## What you get
83
91
 
@@ -87,7 +95,7 @@ What lands on disk is a standalone new collection repo, on its own from the mome
87
95
 
88
96
  - **The engineering skeleton**: workspaces / turbo / the root tsconfig / the config family (oxlint / prettier / editorconfig / gitattributes / gitignorerc / nvmrc / bunfig) / the version pin;
89
97
  - **Commit hooks**: lefthook + `install-git-hooks` (degrading gracefully when lefthook is absent) + `safe-install`;
90
- - **The gate chain, single-source**: `scripts/ci.ts` holds the one step list (manual full runs, pre-push, CI, and the release verify job all call into it), and `bun run ci` runs the whole thing;
98
+ - **The gate chain, single-source**: `scripts/ci.ts` holds the one step list (manual full runs, pre-push, CI, and the release `checks` workflow call all go through it), and `bun run ci` runs the whole thing;
91
99
  - **The release pipeline**: semantic-release, OIDC trusted publishing behind a manual environment approval, a release-credential pre-flight, and per-package release self-checks;
92
100
  - **The docs skeleton**: a docs index / designs as minimal units / an ADR template / CONTRIBUTING / SECURITY / a code of conduct;
93
101
  - **AI-assistant files**: AGENTS.md and recommended `.vscode` settings;
@@ -102,12 +110,12 @@ A published version is proof, not a promise: it generated a complete project, in
102
110
  Package scripts:
103
111
 
104
112
  - `bun run build`: emits both artifacts: the template assets (`assets/template/`, built from this repo by the skeleton manifest) and the executable bundle (`dist/`, with the manifest the launcher reconciles it against);
105
- - `bun run verify:release`: the pre-release check: clean checkout, artifacts built from this commit, manifest consistency, and the packed tarball matching the file whitelist;
106
- - `bun run heavy-smoke`: the heavyweight smoke: generate a complete core-tier project and run its whole gate chain, green or nothing.
113
+ - `bun run verify:release`: the pre-release check: clean checkout, artifacts built from this commit, manifest consistency, the `256 KiB` bundle size cap on `dist/create-clis.js`, and the packed tarball matching the file whitelist;
114
+ - `bun run heavy-smoke`: the heavyweight smoke: packs the already-verified immutable package via `npm pack`, installs it in an isolated temporary directory (`npm install --omit=dev`), and exercises two scenarios through the installed binary — generating a default `standard`-tier project and running its entire `bun run ci` green, plus generating a scoped `core`-tier project and verifying its pruned structure and neutral build scripts.
107
115
 
108
- `prepublishOnly` strings the three together, so every published version carries its own proof: the project it generates is green. The design docs (package design / contract / tiers / snapshot mechanism) are all in [docs/designs/](../../docs/designs/).
116
+ `prepublishOnly` strings the three together, so every published version carries its own proof: the project it generates is green. The design docs (package design / contract / tiers / snapshot mechanism) are all in [docs/designs/](https://github.com/iyowei/clis/tree/main/docs/designs).
109
117
 
110
118
  ---
111
119
 
112
- - Design: [scaffold-package.md](../../docs/designs/scaffold-package.md);
113
- - Package docs entry: [docs/README.md](docs/README.md).
120
+ - Design: [scaffold-package.md](https://github.com/iyowei/clis/blob/main/docs/designs/scaffold-package.md)
121
+ - Contract: [scaffold-contract.md](https://github.com/iyowei/clis/blob/main/docs/designs/scaffold-contract.md)
package/README.zh-CN.md CHANGED
@@ -1,13 +1,12 @@
1
1
  # create-clis
2
2
 
3
3
  [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/create-clis)](https://www.npmjs.com/package/create-clis)
4
5
 
5
6
  [English](README.md) | **中文**
6
7
 
7
8
  从本仓骨架的泛化快照生成一个独立的新 clis 集合仓: 带能力档位与通用词汇, 开箱就是一条全绿的 CI。
8
9
 
9
- > 状态: 尚未发布到 npm registry; npm 徽章随首个发布版本补上。
10
-
11
10
  ## 要求
12
11
 
13
12
  - **运行时**: bun (任意近期版本), 或 node 22.18.0 或更新 (版本下限见包的 `engines` 声明)。
@@ -26,11 +25,18 @@ pnpm create clis
26
25
  # bun: bun create clis 即 bunx create-clis
27
26
  bun create clis
28
27
 
28
+ # deno: deno create 遵循 npm 的 create- 约定 (npm:clis 解析为 create-clis)
29
+ deno create npm:clis
30
+
29
31
  # 也可以直接跑包名
30
32
  bunx create-clis
33
+ npx create-clis
34
+
35
+ # yarn Berry 没有 create 约定, dlx 是等价入口
36
+ yarn dlx create-clis
31
37
  ```
32
38
 
33
- 四个入口等价; 目标目录缺省是当前目录下以项目名命名的子目录:
39
+ 这些入口等价; 目标目录缺省是当前目录下以项目名命名的子目录:
34
40
 
35
41
  ```shell
36
42
  # 交互问答: 位置参数是目标目录, 其余变量逐个提问
@@ -65,7 +71,9 @@ npm create clis -- my-tool --tier core
65
71
  - **`--no-git`**: 跳过 `git init` (默认执行);
66
72
  - **`--no-install`**: 跳过依赖安装 (默认执行);
67
73
  - **`--yes`**: 全部取默认值, 零交互;
68
- - **`--help`**: 打印帮助。
74
+ - **`-V`, `--version`**: 打印版本号;
75
+ - **`-h`, `--help`**: 打印帮助;
76
+ - **`create-clis update [--check] [--pm <管理器>] [--registry <url>] [--force]`**: 全局安装场景下自动识别安装器 (bun / npm / pnpm / yarn / volta) 并原地自更新 (`--check` 仅检查)。
69
77
 
70
78
  经 `npm create` 调用时, 旗标要写在 `--` 后面 (`npm create clis -- --tier core`); 这个 `--` 由 npm 剥离, 是生态的既有行为, 生成器不参与。各变量的取值在收集那一刻就校验 (项目名 kebab-case、bin 名命令行可用、scope / owner / 仓库地址形态), 不合法当场给原因。
71
79
 
@@ -73,11 +81,11 @@ npm create clis -- my-tool --tier core
73
81
 
74
82
  `--tier` 三选一, 默认 `standard`。三档是减法: `full` 是完整箱, `standard` 是 `full` 减增强档装备, `core` 是 `standard` 再减标准档装备。
75
83
 
76
- - **core**: 工程骨架与发布闭环 (集合里每个仓库都默认全带的那一层);
77
- - **standard** (默认): 再加标准档装备: 多包分层 (工具 + 库)、测试体系、技术债登记册;
78
- - **full**: 再加增强档装备: 转写契约套件 (行为契约 + 金样本语料 + 确定性验收器 + 变异自证) 与它的台账对账闸门 (`lint:coverage`)。机制随模板, 内容要自填: `docs/sweep/protocol/` 下的契约 / 覆盖表 / 语料填上之前, `bun run ci` 会在 `lint:coverage` 与 `conformance:bun` / `conformance:node` 上红, full 档开箱不是全绿 (core 与 standard 是)。
84
+ - **core**: 双包工程骨架 (工具 + 库)、基础测试与发布闭环 (集合里每个仓库都默认全带的那一层);
85
+ - **standard** (默认): 在 `core` 之上加标准档治理装备: 依赖方向闸门 (`lint:deps` 及其单测) 与技术债登记册 (`docs/designs/tech-debt.md`);
86
+ - **full**: 再加增强档装备: 转写契约套件 (行为契约 + 金样本语料 + 确定性验收器 + 变异自证) 与它的台账对账闸门 (`lint:coverage`)。机制随模板, 内容要自填: `packages/<name>/docs/protocol/` 下的契约 / 覆盖表 / 语料填上之前, `bun run ci` 会在 `lint:coverage` 与 `conformance:bun` / `conformance:node` 上红 (`typecheck` 保持全绿), full 档开箱不是全绿 (core 与 standard 是)。
79
87
 
80
- 生成物恒为双包集合仓形态 (工具 + 库): 生成器不产出单包仓, 要单包的话生成后自行裁剪。档位只是生成那一刻的装箱单: 它不写进任何配置文件, 之后升降档是手工的按件增删 (裁剪规则见 [capability-tiers.md](../../docs/designs/capability-tiers.md))。
88
+ 生成物恒为双包集合仓形态 (工具 + 库): 生成器不产出单包仓, 要单包的话生成后自行裁剪。档位只是生成那一刻的装箱单: 它不写进任何配置文件, 之后升降档是手工的按件增删 (裁剪规则见 [capability-tiers.md](https://github.com/iyowei/clis/blob/main/docs/designs/capability-tiers.md))。
81
89
 
82
90
  ## 生成物
83
91
 
@@ -87,7 +95,7 @@ npm create clis -- my-tool --tier core
87
95
 
88
96
  - **工程骨架**: workspaces / turbo / 根 tsconfig / 配置族 (oxlint / prettier / editorconfig / gitattributes / gitignorerc / nvmrc / bunfig) / 版本 pin;
89
97
  - **提交与钩子链**: lefthook + `install-git-hooks` (机器上没有 lefthook 时降级) + `safe-install`;
90
- - **闸门链单源**: `scripts/ci.ts` 是唯一一份步骤清单 (手动全链、pre-push、CI 与 Release 都从它走), `bun run ci` 一条命令跑完全套;
98
+ - **闸门链单源**: `scripts/ci.ts` 是唯一一份步骤清单 (手动全链、pre-push、CI 与 Release 前置 `checks` 都从它走), `bun run ci` 一条命令跑完全套;
91
99
  - **发布闭环**: semantic-release 自动发布, 凭据走 OIDC 可信发布 + environment 人工批准, 另有发布凭据预检与逐包发布自证;
92
100
  - **文档体系**: docs 索引 / designs 最小单元组织 / ADR 模板 / CONTRIBUTING / SECURITY / 行为准则;
93
101
  - **AI 协作文件**: AGENTS.md 与 `.vscode` 推荐配置;
@@ -102,12 +110,12 @@ npm create clis -- my-tool --tier core
102
110
  包脚本:
103
111
 
104
112
  - `bun run build`: 一次产出两份东西: 模板资产 (`assets/template/`, 由骨架清单从本仓构建) 与可执行产物 (`dist/`, 含启动器对账用的清单);
105
- - `bun run verify:release`: 发布前置校验: 干净检出、产物出自本提交、清单自洽、发行面包内文件与白名单相符;
106
- - `bun run heavy-smoke`: 重量级冒烟: 现场生成一个 core 档完整项目, 跑它的整套闸门链, 全绿才算过。
113
+ - `bun run verify:release`: 发布前置校验: 干净检出、产物出自本提交、清单自洽、`dist/create-clis.js` 单文件 `256 KiB` 体积上限门禁、以及发行面包内文件与白名单相符;
114
+ - `bun run heavy-smoke`: 重量级冒烟: 对已校验的不可变包执行 `npm pack` 并在独立隔离目录以 `npm install --omit=dev` 装包, 通过装好的入口验收双场景 — 场景 A 生成默认 `standard` 档完整项目并跑通其全套 `bun run ci`, 场景 B 生成带 `--scope` 的 `core` 档项目并校验裁剪结构与中性构建脚本。
107
115
 
108
- `prepublishOnly` 按序串起三者, 发布出去的版本因此自带一份证明: 它生成的项目是绿的。设计与契约文档 (生成器包设计 / 契约 / 档位 / 快照机制) 都在 [docs/designs/](../../docs/designs/) 下。
116
+ `prepublishOnly` 按序串起三者, 发布出去的版本因此自带一份证明: 它生成的项目是绿的。设计与契约文档 (生成器包设计 / 契约 / 档位 / 快照机制) 都在 [docs/designs/](https://github.com/iyowei/clis/tree/main/docs/designs) 下。
109
117
 
110
118
  ---
111
119
 
112
- - 生成器包设计: [scaffold-package.md](../../docs/designs/scaffold-package.md);
113
- - 包级文档入口: [docs/README.md](docs/README.md)。
120
+ - 生成器包设计: [scaffold-package.md](https://github.com/iyowei/clis/blob/main/docs/designs/scaffold-package.md)
121
+ - 生成器契约: [scaffold-contract.md](https://github.com/iyowei/clis/blob/main/docs/designs/scaffold-contract.md)
@@ -17,6 +17,7 @@
17
17
  ".vscode/extensions.json",
18
18
  ".vscode/launch.json",
19
19
  ".vscode/settings.json",
20
+ ".vscode/tasks.json",
20
21
  "AGENTS.md",
21
22
  "CODE_OF_CONDUCT.md",
22
23
  "CONTRIBUTING.md",
@@ -39,11 +40,11 @@
39
40
  "packages/{{NAME}}-cli/LICENSE",
40
41
  "packages/{{NAME}}-cli/README.md",
41
42
  "packages/{{NAME}}-cli/README.zh-CN.md",
43
+ "packages/{{NAME}}-cli/bin/bunfig.toml",
42
44
  "packages/{{NAME}}-cli/bin/{{BIN_NAME}}",
43
45
  "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd",
44
46
  "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts",
45
47
  "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs",
46
- "packages/{{NAME}}-cli/docs/README.md",
47
48
  "packages/{{NAME}}-cli/package.json",
48
49
  "packages/{{NAME}}-cli/scripts/release-artifact.ts",
49
50
  "packages/{{NAME}}-cli/scripts/release.fixtures.ts",
@@ -57,7 +58,6 @@
57
58
  "packages/{{NAME}}/LICENSE",
58
59
  "packages/{{NAME}}/README.md",
59
60
  "packages/{{NAME}}/README.zh-CN.md",
60
- "packages/{{NAME}}/docs/README.md",
61
61
  "packages/{{NAME}}/package.json",
62
62
  "packages/{{NAME}}/scripts/build.ts",
63
63
  "packages/{{NAME}}/scripts/verify-release.test.ts",
@@ -69,10 +69,14 @@
69
69
  "scripts/install-git-hooks.mjs",
70
70
  "scripts/install-git-hooks.test.ts",
71
71
  "scripts/lib/git-env.ts",
72
+ "scripts/lib/npm-trust-parse.ts",
73
+ "scripts/lib/release-cli.ts",
72
74
  "scripts/lib/release-verify.ts",
73
75
  "scripts/lib/tmp-root.ts",
74
76
  "scripts/lib/workspace.test.ts",
75
77
  "scripts/lib/workspace.ts",
78
+ "scripts/lint-dependency-direction.test.ts",
79
+ "scripts/lint-dependency-direction.ts",
76
80
  "scripts/lint-doc-examples.test.ts",
77
81
  "scripts/lint-doc-examples.ts",
78
82
  "scripts/lint-doc-references.test.ts",
@@ -84,6 +88,7 @@
84
88
  "scripts/npm-trust-guard.ts",
85
89
  "scripts/safe-install.ts",
86
90
  "scripts/transcription/api-harness.ts",
91
+ "scripts/transcription/compare.test.ts",
87
92
  "scripts/transcription/compare.ts",
88
93
  "scripts/transcription/corpus.ts",
89
94
  "scripts/transcription/fixture.ts",
@@ -1,14 +1,12 @@
1
1
  name: Bug report
2
- description: Report a problem with the CLI or the programmable API package.
2
+ description: Report a problem with {{NAME}} CLI or programmable API.
3
3
  title: "[Bug]:\x20"
4
4
  labels: ['bug']
5
5
  body:
6
6
  - type: markdown
7
7
  attributes:
8
8
  value: |
9
- Thanks for taking the time to report a bug. Fill in as much as you can; a precise reproduction gets a fix faster.
10
-
11
- For security problems, do not open a public issue. In particular, if the tool deleted something it should not have, or a safety guard can be bypassed, report it privately: on GitHub, open the Security tab and use Report a vulnerability. See [SECURITY.md]({{REPO_URL}}/blob/main/SECURITY.md) for the full policy.
9
+ Thanks for taking the time to report a bug. For security problems, do not open a public issue; see [SECURITY.md]({{REPO_URL}}/blob/main/SECURITY.md).
12
10
  - type: checkboxes
13
11
  id: preflight
14
12
  attributes:
@@ -16,14 +14,23 @@ body:
16
14
  options:
17
15
  - label: I searched the existing issues and did not find this report.
18
16
  required: true
19
- - label: I can reproduce this on the latest published version, or on the current main branch from a clone.
17
+ - label: I can reproduce this on the latest version or main branch.
20
18
  required: true
19
+ - type: dropdown
20
+ id: package
21
+ attributes:
22
+ label: Affected package
23
+ options:
24
+ - '{{SCOPE}}/{{NAME}}-cli ({{BIN_NAME}})'
25
+ - '{{SCOPE}}/{{NAME}} (API)'
26
+ - Repository infrastructure / docs
27
+ validations:
28
+ required: true
21
29
  - type: input
22
30
  id: version
23
31
  attributes:
24
32
  label: Version
25
- description: The version in use (for example 0.1.1), or the commit hash when running from a clone.
26
- placeholder: '0.1.1'
33
+ placeholder: '0.1.0'
27
34
  validations:
28
35
  required: true
29
36
  - type: dropdown
@@ -41,34 +48,19 @@ body:
41
48
  id: runtime
42
49
  attributes:
43
50
  label: Runtime and version
44
- description: The runtime the run actually used, bun or node. The header line of the preview reports it (on interactive terminals).
45
- placeholder: 'node 24.7.0'
46
- validations:
47
- required: true
48
- - type: dropdown
49
- id: install-method
50
- attributes:
51
- label: How the tool is run
52
- options:
53
- - bunx (no install)
54
- - npx (no install)
55
- - Installed globally, run as {{BIN_NAME}}
56
- - From a clone of the repository
57
- - Other
51
+ placeholder: 'bun 1.4.5 / node 24.0.0'
58
52
  validations:
59
53
  required: true
60
54
  - type: textarea
61
55
  id: steps
62
56
  attributes:
63
57
  label: Steps to reproduce
64
- description: The exact commands that were run, copied from the terminal, and whether a config file is involved ({{BIN_NAME}} config shows which config file applies to the current run).
65
58
  validations:
66
59
  required: true
67
60
  - type: textarea
68
61
  id: actual
69
62
  attributes:
70
63
  label: Actual behavior
71
- description: What happened, including the full output if possible. Error messages carry an error code; include it.
72
64
  render: shell
73
65
  validations:
74
66
  required: true
@@ -76,11 +68,5 @@ body:
76
68
  id: expected
77
69
  attributes:
78
70
  label: Expected behavior
79
- description: What should have happened instead.
80
71
  validations:
81
72
  required: true
82
- - type: textarea
83
- id: extra
84
- attributes:
85
- label: Anything else?
86
- description: Optional. Related issues, screenshots, or any other context that might help.
@@ -1,12 +1,12 @@
1
1
  name: Feature request
2
- description: Suggest an idea or an improvement for the CLI or the programmable API package.
2
+ description: Suggest an improvement for {{NAME}}.
3
3
  title: "[Feature]:\x20"
4
4
  labels: ['enhancement']
5
5
  body:
6
6
  - type: markdown
7
7
  attributes:
8
8
  value: |
9
- Thanks for helping improve the project. Describe the problem first; a concrete problem statement is the best starting point for a solution.
9
+ Thanks for helping improve the project. Describe the problem first.
10
10
  - type: checkboxes
11
11
  id: preflight
12
12
  attributes:
@@ -18,10 +18,9 @@ body:
18
18
  id: area
19
19
  attributes:
20
20
  label: Area
21
- description: Which part of the project is this about?
22
21
  options:
23
- - CLI ({{BIN_NAME}})
24
- - Programmable API ({{SCOPE}}/{{NAME}})
22
+ - 'CLI ({{BIN_NAME}})'
23
+ - 'Programmable API ({{SCOPE}}/{{NAME}})'
25
24
  - Documentation
26
25
  - Other
27
26
  validations:
@@ -30,16 +29,11 @@ body:
30
29
  id: problem
31
30
  attributes:
32
31
  label: The problem
33
- description: Describe the task or use case, and where the current behavior gets in the way. Include the workspace layout or setup if it matters.
34
32
  validations:
35
33
  required: true
36
34
  - type: textarea
37
35
  id: solution
38
36
  attributes:
39
37
  label: Proposed solution
40
- description: Optional. If a specific solution shape is already in mind, describe it.
41
- - type: textarea
42
- id: alternatives
43
- attributes:
44
- label: Alternatives
45
- description: Optional. Workarounds in use today, or other approaches considered.
38
+ validations:
39
+ required: false
@@ -20,7 +20,7 @@
20
20
 
21
21
  - [ ] I agree to follow this project's [Code of Conduct](/CODE_OF_CONDUCT.md).
22
22
  - [ ] `bun test` passes, with both bun and node installed so neither runtime pass is skipped.
23
- - [ ] `bun run typecheck` and `bun run lint` are clean, and the code is formatted (`bun run format`).
24
- - [ ] If the CLI output surface changed, the conformance suite passed on both `bun` and `node`.
25
- - [ ] Docs were updated where behavior or contracts changed; new docs are registered (see `docs/README.md`).
23
+ - [ ] `bun run typecheck`, `bun run lint`, and `bun run format-check` are clean.
24
+ - [ ] If any `sweep` CLI/API behavior surface changed, the conformance suite passed on both `bun` and `node`.
25
+ - [ ] Docs were updated where behavior or contracts changed; new repo-level or package-level docs are registered in `docs/README.md` or `packages/<pkg>/docs/README.md`.
26
26
  - [ ] Commits follow the repository convention: a Conventional Commits prefix, one topic per commit.
@@ -1,13 +1,22 @@
1
1
  name: CI
2
2
 
3
3
  on:
4
- push:
5
- branches: [main]
6
4
  pull_request:
5
+ workflow_call:
6
+ workflow_dispatch:
7
7
 
8
8
  permissions:
9
9
  contents: read
10
10
 
11
+ env:
12
+ TURBO_TELEMETRY_DISABLED: '1'
13
+
14
+ concurrency:
15
+ # 按事件名隔离并发组: PR 连续推送自动取消旧跑; 由 release.yml (push main) 经 workflow_call
16
+ # 复用时, 组名与 release.yml 顶层 group: release 互不重叠, 且不中途取消发布检查。
17
+ group: ci-checks-${{ github.event_name }}-${{ github.ref }}
18
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
19
+
11
20
  jobs:
12
21
  verify:
13
22
  runs-on: ubuntu-latest
@@ -15,28 +24,81 @@ jobs:
15
24
  steps:
16
25
  - uses: actions/checkout@v7
17
26
  - uses: oven-sh/setup-bun@v2
27
+ with:
28
+ bun-version-file: package.json
18
29
  - uses: actions/setup-node@v7
19
30
  with:
20
- node-version: 24
31
+ node-version-file: .nvmrc
32
+ - name: Cache Bun packages
33
+ uses: actions/cache@v5
34
+ with:
35
+ path: ~/.bun/install/cache
36
+ key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
37
+ restore-keys: |
38
+ ${{ runner.os }}-bun-
21
39
  - name: Install
22
40
  run: bun install --frozen-lockfile
23
- # 验证组 (步骤集合的单一事实来源在 scripts/ci.ts, 与本地全链 / Release verify 同集合)
41
+ # 验证组 (步骤集合的单一事实来源在 scripts/ci.ts, 与本地全链 / Release 前置门禁同集合)
24
42
  - name: Verify (ci.ts --verify)
25
43
  run: bun run ci -- --verify
26
44
 
45
+ # Windows OS 兼容专项 (路径分隔符 / 启动器 / 双运行时 / 文件系统语义):
46
+ # 不重跑 OS 无关的 typecheck 与静态 lint, 也不在 4 核 VM 并发重跑已在 Linux 验证过的
47
+ # npm pack 白名单; 经 scripts/ci.ts --verify-windows 统一收口并限并发。
48
+ verify-windows:
49
+ runs-on: windows-latest
50
+ timeout-minutes: 20
51
+ steps:
52
+ - uses: actions/checkout@v7
53
+ - name: Exclude workspace from Windows Defender
54
+ shell: pwsh
55
+ run: |
56
+ try {
57
+ Add-MpPreference -ExclusionPath "${{ github.workspace }}", "$env:RUNNER_TEMP", "$env:USERPROFILE\.bun"
58
+ } catch {
59
+ Write-Host "Skip Defender exclusion: $_"
60
+ }
61
+ - uses: oven-sh/setup-bun@v2
62
+ with:
63
+ bun-version-file: package.json
64
+ - uses: actions/setup-node@v7
65
+ with:
66
+ node-version-file: .nvmrc
67
+ - name: Cache Bun packages
68
+ uses: actions/cache@v5
69
+ with:
70
+ path: ~/.bun/install/cache
71
+ key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
72
+ restore-keys: |
73
+ ${{ runner.os }}-bun-
74
+ - name: Install
75
+ run: bun install --frozen-lockfile
76
+ - name: Verify Windows (ci.ts --verify-windows)
77
+ run: bun run ci -- --verify-windows
78
+
27
79
  # 转写验收 (逐字节金样本) 的语料为 macOS 文件系统口径录制 (du 磁盘占用含块分配差异:
28
80
  # 同一 fixture 在 APFS 计 8 KB, 在 ext4 因目录节点再计 4 KB → 12 KB), 故在 macOS runner
29
- # 执行, 与语料录制环境同源; 它长期以来的运行环境即 macOS (手动双跑)。
81
+ # 执行, 与语料录制环境同源。
30
82
  conformance:
31
83
  runs-on: macos-latest
32
84
  timeout-minutes: 15
33
85
  steps:
34
86
  - uses: actions/checkout@v7
35
87
  - uses: oven-sh/setup-bun@v2
88
+ with:
89
+ bun-version-file: package.json
36
90
  - uses: actions/setup-node@v7
37
91
  with:
38
- node-version: 24
39
- - run: bun install --frozen-lockfile
92
+ node-version-file: .nvmrc
93
+ - name: Cache Bun packages
94
+ uses: actions/cache@v5
95
+ with:
96
+ path: ~/.bun/install/cache
97
+ key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
98
+ restore-keys: |
99
+ ${{ runner.os }}-bun-
100
+ - name: Install
101
+ run: bun install --frozen-lockfile
40
102
  # 验收组 (含 build: node target 需 dist 前置, 理由见 scripts/ci.ts 的组注释)
41
103
  - name: Conformance (ci.ts --conformance)
42
104
  run: bun run ci -- --conformance
@@ -1,4 +1,4 @@
1
- name: Release
1
+ name: CI & Release
2
2
 
3
3
  on:
4
4
  push:
@@ -7,32 +7,27 @@ on:
7
7
  permissions:
8
8
  contents: read
9
9
 
10
- concurrency:
11
- group: release
12
- cancel-in-progress: false
10
+ env:
11
+ TURBO_TELEMETRY_DISABLED: '1'
13
12
 
14
13
  jobs:
15
- # 发布前置门禁: 与 CI 同套检查, 发布不依赖另一个 workflow 的状态 (自足)。
16
- verify:
17
- runs-on: ubuntu-latest
18
- timeout-minutes: 20
19
- steps:
20
- - uses: actions/checkout@v7
21
- - uses: oven-sh/setup-bun@v2
22
- - uses: actions/setup-node@v7
23
- with:
24
- node-version: 24
25
- - run: bun install --frozen-lockfile
26
- # 验证组 (步骤集合的单一事实来源在 scripts/ci.ts, 与 CI verify 同集合)
27
- - run: bun run ci -- --verify
14
+ # 发布前置门禁 (单一事实来源): 直接复用 ci.yml 的全套三路检查 (verify / verify-windows /
15
+ # conformance), 既确保 main 推送零双跑、不白烧双倍 macOS runner, 又把 Windows 兼容正式纳入发版硬门禁。
16
+ checks:
17
+ uses: ./.github/workflows/ci.yml
28
18
 
29
19
  # 人工批准闸门 (environment: release, 配 required reviewers): 批准后才进入发布。
20
+ # concurrency 放在 release job 级 (而非顶层): 既保证实际发布严格串行不并发冲突,
21
+ # 又避免前一次待审批的 waiting run 把后续 main 推送的 checks 三平台 CI 卡死在 pending。
30
22
  # OIDC 发布: 不设任何 npm token; id-token: write 供 Trusted Publishing 换取短寿命凭据。
31
23
  release:
32
- needs: verify
24
+ needs: checks
33
25
  runs-on: ubuntu-latest
34
26
  timeout-minutes: 30
35
27
  environment: release
28
+ concurrency:
29
+ group: release
30
+ cancel-in-progress: false
36
31
  permissions:
37
32
  contents: write # 打 tag / push 版本提交 / 建 GitHub Release
38
33
  issues: write # release 评论
@@ -43,20 +38,25 @@ jobs:
43
38
  with:
44
39
  fetch-depth: 0 # semantic-release 需要全历史与全部 tag
45
40
  - uses: oven-sh/setup-bun@v2
41
+ with:
42
+ bun-version-file: package.json
46
43
  - uses: actions/setup-node@v7
47
44
  with:
48
- node-version: 24 # 自带 npm 11.x: OIDC 与 provenance 所需
45
+ node-version-file: .nvmrc # 自带 npm 11.x: OIDC 与 provenance 所需
49
46
  # 不设 registry-url: 它会生成带 NODE_AUTH_TOKEN 的 .npmrc, 压掉 OIDC 通道
47
+ - name: Cache Bun packages
48
+ uses: actions/cache@v5
49
+ with:
50
+ path: ~/.bun/install/cache
51
+ key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
52
+ restore-keys: |
53
+ ${{ runner.os }}-bun-
50
54
  - run: bun install --frozen-lockfile
51
55
  # 发布凭据预检 (发布特有, 经 ci.ts 单源调用): OIDC 换证即与 npm 侧 Trusted Publisher
52
56
  # 登记的全量核对 (含 environment 声明), 失配在发布前当场点名。必须放本 job: environment
53
57
  # 声明来自 job 的 environment, 无 environment 的 job 换证会被 npm 以误导性的 404 拒绝
54
58
  - run: bun run ci -- --only npm-trust
55
59
  - name: Release (multi-semantic-release, OIDC)
56
- # 启动器用 bunx (与本地 dryrun 同链; 实测 --no-install 只经本地 devDep 启动);
57
- # 「发布到 npm」的环节由 semrel 的 npm 插件内部 spawn 的 npm 本体承担 —— OIDC Trusted
58
- # Publishing + provenance 需 npm 11, bun publish 未接该能力 (ADR 0010 决策 7),
59
- # 与启动器选择无关
60
60
  run: bunx --no-install multi-semantic-release
61
61
  env:
62
62
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -10,12 +10,5 @@
10
10
  "Vim",
11
11
  "Archives"
12
12
  ],
13
- "custom": [
14
- "package-lock.json",
15
- "*.log",
16
- "*.modified",
17
- "packages/{{NAME}}/bench/results/",
18
- "scripts/transcription/mutants/gen-*/",
19
- ".turbo/"
20
- ]
13
+ "custom": ["package-lock.json", "*.modified", "*.deleted", ".turbo/"]
21
14
  }
@@ -43,10 +43,5 @@
43
43
  "setTimeout": "readonly",
44
44
  "clearTimeout": "readonly"
45
45
  },
46
- "ignorePatterns": [
47
- "dist/**",
48
- "node_modules/**",
49
- "scripts/transcription/mutants/**",
50
- "packages/create-clis/assets/**"
51
- ]
46
+ "ignorePatterns": ["dist/**", "node_modules/**"]
52
47
  }
@@ -8,4 +8,3 @@ CHANGELOG.md
8
8
  CODE_OF_CONDUCT.md
9
9
  *.modified
10
10
  *.deleted
11
- packages/create-clis/assets
@@ -5,7 +5,12 @@
5
5
  "@semantic-release/release-notes-generator",
6
6
  "@semantic-release/changelog",
7
7
  "@semantic-release/npm",
8
- "@semantic-release/github",
8
+ [
9
+ "@semantic-release/github",
10
+ {
11
+ "labels": false
12
+ }
13
+ ],
9
14
  [
10
15
  "@semantic-release/git",
11
16
  {
@@ -4,7 +4,7 @@
4
4
  {
5
5
  "type": "bun",
6
6
  "request": "launch",
7
- "name": "调试 CLI (从源码运行)",
7
+ "name": "调试 {{BIN_NAME}} (从源码运行)",
8
8
  "program": "./packages/{{NAME}}-cli/src/cli.ts",
9
9
  "cwd": "${workspaceFolder}",
10
10
  "runtime": "bun"
@@ -1,4 +1,5 @@
1
1
  {
2
+ "editor.defaultFormatter": "esbenp.prettier-vscode",
2
3
  "files.exclude": {
3
4
  "**/.git": true,
4
5
  "**/.svn": true,