@nick848/fet 1.0.6 → 1.0.8

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 (5) hide show
  1. package/README.md +79 -220
  2. package/README_en.md +196 -0
  3. package/dist/cli/index.js +1674 -998
  4. package/dist/cli/index.js.map +1 -1
  5. package/package.json +4 -2
package/README.md CHANGED
@@ -1,22 +1,26 @@
1
1
  # FET
2
2
 
3
- FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor 等 AI 编程工具读取正确的项目资料。
3
+ [中文](./README.md) | [English](./README_en.md)
4
4
 
5
- ### 作用
5
+ FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor、Codex 等 AI 编程工具读取正确的项目资料。
6
6
 
7
- - 统一入口：用 `fet <command>` 包装 OpenSpec 工作流，避免用户和 AI 工具绕过 FET 的状态记录。
7
+ ## 功能概览
8
+
9
+ - 统一入口：使用 `fet <command>` 包装 OpenSpec 工作流，避免用户和 AI 工具绕过 FET 的状态记录。
8
10
  - 生成上下文：扫描项目并生成 `AGENTS.md` 与 `openspec/config.yaml` 中的 `fet:` 配置。
9
- - 管理状态：记录 active change、任务同步、手动验证声明、工具适配状态等本地工作流信息。
10
- - 集成 AI 工具：为 Cursor 生成项目规则和 Skill 说明，引导 AI 读取 OpenSpec 规划产物和项目上下文。
11
- - 保护关键阶段：在 `sync` / `archive` 前检查 FET 的 verify 状态，降低未验证变更被归档的风险。
11
+ - 管理状态：记录 active change、任务同步、手动验证声明、工具适配状态和语言偏好。
12
+ - 集成 AI 工具：为 Cursor 生成规则和 Skill，为 Codex 生成上下文、命令指南和 native slash prompt。
13
+ - 统一语言：默认使用中文输出交互信息和生成产物，可通过 `--lang <language>` 切换。
14
+ - 保护关键阶段：在 `sync` / `archive` 前检查 FET verify 状态，降低未验证变更被合入或归档的风险。
15
+ - 可选代码图：可接入 GitNexus，在大范围扫描前优先提供结构化代码上下文。
12
16
 
13
- ### 基本原理
17
+ ## 基本原理
14
18
 
15
- FET 是 OpenSpec 的透明代理和本地编排层。用户运行 `fet apply`、`fet archive` 等命令时，FET 会先读取项目状态和 change 状态，执行必要的 pre-hook，再调用真实的 `openspec` CLI，最后根据 OpenSpec 的结果更新 FET 状态。
19
+ FET 是 OpenSpec 的透明代理和本地编排层。运行 `fet apply`、`fet archive` 等命令时，FET 会先读取项目状态和 change 状态，执行必要的 pre-hook，再调用真实的 `openspec` CLI，最后根据 OpenSpec 的结果更新 FET 状态。
16
20
 
17
- FET 代理命令会保留 OpenSpec 原生命令名。例如 `fet apply --change <id>` 会调用 `openspec apply --change <id>`，`fet sync --change <id>` 会在 FET verify gate 通过后调用 `openspec sync --change <id>`。
21
+ FET 代理命令会保留 OpenSpec 原生命令名。例如，`fet apply --change <id>` 会调用 `openspec apply --change <id>`，`fet sync --change <id>` 会在 FET verify gate 通过后调用 `openspec sync --change <id>`。
18
22
 
19
- ### 环境要求
23
+ ## 环境要求
20
24
 
21
25
  - Node.js 18 或更高版本
22
26
  - OpenSpec CLI 在 `PATH` 中可用
@@ -27,7 +31,7 @@ FET 代理命令会保留 OpenSpec 原生命令名。例如 `fet apply --change
27
31
  npm install -g @fission-ai/openspec
28
32
  ```
29
33
 
30
- ### 安装 FET
34
+ ## 安装
31
35
 
32
36
  ```sh
33
37
  npm install -g @nick848/fet
@@ -40,7 +44,7 @@ fet --version
40
44
  fet --help
41
45
  ```
42
46
 
43
- ### 快速开始
47
+ ## 快速开始
44
48
 
45
49
  在需要接入 OpenSpec 的项目根目录运行：
46
50
 
@@ -53,250 +57,106 @@ fet doctor
53
57
 
54
58
  ```sh
55
59
  fet new my-change
56
- fet apply --change my-change
60
+ fet continue
61
+ fet apply
57
62
  fet verify --change my-change
58
63
  fet verify --done --change my-change
59
- fet sync --change my-change
64
+ fet sync
60
65
  fet archive --change my-change
61
66
  ```
62
67
 
