@shendeguize/remote-dsh-center 0.4.0

package/src/web/form.js

@@ -0,0 +1,220 @@
+/**
+ * 表单校验与解析（10 §3.7 / UI-19、UI-23）。
+ *
+ * 纯函数区（本文件上半）与后端 src/lib/validate.js 的约束保持双层一致：
+ * 前端只做即时提示，落盘对错以后端 400 VALIDATION 为准。
+ */
+
+import { BINDABLE_PORT_MIN, PORT_MAX, PORT_MIN } from './setup-schema.js';
+
+export const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function parsePort(raw, {
+  field = 'port', allowEmpty = false, min = PORT_MIN, max = PORT_MAX,
+} = {}) {
+  const s = String(raw ?? '').trim();
+  if (s === '') {
+    if (allowEmpty) return { ok: true, value: null };
+    return { ok: false, error: `${field} 不能为空` };
+  }
+  if (!/^\d+$/.test(s)) return { ok: false, error: `${field} 必须是整数` };
+  const n = Number(s);
+  if (n < min || n > max) return { ok: false, error: `${field} 须在 ${min}–${max} 之间` };
+  return { ok: true, value: n };
+}
+
+/** 本机端口区间：需成对、有序，且宽度足够容纳预期主机数。 */
+export function parsePortRange(rawFrom, rawTo, { minWidth = 1 } = {}) {
+  const from = parsePort(rawFrom, { field: '区间起点', min: BINDABLE_PORT_MIN });
+  if (!from.ok) return from;
+  const to = parsePort(rawTo, { field: '区间终点', min: BINDABLE_PORT_MIN });
+  if (!to.ok) return to;
+  if (to.value < from.value) return { ok: false, error: '区间终点必须 ≥ 起点' };
+  const width = to.value - from.value + 1;
+  if (width < minWidth) return { ok: false, error: `区间至少需要 ${minWidth} 个端口，当前 ${width}` };
+  return { ok: true, value: [from.value, to.value] };
+}
+
+/**
+ * `KEY=VALUE` 多行文本 → 对象。值可含 `=`，只切第一个。
+ * @returns {{ok:true,value:Record<string,string>}|{ok:false,error:string}}
+ */
+export function parseEnvLines(textValue) {
+  const out = {};
+  const lines = String(textValue ?? '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) return { ok: false, error: `第 ${i + 1} 行不是 KEY=VALUE 形式` };
+    const key = line.slice(0, eq).trim();
+    if (!ENV_KEY_RE.test(key)) return { ok: false, error: `第 ${i + 1} 行键名 "${key}" 非法（须匹配 ^[A-Za-z_][A-Za-z0-9_]*$）` };
+    if (key in out) return { ok: false, error: `第 ${i + 1} 行键名 "${key}" 重复` };
+    out[key] = line.slice(eq + 1).trim();
+  }
+  return { ok: true, value: out };
+}
+
+export function formatEnvLines(env) {
+  return Object.entries(env ?? {}).map(([k, v]) => `${k}=${v}`).join('\n');
+}
+
+/** 每行一项的列表（extraArgs / patches）。空行忽略，保持顺序。 */
+export function parseLines(textValue) {
+  return String(textValue ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l !== '');
+}
+
+export function formatLines(list) {
+  return (list ?? []).join('\n');
+}
+
+/** 与后端 shq.isWorkdirPath 双层一致：只认绝对路径与 `~` 前缀。 */
+export const WORKDIR_RE = /^(?:\/|~$|~\/)/;
+
+/**
+ * 远端启动目录。留空 = null = 维持现状（远端家目录）。
+ * @returns {{ok:true,value:string|null}|{ok:false,error:string}}
+ */
+export function parseWorkdir(raw) {
+  const s = String(raw ?? '').trim();
+  if (s === '') return { ok: true, value: null };
+  if (!WORKDIR_RE.test(s)) {
+    return { ok: false, error: '须是绝对路径（/ 开头）或 ~、~/… 形态；相对路径无从解释' };
+  }
+  return { ok: true, value: s };
+}
+
+/** patches 必须是绝对路径（本机文件才可能被 scp 上去）。 */
+export function validatePatches(list) {
+  for (const p of list) {
+    if (!p.startsWith('/')) return { ok: false, error: `patch 路径必须是绝对路径：${p}` };
+  }
+  return { ok: true, value: list };
+}
+
+/**
+ * 主机注入表单 → PUT /api/hosts/:name/config 请求体。
+ * @param {{enabled:boolean, remoteWebPort:string, workdir:string,
+ *          env:string, extraArgs:string, patches:string}} raw
+ */
+export function buildHostPatch(raw) {
+  const errors = {};
+  const port = parsePort(raw.remoteWebPort, { field: '远端端口', allowEmpty: true });
+  if (!port.ok) errors.remoteWebPort = port.error;
+
+  const workdir = parseWorkdir(raw.workdir);
+  if (!workdir.ok) errors.workdir = workdir.error;
+
+  const env = parseEnvLines(raw.env);
+  if (!env.ok) errors.env = env.error;
+
+  const patches = validatePatches(parseLines(raw.patches));
+  if (!patches.ok) errors.patches = patches.error;
+
+  if (Object.keys(errors).length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    value: {
+      enabled: Boolean(raw.enabled),
+      remoteWebPort: port.value,
+      workdir: workdir.value,
+      inject: { env: env.value, extraArgs: parseLines(raw.extraArgs), patches: patches.value },
+    },
+  };
+}
+
+/** 全局默认表单 → PUT /api/config/defaults 请求体。 */
+export function buildDefaultsPatch(raw, { minWidth = 1 } = {}) {
+  const errors = {};
+  const remote = parsePort(raw.remoteWebPort, { field: '远端默认端口' });
+  if (!remote.ok) errors.remoteWebPort = remote.error;
+
+  const range = parsePortRange(raw.rangeFrom, raw.rangeTo, { minWidth });
+  if (!range.ok) errors.localPortRange = range.error;
+
+  const managerPort = parsePort(raw.managerPort, { field: 'manager 端口' });
+  if (!managerPort.ok) errors.managerPort = managerPort.error;
+
+  if (Object.keys(errors).length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    value: {
+      remoteWebPort: remote.value,
+      localPortRange: range.value,
+      manager: { port: managerPort.value },
+    },
+  };
+}
+
+/** 只提交真正改动的键，避免把未触碰的字段“全量替换”成当前显示值。 */
+export function diffPatch(patch, current) {
+  const out = {};
+  for (const [key, value] of Object.entries(patch)) {
+    if (!deepEqual(value, current?.[key])) out[key] = value;
+  }
+  return out;
+}
+
+export function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+
+// ── DOM 助手（调用时才碰 document） ─────────────────────────────────────
+
+/**
+ * 带 label / 错误位的字段行。
+ * @returns {{root:HTMLElement, input:HTMLElement, setError:(msg:string|null)=>void}}
+ */
+export function field(label, input, { hint = null } = {}) {
+  const id = input.id || `f-${Math.random().toString(36).slice(2, 9)}`;
+  input.id = id;
+  const err = document.createElement('p');
+  err.className = 'field-error';
+  err.hidden = true;
+  const root = document.createElement('div');
+  root.className = 'field';
+  const lab = document.createElement('label');
+  lab.setAttribute('for', id);
+  lab.textContent = label;
+  root.append(lab, input);
+  if (hint) {
+    const h = document.createElement('p');
+    h.className = 'field-hint';
+    h.textContent = hint;
+    root.append(h);
+  }
+  root.append(err);
+  return {
+    root,
+    input,
+    setError(msg) {
+      err.textContent = msg ?? '';
+      err.hidden = !msg;
+      root.classList.toggle('has-error', Boolean(msg));
+      input.setAttribute('aria-invalid', msg ? 'true' : 'false');
+    },
+  };
+}
+
+export function input(type, value, props = {}) {
+  const node = document.createElement(type === 'textarea' ? 'textarea' : 'input');
+  if (type !== 'textarea') node.type = type;
+  if (type === 'checkbox') node.checked = Boolean(value);
+  else node.value = value === null || value === undefined ? '' : String(value);
+  for (const [k, v] of Object.entries(props)) {
+    if (v === null || v === undefined) continue;
+    if (k === 'on') for (const [evt, fn] of Object.entries(v)) node.addEventListener(evt, fn);
+    else node.setAttribute(k, String(v));
+  }
+  return node;
+}

