@askdkc/dsh-cli 0.11.3

package/lib/types/utils/debug.js

@@ -0,0 +1,37 @@
+import { appendFileSync } from 'node:fs';
+import { DATA_DIR } from './paths.js';
+import { join } from 'node:path';
+/**
+ * Debug logger for the renderer. Writes to stderr only when
+ * `DSH_TUI_DEBUG` is set, so normal runs stay quiet.
+ * @param message - The message to log.
+ * @param fields - Optional JSON-serialized fields appended to the line.
+ */
+export function logForDebugging(message, fields) {
+    if (!process.env.DSH_TUI_DEBUG)
+        return;
+    const suffix = fields === undefined ? '' : ` ${JSON.stringify(fields)}`;
+    process.stderr.write(`[dsh-tui] ${message}${suffix}\n`);
+}
+/**
+ * Mouse-chain diagnostics: appends to `~/.dsh-tui/mouse-debug.log` when
+ * `DSH_TUI_DEBUG_MOUSE` is set. Unlike logForDebugging (stderr), a file
+ * keeps the fullscreen alt screen unpolluted and survives the session for
+ * post-mortem reading. Every append is try/catch-guarded — diagnostics
+ * must never take the UI down.
+ * @param message - Stage name (e.g. 'mouse arrive', 'dispatchClick').
+ * @param fields - Optional JSON-serialized fields appended to the line.
+ */
+export function logMouseDebug(message, fields) {
+    if (!process.env.DSH_TUI_DEBUG_MOUSE)
+        return;
+    const suffix = fields === undefined ? '' : ` ${JSON.stringify(fields)}`;
+    try {
+        const line = `${new Date().toISOString()} ${message}${suffix}\n`;
+        // 0600 on creation: the log mirrors UI activity, incl. message content
+        appendFileSync(join(DATA_DIR, 'mouse-debug.log'), line, { mode: 0o600 });
+    }
+    catch {
+        // ignore — see doc comment
+    }
+}

package/lib/types/utils/earlyInput.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The renderer calls this once stdin handoff completes. Early-input capture is
+ * not used by dsh-tui, so this is a no-op.
+ */
+export declare function stopCapturingEarlyInput(): void;
+//# sourceMappingURL=earlyInput.d.ts.map

package/lib/types/utils/earlyInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"earlyInput.d.ts","sourceRoot":"","sources":["../../../src/utils/earlyInput.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAAG"}

package/lib/types/utils/earlyInput.js

@@ -0,0 +1,5 @@
+/**
+ * The renderer calls this once stdin handoff completes. Early-input capture is
+ * not used by dsh-tui, so this is a no-op.
+ */
+export function stopCapturingEarlyInput() { }

package/lib/types/utils/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Minimal terminal-environment shim for terminal capability checks. The
+ * renderer reads `env.terminal` to choose the OSC terminator for Kitty.
+ */
+export declare const env: {
+    readonly terminal: string;
+};
+//# sourceMappingURL=env.d.ts.map

package/lib/types/utils/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/utils/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,GAAG,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAE5C,CAAA"}

package/lib/types/utils/env.js

@@ -0,0 +1,7 @@
+/**
+ * Minimal terminal-environment shim for terminal capability checks. The
+ * renderer reads `env.terminal` to choose the OSC terminator for Kitty.
+ */
+export const env = {
+    terminal: (process.env.TERM_PROGRAM ?? process.env.TERM ?? 'unknown').toLowerCase(),
+};

package/lib/types/utils/envUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Environment truthiness check used by terminal configuration. Accepts the common
+ * shell truthy spellings (`1`, `true`, `yes`, `on`).
+ * @param value - The environment value to interpret.
+ * @returns True for booleans `true` and the truthy spellings, false otherwise.
+ */
+export declare function isEnvTruthy(value: string | boolean | undefined | null): boolean;
+//# sourceMappingURL=envUtils.d.ts.map

package/lib/types/utils/envUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/envUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAI/E"}

package/lib/types/utils/envUtils.js

