@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/plugins/session-router.mjs

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// fang-session-router — hybrid routing between sync (files) and bridge (live sessions).
+//
+// The decision is a pure truth table, exposed for tests and for the panel:
+//   cross-machine + realtime        -> deny (bridge is loopback-only, sync not realtime)
+//   same machine + host + bridge    -> bridge
+//   otherwise                       -> sync
+import { z, roleGate, resolveFangLayout, SERVICE, FANG_VERSION } from '../kernel/index.mjs'
+import { createHttpGuard } from '../lib/http-auth.mjs'
+import { readBridgeDescriptor } from '../lib/bridge-client.mjs'
+
+export const name = 'fang-session-router'
+export const inject = []
+
+export const Config = z.object({
+  sameMachine: z.boolean().default(true)
+    .description('PC 宿主与 Web 母体是否同机（bridge 只支持同机回环）'),
+  bridgeEnabled: z.boolean().default(true)
+    .description('是否允许选择 bridge 模式（descriptor 存在且宿主在跑才会真正选中）'),
+  needsRealtime: z.boolean().default(false)
+    .description('默认是否要求实时（任务级可选择覆盖）'),
+  dshHome: z.string().default('')
+    .description('PC 宿主 DSH_HOME（查找 desktop-bridge.json）；留空 = 本机 $DSH_HOME'),
+  prefix: z.string().default('/fang'),
+  routes: z.object({ enabled: z.boolean().default(true) }).default({}),
+  authToken: z.string().default('')
+    .description('安装级鉴权 token；留空 = env DSH_FANG_AUTH_TOKEN 或 <dataDir>/fang-auth.json（0600，自动生成）'),
+  authEnabled: z.boolean().default(true)
+    .description('是否要求 /fang/api/route 携带安装级鉴权 token（默认开启；仅测试/本地调试可关）'),
+})
+
+/** Pure decision function; `deny` means the request cannot be satisfied honestly. */
+export function chooseMode(context = {}, config = {}) {
+  const sameMachine = context.sameMachine ?? config.sameMachine ?? true
+  const bridgeEnabled = context.bridgeEnabled ?? config.bridgeEnabled ?? true
+  const pcHostRunning = context.pcHostRunning === true
+  const needsRealtime = context.needsRealtime ?? config.needsRealtime ?? false
+  const oneTimeMigration = context.oneTimeMigration === true
+  if (!sameMachine && needsRealtime) return 'deny'
+  if (oneTimeMigration) return 'sync'
+  if (sameMachine && bridgeEnabled && pcHostRunning && needsRealtime) return 'bridge'
+  return 'sync'
+}
+
+export function apply(ctx, config) {
+  const gate = roleGate('sessionRouter', { logger: ctx.logger })
+  if (!gate.active) return
+  const cfg = { ...Config({}), ...(config ?? {}) }
+  const prefix = String(cfg.prefix ?? '/fang').replace(/\/+$/, '') || '/fang'
+  const authGuard = createHttpGuard({
+    dataDir: resolveFangLayout().dataDir,
+    token: cfg.authToken,
+    enabled: cfg.authEnabled !== false,
+  })
+
+  const probe = (context = {}) => {
+    const desc = readBridgeDescriptor({ dshHome: cfg.dshHome })
+    const pcHostRunning = desc.ok
+    const merged = {
+      sameMachine: context.sameMachine ?? cfg.sameMachine,
+      bridgeEnabled: context.bridgeEnabled ?? cfg.bridgeEnabled,
+      needsRealtime: context.needsRealtime ?? cfg.needsRealtime,
+      oneTimeMigration: context.oneTimeMigration === true,
+      pcHostRunning,
+    }
+    const mode = chooseMode(merged, cfg)
+    return {
+      ok: true,
+      role: gate.role,
+      version: FANG_VERSION,
+      mode,
+      reason: mode === 'deny'
+        ? '跨机 + 实时：bridge 只支持回环，sync 不满足实时'
+        : mode === 'bridge'
+          ? '同机 + PC 宿主在跑 + bridge 可用 + 需要实时'
+          : '文件级同步（可离线 / 跨机 / 一次性迁移）',
+      bridge: desc.ok ? { available: true, pid: desc.info.pid } : { available: false, code: desc.code, error: desc.error },
+      context: merged,
+    }
+  }
+
+  const service = {
+    role: gate.role,
+    version: FANG_VERSION,
+    choose: (context) => chooseMode(context, cfg),
+    probe,
+  }
+  ctx.effect(() => ctx.provide(SERVICE.sessionRouter, service))
+
+  if (cfg.routes?.enabled === false) return
+  ctx.inject(['webServer'], (child) => {
+    let webServer = null
+    try { webServer = child?.get?.('webServer') ?? child?.webServer ?? null } catch { webServer = null }
+    if (!webServer || typeof webServer.register !== 'function') return
+    webServer.register({
+      kind: 'exact',
+      path: `${prefix}/api/route`,
+      method: 'GET',
+      handler: async (req, res) => {
+        const decision = authGuard.check(req)
+        if (!decision.ok) {
+          res.statusCode = decision.status
+          res.setHeader?.('content-type', 'application/json; charset=utf-8')
+          res.end(JSON.stringify({ ok: false, error: decision.code, code: decision.code }))
+          return
+        }
+        if (String(req?.method ?? 'GET').toUpperCase() !== 'GET') {
+          res.statusCode = 405
+          res.setHeader?.('allow', 'GET')
+          res.end(JSON.stringify({ ok: false, error: 'method-not-allowed', code: 'method-not-allowed' }))
+          return
+        }
+        const q = new URL(String(req?.url ?? '/'), 'http://fang.local').searchParams
+        const out = probe({
+          needsRealtime: q.get('realtime') === '1' || q.get('realtime') === 'true',
+          oneTimeMigration: q.get('migration') === '1' || q.get('migration') === 'true',
+        })
+        res.statusCode = out.mode === 'deny' ? 409 : 200
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.end(JSON.stringify(out))
+      },
+    })
+  })
+}