package/src/web/host-presentation.js

@@ -0,0 +1,73 @@
+/**
+ * Hub、overflow 等消费者共享的主机展示语义。
+ *
+ * 本模块只处理 HostView 数据，不读取或创建 DOM。
+ */
+
+import {
+  DASH,
+  dshSummary,
+  mappingSummary,
+  phaseHint,
+  phaseMeta,
+} from './utils.js';
+
+const LOCAL_PHASE_META = Object.freeze({
+  unreachable: Object.freeze({ label: '本机不可用', tone: 'neutral', dot: 'none' }),
+  no_dsh: Object.freeze({ label: '本机未安装或未配置', tone: 'neutral', dot: 'none' }),
+});
+
+const LOCAL_NO_DSH_HINT = Object.freeze({
+  'missing-bin': '本机未安装 dsh',
+  'no-web-profile': '本机 dsh 未配置 web profile',
+});
+
+function frozenCopy(value) {
+  return Object.freeze({ ...value });
+}
+
+function isLocalHost(host) {
+  return host?.local === true;
+}
+
+export function hostPhaseMeta(host) {
+  const meta = isLocalHost(host)
+    ? (LOCAL_PHASE_META[host?.phase] ?? phaseMeta(host?.phase))
+    : phaseMeta(host?.phase);
+  return frozenCopy(meta);
+}
+
+export function hostPhaseHint(host) {
+  if (!isLocalHost(host)) return phaseHint(host);
+  if (host?.phase === 'no_dsh') {
+    return LOCAL_NO_DSH_HINT[host.probe?.noDshReason] ?? '';
+  }
+  if (host?.phase === 'unreachable') {
+    return host.probe?.errorSummary || '本机命令执行失败';
+  }
+  return phaseHint(host);
+}
+
+export function hostDshSummary(host) {
+  const summary = dshSummary(host);
+  if (isLocalHost(host) && host?.phase === 'no_dsh') {
+    return frozenCopy({ ...summary, line2: hostPhaseHint(host) });
+  }
+  return frozenCopy(summary);
+}
+
+export function hostMappingSummary(host) {
+  if (!isLocalHost(host)) return frozenCopy(mappingSummary(host));
+  if (host?.mappedUrl && host?.tunnel?.localPort != null) {
+    return frozenCopy({
+      line1: `本机 ${host.tunnel.localPort}`,
+      line2: '直连 dsh web',
+      url: host.mappedUrl,
+    });
+  }
+  return frozenCopy({ line1: DASH, line2: '', url: null });
+}
+
+export function hostStatusText(host, { disabled = false } = {}) {
+  return disabled ? '已禁用' : hostPhaseMeta(host).label;
+}

