ims-flow-dashboard 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 booksongs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# IMS Flow 控制台
+
+可视化 OpenSpec 变更的**生命周期阶段、产物完整性、任务进度与产物全文**——零依赖单文件 Node 工具，为 ims-flow 工作流量身打造。
+
+## 快速开始
+
+```bash
+# 1. 安装（任选其一）
+npm install -g ims-flow-dashboard        # npm 安装，拿到 imsflow 全局命令
+#   源码 clone 场景（写进 PowerShell profile / .bashrc，幂等可重复执行）：
+#   node install.mjs   （卸载用 node install.mjs --uninstall）
+
+# 2. 配置要扫描的工作区根
+mkdir ~/.imsflow && cp projects.example.json ~/.imsflow/projects.json
+#   编辑 projects.json，填入你的 openspec 工作区根路径
+#   （serve 模式下也可以直接在页面「▤ 工作区」面板里增删，自动写入配置）
+
+# 3. 重新打开终端，打开控制台
+imsflow --open        # 快照模式：生成 dashboard.html 并打开
+imsflow serve         # 服务模式：localhost:17771，页面内可重扫/管理工作区
+```
+
+> 源码安装器会往 `Documents\WindowsPowerShell\profile.ps1` 和 `~/.bashrc` 写入带 `>>> imsflow >>>` 标记块的函数，重跑即更新，卸载整块移除。Node 路径取自当前运行 install.mjs 的 node（process.execPath），不依赖 npm link / PATH。npm 全局安装不需要 install.mjs——npm 自动生成 `imsflow` / `imsflow.cmd` / `imsflow.ps1`。
+
+## 给同事安装
+
+```bash
+npm install -g ims-flow-dashboard    # 需 Node ≥ 18
+mkdir ~/.imsflow                     # 配置目录
+#    复制 projects.example.json 为 ~/.imsflow/projects.json，
+#    改成对方自己的 openspec 工作区根路径（或用 serve 模式页面内添加）
+imsflow --open
+```
+
+说明：
+
+- 配置查找顺序：**包目录** `projects.json`（源码 clone 模式）→ **`~/.imsflow/projects.json`**（npm 全局安装模式，升级不丢配置）
+- serve 模式（`imsflow serve`）页面内「重新扫描」「▤ 工作区」（增删扫描根/勾选本次扫描）同样可用——刷新是代码能力，与安装方式无关
+- ⚠️ 不要直接压缩整个项目文件夹分发——dashboard.html（含全部变更数据）和 projects.json（本机路径）会被一起带走
+- 离线场景备选：`npm pack` 出 tgz 传文件，对方 `npm install -g <tgz>`；或 `npm run pack` 出 zip（手动解压 + `node install.mjs` 安装命令）
+
+## 功能
+
+- **生命周期七阶段**：created → proposing → ready → applying → applied → archived（含 review.md 自建标记）
+- **产物完整性检查**：9 类产物是否存在、模板节是否齐全、gates 检查项是否通过
+- **任务进度**：tasks.md 逐项勾选状态，按组折叠
+- **产物全文**：markdown 渲染，代码块、表格、ER 图
+- **全文搜索**（Ctrl+K）：搜全部变更的变更名/标题/产物全文，命中定位 + 高亮
+- **来源溯源**：meta.yaml 的 created-by 区分 Trae / TuanjieAI / WorkBuddy / 人工
+- **单/双模式**：快照（双击 dashboard.html 即看）+ serve（重扫按钮）
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `imsflow` | 生成 dashboard.html |
+| `imsflow --open` | 生成并打开浏览器 |
+| `imsflow serve` | 启动本地服务（默认端口 17771） |
+| `imsflow serve --port=17772` | 指定端口 |
+| `imsflow <过滤词>` | 按名称/路径模糊匹配工作区根 |
+| `imsflow --help` | 帮助 |
+
+## 配置
+
+`projects.json`（各人本地配置，不随包发布）：
+
+```json
+{
+  "roots": [
+    "D:\\project\\my-repo",
+    "D:\\work\\openspec-demo"
+  ]
+}
+```
+
+每个 root 是一个 openspec 工作区根（含 `openspec/changes/` 的目录）。控制台扫描每个 root 下 `openspec/changes/` 的活跃变更和 `openspec/changes/archive/` 的归档变更。
+
+## 技术栈
+
+- **零依赖**：scan.mjs 纯 Node 内置模块，无 node_modules
+- **单文件输出**：dashboard.html 内联全部 CSS/JS，可离线打开
+- **Node ≥ 18**
+
+## 文件结构
+
+```
+ims-flow-dashboard/
+├── bin/
+│   └── imsflow.mjs       # CLI 入口
+├── install.mjs           # 命令安装器（写 profile，幂等，支持 --uninstall）
+├── scan.mjs              # 零依赖扫描器 + serve 服务
+├── template.html         # 控制台模板（单文件 SPA）
+├── projects.example.json # 配置模板
+└── (dashboard.html)     # 生成物，gitignore
+```
+
+## License
+
+MIT

