@mzzsfy/dsh-cron-board 0.5.0 → 0.6.0

package/README.md

@@ -55,4 +55,4 @@ node --test "test/*.test.mjs"              # 测试
 
 ## dsh 版本兼容
 
-三版本全部通过:cron 看板渲染与启停、与侧边栏联动(侧栏标签页形态)、激活 live。0.1.6 新侧栏标签页系统下联动开关双态均验证通过。
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)兼容通过:cron 看板渲染与编辑器、侧栏入口、激活 live。0.1.6 新侧栏标签页系统下联动开关双态均验证通过;0.1.7-rc.1 修复 ui-settings 写失败打崩宿主(await 化 + 路由级 catch 降级),内置插件页改版后设置开关卡锚缺失(宿主演进),看板面实测正常。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-cron-board",
   "description": "轻量级定时任务看板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/api.mjs

@@ -297,8 +297,8 @@ export function createApi({ store, logger, executor, scheduler, periodic, sessio
         if (typeof body.sidebarTab === 'boolean') patch.sidebarTab = body.sidebarTab
         if (!Object.keys(patch).length) return sendJson(res, 400, { error: '无有效字段' })
         if (typeof updateUiSettings !== 'function') return sendJson(res, 200, { ok: false, error: '设置服务不可用' })
-        updateUiSettings(patch)
-        sendJson(res, 200, { ok: true, ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false } })
+        const persisted = await updateUiSettings(patch)
+        sendJson(res, 200, { ok: persisted, ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false } })
       },
     },
     {

package/src/client.js

@@ -1069,6 +1069,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     const TAB_ID = 'cron-board:board'
     const PANEL_ID = 'cron-board'
     const PANEL_LABEL = '定时任务'
+    const PKG_ID = '@mzzsfy/dsh-cron-board'
 
     // 设置>插件页卡片:官方 PluginCard 形制(名称/描述头部 + chevron 折叠 + 行内开关);better-sidebar 在场可切换,否则仅展示禁用态
     const CARD_TITLE = '定时任务'
@@ -1219,6 +1220,15 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             () => h(CronBoardPluginCard, { ctx }),
           )
         }), 'cron-board settings card')
