@mzzsfy/dsh-shell-select 0.4.1 → 0.4.3

package/test/preset-drift.test.mjs

@@ -1,154 +1,45 @@
-// preset 接管守卫(0.1.7 预设架构):本包 patch insert 自带预设声明
-// (preset-shell-select,standard 内联 roster − tool-pwsh 行)并覆写
-// agent-preset-registry 的 default。漂移守卫对照已安装 dsh 的
-// dsh-web-app/presets/standard.patch.yml——上游增删行/改表达式即红,升级后
-// 按官方实文对表镜像;宿主缺失(无 dsh 本体的最小环境)时 skip,不制造假红。
-
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { readFileSync, existsSync, readdirSync } from 'node:fs'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { dirname, join, resolve } from 'node:path'
-import { createRequire } from 'node:module'
-import { execPath } from 'node:process'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const pkgRoot = join(here, '..')
-const patchText = readFileSync(join(pkgRoot, 'cordis.patch.yml'), 'utf8')
-
-// ── 宿主侧 yaml 能力探测:js-yaml 与官方 entryListSchema 经 dsh 安装位解析 ──
-
-function locateHarnessDir() {
-  // 候选锚:运行中 node 的全局安装位(nvm/全局布局:execPath 目录/node_modules)→
-  // 仓库 compat 隔离宿主(.dsh-versions/<v>/package)。缺失即返回 null(skip)。
-  const candidates = [
-    resolve(dirname(execPath), 'node_modules', '@deepseek-ai', 'dsh'),
-  ]
-  const versionsDir = resolve(pkgRoot, '..', '..', '.dsh-versions')
-  try {
-    for (const version of readdirSync(versionsDir)) {
-      candidates.push(join(versionsDir, version, 'package'))
-    }
-  } catch { /* 无 .dsh-versions,忽略 */ }
-  for (const candidate of candidates) {
-    if (existsSync(join(candidate, 'package.json'))) return candidate
-  }
-  return null
-}
+import { readFileSync } from 'node:fs'
+import yaml from 'js-yaml'
 
