dsh-oh-my-terminal 0.2.2 → 0.2.4

package/lib/index.js

@@ -1014,10 +1014,28 @@ function createSettingsBridgeRoutes(settings, namespace, runtimeProfiles) {
 }
 
 // src/settings/index.ts
-function registerSettingsIntegration(ctx, runtimeProfiles) {
+function registerSettingsNamespace(ctx, schema) {
   ctx.inject(["settings"], (sctx) => {
-    sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
+    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);
@@ -1139,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);
@@ -1149,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();
@@ -1277,7 +1296,7 @@ function apply(ctx, config) {
       upgradeDisposers
     })
   });
-  registerSettingsIntegration(ctx, cachedProfiles);
+  registerSettingsIntegration(ctx, Config, cachedProfiles);
   ctx.effect(() => {
     return () => {
       disposeRoute();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-oh-my-terminal",
-  "version": "0.2.2",
+  "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 -> 会话记录 */
@@ -521,9 +528,10 @@ export function apply(ctx: Context, config: Config): void {
   });
 
   // —— settings 集成（可选，软探测）——
-  // 传入 cachedProfiles：让 describe 端点返回运行时合并探测结果后的完整配置表，
-  // 而非配置系统持久化值（可能是空串），设置页面才能看到自动探测到的终端项
-  registerSettingsIntegration(ctx, cachedProfiles);
+  // 传入 Config schema：auto=false 下命名空间需显式注册（见 settings/index.ts），
+  // 缺注册则设置卡片静默不渲染；cachedProfiles 让 describe 端点返回运行时合并
+  // 探测结果后的完整配置表，而非配置系统持久化值（可能是空串）
+  registerSettingsIntegration(ctx, Config, cachedProfiles);
 
   // —— 插件销毁清理 ——
   ctx.effect(() => {

package/src/settings/index.ts

@@ -37,23 +37,80 @@ export { createSettingsBridgeRoutes } from './bridge.js';
  * 逐一调用清理。
  *
  * @param ctx - cordis 上下文（插件主入口的 apply 参数）
+ * @param schema - 插件 Config 的 schemastery schema，用于注册 settings 命名空间。
+ *   auto=false 下服务不会自动注册，缺了这一步 describe/mutate 恒报「命名空间
+ *   不存在」，前端配置卡片静默不渲染（无报错、无入口）
  * @param runtimeProfiles - 运行时终端配置表（探测+合并后的完整数组），传给 bridge
  *   供 describe 端点覆盖持久化的 terminalProfiles 值
  */
-export function registerSettingsIntegration(
-  ctx: Context,
-  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));
+    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;
+      });
+    }
+
+    // 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

@@ -0,0 +1,132 @@
+/**
+ * @file settings 集成注册单元测试
+ * @description 回归锁定 registerSettingsIntegration 的命名空间注册契约：
+ *              注册是 settings 服务注册表的唯一入口，缺注册时 describe/mutate
+ *              恒报「命名空间不存在」，前端配置卡片静默不渲染（无报错、无入口）。
+ *              同时锁定宿主兼容面：旧宿主（0.1.5 系）的 settings 服务没有
+ *              configure 方法，集成不得因此抛错中断注册——曾因无守卫调用
+ *              configure 抛 TypeError，把随后的 register 一并挡掉。
+ *              本测试用假 settings 服务断言：注册确实发生且 schema 原样透传、
+ *              无 configure 的宿主不炸、有 configure 时才调用、重复注册幂等、
+ *              其余注册失败如实上抛（不把失败包装成成功）。
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import type { Context } from '@deepseek-ai/cordis';
+import { registerSettingsIntegration, SETTINGS_NS } from '../../src/settings/index.js';
+
+/** register 调用记录 */
+interface RegisterCall {
+  /** 被注册的命名空间 */
+  ns: string;
+  /** 传入的 schema 引用 */
+  schema: unknown;
+}
+
+/** 假 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: 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 {
+        get: () => ({}),
+        watch: () => (): void => undefined,
+        update: async (): Promise<void> => undefined,
+        replace: async (): Promise<void> => undefined,
+      };
+    };
+  }
+  if (options.withConfigure === true) {
+    settings.configure = (value: unknown): void => {
+      configureCalls.push(value);
+    };
+  }
+  return { settings, registerCalls, configureCalls };
+}
+
+/** 假 cordis 上下文：inject 直接回调，effect 立即执行并回收 cleanup */
+function makeFakeContext(settings: unknown): Context {
+  const ctx = {
+    fiber: {},
+    inject(_deps: string[], callback: (sctx: Record<string, unknown>) => void): void {
+      callback({
+        settings,
+        webServer: { register: () => (): void => undefined },
+        effect: (fn: () => unknown): void => {
+          const returned = fn();
+          if (typeof returned === 'function') returned();
+        },
+      });
+    },
+  };
+  return ctx as unknown as Context;
+}
+
+describe('settings 集成注册', () => {
+  it('旧宿主（无 configure）下仍完成命名空间注册，不抛错', () => {
+    const { settings, registerCalls, configureCalls } = makeFakeSettings();
+    const schema = { marker: 'config-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 不上抛', () => {
+    const { settings } = makeFakeSettings({
+      failRegisterWith: new Error('settings namespace "terminal-panel" is already registered'),
+    });
+    assert.doesNotThrow(() => {
+      registerSettingsIntegration(makeFakeContext(settings), { marker: 'x' });
+    });
+  });
+
+  it('其他注册失败如实上抛，不把失败包装成成功', () => {
+    const { settings } = makeFakeSettings({
+      failRegisterWith: new Error('settings namespace "terminal-panel" 存储段损坏'),
+    });
+    assert.throws(
+      () => registerSettingsIntegration(makeFakeContext(settings), { marker: 'x' }),
+      /存储段损坏/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);
+  });
+});