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

package/lib/packages/service.js

@@ -0,0 +1,441 @@
+/**
+ * Dependency transactions of the management gateway (ADR 0054 §4): one at a time, the instance
+ * stopped while the package manager runs, and a failed install / uninstall / update rolled back
+ * to the captured project files and lockfile with the old instance started again.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { CONSOLE_PERMISSIONS } from '@zhin.js/console-protocol';
+import { createInstallAllowlist } from '../onboarding/allowlist.js';
+import { InstallOutputRelay, streamEvents } from '../onboarding/install.js';
+import { createStreamingPackageManager, detectPackageManager } from '../onboarding/package-manager.js';
+import { PluginDeclarationError, PluginManagementOperationError, PluginManagementWorkflow } from '../plugin-management/workflow.js';
+import { InstanceStartError } from '../supervisor/instance-supervisor.js';
+import { authorizePackages, gatewayPrincipalAllows } from './authorization.js';
+import { GatewayError } from './errors.js';
+import { ProjectFileSnapshot } from './snapshot.js';
+export const DEFAULT_PACKAGE_READY_TIMEOUT_MS = 60_000;
+export const DEFAULT_PACKAGE_STABLE_MS = 5_000;
+const LOCK_FILE = 'gateway-packages.lock';
+const LOG_TAIL_LINES = 50;
+const RUNNING_STATES = new Set(['running', 'starting', 'backoff']);
+/** Thrown inside a transaction when the instance does not come up; carries its log tail. */
+class InstanceStartFailure extends Error {
+    logTail;
+    constructor(message, logTail) {
+        super(message);
+        this.logTail = logTail;
+        this.name = 'InstanceStartFailure';
+    }
+}
+export class GatewayPackageService {
+    #root;
+    #options;
+    #relay = new InstallOutputRelay();
+    #listeners = new Set();
+    #packageManager;
+    #workflow;
+    #active;
+    constructor(options) {
+        this.#root = resolve(options.projectRoot);
+        this.#options = options;
+        const streaming = createStreamingPackageManager(this.#relay.output);
+        this.#packageManager = options.packageManager ?? ((args, root) => streaming(args, root));
+        this.#workflow = options.workflow ?? new PluginManagementWorkflow(this.#root, {
+            ...options.workflowOptions,
+            installDependencies: (args, root) => this.#packageManager(args, root, this.#relay.output),
+        });
+    }
+    /** Id of the running transaction, if any. */
+    get activeTransaction() { return this.#active; }
+    /** Progress of every transaction (for `gateway.packages.progress`); returns an unsubscribe function. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    async allowlist() {
+        return createInstallAllowlist({ market: await this.#options.marketCatalog?.() ?? [] });
+    }
+    /** Authorizes one action; throws {@link GatewayError} (deny by default). */
+    async authorize(principal, action, packages = []) {
+        if (action === 'list') {
+            if (!gatewayPrincipalAllows(principal, CONSOLE_PERMISSIONS.FEATURE_VIEW))
+                throw new GatewayError('forbidden', `需要 ${CONSOLE_PERMISSIONS.FEATURE_VIEW} 权限`);
+            await this.#options.authorize?.(principal, action, []);
+            return Object.freeze([]);
+        }
+        if (action === 'plan')
+            throw new GatewayError('invalid_input', 'plan 需要具体操作');
+        const authorized = authorizePackages(principal, action, packages, {
+            allowlist: await this.allowlist(),
+            ownerExists: await (this.#options.hasOwner?.() ?? true),
+        });
+        await this.#options.authorize?.(principal, action, authorized);
+        return authorized;
+    }
+    /** Declared dependencies with their installed versions. */
+    async list(principal) {
+        await this.authorize(principal, 'list');
+        const manifest = JSON.parse(await readFile(join(this.#root, 'package.json'), 'utf8'));
+        const allowlist = await this.allowlist();
+        const packages = [];
+        for (const dependencyType of ['dependencies', 'optionalDependencies', 'devDependencies']) {
+            const entries = manifest[dependencyType];
+            if (!entries || typeof entries !== 'object')
+                continue;
+            for (const [name, range] of Object.entries(entries)) {
+                if (typeof range !== 'string')
+                    continue;
+                const catalog = allowlist.get(name)?.kind;
+                packages.push(Object.freeze({ name, range, dependencyType, installedVersion: await this.#installedVersion(name), ...(catalog ? { catalog } : {}) }));
+            }
+        }
+        packages.sort((a, b) => a.name.localeCompare(b.name));
+        return Object.freeze({ packageManager: await detectPackageManager(this.#root), packages: Object.freeze(packages) });
+    }
+    /** What a transaction would do, after authorization; changes nothing. */
+    async plan(operation, packages, principal) {
+        const authorized = await this.authorize(principal, operation, packages);
+        const instanceState = this.#instanceState();
+        return Object.freeze({
+            operation,
+            packages: authorized,
+            all: packages === 'all',
+            packageManager: await detectPackageManager(this.#root),
+            instanceState,
+            restartsInstance: instanceState !== 'unmanaged' && RUNNING_STATES.has(instanceState),
+        });
+    }
+    install(packages, options) {
+        return this.#transaction('install', packages, options, async (ctx, authorized) => {
+            const needs = [];
+            for (const item of authorized) {
+                const need = configurationNeed(await ctx.workflow.install(item.spec, undefined, undefined, { enable: options.enable !== false }));
+                if (need)
+                    needs.push(need);
+            }
+            return needs.length ? { needsConfiguration: Object.freeze(needs) } : undefined;
+        });
+    }
+    /**
+     * `gateway.plugins.declare`: declares an installed plugin with its first configuration (schema
+     * validated before the instance is touched), then restarts the instance; a failed start rolls
+     * the configuration file back and starts the previous instance again.
+     */
+    async declare(request, options) {
+        const workflow = this.#workflow;
+        if (!workflow.planDeclaration || !workflow.declare)
+            throw new GatewayError('unavailable', '插件声明不可用');
+        if (typeof request.package !== 'string')
+            throw new GatewayError('invalid_input', 'package 必须是包名');
+        if (request.instanceKey !== undefined && typeof request.instanceKey !== 'string')
+            throw new GatewayError('invalid_input', 'instanceKey 必须是字符串');
+        const config = request.config ?? {};
+        const declareOptions = request.instanceKey === undefined ? {} : { instanceKey: request.instanceKey };
+        // Authorization first, then validation: nothing is stopped for a request that cannot succeed.
+        await this.authorize(options.principal, 'declare', [request.package]);
+        try {
+            await workflow.planDeclaration(request.package, config, declareOptions);
+        }
+        catch (error) {
+            throw declarationError(error);
+        }
+        return this.#transaction('declare', [request.package], options, async (ctx, authorized) => {
+            await ctx.workflow.declare(authorized[0].name, config, declareOptions);
+        });
+    }
+    uninstall(packages, options) {
+        return this.#transaction('uninstall', packages, options, async (ctx, authorized) => {
+            for (const item of authorized) {
+                if (options.removeDependency === false)
+                    await ctx.workflow.uninstall(item.name, undefined, undefined, { removeDependency: false });
+                else
+                    await ctx.workflow.uninstall(item.name);
+            }
+        });
+    }
+    /** Exact versions go through the workflow (verified); bare names / `'all'` run the manager's update. */
+    update(packages, options) {
+        return this.#transaction('update', packages, options, async (ctx, authorized) => {
+            if (packages === 'all') {
+                await ctx.run(['update']);
+                return;
+            }
+            const ranged = authorized.filter(item => item.version === undefined).map(item => item.name);
+            for (const item of authorized) {
+                if (item.version === undefined)
+                    continue;
+                const declared = await ctx.workflow.inspect(item.name).then(state => state.declared, () => false);
+                if (declared)
+                    await ctx.workflow.update(item.name, item.version);
+                else
+                    await ctx.workflow.install(item.spec, undefined, undefined, { enable: false });
+            }
+            if (ranged.length)
+                await ctx.run(['update', ...ranged]);
+        });
+    }
+    /** {@link install} / {@link uninstall} / {@link update} as an async iterator of its events. */
+    stream(operation, packages, options) {
+        return streamEvents(emit => {
+            const forward = { ...options, onEvent: (event) => { emit(event); options.onEvent?.(event); } };
+            if (operation === 'update')
+                return this.update(packages, forward);
+            if (packages === 'all')
+                return Promise.reject(new GatewayError('invalid_input', '只有 update 可以作用于全部依赖'));
+            return operation === 'install' ? this.install(packages, forward) : this.uninstall(packages, forward);
+        });
+    }
+    async #transaction(operation, packages, options, execute) {
+        if (this.#active)
+            throw new GatewayError('conflict', '另一个依赖事务正在进行，请等待它结束');
+        const id = randomUUID();
+        this.#active = id;
+        try {
+            const authorized = await this.authorize(options.principal, operation, packages);
+            const release = await this.#lock();
+            try {
+                await this.#options.beforeTransaction?.().catch(() => undefined);
+                return await this.#run(id, operation, authorized, options, execute);
+            }
+            finally {
+                await release();
+            }
+        }
+        finally {
+            this.#active = undefined;
+        }
+    }
+    async #run(id, operation, authorized, options, execute) {
+        const now = this.#options.now ?? Date.now;
+        const startedAt = now();
+        const emit = (event) => {
+            for (const listener of [options.onEvent, ...this.#listeners]) {
+                try {
+                    listener?.(event);
+                }
+                catch { /* listeners never break a transaction */ }
+            }
+        };
+        let phase = 'snapshot';
+        const enter = (next) => { phase = next; emit({ type: 'phase', id, phase: next }); };
+        const detach = this.#relay.attach((stream, chunk) => emit({ type: 'output', id, stream, chunk }));
+        const instance = this.#options.instance;
+        const before = this.#instanceState();
+        const wasRunning = instance !== undefined && RUNNING_STATES.has(instance.state);
+        const startAfter = instance !== undefined && (options.startInstance ?? wasRunning);
+        const run = (args) => this.#packageManager(args, this.#root, this.#relay.output);
+        // Rollback log tails only show what this transaction's instances printed.
+        const logMark = instance?.logs?.tail(1).at(-1)?.seq ?? -1;
+        // A declaration only writes the configuration file: no package manager, no reinstall on rollback.
+        const configOnly = operation === 'declare';
+        let extras = undefined;
+        let snapshot;
+        let mutated = false;
+        let status = 'succeeded';
+        let failedPhase;
+        let failure;
+        let rollbackFailure;
+        let logTail;
+        emit({ type: 'start', id, operation, packages: authorized });
+        try {
+            try {
+                enter('snapshot');
+                snapshot = await ProjectFileSnapshot.capture(this.#root);
+                if (instance && instance.state !== 'stopped') {
+                    enter('stop-instance');
+                    await instance.stop({ reason: `packages:${operation}` });
+                }
+                enter(configOnly ? 'configure' : 'package-manager');
+                mutated = true;
+                extras = await execute({ workflow: this.#workflow, run }, authorized);
+                if (startAfter) {
+                    enter('start-instance');
+                    await this.#startInstance(instance, logMark);
+                }
+            }
+            catch (error) {
+                failure = error;
+                failedPhase = phase;
+                if (error instanceof InstanceStartFailure)
+                    logTail = error.logTail;
+                status = 'rolledBack';
+                enter('rollback');
+                try {
+                    // Stopping also cancels a pending automatic restart of the broken instance.
+                    if (instance && instance.state !== 'stopped')
+                        await instance.stop({ reason: 'packages:rollback' });
+                    if (mutated && snapshot) {
+                        enter('restore-files');
+                        await snapshot.restore();
+                        if (!configOnly) {
+                            enter('reinstall');
+                            await run(snapshot.hasLockfile ? ['install', '--frozen-lockfile'] : ['install']);
+                        }
+                    }
+                    if (wasRunning) {
+                        enter('restart-instance');
+                        await this.#startInstance(instance, logMark);
+                    }
+                }
+                catch (error) {
+                    status = 'rollbackFailed';
+                    rollbackFailure = error;
+                }
+            }
+            enter('done');
+            const result = Object.freeze({
+                id,
+                operation,
+                packages: authorized,
+                ok: status === 'succeeded',
+                status,
+                ...(failedPhase ? { failedPhase } : {}),
+                ...(failure === undefined ? {} : { error: failureMessage(failure), ...declarationDetails(failure) }),
+                ...(rollbackFailure === undefined ? {} : { rollbackError: failureMessage(rollbackFailure) }),
+                ...(logTail?.length ? { logTail } : {}),
+                ...(status === 'succeeded' && extras?.needsConfiguration?.length ? { needsConfiguration: extras.needsConfiguration } : {}),
+                instance: Object.freeze({ before, after: this.#instanceState() }),
+                startedAt,
+                finishedAt: now(),
+            });
+            emit({ type: 'result', id, result });
+            return result;
+        }
+        finally {
+            detach();
+        }
+    }
+    /** Starts the instance, waits for `ready` within the timeout, then for the stability window. */
+    async #startInstance(instance, logMark) {
+        const configured = this.#options.readyTimeoutMs;
+        const readyTimeoutMs = (typeof configured === 'function' ? configured() : configured) ?? DEFAULT_PACKAGE_READY_TIMEOUT_MS;
+        const stableMs = this.#options.stableMs ?? DEFAULT_PACKAGE_STABLE_MS;
+        // With the log collector, only lines captured since the transaction started (the supervisor's
+        // failure tail also holds earlier runs); without it, the failure's own tail.
+        const tail = (fallback) => {
+            if (instance.logs) {
+                return Object.freeze(instance.logs.tail().filter(line => line.seq > logMark).slice(-LOG_TAIL_LINES).map(line => line.line));
+            }
+            const failureTail = fallback?.length ? fallback : instance.status().lastFailure?.logTail;
+            return Object.freeze([...(failureTail ?? [])]);
+        };
+        let timer;
+        const starting = instance.start();
+        starting.catch(() => undefined);
+        try {
+            await Promise.race([
+                starting,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`Instance did not become ready within ${readyTimeoutMs} ms`)), readyTimeoutMs);
+                }),
+            ]);
+        }
+        catch (error) {
+            throw new InstanceStartFailure(failureMessage(error), tail(error instanceof InstanceStartError ? error.failure.logTail : undefined));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (stableMs <= 0)
+            return;
+        await new Promise((resolvePromise, reject) => {
+            const onFailure = (failure) => {
+                cleanup();
+                reject(new InstanceStartFailure(`Instance failed after ready: ${failure.message}`, tail(failure.logTail)));
+            };
+            const cleanup = () => { clearTimeout(stable); instance.off('failure', onFailure); };
+            const stable = setTimeout(() => {
+                cleanup();
+                if (instance.state === 'running')
+                    resolvePromise();
+                else
+                    reject(new InstanceStartFailure(`Instance is ${instance.state} after ready`, tail()));
+            }, stableMs);
+            instance.on('failure', onFailure);
+        });
+    }
+    #instanceState() {
+        return this.#options.instance?.state ?? 'unmanaged';
+    }
+    async #installedVersion(name) {
+        try {
+            const manifest = JSON.parse(await readFile(join(this.#root, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'));
+            return manifest.name === name && typeof manifest.version === 'string' ? manifest.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Cross-process exclusion (CLI and gateway); separate from the workflow's own lock file. */
+    async #lock() {
+        const directory = join(this.#root, '.zhin');
+        await mkdir(directory, { recursive: true });
+        const file = join(directory, LOCK_FILE);
+        let handle;
+        try {
+            handle = await open(file, 'wx', 0o600);
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+                throw error;
+            let detail = '另一进程正在执行依赖事务';
+            try {
+                const previous = JSON.parse(await readFile(file, 'utf8'));
+                try {
+                    process.kill(previous.pid, 0);
+                }
+                catch (probe) {
+                    if (probe instanceof Error && 'code' in probe && probe.code === 'ESRCH')
+                        detail = `上一次依赖事务进程 ${previous.pid} 已退出；确认没有安装进程后删除 ${file} 再重试`;
+                }
+            }
+            catch { /* an incomplete lock is not safe to take over */ }
+            throw new GatewayError('conflict', detail, { cause: error });
+        }
+        const marker = JSON.stringify({ pid: process.pid, nonce: randomUUID() });
+        try {
+            await handle.writeFile(marker);
+        }
+        catch (error) {
+            await handle.close();
+            await rm(file, { force: true });
+            throw error;
+        }
+        return async () => {
+            await handle.close();
+            if (await readFile(file, 'utf8').catch(() => '') === marker)
+                await rm(file, { force: true });
+        };
+    }
+}
+/** Reads the configuration need a workflow `install` result reports, if any. */
+function configurationNeed(result) {
+    const need = result?.needsConfiguration;
+    if (!need || typeof need.name !== 'string' || typeof need.instanceKey !== 'string')
+        return undefined;
+    const strings = (value) => Object.freeze(Array.isArray(value) ? value.filter((item) => typeof item === 'string') : []);
+    return Object.freeze({ name: need.name, instanceKey: need.instanceKey, missing: strings(need.missing), missingEnv: strings(need.missingEnv) });
+}
+/** A refused declaration is the caller's input problem; anything else stays internal. */
+function declarationError(error) {
+    return error instanceof PluginDeclarationError
+        ? new GatewayError('invalid_input', error.message, { cause: error, details: { errors: error.errors, missingEnv: error.missingEnv } })
+        : error;
+}
+/** Structured feedback of a declaration refused inside the transaction (config changed after preflight). */
+function declarationDetails(error) {
+    const cause = error instanceof PluginManagementOperationError ? error.cause : error;
+    if (!(cause instanceof PluginDeclarationError))
+        return {};
+    return {
+        ...(cause.errors?.length ? { errors: cause.errors } : {}),
+        ...(cause.missingEnv?.length ? { missingEnv: cause.missingEnv } : {}),
+    };
+}
+/** The workflow's own error says files were not rolled back; the gateway does roll back, so report the cause. */
+function failureMessage(error) {
+    const cause = error instanceof PluginManagementOperationError ? error.cause : error;
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/lib/packages/snapshot.d.ts

@@ -0,0 +1,14 @@
+/** Lockfiles of every supported manager; all are captured so a manager switch is also undone. */
+export declare const PROJECT_LOCKFILES: readonly string[];
+/** Files a dependency transaction may change, captured before it starts. */
+export declare class ProjectFileSnapshot {
+    #private;
+    private constructor();
+    /** package.json, lockfiles, pnpm-workspace.yaml and the root config file. */
+    static capture(projectRoot: string, extra?: readonly string[]): Promise<ProjectFileSnapshot>;
+    /** Whether a lockfile existed, so the rollback can reinstall with a frozen lockfile. */
+    get hasLockfile(): boolean;
+    get paths(): readonly string[];
+    /** Writes back every changed file (atomically) and removes files created since the capture. */
+    restore(): Promise<void>;
+}

package/lib/packages/snapshot.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { loadProjectConfig } from '@zhin.js/scaffold-wizard';
+/** Lockfiles of every supported manager; all are captured so a manager switch is also undone. */
+export const PROJECT_LOCKFILES = Object.freeze([
+    'pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'bun.lock', 'bun.lockb',
+]);
+/** Files a dependency transaction may change, captured before it starts. */
+export class ProjectFileSnapshot {
+    #files;
+    constructor(files) { this.#files = files; }
+    /** package.json, lockfiles, pnpm-workspace.yaml and the root config file. */
+    static async capture(projectRoot, extra = []) {
+        const root = resolve(projectRoot);
+        const names = new Set(['package.json', ...PROJECT_LOCKFILES, 'pnpm-workspace.yaml', ...extra]);
+        const loaded = loadProjectConfig(root);
+        if (loaded.configPath)
+            names.add(loaded.configPath);
+        const files = [];
+        for (const name of names) {
+            const path = isAbsolute(name) ? name : join(root, name);
+            const inside = relative(root, path);
+            if (!inside || inside.startsWith('..') || isAbsolute(inside))
+                throw new Error(`Snapshot path escapes the project: ${name}`);
+            files.push(await captureFile(path));
+        }
+        return new ProjectFileSnapshot(Object.freeze(files));
+    }
+    /** Whether a lockfile existed, so the rollback can reinstall with a frozen lockfile. */
+    get hasLockfile() {
+        return this.#files.some(file => file.content !== null && PROJECT_LOCKFILES.includes(basename(file.path)));
+    }
+    get paths() { return this.#files.map(file => file.path); }
+    /** Writes back every changed file (atomically) and removes files created since the capture. */
+    async restore() {
+        for (const file of this.#files) {
+            const current = await readOptional(file.path);
+            if (file.content === null) {
+                if (current !== null)
+                    await rm(file.path, { force: true });
+                continue;
+            }
+            if (current !== null && current.equals(file.content))
+                continue;
+            const temporary = join(dirname(file.path), `.${basename(file.path)}.${randomUUID()}.restore`);
+            try {
+                await writeFile(temporary, file.content, { flag: 'wx', ...(file.mode === undefined ? {} : { mode: file.mode }) });
+                await rename(temporary, file.path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        }
+    }
+}
+async function captureFile(path) {
+    const content = await readOptional(path);
+    if (content === null)
+        return Object.freeze({ path, content: null });
+    const { mode } = await stat(path);
+    return Object.freeze({ path, content, mode: mode & 0o777 });
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}

package/lib/packages.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/packages` — dependency transactions and the gateway RPC dispatcher (ADR 0054 §4 / §5). */
+export * from './packages/index.js';

package/lib/packages.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/packages` — dependency transactions and the gateway RPC dispatcher (ADR 0054 §4 / §5). */
+export * from './packages/index.js';

package/lib/plugin-management/activity.d.ts

@@ -0,0 +1,6 @@
+/** Process composition guard: dependency watchers must not interrupt a mutation. */
+export declare class PluginManagementActivity {
+    #private;
+    get active(): boolean;
+    run<T>(operation: () => Promise<T>): Promise<T>;
+}

package/lib/plugin-management/activity.js

@@ -0,0 +1,14 @@
+/** Process composition guard: dependency watchers must not interrupt a mutation. */
+export class PluginManagementActivity {
+    #operations = 0;
+    get active() { return this.#operations > 0; }
+    async run(operation) {
+        this.#operations += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.#operations -= 1;
+        }
+    }
+}

package/lib/plugin-management/config-explanation.d.ts

@@ -0,0 +1,6 @@
+import type { ConsoleConfigExplanation } from '@zhin.js/console-protocol';
+type Projection = Pick<ConsoleConfigExplanation, 'projection' | 'reason' | 'fields'>;
+type Schema = Readonly<Record<string, unknown>>;
+/** Read-only metadata projection. Actual values never leave this function. */
+export declare function explainConfigFields(schema: Schema, input: unknown, current: unknown, committedInput: unknown): Projection;
+export {};