@@ -0,0 +1,13 @@
+/**
+ * Environment truthiness check used by terminal configuration. Accepts the common
+ * shell truthy spellings (`1`, `true`, `yes`, `on`).
+ * @param value - The environment value to interpret.
+ * @returns True for booleans `true` and the truthy spellings, false otherwise.
+ */
+export function isEnvTruthy(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase());
+}

package/lib/types/utils/execFileNoThrow.d.ts

@@ -0,0 +1,17 @@
+/** The settled outcome of a no-throw command run. */
+export interface ExecFileNoThrowResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Options for {@link execFileNoThrow}: stdin payload, timeout, and child
+ * working directory. */
+export interface ExecFileNoThrowOptions {
+    input?: string;
+    timeout?: number;
+    useCwd?: boolean;
+    cwd?: string;
+}
+/** Run a command without throwing; child output is bounded for safety. */
+export declare function execFileNoThrow(file: string, args?: readonly string[], options?: ExecFileNoThrowOptions): Promise<ExecFileNoThrowResult>;
+//# sourceMappingURL=execFileNoThrow.d.ts.map

package/lib/types/utils/execFileNoThrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execFileNoThrow.d.ts","sourceRoot":"","sources":["../../../src/utils/execFileNoThrow.ts"],"names":[],"mappings":"AAKA,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED;wBACwB;AACxB,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AA6BD,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CA+BhC"}

package/lib/types/utils/execFileNoThrow.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { extname } from 'node:path';
+const MAX_CAPTURE_BYTES = 64 * 1024;
+function appendBounded(chunks, chunk, total) {
+    if (total.value >= MAX_CAPTURE_BYTES)
+        return;
+    const remaining = MAX_CAPTURE_BYTES - total.value;
+    const part = chunk.subarray(0, remaining);
+    chunks.push(part);
+    total.value += part.length;
+}
+/** Quote one argument for the Windows command interpreter without flattening
+ * the caller's argv into an unquoted shell command. */
+function quoteWindowsArg(value) {
+    const escaped = value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, '$1$1');
+    return `"${escaped.replace(/%/g, '%%')}"`;
+}
+function spawnCommand(file, args, options) {
+    const isWindowsScript = process.platform === 'win32' && /\.(?:cmd|bat)$/iu.test(extname(file));
+    if (!isWindowsScript)
+        return spawn(file, args, { timeout: options?.timeout, cwd: options?.cwd });
+    const command = `"${[file, ...args].map(quoteWindowsArg).join(' ')}"`;
+    return spawn(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', command], {
+        timeout: options?.timeout,
+        cwd: options?.cwd,
+        windowsHide: true,
+        windowsVerbatimArguments: true,
+    });
+}
+/** Run a command without throwing; child output is bounded for safety. */
+export function execFileNoThrow(file, args = [], options) {
+    return new Promise(resolve => {
+        let child;
+        try {
+            child = spawnCommand(file, args, options);
+        }
+        catch {
+            resolve({ code: 1, stdout: '', stderr: '' });
+            return;
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const stdoutTotal = { value: 0 };
+        const stderrTotal = { value: 0 };
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({
+                code,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8'),
+            });
+        };
+        child.stdout?.on('data', (chunk) => appendBounded(stdoutChunks, chunk, stdoutTotal));
+        child.stderr?.on('data', (chunk) => appendBounded(stderrChunks, chunk, stderrTotal));
+        child.stdin?.on('error', () => { });
+        child.on('error', () => finish(1));
+        child.on('close', code => finish(code));
+        if (options?.input !== undefined)
+            child.stdin?.write(options.input);
+        child.stdin?.end();
+    });
+}

package/lib/types/utils/externalEditor.d.ts

