Files
deepseek-harness/packages/boot/plugin-manager/src/installer.ts
T
Yichen Jiang 2b40a9d819 merge: restore startup requirements from plugin stack base
# Conflicts:
#	.agents/notes/implemented/architecture/2026-09-11-native-entry-diagnostics-and-static-plugin-declarations.i18n.yaml
#	.agents/notes/implemented/architecture/2026-09-11-native-entry-diagnostics-and-static-plugin-declarations.md
#	.agents/notes/implemented/architecture/2026-09-11-native-entry-diagnostics-and-static-plugin-declarations.zh.md
#	docs/capability-seams.i18n.yaml
#	docs/capability-seams.md
#	docs/capability-seams.zh.md
#	packages/boot/app-boot/src/profile.ts
#	scripts/gen-doc-graphs.ts
2026-09-11 18:21:48 +08:00

285 lines
12 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 { readFileSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import {
awaitChildClose,
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 { dependenciesOf, messageOf, NAME, type PluginToolingConfig, type SpawnLike } from './helpers.ts'
import type { PluginInstallLogChunk, PluginInstallRejection, PluginInstallResult } from './types.ts'
/** 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 } }
/**
* 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, and `dsh.profile.disabledBundles`
* what the user turned off. Nothing here touches a running tree, which is
* what lets the CLI 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 ?? spawnChild
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.
* @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.
*/
async add(spec: string): 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, 'utf8')
const before = readProfileManifest(NAME, profileDir)
let jobId: string
try {
jobId = await this.runPnpm(['add', spec], spec)
} catch (error) {
// pnpm may have written the manifest before failing; the profile keeps
// the manifest it had, and what pnpm left under node_modules is not a
// dependency until a manifest names it.
if (readFileSync(manifestPath, 'utf8') !== snapshot) writeFileSync(manifestPath, snapshot)
throw error
}
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() })
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)
removed.push({ name, reason })
}
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,
}
}
/**
* Run `pnpm remove` and reconcile the layer list.
* @param packageName - the dependency to remove.
* @throws {PluginOperationError} `plugins/install-failed` when pnpm fails.
*/
async remove(packageName: string): Promise<void> {
const { profileDir, installAnchor } = this.options
const before = readProfileManifest(NAME, profileDir)
await this.runPnpm(['remove', packageName], packageName)
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): Promise<string> {
const { color, config, profileDir } = this.options
const jobId = randomUUID()
const argv = [config.pnpmCommand, ...args]
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({ jobId, argv, cwd: profileDir, spec, stream, text })
}
// Windows resolves pnpm through its .cmd shim, which spawn() refuses
// without a shell since the CVE-2024-27980 hardening. The parent
// environment is passed whole, as the `dsh plugin` command does: pnpm
// needs the user's registry, proxy, and auth settings. pnpm writes to a
// pipe and would decide against colour on its own, so `FORCE_COLOR`
// decides for it either way: a parent forcing colours for its own
// terminal cannot leak escapes into a plain log.
const child = this.spawn(config.pnpmCommand, args, {
cwd: profileDir,
stdio: ['ignore', 'pipe', 'pipe'],
shell: process.platform === 'win32',
env: { ...process.env, FORCE_COLOR: color ? '1' : '0' },
})
child.stdout?.setEncoding('utf8')
child.stderr?.setEncoding('utf8')
child.stdout?.on('data', (text: string) => { record('stdout', text) })
child.stderr?.on('data', (text: string) => { record('stderr', text) })
const exitCode = await awaitChildClose(
child, config.installTimeoutMs,
() => new Error(`${NAME}: pnpm ${args.join(' ')} timed out after ${String(config.installTimeoutMs)}ms`),
).catch((error: unknown) => {
const message = messageOf(error)
record('stderr', `${message}\n`)
this.options.installLog({ jobId, argv, cwd: profileDir, spec, stream: 'stderr', text: '', exitCode: null })
throw new PluginOperationError('plugins/install-failed', `${NAME}: ${message}`, { spec, exitCode: null, log: tail.join('') }, { cause: error })
})
this.options.installLog({ jobId, argv, cwd: profileDir, spec, stream: 'stdout', text: '', exitCode })
if (exitCode !== 0) {
throw new PluginOperationError(
'plugins/install-failed',
`${NAME}: pnpm ${args.join(' ')} exited with ${String(exitCode)} in ${profileDir}`,
{ spec, exitCode, log: tail.join('') },
)
}
return jobId
}
}