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

package/src/kernel/paths.mjs

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang kernel — path resolution and the fork web-URL contract.
+//
+// Layout (mother):
+//   $DSH_HOME/fang/<profileTag>/          data dir  (audit.jsonl, forks.json, buffer/, snapshots/, run/)
+// Forks: every fork owns its own $DSH_HOME, so the same rule isolates it from the mother.
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+
+/** `--profile name` > `--profile=name` > $DSH_PROFILE > .../profiles/<name> > 'default' */
+export function detectProfileTag(argv = process.argv, env = process.env) {
+  const argvList = Array.isArray(argv) ? argv : []
+  // The launcher sets DSH_PROFILE for the booted profile; trust it before argv, because a
+  // profile boot may re-exec with the template name still on the command line.
+  if (env && typeof env.DSH_PROFILE === 'string' && env.DSH_PROFILE.trim()) return env.DSH_PROFILE.trim()
+  const i = argvList.indexOf('--profile')
+  if (i >= 0 && argvList[i + 1]) return String(argvList[i + 1])
+  const eq = argvList.find(a => typeof a === 'string' && a.startsWith('--profile='))
+  if (eq) return eq.slice('--profile='.length)
+  const joined = argvList.join(' ')
+  const m = /[\\/]profiles[\\/]([^\\/\s"']+)/.exec(joined)
+  if (m) return m[1]
+  const cwd = process.cwd()
+  const cm = /[\\/]profiles[\\/]([^\\/\s"']+)/.exec(cwd)
+  if (cm) return cm[1]
+  return 'default'
+}
+
+export function resolveDshHome(env = process.env) {
+  const raw = env && env.DSH_HOME
+  if (typeof raw === 'string' && raw.trim()) return path.resolve(raw.trim())
+  return path.join(os.homedir(), '.dsh')
+}
+
+export function resolveProfileDir(profileTag, env = process.env) {
+  return path.join(resolveDshHome(env), 'profiles', profileTag)
+}
+
+/** 用户级数据根：$FANG_HOME 优先；未设置时新装默认 D:\ToFuture（旧布局有数据则继续用旧布局）。 */
+export function resolveFangHome(env = process.env) {
+  const raw = env && env.FANG_HOME
+  if (typeof raw === 'string' && raw.trim()) return path.resolve(raw.trim())
+  // 迁移指针：<DSH_HOME>/fang/fang-home.txt 第一行写明数据根（无需改环境变量/配置即可切换）。
+  try {
+    const pointer = path.join(resolveDshHome(env), 'fang', 'fang-home.txt')
+    if (fs.existsSync(pointer)) {
+      const first = fs.readFileSync(pointer, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)[0].trim()
+      if (first && path.isAbsolute(first)) {
+        // 迁移指针可能是旧盘/旧目录：根不存在或指向普通文件时忽略，回退到本机布局，
+        // 避免 ensureDir(dataDir) 在插件 apply 阶段抛错导致“必须删 .dsh”才能启动。
+        const root = path.parse(first).root
+        const rootUsable = Boolean(root) && fs.existsSync(root)
+        let targetUsable = true
+        try { if (fs.existsSync(first) && !fs.statSync(first).isDirectory()) targetUsable = false } catch { targetUsable = false }
+        if (rootUsable && targetUsable) return path.resolve(first)
+      }
+    }
+  } catch { /* ignore */ }
+  // 兼容：已有 $DSH_HOME/fang/<tag> 数据的安装不搬家，继续旧布局。
+  try {
+    if (fs.existsSync(path.join(resolveDshHome(env), 'fang'))) return ''
+  } catch { /* ignore */ }
+  // 新装默认主文件夹（Windows：D:\ToFuture）——只对“真正的默认安装”生效：
+  // 显式设置 DSH_HOME（e2e/测试/便携安装）时不得跳盘，否则会写进真实 D: 数据根。
+  const explicitDshHome = Boolean(env && String(env.DSH_HOME ?? '').trim())
+  if (!explicitDshHome && process.platform === 'win32') {
+    try { if (fs.existsSync('D:\\')) return 'D:\\ToFuture' } catch { /* ignore */ }
+  }
+  return ''
+}
+
+/**
+ * Every path a Fang plugin needs. Pure: no directory is created here.
+ * @returns {{dataDir:string, profileTag:string, dshHome:string, ledgerFile:string, stateFile:string,
+ *   forksFile:string, pidFile:string, bufferDir:string, snapshotsDir:string, roundsDir:string,
+ *   runDir:string, forkHomesDir:string}}
+ */
+export function resolveFangLayout(options = {}) {
+  const {
+    dataRoot = '',
+    bufferRoot = '',
+    forksRoot = '',
+    fangHome = '',
+    env = process.env,
+    argv = process.argv,
+  } = options
+  const profileTag = detectProfileTag(argv, env)
+  const dshHome = resolveDshHome(env)
+  // 显式传入 dataRoot/forksRoot（测试、独立部署）时不要自动跳到 FANG_HOME 默认值，
+  // 否则临时目录测试会写进真实的 D:\ToFuture。
+  const explicitRoots = Boolean(String(dataRoot ?? '').trim() || String(forksRoot ?? '').trim() || String(bufferRoot ?? '').trim())
+  const hasEnvFangHome = Boolean(String(env?.FANG_HOME ?? '').trim())
+  const resolvedFangHome = fangHome
+    ? path.resolve(fangHome)
+    : (explicitRoots && !hasEnvFangHome ? '' : resolveFangHome(env))
+  const dataDir = dataRoot
+    ? path.resolve(dataRoot)
+    : (resolvedFangHome ? path.join(resolvedFangHome, 'mirror', profileTag) : path.join(dshHome, 'fang', profileTag))
+  // 三区分离：母体=mirror/<tag>，原身=essence/，分身=forks/，会话/运行态=sessions/。
+  const essenceRoot = resolvedFangHome ? path.join(resolvedFangHome, 'essence') : path.join(dataDir, 'essences')
+  const forkHomesDir = forksRoot
+    ? path.resolve(forksRoot)
+    : (resolvedFangHome ? path.join(resolvedFangHome, 'forks') : path.join(dataDir, 'forks'))
+  const sessionsRoot = resolvedFangHome ? path.join(resolvedFangHome, 'sessions') : ''
+  const runtimeRoot = resolvedFangHome ? path.join(resolvedFangHome, 'sessions') : path.join(dataDir, 'runtime')
+  return {
+    dataDir,
+    profileTag,
+    dshHome,
+    fangHome: resolvedFangHome,
+    ledgerFile: path.join(dataDir, 'audit.jsonl'),
+    stateFile: path.join(dataDir, 'state.json'),
+    forksFile: path.join(dataDir, 'forks.json'),
+    tasksFile: path.join(dataDir, 'tasks.json'),
+    pidFile: path.join(dataDir, 'fang.pid'),
+    bufferDir: bufferRoot ? path.resolve(bufferRoot) : path.join(dataDir, 'buffer'),
+    snapshotsDir: path.join(dataDir, 'snapshots'),
+    roundsDir: path.join(dataDir, 'rounds'),
+    runDir: path.join(dataDir, 'run'),
+    forkHomesDir,
+    essenceRoot,
+    runtimeRoot,
+    sessionsRoot,
+  }
+}
+
+/** Matches the line a `dsh web` boot prints: `dsh web: http://127.0.0.1:<port>/...token...` */
+export const WEB_URL_RE = /dsh web:\s+(http:\/\/127\.0\.0\.1:(\d+)\/\S*)/
+
+/**
+ * Parse a fork's stdout tail into its tokenized web URL.
+ * The bare URL is 401, so a line without `?token=` is NOT a usable fork URL and
+ * parses to null — failing loud beats handing the UI an address that always 401s.
+ * @returns {{url:string, port:number, token:string}|null}
+ */
+export function parseWebUrl(text) {
+  if (!text) return null
+  const m = WEB_URL_RE.exec(String(text))
+  if (!m) return null
+  const url = m[1]
+  const t = /[?&]token=([^&\s]+)/.exec(url)
+  if (!t) return null
+  let token = t[1]
+  try { token = decodeURIComponent(token) } catch { /* keep raw */ }
+  return { url, port: Number(m[2]), token }
+}
+
+/** A fork is healthy only when its loopback URL answers; token is part of the URL. */
+export async function probeWebUrl(url, { timeoutMs = 3000, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== 'function') return { ok: false, reason: 'no-fetch' }
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(url, { signal: ac.signal })
+    return { ok: res.status < 500, status: res.status }
+  } catch (e) {
+    return { ok: false, reason: String(e && e.message ? e.message : e) }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+
+/**
+ * Read-only layout of the mother's session/workspace storage. Session catalog uses
+ * this; it must never write these paths ($DSH_HOME is the mother's own data).
+ */
+export function resolveSessionsLayout(options = {}) {
+  const { env = process.env } = options
+  const dshHome = resolveDshHome(env)
+  const sessionsDir = path.join(dshHome, 'sessions')
+  const storagesDir = path.join(dshHome, 'storages')
+  return {
+    dshHome,
+    sessionsDir,
+    storagesDir,
+    workspaceFile: path.join(storagesDir, 'workspace.json'),
+    projcacheDir: path.join(storagesDir, 'session_projcache'),
+  }
+}

package/src/kernel/role.mjs

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang kernel — deployment roles and the plugin/role matrix.
+//
+// The same bundle is installed in the mother and in every fork, so which half of a
+// plugin activates must be decided at runtime: the forker launches a fork with
+// DSH_FANG_ROLE=fork, and every plugin asks this module whether its role is enabled.
+//
+// Matrix is the product contract (docs/CONTRACTS-V2.md §2). Adding a plugin to a role
+// here is the only place that decision lives.
+
+export const ROLE = { MOTHER: 'mother', FORK: 'fork', CONSUMER: 'consumer' }
+
+/** plugin key → roles in which the plugin activates. */
+export const MATRIX = {
+  orchestrator: ['mother'],
+  forker: ['mother'],
+  restartGuard: ['mother'],
+  healer: ['fork'],
+  hotReloader: ['fork'],
+  adapter: ['fork'],
+  scorer: ['mother', 'fork'],
+  router: ['mother', 'fork'],
+  umbrella: ['mother', 'fork'],
+  approver: ['mother', 'fork'],
+  bufferKeeper: ['fork'],
+  auditor: ['mother', 'fork'],
+  sessionCatalog: ['mother'],
+  sessionBridge: ['mother'],
+  sessionSync: ['mother', 'consumer'],
+  sessionRouter: ['mother'],
+  decisionCenter: ['mother', 'fork'],
+}
+
+const VALID_ROLES = new Set([ROLE.MOTHER, ROLE.FORK, ROLE.CONSUMER])
+
+/**
+ * The environment wins over config: a fork is started by the forker with
+ * DSH_FANG_ROLE=fork and must never be able to promote itself to a mother by config.
+ * @returns {'mother'|'fork'|'consumer'}
+ */
+export function resolveRole({ cfgRole = '', env = process.env } = {}) {
+  const fromEnv = env?.DSH_FANG_ROLE
+  if (VALID_ROLES.has(fromEnv)) return fromEnv
+  if (VALID_ROLES.has(cfgRole)) return cfgRole
+  return ROLE.MOTHER
+}
+
+export function roleAllows(pluginKey, role) {
+  return (MATRIX[pluginKey] ?? []).includes(role)
+}
+
+/**
+ * Guard used at the top of every plugin's apply().
+ * @returns {{role:string, active:boolean, reason:string}}
+ */
+export function roleGate(pluginKey, { cfgRole = '', env = process.env, logger = null } = {}) {
+  const role = resolveRole({ cfgRole, env })
+  const active = roleAllows(pluginKey, role)
+  const reason = active ? `${pluginKey} active in ${role}` : `${pluginKey} is not deployed in ${role}`
+  if (!active && logger && typeof logger.info === 'function') logger.info(reason)
+  return { role, active, reason }
+}
+
+/** Roles a plugin activates in — used by status surfaces and tests. */
+export function rolesOf(pluginKey) {
+  return [...(MATRIX[pluginKey] ?? [])]
+}

package/src/kernel/rounds.mjs

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang kernel — round (hot-update transaction) core.
+// Zero node dependencies: every filesystem call comes through an injected fsApi,
+// so the same logic runs under node:fs in the host and under a memory FS in a browser.
+//
+// fsApi contract (node:fs compatible subset):
+//   readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, copyFileSync,
+//   unlinkSync, existsSync
+
+const SKIP_NAMES = new Set(['changes.json', '.age.json', '.rounds'])
+
+function hashHex(bytes) {
+  const data = typeof bytes === 'string' ? bytes : bufferLikeToString(bytes)
+  let h1 = 0x811c9dc5
+  let h2 = 0x01000193
+  for (let i = 0; i < data.length; i++) {
+    const c = data.charCodeAt(i) & 0xff
+    h1 = (h1 ^ c) * 16777619 >>> 0
+    h2 = (h2 + c * (i + 1)) >>> 0
+  }
+  return h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')
+}
+
+function bufferLikeToString(b) {
+  if (b == null) return ''
+  if (typeof b === 'string') return b
+  if (typeof b.toString === 'function') {
+    const s = b.toString('utf8')
+    if (typeof s === 'string' && !/^\[object/.test(s)) return s
+  }
+  if (b instanceof Uint8Array) return Array.from(b).map(x => String.fromCharCode(x)).join('')
+  return String(b)
+}
+
+export function createRounds(fsApi) {
+  const fs = fsApi
+  const join = (...parts) => parts.filter(p => p != null && p !== '').join('/').replace(/\/+/g, '/')
+  const parentOf = (p) => { const i = p.lastIndexOf('/'); return i > 0 ? p.slice(0, i) : '.' }
+  const roundsDirOf = (stagingDir, name) => stagingDir + '/' + name + '/.rounds'
+
+  const fileDigests = (dir) => {
+    const out = {}
+    const walk = (d, rel = '') => {
+      let names = []
+      try { names = fs.readdirSync(d) ?? [] } catch { return }
+      for (const n of names) {
+        const r = rel ? rel + '/' + n : n
+        if (SKIP_NAMES.has(r) || SKIP_NAMES.has(n)) continue
+        const p = d + '/' + n
+        let st
+        try { st = fs.statSync(p) } catch { continue }
+        if (st && typeof st.isDirectory === 'function' && st.isDirectory()) { walk(p, r); continue }
+        try { out[r] = hashHex(fs.readFileSync(p)) } catch { /* unreadable: skip */ }
+      }
+    }
+    walk(dir)
+    return out
+  }
+
+  const copyTreeInto = (srcDir, dstDir) => {
+    try { fs.mkdirSync(dstDir, { recursive: true }) } catch { /* ignore */ }
+    let names = []
+    try { names = fs.readdirSync(srcDir) ?? [] } catch { return }
+    for (const n of names) {
+      if (SKIP_NAMES.has(n)) continue
+      const p = srcDir + '/' + n
+      let st
+      try { st = fs.statSync(p) } catch { continue }
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) { copyTreeInto(p, dstDir + '/' + n); continue }
+      try {
+        fs.mkdirSync(parentOf(dstDir + '/' + n), { recursive: true })
+        fs.copyFileSync(p, dstDir + '/' + n)
+      } catch { /* ignore */ }
+    }
+  }
+
+  const beginRound = ({ stagingDir, name, note = '', now = () => new Date().toISOString() }) => {
+    const stageDir = stagingDir + '/' + name
+    if (!fs.existsSync(stageDir)) return { ok: false, phase: 'not-in-staging' }
+    const roundId = 'r' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5)
+    const dir = roundsDirOf(stagingDir, name) + '/' + roundId
+    const preDir = dir + '/pre'
+    try { copyTreeInto(stageDir, preDir) } catch (e) {
+      return { ok: false, phase: 'copy-failed', error: String(e?.message ?? e) }
+    }
+    const manifest = { roundId, name, note: String(note ?? ''), at: now(), files: fileDigests(preDir) }
+    try { fs.writeFileSync(dir + '/manifest.json', JSON.stringify(manifest, null, 2)) } catch { /* ignore */ }
+    return { ok: true, phase: 'round-open', roundId, files: Object.keys(manifest.files).length }
+  }
+
+  const listRounds = ({ stagingDir, name }) => {
+    let ids = []
+    try { ids = fs.readdirSync(roundsDirOf(stagingDir, name)) ?? [] } catch { return [] }
+    const out = []
+    for (const id of ids) {
+      const dir = roundsDirOf(stagingDir, name) + '/' + id
+      let m = null
+      try { m = JSON.parse(bufferLikeToString(fs.readFileSync(dir + '/manifest.json'))) } catch { /* ignore */ }
+      if (m) out.push({ ...m, dir })
+    }
+    return out.sort((a, b) => (a.at < b.at ? 1 : -1))
+  }
+
+  const resetRound = ({ stagingDir, name, roundId } = {}) => {
+    const errors = []
+    const safeCopy = (src, dst) => {
+      try {
+        if (!fs.existsSync(src)) { errors.push({ src, error: 'missing-source' }); return false }
+        fs.mkdirSync(parentOf(dst), { recursive: true })
+        fs.copyFileSync(src, dst)
+        return true
+      } catch (e) { errors.push({ src, error: String(e?.message ?? e) }); return false }
+    }
+    const safeUnlink = (p) => {
+      try { if (fs.existsSync(p)) fs.unlinkSync(p); return true } catch (e) {
+        errors.push({ path: p, error: String(e?.message ?? e) }); return false
+      }
+    }
+    try {
+      const rounds = listRounds({ stagingDir, name })
+      if (!rounds.length) return { ok: false, phase: 'no-rounds', touched: [], errors }
+      const target = roundId ? rounds.find(r => r.roundId === roundId) : rounds[0]
+      if (!target) return { ok: false, phase: 'round-not-found', available: rounds.map(r => r.roundId), touched: [], errors }
+
+      const stageDir = stagingDir + '/' + name
+      const preDir = target.dir + '/pre'
+      const pre = fileDigests(preDir)
+      const cur = fileDigests(stageDir)
+
+      if (Object.keys(pre).length === 0 && Object.keys(cur).length > 0) {
+        return {
+          ok: false, phase: 'round-corrupt', roundId: target.roundId,
+          manifestFiles: Object.keys(target.files ?? {}).length,
+          currentFiles: Object.keys(cur).length, touched: [], errors,
+        }
+      }
+
+      const manifest = target.files && typeof target.files === 'object' ? target.files : null
+      const inManifest = (p) => !!manifest && Object.prototype.hasOwnProperty.call(manifest, p)
+      const touched = []
+
+      for (const [p, d] of Object.entries(cur)) {
+        if (pre[p] === d) continue
+        if (inManifest(p)) {
+          if (pre[p] !== undefined) {
+            if (safeCopy(preDir + '/' + p, stageDir + '/' + p)) touched.push({ path: p, action: 'restored' })
+          } else {
+            errors.push({ path: p, error: 'pre-image-missing' })
+            touched.push({ path: p, action: 'kept-missing-preimage' })
+          }
+        } else if (pre[p] !== undefined) {
+          if (safeCopy(preDir + '/' + p, stageDir + '/' + p)) touched.push({ path: p, action: 'restored' })
+        } else {
+          if (safeUnlink(stageDir + '/' + p)) touched.push({ path: p, action: 'removed' })
+        }
+      }
+      for (const p of Object.keys(pre)) {
+        if (cur[p] !== undefined) continue
+        if (safeCopy(preDir + '/' + p, stageDir + '/' + p)) touched.push({ path: p, action: 'recovered' })
+      }
+      const after = fileDigests(stageDir)
+      const clean = Object.keys(pre).length === Object.keys(after).length &&
+        Object.entries(pre).every(([k, v]) => after[k] === v)
+      return { ok: errors.length === 0, phase: 'reset', roundId: target.roundId, touched, clean, errors }
+    } catch (e) {
+      return { ok: false, phase: 'threw', error: String(e?.message ?? e), touched: [], errors }
+    }
+  }
+
+  return { fileDigests, copyTreeInto, beginRound, listRounds, resetRound, roundsDirOf, join }
+}

package/src/kernel/schema.mjs

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// Vendored schemastery (link:-installed bundles cannot resolve @deepseek-ai/schemastery,
+// so the schema library ships with the project). Same pattern as packages/shared/vendor.
+export { default } from './vendor/schemastery.mjs'