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

package/lib/onboarding/service.d.ts

@@ -0,0 +1,53 @@
+import type { ConsolePrincipal } from '@zhin.js/host-http';
+import { type PluginManagementOptions } from '../plugin-management/workflow.js';
+import { type InstallAllowlist, type InstallPrincipal, type MarketCatalogEntry } from './allowlist.js';
+import { InstallOutputRelay, type InstallEvent, type InstallListener, type InstallReport, type PackageInstallPort } from './install.js';
+import { OnboardingStateStore, type OnboardingState } from './state-store.js';
+export interface OnboardingStatus extends OnboardingState {
+    /** True until `complete()` ran. */
+    readonly required: boolean;
+}
+export interface OnboardingServiceOptions {
+    readonly projectRoot: string;
+    /** True once an enabled global owner exists (IAM). */
+    readonly hasOwner: () => boolean | Promise<boolean>;
+    /** Root config document used for auto-detection; defaults to the project's YAML/JSON config. */
+    readonly readConfig?: () => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+    readonly store?: OnboardingStateStore;
+    /** Plugin-market entries joining the install allowlist (re-read on every install). */
+    readonly marketCatalog?: () => readonly MarketCatalogEntry[] | Promise<readonly MarketCatalogEntry[]>;
+    /**
+     * Installation port; defaults to a `PluginManagementWorkflow` on the project root whose
+     * package manager streams through `relay`.
+     */
+    readonly installer?: PackageInstallPort;
+    /** Options for the default workflow (activity guard, snapshots, restart request). */
+    readonly workflow?: Omit<PluginManagementOptions, 'installDependencies'>;
+    readonly now?: () => Date;
+}
+export interface MarkStepOptions {
+    /** When given (Web / RPC), the step's credential rule is enforced; the CLI is trusted locally. */
+    readonly principal?: ConsolePrincipal;
+}
+/**
+ * The one onboarding service (ADR 0053 §2/§5): Console and `zhin setup` / `zhin console init`
+ * call the same methods. Transport-independent; routes / RPC wrap it.
+ */
+export declare class OnboardingService {
+    #private;
+    readonly relay: InstallOutputRelay;
+    constructor(options: OnboardingServiceOptions);
+    status(): Promise<OnboardingStatus>;
+    /** Marks database / ai / adapters as done or skipped. The owner step is derived from IAM. */
+    markStep(step: unknown, value: unknown, options?: MarkStepOptions): Promise<OnboardingStatus>;
+    /** Step 5: requires an owner; remaining pending optional steps stay pending (can be resumed later). */
+    complete(options?: MarkStepOptions): Promise<OnboardingStatus>;
+    /** The current install allowlist (official catalogs + market entries). */
+    allowlist(): Promise<InstallAllowlist>;
+    /** Authorizes then installs; progress goes to `onEvent`. Authorization errors throw before any work. */
+    installPackages(packages: readonly unknown[], principal: InstallPrincipal | undefined, onEvent?: InstallListener): Promise<InstallReport>;
+    /** Same as `installPackages`, as an async iterator of progress events (ends with `done`). */
+    streamInstall(packages: readonly unknown[], principal: InstallPrincipal | undefined): AsyncIterableIterator<InstallEvent> & {
+        readonly result: Promise<InstallReport>;
+    };
+}

package/lib/onboarding/service.js

