@rynx-ai/daemon 0.1.0 → 0.1.10-beta.2

package/dist/plugin-package.js

@@ -0,0 +1,732 @@
+/**
+ * Static plugin-package materialization and inspection.
+ *
+ * This module deliberately never imports a plugin entry point. Package code is
+ * copied/downloaded with lifecycle scripts disabled, then only package.json and
+ * the referenced JSON manifest are parsed.
+ */
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants as fsConstants, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { lstat as lstatAsync, open as openFile, opendir, readlink as readlinkAsync, realpath as realpathAsync, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { create as createTar } from "tar";
+import { parsePluginManifest, } from "@rynx-ai/plugin-sdk";
+const MAX_METADATA_BYTES = 1024 * 1024;
+const PACKAGE_HASH_STREAM_BYTES = 256 * 1024;
+const DEFAULT_COMMAND_ABORT_GRACE_MS = 2_000;
+export const DEFAULT_PLUGIN_PACKAGE_INSPECTION_LIMITS = Object.freeze({
+    maxFileBytes: 128 * 1024 * 1024,
+    maxTotalBytes: 512 * 1024 * 1024,
+    maxEntries: 50_000,
+    maxDepth: 64,
+});
+/** Classify provenance without fetching or executing anything. */
+export function detectPluginSource(spec) {
+    if (looksLocal(spec))
+        return "local";
+    if (/^(?:git\+|git:|git@|ssh:|github:|gitlab:|bitbucket:)/i.test(spec) ||
+        /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:#.*)?$/.test(spec)) {
+        return "git";
+    }
+    if (/^https?:\/\//i.test(spec))
+        return spec.includes(".git") ? "git" : "url";
+    return "npm";
+}
+/** Stable provenance for local sources; remote specs are retained verbatim. */
+export function normalizePluginSpec(spec, source) {
+    return source === "local" ? toLocalDir(spec) : spec;
+}
+/**
+ * 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 const materializePluginPackage = async ({ spec, source, destination, onProgress, signal, }) => {
+    if (source === "local") {
+        await materializeLocalDirectory(toLocalDir(spec), destination, onProgress, signal);
+        return;
+    }
+    if (source === "git") {
+        const checkout = join(resolve(destination, ".."), "git-checkout");
+        await cloneGitPackage(spec, checkout, onProgress, signal);
+        await materializeLocalDirectory(checkout, destination, onProgress, signal);
+        return;
+    }
+    const archive = await acquirePublishedPackageArchive(spec, join(resolve(destination, ".."), "package-archive"), onProgress, signal);
+    await materializeWithNpm({
+        spec: archive,
+        prefix: join(resolve(destination, ".."), "remote-prefix"),
+        destination,
+        onProgress,
+        signal,
+    });
+};
+async function materializeLocalDirectory(sourceDir, destination, onProgress, signal) {
+    if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
+        throw new Error(`local plugin source is not a directory: ${sourceDir}`);
+    }
+    const sourceReal = realpathSync(sourceDir);
+    if (isWithin(sourceReal, resolve(destination))) {
+        throw new Error("plugin staging directory must not be inside the local source");
+    }
+    if (!hasProductionDependencies(sourceReal)) {
+        copyPackageTree(sourceReal, destination, true);
+        onProgress(`copied self-contained local plugin package from ${sourceReal}`);
+        return;
+    }
+    const workspaceRoot = findPnpmWorkspaceRoot(sourceReal);
+    if (workspaceRoot) {
+        const stagedWorkspace = await stageLocalWorkspaceClosure(sourceReal, workspaceRoot, join(resolve(destination, ".."), "workspace-packages"));
+        onProgress(`materializing local workspace plugin with ${stagedWorkspace.packageCount - 1} workspace dependency/dependencies`);
+        await materializeWithNpm({
+            spec: stagedWorkspace.pluginArchive,
+            prefix: join(resolve(destination, ".."), "local-prefix"),
+            destination,
+            onProgress,
+            signal,
+            label: "local workspace",
+        });
+        // The rewritten file: specs are a staging-only resolution aid. Keep the
+        // installed plugin's own package metadata identical to its source.
+        copyBoundedMetadataFile(join(sourceReal, "package.json"), join(destination, "package.json"), "package.json");
+        return;
+    }
+    const localArchiveRoot = join(resolve(destination, ".."), "local-package");
+    const localPackage = join(localArchiveRoot, "package");
+    rmSync(localArchiveRoot, { recursive: true, force: true });
+    copyPackageTree(sourceReal, localPackage, true);
+    const localArchive = join(localArchiveRoot, "package.tgz");
+    await createPackageArchive(localPackage, localArchive);
+    await materializeWithNpm({
+        spec: localArchive,
+        prefix: join(resolve(destination, ".."), "local-prefix"),
+        destination,
+        onProgress,
+        signal,
+        label: "local",
+    });
+}
+async function acquirePublishedPackageArchive(spec, archiveRoot, onProgress, signal) {
+    rmSync(archiveRoot, { recursive: true, force: true });
+    mkdirSync(archiveRoot, { recursive: true, mode: 0o700 });
+    await runNpm([
+        "pack",
+        "--ignore-scripts",
+        "--pack-destination",
+        archiveRoot,
+        "--",
+        spec,
+    ], onProgress, signal);
+    const archives = readdirSync(archiveRoot)
+        .filter((name) => name.endsWith(".tgz"))
+        .map((name) => join(archiveRoot, name));
+    if (archives.length !== 1 || !statSync(archives[0]).isFile()) {
+        throw new Error("package source did not produce exactly one npm archive");
+    }
+    return archives[0];
+}
+async function cloneGitPackage(spec, destination, onProgress, signal) {
+    const { url, ref } = parseGitSpec(spec);
+    rmSync(destination, { recursive: true, force: true });
+    const args = ["clone", "--no-checkout", "--filter=blob:none", "--", url, destination];
+    await runPluginPackageCommand("git", args, onProgress, { signal });
+    await runPluginPackageCommand("git", ["-C", destination, "checkout", "--detach", ref ?? "HEAD"], onProgress, { signal });
+}
+export function parseGitSpec(spec) {
+    let value = spec.trim();
+    let shorthand = false;
+    if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:#.*)?$/.test(value)) {
+        value = `https://github.com/${value}`;
+        shorthand = true;
+    }
+    else if (value.startsWith("github:")) {
+        value = `https://github.com/${value.slice("github:".length)}`;
+        shorthand = true;
+    }
+    else if (value.startsWith("gitlab:")) {
+        value = `https://gitlab.com/${value.slice("gitlab:".length)}`;
+        shorthand = true;
+    }
+    else if (value.startsWith("bitbucket:")) {
+        value = `https://bitbucket.org/${value.slice("bitbucket:".length)}`;
+        shorthand = true;
+    }
+    if (value.startsWith("git+"))
+        value = value.slice(4);
+    const hash = value.lastIndexOf("#");
+    const ref = hash >= 0 ? value.slice(hash + 1).trim() : undefined;
+    const url = hash >= 0 ? value.slice(0, hash) : value;
+    if (!url || url.startsWith("-") || /[\r\n\0]/.test(url)) {
+        throw new Error("git plugin source has an invalid URL");
+    }
+    if (ref && (ref.startsWith("-") || /[\r\n\0]/.test(ref))) {
+        throw new Error("git plugin source has an invalid ref");
+    }
+    const normalizedUrl = shorthand && !url.endsWith(".git") ? `${url}.git` : url;
+    return { url: normalizedUrl, ...(ref ? { ref } : {}) };
+}
+async function materializeWithNpm({ spec, prefix, destination, onProgress, signal, installLinks = false, label, }) {
+    mkdirSync(prefix, { recursive: true, mode: 0o700 });
+    writeFileSync(join(prefix, "package.json"), `${JSON.stringify({ name: "rynx-plugin-materializer", private: true }, null, 2)}\n`, { mode: 0o600 });
+    onProgress(`materializing ${label ?? (installLinks ? "local" : "remote")} plugin ${spec}`);
+    await runNpm([
+        "install",
+        "--prefix",
+        prefix,
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--package-lock=false",
+        "--install-strategy=nested",
+        ...(installLinks ? ["--install-links=true"] : []),
+        "--save-exact",
+        "--",
+        spec,
+    ], onProgress, signal);
+    const materializerPackage = readJsonObject(join(prefix, "package.json"), "materializer package.json");
+    const dependencies = materializerPackage.dependencies;
+    if (!isRecord(dependencies)) {
+        throw new Error("npm did not record the materialized plugin package");
+    }
+    const names = Object.keys(dependencies);
+    if (names.length !== 1 || !isSafeNpmPackageName(names[0])) {
+        throw new Error("npm materialization did not resolve exactly one safe package name");
+    }
+    const packageDir = join(prefix, "node_modules", ...names[0].split("/"));
+    const packageReal = requireContainedFile(prefix, packageDir, "materialized package", "directory");
+    copyPackageTree(packageReal, destination, false);
+}
+/** Parse and validate static metadata, validate all executable entry paths, and hash the tree. */
+export async function inspectPluginPackage(packageDir, options = {}) {
+    throwIfInspectionAborted(options.signal);
+    const packageRoot = realpathSync(packageDir);
+    const integrity = await hashPackageTree(packageRoot, normalizedInspectionLimits(options.limits), options.signal);
+    throwIfInspectionAborted(options.signal);
+    const packageJsonPath = requireContainedFile(packageRoot, join(packageRoot, "package.json"), "package.json", "file");
+    const packageJson = readJsonObject(packageJsonPath, "package.json");
+    if (!isRecord(packageJson.rynx) || typeof packageJson.rynx.manifest !== "string") {
+        throw new Error("package.json must declare `rynx.manifest` as a static JSON path");
+    }
+    const manifestPath = resolvePackageEntry(packageRoot, packageJson.rynx.manifest, "rynx.manifest");
+    const manifest = parsePluginManifest(readJsonObject(manifestPath, "plugin manifest"));
+    if (options.requireEntries !== false) {
+        resolvePackageEntry(packageRoot, manifest.runtimeEntry, "runtimeEntry");
+        if (manifest.cliEntry)
+            resolvePackageEntry(packageRoot, manifest.cliEntry, "cliEntry");
+    }
+    const version = typeof packageJson.version === "string" && packageJson.version.trim()
+        ? packageJson.version
+        : undefined;
+    return {
+        manifest,
+        ...(version ? { version } : {}),
+        integrity,
+    };
+}
+/** Run package/dependency build scripts only after explicit user approval. */
+export async function rebuildPluginPackage(packageDir, onProgress, signal) {
+    await runNpm([
+        "rebuild",
+        "--prefix",
+        realpathSync(packageDir),
+        "--foreground-scripts",
+        "--no-audit",
+        "--no-fund",
+    ], onProgress, signal);
+}
+function looksLocal(spec) {
+    if (spec.startsWith("file:"))
+        return true;
+    if (spec === "~" || spec.startsWith("~/"))
+        return true;
+    if (spec.startsWith("./") || spec.startsWith("../") || isAbsolute(spec))
+        return true;
+    try {
+        return existsSync(spec) && statSync(spec).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function toLocalDir(spec) {
+    let path;
+    if (spec.startsWith("file:")) {
+        try {
+            path = fileURLToPath(spec);
+        }
+        catch {
+            path = spec.slice("file:".length);
+        }
+    }
+    else {
+        path = spec;
+    }
+    if (path === "~" || path.startsWith("~/"))
+        path = join(homedir(), path.slice(1));
+    return resolve(path);
+}
+function copyPackageTree(source, destination, excludeNodeModules) {
+    cpSync(source, destination, {
+        recursive: true,
+        errorOnExist: true,
+        force: false,
+        dereference: false,
+        filter: (entry) => {
+            const rel = relative(source, entry);
+            if (!rel)
+                return true;
+            const segments = rel.split(sep);
+            if (segments.includes(".git"))
+                return false;
+            // npm generates command shims as absolute symlinks into its disposable
+            // materialization prefix. Plugin entries resolve tools by package path,
+            // so these non-runtime shims must not escape into the immutable closure.
+            if (segments.includes(".bin"))
+                return false;
+            return !excludeNodeModules || !segments.includes("node_modules");
+        },
+    });
+}
+function findPnpmWorkspaceRoot(start) {
+    let current = start;
+    while (true) {
+        if (existsSync(join(current, "pnpm-workspace.yaml")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function stageLocalWorkspaceClosure(pluginRoot, workspaceRoot, stagingRoot) {
+    const packages = new Map();
+    const workspaceNodeModules = existsSync(join(workspaceRoot, "node_modules"))
+        ? realpathSync(join(workspaceRoot, "node_modules"))
+        : undefined;
+    const visit = (source) => {
+        const sourceReal = realpathSync(source);
+        const packageJson = readJsonObject(join(sourceReal, "package.json"), "package.json");
+        const name = packageJson.name;
+        if (typeof name !== "string" || !isSafeNpmPackageName(name)) {
+            throw new Error(`local workspace package has an invalid name: ${String(name)}`);
+        }
+        const existing = packages.get(name);
+        if (existing) {
+            if (existing.source !== sourceReal) {
+                throw new Error(`local workspace contains duplicate package name: ${name}`);
+            }
+            return;
+        }
+        const key = createHash("sha256").update(name).digest("hex").slice(0, 16);
+        packages.set(name, {
+            source: sourceReal,
+            staged: join(stagingRoot, "packages", key),
+            archive: join(stagingRoot, "archives", `${key}.tgz`),
+        });
+        for (const field of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+            const dependencies = packageJson[field];
+            if (!isRecord(dependencies))
+                continue;
+            for (const [dependencyName, spec] of Object.entries(dependencies)) {
+                const dependencyPath = join(sourceReal, "node_modules", ...dependencyName.split("/"));
+                if (!existsSync(dependencyPath)) {
+                    if (typeof spec === "string" && spec.startsWith("workspace:")) {
+                        throw new Error(`local workspace dependency is not installed: ${name} -> ${dependencyName}`);
+                    }
+                    continue;
+                }
+                const dependencyReal = realpathSync(dependencyPath);
+                if (!isWithin(workspaceRoot, dependencyReal) ||
+                    (workspaceNodeModules && isWithin(workspaceNodeModules, dependencyReal))) {
+                    continue;
+                }
+                const dependencyPackage = readJsonObject(join(dependencyReal, "package.json"), `${dependencyName} package.json`);
+                if (dependencyPackage.name !== dependencyName) {
+                    throw new Error(`local workspace dependency identity mismatch: ${dependencyName}`);
+                }
+                visit(dependencyReal);
+            }
+        }
+    };
+    rmSync(stagingRoot, { recursive: true, force: true });
+    mkdirSync(stagingRoot, { recursive: true, mode: 0o700 });
+    visit(pluginRoot);
+    for (const entry of packages.values())
+        copyPackageTree(entry.source, entry.staged, true);
+    for (const entry of packages.values()) {
+        const file = join(entry.staged, "package.json");
+        const packageJson = readJsonObject(file, "staged package.json");
+        for (const field of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+            const dependencies = packageJson[field];
+            if (!isRecord(dependencies))
+                continue;
+            for (const dependencyName of Object.keys(dependencies)) {
+                const target = packages.get(dependencyName);
+                if (target)
+                    dependencies[dependencyName] = `file:${target.archive}`;
+            }
+        }
+        writeFileSync(file, `${JSON.stringify(packageJson, null, 2)}\n`, { mode: 0o600 });
+    }
+    await Promise.all([...packages.values()].map((entry) => createPackageArchive(entry.staged, entry.archive)));
+    const pluginName = readJsonObject(join(pluginRoot, "package.json"), "package.json").name;
+    const plugin = typeof pluginName === "string" ? packages.get(pluginName) : undefined;
+    if (!plugin)
+        throw new Error("local workspace plugin was not staged");
+    return { pluginArchive: plugin.archive, packageCount: packages.size };
+}
+async function createPackageArchive(packageRoot, archive) {
+    mkdirSync(dirname(archive), { recursive: true, mode: 0o700 });
+    await createTar({
+        cwd: packageRoot,
+        file: archive,
+        gzip: true,
+        portable: true,
+        prefix: "package",
+        noMtime: true,
+    }, readdirSync(packageRoot));
+}
+function hasProductionDependencies(packageRoot) {
+    const packageJson = readJsonObject(join(packageRoot, "package.json"), "package.json");
+    return ["dependencies", "optionalDependencies", "peerDependencies"].some((key) => {
+        const value = packageJson[key];
+        return isRecord(value) && Object.keys(value).length > 0;
+    });
+}
+function resolvePackageEntry(packageRoot, entry, label) {
+    if (!entry.startsWith("./") || entry.includes("\\") || entry.includes("\0")) {
+        throw new Error(`${label} must be a package-root-relative POSIX path starting with ./`);
+    }
+    const segments = entry.slice(2).split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new Error(`${label} must not contain empty, . or .. segments`);
+    }
+    return requireContainedFile(packageRoot, resolve(packageRoot, entry), label, "file");
+}
+function requireContainedFile(root, candidate, label, kind) {
+    let rootReal;
+    let candidateReal;
+    try {
+        rootReal = realpathSync(root);
+        candidateReal = realpathSync(candidate);
+    }
+    catch {
+        throw new Error(`${label} does not exist`);
+    }
+    if (!isWithin(rootReal, candidateReal)) {
+        throw new Error(`${label} resolves outside the plugin package`);
+    }
+    const stat = statSync(candidateReal);
+    if (kind === "file" ? !stat.isFile() : !stat.isDirectory()) {
+        throw new Error(`${label} must be a ${kind}`);
+    }
+    return candidateReal;
+}
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function readJsonObject(path, label) {
+    let raw;
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile())
+            throw new Error("not a file");
+        if (stat.size > MAX_METADATA_BYTES)
+            throw new Error("metadata is too large");
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`cannot read ${label}: ${messageOf(error)}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            throw new Error("must contain a JSON object");
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`invalid ${label}: ${messageOf(error)}`);
+    }
+}
+function copyBoundedMetadataFile(source, destination, label) {
+    try {
+        const stat = statSync(source);
+        if (!stat.isFile())
+            throw new Error("not a file");
+        if (stat.size > MAX_METADATA_BYTES)
+            throw new Error("metadata is too large");
+        copyFileSync(source, destination);
+    }
+    catch (error) {
+        throw new Error(`cannot copy ${label}: ${messageOf(error)}`);
+    }
+}
+async function hashPackageTree(root, limits, signal) {
+    const hash = createHash("sha256");
+    hash.update("rynx-plugin-package-v1\0");
+    let entryCount = 0;
+    let totalBytes = 0;
+    await visit(root, "", 0);
+    return `sha256-${hash.digest("base64")}`;
+    async function visit(path, rel, depth) {
+        throwIfInspectionAborted(signal);
+        entryCount += 1;
+        if (entryCount > limits.maxEntries) {
+            throw new Error(`plugin package exceeds ${limits.maxEntries} entries`);
+        }
+        if (depth > limits.maxDepth) {
+            throw new Error(`plugin package exceeds maximum depth ${limits.maxDepth}`);
+        }
+        const stat = await lstatAsync(path);
+        const normalized = rel.split(sep).join("/");
+        if (stat.isDirectory()) {
+            hash.update(`d\0${normalized}\0`);
+            const names = [];
+            const directory = await opendir(path);
+            for await (const entry of directory) {
+                throwIfInspectionAborted(signal);
+                names.push(entry.name);
+                if (entryCount + names.length > limits.maxEntries) {
+                    throw new Error(`plugin package exceeds ${limits.maxEntries} entries`);
+                }
+            }
+            for (const name of names.sort()) {
+                await visit(join(path, name), join(rel, name), depth + 1);
+            }
+            return;
+        }
+        if (stat.isFile()) {
+            if (stat.size > limits.maxFileBytes) {
+                throw new Error(`plugin package file exceeds ${limits.maxFileBytes} bytes: ${normalized}`);
+            }
+            if (totalBytes + stat.size > limits.maxTotalBytes) {
+                throw new Error(`plugin package exceeds ${limits.maxTotalBytes} total bytes`);
+            }
+            totalBytes += stat.size;
+            hash.update(`f\0${normalized}\0${stat.size}\0`);
+            const noFollow = process.platform === "win32" ? 0 : fsConstants.O_NOFOLLOW;
+            const file = await openFile(path, fsConstants.O_RDONLY | noFollow);
+            try {
+                const before = await file.stat();
+                if (!before.isFile() || before.size !== stat.size) {
+                    throw new Error(`plugin package file changed during inspection: ${normalized}`);
+                }
+                let streamedBytes = 0;
+                const stream = file.createReadStream({
+                    autoClose: false,
+                    highWaterMark: PACKAGE_HASH_STREAM_BYTES,
+                    ...(signal ? { signal } : {}),
+                });
+                for await (const chunk of stream) {
+                    throwIfInspectionAborted(signal);
+                    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                    streamedBytes += bytes.byteLength;
+                    if (streamedBytes > limits.maxFileBytes ||
+                        totalBytes - stat.size + streamedBytes > limits.maxTotalBytes) {
+                        throw new Error(`plugin package file changed during inspection: ${normalized}`);
+                    }
+                    hash.update(bytes);
+                }
+                const after = await file.stat();
+                if (streamedBytes !== before.size ||
+                    after.size !== before.size ||
+                    after.mtimeMs !== before.mtimeMs) {
+                    throw new Error(`plugin package file changed during inspection: ${normalized}`);
+                }
+            }
+            finally {
+                await file.close();
+            }
+            return;
+        }
+        if (stat.isSymbolicLink()) {
+            let target;
+            try {
+                target = await realpathAsync(path);
+            }
+            catch {
+                throw new Error(`plugin package contains a broken symlink: ${normalized}`);
+            }
+            if (!isWithin(root, target)) {
+                throw new Error(`plugin package symlink resolves outside the package: ${normalized}`);
+            }
+            const link = await readlinkAsync(path);
+            hash.update(`l\0${normalized}\0${link}\0`);
+            return;
+        }
+        throw new Error(`unsupported package entry: ${normalized}`);
+    }
+}
+function normalizedInspectionLimits(overrides) {
+    const limits = {
+        ...DEFAULT_PLUGIN_PACKAGE_INSPECTION_LIMITS,
+        ...overrides,
+    };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new Error(`plugin package inspection ${name} must be a positive safe integer`);
+        }
+    }
+    return limits;
+}
+function throwIfInspectionAborted(signal) {
+    if (signal?.aborted) {
+        throw new Error("plugin package inspection aborted", { cause: signal.reason });
+    }
+}
+function isSafeNpmPackageName(name) {
+    return /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+function runNpm(args, onProgress, signal) {
+    return runPluginPackageCommand("npm", args, onProgress, { signal });
+}
+/**
+ * Run one package tool without a shell and tear down its full POSIX process
+ * group on cancellation. Windows cannot signal process groups through Node,
+ * so it safely degrades to TERM→KILL on the direct child.
+ */
+export function runPluginPackageCommand(command, args, onProgress, options = {}) {
+    return new Promise((resolveDone, reject) => {
+        const { signal, cwd } = options;
+        const abortGraceMs = options.abortGraceMs ?? DEFAULT_COMMAND_ABORT_GRACE_MS;
+        if (!Number.isSafeInteger(abortGraceMs) || abortGraceMs <= 0 || abortGraceMs > 60_000) {
+            reject(new Error("plugin command abort grace must be 1-60000ms"));
+            return;
+        }
+        if (signal?.aborted) {
+            reject(new Error("plugin installation aborted"));
+            return;
+        }
+        const useProcessGroup = process.platform !== "win32";
+        const child = spawn(command, args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: useProcessGroup,
+        });
+        let settled = false;
+        let aborting = false;
+        let childClosed = false;
+        let escalationTimer;
+        let hardStopTimer;
+        let groupPollTimer;
+        const settle = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            if (escalationTimer)
+                clearTimeout(escalationTimer);
+            if (hardStopTimer)
+                clearTimeout(hardStopTimer);
+            if (groupPollTimer)
+                clearInterval(groupPollTimer);
+            callback();
+        };
+        const rejectAborted = () => settle(() => reject(new Error("plugin installation aborted", {
+            cause: signal?.reason,
+        })));
+        const processGroupAlive = () => {
+            if (!useProcessGroup || child.pid === undefined)
+                return !childClosed;
+            try {
+                process.kill(-child.pid, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code !== "ESRCH";
+            }
+        };
+        const signalProcessTree = (processSignal) => {
+            if (useProcessGroup && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, processSignal);
+                    return;
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH") {
+                        try {
+                            child.kill(processSignal);
+                        }
+                        catch {
+                            // The bounded hard-stop path below still resolves cancellation.
+                        }
+                    }
+                    return;
+                }
+            }
+            try {
+                child.kill(processSignal);
+            }
+            catch {
+                // A concurrently exited child is already stopped.
+            }
+        };
+        const finishWhenStopped = () => {
+            if (!aborting || settled)
+                return;
+            if (childClosed && !processGroupAlive())
+                rejectAborted();
+        };
+        const abort = () => {
+            if (aborting || settled)
+                return;
+            aborting = true;
+            signalProcessTree("SIGTERM");
+            groupPollTimer = setInterval(finishWhenStopped, 25);
+            escalationTimer = setTimeout(() => {
+                signalProcessTree("SIGKILL");
+                finishWhenStopped();
+            }, abortGraceMs);
+            hardStopTimer = setTimeout(rejectAborted, abortGraceMs * 2);
+            finishWhenStopped();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const onData = (buffer) => {
+            for (const line of buffer.toString().split(/\r?\n/)) {
+                if (line.trim())
+                    onProgress(line);
+            }
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (error) => {
+            if (aborting)
+                rejectAborted();
+            else
+                settle(() => reject(error));
+        });
+        child.on("close", (code) => {
+            childClosed = true;
+            if (aborting || signal?.aborted) {
+                if (!aborting)
+                    abort();
+                if (!useProcessGroup)
+                    rejectAborted();
+                else
+                    finishWhenStopped();
+                return;
+            }
+            settle(() => {
+                if (code === 0)
+                    resolveDone();
+                else
+                    reject(new Error(`${command} exited with code ${code ?? "null"}`));
+            });
+        });
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}