@nick848/fet 1.1.8 → 1.1.10

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 +120 -13
  2. package/README_en.md +116 -13
  3. package/dist/cli/index.js +961 -165
  4. package/dist/cli/index.js.map +1 -1
  5. package/package.json +9 -1
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # FET
2
2
 
3
- [中文](./README.md) | [English](./README_en.md)
3
+ [中文](https://unpkg.com/@nick848/fet/README.md) | [English](https://unpkg.com/@nick848/fet/README_en.md)
4
+
5
+ > npm 包页只展示 `README.md`，站内 `./README_en.md` 等相对链接会 404。请用上方 **unpkg** 链接打开同 npm 包内的另一份文档；源码仓库见 [Gitee](https://gitee.com/agent-team/fet)。
4
6
 
5
7
  FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor、Codex 等 AI 编程工具读取正确的项目资料。
6
8
 
@@ -45,31 +47,133 @@ npm install -g @nick848/fet
45
47
  ```sh
46
48
  fet --version
47
49
  fet --help
50
+ fet update
48
51
  ```
49
52
 
50
- ## 快速开始
53
+ ## 第一次使用（推荐顺序）
54
+
55
+ 以下流程面向**第一次在业务项目中接入 FET** 的场景。请在你希望接入 OpenSpec 的**项目根目录**（含 `package.json` 或业务源码的目录）执行，而不是在 FET 工具仓库自身目录。
56
+
57
+ ### 步骤 1：安装依赖工具
58
+
59
+ 1. 安装 [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec)（全局）：
60
+
61
+ ```sh
62
+ npm install -g @fission-ai/openspec
63
+ openspec --version
64
+ ```
65
+
66
+ 2. 安装 FET（全局）：
51
67
 
52
- 在需要接入 OpenSpec 的项目根目录运行：
68
+ ```sh
69
+ npm install -g @nick848/fet
70
+ fet --version
71
+ ```
72
+
73
+ ### 步骤 2：初始化项目
74
+
75
+ 在业务项目根目录执行：
76
+
77
+ ```sh
78
+ fet init --yes
79
+ ```
80
+
81
+ `fet init` 会：
82
+
83
+ - 检测 OpenSpec；若项目尚无 `openspec/`，则调用 `openspec init`
84
+ - 扫描仓库并生成 `AGENTS.md`、`openspec/config.yaml` 的 `fet:` 配置
85
+ - 写入 `openspec/fet-state.json` 等工作流状态
86
+ - 为 **Cursor**、**Codex** 生成 Skill / 规则 / 命令指南（见下文「在 IDE 中使用」）
87
+ - 可选检测 GitNexus（未安装仅提示一次，不阻断）
88
+
89
+ 需要英文产物时，可在初始化时指定：
90
+
91
+ ```sh
92
+ fet init --yes --lang en
93
+ ```
94
+
95
+ ### 步骤 3：检查环境
53
96
 
54
97
  ```sh
55
- fet init
56
- fet fill-context
57
98
  fet doctor
58
99
  ```
59
100
 
60
- 典型流程：
101
+ 确认 OpenSpec 路径、上下文文件、工具集成无 `fail`。若有锁文件残留，可执行 `fet doctor --fix-lock`。
102
+
103
+ ### 步骤 4：补齐项目上下文（与 IDE 协作）
104
+
105
+ 扫描器无法自动推断的内容会在 `AGENTS.md` 中标记为 `[NEEDS LLM INPUT]`。请执行：
61
106
 
62
107
  ```sh
63
- fet new my-change
64
- fet continue
65
- fet apply
108
+ fet fill-context
109
+ ```
110
+
111
+ 然后在 **Cursor** 或 **Codex** 中按生成的 handoff 说明（如 `.fet/fill-context.md`、`.cursor/skills/fet-fill-context/SKILL.md`）让 AI 协助补全占位符。补全后再次运行 `fet doctor`，占位符相关项应为通过。
112
+
113
+ ### 步骤 5：（可选）配置代码图
114
+
115
+ 若希望 AI 在大范围扫仓库前先读结构化代码图，请先安装 GitNexus CLI（确保 `gitnexus` 在 PATH 中），再执行：
116
+
117
+ ```sh
118
+ fet graph setup # 生成安装引导，FET 不会自动安装 GitNexus
119
+ fet graph init # 首次构建图谱
120
+ fet graph handoff # 生成 IDE 交接说明
121
+ ```
122
+
123
+ ### 步骤 6：在 IDE 中使用
124
+
125
+ 初始化完成后，建议在 AI 工具中确认以下资料可被读取：
126
+
127
+ | 工具 | 主要入口 |
128
+ |------|----------|
129
+ | Cursor | `.cursor/rules/fet-context.mdc`；`.cursor/skills/fet-*/SKILL.md` |
130
+ | Codex | `.codex/fet/context.md`；`$CODEX_HOME/prompts/fet-*.md` |
131
+
132
+ 工作流命令请在**终端**执行 `fet <command>`（例如 `fet apply`），不要绕过 FET 直接调用 `openspec`，否则本地状态与 verify 闸门不会更新。
133
+
134
+ ### 步骤 7：完成第一个 change
135
+
136
+ 初始化无误后，按 OpenSpec 工作流创建并落地第一个变更。简单路径示例：
137
+
138
+ ```sh
139
+ fet propose my-first-change
140
+ # 或在 Cursor/Codex 中按提示逐步执行 fet continue
141
+ fet tdd --change my-first-change
142
+ fet apply --change my-first-change
143
+ fet test --change my-first-change
144
+ fet verify --change my-first-change
145
+ fet verify --done --change my-first-change
146
+ fet sync --change my-first-change
147
+ fet archive --change my-first-change
148
+ ```
149
+
150
+ 复杂路径可先 `fet new <id>`，再多次 `fet continue` 或 `fet ff`。各阶段说明见下文「日常变更流程」。
151
+
152
+ ---
153
+
154
+ ## 日常变更流程
155
+
156
+ 在已完成「第一次使用」的项目中，典型循环为：
157
+
158
+ ```sh
159
+ fet new my-change # 或 fet propose my-change
160
+ fet continue # 按需重复，生成下一规划产物
161
+ fet tdd --change my-change # 生成本 change 的 TDD 清单（.fet/tdd-manifest.yaml）
162
+ fet apply --change my-change
163
+ fet test --change my-change
66
164
  fet verify --change my-change
67
165
  fet verify --done --change my-change
68
- fet sync
166
+ fet sync --change my-change
69
167
  fet archive --change my-change
70
168
  ```
71
169
 
72
- `continue`、`apply`、`ff`、`sync` 等命令在未显式传入 `--change` 时，会优先使用 FET 记录的 active change；如果只有一个打开的 change，也会自动使用它。
170
+ 说明：
171
+
172
+ - `continue`、`apply`、`ff`、`sync` 等命令在未传 `--change` 时，优先使用 FET 记录的 **active change**；若仅有一个打开的 change，会自动选中。
173
+ - `fet apply` 默认要求已运行 `fet tdd`（`openspec/config.yaml` 中 `fet.tdd.mode` 可配置）。
174
+ - `fet verify` 要求本 change 已通过 `fet test`（除非 `fet.tdd.enabled: false` 或 test 被配置为 skip）。
175
+ - 经 FET 执行的 `sync` / `archive` 会先检查是否已 `fet verify --done`。
176
+ - 项目结构变化后运行 `fet update-context`；仅刷新 IDE 占位符提示时运行 `fet fill-context`。
73
177
 
74
178
  ## 语言设置
75
179
 
@@ -116,6 +220,7 @@ fet init --lang en
116
220
  | 命令 | 用法 | 说明 |
117
221
  |------|------|------|
118
222
  | `fet init` | `fet init [--yes] [--lang <language>]` | 初始化 FET 和 OpenSpec；生成上下文、状态、Cursor 集成和 Codex 工作流指南。 |
223
+ | `fet update` | `fet update` | 检查 npm 上的新版本并在需要时自动升级 FET。 |
119
224
  | `fet update-context` | `fet update-context [--yes]` | 重新扫描项目并更新 `AGENTS.md` 与 `openspec/config.yaml` 的 FET 托管区域。 |
120
225
  | `fet fill-context` | `fet fill-context [--yes]` | 刷新 IDE 交接命令；自动识别小程序工程并写入包体积/2MB 约束，引导 AI 补齐其余 `AGENTS.md` 占位符。 |
121
226
  | `fet doctor` | `fet doctor [--fix-lock]` | 诊断 OpenSpec、FET 状态、上下文文件、工具集成和锁文件。 |
@@ -124,8 +229,10 @@ fet init --lang en
124
229
  | `fet new` | `fet new <change-id>` | 创建新的 OpenSpec change。 |
125
230
  | `fet continue` | `fet continue [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 continue。 |
126
231
  | `fet ff` | `fet ff [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 ff。 |
127
- | `fet apply` | `fet apply [...args] [--change <id>]` | 通过 FET 执行 OpenSpec 原生 apply，并同步 FET 状态。 |
128
- | `fet verify` | `fet verify --change <id>` | 生成 `.fet/verify-instructions.md` 手动验证指令。 |
232
+ | `fet tdd` | `fet tdd [--change <id>]` | 根据规划产物生成 `openspec/changes/<id>/.fet/tdd-manifest.yaml` 等 TDD 契约。 |
233
+ | `fet apply` | `fet apply [...args] [--change <id>]` | 准备实施指令；需先有 TDD 清单（默认）。 |
234
+ | `fet test` | `fet test [--change <id>] [--plan]` | 按 TDD 清单运行项目 test 脚本并记录绿灯状态。 |
235
+ | `fet verify` | `fet verify --change <id>` | 生成 `.fet/verify-instructions.md`；需先 `fet test` 通过。 |
129
236
  | `fet verify --done` | `fet verify --done --change <id>` | 声明手动验证完成，允许后续 `sync` / `archive`。 |
130
237
  | `fet verify --auto` | `fet verify --auto [--yes]` | 生成自动验证计划；当前版本不执行项目脚本，`--yes` 会记录计划指纹。 |
131
238
  | `fet sync` | `fet sync [...args] [--change <id>]` | FET verify gate 通过后执行 OpenSpec 原生 sync。 |
package/README_en.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # FET
2
2
 
3
- [中文](./README.md) | [English](./README_en.md)
3
+ [中文](https://unpkg.com/@nick848/fet/README.md) | [English](https://unpkg.com/@nick848/fet/README_en.md)
4
+
5
+ > The npm package page only renders `README.md`; relative links such as `./README_en.md` return 404. Use the **unpkg** links above to open the other file from the same npm package. Source repo: [Gitee](https://gitee.com/agent-team/fet).
4
6
 
5
7
  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
8
 
@@ -48,29 +50,128 @@ fet --help
48
50
  fet update
49
51
  ```
50
52
 
51
- ## Quick Start
53
+ ## First-Time Setup (Recommended Order)
54
+
55
+ This section is for **bringing FET into a business project for the first time**. Run commands in the **project root** you want OpenSpec to manage (where your app source lives), not inside the FET tool repository itself.
56
+
57
+ ### Step 1: Install required tools
58
+
59
+ 1. Install the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) globally:
60
+
61
+ ```sh
62
+ npm install -g @fission-ai/openspec
63
+ openspec --version
64
+ ```
65
+
66
+ 2. Install FET globally:
52
67
 
53
- Run this in a project root that should use OpenSpec:
68
+ ```sh
69
+ npm install -g @nick848/fet
70
+ fet --version
71
+ ```
72
+
73
+ ### Step 2: Initialize the project
74
+
75
+ From your project root:
76
+
77
+ ```sh
78
+ fet init --yes
79
+ ```
80
+
81
+ `fet init` will:
82
+
83
+ - Detect OpenSpec and run `openspec init` when `openspec/` is missing
84
+ - Scan the repository and generate `AGENTS.md` plus the `fet:` namespace in `openspec/config.yaml`
85
+ - Write workflow state such as `openspec/fet-state.json`
86
+ - Install **Cursor** and **Codex** integration files (see “Use in your IDE” below)
87
+ - Optionally detect GitNexus (a one-time recommendation if missing; non-blocking)
88
+
89
+ For English interaction messages and generated artifacts:
90
+
91
+ ```sh
92
+ fet init --yes --lang en
93
+ ```
94
+
95
+ ### Step 3: Verify the environment
54
96
 
55
97
  ```sh
56
- fet init
57
- fet fill-context
58
98
  fet doctor
59
99
  ```
60
100
 
61
- Typical workflow:
101
+ Confirm there are no `fail` results for OpenSpec, context files, or tool integration. Use `fet doctor --fix-lock` if a stale `openspec/.fet.lock` is reported.
102
+
103
+ ### Step 4: Fill project context (with your IDE)
104
+
105
+ The scanner marks unknown facts in `AGENTS.md` as `[NEEDS LLM INPUT]`. Run:
62
106
 
63
107
  ```sh
64
- fet new my-change
65
- fet continue
66
- fet apply
108
+ fet fill-context
109
+ ```
110
+
111
+ Then, in **Cursor** or **Codex**, follow the generated handoff (for example `.fet/fill-context.md` or `.cursor/skills/fet-fill-context/SKILL.md`) so the AI can help replace placeholders. Run `fet doctor` again afterward; placeholder checks should pass.
112
+
113
+ ### Step 5: (Optional) Set up a code graph
114
+
115
+ To let AI prefer structured graph context before broad repository scans, install GitNexus, then:
116
+
117
+ ```sh
118
+ fet graph setup # installation guide only; FET does not install GitNexus for you
119
+ fet graph init # first graph build
120
+ fet graph handoff # IDE handoff document
121
+ ```
122
+
123
+ ### Step 6: Use in your IDE
124
+
125
+ After initialization, make sure your AI tool can read:
126
+
127
+ | Tool | Main entry points |
128
+ |------|-------------------|
129
+ | Cursor | `.cursor/rules/fet-context.mdc`; `.cursor/skills/fet-*/SKILL.md` |
130
+ | Codex | `.codex/fet/context.md`; `$CODEX_HOME/prompts/fet-*.md` |
131
+
132
+ Run workflow commands in the **terminal** as `fet <command>` (for example `fet apply`). Calling `openspec` directly bypasses FET state and the verify gate.
133
+
134
+ ### Step 7: Complete your first change
135
+
136
+ When setup looks healthy, drive your first OpenSpec change. Simple path example:
137
+
138
+ ```sh
139
+ fet propose my-first-change
140
+ # or use fet continue step by step from your IDE handoff
141
+ fet tdd --change my-first-change
142
+ fet apply --change my-first-change
143
+ fet test --change my-first-change
144
+ fet verify --change my-first-change
145
+ fet verify --done --change my-first-change
146
+ fet sync --change my-first-change
147
+ fet archive --change my-first-change
148
+ ```
149
+
150
+ For the expanded workflow, start with `fet new <id>` and repeat `fet continue` or run `fet ff`. See “Day-to-day change workflow” below.
151
+
152
+ ---
153
+
154
+ ## Day-to-day change workflow
155
+
156
+ After first-time setup, a typical loop is:
157
+
158
+ ```sh
159
+ fet new my-change # or fet propose my-change
160
+ fet continue # repeat as needed for the next planning artifact
161
+ fet tdd --change my-change
162
+ fet apply --change my-change
163
+ fet test --change my-change
67
164
  fet verify --change my-change
68
165
  fet verify --done --change my-change
69
- fet sync
166
+ fet sync --change my-change
70
167
  fet archive --change my-change
71
168
  ```
72
169
 
73
- 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.
170
+ Notes:
171
+
172
+ - When `continue`, `apply`, `ff`, or `sync` is called without `--change`, FET uses the recorded **active change**, or the only open change when there is exactly one.
173
+ - `sync` and `archive` through FET require `fet verify --done` first.
174
+ - Run `fet update-context` after major project structure changes; run `fet fill-context` when you only need to refresh IDE placeholder handoff.
74
175
 
75
176
  ## Language
76
177
 
@@ -126,8 +227,10 @@ Before most commands (except `fet update`), FET checks npm for a newer release (
126
227
  | `fet new` | `fet new <change-id>` | Create a new OpenSpec change. |
127
228
  | `fet continue` | `fet continue [...args] [--change <id>]` | Run native OpenSpec continue through FET. |
128
229
  | `fet ff` | `fet ff [...args] [--change <id>]` | Run native OpenSpec ff through FET. |
129
- | `fet apply` | `fet apply [...args] [--change <id>]` | Run native OpenSpec apply through FET and update FET state. |
130
- | `fet verify` | `fet verify --change <id>` | Generate `.fet/verify-instructions.md` for manual verification. |
230
+ | `fet tdd` | `fet tdd [--change <id>]` | Generate per-change TDD manifest under `openspec/changes/<id>/.fet/`. |
231
+ | `fet apply` | `fet apply [...args] [--change <id>]` | Prepare implementation instructions; requires TDD manifest by default. |
232
+ | `fet test` | `fet test [--change <id>] [--plan]` | Run project tests scoped to the TDD manifest; record pass/fail. |
233
+ | `fet verify` | `fet verify --change <id>` | Generate verify instructions; requires `fet test` pass first. |
131
234
  | `fet verify --done` | `fet verify --done --change <id>` | Declare manual verification complete and allow later `sync` / `archive`. |
132
235
  | `fet verify --auto` | `fet verify --auto [--yes]` | Generate an automatic verification plan. This version does not run project scripts; `--yes` records the plan fingerprint. |
133
236
  | `fet sync` | `fet sync [...args] [--change <id>]` | Run native OpenSpec sync after the FET verify gate passes. |