package/src/web/host-rules.js

@@ -0,0 +1,76 @@
+/**
+ * 页面共享的主机分类与生命周期规则。
+ *
+ * 纯数据、纯函数：不依赖 DOM 或 Node，Hub、Tab 与动作入口都应消费这里的语义。
+ */
+
+export const PRIMARY_HOST_PHASES = Object.freeze([
+  'ready',
+  'starting',
+  'running',
+  'degraded',
+  'crashed',
+]);
+
+export function isPrimaryHostPhase(phase) {
+  return PRIMARY_HOST_PHASES.includes(phase);
+}
+
+export function isHostEnabled(host) {
+  return (host?.config?.enabled ?? host?.enabled) === true;
+}
+
+export function isManagedHost(host) {
+  return host?.web?.startedByUs === true;
+}
+
+export function isPrimaryHost(host) {
+  return isHostEnabled(host) && isPrimaryHostPhase(host?.phase);
+}
+
+/** @param {Iterable<object>} hosts */
+export function primaryHosts(hosts) {
+  return [...hosts]
+    .filter(isPrimaryHost)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const ACTIONS = Object.freeze({
+  probe: Object.freeze(['probe']),
+  ready: Object.freeze(['start', 'probe']),
+  starting: Object.freeze(['open', 'probe']),
+  managedRunning: Object.freeze(['open', 'restart', 'stop', 'probe']),
+  managedDegraded: Object.freeze(['open', 'reconnect', 'restart', 'stop', 'probe']),
+  managedCrashed: Object.freeze(['open', 'restart', 'probe']),
+  manualRunning: Object.freeze(['open', 'probe']),
+  manualDegraded: Object.freeze(['open', 'reconnect', 'probe']),
+  manualCrashed: Object.freeze(['start', 'probe']),
+});
+
+/**
+ * 返回当前生命周期允许的不可变动作列表。
+ *
+ * 后端契约：stop 只接受 running/degraded 且必须 startedByUs；reconnect 接受
+ * degraded/running 且不检查 startedByUs。页面只把 reconnect 暴露在 degraded；
+ * running 的竞态请求由 actions.js 判为「已自行恢复」。
+ */
+export function allowedHostActions(host) {
+  switch (host?.phase) {
+    case 'ready':
+      return ACTIONS.ready;
+    case 'starting':
+      return ACTIONS.starting;
+    case 'running':
+      return isManagedHost(host) ? ACTIONS.managedRunning : ACTIONS.manualRunning;
+    case 'degraded':
+      return isManagedHost(host) ? ACTIONS.managedDegraded : ACTIONS.manualDegraded;
+    case 'crashed':
+      return isManagedHost(host) ? ACTIONS.managedCrashed : ACTIONS.manualCrashed;
+    default:
+      return ACTIONS.probe;
+  }
+}
+
+export function isHostActionAllowed(host, action) {
+  return allowedHostActions(host).includes(action);
+}

package/src/web/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DSH Center</title>
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/style.css">
+</head>
+<body>
+<div id="app"><p class="empty-hint">正在加载…</p></div>
+<script type="module">
+  import { bootApp } from '/app.js';
+  bootApp();
+</script>
+</body>
+</html>

package/src/web/router.js

@@ -0,0 +1,118 @@
+/**
+ * hash 路由与 setup 守卫（10 §5）。解析部分是纯函数（DOM-free，可单测）；
+ * 只有 attachRouter 触碰 location。
+ */
+
+import { isHostEnabled } from './host-rules.js';
+
+/**
+ * @param {string} hash
+ * @returns {{kind:'root'|'hub'|'manage'|'host'|'setup'|'invalid', host:string|null, raw:string}}
+ */
+export function parseRoute(hash) {
+  const raw = typeof hash === 'string' && hash !== '' ? hash : '#/';
+  const path = raw.replace(/^#/, '');
+
+  if (path === '' || path === '/') return { kind: 'root', host: null, raw: '#/' };
+  if (path === '/hub') return { kind: 'hub', host: null, raw: '#/hub' };
+  if (path === '/manage') return { kind: 'manage', host: null, raw: '#/manage' };
+  if (path === '/setup') return { kind: 'setup', host: null, raw: '#/setup' };
+
+  const m = /^\/host\/([^/]+)$/.exec(path);
+  if (m) {
+    let host;
+    try {
+      host = decodeURIComponent(m[1]);
+    } catch {
+      return { kind: 'invalid', host: null, raw };
+    }
+    if (host === '') return { kind: 'invalid', host: null, raw };
+    return { kind: 'host', host, raw: `#/host/${m[1]}` };
+  }
+
+  return { kind: 'invalid', host: null, raw };
+}
+
+export function hostRoute(name) {
+  return `#/host/${encodeURIComponent(name)}`;
+}
+
+export const LAST_HOST_KEY = 'dshc.lastHost';
+
+/** localStorage 可能被禁用或由隐私策略拒绝，浏览器偏好失败不能阻断路由。 */
+export function readLastHost(storage) {
+  try {
+    const target = storage === undefined ? globalThis.localStorage : storage;
+    const value = target?.getItem(LAST_HOST_KEY);
+    return typeof value === 'string' && value !== '' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function rememberLastHost(name, storage) {
+  if (typeof name !== 'string' || name === '') return false;
+  try {
+    const target = storage === undefined ? globalThis.localStorage : storage;
+    if (!target?.setItem) return false;
+    target.setItem(LAST_HOST_KEY, name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** manager 与主机清单就绪后，为动态根路由选取最终落点。 */
+export function rootRouteTarget(hosts, storage) {
+  const lastHost = readLastHost(storage);
+  if (lastHost) {
+    for (const host of hosts) {
+      if (host?.name === lastHost && isHostEnabled(host) && canOpenHost(host)) return hostRoute(lastHost);
+    }
+  }
+  return '#/hub';
+}
+
+/**
+ * setup 守卫（10 §5.2）：未初始化时任何路由都改写到 #/setup；
+ * setupCompleted 未知时先渲染骨架，避免主界面闪现。非法路由统一归到 hub。
+ * @returns {{route:object, redirectTo:string|null, blocked:boolean}}
+ */
+export function applyGuard(route, { setupCompleted }) {
+  if (setupCompleted === null || setupCompleted === undefined) {
+    return { route, redirectTo: null, blocked: true };
+  }
+  if (setupCompleted === false && route.kind !== 'setup') {
+    return { route: { kind: 'setup', host: null, raw: '#/setup' }, redirectTo: '#/setup', blocked: false };
+  }
+  if (route.kind === 'invalid') {
+    return { route: { kind: 'hub', host: null, raw: '#/hub' }, redirectTo: '#/hub', blocked: false };
+  }
+  return { route, redirectTo: null, blocked: false };
+}
+
+/** 主机路由是否可落地：starting 先落占位遮罩，其余三态承载已有/可建 iframe。 */
+export function canOpenHost(host) {
+  if (!host) return false;
+  return ['starting', 'running', 'degraded', 'crashed'].includes(host.phase);
+}
+
+/**
+ * 绑定 hashchange。返回 detach。
+ * @param {(route:object)=>void} onRoute
+ */
+export function attachRouter(onRoute, { win = window } = {}) {
+  const handle = () => onRoute(parseRoute(win.location.hash));
+  win.addEventListener('hashchange', handle);
+  handle();
+  return () => win.removeEventListener('hashchange', handle);
+}
+
+export function navigate(to, { win = window, replace = false } = {}) {
+  if (win.location.hash === to) {
+    win.dispatchEvent(new win.HashChangeEvent('hashchange'));
+    return;
+  }
+  if (replace) win.location.replace(to);
+  else win.location.hash = to;
+}