@mzzsfy/dsh-shell-select 0.1.0

package/test/config.test.mjs

@@ -0,0 +1,106 @@
+// config 设置 schema 与 argv 组装:BDD 场景见 docs/progress/shell-select-plan.md「模块 config」。
+// schemastery schema 走真实官方包验证默认值与校验行为。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { Config, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+
+test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
+  const applied = Config({})
+  assert.deepEqual(applied, defaultConfig())
+  assert.equal(applied.default, 'pwsh')
+  assert.deepEqual(applied.shells.map((entry) => entry.id), ['pwsh', 'git-bash', 'cmd'])
+  for (const entry of applied.shells) {
+    assert.equal(entry.path, '')
+    assert.ok(KINDS.includes(entry.kind))
+  }
+})
+
+test('schema 拒绝未知 kind;default 跨字段一致性由 validate hook 与 requireEntry 兜底', () => {
+  assert.throws(() => Config({ shells: [{ id: 'x', name: 'X', kind: 'fish', path: '' }], default: 'x' }))
+})
+
+test('pwsh argv:非交互形 + 编码前缀', () => {
+  const argv = buildArgv({ kind: 'pwsh', path: 'C:\\pf\\pwsh.exe' }, 'Get-Item .')
+  assert.deepEqual(argv, [
+    'C:\\pf\\pwsh.exe',
+    '-NoLogo', '-NoProfile', '-NonInteractive', '-Command',
+    '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); $OutputEncoding = [System.Text.UTF8Encoding]::new($false); Get-Item .',
+  ])
+})
+
+test('bash argv:-c 直传', () => {
+  assert.deepEqual(buildArgv({ kind: 'bash', path: 'C:\\Git\\bin\\bash.exe' }, 'ls -la'), [
+    'C:\\Git\\bin\\bash.exe', '-c', 'ls -la',
+  ])
+})
+
+test('bash argv:login 条目走 -lc 登录壳(profile 注入 PATH)', () => {
+  assert.deepEqual(buildArgv({ kind: 'bash', path: 'C:\\msys64\\usr\\bin\\bash.exe', login: true }, 'uname -a'), [
+    'C:\\msys64\\usr\\bin\\bash.exe', '-lc', 'uname -a',
+  ])
+})
+
+test('bash argv:login=false 与缺省等价(-c)', () => {
+  assert.deepEqual(buildArgv({ kind: 'bash', path: 'C:\\b.exe', login: false }, 'x'), ['C:\\b.exe', '-c', 'x'])
+})
+
+test('login 显式配置与自定义 args 模板互斥时模板优先', () => {
+  assert.deepEqual(buildArgv({ kind: 'bash', path: 'C:\\b.exe', login: true, args: ['-x'] }, 'hi'), ['C:\\b.exe', '-x', 'hi'])
+})
+
+test('schema 往返:login 布尔保留,旧配置缺省落 false', () => {
+  const applied = Config({ 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' })
+  assert.equal(applied.shells[0].login, true)
+  assert.equal(applied.shells[1].login, false)
+})
+
+test('cmd argv:/d /s /c 忽略 AutoRun', () => {
+  assert.deepEqual(buildArgv({ kind: 'cmd', path: 'C:\\S32\\cmd.exe' }, 'dir'), [
+    'C:\\S32\\cmd.exe', '/d', '/s', '/c', 'dir',
+  ])
+})
+
+test('wsl argv:--exec 绕过默认 shell', () => {
+  assert.deepEqual(buildArgv({ kind: 'wsl', path: 'C:\\S32\\wsl.exe' }, 'uname -a'), [
+    'C:\\S32\\wsl.exe', '--exec', 'bash', '-c', 'uname -a',
+  ])
+})
+
+test('自定义 args 模板:{command} 占位替换', () => {
+  const argv = buildArgv({ kind: 'bash', path: 'C:\\x\\fish.exe', args: ['--login', '-c', '{command}'] }, 'echo hi')
+  assert.deepEqual(argv, ['C:\\x\\fish.exe', '--login', '-c', 'echo hi'])
+})
+
+test('自定义 args 模板:无占位则追加末项', () => {
+  const argv = buildArgv({ kind: 'bash', path: 'C:\\x\\sh.exe', args: ['-s'] }, 'echo hi')
+  assert.deepEqual(argv, ['C:\\x\\sh.exe', '-s', 'echo hi'])
+})
+
+test('entryById 按 id 取条目', () => {
+  const shells = [
+    { id: 'a', name: 'A', kind: 'bash', path: '' },
+    { id: 'b', name: 'B', kind: 'cmd', path: '' },
+  ]
+  assert.equal(entryById(shells, 'b'), shells[1])
+  assert.equal(entryById(shells, 'zz'), undefined)
+})
+
+test('requireEntry:缺省用 default,default 缺失报配置指引', () => {
+  const shells = [
+    { id: 'a', name: 'A', kind: 'bash', path: '' },
+    { id: 'b', name: 'B', kind: 'cmd', path: '' },
+  ]
+  assert.equal(requireEntry(shells, undefined, 'b'), shells[1])
+  assert.equal(requireEntry(shells, 'a', 'b'), shells[0])
+  assert.throws(() => requireEntry(shells, undefined, undefined), /default.*shell-select|shell-select.*default/is)
+  assert.throws(() => requireEntry(shells, 'zz', 'b'), /zz/)
+})
+
+test('kind 常量与自动解析标记', () => {
+  assert.deepEqual(KINDS, ['pwsh', 'bash', 'cmd', 'wsl'])
+  assert.equal(RESOLVED_AUTO, '')
+})

package/test/deny-config.test.mjs

@@ -0,0 +1,33 @@
+// deny 顶层字段:schema 往返与 updateConfig 落盘回读。
+// BDD 场景见 docs/progress/feat-shell-select-deny.md 场景 7。
+
+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 { Config, defaultConfig } from '../src/config.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const executorSource = readFileSync(join(here, '..', 'src', 'executor.mjs'), 'utf8')
+
+test('schema 默认:deny 空数组,旧配置反序列化补默认', () => {
+  const config = defaultConfig()
+  assert.deepEqual(config.deny, [])
+})
+
+test('schema 往返:deny 保留;allow 无消费者(deny 绝对,无豁免语义)', () => {
+  const config = Config({ 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/)
+})
+
+test('updateConfig 携带 deny(wholesale replace 防静默重置,同 login 教训)', () => {
+  assert.match(executorSource, /deny: Array\.isArray\(patch\.deny\) \? patch\.deny : current\.deny/)
+  assert.doesNotMatch(executorSource, /patch\.allow/)
+})

package/test/deny-tool.test.mjs

@@ -0,0 +1,26 @@
+// tool.mjs DenyError → 模型可见 blocked 标记(场景 8):源级守卫
+// (registerShellTool 工厂形态,node:test 下不便直拉 dsh-tools 全链)。
+
+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 { DenyError } from '../src/denylist.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const source = readFileSync(join(here, '..', 'src', 'tool.mjs'), 'utf8')
+
+test('execute 路径 catch DenyError 返回 blocked 标记文本', () => {
+  // 前台与后台两分支各自触达 executor 入口,均须拦截转译
+  const catches = (source.match(/catch \(error\) \{[\s\S]*?isDenyError/g) ?? []).length
+  assert.ok(catches >= 2, `execute 前台/后台两分支应各自 catch DenyError(发现 ${catches} 处)`)
+  assert.match(source, /SHELL_COMMAND_BLOCKED/)
+  assert.match(source, /blocked by shell-select/)
+})
+
+test('DenyError 形态契约:code/name 可供跨层判定', () => {
+  const error = new DenyError('p', 'cmd')
+  assert.equal(error.code, 'SHELL_COMMAND_BLOCKED')
+  assert.equal(error.name, 'DenyError')
+})

package/test/denylist.test.mjs

@@ -0,0 +1,39 @@
+// matchDeny 纯函数:命令黑名单匹配(deny 绝对:命中即拒,无豁免语义)。
+// BDD 场景见 docs/progress/feat-shell-select-deny.md 场景 1-4/6。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { matchDeny, DenyError } from '../src/denylist.mjs'
+
+test('deny 命中:抛 DenyError,消息含命中的 pattern', () => {
+  const deny = ['format ']
+  assert.throws(() => matchDeny('format c: /q', deny), (error) => {
+    assert.ok(error instanceof DenyError)
+    assert.equal(error.code, 'SHELL_COMMAND_BLOCKED')
+    assert.ok(error.message.includes('format '))
+    return true
+  })
+})
+
+test('精细放行在 deny 模式内用前瞻表达:禁 rm -rf,放行清 node_modules', () => {
+  const deny = ['rm -rf\\s+(?!\\S*node_modules)']
+  assert.throws(() => matchDeny('rm -rf C:\\Windows', deny), DenyError)
+  assert.doesNotThrow(() => matchDeny('rm -rf ./node_modules', deny))
+})
+
+test('大小写不敏感:DISKPART 拒绝 diskpart', () => {
+  assert.throws(() => matchDeny('diskpart', ['DISKPART']), DenyError)
+})
+
+test('空配置不拦:deny 空数组/undefined 照常放行', () => {
+  assert.doesNotThrow(() => matchDeny('git status', []))
+  assert.doesNotThrow(() => matchDeny('git status', undefined))
+})
+
+test('坏正则容错:非法条目跳过,不瘫执行链', () => {
+  assert.doesNotThrow(() => matchDeny('anything', ['[bad', '(bad', 'ok']))
+})
+
+test('多行命令整文本匹配:第一行干净也挡住后续行命中', () => {
+  assert.throws(() => matchDeny('echo start\nformat c:', ['format ']), DenyError)
+})

package/test/env.test.mjs

@@ -0,0 +1,81 @@
+// buildClientEnv:spawn env 构造纯函数。BDD 场景见 docs/feat-shell-select-optim/plan.md S1-S4。
+// 三层并集:内置覆盖集 < 条目 env(用户客户端配置,如 MSYSTEM) < 调用方 env(spec.env+dshEnv)。
+// wsl 追加键 = 条目与调用方全部键(WSLENV 本身除外);调用方显式 WSLENV 优先于继承值。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { buildClientEnv, ENV_OVERRIDES } from '../src/executor.mjs'
+
+test('pwsh 形:DSH_* 直接并入,不动 WSLENV', () => {
+  const env = buildClientEnv('pwsh', { DSH_WORKSPACE: 'C:\\w' })
+  assert.equal(env.DSH_WORKSPACE, 'C:\\w')
+  assert.equal(env.WSLENV, undefined)
+  assert.equal(env.NO_COLOR, '1')
+})
+
+test('S1 bash 条目 env 并存:MSYSTEM 注入且内置覆盖集仍在', () => {
+  const env = buildClientEnv('bash', undefined, { MSYSTEM: 'MINGW64' })
+  assert.equal(env.MSYSTEM, 'MINGW64')
+  assert.equal(env.NO_COLOR, '1')
+  assert.equal(env.PAGER, 'cat')
+})
+
+test('S2 三层优先级:条目压内置,调用方压条目', () => {
+  const overridden = buildClientEnv('pwsh', undefined, { NO_COLOR: '0' })
+  assert.equal(overridden.NO_COLOR, '0')
+  const callerWins = buildClientEnv('pwsh', { NO_COLOR: '2' }, { NO_COLOR: '0' })
+  assert.equal(callerWins.NO_COLOR, '2')
+})
+
+test('S3 wsl 条目 env 键追加进 WSLENV,与 DSH_* 键并存', () => {
+  const env = buildClientEnv('wsl', { DSH_X: '1' }, { MSYSTEM: 'MINGW64' }, { inheritedWslenv: 'WT_SESSION:' })
+  assert.equal(env.WSLENV, 'WT_SESSION:MSYSTEM:DSH_X')
+})
+
+test('S4 非 wsl 形条目 env 不触发 WSLENV', () => {
+  const env = buildClientEnv('bash', undefined, { MSYSTEM: 'MINGW64' }, { inheritedWslenv: 'WT_SESSION:' })
+  assert.equal(env.WSLENV, undefined)
+})
+
+test('wsl 形:DSH_* 键追加进 WSLENV,继承条目保留,无空段', () => {
+  const env = buildClientEnv('wsl', { DSH_WORKSPACE: 'C:\\w' }, undefined, { inheritedWslenv: 'WT_SESSION:WT_PROFILE_ID:' })
+  assert.equal(env.DSH_WORKSPACE, 'C:\\w')
+  assert.equal(env.WSLENV, 'WT_SESSION:WT_PROFILE_ID:DSH_WORKSPACE')
+})
+
+test('wsl 形:无追加键时 WSLENV 原样继承', () => {
+  const env = buildClientEnv('wsl', undefined, undefined, { inheritedWslenv: 'WT_SESSION:' })
+  assert.equal(env.WSLENV, 'WT_SESSION:')
+})
+
+test('wsl 形:调用方显式 WSLENV 优先于继承值', () => {
+  const env = buildClientEnv('wsl', { DSH_X: '1', WSLENV: 'A' }, undefined, { inheritedWslenv: 'B' })
+  assert.equal(env.WSLENV, 'A:DSH_X')
+})
+
+test('条目显式 WSLENV 优先于继承值,追加键去重保留', () => {
+  const env = buildClientEnv('wsl', { DSH_X: '1' }, { WSLENV: 'E', MSYSTEM: 'MINGW64' }, { inheritedWslenv: 'WT_SESSION:MSYSTEM:' })
+  assert.equal(env.WSLENV, 'E:MSYSTEM:DSH_X')
+})
+
+test('继承值已含的追加键不产生重复段', () => {
+  const env = buildClientEnv('wsl', { DSH_X: '1' }, { MSYSTEM: 'MINGW64' }, { inheritedWslenv: 'WT:DSH_X:' })
+  assert.equal(env.WSLENV, 'WT:DSH_X:MSYSTEM')
+})
+
+test('wsl 形:无继承无显式时从空构建,无空条目', () => {
+  const env = buildClientEnv('wsl', { DSH_X: '1' }, undefined, { inheritedWslenv: undefined })
+  assert.equal(env.WSLENV, 'DSH_X')
+})
+
+test('非 wsl 形不受 inheritedWslenv 影响', () => {
+  const env = buildClientEnv('bash', { DSH_X: '1' }, undefined, { inheritedWslenv: 'B' })
+  assert.equal(env.WSLENV, undefined)
+})
+
+test('覆盖集始终在场且可被 dshEnv 覆盖', () => {
+  const env = buildClientEnv('cmd', { PAGER: 'more' })
+  assert.equal(env.NO_COLOR, '1')
+  assert.equal(env.PAGER, 'more')
+  assert.deepEqual(Object.keys(ENV_OVERRIDES).sort(), ['GIT_PAGER', 'NO_COLOR', 'PAGER'])
+})

package/test/executor-seam.test.mjs

@@ -0,0 +1,136 @@
+// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
+// 背景:preset 注入的官方 tool-pwsh 经 cordis 服务代理(ctx.shell)调用执行器,
+// 代理把方法 this 重定向到阴影对象;执行器公开面必须与官方 PwshLocalExecutor
+// 同构地使用公有字段/方法(#私有在阴影 receiver 下触发品牌检查错误)。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import ShellSelectExecutor from '../src/executor.mjs'
+import { Config } from '../src/config.mjs'
+
+function stubReader(text) {
+  return { readFrom: () => ({ text, lossy: false, nextOffset: text.length }) }
+}
+
+function stubSpawn(stdoutText = '', stderrText = '', exitCode = 0) {
+  const calls = []
+  const spawn = (spec) => {
+    calls.push(spec)
+    return {
+      collected: {
+        stdout: stubReader(stdoutText),
+        stderr: stubReader(stderrText),
+      },
+      done: Promise.resolve({ exitCode, signal: null }),
+      terminate: () => true,
+    }
+  }
+  return { spawn, calls }
+}
+
+function stubCtx({ sandboxMode = 'danger-full-access', spawn = stubSpawn() } = {}) {
+  const registered = { tools: [], sections: [], promptSections: [], routes: [] }
+  const settingsImpl = {
+    installSection: (ctx, ns, schema, base, hooks) => {
+      registered.sections.push({ ns, schema, base, hooks })
+      settingsImpl._source = () => Config(base ?? {})
+    },
+  }
+  const ctx = {
+    reflect: { provide: () => {} },
+    logger: { warn: () => {} },
+    get(service) {
+      if (service === 'webServer') return { register: (item) => registered.routes.push(item.path) }
+      return undefined
+    },
+    subprocess: spawn,
+    sandbox: {
+      confine: (argv, policy) => ({
+        argv: ['WRAPPED', ...argv],
+        enforcement: 'full',
+        denialSignatures: ['file access denied'],
+        runnerFailureRules: [],
+        _policy: policy,
+      }),
+    },
+    sandboxPolicy: {
+      defaultMode: sandboxMode,
+      resolve: () => ({ mode: sandboxMode, roots: [] }),
+    },
+    tools: {
+      register: (definition) => {
+        registered.tools.push(definition)
+        return () => registered.tools.pop()
+      },
+    },
+    systemPrompt: {
+      section: (section) => registered.promptSections.push(section),
+      getSectionOrder: (key) => `order:${key}`,
+    },
+    shellEnv: { collect: () => ({ DSH_TEST: '1' }) },
+    settings: settingsImpl,
+    effect: (fn) => fn(),
+  }
+  return { ctx, registered }
+}
+
+/** cordis 阴影 receiver 模拟:服务方法被以非实例 receiver 调用(Reflect.get 语义)。 */
+function shadow(executor) {
+  return Object.create(executor)
+}
+
+test('官方 run seam:存在且走默认客户端,spec 已解析形态(danger 直跑)', async () => {
+  const spawn = stubSpawn('seam-out', '')
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, {})
+  assert.equal(typeof executor.run, 'function')
+  const result = await executor.run(executor.resolve({ command: 'Get-Date', workdir: process.cwd() }))
+  assert.equal(spawn.calls.length, 1)
+  assert.equal(spawn.calls[0].argv[0], executor.entryFor('pwsh').path)
+  assert.equal(result.stdout.text, 'seam-out')
+  assert.deepEqual(result.sandbox, { mode: 'danger-full-access', denied: false })
+})
+
+test('官方 start seam:存在且返回 ShellProcess 形态句柄', async () => {
+  const spawn = stubSpawn('bg', '')
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, {})
+  assert.equal(typeof executor.start, 'function')
+  const proc = executor.start(executor.resolve({ command: 'sleep 1', workdir: process.cwd() }))
+  assert.equal(proc.status, 'running')
+  await proc.done
+  assert.equal(proc.status, 'completed')
+})
+
+test('cordis 阴影 receiver:公开面调用不触发私有品牌错误', () => {
+  const { ctx } = stubCtx()
+  const executor = new ShellSelectExecutor(ctx, {})
+  const mirrored = shadow(executor)
+  // 官方 tool-pwsh 的调用面:resolve/run/start + apply 期 sandboxMode
+  assert.doesNotThrow(() => mirrored.resolve({ command: 'x' }))
+  assert.equal(typeof mirrored.run, 'function')
+  assert.equal(typeof mirrored.start, 'function')
+  assert.equal(mirrored.entryFor(undefined).id, 'pwsh')
+  assert.ok(Array.isArray(mirrored.listShells().shells))
+  assert.equal(mirrored.config.default, 'pwsh')
+  assert.equal(mirrored.sandboxMode, 'danger-full-access')
+})
+
+test('cordis 阴影 receiver:受限模式 run 全链路(confine + 结果分类)', async () => {
+  const spawn = stubSpawn('', 'file access denied here', 1)
+  const { ctx } = stubCtx({ spawn, sandboxMode: 'read-only' })
+  const executor = new ShellSelectExecutor(ctx, {})
+  const mirrored = shadow(executor)
+  const result = await mirrored.run(mirrored.resolve({ command: 'dir', workdir: process.cwd() }))
+  assert.equal(spawn.calls[0].argv[0], 'WRAPPED')
+  assert.equal(result.sandbox.denied, true)
+  assert.equal(result.sandbox.mode, 'read-only')
+})
+
+test('sandboxMode:透出部署默认模式,策略缺席时 undefined', () => {
+  const { ctx } = stubCtx({ sandboxMode: 'workspace-write' })
+  const executor = new ShellSelectExecutor(ctx, {})
+  assert.equal(executor.sandboxMode, 'workspace-write')
+  const bare = new ShellSelectExecutor({ ...ctx, sandboxPolicy: undefined }, {})
+  assert.equal(bare.sandboxMode, undefined)
+})