dsh-oh-my-terminal 0.2.3 → 0.2.4

package/lib/index.js

@@ -1014,17 +1014,28 @@ function createSettingsBridgeRoutes(settings, namespace, runtimeProfiles) {
 }
 
 // src/settings/index.ts
-function registerSettingsIntegration(ctx, schema, runtimeProfiles) {
+function registerSettingsNamespace(ctx, schema) {
   ctx.inject(["settings"], (sctx) => {
-    sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
-    const registrar = sctx.settings;
-    try {
-      registrar.register(SETTINGS_NS, schema);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (!message.includes("already registered")) throw error;
+    const facade = sctx.settings;
+    if (typeof facade.configure === "function") {
+      const configure = facade.configure;
+      sctx.effect(() => {
+        const cleanup = configure.call(facade, { auto: false }, ctx.fiber);
+        return typeof cleanup === "function" ? cleanup : () => void 0;
+      });
+    }
+    if (typeof facade.register === "function") {
+      try {
+        facade.register(SETTINGS_NS, schema);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes("already registered")) throw error;
+      }
     }
   });
+}
+function registerSettingsIntegration(ctx, schema, runtimeProfiles) {
+  registerSettingsNamespace(ctx, schema);
   ctx.inject(["webServer", "settings"], (sctx) => {
     sctx.effect(() => {
       const routes = createSettingsBridgeRoutes(sctx.settings, SETTINGS_NS, runtimeProfiles);
@@ -1146,7 +1157,7 @@ function apply(ctx, config) {
       ctx.inject(["settings"], (sctx) => {
         const settings = sctx.settings;
         if (typeof settings.update !== "function") return;
-        void settings.update(PKG_NAME.replace(/^dsh-/, ""), { terminalProfiles: payload }).then(() => {
+        void settings.update(SETTINGS_NS, { terminalProfiles: payload }).then(() => {
           log3.info(`\u7EC8\u7AEF\u914D\u7F6E\u8868\u5DF2\u521D\u59CB\u5316\uFF1A\u63A2\u6D4B\u5230 ${merged.length} \u4E2A\u7EC8\u7AEF`);
         }).catch((error) => {
           const msg = error instanceof Error ? error.message : String(error);
@@ -1156,6 +1167,7 @@ function apply(ctx, config) {
     }
     return merged;
   }
+  registerSettingsNamespace(ctx, Config);
   const cachedProfiles = prepareProfiles();
   const sessions = /* @__PURE__ */ new Map();
   const upgradeDisposers = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-oh-my-terminal",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "DSH Web GUI 底部终端面板插件——node-pty 驱动的多标签交互式终端（Windows ConPTY / POSIX openpty）",
   "type": "module",
   "license": "Apache-2.0",

package/src/index.ts

@@ -61,7 +61,7 @@ import { createWsHandlers } from './ws-handler.js';
 import { createRouteHandler } from './routes.js';
 import type { CreateSessionOptions } from './routes.js';
 import { makeId, getSessionCounter, resolveSpawn, resolveSessionCwd } from './routes.js';
-import { registerSettingsIntegration } from './settings/index.js';
+import { registerSettingsIntegration, registerSettingsNamespace, SETTINGS_NS } from './settings/index.js';
 import type { TerminalProfile } from './terminal/index.js';
 import { detectTerminalProfiles, mergeProfiles } from './terminal/index.js';
 
@@ -317,7 +317,10 @@ export function apply(ctx: Context, config: Config): void {
       ctx.inject(['settings'], (sctx) => {
         const settings = sctx.settings as { update?: (ns: string, patch: object) => Promise<void> };
         if (typeof settings.update !== 'function') return;
-        void settings.update(PKG_NAME.replace(/^dsh-/, ''), { terminalProfiles: payload })
+        // 命名空间必须与 settings 集成注册的 SETTINGS_NS 逐字一致——
+        // 此前误用包名派生串（PKG_NAME 去前缀 = 'oh-my-terminal'），与注册的
+        // 'terminal-panel' 对不上，首次落盘恒报「namespace not registered」
+        void settings.update(SETTINGS_NS, { terminalProfiles: payload })
           .then(() => { log.info(`终端配置表已初始化：探测到 ${merged.length} 个终端`); })
           .catch((error: unknown) => {
             const msg = error instanceof Error ? error.message : String(error);
@@ -329,6 +332,10 @@ export function apply(ctx: Context, config: Config): void {
   }
 
   /** 启动时求值的终端配置表（探测 + 合并结果） */
+  // 命名空间注册必须先于 prepareProfiles 的首跑写回（时序竞态：写回早于注册会
+  // 报「namespace is not registered」）——故在此提前注册，settings/index.ts
+  // 内部保留幂等兜底
+  registerSettingsNamespace(ctx, Config);
   const cachedProfiles: TerminalProfile[] = prepareProfiles();
 
   /** id -> 会话记录 */

package/src/settings/index.ts

@@ -43,38 +43,74 @@ export { createSettingsBridgeRoutes } from './bridge.js';
  * @param runtimeProfiles - 运行时终端配置表（探测+合并后的完整数组），传给 bridge
  *   供 describe 端点覆盖持久化的 terminalProfiles 值
  */
-export function registerSettingsIntegration(
-  ctx: Context,
-  schema: unknown,
-  runtimeProfiles?: unknown[],
-): void {
-  // 1. 注册 settings 命名空间 + 关闭自动模式——软探测，服务不存在时不激活
+/**
+ * 注册 settings 命名空间（幂等，须先于任何 settings 读写）。
+ *
+ * 命名空间注册是 settings 服务注册表的唯一入口；首次配置落盘（prepareProfiles
+ * 的首跑写回）等读写都依赖它——必须在 apply 早期调用本函数，晚于首次写回会
+ * 报「namespace is not registered」（时序竞态）。重复注册（热重载、重复 apply、
+ * 以及 registerSettingsIntegration 的兜底调用）抛 "already registered"，作为幂等
+ * 情形吞掉；其余注册失败（如存储段损坏）如实上抛，不把失败包装成成功。
+ *
+ * @param ctx - cordis 上下文
+ * @param schema - 插件 Config 的 schemastery schema
+ */
+export function registerSettingsNamespace(ctx: Context, schema: unknown): void {
+  // 注册命名空间 +（可选）关闭自动模式——软探测，服务不存在时不激活
   ctx.inject(['settings'], (sctx) => {
-    // settings.configure({ auto: false }, fiber) 关闭自动模式：
+    /** settings 服务能力面（不同宿主版本暴露面不同，逐能力探测） */
+    interface SettingsFacade {
+      /** 新宿主可选能力：关闭自动写回；旧宿主（0.1.5 系）无此方法 */
+      configure?: (options: { auto: boolean }, fiber?: unknown) => void;
+      /**
+       * 注册命名空间 schema；重复注册抛 "already registered"。
+       * 可选——宿主 SettingsForms 靠 cordis loader entries 发现命名空间，
+       * 不一定提供此方法（如 0.1.7-rc.1 的 SettingsForms 无 register）。
+       */
+      register?: (ns: string, schema: unknown) => unknown;
+    }
+    const facade = sctx.settings as unknown as SettingsFacade;
+
+    // configure 仅在宿主提供时调用——0.1.5 系宿主的 settings 服务没有该方法，
+    // 直接调用会 TypeError 并中断本回调的后续初始化（包括下面的命名空间注册）：
     // - auto=true：settings 服务自动从 profile patch 读配置并写回插件 Config
     // - auto=false：插件自行管理配置（本插件的 Config 字段都是 volatile 引用，
     //   由 cordis loader 注入，无需 settings 服务二次写入）
     //
     // fiber 参数绑定配置生命周期到当前 effect——effect 销毁时配置自动清理
-    sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
-
-    // auto=false 同时关闭了命名空间的自动注册——必须在此显式 register，否则
-    // describe/mutate 恒报「命名空间不存在」，前端配置卡片静默不渲染。重复注册
-    // （热重载、重复 apply）抛 "already registered"，作为幂等情形吞掉；其余注册
-    // 失败如实上抛，不把失败包装成成功。
-    /** settings 服务注册面的最小鸭子类型（对齐官方 SettingsProvider.register） */
-    interface SettingsRegistrar {
-      /** 注册命名空间 schema；重复注册抛 "already registered" */
-      register(ns: string, schema: unknown): unknown;
+    if (typeof facade.configure === 'function') {
+      const configure = facade.configure;
+      sctx.effect(() => {
+        const cleanup = configure.call(facade, { auto: false }, ctx.fiber);
+        // effect 要求回调返回清理函数；configure 的返回值即其注册的清理效应
+        return typeof cleanup === 'function' ? cleanup : (): void => undefined;
+      });
     }
-    const registrar = sctx.settings as unknown as SettingsRegistrar;
-    try {
-      registrar.register(SETTINGS_NS, schema);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (!message.includes('already registered')) throw error;
+
+    // register 同样逐能力探测——宿主 SettingsForms 靠 cordis loader entries
+    // （configEditor.configuration()）发现命名空间，不一定提供 register 方法
+    // （0.1.7-rc.1 的 SettingsForms 无此方法）。方法不存在时跳过，不抛 TypeError；
+    // 方法存在时重复注册（热重载、重复 apply）抛 "already registered"，作为幂等
+    // 情形吞掉；其余注册失败（如存储段损坏）如实上抛，不把失败包装成成功。
+    if (typeof facade.register === 'function') {
+      try {
+        facade.register(SETTINGS_NS, schema);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes('already registered')) throw error;
+      }
     }
   });
+}
+
+export function registerSettingsIntegration(
+  ctx: Context,
+  schema: unknown,
+  runtimeProfiles?: unknown[],
+): void {
+  // 0. 命名空间注册兜底（幂等）——正常由调用方在 apply 早期先行调用
+  //    registerSettingsNamespace，此处重复注册被吞
+  registerSettingsNamespace(ctx, schema);
 
   // 2. 注册 settings bridge 路由（describe + mutate）——软探测，服务不存在时不激活
   ctx.inject(['webServer', 'settings'], (sctx) => {

package/tests/unit/settings-integration.test.ts

@@ -1,11 +1,14 @@
 /**
  * @file settings 集成注册单元测试
  * @description 回归锁定 registerSettingsIntegration 的命名空间注册契约：
- *              auto=false 下 settings 服务不会自动注册命名空间，插件必须显式
- *              register(SETTINGS_NS, schema)，否则 describe/mutate 恒报
- *              「命名空间不存在」——前端配置卡片静默不渲染（无报错、无入口）。
+ *              注册是 settings 服务注册表的唯一入口，缺注册时 describe/mutate
+ *              恒报「命名空间不存在」，前端配置卡片静默不渲染（无报错、无入口）。
+ *              同时锁定宿主兼容面：旧宿主（0.1.5 系）的 settings 服务没有
+ *              configure 方法，集成不得因此抛错中断注册——曾因无守卫调用
+ *              configure 抛 TypeError，把随后的 register 一并挡掉。
  *              本测试用假 settings 服务断言：注册确实发生且 schema 原样透传、
- *              重复注册幂等吞掉、其余注册失败如实上抛（不把失败包装成成功）。
+ *              无 configure 的宿主不炸、有 configure 时才调用、重复注册幂等、
+ *              其余注册失败如实上抛（不把失败包装成成功）。
  */
 
 import { describe, it } from 'node:test';
@@ -21,19 +24,27 @@ interface RegisterCall {
   schema: unknown;
 }
 
-/** 假 settings 服务：只实现集成代码用到的 configure / register / describe / mutate */
-function makeFakeSettings(options: { failRegisterWith?: Error } = {}): {
+/** 假 settings 服务：可选 configure/register 模拟不同宿主版本的暴露面 */
+function makeFakeSettings(options: {
+  withConfigure?: boolean;
+  withRegister?: boolean;
+  failRegisterWith?: Error;
+} = {}): {
   settings: Record<string, unknown>;
   registerCalls: RegisterCall[];
   configureCalls: unknown[];
 } {
   const registerCalls: RegisterCall[] = [];
   const configureCalls: unknown[] = [];
-  const settings = {
-    configure(value: unknown): void {
-      configureCalls.push(value);
-    },
-    register(ns: string, schema: unknown): unknown {
+  const settings: Record<string, unknown> = {
+    describe: async (): Promise<unknown> => [],
+    mutate: async (): Promise<unknown> => undefined,
+    writable: true,
+  };
+  // register 可选——0.1.7-rc.1 的 SettingsForms 靠 cordis loader entries 发现
+  // 命名空间，不提供 register 方法
+  if (options.withRegister !== false) {
+    settings.register = (ns: string, schema: unknown): unknown => {
       if (options.failRegisterWith !== undefined) throw options.failRegisterWith;
       registerCalls.push({ ns, schema });
       return {
@@ -42,10 +53,13 @@ function makeFakeSettings(options: { failRegisterWith?: Error } = {}): {
         update: async (): Promise<void> => undefined,
         replace: async (): Promise<void> => undefined,
       };
-    },
-    describe: async (): Promise<unknown> => ({ ok: true }),
-    mutate: async (): Promise<unknown> => ({ ok: true }),
-  };
+    };
+  }
+  if (options.withConfigure === true) {
+    settings.configure = (value: unknown): void => {
+      configureCalls.push(value);
+    };
+  }
   return { settings, registerCalls, configureCalls };
 }
 
@@ -68,14 +82,24 @@ function makeFakeContext(settings: unknown): Context {
 }
 
 describe('settings 集成注册', () => {
-  it('settings 服务就位时显式注册命名空间并透传 schema', () => {
+  it('旧宿主（无 configure）下仍完成命名空间注册，不抛错', () => {
     const { settings, registerCalls, configureCalls } = makeFakeSettings();
     const schema = { marker: 'config-schema' };
-    registerSettingsIntegration(makeFakeContext(settings), schema, []);
+    assert.doesNotThrow(() => {
+      registerSettingsIntegration(makeFakeContext(settings), schema, []);
+    });
     assert.equal(registerCalls.length, 1);
     assert.equal(registerCalls[0]?.ns, SETTINGS_NS);
     assert.equal(registerCalls[0]?.schema, schema);
+    assert.deepEqual(configureCalls, []);
+  });
+
+  it('新宿主（有 configure）时调用 auto:false 并照常注册', () => {
+    const { settings, registerCalls, configureCalls } = makeFakeSettings({ withConfigure: true });
+    registerSettingsIntegration(makeFakeContext(settings), { marker: 'x' });
     assert.deepEqual(configureCalls, [{ auto: false }]);
+    assert.equal(registerCalls.length, 1);
+    assert.equal(registerCalls[0]?.ns, SETTINGS_NS);
   });
 
   it('重复注册视为幂等情形，吞掉 already registered 不上抛', () => {
@@ -96,4 +120,13 @@ describe('settings 集成注册', () => {
       /存储段损坏/u,
     );
   });
+
+  it('宿主无 register 方法时不抛 TypeError（靠 cordis loader entries 发现命名空间）', () => {
+    const { settings, registerCalls } = makeFakeSettings({ withRegister: false });
+    assert.doesNotThrow(() => {
+      registerSettingsIntegration(makeFakeContext(settings), { marker: 'x' });
+    });
+    // 宿主无 register——registerCalls 为空，但不抛错
+    assert.equal(registerCalls.length, 0);
+  });
 });