@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,43 @@
+/**
+ * Cross-platform modifier-key helpers. Windows/Linux muscle memory uses
+ * Ctrl+<key>; on macOS the same action maps to Cmd+<key>. Terminals deliver
+ * Cmd as the `super` flag (kitty CSI-u / xterm modifyOtherKeys); Ctrl keeps
+ * working everywhere, so `isMod`
+ * accepts either on the mac and stays Ctrl-only elsewhere.
+ */
+export declare const isMac: boolean;
+/** True when the key event carries the platform's "primary" modifier. */
+export declare function isMod(key: {
+    ctrl?: boolean;
+    super?: boolean;
+}): boolean;
+/**
+ * Display prefix for shortcut labels: "⌘" on macOS (Apple style, no "+"),
+ * "ctrl+" everywhere else. Pair with the bare key, e.g. `${modLabel}o`.
+ */
+export declare const modLabel: string;
+/**
+ * Modal-confirm guard. Since #110 the input pipeline can deliver Enter WITH
+ * modifiers: Option+Enter arrives as meta+return (ESC CR), and on
+ * extended-keys terminals (kitty CSI-u / modifyOtherKeys) Shift/Ctrl+Enter
+ * arrive as return+modifier. A bare `key.return` in a decision dialog would
+ * let those commit by accident — approving a permission escalation or
+ * confirming an irreversible session delete when the user only wanted a
+ * newline. Only a modifier-free Enter may commit a modal.
+ */
+export declare function isPlainReturn(key: {
+    return?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    super?: boolean;
+}): boolean;
+/**
+ * Modal Enter recognition across parsed key events and Windows ConPTY's raw
+ * CR/LF fallback. PromptInput already handled both forms; shared modal
+ * pickers must do the same or their UI can render while Enter appears inert.
+ */
+export declare function isPlainReturnInput(input: string, key: Parameters<typeof isPlainReturn>[0] & {
+    isPasted?: boolean;
+}): boolean;
+//# sourceMappingURL=modifiers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modifiers.d.ts","sourceRoot":"","sources":["../../../src/utils/modifiers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,KAAK,SAAgC,CAAA;AAElD,yEAAyE;AACzE,wBAAgB,KAAK,CAAC,GAAG,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAEvE;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAwB,CAAA;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE;IACjC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,GAAG,OAAO,CAEV;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChE,OAAO,CAQT"}

package/lib/types/utils/modifiers.js

