dsh-plugin 1.6.11 → 2.0.0

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

@@ -17,27 +17,26 @@ export interface InstallResult {
 
 export interface InstallTask {
   id: number
-  /** 操作目标：显式 HTTPS Git URL（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+  /** 操作目标：npm 包名（安装、更新、卸载一致），冲突/恢复时需要展示给用户 */
   target: string
   /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
   displayTarget?: string
-  /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
-   *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
-   *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+  /** 尝试过的安装方式（实际执行过的 CLI 命令，按先后顺序）：
+   *  失败提 Issue 时如实贴给作者，作者据此判断我们真正执行了什么。 */
   attempts: string[]
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
   globalNpm?: string[]
   action: 'add' | 'remove' | 'update'
-  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+  /** 自定义安装入口渠道（NPM 包卡片）：
    *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装无此字段。 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  installChannel?: 'npm'
   /** 队列语义：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 插件 / 更新（ESM 缓存取不到新代码）/
    *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
@@ -70,7 +69,7 @@ export interface QueueItem {
     timeoutMs?: number
     env?: NodeJS.ProcessEnv
     globalNpm?: string[]
-    installChannel?: 'npm' | 'git' | 'dsh'
+    installChannel?: 'npm'
   }
 }
 
@@ -79,7 +78,7 @@ export interface QueueItem {
  * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
  */
 export interface PendingRestart {
-  /** Git 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+  /** 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
   target: string
   /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
   kind: 'install' | 'uninstall'
@@ -87,13 +86,13 @@ export interface PendingRestart {
   at: number
 }
 
-/** Grammar of a catalog GitHub repository identity (`owner/repo`). */
+/** 目录 GitHub 仓库身份（`owner/repo`）的语法。 */
 export const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/
-/** Grammar of an npm package name (used for uninstall targets). */
+/** npm 包名的语法（用于卸载目标）。 */
 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/install.ts

@@ -20,7 +20,6 @@ export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts'
 export {
   addAllowBuildsKey,
-  githubRefOf,
   githubRepoOf,
   githubTarget,
   globalNpmPackagesOf,

package/src/server/services/install/npm-check.ts

@@ -5,8 +5,9 @@
  *
  * 本机 npm 环境检测：判断一次安装失败是否源于「本机 npm 版本过低」。
  *
- * 背景：pnpm 在 git 源插件的 prepare 阶段会调 npm 装依赖，npm arborist 在解 peer 依赖时有
- * 已知内部崩溃 —— `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
+ * 背景：pnpm 在带 `prepare` 构建脚本的依赖上会调 npm 装依赖（npm 包同样可能带原生
+ * 依赖或 git 依赖），npm arborist 在解 peer 依赖时有已知内部崩溃 ——
+ * `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
  * 该报错会被 pnpm 包进 ERR_PNPM_PREPARE_PACKAGE 输出，不能按插件打包问题引导用户提 Issue。
  *
  * 这里的 `npmTooLowMarker` 是纯函数（输出文本 + 环境 → 标记行或 null），不触碰任务/队列，

package/src/server/services/install/npm-resolve.ts

@@ -3,50 +3,18 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * npm 包反查：git 分发不完整（缺构建产物/子模块）导致安装失败时，用 npm
- * registry 的搜索接口按 repository 地址反查该仓库对应的官方 npm 包。
+ * npm 包校验：确认某个 npm 包确实属于该 GitHub 仓库、且声明为 DSH 插件
+ * （包元数据里的 repository 指向该仓库，并带 `dsh-plugin` 关键词或 `dsh` manifest）。
  *
  * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
- * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
- * 从而把 git 分发不完整的插件切换到 npm 通道安装。命中结果带内存缓存，
- * 避免同一会话内重复查询 registry。
+ * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中。
  */
 import { get } from 'node:https'
 import { githubRepoOf } from '../profile/profile.ts'
 import { finalUrl } from '../probe.ts'
 
-/** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
-const cache = new Map<string, string | null>()
-
-/** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
+/** 单次 registry 查询超时（ms）：慢网络下失败返回 false，不阻塞安装流程。 */
 const REQUEST_TIMEOUT_MS = 8000
-/** npm search 是相关性搜索而非 repository 精确索引；拉满单页结果后再本地做严格 repo 过滤。 */
-const SEARCH_RESULT_LIMIT = 250
-
-/**
- * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
- * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
- * 原有错误路径，反查只是额外的一次尝试。只有「已确认」的结果（包名，或 200
- * 响应下确认无匹配）会进缓存；网络异常/超时/解析失败不缓存，同一会话内下次
- * 安装仍会重试反查，避免一次瞬时故障把整个会话锁死在 git 通道。
- * registry 参数：npm 镜像源地址，空串 = 官方源；与安装通道吃同一 registry，
- * 保证「配置了镜像」时反查和安装走同一个源（镜像节点同步完整时结果一致）。
- * proxy 参数：GitHub 改名跳转探测走的代理（与安装/诊断同一口径）。
- * 慢网络下失败不阻塞安装。
- */
-export async function resolveNpmPackage(repo: string, registry = '', proxy = ''): Promise<string | null> {
-  const key = repo.toLowerCase()
-  if (cache.has(key)) return cache.get(key) ?? null
-  let found = await searchRepo(repo, registry)
-  // 仓库改名后 npm 包的 repository 已指向新名，按旧名反查不到：跟随一次 GitHub 的
-  // 改名跳转拿到规范名再查一遍（旧地址本身仍可用，只是仓库名变了）。
-  if (found === null) {
-    const canonical = await canonicalRepo(repo, proxy)
-    if (canonical !== '' && canonical.toLowerCase() !== key) found = await searchRepo(canonical, registry)
-  }
-  if (found !== undefined) cache.set(key, found)
-  return found ?? null
-}
 
 type NpmSearchPackage = {
   name?: unknown
@@ -56,16 +24,7 @@ type NpmSearchPackage = {
   dsh?: unknown
 }
 
-type NpmSearchObject = { package?: NpmSearchPackage }
-type NpmSearchResponse = { objects?: NpmSearchObject[] }
-
-/**
- * Pick the installable npm package for one GitHub repository. npm search is a
- * relevance-ranked text search, not an exact repository index, so first filter
- * by repository URL. If a monorepo publishes both a CLI/helper package and a
- * DSH plugin, prefer the package that explicitly advertises the `dsh-plugin`
- * keyword instead of whichever result npm happened to rank first.
- */
+/** 从包元数据取 repository 地址：字符串或 `{ url }` 对象，缺省回退 search 结果的 links.repository。 */
 function repositoryUrlOf(pkg: NpmSearchPackage): string {
   if (typeof pkg.repository === 'string') return pkg.repository
   if (pkg.repository !== null && typeof pkg.repository === 'object') {
@@ -83,6 +42,10 @@ export function isDshPackageMetadataForRepo(pkg: NpmSearchPackage, repo: string)
   return keywordMarked || manifestMarked
 }
 
+/**
+ * 校验包名对应的 npm 包确实属于该仓库且声明为 DSH 插件：取 registry 上的 `latest`
+ * 元数据比对 repository 与插件标记。网络异常、超时、非 200 一律返回 false，不阻塞调用方。
+ */
 export function isDshNpmPackageForRepo(packageName: string, repo: string, registry = '', proxy = ''): Promise<boolean> {
   if (packageName === '' || repo === '') return Promise.resolve(false)
   const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
@@ -130,56 +93,3 @@ async function canonicalRepo(repo: string, proxy: string): Promise<string> {
   const canonical = final === null ? null : githubRepoOf(final)
   return canonical !== null && canonical.toLowerCase() !== key ? canonical : ''
 }
-
-function matchingPackagesForRepo(objects: NpmSearchObject[], repo: string): Array<{ name: string; isDshPlugin: boolean }> {
-  const matches: Array<{ name: string; isDshPlugin: boolean }> = []
-
-  for (const obj of objects) {
-    const pkg = obj.package
-    if (typeof pkg?.name !== 'string' || pkg.name === '') continue
-    const repoUrl = repositoryUrlOf(pkg)
-    if (githubRepoOf(repoUrl)?.toLowerCase() !== repo.toLowerCase()) continue
-    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : []
-    matches.push({
-      name: pkg.name,
-      isDshPlugin: keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin'),
-    })
-  }
-
-  return matches
-}
-
-export function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null {
-  const matches = matchingPackagesForRepo(objects, repo)
-  return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null
-}
-
-/** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。
- * 返回：包名 = 命中；null = 200 响应下确认无匹配；undefined = 本次未能确认（网络/超时/解析失败）。 */
-function searchRepo(repo: string, registry: string): Promise<string | null | undefined> {
-  const [owner, name] = repo.split('/')
-  if (owner === undefined || name === undefined || name === '') return Promise.resolve(null)
-  const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
-  const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=${SEARCH_RESULT_LIMIT}`
-  return new Promise((resolve) => {
-    const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
-      if (res.statusCode !== 200) {
-        res.resume()
-        resolve(undefined)
-        return
-      }
-      let body = ''
-      res.on('data', (chunk: Buffer) => { body += chunk.toString() })
-      res.on('end', () => {
-        try {
-          const data = JSON.parse(body) as NpmSearchResponse
-          resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`))
-        } catch {
-          resolve(undefined)
-        }
-      })
-    })
-    req.on('timeout', () => req.destroy())
-    req.on('error', () => resolve(undefined))
-  })
-}

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

