create-clis 0.1.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
@@ -0,0 +1,45 @@
1
+ {
2
+ "version": "2.0.0",
3
+ "tasks": [
4
+ {
5
+ "label": "CI: Full (bun run ci)",
6
+ "type": "shell",
7
+ "command": "bun run ci",
8
+ "group": {
9
+ "kind": "test",
10
+ "isDefault": true
11
+ },
12
+ "presentation": {
13
+ "reveal": "always",
14
+ "panel": "shared"
15
+ }
16
+ },
17
+ {
18
+ "label": "CI: Verify (bun run ci -- --verify)",
19
+ "type": "shell",
20
+ "command": "bun run ci -- --verify",
21
+ "group": "test"
22
+ },
23
+ {
24
+ "label": "Build All Packages",
25
+ "type": "shell",
26
+ "command": "bun run build",
27
+ "group": {
28
+ "kind": "build",
29
+ "isDefault": true
30
+ }
31
+ },
32
+ {
33
+ "label": "Typecheck All",
34
+ "type": "shell",
35
+ "command": "bun run typecheck",
36
+ "group": "test"
37
+ },
38
+ {
39
+ "label": "Test All",
40
+ "type": "shell",
41
+ "command": "bun run test",
42
+ "group": "test"
43
+ }
44
+ ]
45
+ }
@@ -15,11 +15,11 @@ This block is written and re-added by `turbo` before repository-scoped commands
15
15
 
16
16
  ## 文档分层与读取路径
17
17
 
18
- - **仓库级文档**在 `docs/`: 先读[文档总索引](docs/README.md); 仓库级设计的入口是[设计文档索引](docs/designs/README.md);
19
- - **包级文档**在各包 `packages/*/docs/`, 入口固定是包内 `docs/README.md` (里面有该包的文档清单、包级 ADR 和指回上级的链接);
20
- - **ADR 编号全仓库共用一套, 不会重号**: 仓库级的在 `docs/adrs/`, 包级的在各包 `docs/adrs/`; 总索引 [docs/adrs/README.md](docs/adrs/README.md) 列出全部编号。
18
+ - **仓库级文档**在 `docs/`: 先读[文档总索引](docs/README.md); 仓库级设计的入口是[设计文档索引](docs/designs/README.md), 仓库级 ADR 入口是 [docs/adrs/README.md](docs/adrs/README.md);
19
+ - **包级文档**按需建在各包 `packages/<pkg>/docs/` (无独立包内文档时不建空壳目录, 总索引直链包根 `README.md`), 存在包内文档时入口为 `packages/<pkg>/docs/README.md`;
20
+ - **ADR 编号全仓库共用一套四位递增编号, 跨级唯一、永不重编**: 仓库级 ADR 位于 `docs/adrs/` 并仅登记在 [docs/adrs/README.md](docs/adrs/README.md); 包级 ADR 位于各包 `packages/<pkg>/docs/adrs/` 并去中心化登记在各自 `packages/<pkg>/docs/adrs/README.md`, 引用闸门联合扫描两级防重号。
21
21
 
22
22
  ## 结构事实
23
23
 
24
- - 工程闸门链只有一份步骤清单, 就是 `scripts/ci.ts` (本地全链、pre-push、CI、Release verify 跑的是同一套);
24
+ - 工程闸门链只有一份步骤清单, 就是 `scripts/ci.ts` (本地全链、pre-push、CI 与 Release 前置门禁共用; Release 获批后额外经 `--only npm-trust` 跑 OIDC 凭据预检, 见 [开发指南](docs/development.md)「发布」章);
25
25
  - 提交信息与发布链的约定见 [CONTRIBUTING.md](CONTRIBUTING.md)。
