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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 iTonyYo
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.
package/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # create-clis
2
+
3
+ [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
+
5
+ **English** | [中文](README.zh-CN.md)
6
+
7
+ 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
+ > Status: not on the npm registry yet; the npm badges land with the first published version.
10
+
11
+ ## Requirements
12
+
13
+ - **Runtime**: any recent bun, or node 22.18.0 or newer (the floor is the package's `engines` declaration).
14
+ - **Zero install**: the generator needs no global install; each run resolves the package from the registry.
15
+ - **The generated repo is a bun project**: the generator itself runs on either runtime, but what it produces is managed with bun (the version pin and dependency install both go through bun). The default finish runs `bun install`; `--no-install` skips it.
16
+
17
+ ## Usage
18
+
19
+ ```shell
20
+ # npm: the create convention resolves to npm exec create-clis
21
+ npm create clis
22
+
23
+ # pnpm
24
+ pnpm create clis
25
+
26
+ # bun: bun create clis is bunx create-clis
27
+ bun create clis
28
+
29
+ # or call the package directly
30
+ bunx create-clis
31
+ ```
32
+
33
+ The four entry points are equivalent. The target directory defaults to a subdirectory of the current directory named after the project:
34
+
35
+ ```shell
36
+ # interactive: pass the target directory; the rest are asked one by one
37
+ bunx create-clis my-tool
38
+
39
+ # zero interaction: all defaults
40
+ bunx create-clis my-tool --yes
41
+
42
+ # through npm create, flags go after -- (standard npm behavior)
43
+ npm create clis -- my-tool --tier core
44
+ ```
45
+
46
+ With no flags it asks the five questions one by one (the brackets show the defaults; Enter takes them, and an answer that fails validation prints the reason and asks again). Fields already given, as flags or through the positional directory, are adopted as-is. `--yes` takes every default, zero questions.
47
+
48
+ **Target directory**: a directory that already exists and is non-empty is refused outright (no overwrite, and no `--force` escape hatch; the risk of overwriting outweighs the convenience). An existing but empty directory is fine, and the files land in it.
49
+
50
+ Failures print the reason and exit non-zero. If a failure occurs after writing has started, the half-finished directory is pointed out and kept (nothing is silently cleaned up; look at it or delete it as you like).
51
+
52
+ ## Variables and flags
53
+
54
+ Five variables, matching the template's generalization vocabulary one-to-one:
55
+
56
+ - **Project name**: the positional argument (the target directory's basename) or `--name`; no default, must be kebab-case (like `my-tool`);
57
+ - **scope**: `--scope`; defaults to none (a bare package name); when given, starts with `@` (like `@me`);
58
+ - **bin name**: `--bin`; defaults to a short form derived from the name (three or more segments take the head plus the initials of the rest: `sweep-node-modules` → `sweep-nm`);
59
+ - **owner**: `--owner`; defaults to the git-wide `user.name`;
60
+ - **repo URL**: `--repo`; defaults to `https://github.com/<owner>/<name>`.
61
+
62
+ The remaining flags:
63
+
64
+ - **`--tier <tier>`**: `core` / `standard` / `full`, default `standard`;
65
+ - **`--no-git`**: skip `git init` (runs by default);
66
+ - **`--no-install`**: skip dependency install (runs by default);
67
+ - **`--yes`**: all defaults, zero interaction;
68
+ - **`--help`**: print help.
69
+
70
+ 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
+
72
+ ## Tiers
73
+
74
+ `--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
+
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).
79
+
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)).
81
+
82
+ ## What you get
83
+
84
+ The template is derived, not maintained. Like the lockfile your package manager writes for you, it is produced from its source: change this repo and the next build carries the change, with no hand-syncing. The build also runs a residue check: the template may not contain the original project's vocabulary, and a leftover fails the build.
85
+
86
+ What lands on disk is a standalone new collection repo, on its own from the moment it exists: the generator does not upgrade or sync repos it has already generated, and the template's later evolution never flows back into them. It ships with:
87
+
88
+ - **The engineering skeleton**: workspaces / turbo / the root tsconfig / the config family (oxlint / prettier / editorconfig / gitattributes / gitignorerc / nvmrc / bunfig) / the version pin;
89
+ - **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;
91
+ - **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
+ - **The docs skeleton**: a docs index / designs as minimal units / an ADR template / CONTRIBUTING / SECURITY / a code of conduct;
93
+ - **AI-assistant files**: AGENTS.md and recommended `.vscode` settings;
94
+ - **Two example packages**: `<name>-cli` (a thin shell over the library) and `<name>` (the library), carrying a minimal greet demo; swap them for your own tool.
95
+
96
+ Generation runs in a fixed order: collect the variables → copy the snapshot → prune by tier → substitute the vocabulary → format the tree back to prettier-stable (what the product's own `format-check` gate needs) → rescan for leftovers → finish (`git init` and dependency install, both on by default). It ends with the next steps: enter the directory, run `bun run ci` to verify green, and start reshaping the repo from `docs/README.md` (the docs index).
97
+
98
+ A published version is proof, not a promise: it generated a complete project, installed its dependencies, and ran that project's entire gate chain green before it was allowed out.
99
+
100
+ ## Development
101
+
102
+ Package scripts:
103
+
104
+ - `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.
107
+
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/).
109
+
110
+ ---
111
+
112
+ - Design: [scaffold-package.md](../../docs/designs/scaffold-package.md);
113
+ - Package docs entry: [docs/README.md](docs/README.md).
@@ -0,0 +1,113 @@
1
+ # create-clis
2
+
3
+ [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
+
5
+ [English](README.md) | **中文**
6
+
7
+ 从本仓骨架的泛化快照生成一个独立的新 clis 集合仓: 带能力档位与通用词汇, 开箱就是一条全绿的 CI。
8
+
9
+ > 状态: 尚未发布到 npm registry; npm 徽章随首个发布版本补上。
10
+
11
+ ## 要求
12
+
13
+ - **运行时**: bun (任意近期版本), 或 node 22.18.0 或更新 (版本下限见包的 `engines` 声明)。
14
+ - **免安装**: 生成器无需预先全局安装; 每次运行按需从 registry 解析包。
15
+ - **生成物是 bun 工程**: 运行生成器 bun / node 皆可, 但生成出来的项目由 bun 管理 (版本 pin 与依赖安装都走 bun); 默认收尾会执行 `bun install`, `--no-install` 可跳过。
16
+
17
+ ## 使用
18
+
19
+ ```shell
20
+ # npm: npm create 约定等价于 npm exec create-clis
21
+ npm create clis
22
+
23
+ # pnpm
24
+ pnpm create clis
25
+
26
+ # bun: bun create clis 即 bunx create-clis
27
+ bun create clis
28
+
29
+ # 也可以直接跑包名
30
+ bunx create-clis
31
+ ```
32
+
33
+ 四个入口等价; 目标目录缺省是当前目录下以项目名命名的子目录:
34
+
35
+ ```shell
36
+ # 交互问答: 位置参数是目标目录, 其余变量逐个提问
37
+ bunx create-clis my-tool
38
+
39
+ # 零交互: 全部取默认值
40
+ bunx create-clis my-tool --yes
41
+
42
+ # 经 npm create 调用时, 旗标写在 -- 后面 (这是 npm 生态的既有行为)
43
+ npm create clis -- my-tool --tier core
44
+ ```
45
+
46
+ 无旗标时逐项提问, 方括号内是默认值、回车采用, 答错会说明原因并重问; 给过旗标 (或位置参数) 的字段直接采用、不再提问; `--yes` 则全部取默认值, 全程零交互。
47
+
48
+ **目标目录**: 已存在且非空直接拒绝 (不做覆盖, 也没有 `--force` 逃生口; 覆盖的风险远大于那点便利); 已存在但为空的目录可用, 文件落进该目录。
49
+
50
+ 失败时打印原因并以非零退出码结束; 写入开始后失败留下的半成品目录会如实指出并保留 (不悄悄清理, 可自行查看或删除)。
51
+
52
+ ## 变量与旗标
53
+
54
+ 五个变量, 与模板的泛化词汇表一一对应:
55
+
56
+ - **项目名**: 位置参数 (目标目录的 basename) 或 `--name`; 没有默认值, 校验 kebab-case (如 `my-tool`);
57
+ - **scope**: `--scope`; 默认不带 (裸包名), 带时以 `@` 开头 (如 `@me`);
58
+ - **bin 名**: `--bin`; 默认由项目名派生短形态 (三段及以上取「首段 + 其余段首字母」: `sweep-node-modules` → `sweep-nm`);
59
+ - **owner**: `--owner`; 默认取 git 全局 `user.name`;
60
+ - **仓库地址**: `--repo`; 默认 `https://github.com/<owner>/<name>`。
61
+
62
+ 其余旗标:
63
+
64
+ - **`--tier <档>`**: `core` / `standard` / `full` 三选一, 默认 `standard`;
65
+ - **`--no-git`**: 跳过 `git init` (默认执行);
66
+ - **`--no-install`**: 跳过依赖安装 (默认执行);
67
+ - **`--yes`**: 全部取默认值, 零交互;
68
+ - **`--help`**: 打印帮助。
69
+
70
+ 经 `npm create` 调用时, 旗标要写在 `--` 后面 (`npm create clis -- --tier core`); 这个 `--` 由 npm 剥离, 是生态的既有行为, 生成器不参与。各变量的取值在收集那一刻就校验 (项目名 kebab-case、bin 名命令行可用、scope / owner / 仓库地址形态), 不合法当场给原因。
71
+
72
+ ## 档位
73
+
74
+ `--tier` 三选一, 默认 `standard`。三档是减法: `full` 是完整箱, `standard` 是 `full` 减增强档装备, `core` 是 `standard` 再减标准档装备。
75
+
76
+ - **core**: 工程骨架与发布闭环 (集合里每个仓库都默认全带的那一层);
77
+ - **standard** (默认): 再加标准档装备: 多包分层 (工具 + 库)、测试体系、技术债登记册;
78
+ - **full**: 再加增强档装备: 转写契约套件 (行为契约 + 金样本语料 + 确定性验收器 + 变异自证) 与它的台账对账闸门 (`lint:coverage`)。机制随模板, 内容要自填: `docs/sweep/protocol/` 下的契约 / 覆盖表 / 语料填上之前, `bun run ci` 会在 `lint:coverage` 与 `conformance:bun` / `conformance:node` 上红, full 档开箱不是全绿 (core 与 standard 是)。
79
+
80
+ 生成物恒为双包集合仓形态 (工具 + 库): 生成器不产出单包仓, 要单包的话生成后自行裁剪。档位只是生成那一刻的装箱单: 它不写进任何配置文件, 之后升降档是手工的按件增删 (裁剪规则见 [capability-tiers.md](../../docs/designs/capability-tiers.md))。
81
+
82
+ ## 生成物
83
+
84
+ 模板是派生出来的, 不是维护出来的: 像依赖锁文件由包管理器生成而不是手抄, 模板由生成器的构建步骤从本仓直接产出; 仓库改了, 下次构建就带上, 不需要人工同步。构建还带一道零残留自检: 模板里不得再出现原项目词汇, 出现即构建失败。
85
+
86
+ 生成物是一份独立的新集合仓, 从落成那一刻起就与本仓无持续关系 (生成即脱离): 生成器不提供对它的升级或同步, 模板之后的演进不回流进已生成的项目。它自带:
87
+
88
+ - **工程骨架**: workspaces / turbo / 根 tsconfig / 配置族 (oxlint / prettier / editorconfig / gitattributes / gitignorerc / nvmrc / bunfig) / 版本 pin;
89
+ - **提交与钩子链**: lefthook + `install-git-hooks` (机器上没有 lefthook 时降级) + `safe-install`;
90
+ - **闸门链单源**: `scripts/ci.ts` 是唯一一份步骤清单 (手动全链、pre-push、CI 与 Release 都从它走), `bun run ci` 一条命令跑完全套;
91
+ - **发布闭环**: semantic-release 自动发布, 凭据走 OIDC 可信发布 + environment 人工批准, 另有发布凭据预检与逐包发布自证;
92
+ - **文档体系**: docs 索引 / designs 最小单元组织 / ADR 模板 / CONTRIBUTING / SECURITY / 行为准则;
93
+ - **AI 协作文件**: AGENTS.md 与 `.vscode` 推荐配置;
94
+ - **两个示例包**: `<name>-cli` (CLI 薄壳) 与 `<name>` (库), 带一个 greet 最小示例, 整包替换成你自己的工具即可。
95
+
96
+ 生成按固定顺序跑: 收集变量 → 复制快照 → 按档裁剪 → 代入词汇 → 格式化收口 (回到 prettier 稳定态, 也就是产物自己 `format-check` 闸门的前提) → 残留自检 → 收尾 (`git init` 与依赖安装, 默认都执行)。完成后打印 next steps: 进入目录、`bun run ci` 验证全绿、从 `docs/README.md` (文档总索引) 读起, 开始改造。
97
+
98
+ 每个发布出去的版本都先自证过一遍: 拿它生成一个完整项目、装好依赖、把生成物的整套闸门链跑到全绿, 才允许发布。
99
+
100
+ ## 开发
101
+
102
+ 包脚本:
103
+
104
+ - `bun run build`: 一次产出两份东西: 模板资产 (`assets/template/`, 由骨架清单从本仓构建) 与可执行产物 (`dist/`, 含启动器对账用的清单);
105
+ - `bun run verify:release`: 发布前置校验: 干净检出、产物出自本提交、清单自洽、发行面包内文件与白名单相符;
106
+ - `bun run heavy-smoke`: 重量级冒烟: 现场生成一个 core 档完整项目, 跑它的整套闸门链, 全绿才算过。
107
+
108
+ `prepublishOnly` 按序串起三者, 发布出去的版本因此自带一份证明: 它生成的项目是绿的。设计与契约文档 (生成器包设计 / 契约 / 档位 / 快照机制) 都在 [docs/designs/](../../docs/designs/) 下。
109
+
110
+ ---
111
+
112
+ - 生成器包设计: [scaffold-package.md](../../docs/designs/scaffold-package.md);
113
+ - 包级文档入口: [docs/README.md](docs/README.md)。
@@ -0,0 +1,99 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "files": [
4
+ ".editorconfig",
5
+ ".gitattributes",
6
+ ".github/ISSUE_TEMPLATE/bug_report.yml",
7
+ ".github/ISSUE_TEMPLATE/feature_request.yml",
8
+ ".github/PULL_REQUEST_TEMPLATE.md",
9
+ ".github/workflows/ci.yml",
10
+ ".github/workflows/release.yml",
11
+ ".gitignorerc.json",
12
+ ".nvmrc",
13
+ ".oxlintrc.json",
14
+ ".prettierignore",
15
+ ".prettierrc",
16
+ ".releaserc.json",
17
+ ".vscode/extensions.json",
18
+ ".vscode/launch.json",
19
+ ".vscode/settings.json",
20
+ "AGENTS.md",
21
+ "CODE_OF_CONDUCT.md",
22
+ "CONTRIBUTING.md",
23
+ "CONTRIBUTING.zh-CN.md",
24
+ "LICENSE",
25
+ "README.md",
26
+ "README.zh-CN.md",
27
+ "SECURITY.md",
28
+ "_gitignore",
29
+ "_npmrc",
30
+ "bunfig.toml",
31
+ "docs/README.md",
32
+ "docs/adrs/README.md",
33
+ "docs/designs/README.md",
34
+ "docs/designs/tech-debt.md",
35
+ "docs/development.md",
36
+ "lefthook.yml",
37
+ "package.json",
38
+ "packages/{{NAME}}-cli/CHANGELOG.md",
39
+ "packages/{{NAME}}-cli/LICENSE",
40
+ "packages/{{NAME}}-cli/README.md",
41
+ "packages/{{NAME}}-cli/README.zh-CN.md",
42
+ "packages/{{NAME}}-cli/bin/{{BIN_NAME}}",
43
+ "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd",
44
+ "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts",
45
+ "packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs",
46
+ "packages/{{NAME}}-cli/docs/README.md",
47
+ "packages/{{NAME}}-cli/package.json",
48
+ "packages/{{NAME}}-cli/scripts/release-artifact.ts",
49
+ "packages/{{NAME}}-cli/scripts/release.fixtures.ts",
50
+ "packages/{{NAME}}-cli/scripts/verify-release.test.ts",
51
+ "packages/{{NAME}}-cli/scripts/verify-release.ts",
52
+ "packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts",
53
+ "packages/{{NAME}}-cli/scripts/write-dist-manifest.ts",
54
+ "packages/{{NAME}}-cli/src/cli.ts",
55
+ "packages/{{NAME}}-cli/tsconfig.json",
56
+ "packages/{{NAME}}/CHANGELOG.md",
57
+ "packages/{{NAME}}/LICENSE",
58
+ "packages/{{NAME}}/README.md",
59
+ "packages/{{NAME}}/README.zh-CN.md",
60
+ "packages/{{NAME}}/docs/README.md",
61
+ "packages/{{NAME}}/package.json",
62
+ "packages/{{NAME}}/scripts/build.ts",
63
+ "packages/{{NAME}}/scripts/verify-release.test.ts",
64
+ "packages/{{NAME}}/scripts/verify-release.ts",
65
+ "packages/{{NAME}}/src/index.ts",
66
+ "packages/{{NAME}}/tsconfig.build.json",
67
+ "packages/{{NAME}}/tsconfig.json",
68
+ "scripts/ci.ts",
69
+ "scripts/install-git-hooks.mjs",
70
+ "scripts/install-git-hooks.test.ts",
71
+ "scripts/lib/git-env.ts",
72
+ "scripts/lib/release-verify.ts",
73
+ "scripts/lib/tmp-root.ts",
74
+ "scripts/lib/workspace.test.ts",
75
+ "scripts/lib/workspace.ts",
76
+ "scripts/lint-doc-examples.test.ts",
77
+ "scripts/lint-doc-examples.ts",
78
+ "scripts/lint-doc-references.test.ts",
79
+ "scripts/lint-doc-references.ts",
80
+ "scripts/lint-doc-shared.ts",
81
+ "scripts/lint-stray-backups.test.ts",
82
+ "scripts/lint-stray-backups.ts",
83
+ "scripts/npm-trust-guard.test.ts",
84
+ "scripts/npm-trust-guard.ts",
85
+ "scripts/safe-install.ts",
86
+ "scripts/transcription/api-harness.ts",
87
+ "scripts/transcription/compare.ts",
88
+ "scripts/transcription/corpus.ts",
89
+ "scripts/transcription/fixture.ts",
90
+ "scripts/transcription/make-mutants.ts",
91
+ "scripts/transcription/report.ts",
92
+ "scripts/transcription/run-conformance.ts",
93
+ "scripts/transcription/validate-coverage.test.ts",
94
+ "scripts/transcription/validate-coverage.ts",
95
+ "scripts/transcription/validate.ts",
96
+ "tsconfig.json",
97
+ "turbo.jsonc"
98
+ ]
99
+ }
@@ -0,0 +1,12 @@
1
+ root = true
2
+
3
+ [*]
4
+ indent_style = space
5
+ indent_size = 2
6
+ end_of_line = lf
7
+ charset = utf-8
8
+ trim_trailing_whitespace = true
9
+ insert_final_newline = true
10
+
11
+ [*.md]
12
+ trim_trailing_whitespace = false
@@ -0,0 +1,18 @@
1
+ # 文本文件入库与检出态统一 LF (跨平台一致性在 git 层兜底; .editorconfig 的
2
+ # end_of_line 只约束编辑器)
3
+ * text=auto eol=lf
4
+
5
+ # 二进制: 不做行尾转换与文本 diff
6
+ *.png binary
7
+ *.jpg binary
8
+ *.jpeg binary
9
+ *.gif binary
10
+ *.ico binary
11
+ *.pdf binary
12
+ *.woff binary
13
+ *.woff2 binary
14
+ *.ttf binary
15
+
16
+ # 生成物: 折叠展示, 不计入语言统计
17
+ bun.lock linguist-generated=true
18
+ packages/*/CHANGELOG.md linguist-generated=true
@@ -0,0 +1,86 @@
1
+ name: Bug report
2
+ description: Report a problem with the CLI or the programmable API package.
3
+ title: "[Bug]:\x20"
4
+ labels: ['bug']
5
+ body:
6
+ - type: markdown
7
+ attributes:
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.
12
+ - type: checkboxes
13
+ id: preflight
14
+ attributes:
15
+ label: Preflight checklist
16
+ options:
17
+ - label: I searched the existing issues and did not find this report.
18
+ required: true
19
+ - label: I can reproduce this on the latest published version, or on the current main branch from a clone.
20
+ required: true
21
+ - type: input
22
+ id: version
23
+ attributes:
24
+ 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'
27
+ validations:
28
+ required: true
29
+ - type: dropdown
30
+ id: os
31
+ attributes:
32
+ label: Operating system
33
+ options:
34
+ - Windows
35
+ - macOS
36
+ - Linux
37
+ - Other
38
+ validations:
39
+ required: true
40
+ - type: input
41
+ id: runtime
42
+ attributes:
43
+ 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
58
+ validations:
59
+ required: true
60
+ - type: textarea
61
+ id: steps
62
+ attributes:
63
+ 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
+ validations:
66
+ required: true
67
+ - type: textarea
68
+ id: actual
69
+ attributes:
70
+ label: Actual behavior
71
+ description: What happened, including the full output if possible. Error messages carry an error code; include it.
72
+ render: shell
73
+ validations:
74
+ required: true
75
+ - type: textarea
76
+ id: expected
77
+ attributes:
78
+ label: Expected behavior
79
+ description: What should have happened instead.
80
+ validations:
81
+ 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.
@@ -0,0 +1,45 @@
1
+ name: Feature request
2
+ description: Suggest an idea or an improvement for the CLI or the programmable API package.
3
+ title: "[Feature]:\x20"
4
+ labels: ['enhancement']
5
+ body:
6
+ - type: markdown
7
+ attributes:
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.
10
+ - type: checkboxes
11
+ id: preflight
12
+ attributes:
13
+ label: Preflight checklist
14
+ options:
15
+ - label: I searched the existing issues and did not find this request.
16
+ required: true
17
+ - type: dropdown
18
+ id: area
19
+ attributes:
20
+ label: Area
21
+ description: Which part of the project is this about?
22
+ options:
23
+ - CLI ({{BIN_NAME}})
24
+ - Programmable API ({{SCOPE}}/{{NAME}})
25
+ - Documentation
26
+ - Other
27
+ validations:
28
+ required: true
29
+ - type: textarea
30
+ id: problem
31
+ attributes:
32
+ 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
+ validations:
35
+ required: true
36
+ - type: textarea
37
+ id: solution
38
+ attributes:
39
+ 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.
@@ -0,0 +1,26 @@
1
+ <!-- Thanks for contributing. Keep this pull request focused on one topic, and fill in the sections below. -->
2
+
3
+ ## Summary
4
+
5
+ <!-- What does this change, and why? -->
6
+
7
+ ## Related issue
8
+
9
+ <!-- The issue this addresses, for example: Closes #123. Write None if there is no issue. -->
10
+
11
+ ## Type of change
12
+
13
+ - [ ] Bug fix
14
+ - [ ] New feature
15
+ - [ ] Refactor or other internal change
16
+ - [ ] Documentation
17
+ - [ ] Other
18
+
19
+ ## Checklist
20
+
21
+ - [ ] I agree to follow this project's [Code of Conduct](/CODE_OF_CONDUCT.md).
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`).
26
+ - [ ] Commits follow the repository convention: a Conventional Commits prefix, one topic per commit.
@@ -0,0 +1,42 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ verify:
13
+ runs-on: ubuntu-latest
14
+ timeout-minutes: 20
15
+ steps:
16
+ - uses: actions/checkout@v7
17
+ - uses: oven-sh/setup-bun@v2
18
+ - uses: actions/setup-node@v7
19
+ with:
20
+ node-version: 24
21
+ - name: Install
22
+ run: bun install --frozen-lockfile
23
+ # 验证组 (步骤集合的单一事实来源在 scripts/ci.ts, 与本地全链 / Release verify 同集合)
24
+ - name: Verify (ci.ts --verify)
25
+ run: bun run ci -- --verify
26
+
27
+ # 转写验收 (逐字节金样本) 的语料为 macOS 文件系统口径录制 (du 磁盘占用含块分配差异:
28
+ # 同一 fixture 在 APFS 计 8 KB, 在 ext4 因目录节点再计 4 KB → 12 KB), 故在 macOS runner
29
+ # 执行, 与语料录制环境同源; 它长期以来的运行环境即 macOS (手动双跑)。
30
+ conformance:
31
+ runs-on: macos-latest
32
+ timeout-minutes: 15
33
+ steps:
34
+ - uses: actions/checkout@v7
35
+ - uses: oven-sh/setup-bun@v2
36
+ - uses: actions/setup-node@v7
37
+ with:
38
+ node-version: 24
39
+ - run: bun install --frozen-lockfile
40
+ # 验收组 (含 build: node target 需 dist 前置, 理由见 scripts/ci.ts 的组注释)
41
+ - name: Conformance (ci.ts --conformance)
42
+ run: bun run ci -- --conformance
@@ -0,0 +1,65 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ concurrency:
11
+ group: release
12
+ cancel-in-progress: false
13
+
14
+ 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
28
+
29
+ # 人工批准闸门 (environment: release, 配 required reviewers): 批准后才进入发布。
30
+ # OIDC 发布: 不设任何 npm token; id-token: write 供 Trusted Publishing 换取短寿命凭据。
31
+ release:
32
+ needs: verify
33
+ runs-on: ubuntu-latest
34
+ timeout-minutes: 30
35
+ environment: release
36
+ permissions:
37
+ contents: write # 打 tag / push 版本提交 / 建 GitHub Release
38
+ issues: write # release 评论
39
+ pull-requests: write # release 评论
40
+ id-token: write # npm Trusted Publishing (OIDC)
41
+ steps:
42
+ - uses: actions/checkout@v7
43
+ with:
44
+ fetch-depth: 0 # semantic-release 需要全历史与全部 tag
45
+ - uses: oven-sh/setup-bun@v2
46
+ - uses: actions/setup-node@v7
47
+ with:
48
+ node-version: 24 # 自带 npm 11.x: OIDC 与 provenance 所需
49
+ # 不设 registry-url: 它会生成带 NODE_AUTH_TOKEN 的 .npmrc, 压掉 OIDC 通道
50
+ - run: bun install --frozen-lockfile
51
+ # 发布凭据预检 (发布特有, 经 ci.ts 单源调用): OIDC 换证即与 npm 侧 Trusted Publisher
52
+ # 登记的全量核对 (含 environment 声明), 失配在发布前当场点名。必须放本 job: environment
53
+ # 声明来自 job 的 environment, 无 environment 的 job 换证会被 npm 以误导性的 404 拒绝
54
+ - run: bun run ci -- --only npm-trust
55
+ - 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
+ run: bunx --no-install multi-semantic-release
61
+ env:
62
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
63
+ # npm 命令 (semrel prepare 的 npm version) 在 workspace 子包内运行, 会尝试生成
64
+ # package-lock.json 而弄脏发布闸门的「工作树干净」判定; env 通道优先于一切配置文件
65
+ npm_config_package_lock: 'false'