@zhin.js/runtime 1.1.7 → 1.1.9

package/lib/config-composer.js

@@ -1,6 +1,7 @@
 import Ajv2020 from 'ajv/dist/2020.js';
 import hostConfigSchema from './host-config-schema.json' with { type: 'json' };
 import { readPluginConfigSchema } from './plugin-config-schema.js';
+import { readApplicationPluginDeclaration } from './application-plugin-declaration.js';
 function deepFreeze(value) {
     if (value && typeof value === 'object' && !Object.isFrozen(value)) {
         for (const nested of Object.values(value))
@@ -12,6 +13,7 @@ function deepFreeze(value) {
 export const HOST_CONFIG_SCHEMA = deepFreeze(hostConfigSchema);
 /** Host configuration keys consumed by Runtime composition and Host installers. */
 export const HOST_CONFIG_KEYS = Object.freeze(Object.keys(HOST_CONFIG_SCHEMA.properties));
+const ROOT_FEATURE_CONFIG_KEYS = ['menuKeyword', 'menuStyle'];
 export class ConfigSchemaCollisionError extends Error {
     plugin;
     instanceKey;
@@ -37,22 +39,36 @@ export class ConfigValidationError extends Error {
 export class ConfigComposer {
     inactivePluginInstanceKeys;
     modules;
-    constructor(inactivePluginInstanceKeys = [], modules) {
+    validatedSchemas;
+    constructor(inactivePluginInstanceKeys = [], modules, 
+    /** Previously validated generation declarations; never import retired owners just to compare inputs. */
+    validatedSchemas) {
         this.inactivePluginInstanceKeys = inactivePluginInstanceKeys;
         this.modules = modules;
+        this.validatedSchemas = validatedSchemas;
     }
     async compose(graph, input = {}, 
     /** Source config file name, annotated on ConfigValidationError. */
     source) {
+        const declaration = readApplicationPluginDeclaration(input, source);
+        if (this.inactivePluginInstanceKeys.length > 0) {
+            throw new TypeError('Legacy disabled Plugin state must move to disable_plugins; see docs/migrations/plugin-instance-declarations.md');
+        }
+        const enabledKeys = new Set(declaration.instances.filter(instance => instance.enabled).map(instance => instance.instanceKey));
+        if (enabledKeys.size !== graph.root.children.length
+            || graph.root.children.some(child => !enabledKeys.has(child.instanceKey))) {
+            throw new TypeError('Compose configuration against its candidate application graph before loading Plugin schemas');
+        }
         // Effective schemas include child namespaces for whole-tree validation;
         // ownSchemas retain each package's private configuration contract.
         const ownSchemas = new Map();
-        const rootOwn = await readOwnSchema(graph.root, this.modules);
+        const rootOwn = await readOwnSchema(graph.root, this.modules, this.validatedSchemas);
         ownSchemas.set(graph.root.id, rootOwn);
         const childSchemas = await Promise.all(graph.root.children.map(async (child) => [
             child.instanceKey,
-            await composeNode(child, ownSchemas, this.modules),
+            await composeNode(child, ownSchemas, this.modules, this.validatedSchemas),
         ]));
+        const childSchemaByKey = new Map(childSchemas);
         // Host-level keys (`http`, `database`, `ai`, `mcp`, `a2a`, `speech`,
         // `htmlRenderer`, `assistant`, `log_level`) are consumed by CLI Root installers /
         // start-command, not Plugin ConfigViews.
@@ -63,15 +79,15 @@ export class ConfigComposer {
             properties: {
                 ...HOST_CONFIG_SCHEMA.properties,
                 plugin: withDefault(rootOwn),
-                plugins: {
-                    type: 'object',
-                    additionalProperties: false,
-                    default: {},
-                    properties: Object.fromEntries([
-                        ...this.inactivePluginInstanceKeys.map((key) => [key, {}]),
-                        ...childSchemas.map(([key, schema]) => [key, withDefault(schema)]),
-                    ]),
-                },
+                configVersion: { const: 2 },
+                plugins: { type: 'object', additionalProperties: { type: 'string' }, default: {} },
+                disable_plugins: { type: 'array', items: { type: 'string' }, default: [] },
+                ...Object.fromEntries(declaration.instances.map(instance => {
+                    const schema = childSchemaByKey.get(instance.instanceKey);
+                    if (instance.enabled && !schema)
+                        throw new TypeError(`Candidate graph is missing enabled Plugin ${instance.instanceKey}`);
+                    return [instance.instanceKey, instance.enabled && schema ? withDefault(schema) : { type: 'object' }];
+                })),
             },
         });
         const document = structuredClone(input);
@@ -83,8 +99,17 @@ export class ConfigComposer {
         const views = new Map();
         // A Plugin never receives its effective node object because that object
         // also contains descendants. Re-pick fields from the owner's own schema.
-        views.set(graph.root.id, pickOwnFields(document.plugin, requireOwnSchema(ownSchemas, graph.root.id)));
-        collectChildViews(graph.root, document.plugins, ownSchemas, views);
+        views.set(graph.root.id, 
+        // Built-in menu settings belong to the application, but Command Feature
+        // consumes the root's generation view. Project only these reserved fields;
+        // Host credentials and other instances never enter a Plugin ConfigView.
+        Object.freeze({
+            ...pickOwnFields(document.plugin, requireOwnSchema(ownSchemas, graph.root.id)),
+            ...Object.fromEntries(ROOT_FEATURE_CONFIG_KEYS
+                .filter(key => Object.hasOwn(document, key))
+                .map(key => [key, deepFreeze(structuredClone(document[key]))])),
+        }));
+        collectChildViews(graph.root, document, ownSchemas, views);
         return Object.freeze({
             effectiveSchema,
             document: Object.freeze(document),
@@ -145,8 +170,8 @@ function injectFrameworkRoleSchema(properties) {
         }),
     });
 }
-async function composeNode(node, ownSchemas, modules) {
-    const own = await readOwnSchema(node, modules);
+async function composeNode(node, ownSchemas, modules, validatedSchemas) {
+    const own = await readOwnSchema(node, modules, validatedSchemas);
     ownSchemas.set(node.id, own);
     const properties = { ...schemaProperties(own) };
     // Adapter plugins (schemas declaring array-typed `endpoints`) get
@@ -159,11 +184,17 @@ async function composeNode(node, ownSchemas, modules) {
         if (Object.hasOwn(properties, child.instanceKey)) {
             throw new ConfigSchemaCollisionError(node.id, child.instanceKey);
         }
-        properties[child.instanceKey] = withDefault(await composeNode(child, ownSchemas, modules));
+        properties[child.instanceKey] = withDefault(await composeNode(child, ownSchemas, modules, validatedSchemas));
     }
     return Object.freeze({ ...own, properties });
 }
-async function readOwnSchema(node, modules) {
+async function readOwnSchema(node, modules, validatedSchemas) {
+    if (validatedSchemas) {
+        const schema = validatedSchemas.get(node.id);
+        if (!schema)
+            throw new TypeError(`Missing committed configuration schema for ${node.id}`);
+        return schema;
+    }
     const file = `${node.package.name} config`;
     const value = await readPluginConfigSchema(node.package, modules)
         ?? { type: 'object', additionalProperties: false, properties: {} };
@@ -183,8 +214,9 @@ async function readOwnSchema(node, modules) {
         throw new TypeError(`${file} root schema must declare properties; composition keywords (anyOf/oneOf/allOf/$ref) are not supported`);
     }
     const properties = schemaProperties(schema);
-    if (Object.hasOwn(properties, 'commandNamespace')) {
-        throw new ConfigSchemaCollisionError(node.id, 'commandNamespace');
+    for (const key of ['commandNamespace', ...(!node.parent ? ROOT_FEATURE_CONFIG_KEYS : [])]) {
+        if (Object.hasOwn(properties, key))
+            throw new ConfigSchemaCollisionError(node.id, key);
     }
     return deepFreeze({
         $id: `urn:zhin:plugin-config:${encodeURIComponent(String(node.id))}`,

package/lib/config-patch-planner.d.ts

@@ -9,6 +9,7 @@ export interface ConfigPatchPlan extends ComposedConfig {
 /** Validates a candidate document before deriving its minimal replacement forest. */
 export declare class ConfigPatchPlanner {
     private readonly composer;
-    constructor(composer?: ConfigComposer);
-    plan(graph: ProjectGraph, current: RuntimeConfigDocument, patches: readonly ConfigPatch[]): Promise<ConfigPatchPlan>;
+    private readonly previousComposer;
+    constructor(composer?: ConfigComposer, previousComposer?: ConfigComposer);
+    plan(graph: ProjectGraph, current: RuntimeConfigDocument, patches: readonly ConfigPatch[], candidateGraph?: ProjectGraph, previousDocument?: RuntimeConfigDocument): Promise<ConfigPatchPlan>;
 }

package/lib/config-patch-planner.js

@@ -4,14 +4,16 @@ import { ConfigComposer } from './config-composer.js';
 /** Validates a candidate document before deriving its minimal replacement forest. */
 export class ConfigPatchPlanner {
     composer;
-    constructor(composer = new ConfigComposer()) {
+    previousComposer;
+    constructor(composer = new ConfigComposer(), previousComposer = composer) {
         this.composer = composer;
+        this.previousComposer = previousComposer;
     }
-    async plan(graph, current, patches) {
-        const previous = await this.composer.compose(graph, current);
+    async plan(graph, current, patches, candidateGraph = graph, previousDocument = current) {
+        const previous = await this.previousComposer.compose(graph, previousDocument);
         const candidate = applyConfigPatches(current, patches);
-        const next = await this.composer.compose(graph, candidate);
-        const changed = indexGraph(graph)
+        const next = await this.composer.compose(candidateGraph, candidate);
+        const changed = indexGraph(candidateGraph)
             .filter((node) => !isDeepStrictEqual(previous.views.get(node.id), next.views.get(node.id)))
             .map((node) => node.id);
         return Object.freeze({