dsh-plugin-upgrader 1.0.0 → 1.0.1

package/lib/host/bundle.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bundle metadata helpers.
+ *
+ * These translate what the profile manager reports into the fields the tab
+ * renders. Pure functions again: given the same bundle they answer the same
+ * thing, which is what makes them testable.
+ *
+ * @module dsh-plugin-upgrader/lib/bundle
+ */
+/** How a profile dependency was declared. */
+export type SourceKind = 'registry' | 'path' | 'git' | 'tarball' | 'unknown';
+/** The display languages this bundle ships. */
+export type Locale = 'zh' | 'en';
+/**
+ * Classify how a profile dependency was declared.
+ *
+ * @param source - `BundleInfo.source`.
+ * @returns the source family.
+ */
+export declare function sourceKind(source: unknown): SourceKind;
+/**
+ * Localized metadata value for the active display language.
+ *
+ * @param text - a string or `{ en, zh, … }`.
+ * @param locale - the requested language.
+ * @returns the best available text.
+ */
+export declare function pickText(text: unknown, locale: Locale): string | undefined;
+/**
+ * Keep an icon only when it is cheap to send.
+ *
+ * Bundle metadata often embeds a base64 data URL, which would bloat every
+ * overview response by ~150 KB.
+ *
+ * @param icon - the manifest icon.
+ * @param limit - the largest inline data URL worth sending.
+ * @returns a usable reference.
+ */
+export declare function inlineIcon(icon: unknown, limit: number): string | undefined;
+/** What `pluginManager.registries()` reports. */
+export interface RegistryReport {
+    registry?: string | null;
+    resolved?: string | null;
+}
+/**
+ * Registry base URL: `null` is pnpm's own configured registry.
+ *
+ * @param registries - manager answer.
+ * @returns a URL without a trailing slash.
+ */
+export declare function registryBase(registries: RegistryReport | undefined | null): string;
+//# sourceMappingURL=bundle.d.ts.map

package/lib/host/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/host/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAA;AAE5E,+CAA+C;AAC/C,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;AAEhC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAUtD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3E;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAIlF"}

package/lib/host/bundle.js

@@ -0,0 +1,73 @@
+/**
+ * Bundle metadata helpers.
+ *
+ * These translate what the profile manager reports into the fields the tab
+ * renders. Pure functions again: given the same bundle they answer the same
+ * thing, which is what makes them testable.
+ *
+ * @module dsh-plugin-upgrader/lib/bundle
+ */
+/**
+ * Classify how a profile dependency was declared.
+ *
+ * @param source - `BundleInfo.source`.
+ * @returns the source family.
+ */
+export function sourceKind(source) {
+    if (typeof source !== 'string' || source.trim() === '')
+        return 'unknown';
+    const value = source.trim();
+    if (value.startsWith('file:') || value.startsWith('link:') || value.startsWith('.') || value.startsWith('/')) {
+        return 'path';
+    }
+    if (/^(git|git\+|github:|https?:\/\/[^/]*\.git)/.test(value))
+        return 'git';
+    if (/\.(tgz|tar\.gz)$/.test(value))
+        return 'tarball';
+    if (/^(npm:|[\^~]?\d|[\^~]?(latest|next|beta|canary|rc)\b)/.test(value))
+        return 'registry';
+    return 'unknown';
+}
+/**
+ * Localized metadata value for the active display language.
+ *
+ * @param text - a string or `{ en, zh, … }`.
+ * @param locale - the requested language.
+ * @returns the best available text.
+ */
+export function pickText(text, locale) {
+    if (typeof text === 'string')
+        return text;
+    if (text !== null && typeof text === 'object') {
+        const record = text;
+        return record[locale] ?? record.en ?? record.zh ?? Object.values(record)[0];
+    }
+    return undefined;
+}
+/**
+ * Keep an icon only when it is cheap to send.
+ *
+ * Bundle metadata often embeds a base64 data URL, which would bloat every
+ * overview response by ~150 KB.
+ *
+ * @param icon - the manifest icon.
+ * @param limit - the largest inline data URL worth sending.
+ * @returns a usable reference.
+ */
+export function inlineIcon(icon, limit) {
+    if (typeof icon !== 'string' || icon === '')
+        return undefined;
+    return icon.startsWith('data:') && icon.length > limit ? undefined : icon;
+}
+/**
+ * Registry base URL: `null` is pnpm's own configured registry.
+ *
+ * @param registries - manager answer.
+ * @returns a URL without a trailing slash.
+ */
+export function registryBase(registries) {
+    const candidate = registries?.registry ?? registries?.resolved ?? null;
+    const value = typeof candidate === 'string' && candidate !== '' ? candidate : 'https://registry.npmjs.org/';
+    return value.replace(/\/+$/, '');
+}
+//# sourceMappingURL=bundle.js.map

