@zhin.js/runtime 1.1.9 → 1.1.10

package/lib/config-composer.js

@@ -14,6 +14,8 @@ 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;
@@ -214,7 +216,7 @@ async function readOwnSchema(node, modules, validatedSchemas) {
         throw new TypeError(`${file} root schema must declare properties; composition keywords (anyOf/oneOf/allOf/$ref) are not supported`);
     }
     const properties = schemaProperties(schema);
-    for (const key of ['commandNamespace', ...(!node.parent ? ROOT_FEATURE_CONFIG_KEYS : [])]) {
+    for (const key of [...COMMAND_CONFIG_KEYS, ...(!node.parent ? ROOT_FEATURE_CONFIG_KEYS : [])]) {
         if (Object.hasOwn(properties, key))
             throw new ConfigSchemaCollisionError(node.id, key);
     }
@@ -231,6 +233,13 @@ async function readOwnSchema(node, modules, validatedSchemas) {
                 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/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();

package/lib/manifest.d.ts

@@ -53,3 +53,13 @@ export declare class ManifestValidationError extends Error {
     constructor(issues: readonly string[]);
 }
 export declare function parsePackageJson(value: unknown, source: string): PackageJson;
+/** Conditions tried, in order, when `exports["./zhin"]` is a condition object. */
+export declare const ZHIN_EXPORT_CONDITIONS: readonly ["zhin", "import", "default"];
+/**
+ * The runtime entry declared by `exports["./zhin"]`, if any.
+ *
+ * A string target is used as is; a condition object is searched for `zhin`, then `import`,
+ * then `default` (nested condition objects are searched the same way); an array uses its
+ * first target that resolves. Other conditions such as `types` or `require` are ignored.
+ */
+export declare function zhinExportTarget(packageExports: unknown): string | undefined;

package/lib/manifest.js

@@ -12,7 +12,7 @@ export function parsePackageJson(value, source) {
     const name = readString(record, 'name', source, issues);
     if (name && !isPackageName(name))
         issues.push(`${source}#name is not a valid package name`);
-    const zhin = parseZhinManifest(record.zhin, `${source}#zhin`, issues);
+    const zhin = parseZhinManifest(record.zhin, `${source}#zhin`, issues, record.exports, `${source}#exports`);
     const version = optionalString(record.version, `${source}#version`, issues);
     const moduleType = optionalModuleType(record.type, `${source}#type`, issues);
     const main = optionalString(record.main, `${source}#main`, issues);
@@ -42,12 +42,54 @@ export function parsePackageJson(value, source) {
         zhin,
     });
 }
-function parseZhinManifest(value, source, issues) {
+/** Conditions tried, in order, when `exports["./zhin"]` is a condition object. */
+export const ZHIN_EXPORT_CONDITIONS = Object.freeze(['zhin', 'import', 'default']);
+/**
+ * The runtime entry declared by `exports["./zhin"]`, if any.
+ *
+ * A string target is used as is; a condition object is searched for `zhin`, then `import`,
+ * then `default` (nested condition objects are searched the same way); an array uses its
+ * first target that resolves. Other conditions such as `types` or `require` are ignored.
+ */
+export function zhinExportTarget(packageExports) {
+    if (!packageExports || typeof packageExports !== 'object' || Array.isArray(packageExports))
+        return undefined;
+    if (!Object.hasOwn(packageExports, './zhin'))
+        return undefined;
+    return selectExportTarget(packageExports['./zhin']);
+}
+function selectExportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const target = selectExportTarget(item);
+            if (target !== undefined)
+                return target;
+        }
+        return undefined;
+    }
+    if (!value || typeof value !== 'object')
+        return undefined;
+    for (const condition of ZHIN_EXPORT_CONDITIONS) {
+        if (!Object.hasOwn(value, condition))
+            continue;
+        const target = selectExportTarget(value[condition]);
+        if (target !== undefined)
+            return target;
+    }
+    return undefined;
+}
+function parseZhinManifest(value, source, issues, packageExports, exportsSource = 'exports') {
     const record = asRecord(value, source, issues);
     if (record.protocol !== 1)
         issues.push(`${source}.protocol must be 1`);
     const type = readString(record, 'type', source, issues);
-    const entry = readRelativeEntry(record.entry, `${source}.entry`, issues);
+    // `zhin.entry` wins when present; `exports["./zhin"]` is the standard-field alternative.
+    const exportedEntry = record.entry === undefined ? zhinExportTarget(packageExports) : undefined;
+    const entry = exportedEntry !== undefined
+        ? readRelativeEntry(exportedEntry, `${exportsSource}["./zhin"]`, issues)
+        : readRelativeEntry(record.entry, `${source}.entry`, issues, `${exportsSource}["./zhin"]`);
     const engine = optionalString(record.engine, `${source}.engine`, issues);
     if (!entry || (type !== 'plugin' && type !== 'feature')) {
         if (type && type !== 'plugin' && type !== 'feature') {
@@ -132,7 +174,11 @@ function parseReferences(value, source, issues, child) {
             }];
     });
 }
