dsh-gufa-code 0.0.0-stage → 1.0.1

package/host/project.js

@@ -0,0 +1,305 @@
+/**
+ * 项目：打开 / 新建 / 校验。只有这里登记过的目录，fs/git/terminal 才允许访问。
+ */
+import { mkdir, realpath, stat } from 'node:fs/promises'
+import { isAbsolute, resolve, sep } from 'node:path'
+import { ApiError, badRequest } from './context.js'
+import { debugLog } from './dev.js'
+
+async function describeDirectory(rawPath) {
+  if (typeof rawPath !== 'string' || rawPath.trim() === '') throw badRequest('path is required')
+  if (!isAbsolute(rawPath)) throw badRequest('path must be absolute')
+  const absolute = resolve(rawPath)
+  let canonical
+  try {
+    canonical = await realpath(absolute)
+  } catch {
+    throw new ApiError('not-found', `目录不存在：${absolute}`, 404)
+  }
+  const info = await stat(canonical)
+  if (!info.isDirectory()) throw new ApiError('not-directory', `不是目录：${canonical}`, 400)
+  return { canonical, info }
+}
+
+export function register(router, env) {
+  router.method('project.open', async (body) => {
+    const project = await env.projects.open(body.path)
+    return project
+  })
+
+  router.method('project.validate', async (body) => {
+    const { canonical, info } = await describeDirectory(body.path)
+    const isGit = await stat(resolve(canonical, '.git')).then(() => true, () => false)
+    return { root: canonical, name: canonical.split(sep).filter(Boolean).at(-1) ?? canonical, isGit, mtimeMs: info.mtimeMs }
+  })
+
+  router.method('project.create', async (body) => {
+    if (typeof body.name !== 'string' || body.name.trim() === '') throw badRequest('项目名不能为空')
+    const name = body.name.trim()
+    if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') throw badRequest('项目名包含非法字符')
+    if (typeof body.parent !== 'string' || !isAbsolute(body.parent)) throw badRequest('parent must be an absolute path')
+    const { canonical: parentCanonical } = await describeDirectory(body.parent)
+    const target = resolve(parentCanonical, name)
+    try {
+      await mkdir(target)
+    } catch (error) {
+      if (error !== null && typeof error === 'object' && error.code === 'EEXIST') throw new ApiError('exists', '同名目录已存在', 409)
+      throw error
+    }
+    return await env.projects.open(target)
+  })
+
+  router.method('project.list', async () => ({ projects: env.projects.list() }))
+
+  router.method('project.forget', async (body) => {
+    if (typeof body.root === 'string') env.projects.forget(body.root)
+    return { projects: env.projects.list() }
+  })
+
+  /** 在 Host 上下文中惰性取服务（兼容 ctx.get 与属性两种访问方式）。 */
+  function serviceOf(name) {
+    const ctx = env.ctx
+    if (ctx === null || ctx === undefined) return undefined
+    try {
+      if (typeof ctx.get === 'function') {
+        const value = ctx.get(name)
+        if (value !== undefined && value !== null) return value
+      }
+    } catch {
+      /* 未注入时 ctx.get 可能抛错，继续尝试属性 */
+    }
+    try {
+      return ctx[name]
+    } catch {
+      return undefined
+    }
+  }
+
+  /** DSH 原生工作区列表（与经典模式同一份 workspaceRegistry 数据）。 */
+  router.method('workspaces.list', async () => {
+    const registry = serviceOf('workspaceRegistry')
+    if (registry === undefined || registry === null || typeof registry.list !== 'function') {
+      return { available: false, workspaces: [] }
+    }
+    let list = []
+    try {
+      list = registry.list()
+    } catch {
+      list = []
+    }
+    const workspaces = (Array.isArray(list) ? list : [])
+      .map((item) => {
+        const value = item !== null && typeof item === 'object' ? item : {}
+        return {
+          id: typeof value.id === 'string' ? value.id : '',
+          path: typeof value.path === 'string' ? value.path : '',
+          title: typeof value.title === 'string' && value.title !== '' ? value.title : '',
+        }
+      })
+      .filter((item) => item.id !== '')
+    return { available: true, workspaces }
+  })
+
+  /** 当前工作区的会话列表（标题/时间），复刻经典侧边栏的可见性规则：
+   *  工作区 sessionIds 成员 → 排除归档 → 排除 subagent 子会话 → 隐藏 blank（空会话，当前会话除外）
+   *  → 标题取自 sessionQuery.readTitleSnapshots / sessionTitle → 按更新时间倒序。 */
+  router.method('workspaces.sessions', async (body) => {
+    try {
+      const controller = serviceOf('workspaceController')
+      const registry = serviceOf('workspaceRegistry')
+      const query = serviceOf('sessionQuery')
+      const sessions = serviceOf('sessions')
+      const titles = serviceOf('sessionTitle')
+
+      let views = []
+      let archivedSessionIds = []
+      let source = 'controller'
+
+      if (controller !== undefined && controller !== null && typeof controller.follow === 'function') {
+        const abort = new AbortController()
+        try {
+          const iterator = controller.follow(abort.signal)[Symbol.asyncIterator]()
+          const first = await iterator.next()
+          try {
+            await iterator.return?.()
+          } catch {
+            /* ignore */
+          }
+          const frame = first?.value
+          if (frame !== null && typeof frame === 'object' && (frame.type === 'baseline' || frame.type === 'replace') && frame.value !== null && typeof frame.value === 'object') {
+            if (Array.isArray(frame.value.items)) views = frame.value.items
+            if (Array.isArray(frame.value.archivedSessionIds)) archivedSessionIds = frame.value.archivedSessionIds
+          }
+        } catch {
+          views = []
+        } finally {
+          abort.abort()
+        }
+      }
+      if (views.length === 0 && registry !== undefined && registry !== null && typeof registry.list === 'function') {
+        source = 'registry'
+        try {
+          views = registry.list().map((item) => ({
+            workspaceId: item.id,
+            path: item.path,
+            title: item.title,
+            sessionIds: Array.isArray(item.sessionIds) ? item.sessionIds : [],
+          }))
+        } catch {
+          views = []
+        }
+      }
+
+      const workspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : ''
+      const path = typeof body.path === 'string' ? body.path : ''
+      const currentSessionId = typeof body.currentSessionId === 'string' ? body.currentSessionId : ''
+      const target = views.find((item) => (workspaceId !== '' ? item.workspaceId === workspaceId : item.path === path))
+      const membership = target !== undefined && Array.isArray(target.sessionIds) ? target.sessionIds.filter((id) => typeof id === 'string') : []
+      const archivedSet = new Set(archivedSessionIds)
+
+      /* 记录元信息：父子关系（subagent）与创建时间 */
+      let records = []
+      try {
+        if (query !== undefined && query !== null && typeof query.listSessions === 'function') {
+          records = await query.listSessions(new AbortController().signal)
+        }
+      } catch {
+        records = []
+      }
+      const metaById = new Map()
+      for (const record of Array.isArray(records) ? records : []) {
+        if (record === null || typeof record !== 'object') continue
+        const header = record.header !== null && typeof record.header === 'object' ? record.header : null
+        const id = typeof header?.id === 'string' ? header.id : typeof record.id === 'string' ? record.id : ''
+        if (id === '') continue
+        const parentRaw = header?.parentSession ?? record.parentSession ?? record.parentSessionId ?? record.parentId
+        const parent = typeof parentRaw === 'string' ? parentRaw : parentRaw !== null && typeof parentRaw === 'object' && typeof parentRaw.id === 'string' ? parentRaw.id : ''
+        const depth = typeof header?.delegationDepth === 'number' ? header.delegationDepth : 0
+        const createdAt = (() => {
+          for (const value of [header?.createdAt, record.updatedAt, record.createdAt]) {
+            if (typeof value === 'number' && Number.isFinite(value)) return value
+            if (typeof value === 'string') {
+              const parsed = Date.parse(value)
+              if (Number.isFinite(parsed)) return parsed
+            }
+          }
+          return 0
+        })()
+        metaById.set(id, { parent, depth, createdAt })
+      }
+
+      /* 标题：批量快照 → 逐个 readTitle → 会话服务兜底；记录哪些是"解析到了" */
+      const titleById = new Map()
+      const updatedAtById = new Map()
+      const titleKnown = new Set()
+      let titleError = ''
+      let batchResolved = false
+      try {
+        if (query !== undefined && query !== null && typeof query.readTitleSnapshots === 'function' && membership.length > 0) {
+          const snapshots = await query.readTitleSnapshots(membership, new AbortController().signal)
+          if (snapshots !== null && typeof snapshots === 'object' && Object.keys(snapshots).length > 0) {
+            batchResolved = true
+            for (const id of membership) {
+              const snapshot = snapshots[id] ?? snapshots.get?.(id)
+              if (snapshot === null || snapshot === undefined) continue
+              titleKnown.add(id)
+              if (typeof snapshot.title === 'string') titleById.set(id, snapshot.title)
+              if (typeof snapshot.updatedAt === 'number') updatedAtById.set(id, snapshot.updatedAt)
+            }
+          }
+        }
+      } catch (error) {
+        titleError = error instanceof Error ? error.message : String(error)
+      }
+      if (titleKnown.size === 0 && query !== undefined && query !== null && typeof query.readTitle === 'function') {
+        for (const id of membership) {
+          try {
+            const snapshot = await query.readTitle(id, new AbortController().signal)
+            if (snapshot === null || snapshot === undefined) continue
+            titleKnown.add(id)
+            if (typeof snapshot.title === 'string') titleById.set(id, snapshot.title)
+            if (typeof snapshot.updatedAt === 'number') updatedAtById.set(id, snapshot.updatedAt)
+          } catch (error) {
+            titleError = titleError === '' ? (error instanceof Error ? error.message : String(error)) : titleError
+          }
+        }
+      }
+      for (const id of membership) {
+        if (titleById.get(id) !== undefined && titleById.get(id) !== '') continue
+        try {
+          if (sessions !== undefined && sessions !== null && typeof sessions.get === 'function') {
+            const session = sessions.get(id)
+            if (session !== null && session !== undefined) {
+              if (titles !== undefined && titles !== null && typeof titles.get === 'function') {
+                const snapshot = titles.get(session)
+                if (snapshot !== null && snapshot !== undefined && typeof snapshot.title === 'string') titleById.set(id, snapshot.title)
+              }
+              if (titleById.get(id) === undefined && typeof session.title === 'string') titleById.set(id, session.title)
+              if (updatedAtById.get(id) === undefined && typeof session.updatedAt === 'number') updatedAtById.set(id, session.updatedAt)
+            }
+          }
+        } catch {
+          /* ignore */
+        }
+      }
+
+      const rows = []
+      for (const id of membership) {
+        if (archivedSet.has(id)) continue
+        const meta = metaById.get(id)
+        if (meta !== undefined && (meta.parent !== '' || meta.depth > 0)) continue
+        const title = titleById.get(id) ?? ''
+        const known = titleKnown.has(id)
+        // blank 会话不会出现在标题快照结果里：批量解析成功但缺少该项 = blank；当前会话例外
+        const blank = (known && title.trim() === '') || (batchResolved && !known)
+        if (blank && id !== currentSessionId) continue
+        rows.push({
+          id,
+          title,
+          updatedAt: updatedAtById.get(id) ?? meta?.createdAt ?? 0,
+        })
+      }
+      rows.sort((a, b) => b.updatedAt - a.updatedAt)
+
+      debugLog(`sessions path=${path} membership=${membership.length} visible=${rows.length} titleKnown=${titleKnown.size} batch=${batchResolved} titleError=${titleError === '' ? '-' : titleError.slice(0, 120)} rows=${rows.map((row) => `${row.id.slice(8, 12)}:${String(row.title).slice(0, 10)}`).join('|')}`)
+      return {
+        available: true,
+        source: source + '+membership',
+        workspaceId: target !== undefined && typeof target.workspaceId === 'string' ? target.workspaceId : workspaceId,
+        title: target !== undefined && typeof target.title === 'string' ? target.title : '',
+        path: target !== undefined && typeof target.path === 'string' ? target.path : path,
+        sessionIds: membership,
+        archivedSessionIds,
+        sessions: rows,
+        groups: [{ workspaceId: target !== undefined && typeof target.workspaceId === 'string' ? target.workspaceId : workspaceId, title: target !== undefined && typeof target.title === 'string' ? target.title : '', path: target !== undefined && typeof target.path === 'string' ? target.path : path, sessions: rows }],
+        debug: { membership: membership.length, visible: rows.length, archived: archivedSessionIds.length, records: Array.isArray(records) ? records.length : 0 },
+      }
+    } catch (error) {
+      return { available: false, error: error instanceof Error ? error.message : String(error), sessions: [], groups: [], sessionIds: [], archivedSessionIds: [] }
+    }
+  })
+
+  /** 新建工作区时的默认目录（用于选择器起点）。 */
+  router.method('workspaces.defaultDirectory', async () => {
+    let directory = ''
+    try {
+      const working = serviceOf('workingDirectory')
+      if (working !== undefined && working !== null && typeof working.defaultDirectory === 'string') directory = working.defaultDirectory
+    } catch {
+      directory = ''
+    }
+    if (directory === '') {
+      try {
+        directory = (await import('node:os')).homedir()
+      } catch {
+        directory = ''
+      }
+    }
+    return { directory }
+  })
+
+  router.method('project.home', async () => {
+    const home = (await import('node:os')).homedir()
+    return { home }
+  })
+}

package/host/ssh.js

@@ -0,0 +1,54 @@
+/**
+ * SSH：读取 ~/.ssh/config 主机列表，供左侧 SSH 面板一键连接（连接在终端里执行 ssh <alias>）。
+ */
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** 解析 ssh_config 的 Host 块（忽略通配 Host *）。 */
+export function parseSshConfig(text) {
+  const hosts = []
+  let current = null
+  let inBlock = false
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim()
+    if (line === '' || line.startsWith('#')) continue
+    const match = /^(\w+)\s+(.*)$/.exec(line)
+    if (match === null) continue
+    const key = match[1].toLowerCase()
+    const value = match[2].split('#')[0].trim()
+    if (key === 'host') {
+      if (current !== null) hosts.push(current)
+      const aliases = value.split(/\s+/).filter((item) => item !== '' && !item.includes('*') && !item.includes('?'))
+      current = aliases.length === 0
+        ? null
+        : { alias: aliases[0], aliases, host: aliases[0], user: '', port: '' }
+      inBlock = current !== null
+      continue
+    }
+    if (!inBlock || current === null) continue
+    if (key === 'hostname') current.host = value
+    else if (key === 'user') current.user = value
+    else if (key === 'port') current.port = value
+  }
+  if (current !== null) hosts.push(current)
+  const seen = new Set()
+  return hosts.filter((host) => {
+    if (seen.has(host.alias)) return false
+    seen.add(host.alias)
+    return true
+  })
+}
+
+export function register(router) {
+  router.method('ssh.hosts', async () => {
+    const candidates = [join(homedir(), '.ssh', 'config'), join(homedir(), '.ssh', 'config.d')]
+    let text = ''
+    try {
+      text = await readFile(candidates[0], 'utf8')
+    } catch {
+      text = ''
+    }
+    return { hosts: parseSshConfig(text), configPath: candidates[0] }
+  })
+}

