@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/plugin-installer.js

@@ -1,186 +1,451 @@
 /**
- * Plugin installation — from npm or a local directory.
+ * Transactional plugin installation.
  *
- * No trust mechanism: installing runs the plugin's code in the daemon process.
- * The user owns that risk.
- *
- *  - **npm**:   `npm install <spec>` into `~/.rynx/plugins`, then record it.
- *  - **local**: register an absolute directory and load it in place (no copy;
- *               supports local development / offline). The directory must be a
- *               ready package (built, deps installed, exporting `plugin`).
+ * Packages are first materialized in a host-owned staging directory. The
+ * installer reads only static JSON metadata, validates every declared entry,
+ * hashes the package, and atomically renames the validated tree into an
+ * immutable installation path. Plugin code is never imported here.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { PLUGIN_ID_PATTERN, pluginCliInvocationLeasePid, readPluginRuntimeLeases, removePluginRuntimeLease, } from "@rynx-ai/plugin-sdk";
+import { rynxHome } from "@rynx-ai/core";
+import { getPlugin, isRunnablePluginRecord, removePlugin, upsertPlugin, } from "./plugin-store.js";
+import { detectPluginSource, inspectPluginPackage, materializePluginPackage, normalizePluginSpec, rebuildPluginPackage, } from "./plugin-package.js";
+import { pluginsDir } from "./registry.js";
+import { db } from "./db.js";
+const INSTALLATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STAGING_TRANSACTION_PATTERN = /^install-[A-Za-z0-9]{6}$/;
+const STAGING_OWNER_FILE = ".rynx-staging-owner.json";
+const PROMOTION_MARKER_SUFFIX = ".rynx-promoted";
+const MAX_HOST_MARKER_BYTES = 4 * 1024;
+const DEFAULT_STAGING_GC_AGE_MS = 24 * 60 * 60 * 1_000;
+/**
+ * Install or replace one arbitrary npm/local/git/URL plugin package.
  *
- * After recording, the channel-type catalog is rebuilt so a freshly-installed
- * plugin's types are usable without a daemon restart.
+ * A failed validation, materialization, atomic move, or registry update leaves
+ * the previously registered installation untouched.
  */
