ims-flow-dashboard 1.2.0 → 1.2.2

package/README.md

@@ -53,11 +53,14 @@ imsflow --open
 
 | 命令 | 说明 |
 |---|---|
-| `imsflow` | 生成 dashboard.html |
+| `imsflow` | 生成 dashboard.html（零配置时自动转服务模式） |
 | `imsflow --open` | 生成并打开浏览器 |
 | `imsflow serve` | 启动本地服务（默认端口 17771） |
 | `imsflow serve --port=17772` | 指定端口 |
 | `imsflow <过滤词>` | 按名称/路径模糊匹配工作区根 |
+| `imsflow --version` / `-v` | 查看版本（本地 + npm 最新比对） |
+| `imsflow --update` | 更新到 npm 最新版（源码模式给出 git pull 指引） |
+| `imsflow --uninstall` | 卸载命令（npm 模式 `npm uninstall -g`；源码模式清理 shell profile；`~/.imsflow` 配置保留） |
 | `imsflow --help` | 帮助 |
 
 ## 配置

package/bin/imsflow.mjs

@@ -2,21 +2,48 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
+import * as fs from 'node:fs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const scanScript = path.join(__dirname, '..', 'scan.mjs');
+const pkgRoot = path.join(__dirname, '..');
+const scanScript = path.join(pkgRoot, 'scan.mjs');
 const nodeExe = process.execPath;
 const args = process.argv.slice(2);
 
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(`imsflow — IMS Flow 控制台
+// 本地版本（package.json 随包分发, 永远和代码同步）
+const VERSION = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
+
+// npm 全局安装 = 包体在 node_modules 里; 否则是源码 clone + install.mjs 的 profile 模式
+const isNpmInstall = __dirname.includes(`node_modules${path.sep}`);
+
+// Windows 下 npm 是 npm.cmd, 必须走 shell 解析
+const npm = (npmArgs, opts = {}) => {
+  const child = spawn('npm', npmArgs, { stdio: 'inherit', shell: true, ...opts });
+  child.on('exit', (code) => process.exit(code ?? 0));
+};
+
+// 查 npm 远程版本（离线/未发布时静默, 不影响本地版本显示）
+function remoteVersion() {
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['view', 'ims-flow-dashboard', 'version'], { shell: true });
+    let out = '';
+    child.stdout.on('data', (c) => { out += c; });
+    child.on('error', () => resolve(null));
+    child.on('exit', () => resolve(out.trim() || null));
+    setTimeout(() => { try { child.kill(); } catch {} resolve(null); }, 8000); // 网络差时别卡住
+  });
+}
+
+const HELP = `imsflow — IMS Flow 控制台 (v${VERSION})
 
 用法:
   imsflow [serve] [过滤词] [--open] [--port=N]
+  imsflow --version | --update | --uninstall
   imsflow --help
 
 模式:
   快照模式 (默认)   生成单文件 dashboard.html，--open 自动打开浏览器
+                    零配置时自动转服务模式（页面「工作区」面板里添加扫描根）
   服务模式 (serve)  本地服务，页面内「重新扫描」按钮生效
                     imsflow serve [--port=17771]
 
@@ -25,13 +52,62 @@ if (args.includes('--help') || args.includes('-h')) {
   <过滤词>           按名称/路径模糊匹配工作区根
   --open            生成后自动打开浏览器
   --port=<N>        serve 模式端口（默认 17771）
+  --version, -v     显示版本（本地 + npm 最新）
+  --update          更新到 npm 最新版（${isNpmInstall ? 'npm 安装模式' : '当前为源码模式, 见提示'}）
+  --uninstall       卸载 imsflow 命令并清理
   --help, -h        显示本帮助
 
 配置:
   projects.json     注册要扫描的工作区根路径（参考 projects.example.json）
-`);
+                    也可在页面顶栏「工作区」面板里添加, 自动写入配置
+`;
+
+// ---------- 子命令分发 ----------
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v') || args.includes('version')) {
+  console.log(`imsflow v${VERSION} (${isNpmInstall ? 'npm 全局安装' : '源码模式'})`);
+  const remote = await remoteVersion();
+  if (remote === null) {
+    console.log('npm registry 不可达, 无法比对最新版本');
+  } else if (remote === VERSION) {
+    console.log(`已是最新版本 (${remote})`);
+  } else {
+    console.log(`npm 最新版本: ${remote} → 可执行 imsflow --update 更新`);
+  }
+  process.exit(0);
+}
+
+if (args.includes('--update') || args.includes('update')) {
+  console.log(`当前版本: v${VERSION} (${isNpmInstall ? 'npm 全局安装' : '源码模式'})`);
+  if (!isNpmInstall) {
+    console.log('\n源码 clone 模式不走 npm, 更新方式:');
+    console.log('  git pull');
+    console.log('  node install.mjs        # 刷新 profile 里的命令指向');
+    process.exit(0);
+  }
+  console.log('\n正在更新 ims-flow-dashboard@latest ...\n');
+  npm(['install', '-g', 'ims-flow-dashboard@latest']);
+  // npm 退出码透传后不会走到这
+}
+
+if (args.includes('--uninstall') || args.includes('uninstall')) {
+  if (!isNpmInstall) {
+    // 源码模式: install.mjs 自己会清 profile 标记块
+    console.log('源码模式: 清理各 shell profile 中的 imsflow 命令...\n');
+    const child = spawn(nodeExe, [path.join(pkgRoot, 'install.mjs'), '--uninstall'], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code ?? 0));
+  } else {
+    console.log('npm 全局安装模式: 执行 npm uninstall -g ims-flow-dashboard ...\n');
+    console.log('（配置 ~/.imsflow/projects.json 会保留, 想彻底清理可手动删除该目录）\n');
+    npm(['uninstall', '-g', 'ims-flow-dashboard']);
+  }
   process.exit(0);
 }
 
