@xiaoso/dsh-tool-plus 0.1.7-beta.0 → 0.1.7

package/lib/types/tools/bash/cd-workdir.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Leading `cd <path> && …` workdir extraction and `~` expansion for the bash
+ * tool.
+ *
+ * Extraction delegates to `extractLeadingCdTarget` (shell-tokenize.ts, verbatim
+ * port of upstream tools/shell-tokenize.ts), so redirect prefixes, extra
+ * arguments, command substitution, and unterminated quotes all bail and leave
+ * the whole command with the shell. `~`/`~/…` prefixes expand against
+ * `os.homedir()` with upstream `expandTilde` semantics
+ * (refs packages/coding-agent/src/tools/path-utils.ts).
+ * @module @xiaoso/dsh-tool-plus/bash/cd-workdir
+ */
+/**
+ * Expand a leading `~`/`~/…`/`~\…` prefix to the home directory, matching
+ * upstream `expandTilde` (refs tools/path-utils.ts). A bare `~name` is joined
+ * under the home directory like upstream (user-home approximation).
+ */
+export declare function expandTilde(filePath: string, home?: string): string;
+/** A leading `cd <path> && …` split into its (tilde-expanded) workdir and the remainder. */
+export interface CdWorkdir {
+    /** Tilde-expanded working directory for the leading `cd`. */
+    workdir: string;
+    /** Command remainder after the top-level `&&`. */
+    command: string;
+}
+/**
+ * Extract a leading `cd <path> && …` prefix, expanding `~` in the target.
+ *
+ * Returns `null` when the command does not start with exactly `cd`, one path
+ * token, and a top-level `&&` — redirects (`cd /tmp 2>/dev/null && …`), extra
+ * arguments, command substitution (`$`, backticks, `(`), and unterminated
+ * quotes all leave the whole command for the shell instead of absorbing shell
+ * syntax into the structured workdir seam.
+ */
+export declare function extractCdWorkdir(command: string, home?: string): CdWorkdir | null;

package/lib/types/tools/bash/logger.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal structured logger seam for the ported bash-runtime modules.
+ * The pi-gateway originals used `createModuleLogger("…")`; dsh provides
+ * `ctx.logger` (Cordis logger), which the plugin entry installs via
+ * {@link setRuntimeLogger}. Until then a console adapter is used, so the
+ * modules stay usable outside a composition (unit tests, executor-only use).
+ * @module @xiaoso/dsh-tool-plus/logger
+ */
+export interface RuntimeLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/** Install the composition logger (Cordis `ctx.logger`); replaces the console adapter. */
+export declare function setRuntimeLogger(logger: RuntimeLogger): void;
+/** The installed logger; defaults to the console adapter. */
+export declare function runtimeLogger(): RuntimeLogger;

package/lib/types/tools/bash/non-interactive-env.d.ts

@@ -0,0 +1,5 @@
+/** Portable command that rejects credential prompts without assuming an FHS layout. */
+export declare const REJECT_PROMPT_COMMAND: string;
+export declare const NON_INTERACTIVE_ENV: Readonly<Record<string, string>>;
+/** Builds the per-command environment for non-interactive child processes. */
+export declare function buildNonInteractiveEnv(overrides?: Record<string, string>, baseEnv?: Record<string, string | undefined>, platform?: NodeJS.Platform): Record<string, string>;