-// yaml 能力与宿主解耦:js-yaml 为 devDep(CI 无宿主也可解析本包文件)。
-// !!js 标签本地同形 Type:tag 必须写完整 URI(tag:yaml.org,2002:js)——文档简写
-// !!js 展开后按完整 URI 匹配,字面 '!!js' 永不命中(unknown tag,CI 假绿教训)。
-import yamlStatic from 'js-yaml'
-
-const LOCAL_SCHEMA = yamlStatic.JSON_SCHEMA.extend(new yamlStatic.Type('tag:yaml.org,2002:js', {
+const schema = yaml.JSON_SCHEMA.extend(new yaml.Type('tag:yaml.org,2002:js', {
   kind: 'scalar',
   resolve: (data) => typeof data === 'string',
   construct: (data) => ({ __jsExpr: data }),
-  represent: (data) => data['__jsExpr'],
 }))
-
-let harness = null
-let entryListSchema = LOCAL_SCHEMA
-try {
-  harness = locateHarnessDir()
-  if (harness !== null) {
-    const req = createRequire(join(harness, 'package.json'))
-    const toUrl = (specifier) => pathToFileURL(req.resolve(specifier)).href
-    entryListSchema = (await import(toUrl('@deepseek-ai/cordis-plugin-include'))).entryListSchema
-  }
-} catch { /* 官方 schema 缺失按本地同形标签处理 */ }
-
-const loadYaml = (text) => yamlStatic.load(text, { schema: entryListSchema })
-
-// 镜像 loader 的表达式求值形态(new Function + with(ctx),全局可用)
-const evalExpr = (expr, ctx) => new Function('ctx', `with (ctx) { return (${expr}) }`)(ctx)
-
-// ── 结构对比:展平行树为 id → {name, disabled, isolate, config 全值} ──
-// config 比全值而非键集:键集守不住文本漂移(plan-mode section 曾落后官方一句
-// 而守卫全绿),镜像声明即「standard 全量 − tool-pwsh 逐项同构」,值必须对表
-
-function flattenRows(rows, out = new Map()) {
-  for (const row of rows ?? []) {
-    if (row.id !== undefined) {
-      out.set(row.id, {
-        name: row.name,
-        disabled: row.disabled === undefined ? undefined : row.disabled.__jsExpr ?? row.disabled,
-        isolate: row.isolate === undefined ? undefined : JSON.parse(JSON.stringify(row.isolate)),
-        config: row.config === undefined ? undefined : JSON.parse(JSON.stringify(row.config)),
-      })
-    }
-    if (row.group && Array.isArray(row.config)) flattenRows(row.config, out)
-  }
-  return out
-}
-
-// 本包 patch 解析:insert 的预设声明行 + 各覆写行
-const patchRows = yamlStatic.load(patchText, { schema: LOCAL_SCHEMA })
-const insertRows = patchRows.filter((entry) => entry.insert !== undefined).flatMap((entry) => entry.insert)
-const ourPresetRow = insertRows.find((row) => row.id === 'preset-shell-select')
-const ourPlugins = ourPresetRow?.config?.plugins ?? []
-
-test('patch 形态:自带预设声明行(preset-shell-select,0.1.7 内联架构)', () => {
-  assert.ok(ourPresetRow, 'patch 缺 preset-shell-select 声明(insert 段)')
-  assert.equal(ourPresetRow.name, '@deepseek-ai/dsh-agent-preset')
-  assert.equal(ourPresetRow.config.id, 'shell-select')
-  const ids = new Set()
-  const walk = (list) => {
-    for (const row of list) {
-      if (row.id !== undefined) ids.add(row.id)
-      if (row.group && Array.isArray(row.config)) walk(row.config)
-    }
-  }
-  walk(ourPlugins)
-  assert.ok(ids.has('tool-bash'), 'POSIX bash 工具行必须保留')
-  assert.ok(!ids.has('tool-pwsh'), 'tool-pwsh 行必须移除(win32 shell 面由本包接管)')
-  assert.ok(!ids.has('persistent-pwsh'), 'persistent-pwsh 行不得进入本包预设')
-})
-
-test('patch 形态:agent-preset-registry 覆写含平台 default(patch 语义为整体替换 config)', () => {
-  const row = patchRows.find((entry) => entry.id === 'agent-preset-registry')
-  assert.ok(row, 'patch 缺 agent-preset-registry 覆写行')
-  assert.equal(row.name, undefined, 'registry 行是本包上层已 insert 的行,覆写按 id 匹配即无须 name')
-  assert.match(row.config.default.__jsExpr, /'shell-select'/)
-  assert.match(row.config.default.__jsExpr, /'standard'/)
+const patch = yaml.load(readFileSync(new URL('../cordis.patch.yml', import.meta.url), 'utf8'), { schema })
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const inserted = patch.flatMap((entry) => entry.insert ?? [])
+
+// Given 插件补丁，When 应用插入行，Then 只增加宿主执行面，不声明会话预设。
+test('补丁仅插入主行、guard 与 web，不增加会话预设', () => {
+  assert.deepEqual(inserted.map(({ id, name }) => ({ id, name })), [
+    { id: 'shell-select', name: '@mzzsfy/dsh-shell-select' },
+    { id: 'shell-select/guard', name: '@mzzsfy/dsh-shell-select/guard' },
+    { id: 'shell-select/web', name: '@mzzsfy/dsh-shell-select/web' },
+  ])
 })
 
-test('patch 表达式求值:default 按平台切换', () => {
-  const row = patchRows.find((entry) => entry.id === 'agent-preset-registry')
-  const expected = process.platform === 'win32' ? 'shell-select' : 'standard'
-  assert.equal(evalExpr(row.config.default.__jsExpr, {}), expected)
+// Given 任意宿主默认预设，When 应用插件补丁，Then 不覆写既有组合行。
+test('补丁不覆写宿主行或默认预设', () => {
+  assert.equal(patch.length, 1)
+  assert.deepEqual(Object.keys(patch[0]), ['insert'])
 })
 
-test('漂移守卫:与已安装 standard 预设逐行对表(缺失宿主则 skip)', (t) => {
-  if (harness === null) return t.skip('未找到 dsh 本体安装,无对照源')
-  const standardPath = join(harness, 'node_modules', '@deepseek-ai', 'dsh-web-app', 'presets', 'standard.patch.yml')
-  if (!existsSync(standardPath)) return t.skip('dsh 安装位无 standard 预设声明,无对照源')
-  const standardPatch = yamlStatic.load(readFileSync(standardPath, 'utf8'), { schema: LOCAL_SCHEMA })
-  const declared = standardPatch.filter((entry) => entry.insert !== undefined).flatMap((entry) => entry.insert).find((row) => row.id === 'preset-standard')
-  assert.ok(declared, 'standard.patch.yml 缺 preset-standard 声明')
-  const standard = flattenRows(declared.config.plugins)
-  const ours = flattenRows(ourPlugins)
-  for (const [id, row] of standard) {
-    if (id === 'tool-pwsh') {
-      assert.ok(!ours.has(id), 'standard 有 tool-pwsh 而本包预设也出现了:镜像被污染')
-      continue
-    }
-    assert.ok(ours.has(id), `standard 行 ${id} 在本包预设缺失,须对表镜像`)
-    assert.deepEqual(ours.get(id), row, `行 ${id} 与 standard 漂移,升级后按官方实文对表`)
-  }
-  for (const id of ours.keys()) {
-    assert.ok(standard.has(id), `本包预设多出 standard 没有的行 ${id}:镜像越界`)
+// Given 不同宿主平台，When 求值禁用表达式，Then Windows 启用、POSIX 停用。
+test('宿主行保持 Windows 平台门控', () => {
+  assert.equal(inserted.length, 3)
+  for (const row of inserted) {
+    const evaluate = new Function('process', `return (${row.disabled.__jsExpr})`)
+    assert.equal(evaluate({ platform: 'win32' }), false)
+    assert.equal(evaluate({ platform: 'linux' }), true)
+    assert.equal(evaluate({ platform: 'darwin' }), true)
   }
 })
 
-test('schema 同构:本地 !!js Type 与官方 entryListSchema 产物 deepEqual(缺失宿主则 skip)', (t) => {
-  if (harness === null) return t.skip('未找到 dsh 本体安装,无官方 schema 对照')
-  // harness 命中时 entryListSchema 已是官方版:loadYaml=官方路径,与 LOCAL_SCHEMA 逐文本对照。
-  // 本地同形标签的语义漂移曾以 unknown tag 形态炸穿 CI,此处固化为机器断言
-  assert.deepEqual(
-    yamlStatic.load(patchText, { schema: LOCAL_SCHEMA }),
-    loadYaml(patchText),
-    'bundle patch 双 schema 产物漂移,本地 !!js Type 须与官方 JsExpr 同构',
-  )
+// Given 插件清单，When 对账宿主依赖，Then 删除预设依赖但保留最低宿主版本。
+test('清单不再依赖预设模块，宿主门槛不变化', () => {
+  assert.equal(manifest.peerDependencies['@deepseek-ai/dsh-agent-preset'], undefined)
+  assert.equal(manifest.dsh.hostMin, '0.1.7-rc.1')
 })

package/test/prompt-projection.test.mjs

@@ -0,0 +1,120 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { Context } from '@deepseek-ai/cordis'
+import { createScope } from '@deepseek-ai/dsh-scope'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime, { defineTool, renderToolsSdk, renderToolsSdkPy } from '@deepseek-ai/dsh-tools'
+import * as projection from '../src/prompt-projection.mjs'
+
+function fixture() {
+  const ctx = new Context()
+  new SystemPrompt(ctx, {})
+  new ToolRuntime(ctx, {})
+  const preset = {}
+  const scoped = createScope(ctx, preset)
+  const register = (target, name, description) => target.tools.register(defineTool({
+    name, description, parameters: {},
+    output: { schema: { type: 'string' }, render: (value) => value },
+    execute: async () => 'PowerShell',
+  }))
+  register(ctx, 'shell', 'multi client')
+  register(ctx, 'pwsh', 'Do not call; use shell.')
+  register(scoped.ctx, 'pwsh', 'official preset description')
+  scoped.ctx.systemPrompt.section({ name: 'tool:pwsh', order: 1001, text: 'duplicate guidance' })
+  ctx.systemPrompt.section({ name: 'tool:shell', order: 1000, text: 'shell guidance' })
+  ctx.systemPrompt.context({ name: 'retained-context', order: 1, text: 'cwd' })
+  return { ctx, scoped, preset }
+}
+
+// Given 官方预设遮蔽根描述；When 组装；Then 无pwsh展示但历史调用保持可执行。
+test('native 投影穿过预设遮蔽且不影响调用', async () => {
+  const { ctx, preset, scoped } = fixture()
+  const agent = {}
+  const child = createScope(ctx, agent, { parent: preset })
+  const original = await ctx.systemPrompt.assemble({ scope: agent })
+  assert.equal(original.tools.find((t) => t.name === 'pwsh').description, 'official preset description')
+  projection.mountShellPromptProjection(ctx)
+  const result = await ctx.systemPrompt.assemble({ scope: agent })
+  assert.deepEqual(result.tools.map((t) => t.name), ['shell'])
+  assert.deepEqual(result.sections.filter((s) => s.name.startsWith('tool:')).map((s) => s.name), ['tool:shell'])
+  assert.deepEqual(result.contexts, original.contexts)
+  assert.deepEqual(result.variables, original.variables)
+  assert.equal(ctx.tools.get('pwsh', agent).description, 'official preset description')
+  assert.equal(await ctx.tools.get('pwsh', agent).execute({}, {}), 'PowerShell')
+  await child.dispose()
+  await scoped.dispose()
+})
+
+// Given 监听卸载；When 再次组装；Then 原预设schema与提示段恢复。
+test('投影卸载自然还原', async () => {
+  const { ctx, preset, scoped } = fixture()
+  const original = await ctx.systemPrompt.assemble({ scope: preset })
+  const dispose = projection.mountShellPromptProjection(ctx)
+  await ctx.systemPrompt.assemble({ scope: preset })
+  dispose()
+  assert.deepEqual(await ctx.systemPrompt.assemble({ scope: preset }), original)
+  await scoped.dispose()
+})
+
+// Given 子代理排除shell；When 组装；Then 不移除其唯一终端。
+test('shell 不可见时保留 pwsh', async () => {
+  const { ctx, preset, scoped } = fixture()
+  const agent = {}
+  const child = createScope(ctx, agent, { parent: preset })
+  child.ctx.tools.restrict({ deny: ['shell'] })
+  const original = await ctx.systemPrompt.assemble({ scope: agent })
+  projection.mountShellPromptProjection(ctx)
+  assert.deepEqual(await ctx.systemPrompt.assemble({ scope: agent }), original)
+  await child.dispose()
+  await scoped.dispose()
+})
+
+for (const [language, render] of [['typescript', renderToolsSdk], ['python', renderToolsSdkPy]]) {
+  for (const mode of ['ptc', 'both']) {
+    // Given PTC SDK；When 组装；Then 仅删除pwsh声明，其他工具类型不变。
+    test(`${language}/${mode} SDK 删除 pwsh 且保留其他输出类型`, async () => {
+      const { ctx, preset, scoped } = fixture()
+      const schemas = ctx.tools.schemas(preset).map((s) => ({ ...s, output: ctx.tools.get(s.name, preset).output.schema }))
+      ctx.on('system-prompt/assemble', async (assembly, context, next) => {
+        const result = await next()
+        return { ...result, tools: mode === 'ptc' ? [{ name: 'run_code' }] : [...result.tools, { name: 'run_code' }],
+          sections: [...result.sections, { name: 'tools:sdk', text: render(schemas), interpolate: false }] }
+      })
+      ctx.reflect.provide('ptcRuntime', { language })
+      projection.mountShellPromptProjection(ctx)
+      const result = await ctx.systemPrompt.assemble({ scope: preset })
+      assert.deepEqual(result.tools.map((t) => t.name), mode === 'ptc' ? ['run_code'] : ['shell', 'run_code'])
+      assert.equal(result.sections.find((s) => s.name === 'tools:sdk').text, render(schemas.filter((s) => s.name !== 'pwsh')))
+      assert.equal(await ctx.tools.get('pwsh', preset).execute({}, {}), 'PowerShell')
+      await scoped.dispose()
+    })
+  }
+}
+
+// Given 其他waterfall在next中添加pwsh；When投影；Then最终结果过滤而非入口快照。
+test('投影过滤 next 返回的最终结果且不篡改输入', async () => {
+  const handlers = []
+  const warnings = []
+  const ctx = { on: (name, handler) => { handlers.push(handler); return () => {} }, tools: { get: () => ({}) }, logger: { warn: (msg) => warnings.push(msg) } }
+  projection.mountShellPromptProjection(ctx)
+  const input = { tools: [], sections: [] }
+  const final = { tools: [{ name: 'shell' }, { name: 'pwsh' }, { name: 'read' }], sections: [{ name: 'tool:pwsh' }, { name: 'policy' }], contexts: [], variables: {} }
+  const result = await handlers[0](input, {}, async () => final)
+  assert.deepEqual(result.tools.map((t) => t.name), ['shell', 'read'])
+  assert.deepEqual(result.sections.map((s) => s.name), ['policy'])
+  assert.equal(final.tools.length, 3)
+  assert.equal(input.tools.length, 0)
+  assert.deepEqual(warnings, [])
+})
+
+// Given 无法识别SDK语言；When投影；Then原样返回且告警，不做半完成SDK。
+test('SDK 投影不可用时整体不改并告警', async () => {
+  const handlers = []
+  const warnings = []
+  const ctx = { on: (name, handler) => { handlers.push(handler); return () => {} }, tools: { get: () => ({}) },
+    get: () => ({ language: 'unsupported' }), logger: { warn: (msg) => warnings.push(msg) } }
+  projection.mountShellPromptProjection(ctx)
+  const final = { tools: [{ name: 'shell' }, { name: 'pwsh' }, { name: 'run_code' }], sections: [{ name: 'tools:sdk', text: 'pwsh sdk' }] }
+  assert.equal(await handlers[0](final, {}, async () => final), final)
+  assert.equal(warnings.length, 1)
+})

package/test/pwsh-takeover.test.mjs

@@ -0,0 +1,41 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mountPwshTakeover } from '../src/pwsh-takeover.mjs'
+
+test('pwsh 接管事实仅归属实际进入执行器的并行调用', async () => {
+  // Given 两条 pwsh 调用；When 仅一条进入接管执行器；Then 仅该结果带标记，值与退出锚不变。
+  const listeners = new Map()
+  const touch = mountPwshTakeover({ on: (name, fn) => listeners.set(name, fn), effect: (fn) => fn() })
+  const dispatch = listeners.get('tools/execute')
+  const post = listeners.get('tools/post-execute')
+  const makeExec = () => ({ name: 'pwsh', token: Symbol() })
+  const taken = makeExec()
+  const untouched = makeExec()
+  const value = { exitCode: 2 }
+  const result = { isError: false, value, content: [{ type: 'text', text: 'out\n[exit code: 2]' }] }
+  await Promise.all([
+    dispatch(taken, async () => { await Promise.resolve(); touch(); return result }),
+    dispatch(untouched, async () => result),
+  ])
+  const marked = await post(taken, result, async () => ({ kind: 'accept' }))
+  assert.equal(marked.kind, 'accept')
+  assert.equal(marked.content[0].text, 'out\n[exit code: 2]')
+  assert.deepEqual(marked.content[1], { type: 'shell-select-takeover', tool: 'pwsh' })
+  assert.equal(result.value, value)
+  assert.deepEqual(await post(untouched, result, async () => ({ kind: 'accept' })), { kind: 'accept' })
+})
+
+test('普通 shell 与下游替换内容保持不变，接管事实消费一次', async () => {
+  // Given shell 与已接管 pwsh；When 下游策略替换内容；Then 不覆盖策略，调用事实无残留。
+  const listeners = new Map()
+  const touch = mountPwshTakeover({ on: (name, fn) => listeners.set(name, fn), effect: (fn) => fn() })
+  const result = { content: [{ type: 'text', text: 'out' }], isError: false }
+  const shell = { name: 'shell', token: Symbol() }
+  await listeners.get('tools/execute')(shell, async () => { touch(); return result })
+  assert.deepEqual(await listeners.get('tools/post-execute')(shell, result, async () => ({ kind: 'accept' })), { kind: 'accept' })
+  const pwsh = { name: 'pwsh', token: Symbol() }
+  await listeners.get('tools/execute')(pwsh, async () => { touch(); return result })
+  const replacement = { kind: 'accept', content: [{ type: 'text', text: 'policy replacement' }] }
+  assert.equal(await listeners.get('tools/post-execute')(pwsh, result, async () => replacement), replacement)
+  assert.deepEqual(await listeners.get('tools/post-execute')(pwsh, result, async () => ({ kind: 'accept' })), { kind: 'accept' })
+})

package/test/resolve.test.mjs

@@ -25,7 +25,7 @@ const ENV_WITH_SYSTEM32_PATH = {
 }
 
 test('pwsh 候选顺序:PowerShell 7 → PATH 各项 → System32 5.1', () => {
-  const candidates = candidatePaths('pwsh', ENV)
+  const candidates = candidatePaths('pwsh', ENV, 'win32')
   assert.deepEqual(candidates, [
     'C:\\PF\\PowerShell\\7\\pwsh.exe',
     'C:\\one\\pwsh.exe',
@@ -36,7 +36,7 @@ test('pwsh 候选顺序:PowerShell 7 → PATH 各项 → System32 5.1', () => {
 })
 
 test('bash 候选顺序:Git 三常见位置 → msys2 真实 bash → PATH', () => {
-  const candidates = candidatePaths('bash', ENV)
+  const candidates = candidatePaths('bash', ENV, 'win32')
   assert.deepEqual(candidates, [
     'C:\\PF\\Git\\bin\\bash.exe',
     'C:\\PF86\\Git\\bin\\bash.exe',
@@ -50,7 +50,7 @@ test('bash 候选顺序:Git 三常见位置 → msys2 真实 bash → PATH', ()
 })
 
 test('bash 候选排除 SystemRoot 下的 PATH 条目(WSL forwarder)', () => {
-  const candidates = candidatePaths('bash', ENV_WITH_SYSTEM32_PATH)
+  const candidates = candidatePaths('bash', ENV_WITH_SYSTEM32_PATH, 'win32')
   assert.deepEqual(candidates, [
     'C:\\PF\\Git\\bin\\bash.exe',
     'C:\\PF86\\Git\\bin\\bash.exe',
@@ -63,21 +63,21 @@ test('bash 候选排除 SystemRoot 下的 PATH 条目(WSL forwarder)', () => {
 
 test('bash 候选排除 SystemRoot 下的正斜杠 PATH 条目', () => {
   const env = { ...ENV, PATH: 'C:/WINDOWS/System32;C:\\one' }
-  const candidates = candidatePaths('bash', env)
+  const candidates = candidatePaths('bash', env, 'win32')
   assert.ok(!candidates.some((candidate) => candidate.toLowerCase().startsWith('c:\\windows')))
   assert.ok(candidates.includes('C:\\one\\bash.exe'))
 })
 
 test('SystemRoot 带尾分隔符时排除规则仍命中', () => {
   const env = { ...ENV, SystemRoot: 'C:\\WINDOWS\\', PATH: 'C:\\WINDOWS\\System32;C:\\one' }
-  const candidates = candidatePaths('bash', env)
+  const candidates = candidatePaths('bash', env, 'win32')
   assert.ok(!candidates.some((candidate) => candidate.toLowerCase().startsWith('c:\\windows')), '尾分隔符 SystemRoot 不得让 forwarder 入候选')
   assert.ok(candidates.includes('C:\\one\\bash.exe'))
 })
 
 test('LocalAppData 缺省:LAD 锚位跳过,其余候选不受影响', () => {
   const env = { ProgramFiles: 'C:\\PF', 'ProgramFiles(x86)': 'C:\\PF86', LocalAppData: '', PATH: '' }
-  const candidates = candidatePaths('bash', env)
+  const candidates = candidatePaths('bash', env, 'win32')
   assert.ok(!candidates.some((candidate) => candidate.startsWith('\\\\')), 'LocalAppData 为空不得产出空根拼接候选')
   assert.ok(!candidates.some((candidate) => candidate.startsWith('undefined')))
   assert.ok(candidates.includes('C:\\PF\\Git\\bin\\bash.exe'))
@@ -85,14 +85,14 @@ test('LocalAppData 缺省:LAD 锚位跳过,其余候选不受影响', () => {
 })
 
 test('bash 候选永不含 msys2.exe 启动器(管道下静默失败)', () => {
-  for (const candidate of candidatePaths('bash', ENV)) {
+  for (const candidate of candidatePaths('bash', ENV, 'win32')) {
     assert.ok(!candidate.toLowerCase().includes('msys2.exe'), candidate)
   }
 })
 
 test('cmd/wsl 候选:仅 System32 单点', () => {
-  assert.deepEqual(candidatePaths('cmd', ENV), ['C:\\WINDOWS\\System32\\cmd.exe'])
-  assert.deepEqual(candidatePaths('wsl', ENV), ['C:\\WINDOWS\\System32\\wsl.exe'])
+  assert.deepEqual(candidatePaths('cmd', ENV, 'win32'), ['C:\\WINDOWS\\System32\\cmd.exe'])
+  assert.deepEqual(candidatePaths('wsl', ENV, 'win32'), ['C:\\WINDOWS\\System32\\wsl.exe'])
 })
 
 test('显式路径原样使用,不探测', () => {
@@ -104,12 +104,12 @@ test('自动解析命中首个存在候选', () => {
   const resolved = resolveEntryPath({ kind: 'bash', path: '' }, stubExists([
     'C:\\one\\bash.exe',
     'C:\\PF\\Git\\bin\\bash.exe',
-  ]), ENV)
+  ]), ENV, 'win32')
   assert.equal(resolved, 'C:\\PF\\Git\\bin\\bash.exe')
 })
 
 test('无候选存在返回 undefined', () => {
-  assert.equal(resolveEntryPath({ kind: 'pwsh', path: '' }, stubExists([]), ENV), undefined)
+  assert.equal(resolveEntryPath({ kind: 'pwsh', path: '' }, stubExists([]), ENV, 'win32'), undefined)
 })
 
 test('detect 返回全部命中并去重', () => {
@@ -117,7 +117,7 @@ test('detect 返回全部命中并去重', () => {
     'C:\\PF\\Git\\bin\\bash.exe',
     'C:\\three\\bash.exe',
     'C:\\WINDOWS\\System32\\cmd.exe',
-  ]))
+  ]), 'win32')
   assert.deepEqual(found, [
     { kind: 'bash', path: 'C:\\PF\\Git\\bin\\bash.exe' },
     { kind: 'bash', path: 'C:\\three\\bash.exe' },
@@ -126,6 +126,36 @@ test('detect 返回全部命中并去重', () => {
 })
 
 test('detect 同路径跨 kind 不重复收录', () => {
-  const found = detectCandidates(['pwsh', 'bash'], ENV, stubExists(['C:\\one\\bash.exe', 'C:\\one\\pwsh.exe']))
+  const found = detectCandidates(['pwsh', 'bash'], ENV, stubExists(['C:\\one\\bash.exe', 'C:\\one\\pwsh.exe']), 'win32')
   assert.equal(found.length, 2)
 })
+
+// POSIX 形态:冒号 PATH、裸可执行名、pwsh 固定锚点先于 PATH
+const POSIX_ENV = { PATH: '/usr/local/bin:/opt/tools', SystemRoot: undefined }
+
+test('POSIX pwsh 候选:固定锚点 → PATH 冒号各项(裸名)', () => {
+  const candidates = candidatePaths('pwsh', POSIX_ENV, 'linux')
+  assert.deepEqual(candidates, [
+    '/usr/bin/pwsh',
+    '/usr/local/bin/pwsh',
+    '/opt/microsoft/powershell/7/pwsh',
+    '/opt/homebrew/bin/pwsh',
+    '/usr/local/bin/pwsh',
+    '/opt/tools/pwsh',
+  ])
+})
+
+test('POSIX System32/cmd/wsl 锚位缺席', () => {
+  assert.deepEqual(candidatePaths('cmd', POSIX_ENV, 'linux'), [])
+  assert.deepEqual(candidatePaths('wsl', POSIX_ENV, 'linux'), [])
+})
+
+test('POSIX bash 候选:PATH 冒号各项(裸名,无 win32 锚位)', () => {
+  const candidates = candidatePaths('bash', POSIX_ENV, 'linux')
+  assert.deepEqual(candidates, ['/usr/local/bin/bash', '/opt/tools/bash'])
+})
+
+test('detect 平台参数化:同集合按平台取候选形态', () => {
+  const found = detectCandidates(['pwsh'], POSIX_ENV, stubExists(['/opt/tools/pwsh']), 'linux')
+  assert.deepEqual(found, [{ kind: 'pwsh', path: '/opt/tools/pwsh' }])
+})

package/test/web-routes.test.mjs

@@ -118,14 +118,27 @@ test('webServer 缺席:路由跳过不抛(带告警,headless 合法形态)', ()
   assert.match(registered.warnings.join('\n'), /webServer/)
 })
 
-test('webServer 在场:三条 exact 路由注册', () => {
+test('webServer 在场:四条 exact 路由注册', () => {
   const { ctx, webServer } = stubCtx()
   webRoutes.apply(ctx)
   const paths = webServer.state.registered.map((item) => item.path).sort()
-  assert.deepEqual(paths, ['/api/shell-select/config', '/api/shell-select/detect', '/api/shell-select/probe'])
+  assert.deepEqual(paths, ['/api/shell-select/config', '/api/shell-select/detect', '/api/shell-select/pathmap', '/api/shell-select/probe'])
   assert.ok(webServer.state.registered.every((item) => item.kind === 'exact'))
 })
 
+test('GET /pathmap:返回宿主平台事实(platform/home/tmpDir)', async () => {
+  const { ctx } = stubCtx()
+  webRoutes.apply(ctx)
+  const handler = ctx.webServer.state.handlers.get('/api/shell-select/pathmap')
+  const res = fakeRes()
+  await handler(fakeReq('GET'), res)
+  assert.equal(res.state.status, 200)
+  const payload = JSON.parse(res.state.body)
+  assert.equal(payload.platform, process.platform)
+  assert.equal(typeof payload.home, 'string')
+  assert.equal(typeof payload.tmpDir, 'string')
+})
+
 test('GET /config:返回 describe 值 + resolved 投影(路径已解析)', async () => {
   const { ctx } = stubCtx()
   webRoutes.apply(ctx)

package/test/client-drift.test.mjs

@@ -1,27 +0,0 @@
-// KINDS 漂移守卫:client.js 工具形态清单与 host config.mjs 同源(竞品
-// bash-terminal-ts 的 drift 守卫同构:加形态忘改文案即测试失败)。
-// BDD 场景见 docs/feat-shell-select-optim/plan.md S14。
-
-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'
-import { KINDS } from '../src/config.mjs'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const clientSource = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
-
-test('S14 client KINDS 字面与 host KINDS 同源', () => {
-  const match = clientSource.match(/const KINDS = \[([^\]]*)\]/)
-  assert.ok(match, 'client.js 缺少 KINDS 声明')
-  const declared = match[1].split(',').map((item) => item.trim().replace(/^'|'$/g, '')).filter((item) => item.length > 0)
-  assert.deepEqual(declared, [...KINDS])
-})
-
-test('S14b client KIND_LABELS 覆盖全部形态', () => {
-  for (const kind of KINDS) {
-    const pattern = new RegExp(kind + ":")
-    assert.match(clientSource, pattern, 'KIND_LABELS 缺少形态 ' + kind)
-  }
-})

package/test/switch-guard.test.mjs

@@ -1,37 +0,0 @@
-// 开关样式守卫 BDD:裸 checkbox 直接呈现违反仓库 client 规约(DEVELOPMENT/plugin-client-conventions.md),
-// 静态断言锁死 sls-switch 结构(参照 mce-switch/tn-switch/cb-switch 同款守卫)。
-import { readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import test from 'node:test'
-import assert from 'node:assert/strict'
-
-const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
-const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
-
-test('switch 隐藏规则以 input[type="checkbox"] 精确匹配', () => {
-  assert.match(source, /\.sls-switch input\[type="checkbox"\] \{ position:absolute/)
-})
-
-test('switch 状态选择器禁止裸 input 锚定(防误伤同 label 的文本输入)', () => {
-  const bare = source.match(/\.sls-switch input:(?!\[type)[a-z-]+/g)
-  assert.equal(bare, null, `裸 input 状态选择器: ${bare}`)
-})
-
-test('checkbox 仅允许出现在 switchToggle 工厂内,禁止裸 checkbox 直出', () => {
-  const occurrences = [...source.matchAll(/type: 'checkbox'/g)].map((match) => match.index)
-  assert.equal(occurrences.length, 1, `checkbox 字面量出现 ${occurrences.length} 次`)
-  const factoryStart = source.indexOf('function switchToggle')
-  const factoryEnd = source.indexOf('}', source.indexOf('__thumb', factoryStart))
-  assert.ok(occurrences[0] > factoryStart && occurrences[0] < factoryEnd, 'checkbox 字面量不在 switchToggle 工厂内')
-})
-
-test('switchToggle 产出顺序为 input 在前 track 在后', () => {
-  const factory = source.slice(source.indexOf('function switchToggle'))
-  assert.ok(factory.indexOf("h('input'") < factory.indexOf('sls-switch__track'), '工厂内 input 必须先于 track')
-})
-
-test('checked/focus-visible 两态均以 checkbox 锚定', () => {
-  assert.match(source, /\.sls-switch input\[type="checkbox"\]:checked \+/)
-  assert.match(source, /\.sls-switch input\[type="checkbox"\]:focus-visible \+/)
-})