create-clis 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +113 -0
  3. package/README.zh-CN.md +113 -0
  4. package/assets/manifest.json +99 -0
  5. package/assets/template/.editorconfig +12 -0
  6. package/assets/template/.gitattributes +18 -0
  7. package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +86 -0
  8. package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +45 -0
  9. package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +26 -0
  10. package/assets/template/.github/workflows/ci.yml +42 -0
  11. package/assets/template/.github/workflows/release.yml +65 -0
  12. package/assets/template/.gitignorerc.json +21 -0
  13. package/assets/template/.nvmrc +1 -0
  14. package/assets/template/.oxlintrc.json +52 -0
  15. package/assets/template/.prettierignore +11 -0
  16. package/assets/template/.prettierrc +11 -0
  17. package/assets/template/.releaserc.json +17 -0
  18. package/assets/template/.vscode/extensions.json +8 -0
  19. package/assets/template/.vscode/launch.json +13 -0
  20. package/assets/template/.vscode/settings.json +14 -0
  21. package/assets/template/AGENTS.md +25 -0
  22. package/assets/template/CODE_OF_CONDUCT.md +91 -0
  23. package/assets/template/CONTRIBUTING.md +85 -0
  24. package/assets/template/CONTRIBUTING.zh-CN.md +85 -0
  25. package/assets/template/LICENSE +21 -0
  26. package/assets/template/README.md +22 -0
  27. package/assets/template/README.zh-CN.md +22 -0
  28. package/assets/template/SECURITY.md +21 -0
  29. package/assets/template/_gitignore +409 -0
  30. package/assets/template/_npmrc +6 -0
  31. package/assets/template/bunfig.toml +16 -0
  32. package/assets/template/docs/README.md +30 -0
  33. package/assets/template/docs/adrs/README.md +7 -0
  34. package/assets/template/docs/designs/README.md +11 -0
  35. package/assets/template/docs/designs/tech-debt.md +22 -0
  36. package/assets/template/docs/development.md +59 -0
  37. package/assets/template/lefthook.yml +55 -0
  38. package/assets/template/package.json +38 -0
  39. package/assets/template/packages/{{NAME}}/CHANGELOG.md +3 -0
  40. package/assets/template/packages/{{NAME}}/LICENSE +21 -0
  41. package/assets/template/packages/{{NAME}}/README.md +33 -0
  42. package/assets/template/packages/{{NAME}}/README.zh-CN.md +33 -0
  43. package/assets/template/packages/{{NAME}}/docs/README.md +21 -0
  44. package/assets/template/packages/{{NAME}}/package.json +40 -0
  45. package/assets/template/packages/{{NAME}}/scripts/build.ts +82 -0
  46. package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +214 -0
  47. package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +152 -0
  48. package/assets/template/packages/{{NAME}}/src/index.ts +15 -0
  49. package/assets/template/packages/{{NAME}}/tsconfig.build.json +12 -0
  50. package/assets/template/packages/{{NAME}}/tsconfig.json +5 -0
  51. package/assets/template/packages/{{NAME}}-cli/CHANGELOG.md +3 -0
  52. package/assets/template/packages/{{NAME}}-cli/LICENSE +21 -0
  53. package/assets/template/packages/{{NAME}}-cli/README.md +35 -0
  54. package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +35 -0
  55. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +30 -0
  56. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +30 -0
  57. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +23 -0
  58. package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +212 -0
  59. package/assets/template/packages/{{NAME}}-cli/docs/README.md +21 -0
  60. package/assets/template/packages/{{NAME}}-cli/package.json +48 -0
  61. package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +141 -0
  62. package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +70 -0
  63. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +444 -0
  64. package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +72 -0
  65. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +126 -0
  66. package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +81 -0
  67. package/assets/template/packages/{{NAME}}-cli/src/cli.ts +36 -0
  68. package/assets/template/packages/{{NAME}}-cli/tsconfig.json +4 -0
  69. package/assets/template/scripts/ci.ts +163 -0
  70. package/assets/template/scripts/install-git-hooks.mjs +122 -0
  71. package/assets/template/scripts/install-git-hooks.test.ts +418 -0
  72. package/assets/template/scripts/lib/git-env.ts +21 -0
  73. package/assets/template/scripts/lib/release-verify.ts +431 -0
  74. package/assets/template/scripts/lib/tmp-root.ts +17 -0
  75. package/assets/template/scripts/lib/workspace.test.ts +92 -0
  76. package/assets/template/scripts/lib/workspace.ts +100 -0
  77. package/assets/template/scripts/lint-doc-examples.test.ts +129 -0
  78. package/assets/template/scripts/lint-doc-examples.ts +249 -0
  79. package/assets/template/scripts/lint-doc-references.test.ts +158 -0
  80. package/assets/template/scripts/lint-doc-references.ts +308 -0
  81. package/assets/template/scripts/lint-doc-shared.ts +59 -0
  82. package/assets/template/scripts/lint-stray-backups.test.ts +53 -0
  83. package/assets/template/scripts/lint-stray-backups.ts +39 -0
  84. package/assets/template/scripts/npm-trust-guard.test.ts +253 -0
  85. package/assets/template/scripts/npm-trust-guard.ts +533 -0
  86. package/assets/template/scripts/safe-install.ts +39 -0
  87. package/assets/template/scripts/transcription/api-harness.ts +219 -0
  88. package/assets/template/scripts/transcription/compare.ts +421 -0
  89. package/assets/template/scripts/transcription/corpus.ts +208 -0
  90. package/assets/template/scripts/transcription/fixture.ts +290 -0
  91. package/assets/template/scripts/transcription/make-mutants.ts +425 -0
  92. package/assets/template/scripts/transcription/report.ts +86 -0
  93. package/assets/template/scripts/transcription/run-conformance.ts +344 -0
  94. package/assets/template/scripts/transcription/validate-coverage.test.ts +119 -0
  95. package/assets/template/scripts/transcription/validate-coverage.ts +144 -0
  96. package/assets/template/scripts/transcription/validate.ts +366 -0
  97. package/assets/template/tsconfig.json +46 -0
  98. package/assets/template/turbo.jsonc +60 -0
  99. package/bin/create-clis +35 -0
  100. package/bin/create-clis.cmd +32 -0
  101. package/bin/create-clis.mjs +219 -0
  102. package/dist/create-clis.js +87682 -0
  103. package/dist/manifest.json +7 -0
  104. package/package.json +57 -0
