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

package/src/lib/mother-link.mjs

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// fang-link（v2.9.0）— 母体连接描述 + 连通性探测（纯逻辑，供 orchestrator 服务与 HTTP 路由复用）。
+//
+// 边界：
+//   * 只描述、不持有连接状态：分身的 token 由 Forker 在 spawn 时注入，fang 不落盘、不回显；
+//   * 探测是只读 GET `${target}${prefix}/api/status`，带超时、不抛异常，失败以结构化错误返回；
+//   * 目标只接受 http(s) origin，拒绝凭据/查询串/非 http 协议（避免把 token 写进 URL）。
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const MOTHER_LINK_PATHS = Object.freeze({
+  DESCRIBE: '/api/mother-link',
+  PROBE: '/api/mother-link/probe',
+})
+
+export const DEFAULT_LINK_TIMEOUT_MS = 3000
+export const MAX_LINK_TIMEOUT_MS = 10000
+export const MIN_LINK_TIMEOUT_MS = 200
+
+/** @param {unknown} raw @returns {string} */
+export function normalizePrefix(raw) {
+  const text = String(raw ?? '/fang').trim().replace(/\/+$/, '')
+  if (text.length === 0) return '/fang'
+  return text.startsWith('/') ? text : `/${text}`
+}
+
+/**
+ * 校验并归一化母体地址（只保留 origin，丢弃 path/query/hash）。
+ * @param {unknown} raw
+ * @returns {{ok:true, origin:string, host:string} | {ok:false, error:string}}
+ */
+export function normalizeLinkOrigin(raw) {
+  const text = String(raw ?? '').trim()
+  if (text.length === 0) return { ok: false, error: 'target-empty' }
+  if (text.length > 512) return { ok: false, error: 'target-too-long' }
+  let url
+  try {
+    url = new URL(text)
+  } catch {
+    return { ok: false, error: 'target-invalid-url' }
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return { ok: false, error: 'target-scheme' }
+  if (url.username.length > 0 || url.password.length > 0) return { ok: false, error: 'target-credentials' }
+  if (url.search.length > 0 || url.hash.length > 0) return { ok: false, error: 'target-query' }
+  return { ok: true, origin: `${url.protocol}//${url.host}`, host: url.host }
+}
+
+/**
+ * 母体侧读取 profile 的“共享配置摘要”（只读、失败降级为 null。
+ * @param {{profileDir?: string, env?: Record<string, string|undefined>}} [options]
+ * @returns {{layer:'profile', profile:string|null, profileDir:string|null, bundles:number|null, name?:string}}
+ */
+export function readSharedProfileSummary(options = {}) {
+  const env = options.env ?? process.env
+  const profile = typeof env.DSH_PROFILE === 'string' && env.DSH_PROFILE.length > 0 ? env.DSH_PROFILE : null
+  const profileDir = String(options.profileDir ?? '').trim()
+  const fallback = { layer: 'profile', profile, profileDir: profileDir.length > 0 ? profileDir : null, bundles: null }
+  if (profileDir.length === 0) return fallback
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8'))
+    const bundles = Array.isArray(pkg?.dsh?.profile?.bundles) ? pkg.dsh.profile.bundles.length : null
+    return {
+      ...fallback,
+      bundles,
+      name: typeof pkg?.name === 'string' ? pkg.name : undefined,
+    }
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * 生成母体连接描述（纯函数）。
+ * @param {{role?: string, version?: string, prefix?: string, profileDir?: string, sharedConfig?: object, now?: () => number}} options
+ * @returns {Record<string, unknown>}
+ */
+export function describeMotherLink(options = {}) {
+  const now = options.now ?? Date.now
+  const prefix = normalizePrefix(options.prefix ?? '/fang')
+  const sharedConfig = options.sharedConfig ?? readSharedProfileSummary({ profileDir: options.profileDir })
+  return {
+    ok: true,
+    role: typeof options.role === 'string' ? options.role : 'mother',
+    version: typeof options.version === 'string' ? options.version : '',
+    at: now(),
+    prefix,
+    motherApiBase: `${prefix}/api`,
+    adapterBase: `${prefix}/adapter`,
+    probe: {
+      method: 'POST',
+      path: `${prefix}${MOTHER_LINK_PATHS.PROBE}`,
+      body: { target: 'http(s)://<mother-host>', timeoutMs: DEFAULT_LINK_TIMEOUT_MS },
+    },
+    tokenPolicy: 'fork adapter token is injected by Forker at spawn time; fang never persists or echoes it',
+    sharedConfig,
+    forkInstructions: [
+      '打开母体 web 门户（/fang/panel）或瓮城面板的「母体连接」卡片',
+      '分身只需母体地址；令牌由 Forker 注入 DSH_ADAPTER_TOKEN，不需要手工填写',
+      '连通性测试调用 POST /fang/api/mother-link/probe，不会写入任何配置',
+    ],
+  }
+}
+
+/**
+ * 探测母体 `/api/status`（一次 GET，超时上限 10s；任何失败都返回结构化错误，不抛）。
+ * @param {{target?: unknown, prefix?: string, timeoutMs?: number, timeoutMsLimit?: number, fetchImpl?: typeof fetch, now?: () => number}} options
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function probeLink(options = {}) {
+  const now = options.now ?? Date.now
+  const normalized = normalizeLinkOrigin(options.target)
+  if (!normalized.ok) {
+    return { ok: false, target: String(options.target ?? ''), error: normalized.error, latencyMs: 0, checkedAt: now() }
+  }
+  const rawTimeout = Number.isFinite(options.timeoutMs) ? Math.trunc(options.timeoutMs) : DEFAULT_LINK_TIMEOUT_MS
+  const timeoutMs = Math.min(Math.max(rawTimeout, MIN_LINK_TIMEOUT_MS), MAX_LINK_TIMEOUT_MS)
+  const prefix = normalizePrefix(options.prefix ?? '/fang')
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch
+  if (typeof fetchImpl !== 'function') {
+    return { ok: false, target: normalized.origin, error: 'fetch-unavailable', latencyMs: 0, checkedAt: now() }
+  }
+  const started = now()
+  try {
+    const response = await fetchImpl(`${normalized.origin}${prefix}/api/status`, {
+      method: 'GET',
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    const latencyMs = Math.max(0, now() - started)
+    let payload = null
+    try {
+      payload = await response.json()
+    } catch {
+      payload = null
+    }
+    const version = typeof payload?.version === 'string' ? payload.version : null
+    if (!response.ok) {
+      return { ok: false, target: normalized.origin, httpStatus: response.status, latencyMs, version, error: 'status-http-error', checkedAt: now() }
+    }
+    return { ok: true, target: normalized.origin, httpStatus: response.status, latencyMs, version, checkedAt: now() }
+  } catch (error) {
+    const name = error instanceof Error ? error.name : ''
+    const message = error instanceof Error ? error.message : String(error)
+    const timedOut = name === 'TimeoutError' || name === 'AbortError'
+    return {
+      ok: false,
+      target: normalized.origin,
+      error: timedOut ? 'timeout' : 'network-error',
+      message: message.slice(0, 200),
+      latencyMs: Math.max(0, now() - started),
+      checkedAt: now(),
+    }
+  }
+}

package/src/lib/mutex.mjs

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// dsh-Fang v2.12.0 — per-key 串行锁（零依赖）。
+// 用途：同一原身的 ensureFresh/重算串行化；不同 key 互不阻塞。
+// 失败不阻断链：then(fn, fn) 保证前一个任务 reject 后下一个仍执行。
+
+export class KeyedMutex {
+  constructor() {
+    /** @type {Map<string, Promise<unknown>>} */
+    this.chains = new Map()
+  }
+
+  /**
+   * @template T
+   * @param {string} key
+   * @param {() => (T|Promise<T>)} fn
+   * @returns {Promise<T>}
+   */
+  run(key, fn) {
+    const previous = this.chains.get(key) ?? Promise.resolve()
+    const next = previous.then(fn, fn).finally(() => {
+      if (this.chains.get(key) === next) this.chains.delete(key)
+    })
+    this.chains.set(key, next)
+    return next
+  }
+
+  /** 当前是否还有排队/执行中的 key（诊断用）。 */
+  size() {
+    return this.chains.size
+  }
+}