package/bin/imsflow.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scanScript = path.join(__dirname, '..', 'scan.mjs');
+const nodeExe = process.execPath;
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`imsflow — IMS Flow 控制台
+
+用法:
+  imsflow [serve] [过滤词] [--open] [--port=N]
+  imsflow --help
+
+模式:
+  快照模式 (默认)   生成单文件 dashboard.html，--open 自动打开浏览器
+  服务模式 (serve)  本地服务，页面内「重新扫描」按钮生效
+                    imsflow serve [--port=17771]
+
+参数:
+  serve             启动本地服务
+  <过滤词>           按名称/路径模糊匹配工作区根
+  --open            生成后自动打开浏览器
+  --port=<N>        serve 模式端口（默认 17771）
+  --help, -h        显示本帮助
+
+配置:
+  projects.json     注册要扫描的工作区根路径（参考 projects.example.json）
+`);
+  process.exit(0);
+}
+
+const child = spawn(nodeExe, [scanScript, ...args], { stdio: 'inherit' });
+child.on('exit', (code) => process.exit(code ?? 0));

package/bin/preview.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * 生成轻量预览 preview.html
+ *
+ * 为什么需要它：dashboard.html 是全量快照（~5.3MB / 11 工作区），在 IDE 预览里很重；
+ * preview.html 是只扫演示仓库的小快照（~95KB），看设计最快。
+ *
+ * 坑（真实踩过）：演示仓库不在 projects.json 里，`node scan.mjs ims-flow-demo` 会直接报
+ * 「没有匹配的根路径」，于是 preview.html 就停在了旧模板上 —— 打开它看到的是**旧设计**，
+ * 而 dashboard.html 早已更新，排查时极易误判成"改了没生效"。
+ *
+ * 用法：node bin/preview.mjs [演示仓库路径]
+ *   未给路径时，按 projects.local.json（本地私有, gitignore+不发布）→ projects.example.json
+ *   的顺序挑一个「存在且未被 projects.json 收录」的根。
+ *   published 的 example 只放通用示例路径，本机演示仓库路径放 local。
+ * 生成后会重新跑一次全量扫描，把 dashboard.html 还原成全量数据。
+ */
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CFG = path.join(DIR, 'projects.json');
+const LOCAL = path.join(DIR, 'projects.local.json');
+const EXAMPLE = path.join(DIR, 'projects.example.json');
+const OUT = path.join(DIR, 'dashboard.html');
+const PREVIEW = path.join(DIR, 'preview.html');
+
+const readRoots = f => {
+  try {
+    const j = JSON.parse(fs.readFileSync(f, 'utf8'));
+    return Array.isArray(j.roots) ? j.roots.filter(r => typeof r === 'string' && r.trim()) : [];
+  } catch { return []; }
+};
+
+const configured = readRoots(CFG);
+
+// 1) 选一个演示根：显式参数 > projects.local.json > projects.example.json（都要求存在且未配置）
+let demo = process.argv[2];
+if (!demo) {
+  demo = readRoots(LOCAL).find(r => fs.existsSync(r) && !configured.includes(r))
+    || readRoots(EXAMPLE).find(r => fs.existsSync(r) && !configured.includes(r));
+}
+if (!demo) {
+  console.error('未找到可用的演示仓库。用法: node bin/preview.mjs <演示仓库路径>');
+  process.exit(1);
+}
+if (!fs.existsSync(demo)) {
+  console.error(`演示仓库不存在: ${demo}`);
+  process.exit(1);
+}
+
+const filter = path.basename(demo);
+// 子进程输出先捕获再转发 —— scan.mjs 早期失败(配置读不到等)时会直接 exit(1) 且几乎不打印,
+// 只看 status 无从判断原因, 所以这里把 stdout/stderr 原样回显出来。
+// ⚠️ args 必须由调用方决定：还原配置之后再用 demo 过滤词跑全量, 会报「没有匹配的根路径」。
+const exec = (args) => {
+  try {
+    const out = execFileSync(process.execPath, ['scan.mjs', ...args], {
+      cwd: DIR, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (out) process.stdout.write(out);
+    return;
+  } catch (e) {
+    if (e.stdout) process.stdout.write(e.stdout);
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new Error(`scan.mjs ${args.join(' ')} 退出码 ${e.status}${e.stderr ? '' : '（无 stderr 输出）'}`);
+  }
+};
+
+// 2) 临时挂上演示根 -> 扫 -> 存成 preview.html
+const original = fs.readFileSync(CFG, 'utf8');
+let failed = null;
+try {
+  fs.writeFileSync(CFG, JSON.stringify({ roots: [...configured, demo] }, null, 2) + '\n', 'utf8');
+  console.log(`[preview] 临时挂载演示根: ${demo}`);
+  exec([filter]);
+  fs.copyFileSync(OUT, PREVIEW);
+  console.log(`[preview] 已生成 ${path.relative(DIR, PREVIEW)} (${(fs.statSync(PREVIEW).size / 1024).toFixed(0)} KB)`);
+} catch (e) {
+  failed = e;
+} finally {
+  // 3) 无论如何都还原配置，别把用户的 projects.json 留在脏状态
+  fs.writeFileSync(CFG, original, 'utf8');
+  console.log(`[preview] projects.json 已还原 (${configured.length} 个根)`);
+}
+if (failed) { console.error('[preview] 失败:', failed.message); process.exit(1); }
+
+// 4) dashboard.html 刚被 demo 数据覆盖了，重新跑全量还原
+console.log('[preview] 重新生成全量 dashboard.html …');
+exec([]);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "ims-flow-dashboard",
+  "version": "1.2.0",
+  "description": "IMS Flow 控制台 — 可视化 OpenSpec 变更生命周期、产物完整性与任务进度",
+  "type": "module",
+  "files": [
+    "bin/",
+    "scan.mjs",
+    "template.html",
+    "projects.example.json"
+  ],
+  "bin": {
+    "imsflow": "./bin/imsflow.mjs"
+  },
+  "scripts": {
+    "scan": "node scan.mjs",
+    "preview": "node bin/preview.mjs",
+    "serve": "node scan.mjs serve",
+    "open": "node scan.mjs --open",
+    "setup": "node install.mjs",
+    "uninstall": "node install.mjs --uninstall",
+    "pack": "git archive --format=zip -o ims-flow-dashboard.zip HEAD"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "openspec",
+    "spec-driven",
+    "dashboard",
+    "cli",
+    "workflow-visualization"
+  ],
+  "author": "booksongs",
+  "license": "MIT"
+}

package/projects.example.json

@@ -0,0 +1,5 @@
+{
+  "roots": [
+    "D:\\project\\my-openspec-workspace"
+  ]
+}