@@ -0,0 +1,409 @@
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
173
+ 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
364
+ .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
+
395
+ *.log
396
+
397
+
398
+ *.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/
@@ -0,0 +1,6 @@
1
+ # npm 命令 (semantic-release prepare 阶段的 npm version、以及任何手动 npm 操作) 一律禁生成
2
+ # package-lock.json: 本项目用 bun (bun.lock 为唯一锁文件), lock 属 npm 副产物,
3
+ # 会弄脏发布闸门的「工作树干净」判定并随发布流程持续复发。
4
+ # 位置说明: 必须放仓库根 (project config 层); 子包目录里的 .npmrc 会被 npm 当作
5
+ # workspace config 忽略 (npm v11 实测), 对 workspace 内运行的命令不生效。
6
+ package-lock=false
@@ -0,0 +1,16 @@
1
+ # bun 配置
2
+ # linker = "hoisted" 是让 oxlint / prettier 等 Node CJS 工具链能正确解析
3
+ # peer dependency 的关键。若改成 isolated, 这些工具的插件会解析到全局缓存
4
+ # 的符号链接路径, 而 peer 依赖落在平行缓存目录, 找不到, 工具链直接报错。
5
+
6
+ [install]
7
+ frozenLockfile = false
8
+ 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/**"]
@@ -0,0 +1,30 @@
1
+ # {{NAME}} 工程技术文档总索引
2
+
3
+ > 文档类型: 全部工程技术文档的总入口
4
+ > 适用对象: 本仓维护者与 AI Agent
5
+ > 范围说明: 本索引收录工程技术文档 (决策 / 设计 / 协议 / 开发); 新增文档必须登记 (adrs/、designs/ 下的登记到各自目录的 README, 其余登记到本索引), 严禁出现索引之外的孤岛文档。
6
+ >
7
+ > 命名约定: `designs/` 下的文件名不带日期, 修订日期登记在正文的「修订记录」里; ADR 按编号顺序追加, 已接受的决定不原地改写。
8
+
9
+ ## 决策与模板
10
+
11
+ **架构决策记录**
12
+ [架构决策记录索引](adrs/README.md)
13
+ 收录本仓演进过程中的重大技术决策 (ADRs), 以及当时的背景与权衡; 新项目从 0001 起编号。
14
+
15
+ ## 设计文档
16
+
17
+ **设计文档索引 (仓库级)**
18
+ [设计文档索引](designs/README.md)
19
+ 仓库级设计 (仓库治理与脚手架) 的登记入口与推荐阅读顺序; 包级设计在各包 `packages/*/docs/designs/` 内。
20
+
21
+ ## 开发
22
+
23
+ **开发指南**
24
+ [开发指南](development.md)
25
+ 环境准备、常用命令、提交钩子与发布链; 面向仓库维护者与贡献者。
26
+
27
+ ## 包
28
+
29
+ - [API 包文档入口](../packages/{{NAME}}/docs/README.md) (可编程 API 与包级 ADR);
30
+ - [CLI 包文档入口](../packages/{{NAME}}-cli/docs/README.md) (命令用法与输出)。
@@ -0,0 +1,7 @@
1
+ # 架构决策记录索引
2
+
3
+ 这里按编号顺序列出本仓全部 ADR。新增决策顺延编新编号; 已接受的记录不回头改, 要修订, 就写新 ADR 或补充说明。编号全局唯一, 仓库级和包级共用一套编号。
4
+
5
+ | 编号 | 标题 | 状态 | 日期 |
6
+ | ---- | ---- | ---- | ---- |
7
+ | | | | |
@@ -0,0 +1,11 @@
1
+ # 设计文档索引
2
+
3
+ > 本索引收录**仓库级设计** (仓库治理与脚手架, 跟具体产品无关); 各产品的设计文档在各自的产品区或包级 `docs/designs/`。每篇文档只讲一个不能再拆的最小单元, 修订登记在文档内的「修订记录」里。
4
+
5
+ ## 仓库级设计
6
+
7
+ > 新项目从这里开始登记第一篇仓库级设计。阅读顺序: 定位 → 治理协议 → 能力与工具 → 落地计划。
8
+
9
+ | 顺序 | 文档 | 一句话 |
10
+ | ---- | -------- | -------------------------- |
11
+ | 1 | (待登记) | 新项目在这里登记第一篇设计 |
@@ -0,0 +1,22 @@
1
+ # 技术债登记 (Tech Debt Registry)
2
+
3
+ > 文档类型: 仓库级设计 (登记册)
4
+ > 适用对象: 本仓维护者与 AI Agent
5
+
6
+ ## 纪律
7
+
8
+ - 每笔债必须有**可判定的解除条件**: 写不出「何时可清除」的条目不是债, 是伪装成债的永久妥协, 应把它写进定位文档的「明确不做」, 或直接删除;
9
+ - 破例 (如依赖方向例外) 必须先在此登记再落地;
10
+ - 解除后移入「已偿付」区, 保留原条目一行 (含解除日期与处置), 偿付历史不删除。
11
+
12
+ ## 未偿付
13
+
14
+ | 编号 | 内容 | 原因 | 影响面 | 解除条件 | 登记日期 |
15
+ | ---- | ---- | ---- | ------ | -------- | -------- |
16
+ | | | | | | |
17
+
18
+ ## 已偿付
19
+
20
+ | 编号 | 内容 | 偿付日期 | 处置 |
21
+ | ---- | ---- | -------- | ---- |
22
+ | | | | |
@@ -0,0 +1,59 @@
1
+ # 开发指南
2
+
3
+ > 面向本仓库的维护者与贡献者; 入门级开发说明见 [CONTRIBUTING](../CONTRIBUTING.md), 本文是深入版。设计决策见[设计文档索引](designs/README.md); 发布链见 `.github/workflows/`。
4
+
5
+ ## 环境准备
6
+
7
+ ```shell
8
+ # 装 devDependencies, 并在本仓库检出态自动装好 git 钩子 (lefthook)
9
+ bun install
10
+ ```
11
+
12
+ 装钩子由 `scripts/install-git-hooks.mjs` 把守 (prepare 入口): 只在本仓库自身的 git 仓库根执行 `lefthook install`, 被作为依赖安装到别的仓库时自动跳过。lefthook 不列为依赖: 安装期取 PATH 上的 lefthook, 无则按 `lefthook.yml` 的配置经 bunx 取 pin 版; 都不可用时安装照常完成, 只是没有钩子。
13
+
14
+ ## 常用命令
15
+
16
+ 以下命令除注明外均在仓库根执行:
17
+
18
+ ```shell
19
+ # 类型检查 (tsc --noEmit; 经 turbo 编排各包)
20
+ bun run typecheck
21
+
22
+ # 代码检查 (oxlint)
23
+ bun run lint
24
+
25
+ # 格式化 (prettier --write)
26
+ bun run format
27
+
28
+ # 测试 (经 turbo 编排各包, 带缓存)
29
+ bun run test
30
+
31
+ # 本地 CI 预演 (与 GitHub Actions 的 verify job 同集合; 推前必跑, pre-push 钩子按同集合自动执行)
32
+ bun run ci
33
+
34
+ # 打包各包发布产物; 发布时由各自的 prepublishOnly 自动跑
35
+ bun run build
36
+ ```
37
+
38
+ ## 提交与推送
39
+
40
+ 由 lefthook 把关 (操作级细节以仓库根 `lefthook.yml` 为准):
41
+
42
+ - **pre-commit** (增量): prettier 重暂存 + oxlint 扫暂存文件; 类型检查例外, 跑全项目 `tsc --noEmit`;
43
+ - **pre-push** (全量): 单条调用 `bun scripts/ci.ts`; 步骤集合的单一事实来源在 `scripts/ci.ts`, CI 与 Release 的 verify job 共用同一套步骤定义。
44
+
45
+ 提交信息按 Conventional Commits 前缀 (`feat` / `fix` / `chore` / `test` 等), 并守单一主题原则: 一个提交只含一个完整逻辑变更, 跨主题须拆分。
46
+
47
+ ## 发布
48
+
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 拒发。
52
+
53
+ **README / LICENSE 类备份别落包目录**: npm 会把包根的 `README*` / `LICENSE*` 无条件收进发行包, 且没有任何配置可以排除; 备份一律落仓库外。
54
+
55
+ ## 相关文档
56
+
57
+ - [工程技术文档总索引](README.md)
58
+ - [设计文档索引](designs/README.md)
59
+ - [架构决策记录](adrs/README.md)
@@ -0,0 +1,55 @@
1
+ # Git 钩子门禁 (lefthook)
2
+ #
3
+ # 分层策略:
4
+ # pre-commit 增量门禁: prettier / oxlint 只扫暂存文件; type-check 例外,
5
+ # 不传 {staged_files}, 跑全项目 tsc --noEmit; prettier 格式化后
6
+ # 自动重暂存
7
+ # pre-push 全量门禁: rebase / merge / cherry-pick 重放提交不触发 pre-commit,
8
+ # base 的改动会让本次提交产生「语义冲突」(如 import 失配),
9
+ # push 是代码外流的唯一必经闸门, 在此全量只读兜底
10
+ #
11
+ # 注意 {staged_files} 模板只在 pre-commit 阶段成立, push 阶段没有暂存区概念,
12
+ # 因此 pre-push 一律只读: prettier 用 --check 而非 --write, 不设 stage_fixed
13
+ # (--write 在 push 阶段是纯副作用: 改动进不了正在推送的提交, 只在本地凭空多出
14
+ # 未提交改动)。
15
+ #
16
+ # 执行链的 lefthook 取用: 官方生成的钩子模板探测链不含 bunx, 且默认「找不到即
17
+ # 静默放行」(门禁悄悄失效); 这里用官方两个配置键补齐 —— lefthook: 指定经 bunx
18
+ # 取 pin 版 (无全局 lefthook 的机器也能跑, 与 LEFTHOOK_BIN / PATH 的优先级由
19
+ # 模板决定), assert_lefthook_installed: true 让整链失败时退非零而非静默通过。
20
+ # 依据见 ADR 0005 决策第 1 条。
21
+
22
+ lefthook: bunx lefthook@2.1.14
23
+ assert_lefthook_installed: true
24
+
25
+ pre-commit:
26
+ parallel: false
27
+ commands:
28
+ # TypeScript 类型检查 (两包, 经 turbo 编排): 不传 {staged_files}, 天然全项目执行
29
+ type-check:
30
+ glob: '*.{ts,tsx,mts,mjs}'
31
+ run: bunx turbo run typecheck
32
+
33
+ # JS/TS (含 .mts / .mjs): prettier 格式化后自动重暂存, 再 oxlint
34
+ prettier-js:
35
+ glob: '*.{ts,tsx,mts,mjs}'
36
+ run: bunx prettier --write --log-level error {staged_files}
37
+ stage_fixed: true
38
+
39
+ oxlint:
40
+ glob: '*.{ts,tsx,mts,mjs}'
41
+ run: bunx oxlint {staged_files}
42
+
43
+ # 非 JS/TS: 仅 prettier 格式化
44
+ prettier-other:
45
+ glob: '*.{md,mdx,json,yaml,yml}'
46
+ run: bunx prettier --write --log-level error {staged_files}
47
+ stage_fixed: true
48
+
49
+ pre-push:
50
+ parallel: false
51
+ commands:
52
+ # 全量预演 (验证组 + 验收组): 步骤集合的单一事实来源在 scripts/ci.ts,
53
+ # 与 CI 的两个 job 及 Release 的 verify job 同集合, 此处不再逐项枚举
54
+ ci:
55
+ run: bun run ci
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "{{NAME}}-monorepo",
3
+ "private": true,
4
+ "packageManager": "bun@1.4.2",
5
+ "author": "{{OWNER}} (https://github.com/{{OWNER}})",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "engines": {
9
+ "node": ">=22.18.0"
10
+ },
11
+ "workspaces": [
12
+ "packages/*"
13
+ ],
14
+ "scripts": {
15
+ "safe-install": "bun scripts/safe-install.ts",
16
+ "prepare": "node scripts/install-git-hooks.mjs || exit 0",
17
+ "build": "turbo run build",
18
+ "typecheck": "turbo run typecheck && tsc --noEmit",
19
+ "lint": "oxlint",
20
+ "lint:fix": "oxlint --fix",
21
+ "format": "prettier --write .",
22
+ "test": "turbo run test && bun test scripts/",
23
+ "conformance": "bun scripts/transcription/run-conformance.ts",
24
+ "ci": "bun scripts/ci.ts"
25
+ },
26
+ "devDependencies": {
27
+ "@lidofinance/multi-semantic-release": "1.0.3",
28
+ "@semantic-release/changelog": "7.0.0",
29
+ "@semantic-release/git": "11.0.1",
30
+ "@trivago/prettier-plugin-sort-imports": "6.0.2",
31
+ "@types/bun": "1.4.2",
32
+ "oxlint": "1.85.0",
33
+ "prettier": "3.9.9",
34
+ "semantic-release": "25.0.9",
35
+ "turbo": "2.11.5",
36
+ "typescript": "7.0.2"
37
+ }
38
+ }
@@ -0,0 +1,3 @@
1
+ # Changelog
2
+
3
+ All notable changes to this package are documented in this file. Entries are written by the release chain (semantic-release) on the first release.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 {{OWNER}}
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.