dsh-plugin 0.1.0 → 1.0.0

package/src/client/styles/tokens.module.css

@@ -0,0 +1,86 @@
+/* Plugin Hub design tokens.
+ *
+ * Semantic aliases over the host's --dsw-alias-* theme tokens, each with the
+ * original light-mode literal as fallback for hosts that do not define the
+ * underlying token. Declared on :root and on the dark body so every theme
+ * re-resolves the aliases against its own token set; the custom property is
+ * then inherited by all section elements.
+ *
+ * Keep raw colors out of the per-area stylesheets: reference --hub-* here so
+ * new styles pick up the theme automatically. */
+:root,
+body[data-ds-dark-theme] {
+  /* text */
+  --hub-text-primary: var(--dsw-alias-label-primary, #1f2328);
+  --hub-text-secondary: var(--dsw-alias-label-secondary, #6b7280);
+  --hub-text-tertiary: var(--dsw-alias-label-tertiary, #8b93a1);
+  --hub-text-disabled: var(--dsw-alias-label-disabled, #aab1bd);
+  --hub-text-on-fill: var(--dsw-alias-label-primary-foreground, #ffffff);
+
+  /* surfaces */
+  --hub-bg-1: var(--dsw-alias-bg-layer-1, #ffffff);
+  --hub-bg-2: var(--dsw-alias-bg-layer-2, rgba(128, 128, 128, 0.08));
+  --hub-bg-3: rgba(128, 128, 128, 0.1);
+  /* 计数胶囊底色（已安装/未安装按钮内的数量胶囊） */
+  --hub-bg-btn: rgba(128, 128, 128, 0.12);
+  --hub-bg-hover: var(--dsw-alias-interactive-bg-hover, rgba(128, 128, 128, 0.16));
+  --hub-bg-on-fill: rgba(128, 128, 128, 0.22);
+
+  /* borders */
+  --hub-border-1: var(--dsw-alias-border-l1, #eceef1);
+  --hub-border-2: var(--dsw-alias-border-l2, #e5e7eb);
+  --hub-border-ghost: var(--dsw-alias-button-ghost-active-border, rgba(79, 110, 247, 0.25));
+  --hub-border-input: var(--dsw-alias-input-border, rgba(107, 114, 128, 0.25));
+
+  /* brand (fixed in both themes) */
+  --hub-brand: var(--dsw-alias-state-business-primary, #4f6ef7);
+  --hub-brand-hover: #3b5bdb;
+  --hub-brand-tint: rgba(79, 110, 247, 0.06);
+  --hub-brand-tint-strong: rgba(79, 110, 247, 0.12);
+  --hub-brand-border: rgba(79, 110, 247, 0.35);
+  --hub-brand-border-soft: rgba(79, 110, 247, 0.22);
+
+  /* purple brand accents (fixed in both themes) */
+  --hub-purple-1: #4f46e5;
+  --hub-purple-2: #7c3aed;
+  --hub-purple-border: rgba(139, 92, 246, 0.55);
+  --hub-purple-tint: rgba(79, 70, 229, 0.08);
+  --hub-purple-shadow: rgba(79, 70, 229, 0.28);
+  --hub-purple-shadow-strong: rgba(124, 58, 237, 0.42);
+
+  /* primary action button */
+  --hub-btn-fill: var(--dsw-alias-button-primary-fill, #1f2328);
+  --hub-btn-hover: var(--dsw-alias-button-primary-hover, #43454a);
+
+  /* success */
+  --hub-success: var(--dsw-alias-state-success-primary, #1a7f37);
+  --hub-success-tint: rgba(34, 197, 94, 0.14);
+  --hub-success-border: var(--dsw-alias-state-success-secondary, rgba(26, 127, 55, 0.3));
+
+  /* warning (amber) */
+  --hub-warn: var(--dsw-alias-state-warn-primary, #b8860b);
+  --hub-warn-tint: rgba(184, 134, 11, 0.08);
+  --hub-warn-border: rgba(184, 134, 11, 0.35);
+  --hub-warn-strong: rgba(184, 134, 11, 0.85);
+
+  /* warning (deep amber) */
+  --hub-warning: var(--dsw-alias-state-warning-primary, #b45309);
+  --hub-warning-tint: rgba(180, 83, 9, 0.08);
+  --hub-warning-border: rgba(180, 83, 9, 0.3);
+
+  /* danger */
+  --hub-danger: var(--dsw-alias-state-danger-primary, #d1242f);
+  --hub-danger-hover: var(--dsw-alias-state-danger-hover, #b91c1c);
+  --hub-danger-strong: #b0202a;
+  --hub-danger-text: #e5484d;
+  --hub-danger-tint: rgba(229, 72, 77, 0.08);
+  --hub-danger-tint-weak: rgba(229, 72, 77, 0.05);
+  --hub-danger-border: rgba(229, 72, 77, 0.35);
+  --hub-danger-border-soft: rgba(229, 72, 77, 0.28);
+  --hub-danger-soft: rgba(209, 36, 47, 0.08);
+}
+
+/* 暗色下的计数胶囊底色：白半透明，深色底上更可辨 */
+body[data-ds-dark-theme] {
+  --hub-bg-btn: rgba(255, 255, 255, 0.12);
+}

package/src/client/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared types for the dsh-plugin browser client. Kept dependency-free so
+ * any client module can import them without pulling in components or styles.
+ */
+
+export type LocaleId = 'zh' | 'en'
+
+/** Translation function signature shared by the host binder and the in-component dictionary. */
+export type Translate = (key: string, params?: Record<string, string | number>) => string
+
+/** The subset of the locale service this plugin touches. */
+export interface LocaleService {
+  register(namespace: string, dicts: { zh: Record<string, string>; en: Record<string, string> }): unknown
+  bind(namespace: string): (key: string, params?: Record<string, string | number>) => string
+  getSnapshot(): { active: LocaleId }
+  subscribe(fn: () => void): () => void
+}
+
+/** The subset of the slots service this plugin touches. */
+export interface SlotsService {
+  inject(slot: string, register: () => unknown): void
+  register(meta: Record<string, unknown>, component: () => unknown): unknown
+}
+
+/** The client cordis context shape this plugin relies on (structural). */
+export interface HubClientContext {
+  effect(callback: () => unknown, label?: string): void
+  slots: SlotsService
+  locale: LocaleService
+}
+
+export interface SectionProps {
+  t: Translate
+  locale: LocaleService
+}
+
+/** Slim projection of the site's DirectoryPlugin entries. */
+export interface HubPlugin {
+  /** 作者小写 key，与 slug 共同构成唯一身份（两级路径 /plugins/{ownerSlug}/{slug}）；旧数据可能缺省 */
+  ownerSlug?: string
+  slug: string
+  displayName?: string
+  /** 仓库已发布版本（GitHub release tag，如 v1.2.3）；无 release 的仓库无此字段 */
+  version?: string
+  category?: string
+  topics?: string[]
+  features?: string[]
+  description?: string
+  source?: { repo?: string }
+  compatibility?: { status?: string }
+  dates?: { repoUpdatedAt?: string; addedAt?: string }
+  stats?: { stargazers_count?: number; forks_count?: number }
+}
+
+/** 后台安装/卸载任务快照：进度 0-100 + 实时输出行（服务端估算，客户端轮询）。 */
+export interface TaskState {
+  id: number
+  /** pending 排队中 / running 执行中 / cancelling 取消中（客户端过渡态）/ done 完成 / failed 失败 / cancelled 已取消 */
+  status: 'pending' | 'running' | 'cancelling' | 'done' | 'failed' | 'cancelled'
+  progress: number
+  lines: string[]
+}
+
+export type ToastKind = 'copied' | 'errCopied' | 'done' | 'fail' | 'removed' | 'removeFail'
+
+export interface ToastState {
+  id: number
+  kind: ToastKind
+}
+
+/** 宿主机器环境快照（后端 /dsh-plugin-hub/env）：提交 bug 时拼进 issue 正文，便于作者复现。 */
+export interface EnvInfo {
+  dshVersion: string | null
+  nodeVersion: string
+  platform: string
+  arch: string
+  release: string
+  profile: string
+  dshHome: string
+}

package/src/server/http/routes.ts

@@ -0,0 +1,397 @@
+/**
+ * Local HTTP routes exposing real installs to the in-app Plugin Hub UI.
+ * The client fetches the same-origin `/dsh-plugin-hub/*` endpoints; the
+ * install handler validates the target, then spawns the official dsh CLI
+ * (see services/install.ts) and reports the captured result back.
+ */
+import { readFileSync } from 'node:fs'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { homedir, release } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { spawn } from 'node:child_process'
+import { activeTask, cancelTask, dumpLoaderEntries, getTask, githubTarget, hasQueuedTarget, listPendingRestarts, readProfileArg, startPluginMutation, validPackageName, type LoaderHandle } from '../services/install.ts'
+import { recordInstalledVersion, readInstalledVersions, removeInstalledVersion } from '../services/installed-versions.ts'
+import { preflightTarget } from '../services/preflight.ts'
+
+export interface WebRoute {
+  kind: 'exact'
+  path: string
+  handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>
+}
+
+/** The subset of the host web-server service this plugin touches. */
+export interface WebServerService {
+  register(route: WebRoute): () => void
+}
+
+const PROFILE_RE = /^[A-Za-z0-9_-]+$/
+const BODY_LIMIT_BYTES = 4 * 1024
+const COMMAND_TIMEOUT_MS = 5 * 60 * 1000
+
+function profileDirectory(profile: string): string {
+  return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile)
+}
+
+/** Read non-official dependencies installed into one profile. */
+export function readInstalled(profile: string): Record<string, string> {
+  try {
+    const manifest = JSON.parse(readFileSync(join(profileDirectory(profile), 'package.json'), 'utf8')) as {
+      dependencies?: Record<string, string>
+    }
+    return Object.fromEntries(
+      Object.entries(manifest.dependencies ?? {}).filter(([name]) => !name.startsWith('@deepseek-ai/')),
+    )
+  } catch {
+    return {}
+  }
+}
+
+/** 宿主 dsh CLI 版本：从入口（process.argv[1]）向上找最近的 dsh/harness 相关 package.json；找不到返回 null。 */
+function hostDshVersion(): string | null {
+  const entry = process.argv[1]
+  if (entry === undefined) return null
+  let dir = dirname(resolve(entry))
+  for (let depth = 0; depth < 4; depth++) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string }
+      const name = manifest.name ?? ''
+      if (typeof manifest.version === 'string' && (name === 'dsh' || name.includes('dsh') || name.includes('harness'))) {
+        return manifest.version
+      }
+    } catch {
+      /* not a package root — keep walking up */
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/** 宿主环境快照：提交 bug 时随 issue 附上，便于作者复现（前端 /env 端点返回）。 */
+function hostEnv(profile: string): Record<string, string | null> {
+  return {
+    dshVersion: hostDshVersion(),
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    release: release(),
+    profile,
+    dshHome: process.env.DSH_HOME ?? join(homedir(), '.dsh'),
+  }
+}
+
+/** Match an install target (`github:<owner>/<repo>`) against the installed table; returns the package name when already installed. */
+function installedByRepo(installed: Record<string, string>, target: string): string | null {
+  const needle = target.toLowerCase()
+  for (const [name, spec] of Object.entries(installed)) {
+    if (spec.toLowerCase().includes(needle)) return name
+  }
+  return null
+}
+
+function sendJson(response: ServerResponse, status: number, value: unknown): void {
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-type': 'application/json; charset=utf-8',
+  })
+  response.end(JSON.stringify(value))
+}
+
+/** POST mutations are only accepted from the local web server origin. */
+function isSameOrigin(request: IncomingMessage): boolean {
+  const origin = request.headers.origin
+  const host = request.headers.host
+  if (origin === undefined || host === undefined) return false
+  try {
+    const url = new URL(origin)
+    const localHostnames = new Set(['localhost', '127.0.0.1', '[::1]'])
+    return url.host === host && localHostnames.has(url.hostname)
+  } catch {
+    return false
+  }
+}
+
+function requireMethod(request: IncomingMessage, response: ServerResponse, method: 'GET' | 'POST'): boolean {
+  if (request.method === method) return true
+  response.writeHead(405, { allow: method })
+  response.end()
+  return false
+}
+
+function requireTrustedPost(request: IncomingMessage, response: ServerResponse): boolean {
+  if (!requireMethod(request, response, 'POST')) return false
+  if (isSameOrigin(request)) return true
+  sendJson(response, 403, { error: 'untrusted origin' })
+  return false
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buffer.length
+    if (size > BODY_LIMIT_BYTES) throw new Error('request body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * Register the Plugin Hub API on the host web server and return a disposer.
+ * @param webServer - DSH web server service.
+ * @param profile - profile that owns plugin mutations.
+ * @param loader - running loader (optional): lets uninstall remove the entry
+ *   immediately so the page survives a refresh without a host restart.
+ */
+export function mountPluginHubRoutes(webServer: WebServerService, profile: string, loader?: LoaderHandle): () => void {
+  if (!PROFILE_RE.test(profile)) throw new Error(`invalid profile name: ${profile}`)
+  console.log(`[hub] routes mounted (profile=${profile}, loader=${loader === undefined ? 'undefined' : 'provided'})`)
+  const disposers = [
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/debug/loader-entries',
+      handler: (request, response) => {
+        if (!requireMethod(request, response, 'GET')) return
+        sendJson(response, 200, { entries: dumpLoaderEntries(loader) })
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/install',
+      handler: async (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        // 任务自动入队：即使已有插件操作在跑也接受请求（FIFO 串行执行），不再 409 拒绝
+        try {
+          const body = await readJsonBody(request)
+          // mode: 'update' = 已安装目标的覆盖更新（放行 add，pnpm 对已存在依赖原位覆盖重装）
+          const mode = body !== null && typeof body === 'object' && (body as { mode?: unknown }).mode === 'update'
+            ? 'update'
+            : 'install'
+          const rawRepo = typeof body === 'object' && body !== null && typeof (body as { repo?: unknown }).repo === 'string'
+            ? (body as { repo: string }).repo.trim()
+            : ''
+          // 目标语法两态：owner/repo → github 源（走装前预检）；npm 包名（@scope/name 或 name）→ 信任 registry 直接安装
+          const repoTarget = githubTarget(rawRepo)
+          const target = repoTarget ?? (repoTarget === null && validPackageName(rawRepo) ? rawRepo : null)
+          if (target === null) {
+            sendJson(response, 400, { error: 'unsupported install target' })
+            return
+          }
+          // 重复安装防护：非更新请求命中已安装目标时直接拒绝，不重复跑 CLI
+          // （否则 CLI 会因「已存在」失败，且用户看到的是莫名其妙的报错）；
+          // 更新请求（mode: 'update'）放行，CLI 的 add 对已存在依赖是 pnpm 原位覆盖重装
+          const already = installedByRepo(readInstalled(profile), target)
+          if (already !== null && mode !== 'update') {
+            sendJson(response, 409, { error: `already installed: ${already}` })
+            return
+          }
+          // 队列级去重：同一目标已在排队/执行中时拒绝，避免客户端防重竞态导致重复入队
+          if (hasQueuedTarget(target)) {
+            sendJson(response, 409, { error: `already queued: ${target}` })
+            return
+          }
+          // 安装前预检：仅新安装走预检（github 源分发改入口文件缺失时直接拦截）。
+          // 更新是已信任目标的覆盖重装，跳过预检避免重复下载 tarball。
+          // 只支持官方默认安装方式（dsh plugin add github:owner/repo），不做任何 npm 兜底降级；
+          // [packaging] 前缀供客户端归类为「插件未适配官方默认安装方式」并引导去仓库提 Issue
+          if (already === null) {
+            const preflight = await preflightTarget(target)
+            if (!preflight.ok) {
+              sendJson(response, 400, {
+                error: `[packaging] ${target}: does not support the official default install method — the git distribution lacks build output (the entry file ${preflight.missing ?? '?'} declared in package.json is not in the repository). Report to the author.`,
+              })
+              return
+            }
+          }
+          // 入队前复检（与上方检查同语义，但必须在同步块内）：preflight 的 await 期间并发请求
+          // 可能已通过上方检查、任务却尚未入队——此处检查与 startPluginMutation 之间无 await，
+          // JS 单线程保证同一目标至多一个任务，杜绝双击/并发产生双任务
+          if (hasQueuedTarget(target)) {
+            sendJson(response, 409, { error: `already queued: ${target}` })
+            return
+          }
+          // Kick off the CLI in the background; the client polls /status for progress
+          const task = startPluginMutation({
+            action: 'add',
+            profile,
+            target,
+            timeoutMs: COMMAND_TIMEOUT_MS,
+            env: { ...process.env, CI: 'true' },
+          })
+          sendJson(response, 200, { ok: true, task: task.id })
+        } catch (error) {
+          sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/uninstall',
+      handler: async (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        // 与安装一致：卸载也进入同一队列，FIFO 串行执行
+        try {
+          const body = await readJsonBody(request)
+          const name = typeof body === 'object' && body !== null && typeof (body as { name?: unknown }).name === 'string'
+            ? (body as { name: string }).name
+            : ''
+          // 展示用的 owner/repo：卸载命令只需要 npm 包名，但待重启行要与安装行一致地显示仓库名
+          const repo = typeof body === 'object' && body !== null && typeof (body as { repo?: unknown }).repo === 'string'
+            ? (body as { repo: string }).repo
+            : ''
+          if (!validPackageName(name) || name === 'dsh-plugin') {
+            sendJson(response, 400, { error: 'plugin cannot be uninstalled here' })
+            return
+          }
+          if (readInstalled(profile)[name] === undefined) {
+            sendJson(response, 400, { error: 'plugin is not installed' })
+            return
+          }
+          // 队列级去重：同一包已在排队/执行中卸载时拒绝
+          if (hasQueuedTarget(name)) {
+            sendJson(response, 409, { error: `already queued: ${name}` })
+            return
+          }
+          const task = startPluginMutation({
+            action: 'remove',
+            profile,
+            target: name,
+            // 卸载的 mutation 目标是 npm 包名；待重启行要显示 owner/repo（与安装行一致），非法/缺失时回退包名
+            displayTarget: githubTarget(repo) ?? undefined,
+            // 运行中 loader：卸载成功后主动移除条目，立即生效、无需重启
+            uninstallLoader: loader,
+            timeoutMs: COMMAND_TIMEOUT_MS,
+            env: { ...process.env, CI: 'true' },
+          })
+          sendJson(response, 200, { ok: true, task: task.id })
+        } catch (error) {
+          sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/status',
+      handler: (request, response) => {
+        if (!requireMethod(request, response, 'GET')) return
+        const url = new URL(request.url ?? '/', 'http://localhost')
+        const id = Number(url.searchParams.get('task'))
+        const task = Number.isInteger(id) ? getTask(id) : undefined
+        if (!task) {
+          sendJson(response, 404, { error: 'task not found' })
+          return
+        }
+        sendJson(response, 200, { task })
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/active',
+      handler: (request, response) => {
+        if (!requireMethod(request, response, 'GET')) return
+        // 整个任务队列（running 在前、pending 在后）+ 待重启列表：客户端刷新后据此恢复
+        // 进行中/排队任务与「装完没重启」的持久提醒
+        sendJson(response, 200, { tasks: activeTask(), pendingRestarts: listPendingRestarts() })
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/env',
+      handler: (request, response) => {
+        if (!requireMethod(request, response, 'GET')) return
+        // 宿主机器环境快照：提交 bug 的 issue 正文会带上，便于作者复现
+        sendJson(response, 200, hostEnv(profile))
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/cancel',
+      handler: async (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        try {
+          const body = await readJsonBody(request)
+          const id = typeof body === 'object' && body !== null && typeof (body as { id?: unknown }).id === 'number'
+            ? (body as { id: number }).id
+            : NaN
+          const ok = Number.isInteger(id) && cancelTask(id)
+          sendJson(response, 200, { ok })
+        } catch (error) {
+          sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/restart',
+      handler: (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        // 当前宿主监听端口来自请求 Host 头（localhost:7923），解析失败回退 7923
+        const host = request.headers.host ?? ''
+        const portMatch = host.match(/:(\d+)$/)
+        const port = portMatch ? Number(portMatch[1]) : 7923
+        // detached 子 shell 完成「停旧进程 → 等端口释放 → 后台拉起 dsh web」，
+        // 即使当前宿主（即本插件所在进程）被 kill，重启仍会继续执行
+        const script = [
+          `pids=$(lsof -ti tcp:${port} -sTCP:LISTEN 2>/dev/null)`,
+          '[ -n "$pids" ] && kill -TERM $pids 2>/dev/null || true',
+          `i=0; while [ -n "$(lsof -ti tcp:${port} -sTCP:LISTEN 2>/dev/null)" ] && [ $i -lt 20 ]; do sleep 0.25; i=$((i + 1)); done`,
+          'mkdir -p "$HOME/.dsh/logs"',
+          `nohup dsh web --port ${port} >>"$HOME/.dsh/logs/dsh-web-${port}.log" 2>&1 &`,
+        ].join('\n')
+        spawn('/bin/sh', ['-c', script], { detached: true, stdio: 'ignore' }).unref()
+        sendJson(response, 200, { ok: true, port })
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/installed-version',
+      handler: async (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        try {
+          const body = await readJsonBody(request)
+          const repo = typeof body === 'object' && body !== null && typeof (body as { repo?: unknown }).repo === 'string'
+            ? (body as { repo: string }).repo
+            : ''
+          if (githubTarget(repo) === null) {
+            sendJson(response, 400, { error: 'invalid install target' })
+            return
+          }
+          // version 为空 = 卸载清理记录；否则记录安装时的目录信号（最新版本 + 仓库更新时间），
+          // 供「有更新」比对：有版本比版本，无版本比更新时间
+          const version = body !== null && typeof (body as { version?: unknown }).version === 'string'
+            ? (body as { version: string }).version
+            : null
+          if (version === null) {
+            removeInstalledVersion(profile, repo)
+          } else {
+            const updatedAt = body !== null && typeof (body as { updatedAt?: unknown }).updatedAt === 'string'
+              ? (body as { updatedAt: string }).updatedAt
+              : ''
+            recordInstalledVersion(profile, repo, version, updatedAt)
+          }
+          sendJson(response, 200, { ok: true })
+        } catch (error) {
+          sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    }),
+    webServer.register({
+      kind: 'exact',
+      path: '/dsh-plugin-hub/installed',
+      handler: (request, response) => {
+        if (!requireMethod(request, response, 'GET')) return
+        // installed：依赖表（包名 → spec）；versions：安装时记录的目录版本（repo → 版本），
+        // 客户端合并两者判断「是否有更新」
+        sendJson(response, 200, { profile, installed: readInstalled(profile), versions: readInstalledVersions(profile) })
+      },
+    }),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+/** Profile resolution shared with the client route docs. */
+export { readProfileArg }

package/src/server/index.ts

@@ -0,0 +1,35 @@
+/**
+ * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
+ * web server service is available. The browser bundle (src/client) talks to
+ * these same-origin routes to perform real installs from inside the app.
+ */
+import { readProfileArg, type LoaderHandle } from './services/install.ts'
+import { mountPluginHubRoutes, type WebServerService } from './http/routes.ts'
+
+export const name = 'dsh-plugin'
+
+export interface Config {
+  /** DSH profile that owns plugin mutations. Defaults to the booted profile. */
+  profile?: string
+}
+
+/** The subset of the cordis host context this plugin touches. */
+interface HostContext {
+  webServer: WebServerService
+  /** 运行中 loader：卸载成功后主动移除条目、立即生效（宿主未提供时卸载仍需重启） */
+  loader?: LoaderHandle
+  inject(services: string[], callback: (host: HostContext) => void): void
+  effect(callback: () => void, label?: string): void
+}
+
+/**
+ * Mount the Plugin Hub routes after the web server service becomes available.
+ * @param ctx - cordis host context.
+ * @param config - optional profile override.
+ */
+export function apply(ctx: HostContext, config: Config = {}): void {
+  const profile = config.profile ?? readProfileArg('web')
+  ctx.inject(['webServer'], (host) => {
+    host.effect(() => mountPluginHubRoutes(host.webServer, profile, host.loader), 'dsh-plugin: http routes')
+  })
+}

package/src/server/services/install-types.ts

@@ -0,0 +1,63 @@
+/** 安装/卸载运行时的公共类型与常量（无依赖，供各服务模块复用）。 */
+
+/** 一个 pnpm 安装子进程的结果快照。 */
+export interface InstallResult {
+  exitCode: number | null
+  timedOut: boolean
+  error: string | null
+  stdout: string
+  stderr: string
+}
+
+export interface InstallTask {
+  id: number
+  /** 操作目标：`github:<owner>/<repo>`（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+  target: string
+  action: 'add' | 'remove'
+  /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
+  status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled'
+  timedOut: boolean
+  exitCode: number | null
+  /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
+  progress: number
+  /** Newest output lines first (consumer shows the tail). */
+  lines: string[]
+}
+
+/** 子进程启动参数（复用宿主 dsh 入口，或回退到 PATH 上的 `dsh`）。 */
+export interface Invocation {
+  file: string
+  prefixArgs: string[]
+  cwd: string
+  useShell: boolean
+}
+
+/** 排队中的变更任务及其启动参数。 */
+export interface QueueItem {
+  task: InstallTask
+  options: { action: 'add' | 'remove'; profile: string; target: string; timeoutMs?: number; env?: NodeJS.ProcessEnv }
+}
+
+/**
+ * 安装成功但宿主尚未重启的插件（待重启后生效）。纯内存态：宿主进程一重启
+ * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
+ */
+export interface PendingRestart {
+  /** `github:<owner>/<repo>` 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+  target: string
+  /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
+  kind: 'install' | 'uninstall'
+  /** 任务完成时刻（epoch ms） */
+  at: number
+}
+
+/** Grammar of an accepted `github:<owner>/<repo>` install target. */
+export const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/
+/** Grammar of an npm package name (used for uninstall targets). */
+export const PACKAGE_RE = /^(?:@[a-z0-9._-]+\/)?[A-Za-z0-9._-]+$/
+/** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
+export const CAPTURE_LIMIT_BYTES = 64 * 1024
+/** Max output lines kept per task (newest wins). */
+export const MAX_TASK_LINES = 200
+/** Max tracked tasks; oldest finished tasks are dropped first. */
+export const MAX_TASKS = 50

package/src/server/services/install.ts

@@ -0,0 +1,18 @@
+/**
+ * Install runner 的统一出口：执行真实插件变更（spawn 官方 dsh CLI 子进程）。
+ * 实现按职责拆分在同目录子模块，本文件只做公共 API 的 re-export，保持外部
+ * import 面稳定（routes.ts / index.ts 仍从 `services/install.ts` 引入）。
+ *
+ * 模块划分：
+ *  - install-types.ts  公共类型与常量
+ *  - pending-restart.ts  待重启列表内存态管理
+ *  - loader.ts          运行中 loader 的读取与卸载即时停用
+ *  - profile.ts         宿主 profile / 目标校验 / allowBuilds 写入
+ *  - task-queue.ts      任务注册表 + FIFO 队列 worker + 子进程生命周期
+ */
+export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem } from './install-types.ts'
+export type { LoaderHandle } from './loader.ts'
+export { addPendingRestart, clearPendingRestart, listPendingRestarts } from './pending-restart.ts'
+export { dumpLoaderEntries, removeLoadedEntry } from './loader.ts'
+export { addAllowBuildsKey, githubTarget, parseAllowBuildsKey, readProfileArg, validPackageName } from './profile.ts'
+export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts'