@mzzsfy/dsh-shell-select 0.1.0

package/src/tool.mjs

@@ -0,0 +1,350 @@
+// shell 工具:官方 dsh-tool-pwsh 逐调用镜像,三处参数化——
+// 1. 工具名 shell(含 shell 枚举参数,模型按名选择客户端);
+// 2. 描述动态含可用客户端清单与方言提示(settings onChange 重注册);
+// 3. 执行经 executor.entryFor/runFor/startFor 按条目 argv 运行。
+// 输出 schema、后台任务语义、升权流程、terminal 卡呈现与官方逐字同构。
+
+import { TOOL_ABORTED, defineTool } from '@deepseek-ai/dsh-tools'
+import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
+import { isAbsolute, resolve } from 'node:path'
+import { renderResult, renderProcessRead } from './render.mjs'
+import { parseExitStatus } from '@deepseek-ai/dsh-shell'
+
+/** 拒升权/Abort 错误构造:dsh-llm HarnessError 缺失时以同码 Error 降级(错误码通道不变)。 */
+async function loadHarnessError(ctx) {
+  try {
+    const dshLlm = await import('@deepseek-ai/dsh-llm')
+    if (typeof dshLlm.HarnessError === 'function') return dshLlm.HarnessError
+  } catch (error) {
+    ctx.logger?.warn?.(`shell-select: dsh-llm HarnessError 不可用,abort 错误降级为普通 Error: ${error?.message ?? error}`)
+  }
+  return class FallbackHarnessError extends Error {
+    constructor(message, code) {
+      super(message)
+      this.code = code
+    }
+  }
+}
+
+/** DenyError 判定:跨层类型检查靠 code(动态 import 环境下 instanceof 不可靠)。 */
+function isDenyError(error) {
+  return error?.code === 'SHELL_COMMAND_BLOCKED'
+}
+
+/** 拒绝 → 模型可见标记文本(与沙箱拒绝标记同风格)。 */
+function blockedMarker(error) {
+  return `[blocked by shell-select: matches deny pattern ${error.pattern}]`
+}
+
+/** 显式 workdir 先行,相对者落会话工作区;否则用会话 cwd,执行器默认兜底(官方同构)。 */
+function resolveWorkdir(modelWorkdir, exec) {
+  const headerCwd = exec.agent?.session.header.cwd
+  if (modelWorkdir === undefined) return headerCwd
+  if (headerCwd !== undefined && !isAbsolute(modelWorkdir)) return resolve(headerCwd, modelWorkdir)
+  return modelWorkdir
+}
+
+/** 后台进程定局 → 通用任务结果词汇(官方同构)。 */
+function processOutcome(proc) {
+  if (proc.status === 'killed') {
+    return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
+  }
+  return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+}
+
+/** 前台结果 DTO 去只读化(官方 canonical 同构)。 */
+function canonicalResult(result) {
+  const output = (stream) => ({
+    text: stream.text,
+    truncated: stream.truncated,
+    ...stream.spillPath !== undefined ? { spillPath: stream.spillPath } : {},
+  })
+  return {
+    kind: 'foreground',
+    exitCode: result.exitCode,
+    signal: result.signal,
+    timedOut: result.timedOut,
+    aborted: result.aborted,
+    timeoutMs: result.timeoutMs,
+    stdout: output(result.stdout),
+    stderr: output(result.stderr),
+    ...result.sandbox !== undefined ? { sandbox: {
+      mode: result.sandbox.mode,
+      denied: result.sandbox.denied,
+      ...result.sandbox.enforcement !== undefined ? { enforcement: result.sandbox.enforcement } : {},
+      ...result.sandbox.runnerFailed !== undefined ? { runnerFailed: result.sandbox.runnerFailed } : {},
+    } } : {},
+  }
+}
+
+/** 后台输出并集公共键(官方同构)。 */
+const BACKGROUND_OUTPUT_PROPERTIES = {
+  kind: { type: 'string', required: true, const: 'background' },
+  jobId: { type: 'string', required: true },
+}
+
+/** 前台输出分支(官方同构,逐字段)。 */
+function foregroundOutputProperties() {
+  const streamSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: true,
+    properties: {
+      text: { type: 'string', required: true },
+      truncated: { type: 'boolean', required: true },
+      spillPath: { type: 'string' },
+    },
+  }
+  return {
+    kind: { type: 'string', required: true, const: 'foreground' },
+    exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
+    signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+    timedOut: { type: 'boolean', required: true },
+    aborted: { type: 'boolean', required: true },
+    timeoutMs: { type: 'number', required: true },
+    stdout: streamSchema,
+    stderr: streamSchema,
+    sandbox: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        mode: { type: 'string', required: true },
+        denied: { type: 'boolean', required: true },
+        enforcement: { type: 'string' },
+        runnerFailed: { type: 'boolean' },
+      },
+    },
+  }
+}
+
+/** 工具描述:客户端清单与方言随配置动态变化。 */
+function shellDescription({ executor, backgroundEnabled, escalationModes }) {
+  const listing = executor.listShells()
+  const lines = listing.shells
+    .map((entry) => `${entry.id} (${entry.kind}${entry.available ? '' : ', executable not found'})`)
+    .join(', ')
+  const base = 'Execute a command in one of the configured shell clients and return its stdout/stderr. '
+    + `Available clients: ${lines}. The default client is "${listing.default}"; pass \`shell\` only when this command needs a different client (dialects differ: pwsh = PowerShell, bash/wsl = POSIX, cmd = cmd.exe). `
+    + 'Each call runs in a fresh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. '
+    + 'Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed environment variables (`DSH_*`); inspect them when needed. '
+    + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
+    + (backgroundEnabled
+      ? 'Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`.'
+      : 'Background execution is not available; long-running commands must finish within the timeout.')
+  if (escalationModes.length === 0) return base
+  return base + ' Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Never escalate speculatively: ground the request in a real denial. If the session states approval prompts are disabled, a denial is final — do not set `sandbox_permissions`.'
+}
+
+/**
+ * 注册 shell 工具,返回卸载 disposer(重注册 = 先卸后挂)。
+ * @param {object} ctx cordis context(需 tools/shellEnv 服务在场)
+ * @param {{executor: object}} faces 执行器实例
+ */
+export function registerShellTool(ctx, { executor }) {
+  const backgroundEnabled = true
+  const escalationModes = ESCALATION_TARGETS
+  let HarnessErrorClass = undefined
+  let disposed = false
+  let HarnessErrorReady = loadHarnessError(ctx).then((resolved) => {
+    HarnessErrorClass = resolved
+    return resolved
+  })
+
+  async function abortError(message) {
+    await HarnessErrorReady
+    const error = new HarnessErrorClass(message, TOOL_ABORTED)
+    error.name = 'AbortError'
+    return error
+  }
+
+  function validateArgs(args) {
+    if (args.command.trim().length === 0) throw new Error('invalid command: expected a non-empty string')
+    if (args.description.trim().length === 0) throw new Error('invalid description: expected a non-empty string')
+    if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+      throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`)
+    }
+    validateEscalationArgs(args.sandbox_permissions, args.justification)
+  }
+
+  const definition = (faces) => defineTool({
+    name: 'shell',
+    description: shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes }),
+    parameters: {
+      command: {
+        type: 'string',
+        required: true,
+        description: 'The command to execute, in the dialect of the selected shell client (default client when `shell` is omitted).',
+      },
+      description: {
+        type: 'string',
+        required: true,
+        description: 'Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI).',
+      },
+      shell: {
+        type: 'string',
+        description: 'Shell client id from the tool description list (e.g. pwsh, git-bash, cmd). Omit to use the configured default client.',
+      },
+      timeoutMs: {
+        type: 'number',
+        description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.',
+      },
+      workdir: {
+        type: 'string',
+        description: 'Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.',
+      },
+      ...backgroundEnabled ? { run_in_background: {
+        type: 'boolean',
+        description: 'Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies.',
+      } } : {},
+      ...escalationModes.length > 0 ? {
+        sandbox_permissions: {
+          type: 'string',
+          enum: [...escalationModes],
+          description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.',
+        },
+        justification: {
+          type: 'string',
+          description: 'Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access.',
+        },
+      } : {},
+    },
+    output: {
+      schema: { oneOf: [{
+        type: 'object',
+        additionalProperties: false,
+        properties: BACKGROUND_OUTPUT_PROPERTIES,
+      }, {
+        type: 'object',
+        additionalProperties: false,
+        properties: foregroundOutputProperties(),
+      }] },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.kind === 'background' ? `started background job ${value.jobId}` : renderResult(value, escalationModes),
+      }],
+    },
+    async execute(args, exec) {
+      validateArgs(args)
+      const standingPolicy = resolveStandingPolicy(exec)
+      const approvedMode = args.sandbox_permissions !== undefined && args.justification !== undefined
+        ? await approveShellEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy)
+        : undefined
+      const policy = approvedMode === undefined ? standingPolicy : { ...standingPolicy, mode: approvedMode }
+      const workdir = resolveWorkdir(args.workdir, exec)
+      const entry = faces.executor.entryFor(args.shell)
+      const request = {
+        command: args.command,
+        ...workdir !== undefined ? { workdir } : {},
+        ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
+        dshEnv: ctx.shellEnv.collect(exec),
+        ...policy !== undefined ? { sandboxPolicy: policy } : {},
+      }
+      if (args.run_in_background === true) {
+        const jobs = ctx.get('jobs')
+        if (jobs === undefined) throw new Error('background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs')
+        if (exec.signal.aborted) throw await abortError('tool call aborted')
+        try {
+          faces.executor.startFor(entry, faces.executor.resolve(request))
+        } catch (error) {
+          if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+          throw error
+        }
+        return {
+          kind: 'background',
+          jobId: jobs.start({
+            kind: 'shell',
+            label: args.command,
+            ...exec.agent ? { owner: exec.agent } : {},
+            run: () => {
+              const proc = faces.executor.startFor(entry, faces.executor.resolve(request))
+              return {
+                cancel: () => void proc.kill(),
+                done: proc.done.then(() => processOutcome(proc)),
+                readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes),
+              }
+            },
+          }),
+        }
+      }
+      let result
+      try {
+        result = await faces.executor.runFor(entry, faces.executor.resolve({
+          ...request,
+          signal: exec.signal,
+        }))
+      } catch (error) {
+        if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+        throw error
+      }
+      if (result.aborted) throw await abortError('tool call aborted')
+      return canonicalResult(result)
+    },
+    presentCall: (args) => {
+      if (args.run_in_background === true) {
+        return {
+          card: 'generic',
+          title: args.command,
+          kind: 'execute',
+          rawInput: args.command,
+          content: [{ type: 'text', text: args.description }],
+        }
+      }
+      return {
+        card: 'terminal',
+        title: args.command,
+        description: args.description,
+        ...args.workdir !== undefined ? { cwd: args.workdir } : {},
+      }
+    },
+    presentResult: (args, result) => {
+      const block = result.content.length === 1 ? result.content[0] : undefined
+      if (block === undefined || block.type !== 'text') return undefined
+      const raw = block.text
+      if (typeof args === 'object' && args !== null && args.run_in_background === true || result.isError) {
+        return {
+          card: 'generic',
+          content: [{ type: 'text', text: `\`\`\`console\n${raw.replace(/\n+$/, '')}\n\`\`\`` }],
+        }
+      }
+      const { body, ...exit } = parseExitStatus(raw)
+      return {
+        card: 'terminal',
+        output: body,
+        ...exit,
+      }
+    },
+  })
+
+  /** 会话在场时解析其完整标准策略,直调落部署策略(官方同构)。 */
+  function resolveStandingPolicy(exec) {
+    const sandboxPolicy = ctx.get('sandboxPolicy')
+    if (sandboxPolicy === undefined) return undefined
+    return sandboxPolicy.resolve(exec.agent === undefined ? {} : { session: exec.agent.session })
+  }
+
+  /** 升权审批:先于执行,共享 fail-closed 序列交 approveEscalation(官方同构)。 */
+  function approveShellEscalation(mode, justification, exec, standingPolicy) {
+    if (escalationModes.length === 0) throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
+    const approver = ctx.get('approval')
+    return approveEscalation({
+      requestedMode: mode,
+      justification,
+      effectiveMode: standingPolicy.mode,
+      subject: 'command',
+    }, {
+      approver,
+      agent: exec.agent,
+      callId: exec.callId,
+      toolName: 'shell',
+      signal: exec.signal,
+    })
+  }
+
+  const faces = { executor }
+  const disposer = ctx.tools.register(definition(faces))
+  return () => {
+    if (disposed) return
+    disposed = true
+    disposer()
+  }
+}