@@ -4,17 +4,12 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * 分发文件解析：从 package.json 推出装完后必须真实存在的文件 —— 作者声明的入口
- * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch）。git 通道（tar 预检）
- * 与 npm 通道（装后 statSync 校验）共用，保证两条通道对同一个包判定一致。
+ * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch），供装后校验使用。
  *
- * 这里不替作者补一个 index.js：宿主加载一个 bundle 读的是它的 package.json 和它声明的
- * 补丁文件（官方 bundleManifest 的注释即「Read bundle metadata without loading its
- * JavaScript」），从不 import 包本身。凭空要求一个作者没声明的入口，只会把完整的
- * 技能包判成分发残缺，并把一条假缺陷推到作者仓库（见 QingYunA/answer-me-with-html#209）。
- *
- * 例外是补丁自己 mount 了本包：dsh 的《打包与安装插件》里组合包的常规写法就是
- * `- insert: - name: <本包名>`，宿主随后按包名 import 本包，入口那时必须存在。
- * 所以只有补丁真的写了自己的包名，才把这个入口算进分发要求。
+ * 只在包自己声明了入口时才要求它存在：宿主加载 bundle 读的是它的 package.json 与声明的补丁，
+ * 从不 import 包本身。硬要一个作者没声明过的 index.js，会把完整的包判成分发残缺、把一条假缺陷
+ * 推到作者仓库。例外是补丁自己 mount 了本包（组合包的常规写法）—— 那时宿主按包名 import 本包，
+ * 入口必须存在，所以只有补丁真的写了自己的包名才把这个入口算进分发要求。
  */
 
 /** exports 条件对象里按优先级尝试的键；Node 语义下 default 最宽，import/require 次之。 */