package/lib/types/tools/bash/render.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Model-facing result rendering for the bash-plus tool: output body, wall
+ * time, minimization/truncation notices, then the exit-status marker the dsh
+ * presentation layer parses back into a terminal pill.
+ *
+ * Marker contract (shared with `dsh-tool-bash`): `[exit code: N]` and
+ * `[killed by signal: X]` MUST be the final line of the rendered text —
+ * `parseExitStatus` anchors there. Other notices stay in the body.
+ * @module @xiaoso/dsh-tool-plus/render
+ */
+import { parseExitStatus } from '@deepseek-ai/dsh-shell';
+import type { BashForegroundOutput, CollectedOutput } from './types.ts';
+/** The wall-time line appended to every completed foreground result. */
+export declare function formatWallTimeNotice(wallTimeMs: number): string;
+/**
+ * The OMP-form truncation notice: line-range accounting (head+tail ranges for
+ * middle elision, shown range for one-sided truncation) plus elided stats,
+ * then the spill-file pointer and a read-back hint. Range reconstruction rides
+ * the shared OMP algorithm (`outputMeta().truncationFromSummary`), with the
+ * upstream `artifact://N` clause replaced by the spill-file path — bash spill
+ * files are plain files (deliberately not registered in the read tool's
+ * artifact:// space, see adapter/spill.ts) and are recovered with `:N-M`
+ * inline selectors instead.
+ * @returns the notice lines, or `undefined` when output was not truncated.
+ */
+export declare function formatTruncationNotice(value: CollectedOutput): string[] | undefined;
+/**
+ * Shape one completed run into the text the model sees. Non-zero exits are
+ * reported, not errored — the model decides how to react; only infrastructure
+ * failures (spawn errors, aborts) surface as isError results.
+ * @param value - the completed foreground run.
+ * @returns the model-facing text: output body (or `(no output)`), then wall
+ *   time, minimization/truncation notices, timeout marker, and finally the
+ *   exit-status marker on its own line.
+ */
+export declare function renderBashResult(value: BashForegroundOutput): string;
+/**
+ * Shape one background-process read into the delta the model sees: the
+ * incremental output since the previous read, with the lossy-read notice when
+ * the in-memory tail dropped unread bytes.
+ * @param text - the incremental delta from the job producer.
+ * @param droppedBytes - bytes elided from the tail window, when any.
+ * @returns the delta text with any loss notice appended.
+ */
+export declare function renderJobRead(text: string, droppedBytes: number | undefined): string;
+export { parseExitStatus };

package/lib/types/tools/bash/rm-safe-status.d.ts

@@ -0,0 +1,62 @@
+/** 运行时探测结果：`rm` 是函数（生效）/ 系统命令（未生效）/ 探测不可用。 */
+export type RmSafeRuntime = 'function' | 'system' | 'unknown';
+/** 注入失败原因（client 侧映射为本地化文案）。 */
+export type RmSafeFailureReason = 'snapshot-unavailable' | 'cli-missing' | 'snapshot-write-failed' | 'runtime-not-effective';
+/** rmSafe/status 查询结果（host RPC 返回值，client 直接消费）。 */
+export type RmSafeStatus = {
+    status: 'disabled';
+} | {
+    status: 'failed';
+    reason: RmSafeFailureReason;
+} | {
+    status: 'injected';
+    runtime: RmSafeRuntime;
+};
+/** 查询依赖（host 侧绑定真实实现；测试注入 fake）。 */
+export interface RmSafeStatusDeps {
+    /** 取快照路径（幂等；可能触发创建）。null = 快照不可用。 */
+    getOrCreateSnapshot: () => Promise<string | null>;
+    /** trash-cli 构建产物是否存在。 */
+    cliExists: () => boolean;
+    /** node 可执行文件路径（注入内容的一部分）。 */
+    nodePath: () => string;
+    /** trash-cli 路径（注入内容的一部分）。 */
+    cliPath: () => string;
+    /** 向快照内联追加注入（幂等）。false = 快照不可写。 */
+    inject: (snapshotPath: string, nodePath: string, cliPath: string) => boolean;
+    /** 运行时探测：新会话里 `rm` 是否被重定义。 */
+    probe: (snapshotPath: string) => Promise<RmSafeRuntime>;
+}
+/**
+ * 解析 `type rm` / `declare -f rm` 探测输出。
+ * `rm is a function` → 函数重定义生效；其余（`rm is /usr/bin/rm`、
+ * `rm is hashed (...)`、空输出）→ 系统命令。
+ */
+export declare function parseProbeOutput(stdout: string): RmSafeRuntime;
+/**
+ * Windows 路径转 Git Bash 形式（`C:\Users\x` → `/c/Users/x`）。
+ * 非 Windows 原样返回；非盘符路径仅把反斜杠转正斜杠。
+ */
+export declare function toGitBashPath(p: string): string;
+/** 一次性 shell 进程的探测结果。 */
+export interface ProbeSpawnResult {
+    stdout: string;
+    /** 超时被杀时为 true（与退出码无关）。 */
+    timedOut: boolean;
+}
+/** spawn 依赖（测试注入 fake）。 */
+export interface ProbeSpawnDeps {
+    spawnShell: (shell: string, args: string[], timeoutMs: number) => Promise<ProbeSpawnResult>;
+}
+/**
+ * 运行时探测：在一次性 bash 会话里 source 快照（模拟新会话创建），
+ * 然后 `type rm` + `declare -f rm` 看 `rm` 是否被重定义为函数。
+ * spawn 失败或超时 → 'unknown'（探测不可用，不代表注入失败）。
+ */
+export declare function probeRmSafeRuntime(shell: string, snapshotPath: string, deps?: ProbeSpawnDeps, timeoutMs?: number): Promise<RmSafeRuntime>;
+/**
+ * 查询 rmSafe 注入状态（查询即确保注入：幂等，与 executeBash 的注入
+ * 路径一致）。rmSafe 关闭时调用方不应调用本函数（返回 disabled 由
+ * 调用方短路）；此处仍兜底返回 disabled 语义由调用方保证。
+ */
+export declare function queryRmSafeStatus(deps: RmSafeStatusDeps): Promise<RmSafeStatus>;