@@ -0,0 +1,116 @@
+/**
+ * External editor round-trip for the prompt input (issue #123): Ctrl+G dumps
+ * the current draft into a temp file, hands the terminal to `$VISUAL` /
+ * `$EDITOR` (nvim, vim, nano, `code --wait`, …), and returns the saved text
+ * for the input to adopt.
+ *
+ * Terminal handover reuses the Ink core's editor handoff pair —
+ * `enterAlternateScreen()` pauses rendering, suspends raw-mode stdin, and
+ * drops the extended key reporting that non-CSI-u editors (nano) choke on;
+ * `exitAlternateScreen()` re-enters the alt screen (vim's rmcup pops back to
+ * the main screen on quit), repaints, and resumes stdin. See ink.tsx. The
+ * saved file is read back BEFORE stdin is resumed: resuming earlier would
+ * let keystrokes typed right at editor exit race the prompt's `setValue`
+ * and get overwritten. The restore is attempted whenever the handover was
+ * attempted (a partially-failed enter still gets an exit pass), and a
+ * failing restore never overrides the outcome.
+ *
+ * Editor resolution order mirrors readline's edit-and-execute-command:
+ * `$VISUAL` → `$EDITOR`. There is deliberately NO fallback editor: an
+ * unresolved editor reports `unavailable` and the UI asks the user to set
+ * `$VISUAL` or `$EDITOR` (dropping someone into an unconfigured `vi` is a
+ * trap for users who don't know how to quit it). The variable may carry
+ * arguments (`EDITOR="code --wait"`), so the command line is split
+ * quote-aware before spawning.
+ *
+ * Windows launch: libuv resolves bare names to `.exe` on PATH but will NOT
+ * execute `.cmd`/`.bat` shims (VS Code's `code` on PATH is `code.cmd`), and
+ * `spawn(..., {shell: true})` with arguments triggers DEP0190 on Node 24+.
+ * So bare commands are resolved against PATH/PATHEXT up front, and shim
+ * scripts go through an explicit `$comspec /d /s /c` whose payload is built
+ * with the cross-spawn quoting protocol (vendored in shellQuote.ts) and
+ * passed with `windowsVerbatimArguments: true` — without verbatim, libuv
+ * re-quotes the already-quoted payload and corrupts paths containing
+ * spaces (a stock VS Code install path has them).
+ */
+/**
+ * Outcome of one editor round-trip; the caller maps these to UI feedback:
+ * - `edited`: the saved content differs from the draft — adopt `text`
+ * - `unchanged`: the file matches the draft (modulo newline convention), or
+ *   the editor exited non-zero (`:cq` abort semantics) — keep the draft
+ * - `unavailable`: no editor could be resolved (neither `$VISUAL` nor
+ *   `$EDITOR` is set)
+ * - `failed`: the editor process or the temp-file round-trip errored
+ *   (`message` names the failed command or carries the fs error)
+ */
+export type EditorOutcome = {
+    kind: 'edited';
+    text: string;
+} | {
+    kind: 'unchanged';
+} | {
+    kind: 'unavailable';
+} | {
+    kind: 'failed';
+    message: string;
+};
+/**
+ * Split an `$EDITOR`-style command line into argv, honoring single/double
+ * quotes (`code --wait`, `"C:\Program Files\...\nvim.exe" -f`).
+ */
+export declare function splitEditorCommand(commandLine: string): string[];
+/**
+ * Resolve the editor argv from the environment. `$VISUAL` wins over
+ * `$EDITOR` (readline convention); when neither is set there is no fallback
+ * editor — returns undefined and the caller reports `unavailable`.
+ */
+export declare function resolveEditorCommand(env?: NodeJS.ProcessEnv): string[] | undefined;
+/**
+ * Windows shim resolution: a bare command like `code` usually lives on PATH
+ * as `code.cmd`, which libuv refuses to execute directly. Walk PATH with
+ * PATHEXT (case-insensitive on Windows; both casings tried for tests on
+ * case-sensitive filesystems) and report whether the resolved file needs
+ * cmd.exe to run. Commands carrying an explicit extension are used as-is;
+ * unresolved names fall back to the bare command (spawn then resolves
+ * `.exe`, or fails into the `failed` outcome).
+ */
+export declare function resolveWindowsShim(command: string, env?: NodeJS.ProcessEnv): {
+    command: string;
+    viaCmd: boolean;
+};
+/**
+ * Build the `comspec /d /s /c` spawn descriptor for a `.cmd`/`.bat` editor,
+ * following the cross-spawn protocol: the command is normalized first
+ * (explicit forward-slash paths like `C:/Program Files/.../code.cmd` must
+ * become backslash form — cross-spawn's path.normalize step, without which
+ * Windows can ENOENT), then command and arguments are escaped, joined, and
+ * wrapped in one pair of quotes (`/s` strips exactly those), and passed
+ * with `windowsVerbatimArguments` so libuv does not re-quote the payload.
+ * Exported for tests — the assembly is pure.
+ */
+export declare function buildCmdExeSpawn(command: string, args: readonly string[], env?: NodeJS.ProcessEnv): {
+    file: string;
+    args: string[];
+    verbatim: true;
+};
+/**
+ * Edit `draft` in the user's editor and report what happened. Never throws:
+ * every filesystem, spawn, or terminal-restore failure maps to a `failed`
+ * outcome (or is swallowed in the finally) so the UI notifies instead of
+ * dying on an unhandled rejection.
+ *
+ * The Ink instance is looked up lazily (same pattern as Chat's Ctrl+L
+ * redraw) so the util stays usable in tests and non-TTY contexts: without a
+ * live instance the handover escapes are skipped and the editor simply
+ * inherits stdio.
+ *
+ * Newline handling: the saved file is compared against the draft with BOTH
+ * sides CRLF-normalized, so an editor that only converts line endings (or
+ * a draft that already carries `\r\n`) never counts as an edit. Otherwise
+ * ONE trailing newline is stripped when the normalized draft did not end
+ * with one — that is the terminating newline editors append on save, not
+ * user content. Trailing blank lines the user actually added (or had in
+ * the draft, e.g. from Shift+Enter) survive untouched.
+ */
+export declare function editInExternalEditor(draft: string): Promise<EditorOutcome>;
+//# sourceMappingURL=externalEditor.d.ts.map

