@mingmaple/dsh-handover 0.9.14 → 1.0.0

package/src/tools/ho_workspace.mjs

@@ -1,14 +1,18 @@
-/** ho_workspace —— 工作区生命周期：list / create / delete（官方 workspaceRegistry）＋ 全局根目录搬迁。 */
+/** ho_workspace —— 工作区生命周期：list / create / delete / init / scaffold / migrate（旧体系迁移）＋ 全局根目录迁移。 */
 import fs from 'node:fs';
 import { nameOf } from '../lib/names.mjs';
 import path from 'node:path';
+import { pathKey } from '../lib/pathkey.mjs';
 import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
 import { workspaceRows } from '../lib/registry.mjs';
+import { createGlobalWorkspace, ensureScaffold } from '../lib/scaffold.mjs';
+import { legacyInfo, migrateLegacyDocmaps } from '../lib/legacy.mjs';
+import { syncGlobalRefs } from '../lib/system.mjs';
 import { probeMove, startMove, moveStatus, cleanupOld, stageSwitch, repairLink, stageRetarget } from '../lib/mover.mjs';
 import { currentRoot } from '../lib/api.mjs';
 
-const BAD = '不能删除「全局」工作区（那是管理会话的家）。';
+const BAD = '不能删除「全局」工作区：该工作区为管理会话所在工作区。';
 
 function gb(n) {
   const v = Number(n) || 0;
@@ -20,7 +24,7 @@ function gb(n) {
 
 function renderProbe(p) {
   const out = [];
-  out.push('搬迁预检：' + (p.ok ? '通过' : '不通过'));
+  out.push('迁移预检：' + (p.ok ? '通过' : '不通过'));
   out.push('  源  ' + p.src + (p.srcIsLink ? '（已是链接，指向 ' + p.linkTarget + '）' : ''));
   out.push('  复制源  ' + p.copyFrom);
   out.push('  目标  ' + p.dst);
@@ -28,7 +32,7 @@ function renderProbe(p) {
   if (p.freeBytes !== null && p.freeBytes !== undefined) out.push('  目标盘可用  ' + gb(p.freeBytes));
   for (const w of p.warnings || []) out.push('  注意：' + w);
   for (const x of p.problems || []) out.push('  未通过：' + x);
-  if (p.ok) out.push('提示：复制完会生成切换脚本；切换那一步需要**完全退出 DSH** 再跑（源目录被占用）。');
+  if (p.ok) out.push('提示：复制完成后生成切换脚本；切换步骤须完全退出 DSH 后再执行（源目录被占用）。');
   return out.join(NL);
 }
 
@@ -36,7 +40,7 @@ export function pmWorkspaceTool(env) {
   return {
     name: nameOf('workspace'),
     description:
-      '工作区 list、create、delete；move-* 搬整个全局根目录（探针、执行、状态、清旧副本）。删除只删注册。',
+      '工作区：init 首次建立全局体系、scaffold 补齐缺失目录与说明、migrate 旧体系迁移、list、create、delete、move-* 迁移整个全局根目录。删除只删注册。',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -44,15 +48,18 @@ export function pmWorkspaceTool(env) {
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
-          description: 'list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
+          enum: ['init', 'scaffold', 'migrate', 'list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
+          description: 'init / scaffold / migrate / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
         },
-        path: { type: 'string', description: 'create 用：目录绝对路径；默认要求已存在，ensure=true 时自动创建' },
-        title: { type: 'string', description: 'create 用：显示标题' },
-        ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（默认 false，不替你建目录）' },
-        workspace: { type: 'string', description: 'delete 用：工作区 id、标题、路径' },
-        to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动建）' },
-        confirm: { type: 'boolean', description: 'move-cleanup 用：true 才真的删旧副本' },
+        parent: { type: 'string', description: 'init 用：目标父目录的绝对路径（不存在时创建）；全局根建于其中' },
+        name: { type: 'string', description: 'init 用：全局根目录名，缺省 _Workspace' },
+        register: { type: 'boolean', description: 'init 用：建立后一并注册为工作区（缺省 false）' },
+        path: { type: 'string', description: 'create 用：目录绝对路径；缺省要求已存在，ensure=true 时自动创建' },
+        title: { type: 'string', description: 'create、init 用：工作区显示标题（init 缺省「全局」）' },
+        ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（缺省 false，不代建目录）' },
+        workspace: { type: 'string', description: 'delete 用：工作区 id、标题或路径' },
+        to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动创建）' },
+        confirm: { type: 'boolean', description: 'move-cleanup 用：为 true 才实际删除旧备份' },
       },
     },
     output: textOutput(),
@@ -61,6 +68,103 @@ export function pmWorkspaceTool(env) {
       const action = String(args.action || '');
       const out = [];
 
+      if (action === 'init') {
+        const parent = String(args.parent || '').trim();
+        if (!parent) throw new Error('action="init" 需要 parent（目标父目录绝对路径）');
+        const r = createGlobalWorkspace(parent, { name: args.name });
+        if (!r.ok) {
+          out.push('未建立：' + r.error);
+          if (r.root) out.push('目标：' + r.root);
+          out.push('');
+          out.push('用法：ho_workspace(action="init", parent="<已存在的目录绝对路径>")。插件仅新建，不覆盖。');
+          return { text: out.join(NL) };
+        }
+        out.push('已建立全局文件体系：' + r.root);
+        out.push('  目录 ' + r.created.length + ' 个：' + r.created.slice(0, 5).join('、') + (r.created.length > 5 ? ' 等' : ''));
+        out.push('  文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（均已存在，未覆盖）'));
+        if (r.existed) out.push('  目标原为空目录，直接使用。');
+        if (r.createdParent) out.push('  父目录原不存在，已创建。');
+        if (r.skipped.length) out.push('  跳过（已存在、未覆盖）：' + r.skipped.join('、'));
+        let registered = null;
+        if (args.register === true) {
+          if (!reg || typeof reg.create !== 'function') {
+            out.push('');
+            out.push('注册未完成：workspaceRegistry 不可用。请将下列路径粘贴到 DSH 的新建工作区窗口：');
+            out.push('  ' + r.root);
+            return { text: out.join(NL) };
+          }
+          const title = String(args.title || '').trim() || '全局';
+          try {
+            const w = await reg.create(r.root, title);
+            registered = w;
+            out.push('');
+            out.push('已注册工作区：' + title + '（' + String(w && w.id ? w.id : '?') + '）');
+          } catch (e) {
+            out.push('');
+            out.push('注册失败：' + String(e && e.message ? e.message : e));
+            out.push('可将下列路径粘贴到 DSH 的新建工作区窗口：');
+            out.push('  ' + r.root);
+            return { text: out.join(NL) };
+          }
+        }
+        out.push('');
+        out.push('下一步：');
+        if (!registered) {
+          out.push('  1. 注册为工作区：ho_workspace(action="create", path="' + r.root + '", title="全局")，或将该路径粘贴到 DSH 的新建工作区窗口；');
+          out.push('  2. 新建一个标题含「全局」的会话，闸门、交接体检与会话水位即接入。');
+        } else {
+          out.push('  新建一个标题含「全局」的会话，闸门、交接体检与会话水位即接入。');
+        }
+        out.push('（也可在设置页的 dsh-handover 中完成「首次安装」，效果相同。）');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'scaffold') {
+        const root = currentRoot(env);
+        if (!root) throw new Error('未找到全局根（工作区未接入）');
+        const r = ensureScaffold(root);
+        if (!r.ok) {
+          out.push('未补齐：' + r.error);
+          out.push('根目录：' + root);
+          return { text: out.join(NL) };
+        }
+        out.push('已核对文件体系：' + root);
+        out.push('  新建目录 ' + r.created.length + ' 个：' + (r.created.length ? r.created.join('、') : '（无缺失）'));
+        out.push('  新建文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（无缺失）'));
+        out.push('  已存在未覆盖 ' + r.skipped.length + ' 个' + (r.skipped.length ? '：' + r.skipped.join('、') : ''));
+        if (r.missingTemplates && r.missingTemplates.length) {
+          out.push('  内置模板缺失 ' + r.missingTemplates.length + ' 个（未写空文件）：' + r.missingTemplates.join('、'));
+        }
+        out.push('只新建，不覆盖、不删除：已有文件的内容未作任何改动。');
+        const legacy = legacyInfo(root);
+        if (legacy.exists) out.push('提示：检测到旧文档定位（' + legacy.dir + '），执行 ho_workspace(action="migrate") 并入体系注册。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'migrate') {
+        const root = currentRoot(env);
+        if (!root) throw new Error('未找到全局根（工作区未接入）');
+        const pre = legacyInfo(root);
+        if (!pre.exists) {
+          out.push('没有旧文档定位：' + pre.dir);
+          out.push('判定：无需迁移。');
+          return { text: out.join(NL) };
+        }
+        const r = migrateLegacyDocmaps(root);
+        out.push('旧文档定位迁移：' + (r.ok ? '完成' : '部分完成'));
+        out.push('  已并入体系注册 ' + r.converted.length + ' 份' + (r.converted.length ? '：' + r.converted.join('、') : ''));
+        out.push('  全局旧内容保留为工作区文档清单 ' + r.kept.length + ' 份' + (r.kept.length ? '：' + r.kept.join('、') : ''));
+        if (r.archived) out.push('  旧目录已归档（未删除）：' + r.archived);
+        for (const p of r.problems || []) out.push('  未迁移：' + p);
+        try {
+          const g = syncGlobalRefs(root);
+          out.push('  全局总注册已重建：' + g.rows.length + ' 个任务');
+        } catch (e) {
+          out.push('  全局总注册重建失败：' + String(e && e.message ? e.message : e));
+        }
+        return { text: out.join(NL) };
+      }
+
       if (action === 'list') {
         if (reg && typeof reg.list === 'function') {
           let list = [];
@@ -75,7 +179,7 @@ export function pmWorkspaceTool(env) {
           }
         }
         const rows = workspaceRows();
-        out.push('工作区（退化：读 workspace.json，' + rows.length + ' 个）');
+        out.push('工作区（退化读取 workspace.json，' + rows.length + ' 个）');
         for (const r of rows) out.push('  ' + r.id + '  ' + r.title + '  ' + r.path + '  会话 ' + r.sessions);
         return { text: out.join(NL) };
       }
@@ -89,13 +193,13 @@ export function pmWorkspaceTool(env) {
         if ((!st || !st.isDirectory()) && args.ensure === true) {
           try { fs.mkdirSync(p, { recursive: true }); st = fs.statSync(p); } catch (e) { throw new Error('建目录失败：' + p + '（' + String(e && e.message ? e.message : e) + '）'); }
         }
-        if (!st || !st.isDirectory()) throw new Error('目录不存在或不是目录：' + p + '（默认不替你建目录；要建请传 ensure=true，或先手工建好）');
+        if (!st || !st.isDirectory()) throw new Error('目录不存在或不是目录：' + p + '（缺省不代建目录；需要创建时传 ensure=true，或先行手工建好）');
         const title = String(args.title || '').trim() || p.split(/[\\/]/).filter(Boolean).pop() || p;
         let w = null;
         try { w = await reg.create(p, title); } catch (e) { throw new Error('建工作区失败：' + String(e && e.message ? e.message : e)); }
         out.push('已注册工作区 ' + String(w && w.id ? w.id : '?') + '  ' + String(w && w.title ? w.title : title));
         out.push('路径 ' + String(w && w.path ? w.path : p));
-        out.push('同一路径重复调用返回原记录、不改标题；新登记的工作区排在列表最前。');
+        out.push('同一路径重复调用返回原记录，不改标题；新登记的工作区排在列表最前。');
         return { text: out.join(NL) };
       }
 
@@ -105,13 +209,13 @@ export function pmWorkspaceTool(env) {
         if (!key) throw new Error('delete 需要 workspace（id、标题、路径）');
         let list = [];
         try { list = reg.list() || []; } catch { list = []; }
-        const norm = (s) => String(s || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+        const norm = (s) => pathKey(String(s || ''));
         const hit = list.find((w) => String(w.id) === key || w.title === key || norm(w.path) === norm(key));
         if (!hit) throw new Error('找不到工作区：' + key);
         if (String(hit.title || '').indexOf('全局') !== -1) throw new Error(BAD);
         const ok = await reg.delete(hit.id);
         out.push((ok ? '已删除工作区注册 ' : '该工作区不存在（无操作）') + String(hit.id) + '  ' + String(hit.title || '-'));
-        out.push('注意：只删注册；目录与全部会话日志都保留在原处。');
+        out.push('注意：只删注册；目录与全部会话日志均保留在原处。');
         return { text: out.join(NL) };
       }
 
@@ -128,11 +232,11 @@ export function pmWorkspaceTool(env) {
         if (!p.ok) return { text: renderProbe(p) + NL + '未开始复制。' };
         const r = await startMove({ src, to });
         if (!r.ok) {
-          out.push('复制完成但**校验有差异**，未生成切换脚本。');
+          out.push('复制完成，但校验存在差异，未生成切换脚本。');
           out.push('  文件 源 ' + r.report.files + ' / 目标 ' + r.report.copies);
           out.push('  缺失 ' + r.report.missingCount + ' 条' + (r.report.missing.length ? '：' + r.report.missing.join('、') : ''));
           out.push('  多出 ' + r.report.extraCount + ' 条' + (r.report.extra.length ? '：' + r.report.extra.join('、') : ''));
-          out.push('处置：清空目标目录后重跑，或先停掉在写文件的会话。');
+          out.push('处置：清空目标目录后重跑，或先停止正在写入文件的会话。');
           return { text: out.join(NL) };
         }
         out.push('复制并校验通过：' + r.report.files + ' 文件 · ' + gb(r.report.bytes));
@@ -141,44 +245,44 @@ export function pmWorkspaceTool(env) {
         out.push('  切换助手  ' + r.marker.script.helper);
         out.push('  手工启动器（Windows、POSIX）  ' + r.marker.script.cmd + ' 、 ' + r.marker.script.sh);
         out.push('');
-        out.push('下一步（三条，顺序不能换）：');
+        out.push('下一步（3 步，顺序不可调换）：');
         out.push('  ① 完全退出 DSH（源目录被占用，改名会失败）');
-        out.push('  ② 执行 ho_workspace(action="move-switch") 派后台助手（推荐）；助手会等待 DSH 退出后自动完成');
-        out.push('  ③ 重新启动 DSH；确认无误后在设置页点「删除旧副本」');
+        out.push('  ② 执行 ho_workspace(action="move-switch") 派出后台助手（推荐用法）；该助手会在 DSH 退出后自动完成');
+        out.push('  ③ 重新启动 DSH；确认无误后可在设置页删除旧备份');
         return { text: out.join(NL) };
       }
 
       if (action === 'move-switch') {
         const r = stageSwitch({ relaunch: args.relaunch === true });
-        if (r.already) { out.push('已经是切换态（旧路径就是 junction），无需再切。'); return { text: out.join(NL) }; }
+        if (r.already) { out.push('已处于切换态（原路径即链接），无需再次切换。'); return { text: out.join(NL) }; }
         out.push('已派出后台切换助手（pid ' + r.pid + '）。');
-        out.push('  它会在你**完全退出 DSH** 后自动完成：旧目录改名、原位建 junction、校验指向' + (r.relaunch ? '，然后重新启动 DSH' : '') + '。');
+        out.push('  该助手会在完全退出 DSH 后自动完成：旧目录改名、原位建立链接、校验指向' + (r.relaunch ? '，然后重新启动 DSH' : '') + '。');
         out.push('  日志：' + r.log);
-        out.push('  提醒：从现在起不要改这个工作区里的文件（改动只会落在还活着的旧目录上）。');
+        out.push('  提醒：此后不得修改该工作区内的文件（改动只会落在仍在使用的旧目录上）。');
         return { text: out.join(NL) };
       }
 
       if (action === 'move-status') {
         const st = moveStatus();   // 以标记里的源路径为准：修改登记后当前根已是新位置，拿它比对会误报
-        const label = { none: '没有搬迁记录', verified: '已复制校验通过，等待切换', switched: '已切换（旧路径是 junction）', partial: '复制有差异，未生成脚本' };
-        out.push('搬迁状态：' + (label[st.phase] || st.phase));
-        out.push('  源  ' + st.src + (st.linkTarget ? '（→ ' + st.linkTarget + '）' : ''));
+        const label = { none: '没有迁移记录', verified: '已复制并校验通过，待切换', switched: '已切换（原路径为链接）', partial: '复制有差异，未生成脚本' };
+        out.push('迁移状态：' + (label[st.phase] || st.phase));
+        out.push('  源  ' + st.src + (st.linkTarget ? '（当前为链接，指向 ' + st.linkTarget + '）' : ''));
         if (st.dst) out.push('  目标  ' + st.dst);
         if (st.marker && st.marker.files) out.push('  清单  ' + st.marker.files + ' 文件 · ' + (st.marker.digest || '').slice(0, 16) + '…');
         if (st.retarget) {
           if (st.retarget.needed) {
-            out.push('  DSH 登记仍指着旧路径：' + st.retarget.total + ' 处');
+            out.push('  DSH 登记仍指向旧路径：' + st.retarget.total + ' 处');
             for (const f of st.retarget.files) out.push('    ' + f.path + '  ×' + f.count);
-            out.push('  修改登记：ho_workspace(action="move-retarget")（退出 DSH 后由助手改写，先备份）');
+            out.push('  修改登记：ho_workspace(action="move-retarget")（退出 DSH 后由助手改写，改写前先备份）');
           } else {
             out.push('  DSH 登记已在新位置（无需修改登记）');
           }
         }
         if (st.olds && st.olds.length) {
-          for (const o of st.olds) out.push('  旧副本  ' + o.path + '  ' + gb(o.bytes));
+          for (const o of st.olds) out.push('  旧备份  ' + o.path + '  ' + gb(o.bytes));
           out.push('  删除：ho_workspace(action="move-cleanup", confirm=true)');
         } else if (st.phase === 'switched') {
-          out.push('  没有旧副本残留');
+          out.push('  无旧备份');
         }
         return { text: out.join(NL) };
       }
@@ -186,32 +290,32 @@ export function pmWorkspaceTool(env) {
       if (action === 'move-retarget') {
         const r = stageRetarget();
         if (r.already) { out.push('DSH 登记已在新位置，无需修改登记。'); return { text: out.join(NL) }; }
-        if (!r.ok) { out.push('派助手失败：' + r.error); out.push('  手工执行：' + (r.script && r.script.helper)); return { text: out.join(NL) }; }
-        out.push('已派出登记修改登记助手（pid ' + r.pid + '）。');
-        out.push('  它会在你完全退出 DSH 后改写这些登记（每份先备份）：');
+        if (!r.ok) { out.push('派出助手失败：' + r.error); out.push('  手工执行：' + (r.script && r.script.helper)); return { text: out.join(NL) }; }
+        out.push('已派出修改登记的助手（pid ' + r.pid + '）。');
+        out.push('  该助手会在完全退出 DSH 后改写下列登记（每份先备份）：');
         for (const f of (r.plan.files || [])) if (f.count) out.push('    ' + f.path + '  ×' + f.count);
-        out.push('  只改登记文本，不动任何数据文件；日志：' + (r.script && r.script.log));
+        out.push('  只改登记文本，不改动任何数据文件；日志：' + (r.script && r.script.log));
         return { text: out.join(NL) };
       }
 
       if (action === 'move-repair') {
         const r = repairLink();
         if (r.already) { out.push('原路径已是指向新根的链接，无需重建。'); return { text: out.join(NL) }; }
-        out.push('已重建链接：' + r.src + ' → ' + r.dst + '（' + r.kind + '）');
-        out.push('  说明：只建链接，未改动任何文件。');
+        out.push('已重建链接：' + r.src + ' 指向 ' + r.dst + '（' + r.kind + '）');
+        out.push('  说明：仅建立链接，未改动任何文件。');
         return { text: out.join(NL) };
       }
 
       if (action === 'move-cleanup') {
-        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（会真删旧副本目录）');
+        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（将实际删除旧备份目录）');
         const r = await cleanupOld({ confirm: true });
         out.push(r.note);
-        for (const p of r.removed) out.push('  已删 ' + p);
+        for (const p of r.removed) out.push('  已删除 ' + p);
         if (r.bytes) out.push('  释放 ' + gb(r.bytes));
         return { text: out.join(NL) };
       }
 
-      throw new Error('action 只能是 list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
+      throw new Error('action 只能是 init / scaffold / migrate / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
     },
   };
 }