package/lib/types/tools/bash/rm-safe.d.ts

@@ -0,0 +1,18 @@
+/** 注入标记行：injectRmSafe 以此判断是否已注入（幂等）。 */
+export declare const RM_SAFE_MARKER = "# dsh-tool-plus rmSafe";
+/** trash-cli 构建产物路径（lib/trash-cli.mjs，与主 bundle 同目录）。 */
+export declare function rmSafeCliPath(): string;
+/** 单引号转义（bash 单引号内 `'\''` 表示一个字面单引号）。 */
+export declare function quote(s: string): string;
+/**
+ * 生成 rm 重定义脚本内容：bash 函数 `rm()` 把参数原样转交 trash-cli。
+ * 逃生口：`command rm`（bash 的 command 关键字跳过函数/alias 查找）或
+ * 绝对路径（/usr/bin/rm）走系统真删除。注意 `\rm` 反斜杠只抑制 alias
+ * 展开、不抑制函数查找，对函数重定义无效——不是逃生口。
+ */
+export declare function rmSafeScript(nodePath: string, cliPath: string): string;
+/**
+ * 向快照文件内联追加 rm 重定义（幂等：已有标记则跳过）。
+ * 返回是否注入成功；快照文件不可读/不可写时返回 false（不抛异常）。
+ */
+export declare function injectRmSafe(snapshotPath: string, nodePath: string, cliPath: string): boolean;

package/lib/types/tools/bash/sanitize-text.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Strip ANSI escape sequences, remove control characters / lone surrogates,
+ * and normalize line endings.
+ *
+ * Bun-native implementation of the former native `sanitizeText` (see
+ * `crates/pi-natives/src/text.rs::sanitize_text`). JavaScript strings are
+ * already UTF-16 code-unit arrays. `toWellFormed()` handles the uncommon
+ * malformed path; when it changes the input, replacement characters are
+ * dropped and the normalized result goes through the well-formed sanitizer.
+ *
+ * S-8 normalization: ANSI stripping re-exports the ECMA-48 state machine from
+ * `src/tools/shared/bun-shim.ts` — the same function installed as
+ * `Bun.stripANSI`; `toWellFormed()` delegates to the native
+ * `String.prototype.toWellFormed`.
+ *
+ * Fast path: well-formed input with no controls or ANSI returns the original
+ * string after the control probe.
+ */
+export declare function sanitizeText(text: string): string;
+/**
+ * Escape the three XML-significant characters (`&`, `<`, `>`) in text destined
+ * for an XML/markup element body. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Quotes are left as-is
+ * — use it for element text, not attribute values.
+ */
+export declare function escapeXmlText(input: string): string;
+/**
+ * Escape XML-significant characters for an attribute VALUE: the three body
+ * characters (`&`, `<`, `>`) plus the double quote (`"` → `&quot;`) that would
+ * otherwise close the attribute. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Use it for attribute
+ * values; {@link escapeXmlText} is for element bodies and leaves `"` intact.
+ */
+export declare function escapeXmlAttribute(input: string): string;