package/lib/types/utils/externalEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalEditor.d.ts","sourceRoot":"","sources":["../../../src/utils/externalEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAUH;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvC;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA0BhE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,GAAG,SAAS,CAOtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAqBtC;AAKD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAalD;AA8CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsDhF"}

package/lib/types/utils/externalEditor.js

@@ -0,0 +1,270 @@
+/**
+ * External editor round-trip for the prompt input (issue #123): Ctrl+G dumps
+ * the current draft into a temp file, hands the terminal to `$VISUAL` /
+ * `$EDITOR` (nvim, vim, nano, `code --wait`, …), and returns the saved text
+ * for the input to adopt.
+ *
+ * Terminal handover reuses the Ink core's editor handoff pair —
+ * `enterAlternateScreen()` pauses rendering, suspends raw-mode stdin, and
+ * drops the extended key reporting that non-CSI-u editors (nano) choke on;
+ * `exitAlternateScreen()` re-enters the alt screen (vim's rmcup pops back to
+ * the main screen on quit), repaints, and resumes stdin. See ink.tsx. The
+ * saved file is read back BEFORE stdin is resumed: resuming earlier would
+ * let keystrokes typed right at editor exit race the prompt's `setValue`
+ * and get overwritten. The restore is attempted whenever the handover was
+ * attempted (a partially-failed enter still gets an exit pass), and a
+ * failing restore never overrides the outcome.
+ *
+ * Editor resolution order mirrors readline's edit-and-execute-command:
+ * `$VISUAL` → `$EDITOR`. There is deliberately NO fallback editor: an
+ * unresolved editor reports `unavailable` and the UI asks the user to set
+ * `$VISUAL` or `$EDITOR` (dropping someone into an unconfigured `vi` is a
+ * trap for users who don't know how to quit it). The variable may carry
+ * arguments (`EDITOR="code --wait"`), so the command line is split
+ * quote-aware before spawning.
+ *
+ * Windows launch: libuv resolves bare names to `.exe` on PATH but will NOT
+ * execute `.cmd`/`.bat` shims (VS Code's `code` on PATH is `code.cmd`), and
+ * `spawn(..., {shell: true})` with arguments triggers DEP0190 on Node 24+.
+ * So bare commands are resolved against PATH/PATHEXT up front, and shim
+ * scripts go through an explicit `$comspec /d /s /c` whose payload is built
+ * with the cross-spawn quoting protocol (vendored in shellQuote.ts) and
+ * passed with `windowsVerbatimArguments: true` — without verbatim, libuv
+ * re-quotes the already-quoted payload and corrupts paths containing
+ * spaces (a stock VS Code install path has them).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join, win32 } from 'node:path';
+import instances from '../ink/instances.js';
+import { cmdEscapeArgument, cmdEscapeCommand } from './shellQuote.js';
+/**
+ * Split an `$EDITOR`-style command line into argv, honoring single/double
+ * quotes (`code --wait`, `"C:\Program Files\...\nvim.exe" -f`).
+ */
+export function splitEditorCommand(commandLine) {
+    const args = [];
+    let current = '';
+    let quote = null;
+    let hasToken = false;
+    for (const ch of commandLine) {
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            hasToken = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current !== '' || hasToken)
+                args.push(current);
+            current = '';
+            hasToken = false;
+            continue;
+        }
+        current += ch;
+    }
+    if (current !== '' || hasToken)
+        args.push(current);
+    return args;
+}
+/**
+ * Resolve the editor argv from the environment. `$VISUAL` wins over
+ * `$EDITOR` (readline convention); when neither is set there is no fallback
+ * editor — returns undefined and the caller reports `unavailable`.
+ */
+export function resolveEditorCommand(env = process.env) {
+    const raw = (env.VISUAL ?? '').trim() || (env.EDITOR ?? '').trim();
+    if (raw !== '') {
+        const args = splitEditorCommand(raw);
+        return args.length > 0 ? args : undefined;
+    }
+    return undefined;
+}
+/**
+ * Windows shim resolution: a bare command like `code` usually lives on PATH
+ * as `code.cmd`, which libuv refuses to execute directly. Walk PATH with
+ * PATHEXT (case-insensitive on Windows; both casings tried for tests on
+ * case-sensitive filesystems) and report whether the resolved file needs
+ * cmd.exe to run. Commands carrying an explicit extension are used as-is;
+ * unresolved names fall back to the bare command (spawn then resolves
+ * `.exe`, or fails into the `failed` outcome).
+ */
+export function resolveWindowsShim(command, env = process.env) {
+    if (/\.[a-z0-9]+$/i.test(command)) {
+        return { command, viaCmd: /\.(cmd|bat)$/i.test(command) };
+    }
+    const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map(ext => ext.trim())
+        .filter(ext => ext !== '');
+    const pathValue = env.PATH ?? env.Path ?? env.path ?? '';
+    for (const dir of pathValue.split(delimiter)) {
+        if (dir === '')
+            continue;
+        for (const ext of extensions) {
+            for (const casing of [ext, ext.toLowerCase()]) {
+                const candidate = join(dir, command + casing);
+                if (existsSync(candidate)) {
+                    return { command: candidate, viaCmd: /\.(cmd|bat)$/i.test(candidate) };
+                }
+            }
+        }
+    }
+    return { command, viaCmd: false };
+}
+/** npm-generated node shims re-invoke node, parsing the line a second time. */
+const CMD_SHIM_RE = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i;
+/**
+ * Build the `comspec /d /s /c` spawn descriptor for a `.cmd`/`.bat` editor,
+ * following the cross-spawn protocol: the command is normalized first
+ * (explicit forward-slash paths like `C:/Program Files/.../code.cmd` must
+ * become backslash form — cross-spawn's path.normalize step, without which
+ * Windows can ENOENT), then command and arguments are escaped, joined, and
+ * wrapped in one pair of quotes (`/s` strips exactly those), and passed
+ * with `windowsVerbatimArguments` so libuv does not re-quote the payload.
+ * Exported for tests — the assembly is pure.
+ */
+export function buildCmdExeSpawn(command, args, env = process.env) {
+    const normalized = win32.normalize(command);
+    const line = [
+        cmdEscapeCommand(normalized),
+        ...args.map(arg => cmdEscapeArgument(arg, CMD_SHIM_RE.test(normalized))),
+    ].join(' ');
+    return {
+        // `||`, not `??`: a present-but-empty ComSpec must fall back too
+        // (cross-spawn semantics); spawning an empty file name fails outright.
+        file: env.comspec || 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${line}"`],
+        verbatim: true,
+    };
+}
+/**
+ * Run the editor to completion with the terminal attached; resolves to the
+ * exit code, or -1 when the process could not start — including a
+ * SYNCHRONOUS spawn failure (e.g. an empty command string), which would
+ * otherwise reject the promise and skip every cleanup step.
+ */
+function runEditor(argv, file) {
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(code);
+        };
+        let child;
+        try {
+            if (process.platform === 'win32') {
+                const shim = resolveWindowsShim(argv[0]);
+                if (shim.viaCmd) {
+                    const cmd = buildCmdExeSpawn(shim.command, [...argv.slice(1), file]);
+                    child = spawn(cmd.file, cmd.args, {
+                        stdio: 'inherit',
+                        windowsVerbatimArguments: cmd.verbatim,
+                    });
+                }
+                else {
+                    child = spawn(shim.command, [...argv.slice(1), file], { stdio: 'inherit' });
+                }
+            }
+            else {
+                child = spawn(argv[0], [...argv.slice(1), file], { stdio: 'inherit' });
+            }
+        }
+        catch {
+            finish(-1);
+            return;
+        }
+        child.once('error', () => finish(-1));
+        child.once('close', code => finish(code ?? 1));
+    });
+}
+/** Error text for the `failed` outcome, err.message when available. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Edit `draft` in the user's editor and report what happened. Never throws:
+ * every filesystem, spawn, or terminal-restore failure maps to a `failed`
+ * outcome (or is swallowed in the finally) so the UI notifies instead of
+ * dying on an unhandled rejection.
+ *
+ * The Ink instance is looked up lazily (same pattern as Chat's Ctrl+L
+ * redraw) so the util stays usable in tests and non-TTY contexts: without a
+ * live instance the handover escapes are skipped and the editor simply
+ * inherits stdio.
+ *
+ * Newline handling: the saved file is compared against the draft with BOTH
+ * sides CRLF-normalized, so an editor that only converts line endings (or
+ * a draft that already carries `\r\n`) never counts as an edit. Otherwise
+ * ONE trailing newline is stripped when the normalized draft did not end
+ * with one — that is the terminating newline editors append on save, not
+ * user content. Trailing blank lines the user actually added (or had in
+ * the draft, e.g. from Shift+Enter) survive untouched.
+ */
+export async function editInExternalEditor(draft) {
+    const argv = resolveEditorCommand();
+    if (argv === undefined)
+        return { kind: 'unavailable' };
+    const ink = instances.get(process.stdout) ??
+        // Test harnesses render onto a fake stdout — fall back to the process's
+        // single live instance so the handover path stays exercisable there.
+        (instances.size === 1 ? [...instances.values()][0] : undefined);
+    let handed = false;
+    let dir;
+    try {
+        dir = await mkdtemp(join(tmpdir(), 'dsh-tui-prompt-'));
+        // .md so markdown-aware editors highlight the draft like a chat message.
+        const file = join(dir, 'input.md');
+        await writeFile(file, draft, 'utf8');
+        // Mark the handover as attempted BEFORE entering: if enter fails after
+        // suspending stdin, the finally must still run the restore pass.
+        handed = ink !== undefined;
+        ink?.enterAlternateScreen();
+        const code = await runEditor(argv, file);
+        // Read back BEFORE the finally resumes stdin — keystrokes typed the
+        // moment the editor exits must not race the prompt adopting the result.
+        const saved = await readFile(file, 'utf8').catch(() => null);
+        if (code === -1)
+            return { kind: 'failed', message: argv[0] };
+        if (code !== 0 || saved === null)
+            return { kind: 'unchanged' };
+        const normalized = saved.replace(/\r\n/g, '\n');
+        const draftNormalized = draft.replace(/\r\n/g, '\n');
+        if (normalized === draftNormalized)
+            return { kind: 'unchanged' };
+        const text = !draftNormalized.endsWith('\n') && normalized.endsWith('\n')
+            ? normalized.slice(0, -1)
+            : normalized;
+        return text === draftNormalized ? { kind: 'unchanged' } : { kind: 'edited', text };
+    }
+    catch (error) {
+        return { kind: 'failed', message: errorMessage(error) };
+    }
+    finally {
+        // Cleanup runs before the restore: when the finally ends, stdin must
+        // come back to a fully settled state. Both steps are best-effort — a
+        // failure here never overrides the outcome produced above.
+        if (dir !== undefined) {
+            await rm(dir, { recursive: true, force: true }).catch(() => { });
+        }
+        if (handed) {
+            try {
+                ink?.exitAlternateScreen();
+            }
+            catch {
+                // A stuck alt screen is visible to the user; a rejection on top of
+                // a valid outcome is strictly worse — swallow and keep the outcome.
+            }
+        }
+    }
+}