@@ -0,0 +1,45 @@
+/**
+ * Cross-platform modifier-key helpers. Windows/Linux muscle memory uses
+ * Ctrl+<key>; on macOS the same action maps to Cmd+<key>. Terminals deliver
+ * Cmd as the `super` flag (kitty CSI-u / xterm modifyOtherKeys); Ctrl keeps
+ * working everywhere, so `isMod`
+ * accepts either on the mac and stays Ctrl-only elsewhere.
+ */
+export const isMac = process.platform === 'darwin';
+/** True when the key event carries the platform's "primary" modifier. */
+export function isMod(key) {
+    return !!key.ctrl || (isMac && !!key.super);
+}
+/**
+ * Display prefix for shortcut labels: "⌘" on macOS (Apple style, no "+"),
+ * "ctrl+" everywhere else. Pair with the bare key, e.g. `${modLabel}o`.
+ */
+export const modLabel = isMac ? '⌘' : 'ctrl+';
+/**
+ * Modal-confirm guard. Since #110 the input pipeline can deliver Enter WITH
+ * modifiers: Option+Enter arrives as meta+return (ESC CR), and on
+ * extended-keys terminals (kitty CSI-u / modifyOtherKeys) Shift/Ctrl+Enter
+ * arrive as return+modifier. A bare `key.return` in a decision dialog would
+ * let those commit by accident — approving a permission escalation or
+ * confirming an irreversible session delete when the user only wanted a
+ * newline. Only a modifier-free Enter may commit a modal.
+ */
+export function isPlainReturn(key) {
+    return !!key.return && !key.ctrl && !key.meta && !key.shift && !key.super;
+}
+/**
+ * Modal Enter recognition across parsed key events and Windows ConPTY's raw
+ * CR/LF fallback. PromptInput already handled both forms; shared modal
+ * pickers must do the same or their UI can render while Enter appears inert.
+ */
+export function isPlainReturnInput(input, key) {
+    // Bracketed paste can deliver a chunk that is all line breaks — that is
+    // pasted content, not an Enter press, and must never confirm a modal.
+    // Checked FIRST: a paste chunk may even carry the return flag.
+    if (key.isPasted === true)
+        return false;
+    if (isPlainReturn(key))
+        return true;
+    return /^[\r\n]+$/u.test(input)
+        && !key.ctrl && !key.meta && !key.shift && !key.super;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Strip the `⏵` self-narration line from assistant text. The
+ * dsh-working-activity narrate contract puts exactly one `⏵` line at the
+ * very top of a reply; the live working line already surfaces it, so
+ * showing it again in the transcript would double it. Only the FIRST line
+ * is checked — the contract allows one `⏵` line per reply.
+ * @param text - Assistant text to strip.
+ * @returns The text without its leading `⏵` narration line.
+ */
+export declare function stripNarration(text: string): string;
+//# sourceMappingURL=narration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"narration.d.ts","sourceRoot":"","sources":["../../../src/utils/narration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD"}

package/lib/types/utils/narration.js

@@ -0,0 +1,16 @@
+/**
+ * Strip the `⏵` self-narration line from assistant text. The
+ * dsh-working-activity narrate contract puts exactly one `⏵` line at the
+ * very top of a reply; the live working line already surfaces it, so
+ * showing it again in the transcript would double it. Only the FIRST line
+ * is checked — the contract allows one `⏵` line per reply.
+ * @param text - Assistant text to strip.
+ * @returns The text without its leading `⏵` narration line.
+ */
+export function stripNarration(text) {
+    const newline = text.indexOf('\n');
+    const firstLine = newline === -1 ? text : text.slice(0, newline);
+    if (!firstLine.trimStart().startsWith('⏵'))
+        return text;
+    return newline === -1 ? '' : text.slice(newline + 1).replace(/^\n+/, '');
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Windows `start` via cmd.exe: `start "" "<target>"` (the empty quoted
+ * title is mandatory — start would otherwise treat a quoted target as the
+ * window title). Exported for tests: assembly is pure.
+ */
+export declare function buildWin32StartSpawn(target: string): {
+    file: string;
+    args: string[];
+    verbatim: true;
+    detach: true;
+};
+/** Whether `target` exists on disk as a directory (decides the open
+ *  channel: folders bypass the ShellExecute verb and go through the
+ *  Shell.Application COM API). Never throws. */
+export declare function isDirectory(target: string): boolean;
+/**
+ * The Windows spawn descriptor for opening `target` (pure, testable):
+ * directories go through `powershell (New-Object -ComObject
+ * Shell.Application).Open('<dir>')`, everything else (files, URLs) through
+ * `start`. Explorer's single-instance forwarding silently swallows
+ * "open folder" requests on many systems (diagnosed in the field: `start`,
+ * raw explorer, and `/select,` all dead while the COM API works), so the
+ * COM channel is the reliable folder opener; single quotes in the path are
+ * doubled for the PowerShell literal. The COM descriptor also carries
+ * `detach: false` — a DETACHED_PROCESS (console-less) PowerShell silently
+ * drops the Shell.Application Open call, so the channel only works with
+ * `windowsHide` (CREATE_NO_WINDOW) alone (field-diagnosed spawn matrix:
+ * detached+hide → dead, hide-only → works; start keeps working detached).
+ */
+export declare function buildWin32OpenSpawn(target: string): {
+    file: string;
+    args: string[];
+    verbatim: boolean;
+    detach: boolean;
+};
+/** Open a URL, file or directory with the platform's default handler. */
+export declare function openExternal(target: string): void;
+/** Open a file with its associated application (openExternal with a file). */
+export declare function openFile(path: string): void;
+/**
+ * Open the folder containing `filePath` in the platform file manager.
+ *
+ * Windows and Linux open the parent DIRECTORY through openExternal —
+ * Windows routes folders through the Shell.Application COM channel (see
+ * buildWin32OpenSpawn). macOS uses `open -R` to select the file, degrading
+ * to the folder when the file is gone. No-op when neither the file nor its
+ * parent exists (a stale/hallucinated path must not spawn error dialogs).
+ */
+export declare function revealInFileManager(filePath: string): void;
+//# sourceMappingURL=openExternal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openExternal.d.ts","sourceRoot":"","sources":["../../../src/utils/openExternal.ts"],"names":[],"mappings":"AAgEA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAQnH;AAED;;gDAEgD;AAChD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAWxH;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAqBjD;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAgB1D"}

package/lib/types/utils/openExternal.js

@@ -0,0 +1,170 @@
+/**
+ * Open URLs, files and folders with the platform's default handler, fully
+ * detached from the TUI process (fire-and-forget: no stdio pipes, no wait,
+ * child unref'd so the TUI can exit without waiting for the handler).
+ *
+ * Launch strategy per platform:
+ * - Windows files/URLs: `start` is a cmd.exe builtin, so everything goes
+ *   through `$comspec /d /s /c start "" "<target>"` using the vendored
+ *   cross-spawn quoting (shellQuote.ts) with windowsVerbatimArguments —
+ *   the same protocol externalEditor.ts uses for .cmd shims.
+ * - Windows DIRECTORIES: `powershell (New-Object -ComObject
+ *   Shell.Application).Open('<dir>')`. Explorer's single-instance
+ *   forwarding silently swallows "open folder" requests on many systems
+ *   (field-diagnosed: `start`, raw explorer and `/select,` all dead while
+ *   the COM API works), so folders bypass ShellExecute entirely. This
+ *   powershell child must NOT be spawned detached: libuv maps
+ *   `detached: true` to DETACHED_PROCESS (a console-less process) and in
+ *   that state the Shell.Application Open call silently does nothing
+ *   (field-diagnosed via spawn matrix: detached+hide dead, hide-only
+ *   works) — `windowsHide` alone (CREATE_NO_WINDOW) keeps it invisible
+ *   AND functional.
+ * - macOS: `open` (reveal adds `-R`).
+ * - Linux/other: `xdg-open`.
+ */
+import { spawn } from 'node:child_process';
+import { dirname } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { cmdEscapeArgument } from './shellQuote.js';
+import { logError } from './log.js';
+/**
+ * Spawn a fire-and-forget child: no stdio pipes, no wait, unref'd so the
+ * TUI can exit without waiting for the handler. On Windows `detach`
+ * controls the DETACHED_PROCESS flag — it must stay false for the
+ * Shell.Application COM channel (console-less PowerShell swallows the
+ * Open call; see buildWin32OpenSpawn). Failures are logged, never
+ * thrown — an unopenable target (missing handler, sandboxed desktop)
+ * must not disturb the TUI. `onError` lets callers degrade (e.g.
+ * reveal → open parent folder).
+ */
+function spawnDetached(file, args, opts = {}) {
+    const { verbatim = false, detach = true, onError } = opts;
+    try {
+        const child = spawn(file, [...args], {
+            stdio: 'ignore',
+            detached: detach,
+            windowsHide: true,
+            windowsVerbatimArguments: verbatim,
+        });
+        child.on('error', error => {
+            logError(error);
+            onError?.();
+        });
+        child.unref();
+    }
+    catch (error) {
+        logError(error);
+        onError?.();
+    }
+}
+/**
+ * Windows `start` via cmd.exe: `start "" "<target>"` (the empty quoted
+ * title is mandatory — start would otherwise treat a quoted target as the
+ * window title). Exported for tests: assembly is pure.
+ */
+export function buildWin32StartSpawn(target) {
+    const line = ['start', cmdEscapeArgument(''), cmdEscapeArgument(target)].join(' ');
+    return {
+        file: process.env.ComSpec || 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${line}"`],
+        verbatim: true,
+        detach: true,
+    };
+}
+/** Whether `target` exists on disk as a directory (decides the open
+ *  channel: folders bypass the ShellExecute verb and go through the
+ *  Shell.Application COM API). Never throws. */
+export function isDirectory(target) {
+    try {
+        return statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Windows spawn descriptor for opening `target` (pure, testable):
+ * directories go through `powershell (New-Object -ComObject
+ * Shell.Application).Open('<dir>')`, everything else (files, URLs) through
+ * `start`. Explorer's single-instance forwarding silently swallows
+ * "open folder" requests on many systems (diagnosed in the field: `start`,
+ * raw explorer, and `/select,` all dead while the COM API works), so the
+ * COM channel is the reliable folder opener; single quotes in the path are
+ * doubled for the PowerShell literal. The COM descriptor also carries
+ * `detach: false` — a DETACHED_PROCESS (console-less) PowerShell silently
+ * drops the Shell.Application Open call, so the channel only works with
+ * `windowsHide` (CREATE_NO_WINDOW) alone (field-diagnosed spawn matrix:
+ * detached+hide → dead, hide-only → works; start keeps working detached).
+ */
+export function buildWin32OpenSpawn(target) {
+    if (isDirectory(target)) {
+        const literal = target.replace(/'/g, "''");
+        return {
+            file: 'powershell.exe',
+            args: ['-NoProfile', '-Command', `(New-Object -ComObject Shell.Application).Open('${literal}')`],
+            verbatim: false,
+            detach: false,
+        };
+    }
+    return buildWin32StartSpawn(target);
+}
+/** Open a URL, file or directory with the platform's default handler. */
+export function openExternal(target) {
+    if (target === '')
+        return;
+    if (process.platform === 'win32') {
+        const cmd = buildWin32OpenSpawn(target);
+        // If the primary channel cannot even spawn (e.g. PowerShell missing on
+        // an exotic system), fall back to `start` — reliable on healthy boxes.
+        spawnDetached(cmd.file, cmd.args, {
+            verbatim: cmd.verbatim,
+            detach: cmd.detach,
+            onError: () => {
+                if (cmd.file !== (process.env.ComSpec || 'cmd.exe')) {
+                    const fb = buildWin32StartSpawn(target);
+                    spawnDetached(fb.file, fb.args, { verbatim: fb.verbatim });
+                }
+            },
+        });
+    }
+    else if (process.platform === 'darwin') {
+        spawnDetached('open', [target]);
+    }
+    else {
+        spawnDetached('xdg-open', [target]);
+    }
+}
+/** Open a file with its associated application (openExternal with a file). */
+export function openFile(path) {
+    openExternal(path);
+}
+/**
+ * Open the folder containing `filePath` in the platform file manager.
+ *
+ * Windows and Linux open the parent DIRECTORY through openExternal —
+ * Windows routes folders through the Shell.Application COM channel (see
+ * buildWin32OpenSpawn). macOS uses `open -R` to select the file, degrading
+ * to the folder when the file is gone. No-op when neither the file nor its
+ * parent exists (a stale/hallucinated path must not spawn error dialogs).
+ */
+export function revealInFileManager(filePath) {
+    if (filePath === '')
+        return;
+    const dir = dirname(filePath);
+    if (process.platform === 'darwin') {
+        if (existsSync(filePath)) {
+            spawnDetached('open', ['-R', filePath], {
+                onError: () => {
+                    if (existsSync(dir))
+                        openExternal(dir);
+                },
+            });
+            return;
+        }
+        if (existsSync(dir))
+            openExternal(dir);
+        return;
+    }
+    if (existsSync(dir))
+        openExternal(dir);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Conservative recognition of "the terminal pasted exactly one local image
+ * file path" — the only shape a Finder/desktop drop reliably reaches the TUI
+ * as. Ghostty (and most terminals) forward a drop as shell-escaped plain
+ * text through the PTY, with no MIME or drag-and-drop boundary, so anything
+ * ambiguous must stay verbatim text: this parser returns null unless the
+ * WHOLE paste is a single, syntactically unambiguous local image path.
+ * Existence is the caller's async check; parse success alone stages nothing.
+ */
+/** Image media type per file extension, or undefined for non-image paths.
+ *  The one extension→type table shared by every composer staging path. */
+export declare function imagePathMediaType(path: string): 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | undefined;
+/**
+ * Parse a bracketed-paste payload as one unambiguous local image path.
+ *
+ * Accepted forms (after trimming outer whitespace):
+ * - a wholly single- or double-quoted path: `'/a/b c.png'`, `"/a/b c.png"`
+ * - one bare token with backslash-escaped separators (Ghostty's
+ *   `Shell.escape`): `/a/b\ c.png`
+ * - a Windows drive-letter absolute path, quoted or bare: `D:\shots\a.png`,
+ *   `D:/shots/a.png` (the terminal text-paste shape of an Explorer file
+ *   copy — Warp and friends forward file copies as plain path text; the
+ *   backslash separators decode literally in the bare-token branch)
+ *
+ * The decoded path must be absolute (or `~/…`, expanded) and carry a
+ * supported image extension. Everything else — multiple tokens, relative
+ * paths, embedded newlines, unterminated quotes, non-image extensions —
+ * returns null so the caller inserts the paste verbatim.
+ */
+export declare function parsePastedImagePath(text: string): string | null;
+/**
+ * Partition a file-manager clipboard offer: image paths resolve to opaque
+ * staged values through `stage`, while other or failed paths keep
+ * `formatPath`'s plain insert, preserving offer order. The caller binds all
+ * staged values to visible tokens only after this batch settles. `failure`
+ * carries the last staging error message ('' when none) for one warning.
+ */
+export type StagedClipboardFilePart<T> = {
+    readonly kind: 'staged';
+    readonly value: T;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+};
+export declare function stageClipboardFilePaths<T>(paths: readonly string[], stage: (path: string) => Promise<T>, formatPath: (path: string) => string, maxStaged?: number): Promise<{
+    readonly parts: readonly StagedClipboardFilePart<T>[];
+    readonly staged: readonly T[];
+    readonly failure: string;
+    readonly failureCode?: 'image-limit';
+}>;
+//# sourceMappingURL=pastedImagePath.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pastedImagePath.d.ts","sourceRoot":"","sources":["../../../src/utils/pastedImagePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GACX,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAMrE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiChE;AAgFD;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACpC,SAAS,SAA2B,GACnC,OAAO,CAAC;IACT,QAAQ,CAAC,KAAK,EAAE,SAAS,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAA;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAA;CACrC,CAAC,CA2BD"}

package/lib/types/utils/pastedImagePath.js

@@ -0,0 +1,194 @@
+/**
+ * Conservative recognition of "the terminal pasted exactly one local image
+ * file path" — the only shape a Finder/desktop drop reliably reaches the TUI
+ * as. Ghostty (and most terminals) forward a drop as shell-escaped plain
+ * text through the PTY, with no MIME or drag-and-drop boundary, so anything
+ * ambiguous must stay verbatim text: this parser returns null unless the
+ * WHOLE paste is a single, syntactically unambiguous local image path.
+ * Existence is the caller's async check; parse success alone stages nothing.
+ */
+import { homedir } from 'node:os';
+/** Image media type per file extension, or undefined for non-image paths.
+ *  The one extension→type table shared by every composer staging path. */
+export function imagePathMediaType(path) {
+    if (/\.png$/iu.test(path))
+        return 'image/png';
+    if (/\.jpe?g$/iu.test(path))
+        return 'image/jpeg';
+    if (/\.webp$/iu.test(path))
+        return 'image/webp';
+    if (/\.gif$/iu.test(path))
+        return 'image/gif';
+    return undefined;
+}
+const MAX_PASTED_PATH_CHARS = 4096;
+/**
+ * Parse a bracketed-paste payload as one unambiguous local image path.
+ *
+ * Accepted forms (after trimming outer whitespace):
+ * - a wholly single- or double-quoted path: `'/a/b c.png'`, `"/a/b c.png"`
+ * - one bare token with backslash-escaped separators (Ghostty's
+ *   `Shell.escape`): `/a/b\ c.png`
+ * - a Windows drive-letter absolute path, quoted or bare: `D:\shots\a.png`,
+ *   `D:/shots/a.png` (the terminal text-paste shape of an Explorer file
+ *   copy — Warp and friends forward file copies as plain path text; the
+ *   backslash separators decode literally in the bare-token branch)
+ *
+ * The decoded path must be absolute (or `~/…`, expanded) and carry a
+ * supported image extension. Everything else — multiple tokens, relative
+ * paths, embedded newlines, unterminated quotes, non-image extensions —
+ * returns null so the caller inserts the paste verbatim.
+ */
+export function parsePastedImagePath(text) {
+    if (text.length > MAX_PASTED_PATH_CHARS)
+        return null;
+    const trimmed = text.trim();
+    if (trimmed === '' || trimmed.includes('\n') || trimmed.includes('\r'))
+        return null;
+    let path;
+    const quote = trimmed[0];
+    if (quote === "'" || quote === '"') {
+        if (trimmed.length < 3 || !trimmed.endsWith(quote))
+            return null;
+        const inner = trimmed.slice(1, -1);
+        if (quote === "'") {
+            // POSIX single quotes are wholly literal and cannot contain one.
+            if (inner.includes(quote))
+                return null;
+            path = inner;
+        }
+        else if (isDriveLetterPath(inner)) {
+            // A quoted Windows path is already literal: backslashes are
+            // separators, not shell escapes (a quote itself cannot appear in a
+            // path, so nothing needs unescaping here).
+            path = inner;
+        }
+        else {
+            path = unescapeDoubleQuoted(inner);
+        }
+    }
+    else {
+        path = isDriveLetterPath(trimmed)
+            ? unescapeWindowsPath(trimmed)
+            : unescapeBackslashes(trimmed);
+    }
+    if (path === null)
+        return null;
+    if (path.startsWith('~/'))
+        path = homedir() + path.slice(1);
+    if (!isAbsolutePath(path))
+        return null;
+    if (imagePathMediaType(path) === undefined)
+        return null;
+    return path;
+}
+/** True for `X:\…` / `X:/…` (Windows absolute, drive letter first). */
+function isDriveLetterPath(path) {
+    return /^[A-Za-z]:[/\\]/u.test(path);
+}
+/** Absolute on POSIX (`/…`) and Windows (`X:\…` / `X:/…`). No platform
+ *  branch: a POSIX path never starts with a drive letter and a Windows
+ *  absolute path always does, so the forms are disjoint. Existence remains
+ *  the caller's async check. */
+function isAbsolutePath(path) {
+    if (path.startsWith('/'))
+        return true;
+    return isDriveLetterPath(path);
+}
+/**
+ * Decode a bare Windows drive-letter token: backslashes are literal path
+ * separators, not shell escapes. A space/tab (multiple shell tokens), a
+ * double backslash (UNC-ish) or a dangling trailing backslash still fails
+ * closed and the paste stays verbatim.
+ */
+function unescapeWindowsPath(text) {
+    let out = '';
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '\\') {
+            const next = text[index + 1];
+            if (next === undefined)
+                return null;
+            if (next === ' ' || next === '\t' || next === '\\')
+                return null;
+            out += char;
+            continue;
+        }
+        if (char === ' ' || char === '\t')
+            return null;
+        out += char;
+    }
+    return out;
+}
+/** Decode only the two unambiguous escapes inside a shell double-quoted
+ * token. Treating every `\x` as x can silently redirect a pasted path to a
+ * different existing file, so unknown escapes and naked quotes fail closed. */
+function unescapeDoubleQuoted(text) {
+    let out = '';
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"')
+            return null;
+        if (char !== '\\') {
+            out += char;
+            continue;
+        }
+        if (index + 1 >= text.length)
+            return null;
+        const escaped = text[index + 1];
+        if (escaped !== '\\' && escaped !== '"')
+            return null;
+        out += escaped;
+        index += 1;
+    }
+    return out;
+}
+/** Resolve `\x` escapes with one linear scan. An unescaped space/tab
+ *  (multiple shell tokens) or a dangling trailing backslash fails. */
+function unescapeBackslashes(text) {
+    let out = '';
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '\\') {
+            if (index + 1 >= text.length)
+                return null;
+            out += text[index + 1];
+            index += 1;
+            continue;
+        }
+        if (char === ' ' || char === '\t') {
+            return null;
+        }
+        out += char;
+    }
+    return out;
+}
+export async function stageClipboardFilePaths(paths, stage, formatPath, maxStaged = Number.POSITIVE_INFINITY) {
+    const parts = [];
+    const staged = [];
+    let failure = '';
+    let failureCode;
+    for (const path of paths) {
+        if (imagePathMediaType(path) === undefined) {
+            parts.push({ kind: 'text', value: formatPath(path) });
+            continue;
+        }
+        if (staged.length >= maxStaged) {
+            failure = 'image count exceeds this profile\'s per-message limit';
+            failureCode = 'image-limit';
+            parts.push({ kind: 'text', value: formatPath(path) });
+            continue;
+        }
+        try {
+            const value = await stage(path);
+            parts.push({ kind: 'staged', value });
+            staged.push(value);
+        }
+        catch (error) {
+            failure = error instanceof Error ? error.message : String(error);
+            failureCode = undefined;
+            parts.push({ kind: 'text', value: formatPath(path) });
+        }
+    }
+    return { parts, staged, failure, ...(failureCode ? { failureCode } : {}) };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Data-directory paths for the dsh-tui profile. All preferences and history
+ * live under `~/.dsh-tui`.
+ *
+ * The compiled copy (lib/types/utils/paths.js) is also imported by the bin
+ * launcher, mirroring the shellQuote precedent.
+ */
+/**
+ * The user's home directory. `os.homedir()` first; the USERPROFILE/HOME
+ * spellings are the last-resort fallback for stripped-down environments.
+ * @returns Absolute home path.
+ */
+export declare function homeDir(): string;
+/** Data directory all preferences/history live in (`~/.dsh-tui`). */
+export declare const DATA_DIR: string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/utils/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED,qEAAqE;AACrE,eAAO,MAAM,QAAQ,QAA8B,CAAA"}

package/lib/types/utils/paths.js

@@ -0,0 +1,19 @@
+/**
+ * Data-directory paths for the dsh-tui profile. All preferences and history
+ * live under `~/.dsh-tui`.
+ *
+ * The compiled copy (lib/types/utils/paths.js) is also imported by the bin
+ * launcher, mirroring the shellQuote precedent.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * The user's home directory. `os.homedir()` first; the USERPROFILE/HOME
+ * spellings are the last-resort fallback for stripped-down environments.
+ * @returns Absolute home path.
+ */
+export function homeDir() {
+    return homedir() || process.env.USERPROFILE || process.env.HOME || '';
+}
+/** Data directory all preferences/history live in (`~/.dsh-tui`). */
+export const DATA_DIR = join(homeDir(), '.dsh-tui');

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

@@ -0,0 +1,9 @@
+/**
+ * Minimal semver `>=` comparison used when terminal capabilities depend on
+ * `TERM_PROGRAM_VERSION`.
+ * @param a - First version string (optional `v` prefix and pre-release suffix tolerated).
+ * @param b - Second version string.
+ * @returns True when `a` is greater than or equal to `b`.
+ */
+export declare function gte(a: string, b: string): boolean;
+//# sourceMappingURL=semver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../../../src/utils/semver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAOjD"}