package/lib/types/tools/bash/shell-snapshot.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shell environment snapshot for preserving user aliases, functions, and options.
+ *
+ * Creates a snapshot file that captures the user's shell environment from their
+ * .bashrc/.zshrc, which can be sourced before each command to provide a familiar
+ * shell experience.
+ */
+/**
+ * Strip alias definitions brush's whitespace-only expander cannot execute.
+ *
+ * Returns the rewritten snapshot plus the list of dropped alias names so the
+ * caller can surface them in the debug log.
+ */
+export declare function sanitizeSnapshotForBrush(content: string): {
+    content: string;
+    dropped: string[];
+};
+/**
+ * Create a shell snapshot, caching the result.
+ * Returns the path to the snapshot file, or null if creation failed.
+ *
+ * `timeoutMs` is configurable so callers exercising failure handling do not
+ * have to wait out the production startup budget.
+ */
+export declare function getOrCreateSnapshot(shell: string, env: Record<string, string | undefined>, timeoutMs?: number): Promise<string | null>;
+/**
+ * Delete every cached snapshot file and clear the cache. Called from the
+ * plugin's disposal path (the pi-gateway original ran this through its
+ * postmortem registry).
+ */
+export declare function cleanupSnapshots(): void;

package/lib/types/tools/bash/shell-tokenize.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Conservative shell command tokenizer shared by the bash approval-pattern
+ * matcher and the gh-cache invalidator.
+ *
+ * Splits a bash command into independent command segments, each a list of word
+ * tokens. Handles single/double-quoted strings, backslash escapes, and the
+ * standard operators (`;`, `&&`, `||`, `|`, `&`, `(`, `)`, newlines) as segment
+ * boundaries so callers treat the pieces as independent command sequences.
+ *
+ * It is deliberately not a full POSIX parser — heredocs, command substitution,
+ * and arithmetic expansion are out of scope; callers fall through when they
+ * cannot find the structure they need.
+ */
+export declare function tokenizeShellSegments(command: string): string[][];
+/**
+ * A flat shell command segment with the context needed to decide interception.
+ *
+ * @see extractFlatShellCommandSegments
+ */
+interface FlatShellCommandSegment {
+    /** Original segment text with quoting and escaping preserved. */
+    text: string;
+    /**
+     * True when this segment consumes the previous stage's stdout via an
+     * unquoted `|` or `|&`. Blank and comment-only continuation lines preserve
+     * the pending pipe state. Such a stage reads piped stdin, so path-based
+     * dedicated tools (read/grep/glob) cannot replace it. `||`, `;`, `&`, and
+     * `&&` start an independent command and leave this false.
+     */
+    pipedStdin: boolean;
+}
+/**
+ * Returns the flat shell command segments with the original text of each. Unlike
+ * `tokenizeShellSegments`, this preserves quoting and escaping so the results
+ * are safe to match against user-configured regular expressions, and flags
+ * segments that receive piped stdin.
+ *
+ * The extractor deliberately declines to split syntax whose execution context
+ * cannot be determined with this small scanner (heredocs, command substitution,
+ * backticks, grouping, and malformed quoting). Callers must still check the
+ * complete input in that case.
+ */
+export declare function extractFlatShellCommandSegments(command: string): FlatShellCommandSegment[];
+/**
+ * Parses a leading `cd <path> && ...` prefix so the bash tool can route the
+ * target through its structured `cwd` parameter when the model omits it.
+ *
+ * Returns the single path token (quotes and backslash escapes resolved to their
+ * literal value) and the command remainder after the top-level `&&`, or `null`
+ * when the command does not begin with exactly `cd`, one path token, and a
+ * top-level `&&`. The scanner deliberately bails on anything else in the prefix
+ * — redirects (`cd /tmp 2>/dev/null && ...`), extra arguments, or paths needing
+ * shell expansion (`$`, backticks, `(`) — leaving the whole command for the
+ * shell instead of absorbing shell syntax into `cwd`.
+ */
+export declare function extractLeadingCdTarget(command: string): {
+    path: string;
+    rest: string;
+} | null;
+export {};