+// ---------- 默认: 透传给 scan.mjs ----------
 const child = spawn(nodeExe, [scanScript, ...args], { stdio: 'inherit' });
 child.on('exit', (code) => process.exit(code ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ims-flow-dashboard",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "IMS Flow 控制台 — 可视化 OpenSpec 变更生命周期、产物完整性与任务进度",
   "type": "module",
   "files": [

package/scan.mjs

@@ -541,14 +541,19 @@ function loadRoots() {
     console.error('[warn] projects.json 读取失败:', e.message);
   }
   if (roots.length === 0) {
-    console.error('未配置扫描根目录。请在以下任一位置创建 projects.json (参考 projects.example.json):');
-    console.error('  ' + path.join(TOOL_DIR, 'projects.json') + '        (源码 clone 模式)');
-    console.error('  ' + path.join(USER_CONFIG_DIR, 'projects.json') + '          (npm 全局安装模式)');
+    console.error('未配置扫描根目录。两种方式配置：');
+    console.error('  1. 直接运行 imsflow（会自动进入服务模式），在页面顶栏「工作区」面板里添加（推荐，自动写入配置）');
+    console.error('  2. 手动创建 ' + PROJECTS_FILE + '（参考 projects.example.json）');
     process.exit(1);
   }
   return roots;
 }
 
+// 零配置空数据：serve 允许「先打开页面、再在面板里加根」，空态是合法状态而非错误
+function emptyData() {
+  return { generatedAt: new Date().toISOString(), roots: [], workspaces: [] };
+}
+
 function filterRoots(roots, filterWord) {
   if (!filterWord) return roots;
   const w = filterWord.toLowerCase();
@@ -641,10 +646,16 @@ function buildHtml(data) {
 const args = process.argv.slice(2);
 const wantOpen = args.includes('--open');
 const positional = args.filter(a => !a.startsWith('--'));
-const serveMode = positional.includes('serve');
+let serveMode = positional.includes('serve');
 // 非 flag 位置参数（除 serve 外）= 根路径过滤词（按名称或路径模糊匹配）
 const filterWord = positional.filter(a => a !== 'serve').pop() || null;
 
+// 零配置: 快照页面只读、无法在页面上添加根 → 自动转服务模式（页面「工作区」面板可添加, 添加即持久化）
+if (!serveMode && safeLoadRoots().length === 0) {
+  console.log('[info] 未配置扫描根目录 → 自动进入服务模式，打开页面后在顶栏「工作区」面板中添加扫描根');
+  serveMode = true;
+}
+
 if (serveMode) {
   // ---- 服务模式: imsflow serve [--port=N] ----
   // 页面内「重新扫描」按钮调 /api/rescan 实时重扫, 解决快照模式的刷新问题
@@ -687,16 +698,16 @@ if (serveMode) {
           saveRoots(roots);
         } else if (action === 'remove') {
           if (!roots.some(r => samePath(r, raw))) { sendJson(400, { ok: false, error: '该路径不在扫描列表中' }); return; }
-          if (roots.length <= 1) { sendJson(400, { ok: false, error: '至少保留一个扫描根，移除后列表为空会导致服务无内容可扫' }); return; }
+          // 允许删到 0：空态是合法状态，页面上还能继续添加（面板始终可用）
           saveRoots(roots.filter(r => !samePath(r, raw)));
         } else {
           sendJson(400, { ok: false, error: 'action 必须是 add 或 remove' });
           return;
         }
-        const data = scanAll(null);
-        refresh(data);
-        console.log(`[roots:${action}] ${raw} · 现在 ${data.workspaces.length} 个工作区`);
-        sendJson(200, { ok: true, roots: data.roots });
+        const configured = safeLoadRoots();
+        refresh(configured.length > 0 ? scanAll(null, configured) : emptyData());
+        console.log(`[roots:${action}] ${raw} · 现在 ${lastData.workspaces.length} 个工作区`);
+        sendJson(200, { ok: true, roots: configured });
       } else if (url === '/api/rescan') {
         // GET = 全量重扫（页面路径筛选器负责聚焦）; POST {roots:[...]} = 只扫勾选的根, 不落盘
         let subset = null;
@@ -706,7 +717,7 @@ if (serveMode) {
           subset = [...new Set((Array.isArray(body.roots) ? body.roots : []).filter(r => configured.some(c => samePath(c, String(r)))))];
           if (subset.length === 0) { sendJson(400, { ok: false, error: '未选择任何已配置的扫描根' }); return; }
         } else if (safeLoadRoots().length === 0) {
-          sendJson(500, { ok: false, error: 'projects.json 未配置任何扫描根' });
+          sendJson(500, { ok: false, error: '未配置扫描根，请在顶栏「工作区」面板添加' });
           return;
         }
         const t0 = Date.now();
@@ -717,8 +728,15 @@ if (serveMode) {
         res.end(JSON.stringify(data));
       } else if (url === '/' || url === '/index.html') {
         if (!cachedHtml) {
-          refresh(scanAll(null));
-          console.log(`初始扫描完成, 页面 ${(cachedHtml.length / 1024).toFixed(0)} KB`);
+          const configured = safeLoadRoots();
+          if (configured.length > 0) {
+            refresh(scanAll(null, configured));
+            console.log(`初始扫描完成, 页面 ${(cachedHtml.length / 1024).toFixed(0)} KB`);
+          } else {
+            // 零配置: 渲染空态页面, 让用户在「工作区」面板里添加根（不能在这里 exit —— 会杀掉整个 serve）
+            refresh(emptyData());
+            console.log('未配置扫描根, 页面显示空态（配置文件: ' + PROJECTS_FILE + '）');
+          }
         } else if (templateMtime() !== cachedTpl && lastData) {
           // 模板文件改过了 → 用上次扫描数据重建（不必重扫），刷新页面即可看到新 UI
           refresh(lastData);

package/template.html

@@ -1031,6 +1031,13 @@ const EMPTY_HTML = '<div class="placeholder">'
   + '<div class="ph-2">生命周期 · 产物清单 · 任务状态 · 产物全文</div>'
   + '</div>';
 
+/* 零配置引导空态 —— serve 模式且没有任何扫描根时显示（首次安装的典型状态） */
+const NO_ROOT_HTML = '<div class="placeholder">'
+  + '<svg class="ph-ic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 7a2 2 0 0 1 2-2h4l2 2.5h7a2 2 0 0 1 2 2V17a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2Z"/><path d="M12 11v5M9.5 13.5h5"/></svg>'
+  + '<div class="ph-1">未配置扫描根目录</div>'
+  + '<div class="ph-2">在右侧弹出的「工作区」面板中粘贴目录路径并添加，配置会自动保存</div>'
+  + '</div>';
+
 /* ---------- 轻量 markdown 渲染 ---------- */
 function renderMd(src) {
   if (!src) return '<div class="empty-panel">（空文件）</div>';
@@ -1524,6 +1531,12 @@ function resetView() {
   };
   updateStats();
   renderSidebar();
+  // 零配置（首次安装典型状态）: serve 模式 + 无任何扫描根 → 引导空态 + 自动弹出「工作区」面板
+  if (/^https?:$/.test(location.protocol) && (DATA.workspaces || []).length === 0 && (DATA.roots || []).length === 0) {
+    document.getElementById('main').innerHTML = NO_ROOT_HTML;
+    const b = document.getElementById('wsBtn');
+    if (b) setTimeout(() => { if (!b.disabled) b.click(); }, 150); // 等面板事件绑定完成后再弹
+  }
   // 恢复重扫前选中的变更（serve 模式整页重载后从 sessionStorage 找回）
   try {
     const savedSel = sessionStorage.getItem('imsflow.sel');