package/lib/host/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../../src/host/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe;IACxC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7G,OAAO,MAAM,CAAA;IACf,CAAC;IACD,IAAI,4CAA4C,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC1E,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACpD,IAAI,uDAAuD,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAA;IAC1F,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,MAAc;IACpD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACzC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,IAA0C,CAAA;QACzD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7E,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,KAAa;IACrD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IAC7D,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;AAC3E,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,UAA6C;IACxE,MAAM,SAAS,GAAG,UAAU,EAAE,QAAQ,IAAI,UAAU,EAAE,QAAQ,IAAI,IAAI,CAAA;IACtE,MAAM,KAAK,GAAG,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,6BAA6B,CAAA;IAC3G,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AAClC,CAAC"}

package/lib/host/http.d.ts

@@ -0,0 +1,46 @@
+/**
+ * HTTP helpers shared by every route.
+ *
+ * The host half answers a small, fixed set of JSON endpoints, so these helpers
+ * stay deliberately narrow: one trust fence, one bounded body reader, one
+ * response writer.
+ *
+ * @module dsh-plugin-upgrader/lib/http
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Whether a socket address names the loopback range.
+ *
+ * @param address - `req.socket.remoteAddress`.
+ * @returns true for 127/8 and ::1.
+ */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Request-level trust fence for a route that can install packages.
+ *
+ * This endpoint can add and remove packages, so it must not be reachable from a
+ * page on another origin: a remote address outside loopback is refused, a
+ * cross-site fetch is refused, and a stated `Origin` must match the served host.
+ *
+ * @param req - the incoming request.
+ * @returns true when the request comes from this machine and origin.
+ */
+export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+/**
+ * Read a bounded JSON object body.
+ *
+ * @param req - the request.
+ * @param maxBytes - cap before the body is dropped.
+ * @returns the parsed object, or `null` when the body is absent, oversized, or
+ * not a JSON object.
+ */
+export declare function readJsonBody(req: IncomingMessage, maxBytes?: number): Promise<Record<string, unknown> | null>;
+/**
+ * Write one JSON response.
+ *
+ * @param res - the response.
+ * @param status - HTTP status.
+ * @param body - JSON payload.
+ */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
+//# sourceMappingURL=http.d.ts.map

package/lib/host/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/host/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAY/D;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,QAAQ,SAAa,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CA6BzC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CASlF"}

package/lib/host/http.js

@@ -0,0 +1,104 @@
+/**
+ * Whether a socket address names the loopback range.
+ *
+ * @param address - `req.socket.remoteAddress`.
+ * @returns true for 127/8 and ::1.
+ */
+export function isLoopbackAddress(address) {
+    if (address === undefined)
+        return false;
+    const normalized = address.toLowerCase();
+    if (normalized === '::1')
+        return true;
+    const v4 = normalized.startsWith('::ffff:') ? normalized.slice(7) : normalized;
+    const parts = v4.split('.');
+    return parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part));
+}
+/**
+ * Request-level trust fence for a route that can install packages.
+ *
+ * This endpoint can add and remove packages, so it must not be reachable from a
+ * page on another origin: a remote address outside loopback is refused, a
+ * cross-site fetch is refused, and a stated `Origin` must match the served host.
+ *
+ * @param req - the incoming request.
+ * @returns true when the request comes from this machine and origin.
+ */
+export function isLoopbackRequest(req) {
+    if (!isLoopbackAddress(req.socket?.remoteAddress))
+        return false;
+    const host = req.headers.host;
+    if (typeof host !== 'string')
+        return false;
+    if (req.headers['sec-fetch-site'] === 'cross-site')
+        return false;
+    const origin = req.headers.origin;
+    if (origin === undefined)
+        return true;
+    try {
+        return new URL(origin).host === new URL(`http://${host}`).host;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a bounded JSON object body.
+ *
+ * @param req - the request.
+ * @param maxBytes - cap before the body is dropped.
+ * @returns the parsed object, or `null` when the body is absent, oversized, or
+ * not a JSON object.
+ */
+export async function readJsonBody(req, maxBytes = 256 * 1024) {
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of req) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += buffer.length;
+            if (size > maxBytes) {
+                req.destroy();
+                return null;
+            }
+            chunks.push(buffer);
+        }
+    }
+    catch {
+        return null;
+    }
+    let text = Buffer.concat(chunks).toString('utf8');
+    // A UTF-8 BOM survives `JSON.parse` on some clients and fails the parse.
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    if (text === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : null;
+}
+/**
+ * Write one JSON response.
+ *
+ * @param res - the response.
+ * @param status - HTTP status.
+ * @param body - JSON payload.
+ */
+export function writeJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'referrer-policy': 'no-referrer',
+        'content-length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+//# sourceMappingURL=http.js.map