package/lib/types/tools/bash/streaming-output.d.ts

@@ -0,0 +1,32 @@
+import { OutputSink as VerbatimOutputSink, OutputSummary as VerbatimOutputSummary, type OutputSinkOptions } from "../omp/session/streaming-output.ts";
+export * from "../omp/session/streaming-output.ts";
+/**
+ * Verbatim `OutputSummary` 加 DSH 增量字段 `artifactPath`。
+ */
+export interface OutputSummary extends VerbatimOutputSummary {
+    /**
+     * Path of the spill file mirroring the raw stream, when one was created.
+     * Present even when only the per-line column cap triggered mirroring.
+     */
+    artifactPath?: string;
+}
+export declare class OutputSink extends VerbatimOutputSink {
+    #private;
+    constructor(options?: OutputSinkOptions);
+    dump(notice?: string): Promise<OutputSummary>;
+}
+/**
+ * Composition wrapper over the verbatim {@link TailBuffer}, adding the DSH
+ * `reset()` increment. The verbatim class keeps its state in private fields,
+ * so reset is modeled as a fresh window with the same budget.
+ */
+export declare class TailBuffer {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    text(): string;
+    bytes(): number;
+    /** Drop all held output; the next {@link append} starts a fresh window. */
+    reset(): void;
+}

package/lib/types/tools/bash/trash-cli-main.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/tools/bash/trash-cli.d.ts

@@ -0,0 +1,77 @@
+/** 解析后的 rm 参数。 */
+export interface ParsedRmArgs {
+    recursive: boolean;
+    force: boolean;
+    interactive: boolean;
+    verbose: boolean;
+    dir: boolean;
+    /** --preserve-root（默认开启，对齐 GNU rm）。 */
+    preserveRoot: boolean;
+    /** --one-file-system（接受并忽略：trash 原子移动无递归遍历）。 */
+    oneFileSystem: boolean;
+    paths: string[];
+    error?: {
+        kind: 'missing-operand';
+    } | {
+        kind: 'invalid-option';
+        option: string;
+    } | {
+        kind: 'unrecognized-option';
+        option: string;
+    } | {
+        kind: 'invalid-argument';
+        option: string;
+        value: string;
+    } | {
+        kind: 'option-argument';
+        option: string;
+    };
+}
+/**
+ * 解析 rm 风格参数（coreutils rm 语义）：
+ * - 短选项支持组合（`-rf`），`-r`/`-R`/`--recursive` 等价，`-i`/`-I` 等价；
+ * - `--` 结束符后全部视为路径（允许 `-` 开头的文件名）；
+ * - `--interactive[=once|always|never]` 接受（回收站模式忽略交互）；
+ * - 未知短选项 → invalid-option，未知长选项 → unrecognized-option；
+ * - 无路径 → missing-operand。
+ */
+export declare function parseRmArgs(argv: string[]): ParsedRmArgs;
+/** trash 层与 IO 依赖（单测注入 fake）。 */
+export interface TrashCliDeps {
+    trash: (paths: string[]) => Promise<void>;
+    /** lstat 语义：链接本身存在即可删；返回 null = 不存在。 */
+    lstat: (p: string) => Promise<{
+        isDirectory: boolean;
+    } | null>;
+    /** stat 语义：返回 dev/ino 用于根目录判定（GNU preserve-root 的 dev/ino 比较）；失败返回 null。 */
+    stat: (p: string) => Promise<{
+        dev: number;
+        ino: number;
+    } | null>;
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    exit: (code: number) => void;
+    /** rename 探测（默认实现 fs.rename 到同目录临时名再改回）。返回 errno 码或 null（可移动）。 */
+    probeRename?: (from: string, to: string) => Promise<string | null>;
+}
+/**
+ * rename 探测结果 → 可读原因（null = 无结论）。
+ *
+ * trash 的 windows-trash.exe 失败时把原因吞成 0x8000FFFF、stderr 为空，
+ * 所以这里靠 rename 探测拿文件系统的真实回答；不同 errno 必须分开报，
+ * 权限不足不是“被占用”。
+ */
+export declare function describeProbeCode(code: string | null): string | null;
+/**
+ * 执行一次 rm 语义的回收站删除。
+ *
+ * 行为对齐 coreutils rm：
+ * - 无 -r/-d 时目录报 `Is a directory` 并保留（rm4）；
+ * - 不存在路径：-f 静默忽略（f-1），否则报 `No such file or directory`；
+ * - `.`/`..` 结尾路径拒绝（r-4）；`/` 及同义词拒绝（r-root，preserve-root 默认开）；
+ * - 符号链接按链接本身处理（lstat，dangling-symlink 移植）；
+ * - trash 失败：-f 静默但退出 1，否则报 `cannot remove`；
+ * - -v 输出 `removed 'x'` / `removed directory 'x'`（r-1/d-1/v-slash）；
+ * - 退出码：全部成功 0，任一失败 1。
+ */
+export declare function runTrashCli(argv: string[], deps: TrashCliDeps): Promise<void>;