63
- ### 全局参数
68
+ `continue`、`apply`、`ff`、`sync` 等命令在未显式传入 `--change` 时，会优先使用 FET 记录的 active change；如果只有一个打开的 change，也会自动使用它。
69
+
70
+ ## 语言设置
71
+
72
+ FET 默认使用中文输出交互信息和生成产物。
73
+
74
+ ```sh
75
+ fet init --lang zh-CN
76
+ fet init --lang en
77
+ ```
78
+
79
+ `fet init --lang <language>` 会把语言写入 `openspec/fet-state.json`。后续命令如果没有传 `--lang`，会复用初始化时保存的语言。支持值：
80
+
81
+ | 参数值 | 含义 |
82
+ |------|------|
83
+ | `zh-CN`、`zh`、`cn`、`chinese` | 中文 |
84
+ | `en`、`en-US`、`english` | 英文 |
85
+
86
+ ## 全局参数
64
87
 
65
88
  | 参数 | 说明 | 示例 |
66
89
  |------|------|------|
67
90
  | `--cwd <path>` | 指定项目根目录，默认当前目录。 | `fet doctor --cwd ./app` |
68
91
  | `--change <id>` | 指定 OpenSpec change。 | `fet apply --change add-login` |
92
+ | `--lang <language>` | 指定交互信息和生成产物语言。 | `fet init --lang en` |
69
93
  | `--yes` | 对低风险确认使用默认同意。 | `fet init --yes` |
70
94
  | `--json` | 输出机器可读 JSON。 | `fet doctor --json` |
71
95
  | `--verbose` | 输出更多诊断信息。 | `fet doctor --verbose` |
72
96
  | `--no-color` | 禁用终端颜色。 | `fet --no-color doctor` |
73
97
 
74
- ### 命令列表
98
+ ## 命令列表
75
99
 
76
100
  | 命令 | 用法 | 说明 |
77
101
  |------|------|------|
78
- | `fet init` | `fet init [--yes]` | 初始化 FET 和 OpenSpec；生成上下文文件、状态文件、Cursor 规则和 Skill。 |
102
+ | `fet init` | `fet init [--yes] [--lang <language>]` | 初始化 FET 和 OpenSpec；生成上下文、状态、Cursor 集成和 Codex 工作流指南。 |
79
103
  | `fet update-context` | `fet update-context [--yes]` | 重新扫描项目并更新 `AGENTS.md` 与 `openspec/config.yaml` 的 FET 托管区域。 |