-import { spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { getPlugin, removePlugin, upsertPlugin, } from "./plugin-store.js";
-import { importPluginManifest, pluginPkgDir, pluginsDir } from "./registry.js";
-/** A spec is "local" if it's a path/file: URL or an existing directory. */
-function detectSource(spec) {
-    if (spec.startsWith("file:"))
-        return "local";
-    if (spec.startsWith("~") || spec.startsWith("./") || spec.startsWith("../") || isAbsolute(spec)) {
-        return "local";
+export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
+    if (!spec.trim())
+        throw new Error("plugin spec must not be empty");
+    const progress = safeProgress(onProgress);
+    const source = detectPluginSource(spec);
+    const storedSpec = normalizePluginSpec(spec, source);
+    const storage = ensureStorageRoots();
+    const transactionDir = mkdtempSync(join(storage.stagingRoot, "install-"));
+    try {
+        writeStagingOwner(transactionDir);
+    }
+    catch (error) {
+        rmSync(transactionDir, { recursive: true, force: true });
+        throw error;
     }
+    const stagedPackage = join(transactionDir, "package");
+    let finalPath;
+    let registryUpdated = false;
     try {
-        if (existsSync(spec) && statSync(spec).isDirectory())
-            return "local";
+        await (opts.materializer ?? materializePluginPackage)({
+            spec: storedSpec,
+            source,
+            destination: stagedPackage,
+            onProgress: progress,
+            signal: opts.signal,
+        });
+        let inspected = inspectPluginPackage(stagedPackage, { requireEntries: false });
+        if (inspected.manifest.requiresBuildScripts && !opts.allowScripts) {
+            throw new Error(`plugin "${inspected.manifest.id}" requires package build scripts; ` +
+                "review the package and re-run with --allow-scripts");
+        }
+        if (opts.allowScripts && !inspected.manifest.requiresBuildScripts) {
+            throw new Error(`plugin "${inspected.manifest.id}" does not declare requiresBuildScripts; ` +
+                "refusing unnecessary --allow-scripts approval");
+        }
+        if (inspected.manifest.requiresBuildScripts) {
+            const manifestBeforeBuild = JSON.stringify(inspected.manifest);
+            const versionBeforeBuild = inspected.version;
+            progress(`running explicitly approved build scripts for plugin "${inspected.manifest.id}"`);
+            await rebuildPluginPackage(stagedPackage, progress, opts.signal);
+            const built = inspectPluginPackage(stagedPackage);
+            if (JSON.stringify(built.manifest) !== manifestBeforeBuild ||
+                built.version !== versionBeforeBuild) {
+                throw new Error("plugin build scripts changed static package identity or manifest metadata");
+            }
+            inspected = built;
+        }
+        else {
+            inspected = inspectPluginPackage(stagedPackage);
+        }
+        const name = inspected.manifest.id;
+        if (opts.expectedId && name !== opts.expectedId) {
+            throw new Error(`plugin update id mismatch: expected "${opts.expectedId}", received "${name}"`);
+        }
+        const existing = getPlugin(name);
+        if (existing && opts.onConflict && !(await opts.onConflict(existing))) {
+            return {
+                name,
+                source,
+                ...(inspected.version ? { version: inspected.version } : {}),
+                skipped: true,
+            };
+        }
+        if (opts.signal?.aborted)
+            throw new Error("plugin installation aborted");
+        const requested = new Set(inspected.manifest.requestedCapabilities);
+        if (!opts.approveCapabilities &&
+            opts.grants === undefined &&
+            !existing &&
+            requested.size > 0) {
+            throw new Error(`plugin "${name}" requests host capabilities; explicit grants or approval are required`);
+        }
+        const grants = opts.approveCapabilities
+            ? await opts.approveCapabilities(inspected.manifest, existing)
+            : opts.grants ??
+                (existing
+                    ? existing.grants.filter((capability) => requested.has(capability))
+                    : []);
+        for (const grant of grants) {
+            if (!requested.has(grant)) {
+                throw new Error(`plugin capability was not requested: ${grant}`);
+            }
+        }
+        db().transaction(() => {
+            const current = getPlugin(name);
+            if (!samePluginGeneration(existing, current)) {
+                throw new Error(`plugin "${name}" changed concurrently; retry the installation`);
+            }
+            const leases = activeRuntimeLeases(name, storage.installationsRoot);
+            if (leases.length > 0) {
+                throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
+                    .map((lease) => lease.leaseId)
+                    .join(", ")}; stop its managed services or CLI commands before updating`);
+            }
+            const idRoot = ensureDirectDirectory(storage.installationsRoot, name, "plugin id directory");
+            const installationId = randomUUID();
+            finalPath = join(idRoot, installationId);
+            const marker = promotionMarkerPath(idRoot, installationId);
+            writePromotionMarker(marker);
+            try {
+                renameSync(stagedPackage, finalPath);
+            }
+            catch (error) {
+                rmSync(marker, { force: true });
+                finalPath = undefined;
+                throw error;
+            }
+            progress(`staged validated plugin "${name}" → ${finalPath}`);
+            upsertPlugin({
+                name,
+                spec: storedSpec,
+                source,
+                version: inspected.version,
+                installPath: finalPath,
+                manifest: inspected.manifest,
+                integrity: inspected.integrity,
+                grants,
+                enabled: current?.enabled,
+            });
+        }).immediate();
+        registryUpdated = true;
+        if (existing?.installPath && existing.installPath !== finalPath) {
+            progress(`retained superseded installation until the daemon switches versions`);
+        }
+        progress(`installed plugin "${name}"${inspected.version ? `@${inspected.version}` : ""}`);
+        return {
+            name,
+            source,
+            ...(inspected.version ? { version: inspected.version } : {}),
+        };
     }
-    catch {
-        /* not a path */
+    finally {
+        // Once registered, finalPath is the active immutable installation and must
+        // outlive this transaction. Everything else under staging is disposable.
+        if (!registryUpdated && finalPath) {
+            removeOwnedInstallation(storage.installationsRoot, basename(dirname(finalPath)), finalPath);
+        }
+        try {
+            rmSync(transactionDir, { recursive: true, force: true });
+        }
+        catch {
+            /* orphaned staging is inactive and can be collected later */
+        }
     }
-    return "npm";
 }
-function toLocalDir(spec) {
-    let p = spec.startsWith("file:") ? fileURLToPath(spec) : spec;
-    if (p === "~" || p.startsWith("~/"))
-        p = join(homedir(), p.slice(1));
-    return resolve(p);
-}
-/** Package name from an npm spec, dropping any version range (`x@^1` → `x`). */
-function npmPackageName(spec) {
-    const at = spec.lastIndexOf("@");
-    return at > 0 ? spec.slice(0, at) : spec;
+/**
+ * Remove the registry row but retain the immutable package until the next
+ * daemon boot. A currently running supervisor may still be executing it.
+ */
+export async function uninstallPlugin(name, onProgress = () => { }) {
+    const progress = safeProgress(onProgress);
+    let record;
+    const removed = db().transaction(() => {
+        record = getPlugin(name);
+        if (!record)
+            return false;
+        const leases = activeRuntimeLeases(name, ensureStorageRoots().installationsRoot);
+        if (leases.length > 0) {
+            throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
+                .map((lease) => lease.leaseId)
+                .join(", ")}; stop its managed services or CLI commands before uninstalling`);
+        }
+        return removePlugin(name);
+    }).immediate();
+    if (!removed || !record)
+        return false;
+    if (record.installPath)
+        progress(`retained active package until the daemon stops using it`);
+    progress(`uninstalled plugin "${name}"`);
+    return true;
 }
 /**
- * Install (or re-install) a plugin from an npm spec or a local directory.
- *  - **local**: copy the package (minus `node_modules`) into `~/.rynx/plugins/<name>`
- *    and load it there. The plugin must be self-contained — it bundles its deps at
- *    build time (incl. the unpublished workspace `@rynx-ai/core`) and declares a
- *    `rynx.plugin` entry; the daemon installs nothing.
- *  - **npm**: `npm install` into `~/.rynx/plugins` (deps resolved by npm).
+ * Delete inactive immutable versions at a daemon-start safe point.
  *
- * `onConflict` is consulted when a plugin of the same `name` already exists; if it
- * returns false the install is aborted with `{ skipped: true }` (nothing changes).
- * `onProgress` streams human-readable lines.
+ * A short grace window prevents a concurrently materializing install (renamed
+ * just before its registry transaction) from being mistaken for an orphan.
  */
-export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
-    const source = detectSource(spec);
-    let pkgDir;
-    let storedSpec;
-    if (source === "local") {
-        const srcDir = toLocalDir(spec);
-        if (!existsSync(join(srcDir, "package.json")))
-            throw new Error(`no package.json at ${srcDir}`);
-        const name = (await importPluginManifest(srcDir))?.name;
-        if (!name)
-            throw new Error(`package at ${srcDir} has no valid \`plugin\` export`);
-        if (await declined(name, opts.onConflict))
-            return { name, source, skipped: true };
-        const dest = join(pluginsDir(), name);
-        ensurePluginsRoot(pluginsDir());
-        rmSync(dest, { recursive: true, force: true });
-        // A self-contained plugin bundles its deps, so node_modules is never copied.
-        cpSync(srcDir, dest, { recursive: true, filter: (p) => basename(p) !== "node_modules" });
-        onProgress(`copied local plugin "${name}" → ${dest}`);
-        pkgDir = dest;
-        storedSpec = dest;
-    }
-    else {
-        const dir = pluginsDir();
-        ensurePluginsRoot(dir);
-        onProgress(`npm install ${spec}`);
-        await runNpm(["install", spec, "--prefix", dir, "--no-audit", "--no-fund", "--save"], onProgress, opts.signal);
-        storedSpec = npmPackageName(spec);
-        pkgDir = pluginPkgDir({ source, spec: storedSpec });
-        const name = (await importPluginManifest(pkgDir))?.name;
-        if (!name)
-            throw new Error(`package at ${pkgDir} has no valid \`plugin\` export`);
-        if (await declined(name, opts.onConflict))
-            return { name, source, skipped: true };
-    }
-    const manifest = await importPluginManifest(pkgDir);
-    if (!manifest || typeof manifest.name !== "string" || !manifest.name) {
-        throw new Error(`package at ${pkgDir} has no valid \`plugin\` export`);
-    }
-    const version = readVersion(pkgDir);
-    upsertPlugin({ name: manifest.name, spec: storedSpec, source, version });
-    onProgress(`installed plugin "${manifest.name}"${version ? `@${version}` : ""}`);
-    return { name: manifest.name, source, version };
-}
-/** A same-named plugin already exists and `onConflict` says don't overwrite. */
-async function declined(name, onConflict) {
-    if (!onConflict)
-        return false;
-    const existing = getPlugin(name);
-    if (!existing)
-        return false;
-    return !(await onConflict(existing));
+export function pruneInactivePluginInstallations({ minAgeMs = 60_000, stagingMinAgeMs = DEFAULT_STAGING_GC_AGE_MS, now = Date.now(), } = {}) {
+    const { stagingRoot, installationsRoot } = ensureStorageRoots();
+    const minimumAge = Math.max(0, minAgeMs);
+    const removed = [];
+    pruneStagingTransactions(stagingRoot, Math.max(0, stagingMinAgeMs), now, removed);
+    for (const pluginId of readdirSync(installationsRoot)) {
+        if (!PLUGIN_ID_PATTERN.test(pluginId))
+            continue;
+        db().transaction(() => {
+            const active = new Set();
+            const current = getPlugin(pluginId);
+            if (current && isRunnablePluginRecord(current))
+                active.add(resolve(current.installPath));
+            for (const lease of activeRuntimeLeases(pluginId, installationsRoot)) {
+                active.add(resolve(lease.installPath));
+            }
+            const idRoot = join(installationsRoot, pluginId);
+            let idStat;
+            try {
+                idStat = lstatSync(idRoot);
+            }
+            catch {
+                return;
+            }
+            if (!idStat.isDirectory() || idStat.isSymbolicLink())
+                return;
+            const entries = readdirSync(idRoot);
+            for (const installationId of entries) {
+                if (!INSTALLATION_ID_PATTERN.test(installationId))
+                    continue;
+                const candidate = join(idRoot, installationId);
+                if (active.has(resolve(candidate)))
+                    continue;
+                let candidateStat;
+                try {
+                    candidateStat = lstatSync(candidate);
+                }
+                catch {
+                    continue;
+                }
+                if (!candidateStat.isDirectory() ||
+                    candidateStat.isSymbolicLink() ||
+                    now - promotionTimestampMs(idRoot, installationId, candidateStat.ctimeMs) < minimumAge) {
+                    continue;
+                }
+                if (removeOwnedInstallation(installationsRoot, pluginId, candidate)) {
+                    removed.push(candidate);
+                }
+            }
+            for (const entry of entries) {
+                const installationId = promotionMarkerInstallationId(entry);
+                if (!installationId || existsSync(join(idRoot, installationId)))
+                    continue;
+                const marker = join(idRoot, entry);
+                try {
+                    const stat = lstatSync(marker);
+                    if (stat.isFile() &&
+                        !stat.isSymbolicLink() &&
+                        now - stat.mtimeMs >= minimumAge) {
+                        rmSync(marker, { force: true });
+                    }
+                }
+                catch {
+                    // A concurrently removed orphan marker needs no further work.
+                }
+            }
+        }).immediate();
+    }
+    return removed;
 }
-/** Uninstall a plugin: drop its record, npm-uninstall if applicable, refresh catalog. */
-export async function uninstallPlugin(name, onProgress = () => { }) {
-    const rec = getPlugin(name);
-    if (!rec)
-        return false;
-    if (rec.source === "npm") {
+function activeRuntimeLeases(pluginId, installationsRoot) {
+    const dataDir = join(rynxHome(), "plugin-data", pluginId);
+    return readPluginRuntimeLeases(dataDir).filter((lease) => {
+        if (lease.pluginId !== pluginId)
+            return false;
+        const invocationPid = pluginCliInvocationLeasePid(lease.leaseId);
+        if (invocationPid !== undefined && !isProcessAlive(invocationPid)) {
+            removePluginRuntimeLease(dataDir, lease.leaseId);
+            return false;
+        }
+        const candidate = resolve(lease.installPath);
+        if (dirname(candidate) !== join(installationsRoot, pluginId) ||
+            !INSTALLATION_ID_PATTERN.test(basename(candidate))) {
+            return false;
+        }
         try {
-            await runNpm(["uninstall", rec.spec, "--prefix", pluginsDir(), "--no-audit", "--no-fund"], onProgress);
+            const stat = lstatSync(candidate);
+            return stat.isDirectory() && !stat.isSymbolicLink() && realpathSync(candidate) === candidate;
         }
-        catch (error) {
-            onProgress(`npm uninstall warning: ${messageOf(error)}`);
+        catch {
+            return false;
         }
+    });
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
     }
-    else {
-        // local: remove the copied package dir — but only if it lives under our plugins
-        // root (older records may point at an in-place source tree; never delete that).
-        const dir = pluginPkgDir(rec);
-        if (dirname(dir) === pluginsDir()) {
-            try {
-                rmSync(dir, { recursive: true, force: true });
-                onProgress(`removed ${dir}`);
-            }
-            catch (error) {
-                onProgress(`remove warning: ${messageOf(error)}`);
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function samePluginGeneration(before, current) {
+    if (!before || !current)
+        return before === current;
+    return JSON.stringify(before) === JSON.stringify(current);
+}
+function writeStagingOwner(transactionDir) {
+    writeFileSync(join(transactionDir, STAGING_OWNER_FILE), `${JSON.stringify({ schemaVersion: 1, pid: process.pid, createdAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+}
+function pruneStagingTransactions(stagingRoot, minAgeMs, now, removed) {
+    for (const entry of readdirSync(stagingRoot)) {
+        if (!STAGING_TRANSACTION_PATTERN.test(entry))
+            continue;
+        const candidate = join(stagingRoot, entry);
+        try {
+            const stat = lstatSync(candidate);
+            if (!stat.isDirectory() ||
+                stat.isSymbolicLink() ||
+                dirname(realpathSync(candidate)) !== realpathSync(stagingRoot)) {
+                continue;
             }
+            const owner = readStagingOwner(candidate);
+            if (owner?.pid && isProcessAlive(owner.pid))
+                continue;
+            const createdAt = owner?.createdAtMs ?? Math.max(stat.ctimeMs, stat.mtimeMs);
+            if (now - createdAt < minAgeMs)
+                continue;
+            rmSync(candidate, { recursive: true, force: true });
+            removed.push(candidate);
+        }
+        catch {
+            // Invalid or concurrently removed staging data is never followed.
         }
     }
-    removePlugin(name);
-    onProgress(`uninstalled plugin "${name}"`);
-    return true;
 }
-function ensurePluginsRoot(dir) {
-    mkdirSync(dir, { recursive: true });
-    const pkg = join(dir, "package.json");
-    if (!existsSync(pkg)) {
-        writeFileSync(pkg, `${JSON.stringify({ name: "rynx-plugins", private: true, version: "0.0.0" }, null, 2)}\n`);
+function readStagingOwner(transactionDir) {
+    const file = join(transactionDir, STAGING_OWNER_FILE);
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_HOST_MARKER_BYTES)
+            return undefined;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.schemaVersion !== 1 ||
+            !Number.isSafeInteger(parsed.pid) ||
+            Number(parsed.pid) <= 0 ||
+            typeof parsed.createdAt !== "string" ||
+            !Number.isFinite(Date.parse(parsed.createdAt))) {
+            return undefined;
+        }
+        return { pid: Number(parsed.pid), createdAtMs: stat.mtimeMs };
+    }
+    catch {
+        return undefined;
     }
 }
-function readVersion(pkgDir) {
+function promotionMarkerPath(idRoot, installationId) {
+    return join(idRoot, `${installationId}${PROMOTION_MARKER_SUFFIX}`);
+}
+function writePromotionMarker(marker) {
+    writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, promotedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+}
+function promotionTimestampMs(idRoot, installationId, conservativeFallback) {
     try {
-        return JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"))
-            .version;
+        const stat = lstatSync(promotionMarkerPath(idRoot, installationId));
+        if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= MAX_HOST_MARKER_BYTES) {
+            return stat.mtimeMs;
+        }
     }
     catch {
-        return undefined;
+        // Installations predating promotion markers fall back to rename-sensitive ctime.
     }
+    return conservativeFallback;
 }
-function runNpm(args, onProgress, signal) {
-    return new Promise((resolveDone, reject) => {
-        const child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
-        const abort = () => child.kill();
-        signal?.addEventListener("abort", abort, { once: true });
-        const onData = (buf) => {
-            for (const line of buf.toString().split(/\r?\n/)) {
-                if (line.trim())
-                    onProgress(line);
-            }
-        };
-        child.stdout?.on("data", onData);
-        child.stderr?.on("data", onData);
-        child.on("error", reject);
-        child.on("close", (code) => {
-            signal?.removeEventListener("abort", abort);
-            if (code === 0)
-                resolveDone();
-            else
-                reject(new Error(`npm exited with code ${code ?? "null"}`));
-        });
-    });
+function promotionMarkerInstallationId(entry) {
+    const match = /^([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.rynx-promoted$/i.exec(entry);
+    return match?.[1];
 }
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
+function ensureStorageRoots() {
+    const configuredRoot = resolve(pluginsDir());
+    mkdirSync(configuredRoot, { recursive: true, mode: 0o700 });
+    const root = realpathSync(configuredRoot);
+    return {
+        stagingRoot: ensureDirectDirectory(root, "staging", "plugin staging directory"),
+        installationsRoot: ensureDirectDirectory(root, "installed", "plugin installations directory"),
+    };
+}
+/** Create/validate one non-symlink direct child of a canonical parent. */
+function ensureDirectDirectory(parent, child, label) {
+    const path = join(parent, child);
+    if (!existsSync(path))
+        mkdirSync(path, { mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a host-owned directory, not a symlink`);
+    }
+    const real = realpathSync(path);
+    if (dirname(real) !== realpathSync(parent)) {
+        throw new Error(`${label} resolves outside its host-owned parent`);
+    }
+    return real;
+}
+/**
+ * Delete only `<installations>/<validated-id>/<host UUID>`.
+ * Legacy paths, source directories, traversal strings, and symlinks are kept.
+ */
+function removeOwnedInstallation(installationsRoot, pluginId, installPath) {
+    try {
+        if (!PLUGIN_ID_PATTERN.test(pluginId))
+            return false;
+        const root = realpathSync(installationsRoot);
+        const idRoot = join(root, pluginId);
+        const candidate = resolve(installPath);
+        if (dirname(candidate) !== idRoot || !INSTALLATION_ID_PATTERN.test(basename(candidate))) {
+            return false;
+        }
+        const idStat = lstatSync(idRoot);
+        const candidateStat = lstatSync(candidate);
+        if (!idStat.isDirectory() ||
+            idStat.isSymbolicLink() ||
+            !candidateStat.isDirectory() ||
+            candidateStat.isSymbolicLink()) {
+            return false;
+        }
+        if (realpathSync(idRoot) !== idRoot || realpathSync(candidate) !== candidate)
+            return false;
+        rmSync(candidate, { recursive: true, force: true });
+        rmSync(promotionMarkerPath(idRoot, basename(candidate)), { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeProgress(callback) {
+    return (line) => {
+        try {
+            callback(line);
+        }
+        catch {
+            /* progress reporting must never change installation state */
+        }
+    };
 }

package/dist/plugin-package.d.ts

@@ -0,0 +1,38 @@
+import { type PluginManifestV1 } from "@rynx-ai/plugin-sdk";
+import type { PluginSource } from "./plugin-store.js";
+export interface MaterializePluginPackageRequest {
+    spec: string;
+    source: PluginSource;
+    destination: string;
+    onProgress: (line: string) => void;
+    signal?: AbortSignal;
+}
+export type PluginPackageMaterializer = (request: MaterializePluginPackageRequest) => Promise<void>;
+export interface InspectedPluginPackage {
+    manifest: PluginManifestV1;
+    version?: string;
+    integrity: string;
+}
+/** Classify provenance without fetching or executing anything. */
+export declare function detectPluginSource(spec: string): PluginSource;
+/** Stable provenance for local sources; remote specs are retained verbatim. */
+export declare function normalizePluginSpec(spec: string, source: PluginSource): string;
+/**
+ * Materialize a package without running package lifecycle scripts.
+ *
+ * Local workspace packages are archived with their internal dependency closure
+ * and then installed into a disposable npm prefix. Other local, npm, git, and
+ * URL specs use the same prefix flow. Every path therefore reaches inspection
+ * with runtime dependencies present, while lifecycle scripts remain disabled.
+ */
+export declare const materializePluginPackage: PluginPackageMaterializer;
+export declare function parseGitSpec(spec: string): {
+    url: string;
+    ref?: string;
+};
+/** Parse and validate static metadata, validate all executable entry paths, and hash the tree. */
+export declare function inspectPluginPackage(packageDir: string, options?: {
+    requireEntries?: boolean;
+}): InspectedPluginPackage;
+/** Run package/dependency build scripts only after explicit user approval. */
+export declare function rebuildPluginPackage(packageDir: string, onProgress: (line: string) => void, signal?: AbortSignal): Promise<void>;