package/test/client-card.test.mjs

@@ -0,0 +1,106 @@
+// shellCardModel 行为测试:LOGIC 段提取(client.js 工厂内纯函数,形态照
+// dsh-maintain/test/logic-extract.mjs)。BDD 场景见 docs/feat-shell-select-optim/plan.md S11-S13。
+
+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 extractLogic(name, deps = {}) {
+  const pattern = new RegExp('// LOGIC-BEGIN ' + name + '\\n([\\s\\S]*?)\\n\\s*// LOGIC-END ' + name)
+  const match = source.match(pattern)
+  if (!match) throw new Error('client.js 缺少 LOGIC 段: ' + name)
+  const keys = Object.keys(deps)
+  return new Function(...keys, 'return (' + match[1].trim() + ')')(...keys.map((key) => deps[key]))
+}
+
+function cardModel() {
+  const lastSegment = extractLogic('lastSegment')
+  const displayCwd = extractLogic('displayCwd', { lastSegment })
+  return extractLogic('shellCardModel', { displayCwd, lastSegment, parseExitTail: extractLogic('parseExitTail'), hasSpillNotice: extractLogic('hasSpillNotice') })
+}
+
+function parseEnvText() {
+  return extractLogic('parseEnvText')
+}
+
+function invalidEnvLines() {
+  return extractLogic('invalidEnvLines')
+}
+
+// 运行中调用块(官方形态:无 kind 字段)
+function runningBlock(argsRaw) {
+  return { callId: 'c1', name: 'shell', argsRaw }
+}
+
+// 已定调用块(官方形态:kind 字段在)
+function settledBlock(argsRaw, text, options = {}) {
+  return {
+    kind: 'tool',
+    callId: 'c1',
+    call: { callId: 'c1', name: 'shell', argsRaw },
+    content: [{ type: 'text', text }],
+    isError: options.isError,
+  }
+}
+
+const ARGS = JSON.stringify({ command: 'git status', description: 'Show working tree status', workdir: 'sub' })
+const SESSION_CWD = 'C:\\repo'
+
+test('S11 running 且无 description(persistent 形)回退 generic', () => {
+  const model = cardModel()(runningBlock(JSON.stringify({ command: 'interactive session' })), SESSION_CWD)
+  assert.equal(model.kind, 'generic')
+  assert.equal(model.running, true)
+})
+
+test('S11b settled 无 description(persistent 结束)回退 generic', () => {
+  const model = cardModel()(settledBlock(JSON.stringify({ command: 'interactive session' }), 'out\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(model.kind, 'generic')
+})
+
+test('S12 官方 pwsh 形 settled:terminal 卡派生退出码与输出', () => {
+  const model = cardModel()(settledBlock(ARGS, 'On branch main\n[exit code: 2]', { isError: false }), SESSION_CWD)
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.status, 'failed')
+  assert.equal(model.exitCode, 2)
+  assert.equal(model.output, 'On branch main')
+  assert.equal(model.cwdDir, 'sub')
+})
+
+test('S12b running 完整参数:terminal running 卡', () => {
+  const model = cardModel()(runningBlock(ARGS), SESSION_CWD)
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.status, 'running')
+})
+
+test('S12c 后台 ack 与 isError 仍走 generic(回归)', () => {
+  const background = cardModel()(
+    settledBlock(JSON.stringify({ ...JSON.parse(ARGS), run_in_background: true }), 'started', { isError: false }),
+    SESSION_CWD,
+  )
+  assert.equal(background.kind, 'generic')
+  const errored = cardModel()(settledBlock(ARGS, 'boom', { isError: true }), SESSION_CWD)
+  assert.equal(errored.kind, 'generic')
+})
+
+test('S13 注册面:shell/pwsh/bash 三 key 且 priority -1(文本守卫)', () => {
+  assert.match(source, /const TOOLVIEW_KEYS = \['shell', 'pwsh', 'bash'\]/)
+  assert.match(source, /key: toolKey, priority: -1/)
+})
+
+test('K=V 往返:值含 = 与空格无损,空行忽略,重复键后行胜', () => {
+  const parse = parseEnvText()
+  assert.deepEqual(parse('A=1\nB=x=y z\n\nA=2'), { A: '2', B: 'x=y z' })
+  assert.deepEqual(parse(''), {})
+  assert.deepEqual(parse(undefined), {})
+})
+
+test('invalidEnvLines:缺 = 行报出,空行不报', () => {
+  const invalid = invalidEnvLines()
+  assert.deepEqual(invalid('A=1\nbroken\n\n  noSep  '), ['broken', 'noSep'])
+  assert.deepEqual(invalid('A=1'), [])
+})

