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.
- package/README.md +22 -14
- package/README.zh-CN.md +22 -14
- package/assets/manifest.json +7 -2
- package/assets/template/.github/ISSUE_TEMPLATE/bug_report.yml +15 -29
- package/assets/template/.github/ISSUE_TEMPLATE/feature_request.yml +6 -12
- package/assets/template/.github/PULL_REQUEST_TEMPLATE.md +3 -3
- package/assets/template/.github/workflows/ci.yml +69 -7
- package/assets/template/.github/workflows/release.yml +23 -23
- package/assets/template/.gitignorerc.json +1 -8
- package/assets/template/.oxlintrc.json +1 -6
- package/assets/template/.prettierignore +0 -1
- package/assets/template/.releaserc.json +6 -1
- package/assets/template/.vscode/launch.json +1 -1
- package/assets/template/.vscode/settings.json +1 -0
- package/assets/template/.vscode/tasks.json +45 -0
- package/assets/template/AGENTS.md +4 -4
- package/assets/template/CONTRIBUTING.md +6 -4
- package/assets/template/CONTRIBUTING.zh-CN.md +6 -4
- package/assets/template/_gitignore +7 -405
- package/assets/template/bunfig.toml +2 -11
- package/assets/template/docs/README.md +6 -6
- package/assets/template/docs/adrs/README.md +4 -2
- package/assets/template/docs/development.md +15 -9
- package/assets/template/lefthook.yml +20 -30
- package/assets/template/package.json +5 -6
- package/assets/template/packages/{{NAME}}/README.md +4 -4
- package/assets/template/packages/{{NAME}}/README.zh-CN.md +2 -2
- package/assets/template/packages/{{NAME}}/package.json +3 -1
- package/assets/template/packages/{{NAME}}/scripts/build.ts +50 -14
- package/assets/template/packages/{{NAME}}/scripts/verify-release.test.ts +140 -15
- package/assets/template/packages/{{NAME}}/scripts/verify-release.ts +27 -14
- package/assets/template/packages/{{NAME}}/tsconfig.build.json +1 -1
- package/assets/template/packages/{{NAME}}-cli/README.md +6 -6
- package/assets/template/packages/{{NAME}}-cli/README.zh-CN.md +2 -2
- package/assets/template/packages/{{NAME}}-cli/bin/bunfig.toml +3 -0
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}} +43 -21
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.cmd +8 -17
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.d.mts +6 -3
- package/assets/template/packages/{{NAME}}-cli/bin/{{BIN_NAME}}.mjs +189 -107
- package/assets/template/packages/{{NAME}}-cli/package.json +3 -2
- package/assets/template/packages/{{NAME}}-cli/scripts/release-artifact.ts +24 -73
- package/assets/template/packages/{{NAME}}-cli/scripts/release.fixtures.ts +8 -3
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.test.ts +16 -10
- package/assets/template/packages/{{NAME}}-cli/scripts/verify-release.ts +8 -52
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.test.ts +3 -3
- package/assets/template/packages/{{NAME}}-cli/scripts/write-dist-manifest.ts +8 -68
- package/assets/template/scripts/ci.ts +285 -64
- package/assets/template/scripts/install-git-hooks.mjs +10 -0
- package/assets/template/scripts/install-git-hooks.test.ts +1 -1
- package/assets/template/scripts/lib/npm-trust-parse.ts +169 -0
- package/assets/template/scripts/lib/release-cli.ts +299 -0
- package/assets/template/scripts/lib/release-verify.ts +148 -15
- package/assets/template/scripts/lib/workspace.test.ts +63 -1
- package/assets/template/scripts/lib/workspace.ts +132 -42
- package/assets/template/scripts/lint-dependency-direction.test.ts +131 -0
- package/assets/template/scripts/lint-dependency-direction.ts +130 -0
- package/assets/template/scripts/lint-doc-examples.test.ts +45 -9
- package/assets/template/scripts/lint-doc-examples.ts +227 -50
- package/assets/template/scripts/lint-doc-references.test.ts +36 -0
- package/assets/template/scripts/lint-doc-references.ts +142 -57
- package/assets/template/scripts/lint-doc-shared.ts +26 -23
- package/assets/template/scripts/lint-stray-backups.test.ts +3 -1
- package/assets/template/scripts/lint-stray-backups.ts +7 -3
- package/assets/template/scripts/npm-trust-guard.test.ts +56 -8
- package/assets/template/scripts/npm-trust-guard.ts +116 -200
- package/assets/template/scripts/safe-install.ts +28 -23
- package/assets/template/scripts/transcription/api-harness.ts +28 -206
- package/assets/template/scripts/transcription/compare.test.ts +84 -0
- package/assets/template/scripts/transcription/compare.ts +4 -4
- package/assets/template/scripts/transcription/corpus.ts +9 -3
- package/assets/template/scripts/transcription/fixture.ts +2 -4
- package/assets/template/scripts/transcription/make-mutants.ts +116 -37
- package/assets/template/scripts/transcription/run-conformance.ts +57 -34
- package/assets/template/scripts/transcription/validate-coverage.test.ts +11 -14
- package/assets/template/scripts/transcription/validate-coverage.ts +8 -10
- package/assets/template/scripts/transcription/validate.ts +18 -3
- package/assets/template/tsconfig.json +2 -20
- package/assets/template/turbo.jsonc +7 -52
- package/bin/bunfig.toml +3 -0
- package/bin/create-clis.mjs +165 -104
- package/dist/create-clis.js +48 -87681
- package/dist/manifest.json +3 -3
- package/package.json +9 -5
- package/assets/template/packages/{{NAME}}/docs/README.md +0 -21
- package/assets/template/packages/{{NAME}}-cli/docs/README.md +0 -21
- package/bin/create-clis +0 -35
- package/bin/create-clis.cmd +0 -32
package/README.md
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
# create-clis
|
|
2
2
|
|
|
3
3
|
[](https://github.com/iyowei/clis/actions/workflows/ci.yml)
|
|
4
|
+
[](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
|
-
|
|
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
|
-
-
|
|
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
|
|
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/
|
|
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](
|
|
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
|
|
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:
|
|
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/](
|
|
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](
|
|
113
|
-
-
|
|
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
|
[](https://github.com/iyowei/clis/actions/workflows/ci.yml)
|
|
4
|
+
[](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
|
-
-
|
|
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/
|
|
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](
|
|
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`: 重量级冒烟:
|
|
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/](
|
|
116
|
+
`prepublishOnly` 按序串起三者, 发布出去的版本因此自带一份证明: 它生成的项目是绿的。设计与契约文档 (生成器包设计 / 契约 / 档位 / 快照机制) 都在 [docs/designs/](https://github.com/iyowei/clis/tree/main/docs/designs) 下。
|
|
109
117
|
|
|
110
118
|
---
|
|
111
119
|
|
|
112
|
-
- 生成器包设计: [scaffold-package.md](
|
|
113
|
-
-
|
|
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)
|
package/assets/manifest.json
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
41
|
-
|
|
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
|
|
24
|
-
- [ ] If
|
|
25
|
-
- [ ] Docs were updated where behavior or contracts changed; new docs are registered
|
|
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:
|
|
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
|
|
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
|
-
# 执行,
|
|
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:
|
|
39
|
-
-
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
cancel-in-progress: false
|
|
10
|
+
env:
|
|
11
|
+
TURBO_TELEMETRY_DISABLED: '1'
|
|
13
12
|
|
|
14
13
|
jobs:
|
|
15
|
-
#
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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:
|
|
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:
|
|
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
|
}
|