-function readRelativeEntry(value, source, issues) {
+function readRelativeEntry(value, source, issues, alternative) {
+    if (value === undefined && alternative) {
+        issues.push(`${source} or ${alternative} must declare a package-relative path starting with ./`);
+        return undefined;
+    }
     if (typeof value !== 'string' || !value.startsWith('./')) {
         issues.push(`${source} must be a package-relative path starting with ./`);
         return undefined;

package/lib/native-development-runtime.js

@@ -4,6 +4,7 @@ import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path
 import { pathToFileURL } from 'node:url';
 import { ModuleDependencyIndex, } from './module-dependency-index.js';
 import { withToolPackageInstallHint } from './missing-tool-package.js';
+import { isEditorTempFile } from './editor-temp-file.js';
 import { ensureTypeScriptSpecifierRemap } from './typescript-specifier-remap.js';
 const ignoredDirectories = new Set([
     '.git', '.zhin', 'coverage', 'data', 'dist', 'lib', 'node_modules',
@@ -353,8 +354,12 @@ function sourceSnapshot(roots) {
         visit(root);
     return result;
 }
+/** Shared by the native watcher and the polling fallback, so both skip the same files. */
 function isWatchedSource(source) {
     const name = source.slice(source.lastIndexOf(sep) + 1);
+    // Editor temp/backup files (e.g. `.!97910!index.ts`, `.env.swp`) never reload (#857).
+    if (isEditorTempFile(name))
+        return false;
     return watchedExtensions.has(extname(source)) || name.startsWith('.env');
 }
 /** Mirrors sourceSnapshot: any path segment matching an ignored directory opts out. */

package/lib/plugin-config-schema.d.ts

@@ -4,3 +4,13 @@ import type { ResolvedPackage } from './package-resolver.js';
 export declare function readPluginConfigSchema(pkg: ResolvedPackage, modules?: Pick<ModuleRuntime, 'load'>): Promise<Readonly<Record<string, unknown>> | null>;
 /** Detached declaration metadata for preflight and custom-resolver startup views. */
 export declare function immutableConfigSchema(schema: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/**
+ * Thrown when a trusted plugin declares both `definePlugin({ config })` and a root `schema.json`.
+ * Neither source wins: startup stops so the two schemas cannot silently drift apart.
+ */
+export declare class PluginConfigSourceConflictError extends TypeError {
+    readonly packageName: string;
+    readonly entryFile: string;
+    readonly schemaFile: string;
+    constructor(packageName: string, entryFile: string, schemaFile: string);
+}

package/lib/plugin-config-schema.js

@@ -14,12 +14,14 @@ export async function readPluginConfigSchema(pkg, modules) {
     // Isolated plugin code never executes in the composition process.
     const manifest = pkg.packageJson.zhin;
     let declaration;
+    let entryFile;
     if (modules && manifest.type === 'plugin' && manifest.runtime !== 'isolated') {
-        const module = await modules.load(resolve(pkg.root, manifest.entry));
+        entryFile = resolve(pkg.root, manifest.entry);
+        const module = await modules.load(entryFile);
         declaration = module.default?.config;
     }
     if (declaration && fileSchema !== undefined) {
-        throw new TypeError(`${pkg.name} declares both plugin config and schema.json; choose one configuration schema`);
+        throw new PluginConfigSourceConflictError(pkg.name, entryFile ?? manifest.entry, file);
     }
     const schema = declaration ? declaration.toJsonSchema() : fileSchema;
     if (schema === undefined)
@@ -42,3 +44,24 @@ export function immutableConfigSchema(schema) {
     freeze(copy);
     return copy;
 }
+/**
+ * Thrown when a trusted plugin declares both `definePlugin({ config })` and a root `schema.json`.
+ * Neither source wins: startup stops so the two schemas cannot silently drift apart.
+ */
+export class PluginConfigSourceConflictError extends TypeError {
+    packageName;
+    entryFile;
+    schemaFile;
+    constructor(packageName, entryFile, schemaFile) {
+        super(`${packageName} declares both plugin config and schema.json; choose one configuration schema. `
+            + `Inline config: definePlugin({ config }) in ${entryFile}. JSON Schema: ${schemaFile}. `
+            + 'Zhin does not pick one for you. To keep the typed inline Schema, delete schema.json; '
+            + 'to keep schema.json (required for isolated plugins, readable without running the plugin), '
+            + 'remove config from definePlugin. '
+            + 'See https://zhin.js.org/authoring/define-plugin#choose-a-config-source');
+        this.packageName = packageName;
+        this.entryFile = entryFile;
+        this.schemaFile = schemaFile;
+        this.name = 'PluginConfigSourceConflictError';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,25 +19,25 @@
     "es-module-lexer": "2.3.1",
     "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.1.6",
+    "@zhin.js/feature-kit": "1.1.7",
     "@zhin.js/plugin-runtime": "1.1.15"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.20",
-    "@zhin.js/command": "1.1.8",
-    "@zhin.js/component": "1.1.7",
-    "@zhin.js/handler": "1.1.6",
-    "@zhin.js/mcp-feature": "1.1.7",
-    "@zhin.js/agent-feature": "1.1.7",
-    "@zhin.js/page": "1.1.7",
-    "@zhin.js/prompt-section": "1.1.6",
-    "@zhin.js/skill": "1.1.7",
-    "@zhin.js/tool": "1.1.7",
-    "@zhin.js/middleware": "1.1.7",
-    "@zhin.js/layout": "1.1.7"
+    "@zhin.js/adapter": "1.1.21",
+    "@zhin.js/agent-feature": "1.1.8",
+    "@zhin.js/command": "1.1.9",
+    "@zhin.js/component": "1.1.8",
+    "@zhin.js/layout": "1.1.8",
+    "@zhin.js/page": "1.1.8",
+    "@zhin.js/handler": "1.1.7",
+    "@zhin.js/middleware": "1.1.8",
+    "@zhin.js/prompt-section": "1.1.7",
+    "@zhin.js/mcp-feature": "1.1.8",
+    "@zhin.js/skill": "1.1.8",
+    "@zhin.js/tool": "1.1.8"
   },
   "repository": {
     "type": "git",