Files
deepseek-harness/packages/boot/plugin-manager/src/installer.ts
T
Yichen Jiang ac2bed35e2 feat(web): guide plugin installation with a pre-install check and classified failures
The install dialog asks the Host to read a spec before installing it:
`plugins/inspect` sorts the spec (registry name, absolute path, git address,
tarball), asks the registry through `pnpm view` in the profile directory, or
reads a directory's package.json, and refuses what would fail with
`plugins/inspect-rejected` and a problem the dialog words under the field.
A failed pnpm run carries a `kind` classified from how it ended and what pnpm
printed, shown as one line with the output folded behind the details.
Enabling happens after the fact from the installed screen, which scrolls the
list to the first new bundle. Refusals of the moment and the confirmed
cancellation are toasts; the run is stopped through the manager's
`cancelInstall` and the dialog offers the spec again once the Host confirms.
The non-pack dependency group folds by default under its own name.

The host config gains `inspectTimeoutMs`; the CLI passes it explicitly.
2026-09-15 12:43:44 +08:00

498 lines
22 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Installing and removing packages with pnpm and reading static declarations
* from the profile on disk: nothing here touches a running tree, which
* is what lets the `dsh plugin` command install before any plugin starts.
* @module @deepseek-ai/dsh-plugin-manager/installer
*/
import { spawn as spawnChild } from 'node:child_process'
import { randomUUID } from 'node:crypto'
import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
import type { Readable } from 'node:stream'
import { finished } from 'node:stream/promises'
import { spawnSubprocess } from '@deepseek-ai/dsh-subprocess-local/spawn'
import { join } from 'node:path'
import {
claimLayerIds,
healProfilesModuleFallback,
readPackageMetadata,
readProfileManifest,
reconcileInstalledBundles,
resolveBundleDir,
resolveProfileLayer,
type PackageMetadata,
type Profile,
type ProfileManifest,
} from '@deepseek-ai/dsh-app-boot'
import { PluginOperationError } from './errors.ts'
import { bundlesOf, dependenciesOf, messageOf, NAME, optional, type PluginToolingConfig, type SpawnLike } from './helpers.ts'
import { classifyInstallFailure } from './install-failure.ts'
import { parseInstallSpec } from './install-spec.ts'
import type {
PluginInspectProblem, PluginInstallFailureKind, PluginInstallLogChunk, PluginInstallRejection, PluginInstallRequestId,
PluginInstallResult, PluginSpecInspection,
} from './types.ts'
/** The manager owns cancellation until prepared transfers control to runtime application. */
export interface PluginInstallControl {
readonly requestId: PluginInstallRequestId
readonly signal: AbortSignal
readonly prepared?: () => void
}
/** Check cancellation between subprocesses and before committing the installation. */
function checkCancelled(control?: PluginInstallControl): void {
if (control?.signal.aborted) {
throw new PluginOperationError('plugins/install-cancelled', `${NAME}: installation cancelled`, { requestId: control.requestId })
}
}
/** Read an optional pnpm lockfile without hiding unreadable-file failures. */
function readLockfile(path: string): Buffer | undefined {
try { return readFileSync(path) } catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
throw error
}
}
/** What one install run changed before any newly installed bundle was enabled. */
export type PluginInstallOutcome = Omit<PluginInstallResult, 'enabled'>
/** A terminal escape sequence (CSI): colours, cursor moves, and the rest of what a coloured pnpm prints. */
const ANSI_SEQUENCE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g
/** What {@link PluginInstaller} needs: the profile on disk, the tooling bounds, and where pnpm's output goes. */
export interface PluginInstallerOptions {
/** The profile directory pnpm runs in and whose manifest records installs. */
readonly profileDir: string
/** The profile name, for diagnostics. */
readonly profileName: string
/** Absolute path of the dsh app's package.json: the first resolution anchor for installed packages. */
readonly installAnchor: string
/** The profile's composed layers, read when a new bundle's row ids are checked against them. */
readonly loadProfile: () => Profile
readonly config: PluginToolingConfig
/** Receives every chunk of a pnpm run's output, in order; the last chunk carries the exit code. */
readonly installLog: (chunk: PluginInstallLogChunk) => void
/**
* Whether pnpm colours its output. On, the chunks carry SGR escapes for a
* consumer that draws them (the Web install dialog's terminal); off, they
* are plain text, with the escapes a pnpm told to colour anyway prints
* (a `color=always` config) dropped.
*/
readonly color: boolean
/** Test seam: the child spawner; defaults to `node:child_process`. */
readonly spawn?: SpawnLike
/** Test seam: the static metadata reader; defaults to app-boot’s. */
readonly metadata?: typeof readPackageMetadata
}
/** The installed package's manifest slice the view reads. */
export type InstalledManifest = ProfileManifest & { description?: string; dsh?: ProfileManifest['dsh'] & { title?: string } }
/** The fields an inspection reads off a manifest, on disk or as the registry reports it. */
interface InspectedManifest {
readonly name?: unknown
readonly version?: unknown
readonly description?: unknown
readonly dsh?: { readonly title?: unknown; readonly bundle?: unknown } | null
}
/** How one quiet pnpm run ended. */
interface QuietRun {
readonly exitCode: number | null
readonly stdout: string
readonly stderr: string
readonly kind: PluginInstallFailureKind | null
}
function stringField(value: unknown): string | undefined {
return typeof value === 'string' && value !== '' ? value : undefined
}
/** The manifest facts an inspection reports, with only the fields the manifest carries. */
function inspectionOf(kind: PluginSpecInspection['kind'], manifest: InspectedManifest): PluginSpecInspection {
const dsh = manifest.dsh ?? undefined
const bundle = dsh?.bundle
return {
kind,
...optional('name', stringField(manifest.name)),
...optional('version', stringField(manifest.version)),
...optional('description', stringField(manifest.description)),
...optional('title', stringField(dsh?.title)),
bundle: bundle !== undefined && bundle !== null,
}
}
/**
* Installs and removes packages in one profile with pnpm, and reads their declarations.
*
* Every run reads the profile manifest afresh and writes it through the
* app-boot helpers the `dsh plugin` command uses, so the CLI and the Web
* host never disagree on the file: `dependencies` records what is installed,
* `dsh.profile.bundles` what is enabled. No operation here touches a running
* tree, so the CLI can install before any plugin starts.
*/
export class PluginInstaller {
private readonly spawn: SpawnLike
private readonly metadataReader: typeof readPackageMetadata
/**
* @param options - the profile, the tooling bounds, and the output sink.
*/
constructor(private readonly options: PluginInstallerOptions) {
this.spawn = options.spawn ?? (spec => spawnSubprocess(spec, {
// Windows pnpm is normally a .cmd shim; retain the CLI's shell resolution.
spawn: (command, args, options) => spawnChild(command, [...args], { ...options, shell: process.platform === 'win32' }),
}))
this.metadataReader = options.metadata ?? readPackageMetadata
}
/**
* Whether the package is a profile dependency.
* @param packageName - the package.
* @returns true when the manifest lists it.
*/
isInstalled(packageName: string): boolean {
return packageName in dependenciesOf(readProfileManifest(NAME, this.options.profileDir))
}
/**
* Refuse a package the profile does not have.
* @param packageName - the package.
* @throws {PluginOperationError} `plugins/not-installed`.
*/
assertInstalled(packageName: string): void {
if (this.isInstalled(packageName)) return
throw new PluginOperationError(
'plugins/not-installed',
`${NAME}: ${packageName} is not installed in profile ${this.options.profileName}`,
{ packageName },
)
}
/**
* The installed package's manifest.
* @param packageName - the package.
* @returns the manifest, or undefined when the package cannot be resolved from the profile.
*/
readInstalledManifest(packageName: string): InstalledManifest | undefined {
let dir: string
try {
dir = resolveBundleDir(NAME, packageName, this.options.installAnchor, this.options.profileDir)
} catch {
// A dependency pnpm removed underneath the manifest, or one that never
// materialized; the caller reports what the manifest still says.
return undefined
}
// resolveBundleDir answers only a directory holding a package.json.
return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as InstalledManifest
}
/**
* Read the installed manifest and patch without executing modules or caching runtime verdicts.
* @param packageName - the installed package.
* @returns its current static declarations.
*/
metadata(packageName: string): PackageMetadata {
return this.metadataReader({
binName: NAME, profileDir: this.options.profileDir,
installAnchor: this.options.installAnchor, packageName,
})
}
/**
* Install with pnpm and reject bundles whose declarations conflict with the profile.
* Undeclared packages remain installed; new bundles are left disabled.
* @param spec - what to install, in pnpm's own vocabulary: a registry
* name, a `github:` or git URL, a tarball, or an absolute path.
* @param control - optional cancellation and the handoff to runtime application.
* @returns what the run installed and what it removed again.
* @throws {PluginOperationError} `plugins/bad-request` for an empty spec,
* `plugins/install-failed` when pnpm exits non-zero, cannot be spawned, or times out;
* `plugins/install-cancelled` after cancellation and manifest/lockfile restoration.
*/
async add(spec: string, control?: PluginInstallControl): Promise<PluginInstallOutcome> {
if (spec.trim().length === 0) {
throw new PluginOperationError('plugins/bad-request', `${NAME}: the package spec must not be empty`, {})
}
const { profileDir, installAnchor } = this.options
const manifestPath = join(profileDir, 'package.json')
const snapshot = readFileSync(manifestPath)
const lockPath = join(profileDir, 'pnpm-lock.yaml')
const lock = readLockfile(lockPath)
const before = readProfileManifest(NAME, profileDir)
try {
checkCancelled(control)
const jobId = await this.runPnpm(['add', spec], spec, control)
const outcome = reconcileInstalledBundles(NAME, profileDir, installAnchor, before, { autoEnable: false })
const after = readProfileManifest(NAME, profileDir)
const added = Object.keys(dependenciesOf(after)).filter(name => !(name in dependenciesOf(before)))
await healProfilesModuleFallback({ installAnchor, profile: this.options.loadProfile() })
checkCancelled(control)
const installed: string[] = []
const removed: PluginInstallRejection[] = []
for (const name of added) {
const reason = this.rejection(name)
if (reason === undefined) {
installed.push(name)
continue
}
await this.remove(name, control)
removed.push({ name, reason })
}
checkCancelled(control)
control?.prepared?.()
const kept = new Set(installed)
return {
installed,
removed,
installedOnly: outcome.installedOnly.filter(name => kept.has(name)),
plain: outcome.plain.filter(name => kept.has(name)),
jobId,
}
} catch (error) {
// The child and its process group have stopped before these files are restored.
// node_modules and the pnpm store are not a transactional snapshot.
writeFileSync(manifestPath, snapshot)
if (lock === undefined) rmSync(lockPath, { force: true })
else writeFileSync(lockPath, lock)
throw error
}
}
/**
* Read what a spec names before installing it: its form, and for a registry
* name or a directory the package's name, version, description, title, and
* whether it declares a bundle. A registry name is asked of the registry
* through `pnpm view`, run in the profile directory so the same registry,
* proxy, and auth settings apply as to the install itself; a git or tarball
* spec is only checked for form, and a tarball on disk for existence.
* @param spec - what would be installed, in pnpm's own vocabulary.
* @param signal - cancels the registry lookup.
* @returns the inspection.
* @throws {PluginOperationError} `plugins/inspect-rejected` with the problem: an
* `invalid-spec`, a package `already-installed` (a dependency or a template bundle),
* a registry name `not-found` (no such package, or no version in the range), a path that is
* `not-a-package`, a `network` failure reaching the registry, or an `unknown` lookup failure.
*/
async inspect(spec: string, signal?: AbortSignal): Promise<PluginSpecInspection> {
const parsed = parseInstallSpec(spec)
const manifest = readProfileManifest(NAME, this.options.profileDir)
const known = new Set([...bundlesOf(manifest), ...Object.keys(dependenciesOf(manifest))])
const rejected = (problem: PluginInspectProblem, reason: string): PluginOperationError<'plugins/inspect-rejected'> =>
new PluginOperationError('plugins/inspect-rejected', `${NAME}: ${reason}: ${parsed.spec}`, { spec: parsed.spec, problem, reason })
const assertNew = (name: string): void => {
if (known.has(name)) throw rejected('already-installed', `${name} is already installed`)
}
switch (parsed.kind) {
case 'path': {
if (!existsSync(parsed.path)) throw rejected('not-a-package', 'the path does not exist')
let read: InspectedManifest
try {
read = JSON.parse(readFileSync(join(parsed.path, 'package.json'), 'utf8')) as InspectedManifest
} catch (error) {
throw rejected('not-a-package', `no readable package.json at the path: ${messageOf(error)}`)
}
const inspection = inspectionOf('path', read)
if (inspection.name === undefined) throw rejected('not-a-package', 'the package.json names no package')
assertNew(inspection.name)
return inspection
}
case 'tarball': {
if (parsed.path !== undefined && !existsSync(parsed.path)) throw rejected('not-a-package', 'the tarball does not exist')
return { kind: 'tarball', bundle: null }
}
case 'git':
return { kind: 'git', bundle: null }
case 'registry': {
assertNew(parsed.name)
const run = await this.runQuietly(['view', parsed.spec, 'name', 'version', 'description', 'dsh', '--json'], signal)
if (run.kind !== null) {
const log = run.stderr.trim() || run.stdout.trim()
switch (run.kind) {
case 'not-found':
case 'no-matching-version':
throw rejected('not-found', log)
case 'network':
throw rejected('network', log)
default:
throw rejected('unknown', log || `pnpm view exited with ${String(run.exitCode)}`)
}
}
let answer: unknown
try {
answer = JSON.parse(run.stdout)
} catch (error) {
throw rejected('unknown', `unreadable pnpm view output: ${messageOf(error)}`)
}
// A range that several versions satisfy answers one object per version, newest last.
const latest: unknown = Array.isArray(answer) ? answer.at(-1) : answer
if (typeof latest !== 'object' || latest === null) throw rejected('unknown', 'pnpm view answered no package')
const inspection = inspectionOf('registry', latest)
return inspection.name === undefined ? { ...inspection, name: parsed.name } : inspection
}
/* v8 ignore next -- closed-union exhaustiveness guard */
default: return parsed satisfies never
}
}
/**
* Run one pnpm command whose output is answered, not streamed: a registry
* lookup, bounded by `inspectTimeoutMs` and the caller's signal.
*/
private async runQuietly(args: readonly string[], signal: AbortSignal | undefined): Promise<QuietRun> {
const { color, config, profileDir } = this.options
const deadline = new AbortController()
const timer = setTimeout(() => { deadline.abort() }, config.inspectTimeoutMs)
let stdout = ''
let stderr = ''
let exitCode: number | null = null
let cause: unknown
try {
const child = this.spawn({
argv: [config.pnpmCommand, ...args], cwd: profileDir, stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
graceMs: config.installKillGraceMs, signal: signal === undefined ? deadline.signal : AbortSignal.any([deadline.signal, signal]),
env: { ...process.env, FORCE_COLOR: color ? '1' : '0' },
})
const out = child.stdout as Readable
const err = child.stderr as Readable
out.setEncoding('utf8')
err.setEncoding('utf8')
out.on('data', (text: string) => { stdout += text })
err.on('data', (text: string) => { stderr += text })
try {
const [outcome] = await Promise.all([child.done, finished(out), finished(err)])
exitCode = outcome.exitCode
} finally {
await child.waitForExit()
}
if (deadline.signal.aborted) cause = new Error(`${NAME}: pnpm ${args.join(' ')} timed out after ${String(config.inspectTimeoutMs)}ms`)
} catch (error) {
cause = error
} finally {
clearTimeout(timer)
}
const plain = stderr.replace(ANSI_SEQUENCE, '')
const log = cause === undefined ? plain : `${plain}${messageOf(cause)}\n`
const failed = exitCode !== 0 || cause !== undefined
return {
exitCode,
stdout: stdout.replace(ANSI_SEQUENCE, ''),
stderr: log,
kind: failed ? classifyInstallFailure({ log, cause, timedOut: deadline.signal.aborted }) : null,
}
}
/**
* Run `pnpm remove` and reconcile the layer list.
* @param packageName - the dependency to remove.
* @param control - optional cancellation for this package operation.
* @throws {PluginOperationError} `plugins/install-failed` when pnpm fails.
*/
async remove(packageName: string, control?: PluginInstallControl): Promise<void> {
const { profileDir, installAnchor } = this.options
const before = readProfileManifest(NAME, profileDir)
await this.runPnpm(['remove', packageName], packageName, control)
reconcileInstalledBundles(NAME, profileDir, installAnchor, before, { autoEnable: false })
}
/**
* Check a new bundle against the profile’s row ownership rules.
* Undeclared or unreadable packages remain installed for repair or removal.
* @returns why the package is removed again, or undefined to keep it.
*/
private rejection(packageName: string): string | undefined {
let metadata: PackageMetadata
try {
metadata = this.metadata(packageName)
} catch {
return undefined // Keep unreadable declarations installed so the user can repair or remove the package.
}
if (metadata.kind !== 'bundle') return undefined
const { profileDir, installAnchor } = this.options
try {
const layer = resolveProfileLayer(NAME, packageName, installAnchor, profileDir)
const lost = claimLayerIds([...this.options.loadProfile().layers, layer]).skipped.get(packageName)
if (lost === undefined) return undefined
return lost.map(conflict => `row ${JSON.stringify(conflict.rowId)} is already declared by ${conflict.declaredBy}`).join('; ')
} catch (error) {
return messageOf(error)
}
}
/**
* Run one pnpm command in the profile directory, streaming its output as
* install-log chunks.
* @returns the run's job id.
* @throws {PluginOperationError} `plugins/install-failed` on a non-zero exit, a signal, or the timeout.
*/
private async runPnpm(args: readonly string[], spec: string, control?: PluginInstallControl): Promise<string> {
const { color, config, profileDir } = this.options
const jobId = randomUUID()
const argv = [config.pnpmCommand, ...args]
const request = control === undefined ? {} : { requestId: control.requestId }
const tail: string[] = []
let tailBytes = 0
const record = (stream: 'stdout' | 'stderr', chunk: string): void => {
const text = color ? chunk : chunk.replace(ANSI_SEQUENCE, '')
tail.push(text)
tailBytes += Buffer.byteLength(text)
while (tailBytes > config.installLogTailBytes && tail.length > 1) {
tailBytes -= Buffer.byteLength(tail.shift() as string)
}
this.options.installLog({ ...request, jobId, argv, cwd: profileDir, spec, stream, text })
}
const deadline = new AbortController()
const signal = control === undefined ? deadline.signal : AbortSignal.any([deadline.signal, control.signal])
const timer = setTimeout(() => { deadline.abort() }, config.installTimeoutMs)
let exitCode: number | null = null
try {
checkCancelled(control)
const child = this.spawn({
argv, cwd: profileDir, stdio: { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' },
graceMs: config.installKillGraceMs, signal,
// Preserve registry, proxy and authentication settings, including pnpm credentials.
env: { ...process.env, FORCE_COLOR: color ? '1' : '0' },
})
// Both outputs were requested as pipes; their presence follows the subprocess contract.
const stdout = child.stdout as Readable
const stderr = child.stderr as Readable
const drains = [finished(stdout), finished(stderr)]
stdout.setEncoding('utf8')
stderr.setEncoding('utf8')
stdout.on('data', (text: string) => { record('stdout', text) })
stderr.on('data', (text: string) => { record('stderr', text) })
try {
const [outcome] = await Promise.all([child.done, ...drains])
exitCode = outcome.exitCode
} finally {
// Cancellation starts termination; this separate wait confirms the owned range is empty.
await child.waitForExit()
}
checkCancelled(control)
if (deadline.signal.aborted) throw new Error(`${NAME}: pnpm ${args.join(' ')} timed out after ${String(config.installTimeoutMs)}ms`)
} catch (error) {
const message = messageOf(error)
record('stderr', `${message}\n`)
this.options.installLog({ ...request, jobId, argv, cwd: profileDir, spec, stream: 'stderr', text: '', exitCode })
if (error instanceof PluginOperationError && error.code === 'plugins/install-cancelled') throw error
const log = tail.join('')
const kind = classifyInstallFailure({ log, cause: error, timedOut: deadline.signal.aborted })
throw new PluginOperationError('plugins/install-failed', `${NAME}: ${message}`, { spec, exitCode, log, kind }, { cause: error })
} finally {
clearTimeout(timer)
}
this.options.installLog({ ...request, jobId, argv, cwd: profileDir, spec, stream: 'stdout', text: '', exitCode })
if (exitCode !== 0) {
const log = tail.join('')
throw new PluginOperationError(
'plugins/install-failed',
`${NAME}: pnpm ${args.join(' ')} exited with ${String(exitCode)} in ${profileDir}`,
{ spec, exitCode, log, kind: classifyInstallFailure({ log }) },
)
}
return jobId
}
}