@@ -13,7 +13,7 @@ Everyone taking part in this project is covered by the [Code of Conduct](CODE_OF
13
13
  - Send a change: open a pull request. For anything beyond a small fix, open an issue first, so the approach can be settled before work starts.
14
14
  - Report a security problem: do not open a public issue; follow [SECURITY.md](SECURITY.md).
15
15
 
16
- <!-- 模板骨架: 示例包是占位实现; 换成自己的工具后, 同步下面「Repository layout」与两条命令示例。 -->
16
+ <!-- 模板骨架: 示例包是占位实现; 换成自己的工具后, 同步下面「Repository layout」。 -->
17
17
 
18
18
  ## Repository layout
19
19
 
@@ -35,20 +35,22 @@ Prerequisites: bun and node.
35
35
  bun install
36
36
  ```
37
37
 
38
- The hooks check code on the way in (pre-commit: a project-wide type check, plus prettier and oxlint over the staged files) and re-run the full checks before a push (pre-push runs `bun scripts/ci.ts`, the single source of the gate list). Where lefthook is not installed, the hook chain falls back to a pinned version fetched through bunx. Configuration: [lefthook.yml](lefthook.yml).
38
+ The hooks check code on the way in (pre-commit: a project-wide `bun check`, plus `bun fmt` and oxlint over the staged files) and re-run the full checks before a push (pre-push runs `bun scripts/ci.ts`, the single source of the gate list). Where lefthook is not installed, the hook chain falls back to a pinned version fetched through bunx. Configuration: [lefthook.yml](lefthook.yml).
39
+
40
+ Manage custom ignore entries in `.gitignorerc.json` and regenerate `.gitignore` via `fgi` rather than editing `.gitignore` directly.
39
41
 
40
42
  ## Common commands
41
43
 
42
44
  Run from the repository root:
43
45
 
44
46
  ```shell
45
- # Type check (tsc --noEmit, through turbo)
47
+ # Type check (bun check, through turbo)
46
48
  bun run typecheck
47
49
 
48
50
  # Lint (oxlint); `bun run lint:fix` applies the automatic fixes
49
51
  bun run lint
50
52
 
51
- # Format (prettier --write .)
53
+ # Format (bun fmt)
52
54
  bun run format
53
55
 
54
56
  # Tests (through turbo; `bun test` runs the test runner directly)
@@ -13,7 +13,7 @@
13
13
  - 提改动: 开一个 pull request。超出小修的改动请先开 issue, 把做法谈定再动手;
14
14
  - 报安全问题: 不要开公开 issue, 按 [SECURITY.md](SECURITY.md) 走。
15
15
 
16
- <!-- 模板骨架: 示例包是占位实现; 换成自己的工具后, 同步下面「仓库结构」与两条命令示例。 -->
16
+ <!-- 模板骨架: 示例包是占位实现; 换成自己的工具后, 同步下面「仓库结构」。 -->
17
17
 
18
18
  ## 仓库结构
19
19
 
@@ -35,20 +35,22 @@
35
35
  bun install
36
36
  ```
37
37
 
38
- 钩子在入口把关 (pre-commit: 全项目类型检查 + prettier / oxlint 扫暂存文件), 推送前再跑一遍全量检查 (pre-push 跑 `bun scripts/ci.ts`, 步骤清单的单一来源)。机器上没有 lefthook 时, 钩子链经 bunx 取 pin 版兜底。配置见 [lefthook.yml](lefthook.yml)。
38
+ 钩子在入口把关 (pre-commit: 全项目 `bun check` 类型检查 + `bun fmt` / oxlint 扫暂存文件), 推送前再跑一遍全量检查 (pre-push 跑 `bun scripts/ci.ts`, 步骤清单的单一来源)。机器上没有 lefthook 时, 钩子链经 bunx 取 pin 版兜底。配置见 [lefthook.yml](lefthook.yml)。
39
+
40
+ 仓库的 `.gitignore` 由 `.gitignorerc.json` 维护, 新增规则请写入 `.gitignorerc.json` 的 `custom` 数组并重跑 `fgi`, 不要直接手改 `.gitignore`。
39
41
 
40
42
  ## 常用命令
41
43
 
42
44
  以下命令均在仓库根执行:
43
45
 
44
46
  ```shell
45
- # 类型检查 (tsc --noEmit, 经 turbo)
47
+ # 类型检查 (bun check, 经 turbo)
46
48
  bun run typecheck
47
49
 
48
50
  # 代码检查 (oxlint); `bun run lint:fix` 自动修复
49
51
  bun run lint
50
52
 
51
- # 格式化 (prettier --write .)
53
+ # 格式化 (bun fmt)
52
54
  bun run format
53
55
 
54
56
  # 测试 (经 turbo; `bun test` 直跑测试器)
@@ -1,409 +1,11 @@
1
- # It's better to unpack these files and commit the raw source because
2
- # git has its own built in compression methods.
3
- *.7z
4
- *.jar
5
- *.rar
6
- *.zip
7
- *.gz
8
- *.gzip
9
- *.tgz
10
- *.bzip
11
- *.bzip2
12
- *.bz2
13
- *.xz
14
- *.lzma
15
- *.cab
16
- *.xar
17
-
18
- # Packing-only formats
19
- *.iso
20
- *.tar
21
-
22
- # Package management formats
23
- *.dmg
24
- *.xpi
25
- *.gem
26
- *.egg
27
- *.deb
28
- *.rpm
29
- *.msi
30
- *.msm
31
- *.msp
32
- *.txz
33
-
34
-
35
-
36
- # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
37
- # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
38
-
39
- # User-specific stuff
40
- .idea/**/workspace.xml
41
- .idea/**/tasks.xml
42
- .idea/**/usage.statistics.xml
43
- .idea/**/dictionaries
44
- .idea/**/shelf
45
-
46
- # AWS User-specific
47
- .idea/**/aws.xml
48
-
49
- # Generated files
50
- .idea/**/contentModel.xml
51
-
52
- # Sensitive or high-churn files
53
- .idea/**/dataSources/
54
- .idea/**/dataSources.ids
55
- .idea/**/dataSources.local.xml
56
- .idea/**/sqlDataSources.xml
57
- .idea/**/dynamic.xml
58
- .idea/**/uiDesigner.xml
59
- .idea/**/dbnavigator.xml
60
-
61
- # Gradle
62
- .idea/**/gradle.xml
63
- .idea/**/libraries
64
-
65
- # Gradle and Maven with auto-import
66
- # When using Gradle or Maven with auto-import, you should exclude module files,
67
- # since they will be recreated, and may cause churn. Uncomment if using
68
- # auto-import.
69
- # .idea/artifacts
70
- # .idea/compiler.xml
71
- # .idea/jarRepositories.xml
72
- # .idea/modules.xml
73
- # .idea/*.iml
74
- # .idea/modules
75
- # *.iml
76
- # *.ipr
77
-
78
- # CMake
79
- cmake-build-*/
80
-
81
- # Mongo Explorer plugin
82
- .idea/**/mongoSettings.xml
83
-
84
- # File-based project format
85
- *.iws
86
-
87
- # IntelliJ
88
- out/
89
-
90
- # mpeltonen/sbt-idea plugin
91
- .idea_modules/
92
-
93
- # JIRA plugin
94
- atlassian-ide-plugin.xml
95
-
96
- # Cursive Clojure plugin
97
- .idea/replstate.xml
98
-
99
- # SonarLint plugin
100
- .idea/sonarlint/
101
-
102
- # Crashlytics plugin (for Android Studio and IntelliJ)
103
- com_crashlytics_export_strings.xml
104
- crashlytics.properties
105
- crashlytics-build.properties
106
- fabric.properties
107
-
108
- # Editor-based Rest Client
109
- .idea/httpRequests
110
-
111
- # Android studio 3.1+ serialized cache file
112
- .idea/caches/build_file_checksums.ser
113
-
114
-
115
-
116
- *~
117
-
118
- # temporary files which can be created if a process still has a handle open of a deleted file
119
- .fuse_hidden*
120
-
121
- # KDE directory preferences
122
- .directory
123
-
124
- # Linux trash folder which might appear on any partition or disk
125
- .Trash-*
126
-
127
- # .nfs files are created when an open file is removed but is still being accessed
128
- .nfs*
129
-
130
-
131
-
132
- # Logs
133
- logs
134
- *.log
135
- npm-debug.log*
136
- yarn-debug.log*
137
- yarn-error.log*
138
- lerna-debug.log*
139
- .pnpm-debug.log*
140
-
141
- # Diagnostic reports (https://nodejs.org/api/report.html)
142
- report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
143
-
144
- # Runtime data
145
- pids
146
- *.pid
147
- *.seed
148
- *.pid.lock
149
-
150
- # Directory for instrumented libs generated by jscoverage/JSCover
151
- lib-cov
152
-
153
- # Coverage directory used by tools like istanbul
154
- coverage
155
- *.lcov
156
-
157
- # nyc test coverage
158
- .nyc_output
159
-
160
- # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
161
- .grunt
162
-
163
- # Bower dependency directory (https://bower.io/)
164
- bower_components
165
-
166
- # node-waf configuration
167
- .lock-wscript
168
-
169
- # Compiled binary addons (https://nodejs.org/api/addons.html)
170
- build/Release
171
-
172
- # Dependency directories
1
+ # Generated baseline; manage custom entries in .gitignorerc.json and re-run `fgi` when updating.
173
2
  node_modules/
174
- jspm_packages/
175
-
176
- # Snowpack dependency directory (https://snowpack.dev/)
177
- web_modules/
178
-
179
- # TypeScript cache
180
- *.tsbuildinfo
181
-
182
- # Optional npm cache directory
183
- .npm
184
-
185
- # Optional eslint cache
186
- .eslintcache
187
-
188
- # Optional stylelint cache
189
- .stylelintcache
190
-
191
- # Microbundle cache
192
- .rpt2_cache/
193
- .rts2_cache_cjs/
194
- .rts2_cache_es/
195
- .rts2_cache_umd/
196
-
197
- # Optional REPL history
198
- .node_repl_history
199
-
200
- # Output of 'npm pack'
201
- *.tgz
202
-
203
- # Yarn Integrity file
204
- .yarn-integrity
205
-
206
- # dotenv environment variable files
207
- .env
208
- .env.development.local
209
- .env.test.local
210
- .env.production.local
211
- .env.local
212
-
213
- # parcel-bundler cache (https://parceljs.org/)
214
- .cache
215
- .parcel-cache
216
-
217
- # Next.js build output
218
- .next
219
- out
220
-
221
- # Nuxt.js build / generate output
222
- .nuxt
223
- dist
224
-
225
- # Gatsby files
226
- .cache/
227
- # Comment in the public line in if your project uses Gatsby and not Next.js
228
- # https://nextjs.org/blog/next-9-1#public-directory-support
229
- # public
230
-
231
- # vuepress build output
232
- .vuepress/dist
233
-
234
- # vuepress v2.x temp and cache directory
235
- .temp
236
- .cache
237
-
238
- # Docusaurus cache and generated files
239
- .docusaurus
240
-
241
- # Serverless directories
242
- .serverless/
243
-
244
- # FuseBox cache
245
- .fusebox/
246
-
247
- # DynamoDB Local files
248
- .dynamodb/
249
-
250
- # TernJS port file
251
- .tern-port
252
-
253
- # Stores VSCode versions used for testing VSCode extensions
254
- .vscode-test
255
-
256
- # yarn v2
257
- .yarn/cache
258
- .yarn/unplugged
259
- .yarn/build-state.yml
260
- .yarn/install-state.gz
261
- .pnp.*
262
-
263
-
264
-
265
- # Cache files for Sublime Text
266
- *.tmlanguage.cache
267
- *.tmPreferences.cache
268
- *.stTheme.cache
269
-
270
- # Workspace files are user-specific
271
- *.sublime-workspace
272
-
273
- # Project files should be checked into the repository, unless a significant
274
- # proportion of contributors will probably not be using Sublime Text
275
- # *.sublime-project
276
-
277
- # SFTP configuration file
278
- sftp-config.json
279
- sftp-config-alt*.json
280
-
281
- # Package control specific files
282
- Package Control.last-run
283
- Package Control.ca-list
284
- Package Control.ca-bundle
285
- Package Control.system-ca-bundle
286
- Package Control.cache/
287
- Package Control.ca-certs/
288
- Package Control.merged-ca-bundle
289
- Package Control.user-ca-bundle
290
- oscrypto-ca-bundle.crt
291
- bh_unicode_properties.cache
292
-
293
- # Sublime-github package stores a github token in this file
294
- # https://packagecontrol.io/packages/sublime-github
295
- GitHub.sublime-settings
296
-
297
-
298
-
299
- # Swap
300
- [._]*.s[a-v][a-z]
301
- !*.svg # comment out if you don't need vector files
302
- [._]*.sw[a-p]
303
- [._]s[a-rt-v][a-z]
304
- [._]ss[a-gi-z]
305
- [._]sw[a-p]
306
-
307
- # Session
308
- Session.vim
309
- Sessionx.vim
310
-
311
- # Temporary
312
- .netrwhist
313
- *~
314
- # Auto-generated tag files
315
- tags
316
- # Persistent undo
317
- [._]*.un~
318
-
319
-
320
-
321
- .vscode/*
322
- !.vscode/settings.json
323
- !.vscode/tasks.json
324
- !.vscode/launch.json
325
- !.vscode/extensions.json
326
- !.vscode/*.code-snippets
327
-
328
- # Local History for Visual Studio Code
329
- .history/
330
-
331
- # Built Visual Studio Code Extensions
332
- *.vsix
333
-
334
-
335
-
336
- # Windows thumbnail cache files
337
- Thumbs.db
338
- Thumbs.db:encryptable
339
- ehthumbs.db
340
- ehthumbs_vista.db
341
-
342
- # Dump file
343
- *.stackdump
344
-
345
- # Folder config file
346
- [Dd]esktop.ini
347
-
348
- # Recycle Bin used on file shares
349
- $RECYCLE.BIN/
350
-
351
- # Windows Installer files
352
- *.cab
353
- *.msi
354
- *.msix
355
- *.msm
356
- *.msp
357
-
358
- # Windows shortcuts
359
- *.lnk
360
-
361
-
362
-
363
- # General
3
+ dist/
4
+ coverage/
5
+ .turbo/
364
6
  .DS_Store
365
- .AppleDouble
366
- .LSOverride
367
-
368
- # Icon must end with two \r
369
- Icon
370
-
371
- # Thumbnails
372
- ._*
373
-
374
- # Files that might appear in the root of a volume
375
- .DocumentRevisions-V100
376
- .fseventsd
377
- .Spotlight-V100
378
- .TemporaryItems
379
- .Trashes
380
- .VolumeIcon.icns
381
- .com.apple.timemachine.donotpresent
382
-
383
- # Directories potentially created on remote AFP share
384
- .AppleDB
385
- .AppleDesktop
386
- Network Trash Folder
387
- Temporary Items
388
- .apdisk
389
-
390
-
391
-
392
- package-lock.json
393
-
394
-
7
+ Thumbs.db
395
8
  *.log
396
-
397
-
9
+ package-lock.json
398
10
  *.modified
399
-
400
-
401
- packages/{{NAME}}/bench/results/
402
-
403
-
404
- scripts/transcription/mutants/gen-*/
405
-
406
-
407
- .turbo/
408
-
409
- packages/create-clis/assets/
11
+ *.deleted
@@ -1,16 +1,7 @@
1
1
  # bun 配置
2
- # linker = "hoisted" 是让 oxlint / prettier 等 Node CJS 工具链能正确解析
3
- # peer dependency 的关键。若改成 isolated, 这些工具的插件会解析到全局缓存
4
- # 的符号链接路径, 而 peer 依赖落在平行缓存目录, 找不到, 工具链直接报错。
2
+ # linker = "hoisted" 确保 oxlint / typescript 等 Node CJS 工具链能解析 peer dependency。
3
+ # 默认使用官方 npm registry; 如需本机镜像加速, 请在个人 ~/.bunfig.toml 配置。
5
4
 
6
5
  [install]
7
6
  frozenLockfile = false
8
7
  linker = "hoisted"
9
- registry = "https://registry.npmmirror.com"
10
-
11
- # 测试发现面: packages/create-clis/assets 是生成器按骨架清单产出的模板资产 (目录结构是
12
- # 「新项目根」, 内含从本仓复制过去的 *.test.ts), 不是本仓的测试; 排除它们, 防其在生成器
13
- # 语境里被误跑 (同款排除见 .gitignore / .prettierignore / .oxlintrc.json 与 tsconfig.json;
14
- # 包内一次测试由 packages/create-clis 的 test 脚本自带同款旗标)
15
- [test]
16
- pathIgnorePatterns = ["packages/create-clis/assets/**"]
@@ -8,15 +8,15 @@
8
8
 
9
9
  ## 决策与模板
10
10
 
11
- **架构决策记录**
12
- [架构决策记录索引](adrs/README.md)
13
- 收录本仓演进过程中的重大技术决策 (ADRs), 以及当时的背景与权衡; 新项目从 0001 起编号。
11
+ **仓库级架构决策记录**
12
+ [仓库级架构决策记录索引](adrs/README.md)
13
+ 仅登记仓库级工程与治理决策 (ADRs); 全仓共用四位递增编号 (新项目从 0001 起), 包级 ADR 去中心化登记在各自 `packages/<pkg>/docs/adrs/README.md`。
14
14
 
15
15
  ## 设计文档
16
16
 
17
17
  **设计文档索引 (仓库级)**
18
18
  [设计文档索引](designs/README.md)
19
- 仓库级设计 (仓库治理与脚手架) 的登记入口与推荐阅读顺序; 包级设计在各包 `packages/*/docs/designs/` 内。
19
+ 仓库级设计 (仓库治理与脚手架) 的登记入口与推荐阅读顺序; 包级设计按需建在各包 `packages/<pkg>/docs/designs/` 内。
20
20
 
21
21
  ## 开发
22
22
 
@@ -26,5 +26,5 @@
26
26
 
27
27
  ## 包
28
28
 
29
- - [API 包文档入口](../packages/{{NAME}}/docs/README.md) (可编程 API 与包级 ADR);
30
- - [CLI 包文档入口](../packages/{{NAME}}-cli/docs/README.md) (命令用法与输出)。
29
+ - [API 包 README](../packages/{{NAME}}/README.md) (可编程 API; 有专属设计或包级 ADR 时按需在包内创建 `docs/`);
30
+ - [CLI 包 README](../packages/{{NAME}}-cli/README.md) (命令用法与输出; 有专属命令面设计时按需在包内创建 `docs/`)。
@@ -1,6 +1,8 @@
1
- # 架构决策记录索引
1
+ # 仓库级架构决策记录索引
2
2
 
3
- 这里按编号顺序列出本仓全部 ADR。新增决策顺延编新编号; 已接受的记录不回头改, 要修订, 就写新 ADR 或补充说明。编号全局唯一, 仓库级和包级共用一套编号。
3
+ 本表仅登记**仓库级工程与治理 ADR** (`docs/adrs/` 下的记录)。新增决策按全仓最大号顺延四位递增编号; 已接受的记录不原地改写, 要修订就写新 ADR 或补充说明。
4
+
5
+ > 分层说明: 全仓共用一套全局唯一四位编号 (由 `scripts/lint-doc-references.ts` 联合扫描仓级与包级 `docs/adrs/` 防幽灵编号与重号碰撞); 包级 ADR 随各自包内聚存放并登记在各自 `packages/<pkg>/docs/adrs/README.md`, 不在本表重复手抄。
4
6
 
5
7
  | 编号 | 标题 | 状态 | 日期 |
6
8
  | ---- | ---- | ---- | ---- |
@@ -16,41 +16,47 @@ bun install
16
16
  以下命令除注明外均在仓库根执行:
17
17
 
18
18
  ```shell
19
- # 类型检查 (tsc --noEmit; 经 turbo 编排各包)
19
+ # 类型检查 (bun check; 经 turbo 编排各包)
20
20
  bun run typecheck
21
21
 
22
22
  # 代码检查 (oxlint)
23
23
  bun run lint
24
24
 
25
- # 格式化 (prettier --write)
25
+ # 格式化 (bun fmt)
26
26
  bun run format
27
27
 
28
28
  # 测试 (经 turbo 编排各包, 带缓存)
29
29
  bun run test
30
30
 
31
- # 本地 CI 预演 (与 GitHub Actions 的 verify job 同集合; 推前必跑, pre-push 钩子按同集合自动执行)
31
+ # 本地 CI 预演 (与 GitHub Actions 同集合; 推前必跑, pre-push 钩子自动执行)
32
32
  bun run ci
33
33
 
34
34
  # 打包各包发布产物; 发布时由各自的 prepublishOnly 自动跑
35
35
  bun run build
36
+
37
+ # 干净重装 (清掉全部工作区包产物 / 锁文件 / node_modules 后重新 bun install)
38
+ bun run safe-install
36
39
  ```
37
40
 
41
+ > 双运行时提示: 机器上未安装的运行时 (bun / node) 在单测中会被跳过, 完整验证请同时安装两者。
42
+
38
43
  ## 提交与推送
39
44
 
40
45
  由 lefthook 把关 (操作级细节以仓库根 `lefthook.yml` 为准):
41
46
 
42
- - **pre-commit** (增量): prettier 重暂存 + oxlint 扫暂存文件; 类型检查例外, 跑全项目 `tsc --noEmit`;
43
- - **pre-push** (全量): 单条调用 `bun scripts/ci.ts`; 步骤集合的单一事实来源在 `scripts/ci.ts`, CI 与 Release 的 verify job 共用同一套步骤定义。
47
+ - **pre-commit** (增量): `bun fmt` 重暂存 + oxlint 扫暂存文件; 类型检查例外, 跑全项目 `bun run typecheck`;
48
+ - **pre-push** (全量): 单条调用 `bun scripts/ci.ts`; 步骤集合的单一事实来源在 `scripts/ci.ts`, CI 与 Release 的前置门禁共用同一套步骤定义。
44
49
 
45
50
  提交信息按 Conventional Commits 前缀 (`feat` / `fix` / `chore` / `test` 等), 并守单一主题原则: 一个提交只含一个完整逻辑变更, 跨主题须拆分。
46
51
 
47
52
  ## 发布
48
53
 
49
- 主路径是 CI 自动链 (`.github/workflows/release.yml`): 推送到 `main` 后, `verify` job 先跑与 CI 同套的检查, 通过后 `release` job 停在 `environment: release` 的人工批准闸门外, 批准即由 multi-semantic-release 执行发布; npm 侧走 OIDC Trusted Publishing, 不设 token、无 OTP。
50
-
51
- 发布动作统一过 `prepublishOnly` 闸门 (链上链下同一道, 各包各自): 构建 (`bun run build`) + 发布前置闸门 (`bun run verify:release`, 在各自包目录跑); 闸门按序短路, 任一命中即退 1 拒发。
54
+ 主路径是 CI 自动链 (`.github/workflows/release.yml`): 推送到 `main` 后, `checks` job 直接通过 `workflow_call` 复用 `.github/workflows/ci.yml` 的全部验证与兼容检查 (零双跑), 通过后 `release` job 停在 `environment: release` 的人工批准闸门外, 批准后先经 `bun run ci -- --only npm-trust` 做 OIDC Trusted Publisher 预检, 通过即由 multi-semantic-release 执行免密发布。
52
55
 
53
- **README / LICENSE 类备份别落包目录**: npm 会把包根的 `README*` / `LICENSE*` 无条件收进发行包, 且没有任何配置可以排除; 备份一律落仓库外。
56
+ - **本地凭据对账与修复**: `bun scripts/npm-trust-guard.ts check` 只读核对 npm Trusted Publisher 登记, `bun scripts/npm-trust-guard.ts fix` 自动创建或重建登记 (需 npm 登录态与交互式终端);
57
+ - **待首发新包隔离**: 尚未首发的新包在自身 `package.json` 标 `"private": true`, 首发时移除并完成首次发布与 Trusted Publisher 登记;
58
+ - **包级前置闸门**: 发布动作统一过 `prepublishOnly` (`build` + `verify:release`), 任一检查不过即退 1 拒发;
59
+ - **README / LICENSE 类备份别落包目录**: npm 会把包根的 `README*` / `LICENSE*` 无条件收进发行包, 备份一律落仓库外 (`~/tmp/`), 由 `lint:backups` 全树兜底。
54
60
 
55
61
  ## 相关文档
56
62