@zhin.js/host-http 1.1.6 → 1.1.7

package/README.md

@@ -70,3 +70,12 @@ path; links outside the root, blocked path segments, and dangling links are deni
 checked through their nearest existing parent and checked again after parent creation. File-tree
 and environment-file inventory use the same boundary. This covers existing symlink layouts; it does
 not provide an OS sandbox against a local process concurrently replacing directories during access.
+
+
+### Saved configuration explanations
+
+The full-scope `config:explain` Console RPC reuses the composition root's
+`PluginManagementPort.explainConfiguration(instanceKey, expectedRevision)` authority.
+The route returns metadata only, rejects demo before reading configuration, and normalizes
+errors without forwarding validator details or causes. It does not apply/restart the Runtime,
+expand values for clients, execute plugin code, or perform platform/network actions.

package/lib/console-rpc.d.ts

@@ -1,6 +1,6 @@
 import type { AuthScope } from './token-registry.js';
 import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
-import { type ConsoleConfigSource, type ConsoleEndpointSummary } from '@zhin.js/console-protocol';
+import { type ConsoleConfigSource, type ConsoleConfigExplanation, type ConsoleEndpointSummary } from '@zhin.js/console-protocol';
 import { type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
 /**
  * Console RPC 请求结构：未锚定 endpoint 的会话地址（结构对齐
@@ -99,6 +99,7 @@ export interface PluginVerificationResult {
     readonly evidence: readonly string[];
 }
 export interface PluginManagementPort {
+    explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
     inspect?(packageName: string): Promise<PluginManagementState>;
     apply?(packageName: string, expectedProjectRevision?: string): Promise<{
         readonly requested: boolean;

package/lib/console-rpc.js

@@ -75,6 +75,29 @@ export async function dispatchRuntimeConsoleRpc(message, ctx) {
             emit({ requestId, data: pages });
             return payloads;
         }
+        case CONFIG_RPC.EXPLAIN: {
+            if (ctx.authScope !== 'full') {
+                emit({ requestId, error: 'Full scope required' });
+                return payloads;
+            }
+            const { instanceKey, expectedRevision } = message;
+            if (typeof instanceKey !== 'string' || instanceKey.length > 128 || !/^[a-z0-9][a-z0-9-]*$/u.test(instanceKey)
+                || typeof expectedRevision !== 'string' || !/^[a-f0-9]{64}$/u.test(expectedRevision)) {
+                emit({ requestId, error: '精确 instanceKey 与已读取的 expectedRevision 必填' });
+                return payloads;
+            }
+            if (!ctx.pluginManagement?.explainConfiguration) {
+                emit({ requestId, error: '配置解释尚未配置' });
+                return payloads;
+            }
+            try {
+                emit({ requestId, data: await ctx.pluginManagement.explainConfiguration(instanceKey, expectedRevision) });
+            }
+            catch {
+                emit({ requestId, error: '配置解释未确认，请重新读取文件版本与当前运行状态；原配置未改动。' });
+            }
+            return payloads;
+        }
         case CONFIG_RPC.GET_SOURCE: {
             try {
                 const config = ctx.readConfigSource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,11 +17,11 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.9",
+    "@zhin.js/console-protocol": "1.1.10",
     "@zhin.js/host-http-contract": "1.1.1",
     "@zhin.js/logger": "1.1.2",
     "@zhin.js/schedule": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.1.14"
+    "@zhin.js/plugin-runtime": "1.1.15"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/console-rpc.ts

@@ -4,6 +4,7 @@ import {
   CONFIG_RPC,
   ENDPOINT_RPC,
   type ConsoleConfigSource,
+  type ConsoleConfigExplanation,
   type ConsoleEndpointSummary,
   assertDemoConsoleRpcAllowed,
 } from '@zhin.js/console-protocol';
@@ -136,6 +137,7 @@ export interface PluginVerificationResult {
 }
 
 export interface PluginManagementPort {
+  explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
   inspect?(packageName: string): Promise<PluginManagementState>;
   apply?(packageName: string, expectedProjectRevision?: string): Promise<{ readonly requested: boolean; readonly state: PluginManagementState }>;
   verificationPlan?(packageName: string): Promise<PluginVerificationPlan>;
@@ -332,6 +334,18 @@ export async function dispatchRuntimeConsoleRpc(
       emit({ requestId, data: pages });
       return payloads;
     }
+    case CONFIG_RPC.EXPLAIN: {
+      if (ctx.authScope !== 'full') { emit({ requestId, error: 'Full scope required' }); return payloads; }
+      const { instanceKey, expectedRevision } = message;
+      if (typeof instanceKey !== 'string' || instanceKey.length > 128 || !/^[a-z0-9][a-z0-9-]*$/u.test(instanceKey)
+        || typeof expectedRevision !== 'string' || !/^[a-f0-9]{64}$/u.test(expectedRevision)) {
+        emit({ requestId, error: '精确 instanceKey 与已读取的 expectedRevision 必填' }); return payloads;
+      }
+      if (!ctx.pluginManagement?.explainConfiguration) { emit({ requestId, error: '配置解释尚未配置' }); return payloads; }
+      try { emit({ requestId, data: await ctx.pluginManagement.explainConfiguration(instanceKey, expectedRevision) }); }
+      catch { emit({ requestId, error: '配置解释未确认，请重新读取文件版本与当前运行状态；原配置未改动。' }); }
+      return payloads;
+    }
     case CONFIG_RPC.GET_SOURCE: {
       try {
         const config: ConsoleConfigSource = ctx.readConfigSource