@mzzsfy/dsh-shell-select 0.3.1 → 0.4.1

package/test/client-render.test.mjs

@@ -0,0 +1,169 @@
+// 渲染守卫:全量执行 client.js 工厂(React 桩),实际调用注册出的 toolview
+// 组件——纯文本/LOGIC 提取守卫抓不住的渲染期未定义引用(model 丢失事故)在此暴露。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const source = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
+
+function reactStub() {
+  // 函数组件即时执行(模拟渲染语义):组件体内的未定义引用/坏访问当场抛出
+  const createElement = (type, props, ...children) => {
+    if (typeof type === 'function') return type(props ?? {})
+    return { type, props, children }
+  }
+  return {
+    createElement,
+    useState: (init) => [typeof init === 'function' ? init() : init, () => {}],
+    useEffect: () => {},
+  }
+}
+
+// 加载 client.js 并执行 apply,返回 slots 注册面
+function loadClient() {
+  const React = reactStub()
+  const registrations = []
+  const slots = {
+    inject: (_name, factory) => factory(),
+    register: (meta, component) => registrations.push({ meta, component }),
+  }
+  const document = {
+    documentElement: { lang: 'zh-CN' },
+    createElement: () => ({ setAttribute: () => {}, remove: () => {}, style: {} }),
+    head: { appendChild: () => {} },
+  }
+  let loaded
+  const window = { __ModuleLoader__: { load: (definition) => { loaded = definition } } }
+  new Function('window', 'document', 'navigator', source)(window, document, {}, undefined)
+  assert.notEqual(loaded, undefined, 'client.js 未调用 __ModuleLoader__.load')
+  const ctx = {
+    effect(fn) {
+      return fn()
+    },
+    slots,
+  }
+  loaded.factory((name) => {
+    if (name === 'react') return React
+    // 其余模块(primitives 等)按缺席处理:抛错触发 client 内 try/catch 降级
+    throw new Error('module not available: ' + name)
+  }).apply(ctx)
+  return registrations
+}
+
+function toolviewOf(registrations, key) {
+  const view = registrations.find((item) => item.meta.name === 'tool.call.toolview' && item.meta.key === key)
+  assert.notEqual(view, undefined, `缺少 key=${key} 的 toolview 注册`)
+  return view.component
+}
+
+// 已定调用块(官方形态:kind 字段在)
+function settledBlock(argsRaw, text) {
+  return {
+    kind: 'tool',
+    callId: 'c1',
+    call: { callId: 'c1', name: 'shell', argsRaw },
+    content: [{ type: 'text', text }],
+  }
+}
+
+test('渲染守卫:settled terminal 调用组件执行不抛(引用完整)', () => {
+  const component = toolviewOf(loadClient(), 'shell')
+  const element = component({
+    block: settledBlock(JSON.stringify({ command: 'git status', description: 'status' }), 'On branch main\n[exit code: 0]'),
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('渲染守卫:running 块组件执行不抛', () => {
+  const component = toolviewOf(loadClient(), 'pwsh')
+  const element = component({
+    block: { callId: 'c2', name: 'pwsh', argsRaw: JSON.stringify({ command: 'Start-Sleep 1', description: 'wait' }), time: Date.now() - 65_000 },
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('渲染守卫:运行中卡展开后可见命令全文与实时时长', () => {
+  const component = toolviewOf(loadClient(), 'shell')
+  // 默认收起:运行中折叠行 = 黄点 + 描述 + 时长,不含卡体
+  const element = component({
+    block: { callId: 'c3', name: 'shell', argsRaw: JSON.stringify({ command: 'npm run build', description: 'build' }), time: Date.now() - 65_000 },
+    cwd: 'C:\\repo',
+  })
+  assert.doesNotMatch(JSON.stringify(element), /sls-tv__body/)
+  assert.match(JSON.stringify(element), /1:05/)
+})
+
+test('渲染守卫:后台 ack 块(默认收起行 + 任务号徽标)组件执行不抛', () => {
+  const component = toolviewOf(loadClient(), 'bash')
+  const element = component({
+    block: settledBlock(JSON.stringify({ command: 'npm test', description: 'tests', run_in_background: true }), 'started background job bg-1'),
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('设置卡注册:settings.section 单卡 id shell-select', () => {
+  const registrations = loadClient()
+  const card = registrations.find((item) => item.meta.name === 'settings.section')
+  assert.notEqual(card, undefined)
+  assert.equal(card.meta.id, 'shell-select')
+})
+
+test('图标名守卫:0.1.7 primitives 字重后缀名在场,尺寸后缀旧名不在首选位', () => {
+  // 0.1.7 图标改名:尺寸从名字移除(IconApiOutline14 → IconApiOutlineRegular/Medium),
+  // 旧名 miss 使 IconApi 落淡灰 fallback 被当成"空白 icon"(实测事故)
+  assert.match(source, /'IconApiOutlineRegular'/)
+  assert.match(source, /'IconInspectOutlineRegular'/)
+  assert.doesNotMatch(source, /createElementOf\('IconApiOutline14'/)
+})
+
+test('名册单飞守卫:失败复位 promise,下次渲染重试(宿主启动窗口 404 不永久缺徽章)', () => {
+  // 旧实现 catch 静默吞错且 promise 不复位:boot 窗口期 404 后所有卡永久缺客户端徽章
+  assert.doesNotMatch(source, /catch\(\(\) => \{ \}\)/)
+  assert.match(source, /clientCatalogPromise = null/)
+})
+
+test('后台卡头部守卫:状态点缺省渲染(bg pill 即标识),非法 StateDot state 不再传入', () => {
+  // StateDot 合法 state 仅 done/warning/ongoing/error/idle;'none' 是编造值
+  assert.match(source, /dot: undefined/)
+  assert.match(source, /meta\.dot !== undefined \? TOOLVIEW_ICONS\.StateDot/)
+  assert.doesNotMatch(source, /dot: 'none'/)
+})
+
+test('hooks 恒序守卫:组件内 hook 调用必须全部位于第一个提前 return 之前', () => {
+  // 真实 React 的 hooks 链表按调用序对位:提前 return 之后的 hook 使不同
+  // 块形态(generic/terminal)的 hook 数量分叉 → "Rendered fewer hooks
+  // than expected" → 行组件树整棵卸载(shell 卡全消失事故)。React 桩无
+  // hooks 链表,渲染守卫抓不住,必须源码结构断言。
+  const extract = (name) => {
+    const begin = source.indexOf(`function ${name}(`)
+    assert.ok(begin >= 0, `缺函数 ${name}`)
+    const beginLine = source.slice(0, begin).split('\n').length
+    const body = source.slice(begin)
+    const end = body.indexOf('\n    function ', 1)
+    const scope = end >= 0 ? body.slice(0, end) : body
+    const hookLines = [...scope.matchAll(/\b(?:useState|useEffect|useRef|useMemo|useCallback)\(/g)]
+      .map((m) => beginLine + scope.slice(0, m.index).split('\n').length - 1)
+    return { hookLines, scopeLines: beginLine + scope.split('\n').length }
+  }
+  const earlyReturnLine = (scope, beginLine) => {
+    const m = /return h\(/.exec(scope)
+    return m === null ? Number.POSITIVE_INFINITY : beginLine + scope.slice(0, m.index).split('\n').length - 1
+  }
+  for (const name of ['ShellToolRow', 'GenericShellRow', 'CopyButton', 'RunningDuration', 'ShellSelectApp']) {
+    const { hookLines } = extract(name)
+    const scopeBody = source.slice(source.indexOf(`function ${name}(`))
+    const end = scopeBody.indexOf('\n    function ', 1)
+    const scope = end >= 0 ? scopeBody.slice(0, end) : scopeBody
+    const limit = earlyReturnLine(scope, source.slice(0, source.indexOf(`function ${name}(`)).split('\n').length)
+    for (const line of hookLines) {
+      assert.ok(line < limit, `${name} 的 hook 在第 ${line} 行,位于提前 return(第 ${limit} 行)之后:hooks 恒序被破坏`)
+    }
+  }
+})

package/test/config-entry.test.mjs

@@ -1,12 +1,12 @@
-// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
+// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import ShellSelectExecutor from '../src/executor.mjs'
-import { Config, buildArgv, defaultConfig } from '../src/config.mjs'
+import { resolveConfig, buildArgv, defaultConfig, entryById, requireEntry } from '../src/config.mjs'
 
 test('S5 schema 默认:条目 env 空对象、distro 空串,旧配置反序列化补默认', () => {
-  const config = Config({ shells: [{ id: 'w', name: 'WSL', kind: 'wsl' }], default: 'w' })
+  const config = resolveConfig({ shells: [{ id: 'w', name: 'WSL', kind: 'wsl' }], default: 'w' })
   const entry = config.shells[0]
   assert.deepEqual(entry.env, {})
   assert.equal(entry.distro, '')
@@ -32,7 +32,7 @@ test('S10 args 模板条目接管 argv,distro 不出现', () => {
 
 test('S6 entryFor 透传 env 与 distro;spawnSpec env 含条目键', () => {
   const cmdPath = process.execPath
-  const config = Config({
+  const config = resolveConfig({
     shells: [{ id: 'c', name: 'CMD', kind: 'cmd', path: cmdPath, env: { MSYSTEM: 'MINGW64' } }, { id: 'p', name: 'pwsh', kind: 'pwsh' }],
     default: 'c',
   })
@@ -45,19 +45,24 @@ test('S6 entryFor 透传 env 与 distro;spawnSpec env 含条目键', () => {
   assert.equal(spawned.env.NO_COLOR, '1')
 })
 
-test('S7 updateConfig 接受 env/distro 字段并落盘回读', async () => {
-  const section = Config({
+test('S7 web 行写路径接受 env/distro 字段并落盘', async () => {
+  const { SECTION_NS, buildFaces } = await import('../src/web-routes.mjs')
+  const section = resolveConfig({
     shells: [
       { id: 'p', name: 'pwsh', kind: 'pwsh' },
       { id: 'w', name: 'WSL', kind: 'wsl', distro: 'Debian', env: { LANG: 'C.UTF-8' } },
     ],
     default: 'p',
   })
-  const executor = new ShellSelectExecutor(stubCtxFor(section), section)
-  const next = await executor.updateConfig({})
+  const replaced = []
+  const ctx = { logger: { warn: () => {} } }
+  const settings = { describe: () => [{ ns: SECTION_NS, value: section }], replace: async (ns, next) => { replaced.push({ ns, next }) } }
+  const faces = buildFaces(ctx, settings)
+  const next = await faces.updateConfig({})
   const wsl = next.shells.find((entry) => entry.id === 'w')
   assert.equal(wsl.distro, 'Debian')
   assert.deepEqual(wsl.env, { LANG: 'C.UTF-8' })
+  assert.equal(replaced[0].ns, SECTION_NS)
 })
 
 function stubCtxFor(config) {

package/test/config.test.mjs

@@ -3,10 +3,11 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { Config, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+import { resolveConfig, resolveConfigStrict, coerceServiceable, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+import { assertServiceableConfig } from '../src/config.mjs'
 
 test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
-  const applied = Config({})
+  const applied = resolveConfig({})
   assert.deepEqual(applied, defaultConfig())
   assert.equal(applied.default, 'pwsh')
   assert.deepEqual(applied.shells.map((entry) => entry.id), ['pwsh', 'git-bash', 'cmd'])
@@ -17,7 +18,97 @@ test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
 })
 
 test('schema 拒绝未知 kind;default 跨字段一致性由 validate hook 与 requireEntry 兜底', () => {
-  assert.throws(() => Config({ shells: [{ id: 'x', name: 'X', kind: 'fish', path: '' }], default: 'x' }))
+  assert.throws(() => resolveConfig({ shells: [{ id: 'x', name: 'X', kind: 'fish', path: '' }], default: 'x' }))
+})
+
+test('落盘坏形态防御:volatile 字段被序列化成对象时降级默认,行构造不炸', () => {
+  // 事故:原生设置页/ref 序列化把 shells 落盘为 {},冷启动 Config 抛
+  // "expected array but got [object Object]" → 行死 → settings 无节 →
+  // 设置页 "no longer configurable" 死锁。类型不符的键必须降级默认。
+  const poisoned = {
+    shells: {},
+    deny: { 0: 'rm' },
+    default: 42,
+    timeoutMs: 'forever',
+    cwd: ['C:\\'],
+    good: 'ignored-by-schema',
+  }
+  const applied = resolveConfig(poisoned)
+  assert.deepEqual(applied, defaultConfig())
+  // 合法值原样保留,清洗不做过度剥离
+  const valid = resolveConfig({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'pwsh', deny: ['rm -rf'], cwd: 'C:\\tmp', timeoutMs: 5000 })
+  assert.equal(valid.shells.length, 1)
+  assert.equal(valid.default, 'pwsh')
+
+  // 执行面 strict:同款坏形态必须炸(宿主 resolve 产物须先解箱;静默降级
+  // 曾让行 config 永不生效,0.2.0-rc.2 真机实证)。宽容路径(上方)保留。
+  assert.throws(() => resolveConfigStrict(poisoned), /形态非法.*shells/)
+  // 合法输入与 undefined 缺省:strict 与宽容同产出
+  assert.deepEqual(resolveConfigStrict(valid), valid)
+  assert.deepEqual(resolveConfigStrict(undefined), defaultConfig())
+  assert.deepEqual(valid.deny, ['rm -rf'])
+  assert.equal(valid.cwd, 'C:\\tmp')
+  assert.equal(valid.timeoutMs, 5000)
+  // 非对象整体(null/数组/标量)= 无配置,出厂默认
+  for (const junk of [null, 'x', 42, ['shells']]) {
+    assert.deepEqual(resolveConfig(junk), defaultConfig())
+  }
+})
+
+// --- coerceServiceable:任意用户输入产出可服务配置(插件不因配置死) ---
+
+test('coerce:悬空 default 归 shells[0],空/全非法 shells 回落出厂默认', () => {
+  const { config, warnings } = coerceServiceable({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'nope' })
+  assert.equal(config.default, 'pwsh')
+  assert.ok(warnings.some((line) => line.includes('default')))
+  const emptied = coerceServiceable({ shells: [{ id: 'x', kind: 'fish' }], default: 'x' })
+  assert.deepEqual(emptied.config.shells.map((entry) => entry.id), ['pwsh', 'git-bash', 'cmd'])
+  assert.equal(emptied.config.default, 'pwsh')
+  assert.ok(emptied.warnings.length >= 2)
+})
+
+test('coerce:预算字段非正数降默认,deny 剔除不可编译条目,合法输入零告警原样', () => {
+  const { config, warnings } = coerceServiceable({
+    shells: [{ id: 'pwsh', kind: 'pwsh' }],
+    default: 'pwsh',
+    timeoutMs: -5,
+    graceMs: Number.MAX_SAFE_INTEGER,
+    deny: ['rm -rf', '(unclosed', '', 42],
+  })
+  assert.equal(config.timeoutMs, undefined)
+  assert.equal(config.graceMs, undefined)
+  assert.deepEqual(config.deny, ['rm -rf'])
+  assert.equal(warnings.length, 3)
+  const clean = coerceServiceable({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'pwsh' })
+  assert.equal(clean.warnings.length, 0)
+  // 产物必过可服务校验:任意输入不产出会炸挂载的配置
+  assertServiceableConfig(resolveConfig(clean.config))
+  assertServiceableConfig(resolveConfig(config))
+})
+
+test('冻结输入防御:volatile ref 深冻结快照喂入不改写不抛(挂载路径)', () => {  // 事故:cosmokit createVolatile 的 snapshot 对 volatile 值逐层 Object.freeze,
+  // 行 Config ref .get() 产物是深冻结对象;sanitizeConfigEntry 引用透传,
+  // schemastery resolve 原地改写入参(填默认)撞冻结 env 抛
+  // "Cannot assign to read only property 'MSYSTEM'" → 执行器挂载失败,
+  // 每次启动回滚官方 pwsh 链,shell 工具永不注册。
+  // 契约:resolveConfig 对输入不可变(与 unwrapConfig 输出 clone 对称)。
+  const frozenSection = Object.freeze({
+    shells: Object.freeze([
+      Object.freeze({ id: 'pwsh', kind: 'pwsh', path: '', args: Object.freeze([]), env: Object.freeze({}) }),
+      Object.freeze({ id: 'git-bash', kind: 'bash', path: '', args: Object.freeze([]), login: true, distro: '', env: Object.freeze({ MSYSTEM: 'MINGW64' }) }),
+    ]),
+    default: 'git-bash',
+  })
+  const applied = resolveConfig(frozenSection)
+  assert.equal(applied.default, 'git-bash')
+  assert.deepEqual(applied.shells.map((entry) => entry.id), ['pwsh', 'git-bash'])
+  assert.deepEqual(applied.shells[1].env, { MSYSTEM: 'MINGW64' })
+  // 二轮 resolve(行重载/快照回灌常态)同样幂等
+  const again = resolveConfig(frozenSection)
+  assert.deepEqual(again, applied)
+  // 输出与冻结输入脱耦:改输出不 affects 输入,反复解析结果稳定
+  applied.shells[1].env.MSYSTEM = 'TERM'
+  assert.deepEqual(resolveConfig(frozenSection).shells[1].env, { MSYSTEM: 'MINGW64' })
 })
 
 test('pwsh argv:非交互形 + 编码前缀', () => {
@@ -50,7 +141,7 @@ test('login 显式配置与自定义 args 模板互斥时模板优先', () => {
 })
 
 test('schema 往返:login 布尔保留,旧配置缺省落 false', () => {
-  const applied = Config({ shells: [
+  const applied = resolveConfig({ shells: [
     { id: 'm', name: 'MSYS2', kind: 'bash', path: 'C:\\msys64\\usr\\bin\\bash.exe', login: true },
     { id: 'g', name: 'Git Bash', kind: 'bash', path: '' },
   ], default: 'm' })

package/test/deny-config.test.mjs

@@ -1,4 +1,4 @@
-// deny 顶层字段:schema 往返与 updateConfig 落盘回读。
+// deny 顶层字段:schema 往返与 updateConfig 落盘回读。
 // BDD 场景见 docs/progress/feat-shell-select-deny.md 场景 7。
 
 import { test } from 'node:test'
@@ -6,10 +6,10 @@ import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { Config, defaultConfig } from '../src/config.mjs'
+import { resolveConfig, defaultConfig } from '../src/config.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
-const executorSource = readFileSync(join(here, '..', 'src', 'executor.mjs'), 'utf8')
+const webRoutesSource = readFileSync(join(here, '..', 'src', 'web-routes.mjs'), 'utf8')
 
 test('schema 默认:deny 空数组,旧配置反序列化补默认', () => {
   const config = defaultConfig()
@@ -17,17 +17,17 @@ test('schema 默认:deny 空数组,旧配置反序列化补默认', () => {
 })
 
 test('schema 往返:deny 保留;allow 无消费者(deny 绝对,无豁免语义)', () => {
-  const config = Config({ deny: ['format '], allow: ['git .*'] })
+  const config = resolveConfig({ deny: ['format '], allow: ['git .*'] })
   assert.deepEqual(config.deny, ['format '])
   // schemastery 透传未知键,僵尸键靠"无读取方"守卫:matchDeny/toSection 均只触 deny
   const denylistSource = readFileSync(join(here, '..', 'src', 'denylist.mjs'), 'utf8')
   const clientSource = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
   assert.doesNotMatch(denylistSource, /allow/)
   assert.doesNotMatch(clientSource, /allowText|section\.allow/)
-  assert.doesNotMatch(executorSource, /current\.allow|patch\.allow/)
+  assert.doesNotMatch(webRoutesSource, /current\.allow|patch\.allow/)
 })
 
-test('updateConfig 携带 deny(wholesale replace 防静默重置,同 login 教训)', () => {
-  assert.match(executorSource, /deny: Array\.isArray\(patch\.deny\) \? patch\.deny : current\.deny/)
-  assert.doesNotMatch(executorSource, /patch\.allow/)
+test('updateConfig 携带 deny(wholesale replace 防静默重置,同 login 教训;写路径在 web 行)', () => {
+  assert.match(webRoutesSource, /deny: Array\.isArray\(patch\.deny\) \? patch\.deny : current\.deny/)
+  assert.doesNotMatch(webRoutesSource, /patch\.allow/)
 })

package/test/executor-seam.test.mjs

@@ -1,4 +1,4 @@
-// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
+// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
 // 背景:preset 注入的官方 tool-pwsh 经 cordis 服务代理(ctx.shell)调用执行器,
 // 代理把方法 this 重定向到阴影对象;执行器公开面必须与官方 PwshLocalExecutor
 // 同构地使用公有字段/方法(#私有在阴影 receiver 下触发品牌检查错误)。
@@ -6,7 +6,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import ShellSelectExecutor from '../src/executor.mjs'
-import { Config } from '../src/config.mjs'
+import { resolveConfig } from '../src/config.mjs'
 
 function stubReader(text) {
   return { readFrom: () => ({ text, lossy: false, nextOffset: text.length }) }
@@ -33,7 +33,7 @@ function stubCtx({ sandboxMode = 'danger-full-access', spawn = stubSpawn() } = {
   const settingsImpl = {
     installSection: (ctx, ns, schema, base, hooks) => {
       registered.sections.push({ ns, schema, base, hooks })
-      settingsImpl._source = () => Config(base ?? {})
+      settingsImpl._source = () => resolveConfig(base ?? {})
     },
   }
   const ctx = {