@zhin.js/runtime 1.1.8 → 1.1.10

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,9 @@ 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'];
+/** Command routing keys the framework injects into every Plugin config schema. */
+const COMMAND_CONFIG_KEYS = ['commandNamespace', 'disabledCommands'];
 export class ConfigSchemaCollisionError extends Error {
     plugin;
     instanceKey;
@@ -37,22 +41,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 +81,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 +101,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 +172,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 +186,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 +216,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 [...COMMAND_CONFIG_KEYS, ...(!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))}`,
@@ -199,6 +233,13 @@ async function readOwnSchema(node, modules) {
                 description: 'Explicit command namespace prepended after the Endpoint commandPrefix.',
                 'x-descriptionZh': '显式指令命名空间；在 Endpoint commandPrefix 之后参与路由。',
             },
+            disabledCommands: {
+                type: 'array',
+                uniqueItems: true,
+                items: { type: 'string', minLength: 1, pattern: '^\\S+(?: \\S+)*$' },
+                description: 'Commands of this Plugin instance to leave out of routing, by local path without commandNamespace or parameters (e.g. "fanyi", "netease login"). A parent path also disables its subcommands.',
+                'x-descriptionZh': '不注册的指令：写插件内的指令路径（不含 commandNamespace 和参数，如 fanyi、netease login），写上级路径会连同子命令一起禁用。',
+            },
             ...properties,
         },
     });

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({

package/lib/editor-temp-file.d.ts

@@ -0,0 +1,12 @@
+interface EditorTempPattern {
+    readonly editor: string;
+    readonly test: (name: string) => boolean;
+}
+/** Ordered, documented list; each entry is covered by a unit test. */
+export declare const EDITOR_TEMP_FILE_PATTERNS: readonly EditorTempPattern[];
+/**
+ * Returns true when `source` (a path or a bare file name) is an editor temp or
+ * backup file. Only the basename is inspected.
+ */
+export declare function isEditorTempFile(source: string): boolean;
+export {};

package/lib/editor-temp-file.js

@@ -0,0 +1,44 @@
+/**
+ * Editor temp, swap, lock, and backup files that must never trigger an HMR
+ * reload (#857 P2-11).
+ *
+ * Editors write these next to the real source while saving. Several of them
+ * keep the source extension (for example `.!97910!index.ts`), so an
+ * extension allow-list alone is not enough.
+ *
+ * Matching uses the basename only, so a directory such as `tmp/` or a file
+ * such as `tmp.ts` or `foo.tmp.ts` is still watched: those are ordinary
+ * sources a plugin may really import. Only the exact shapes below are skipped.
+ */
+import { basename } from 'node:path';
+/** Ordered, documented list; each entry is covered by a unit test. */
+export const EDITOR_TEMP_FILE_PATTERNS = Object.freeze([
+    // `.!<digits>!<name>`: atomic-save temp file seen in practice (`.!97910!index.ts`).
+    { editor: 'atomic save (.!<pid>!name)', test: (name) => /^\.!\d+!/.test(name) },
+    // Vim swap files: `.index.ts.swp`, then `.swo`, `.swx` when the first one is taken.
+    { editor: 'vim swap (*.swp, *.swo, *.swx)', test: (name) => /\.sw[pox]$/.test(name) },
+    // Vim `writebackup` probe: Vim creates and deletes `4913` to test the directory.
+    { editor: 'vim probe (4913)', test: (name) => name === '4913' },
+    // Backup copies from Vim, Emacs, nano and others: `index.ts~`.
+    { editor: 'backup (*~)', test: (name) => name.endsWith('~') },
+    // Emacs lock files: `.#index.ts` (usually a dangling symlink).
+    { editor: 'emacs lock (.#*)', test: (name) => name.startsWith('.#') },
+    // Generic temp files: `index.ts.tmp`. `foo.tmp.ts` is a real source and still reloads.
+    { editor: 'temp (*.tmp)', test: (name) => name.endsWith('.tmp') },
+    // JetBrains "safe write": `index.ts___jb_tmp___` and `index.ts___jb_old___`.
+    {
+        editor: 'JetBrains safe write (*___jb_tmp___, *___jb_old___)',
+        test: (name) => name.endsWith('___jb_tmp___') || name.endsWith('___jb_old___'),
+    },
+]);
+/**
+ * Returns true when `source` (a path or a bare file name) is an editor temp or
+ * backup file. Only the basename is inspected.
+ */
+export function isEditorTempFile(source) {
+    // Accept both separators so Windows paths behave the same on every host.
+    const name = basename(source.replaceAll('\\', '/'));
+    if (!name)
+        return false;
+    return EDITOR_TEMP_FILE_PATTERNS.some((pattern) => pattern.test(name));
+}

package/lib/hmr-coordinator.js

@@ -1,5 +1,6 @@
 import { normalizeSourcePath } from './source-path.js';
 import { InvalidationPlanner, } from './invalidation-planner.js';
+import { isEditorTempFile } from './editor-temp-file.js';
 export class HmrCoordinator {
     options;
     #pending = new Set();
@@ -24,6 +25,9 @@ export class HmrCoordinator {
         }
         this.#syncModuleState();
         this.#unwatch = this.options.modules.watch((source) => {
+            // Any ModuleRuntime watcher may report editor temp/backup files; they never reload (#857).
+            if (isEditorTempFile(source))
+                return;
             void this.enqueue(source).catch(() => undefined);
         });
         return () => this.stop();