package/lib/host/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/host/http.ts"],"names":[],"mappings":"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"}

package/lib/host/install.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Installing one version, and putting the plugin's state back afterwards.
+ *
+ * `installBundle` refuses a spec that names an already-installed dependency, so
+ * replacing a version means removing first. These helpers wrap that two-step in
+ * one call and undo the side effects a reinstall has on the enabled flag.
+ *
+ * @module dsh-plugin-upgrader/lib/install
+ */
+import type { ChangeResult, PluginManager, StepRecord } from './manager.ts';
+/** Progress sink for one job. */
+export type LogSink = (message: string) => void;
+/** One step's outcome, including every failure stage. */
+export interface StepOutcome {
+    name: string;
+    version: string;
+    spec: string;
+    requestId: string;
+    ok: boolean;
+    enabled?: boolean;
+    application?: ChangeResult['application'];
+    changed?: boolean;
+    stage?: 'install' | 'remove' | 'enable';
+    restartReason?: string;
+    message?: string;
+    detail?: string;
+    pendingBuilds?: string[];
+    warnings?: string[];
+    packageResult?: {
+        exitCode: number;
+        kind?: string;
+        timedOut?: boolean;
+        tail?: string;
+    };
+}
+/** Allowed per-step actions. */
+export declare const ACTIONS: Set<string>;
+/**
+ * Re-apply the enabled state a step asked for after the package was replaced.
+ *
+ * `installBundle` activates what it installs, so a disabled plugin would
+ * otherwise come back enabled; the bundle switch is the persistent lever.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the step that just ran.
+ * @param wanted - the state to restore, if any.
+ * @param log - progress sink.
+ * @returns the state now in effect, if known.
+ */
+export declare function restoreEnabledState(manager: PluginManager, step: Pick<StepRecord, 'name'>, wanted: boolean | undefined, log: LogSink): Promise<boolean | undefined>;
+/**
+ * Run one step: install the exact version, falling back to remove + install,
+ * then restore the plugin's previous enabled state.
+ *
+ * Every outcome — including a thrown manager call — comes back as one record so
+ * the job log can report per-plugin success without a second error channel.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the requested change.
+ * @param log - progress sink.
+ * @returns the outcome record.
+ */
+export declare function runStep(manager: PluginManager, step: StepRecord, log: LogSink): Promise<StepOutcome>;
+/**
+ * Whether a step names something this plugin is willing to install.
+ *
+ * @param step - one element of the request body.
+ * @returns an error code, or undefined when valid.
+ */
+export declare function validateStep(step: unknown): string | undefined;
+//# sourceMappingURL=install.d.ts.map

package/lib/host/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/host/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE3E,iCAAiC;AACjC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;AAE/C,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,aAAa,CAAC,EAAE;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,gCAAgC;AAChC,eAAO,MAAM,OAAO,aAAyC,CAAA;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAuB9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,WAAW,CAAC,CA4FtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM9D"}

package/lib/host/install.js

