flow-comet 1.6.3 → 1.6.5

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 (106) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +21 -3
  3. package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
  4. package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
  5. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +8 -2
  6. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  7. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +180 -6
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +69 -18878
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +29 -5
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1053 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
  15. package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
  16. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
  17. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
  18. package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
  19. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +817 -0
  20. package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
  21. package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
  22. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
  23. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
  24. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +618 -0
  25. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  26. package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +756 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1235 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +384 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +714 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +204 -0
  35. package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
  36. package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +179 -0
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +714 -0
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +123 -0
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
  46. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
  47. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +249 -0
  48. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1505 -0
  49. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
  51. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1248 -0
  52. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
  53. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2493 -0
  54. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +214 -2
  55. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +976 -0
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1398 -0
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1367 -0
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1492 -0
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
  69. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  70. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
  71. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +59 -7559
  72. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
  73. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +223 -2476
  74. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
  75. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
  76. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  77. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  78. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  79. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  80. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  81. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  82. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  83. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  84. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  85. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  86. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  87. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  88. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  89. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  90. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  91. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  92. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  93. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  94. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  95. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  96. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  97. package/README.md +52 -69
  98. package/package.json +3 -2
  99. package/scripts/dsh-bridge.mjs +2 -2
  100. package/scripts/lib/installer-cleanup.mjs +152 -0
  101. package/scripts/lib/installer-flowkit.mjs +159 -0
  102. package/scripts/lib/installer-hooks.mjs +363 -0
  103. package/scripts/lib/installer-loader.mjs +220 -0
  104. package/scripts/lib/installer-migrate.mjs +236 -0
  105. package/scripts/lib/installer-platforms.mjs +314 -0
  106. package/scripts/prepare-env.mjs +21 -1313