80
- | `fet doctor` | `fet doctor [--fix-lock]` | 诊断 OpenSpec、FET 状态、上下文文件、Cursor 集成和锁文件。 |
81
- | `fet explore` | `fet explore [...args] [--change <id>]` | 代理 OpenSpec 原生 explore 流程，保留交互式需求澄清。 |
82
- | `fet propose` | `fet propose <change-id>` | 创建新的 OpenSpec change；等价于 FET 高层提案入口。 |
104
+ | `fet fill-context` | `fet fill-context [--yes]` | 刷新 IDE 交接命令，引导 AI 替换 `AGENTS.md` 占位符。 |
105
+ | `fet doctor` | `fet doctor [--fix-lock]` | 诊断 OpenSpec、FET 状态、上下文文件、工具集成和锁文件。 |
106
+ | `fet explore` | `fet explore [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 explore，保留交互式需求澄清。 |
107
+ | `fet propose` | `fet propose <change-id>` | 创建新的 OpenSpec change，并进入提案工作流。 |
83
108
  | `fet new` | `fet new <change-id>` | 创建新的 OpenSpec change。 |
84
109
  | `fet continue` | `fet continue [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 continue。 |
85
110
  | `fet ff` | `fet ff [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 ff。 |
86
111
  | `fet apply` | `fet apply [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 apply，并同步 FET 状态。 |
87
112
  | `fet verify` | `fet verify --change <id>` | 生成 `.fet/verify-instructions.md` 手动验证指令。 |
88
- | `fet verify --done` | `fet verify --done --change <id>` | 声明已完成手动验证，允许后续 `sync` / `archive`。 |
89
- | `fet verify --auto` | `fet verify --auto [--yes]` | 生成自动验证执行计划；当前版本不执行项目脚本，`--yes` 会记录授权计划指纹。 |
90
- | `fet sync` | `fet sync [...args] [--change <id>]` | 在 FET verify gate 通过后，执行 OpenSpec 原生 sync。 |
91
- | `fet archive` | `fet archive --change <id>` | 在 FET verify gate 通过后，归档 change 并更新 OpenSpec 主规范。 |
113
+ | `fet verify --done` | `fet verify --done --change <id>` | 声明手动验证完成，允许后续 `sync` / `archive`。 |
114
+ | `fet verify --auto` | `fet verify --auto [--yes]` | 生成自动验证计划；当前版本不执行项目脚本，`--yes` 会记录计划指纹。 |
115
+ | `fet sync` | `fet sync [...args] [--change <id>]` | FET verify gate 通过后执行 OpenSpec 原生 sync。 |
116
+ | `fet archive` | `fet archive --change <id>` | FET verify gate 通过后归档 change，并追加 `CHANGELOG.md`。 |
92
117
  | `fet bulk-archive` | `fet bulk-archive [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 bulk-archive。 |
93
118
  | `fet onboard` | `fet onboard [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 onboard。 |
94
119
  | `fet passthrough` | `fet passthrough <command> [...args]` | 透传暂未接管的 OpenSpec 命令，不更新 FET 生命周期状态。 |
95
120
 
96
- ### 生成文件
97
-
98
- FET 可能创建或更新：
99
-
100
- - `AGENTS.md`
101
- - `openspec/config.yaml` 的 `fet:` 命名空间
102
- - `openspec/fet-state.json`
103
- - `openspec/changes/<change-id>/fet-state.json`
104
- - `openspec/changes/<change-id>/.fet/verify-instructions.md`
105
- - `.cursor/skills/fet-*/SKILL.md`
106
- - `.cursor/rules/fet-context.mdc`
107
-
108
- FET 只拥有明确标记的托管区域，托管区域之外的用户内容应被保留。`fet init` 还会向 `.gitignore` 添加 FET 本地状态块，避免把锁文件和本地状态误提交。
109
-
110
- ### 安全边界
111
-
112
- FET 是本地工作流辅助工具，不是沙箱、CI 强制 gate 或密码学审计系统。直接调用 `openspec` 可以绕过 FET 的本地 gate。团队如果需要强制执行验证，应在 CI、分支保护或代码审查规则中重复校验。
113
-
114
- ### 开发
115
-
116
- ```sh
117
- npm install
118
- npm run typecheck
119
- npm run test
120
- npm run build
121
- npm run release:check
122
- ```
123
-
124
- 运行真实 OpenSpec 烟测：
125
-
126
- ```powershell
127
- $env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec
128
- ```
129
-
130
- ### 许可证
131
-
132
- MIT
133
-
134
- ### 可选 GitNexus 图谱支持
135
-
136
- FET 会在 `fet init` 时检测可选的 `gitnexus` 可执行文件，并把结果记录到 `openspec/fet-state.json`。如果没有安装 GitNexus，初始化只会给出一次推荐提示，主流程会继续执行；`fet doctor` 也会把缺失 GitNexus 作为提示性 warning，而不是阻断问题。
121
+ ## GitNexus 代码图支持
137
122
 
138
- 二阶段图谱命令统一放在 `fet graph` 下：
123
+ GitNexus 是可选能力。FET 会在 `fet init` 时检测 `gitnexus` 可执行文件，并把结果记录到 `openspec/fet-state.json`。如果没有安装 GitNexus，初始化只会给出一次推荐提示，主流程会继续执行；`fet doctor` 也只会把缺失 GitNexus 作为 warning。
139
124
 
140
- - `fet graph status`：检查 GitNexus、图谱路径和当前状态，并更新 FET 状态。
141
- - `fet graph setup`：生成 `.fet/graph-setup.md`，用于安装和 IDE 辅助配置引导；FET 不会自动安装 GitNexus。
142
- - `fet graph init`：执行 `gitnexus analyze`，用于首次构建图谱。
143
- - `fet graph refresh`：再次执行 `gitnexus analyze`，用于刷新图谱。
144
- - `fet graph doctor`：检查图谱集成健康状态，缺失只提示，不阻断 FET/OpenSpec 命令。
145
- - `fet graph handoff`：生成 `.fet/graph-handoff.md`，供 Cursor、Codex、OpenCode 等 IDE AI 在大范围扫描前优先参考图谱上下文。
125
+ 图谱命令统一放在 `fet graph` 下：
146
126
 
147
- 默认情况下，FET 会从 `PATH` 查找 `gitnexus`，并认为图谱目录是 `.gitnexus`。高级用户可以通过 `FET_GITNEXUS_EXECUTABLE`、`FET_GITNEXUS_COMMAND`、`FET_GITNEXUS_GRAPH_PATH` 覆盖默认行为。
127
+ | 命令 | 说明 |
128
+ |------|------|
129
+ | `fet graph status` | 检查 GitNexus、图谱路径和当前状态，并更新 FET 状态。 |
130
+ | `fet graph setup` | 生成 `.fet/graph-setup.md`，用于安装和 IDE 辅助配置引导；FET 不会自动安装 GitNexus。 |
131
+ | `fet graph init` | 执行 `gitnexus analyze`，用于首次构建图谱。 |
132
+ | `fet graph refresh` | 再次执行 `gitnexus analyze`，用于刷新图谱。 |
133
+ | `fet graph doctor` | 检查图谱集成健康状态，缺失只提示，不阻断 FET/OpenSpec 命令。 |
134
+ | `fet graph handoff` | 生成 `.fet/graph-handoff.md`，供 Cursor、Codex、OpenCode 等 IDE AI 在大范围扫描前优先参考图谱上下文。 |
148
135
 
149
- ### Andrej Karpathy Skills
136
+ 默认情况下，FET 从 `PATH` 查找 `gitnexus`，并认为图谱目录是 `.gitnexus`。高级用户可以通过 `FET_GITNEXUS_EXECUTABLE`、`FET_GITNEXUS_COMMAND`、`FET_GITNEXUS_GRAPH_PATH` 覆盖默认行为。
150
137
 
151
- `fet init` 和 `fet update-context` 会为当前工程加入一份 FET 管理的 Andrej Karpathy 风格编码指南。FET 不假设 Codex 或 OpenCode 会主动读取 `CLAUDE.md`，因此会把指南同步到 FET 自己的上下文文件中：
138
+ ## Andrej Karpathy 风格指南
152
139
 
153
- - `CLAUDE.md`：追加或刷新 `FET:BEGIN ANDREJ-KARPATHY-SKILLS` 管理块，供 Claude Code、Codex、OpenCode 等能读取项目根文档的 AI 工具使用。
154
- - `.cursor/rules/karpathy-guidelines.mdc`：为 Cursor 生成项目规则。若该文件已存在且不是 FET 管理文件，FET 会保留原文件并给出 warning。
155
- - `.fet/karpathy-guidelines.md`：通用 IDE handoff，供 OpenCode 或其他不读取 `CLAUDE.md` 的工具显式读取。
156
- - `.codex/fet/karpathy-guidelines.md`：Codex 专用上下文；FET 生成的 Codex context、command guide 和 slash prompt 会明确要求读取该文件。
140
+ `fet init` 和 `fet update-context` 会为当前工程加入一份 FET 管理的 Andrej Karpathy 风格编码指南。FET 不假设 Codex 或 OpenCode 会主动读取 `CLAUDE.md`，因此会把指南同步到多个上下文文件中：
157
141
 
158
- 这份指南不会复制第三方仓库全文，而是基于 `andrej-karpathy-skills` 的使用目标生成项目级精简规则：先思考、保持简单、精准修改、按目标验证。来源项目：<https://github.com/forrestchang/andrej-karpathy-skills>。
142
+ - `CLAUDE.md`：追加或刷新 `FET:BEGIN ANDREJ-KARPATHY-SKILLS` 管理块。
143
+ - `.fet/karpathy-guidelines.md`：通用 IDE handoff。
144
+ - `.codex/fet/karpathy-guidelines.md`：Codex 专用上下文。
145
+ - `.cursor/rules/karpathy-guidelines.mdc`：Cursor 项目规则。
159
146
 
160
- ## English
147
+ 这份指南不是复制第三方仓库全文，而是基于 `andrej-karpathy-skills` 的使用目标生成项目级精简规则：先思考、保持简单、精准修改、按目标验证。来源项目：<https://github.com/forrestchang/andrej-karpathy-skills>。
161
148
 
162
- FET is a frontend development workflow orchestration CLI built around OpenSpec. It does not generate business code directly. Instead, it proxies OpenSpec commands, maintains local workflow state, generates auditable project context, and helps AI coding tools such as Cursor and Codex load the right files.
149
+ ## 生成文件
163
150
 
164
- ### What It Does
165
-
166
- - Provides one entry point through `fet <command>` for OpenSpec workflows.
167
- - Generates `AGENTS.md` and the `fet:` namespace in `openspec/config.yaml`.
168
- - Tracks local workflow state such as active changes, synced tasks, manual verification declarations, and tool adapter state.
169
- - Integrates with AI tools by generating Cursor project rules, Cursor Skill instructions, and Codex-readable FET workflow guides.
170
- - Guards important stages by checking FET verification state before `sync` and `archive`.
171
-
172
- ### How It Works
173
-
174
- FET is a transparent proxy and local orchestration layer for OpenSpec. When you run commands such as `fet apply` or `fet archive`, FET loads project and change state, runs pre-hooks, calls the real `openspec` CLI, and then updates FET state based on the result.
175
-
176
- FET proxy commands keep the OpenSpec command name intact. For example, `fet apply --change <id>` calls `openspec apply --change <id>`, and `fet sync --change <id>` calls `openspec sync --change <id>` after FET's verification gate passes.
177
-
178
- ### Requirements
179
-
180
- - Node.js 18 or newer
181
- - OpenSpec CLI available on `PATH`
182
-
183
- Install OpenSpec:
184
-
185
- ```sh
186
- npm install -g @fission-ai/openspec
187
- ```
188
-
189
- ### Installation
190
-
191
- ```sh
192
- npm install -g @nick848/fet
193
- ```
194
-
195
- Check the installation:
196
-
197
- ```sh
198
- fet --version
199
- fet --help
200
- ```
201
-
202
- ### Quick Start
203
-
204
- Run this in a project root:
205
-
206
- ```sh
207
- fet init
208
- fet doctor
209
- ```
210
-
211
- Typical workflow:
212
-
213
- ```sh
214
- fet new my-change
215
- fet apply --change my-change
216
- fet verify --change my-change
217
- fet verify --done --change my-change
218
- fet sync --change my-change
219
- fet archive --change my-change
220
- ```
221
-
222
- ### Optional GitNexus Graph Support
223
-
224
- FET can detect an optional `gitnexus` executable during `fet init` and records the result in `openspec/fet-state.json`. If GitNexus is not installed, init shows a one-time recommendation and continues normally. `fet doctor` reports the current GitNexus status as an informational warning when it is missing.
225
-
226
- Generated Cursor and Codex instructions tell the IDE AI to prefer GitNexus graph context before broad repository scans when that context is available. FET does not install GitNexus, generate graphs, or require graph support for any command.
227
-
228
- ### Andrej Karpathy Skills
229
-
230
- `fet init` and `fet update-context` add FET-managed Andrej Karpathy inspired coding guidelines. FET does not assume Codex, OpenCode, or other IDE agents will read `CLAUDE.md` automatically, so the guidelines are also written into FET-owned context files:
231
-
232
- - `CLAUDE.md` receives a managed `FET:BEGIN ANDREJ-KARPATHY-SKILLS` block for tools that do read root-level Claude guidance.
233
- - `.fet/karpathy-guidelines.md` is the generic handoff for OpenCode or other IDEs.
234
- - `.codex/fet/karpathy-guidelines.md` is the Codex-specific copy; generated Codex context, command guides, and slash prompts explicitly ask Codex to read it.
235
- - `.cursor/rules/karpathy-guidelines.mdc` is the Cursor project rule.
236
-
237
- The generated guidance is a concise project-level adaptation of `andrej-karpathy-skills`: think before coding, keep changes simple, edit precisely, and verify against concrete goals.
238
-
239
- Phase-two graph commands are available under `fet graph`:
240
-
241
- - `fet graph status` checks GitNexus, the configured graph path, and records the result.
242
- - `fet graph setup` writes `.fet/graph-setup.md` with installation and IDE-assisted setup guidance.
243
- - `fet graph init` runs `gitnexus analyze` to build the first graph.
244
- - `fet graph refresh` runs `gitnexus analyze` again to refresh graph data.
245
- - `fet graph doctor` reports graph integration warnings without blocking normal FET commands.
246
- - `fet graph handoff` writes `.fet/graph-handoff.md` for Cursor, Codex, OpenCode, or other IDE AI tools.
247
-
248
- By default FET looks for `gitnexus` on `PATH` and expects the graph directory at `.gitnexus`. Advanced users can override these with `FET_GITNEXUS_EXECUTABLE`, `FET_GITNEXUS_COMMAND`, and `FET_GITNEXUS_GRAPH_PATH`.
249
-
250
- ### Global Options
251
-
252
- | Option | Description | Example |
253
- |--------|-------------|---------|
254
- | `--cwd <path>` | Set project root. Defaults to current directory. | `fet doctor --cwd ./app` |
255
- | `--change <id>` | Select an OpenSpec change. | `fet apply --change add-login` |
256
- | `--yes` | Accept low-risk confirmations. | `fet init --yes` |
257
- | `--json` | Print machine-readable JSON. | `fet doctor --json` |
258
- | `--verbose` | Print more diagnostics. | `fet doctor --verbose` |
259
- | `--no-color` | Disable terminal colors. | `fet --no-color doctor` |
260
-
261
- ### Commands
262
-
263
- | Command | Usage | Description |
264
- |---------|-------|-------------|
265
- | `fet init` | `fet init [--yes]` | Initialize FET and OpenSpec; generate context, state, Cursor rules and Skills, plus Codex workflow guides. |
266
- | `fet update-context` | `fet update-context [--yes]` | Rescan the project and update FET-managed regions in `AGENTS.md` and `openspec/config.yaml`. |
267
- | `fet fill-context` | `fet fill-context [--yes]` | Refresh IDE handoff commands that ask Cursor/Codex/OpenCode-style AI to replace `AGENTS.md` placeholders. |
268
- | `fet graph status` | `fet graph status` | Check optional GitNexus installation and graph status. |
269
- | `fet graph setup` | `fet graph setup` | Generate GitNexus installation and setup handoff instructions without installing anything. |
270
- | `fet graph init` | `fet graph init [...args]` | Run `gitnexus analyze` to build the first graph. |
271
- | `fet graph refresh` | `fet graph refresh [...args]` | Run `gitnexus analyze` again and update recorded graph state. |
272
- | `fet graph doctor` | `fet graph doctor` | Diagnose optional graph integration health. |
273
- | `fet graph handoff` | `fet graph handoff` | Generate IDE AI instructions for using graph context before broad scans. |
274
- | `fet doctor` | `fet doctor [--fix-lock]` | Diagnose OpenSpec, FET state, context files, Cursor and Codex integration, and lock files. |
275
- | `fet explore` | `fet explore [...args] [--change <id>]` | Run native OpenSpec explore through FET so clarification prompts stay interactive. |
276
- | `fet propose` | `fet propose <change-id>` | Create a new OpenSpec change through FET's proposal entry point. |
277
- | `fet new` | `fet new <change-id>` | Create a new OpenSpec change. |
278
- | `fet continue` | `fet continue [...args] [--change <id>]` | Run native OpenSpec continue through FET. |
279
- | `fet ff` | `fet ff [...args] [--change <id>]` | Run native OpenSpec ff through FET. |
280
- | `fet apply` | `fet apply [...args] [--change <id>]` | Run native OpenSpec apply through FET and update FET state. |
281
- | `fet verify` | `fet verify --change <id>` | Generate `.fet/verify-instructions.md` for manual verification. |
282
- | `fet verify --done` | `fet verify --done --change <id>` | Declare manual verification complete and allow `sync` / `archive`. |
283
- | `fet verify --auto` | `fet verify --auto [--yes]` | Generate an automatic verification plan. This version does not run project scripts; `--yes` records the plan fingerprint. |
284
- | `fet sync` | `fet sync [...args] [--change <id>]` | After FET verify gate passes, run native OpenSpec sync. |
285
- | `fet archive` | `fet archive --change <id>` | After FET verify gate passes, archive the change and append the change summary to `CHANGELOG.md`. |
286
- | `fet bulk-archive` | `fet bulk-archive [...args] [--change <id>]` | Run native OpenSpec bulk-archive through FET. |
287
- | `fet onboard` | `fet onboard [...args] [--change <id>]` | Run native OpenSpec onboard through FET. |
288
- | `fet passthrough` | `fet passthrough <command> [...args]` | Pass through unmanaged OpenSpec commands without updating FET lifecycle state. |
289
-
290
- ### Generated Files
291
-
292
- FET may create or update:
151
+ FET 可能创建或更新：
293
152
 
294
153
  - `AGENTS.md`
295
- - the `fet:` namespace in `openspec/config.yaml`
154
+ - `openspec/config.yaml` 的 `fet:` 命名空间
296
155
  - `openspec/fet-state.json`
297
156
  - `openspec/changes/<change-id>/fet-state.json`
298
157
  - `openspec/changes/<change-id>/.fet/verify-instructions.md`
299
158
  - `CHANGELOG.md`
159
+ - `.fet/fill-context.md`
300
160
  - `.fet/graph-setup.md`
301
161
  - `.fet/graph-handoff.md`
302
162
  - `.fet/karpathy-guidelines.md`
@@ -307,16 +167,15 @@ FET may create or update:
307
167
  - `.codex/fet/context.md`
308
168
  - `.codex/fet/karpathy-guidelines.md`
309
169
  - `.codex/fet/commands/*.md`
310
- - `$CODEX_HOME/prompts/fet-*.md` for Codex native slash commands. If `CODEX_HOME` is not set, FET uses `~/.codex`.
311
- - `.fet/fill-context.md` as a generic IDE handoff for tools without native command support.
170
+ - `$CODEX_HOME/prompts/fet-*.md`
312
171
 
313
- FET only owns explicitly marked managed regions. User content outside those regions should be preserved. During `fet init`, FET also adds a managed `.gitignore` block for local workflow state.
172
+ FET 只拥有明确标记的托管区域。托管区域之外的用户内容应被保留。`fet init` 还会向 `.gitignore` 添加 FET 本地状态块，避免把锁文件和本地状态误提交。
314
173
 
315
- ### Safety Model
174
+ ## 安全边界
316
175
 
317
- FET is a local workflow helper. It is not a sandbox, mandatory CI gate, or cryptographic audit system. Direct `openspec` calls can bypass FET local gates. Teams that require enforcement should repeat validation in CI, branch protection, or review policy.
176
+ FET 是本地工作流辅助工具，不是沙箱、强制 CI gate 或密码学审计系统。直接调用 `openspec` 可以绕过 FET 的本地 gate。团队如果需要强制执行验证，应在 CI、分支保护或代码审查规则中重复校验。
318
177
 
319
- ### Development
178
+ ## 开发
320
179
 
321
180
  ```sh
322
181
  npm install
@@ -326,12 +185,12 @@ npm run build
326
185
  npm run release:check
327
186
  ```
328
187
 
329
- Run the real OpenSpec smoke test:
188
+ 运行真实 OpenSpec 烟测：
330
189
 
331
190
  ```powershell
332
191
  $env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec
333
192
  ```
334
193
 
335
- ### License
194
+ ## 许可证
336
195
 
337
196
  MIT
package/README_en.md ADDED
@@ -0,0 +1,196 @@
1
+ # FET
2
+
3
+ [中文](./README.md) | [English](./README_en.md)
4
+
5
+ FET is a frontend development workflow orchestration CLI built around OpenSpec. It does not generate business code directly. Instead, it proxies OpenSpec commands, maintains local workflow state, generates auditable project context, and helps AI coding tools such as Cursor and Codex load the right project material.
6
+
7
+ ## What It Does
8
+
9
+ - Provides one entry point: wraps OpenSpec workflows with `fet <command>` so users and AI tools do not bypass FET state tracking.
10
+ - Generates context: scans the project and writes `AGENTS.md` plus the `fet:` namespace in `openspec/config.yaml`.
11
+ - Manages state: records the active change, synced tasks, manual verification declarations, tool adapter state, and language preference.
12
+ - Integrates AI tools: generates Cursor rules and Skills, plus Codex context files, command guides, and native slash prompts.
13
+ - Unifies language: Chinese is the default for interaction messages and generated artifacts; use `--lang <language>` to switch.
14
+ - Guards critical stages: checks FET verification state before `sync` / `archive`.
15
+ - Supports optional code graphs: integrates with GitNexus so AI tools can prefer structured code context before broad repository scans.
16
+
17
+ ## How It Works
18
+
19
+ FET is a transparent proxy and local orchestration layer for OpenSpec. When you run commands such as `fet apply` or `fet archive`, FET loads project and change state, runs required pre-hooks, calls the real `openspec` CLI, and then updates FET state based on the result.
20
+
21
+ FET proxy commands keep the native OpenSpec command name intact. For example, `fet apply --change <id>` calls `openspec apply --change <id>`, and `fet sync --change <id>` calls `openspec sync --change <id>` after FET's verification gate passes.
22
+
23
+ ## Requirements
24
+
25
+ - Node.js 18 or newer
26
+ - OpenSpec CLI available on `PATH`
27
+
28
+ Install OpenSpec:
29
+
30
+ ```sh
31
+ npm install -g @fission-ai/openspec
32
+ ```
33
+
34
+ ## Installation
35
+
36
+ ```sh
37
+ npm install -g @nick848/fet
38
+ ```
39
+
40
+ Check the installation:
41
+
42
+ ```sh
43
+ fet --version
44
+ fet --help
45
+ ```
46
+
47
+ ## Quick Start
48
+
49
+ Run this in a project root that should use OpenSpec:
50
+
51
+ ```sh
52
+ fet init
53
+ fet doctor
54
+ ```
55
+
56
+ Typical workflow:
57
+
58
+ ```sh
59
+ fet new my-change
60
+ fet continue
61
+ fet apply
62
+ fet verify --change my-change
63
+ fet verify --done --change my-change
64
+ fet sync
65
+ fet archive --change my-change
66
+ ```
67
+
68
+ When `continue`, `apply`, `ff`, or `sync` is called without `--change`, FET first uses the recorded active change. If there is exactly one open change, FET uses it automatically.
69
+
70
+ ## Language
71
+
72
+ FET defaults to Chinese for interaction messages and generated artifacts.
73
+
74
+ ```sh
75
+ fet init --lang zh-CN
76
+ fet init --lang en
77
+ ```
78
+
79
+ `fet init --lang <language>` saves the language in `openspec/fet-state.json`. Later commands reuse the saved language when `--lang` is not provided. Supported values:
80
+
81
+ | Value | Meaning |
82
+ |-------|---------|
83
+ | `zh-CN`, `zh`, `cn`, `chinese` | Chinese |
84
+ | `en`, `en-US`, `english` | English |
85
+
86
+ ## Global Options
87
+
88
+ | Option | Description | Example |
89
+ |--------|-------------|---------|
90
+ | `--cwd <path>` | Set the project root. Defaults to the current directory. | `fet doctor --cwd ./app` |
91
+ | `--change <id>` | Select an OpenSpec change. | `fet apply --change add-login` |
92
+ | `--lang <language>` | Set the language for interaction messages and generated artifacts. | `fet init --lang en` |
93
+ | `--yes` | Accept low-risk confirmations. | `fet init --yes` |
94
+ | `--json` | Print machine-readable JSON. | `fet doctor --json` |
95
+ | `--verbose` | Print more diagnostics. | `fet doctor --verbose` |
96
+ | `--no-color` | Disable terminal colors. | `fet --no-color doctor` |
97
+
98
+ ## Commands
99
+
100
+ | Command | Usage | Description |
101
+ |---------|-------|-------------|
102
+ | `fet init` | `fet init [--yes] [--lang <language>]` | Initialize FET and OpenSpec; generate context, state, Cursor integration, and Codex workflow guides. |
103
+ | `fet update-context` | `fet update-context [--yes]` | Rescan the project and update FET-managed regions in `AGENTS.md` and `openspec/config.yaml`. |
104
+ | `fet fill-context` | `fet fill-context [--yes]` | Refresh IDE handoff commands that ask AI to replace `AGENTS.md` placeholders. |
105
+ | `fet doctor` | `fet doctor [--fix-lock]` | Diagnose OpenSpec, FET state, context files, tool integration, and lock files. |
106
+ | `fet explore` | `fet explore [...args] [--change <id>]` | Run native OpenSpec explore through FET so clarification prompts remain interactive. |
107
+ | `fet propose` | `fet propose <change-id>` | Create a new OpenSpec change and enter the proposal workflow. |
108
+ | `fet new` | `fet new <change-id>` | Create a new OpenSpec change. |
109
+ | `fet continue` | `fet continue [...args] [--change <id>]` | Run native OpenSpec continue through FET. |
110
+ | `fet ff` | `fet ff [...args] [--change <id>]` | Run native OpenSpec ff through FET. |
111
+ | `fet apply` | `fet apply [...args] [--change <id>]` | Run native OpenSpec apply through FET and update FET state. |
112
+ | `fet verify` | `fet verify --change <id>` | Generate `.fet/verify-instructions.md` for manual verification. |
113
+ | `fet verify --done` | `fet verify --done --change <id>` | Declare manual verification complete and allow later `sync` / `archive`. |
114
+ | `fet verify --auto` | `fet verify --auto [--yes]` | Generate an automatic verification plan. This version does not run project scripts; `--yes` records the plan fingerprint. |
115
+ | `fet sync` | `fet sync [...args] [--change <id>]` | Run native OpenSpec sync after the FET verify gate passes. |
116
+ | `fet archive` | `fet archive --change <id>` | Archive the change after the FET verify gate passes and append to `CHANGELOG.md`. |
117
+ | `fet bulk-archive` | `fet bulk-archive [...args] [--change <id>]` | Run native OpenSpec bulk-archive through FET. |
118
+ | `fet onboard` | `fet onboard [...args] [--change <id>]` | Run native OpenSpec onboard through FET. |
119
+ | `fet passthrough` | `fet passthrough <command> [...args]` | Pass through unmanaged OpenSpec commands without updating FET lifecycle state. |
120
+
121
+ ## GitNexus Graph Support
122
+
123
+ GitNexus support is optional. FET detects a `gitnexus` executable during `fet init` and records the result in `openspec/fet-state.json`. If GitNexus is not installed, init shows a one-time recommendation and continues normally. `fet doctor` reports missing GitNexus as a warning only.
124
+
125
+ Graph commands are grouped under `fet graph`:
126
+
127
+ | Command | Description |
128
+ |---------|-------------|
129
+ | `fet graph status` | Check GitNexus, the graph path, and current status; update FET state. |
130
+ | `fet graph setup` | Generate `.fet/graph-setup.md` for installation and IDE-assisted setup guidance; FET does not install GitNexus automatically. |
131
+ | `fet graph init` | Run `gitnexus analyze` to build the first graph. |
132
+ | `fet graph refresh` | Run `gitnexus analyze` again to refresh the graph. |
133
+ | `fet graph doctor` | Diagnose graph integration health; missing graph support warns but does not block FET/OpenSpec commands. |
134
+ | `fet graph handoff` | Generate `.fet/graph-handoff.md` so Cursor, Codex, OpenCode, and other IDE AI tools can prefer graph context before broad scans. |
135
+
136
+ By default, FET looks for `gitnexus` on `PATH` and expects the graph directory at `.gitnexus`. Advanced users can override this with `FET_GITNEXUS_EXECUTABLE`, `FET_GITNEXUS_COMMAND`, and `FET_GITNEXUS_GRAPH_PATH`.
137
+
138
+ ## Andrej Karpathy Inspired Guidelines
139
+
140
+ `fet init` and `fet update-context` add FET-managed Andrej Karpathy inspired coding guidelines to the current project. FET does not assume Codex or OpenCode will read `CLAUDE.md` automatically, so it syncs the guidance into multiple context files:
141
+
142
+ - `CLAUDE.md`: appends or refreshes a managed `FET:BEGIN ANDREJ-KARPATHY-SKILLS` block.
143
+ - `.fet/karpathy-guidelines.md`: generic IDE handoff.
144
+ - `.codex/fet/karpathy-guidelines.md`: Codex-specific context.
145
+ - `.cursor/rules/karpathy-guidelines.mdc`: Cursor project rule.
146
+
147
+ The generated guidance is not a full copy of the upstream repository. It is a concise project-level adaptation of `andrej-karpathy-skills`: think before coding, keep changes simple, edit precisely, and verify against concrete goals. Source project: <https://github.com/forrestchang/andrej-karpathy-skills>.
148
+
149
+ ## Generated Files
150
+
151
+ FET may create or update:
152
+
153
+ - `AGENTS.md`
154
+ - the `fet:` namespace in `openspec/config.yaml`
155
+ - `openspec/fet-state.json`
156
+ - `openspec/changes/<change-id>/fet-state.json`
157
+ - `openspec/changes/<change-id>/.fet/verify-instructions.md`
158
+ - `CHANGELOG.md`
159
+ - `.fet/fill-context.md`
160
+ - `.fet/graph-setup.md`
161
+ - `.fet/graph-handoff.md`
162
+ - `.fet/karpathy-guidelines.md`
163
+ - `CLAUDE.md`
164
+ - `.cursor/skills/fet-*/SKILL.md`
165
+ - `.cursor/rules/fet-context.mdc`
166
+ - `.cursor/rules/karpathy-guidelines.mdc`
167
+ - `.codex/fet/context.md`
168
+ - `.codex/fet/karpathy-guidelines.md`
169
+ - `.codex/fet/commands/*.md`
170
+ - `$CODEX_HOME/prompts/fet-*.md`
171
+
172
+ FET only owns explicitly marked managed regions. User content outside those regions should be preserved. During `fet init`, FET also adds a managed `.gitignore` block for local workflow state.
173
+
174
+ ## Safety Model
175
+
176
+ FET is a local workflow helper. It is not a sandbox, mandatory CI gate, or cryptographic audit system. Direct `openspec` calls can bypass FET local gates. Teams that require enforcement should repeat validation in CI, branch protection, or review policy.
177
+
178
+ ## Development
179
+
180
+ ```sh
181
+ npm install
182
+ npm run typecheck
183
+ npm run test
184
+ npm run build
185
+ npm run release:check
186
+ ```
187
+
188
+ Run the real OpenSpec smoke test:
189
+
190
+ ```powershell
191
+ $env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec
192
+ ```
193
+
194
+ ## License
195
+
196
+ MIT