@@ -0,0 +1,144 @@
+import { resolve } from 'node:path';
+import { CONSOLE_PERMISSIONS, grantsAllow } from '@zhin.js/console-protocol';
+import { loadProjectConfig } from '@zhin.js/scaffold-wizard';
+import { PluginManagementWorkflow } from '../plugin-management/workflow.js';
+import { authorizeInstall, createInstallAllowlist, } from './allowlist.js';
+import { OnboardingError } from './errors.js';
+import { InstallOutputRelay, installPackages, streamEvents, } from './install.js';
+import { createStreamingPackageManager } from './package-manager.js';
+import { applyDetection, detectConfiguredSteps, emptyOnboardingState, OnboardingStateStore, ONBOARDING_STEPS, } from './state-store.js';
+const OPTIONAL_STEPS = new Set(['database', 'ai', 'adapters']);
+/** Permissions a step needs besides `plugin.manage` (ADR 0053 §2). */
+const STEP_PERMISSIONS = Object.freeze({
+    ai: CONSOLE_PERMISSIONS.AGENT_CONFIGURE,
+    adapters: CONSOLE_PERMISSIONS.ENDPOINT_MANAGE,
+});
+/**
+ * The one onboarding service (ADR 0053 §2/§5): Console and `zhin setup` / `zhin console init`
+ * call the same methods. Transport-independent; routes / RPC wrap it.
+ */
+export class OnboardingService {
+    #options;
+    #store;
+    relay = new InstallOutputRelay();
+    #installer;
+    #queue = Promise.resolve();
+    // Installs queue separately so status reads are not blocked by a long install.
+    #installQueue = Promise.resolve();
+    constructor(options) {
+        this.#options = options;
+        this.#store = options.store ?? new OnboardingStateStore(options.projectRoot);
+        this.#installer = options.installer;
+    }
+    /** Serializes state read-modify-write cycles within this process. */
+    #exclusive(operation) {
+        const next = this.#queue.then(operation, operation);
+        this.#queue = next.catch(() => undefined);
+        return next;
+    }
+    #exclusiveInstall(operation) {
+        const next = this.#installQueue.then(operation, operation);
+        this.#installQueue = next.catch(() => undefined);
+        return next;
+    }
+    async #readConfig() {
+        if (this.#options.readConfig)
+            return this.#options.readConfig();
+        const loaded = loadProjectConfig(resolve(this.#options.projectRoot));
+        return loaded.status === 'loaded' ? loaded.config : {};
+    }
+    /** Stored state with auto-detection applied; persisted only when detection changed it. */
+    async #current() {
+        const stored = await this.#store.read();
+        const detected = new Set(detectConfiguredSteps(await this.#readConfig()));
+        if (await this.#options.hasOwner())
+            detected.add('owner');
+        const next = applyDetection(stored ?? emptyOnboardingState(), detected);
+        if (!stored || next !== stored)
+            await this.#store.write(next);
+        return next;
+    }
+    #view(state) {
+        return Object.freeze({ ...state, required: !state.completedAt });
+    }
+    status() {
+        return this.#exclusive(async () => this.#view(await this.#current()));
+    }
+    /** Marks database / ai / adapters as done or skipped. The owner step is derived from IAM. */
+    async markStep(step, value, options = {}) {
+        if (typeof step !== 'string' || !ONBOARDING_STEPS.includes(step)) {
+            throw new OnboardingError('invalid_input', '未知的引导步骤');
+        }
+        if (value !== 'done' && value !== 'skipped')
+            throw new OnboardingError('invalid_input', '步骤状态只能是 done 或 skipped');
+        if (!OPTIONAL_STEPS.has(step)) {
+            throw new OnboardingError('invalid_input', '所有者步骤在创建第一个所有者后自动完成，不能手动标记');
+        }
+        return this.#exclusive(async () => {
+            if (options.principal)
+                await this.#authorizeStep(step, options.principal);
+            const state = await this.#current();
+            const steps = { ...state.steps, [step]: value };
+            const next = Object.freeze({ ...state, steps: Object.freeze(steps) });
+            await this.#store.write(next);
+            return this.#view(next);
+        });
+    }
+    /** Step 5: requires an owner; remaining pending optional steps stay pending (can be resumed later). */
+    complete(options = {}) {
+        return this.#exclusive(async () => {
+            if (options.principal)
+                this.#requireManager(options.principal);
+            const state = await this.#current();
+            if (state.steps.owner !== 'done')
+                throw new OnboardingError('conflict', '请先创建所有者');
+            if (state.completedAt)
+                return this.#view(state);
+            const next = Object.freeze({ ...state, completedAt: (this.#options.now?.() ?? new Date()).toISOString() });
+            await this.#store.write(next);
+            return this.#view(next);
+        });
+    }
+    async #authorizeStep(step, principal) {
+        // Database (step 1) is a bootstrap-token step until an owner exists; later steps need an owner session.
+        if (step === 'database' && principal.kind === 'bootstrap') {
+            if (await this.#options.hasOwner())
+                throw new OnboardingError('forbidden', '已创建所有者：初始化令牌已失效');
+            return;
+        }
+        this.#requireManager(principal);
+        const extra = STEP_PERMISSIONS[step];
+        if (extra && (principal.kind === 'bootstrap' || !grantsAllow(principal.grants, extra))) {
+            throw new OnboardingError('forbidden', `需要 ${extra} 权限`);
+        }
+    }
+    #requireManager(principal) {
+        if (principal.kind === 'bootstrap' || !grantsAllow(principal.grants, CONSOLE_PERMISSIONS.PLUGIN_MANAGE)) {
+            throw new OnboardingError('forbidden', `需要 ${CONSOLE_PERMISSIONS.PLUGIN_MANAGE} 权限`);
+        }
+    }
+    /** The current install allowlist (official catalogs + market entries). */
+    async allowlist() {
+        return createInstallAllowlist({ market: await this.#options.marketCatalog?.() ?? [] });
+    }
+    #port() {
+        this.#installer ??= new PluginManagementWorkflow(this.#options.projectRoot, {
+            ...this.#options.workflow,
+            installDependencies: createStreamingPackageManager(this.relay.output),
+        });
+        return this.#installer;
+    }
+    /** Authorizes then installs; progress goes to `onEvent`. Authorization errors throw before any work. */
+    installPackages(packages, principal, onEvent) {
+        return this.#exclusiveInstall(async () => {
+            const authorized = authorizeInstall(packages, principal, await this.allowlist(), {
+                ownerExists: await this.#options.hasOwner(),
+            });
+            return installPackages(authorized, { port: this.#port(), relay: this.relay, ...(onEvent ? { onEvent } : {}) });
+        });
+    }
+    /** Same as `installPackages`, as an async iterator of progress events (ends with `done`). */
+    streamInstall(packages, principal) {
+        return streamEvents(emit => this.installPackages(packages, principal, emit));
+    }
+}

