flow-comet 1.6.3 → 1.6.4
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/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +6 -6
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +67 -18878
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1030 -0
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
- package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
- package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
- package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +815 -0
- package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
- package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
- package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +614 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +553 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +837 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +404 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +302 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +141 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +700 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +106 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +189 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1441 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1228 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2484 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +966 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1388 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1364 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1484 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +58 -7559
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +151 -2476
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/README.md +52 -69
- package/package.json +3 -2
- package/scripts/dsh-bridge.mjs +2 -2
- package/scripts/lib/installer-cleanup.mjs +152 -0
- package/scripts/lib/installer-flowkit.mjs +119 -0
- package/scripts/lib/installer-hooks.mjs +363 -0
- package/scripts/lib/installer-loader.mjs +220 -0
- package/scripts/lib/installer-migrate.mjs +236 -0
- package/scripts/lib/installer-platforms.mjs +314 -0
- package/scripts/prepare-env.mjs +21 -1313
|
@@ -17,7 +17,7 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
|
|
|
17
17
|
|
|
18
18
|
| 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
|
|
19
19
|
|------|-------------------------------|-----------------------------------|
|
|
20
|
-
| TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 + 新格式任务的 7 字段在场(集合见本册 `SKILL.md`「必填段清单」表行;单一权威 = `
|
|
20
|
+
| TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 + 新格式任务的 7 字段在场(集合见本册 `SKILL.md`「必填段清单」表行;单一权威 = 技能脚本的 `lib/task-graph.mjs` 导出的 `TASK7_REQUIRED` 常量,本文不复述集合) | 任务规模 / 粒度 / 字段内容质量(模板要求,guard 不拦)——**填得好不好**由 review 把关;`id` 是 `<task>` 元素的属性(不是字段:`<task id="T01" parallel="true" status="pending">`) |
|
|
21
21
|
|
|
22
22
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
23
23
|
|
package/README.md
CHANGED
|
@@ -4,17 +4,15 @@
|
|
|
4
4
|
|
|
5
5
|
</div>
|
|
6
6
|
|
|
7
|
-
<h1 align="center">flow-comet</h1>
|
|
8
|
-
|
|
9
7
|
<p align="center">
|
|
10
|
-
<
|
|
11
|
-
<br />
|
|
12
|
-
<em>For AI coding workflows — deterministic state machine · protocol-driven · guard-validated · subagent-isolated</em>
|
|
8
|
+
<img src="assets/readme/hero.svg" width="100%" alt="flow-comet — the project mark beside the name, and the engine's eight nodes drawn as a rail in which every transition carries a gate" />
|
|
13
9
|
</p>
|
|
14
10
|
|
|
15
11
|
<p align="center">
|
|
16
|
-
<a href="
|
|
17
|
-
<a href="
|
|
12
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat" alt="License: MIT" /></a>
|
|
13
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
14
|
+
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI status" /></a>
|
|
15
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.4-blue.svg" alt="Version 1.6.4" /></a>
|
|
18
16
|
</p>
|
|
19
17
|
|
|
20
18
|
<p align="center">
|
|
@@ -22,13 +20,6 @@
|
|
|
22
20
|
<a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-10A37F?style=flat&logoColor=white" alt="Codex" /></a>
|
|
23
21
|
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-4D6BFE?style=flat&logoColor=white" alt="DeepSeek Harness" /></a>
|
|
24
22
|
<a href="https://github.com/rihebty/flow-kit"><img src="https://img.shields.io/badge/flow--kit-4CAF50?style=flat" alt="flow-kit" /></a>
|
|
25
|
-
<a href="https://github.com/rpamis/comet"><img src="https://img.shields.io/badge/comet-4CAF50?style=flat" alt="comet" /></a>
|
|
26
|
-
</p>
|
|
27
|
-
|
|
28
|
-
<p align="center">
|
|
29
|
-
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
30
|
-
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
|
|
31
|
-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.3-blue.svg" alt="Version" /></a>
|
|
32
23
|
</p>
|
|
33
24
|
|
|
34
25
|
---
|
|
@@ -48,7 +39,7 @@ cd <your project>
|
|
|
48
39
|
fcomet init
|
|
49
40
|
```
|
|
50
41
|
|
|
51
|
-
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal
|
|
42
|
+
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal, a run without `--platform` asks which platform to set up — the arrow-key selector pre-selects the platforms it detects, and the fallback prompt takes the detected platform as its default (Claude Code when several traces are present); for a non-interactive pick use `--platform claude-code`, `--platform codex`, `--platform dsh`, a comma-separated combination such as `--platform claude-code,dsh`, or `--platform all`. Re-running the same command updates an existing install and is idempotent. Upgrading the global package only replaces the CLI — run `fcomet init` in a project again to refresh that project's copy.
|
|
52
43
|
|
|
53
44
|
**Verify**:
|
|
54
45
|
|
|
@@ -71,84 +62,76 @@ The first call confirms scope, then creates the branch for the change, initializ
|
|
|
71
62
|
|
|
72
63
|
To see where it is, just ask it — or inspect it from the command line with `status` and `next` in the project (the per-platform paths are in [Installation](docs/INSTALLATION.md)).
|
|
73
64
|
|
|
74
|
-
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is
|
|
65
|
+
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is appended at the top of `.specs/CHANGELOG.md`. The node-by-node walkthrough — including what the workflow runs underneath, and how to drive a node by hand when you need to — is in [Usage](docs/USAGE.md).
|
|
75
66
|
|
|
76
67
|
## Pick a platform
|
|
77
68
|
|
|
78
69
|
| Platform | Skills install to | Hook / bridge | First use |
|
|
79
70
|
|---|---|---|---|
|
|
80
71
|
| Claude Code (default) | `.claude/skills/` | `settings.local.json` → `hooks.PreToolUse` | the workspace must be trusted; headless sessions need that trust pre-accepted |
|
|
81
|
-
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs
|
|
72
|
+
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs |
|
|
82
73
|
| DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
|
|
83
74
|
|
|
84
75
|
Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
|
|
85
76
|
|
|
86
|
-
##
|
|
77
|
+
## Real-run artifacts
|
|
87
78
|
|
|
88
|
-
|
|
79
|
+
A complete 8-node run leaves the artifact trail below — [a real archived change](docs/examples/processor-pipeline/) from the end-to-end test project (2026-08-13), kept in this repository as the quality reference: CHANGE / REQUIREMENT / DESIGN / TASK / six-section summaries / REVIEW with disposition markers / TEST / UAT / KNOWN-ISSUES / skill-load declaration markers.
|
|
89
80
|
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
81
|
+
```
|
|
82
|
+
processor-pipeline/ (archived change, full artifact set)
|
|
83
|
+
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
84
|
+
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
85
|
+
├── REVIEW.md (findings with disposition markers)
|
|
86
|
+
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
87
|
+
├── KNOWN-ISSUES.md
|
|
88
|
+
└── .skill-loads/ (11 skill-load declaration markers)
|
|
89
|
+
```
|
|
95
90
|
|
|
96
|
-
|
|
91
|
+
Two captures from real sessions of this project, unedited: a workflow skill loading normally more than four hours in, and the end of a five-hour run whose verify exit had already executed the test commands.
|
|
97
92
|
|
|
98
|
-
|
|
93
|
+
<p align="center">
|
|
94
|
+
<img src="assets/readme/proof-board.png" width="100%" alt="Two terminal captures: a workflow skill loading four hours into a session, and the end of a five-hour run after verification" />
|
|
95
|
+
</p>
|
|
99
96
|
|
|
100
|
-
|
|
101
|
-
|---------|-------------|-----------|---------------------------|
|
|
102
|
-
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process + `.specs/` templates + R1-R8 rules, zero runtime | Humans load prompt files stage by stage; state flows through `.md` artifacts | **Dependency / base** — flow-comet is its automation layer; artifacts and rules fully inherited |
|
|
103
|
-
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding | `openspec/` directory, one proposal/specs/design/tasks per change, propose→apply→verify→archive | **Idea source + lighter alternative** — spec-first thinking fused into flow-kit; standalone use is lighter (no state machine, no stage gates) |
|
|
104
|
-
| **Superpowers** (obra) | Claude Code skill set + full dev methodology | Composable skills (brainstorm/plan/TDD/debug/review), triggered by context, enforced by instructions | **Idea source + partial overlap** — skill-based discipline relies on model compliance; flow-comet scripts and machine-verifies the same discipline |
|
|
105
|
-
| **comet** (rpamis) | Resumable long-task workflows + skill platform: protocol state machine, guard gates, hook interception | `/comet` routes by config; Classic = OpenSpec + Superpowers 5-stage state machine | **Mechanism source** — flow-comet borrows its mechanism shapes (protocol-as-truth, script-owned state, guard gates, hook whitelist) and drops its platform facilities (eval/publish); state does not interoperate with Comet Classic |
|
|
106
|
-
| **GSD** | Spec-driven development meta-prompt / context-engineering workflow | Milestones → slices → tasks; fresh context per stage with pre-inlined context; worktree isolation + UAT | **Idea source (same lane)** — fresh-context execution and stage gates align; no script state-machine routing, relies on prompt discipline |
|
|
107
|
-
| **spec-kit** (GitHub) | SDD toolkit: Spec → Plan → Tasks → Implement | Each stage feeds markdown artifacts to the next; task format with order IDs, parallel `[P]` markers, file paths | **Idea source (same lane)** — task-with-file-paths/parallel-marker shape is same-origin with flow-kit TASK; no stage-transition enforcement |
|
|
108
|
-
| **claude-task-master** | AI-driven task management (MCP + CLI) | PRD parsing → task decomposition → dependency graph → next-task orchestration | **Complement** — manages the task layer only (decomposition/ordering/dependencies), not stage gates, artifact validation, or write permissions |
|
|
97
|
+
## How it works
|
|
109
98
|
|
|
110
|
-
|
|
99
|
+
The process is flow-kit's nine stages; the engine runs them as eight nodes. CHANGE and REQUIREMENT are covered by `open`, TEST and REVIEW by `review`, and DEV runs as `execute` or `subagent-execute` depending on the execution mode. Every node's exit is validated before the next one opens — the `verify` exit really executes the commands in `TEST.md` — and each node's artifacts land under `.specs/<change-id>/`.
|
|
111
100
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| Validation | Humans eyeball artifacts against the rules; TEST.md commands "should" run | Guards enforce required artifacts/sections at every node entry/exit; verify actually executes the TEST.md commands and counts failures |
|
|
116
|
-
| Discipline enforcement | Rules are markdown text the model may ignore | Three defense layers: write whitelist physically blocks out-of-scope writes / coordinator prohibition / exit takeover detection |
|
|
117
|
-
| Recovery | Depends on conversation memory; progress is lost across sessions | File-as-truth: re-derive the node from `.specs/` and auto-correct state; any session resumes correctly |
|
|
118
|
-
| Parallel implementation | Humans coordinate multiple windows, easy to overstep | One delegation contract on every supported platform — write permission, commit isolation, verification isolation and integration discipline. The guard decides by the caller's identity, an isolated worktree is one implementation of write permission rather than a requirement, and the only platform difference is who builds the tree (per-platform channels and what is not yet covered: [Parallel delegation](docs/MECHANISM.md#parallel-delegation)). Subagents return a verified contract (commit hash + evidence) and the coordinator cannot write source |
|
|
119
|
-
| Decision burden | A confirmation point at every stage, humans answer everything | Decisions are classified (user-decided / auto-handled / stop conditions / manual handover); humans only intervene at key points (scope, tech stack, breaking changes, review findings, archive) |
|
|
101
|
+
<p align="center">
|
|
102
|
+
<img src="assets/readme/workflow.gif" width="100%" alt="An animated diagram mapping the nine flow-kit stages onto the engine's eight nodes: CHANGE and REQUIREMENT merge into open, TEST and REVIEW into review, DEV runs as execute or subagent-execute, and every transition carries a gate" />
|
|
103
|
+
</p>
|
|
120
104
|
|
|
121
|
-
|
|
105
|
+
Driving a node by hand, the artifacts each node produces, and the two command surfaces are documented in [Usage](docs/USAGE.md); what the engine guarantees and how a node's exit is validated are in [Core Mechanisms](docs/MECHANISM.md).
|
|
106
|
+
|
|
107
|
+
## Why flow-comet
|
|
122
108
|
|
|
123
109
|
1. **Discipline goes from "self-discipline" to "machine-checked"** — every stage entry/exit has script validation: artifacts complete, sections filled, verify commands actually run, tasks stay in bounds.
|
|
124
110
|
2. **No lost progress across sessions** — where you are is always derived from `.specs/` artifacts, never from conversation memory; reopen and continue from the right node.
|
|
125
|
-
3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement
|
|
126
|
-
4. **The native automation layer for flow-kit** — not a re-invention: artifact formats, rules, and stages are identical to flow-kit; a flow-kit project upgrades to a machine-driven flow by installing flow-comet, no migration needed.
|
|
127
|
-
5. **Protocol-driven, minimal dependency, install-and-run** — the built-in 8-node flow works out of the box; any installed skill can be composed into a custom protocol on the same engine; Node.js 18+; the only third-party dependency is `@clack/prompts`, used exclusively by the installer's TTY multi-select (with an automatic readline fallback otherwise); one command installs it.
|
|
111
|
+
3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement. The coordinator is banned from writing source, and writes outside the current node's scope are refused by the hook. The layers themselves are described in [Core Mechanisms](docs/MECHANISM.md).
|
|
128
112
|
|
|
129
|
-
|
|
113
|
+
### Related projects
|
|
130
114
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
processor-pipeline/ (archived change, full artifact set)
|
|
137
|
-
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
138
|
-
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
139
|
-
├── REVIEW.md (findings with disposition markers)
|
|
140
|
-
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
141
|
-
├── KNOWN-ISSUES.md
|
|
142
|
-
└── .skill-loads/ (11 skill-load declaration markers)
|
|
143
|
-
```
|
|
115
|
+
<p align="center">
|
|
116
|
+
<img src="assets/readme/related-projects.svg" width="100%" alt="How flow-comet relates to the projects it is compared with: five sources aggregated through flow-kit, comet as an early mechanism reference that is now decoupled, and brooks-lint as an optional integration" />
|
|
117
|
+
</p>
|
|
144
118
|
|
|
145
|
-
|
|
119
|
+
| Project | What it is, and how it works | Relationship to flow-comet |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer and inherits its artifacts and rules; the projects below reached flow-comet through it. |
|
|
122
|
+
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding. One `proposal` / `specs` / `design` / `tasks` set per change under `openspec/`; the default profile runs propose → apply → sync → archive. | **Aggregated through flow-kit** (idea source). Standalone it stays lighter: no state machine, no gates. |
|
|
123
|
+
| **Superpowers** (obra) | Agentic skills framework plus a full development methodology, installed per harness across Claude Code, Codex, Cursor, Gemini CLI and more. Skills trigger by context and are enforced by instructions. | **Aggregated through flow-kit** (idea source, partial overlap). Discipline lives in skill text and relies on model compliance; flow-comet machine-checks the same discipline. |
|
|
124
|
+
| **comet** (rpamis) | Resumable long-running task workflow and skill platform: a five-stage state machine, stage guards, hook write-interception. `/comet` routes from config and defaults to its Native branch. | **Early mechanism reference, now decoupled.** The hook-injection shape and script-owned state came from here; the naming was decoupled and state does not interoperate. Only its Classic branch carries the OpenSpec + Superpowers lineage. |
|
|
125
|
+
| **GSD** | Spec-driven development meta-prompt and context-engineering workflow: milestones → phases → plans, a fresh context window per agent with scoped payloads, worktree isolation and a UAT gate. | **Aggregated through flow-kit** (idea source, same lane). Fresh-context execution and stage gates align; routing stays prompt-driven. |
|
|
126
|
+
| **spec-kit** (GitHub) | SDD toolkit: Specify → Plan → Tasks → Implement → Converge. Each stage feeds markdown artifacts to the next, with order ids, `[P]` parallel markers and file paths in the task block. | **Aggregated through flow-kit** (idea source, same lane). That task-block shape is what flow-kit's TASK template inherited; stage transitions are not enforced. |
|
|
127
|
+
| **claude-task-master** | AI-driven task management over MCP and a CLI: PRD parsing → task breakdown → dependency graph → next-task orchestration. Distributed under MIT with Commons Clause. | **Aggregated through flow-kit** (complement). Covers the task layer only: no stage gates, no artifact validation, no write permissions. |
|
|
128
|
+
| **brooks-lint** (hyhmrright) | Third-party review engine grounded in twelve classic engineering books: 6 production and 6 test decay risks, findings cited as Symptom → Source → Consequence → Remedy, a 0–100 health score and six modes. | **Optional integration (MIT, not a dependency).** Where installed, five of its six commands back the self-check and review rounds; absent, the workflow degrades along a declared fallback chain. |
|
|
146
129
|
|
|
147
|
-
|
|
130
|
+
**Fit**: flow-comet is built for long-running, multi-session development changes. The contract is the same on all three platforms — write permission, commit isolation, verification isolation and integration discipline — while the depth of testing differs per platform, and the per-platform coverage is stated in [Core Mechanisms](docs/MECHANISM.md#parallel-delegation). It is not a general CI/CD or project-management tool; other platforms (Gemini / Cursor) are not guaranteed.
|
|
148
131
|
|
|
149
|
-
|
|
132
|
+
## Recommended: brooks-lint
|
|
150
133
|
|
|
151
|
-
|
|
134
|
+
The quality checks are grounded in the decay-risk framework of [brooks-lint](https://github.com/hyhmrright/brooks-lint), a third-party (MIT) review engine that diagnoses code against twelve classic engineering books. Where it is installed, the per-task self-check, the review node's code-quality round and the test-quality check run through it, and the `health` side command folds its result into its report; where it is not, the workflow still completes along a declared fallback chain and says so. It is not a dependency and nothing needs configuring on the flow-comet side; its installer covers more platforms than this project does, with a different depth of verification per platform — the details are in [Installation](docs/INSTALLATION.md).
|
|
152
135
|
|
|
153
136
|
## Relationship to the upstream project
|
|
154
137
|
|
|
@@ -173,13 +156,13 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
173
156
|
|
|
174
157
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
175
158
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
176
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
159
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 325 SCENARIOS PASSED`
|
|
177
160
|
4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
|
|
178
161
|
|
|
179
|
-
CI enforces the repository conventions automatically on every PR and push
|
|
162
|
+
CI enforces the repository conventions automatically on every PR and push: regression, installer reproducibility, workflow and bilingual-mirror quality, PR discipline, version consistency, and dead links. Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
|
|
180
163
|
|
|
181
164
|
## License
|
|
182
165
|
|
|
183
166
|
[MIT](LICENSE) © 2026 baobaolaodie
|
|
184
167
|
|
|
185
|
-
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT)
|
|
168
|
+
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT). Its mechanism shapes were borrowed from [Comet](https://github.com/rpamis/comet) (MIT), which it does not depend on.
|
package/package.json
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-comet",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.4",
|
|
4
4
|
"description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
7
7
|
".flow-comet/skills",
|
|
8
8
|
".flow-comet/rules",
|
|
9
9
|
"scripts/prepare-env.mjs",
|
|
10
|
-
"scripts/dsh-bridge.mjs"
|
|
10
|
+
"scripts/dsh-bridge.mjs",
|
|
11
|
+
"scripts/lib"
|
|
11
12
|
],
|
|
12
13
|
"bin": {
|
|
13
14
|
"fcomet": "scripts/prepare-env.mjs",
|
package/scripts/dsh-bridge.mjs
CHANGED
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
// 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
|
|
39
39
|
// ESM 模块导出 { name, apply },ctx 由 dsh 注入。
|
|
40
40
|
//
|
|
41
|
-
// BRIDGE_VERSION: 1.6.
|
|
41
|
+
// BRIDGE_VERSION: 1.6.4
|
|
42
42
|
|
|
43
43
|
import { spawn } from 'node:child_process';
|
|
44
44
|
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
@@ -50,7 +50,7 @@ import path from 'node:path';
|
|
|
50
50
|
// 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
|
|
51
51
|
// bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
|
|
52
52
|
export const name = 'dsh-flow-comet-bridge';
|
|
53
|
-
export const version = '1.6.
|
|
53
|
+
export const version = '1.6.4';
|
|
54
54
|
|
|
55
55
|
// guard 在项目内的相对路径常量(随 skill 包分发)。
|
|
56
56
|
const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* installer-cleanup.mjs — 生成物镜像目录的定向清理(升级路径残留)
|
|
3
|
+
*
|
|
4
|
+
* 为什么清理独立成模块:判据只有一条——「权威源同一相对路径上不存在同类型条目」,而删除面
|
|
5
|
+
* 必须与本次整树复制的目标根严格对应。每一条 fail-closed(镜像根是链接不跟随 / 真实路径越出
|
|
6
|
+
* 项目根不删 / 符号链接不跟随 / 类型冲突不删 / 清理后仍非空不删)都是**不可放宽**的安全边界:
|
|
7
|
+
* 放宽任何一条,删除动作就可能落到项目之外、或落到用户自有文件上。把它与入口的 CLI / 编排
|
|
8
|
+
* 分开,是为了让「哪些路径允许删」只有一处、可单独审查与测试。
|
|
9
|
+
*
|
|
10
|
+
* 依赖方向:本模块依赖 installer-migrate 的探测原语(lstatIfExists / readdirIfExists——
|
|
11
|
+
* 「该路径确实不存在」的单一判定);反向依赖不存在。
|
|
12
|
+
*/
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
|
|
16
|
+
import { lstatIfExists, readdirIfExists } from './installer-migrate.mjs';
|
|
17
|
+
|
|
18
|
+
// ---------- 生成物镜像目录的定向清理(升级路径残留) ----------
|
|
19
|
+
//
|
|
20
|
+
// 缺陷形态(实测):copyTree 只覆盖、不删除 ⇒ 权威源里已删除或改名的文件在已有副本里永久残留。
|
|
21
|
+
// 一次改名 + 一次移出即可在三平台副本各留 8 条残留,且残留会让安装副本跑自身回归套件报
|
|
22
|
+
// 308/309(失败项的失败信息逐条指向残留文件),而权威源同一命令 309/309——落差纯由残留造成。
|
|
23
|
+
//
|
|
24
|
+
// 镜像白名单(唯一允许删除的路径集合,逐条由本次生成动作定义):本次真实 copyTree 的目标根
|
|
25
|
+
// `<skillRoot>/<name>`,其中 <name> ∈ 权威源 `skills/` 下的 `flow-comet*` 目录清单。
|
|
26
|
+
// 命名空间(flow-comet* 前缀)与安装位置(平台技能根)共同构成归属判据;白名单之外的一切路径
|
|
27
|
+
// **永不触碰**。两条 fail-closed 边界(不删,但必须可见):
|
|
28
|
+
// · 整个技能目录不在权威源清单里(`<skillRoot>/flow-comet-fork` 一类):安装器没有生成清单,
|
|
29
|
+
// 用户自建的同命名空间目录与「权威源已移除的技能」在结构上不可区分 ⇒ 归属不可判定,保留;
|
|
30
|
+
// 该形态由显式 `--purge` 处置。
|
|
31
|
+
// · `.claude/rules`(同为 copyTree 目标):路径不含命名空间,无法与用户自有规则文件区分 ⇒
|
|
32
|
+
// 不纳入删除面(同上,`--purge` 处置)。
|
|
33
|
+
//
|
|
34
|
+
// 删除判据只有一条:**权威源同一相对路径上不存在同类型条目**。fail-closed 情形逐条打印、绝不静默:
|
|
35
|
+
// · **镜像根自身**是符号链接/junction(不跟随、不删除——条目层检查拦不住根级穿越:根为链接时
|
|
36
|
+
// `readdirSync` 会跟随进链接目标,删除动作落在**项目之外**,而播报打印的是项目内的表象路径);
|
|
37
|
+
// · **镜像根的真实路径越出目标项目根**(realpath 包含性判据——根或其任一祖先段为链接时,
|
|
38
|
+
// 词法路径仍显示在项目内,只有解析后才能证否;无法证明「在项目内」一律不删);
|
|
39
|
+
// · 条目是符号链接(不跟随、不删除——防穿越到目标项目之外);
|
|
40
|
+
// · 权威源同路径在场但类型不同(文件 ↔ 目录):归属不可判定,留给复制阶段的既有语义;
|
|
41
|
+
// · 目录清理后仍非空(其中含非残留内容 = 用户文件)→ 只删残留子孙,目录本身保留。
|
|
42
|
+
// 幂等:重复运行零残留可删 ⇒ 零输出、零报错;删除动作逐条打印(输出可核对)。
|
|
43
|
+
/**
|
|
44
|
+
* realpath 解析:返回真实路径,**解析不出即 null**(路径不存在 / 悬空链接 / 权限或 IO 故障一视同仁)。
|
|
45
|
+
* 与 lstatIfExists「访问类故障原样抛出」的取舍不同——本函数只服务**删除前的包含性判据**,
|
|
46
|
+
* 调用方约定为 fail-closed(null ⇒ 不删并打印原因):解析不出就**证明不了**在项目内,
|
|
47
|
+
* 此时中止安装比静默放行危险,而静默放行又比不删危险。
|
|
48
|
+
* 优先 `realpathSync.native`:Windows 上 libuv 实现不展开 8.3 短名(实测 `LONGYI~1` 形态),
|
|
49
|
+
* 而词法形态不同的两侧直接比较会把项目内路径误判为越界——本仓既有同判据(dsh-bridge 的
|
|
50
|
+
* 包含性检查)已登记该平台事实,此处沿用同一取值口径(失败方向仍是 fail-closed:误判 = 不删)。
|
|
51
|
+
*/
|
|
52
|
+
function realpathOrNull(target) {
|
|
53
|
+
try {
|
|
54
|
+
return fs.realpathSync.native(target);
|
|
55
|
+
} catch {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* 真实路径包含性:`target` 解析后的真实路径是否仍在 `root` 解析后的真实路径之内。
|
|
62
|
+
* 两侧都先 realpath——根或祖先段是链接时词法路径会骗人(Windows 8.3 短名 / 平台临时目录链接同理)。
|
|
63
|
+
* 任一解析失败 ⇒ false(fail-closed);`path.relative` 的 `..` 前缀与绝对路径都判越界。
|
|
64
|
+
*/
|
|
65
|
+
function isRealPathInside(target, root) {
|
|
66
|
+
const targetReal = realpathOrNull(target);
|
|
67
|
+
const rootReal = realpathOrNull(root);
|
|
68
|
+
if (targetReal === null || rootReal === null) return false;
|
|
69
|
+
const rel = path.relative(rootReal, targetReal);
|
|
70
|
+
return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function pruneMirrorEntries(srcRoot, dstRoot, report, projectRoot) {
|
|
74
|
+
// 根级 fail-closed(**进入递归/枚举之前**):镜像根自身是链接 ⇒ 不跟随;真实路径越出目标项目根
|
|
75
|
+
// ⇒ 不删。条目层的 entry.isSymbolicLink() 只覆盖根以下的条目,拦不住根级的符号链接/junction。
|
|
76
|
+
const rootStat = lstatIfExists(dstRoot);
|
|
77
|
+
if (rootStat === null) return; // 镜像根不在场(首次安装)——无残留可清
|
|
78
|
+
if (rootStat.isSymbolicLink()) {
|
|
79
|
+
report.skipped.push(`${dstRoot}(镜像根是符号链接/junction——不跟随、不删除,防穿越到目标项目之外)`);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
if (!isRealPathInside(dstRoot, projectRoot)) {
|
|
83
|
+
report.skipped.push(`${dstRoot}(真实路径 ${realpathOrNull(dstRoot) || '无法解析'} 越出目标项目根 ${realpathOrNull(projectRoot) || '无法解析'}——归属不可判定,不删)`);
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const entries = readdirIfExists(dstRoot);
|
|
87
|
+
if (entries === null) return; // TOCTOU:lstat 后、枚举前被移走——无残留可清(判定同 lstatIfExists 口径)
|
|
88
|
+
for (const entry of entries) {
|
|
89
|
+
const srcPath = path.join(srcRoot, entry.name);
|
|
90
|
+
const dstPath = path.join(dstRoot, entry.name);
|
|
91
|
+
if (entry.isSymbolicLink()) {
|
|
92
|
+
report.skipped.push(`${dstPath}(符号链接——不跟随、不删除)`);
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
const srcStat = lstatIfExists(srcPath);
|
|
96
|
+
const isDir = entry.isDirectory();
|
|
97
|
+
if (srcStat && isDir === srcStat.isDirectory()) {
|
|
98
|
+
// 权威源在场且同类型:目录递归下探,文件保留(内容由 copyTree 覆盖)
|
|
99
|
+
if (isDir) pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
if (srcStat) {
|
|
103
|
+
report.skipped.push(`${dstPath}(权威源同路径类型不同——归属不可判定,不删)`);
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
if (isDir) {
|
|
107
|
+
// 权威源无该目录 ⇒ 其中全部条目都属残留:先递归清空,再连同目录本身移除
|
|
108
|
+
pruneMirrorEntries(srcPath, dstPath, report, projectRoot);
|
|
109
|
+
const left = readdirIfExists(dstPath);
|
|
110
|
+
if (left === null) continue; // 递归中已被移除(与其祖先同批)
|
|
111
|
+
if (left.length > 0) {
|
|
112
|
+
report.skipped.push(`${dstPath}(清理后仍非空——保留其中非残留内容)`);
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
fs.rmdirSync(dstPath);
|
|
116
|
+
report.removed.push(dstPath);
|
|
117
|
+
continue;
|
|
118
|
+
}
|
|
119
|
+
if (entry.isFile()) {
|
|
120
|
+
fs.rmSync(dstPath, { force: true });
|
|
121
|
+
report.removed.push(dstPath);
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
report.skipped.push(`${dstPath}(既非普通文件也非目录——不删)`);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* 平台镜像清理总入口:对本次安装的每个技能镜像根(`<skillRoot>/<name>` ← `skills/<name>`)
|
|
130
|
+
* 做定向清理,逐条打印结果。无残留时零输出(幂等可核对:重复运行不再打印清理项);
|
|
131
|
+
* fail-closed 保留项以警告逐条打印——保留是**可见的决定**,不是静默跳过。
|
|
132
|
+
* `projectRoot` = 本次安装的目标项目根:**删除面的包含性上界**(镜像根 realpath 必须落在其内,
|
|
133
|
+
* 见 pruneMirrorEntries 的根级判据)。
|
|
134
|
+
*/
|
|
135
|
+
export function cleanStaleMirrorEntries(skillsSrc, skillRoot, skillNames, projectRoot) {
|
|
136
|
+
const report = { removed: [], skipped: [] };
|
|
137
|
+
for (const name of skillNames) {
|
|
138
|
+
pruneMirrorEntries(path.join(skillsSrc, name), path.join(skillRoot, name), report, projectRoot);
|
|
139
|
+
}
|
|
140
|
+
if (report.removed.length > 0) {
|
|
141
|
+
console.log(`[flow-comet] 镜像清理: 已删除 ${report.removed.length} 项(权威源已不存在的生成物)`);
|
|
142
|
+
for (const p of report.removed) {
|
|
143
|
+
console.log(` - 已删除: ${p}`);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
if (report.skipped.length > 0) {
|
|
147
|
+
console.warn(`[flow-comet] 警告: 镜像清理保留 ${report.skipped.length} 项(fail-closed——无法判定归属即不删):`);
|
|
148
|
+
for (const p of report.skipped) {
|
|
149
|
+
console.warn(` - 保留: ${p}`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* installer-flowkit.mjs — flow-kit 上游快照获取链路(prepare-env 的逻辑层模块)
|
|
3
|
+
*
|
|
4
|
+
* 非破坏是这条链路的全部要点:已存在的目录一律只读不动(只读 HEAD、只读 origin 判定归属),
|
|
5
|
+
* 归属不可确认即跳过并给手动指引;clone / checkout 的失败**不抛错**——外网故障不得绑架安装器
|
|
6
|
+
* 的其余职责(技能树、规则、hook 注入照常完成,进程照常 exit 0)。把这条链路独立成模块,是为
|
|
7
|
+
* 了让「什么情况下会改动用户目录」只有一个落点可审——答案必须是「只有目标不存在时」。
|
|
8
|
+
*
|
|
9
|
+
* 依赖方向:本模块是叶子(只用 node 内置模块与 git 命令)。
|
|
10
|
+
*/
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
import { execFileSync } from 'node:child_process';
|
|
14
|
+
|
|
15
|
+
// ---------- flow-kit 获取链路(ADR-008 / DESIGN D1~D6——平台无关,main 平台循环前调用一次) ----------
|
|
16
|
+
|
|
17
|
+
// 锁定点常量(D2):上游 github.com/rihebty/flow-kit 实测无 tag,commit 是唯一精确锚;
|
|
18
|
+
// 升级锁定点 = 显式修改此常量并记 CHANGELOG,不做自动跟随(2026-08-23 ls-remote 实测 == 上游 HEAD)。
|
|
19
|
+
const FLOW_KIT_UPSTREAM_URL = 'https://github.com/rihebty/flow-kit.git';
|
|
20
|
+
const FLOW_KIT_LOCKED_COMMIT = '9b5dda7206ae841230f118348d660ad8d0ae2830';
|
|
21
|
+
// git 网络调用统一超时(D5——沿用 resolveInstalledVersion 的 execFileSync timeout 先例风格)
|
|
22
|
+
const FLOW_KIT_GIT_TIMEOUT_MS = 60000;
|
|
23
|
+
// 摘要展示用短 sha 长度(git 短哈希惯例——单一来源,clone 成功/已有/指引三处引用)
|
|
24
|
+
const FLOW_KIT_SHORT_SHA_LEN = 7;
|
|
25
|
+
|
|
26
|
+
/** 提取 git 调用失败信息首行(execFileSync 错误消息含多行 stderr——警告只留首行) */
|
|
27
|
+
function gitErrorFirstLine(err) {
|
|
28
|
+
return String(err && err.message ? err.message : err).split('\n')[0].trim();
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** 手动获取指引(clone/checkout 失败或目录非上游克隆时打印——含上游 URL 与目标路径;不抛错) */
|
|
32
|
+
function printFlowKitManualGuide(target) {
|
|
33
|
+
const flowKitDir = path.join(target, 'flow-kit');
|
|
34
|
+
console.warn(`[flow-comet] 手动获取指引: git clone ${FLOW_KIT_UPSTREAM_URL} "${flowKitDir}"`);
|
|
35
|
+
console.warn(`[flow-comet] 然后锁定快照: git -C "${flowKitDir}" checkout --detach ${FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN)}`);
|
|
36
|
+
console.warn('[flow-comet] 未获取 flow-kit 时技能协议引用悬空、guard 段名基准退化为内置 fallback——其余安装职责不受影响。');
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* 归属判定(D3):origin remote URL 匹配上游——本地 config 读取,无网络。
|
|
41
|
+
* 兼容 https / ssh 形态与可选 .git 后缀;读取失败视为不匹配(保守落入"非上游克隆"分支,
|
|
42
|
+
* 绝不改动用户目录)。返回 'match' | 'mismatch' | 'unreadable'。
|
|
43
|
+
*/
|
|
44
|
+
function flowKitOriginStatus(flowKitDir) {
|
|
45
|
+
try {
|
|
46
|
+
const url = execFileSync(
|
|
47
|
+
'git',
|
|
48
|
+
['-C', flowKitDir, 'config', '--get', 'remote.origin.url'],
|
|
49
|
+
{ encoding: 'utf8', timeout: FLOW_KIT_GIT_TIMEOUT_MS }
|
|
50
|
+
).trim().replace(/\.git$/i, '').replace(/\/+$/, '');
|
|
51
|
+
return /github\.com[:/]rihebty\/flow-kit$/i.test(url) ? 'match' : 'mismatch';
|
|
52
|
+
} catch {
|
|
53
|
+
return 'unreadable';
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* 确保 <target>/flow-kit/ 就位(ADR-008 / DESIGN D1~D6——L-008 非破坏哲学:已存在路径一律只读不动):
|
|
59
|
+
* 路径 1 目标不存在 → execFileSync('git',…) 数组参数形态 clone 上游后 detached checkout 到锁定 commit;
|
|
60
|
+
* 路径 2 已存在且 .git 存在且 origin 匹配上游 → 只读 rev-parse HEAD 并输出与锁定点差异影响,绝不改动;
|
|
61
|
+
* 路径 3 已存在但不满足归属判定 → 摘要"非上游克隆,已跳过"+ 手动指引,不改动;
|
|
62
|
+
* 路径 4 clone/checkout 任一失败 → 警告 + 手动获取指引,**不抛错**(D5——外网故障不得绑架安装器
|
|
63
|
+
* 其余职责,进程照常 exit 0);各平台 purge 清单永不包含 flow-kit(D6,见 PLATFORMS 表头注释)。
|
|
64
|
+
*/
|
|
65
|
+
export function ensureFlowKit(target) {
|
|
66
|
+
const flowKitDir = path.join(target, 'flow-kit');
|
|
67
|
+
const shortLock = FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN);
|
|
68
|
+
if (!fs.existsSync(flowKitDir)) {
|
|
69
|
+
// 路径 1:目标缺失 → clone + detached checkout 到锁定 commit(D1/D2)
|
|
70
|
+
try {
|
|
71
|
+
execFileSync('git', ['clone', FLOW_KIT_UPSTREAM_URL, flowKitDir], {
|
|
72
|
+
encoding: 'utf8',
|
|
73
|
+
timeout: FLOW_KIT_GIT_TIMEOUT_MS,
|
|
74
|
+
});
|
|
75
|
+
execFileSync('git', ['-C', flowKitDir, 'checkout', '--detach', FLOW_KIT_LOCKED_COMMIT], {
|
|
76
|
+
encoding: 'utf8',
|
|
77
|
+
timeout: FLOW_KIT_GIT_TIMEOUT_MS,
|
|
78
|
+
});
|
|
79
|
+
console.log(`[flow-comet] 已获取 flow-kit(锁定 ${shortLock})`);
|
|
80
|
+
} catch (err) {
|
|
81
|
+
// 路径 4:clone/checkout 任一失败 → WARN + 手动指引,不抛错
|
|
82
|
+
console.warn(`[flow-comet] 警告: flow-kit 自动获取失败(${gitErrorFirstLine(err)})`);
|
|
83
|
+
printFlowKitManualGuide(target);
|
|
84
|
+
}
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
// 目录已存在 → 归属判定(D3:.git 存在 且 origin remote 匹配上游)
|
|
88
|
+
const hasDotGit = fs.existsSync(path.join(flowKitDir, '.git'));
|
|
89
|
+
const originStatus = hasDotGit ? flowKitOriginStatus(flowKitDir) : 'mismatch';
|
|
90
|
+
if (originStatus !== 'match') {
|
|
91
|
+
// 路径 3:同名非克隆目录(或 remote 无法确认归属)→ 跳过 + 指引,绝不改动
|
|
92
|
+
if (originStatus === 'unreadable') {
|
|
93
|
+
console.warn('[flow-comet] 警告: flow-kit 目录存在且含 .git,但 origin remote 读取失败——无法确认归属');
|
|
94
|
+
}
|
|
95
|
+
console.log('[flow-comet] 目录存在但非上游克隆,已跳过');
|
|
96
|
+
printFlowKitManualGuide(target);
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
// 路径 2:上游克隆 → 只读检测并输出差异影响(D4——绝不 fetch/checkout 改动用户克隆)
|
|
100
|
+
try {
|
|
101
|
+
const head = execFileSync('git', ['-C', flowKitDir, 'rev-parse', 'HEAD'], {
|
|
102
|
+
encoding: 'utf8',
|
|
103
|
+
timeout: FLOW_KIT_GIT_TIMEOUT_MS,
|
|
104
|
+
}).trim();
|
|
105
|
+
const shortHead = head.slice(0, FLOW_KIT_SHORT_SHA_LEN);
|
|
106
|
+
console.log(`[flow-comet] 已有 flow-kit(HEAD=${shortHead},推荐锁定点=${shortLock})`);
|
|
107
|
+
if (head === FLOW_KIT_LOCKED_COMMIT) {
|
|
108
|
+
console.log('[flow-comet] 当前 HEAD 与推荐锁定点一致。');
|
|
109
|
+
} else {
|
|
110
|
+
console.warn(
|
|
111
|
+
`[flow-comet] 差异影响: 当前 HEAD 与推荐锁定点不一致——guard 段名基准与协议引用可能偏离安装器锁定内容` +
|
|
112
|
+
`(安装器绝不改动已有克隆;如需对齐请手动执行 git -C "${flowKitDir}" fetch 后 checkout --detach ${shortLock})`
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
} catch (err) {
|
|
116
|
+
// HEAD 只读失败同样不改动、不中断安装(保守降级为警告)
|
|
117
|
+
console.warn(`[flow-comet] 警告: flow-kit HEAD 读取失败(${gitErrorFirstLine(err)}),已跳过比对`);
|
|
118
|
+
}
|
|
119
|
+
}
|