dsh-plugin 0.1.0 → 1.0.0

package/src/server/services/installed-versions.ts

@@ -0,0 +1,65 @@
+/**
+ * Installed-plugin version tracking.
+ *
+ * The installed table (`readInstalled` in routes.ts) only knows the manifest
+ * spec of each dependency (`github:<owner>/<repo>`), which carries no version.
+ * To let the Plugin Hub tell "an update is available", we record the catalog
+ * signal present at install time into a small per-profile JSON file, then
+ * compare it against the catalog's current signal later.
+ *
+ * Two signals cover every repo:
+ *   - version:  the catalog's latest release tag (e.g. v1.2.3). Repos that
+ *     publish releases are compared on this.
+ *   - updatedAt: the repo's last push time (GitHub pushed_at, `repoUpdatedAt`).
+ *     Repos that never publish a release fall back to this: a newer push time
+ *     means new commits → an update is available.
+ *
+ * Storage: `DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
+ *   { "<owner>/<repo>" (lowercase): { version: string, updatedAt: string, installedAt: string } }
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export interface InstalledVersionRecord {
+  /** 安装时的目录最新 release 版本（无 release 的仓库为空串） */
+  version: string
+  /** 安装时的仓库最近更新时间（ISO，GitHub pushed_at）；无 release 仓库的更新依据 */
+  updatedAt: string
+  installedAt: string
+}
+
+export type InstalledVersionTable = Record<string, InstalledVersionRecord>
+
+export function versionsFilePath(profile: string): string {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile, 'gro.ngilp-hsd-versions.json')
+}
+
+export function readInstalledVersions(profile: string): InstalledVersionTable {
+  try {
+    const raw = JSON.parse(readFileSync(versionsFilePath(profile), 'utf8')) as unknown
+    return raw !== null && typeof raw === 'object' ? raw as InstalledVersionTable : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Record the catalog signals (version + repo updated time) present at install time for one repo. */
+export function recordInstalledVersion(profile: string, repo: string, version: string, updatedAt: string): void {
+  const table = readInstalledVersions(profile)
+  table[repo.toLowerCase()] = { version, updatedAt, installedAt: new Date().toISOString() }
+  writeVersions(profile, table)
+}
+
+/** Forget the recorded version for one repo (called on uninstall). */
+export function removeInstalledVersion(profile: string, repo: string): void {
+  const table = readInstalledVersions(profile)
+  delete table[repo.toLowerCase()]
+  writeVersions(profile, table)
+}
+
+function writeVersions(profile: string, table: InstalledVersionTable): void {
+  const file = versionsFilePath(profile)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(table, null, 2) + '\n', 'utf8')
+}

package/src/server/services/loader.ts

@@ -0,0 +1,110 @@
+/**
+ * 运行中 loader 的读取与停用：卸载成功后对匹配条目做 live-disable，
+ * 使卸载立即生效（刷新页面不再加载已卸载的 client bundle，也无需重启）。
+ */
+
+/**
+ * 运行中 loader 的最小接口：卸载成功后即时移除条目用。
+ * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取面与移除面。
+ * 移除方式：对匹配条目 live-disable（`entry.update({ disabled: true })`），
+ * 而不是 `loader.remove(id)` —— disable 走 Entry.update 的 disabled 分支，不触发
+ * tree.write()（不会把运行态条目烘焙回 cordis.yml），也不依赖嵌套子树的 id 解析。
+ */
+export interface LoaderHandle {
+  /** 遍历当前插件树的全部条目（含嵌套子树）。 */
+  entries(): Iterable<{
+    id: string
+    options: { id?: string; name?: string; disabled?: boolean | null }
+    /** live-disable 一个条目（官方 Entry.update，force=true 覆盖初始化竞态）。 */
+    update(options: { disabled: boolean | null }, create?: boolean, force?: boolean): Promise<void>
+  }>
+  /** 停止并移除一个条目（官方 Loader API：resolve → EntryGroup.remove → tree.write）。 */
+  remove(id: string): Promise<void>
+}
+
+/** 运行中 loader 的全部条目（id + options.name），诊断用。 */
+export function dumpLoaderEntries(loader: LoaderHandle | undefined): Array<{ id: string; name?: string }> {
+  if (!loader) return []
+  const entries: Array<{ id: string; name?: string }> = []
+  for (const entry of Array.from(loader.entries())) {
+    entries.push({ id: entry.id, name: entry.options?.name })
+  }
+  return entries
+}
+
+/**
+ * 卸载目标（npm 包名，如 `@scope/widget`）与 loader 条目名的匹配。
+ * loader 条目名由插件作者/工具写入，形式不可控，常见变体：
+ *  - 完整 npm 名：`@scope/widget`
+ *  - 去 `@` 前缀：`scope/widget`
+ *  - 去 scope 的短名：`widget`
+ *  - scope 分隔符变 `-`：`scope-widget`
+ * 因此归一化后比较全串与短名两个维度。profile 内包名唯一，宽松匹配不会误伤其它包。
+ */
+function nameMatches(entryName: string | undefined, target: string): boolean {
+  if (!entryName) return false
+  // 归一化：去 @、非 [a-z0-9-] 一律换 `-`、小写
+  const norm = (s: string) => s.trim().replace(/^@+/, '').replace(/[^a-z0-9-]/gi, '-').toLowerCase()
+  const e = norm(entryName)
+  if (!e) return false
+  const t = norm(target) // @scope/pkg → scope-pkg
+  const tShort = norm(target.replace(/^@[^/]+\//, '')) // @scope/pkg → pkg（无 scope 时与原串一致）
+  // 1) 全串相等：覆盖 完整名 == 完整名 / 去@ == 去@ / scope-pkg == scope/pkg 归一化
+  if (e === t) return true
+  // 2) 条目是去 scope 的短名（bundle patch 手写短名最常见）
+  if (e === tShort) return true
+  // 3) 反向变体：目标短名可能就是条目的完整形式（条目 `scope-widget`，
+  //    目标短名 `widget` 是它的尾段）——用「条目名以短名结尾」收口，避免误伤。
+  if (tShort.length >= 2 && e.endsWith(`-${tShort}`)) return true
+  return false
+}
+
+/**
+ * 卸载成功后从运行中 loader 停用指定包的条目，使卸载立即生效（刷新页面不再
+ * 加载已卸载的 client bundle，也无需重启）。做法：按 name 扫描
+ * `loader.entries()`（含嵌套子树），对每个匹配条目
+ * `entry.update({ disabled: true })` 做 live-disable —— fiber 被 dispose，
+ * client-modules 对账后不再把它写进 `__DSH_BOOT__`，页面刷新即恢复。
+ * 返回 true = 无需重启（条目已停用，或本就没加载过）；false = 未能停用，
+ * 需登记「待重启清理」兜底。宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
+ */
+export async function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean> {
+  if (name === 'dsh-plugin' || name.startsWith('@deepseek-ai/')) return false
+  // 5s 超时兜底：fiber dispose 卡住时不能让卸载任务（乃至整个队列）被拖死
+  const removal = (async () => {
+    const entries = dumpLoaderEntries(loader)
+    const match = entries.find((e) => e.name === name)
+    console.log(`[hub-uninstall] loader=${entries.length} entries; target=${name}; match=${match ? match.id : 'none'}; names=${entries.map((e) => e.name ?? '').join(',')}`)
+    let found = false
+    for (const entry of Array.from(loader.entries())) {
+      if (!nameMatches(entry.options?.name, name)) continue
+      found = true
+      // force=true：disable 可能落在 init 进行中，options 翻转但 fiber 仍会起来，
+      // 重试直到实际状态与目标一致
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          await entry.update({ disabled: true }, false, true)
+          break
+        } catch (error) {
+          console.log(`[hub-uninstall] disable ${name} attempt ${attempt + 1} failed: ${error instanceof Error ? error.message : String(error)}`)
+          if (attempt === 2) return false
+          await new Promise((resolvePromise) => setTimeout(resolvePromise, 200))
+        }
+      }
+    }
+    if (!found) {
+      // 运行中 loader 无该条目：宿主从未加载过它（装完未重启），磁盘已干净，无需重启
+      console.log(`[hub-uninstall] no live entry for ${name}; nothing to disable`)
+    }
+    return true
+  })()
+  const result = await Promise.race([
+    removal.catch((error) => {
+      console.log(`[hub-uninstall] disable failed: ${error instanceof Error ? error.message : String(error)}`)
+      return false
+    }),
+    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 5_000)),
+  ])
+  console.log(`[hub-uninstall] disable ${name} -> ${result ? 'ok/clean' : 'timed out or failed'}`)
+  return result
+}