package/lib/types/tools/bash/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Plugin configuration, tool argument, and result DTO types for the ported
+ * Oh My Pi bash tool. The runtime `Config` schema lives in `index.ts`.
+ * @module @xiaoso/dsh-tool-plus/types
+ */
+/** Minimizer settings mirroring the native `MinimizerOptions` surface. */
+export interface MinimizerConfig {
+    enabled: boolean;
+    /** Restrict minimization to these filter names (empty = all). */
+    only: string[];
+    /** Exclude these filter names from minimization. */
+    except: string[];
+    /** Output capture budget in bytes; larger outputs pass through raw. */
+    maxCaptureBytes: number;
+}
+/**
+ * Runtime configuration schema for the plugin; declared in `index.ts`
+ * alongside `apply`. Every field is optional at the composition boundary and
+ * defaults inside `apply`; {@link ResolvedConfig} is the fully-defaulted form.
+ */
+export interface Config {
+    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    enableRunInBackground?: boolean;
+    /** Foreground commands exceeding this wall time are moved to the background (0 = never). */
+    autoBackgroundMs?: number;
+    /** Deadline applied when the model omits `timeoutMs`. */
+    defaultTimeoutMs?: number;
+    /** Upper clamp for explicit timeouts; `timeoutMs: 0` disables the deadline. */
+    maxTimeoutMs?: number;
+    /** Tail budget for live previews and background-job output reads. */
+    outputMaxBytes?: number;
+    /** OutputSink rolling tail window (bytes). */
+    outputSinkTailBytes?: number;
+    /** OutputSink head window (bytes) retained in addition to the tail. */
+    outputSinkHeadBytes?: number;
+    /** Output minimizer (native intelligent compression for git/npm/cargo/…). */
+    minimizer?: MinimizerConfig;
+    /** Block intercepted commands and suggest the dedicated dsh tool instead. */
+    interceptorEnabled?: boolean;
+    /** Harden the command environment for non-interactive use (pagers, prompts, color). */
+    nonInteractiveEnv?: boolean;
+    /** Capture the user's rc file (aliases, functions, options) into the session shell. */
+    snapshotEnabled?: boolean;
+    /** Redefine `rm` in the session shell to move into the system trash; the plugin config layer decides the default (rmSafe: true). */
+    rmSafe?: boolean;
+    /** Wrap every command in `bash -c '…'` for a full bash environment. */
+    useShellCommandWrapper?: boolean;
+}
+/** {@link Config} with every field resolved to its default. */
+export type ResolvedConfig = Required<Config>;
+/** Parsed tool arguments; execute validates value constraints absent from ParameterSchemaSpec. */
+export interface BashToolArgs {
+    command: string;
+    description: string;
+    timeoutMs?: number;
+    workdir?: string;
+    env?: Record<string, string>;
+    run_in_background?: boolean;
+}
+/** Minimizer facts surfaced with a foreground result. */
+export interface MinimizedOutputInfo {
+    filter: string;
+    inputBytes: number;
+    outputBytes: number;
+}
+/** One collected output stream (single merged stdout+stderr, like the native Shell). */
+export interface CollectedOutput {
+    text: string;
+    truncated: boolean;
+    /** Path of the spill file mirroring the full raw output stream, when one was created. */
+    spillPath?: string;
+    /** Path holding the pre-minimization original text, when the native minimizer rewrote the output. */
+    originalSpillPath?: string;
+    /** Stream counters carried for the truncation notice (OMP OutputSummary parity). */
+    totalLines?: number;
+    totalBytes?: number;
+    outputLines?: number;
+    outputBytes?: number;
+    elidedLines?: number;
+    elidedBytes?: number;
+}
+/** Foreground completion of one bash call. */
+export interface BashForegroundOutput {
+    kind: 'foreground';
+    /** Process exit code; null when the run was interrupted before exit. */
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    /** The effective deadline in ms (null when the deadline was disabled). */
+    timeoutMs: number | null;
+    /** Wall-clock duration of the run. */
+    wallTimeMs: number;
+    /** The shell's working directory after the command (persists across calls). */
+    workingDir?: string;
+    /** Present when the native minimizer rewrote the output. */
+    minimized?: MinimizedOutputInfo;
+    /** True when the rmSafe injection failed: `rm` deletes permanently. */
+    rmSafeInjectionFailed?: boolean;
+    output: CollectedOutput;
+}
+/** Background acknowledgement: the call returned a managed job id. */
+export interface BashBackgroundOutput {
+    kind: 'background';
+    jobId: string;
+}
+/** The tool's canonical output DTO. */
+export type BashOutput = BashForegroundOutput | BashBackgroundOutput;