@@ -0,0 +1,161 @@
+/** Allowed per-step actions. */
+export const ACTIONS = new Set(['upgrade', 'switch']);
+/**
+ * Re-apply the enabled state a step asked for after the package was replaced.
+ *
+ * `installBundle` activates what it installs, so a disabled plugin would
+ * otherwise come back enabled; the bundle switch is the persistent lever.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the step that just ran.
+ * @param wanted - the state to restore, if any.
+ * @param log - progress sink.
+ * @returns the state now in effect, if known.
+ */
+export async function restoreEnabledState(manager, step, wanted, log) {
+    if (wanted === undefined)
+        return undefined;
+    let current;
+    try {
+        const bundles = await manager.listBundles();
+        const entry = Array.isArray(bundles) ? bundles.find((item) => item?.name === step.name) : undefined;
+        current = entry?.enabled;
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === wanted)
+        return current;
+    log(`${wanted ? 'enable' : 'disable'} ${step.name} (restoring the previous state)`);
+    try {
+        const outcome = await manager.setBundleEnabled(step.name, wanted);
+        if (outcome?.error !== undefined) {
+            log(`  ! could not restore the enabled state: ${outcome.error.code}`);
+            return current;
+        }
+        return wanted;
+    }
+    catch (error) {
+        log(`  ! could not restore the enabled state: ${error instanceof Error ? error.message : String(error)}`);
+        return current;
+    }
+}
+/**
+ * Run one step: install the exact version, falling back to remove + install,
+ * then restore the plugin's previous enabled state.
+ *
+ * Every outcome — including a thrown manager call — comes back as one record so
+ * the job log can report per-plugin success without a second error channel.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the requested change.
+ * @param log - progress sink.
+ * @returns the outcome record.
+ */
+export async function runStep(manager, step, log) {
+    const spec = `${step.name}@${step.version}`;
+    const requestId = globalThis.crypto?.randomUUID?.() ?? `pu-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const buildApproval = Array.isArray(step.approveBuilds) && step.approveBuilds.length > 0
+        ? { approvedBuilds: step.approveBuilds }
+        : {};
+    const base = { name: step.name, version: step.version, spec, requestId };
+    const restoreEnabled = typeof step.enabled === 'boolean' ? step.enabled : undefined;
+    log(`install ${spec}`);
+    const options = {
+        saveExact: true,
+        ...(restoreEnabled === undefined ? {} : { enabled: restoreEnabled }),
+        ...buildApproval,
+    };
+    let result;
+    try {
+        result = await manager.installBundle(spec, { ...options, requestId });
+    }
+    catch (error) {
+        return {
+            ...base,
+            ok: false,
+            stage: 'install',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (result?.error?.code === 'already-installed') {
+        log(`remove ${step.name} (replacing an installed dependency)`);
+        let removed;
+        try {
+            removed = await manager.removeBundle(step.name);
+        }
+        catch (error) {
+            return {
+                ...base,
+                ok: false,
+                stage: 'remove',
+                application: 'failed',
+                message: `removal failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        if (removed?.application === 'failed' || removed?.error !== undefined) {
+            return {
+                ...base,
+                ok: false,
+                stage: 'remove',
+                application: removed?.application,
+                message: removed?.error?.code ?? 'removal refused',
+                detail: removed?.error?.diagnostic,
+            };
+        }
+        try {
+            result = await manager.installBundle(spec, { ...options, requestId: undefined });
+        }
+        catch (error) {
+            return {
+                ...base,
+                ok: false,
+                stage: 'install',
+                application: 'failed',
+                message: `install after removal failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    const enabled = await restoreEnabledState(manager, step, restoreEnabled, log);
+    return {
+        ...base,
+        ...(enabled === undefined ? {} : { enabled }),
+        ok: result?.application === 'applied' || result?.application === 'restart-required',
+        application: result?.application,
+        changed: result?.changed === true,
+        stage: result?.stage,
+        restartReason: result?.restartReason,
+        version: result?.version ?? step.version,
+        message: result?.error === undefined ? undefined : result.error.code,
+        detail: result?.error?.diagnostic,
+        pendingBuilds: result?.pendingBuilds,
+        warnings: result?.warnings,
+        packageResult: result?.packageResult === undefined
+            ? undefined
+            : {
+                exitCode: result.packageResult.exitCode,
+                kind: result.packageResult.kind,
+                timedOut: result.packageResult.timedOut,
+                tail: typeof result.packageResult.output === 'string'
+                    ? result.packageResult.output.slice(-1600)
+                    : undefined,
+            },
+    };
+}
+/**
+ * Whether a step names something this plugin is willing to install.
+ *
+ * @param step - one element of the request body.
+ * @returns an error code, or undefined when valid.
+ */
+export function validateStep(step) {
+    if (step === null || typeof step !== 'object')
+        return 'invalid-step';
+    const record = step;
+    if (typeof record.name !== 'string' || typeof record.version !== 'string')
+        return 'invalid-step';
+    if (record.action !== undefined && !ACTIONS.has(String(record.action)))
+        return 'invalid-action';
+    return undefined;
+}
+//# sourceMappingURL=install.js.map

package/lib/host/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/host/install.ts"],"names":[],"mappings":"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"}