@shendeguize/remote-dsh-center 0.4.0

package/src/web/setup-schema.js

@@ -0,0 +1,203 @@
+/**
+ * 首启引导的「问题定义」——CLI 向导与页面向导共用的唯一源（11 §6.3 / ENG-17）。
+ *
+ * 硬约束：纯数据 + 纯函数，不引 DOM、不引 node API，也不 import 项目里任何带副作用的模块。
+ * 页面用 <script type=module> 直接 import；cli.js 以文件路径 import。
+ */
+
+export const PORT_MIN = 1;
+export const BINDABLE_PORT_MIN = 1024;
+export const PORT_MAX = 65_535;
+
+export function parseIntStrict(raw) {
+  const s = String(raw ?? '').trim();
+  if (!/^\d+$/.test(s)) return { ok: false, error: '请输入整数' };
+  return { ok: true, value: Number(s) };
+}
+
+export function vPort(n) {
+  if (!Number.isInteger(n) || n < PORT_MIN || n > PORT_MAX) return `端口须为 ${PORT_MIN}–${PORT_MAX} 的整数`;
+  return null;
+}
+
+/** `17701-17799`、`17701 17799`、`17701,17799` 都收。 */
+export function parseRange(raw) {
+  const parts = String(raw ?? '').split(/[\s,\-–~]+/).map((s) => s.trim()).filter(Boolean);
+  if (parts.length !== 2) return { ok: false, error: '请输入两个端口，如 17701-17799' };
+  const from = parseIntStrict(parts[0]);
+  const to = parseIntStrict(parts[1]);
+  if (!from.ok) return from;
+  if (!to.ok) return to;
+  return { ok: true, value: [from.value, to.value] };
+}
+
+export function vBindableRange(range) {
+  if (!Array.isArray(range) || range.length !== 2) return '区间需要起点与终点两个值';
+  for (const p of range) {
+    if (!Number.isInteger(p) || p < BINDABLE_PORT_MIN || p > PORT_MAX) {
+      return `端口须为 ${BINDABLE_PORT_MIN}–${PORT_MAX} 的整数`;
+    }
+  }
+  if (range[1] < range[0]) return '区间终点必须 ≥ 起点';
+  return null;
+}
+
+// 兼容既有页面向导消费者；区间只用于 defaults.localPortRange，语义即本机可绑定范围。
+export const vRange = vBindableRange;
+
+/**
+ * 四步定义，与 01 §2.5 一一对应。
+ * `def(current)` 取预填值：current 是「现有 config 或出厂默认」的同形对象。
+ */
+export const SETUP_STEPS = Object.freeze([
+  {
+    id: 'manager',
+    title: '本机服务',
+    fields: [
+      {
+        key: 'manager.port',
+        label: 'manager 端口',
+        hint: '管理台与 API 的本机监听端口',
+        def: (c) => c.manager.port,
+        parse: parseIntStrict,
+        validate: vPort,
+      },
+      {
+        key: 'defaults.localPortRange',
+        label: '本机映射端口区间',
+        hint: '每台远端主机从这个区间里分一个本机端口，如 17701-17799',
+        def: (c) => c.defaults.localPortRange,
+        parse: parseRange,
+        validate: vBindableRange,
+        format: (v) => `${v[0]}-${v[1]}`,
+      },
+    ],
+  },
+  {
+    id: 'remote',
+    title: '远端约定',
+    fields: [
+      {
+        key: 'defaults.remoteWebPort',
+        label: '远端 dsh web 端口',
+        hint: '统一约定值；个别主机可事后单独覆写',
+        def: (c) => c.defaults.remoteWebPort,
+        parse: parseIntStrict,
+        validate: vPort,
+      },
+    ],
+  },
+  { id: 'hosts', title: '主机纳管与开启', kind: 'host-select' },
+  { id: 'confirm', title: '确认', kind: 'preview' },
+]);
+
+/** 按 `a.b` 点路径取值，两侧向导共用同一套 key 字符串。 */
+export function getByPath(obj, keyPath) {
+  return keyPath.split('.').reduce((acc, k) => (acc === null || acc === undefined ? acc : acc[k]), obj);
+}
+
+export function setByPath(obj, keyPath, value) {
+  const keys = keyPath.split('.');
+  const last = keys.pop();
+  let cur = obj;
+  for (const k of keys) {
+    cur[k] ??= {};
+    cur = cur[k];
+  }
+  cur[last] = value;
+  return obj;
+}
+
+/** 收集所有字段的预填答案（一路回车即得此结果）。 */
+export function defaultAnswers(current) {
+  const answers = {};
+  for (const step of SETUP_STEPS) {
+    for (const f of step.fields ?? []) setByPath(answers, f.key, f.def(current));
+  }
+  return answers;
+}
+
+/**
+ * 逐字段校验答案；返回按 key 的错误表（空表 = 全通过）。
+ * 两侧向导共用，保证「同源同题同判定」。
+ */
+export function validateAnswers(answers) {
+  const errors = {};
+  for (const step of SETUP_STEPS) {
+    for (const f of step.fields ?? []) {
+      const bad = f.validate(getByPath(answers, f.key));
+      if (bad) errors[f.key] = bad;
+    }
+  }
+  return errors;
+}
+
+/**
+ * 主机勾选规则（01 §2.5 第 3 步 / UI-23）：只有探测为 ready 才能开启链接；
+ * 探测未完成的行可以纳管，但 autoStart 一律 false。
+ * @param {{phase?:string}|null} probe
+ */
+export function canAutoStart(probe) {
+  return probe?.phase === 'ready';
+}
+
+/**
+ * 候选入口兼容旧 string[]；Node/页面只需注入名字与运输类型，纯模块不猜本机身份。
+ * @param {Array<string|{name:string,local?:boolean}>} candidates
+ * @returns {{name:string,local:boolean}[]}
+ */
+export function normalizeHostCandidates(candidates = []) {
+  return candidates.map((candidate) => (
+    typeof candidate === 'string'
+      ? { name: candidate, local: false }
+      : { name: candidate.name, local: candidate.local === true }
+  ));
+}
+
+/**
+ * answers + 主机候选 + 探测结果 → 完整 config（setupCompleted 由落盘侧强制置 true）。
+ *
+ * @param {object} answers 形如 { manager:{port}, defaults:{remoteWebPort, localPortRange} }
+ * @param {Array<string|{name:string,local?:boolean}>} candidates 主机候选；string 视为远端
+ * @param {Record<string, {phase?:string}>} probeResults 主机名 → 探测结果（可缺）
+ * @param {object} factoryDefaults 出厂默认（提供 hostDefaults 形状）
+ * @param {{selection?:Record<string,{enabled?:boolean, autoStart?:boolean}>}} [opts]
+ */
+export function buildConfigFromAnswers(answers, candidates, probeResults, factoryDefaults, opts = {}) {
+  const selection = opts.selection ?? {};
+  const hostDefaults = factoryDefaults.hostDefaults;
+
+  const hosts = {};
+  for (const candidate of normalizeHostCandidates(candidates)) {
+    const { name, local } = candidate;
+    const pick = selection[name] ?? {};
+    const enabled = pick.enabled ?? true;
+    // 未探测/非 ready 的主机永远不自启：避免开机就撞一串失败
+    const autoStart = Boolean(enabled && pick.autoStart && canAutoStart(probeResults?.[name]));
+    hosts[name] = {
+      local,
+      enabled,
+      autoStart,
+      localPort: local ? null : hostDefaults.localPort,
+      remoteWebPort: hostDefaults.remoteWebPort,
+      workdir: hostDefaults.workdir ?? null,
+      inject: { env: {}, extraArgs: [], patches: [] },
+    };
+  }
+
+  return {
+    configVersion: 1,
+    setupCompleted: true,
+    manager: { port: getByPath(answers, 'manager.port') },
+    defaults: {
+      remoteWebPort: getByPath(answers, 'defaults.remoteWebPort'),
+      localPortRange: [...getByPath(answers, 'defaults.localPortRange')],
+    },
+    hosts,
+  };
+}
+
+/** 第 4 步预览：2 空格缩进的完整 config JSON。 */
+export function previewJson(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}