@@ -53,7 +48,7 @@ export function resolvePackageEntry(meta: PackageManifest): string | null {
 /**
  * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
  * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
- * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ * bundlePatchFiles 的报错职责，装后校验只负责「声明了就要在包里存在」。
  */
 export function resolveBundlePatchFiles(meta: PackageManifest): string[] {
   const patch = (meta.dsh as { bundle?: { patch?: unknown } } | undefined)?.bundle?.patch

package/src/server/services/install/registry-check.ts

@@ -3,20 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 官方 registry 存在性复核：把「包在 registry 上不存在」这类失败的责任方分开。
- *
- * 背景：安装失败日志出现 `ERR_PNPM_FETCH_404` / `Not Found - 404` 时，光看日志分不清三种情形：
- *   ① 缺的包是 **profile 自己声明的依赖**（历史残留条目，指向一个从未发布的包）—— 用户环境问题：
- *      pnpm 每次解析依赖都会先卡在它上面，任何插件都装不进来（issue #73），提示删掉该条目即可；
- *   ② 缺的包来自**插件的依赖树**，且该包在官方 registry 上也不存在 —— 作者侧问题（漏声明依赖、
- *      依赖被删除或从未发布），应引导用户投插件作者仓库；
- *   ③ 缺的包来自插件依赖树，但官方 registry 上有 —— 用户本机 registry 指向的镜像/私有源未同步
- *      该包，属用户环境问题，提示换源即可。
- * 故本模块先排除 ①（读 profile 的 package.json），再用**官方** registry（registry.npmjs.org，
- * 绕开本机可能配置的镜像）复查存在性，产出 ② / ③ 的标记行。
- *
- * 与 npm-check.ts 同构：本模块只产出「标记行」，由 task-queue 追加到任务输出，前端按标记分类。
- * fetch 与 profile 目录都可注入，便于单测覆盖全部结论而不依赖网络。
+ * 官方 registry 存在性复核：用官方源（绕开本机镜像）复查 404 的包，产出标记行区分
+ * 「profile 残留依赖」「插件依赖在官方源也不存在（作者侧）」「本机镜像未同步」三种情形；
+ * 标记由 task-queue 追加到任务输出，前端按标记归类。fetch 与 profile 目录可注入，便于单测。
  */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -80,8 +69,8 @@ export async function registryMissingMarker(
 ): Promise<string | null> {
   const name = missingPackageOf(output)
   if (name === null) return null
-  // ① profile 自己声明的残留依赖（#73）：用户环境问题，交给既有的 pnpmMissingDep 提示（该提示就是
-  // 教用户删 profile 里那条依赖），这里不再产出标记、不改归属
+  // 该包是 profile 自己声明的依赖（用户环境里留下的条目）→ 用户环境问题，交给既有的 pnpmMissingDep
+  // 提示处理（那条提示就是教用户删掉它），不产出标记、不改归属
   if (profileDependencyNames(opts.profileDir).some((dep) => dep.toLowerCase() === name.toLowerCase())) return null
   const exists = await existsOnOfficialRegistry(name, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 8000)
   if (exists === false) {

package/src/server/services/install/release-target.ts

@@ -3,14 +3,13 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 预构建 GitHub release 安装目标（目录权威命令 → 可安装直链）。
- * 部分插件（如 loopx）把构建产物发布成 GitHub release 的 .tgz，仓库 HEAD 反而是
- * monorepo 根、走 git 直装会因缺入口文件失败；目录下发的权威安装命令直接指向该
- * release 包。这里把「目录命令」解析成安全的 release 目标，供客户端选路与服务端
- * 校验共用（单一事实来源，避免两端口径漂移）。
+ * 预构建 release 直链的仓库身份解析。部分插件（如 loopx）当初以 GitHub release 的 .tgz
+ * 安装过，仓库 HEAD 反而是 monorepo 根、走 git 直装会因缺入口文件失败；老安装记录里留的
+ * 就是这种 release 直链。这里把「历史安装目标」还原成所属仓库身份，供已装态读回、队列
+ * 去重与展示复用（单一事实来源，避免两端口径漂移）。
  *
  * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
- * 目录命令是展示数据、绝非 shell 代码，绝不执行命令文本；跨仓跳转、外部主机、凭据、
+ * 输入是记录/展示数据、绝非 shell 代码，绝不执行其文本；跨仓跳转、外部主机、凭据、
  * 移动的 latest 链接、query/fragment、多余 CLI 参数与 shell 片段一律拒绝。
  */
 
@@ -22,15 +21,15 @@ export interface GithubReleaseTarget {
   repo: string
 }
 
-/** 目录权威命令：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
+/** 完整命令前缀：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
 const DSH_PLUGIN_CMD_RE = /^dsh[ \t]+plugin[ \t]+--profile(?:[ \t]+|=)[A-Za-z0-9_-]+[ \t]+(?:add|update)[ \t]+(.+)$/i
 
 /** 固定形态的 release .tgz 直链：主机、路径段与扩展名全部锁死。 */
 const RELEASE_URL_RE = /^https:\/\/github\.com\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+\.tgz)$/
 
 /**
- * 解析一个 release 安装目标。
- * @param value - 目录命令（`dsh plugin --profile web add <url>`）或裸直链。
+ * 解析一个历史安装目标里的 release 直链。
+ * @param value - 完整命令（`dsh plugin --profile web add <url>`）或裸直链。
  * @returns 命中返回 `{ target, repo }`，否则 null。
  */
 export function githubReleaseTarget(value: string): GithubReleaseTarget | null {