@@ -0,0 +1,220 @@
1
+ /**
2
+ * installer-loader.mjs — 桥接 loader 的版本比对与托管块注入(prepare-env 的逻辑层模块)
3
+ *
4
+ * 为什么版本比对与 cordis patch 同处一个模块:两者都作用于「$DSH_HOME 全局挂载的桥接 loader」
5
+ * 这一条生命周期链——loader 覆盖前先报版本方向(首次安装 / 升级 / 降级 / 版本一致),再按同一个
6
+ * loader 路径生成 cordis.patch.yml 的托管块;而托管块的插入与移除又共用同一幂等替换边界
7
+ * (stripManagedBlock,AGENTS.md 托管区亦复用它)。拆成两处会让「loader 路径 → patch 引用」的
8
+ * 对应关系失去单一落点,两处路径推导一旦漂移,patch 会静默指向不存在的文件。
9
+ *
10
+ * 依赖方向:本模块是叶子(只用 node 内置模块);installer-hooks 与 installer-platforms 依赖它。
11
+ */
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { pathToFileURL } from 'node:url';
15
+
16
+ // $DSH_HOME/cordis.patch.yml 托管块标记(dsh 平台 home patch 注入——幂等替换边界;
17
+ // 参照本机既有惯例:# --- dsh-skin managed --- ... # --- end dsh-skin managed ---)
18
+ const MANAGED_CORDIS_START = '# --- flow-comet managed ---';
19
+ const MANAGED_CORDIS_END = '# --- end flow-comet managed ---';
20
+ // ---------- loader 覆盖前版本比对(全局挂载的桥接 loader 生命周期治理) ----------
21
+
22
+ // 版本戳锚点正则(标记行格式契约:独立整行、行首无缩进、冒号后恰一个空格、行尾无其它字符;
23
+ // 格式禁动——安装器与 bridge-check 双侧提取以此为准;技能包自包含,语义同值复刻不跨模块 import)。
24
+ const BRIDGE_VERSION_RE = /^\/\/ BRIDGE_VERSION: ([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$/m;
25
+
26
+ /**
27
+ * 从 loader 文件提取版本戳(同一锚点正则)。返回 { ok:true, version };
28
+ * 文件缺失/读取失败/无标记行 → { ok:false, reason }(调用方告警兜底,不抛错)。
29
+ */
30
+ function extractBridgeVersion(loaderPath) {
31
+ let text;
32
+ try {
33
+ text = fs.readFileSync(loaderPath, 'utf8');
34
+ } catch {
35
+ return { ok: false, reason: '文件读取失败' };
36
+ }
37
+ const match = BRIDGE_VERSION_RE.exec(text);
38
+ if (match) return { ok: true, version: match[1] };
39
+ // 标记行存在但形态非法(区别于「无标记行」)——仍走既有警告路径,原因精确可诊断
40
+ const loose = /^\/\/ BRIDGE_VERSION: (.*)$/m.exec(text);
41
+ return loose
42
+ ? { ok: false, reason: '版本戳形态非法(非语义化版本: ' + loose[1] + ')' }
43
+ : { ok: false, reason: '未提取到版本戳标记行' };
44
+ }
45
+
46
+ /**
47
+ * 语义化版本数值序比较(覆盖前判定方向):major.minor.patch 逐段按数值比较
48
+ * (如 1.10.0 > 1.6.0——非字典序);核心版本相等时按语义化版本规则处理预发布后缀
49
+ * (如 1.6.0-alpha.1 < 1.6.0)。返回 -1 / 0 / 1。
50
+ */
51
+ function compareBridgeVersions(a, b) {
52
+ const parse = (v) => {
53
+ const text = String(v);
54
+ const dash = text.indexOf('-');
55
+ const core = (dash === -1 ? text : text.slice(0, dash)).split('.').map((seg) => parseInt(seg, 10));
56
+ return { core, pre: dash === -1 ? null : text.slice(dash + 1) };
57
+ };
58
+ const av = parse(a);
59
+ const bv = parse(b);
60
+ const coreLen = Math.max(av.core.length, bv.core.length);
61
+ for (let i = 0; i < coreLen; i++) {
62
+ const x = av.core[i] ?? 0;
63
+ const y = bv.core[i] ?? 0;
64
+ if (x !== y) return x < y ? -1 : 1;
65
+ }
66
+ const ap = av.pre !== null;
67
+ const bp = bv.pre !== null;
68
+ if (ap !== bp) return ap ? -1 : 1; // 预发布 < 正式版
69
+ if (!ap) return 0;
70
+ const ai = av.pre.split('.');
71
+ const bi = bv.pre.split('.');
72
+ const preLen = Math.max(ai.length, bi.length);
73
+ for (let i = 0; i < preLen; i++) {
74
+ if (i >= ai.length) return -1; // 更短标识符列表是更长列表的前缀 → 更小
75
+ if (i >= bi.length) return 1;
76
+ const x = ai[i];
77
+ const y = bi[i];
78
+ if (x === y) continue;
79
+ const xn = /^\d+$/.test(x) ? parseInt(x, 10) : null;
80
+ const yn = /^\d+$/.test(y) ? parseInt(y, 10) : null;
81
+ if (xn !== null && yn !== null) return xn < yn ? -1 : 1;
82
+ if (xn !== null) return -1; // 数字标识符 < 字母标识符(语义化版本规则)
83
+ if (yn !== null) return 1;
84
+ return x < y ? -1 : 1;
85
+ }
86
+ return 0;
87
+ }
88
+
89
+ /**
90
+ * 覆盖前版本比对明示:从权威源 loader 与已装 loader 各提取版本戳,按数值序输出
91
+ * 首次安装 / 升级 A→B / 降级 A→B / 版本一致 四类结论之一(人读、带 [flow-comet] 前缀)。
92
+ * 任一侧提取失败(文件缺失/无标记行)→ 告警并跳过比对——不抛错、不中断安装;
93
+ * 覆盖动作(copyFileSync)由调用方照常执行,幂等语义不变。
94
+ */
95
+ export function reportLoaderVersionTransition(loaderSrc, loaderDst) {
96
+ if (!fs.existsSync(loaderDst)) {
97
+ console.log('[flow-comet] 桥接 loader 首次安装($DSH_HOME/plugins 无已装 loader)');
98
+ return;
99
+ }
100
+ const src = extractBridgeVersion(loaderSrc);
101
+ const installed = extractBridgeVersion(loaderDst);
102
+ if (!src.ok || !installed.ok) {
103
+ const failedSide = !src.ok ? '权威源 loader' : '已装 loader';
104
+ const reason = !src.ok ? src.reason : installed.reason;
105
+ console.warn(
106
+ `[flow-comet] 警告: ${failedSide} 版本戳提取失败(${reason})——跳过版本比对,继续覆盖安装`
107
+ );
108
+ return;
109
+ }
110
+ const a = installed.version;
111
+ const b = src.version;
112
+ const cmp = compareBridgeVersions(a, b);
113
+ if (cmp < 0) {
114
+ console.log(`[flow-comet] 桥接 loader 升级 ${a} → ${b}`);
115
+ } else if (cmp > 0) {
116
+ console.log(`[flow-comet] 桥接 loader 降级 ${a} → ${b}`);
117
+ } else {
118
+ console.log(`[flow-comet] 桥接 loader 版本一致(${a})`);
119
+ }
120
+ }
121
+
122
+ /**
123
+ * 极简 YAML 形状校验(零依赖——用于 cordis.patch.yml 的 fail-safe 判定):
124
+ * 文件须为顶层 YAML 列表形态(行形态:注释 / 空行 / 顶层 `- 条目` / 条目下缩进内容 / 文档分隔符),
125
+ * 无法识别(二进制、顶层 map 形态等)→ 返回 false——调用方据此 fail-safe 不覆盖(保护用户配置)。
126
+ */
127
+ function isSimpleYamlText(text) {
128
+ return text.split(/\r?\n/).every((line) => {
129
+ const t = line.trimEnd();
130
+ if (t.trim() === '') return true; // 空行
131
+ if (/^\s*#/.test(t)) return true; // 注释
132
+ if (/^\s*---\s*$/.test(t)) return true; // 文档分隔符
133
+ if (/^\s*-\s+\S/.test(t)) return true; // 顶层列表条目
134
+ if (/^\s+\S/.test(t)) return true; // 条目下缩进内容(键值/嵌套列表;YAML 允许 1 空格缩进)
135
+ return false;
136
+ });
137
+ }
138
+
139
+ /**
140
+ * 注入桥接 loader 托管块到 $DSH_HOME/cordis.patch.yml(dsh 平台 home patch——
141
+ * 读-合并-写,L-008 非破坏):
142
+ * 读现有 cordis.patch.yml(缺失 → 空)→ 移除旧托管块(幂等)→ 托管块内联 loader 的
143
+ * file:// 引用(**insert 形态**:无 id 的顶层 `- insert:` 条目内嵌插件行
144
+ * `- id: dsh-flow-comet-bridge` + `name: 'file:///<abs 路径>'`——dsh-app-boot 的
145
+ * applyEntryPatches 语义是 id-targeted patch(id 必须已存在于配置树);无 id 的
146
+ * `insert:` 顶层条目才执行 data.push 追加新插件行,是 home patch 新增插件的唯一正确形态;
147
+ * 旧的 `- id: ... + name:` patch 形态对不存在的 id 报 entry not found 并跳过——
148
+ * loader 从不加载 → 拦截整链静默失效)
149
+ * → 保留托管块外既有块(dsh-skin 等)→ 写回。
150
+ * fail-safe:文件存在但内容无法识别为 YAML → 抛错退出不覆盖(参照 injectSettingsHook 模式)。
151
+ */
152
+ export function injectDshCordisPatch(dshHome, loaderPath) {
153
+ const patchPath = path.join(dshHome, 'cordis.patch.yml');
154
+ let existing = '';
155
+ let fileExists = false;
156
+ try {
157
+ existing = fs.readFileSync(patchPath, 'utf8');
158
+ fileExists = true;
159
+ } catch { /* 文件缺失 = 首次安装 */ }
160
+ if (fileExists && !isSimpleYamlText(existing)) {
161
+ throw new Error(
162
+ `cordis.patch.yml 已存在但内容无法解析为 YAML(${patchPath})——为保护用户配置,中止注入。` +
163
+ `请修复该文件(顶层 YAML 列表形态)后重试,或手动添加桥接 loader 引用。`
164
+ );
165
+ }
166
+ const stripped = stripManagedBlock(existing, MANAGED_CORDIS_START, MANAGED_CORDIS_END);
167
+ const fileUrl = pathToFileURL(loaderPath).href;
168
+ const managedBlock =
169
+ MANAGED_CORDIS_START + '\n' +
170
+ '- insert:\n' +
171
+ ' - id: dsh-flow-comet-bridge\n' +
172
+ ` name: '${fileUrl.replace(/'/g, "''")}'\n` +
173
+ MANAGED_CORDIS_END + '\n';
174
+ const merged = (stripped.trim() ? stripped.trim() + '\n\n' : '') + managedBlock;
175
+ fs.mkdirSync(dshHome, { recursive: true });
176
+ fs.writeFileSync(patchPath, merged, 'utf8');
177
+ return merged;
178
+ }
179
+
180
+ /**
181
+ * 移除 $DSH_HOME/cordis.patch.yml 中的托管块(purge 语义:移除而非注入——保留 dsh-skin
182
+ * 等既有块与用户内容)。文件缺失 → 跳过;内容无法识别为 YAML → 不动(fail-safe 保护
183
+ * 用户配置)。移除后文件为空 → 删除文件本身。返回删除清单条目(供 purge 打印)。
184
+ */
185
+ export function removeDshCordisPatch(dshHome) {
186
+ const patchPath = path.join(dshHome, 'cordis.patch.yml');
187
+ const removed = [];
188
+ if (!fs.existsSync(patchPath)) return removed;
189
+ let content;
190
+ try {
191
+ content = fs.readFileSync(patchPath, 'utf8');
192
+ } catch { return removed; }
193
+ if (!content.includes(MANAGED_CORDIS_START)) return removed;
194
+ if (!isSimpleYamlText(content)) {
195
+ // 无法识别 → 不触碰(fail-safe 语义与注入一致——保护用户配置)
196
+ return removed;
197
+ }
198
+ const stripped = stripManagedBlock(content, MANAGED_CORDIS_START, MANAGED_CORDIS_END);
199
+ const trimmed = stripped.trim();
200
+ if (trimmed) {
201
+ fs.writeFileSync(patchPath, trimmed + '\n', 'utf8');
202
+ } else {
203
+ fs.rmSync(patchPath, { force: true });
204
+ }
205
+ removed.push(patchPath + '(托管块)');
206
+ return removed;
207
+ }
208
+
209
+ function escapeRegExp(value) {
210
+ return String(value).replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
211
+ }
212
+
213
+ // 移除托管块(幂等替换边界):start 标记到 end 标记(含尾随换行)之间的全部内容。
214
+ // 注入与清理共用——AGENTS.md 托管区 / cordis.patch.yml 托管块(L-008 读-合并-写)。
215
+ export function stripManagedBlock(content, startMarker, endMarker) {
216
+ return content.replace(
217
+ new RegExp(escapeRegExp(startMarker) + '[\\s\\S]*?' + escapeRegExp(endMarker) + '\\n?'),
218
+ ''
219
+ );
220
+ }
@@ -0,0 +1,236 @@
1
+ /**
2
+ * installer-migrate.mjs — 运行时文件位置迁移 + 路径存在性探测原语(prepare-env 的逻辑层模块)
3
+ *
4
+ * 为什么这两件事同处一个模块:迁移的白名单枚举与三处调用方(迁移自身 / .gitignore 纳管 /
5
+ * 生成物镜像的定向清理)共用同一条「该路径确实不存在」判定——ENOENT 与 ENOTDIR 算不存在,
6
+ * 访问类故障(EACCES / EPERM / EIO)必须原样抛出。这条语义若在调用方各写一份必然分叉:
7
+ * 一旦把访问故障当成「文件不存在」,迁移会静默跳过(用户以为已迁移)、.gitignore 会被按
8
+ * 空内容截断覆盖——都是静默的数据丢失。故它只有一份实现(本模块导出,调用方一律 import)。
9
+ *
10
+ * 依赖方向:本模块是叶子(只依赖 node 内置模块);installer-cleanup 与 installer-hooks 依赖它。
11
+ */
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+
15
+ // ---------- 运行时文件位置迁移(旧命名空间 .comet/ → 新命名空间 .flow-comet/) ----------
16
+ //
17
+ // 【过渡性模块——有明确退役条件,不是永久耦合】
18
+ // 本模块存在的唯一理由:让已安装项目把状态文件从旧命名空间搬到新命名空间,避免破坏性变更
19
+ // 导致用户进行中的流程状态丢失。它**只在安装/升级时执行一次**,从不进入任何日常运行路径
20
+ // (写入守卫、工作流脚本、协议解析均已完全不含对旧命名空间的感知)。
21
+ //
22
+ // 因此这里的 `.comet` 字面量是**迁移源**,不是 flow-comet 的命名归属——它标记的是"要从哪里
23
+ // 搬走",而非"我们是谁"。这是任何破坏性变更都需要的过渡桥(同"改名迁移脚本必须知道旧表名")。
24
+ //
25
+ // **退役条件**(满足任一即可整体删除本模块及其常量):
26
+ // ① 下一个破坏性版本发布时——迁移公告期结束(建议至少覆盖一个完整的 minor 周期,让下游
27
+ // 项目有时间升级);
28
+ // ② 或:连续多次安装运行中迁移报告**全部为「已跳过」**(说明已知项目均已迁移完毕)。
29
+ // 判据取证:每次安装都会打印迁移明细(已迁移 / 已跳过);长期全为「已跳过」即为退役信号。
30
+ //
31
+ // 位置迁移白名单(单一来源):目标项目的 `.comet/` 是三方共占目录——flow-comet 运行时文件
32
+ // + Comet 资产(`runs/`、`config.yaml` 等)+ 用户自有文件(`*.bak-*` 等)。只有下表列出的
33
+ // 文件属 flow-comet 运行时域,其余一律原位不动(不搬迁、不删除、不改写)——整目录搬迁或
34
+ // 前缀正则匹配都会越界处置非 flow-comet 资产。新增运行时文件时必须同步本表。
35
+ const LEGACY_RUNTIME_DIR = '.comet';
36
+ export const RUNTIME_DIR = '.flow-comet';
37
+ const RUNTIME_FILE_MIGRATIONS = [
38
+ { name: 'flow-comet-state.json', validateJson: true },
39
+ ];
40
+ /**
41
+ * readdir(withFileTypes):仅「该路径确实不存在」返回 null——判定与 lstatIfExists 同口径
42
+ * (见 isMissingPathError:只有 ENOENT / ENOTDIR 算不存在,访问类故障原样抛出)。
43
+ * 供镜像清理复用:把「目录不可枚举」与「目录为空」两个分支分开,避免清理判定深嵌 try/catch。
44
+ */
45
+ export function readdirIfExists(dir) {
46
+ try {
47
+ return fs.readdirSync(dir, { withFileTypes: true });
48
+ } catch (err) {
49
+ if (isMissingPathError(err)) return null;
50
+ throw err;
51
+ }
52
+ }
53
+ /**
54
+ * 「该路径确实不存在」一类错误的单一判定(迁移探测与 gitignore 纳管共用同一判据——
55
+ * 同一语义只有一处实现,改一处即全改,不会分叉):
56
+ * - ENOENT:路径缺失;
57
+ * - ENOTDIR:路径中某一段不是目录——该路径不可能存在为文件(跨平台等价于「不存在」:
58
+ * 同一形态在 Windows 报 ENOENT、在 POSIX 报 ENOTDIR)。
59
+ * 其余错误(EACCES / EPERM / EIO 等访问类故障)**不算**「不存在」——把访问故障当成
60
+ * 「文件不存在」会让调用方按空内容继续(迁移静默跳过 / gitignore 被截断覆盖),
61
+ * 都是静默的数据丢失风险,必须原样抛出并中止。
62
+ */
63
+ export function isMissingPathError(err) {
64
+ return Boolean(err) && typeof err === 'object' && (err.code === 'ENOENT' || err.code === 'ENOTDIR');
65
+ }
66
+
67
+ /**
68
+ * lstat 探测:返回 stat 或 null(**不跟随符号链接**——isSymbolicLink() 判定依赖 lstat)。
69
+ * 只有「该路径确实不存在」一类错误返回 null(判定见 isMissingPathError);其余错误原样抛出——
70
+ * 迁移静默跳过会让安装照常继续并报告「已跳过:旧位置不存在」,用户的旧状态却永远留在旧位置
71
+ * (用户以为已迁移)。
72
+ */
73
+ export function lstatIfExists(target) {
74
+ try {
75
+ return fs.lstatSync(target);
76
+ } catch (err) {
77
+ if (isMissingPathError(err)) {
78
+ return null;
79
+ }
80
+ throw err;
81
+ }
82
+ }
83
+ /** 迁移备份文件名时间戳(ISO 串里的 `:` 与 `.` 在 Windows 文件名中非法——统一替换为 `-`)。 */
84
+ function migrationTimestamp() {
85
+ return new Date().toISOString().replace(/[:.]/g, '-');
86
+ }
87
+
88
+ /** 逐字节读回并比较;读取失败一律视为不一致(调用方按校验失败处置)。 */
89
+ function fileEqualsBytes(filePath, bytes) {
90
+ try {
91
+ return fs.readFileSync(filePath).equals(bytes);
92
+ } catch {
93
+ return false;
94
+ }
95
+ }
96
+
97
+ /**
98
+ * 迁移前置校验:旧件不存在 → 返回 null(无需迁移);命中边界情形 → 抛错中止(不返回字节)。
99
+ * 三种边界一律不静默覆盖或丢弃:
100
+ * - 旧件是符号链接 → 不跟随(防穿越到项目外),报错并给人工处置指引
101
+ * - 新旧位置并存 → 不覆盖任何一方,报错并列出两处路径供人工判断
102
+ * - 内容损坏(validateJson 条目)→ 保留原件未改动,报错并给修复指引
103
+ */
104
+ function readMigratableRuntimeFile(oldPath, newPath, entry) {
105
+ const oldStat = lstatIfExists(oldPath);
106
+ if (!oldStat) return null;
107
+ if (oldStat.isSymbolicLink()) {
108
+ let linkTarget = '(读取失败)';
109
+ try {
110
+ linkTarget = fs.readlinkSync(oldPath);
111
+ } catch {
112
+ /* 链接目标读取失败不改变处置(同样中止) */
113
+ }
114
+ throw new Error(
115
+ `${oldPath} 是符号链接(指向 ${linkTarget})——不跟随链接搬移(避免穿越到项目外)。` +
116
+ `请人工确认后处理:把真实文件复制到 ${newPath}(保留本链接),或删除该链接后重跑安装器。`
117
+ );
118
+ }
119
+ if (lstatIfExists(newPath)) {
120
+ throw new Error(
121
+ `新旧位置同时存在该运行时文件,不覆盖任何一方:\n - 旧位置: ${oldPath}\n - 新位置: ${newPath}\n` +
122
+ `请人工比对两处内容,保留正确的一份(删除或改名另一份)后重跑安装器。`
123
+ );
124
+ }
125
+ let bytes;
126
+ try {
127
+ bytes = fs.readFileSync(oldPath);
128
+ } catch (err) {
129
+ throw new Error(`${oldPath} 读取失败(${err.message})——未做任何改动,中止迁移。请检查文件权限后重跑安装器。`);
130
+ }
131
+ if (entry.validateJson) {
132
+ let parsed = null;
133
+ try {
134
+ // 校验容忍 UTF-8 BOM(与运行时判定一致:workflow-state.mjs 的 readJson 明确容忍 BOM,
135
+ // 外部写入如会话 Write 可能带 BOM)——否则运行时读得动的状态文件会被迁移判为损坏而
136
+ // 中止安装(同一份数据两处判定不一致)。strip 只作用于校验:备份与落盘始终写原始字节
137
+ // bytes,绝不改写用户数据(BOM strip 用字面形态——与 workflow-state.mjs 的 readJson 同形,
138
+ // 行为由场景 234 端到端锚定:若该字符被剥离会立即变红)。
139
+ parsed = JSON.parse(bytes.toString('utf8').replace(/^/, ''));
140
+ } catch (err) {
141
+ throw new Error(
142
+ `${oldPath} 内容不是合法 JSON(${err.message})——保留原件未改动,中止迁移。` +
143
+ `请修复该文件(或从备份恢复)后重跑安装器。`
144
+ );
145
+ }
146
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
147
+ throw new Error(`${oldPath} 顶层不是 JSON 对象——保留原件未改动,中止迁移。请修复该文件后重跑安装器。`);
148
+ }
149
+ }
150
+ return bytes;
151
+ }
152
+
153
+ /**
154
+ * 搬移落盘(写成功才删旧件):建目标目录 → 复制备份 → 逐字节校验备份 → 写新位置 →
155
+ * 回读校验新位置 → 删旧件。任一环节失败都抛错,且**旧件与备份至少保留一份**(不丢数据)。
156
+ */
157
+ function writeRuntimeFileWithBackup(oldPath, newPath, backupPath, bytes) {
158
+ const targetDir = path.dirname(newPath);
159
+ const keepNote = `旧文件完整保留于 ${oldPath}`;
160
+ try {
161
+ fs.mkdirSync(targetDir, { recursive: true });
162
+ } catch (err) {
163
+ throw new Error(
164
+ `无法建立迁移目标目录 ${targetDir}(${err.message})——${keepNote},未做任何改动。` +
165
+ `请确认该路径未被普通文件占用且可写后重跑安装器。`
166
+ );
167
+ }
168
+ try {
169
+ fs.copyFileSync(oldPath, backupPath);
170
+ } catch (err) {
171
+ throw new Error(
172
+ `生成迁移前备份失败(${backupPath}:${err.message})——${keepNote},未做任何改动。` +
173
+ `请解除目标目录的写入限制后重跑安装器。`
174
+ );
175
+ }
176
+ if (!fileEqualsBytes(backupPath, bytes)) {
177
+ throw new Error(`备份逐字节校验失败(${backupPath} 与源文件不一致)——${keepNote},中止迁移。请重跑安装器。`);
178
+ }
179
+ try {
180
+ fs.writeFileSync(newPath, bytes);
181
+ } catch (err) {
182
+ throw new Error(
183
+ `写入新位置失败(${newPath}:${err.message})——${keepNote},备份保留于 ${backupPath}。` +
184
+ `请解除该路径的写入限制后重跑安装器。`
185
+ );
186
+ }
187
+ if (!fileEqualsBytes(newPath, bytes)) {
188
+ throw new Error(
189
+ `新位置回读校验失败(${newPath} 与源文件不一致)——${keepNote},备份保留于 ${backupPath},中止迁移。请人工检查后重跑安装器。`
190
+ );
191
+ }
192
+ fs.rmSync(oldPath, { force: true });
193
+ }
194
+
195
+ /**
196
+ * 编排单个白名单文件的位置迁移(前置校验 → 备份 → 写 → 回读校验 → 删旧件);
197
+ * 无需迁移时把跳过说明记入 report(调用方统一打印)。
198
+ */
199
+ function migrateRuntimeFile(target, entry, report) {
200
+ const oldRel = path.join(LEGACY_RUNTIME_DIR, entry.name);
201
+ const newRel = path.join(RUNTIME_DIR, entry.name);
202
+ const oldPath = path.join(target, oldRel);
203
+ const newPath = path.join(target, newRel);
204
+ const bytes = readMigratableRuntimeFile(oldPath, newPath, entry);
205
+ if (!bytes) {
206
+ report.skipped.push(`${oldRel} 不存在——无需迁移`);
207
+ return;
208
+ }
209
+ const backupRel = path.join(RUNTIME_DIR, `${entry.name}.bak-${migrationTimestamp()}`);
210
+ writeRuntimeFileWithBackup(oldPath, newPath, path.join(target, backupRel), bytes);
211
+ report.migrated.push(`${oldRel} → ${newRel}(迁移前备份: ${backupRel})`);
212
+ }
213
+
214
+ /**
215
+ * 运行时文件位置迁移总入口:按 RUNTIME_FILE_MIGRATIONS 白名单逐个执行(白名单之外的内容
216
+ * 一律原位不动——目标项目 `.comet/` 三方共占),打印迁移/跳过报告;任一文件失败即抛错中止
217
+ * (旧件与备份保留,可重跑自愈)。
218
+ */
219
+ export function migrateRuntimeFiles(target) {
220
+ const report = { migrated: [], skipped: [] };
221
+ for (const entry of RUNTIME_FILE_MIGRATIONS) {
222
+ migrateRuntimeFile(target, entry, report);
223
+ }
224
+ console.log(`[flow-comet] 运行时文件迁移(${LEGACY_RUNTIME_DIR}/ → ${RUNTIME_DIR}/;白名单 ${RUNTIME_FILE_MIGRATIONS.length} 项):`);
225
+ for (const line of report.migrated) {
226
+ console.log(` - 已迁移: ${line}`);
227
+ }
228
+ for (const line of report.skipped) {
229
+ console.log(` - 已跳过: ${line}`);
230
+ }
231
+ if (report.migrated.length > 0) {
232
+ console.log(' (迁移前备份保留在新位置,确认无误后可自行清理)');
233
+ } else {
234
+ console.log(' (全部跳过 = 本项目的状态已在当前命名空间,安装器不再需要触碰旧目录)');
235
+ }
236
+ }