@zhin.js/gateway 1.1.1 → 1.2.0

package/lib/plugin-management/workflow.js

@@ -9,7 +9,7 @@ import { featureId, pluginVerificationToken, rootPluginId, readPluginConfigurati
 import { ConsoleConfigurationStore } from '../config/configuration.js';
 import { explainConfigFields } from './config-explanation.js';
 import { resolveCommand } from '../onboarding/package-manager.js';
-import { readPluginLifecycleState, resolvePluginLifecycleFile } from '@zhin.js/runtime';
+import { inferConventionFeatureReferences, readPluginLifecycleState, resolvePluginLifecycleFile } from '@zhin.js/runtime';
 const execute = promisify(execFile);
 // Narrow local view of the `@zhin.js/adapter` index projection: the gateway must not import IM layers (ADR 0054 §0).
 const adapterFeatureId = featureId('zhin.adapter');
@@ -28,6 +28,21 @@ export class PluginDeclarationError extends Error {
         this.missingEnv = Object.freeze([...missingEnv]);
     }
 }
+/** An enable / disable refused before anything was written (invalid target or configuration). */
+export class PluginEnablementError extends Error {
+    code;
+    errors;
+    missingEnv;
+    constructor(code, message, errors = [], missingEnv = []) {
+        super(message);
+        this.name = 'PluginEnablementError';
+        this.code = code;
+        this.errors = Object.freeze(errors.map(error => Object.freeze({ ...error })));
+        this.missingEnv = Object.freeze([...missingEnv]);
+    }
+}
+/** Keys that never name a plugin instance (Host sections and the declaration protocol). */
+const RESERVED_INSTANCE_KEYS = new Set([...HOST_CONFIG_KEYS, 'configVersion', 'plugins', 'disable_plugins', 'plugin', 'root']);
 /** One installation authority for CLI and Console. No generation or package parser of its own. */
 export class PluginManagementWorkflow {
     #root;
@@ -133,7 +148,9 @@ export class PluginManagementWorkflow {
             try {
                 if (pkg.packageJson.zhin.type !== 'plugin')
                     throw new Error(`${packageName} is a Feature package, not a Plugin`);
-                await access(join(pkg.root, pkg.packageJson.zhin.entry));
+                // An entry-less Plugin has no entry file; its manifest alone makes it a Plugin.
+                if (pkg.packageJson.zhin.entry !== undefined)
+                    await access(join(pkg.root, pkg.packageJson.zhin.entry));
                 return { installed: true, plugin: true, version: pkg.packageJson.version ?? null, error: undefined, pkg };
             }
             catch (error) {
@@ -164,7 +181,9 @@ export class PluginManagementWorkflow {
             const installedPackage = await resolver.loadPackage(directory);
             if (installedPackage.packageJson.zhin.type !== 'plugin')
                 throw new Error(`${packageName} is a Feature package, not a Plugin`);
-            await access(join(installedPackage.root, installedPackage.packageJson.zhin.entry));
+            const entry = installedPackage.packageJson.zhin.entry;
+            if (entry !== undefined)
+                await access(join(installedPackage.root, entry));
             const declarationMissing = resolutionError instanceof PackageResolutionError && resolutionError.message.includes('does not declare');
             return { installed: true, plugin: true, version, error: declarationMissing ? errorMessage(resolutionError) : undefined, pkg: installedPackage };
         }
@@ -561,6 +580,90 @@ export class PluginManagementWorkflow {
             return Object.freeze({ packageName: plan.packageName, instanceKey: plan.instanceKey, restartRequired: state.restartRequired, state });
         }, request);
     }
+    /**
+     * 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.
+     */
+    async planSetEnabled(request, enabled) {
+        if (typeof request !== 'string' || !request.trim() || request.length > 256)
+            throw new PluginEnablementError('invalid-request', '请提供插件包名或 instanceKey');
+        if (typeof enabled !== 'boolean')
+            throw new PluginEnablementError('invalid-request', 'enabled 必须是布尔值');
+        const key = request.trim().replace(/^root\//u, '');
+        if (RESERVED_INSTANCE_KEYS.has(key))
+            throw new PluginEnablementError('reserved', `${key} 是保留配置键，不是插件实例`);
+        const { project } = await this.#project();
+        if (project.name !== undefined && key === project.name)
+            throw new PluginEnablementError('root', '项目根插件始终加载，不能启用或停用');
+        let target;
+        let declared;
+        try {
+            const entries = await this.#declaredEntries();
+            target = await this.#resolveTarget(key, entries);
+            declared = entries.some(entry => entry.package === target.packageName && entry.instanceKey === target.instanceKey);
+        }
+        catch (error) {
+            throw new PluginEnablementError('invalid-request', errorMessage(error), [], []);
+        }
+        if (!declared)
+            throw new PluginEnablementError('not-declared', `插件实例 ${target.instanceKey}（${target.packageName}）未在配置中声明；先运行 zhin install ${target.packageName}`);
+        const state = await this.inspect(target.instanceKey);
+        if (enabled && (!state.installed || !state.plugin)) {
+            throw new PluginEnablementError('not-installed', `${state.packageName} ${state.installed ? `不是可加载的 Plugin 包${state.issues[0] ? `：${state.issues[0]}` : ''}` : '未安装'}；先运行 zhin install ${state.packageName}`);
+        }
+        const configuration = this.#configuration();
+        if (!configuration)
+            throw new Error('Missing configVersion: 2 configuration; run zhin setup');
+        const current = await configuration.document.read();
+        if (current.revision !== state.revision)
+            throw new Error('配置在读取期间变化，请重试');
+        const declaration = readApplicationPluginDeclaration(current.document);
+        const wasDisabled = declaration.disabled.includes(state.instanceKey);
+        const changed = enabled === wasDisabled;
+        const disabled = enabled ? declaration.disabled.filter(item => item !== state.instanceKey)
+            : wasDisabled ? declaration.disabled : [...declaration.disabled, state.instanceKey];
+        if (enabled && changed) {
+            const candidate = { ...current.document, disable_plugins: disabled };
+            readApplicationPluginDeclaration(candidate);
+            try {
+                await this.#checkDependencies(undefined, candidate);
+            }
+            catch (error) {
+                throw new PluginEnablementError('invalid-config', `依赖检查未通过，未启用：${errorMessage(error)}`);
+            }
+            const validation = await configuration.store.validatePluginConfig(state.instanceKey, readPluginConfigurationMap(candidate)[state.instanceKey] ?? {}, candidate);
+            if (!validation.valid || validation.missingEnv.length) {
+                throw new PluginEnablementError('invalid-config', `配置未通过插件 Schema 校验，未启用：${[
+                    ...validation.errors.map(error => `${error.path} ${error.message}`),
+                    ...validation.missingEnv.map(name => `缺少环境变量 ${name}`)
+                ].join('；')}`, validation.errors, validation.missingEnv);
+            }
+        }
+        return Object.freeze({ packageName: state.packageName, instanceKey: state.instanceKey, enabled, changed,
+            disabled: Object.freeze([...disabled]), projectRevision: state.projectRevision, configurationRevision: current.revision,
+            restartRequired: changed || state.restartRequired });
+    }
+    /** Writes `disable_plugins` in one atomic config write; already in the requested state → nothing written. */
+    async setEnabled(request, enabled, expectedRevision, expectedProjectRevision) {
+        return this.#mutate(async (completed) => {
+            await this.#assertRevision(expectedRevision, expectedProjectRevision);
+            const plan = await this.planSetEnabled(request, enabled);
+            if (plan.changed) {
+                const configuration = this.#configuration();
+                if (!configuration)
+                    throw new Error('Missing configVersion: 2 configuration; run zhin setup');
+                const current = await configuration.document.read();
+                if (current.revision !== plan.configurationRevision)
+                    throw new Error('配置在校验期间变化，请刷新后重试');
+                await (await configuration.document.prepare(current, [{ op: 'set', path: ['disable_plugins'], value: [...plan.disabled] }])).commit();
+                completed.push(enabled ? 'plugin-enable' : 'plugin-disable');
+            }
+            const state = await this.inspect(plan.instanceKey);
+            return Object.freeze({ plan, changed: plan.changed, restartRequired: plan.changed || state.restartRequired, state });
+        }, request);
+    }
     async planUninstall(request) {
         const state = await this.inspect(request);
         const configuration = this.#configuration();
@@ -609,6 +712,9 @@ export class PluginManagementWorkflow {
                 return false;
             if (pkg.packageJson.zhin.features.some(item => item.package === packageName))
                 return true;
+            // A convention directory implies its Feature package even when zhin.features omits it.
+            if (inferConventionFeatureReferences(pkg.root, pkg.packageJson.zhin).some(item => item.package === packageName))
+                return true;
             if (!isRoot && [pkg.packageJson.dependencies, pkg.packageJson.optionalDependencies, pkg.packageJson.peerDependencies].some(deps => deps?.[packageName]))
                 return true;
             const entries = isRoot ? await this.#declaredEntries() : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/gateway",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Zhin.js management gateway: Console access control, terminal, project configuration and instance supervision (ADR 0054)",
   "type": "module",
   "main": "./lib/index.js",
@@ -72,13 +72,13 @@
     "fs-extra": "^11.4.0",
     "tsx": "^4.23.1",
     "yaml": "^2.9.0",
-    "@zhin.js/console-protocol": "1.2.0",
-    "@zhin.js/database": "1.1.8",
-    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/console-protocol": "1.2.2",
+    "@zhin.js/database": "1.2.0",
+    "@zhin.js/host-http": "1.2.2",
     "@zhin.js/logger": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.2.0",
-    "@zhin.js/runtime": "1.2.0",
-    "@zhin.js/scaffold-wizard": "1.1.19"
+    "@zhin.js/plugin-runtime": "1.2.1",
+    "@zhin.js/runtime": "1.2.2",
+    "@zhin.js/scaffold-wizard": "1.1.21"
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",