package/src/web/sse.js

@@ -0,0 +1,118 @@
+/**
+ * 唯一 EventSource 客户端（10 §6 / UI-05、UI-06）。
+ *
+ * 后端首帧就是 snapshot（13 §3.2），所以不需要 300ms 静默窗口去抖：
+ * 收到 snapshot 即视为全量同步完成，resyncing 清零。
+ * 不自建重连循环——浏览器原生重连已足够；只在 pageshow / bfcache 恢复时重建。
+ */
+
+const FRAME_TYPES = ['snapshot', 'host-changed', 'log-line', 'operation-done', 'config-changed'];
+
+export function createSseClient({ store, url = '/api/events', onSnapshot = null, factory = null }) {
+  const make = factory ?? ((u) => new EventSource(u));
+  let es = null;
+  let closed = false;
+
+  const parse = (raw) => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      store.addToast({ level: 'warn', summary: 'SSE 帧解析失败（已忽略该帧）', detail: String(raw).slice(0, 400) });
+      return null;
+    }
+  };
+
+  const handlers = {
+    snapshot(frame) {
+      store.applySnapshot(frame);
+      onSnapshot?.(frame);
+    },
+    'host-changed': (frame) => store.applyHostChanged(frame),
+    'log-line': (frame) => store.appendEvent(frame),
+    'operation-done': (frame) => {
+      const settled = store.settleByOperation(frame.operationId);
+      if (frame.status === 'failed') {
+        store.addToast({
+          level: 'error',
+          summary: `${frame.host ?? 'manager'} ${frame.action} 失败：${frame.error ?? '未知原因'}`,
+          detail: frame.detail ?? null,
+        });
+      } else if (settled) {
+        store.addToast({ level: 'success', summary: `${frame.host ?? 'manager'} ${frame.action} 完成` });
+      }
+    },
+    'config-changed': (frame) => store.applyConfigChanged(frame),
+  };
+
+  function connect() {
+    if (closed || es) return;
+    store.setConnection({ sse: store.state.connection.everOpened ? 'reconnecting' : 'connecting' });
+    es = make(url);
+
+    es.addEventListener('open', () => {
+      // 断线恢复也走 snapshot：横幅在 snapshot 到达后才撤，避免露出旧数据
+      store.setConnection({ sse: 'open', resyncing: store.state.connection.everOpened });
+    });
+
+    es.addEventListener('error', () => {
+      // readyState CLOSED 时浏览器已放弃；否则它会自己退避重连
+      const dead = es?.readyState === 2;
+      store.setConnection({ sse: dead ? 'offline' : 'reconnecting' });
+      if (dead) {
+        es?.close();
+        es = null;
+      }
+    });
+
+    for (const type of FRAME_TYPES) {
+      es.addEventListener(type, (ev) => {
+        const frame = parse(ev.data);
+        if (!frame) return;
+        store.setConnection({ lastEventAt: Date.now() });
+        handlers[type](frame);
+      });
+    }
+  }
+
+  function close() {
+    closed = true;
+    es?.close();
+    es = null;
+    store.setConnection({ sse: 'offline' });
+  }
+
+  /** bfcache 返回时 EventSource 可能已死：只在确实断了才重建，避免多连接。 */
+  function revive() {
+    closed = false;
+    if (es && es.readyState !== 2) return;
+    es?.close();
+    es = null;
+    connect();
+  }
+
+  function attachLifecycle(win = window) {
+    const onHide = () => {
+      es?.close();
+      es = null;
+      store.setConnection({ sse: 'offline' });
+    };
+    win.addEventListener('pagehide', onHide);
+    win.addEventListener('pageshow', revive);
+    return () => {
+      win.removeEventListener('pagehide', onHide);
+      win.removeEventListener('pageshow', revive);
+    };
+  }
+
+  return { connect, close, revive, attachLifecycle, get raw() { return es; } };
+}
+
+/** 横幅文案（纯函数，便于单测覆盖 10 §3.11 的四种情形）。 */
+export function bannerText(connection, { managerRestarting = false } = {}) {
+  if (managerRestarting) return 'manager 正在重启，稍后自动重连…';
+  const { sse, everOpened, resyncing } = connection;
+  if (sse === 'open') return resyncing ? '已重新连上 manager，正在同步状态…' : null;
+  if (!everOpened) return sse === 'offline' ? '无法连接 manager，请确认服务已启动' : '正在连接 manager…';
+  if (sse === 'offline') return '与 manager 失联且已停止重连；请检查 manager 进程后刷新页面';
+  return '与 manager 失联，正在重连；写操作已暂停。';
+}