@zhin.js/gateway 1.1.1 → 1.1.2

package/lib/http/plugin-switch-rpc.js

@@ -0,0 +1,214 @@
+/**
+ * The Console's global plugin switch, answered by the gateway (ADR 0054 §4, ADR 0050 §4):
+ * `plugin:set-enabled` and `feature.set-enabled` with `level: 'global'` both write
+ * `disable_plugins`, which is plugin lifecycle rather than a feature switch. The gateway
+ * intercepts them on `POST {base}/console/request` before anything is forwarded, authorizes them
+ * with `plugin.manage` (the shared permission map refines `feature.set-enabled` by level), and
+ * runs the enable / disable transaction of {@link GatewayPackageService.setEnabled}: stop the
+ * instance → write `disable_plugins` → start it, restoring the file and the old instance on
+ * failure. `feature.set-enabled` below the global level is forwarded to the instance untouched.
+ *
+ * Replies keep the shapes the instance used to send, so a published Console keeps working:
+ * - `plugin:set-enabled`: `{ success, instanceKey, enabled, disabled, restartRequired, message }`;
+ * - `feature.set-enabled`: `ConsoleFeatureWriteResult` (`saved` / `unchanged`) with the
+ *   configuration revision after the write and the override warnings of the new state.
+ * Both add `transaction` (the gateway transaction result). A failed or rolled-back transaction
+ * answers the RPC's error envelope (`success: false`, `code`, `error`) with `transaction`.
+ */
+import { join } from 'node:path';
+import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
+import { FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME, FEATURE_OVERRIDES_KEY } from '@zhin.js/plugin-runtime';
+import { collectFeatureOverrideWarnings, createConfigDocument } from '@zhin.js/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { GatewayError } from '../packages/errors.js';
+import { findConfigFile } from '../project/config-file.js';
+const logger = getLogger('gateway');
+/** Top-level plugin instance alias (the global switch only applies to top-level instances). */
+const INSTANCE_KEY = /^[a-z0-9][a-z0-9-]*$/u;
+/** Whether the gateway answers this Console RPC message itself (the global plugin switch). */
+export function isGatewayPluginSwitch(message) {
+    return message.type === PLUGIN_RPC.SET_ENABLED || isGlobalFeatureSwitch(message);
+}
+export function createGatewayPluginSwitchRpc(options) {
+    const readConfig = options.readConfig ?? (async () => {
+        const file = join(options.projectRoot, findConfigFile(options.projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME);
+        const { revision, document } = await createConfigDocument(file).read();
+        return { revision, document: document };
+    });
+    return Object.freeze({
+        owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
+        claims: isGatewayPluginSwitch,
+        async handle(message, context, registry) {
+            const noStore = { 'cache-control': 'no-store' };
+            const type = String(message.type ?? '');
+            const requestId = message.requestId;
+            const principal = context.principal;
+            if (!principal) {
+                return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
+            }
+            // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
+            const decision = authorizeConsoleRpc(principal, message);
+            const audit = (outcome) => {
+                try {
+                    registry.accessProvider?.audit?.({
+                        actor: auditActor(principal),
+                        action: `rpc:${type}`.slice(0, 256),
+                        ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
+                        outcome,
+                        detail: rpcAuditDetail(message),
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            };
+            if (!decision.allowed) {
+                audit('denied');
+                return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
+            }
+            const reply = type === PLUGIN_RPC.SET_ENABLED
+                ? await setPluginEnabled(message, principal, options, readConfig)
+                : await setFeatureGlobal(message, principal, options, readConfig);
+            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error');
+            return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
+        },
+    });
+}
+/** `plugin:set-enabled` `{ instanceKey, enabled }` (top-level fields, as the Console sends them). */
+async function setPluginEnabled(message, principal, options, readConfig) {
+    const type = PLUGIN_RPC.SET_ENABLED;
+    const instanceKey = typeof message.instanceKey === 'string' ? message.instanceKey.trim() : '';
+    const enabled = message.enabled;
+    if (!instanceKey || typeof enabled !== 'boolean')
+        return error(400, 'invalid_input', 'instanceKey and boolean enabled are required', type);
+    const outcome = await runSwitch(instanceKey, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch(() => undefined);
+    const key = result.plugin?.instanceKey ?? instanceKey;
+    const changed = result.plugin?.changed === true;
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: {
+                success: true,
+                instanceKey: key,
+                enabled,
+                disabled: disabledPlugins(config?.document),
+                // The gateway restarted the instance for a change (it already is back): the Console re-syncs.
+                restartRequired: changed,
+                message: switchMessage(key, enabled, changed),
+                transaction: result,
+            },
+        },
+    };
+}
+/** `feature.set-enabled` with `level: 'global'`, payload in `data` (or on the message). */
+async function setFeatureGlobal(message, principal, options, readConfig) {
+    const type = FEATURE_RPC.SET_ENABLED;
+    const data = message.data;
+    const input = (data && typeof data === 'object' && !Array.isArray(data) ? data : message);
+    const plugin = input.plugin;
+    if (typeof plugin !== 'string' || !plugin)
+        return error(400, undefined, '缺少 plugin', type);
+    if (input.key !== undefined && input.key !== '')
+        return error(400, undefined, 'global 层不需要 key', type);
+    if (!INSTANCE_KEY.test(plugin)) {
+        return error(400, undefined, plugin.includes('/') ? '全局开关只适用于顶层插件实例' : 'plugin 必须是插件实例别名', type);
+    }
+    if (typeof input.enabled !== 'boolean')
+        return error(400, undefined, 'enabled 必须是布尔值', type);
+    const enabled = input.enabled;
+    const outcome = await runSwitch(plugin, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch((failure) => {
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_config_read_failed', error: failure instanceof Error ? failure.message : String(failure) }));
+        return undefined;
+    });
+    const revision = config?.revision ?? '';
+    const changed = result.plugin?.changed === true;
+    if (!changed) {
+        return { status: 200, body: { success: true, type, data: Object.freeze({ status: 'unchanged', revision, warnings: Object.freeze([]), transaction: result }) } };
+    }
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: Object.freeze({
+                status: 'saved',
+                revision,
+                // The instance was restarted by the gateway transaction (it already is back).
+                restartRequired: true,
+                warnings: config ? overrideWarnings(config.document, plugin) : Object.freeze([]),
+                message: switchMessage(plugin, enabled, true),
+                transaction: result,
+            }),
+        },
+    };
+}
+/** Runs the transaction; a refusal or a failed / rolled-back transaction becomes an error reply. */
+async function runSwitch(plugin, enabled, principal, options, type) {
+    if (!options.packages)
+        return { reply: error(503, 'unavailable', '插件启停不可用：网关未管理依赖', type) };
+    let result;
+    try {
+        result = await options.packages.setEnabled({ plugin }, enabled, { principal });
+    }
+    catch (failure) {
+        if (failure instanceof GatewayError) {
+            return {
+                reply: error(failure.status, failure.code, failure.message, type, {
+                    ...(failure.details?.errors ? { errors: failure.details.errors } : {}),
+                    ...(failure.details?.missingEnv ? { missingEnv: failure.details.missingEnv } : {}),
+                }),
+            };
+        }
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_failed', plugin, error: failure instanceof Error ? failure.message : String(failure) }));
+        return { reply: error(500, 'internal', '插件启停失败', type) };
+    }
+    if (result.ok)
+        return { result };
+    const action = enabled ? '启用' : '停用';
+    const text = result.status === 'rollbackFailed'
+        ? `${action} ${plugin} 失败，且回滚未完成：${result.rollbackError ?? '未知错误'}（原因：${result.error ?? '未知错误'}）`
+        : `${action} ${plugin} 失败，已回滚：${result.error ?? '未知错误'}`;
+    return {
+        reply: error(500, result.status === 'rollbackFailed' ? 'rollback_failed' : 'transaction_failed', text, type, {
+            transaction: result,
+            ...(result.errors?.length ? { errors: result.errors } : {}),
+            ...(result.missingEnv?.length ? { missingEnv: result.missingEnv } : {}),
+        }),
+    };
+}
+function error(status, code, message, type, extra = {}) {
+    return { status, body: { success: false, ...(code ? { code } : {}), error: message, type, ...extra } };
+}
+function switchMessage(plugin, enabled, changed) {
+    const action = enabled ? '启用' : '停用';
+    return changed ? `${plugin} 已${action}，实例已由管理网关重启` : `${plugin} 已处于${action}状态`;
+}
+function disabledPlugins(document) {
+    const list = document?.disable_plugins;
+    return Object.freeze(Array.isArray(list) ? list.filter((item) => typeof item === 'string') : []);
+}
+/** The global plugin switch's warnings about the plugin's own overrides (as the instance computed them). */
+function overrideWarnings(document, plugin) {
+    const block = document[plugin];
+    const overrides = block && typeof block === 'object' && !Array.isArray(block) ? block[FEATURE_OVERRIDES_KEY] : undefined;
+    if (overrides === undefined)
+        return Object.freeze([]);
+    try {
+        const enabled = !disabledPlugins(document).includes(plugin);
+        return Object.freeze(collectFeatureOverrideWarnings(document, plugin, overrides, enabled)
+            .map(({ code, path, message }) => Object.freeze({ code, path, message })));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}

package/lib/http/start-gateway.js

@@ -12,6 +12,7 @@ import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
 import { GatewayPackageService } from '../packages/service.js';
 import { createGatewayRpcDispatcher } from '../packages/rpc.js';
 import { createGatewayConsoleRpc } from './console-rpc.js';
+import { createGatewayPluginSwitchRpc } from './plugin-switch-rpc.js';
 import { startGatewayConsole } from './gateway-console.js';
 import { registerGatewayEventRoutes } from './gateway-events.js';
 import { GatewayHttpServer } from './gateway-http-server.js';
@@ -114,6 +115,9 @@ export async function startGateway(options) {
         consoleRpc: createGatewayConsoleRpc(rpc),
     });
     registry = server.tokenRegistry;
+    // The Console's global plugin switch is a gateway transaction (stop → write → start, rollback);
+    // registered even without package management so it is never forwarded to the instance.
+    const disposePluginSwitch = server.useConsoleRpc(createGatewayPluginSwitchRpc({ projectRoot: options.projectRoot, packages }));
     const disposeEvents = registerGatewayEventRoutes({
         server,
         ...(packages ? { packages } : {}),
@@ -146,6 +150,7 @@ export async function startGateway(options) {
     }
     catch (error) {
         disposeEvents();
+        disposePluginSwitch();
         await gatewayConsole?.close().catch(() => undefined);
         await transport.dispose?.();
         supervisor.dispose();
@@ -179,6 +184,7 @@ export async function startGateway(options) {
                 }
                 finally {
                     disposeEvents();
+                    disposePluginSwitch();
                     await gatewayConsole?.close().catch(() => undefined);
                     supervisor.dispose();
                     await server.close();

package/lib/local/handler.js

@@ -53,7 +53,7 @@ async function handleHttp(options, data) {
     const result = { status: response.status, headers, body: text };
     return { ok: true, data: result };
 }
-const STREAMED = new Set([GATEWAY_RPC.INSTALL, GATEWAY_RPC.UNINSTALL, GATEWAY_RPC.UPDATE, GATEWAY_RPC.DECLARE]);
+const STREAMED = new Set([GATEWAY_RPC.INSTALL, GATEWAY_RPC.UNINSTALL, GATEWAY_RPC.UPDATE, GATEWAY_RPC.DECLARE, GATEWAY_RPC.ENABLE, GATEWAY_RPC.DISABLE]);
 export function createLocalRpcHandler(options) {
     return async (request, emit) => {
         if (request.type === LOCAL_GATEWAY_RPC.INFO)

package/lib/packages/authorization.d.ts

@@ -18,6 +18,7 @@ export declare function gatewayPrincipalAllows(principal: GatewayPrincipal | und
  * - 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`.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`;
+ * `enable` / `disable` take the declared package (a bare name, or a `./` local plugin for owners).
  */
 export declare function authorizePackages(principal: GatewayPrincipal | undefined, operation: GatewayTransactionOperation, requests: readonly unknown[] | 'all', options: AuthorizePackagesOptions): readonly GatewayAuthorizedPackage[];

package/lib/packages/authorization.js

@@ -3,6 +3,8 @@ import { authorizeInstall, parseInstallRequest } from '../onboarding/allowlist.j
 import { OnboardingError } from '../onboarding/errors.js';
 import { GatewayError } from './errors.js';
 const MAX_PACKAGES = 32;
+/** A project-local plugin package reference as declared in `plugins.<instanceKey>`. */
+const LOCAL_PACKAGE = /^\.\/[A-Za-z0-9._@-]+(?:\/[A-Za-z0-9._@-]+)*$/u;
 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) {
@@ -32,7 +34,8 @@ function rethrow(error) {
  * - 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`.
+ * `'all'` (update every dependency) is owner-only. `declare` takes bare names, like `uninstall`;
+ * `enable` / `disable` take the declared package (a bare name, or a `./` local plugin for owners).
  */
 export function authorizePackages(principal, operation, requests, options) {
     if (!principal)
@@ -73,7 +76,21 @@ export function authorizePackages(principal, operation, requests, options) {
     }
     const seen = new Set();
     const authorized = [];
+    const toggle = operation === 'enable' || operation === 'disable';
     for (const request of requests) {
+        // enable / disable name the declared package, which may be a project-local plugin directory.
+        if (toggle && typeof request === 'string' && request.startsWith('./')) {
+            if (!LOCAL_PACKAGE.test(request) || request.split('/').slice(1).some(part => part === '.' || part === '..')) {
+                throw new GatewayError('invalid_input', `本地插件路径无效：${request.slice(0, 64)}`);
+            }
+            if (!owner)
+                throw new GatewayError('forbidden', '只有所有者可以启停本地插件');
+            if (seen.has(request))
+                throw new GatewayError('invalid_input', `重复的包：${request}`);
+            seen.add(request);
+            authorized.push(Object.freeze({ name: request, spec: request, source: 'local' }));
+            continue;
+        }
         let parsed;
         try {
             parsed = parseInstallRequest(request);
@@ -93,6 +110,8 @@ export function authorizePackages(principal, operation, requests, options) {
             throw new GatewayError('invalid_input', `卸载 ${name} 时不能指定版本`);
         if (operation === 'declare' && version !== undefined)
             throw new GatewayError('invalid_input', `声明 ${name} 时不能指定版本`);
+        if (toggle && version !== undefined)
+            throw new GatewayError('invalid_input', `启停 ${name} 时不能指定版本`);
         if (operation === 'update' && version !== undefined && !EXACT_VERSION.test(version)) {
             throw new GatewayError('invalid_input', `${name} 的更新版本必须是精确 semver 版本`);
         }

package/lib/packages/rpc.js

@@ -64,6 +64,11 @@ async function handle(type, data, principal, deps) {
                 principal, ...optionalBoolean(data, 'startInstance'),
             });
         }
+        case 'gateway.plugins.enable':
+        case 'gateway.plugins.disable':
+            return packagesOf(deps).setEnabled({ plugin: data.plugin }, type === 'gateway.plugins.enable', {
+                principal, ...optionalBoolean(data, 'startInstance'),
+            });
         case 'gateway.instance.status': return instanceStatus(instanceOf(deps).status());
         case 'gateway.instance.logs': {
             const lines = data.lines === undefined ? DEFAULT_LOG_LINES : data.lines;

package/lib/packages/service.d.ts

@@ -36,6 +36,13 @@ export interface PackageWorkflowPort {
     declare?(request: string, config?: unknown, options?: {
         readonly instanceKey?: string;
     }): Promise<unknown>;
+    /** Validates an enable / disable without writing (throws `PluginEnablementError`). */
+    planSetEnabled?(request: string, enabled: boolean): Promise<{
+        readonly packageName: string;
+        readonly instanceKey: string;
+        readonly changed: boolean;
+    }>;
+    setEnabled?(request: string, enabled: boolean): Promise<unknown>;
 }
 /**
  * Runs the package manager with pnpm-style args (`add|remove|update|install …`), streaming output.
@@ -88,6 +95,10 @@ export interface GatewayDeclareRequest {
     readonly instanceKey?: unknown;
     readonly config?: unknown;
 }
+export interface GatewaySetEnabledRequest {
+    /** A declared instance key, or the package name of a package declared exactly once. */
+    readonly plugin: unknown;
+}
 export declare const DEFAULT_PACKAGE_READY_TIMEOUT_MS = 60000;
 export declare const DEFAULT_PACKAGE_STABLE_MS = 5000;
 export declare class GatewayPackageService {
@@ -111,6 +122,13 @@ export declare class GatewayPackageService {
      * the configuration file back and starts the previous instance again.
      */
     declare(request: GatewayDeclareRequest, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
+    /**
+     * `gateway.plugins.enable` / `gateway.plugins.disable`: rewrites `disable_plugins` for one
+     * declared instance, then restarts the instance (a failed start restores the configuration file
+     * and starts the previous instance again). Validation runs before the instance is touched; an
+     * instance already in the requested state succeeds without stopping anything or writing.
+     */
+    setEnabled(request: GatewaySetEnabledRequest, enabled: boolean, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
     uninstall(packages: readonly unknown[], options: GatewayUninstallOptions): Promise<GatewayPackageTransactionResult>;
     /** Exact versions go through the workflow (verified); bare names / `'all'` run the manager's update. */
     update(packages: readonly unknown[] | 'all', options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;

package/lib/packages/service.js

@@ -10,7 +10,7 @@ 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 { PluginDeclarationError, PluginEnablementError, 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';
@@ -20,6 +20,8 @@ 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']);
+/** Transactions that only write the configuration file: no package manager, no reinstall on rollback. */
+const CONFIG_ONLY_OPERATIONS = new Set(['declare', 'enable', 'disable']);
 /** Thrown inside a transaction when the instance does not come up; carries its log tail. */
 class InstanceStartFailure extends Error {
     logTail;
@@ -145,6 +147,60 @@ export class GatewayPackageService {
             await ctx.workflow.declare(authorized[0].name, config, declareOptions);
         });
     }
+    /**
+     * `gateway.plugins.enable` / `gateway.plugins.disable`: rewrites `disable_plugins` for one
+     * declared instance, then restarts the instance (a failed start restores the configuration file
+     * and starts the previous instance again). Validation runs before the instance is touched; an
+     * instance already in the requested state succeeds without stopping anything or writing.
+     */
+    async setEnabled(request, enabled, options) {
+        const workflow = this.#workflow;
+        if (!workflow.planSetEnabled || !workflow.setEnabled)
+            throw new GatewayError('unavailable', '插件启停不可用');
+        const operation = enabled ? 'enable' : 'disable';
+        // Permission before anything about the project is read.
+        if (!options.principal || options.principal !== 'local' && options.principal.kind === 'bootstrap'
+            || !gatewayPrincipalAllows(options.principal, CONSOLE_PERMISSIONS.PLUGIN_MANAGE)) {
+            throw new GatewayError('forbidden', `需要 ${CONSOLE_PERMISSIONS.PLUGIN_MANAGE} 权限`);
+        }
+        if (typeof request.plugin !== 'string' || !request.plugin.trim() || request.plugin.length > 256) {
+            throw new GatewayError('invalid_input', 'plugin 必须是插件包名或 instanceKey');
+        }
+        let plan;
+        try {
+            plan = await workflow.planSetEnabled(request.plugin, enabled);
+        }
+        catch (error) {
+            throw enablementError(error);
+        }
+        const plugin = Object.freeze({ instanceKey: plan.instanceKey, packageName: plan.packageName, enabled, changed: plan.changed });
+        if (!plan.changed)
+            return this.#unchanged(operation, await this.authorize(options.principal, operation, [plan.packageName]), plugin, options);
+        return this.#transaction(operation, [plan.packageName], options, async (ctx) => {
+            // The exact instance key: the declaration may not be re-resolved to another instance.
+            await ctx.workflow.setEnabled(plan.instanceKey, enabled);
+            return { plugin };
+        });
+    }
+    /** The result of an enable / disable that found nothing to change (instance untouched). */
+    #unchanged(operation, authorized, plugin, options) {
+        const now = (this.#options.now ?? Date.now)();
+        const id = randomUUID();
+        const state = this.#instanceState();
+        const result = Object.freeze({
+            id, operation, packages: authorized, ok: true, status: 'succeeded', plugin,
+            instance: Object.freeze({ before: state, after: state }), startedAt: now, finishedAt: now,
+        });
+        for (const event of [{ type: 'start', id, operation, packages: authorized }, { type: 'phase', id, phase: 'done' }, { type: 'result', id, result }]) {
+            for (const listener of [options.onEvent, ...this.#listeners]) {
+                try {
+                    listener?.(event);
+                }
+                catch { /* listeners never break a request */ }
+            }
+        }
+        return result;
+    }
     uninstall(packages, options) {
         return this.#transaction('uninstall', packages, options, async (ctx, authorized) => {
             for (const item of authorized) {
@@ -229,7 +285,7 @@ export class GatewayPackageService {
         // 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';
+        const configOnly = CONFIG_ONLY_OPERATIONS.has(operation);
         let extras = undefined;
         let snapshot;
         let mutated = false;
@@ -296,6 +352,7 @@ export class GatewayPackageService {
                 ...(rollbackFailure === undefined ? {} : { rollbackError: failureMessage(rollbackFailure) }),
                 ...(logTail?.length ? { logTail } : {}),
                 ...(status === 'succeeded' && extras?.needsConfiguration?.length ? { needsConfiguration: extras.needsConfiguration } : {}),
+                ...(status === 'succeeded' && extras?.plugin ? { plugin: extras.plugin } : {}),
                 instance: Object.freeze({ before, after: this.#instanceState() }),
                 startedAt,
                 finishedAt: now(),
@@ -424,10 +481,16 @@ function declarationError(error) {
         ? new GatewayError('invalid_input', error.message, { cause: error, details: { errors: error.errors, missingEnv: error.missingEnv } })
         : error;
 }
+/** A refused enable / disable is the caller's input problem; anything else stays internal. */
+function enablementError(error) {
+    return error instanceof PluginEnablementError
+        ? 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))
+    if (!(cause instanceof PluginDeclarationError) && !(cause instanceof PluginEnablementError))
         return {};
     return {
         ...(cause.errors?.length ? { errors: cause.errors } : {}),

package/lib/plugin-management/config-explanation.js

@@ -1,5 +1,5 @@
 import { isDeepStrictEqual } from 'node:util';
-import { parsePluginConfigSchema } from '@zhin.js/runtime';
+import { isSecretConfigSchema, parsePluginConfigSchema } from '@zhin.js/runtime';
 import { readStringLiteralOptions } from '../config/console-schema.js';
 const complexKeywords = ['$ref', '$dynamicRef', 'anyOf', 'oneOf', 'allOf', 'not', 'if', 'then', 'else', 'dependentSchemas', 'dependentRequired', 'patternProperties', 'prefixItems', 'unevaluatedProperties'];
 const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
@@ -28,7 +28,7 @@ export function explainConfigFields(schema, input, current, committedInput) {
             return;
         }
         const metadata = record(node['x-zhin-config']) ? node['x-zhin-config'] : {};
-        const secret = inheritedSecret || node.writeOnly === true || metadata.secret === true || metadata.hidden === true || metadata.component === 'password';
+        const secret = inheritedSecret || isSecretConfigSchema(node) || metadata.hidden === true;
         if (node.type === 'object') {
             if (node.properties !== undefined && !record(node.properties)) {
                 issue = 'complex-schema';
@@ -54,7 +54,7 @@ export function explainConfigFields(schema, input, current, committedInput) {
         }
         const items = list && record(node.items) ? node.items : {};
         const itemMetadata = record(items['x-zhin-config']) ? items['x-zhin-config'] : {};
-        const itemSecret = items.writeOnly === true || itemMetadata.secret === true || itemMetadata.hidden === true || itemMetadata.component === 'password';
+        const itemSecret = isSecretConfigSchema(items) || itemMetadata.hidden === true;
         fields.push({ path: Object.freeze([...path]), secret: secret || itemSecret, list });
     };
     visit(schema, [], false);

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

@@ -33,6 +33,36 @@ export declare class PluginDeclarationError extends Error {
         message: string;
     }[], missingEnv?: readonly string[]);
 }
+/** Why an enable / disable request was refused before anything was written. */
+export type PluginEnablementErrorCode = 'invalid-request' | 'reserved' | 'root' | 'not-declared' | 'not-installed' | 'invalid-config';
+/** An enable / disable refused before anything was written (invalid target or configuration). */
+export declare class PluginEnablementError extends Error {
+    readonly code: PluginEnablementErrorCode;
+    readonly errors: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+    readonly missingEnv: readonly string[];
+    constructor(code: PluginEnablementErrorCode, message: string, errors?: readonly {
+        path: string;
+        message: string;
+    }[], missingEnv?: readonly string[]);
+}
+/** What `setEnabled` would write to `disable_plugins`; changes nothing. */
+export interface PluginEnablementPlan {
+    readonly packageName: string;
+    readonly instanceKey: string;
+    /** The requested state. */
+    readonly enabled: boolean;
+    /** False when the instance already is in the requested state: nothing would be written. */
+    readonly changed: boolean;
+    /** `disable_plugins` after the change. */
+    readonly disabled: readonly string[];
+    readonly projectRevision: string;
+    readonly configurationRevision: string;
+    /** A running instance must restart to reflect the (current or requested) state. */
+    readonly restartRequired: boolean;
+}
 /** One installation authority for CLI and Console. No generation or package parser of its own. */
 export declare class PluginManagementWorkflow implements PluginManagementPort {
     #private;
@@ -64,6 +94,20 @@ export declare class PluginManagementWorkflow implements PluginManagementPort {
         restartRequired: boolean;
         state: PluginManagementState;
     }>>;
+    /**
+     * Validates enabling / disabling one declared instance (an instance key, or a package name
+     * declared exactly once) without writing. Enabling needs an installed plugin package whose
+     * dependencies and configuration pass; disabling also accepts a declared package that is no
+     * longer installed, so a broken instance can be taken out of the next generation.
+     */
+    planSetEnabled(request: string, enabled: boolean): Promise<PluginEnablementPlan>;
+    /** Writes `disable_plugins` in one atomic config write; already in the requested state → nothing written. */
+    setEnabled(request: string, enabled: boolean, expectedRevision?: string, expectedProjectRevision?: string): Promise<Readonly<{
+        plan: PluginEnablementPlan;
+        changed: boolean;
+        restartRequired: boolean;
+        state: PluginManagementState;
+    }>>;
     planUninstall(request: string): Promise<PluginUninstallPlan>;
     uninstall(request: string, expectedRevision?: string, expectedProjectRevision?: string, options?: {
         removeDependency?: boolean;