@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.1

package/lib/onboarding/allowlist.d.ts

@@ -0,0 +1,54 @@
+import type { ConsolePrincipal } from '@zhin.js/host-http';
+/** Where an allowlisted package comes from (ADR 0053 §3). */
+export type InstallPackageKind = 'database-driver' | 'adapter' | 'ai' | 'market';
+export interface InstallAllowlistEntry {
+    readonly name: string;
+    readonly kind: InstallPackageKind;
+    /** Range / dist-tag used when a request names no version (`latest` → bare name). */
+    readonly defaultVersion?: string;
+}
+/** One plugin-market entry; the catalog source (plugins.json, registry) is the caller's. */
+export interface MarketCatalogEntry {
+    readonly name: string;
+    readonly version?: string;
+}
+export interface InstallAllowlist {
+    get(name: string): InstallAllowlistEntry | undefined;
+    entries(): readonly InstallAllowlistEntry[];
+}
+/** A request that passed parsing and the allowlist. `spec` is what the package manager receives. */
+export interface AuthorizedPackage {
+    readonly name: string;
+    readonly kind: InstallPackageKind;
+    readonly version?: string;
+    readonly spec: string;
+}
+export declare function isSafeVersionSpec(version: string): boolean;
+/**
+ * Parses `name` or `name@version` strictly. Anything else (URLs, paths, git / file / npm: aliases,
+ * whitespace, shell syntax) is rejected; there is no fallback interpretation.
+ */
+export declare function parseInstallRequest(request: unknown): {
+    readonly name: string;
+    readonly version?: string;
+};
+export interface InstallAllowlistOptions {
+    /** Plugin-market entries; names that fail parsing are dropped. */
+    readonly market?: readonly MarketCatalogEntry[];
+}
+/** Official catalog: database drivers, adapter packages (+ their extra deps), AI stack, market entries. */
+export declare function createInstallAllowlist(options?: InstallAllowlistOptions): InstallAllowlist;
+/**
+ * A Console principal, or `'local'` for the CLI: the operator already has shell access to the
+ * project, so only the allowlist and spec rules apply.
+ */
+export type InstallPrincipal = ConsolePrincipal | 'local';
+export interface AuthorizeInstallOptions {
+    /** True once an owner exists; the bootstrap token is refused afterwards. */
+    readonly ownerExists?: boolean;
+}
+/**
+ * ADR 0053 §3: only allowlisted packages; the bootstrap token may install database drivers only
+ * (and only before the first owner exists); everything else needs `plugin.manage`. Deny by default.
+ */
+export declare function authorizeInstall(packages: readonly unknown[], principal: InstallPrincipal | undefined, allowlist: InstallAllowlist, options?: AuthorizeInstallOptions): readonly AuthorizedPackage[];

package/lib/onboarding/allowlist.js

