@shendeguize/remote-dsh-center 0.4.0

package/src/web/actions.js

@@ -0,0 +1,409 @@
+/**
+ * 动作层（10 §4.5 / UI-09）：请求 → pending → 202 结算 → 超时兜底 → 错误 toast。
+ *
+ * 铁律：这里绝不擅改 host.phase，phase 只由 SSE 推进。
+ */
+
+import { ApiError, api } from './api.js';
+import { isHostEnabled, isManagedHost } from './host-rules.js';
+import { ACTION_TIMEOUT_MS, pendingKey } from './store.js';
+import { phaseMeta } from './utils.js';
+
+const CALL = {
+  start: api.startHost,
+  stop: api.stopHost,
+  restart: api.restartHost,
+  reconnect: api.reconnectHost,
+  probe: api.probeHost,
+};
+
+const NEEDS_CONFIRM = new Set(['stop', 'restart']);
+export const CONFIG_SYNC_TARGET_LIMIT = 200;
+export const HOST_WEB_RESTART_NOTICE = '需重启此主机的 dsh web（重启 manager 无效）';
+const HOST_RESTART_PHASES = new Set(['running', 'degraded', 'starting']);
+
+function workdirChangePending(patch, hostBeforeSave, savedHost) {
+  if (!Object.hasOwn(patch, 'workdir') || !HOST_RESTART_PHASES.has(savedHost?.phase)) {
+    return false;
+  }
+
+  const savedWorkdir = savedHost.config?.workdir ?? null;
+  if (savedHost.web) return (savedHost.web.workdir ?? null) !== savedWorkdir;
+
+  return savedHost.phase === 'starting'
+    && hostBeforeSave?.phase === 'starting'
+    && (hostBeforeSave.config?.workdir ?? null) !== savedWorkdir;
+}
+
+export function createActions({ store, confirm, navigate }) {
+  /** 统一错误呈现：ApiError 的 detail 落可展开区域（10 §3.9）。 */
+  function reportError(err, fallback, { preferFallback = false } = {}) {
+    let presentation;
+    if (err instanceof ApiError) {
+      const apiDetail = err.detail ? String(err.detail) : null;
+      const detail = preferFallback
+        ? [err.message && err.message !== fallback ? err.message : null, apiDetail].filter(Boolean).join('\n') || null
+        : apiDetail;
+      presentation = {
+        level: 'error',
+        summary: preferFallback ? fallback : (err.message || fallback),
+        detail,
+      };
+    } else {
+      presentation = {
+        level: 'error',
+        summary: `${fallback}：${err.message}`,
+        detail: err.stack ?? null,
+      };
+    }
+    const toast = store.addToast(presentation);
+    return {
+      ...presentation,
+      id: toast.id,
+      code: err instanceof ApiError ? err.code : null,
+      status: err instanceof ApiError ? err.status : null,
+    };
+  }
+
+  /**
+   * 包住一次受保护操作：pending 生命周期 + 202 accepted + 超时只解 loading。
+   * @param {{
+   *   action:string, host?:string|null, run:()=>Promise<any>,
+   *   settleOnResolve?:boolean, failureMessage?:string, requireWritable?:boolean,
+   *   onError?:(toast:{
+   *     id:number,level:string,summary:string,detail:string|null,
+   *     code:string|null,status:number|null,
+   *   })=>void,
+   * }} opts
+   */
+  async function guarded({
+    action,
+    host = null,
+    run,
+    settleOnResolve = false,
+    failureMessage,
+    onError,
+    requireWritable = true,
+  }) {
+    if (requireWritable && !store.canWrite()) {
+      const presentation = {
+        level: 'warn',
+        summary: '与 manager 失联，写操作已暂停',
+        detail: null,
+      };
+      const toast = store.addToast(presentation);
+      onError?.({
+        ...presentation,
+        id: toast.id,
+        code: null,
+        status: null,
+      });
+      return null;
+    }
+    if (store.isPending(action, host)) return null;
+
+    const key = pendingKey(action, host);
+    store.beginPending({ action, host });
+    try {
+      const res = await run();
+      if (settleOnResolve) {
+        store.settlePending(key);
+        return res;
+      }
+      store.acceptPending(key, res?.operationId ?? null, (entry) => {
+        store.addToast({
+          level: 'warn',
+          summary: `${entry.host ?? 'manager'} ${entry.action} 结果未确认（${ACTION_TIMEOUT_MS[entry.action] / 1000}s 未回执）`,
+          detail: '请以当前状态为准，或重新探测。manager 侧可能仍在执行。',
+        });
+      });
+      return res;
+    } catch (err) {
+      store.settlePending(key);
+      const errorToast = reportError(
+        err,
+        failureMessage ?? `${host ?? 'manager'} ${action} 失败`,
+        { preferFallback: failureMessage !== undefined },
+      );
+      onError?.(errorToast);
+      return null;
+    }
+  }
+
+  async function hostAction(action, name) {
+    const host = store.getHost(name);
+    if (!host) {
+      store.addToast({ level: 'warn', summary: `主机 ${name} 不存在或尚未同步` });
+      return null;
+    }
+    // 点击前重新读 store：自动恢复可能已经跑在手动重连之前（10 §7 第 12 条）
+    if (action === 'reconnect' && host.phase === 'running') {
+      store.addToast({ level: 'info', summary: `${name} 隧道已自行恢复，无需重连` });
+      return null;
+    }
+    if (NEEDS_CONFIRM.has(action) && !isManagedHost(host)) {
+      store.addToast({ level: 'warn', summary: `${name} 上的 dsh web 不是本工具拉起的，禁止 ${action}` });
+      return null;
+    }
+    if (NEEDS_CONFIRM.has(action)) {
+      const ok = await confirm({
+        title: action === 'stop' ? `关停 ${name} 的 dsh web？` : `重启 ${name} 的 dsh web？`,
+        lines: [
+          `进程 PID ${host.web?.pid ?? '—'}，当前状态「${phaseMeta(host.phase).label}」。`,
+          '仅关停由本工具拉起且指纹校验通过的进程；页面内未保存的会话会中断。',
+        ],
+        confirmLabel: action === 'stop' ? '关停' : '重启',
+      });
+      if (!ok) return null;
+    }
+
+    return guarded({ action, host: name, run: () => CALL[action](name) });
+  }
+
+  async function probeAll({ failureMessage } = {}) {
+    return guarded({ action: 'probe-all', failureMessage, run: () => api.probeAll() });
+  }
+
+  /** 创建响应先落服务端 HostView，再复用既有 probe pending；phase 仍只由响应/SSE 决定。 */
+  async function addLocalHost(name) {
+    const requestedName = typeof name === 'string' ? name.trim() : '';
+    const created = await guarded({
+      action: 'local:create',
+      settleOnResolve: true,
+      run: () => api.createLocalHost(requestedName || undefined),
+    });
+    if (!created?.host) return created;
+
+    const hostName = created.host.name;
+    store.upsertHost(created.host);
+    store.addToast({ level: 'success', summary: `已添加本机 ${hostName}，正在探测`, timeoutMs: 4_000 });
+    await guarded({
+      action: 'probe',
+      host: hostName,
+      run: () => api.probeHost(hostName),
+    });
+    return created;
+  }
+
+  /** toggle 走 config:save 通道；失败时用响应/回滚保持与服务端一致（10 §7 第 4 条）。 */
+  async function setAutoStart(name, value) {
+    const host = store.getHost(name);
+    if (!host) return null;
+    const res = await guarded({
+      action: 'config:save',
+      host: name,
+      settleOnResolve: true,
+      run: () => api.saveHostConfig(name, { autoStart: value }),
+    });
+    if (res?.host) store.upsertHost(res.host);
+    else store.emit('hosts:changed', name); // 失败：用本地已有视图复位复选框
+    return res;
+  }
+
+  async function saveHostConfig(name, patch) {
+    const hostBeforeSave = store.getHost(name);
+    let hostMergeGuard = null;
+    const res = await guarded({
+      action: 'config:save',
+      host: name,
+      settleOnResolve: true,
+      run: () => {
+        hostMergeGuard = store.captureHostMergeGuard();
+        return api.saveHostConfig(name, patch);
+      },
+    });
+    if (res?.host && hostMergeGuard !== null) {
+      store.mergeActionHosts([res.host], hostMergeGuard);
+    }
+    if (res?.host && store.getHost(name)) {
+      const restartNotice = workdirChangePending(patch, hostBeforeSave, res.host)
+        ? `；${HOST_WEB_RESTART_NOTICE}`
+        : '';
+      store.addToast({ level: 'success', summary: `${name} 配置已保存${restartNotice}` });
+    }
+    return res;
+  }
+
+  async function syncConfig({
+    source, targets, dryRun, previewToken, onError,
+  }) {
+    if (targets.length > CONFIG_SYNC_TARGET_LIMIT) {
+      store.addToast({
+        level: 'warn',
+        summary: `一次最多同步 ${CONFIG_SYNC_TARGET_LIMIT} 台目标主机`,
+        detail: '请减少目标后重试；配置同步按整单原子执行，不会自动拆分。',
+      });
+      return null;
+    }
+    let hostMergeGuard = null;
+    const res = await guarded({
+      action: 'config:sync',
+      settleOnResolve: true,
+      onError,
+      run: () => {
+        hostMergeGuard = store.captureHostMergeGuard();
+        return api.syncHostConfig({
+          source, targets, dryRun, previewToken,
+        });
+      },
+    });
+    if (!res || dryRun) return res;
+
+    if (Array.isArray(res.hosts) && hostMergeGuard !== null) {
+      store.mergeActionHosts(res.hosts, hostMergeGuard);
+    }
+    const count = Array.isArray(res.applied) ? res.applied.length : 0;
+    const restartTargets = (res.targets ?? [])
+      .filter((target) => target.changed && HOST_RESTART_PHASES.has(store.getHost(target.name)?.phase))
+      .map((target) => target.name);
+    const restartSummary = restartTargets.length > 0
+      ? '；运行中目标需重启 dsh web（重启 manager 无效）'
+      : '';
+    store.addToast({
+      level: 'success',
+      summary: count > 0 ? `已同步 ${count} 台主机配置${restartSummary}` : '目标配置已一致',
+      detail: restartTargets.length > 0
+        ? restartTargets.map((name) => `${name}：${HOST_WEB_RESTART_NOTICE}`).join('\n')
+        : null,
+    });
+    return res;
+  }
+
+  async function loadDshSettings(name, { onError } = {}) {
+    return guarded({
+      action: 'settings:load',
+      host: name,
+      settleOnResolve: true,
+      onError,
+      requireWritable: false,
+      run: () => api.getDshSettings(name),
+    });
+  }
+
+  async function saveDshSettings(name, payload, { onError } = {}) {
+    return guarded({
+      action: 'settings:save',
+      host: name,
+      settleOnResolve: true,
+      onError,
+      run: () => api.saveDshSettings(name, payload),
+    });
+  }
+
+  async function registerDshWorkspace(name, { onError } = {}) {
+    const res = await guarded({
+      action: 'workspace:register',
+      host: name,
+      settleOnResolve: true,
+      onError,
+      run: () => api.registerDshWorkspace(name),
+    });
+    if (res) {
+      store.addToast({
+        level: 'success',
+        summary: res.created
+          ? `${name} 已登记启动目录为 dsh Workspace`
+          : `${name} 的启动目录已是 dsh Workspace`,
+      });
+    }
+    return res;
+  }
+
+  async function saveDefaults(patch) {
+    const res = await guarded({
+      action: 'defaults:save',
+      settleOnResolve: true,
+      run: () => api.saveDefaults(patch),
+    });
+    if (res) {
+      store.setDefaults(res.defaults);
+      if (res.manager) store.setManagerConfig(res.manager);
+      store.addToast({
+        level: 'success',
+        summary: res.restartRequired ? '已保存；manager 端口需重启后生效' : '全局默认已保存',
+      });
+    }
+    return res;
+  }
+
+  async function reload() {
+    const res = await guarded({ action: 'config:reload', settleOnResolve: true, run: () => api.reload() });
+    if (res) {
+      store.addToast({
+        level: 'success',
+        summary: res.changed.length > 0 ? `已重载配置（${res.changed.length} 项变化）` : '配置无变化',
+        detail: res.changed.length > 0 ? res.changed.join('\n') : null,
+      });
+    }
+    return res;
+  }
+
+  async function restartManager() {
+    const ok = await confirm({
+      title: '重启 manager？',
+      lines: [
+        '存活的受管实例会按原 PID 与命令指纹复核接管，只重建隧道或直连登记：远端重建隧道、本机重新登记直连；不会重启这些 dsh web。',
+        '只有恢复时探测为 ready 且已启用 autoStart 的主机才会拉起 dsh web；已打开的页面标签会短暂失联。',
+        '前台模式不支持自我重启，manager 会直接拒绝。',
+      ],
+      confirmLabel: '重启',
+    });
+    if (!ok) return null;
+    return guarded({ action: 'manager:restart', run: () => api.restartManager() });
+  }
+
+  function openHost(name) {
+    const host = store.getHost(name);
+    if (!host) {
+      store.addToast({ level: 'warn', summary: `主机 ${name} 不存在或尚未同步` });
+      return;
+    }
+    // ready 标签就是「一步拉起」入口：先提交启动，再立即切路由；phase 仍只等
+    // 响应/SSE 推进，绝不在动作层乐观改成 running。
+    if (host.phase === 'ready' && isHostEnabled(host)) void hostAction('start', name);
+    navigate(`#/host/${encodeURIComponent(name)}`);
+  }
+
+  function openHostDrawer(name) {
+    store.setDrawer({ open: true, host: name, dirty: false });
+  }
+
+  function viewHostInManage(name) {
+    if (!store.getHost(name)) {
+      store.addToast({ level: 'warn', summary: `主机 ${name} 不存在或尚未同步` });
+      return;
+    }
+    navigate('#/manage');
+    openHostDrawer(name);
+  }
+
+  async function loadHostLog(name, lines = 200) {
+    try {
+      return await api.hostLog(name, lines);
+    } catch (err) {
+      reportError(err, `${name} 日志拉取失败`);
+      return null;
+    }
+  }
+
+  return {
+    navigate,
+    hostAction,
+    probeAll,
+    addLocalHost,
+    setAutoStart,
+    saveHostConfig,
+    syncConfig,
+    loadDshSettings,
+    saveDshSettings,
+    registerDshWorkspace,
+    saveDefaults,
+    reload,
+    restartManager,
+    openHost,
+    openHostDrawer,
+    viewHostInManage,
+    loadHostLog,
+    reportError,
+  };
+}