package/host/terminal-pty.js

@@ -0,0 +1,237 @@
+/**
+ * 终端 PTY 的纯工具层：与 Cordis / node-pty 无关，便于单测。
+ *
+ * 提供：
+ *   - filteredEnvironment()  过滤敏感环境变量后交给 PTY（KEY/TOKEN/SECRET/…）
+ *   - ReplayBuffer           按 UTF-8 字节计量的输出回放缓冲（默认 2MB），支持 since 增量续传
+ *   - clampInteger()         cols / rows 规范化
+ *   - resolveShellPath()     选择登录 shell（显式参数 → provider 默认 → $SHELL → 平台默认）
+ *
+ * 这些逻辑被 host/terminal.js 使用，并由 scripts/selftest-terminal.mjs 覆盖。
+ */
+import { stat } from 'node:fs/promises'
+import { isAbsolute } from 'node:path'
+
+/** 传给 PTY 的 TERM；subprocess 会把同一值写入终端环境。 */
+export const TERMINAL_TYPE = 'xterm-256color'
+/** 每个项目根目录下最多保留的终端数。 */
+export const MAX_TERMINALS_PER_ROOT = 8
+/** 每个终端的输出回放缓冲上限（字节，按解码后的 UTF-8 计）。 */
+export const REPLAY_LIMIT_BYTES = 2 * 1024 * 1024
+/** PTY 终止宽限（TERM → KILL）。 */
+export const TERMINAL_GRACE_MS = 5000
+/** 终端创建请求的默认 / 边界尺寸。 */
+export const DEFAULT_COLS = 80
+export const DEFAULT_ROWS = 24
+export const MIN_COLS = 2
+export const MAX_COLS = 1000
+export const MIN_ROWS = 2
+export const MAX_ROWS = 500
+
+/**
+ * 敏感环境变量名：不传给终端 shell。
+ * 按「名字边界」匹配，避免误伤 MONKEY / KEYBOARD 之类普通变量；
+ * 同时保留 SSH_AUTH_SOCK、GIT_AUTHOR_* 等交互式 shell 常用变量。
+ */
+export const SENSITIVE_ENV_PATTERN = /(^|_)(API_?KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY)(_|$)/i
+/** DSH 内部变量不暴露给终端 shell。 */
+export const DSH_ENV_PREFIX = 'DSH_'
+
+/**
+ * 生成传给 PTY 的环境变量：过滤敏感名与 DSH_*，其余原样保留（HOME/PATH/LANG/SHELL…）。
+ * @param {NodeJS.ProcessEnv} [base]
+ * @returns {Record<string, string>}
+ */
+export function filteredEnvironment(base = process.env) {
+  /** @type {Record<string, string>} */
+  const env = {}
+  for (const [name, value] of Object.entries(base)) {
+    if (typeof value !== 'string') continue
+    if (name.toUpperCase().startsWith(DSH_ENV_PREFIX)) continue
+    if (SENSITIVE_ENV_PATTERN.test(name)) continue
+    env[name] = value
+  }
+  env.TERM = TERMINAL_TYPE
+  if (env.COLORTERM === undefined) env.COLORTERM = 'truecolor'
+  return env
+}
+
+/** 把任意输入规范成 [min, max] 内的整数；非法值返回 fallback。 */
+export function clampInteger(value, fallback, min, max) {
+  const number = typeof value === 'number' ? value : Number(value)
+  if (!Number.isFinite(number)) return fallback
+  return Math.min(max, Math.max(min, Math.trunc(number)))
+}
+
+/** 判断一个码元是否为 UTF-16 低代理项（避免按字节截断时切坏字符）。 */
+function isLowSurrogate(code) {
+  return code >= 0xdc00 && code <= 0xdfff
+}
+
+/** 取字符串尾部不超过 limit 字节的最长片段（按 UTF-8，尽量不切坏字符）。 */
+export function tailByBytes(text, limit) {
+  if (limit <= 0) return ''
+  if (Buffer.byteLength(text, 'utf8') <= limit) return text
+  let low = 0
+  let high = text.length
+  while (low < high) {
+    const middle = (low + high) >> 1
+    if (Buffer.byteLength(text.slice(middle), 'utf8') > limit) low = middle + 1
+    else high = middle
+  }
+  if (low > 0 && isLowSurrogate(text.charCodeAt(low))) low += 1
+  return text.slice(low)
+}
+
+/**
+ * 按 UTF-8 字节计量的输出回放缓冲。
+ *
+ * 语义：
+ *   - totalBytes 是「历史上写入过的全部文本字节数」，即绝对偏移；
+ *   - 只保留最新 limitBytes 字节；retainedStart 是保留窗口的绝对起始偏移；
+ *   - sliceFrom(offset) 返回从绝对偏移 offset 开始的可续传文本；若 offset 已滑出窗口
+ *     或落点非法，返回 { lossy: true, text: 完整保留窗口 }，调用方应先让客户端 reset。
+ */
+export class ReplayBuffer {
+  /** @type {{ text: string, bytes: number, start: number }[]} */
+  #entries = []
+  #bytes = 0
+  #totalBytes = 0
+
+  constructor(limitBytes = REPLAY_LIMIT_BYTES) {
+    this.limitBytes = Number.isSafeInteger(limitBytes) && limitBytes > 0 ? limitBytes : REPLAY_LIMIT_BYTES
+  }
+
+  /** 保留窗口的字节数。 */
+  get retainedBytes() {
+    return this.#bytes
+  }
+
+  /** 保留窗口的绝对起始偏移。 */
+  get retainedStart() {
+    return this.#entries.length === 0 ? this.#totalBytes : this.#entries[0].start
+  }
+
+  /** 历史写入的总字节数（绝对偏移上界）。 */
+  get totalBytes() {
+    return this.#totalBytes
+  }
+
+  get size() {
+    return this.#entries.length
+  }
+
+  /** 追加一段解码后的输出。 */
+  push(text) {
+    if (typeof text !== 'string' || text === '') return
+    const bytes = Buffer.byteLength(text, 'utf8')
+    this.#totalBytes += bytes
+    if (bytes >= this.limitBytes) {
+      const tail = tailByBytes(text, this.limitBytes)
+      const tailBytes = Buffer.byteLength(tail, 'utf8')
+      this.#entries = [{ text: tail, bytes: tailBytes, start: this.#totalBytes - tailBytes }]
+      this.#bytes = tailBytes
+      return
+    }
+    this.#entries.push({ text, bytes, start: this.#totalBytes - bytes })
+    this.#bytes += bytes
+    while (this.#bytes > this.limitBytes && this.#entries.length > 1) {
+      const removed = this.#entries.shift()
+      this.#bytes -= removed.bytes
+    }
+  }
+
+  /** 返回保留窗口内的完整文本。 */
+  toString() {
+    return this.#entries.map((entry) => entry.text).join('')
+  }
+
+  /**
+   * 从绝对偏移 offset 续传。
+   * @param {number} offset
+   * @returns {{ text: string, lossy: boolean }}
+   */
+  sliceFrom(offset) {
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > this.#totalBytes) {
+      return { text: this.toString(), lossy: true }
+    }
+    if (offset === this.#totalBytes) return { text: '', lossy: false }
+    const start = this.retainedStart
+    if (offset < start) return { text: this.toString(), lossy: true }
+    for (let index = 0; index < this.#entries.length; index += 1) {
+      const entry = this.#entries[index]
+      if (entry.start !== offset) continue
+      return { text: this.#entries.slice(index).map((item) => item.text).join(''), lossy: false }
+    }
+    // 偏移落在某个 chunk 内部（正常流式下不会出现；仅当调用方计数与写入边界不一致时兜底）。
+    for (let index = 0; index < this.#entries.length; index += 1) {
+      const entry = this.#entries[index]
+      if (offset < entry.start || offset > entry.start + entry.bytes) continue
+      const within = Buffer.from(entry.text, 'utf8')
+      const tail = within.subarray(offset - entry.start).toString('utf8')
+      return { text: [tail, ...this.#entries.slice(index + 1).map((item) => item.text)].join(''), lossy: false }
+    }
+    return { text: this.toString(), lossy: true }
+  }
+
+  /** 清空（历史绝对偏移保持不变，避免正在重连的客户端错位）。 */
+  clear() {
+    this.#entries = []
+    this.#bytes = 0
+  }
+}
+
+/** 默认的「文件存在且是普通文件」判断。 */
+async function defaultFileExists(path) {
+  try {
+    const info = await stat(path)
+    return info.isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 选择交互式登录 shell：显式参数 → provider 的默认 shell → $SHELL → 平台默认。
+ * @param {{ explicit?: unknown, preferred?: unknown, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => Promise<boolean> }} [options]
+ * @returns {Promise<string>}
+ */
+export async function resolveShellPath(options = {}) {
+  const {
+    explicit,
+    preferred,
+    env = process.env,
+    platform = process.platform,
+    exists = defaultFileExists,
+  } = options
+  const usable = async (value) => {
+    if (typeof value !== 'string') return false
+    const candidate = value.trim()
+    if (candidate === '' || !isAbsolute(candidate)) return false
+    try {
+      return await exists(candidate)
+    } catch {
+      return false
+    }
+  }
+  if (await usable(explicit)) return explicit.trim()
+  if (await usable(preferred)) return preferred.trim()
+  if (await usable(env.SHELL)) return env.SHELL.trim()
+  if (platform === 'win32') {
+    const comspec = typeof env.COMSPEC === 'string' && env.COMSPEC !== '' ? env.COMSPEC : 'powershell.exe'
+    return comspec
+  }
+  return platform === 'darwin' ? '/bin/zsh' : '/bin/bash'
+}
+
+/** 登录 shell 的参数：POSIX 用 `-l`，Windows 关闭 logo。 */
+export function terminalShellArgs(platform = process.platform) {
+  return platform === 'win32' ? ['-NoLogo'] : ['-l']
+}
+
+/** 终端标签标题：shell 可执行文件名（兼容 PATH 分隔符差异，去掉 .exe）。 */
+export function terminalTitleFor(shellPath) {
+  const base = String(shellPath ?? '').split(/[\\/]/).filter(Boolean).at(-1) ?? ''
+  const trimmed = base.endsWith('.exe') ? base.slice(0, -4) : base
+  return trimmed === '' ? 'shell' : trimmed
+}