package/lib/onboarding/state-store.d.ts

@@ -0,0 +1,26 @@
+export declare const ONBOARDING_STEPS: readonly ["database", "owner", "ai", "adapters"];
+export type OnboardingStep = typeof ONBOARDING_STEPS[number];
+export type OnboardingStepStatus = 'pending' | 'done' | 'skipped';
+/** `.zhin/onboarding.json` (ADR 0053 §4). */
+export interface OnboardingState {
+    readonly version: 1;
+    readonly steps: Readonly<Record<OnboardingStep, OnboardingStepStatus>>;
+    /** ISO timestamp set by `complete()`. */
+    readonly completedAt?: string;
+}
+export declare const ONBOARDING_FILE: string;
+export declare function emptyOnboardingState(): OnboardingState;
+/** Strict parse; anything malformed returns undefined (treated as a fresh state). */
+export declare function parseOnboardingState(value: unknown): OnboardingState | undefined;
+/** Reads / atomically writes `.zhin/onboarding.json` (temp file + rename, mode 0600). */
+export declare class OnboardingStateStore {
+    readonly file: string;
+    constructor(projectRoot: string, file?: string);
+    /** The stored state, or undefined when the file is absent or invalid. */
+    read(): Promise<OnboardingState | undefined>;
+    write(state: OnboardingState): Promise<void>;
+}
+/** Steps an existing project has already configured (ADR 0053 §4 upgrade rule). */
+export declare function detectConfiguredSteps(config: Readonly<Record<string, unknown>>): ReadonlySet<OnboardingStep>;
+/** Pending steps become `done` when detected; `done` / `skipped` are never overridden. */
+export declare function applyDetection(state: OnboardingState, detected: ReadonlySet<OnboardingStep>): OnboardingState;