package/src/server/services/pending-restart.ts

@@ -0,0 +1,36 @@
+/** 待重启列表的内存态管理（宿主进程一重启自然清空）。 */
+import type { PendingRestart } from './install-types.ts'
+
+const pendingRestarts: PendingRestart[] = []
+
+/**
+ * 登记一条待重启记录（同一目标去重）。
+ * - 卸载：目标刚装完未重启（已有待重启记录）→ 宿主从未加载过它，卸完磁盘已干净、
+ *   loader 无残留，无需再提醒重启，直接移除该条；否则（此前已被宿主加载过）登记「卸载后待重启清理」。
+ * - 安装：已有记录则刷新为安装语义（如卸载后未重启又重装），否则新登记。
+ */
+export function addPendingRestart(target: string, kind: 'install' | 'uninstall'): void {
+  const existing = pendingRestarts.find((p) => p.target === target)
+  if (kind === 'uninstall') {
+    if (existing) pendingRestarts.splice(pendingRestarts.indexOf(existing), 1)
+    else pendingRestarts.push({ target, kind, at: Date.now() })
+    return
+  }
+  if (existing) {
+    existing.kind = 'install'
+    existing.at = Date.now()
+  } else {
+    pendingRestarts.push({ target, kind, at: Date.now() })
+  }
+}
+
+/** 当前待重启列表快照（副本，消费方不会污染内部数组）。 */
+export function listPendingRestarts(): PendingRestart[] {
+  return pendingRestarts.map((p) => ({ ...p }))
+}
+
+/** 清除某目标的待重启记录（卸载已即时生效、无需重启时调用）。 */
+export function clearPendingRestart(target: string): void {
+  const index = pendingRestarts.findIndex((p) => p.target === target)
+  if (index >= 0) pendingRestarts.splice(index, 1)
+}