package/test/client-drift.test.mjs

@@ -0,0 +1,27 @@
+// 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/client-id.test.mjs

@@ -0,0 +1,68 @@
+// client-id 守卫:样式注入点必须伴随 data-plugin=@mzzsfy/dsh-shell-select 标记
+// (仓库契约,守卫形态照 dsh-cron-board/test/client-id.test.mjs:createElement('style')
+// 与 setAttribute('data-plugin') 计数相等)。
+
+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')
+
+test('head 注入样式全部带 data-plugin 标记', () => {
+  const createElementStyle = (source.match(/createElement\('style'/g) ?? []).length
+    + (source.match(/createElement\("style"/g) ?? []).length
+  const marked = (source.match(/'data-plugin'/g) ?? []).length + (source.match(/"data-plugin"/g) ?? []).length
+  assert.ok(createElementStyle > 0, 'client.js 应至少有一个样式注入点')
+  assert.equal(marked, createElementStyle, '每个 createElement(\'style\') 必须伴随一个 data-plugin 标记')
+})
+
+test('标记值为完整 npm 包名', () => {
+  assert.match(source, /setAttribute\('data-plugin', '@mzzsfy\/dsh-shell-select'\)/)
+})
+
+test('settings.section 注册与 id', () => {
+  assert.match(source, /settings\.section/)
+  assert.match(source, /id: 'shell-select'/)
+})
+
+test('tool.call.toolview 注册:shell 族三 key + priority -1', () => {
+  assert.match(source, /'tool\.call\.toolview'/)
+  assert.match(source, /const TOOLVIEW_KEYS = \['shell', 'pwsh', 'bash'\]/)
+  assert.match(source, /key: toolKey, priority: -1/)
+})
+
+test('卡片数据链:官方同构派生(argsRaw + content 尾部退出标记)+ generic 回退', () => {
+  assert.match(source, /parseExitTail/)
+  assert.ok(source.includes("[exit code: ("), '缺少 exit 尾标解析')
+  assert.match(source, /kind: 'generic'/)
+})
+
+test('primitives 缺席时图标降级自绘(require 有 try/catch 兜底)', () => {
+  assert.match(source, /require\('@deepseek-ai\/dsh-client-ui-primitives'\)/)
+  assert.match(source, /catch \{\s*return null\s*\}/)
+})
+
+test('扩展字段守卫:login/distro/env 进设置页数据链(wholesale replace 防静默重置)', () => {
+  // toSection(保存)与 toEntries(加载)必须同时携带 login/distro;
+  // env 走 envText(K=V 每行)编辑态往返:保存侧 parseEnvText,加载侧 envText
+  for (const field of ['login', 'distro']) {
+    const writes = (source.match(new RegExp(`^\\s*${field}: .*$`, 'gm')) ?? []).length
+    assert.ok(writes >= 2, `toSection/toEntries 应各携带 ${field}(发现 ${writes} 处)`)
+  }
+  assert.match(source, /env: parseEnvText\(entry\.envText\)/)
+  assert.match(source, /envText: Object\.entries\(entry\.env \?\? \{\}\)/)
+  assert.match(source, /登录壳/)
+  assert.match(source, /发行版/)
+})
+
+test('deny 名单进设置页数据链:state/toSection/校验/往返;allow 已移除(deny 绝对)', () => {
+  assert.match(source, /denyText/)
+  assert.match(source, /deny: splitPatternLines\(denyText\)/)
+  assert.match(source, /名单正则非法/)
+  assert.match(source, /拒绝名单/)
+  assert.doesNotMatch(source, /allowText/)
+  assert.doesNotMatch(source, /豁免名单/)
+})

package/test/config-entry.test.mjs

@@ -0,0 +1,93 @@
+// 条目级 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'
+
+test('S5 schema 默认:条目 env 空对象、distro 空串,旧配置反序列化补默认', () => {
+  const config = Config({ shells: [{ id: 'w', name: 'WSL', kind: 'wsl' }], default: 'w' })
+  const entry = config.shells[0]
+  assert.deepEqual(entry.env, {})
+  assert.equal(entry.distro, '')
+  const factory = defaultConfig()
+  assert.deepEqual(factory.shells[0].env, {})
+  assert.equal(factory.shells[0].distro, '')
+})
+
+test('S8 wsl distro 非空:argv 带 -d 发行版', () => {
+  const argv = buildArgv({ kind: 'wsl', path: 'C:\\wsl.exe', distro: 'Ubuntu' }, 'ls')
+  assert.deepEqual(argv, ['C:\\wsl.exe', '-d', 'Ubuntu', '--exec', 'bash', '-c', 'ls'])
+})
+
+test('S9 wsl distro 空:argv 现状形态', () => {
+  const argv = buildArgv({ kind: 'wsl', path: 'C:\\wsl.exe', distro: '' }, 'ls')
+  assert.deepEqual(argv, ['C:\\wsl.exe', '--exec', 'bash', '-c', 'ls'])
+})
+
+test('S10 args 模板条目接管 argv,distro 不出现', () => {
+  const argv = buildArgv({ kind: 'wsl', path: 'C:\\wsl.exe', args: ['--data', '{command}'], distro: 'Ubuntu' }, 'ls')
+  assert.deepEqual(argv, ['C:\\wsl.exe', '--data', 'ls'])
+})
+
+test('S6 entryFor 透传 env 与 distro;spawnSpec env 含条目键', () => {
+  const cmdPath = `${process.env.SystemRoot ?? 'C:\\WINDOWS'}\\System32\\cmd.exe`
+  const config = Config({
+    shells: [{ id: 'c', name: 'CMD', kind: 'cmd', path: cmdPath, env: { MSYSTEM: 'MINGW64' } }, { id: 'p', name: 'pwsh', kind: 'pwsh' }],
+    default: 'c',
+  })
+  const executor = new ShellSelectExecutor(stubCtxFor(config), config)
+  const entry = executor.entryFor('c')
+  assert.deepEqual(entry.env, { MSYSTEM: 'MINGW64' })
+  const spec = executor.resolve({ command: 'ver', workdir: process.cwd() })
+  const spawned = executor.spawnSpec(entry, spec, executor.argvFor(entry, spec), 1024, undefined)
+  assert.equal(spawned.env.MSYSTEM, 'MINGW64')
+  assert.equal(spawned.env.NO_COLOR, '1')
+})
+
+test('S7 updateConfig 接受 env/distro 字段并落盘回读', async () => {
+  const section = Config({
+    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 wsl = next.shells.find((entry) => entry.id === 'w')
+  assert.equal(wsl.distro, 'Debian')
+  assert.deepEqual(wsl.env, { LANG: 'C.UTF-8' })
+})
+
+function stubCtxFor(config) {
+  const registered = { sections: [], tools: [], promptSections: [], routes: [] }
+  return {
+    reflect: { provide: () => {} },
+    logger: { warn: () => {} },
+    effect: (fn) => { registered.routes.push(fn) },
+    get() { return { register: () => {} } },
+    subprocess: { spawn: () => { throw new Error('not expected') } },
+    sandbox: { confine: (argv) => ({ argv, enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }) },
+    sandboxPolicy: { resolve: () => ({ mode: 'danger-full-access', roots: [] }) },
+    tools: { register: (definition) => registered.tools.push(definition) },
+    systemPrompt: {
+      section: (item) => registered.promptSections.push(item),
+      getSectionOrder: () => 10,
+    },
+    settings: {
+      installSection: (ctx, ns, schema, base) => {
+        registered.sections.push({ ns, base })
+      },
+      replace: async (ns, next) => { registered.replaced = { ns, next } },
+    },
+    webServer: undefined,
+    shellEnv: { collect: () => ({}) },
+    _config: config,
+    _registered: registered,
+    ...configAccessor(),
+  }
+  function configAccessor() {
+    return { get config() { return config } }
+  }
+}