package/src/web/api.js

@@ -0,0 +1,262 @@
+/**
+ * REST 客户端（10 §2 / UI-02）。同源相对 URL——页面绝不硬编码运行期端口。
+ * 错误统一抛 ApiError（携带后端 13 §1.1 的 error/code/detail）。
+ */
+
+const JSON_HEADERS = { 'content-type': 'application/json' };
+const DEFAULT_TIMEOUT_MS = 15_000;
+const SETTINGS_TIMEOUT_MS = 30_000;
+const SETTINGS_MUTATION_UNKNOWN_MESSAGE = '保存结果未知，请重新加载后确认';
+const SETTINGS_ERROR_MESSAGES = Object.freeze({
+  SETTINGS_STALE: 'dsh 配置文件已变化，请重新加载后再保存',
+  SETTINGS_TOO_LARGE: 'dsh 配置文件超过大小限制，无法处理',
+  SETTINGS_UNSUPPORTED: '该主机不支持安全编辑 dsh 配置文件',
+  SETTINGS_INVALID_UTF8: 'dsh 配置文件不是有效的 UTF-8 文本',
+  SETTINGS_READ_FAILED: '读取 dsh 配置文件失败，请稍后重试',
+  SETTINGS_WRITE_FAILED: '保存 dsh 配置文件失败，请重新加载确认结果',
+  SETTINGS_BUSY: '该主机已有 dsh 配置操作正在进行，请稍后重试',
+  SSH_TIMEOUT: 'dsh 配置请求超时，请稍后重试',
+  SSH_UNREACHABLE: '无法连接目标主机，请稍后重试',
+  LOCAL_TIMEOUT: '本机 dsh 配置请求超时，请稍后重试',
+  LOCAL_EXEC_FAILED: '本机 dsh 配置操作失败，请稍后重试',
+  LOCAL_COPY_FAILED: '本机 dsh 配置传输失败，请稍后重试',
+  NOT_FOUND: '目标主机不存在或已被删除',
+  VALIDATION: 'dsh 配置请求无效，请检查后重试',
+  PROTO_PARSE: 'dsh 配置响应无法解析，请重试',
+  INTERNAL: 'dsh 配置请求失败，请稍后重试',
+});
+const SETTINGS_MUTATION_UNCERTAIN_CODES = new Set([
+  'SSH_TIMEOUT',
+  'SSH_UNREACHABLE',
+  'LOCAL_TIMEOUT',
+  'LOCAL_EXEC_FAILED',
+  'LOCAL_COPY_FAILED',
+  'PROTO_PARSE',
+  'INTERNAL',
+]);
+const WORKSPACE_ERROR_MESSAGES = Object.freeze({
+  WORKSPACE_BUSY: '该主机已有 dsh Workspace 登记正在进行，请稍后重试',
+  WORKSPACE_WORKDIR_REQUIRED: '请先配置启动目录并重启 dsh web 后再登记',
+  WORKSPACE_CWD_UNAVAILABLE: '当前 dsh web 的实际工作目录不可用，请重启后重试',
+  WORKSPACE_INVALID_PATH: '当前 dsh web 的实际工作目录不是绝对路径，无法登记',
+  WORKSPACE_REGISTER_FAILED: 'dsh Workspace 登记失败，请稍后重试',
+  WORKSPACE_REGISTER_TIMEOUT: 'dsh Workspace 登记超时；可安全重试',
+  NOT_FOUND: '目标主机不存在或已被删除',
+  PHASE_CONFLICT: '主机状态已变化，请确认 dsh web 已连接且启动目录已应用',
+  VALIDATION: 'dsh Workspace 请求无效，请检查启动目录后重试',
+  PROTO_PARSE: 'dsh Workspace 响应无法解析，请重试',
+  INTERNAL: 'dsh Workspace 登记失败，请稍后重试',
+});
+const SETTINGS_REDACTION = Object.freeze({
+  messages: SETTINGS_ERROR_MESSAGES,
+  mutationUnknownMessage: SETTINGS_MUTATION_UNKNOWN_MESSAGE,
+  mutationUncertainCodes: SETTINGS_MUTATION_UNCERTAIN_CODES,
+  timeoutCode: 'SSH_TIMEOUT',
+  timeoutMessage: SETTINGS_ERROR_MESSAGES.SSH_TIMEOUT,
+  internalMessage: SETTINGS_ERROR_MESSAGES.INTERNAL,
+  parseMessage: '响应不是合法 JSON',
+  httpFallback: (status) => `dsh 配置请求失败（HTTP ${status}）`,
+});
+const WORKSPACE_REDACTION = Object.freeze({
+  messages: WORKSPACE_ERROR_MESSAGES,
+  timeoutCode: 'WORKSPACE_REGISTER_TIMEOUT',
+  timeoutMessage: WORKSPACE_ERROR_MESSAGES.WORKSPACE_REGISTER_TIMEOUT,
+  internalMessage: WORKSPACE_ERROR_MESSAGES.INTERNAL,
+  parseMessage: WORKSPACE_ERROR_MESSAGES.PROTO_PARSE,
+  httpFallback: (status) => `dsh Workspace 请求失败（HTTP ${status}）`,
+});
+
+function safeRedactedHttpError(rawCode, status, redaction, mutationResultUnknown) {
+  const known = typeof rawCode === 'string'
+    && Object.hasOwn(redaction.messages, rawCode);
+  const code = known ? rawCode : 'INTERNAL';
+  const message = mutationResultUnknown
+    && (!known || redaction.mutationUncertainCodes?.has(code))
+    ? redaction.mutationUnknownMessage
+    : (known
+      ? redaction.messages[code]
+      : redaction.httpFallback(status));
+  return { code, message };
+}
+
+export class ApiError extends Error {
+  constructor({ status, code, message, detail }) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code ?? 'INTERNAL';
+    this.detail = detail ?? null;
+  }
+}
+
+async function call(method, path, {
+  body,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  as = 'json',
+  redactParseError = false,
+  redactErrorResponse = false,
+  redaction = null,
+  mutationResultUnknown = false,
+} = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  let text;
+  try {
+    res = await fetch(path, {
+      method,
+      headers: body === undefined ? undefined : JSON_HEADERS,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+      cache: 'no-store',
+    });
+    text = await res.text();
+  } catch (err) {
+    const aborted = err?.name === 'AbortError' || controller.signal.aborted;
+    if (!aborted && res && !redactErrorResponse) throw err;
+    throw new ApiError({
+      status: 0,
+      code: aborted ? (redaction?.timeoutCode ?? 'SSH_TIMEOUT') : 'INTERNAL',
+      message: mutationResultUnknown
+        ? redaction?.mutationUnknownMessage ?? SETTINGS_MUTATION_UNKNOWN_MESSAGE
+        : redactErrorResponse
+        ? (aborted
+          ? redaction?.timeoutMessage ?? SETTINGS_ERROR_MESSAGES.SSH_TIMEOUT
+          : redaction?.internalMessage ?? SETTINGS_ERROR_MESSAGES.INTERNAL)
+        : (aborted ? `请求超时（${method} ${path}）` : `无法连接 manager：${err.message}`),
+      detail: null,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!res.ok) {
+    let payload = null;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = null;
+    }
+    const rawCode = typeof payload?.code === 'string' ? payload.code : undefined;
+    const safeError = redactErrorResponse
+      ? safeRedactedHttpError(
+        rawCode,
+        res.status,
+        redaction ?? SETTINGS_REDACTION,
+        mutationResultUnknown,
+      )
+      : null;
+    throw new ApiError({
+      status: res.status,
+      code: safeError?.code ?? rawCode,
+      message: redactErrorResponse
+        ? safeError.message
+        : (payload?.error ?? `${method} ${path} 失败（HTTP ${res.status}）`),
+      detail: redactErrorResponse ? null : (payload?.detail ?? (text || null)),
+    });
+  }
+
+  if (as === 'text') return text;
+  if (text === '') {
+    if (!redactParseError) return null;
+    throw new ApiError({
+      status: res.status,
+      code: 'PROTO_PARSE',
+      message: mutationResultUnknown
+        ? redaction?.mutationUnknownMessage ?? SETTINGS_MUTATION_UNKNOWN_MESSAGE
+        : redaction?.parseMessage ?? '响应不是合法 JSON',
+      detail: null,
+    });
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ApiError({
+      status: res.status,
+      code: 'PROTO_PARSE',
+      message: mutationResultUnknown
+        ? redaction?.mutationUnknownMessage ?? SETTINGS_MUTATION_UNKNOWN_MESSAGE
+        : redaction?.parseMessage ?? '响应不是合法 JSON',
+      detail: redactParseError ? null : text,
+    });
+  }
+}
+
+const enc = encodeURIComponent;
+
+export const api = {
+  managerInfo: () => call('GET', '/api/manager/info'),
+  hosts: () => call('GET', '/api/hosts'),
+  config: () => call('GET', '/api/config'),
+
+  probeAll: () => call('POST', '/api/hosts/probe'),
+  createLocalHost: (name) => call('POST', '/api/hosts/local', {
+    body: name === undefined ? {} : { name },
+  }),
+  probeHost: (name) => call('POST', `/api/hosts/${enc(name)}/probe`),
+  startHost: (name) => call('POST', `/api/hosts/${enc(name)}/start`),
+  stopHost: (name) => call('POST', `/api/hosts/${enc(name)}/stop`),
+  restartHost: (name) => call('POST', `/api/hosts/${enc(name)}/restart`),
+  reconnectHost: (name) => call('POST', `/api/hosts/${enc(name)}/reconnect`),
+  syncHostConfig: ({
+    source, targets, dryRun, previewToken,
+  }) => call('POST', '/api/hosts/sync-config', {
+    body: {
+      source,
+      targets,
+      dryRun,
+      ...(previewToken === undefined ? {} : { previewToken }),
+    },
+  }),
+
+  hostLog: (name, lines = 200) => call('GET', `/api/hosts/${enc(name)}/log?lines=${lines}`, { as: 'text', timeoutMs: 30_000 }),
+  getDshSettings: (name) => call('GET', `/api/hosts/${enc(name)}/dsh-settings`, {
+    timeoutMs: SETTINGS_TIMEOUT_MS,
+    redactParseError: true,
+    redactErrorResponse: true,
+    redaction: SETTINGS_REDACTION,
+  }),
+  saveDshSettings: (name, { content, baseChecksum }) => call(
+    'PUT',
+    `/api/hosts/${enc(name)}/dsh-settings`,
+    {
+      body: { content, baseChecksum },
+      timeoutMs: SETTINGS_TIMEOUT_MS,
+      redactParseError: true,
+      redactErrorResponse: true,
+      redaction: SETTINGS_REDACTION,
+      mutationResultUnknown: true,
+    },
+  ),
+  registerDshWorkspace: (name) => call('POST', `/api/hosts/${enc(name)}/dsh-workspace`, {
+    body: {},
+    timeoutMs: 20_000,
+    redactParseError: true,
+    redactErrorResponse: true,
+    redaction: WORKSPACE_REDACTION,
+  }),
+  saveHostConfig: (name, patch) => call('PUT', `/api/hosts/${enc(name)}/config`, { body: patch }),
+  saveDefaults: (patch) => call('PUT', '/api/config/defaults', { body: patch }),
+  reload: () => call('POST', '/api/reload'),
+
+  setup: (config) => call('POST', '/api/setup', { body: config, timeoutMs: 30_000 }),
+  restartManager: () => call('POST', '/api/manager/restart'),
+  shutdownManager: () => call('POST', '/api/manager/shutdown'),
+
+  /** 迁移页用：探测目标 origin 是否已就绪（10 §3.5，端口来自用户提交值）。 */
+  probeOrigin: async (origin, { timeoutMs = 2_000 } = {}) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${origin}/api/manager/info`, { signal: controller.signal, cache: 'no-store' });
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+};
+
+export { call as rawCall };