@@ -0,0 +1,106 @@
+import { CONSOLE_PERMISSIONS, grantsAllow } from '@zhin.js/console-protocol';
+import { ADAPTERS, AI_STACK_VERSIONS, DATABASE_DIALECT_DEFINITIONS, ZHIN_STACK_VERSIONS, } from '@zhin.js/scaffold-wizard';
+import { OnboardingError } from './errors.js';
+const NAME = /^(?:@[a-z0-9][a-z0-9._-]{0,213}\/)?[a-z0-9][a-z0-9._-]{0,213}$/u;
+// One comparator without whitespace: 1.2.3, ^1.2.3, ~1.2, >=1.0.0, 1.x, with an optional prerelease.
+const SEMVER_RANGE = /^(?:[~^]|[<>]=?|=)?\d{1,9}(?:\.(?:\d{1,9}|x|\*)){0,2}(?:-[0-9A-Za-z][0-9A-Za-z.-]{0,63})?$/u;
+// npm dist-tags must not look like a version or a path.
+const DIST_TAG = /^[a-z][a-z0-9-]{0,31}$/u;
+export function isSafeVersionSpec(version) {
+    return SEMVER_RANGE.test(version) || DIST_TAG.test(version) || version === '*';
+}
+/**
+ * Parses `name` or `name@version` strictly. Anything else (URLs, paths, git / file / npm: aliases,
+ * whitespace, shell syntax) is rejected; there is no fallback interpretation.
+ */
+export function parseInstallRequest(request) {
+    if (typeof request !== 'string' || request.length === 0 || request.length > 256) {
+        throw new OnboardingError('invalid_input', '包名无效');
+    }
+    const at = request.indexOf('@', request.startsWith('@') ? 1 : 0);
+    const name = at < 0 ? request : request.slice(0, at);
+    const version = at < 0 ? undefined : request.slice(at + 1);
+    if (!NAME.test(name) || name.includes('..'))
+        throw new OnboardingError('invalid_input', `包名无效：${name.slice(0, 64)}`);
+    if (version !== undefined && !isSafeVersionSpec(version)) {
+        throw new OnboardingError('invalid_input', `${name} 的版本只能是 semver 范围或 dist-tag`);
+    }
+    return Object.freeze({ name, ...(version === undefined ? {} : { version }) });
+}
+/** Official catalog: database drivers, adapter packages (+ their extra deps), AI stack, market entries. */
+export function createInstallAllowlist(options = {}) {
+    const map = new Map();
+    const add = (name, kind, version) => {
+        if (map.has(name) || !NAME.test(name))
+            return;
+        const defaultVersion = version && version !== 'latest' && isSafeVersionSpec(version) ? version : undefined;
+        map.set(name, Object.freeze({ name, kind, ...(defaultVersion ? { defaultVersion } : {}) }));
+    };
+    // Order matters: a driver stays a driver even if a later catalog also lists it.
+    for (const definition of DATABASE_DIALECT_DEFINITIONS) {
+        if (definition.driver)
+            add(definition.driver.package, 'database-driver', definition.driver.version);
+    }
+    const stack = ZHIN_STACK_VERSIONS;
+    for (const adapter of ADAPTERS) {
+        add(adapter.package, 'adapter', stack[adapter.package]);
+        for (const [name, version] of Object.entries(adapter.extraDeps ?? {}))
+            add(name, 'adapter', version);
+    }
+    for (const [name, version] of Object.entries(AI_STACK_VERSIONS))
+        add(name, 'ai', version);
+    // AI authoring conventions the wizard adds with the agent (collectWizardDependencies).
+    for (const name of ['@zhin.js/tool', '@zhin.js/prompt-section'])
+        add(name, 'ai', stack[name]);
+    for (const entry of options.market ?? []) {
+        if (entry && typeof entry.name === 'string')
+            add(entry.name, 'market', entry.version);
+    }
+    const entries = Object.freeze([...map.values()]);
+    return Object.freeze({
+        get: (name) => map.get(name),
+        entries: () => entries,
+    });
+}
+/**
+ * ADR 0053 §3: only allowlisted packages; the bootstrap token may install database drivers only
+ * (and only before the first owner exists); everything else needs `plugin.manage`. Deny by default.
+ */
+export function authorizeInstall(packages, principal, allowlist, options = {}) {
+    if (!principal)
+        throw new OnboardingError('forbidden', '未登录');
+    if (!Array.isArray(packages) || packages.length === 0 || packages.length > 32) {
+        throw new OnboardingError('invalid_input', '请提供 1–32 个包');
+    }
+    const seen = new Set();
+    const authorized = [];
+    for (const request of packages) {
+        const { name, version } = parseInstallRequest(request);
+        const entry = allowlist.get(name);
+        if (!entry)
+            throw new OnboardingError('forbidden', `${name} 不在可安装目录中`);
+        if (seen.has(name))
+            throw new OnboardingError('invalid_input', `重复的包：${name}`);
+        seen.add(name);
+        if (principal === 'local') {
+            // Allowlist and spec checks above still apply.
+        }
+        else if (principal.kind === 'bootstrap') {
+            if (options.ownerExists)
+                throw new OnboardingError('forbidden', '已创建所有者：初始化令牌已失效');
+            if (entry.kind !== 'database-driver')
+                throw new OnboardingError('forbidden', '初始化令牌只能安装数据库驱动');
+        }
+        else if (!grantsAllow(principal.grants, CONSOLE_PERMISSIONS.PLUGIN_MANAGE)) {
+            throw new OnboardingError('forbidden', `安装 ${name} 需要 ${CONSOLE_PERMISSIONS.PLUGIN_MANAGE} 权限`);
+        }
+        const resolved = version ?? entry.defaultVersion;
+        authorized.push(Object.freeze({
+            name,
+            kind: entry.kind,
+            ...(resolved === undefined ? {} : { version: resolved }),
+            spec: resolved === undefined ? name : `${name}@${resolved}`,
+        }));
+    }
+    return Object.freeze(authorized);
+}