package/src/lib/permissions.mjs

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// dsh-Fang v3.0.4 — 三层产品形态的权限契约（fail-closed）。
+//
+// 母体版 Mirror：只有官方插件，不能开会话/任务；
+// 原身版 Essence：可装第三方插件，不能开会话/任务；
+// 分身版 Derived：不能装插件，可开会话/任务。
+//
+// 说明：真正的硬隔离靠“profile 里装不装对应插件”（第一道门）；
+// 本模块是宿主/Adapter 侧的第二道门（防止直连 API 绕过 UI）。
+
+export const ENV_TYPE = Object.freeze({
+  MIRROR: 'mirror',
+  ESSENCE: 'essence',
+  DERIVED: 'derived',
+})
+
+export const ENV_TYPES = Object.freeze(Object.values(ENV_TYPE))
+
+/** @type {Record<string, {installPlugins:boolean, openSessions:boolean}>} */
+export const PERMISSION_RULES = Object.freeze({
+  mirror: Object.freeze({ installPlugins: false, openSessions: false }),
+  essence: Object.freeze({ installPlugins: true, openSessions: false }),
+  derived: Object.freeze({ installPlugins: false, openSessions: true }),
+})
+
+export const ACTION_GROUPS = Object.freeze({
+  installPlugins: Object.freeze(['plugin-install', 'plugin-uninstall', 'plugin-update', 'plugin-set']),
+  openSessions: Object.freeze(['session-create', 'task-enqueue', 'agent-run', 'chat-send']),
+})
+
+export const PERMISSION_DENIED = 'permission-denied'
+
+/**
+ * 规范化环境类型；未知值一律视为 unknown（后续 fail-closed 拒绝）。
+ * @param {unknown} value
+ * @returns {'mirror'|'essence'|'derived'|'unknown'}
+ */
+export function resolveEnvType(value) {
+  const text = String(value ?? '')
+  return ENV_TYPES.includes(text) ? text : 'unknown'
+}
+
+/**
+ * 检查某个动作在某环境下是否允许。
+ * 未知环境 / 未知动作 → 拒绝（fail-closed）。
+ * @param {unknown} envType
+ * @param {string} action
+ * @returns {{allowed:boolean, envType:string, action:string, code?:string, message?:string}}
+ */
+export function checkPermission(envType, action) {
+  const env = resolveEnvType(envType)
+  const name = String(action ?? '')
+  const rule = PERMISSION_RULES[env]
+  if (rule === undefined) {
+    return {
+      allowed: false, envType: env, action: name, code: PERMISSION_DENIED,
+      message: `未知环境类型：${String(envType)}（fail-closed）`,
+    }
+  }
+  const group = Object.keys(ACTION_GROUPS).find(key => ACTION_GROUPS[key].includes(name))
+  if (group === undefined) {
+    return {
+      allowed: false, envType: env, action: name, code: PERMISSION_DENIED,
+      message: `未知动作：${name}（fail-closed）`,
+    }
+  }
+  if (rule[group] !== true) {
+    const label = group === 'installPlugins' ? '安装/修改插件' : '开启会话或任务'
+    const envLabel = { mirror: '母体版', essence: '原身版', derived: '分身版' }[env]
+    return {
+      allowed: false, envType: env, action: name, code: PERMISSION_DENIED,
+      message: `[权限拒绝] ${envLabel} 不支持${label}`,
+    }
+  }
+  return { allowed: true, envType: env, action: name }
+}
+
+/** 权限拒绝错误（Adapter/Guard 抛出用）。 */
+export class PermissionDeniedError extends Error {
+  constructor(decision) {
+    super(decision?.message ?? 'permission denied')
+    this.name = 'PermissionDeniedError'
+    this.code = PERMISSION_DENIED
+    this.envType = decision?.envType ?? 'unknown'
+    this.action = decision?.action ?? ''
+  }
+}
+
+/**
+ * 创建一个绑定环境的守卫：返回 decision；`assert` 形式抛错。
+ * @param {unknown} envType
+ */
+export function createEnvironmentGuard(envType) {
+  const env = resolveEnvType(envType)
+  const decide = (action) => checkPermission(env, action)
+  return {
+    envType: env,
+    can: (action) => decide(action).allowed,
+    check: decide,
+    assert(action) {
+      const decision = decide(action)
+      if (!decision.allowed) throw new PermissionDeniedError(decision)
+      return decision
+    },
+  }
+}
+
+/** 供 UI 展示的能力摘要。 */
+export function describePermissions(envType) {
+  const env = resolveEnvType(envType)
+  const rule = PERMISSION_RULES[env]
+  return rule === undefined
+    ? { envType: env, installPlugins: false, openSessions: false, known: false }
+    : { envType: env, installPlugins: rule.installPlugins, openSessions: rule.openSessions, known: true }
+}