+        // 插件管理页(0.1.7-rc.1+)包详情配置卡:key = 包名,管理页 ledger.bundles 判定 section
+        // 在场;卡片自包含(只调本插件 API,不触宿主 settings)。两代槽位并存注册:inject 是
+        // 声明生命周期效应,错误世代宿主永不声明该槽,回调挂起不执行,零成本
+        ctx.effect(() => ctx.slots.inject('plugins.bundle.config', function* () {
+          yield ctx.slots.register(
+            { name: 'plugins.bundle.config', key: PKG_ID },
+            () => h(CronBoardPluginCard, { ctx }),
+          )
+        }), 'cron-board plugin manager card')
         ctx.inject(['betterSidebar'], (bsCtx) => {
           currentSidebar = bsCtx.betterSidebar
           applyPref()

package/src/index.js

@@ -43,6 +43,21 @@ const SETTINGS_SCHEMA = schemastery.object({
   sidebarTab: schemastery.boolean().default(false).description('看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面)'),
 })
 
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构);legacy 宿主经
+// settings.register 注册同名命名空间。根级 volatile 包装:0.1.7 下整节为 live
+// 表单,节写经 loader 原地热更;旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = volatileWrap(SETTINGS_SCHEMA)
+
+function volatileWrap(schema) {
+  return typeof schema.volatile === 'function' ? schema.volatile() : schema
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
 export function resolveDataDir(env = process.env) {
   const override = env[DATA_DIR_ENV]
   if (override && override.trim() !== '') return override.trim()
@@ -139,17 +154,42 @@ export function apply(ctx, config) {
     const value = readSettingValue(name)
     return typeof value === 'boolean' ? value : fallback
   }
-  // 客户端设置面板写入通道:settings 服务在场时按命名空间合并补丁
-  function updateUiSettings(patch) {
+  // 配置面双形态(maintain 同构,判定一律延迟到使用点,settings 挂载时序无保证):
+  // legacy(≤0.1.6)settings 服务 register/get/update 命名空间语义;
+  // 0.1.7+ 静态 Config 导出生成节表单,读经 volatile ref 解包,写经 configEditor
+  const legacySettingsFace = () => {
     const settings = ctx.get('settings')
-    if (!settings || typeof settings.update !== 'function') return false
-    settings.update(SETTINGS_NS, patch)
+    return typeof settings?.register === 'function' && typeof settings?.update === 'function'
+  }
+  // 0.1.7 写路径:configEditor.edit 定位本条目(fiber.entry,与命名空间解耦),
+  // change 回调合并落 profile patch;仅 volatile 字段变化时 loader 原地热更不重启
+  async function persistPatch(patch) {
+    if (legacySettingsFace()) {
+      await ctx.get('settings').update(SETTINGS_NS, patch)
+      return true
+    }
+    const editor = ctx.get('configEditor')
+    const entry = ctx.fiber?.entry
+    if (!editor || typeof editor.edit !== 'function' || !entry) return false
+    await editor.edit(entry, (current) => ({ ...current, ...patch }))
     return true
   }
+  // 客户端设置面板写入通道。必须 await:宿主写失败在异步段抛出(0.1.5 前
+  // settings 对未注册命名空间 "No configurable plugin entry" 实测打崩宿主),
+  // await 后异常传播到 api.handle 的路由级 catch,降级为 400 响应,宿主存活
+  async function updateUiSettings(patch) {
+    return persistPatch(patch)
+  }
   function readSettingValue(name) {
-    const settings = ctx.get('settings')
-    const scope = settings && settings.get ? settings.get(SETTINGS_NS) : undefined
-    return scope ? scope[name] : undefined
+    try {
+      const settings = ctx.get('settings')
+      // 双形读:legacy settings 命名空间;0.1.7+ apply 入参 config 整节解包
+      const scope = settings && settings.get ? settings.get(SETTINGS_NS) : unwrapVolatile(config)
+      return scope ? scope[name] : undefined
+    } catch {
+      // 与写入同防:宿主 settings 对未注册命名空间抛错时读面降级为缺省
+      return undefined
+    }
   }
   function readTickMs() {
     return Math.max(MIN_TICK_MS, readNumber('tickSeconds', DEFAULT_TICK_MS / 1000) * 1000)
@@ -183,7 +223,14 @@ export function apply(ctx, config) {
   })
 
   ctx.inject(['settings'], (sctx) => {
-    if (typeof sctx.settings.register !== 'function') return
+    // 方法面守卫:settings 服务缺 register 面(0.1.7 已移除)即走新形态分支
+    if (typeof sctx.settings.register !== 'function') {
+      // 0.1.7:原生自动设置页与本包插件卡重复,特性检测关闭(maintain 同构)
+      if (typeof sctx.settings?.configure === 'function') {
+        sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber))
+      }
+      return
+    }
     const scope = sctx.settings.register(SETTINGS_NS, SETTINGS_SCHEMA, { base: config })
     // tick 周期等设置变更即时对账(重建 interval)
     if (scope && typeof scope.watch === 'function') {

package/test/index.test.mjs

@@ -185,6 +185,36 @@ test('index:settings 注册 cron-board 命名空间且 timer 承载默认周期
   assert.deepEqual(intervals.map((entry) => entry.ms), [30 * 1000])
 })
 
+test('index:settings.update 异步拒绝(镜像 rc.1 无命名空间条目)被路由级 catch 接住降级 400,不打崩进程', async () => {
+  // Given settings.update 返回 rejected promise 的宿主形态(0.1.7-rc.1 L3 实测:
+  // "No configurable plugin entry 'cron-board'" 在异步段抛出,不 await 时逃逸成
+  // uncaughtException 打崩宿主;await 后由 api.handle 路由级 catch 接住)
+  const { ctx, settingsService } = makeFullCtx()
+  settingsService.update = () => Promise.reject(new Error("No configurable plugin entry 'cron-board'"))
+  delete settingsService.get
+  const captured = []
+  const ctx2 = {
+    ...ctx,
+    get(name) {
+      if (name === 'settings') return settingsService
+      return ctx.get(name)
+    },
+    webServer: { register(route) { captured.push(route); return () => {} } },
+  }
+  apply(ctx2)
+  const route = captured[0]
+  assert.ok(route)
+  const res = { status: null, payload: null }
+  res.writeHead = (status) => { res.status = status }
+  res.end = (text) => { res.payload = JSON.parse(text) }
+  const req = { method: 'POST', url: 'http://localhost/api/cron-board/ui-settings', headers: { 'content-type': 'application/json' } }
+  req.on = (event, fn) => { if (event === 'data') setImmediate(() => fn(Buffer.from(JSON.stringify({ sidebarTab: true })))); if (event === 'end') setImmediate(fn) }
+  await route.handler(req, res)
+  // Then 路由级 catch 接住,降级 400 系统级错误响应,进程存活(测试正常走完即证)
+  assert.equal(res.status, 400)
+  assert.ok(res.payload.error)
+})
+
 test('index:tickSeconds 设置变更经 watch 重建 interval', async () => {
   // Given 全服务桩,settings.register 的 watch 回调被捕获
   let watchFn = null
@@ -264,7 +294,188 @@ function waitForRecord(poll, timeoutMs = 10 * 1000) {
         }
         setTimeout(tick, 50)
       }).catch(reject)
+     }
+     tick()
+   })
+}
+
+// --- 0.1.7 settings 面双形适配(maintain a913c2c 同构) ---
+
+// 0.1.7 形态装配桩:settings 无 register/get(宿主已移除),config 为整节单 ref 桩,
+// configEditor 桩经 change 合并后原样写回(模拟 loader 仅 volatile 变化的原地热更)
+function makeRc17Ctx({ configStore = {}, configEditorAvailable = true, configureAvailable = true } = {}) {
+  const routes = new Map()
+  const calls = { editCalls: [], configureCalls: [], registerCalls: [] }
+  const config = { get: () => ({ ...configStore }) }
+  const settingsService = {}
+  if (configureAvailable) {
+    settingsService.configure = (presentation, owner) => {
+      calls.configureCalls.push({ presentation, owner })
+      return () => {}
     }
-    tick()
-  })
+  }
+  const configEditor = {
+    async edit(entry, change) {
+      calls.editCalls.push(entry)
+      const next = change({ ...configStore }, {})
+      for (const [key, value] of Object.entries(next)) configStore[key] = value
+    },
+  }
+  const effects = []
+  const ctx = {
+    calls,
+    fiber: { entry: { options: { id: 'cron-board', name: '@mzzsfy/dsh-cron-board' } } },
+    effect(fn, label) {
+      // 会话等待轮询为真实定时器形态:桩跳过(与 makeFullCtx 同款),其余同步执行
+      if (label === 'cron-board session wait') return
+      effects.push(fn)
+      fn()
+    },
+    get(name) {
+      if (name === 'settings') return settingsService
+      if (name === 'configEditor') return configEditorAvailable ? configEditor : undefined
+      if (name === 'agents') return { get: () => undefined }
+      if (name === 'sessionQuery') return { listSessions: async () => [] }
+      if (name === 'workspaceRegistry') return { archivedSessionIds: [] }
+      if (name === 'agentPresets') return { defaultId: '', list: async () => [] }
+      return undefined
+    },
+    inject(deps, fn) {
+      if (deps[0] === 'timer') {
+        fn({ interval(intervalFn) { return () => {} } })
+      }
+      if (deps[0] === 'settings') {
+        fn({
+          settings: settingsService,
+          effect(stubEffect) {
+            const disposer = stubEffect()
+            if (typeof disposer === 'function') effects.push(disposer)
+          },
+        })
+      }
+    },
+    webServer: {
+      register(route) {
+        routes.set(route.path, route.handler)
+        return () => {}
+      },
+    },
+  }
+  return { ctx, routes, config, configStore, calls, effects }
+}
+
+// ui-settings 请求走 prefix 路由(api.handle 按 method+segments 分发);
+// 需真实数据目录(getRuntime 装配 store),env 注入临时目录
+async function callApi(routes, path, body) {
+  const handler = routes.get('/api/cron-board')
+  assert.ok(handler, 'prefix 路由未注册')
+  const res = { status: null, payload: null }
+  res.writeHead = (status) => { res.status = status }
+  res.end = (text) => { res.payload = text ? JSON.parse(text) : null }
+  const req = new EventEmitter()
+  req.method = body === undefined ? 'GET' : 'POST'
+  req.url = 'http://localhost' + path
+  req.headers = { 'content-type': 'application/json' }
+  // 装配层初始化后才挂读体监听:桩事件须延后发射(与既有 post 桩同款)
+  setTimeout(() => {
+    if (body !== undefined) req.emit('data', Buffer.from(JSON.stringify(body)))
+    req.emit('end')
+  }, 80)
+  await handler(req, res)
+  return res
 }