package/lib/onboarding/errors.d.ts

@@ -0,0 +1,7 @@
+export type OnboardingErrorCode = 'invalid_input' | 'forbidden' | 'conflict' | 'unavailable';
+/** Transport-independent onboarding error; adapters map `status` to HTTP / RPC errors. */
+export declare class OnboardingError extends Error {
+    readonly code: OnboardingErrorCode;
+    readonly status: number;
+    constructor(code: OnboardingErrorCode, message: string);
+}

package/lib/onboarding/errors.js

@@ -0,0 +1,17 @@
+const STATUS = {
+    invalid_input: 400,
+    forbidden: 403,
+    conflict: 409,
+    unavailable: 503,
+};
+/** Transport-independent onboarding error; adapters map `status` to HTTP / RPC errors. */
+export class OnboardingError extends Error {
+    code;
+    status;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OnboardingError';
+        this.status = STATUS[code];
+    }
+}

package/lib/onboarding/index.d.ts

@@ -0,0 +1,6 @@
+export * from './errors.js';
+export * from './allowlist.js';
+export * from './state-store.js';
+export * from './package-manager.js';
+export * from './install.js';
+export * from './service.js';

package/lib/onboarding/index.js

@@ -0,0 +1,6 @@
+export * from './errors.js';
+export * from './allowlist.js';
+export * from './state-store.js';
+export * from './package-manager.js';
+export * from './install.js';
+export * from './service.js';

package/lib/onboarding/install.d.ts

@@ -0,0 +1,99 @@
+import type { GatewayPluginConfigurationNeed } from '@zhin.js/console-protocol';
+import type { AuthorizedPackage, InstallPackageKind } from './allowlist.js';
+import type { PackageManagerOutput } from './package-manager.js';
+/** The part of `PluginManagementWorkflow` / `PluginManagementPort` installation uses. */
+export interface PackageInstallPort {
+    inspect?(packageName: string): Promise<{
+        readonly installed: boolean;
+    }>;
+    install(spec: string, expectedRevision?: string, expectedProjectRevision?: string, options?: {
+        readonly enable?: boolean;
+    }): Promise<{
+        readonly restartRequired: boolean;
+        /** Installed but left undeclared: the schema requires fields without defaults. */
+        readonly needsConfiguration?: GatewayPluginConfigurationNeed;
+    }>;
+    uninstall?(packageName: string): Promise<unknown>;
+}
+export type InstallEvent = {
+    readonly type: 'start';
+    readonly packages: readonly {
+        readonly name: string;
+        readonly spec: string;
+        readonly kind: InstallPackageKind;
+    }[];
+} | {
+    readonly type: 'package-start';
+    readonly name: string;
+    readonly spec: string;
+} | {
+    readonly type: 'output';
+    readonly name: string;
+    readonly stream: 'stdout' | 'stderr';
+    readonly chunk: string;
+} | {
+    readonly type: 'package-done';
+    readonly name: string;
+    readonly restartRequired: boolean;
+    readonly needsConfiguration?: GatewayPluginConfigurationNeed;
+} | {
+    readonly type: 'package-failed';
+    readonly name: string;
+    readonly error: string;
+    readonly completedStages: readonly string[];
+} | {
+    readonly type: 'rollback';
+    readonly name: string;
+    readonly ok: boolean;
+    readonly error?: string;
+} | {
+    readonly type: 'done';
+    readonly report: InstallReport;
+};
+export interface InstallReport {
+    readonly ok: boolean;
+    readonly installed: readonly string[];
+    readonly failed?: {
+        readonly name: string;
+        readonly error: string;
+        readonly completedStages: readonly string[];
+    };
+    /** Packages this batch added and then removed again after a failure. */
+    readonly rolledBack: readonly string[];
+    /** Rollback attempts that failed; those packages remain and need manual cleanup. */
+    readonly rollbackFailed: readonly {
+        readonly name: string;
+        readonly error: string;
+    }[];
+    /** Packages that were already installed and therefore never rolled back. */
+    readonly preexisting: readonly string[];
+    readonly restartRequired: boolean;
+    /**
+     * Plugins installed but not declared because their configuration is incomplete (e.g. an
+     * adapter's first account): configure and declare them next (`gateway.plugins.declare`).
+     */
+    readonly needsConfiguration?: readonly GatewayPluginConfigurationNeed[];
+}
+export type InstallListener = (event: InstallEvent) => void;
+/** Routes package-manager output to whichever install is running (installs are serialized). */
+export declare class InstallOutputRelay {
+    #private;
+    readonly output: PackageManagerOutput;
+    attach(listener: PackageManagerOutput): () => void;
+}
+export interface InstallPackagesOptions {
+    readonly port: PackageInstallPort;
+    readonly onEvent?: InstallListener;
+    readonly relay?: InstallOutputRelay;
+    /** Remove packages this batch added when a later one fails (default true). */
+    readonly rollback?: boolean;
+}
+/**
+ * Installs already-authorized packages one at a time through the plugin-management workflow.
+ * Stops at the first failure and, when possible, removes what this batch added (reported, never assumed).
+ */
+export declare function installPackages(packages: readonly AuthorizedPackage[], options: InstallPackagesOptions): Promise<InstallReport>;
+/** Adapts a listener-based run into an async iterator of its events (ends after the run settles). */
+export declare function streamEvents<E, T>(run: (emit: (event: E) => void) => Promise<T>): AsyncIterableIterator<E> & {
+    readonly result: Promise<T>;
+};