package/lib/onboarding/state-store.js

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { ADAPTERS, isAiEnabledInConfig } from '@zhin.js/scaffold-wizard';
+export const ONBOARDING_STEPS = Object.freeze(['database', 'owner', 'ai', 'adapters']);
+export const ONBOARDING_FILE = join('.zhin', 'onboarding.json');
+export function emptyOnboardingState() {
+    return Object.freeze({
+        version: 1,
+        steps: Object.freeze({ database: 'pending', owner: 'pending', ai: 'pending', adapters: 'pending' }),
+    });
+}
+const STATUSES = new Set(['pending', 'done', 'skipped']);
+/** Strict parse; anything malformed returns undefined (treated as a fresh state). */
+export function parseOnboardingState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (raw.version !== 1 || !raw.steps || typeof raw.steps !== 'object')
+        return undefined;
+    const steps = {};
+    for (const step of ONBOARDING_STEPS) {
+        const status = raw.steps[step];
+        steps[step] = typeof status === 'string' && STATUSES.has(status) ? status : 'pending';
+    }
+    const completedAt = typeof raw.completedAt === 'string' && !Number.isNaN(Date.parse(raw.completedAt)) ? raw.completedAt : undefined;
+    return Object.freeze({ version: 1, steps: Object.freeze(steps), ...(completedAt ? { completedAt } : {}) });
+}
+/** Reads / atomically writes `.zhin/onboarding.json` (temp file + rename, mode 0600). */
+export class OnboardingStateStore {
+    file;
+    constructor(projectRoot, file = ONBOARDING_FILE) {
+        this.file = resolve(projectRoot, file);
+    }
+    /** The stored state, or undefined when the file is absent or invalid. */
+    async read() {
+        let source;
+        try {
+            source = await readFile(this.file, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        try {
+            return parseOnboardingState(JSON.parse(source));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async write(state) {
+        const parsed = parseOnboardingState(state);
+        if (!parsed)
+            throw new Error('Invalid onboarding state');
+        await mkdir(dirname(this.file), { recursive: true });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+            await chmod(temporary, 0o600);
+            await rename(temporary, this.file);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+}
+const ADAPTER_PACKAGES = new Set(ADAPTERS.map(adapter => adapter.package));
+/** Steps an existing project has already configured (ADR 0053 §4 upgrade rule). */
+export function detectConfiguredSteps(config) {
+    const detected = new Set();
+    const database = config.database;
+    if (database && typeof database === 'object' && !Array.isArray(database)
+        && typeof database.dialect === 'string')
+        detected.add('database');
+    const plugins = config.plugins;
+    const packages = plugins && typeof plugins === 'object' && !Array.isArray(plugins)
+        ? Object.values(plugins) : [];
+    if (packages.some(value => typeof value === 'string' && ADAPTER_PACKAGES.has(value)))
+        detected.add('adapters');
+    if (isAiEnabledInConfig(config))
+        detected.add('ai');
+    return detected;
+}
+/** Pending steps become `done` when detected; `done` / `skipped` are never overridden. */
+export function applyDetection(state, detected) {
+    let changed = false;
+    const steps = { ...state.steps };
+    for (const step of detected) {
+        if (steps[step] === 'pending') {
+            steps[step] = 'done';
+            changed = true;
+        }
+    }
+    return changed ? Object.freeze({ ...state, steps: Object.freeze(steps) }) : state;
+}

package/lib/onboarding.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/onboarding` — Console onboarding state, install allowlist and installs (ADR 0053). */
+export * from './onboarding/index.js';

package/lib/onboarding.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/onboarding` — Console onboarding state, install allowlist and installs (ADR 0053). */
+export * from './onboarding/index.js';

package/lib/packages/authorization.d.ts

@@ -0,0 +1,23 @@
+import type { ConsolePrincipal } from '@zhin.js/host-http';
+import { type GatewayAuthorizedPackage, type GatewayTransactionOperation } from '@zhin.js/console-protocol';
+import { type InstallAllowlist } from '../onboarding/allowlist.js';
+/** A Console principal, or `'local'` for the CLI on the local control socket (owner, ADR 0054 §6). */
+export type GatewayPrincipal = ConsolePrincipal | 'local';
+export type GatewayPackageAction = 'list' | 'plan' | GatewayTransactionOperation;
+export interface AuthorizePackagesOptions {
+    readonly allowlist: InstallAllowlist;
+    /** True once an owner exists: the bootstrap token is refused afterwards. */
+    readonly ownerExists: boolean;
+}
+/** A global `owner` binding, or the local control socket. */
+export declare function isGatewayOwner(principal: GatewayPrincipal | undefined): boolean;
+/** Whether the principal holds a global Console permission (bootstrap: only an open, local Host). */
+export declare function gatewayPrincipalAllows(principal: GatewayPrincipal | undefined, permission: string): boolean;
+/**
+ * Authorizes one package transaction (deny by default):
+ * - bootstrap token: `install` of allowlisted database drivers only, before the first owner (ADR 0053 §3);
+ * - `plugin.manage` without a global owner binding: allowlisted packages only (ADR 0053 §3);
+ * - owners and the local socket: any npm package by name, with the same strict spec rules.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`.
+ */
+export declare function authorizePackages(principal: GatewayPrincipal | undefined, operation: GatewayTransactionOperation, requests: readonly unknown[] | 'all', options: AuthorizePackagesOptions): readonly GatewayAuthorizedPackage[];

package/lib/packages/authorization.js

@@ -0,0 +1,109 @@
+import { CONSOLE_PERMISSIONS, grantsAllow, } from '@zhin.js/console-protocol';
+import { authorizeInstall, parseInstallRequest } from '../onboarding/allowlist.js';
+import { OnboardingError } from '../onboarding/errors.js';
+import { GatewayError } from './errors.js';
+const MAX_PACKAGES = 32;
+const EXACT_VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}(?:-[0-9A-Za-z][0-9A-Za-z.-]{0,63})?$/u;
+/** A global `owner` binding, or the local control socket. */
+export function isGatewayOwner(principal) {
+    if (principal === 'local')
+        return true;
+    if (!principal || principal.kind === 'bootstrap')
+        return false;
+    return principal.grants.some(grant => grant.role === 'owner' && grant.scope.kind === 'global');
+}
+/** Whether the principal holds a global Console permission (bootstrap: only an open, local Host). */
+export function gatewayPrincipalAllows(principal, permission) {
+    if (principal === 'local')
+        return true;
+    if (!principal)
+        return false;
+    if (principal.kind === 'bootstrap')
+        return principal.open;
+    return grantsAllow(principal.grants, permission);
+}
+function rethrow(error) {
+    if (error instanceof OnboardingError)
+        throw new GatewayError(error.code, error.message, { cause: error });
+    throw error;
+}
+/**
+ * Authorizes one package transaction (deny by default):
+ * - bootstrap token: `install` of allowlisted database drivers only, before the first owner (ADR 0053 §3);
+ * - `plugin.manage` without a global owner binding: allowlisted packages only (ADR 0053 §3);
+ * - owners and the local socket: any npm package by name, with the same strict spec rules.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`.
+ */
+export function authorizePackages(principal, operation, requests, options) {
+    if (!principal)
+        throw new GatewayError('forbidden', '未登录');
+    if (principal !== 'local' && principal.kind === 'bootstrap') {
+        if (operation !== 'install' || requests === 'all')
+            throw new GatewayError('forbidden', '初始化令牌只能安装数据库驱动');
+        try {
+            return Object.freeze(authorizeInstall(requests, principal, options.allowlist, { ownerExists: options.ownerExists })
+                .map(item => Object.freeze({ name: item.name, ...(item.version === undefined ? {} : { version: item.version }), spec: item.spec, source: item.kind })));
+        }
+        catch (error) {
+            rethrow(error);
+        }
+    }
+    if (!gatewayPrincipalAllows(principal, CONSOLE_PERMISSIONS.PLUGIN_MANAGE)) {
+        throw new GatewayError('forbidden', `需要 ${CONSOLE_PERMISSIONS.PLUGIN_MANAGE} 权限`);
+    }
+    const owner = isGatewayOwner(principal);
+    if (requests === 'all') {
+        if (operation !== 'update')
+            throw new GatewayError('invalid_input', '只有 update 可以作用于全部依赖');
+        if (!owner)
+            throw new GatewayError('forbidden', '只有所有者可以更新全部依赖');
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(requests) || requests.length === 0 || requests.length > MAX_PACKAGES) {
+        throw new GatewayError('invalid_input', `请提供 1–${MAX_PACKAGES} 个包`);
+    }
+    if (operation === 'install' && !owner) {
+        try {
+            return Object.freeze(authorizeInstall(requests, principal, options.allowlist)
+                .map(item => Object.freeze({ name: item.name, ...(item.version === undefined ? {} : { version: item.version }), spec: item.spec, source: item.kind })));
+        }
+        catch (error) {
+            rethrow(error);
+        }
+    }
+    const seen = new Set();
+    const authorized = [];
+    for (const request of requests) {
+        let parsed;
+        try {
+            parsed = parseInstallRequest(request);
+        }
+        catch (error) {
+            rethrow(error);
+        }
+        const { name } = parsed;
+        if (seen.has(name))
+            throw new GatewayError('invalid_input', `重复的包：${name}`);
+        seen.add(name);
+        const entry = options.allowlist.get(name);
+        if (!owner && !entry)
+            throw new GatewayError('forbidden', `${name} 不在可管理目录中；只有所有者可以管理任意 npm 包`);
+        let version = parsed.version;
+        if (operation === 'uninstall' && version !== undefined)
+            throw new GatewayError('invalid_input', `卸载 ${name} 时不能指定版本`);
+        if (operation === 'declare' && version !== undefined)
+            throw new GatewayError('invalid_input', `声明 ${name} 时不能指定版本`);
+        if (operation === 'update' && version !== undefined && !EXACT_VERSION.test(version)) {
+            throw new GatewayError('invalid_input', `${name} 的更新版本必须是精确 semver 版本`);
+        }
+        if (operation === 'install')
+            version ??= entry?.defaultVersion;
+        authorized.push(Object.freeze({
+            name,
+            ...(version === undefined ? {} : { version }),
+            spec: version === undefined ? name : `${name}@${version}`,
+            source: entry?.kind ?? 'npm',
+        }));
+    }
+    return Object.freeze(authorized);
+}

package/lib/packages/errors.d.ts

@@ -0,0 +1,11 @@
+import type { GatewayRpcErrorCode, GatewayRpcErrorDetails } from '@zhin.js/console-protocol';
+/** Transport-independent gateway error raised before a transaction does any work. */
+export declare class GatewayError extends Error {
+    readonly code: GatewayRpcErrorCode;
+    readonly status: number;
+    /** Structured details sent with the reply (only non-empty fields). */
+    readonly details?: GatewayRpcErrorDetails;
+    constructor(code: GatewayRpcErrorCode, message: string, options?: ErrorOptions & {
+        readonly details?: GatewayRpcErrorDetails;
+    });
+}

package/lib/packages/errors.js

@@ -0,0 +1,26 @@
+const STATUS = {
+    invalid_input: 400,
+    forbidden: 403,
+    unmapped: 403,
+    conflict: 409,
+    unavailable: 503,
+    internal: 500,
+};
+/** Transport-independent gateway error raised before a transaction does any work. */
+export class GatewayError extends Error {
+    code;
+    status;
+    /** Structured details sent with the reply (only non-empty fields). */
+    details;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'GatewayError';
+        this.status = STATUS[code];
+        const details = options?.details;
+        const errors = details?.errors?.length ? Object.freeze(details.errors.map(item => Object.freeze({ path: item.path, message: item.message }))) : undefined;
+        const missingEnv = details?.missingEnv?.length ? Object.freeze([...details.missingEnv]) : undefined;
+        if (errors || missingEnv)
+            this.details = Object.freeze({ ...(errors ? { errors } : {}), ...(missingEnv ? { missingEnv } : {}) });
+    }
+}

package/lib/packages/index.d.ts

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './authorization.js';
+export * from './snapshot.js';
+export * from './service.js';
+export * from './rpc.js';

package/lib/packages/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './authorization.js';
+export * from './snapshot.js';
+export * from './service.js';
+export * from './rpc.js';

package/lib/packages/rpc.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transport-independent dispatcher for the gateway's own RPC (`gateway.packages.*`,
+ * `gateway.instance.*`, ADR 0054 §4 / §5). The HTTP server maps envelopes onto it; the permission
+ * map in `@zhin.js/console-protocol` is checked here, then each service applies its own rules.
+ */
+import { type GatewayInstanceStatus, type GatewayRpcRequest, type GatewayRpcResponse, type GatewayRpcType } from '@zhin.js/console-protocol';
+import type { InstanceStatus, InstanceStopOptions } from '../supervisor/instance-supervisor.js';
+import type { InstanceLogLine } from '../supervisor/instance-logs.js';
+import { type GatewayPrincipal } from './authorization.js';
+import type { GatewayPackageService } from './service.js';
+/** The part of `InstanceSupervisor` the lifecycle RPC uses. */
+export interface GatewayRpcInstance {
+    start(): Promise<void>;
+    stop(options?: InstanceStopOptions): Promise<void>;
+    restart(options?: Omit<InstanceStopOptions, 'force'>): Promise<void>;
+    status(): InstanceStatus;
+    readonly logs: {
+        tail(limit?: number): readonly InstanceLogLine[];
+    };
+}
+export interface GatewayRpcDependencies {
+    readonly packages?: GatewayPackageService;
+    readonly instance?: GatewayRpcInstance;
+}
+export type GatewayRpcDispatcher = (request: GatewayRpcRequest, principal: GatewayPrincipal | undefined) => Promise<GatewayRpcResponse>;
+export declare function isGatewayRpcType(type: unknown): type is GatewayRpcType;
+export declare function createGatewayRpcDispatcher(dependencies: GatewayRpcDependencies): GatewayRpcDispatcher;
+/** Dispatches one gateway RPC; never throws (errors become `{ ok: false }`). */
+export declare function dispatchGatewayRpc(request: GatewayRpcRequest, principal: GatewayPrincipal | undefined, dependencies: GatewayRpcDependencies): Promise<GatewayRpcResponse>;
+export declare function instanceStatus(status: InstanceStatus): GatewayInstanceStatus;