package/src/lib/pnpm-store.mjs

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang lib — pnpm settings for the essence runtime profile.
+//
+// DSH 0.2.2-rc.1 bundles pnpm 11, and pnpm 11 no longer reads non-auth settings
+// (`store-dir`, `package-import-method`, …) from a project `.npmrc`: only auth and
+// network keys are read from that file, the rest moved to `pnpm-workspace.yaml`
+// (camelCase). Fang used to write only `.npmrc`, so every pnpm operation inside an
+// essence runtime picked the per-drive default store (`D:\.pnpm-store\v11` on a D:
+// project) while the module tree recorded the mother's C: store, and pnpm failed with
+//     [ERR_PNPM_UNEXPECTED_STORE] Unexpected store location ...
+// Before removing/updating any plugin (v3.1.8 report).
+//
+// This module writes the settings in the form pnpm 11 actually reads, keeps the legacy
+// `.npmrc` for older pnpm/npm, and aligns the modules manifest so pnpm's compatibility
+// check accepts the shared module tree: the store must match and the virtual store must
+// be this project's own `node_modules/.pnpm` (the copied manifest still named the
+// mother's virtual store).
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** The project settings file pnpm 11 reads (non-auth settings). */
+export const PNPM_WORKSPACE_FILE = 'pnpm-workspace.yaml'
+/** Legacy npm/pnpm config file; still written for older toolchains. */
+export const NPMRC_FILE = '.npmrc'
+/** The modules manifest pnpm writes into `node_modules`. */
+export const MODULES_MANIFEST_FILE = '.modules.yaml'
+
+function readText(file, fallback = '') {
+  try { return fs.readFileSync(file, 'utf8') } catch { return fallback }
+}
+
+function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return fallback }
+}
+
+function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, text, 'utf8')
+}
+
+/**
+ * Read the store + virtual store recorded for a module tree.
+ * @param {string} modulesDir `node_modules` directory (its `.modules.yaml` is read).
+ * @returns {{storeDir:string, virtualStoreDir:string|null, layoutVersion:number|null, file:string}|null}
+ */
+export function readModulesManifest(modulesDir) {
+  const file = path.join(String(modulesDir ?? ''), MODULES_MANIFEST_FILE)
+  const manifest = readJson(file, null)
+  if (!manifest || typeof manifest !== 'object') return null
+  return {
+    storeDir: typeof manifest.storeDir === 'string' ? manifest.storeDir : '',
+    virtualStoreDir: typeof manifest.virtualStoreDir === 'string' ? manifest.virtualStoreDir : null,
+    layoutVersion: Number.isFinite(manifest.layoutVersion) ? manifest.layoutVersion : null,
+    file,
+  }
+}
+
+/**
+ * The linker an existing module tree was laid out with, from the profile that owns it.
+ * DSH's desktop profile declares `nodeLinker: hoisted`; a runtime profile cloned from it
+ * must keep the same linker or pnpm would want to rebuild the modules directory.
+ * @param {string} profileDir Profile directory whose pnpm-workspace.yaml is read.
+ * @param {string} [fallback='hoisted'] Value used when the file has no nodeLinker.
+ * @returns {string}
+ */
+export function readNodeLinker(profileDir, fallback = 'hoisted') {
+  const text = readText(path.join(String(profileDir ?? ''), PNPM_WORKSPACE_FILE))
+  const match = /^nodeLinker:\s*([A-Za-z-]+)\s*$/m.exec(text)
+  return match ? match[1] : fallback
+}
+
+/**
+ * Upsert top-level keys in a pnpm settings YAML file, preserving every other line
+ * (settings, comments, order). The values written here are machine paths and simple
+ * scalars, so a line-oriented upsert is enough and keeps the file readable.
+ * @param {string} file pnpm-workspace.yaml path.
+ * @param {Record<string,string>} settings Keys to write (camelCase).
+ * @returns {string[]} Keys written.
+ */
+export function upsertPnpmWorkspaceSettings(file, settings = {}) {
+  const entries = Object.entries(settings).filter(([, value]) => typeof value === 'string' && value !== '')
+  if (entries.length === 0) return []
+  const keys = new Set(entries.map(([key]) => key))
+  const original = readText(file)
+  const kept = original.split(/\r?\n/).filter((line) => {
+    const match = /^([A-Za-z][A-Za-z0-9_]*):/.exec(line)
+    return !(match && keys.has(match[1]))
+  })
+  const trimmed = kept.join('\n').replace(/[ \t]+$/gm, '').replace(/^\n+|\n+$/g, '')
+  const appended = entries.map(([key, value]) => `${key}: ${value}`).join('\n')
+  writeText(file, `${trimmed ? `${trimmed}\n` : ''}${appended}\n`)
+  return entries.map(([key]) => key)
+}
+
+/**
+ * Upsert legacy `.npmrc` keys. pnpm 11 ignores these, but npm and older pnpm honor
+ * them and the runtime profile may outlive a DSH downgrade.
+ * @param {string} profileDir Profile directory.
+ * @param {{storeDir:string, packageImportMethod:string}} options
+ * @returns {string[]}
+ */
+export function upsertNpmrc(profileDir, { storeDir, packageImportMethod = 'copy' } = {}) {
+  const file = path.join(String(profileDir ?? ''), NPMRC_FILE)
+  const pairs = [
+    ['store-dir', storeDir],
+    ['package-import-method', packageImportMethod],
+  ].filter(([, value]) => typeof value === 'string' && value !== '')
+  if (pairs.length === 0) return []
+  const written = []
+  let text = readText(file)
+  for (const [key, value] of pairs) {
+    const re = new RegExp(`^${key}=.*$`, 'm')
+    if (re.test(text)) text = text.replace(re, `${key}=${value}`)
+    else text = `${text && !text.endsWith('\n') ? `${text}\n` : text}${key}=${value}\n`
+    written.push(key)
+  }
+  writeText(file, text.replace(/^\n+/, ''))
+  return written
+}
+
+/**
+ * Align a modules manifest with the store and virtual store pnpm will compute for this
+ * project. pnpm's `checkCompatibility` refuses a modules directory whose recorded store
+ * differs from the chosen store, or whose recorded `virtualStoreDir` differs from the
+ * project's own — the runtime tree was copied from the mother, so it names the mother's
+ * virtual store. Both become this project's values; the rest of the manifest is kept.
+ * @param {string} modulesDir `node_modules` directory.
+ * @param {{storeDir:string, virtualStoreDir:string}} options
+ * @returns {{changed:boolean, storeDir?:string, virtualStoreDir?:string, error?:string}}
+ */
+export function patchModulesManifest(modulesDir, { storeDir, virtualStoreDir } = {}) {
+  const manifest = readModulesManifest(modulesDir)
+  if (!manifest) return { changed: false, error: 'modules-manifest-missing' }
+  if (!storeDir || !virtualStoreDir) return { changed: false, error: 'store-or-virtual-store-missing' }
+  const raw = readJson(manifest.file, null)
+  if (!raw) return { changed: false, error: 'modules-manifest-unreadable' }
+  const sameStore = raw.storeDir === storeDir
+  const sameVirtual = raw.virtualStoreDir === virtualStoreDir
+  if (sameStore && sameVirtual) return { changed: false, storeDir, virtualStoreDir }
+  raw.storeDir = storeDir
+  raw.virtualStoreDir = virtualStoreDir
+  writeText(manifest.file, `${JSON.stringify(raw, null, 2)}\n`)
+  return { changed: true, storeDir, virtualStoreDir }
+}
+
+/**
+ * Make an essence runtime profile's pnpm operations work off the shared module tree.
+ *
+ * Writes the settings pnpm 11 reads (`pnpm-workspace.yaml`), refreshes the legacy
+ * `.npmrc`, and aligns `node_modules/.modules.yaml` with the store and this project's
+ * virtual store. The store location is taken from the module tree's own manifest, so the
+ * chosen store always matches what the installed packages were linked from.
+ * @param {{profileDir:string, modulesDir:string, sourceModulesDir?:string, nodeLinker?:string}} options
+ * @returns {{ok:boolean, storeDir?:string, virtualStoreDir?:string, nodeLinker?:string, settings?:string[], npmrc?:string[], manifest?:object, error?:string}}
+ */
+export function ensureEssenceRuntimePnpmConfig({ profileDir, modulesDir, sourceModulesDir = '', nodeLinker = 'hoisted' } = {}) {
+  const profile = String(profileDir ?? '')
+  const modules = String(modulesDir ?? '')
+  if (!profile || !modules) return { ok: false, error: 'profile-or-modules-missing' }
+  const source = String(sourceModulesDir ?? '') || modules
+  const manifest = readModulesManifest(source) ?? readModulesManifest(modules)
+  if (!manifest) return { ok: false, error: 'modules-manifest-missing' }
+  const storeDir = manifest.storeDir
+  if (!storeDir) return { ok: false, error: 'store-dir-unknown' }
+  const virtualStoreDir = path.join(modules, '.pnpm')
+  const settings = upsertPnpmWorkspaceSettings(path.join(profile, PNPM_WORKSPACE_FILE), {
+    nodeLinker,
+    storeDir,
+    packageImportMethod: 'copy',
+    // v3.1.11：元宝运行态是“用户显式更新插件”的交互场景，pnpm 11 默认的
+    // minimumReleaseAge（供应链观察期）会把刚发布的自家插件判为过新：
+    // ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION（3.1.10 / queue-journal 0.1.4 实测）。
+    // 母体的供应链策略不在这里改动；只在运行态关闭观察期，保证插件更新/卸载可用。
+    minimumReleaseAge: '0',
+  })
+  const npmrc = upsertNpmrc(profile, { storeDir, packageImportMethod: 'copy' })
+  const patched = patchModulesManifest(modules, { storeDir, virtualStoreDir })
+  return {
+    ok: patched.error === undefined,
+    storeDir,
+    virtualStoreDir,
+    nodeLinker,
+    settings,
+    npmrc,
+    manifest: patched,
+    ...(patched.error === undefined ? {} : { error: patched.error }),
+  }
+}