package/lib/onboarding/install.js

@@ -0,0 +1,132 @@
+/** Routes package-manager output to whichever install is running (installs are serialized). */
+export class InstallOutputRelay {
+    #listener;
+    output = (stream, chunk) => this.#listener?.(stream, chunk);
+    attach(listener) {
+        this.#listener = listener;
+        return () => { if (this.#listener === listener)
+            this.#listener = undefined; };
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function completedStages(error) {
+    const stages = error?.completedStages;
+    return Array.isArray(stages) ? Object.freeze(stages.filter((stage) => typeof stage === 'string')) : Object.freeze([]);
+}
+/**
+ * Installs already-authorized packages one at a time through the plugin-management workflow.
+ * Stops at the first failure and, when possible, removes what this batch added (reported, never assumed).
+ */
+export async function installPackages(packages, options) {
+    const emit = (event) => { try {
+        options.onEvent?.(event);
+    }
+    catch { /* listeners never break installs */ } };
+    emit({ type: 'start', packages: packages.map(({ name, spec, kind }) => ({ name, spec, kind })) });
+    const installed = [];
+    const added = [];
+    const preexisting = [];
+    let restartRequired = false;
+    const needsConfiguration = [];
+    let failed;
+    for (const item of packages) {
+        let existed;
+        try {
+            existed = options.port.inspect ? (await options.port.inspect(item.name)).installed : undefined;
+        }
+        catch {
+            existed = undefined;
+        }
+        if (existed)
+            preexisting.push(item.name);
+        emit({ type: 'package-start', name: item.name, spec: item.spec });
+        const detach = options.relay?.attach((stream, chunk) => emit({ type: 'output', name: item.name, stream, chunk }));
+        try {
+            // Drivers and AI stack packages are plain dependencies; adapters and market plugins get declared.
+            const enable = item.kind === 'adapter' || item.kind === 'market';
+            const result = await options.port.install(item.spec, undefined, undefined, { enable });
+            restartRequired ||= result.restartRequired;
+            installed.push(item.name);
+            // Only packages proven absent beforehand are ours to remove.
+            if (existed === false)
+                added.push(item.name);
+            if (result.needsConfiguration)
+                needsConfiguration.push(result.needsConfiguration);
+            emit({ type: 'package-done', name: item.name, restartRequired: result.restartRequired,
+                ...(result.needsConfiguration ? { needsConfiguration: result.needsConfiguration } : {}) });
+        }
+        catch (error) {
+            const stages = completedStages(error);
+            failed = Object.freeze({ name: item.name, error: message(error), completedStages: stages });
+            if (existed === false && stages.includes('dependency-install'))
+                added.push(item.name);
+            emit({ type: 'package-failed', ...failed });
+            break;
+        }
+        finally {
+            detach?.();
+        }
+    }
+    const rolledBack = [];
+    const rollbackFailed = [];
+    if (failed && options.rollback !== false) {
+        for (const name of [...added].reverse()) {
+            if (!options.port.uninstall) {
+                rollbackFailed.push({ name, error: 'uninstall unavailable' });
+                emit({ type: 'rollback', name, ok: false, error: 'uninstall unavailable' });
+                continue;
+            }
+            try {
+                await options.port.uninstall(name);
+                rolledBack.push(name);
+                emit({ type: 'rollback', name, ok: true });
+            }
+            catch (error) {
+                rollbackFailed.push({ name, error: message(error) });
+                emit({ type: 'rollback', name, ok: false, error: message(error) });
+            }
+        }
+    }
+    const report = Object.freeze({
+        ok: !failed,
+        installed: Object.freeze(installed.filter(name => !rolledBack.includes(name))),
+        ...(failed ? { failed } : {}),
+        rolledBack: Object.freeze(rolledBack),
+        rollbackFailed: Object.freeze(rollbackFailed.map(entry => Object.freeze(entry))),
+        preexisting: Object.freeze(preexisting),
+        restartRequired: restartRequired && installed.some(name => !rolledBack.includes(name)),
+        ...(() => {
+            const pending = needsConfiguration.filter(need => installed.includes(need.name) && !rolledBack.includes(need.name));
+            return pending.length ? { needsConfiguration: Object.freeze(pending) } : {};
+        })(),
+    });
+    emit({ type: 'done', report });
+    return report;
+}
+/** Adapts a listener-based run into an async iterator of its events (ends after the run settles). */
+export function streamEvents(run) {
+    const queue = [];
+    let wake;
+    let settled = false;
+    const result = run(event => { queue.push(event); wake?.(); }).finally(() => { settled = true; wake?.(); });
+    result.catch(() => { });
+    const iterator = {
+        result,
+        async next() {
+            for (;;) {
+                if (queue.length)
+                    return { value: queue.shift(), done: false };
+                if (settled) {
+                    await result;
+                    return { value: undefined, done: true };
+                }
+                await new Promise(resolveWake => { wake = resolveWake; });
+                wake = undefined;
+            }
+        },
+        [Symbol.asyncIterator]() { return iterator; },
+    };
+    return iterator;
+}

package/lib/onboarding/package-manager.d.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+export type PackageManagerName = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/** `package.json#packageManager`, then lockfiles; pnpm is the scaffold default. */
+export declare function detectPackageManager(projectRoot: string): Promise<PackageManagerName>;
+/**
+ * Maps the workflow's pnpm invocation (`add|remove [-w] [-D] <spec>`) and the gateway's
+ * `update [-w] [<name>…]` / `install [--frozen-lockfile]` to another manager.
+ * Unknown flags are refused rather than forwarded.
+ */
+export declare function translatePackageManagerArgs(manager: PackageManagerName, args: readonly string[]): readonly string[];
+/** How to spawn one command without `shell: true`. */
+export interface ResolvedCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Set for `cmd.exe /d /s /c "…"`: the command line is already quoted. */
+    readonly windowsVerbatimArguments?: boolean;
+}
+export interface ResolveCommandOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly env?: NodeJS.ProcessEnv;
+    /** File probe; defaults to a synchronous `stat().isFile()`. */
+    readonly isFile?: (path: string) => boolean;
+}
+/** Quotes one argument for `CommandLineToArgvW`, then escapes cmd metacharacters. */
+export declare function quoteWindowsCmdArgument(argument: string, doubleEscape: boolean): string;
+/**
+ * Resolves a package-manager command for `spawn` / `execFile` without a shell. POSIX: unchanged.
+ * Windows: `PATH` × `PATHEXT` lookup; an `.exe` / `.com` runs directly, a `.cmd` / `.bat` shim
+ * (or an unresolved name, assumed to be `<name>.cmd`) runs through `cmd.exe /d /s /c` with every
+ * argument quoted and its metacharacters escaped, since Node refuses to spawn batch files directly.
+ */
+export declare function resolveCommand(name: string, args: readonly string[], options?: ResolveCommandOptions): ResolvedCommand;
+export type PackageManagerOutput = (stream: 'stdout' | 'stderr', chunk: string) => void;
+export interface StreamingPackageManagerOptions {
+    /** Fixed manager; otherwise detected per project root. */
+    readonly manager?: PackageManagerName;
+    /** Injection point for tests. */
+    readonly spawn?: typeof spawn;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Platform used for command resolution (tests). */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * An `installDependencies` implementation for `PluginManagementWorkflow` that streams output.
+ * No shell: the command and every argument are passed as an argv array.
+ */
+export declare function createStreamingPackageManager(output: PackageManagerOutput, options?: StreamingPackageManagerOptions): (args: readonly string[], projectRoot: string) => Promise<void>;

package/lib/onboarding/package-manager.js

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm'],
+];
+/** `package.json#packageManager`, then lockfiles; pnpm is the scaffold default. */
+export async function detectPackageManager(projectRoot) {
+    try {
+        const manifest = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'));
+        const declared = typeof manifest.packageManager === 'string' ? manifest.packageManager.split('@')[0] : undefined;
+        if (declared === 'pnpm' || declared === 'npm' || declared === 'yarn' || declared === 'bun')
+            return declared;
+    }
+    catch { /* fall through to lockfiles */ }
+    for (const [file, name] of LOCKFILES) {
+        if (await access(join(projectRoot, file)).then(() => true, () => false))
+            return name;
+    }
+    return 'pnpm';
+}
+/**
+ * Maps the workflow's pnpm invocation (`add|remove [-w] [-D] <spec>`) and the gateway's
+ * `update [-w] [<name>…]` / `install [--frozen-lockfile]` to another manager.
+ * Unknown flags are refused rather than forwarded.
+ */
+export function translatePackageManagerArgs(manager, args) {
+    const [command, ...rest] = args;
+    if (command === 'install') {
+        const frozen = rest.includes('--frozen-lockfile');
+        if (rest.some(arg => arg !== '--frozen-lockfile'))
+            throw new Error('Unsupported package-manager flag');
+        if (!frozen)
+            return ['install'];
+        return manager === 'npm' ? ['ci'] : ['install', '--frozen-lockfile'];
+    }
+    if (command !== 'add' && command !== 'remove' && command !== 'update')
+        throw new Error(`Unsupported package-manager command: ${String(command)}`);
+    const workspace = rest.includes('-w');
+    const dev = rest.includes('-D');
+    const specs = rest.filter(arg => arg !== '-w' && arg !== '-D');
+    if (specs.some(spec => spec.startsWith('-')))
+        throw new Error('Unsupported package-manager flag');
+    if (command === 'update') {
+        if (dev)
+            throw new Error('Unsupported package-manager flag');
+        switch (manager) {
+            case 'pnpm': return ['update', ...(workspace ? ['-w'] : []), ...specs];
+            case 'npm': return ['update', ...specs];
+            case 'yarn': return ['upgrade', ...specs];
+            case 'bun': return ['update', ...specs];
+        }
+    }
+    if (command !== 'add' && command !== 'remove')
+        throw new Error('unreachable');
+    switch (manager) {
+        case 'pnpm': return [command, ...(workspace ? ['-w'] : []), ...(dev ? ['-D'] : []), ...specs];
+        case 'npm': return [command === 'add' ? 'install' : 'uninstall', ...(dev ? ['--save-dev'] : []), ...specs];
+        case 'yarn': return [command, ...(workspace ? ['-W'] : []), ...(dev ? ['-D'] : []), ...specs];
+        case 'bun': return [command, ...(dev ? ['-d'] : []), ...specs];
+    }
+}
+// cmd.exe metacharacters (same set as cross-spawn).
+const CMD_META = /([()\][%!^"`<>&|;, *?])/gu;
+/** Quotes one argument for `CommandLineToArgvW`, then escapes cmd metacharacters. */
+export function quoteWindowsCmdArgument(argument, doubleEscape) {
+    // Single linear pass (no backtracking regex): backslashes before a quote and trailing
+    // backslashes (they precede the closing quote) are doubled; quotes are escaped.
+    let body = '';
+    let backslashes = 0;
+    for (const char of argument) {
+        if (char === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (char === '"') {
+            body += '\\'.repeat(backslashes * 2) + '\\"';
+        }
+        else {
+            body += '\\'.repeat(backslashes) + char;
+        }
+        backslashes = 0;
+    }
+    body += '\\'.repeat(backslashes * 2);
+    const quoted = `"${body}"`.replace(CMD_META, '^$1');
+    // Package-manager shims (`pnpm.cmd`) re-expand `%*`, so metacharacters are parsed twice.
+    return doubleEscape ? quoted.replace(CMD_META, '^$1') : quoted;
+}
+function envValue(env, name) {
+    const key = Object.keys(env).find(item => item.toUpperCase() === name);
+    return key === undefined ? undefined : env[key];
+}
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves a package-manager command for `spawn` / `execFile` without a shell. POSIX: unchanged.
+ * Windows: `PATH` × `PATHEXT` lookup; an `.exe` / `.com` runs directly, a `.cmd` / `.bat` shim
+ * (or an unresolved name, assumed to be `<name>.cmd`) runs through `cmd.exe /d /s /c` with every
+ * argument quoted and its metacharacters escaped, since Node refuses to spawn batch files directly.
+ */
+export function resolveCommand(name, args, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== 'win32')
+        return Object.freeze({ command: name, args: Object.freeze([...args]) });
+    const env = options.env ?? process.env;
+    const isFile = options.isFile ?? defaultIsFile;
+    const extensions = (envValue(env, 'PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';').map(ext => ext.trim()).filter(Boolean);
+    const directories = (envValue(env, 'PATH') ?? '').split(';').map(dir => dir.trim().replace(/^"(.*)"$/u, '$1')).filter(Boolean);
+    let resolved;
+    if (/[\\/]/u.test(name) || win32.extname(name))
+        resolved = name;
+    else {
+        search: for (const directory of directories) {
+            for (const extension of extensions) {
+                const candidate = win32.join(directory, `${name}${extension.toLowerCase()}`);
+                if (isFile(candidate)) {
+                    resolved = candidate;
+                    break search;
+                }
+            }
+        }
+    }
+    const target = resolved ?? `${name}.cmd`;
+    const extension = win32.extname(target).toLowerCase();
+    if (extension === '.exe' || extension === '.com')
+        return Object.freeze({ command: target, args: Object.freeze([...args]) });
+    const doubleEscape = extension === '.cmd' || extension === '.bat';
+    const line = [win32.normalize(target).replace(CMD_META, '^$1'), ...args.map(arg => quoteWindowsCmdArgument(arg, doubleEscape))].join(' ');
+    return Object.freeze({
+        command: envValue(env, 'COMSPEC') ?? 'cmd.exe',
+        args: Object.freeze(['/d', '/s', '/c', `"${line}"`]),
+        windowsVerbatimArguments: true,
+    });
+}
+/**
+ * An `installDependencies` implementation for `PluginManagementWorkflow` that streams output.
+ * No shell: the command and every argument are passed as an argv array.
+ */
+export function createStreamingPackageManager(output, options = {}) {
+    const run = options.spawn ?? spawn;
+    return async (args, projectRoot) => {
+        const manager = options.manager ?? await detectPackageManager(projectRoot);
+        const argv = translatePackageManagerArgs(manager, args);
+        await new Promise((resolvePromise, reject) => {
+            const env = options.env ?? process.env;
+            const resolved = resolveCommand(manager, argv, { env, ...(options.platform ? { platform: options.platform } : {}) });
+            const child = run(resolved.command, [...resolved.args], {
+                cwd: projectRoot,
+                shell: false,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env,
+                windowsHide: true,
+                ...(resolved.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+            });
+            child.stdout?.setEncoding('utf8');
+            child.stderr?.setEncoding('utf8');
+            child.stdout?.on('data', (chunk) => output('stdout', chunk));
+            child.stderr?.on('data', (chunk) => output('stderr', chunk));
+            child.once('error', reject);
+            child.once('close', (code, signal) => {
+                if (code === 0)
+                    resolvePromise();
+                else
+                    reject(new Error(`${manager} ${argv[0]} exited with ${signal ?? `code ${code}`}`));
+            });
+        });
+    };
+}