package/lib/types/tools/bash/which.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal PATH (+ PATHEXT on Windows) executable lookup — the plugin's single
+ * implementation of `Bun.which` semantics on the Node runtime.
+ *
+ * Two callers, one scanner: DSH code that must resolve executables the way OMP
+ * does (procmgr `resolveWindowsShell` for shell discovery, `REJECT_PROMPT_COMMAND`
+ * in non-interactive-env) calls `findOnPath` directly, and the bun-shim installs
+ * `Bun.which` on top of it — which is also how upstream pi-utils' `$which` lands
+ * here (@oh-my-pi/pi-utils src/which.ts:201 calls `Bun.which` on non-darwin).
+ * Single implementation — any new caller resolves executables through here,
+ * never hand-rolls a PATH walk.
+ * @module @xiaoso/dsh-tool-plus/bash/which
+ */
+/**
+ * Resolve `command` against PATH the way `Bun.which` would: absolute/relative
+ * candidates are returned as-is when they name an existing file; bare names
+ * are looked up in each PATH dir (appending PATHEXT extensions on win32, in
+ * order). Returns the first existing regular file, or `undefined`.
+ */
+export declare function findOnPath(command: string, env?: NodeJS.ProcessEnv): string | undefined;

package/lib/types/tools/bash/windows-shell.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Windows shell discovery, ported from oh-my-pi procmgr's `resolveWindowsShell`
+ * (refs/oh-my-pi/packages/utils/src/procmgr.ts:148-173) — adapted verbatim:
+ * `Bun.env` → injectable Node env (default `process.env`), and pi-utils
+ * `$which` → `findOnPath` (src/tools/bash/which.ts).
+ *
+ * Deliberately NOT ported from procmgr: buildSpawnEnv, shell prefix handling,
+ * direnv integration, and PI_SHELL_PREFIX — DSH has no shell-prefix seam;
+ * commands run inside the embedded brush shell or the resolved user shell.
+ * @module @xiaoso/dsh-tool-plus/bash/windows-shell
+ */
+/**
+ * Resolve the external shell to advertise on Windows.
+ *
+ * A host bash is OPTIONAL: bash tool commands always execute in the embedded
+ * brush-core shell. The resolved binary only serves the spawn-a-shell paths,
+ * so this prefers a real Git Bash when one exists and otherwise falls back to
+ * cmd.exe — it never fails.
+ *
+ * Search order:
+ * 1. Git for Windows install roots (machine + per-user installers)
+ * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
+ *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
+ * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
+ * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
+ *    bash.exe when present)
+ * 5. cmd.exe from ComSpec
+ *
+ * Exported for tests; `env` overrides process.env-based discovery.
+ */
+export declare function resolveWindowsShell(env?: NodeJS.ProcessEnv): string;