package/src/plugins/session-sync.mjs

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// fang-session-sync — selected-session export/import (file-level sync mode).
+// Export is read-only on the source; import never overwrites (keep-both + fork).
+import path from 'node:path'
+import {
+  z, roleGate, resolveDshHome, resolveFangLayout, SERVICE, FANG_VERSION, ensureDir, readJson, exists,
+} from '../kernel/index.mjs'
+import { exportSessions, importSessions } from '../lib/session-bundle.mjs'
+import { encodeWorkspaceKey } from '../lib/session-format.mjs'
+import { createHttpGuard } from '../lib/http-auth.mjs'
+
+export const name = 'fang-session-sync'
+export const inject = []
+
+export const Config = z.object({
+  sessionsRoot: z.string().default('')
+    .description('源会话目录（PC）；留空 = <DSH_HOME>/sessions'),
+  storagesRoot: z.string().default('')
+    .description('workspace.json 所在目录（源）；留空 = <DSH_HOME>/storages'),
+  bundleRoot: z.string().default('')
+    .description('交接 bundle 根；留空 = <fang dataDir>/sync-bundles'),
+  prefix: z.string().default('/fang'),
+  maxBundleBytes: z.number().min(0).max(4 * 1024 * 1024 * 1024).default(512 * 1024 * 1024)
+    .description('单个 bundle 的大小上限（字节）；超过则拒绝导出'),
+  routes: z.object({ enabled: z.boolean().default(true) }).default({}),
+  authToken: z.string().default('')
+    .description('安装级鉴权 token；留空 = env DSH_FANG_AUTH_TOKEN 或 <dataDir>/fang-auth.json（0600，自动生成）'),
+  authEnabled: z.boolean().default(true)
+    .description('是否要求 /fang/api/sync/* 携带安装级鉴权 token（默认开启；仅测试/本地调试可关）'),
+})
+
+export function apply(ctx, config) {
+  const gate = roleGate('sessionSync', { logger: ctx.logger })
+  if (!gate.active) return
+  const cfg = { ...Config({}), ...(config ?? {}) }
+  const layout = resolveFangLayout()
+  const sessionsRoot = cfg.sessionsRoot ? path.resolve(cfg.sessionsRoot) : path.join(resolveDshHome(), 'sessions')
+  const storagesRoot = cfg.storagesRoot ? path.resolve(cfg.storagesRoot) : path.join(resolveDshHome(), 'storages')
+  const bundleRoot = cfg.bundleRoot ? path.resolve(cfg.bundleRoot) : path.join(layout.dataDir, 'sync-bundles')
+  const prefix = String(cfg.prefix ?? '/fang').replace(/\/+$/, '') || '/fang'
+  const authGuard = createHttpGuard({
+    dataDir: layout.dataDir,
+    token: cfg.authToken,
+    enabled: cfg.authEnabled !== false,
+  })
+
+  const workspacesOf = (homeDir) => {
+    const file = path.join(homeDir, 'storages', 'workspace.json')
+    if (!exists(file)) return []
+    try {
+      const doc = readJson(file)
+      const table = doc?.tables?.workspaces
+      if (!table || typeof table !== 'object') return []
+      return Object.entries(table).map(([id, ws]) => ({ id, path: ws?.path, title: ws?.title })).filter((w) => typeof w.path === 'string')
+    } catch { return [] }
+  }
+
+  const service = {
+    role: gate.role,
+    version: FANG_VERSION,
+    sessionsRoot,
+    storagesRoot,
+    bundleRoot,
+    status() {
+      return { ok: true, role: gate.role, sessionsRoot, bundleRoot, exists: exists(sessionsRoot) }
+    },
+    /** PC 侧：把勾选会话只读地导出到 staging bundle。 */
+    exportSelected(input = {}) {
+      const workspaces = workspacesOf(storagesRoot)
+      const requestedBundleId = input.bundleId === undefined ? `sync-${Date.now()}` : String(input.bundleId)
+      // v3.0.5/B3：bundleId 只允许安全段（防 `../` 写出 bundleRoot）
+      if (!/^[A-Za-z0-9._-]{1,128}$/.test(requestedBundleId) || requestedBundleId === '.' || requestedBundleId === '..') {
+        return { ok: false, code: 'invalid-bundle-id' }
+      }
+      const out = exportSessions({
+        sessionsRoot,
+        bundleDir: path.join(bundleRoot, requestedBundleId),
+        sessionIds: input.sessionIds,
+        workspaces,
+      })
+      if (out.ok && cfg.maxBundleBytes > 0 && out.bytes > cfg.maxBundleBytes) {
+        return { ok: false, code: 'bundle-too-large', bytes: out.bytes, limit: cfg.maxBundleBytes }
+      }
+      return out
+    },
+    /** Web 侧：把 bundle 导入目标 sessionsRoot；workospace 由目标 workspace.json 决定。 */
+    importInto(input = {}) {
+      const bundleDir = path.resolve(String(input.bundleDir ?? ''))
+      const targetHome = path.resolve(String(input.targetHome ?? ''))
+      // v3.0.5/B3：bundle 必须位于 bundleRoot 内；目标 home 只允许当前 DSH_HOME 或 fork homes 根
+      const inside = (base, target) => {
+        const rel = path.relative(base, target)
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+      }
+      if (!inside(bundleRoot, bundleDir)) return { ok: false, code: 'bundle-outside-root' }
+      const allowedHomes = [resolveDshHome(), layout.forkHomesDir].filter((p) => typeof p === 'string' && p.length > 0)
+      if (!allowedHomes.some((base) => inside(base, targetHome))) return { ok: false, code: 'target-outside-allowed' }
+      const targetSessions = path.join(targetHome, 'sessions')
+      ensureDir(targetSessions)
+      const workspaces = workspacesOf(path.join(targetHome, 'storages'))
+      const out = importSessions({
+        bundleDir,
+        targetSessionsRoot: targetSessions,
+        workspaces,
+        encodeWorkspaceKey,
+      })
+      return { ...out, targetHome, targetSessionsRoot: targetSessions }
+    },
+  }
+
+  ctx.effect(() => ctx.provide(SERVICE.sessionSync, service))
+
+  if (cfg.routes?.enabled === false) return
+  ctx.inject(['webServer'], (child) => {
+    let webServer = null
+    try { webServer = child?.get?.('webServer') ?? child?.webServer ?? null } catch { webServer = null }
+    if (!webServer || typeof webServer.register !== 'function') return
+    const json = (res, status, value) => {
+      res.statusCode = status
+      res.setHeader('content-type', 'application/json; charset=utf-8')
+      res.end(JSON.stringify(value))
+    }
+    const readBody = async (req) => {
+      const chunks = []
+      let size = 0
+      for await (const chunk of req) {
+        const buf = Buffer.from(chunk)
+        size += buf.length
+        if (size > 1_000_000) return { __tooLarge: true }
+        chunks.push(buf)
+      }
+      const text = Buffer.concat(chunks).toString('utf8')
+      if (!text) return {}
+      try { return JSON.parse(text) } catch { return { __parseError: true } }
+    }
+    const route = (method, routePath, handler) => {
+      webServer.register({
+        kind: 'exact',
+        path: routePath,
+        method,
+        handler: async (req, res) => {
+          try {
+            const decision = authGuard.check(req)
+            if (!decision.ok) return json(res, decision.status, { ok: false, error: decision.code, code: decision.code })
+            if (String(req?.method ?? 'GET').toUpperCase() !== method) {
+              try { res.setHeader?.('allow', method) } catch { /* fake res */ }
+              return json(res, 405, { ok: false, error: 'method-not-allowed', code: 'method-not-allowed' })
+            }
+            return await handler(req, res)
+          } catch (e) { return json(res, 500, { ok: false, error: String(e?.message ?? e), code: 'handler-threw' }) }
+        },
+      })
+    }
+    route('GET', `${prefix}/api/sync/status`, (req, res) => json(res, 200, service.status()))
+    route('POST', `${prefix}/api/sync/export`, async (req, res) => {
+      const body = await readBody(req)
+      if (body.__tooLarge) return json(res, 413, { ok: false, error: 'body-too-large' })
+      if (body.__parseError) return json(res, 400, { ok: false, error: 'bad-json' })
+      const out = service.exportSelected(body)
+      json(res, out.ok ? 200 : 400, out)
+    })
+    route('POST', `${prefix}/api/sync/import`, async (req, res) => {
+      const body = await readBody(req)
+      if (body.__tooLarge) return json(res, 413, { ok: false, error: 'body-too-large' })
+      if (body.__parseError) return json(res, 400, { ok: false, error: 'bad-json' })
+      const out = service.importInto(body)
+      json(res, out.ok ? 200 : 400, out)
+    })
+  })
+}