+
+test('Config 导出契约:根级 volatile 包装,validate 产整节单 ref,默认值对拍', () => {
+  // Given 静态 Config 导出(0.1.7 节表单事实源)
+  assert.ok(mod.Config, 'Config 导出必须在场')
+  // When 空配置校验
+  const resolved = mod.Config['~standard'].validate({})
+  // Then 产整节单 ref(get 协议),字段为 schema 默认值
+  assert.equal(resolved.issues, undefined)
+  const section = resolved.value.get()
+  assert.equal(section.tickSeconds, 30)
+  assert.equal(section.maxConcurrent, 2)
+  assert.equal(section.logKeepPerJob, 200)
+  assert.equal(section.maskEnvInPrompt, false)
+  assert.equal(section.sidebarTab, false)
+  // When 显式值校验
+  // Then 值透传
+  const provided = mod.Config['~standard'].validate({ sidebarTab: true }).value.get()
+  assert.equal(provided.sidebarTab, true)
+})
+
+test('0.1.7 形态:ui-settings GET 读 config 节值(ref 解包),非默认值', async (t) => {
+  // Given settings 无 register/get 的宿主 + config ref 携带用户值
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config } = makeRc17Ctx({ configStore: { sidebarTab: true, tickSeconds: 60 } })
+  apply(ctx, config)
+  // When GET ui-settings
+  const res = await callApi(routes, '/api/cron-board/status')
+  // Then 返回 config 节值
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('0.1.7 形态:ui-settings POST 经 configEditor.edit 落 fiber.entry 且持久合并', async (t) => {
+  // Given configEditor 桩记录 edit 调用
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config, configStore, calls } = makeRc17Ctx({ configStore: { tickSeconds: 60 } })
+  apply(ctx, config)
+  // When POST 写 sidebarTab
+  const res = await callApi(routes, '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then edit 定位本条目,合并写回,响应 200 携新值
+  assert.equal(res.status, 200)
+  assert.equal(calls.editCalls.length, 1)
+  assert.equal(calls.editCalls[0].options.id, 'cron-board')
+  assert.equal(configStore.sidebarTab, true)
+  assert.equal(configStore.tickSeconds, 60)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('0.1.7 形态:configEditor 缺失即 200 ok:false 拒写,不崩溃', async (t) => {
+  // Given configEditor 服务缺席
+  const dir = await mkdtemp(join(tmpdir(), 'cron-board-rc17-'))
+  t.after(async () => {
+    delete process.env.DSH_CRON_BOARD_DATA_DIR
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
+  process.env.DSH_CRON_BOARD_DATA_DIR = dir
+  const { ctx, routes, config } = makeRc17Ctx({ configEditorAvailable: false })
+  apply(ctx, config)
+  // When POST 写设置
+  const res = await callApi(routes, '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then ok:false 拒写(api 层 persisted=false 语义),进程存活(测试走完即证)
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ok, false)
+})
+
+test('0.1.7 形态:settings.configure 在场即关闭原生自动页,缺席静默跳过', () => {
+  // Given configure 在场
+  const { ctx, calls, config } = makeRc17Ctx()
+  apply(ctx, config)
+  // Then 关闭自动页,owner 为本插件 fiber
+  assert.deepEqual(calls.configureCalls, [{ presentation: { auto: false }, owner: ctx.fiber }])
+  // Given configure 缺席
+  const bare = makeRc17Ctx({ configureAvailable: false })
+  // When apply
+  // Then 不抛错(测试走完即证)
+  apply(bare.ctx, bare.config)
+})
+
+test('0.1.7 形态:settings 注入回调不因 register 缺失抛错', () => {
+  // Given settings 桩全空方法面(比真实宿主更严)
+  const { ctx, config } = makeRc17Ctx({ configureAvailable: false })
+  // When apply
+  // Then 注入回调静默返回,无异常
+  apply(ctx, config)
+})

package/test/routes.test.mjs

@@ -324,10 +324,11 @@ test('status 路由:ui.sidebarTab 透出用户侧边栏移入偏好', async (t)
 })
 
 test('ui-settings 路由:布尔补丁经 updateUiSettings 写入并回读', async (t) => {
-  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效)
+  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效);
+  // 写入桩 async 返回 true 镜像持久化成功契约(宿主 update 为异步面)
   let stored = false
   const { api } = await makeApi(t, {
-    updateUiSettings: (patch) => { if (typeof patch.sidebarTab === 'boolean') stored = patch.sidebarTab },
+    updateUiSettings: async (patch) => { if (typeof patch.sidebarTab === 'boolean') { stored = patch.sidebarTab; return true } return false },
     readSidebarTab: () => stored,
   })
   // When POST 开关开

package/test/switch-guard.test.mjs

@@ -109,6 +109,11 @@ test('client.js 主页面双形态挂载契约(默认宿主全局面板;设置
   assert.match(source, /function CronBoardPluginCard/)
   assert.match(source, /'ui-settings'/)
   assert.match(source, /sidebarReady/)
+  // 插件管理页包详情配置卡(0.1.7-rc.1+ plugins.bundle.config,key=包名);两代槽位并存注册,
+  // 各自宿主只消费其一(旧宿主无 plugins.bundle.config 消费方,rc.1 无 settings.plugin.item 消费方)
+  assert.match(source, /const PKG_ID = '@mzzsfy\/dsh-cron-board'/)
+  assert.match(source, /ctx\.slots\.inject\('plugins\.bundle\.config'/)
+  assert.match(source, /name: 'plugins\.bundle\.config', key: PKG_ID/)
   // 挂载仲裁:偏好(status.ui.sidebarTab)驱动全局面板/扩展槽互斥
   assert.match(source, /applyPref\(\)/)
   assert.match(source, /ui\.sidebarTab/)