package/src/server/services/preflight.ts

@@ -0,0 +1,97 @@
+/**
+ * 安装前预检：对 `github:` 源的插件，检查其分发（codeload tarball）里是否
+ * 真的包含 package.json 声明的入口文件（main / exports["."].default）。
+ * git 分发常不提交构建产物（lib/ 等），这类残缺包装完会让宿主重启加载插件树时
+ * ERR_MODULE_NOT_FOUND 直接崩溃 —— 预检在动手安装前就把它们拦下，避免白装一次。
+ * npm 包信任 registry 的完整性，直接放行；任何无法预检的情况也放行，交给装后
+ * 校验（verifyInstalledEntry）兜底，保证预检自身失败不会卡死安装流程。
+ */
+import { execFile } from 'node:child_process'
+import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { get } from 'node:https'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/** 预检结果：ok=false 表示分发改入口文件缺失，missing 为该文件在包内的相对路径。 */
+export interface PreflightResult {
+  ok: boolean
+  missing: string | null
+}
+
+export async function preflightTarget(target: string): Promise<PreflightResult> {
+  const m = /^github:([^/]+)\/([^/]+)$/.exec(target)
+  if (m === null) return { ok: true, missing: null }
+  const [, owner, repo] = m
+  let commit = ''
+  try {
+    const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD'])
+    commit = stdout.split(/\s+/)[0] ?? ''
+  } catch {
+    return { ok: true, missing: null }
+  }
+  if (!commit) return { ok: true, missing: null }
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'))
+  try {
+    const tar = join(dir, 'pkg.tar.gz')
+    await download(`https://codeload.github.com/${owner}/${repo}/tar.gz/${commit}`, tar)
+    const meta = await readTarJson(tar, 'package/package.json')
+    if (meta === null) return { ok: true, missing: null }
+    const dot = (meta.exports as Record<string, unknown> | undefined)?.['.']
+    const resolved = typeof dot === 'string'
+      ? dot
+      : dot !== null && typeof dot === 'object'
+        ? (dot as Record<string, unknown>).default
+        : undefined
+    const entry = typeof resolved === 'string' ? resolved : typeof meta.main === 'string' ? meta.main : 'index.js'
+    const inTar = await hasTarEntry(tar, `package/${entry}`)
+    return { ok: inTar, missing: inTar ? null : entry }
+  } catch {
+    return { ok: true, missing: null }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+function download(url: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    get(url, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302 || res.statusCode === 303) {
+        res.resume()
+        if (res.headers.location) {
+          void download(res.headers.location, dest).then(resolve, reject)
+          return
+        }
+      }
+      if (res.statusCode !== 200) {
+        res.resume()
+        reject(new Error(`download failed: HTTP ${res.statusCode ?? '?'}`))
+        return
+      }
+      void pipeline(res, createWriteStream(dest)).then(resolve, reject)
+    }).on('error', reject)
+  })
+}
+
+/** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
+async function readTarJson(tar: string, entry: string): Promise<Record<string, unknown> | null> {
+  try {
+    const { stdout } = await execFileAsync('tar', ['-xzOf', tar, entry], { maxBuffer: 4 * 1024 * 1024 })
+    return JSON.parse(stdout) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+/** 检查 tarball 内是否存在指定 entry。 */
+async function hasTarEntry(tar: string, entry: string): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync('tar', ['-tzf', tar, entry], { maxBuffer: 1024 * 1024 })
+    return stdout.split(/\r?\n/).some((line) => line === entry)
+  } catch {
+    return false
+  }
+}