package/lib/types/utils/fileSuggestions.d.ts

@@ -0,0 +1,12 @@
+import type { FileCandidate } from '../adapter/ports/channel-catalog.js';
+export type { FileCandidate, FileCandidateKind } from '../adapter/ports/channel-catalog.js';
+export interface FileSuggestionOptions {
+    topK?: number;
+    maxFiles?: number;
+    maxDirectories?: number;
+}
+export declare function isPathLikeQuery(query: string): boolean;
+export declare function fuzzySubsequenceScore(query: string, candidate: string): number | undefined;
+export declare function rankFileCandidates(candidates: readonly FileCandidate[], query: string, topK?: number): FileCandidate[];
+export declare function preserveSelection(previous: FileCandidate | undefined, next: readonly FileCandidate[], fallback?: number): number;
+//# sourceMappingURL=fileSuggestions.d.ts.map

package/lib/types/utils/fileSuggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSuggestions.d.ts","sourceRoot":"","sources":["../../../src/utils/fileSuggestions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,qCAAqC,CAAA;AAC3F,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAA;AAG3F,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAID,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB1F;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,aAAa,EAAE,CAMlH;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,SAAI,GAAG,MAAM,CAM3H"}

package/lib/types/utils/fileSuggestions.js

@@ -0,0 +1,40 @@
+const pathSeparators = /[\\/]/;
+export function isPathLikeQuery(query) {
+    return query.startsWith('.') || query.startsWith('~') || query.startsWith('/') || /^[A-Za-z]:[\\/]/.test(query) || pathSeparators.test(query);
+}
+export function fuzzySubsequenceScore(query, candidate) {
+    const needle = query.toLocaleLowerCase();
+    const haystack = candidate.toLocaleLowerCase();
+    if (!needle)
+        return 0;
+    let cursor = 0;
+    let first = -1;
+    let gaps = 0;
+    for (const char of needle) {
+        const found = haystack.indexOf(char, cursor);
+        if (found === -1)
+            return undefined;
+        if (first === -1)
+            first = found;
+        gaps += found - cursor;
+        cursor = found + 1;
+    }
+    const prefixBonus = first === 0 ? 20 : 0;
+    const boundaryBonus = first > 0 && /[\\/_. -]/.test(haystack[first - 1] ?? '') ? 8 : 0;
+    return needle.length * 10 + prefixBonus + boundaryBonus - gaps - haystack.length / 100;
+}
+export function rankFileCandidates(candidates, query, topK = 50) {
+    const ranked = candidates
+        .map(candidate => ({ ...candidate, score: fuzzySubsequenceScore(query, `${candidate.path} ${candidate.name}`) ?? -Infinity }))
+        .filter(candidate => Number.isFinite(candidate.score))
+        .sort((a, b) => b.score - a.score || a.kind.localeCompare(b.kind) || a.path.localeCompare(b.path));
+    return ranked.slice(0, Math.max(0, topK));
+}
+export function preserveSelection(previous, next, fallback = 0) {
+    if (previous) {
+        const index = next.findIndex(candidate => candidate.id === previous.id);
+        if (index >= 0)
+            return index;
+    }
+    return next.length === 0 ? 0 : Math.min(Math.max(0, fallback), next.length - 1);
+}