Files
deepseek-harness/packages/boot/app-boot/src/plugin-compatibility.ts
T
turtle1999 51d70c5f5c feat(plugins): report incompatible versions as typed refusals
Compatibility checks now yield the refused packages as data instead of a
profile-specific sentence. runProfilePnpm returns them as
PackageResult.incompatible, and the plugin manager refuses with the
incompatible-version code carrying the same records. Each surface renders
them: the CLI prints the exact allow-version command for its profile, the
Web plugin manager words them through its locale dictionary, and app-boot
keeps one neutral English diagnostic for logs and startup stderr.
2026-09-23 19:51:29 +08:00

104 lines
5.0 KiB
TypeScript

/** Evaluate plugin dsh peer requirements without importing plugin code. */
import fs from 'node:fs'
import { fileURLToPath } from 'node:url'
import semver from 'semver'
/** Incompatible dsh peers and the exact plugin/runtime exemption decision. */
export interface PluginCompatibility {
name: string
version: string
runtimeVersion: string
/** Only peer requirements not satisfied by the running dsh version. */
peers: Record<string, string>
exempted: boolean
}
function objectOf(value: unknown, field: string): Record<string, unknown> {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
throw new Error(`${field} must be an object`)
}
return value as Record<string, unknown>
}
function runtimeVersionOf(value: unknown): string {
if (typeof value !== 'string' || semver.valid(value) === null) {
throw new Error(`Invalid dsh runtime version: ${JSON.stringify(value)}; expected a semantic version`)
}
return value
}
function identityField(manifest: Record<string, unknown>, field: 'name' | 'version'): string {
const value = Object.hasOwn(manifest, field) ? manifest[field] : undefined
if (typeof value !== 'string' || value.trim() === '') {
throw new Error(`Plugin manifest ${field} must be a non-empty string when dsh peers are incompatible`)
}
return value
}
/**
* Read this app-boot package's version in both source and bundled installations.
* @returns the validated runtime semantic version, preserving its exact spelling.
* @throws if package.json cannot be read or its version is missing or invalid.
*/
export function getDshRuntimeVersion(): string {
// The executable's virtual filesystem intercepts string paths, not URL arguments.
const filename = fileURLToPath(new URL('../package.json', import.meta.url))
const manifest = objectOf(JSON.parse(fs.readFileSync(filename, 'utf8')), 'app-boot package.json')
return runtimeVersionOf(Object.hasOwn(manifest, 'version') ? manifest.version : undefined)
}
/**
* Check every @deepseek-ai/dsh or @deepseek-ai/dsh-* peer against the runtime.
* Prereleases participate in ranges. workspace:^, workspace:~, and workspace:*
* refer to the current runtime; other invalid ranges are incompatible.
* @param manifest - parsed plugin package.json; inherited fields are ignored.
* @param exemptions - exact plugin name@version keys mapped to exact runtime versions.
* @param runtimeVersion - running dsh version, defaulting to this app-boot package.
* @returns incompatible peers and exemption status, or undefined when none are incompatible.
* @throws for malformed manifest peer fields, invalid runtime versions, or missing identity on a mismatch.
*/
export function evaluatePluginCompatibility(
manifest: object,
exemptions: Readonly<Record<string, readonly string[]>> = {},
runtimeVersion = getDshRuntimeVersion(),
): PluginCompatibility | undefined {
runtimeVersionOf(runtimeVersion)
const fields = objectOf(manifest, 'Plugin manifest')
if (!Object.hasOwn(fields, 'peerDependencies')) return undefined
const dependencies = objectOf(fields.peerDependencies, 'Plugin manifest peerDependencies')
const peers: Record<string, string> = {}
for (const [name, range] of Object.entries(dependencies)) {
if (typeof range !== 'string') {
throw new Error(`Plugin manifest peerDependencies[${JSON.stringify(name)}] must be a string`)
}
if (name !== '@deepseek-ai/dsh' && !name.startsWith('@deepseek-ai/dsh-')) continue
const requirement = ['workspace:^', 'workspace:~', 'workspace:*'].includes(range) ? runtimeVersion : range
if (requirement.trim() === '' || !semver.satisfies(runtimeVersion, requirement, { includePrerelease: true })) {
peers[name] = range
}
}
if (Object.keys(peers).length === 0) return undefined
const name = identityField(fields, 'name')
const version = identityField(fields, 'version')
const key = `${name}@${version}`
const exemptedVersions = Object.hasOwn(exemptions, key) ? exemptions[key] : undefined
const exempted = exemptedVersions?.includes(runtimeVersion) === true
return { name, version, runtimeVersion, peers, exempted }
}
/**
* Describe incompatible peers, their risk, and the exact-version remedy.
* Surfaces with their own grant mechanism or locale render the structured result themselves.
* @param issue - incompatible plugin/runtime result, including exempted mismatches.
* @returns an English diagnostic for logs and stderr.
*/
export function pluginCompatibilityWarning(issue: PluginCompatibility): string {
const key = `${issue.name}@${issue.version}`
return `Plugin ${key} is incompatible with dsh ${issue.runtimeVersion}: peerDependencies ${JSON.stringify(issue.peers)}. `
+ 'Running it may cause crashes or data loss. '
+ 'Update the plugin or install a plugin version compatible with this dsh runtime. '
+ `To accept this risk explicitly, grant the exact-version exemption for ${key} on dsh ${issue.runtimeVersion} with \`dsh plugin allow-version\` or the plugin manager, then retry the installation or restart dsh. `
+ `Exact-version exemption: ${issue.exempted ? 'active' : 'not active'}.`
}