package/src/server/services/profile.ts

@@ -0,0 +1,89 @@
+/**
+ * 宿主 profile 与目标校验工具：解析当前 profile、目录定位、安装目标语法校验，
+ * 以及 pnpm allowBuilds 白名单的写入（失败恢复路径）。
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { PACKAGE_RE, REPO_RE } from './install-types.ts'
+
+/** Resolve the active profile from the booted CLI args, falling back to `web`. */
+export function readProfileArg(fallback = 'web'): string {
+  const index = process.argv.indexOf('--profile')
+  const candidate = index >= 0 ? process.argv[index + 1] : undefined
+  return candidate !== undefined && !candidate.startsWith('-') ? candidate : fallback
+}
+
+/** Resolve a profile directory (`DSH_HOME` or `~/.dsh`). */
+export function profileDirectory(profile: string): string {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile)
+}
+
+/** Build a safe `github:<owner>/<repo>` target, or null when the repo is unsafe. */
+export function githubTarget(repo: string): string | null {
+  if (typeof repo !== 'string' || !REPO_RE.test(repo)) return null
+  return `github:${repo}`
+}
+
+/** Validate an npm package name (uninstall target grammar). */
+export function validPackageName(name: string): boolean {
+  return typeof name === 'string' && PACKAGE_RE.test(name)
+}
+
+/**
+ * The exact `allowBuilds` key pnpm printed in its
+ * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For `github:` installs pnpm
+ * matches against `name@<resolved fetch URL>` — the URL it actually fetches,
+ * e.g. `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>` — not the
+ * `git+ssh://`/branch spec. A bare name or a `git+` spec does not match, so
+ * the only reliable key is the one pnpm prints verbatim. Null when absent.
+ */
+export function parseAllowBuildsKey(output: string): string | null {
+  const m = /^[ \t]*(\S+@\S+):[ \t]*true[ \t]*$/m.exec(output)
+  return m === null ? null : m[1].trim()
+}
+
+/** Quote a YAML block-mapping key when a plain scalar would be invalid. */
+function quoteYamlKey(key: string): string {
+  if (/^[-?:,[\]{}#&*!|>'"%@`]/.test(key) || /:(\s|$)/.test(key)) {
+    return `'${key.replace(/'/g, "''")}'`
+  }
+  return key
+}
+
+/**
+ * Add one `allowBuilds` entry to the profile's pnpm-workspace.yaml, merging
+ * with existing entries and leaving the rest of the yaml intact. Broken
+ * placeholder entries (pnpm's failed-install bug writes a literal
+ * `set this to true or false` value) are dropped on rewrite.
+ */
+export function addAllowBuildsKey(profile: string, key: string): void {
+  const file = join(profileDirectory(profile), 'pnpm-workspace.yaml')
+  let yaml = ''
+  try { yaml = readFileSync(file, 'utf8') } catch { /* created below */ }
+  const eol = /\r\n/.test(yaml) ? '\r\n' : '\n'
+  const blockRe = /allowBuilds:[ \t]*\r?\n((?:[ \t]+[^\r\n]*\r?\n?)*)/g
+  const map = new Map<string, string>()
+  for (const match of Array.from(yaml.matchAll(blockRe))) {
+    for (const line of match[1].split(/\r?\n/)) {
+      const m = /^[ \t]+(\S.*?)\s*:\s*(true|false)?\s*$/.exec(line)
+      if (m === null || m[1] === '') continue
+      let k = m[1]
+      if (k.length >= 2 && ((k[0] === "'" && k[k.length - 1] === "'") || (k[0] === '"' && k[k.length - 1] === '"'))) {
+        k = k.slice(1, -1)
+      }
+      map.set(k, m[2] ?? 'true')
+    }
+  }
+  map.set(key, 'true')
+  const block = Array.from(map).map(([k, v]) => `  ${quoteYamlKey(k)}: ${v}`).join(eol)
+  const blockText = `allowBuilds:${eol}${block}${eol}`
+  let next: string
+  if (/allowBuilds:[ \t]*\r?\n/.test(yaml)) {
+    let seen = 0
+    next = yaml.replace(blockRe, () => (seen++ === 0 ? blockText : ''))
+  } else {
+    next = `${yaml.replace(/\r?\n?$/, eol)}${blockText}`
+  }
+  writeFileSync(file, next)
+}

package/src/server/services/progress.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure progress-estimation helpers shared by the install runner.
+ *
+ * The dsh CLI wraps pnpm, which refreshes its `Progress: …` line in place
+ * with carriage returns, so raw output arrives as a stream of partial
+ * fragments. These helpers normalize one fragment into a clean terminal
+ * line and map it onto a 0-100 estimate; keeping them free of I/O makes the
+ * estimation logic directly unit-testable (see tests/progress.test.ts).
+ */
+
+/** Strip the `[out]` / `[err]` source prefix and ANSI escape sequences. */
+export function cleanLine(raw: string): string {
+  return raw.replace(/^\[(?:err|out)\]\s*/, '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').trim()
+}
+
+/**
+ * Estimate 0-100 progress from one CLI output line. pnpm emits
+ * `Progress: resolved N, reused X, downloaded Y, added Z` during the fetch
+ * phase; resolution/install phase lines bump the estimate towards done.
+ */
+export function estimateProgress(line: string): number {
+  const progress = line.match(/Progress:\s*(.+)/)
+  if (progress) {
+    let resolved = 0
+    let handled = 0
+    for (const part of progress[1].split(',')) {
+      // pnpm emits `label count` tokens, e.g. `resolved 100, reused 40`
+      const [label, raw] = part.trim().split(/\s+/)
+      const value = Number(raw)
+      if (label === 'resolved') resolved = value
+      else if (label === 'reused' || label === 'downloaded' || label === 'added' || label === 'imported') {
+        handled += value
+      }
+    }
+    // pnpm 的 resolved 是"解析出的包数"，reused/downloaded/added 是"已处理的包数"，
+    // 两者几乎总是相等，比值没有进度区分度（一出现就贴满 100%）。
+    // fetch 阶段只占安装总时长的一小部分（git 依赖之后还要 clone + 跑 prepare 构建），
+    // 因此按已处理量在低区间（8-30）缓步推进，把中段留给真正的安装/构建阶段。
+    if (resolved > 0 && handled > 0) {
+      return Math.min(30, 8 + Math.round((handled / resolved) * 20))
+    }
+    return resolved > 0 ? 8 : 0
+  }
+  if (/^dependencies:|^Packages:/i.test(line)) return 85
+  if (/^Running\b|prepare|build scripts/i.test(line)) return 60
+  if (/^Done in\b/i.test(line)) return 96
+  return 0
+}