@deepseek-harness-tui/dsh-tui 0.8.8 → 0.9.1

package/lib/types/update.js

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
-import { readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gte, gt, lt, valid } from 'semver';
 import { shellQuote } from './utils/shellQuote.js';
+import { DATA_DIR } from './utils/paths.js';
 // Re-exported for scripts/verify-update.mjs and the bin launcher, which reads
 // the compiled copy at lib/types/utils/shellQuote.js.
 export { shellQuote };
@@ -13,6 +14,72 @@ const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 const UPDATE_CHECK_TIMEOUT_MS = 4000;
 /** env marker set on the /update restart; the new process verifies it at boot. */
 const UPDATED_FROM_ENV = 'DSH_TUI_UPDATED_FROM';
+/**
+ * env marker set on the /restart replacement: its boot logs to restart.log
+ * (ordinary launches stay silent, so the file is restart-only evidence).
+ */
+const RESTART_CHILD_ENV = 'DSH_TUI_RESTART_CHILD';
+/**
+ * Field-diagnosis log for the /restart terminal handoff, appended by BOTH
+ * processes: the exiting TUI logs the funnel path, the spawned replacement
+ * logs its boot progress, and every line carries pid + timestamp — so a
+ * handoff that dies at any stage (loader entry, TTY gate, session resume,
+ * even after the parent's survival window) leaves breadcrumbs on disk even
+ * when nothing reaches the already-confused terminal. Diagnosis only: every
+ * write is best effort and must never break the handoff itself.
+ */
+const RESTART_LOG = join(DATA_DIR, 'restart.log');
+/** Cap so a long debugging streak cannot grow the log unbounded. */
+const RESTART_LOG_MAX_BYTES = 256 * 1024;
+function writeRestartLine(line) {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        appendFileSync(RESTART_LOG, `${new Date().toISOString()} pid=${process.pid} ${line}\n`);
+    }
+    catch {
+        // Diagnosis only.
+    }
+}
+/**
+ * Append a /restart handoff event to ~/.dsh-tui/restart.log.
+ * @param event - Short stable event name.
+ * @param data - Small JSON-safe detail (never credentials or session text).
+ */
+export function logRestartEvent(event, data) {
+    writeRestartLine(`${event}${data === undefined ? '' : ` ${JSON.stringify(data)}`}`);
+}
+/** Start a fresh, clearly delimited /restart attempt block in the log. */
+export function beginRestartAttempt(sessionId) {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        let size = 0;
+        try {
+            size = statSync(RESTART_LOG).size;
+        }
+        catch {
+            size = 0;
+        }
+        if (size > RESTART_LOG_MAX_BYTES)
+            writeFileSync(RESTART_LOG, '');
+    }
+    catch {
+        // Diagnosis only.
+    }
+    writeRestartLine(`--- /restart attempt session=${sessionId} ---`);
+}
+/**
+ * Write a handoff notice to stderr synchronously: process.exit() right after
+ * an async stream write skips the flush, and a vanished diagnosis is
+ * indistinguishable from a silent failure.
+ */
+export function writeHandoffNotice(text) {
+    try {
+        writeFileSync(2, text);
+    }
+    catch {
+        process.stderr.write(text);
+    }
+}
 /** Read the version from either the compiled package or the source checkout. */
 export function installedTuiVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -225,6 +292,79 @@ export function tuiUpdatePluginArgs(profile, targetVersion) {
 export function isTransientUpdateFailure(stderr) {
     return /ENOENT|EPERM|EBUSY/i.test(stderr) && /_tmp_\d+/i.test(stderr);
 }
+/**
+ * The pnpm Linux flavor of the tmp-rename race (issue #479): the very same
+ * `importPackage` staging path, but overlayfs surfaces the second swap of an
+ * already-replaced package dir as EEXIST — deterministically, on every run,
+ * never transiently. A plain retry of the identical command ALWAYS fails the
+ * same way (the leftover `_tmp_<pid>_<threadId>` staging dir keeps colliding),
+ * so this signature must route to the recovery path
+ * (removeStalePackageInstall + rerun), not to the plain retry.
+ */
+export function isEexistTmpRenameFailure(stderr) {
+    return /EEXIST/i.test(stderr) && /_tmp_\d+/i.test(stderr);
+}
+/**
+ * The dsh profile layout places plugin packages under
+ * `$DSH_HOME ?? ~/.dsh` — the same root dsh itself resolves
+ * (`dshHomePath is $DSH_HOME ?? ~/.dsh`, and packaged presets resolve
+ * identically). /update's recovery path needs this location to clear a
+ * half-updated install pnpm can no longer swap in place (issue #479).
+ */
+export function profilePackageDir(profile) {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dshHome, 'profiles', profile, 'node_modules', PACKAGE_NAME);
+}
+/**
+ * Recovery for the pnpm tmp-rename races (issues #225/#479): remove the
+ * profile's installed copy of this package plus the sibling `_tmp_`
+ * staging dirs a crashed swap leaves behind, so the next installer run
+ * takes the fresh-install path instead of renaming over the collision.
+ * Field-verified workaround (issue #479): `rm -rf <pkg dir>` + rerun
+ * succeeds where ten plain retries fail.
+ *
+ * A junction/symlink at the package dir is UNLINKED only — the link is
+ * removed, the target tree (a dev checkout it may point at) is never
+ * traversed or deleted. Best effort throughout: this runs inside a
+ * failure-recovery branch, so an unusable result simply falls through to
+ * the rerun and the manual repair hint.
+ */
+export function removeStalePackageInstall(profile) {
+    const pkgDir = profilePackageDir(profile);
+    const scopeDir = dirname(pkgDir);
+    const removal = { packageDir: 'absent', tmpDirs: [] };
+    try {
+        const stats = lstatSync(pkgDir);
+        // lstat reports junctions AND symlinks as isSymbolicLink — remove the
+        // link itself, never what it points at.
+        if (stats.isSymbolicLink() || stats.isDirectory()) {
+            rmSync(pkgDir, { recursive: true, force: true });
+            removal.packageDir = 'removed';
+        }
+    }
+    catch (error) {
+        removal.packageDir = error.code === 'ENOENT' ? 'absent' : 'failed';
+    }
+    try {
+        for (const name of readdirSync(scopeDir)) {
+            if (!/^dsh-tui_tmp_\d+_\d+$/.test(name))
+                continue;
+            const staging = join(scopeDir, name);
+            try {
+                rmSync(staging, { recursive: true, force: true });
+                removal.tmpDirs.push(name);
+            }
+            catch {
+                // Staging leftovers are best effort; the package dir removal is
+                // the load-bearing half of the recovery.
+            }
+        }
+    }
+    catch {
+        // Unreadable scope dir — nothing more to clear.
+    }
+    return removal;
+}
 /**
  * Best-effort migrate the GLOBAL launcher to the delegating shim (0.8.7):
  * after a successful profile update, copy this package's `bin/dsh-tui.js`
@@ -290,24 +430,17 @@ export function migrateGlobalLauncher() {
     return false;
 }
 /**
- * Update the installed dsh-tui package and restart the same launcher while
- * preserving the active session. The TUI must already be unmounted before
- * this is called so pnpm output cannot corrupt the rendered terminal frame.
+ * Install-only half of `/update`: run `dsh plugin add`, refuse boot-deadlock
+ * targets, verify the profile actually advanced, and migrate the global
+ * launcher. No restart — `updateTuiAndRestart` layers the session-preserving
+ * restart on top, and the `dsh-tui update` CLI stops here.
  *
- * When the preflight registry check resolved an exact target, pass that
- * version to pnpm instead of resolving `latest` a second time. This avoids a
- * stale mirror/dist-tag response between the check and install. If preflight
- * failed, retain the `--latest` fallback: a plain `pnpm update` stays inside
- * the manifest range and can restart unchanged across minor releases.
- *
- * @param sessionId - Session to resume in the replacement process.
- * @param profile - The dsh profile this TUI was launched with; updating any
- *   other profile would leave the running install untouched.
- * @param targetVersion - Exact version returned by the preflight registry
- *   check, or undefined when that check failed and pnpm should resolve latest.
- * @returns Exit codes for the update run and the replacement process.
+ * @param profile - The dsh profile to update.
+ * @param targetVersion - Exact version from the preflight registry check, or
+ *   undefined when that check failed and pnpm should resolve latest.
+ * @returns The update exit code plus the before/after versions.
  */
-export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
+export async function updateTui(profile, targetVersion) {
     // Stamp the pre-update version BEFORE pnpm runs: it reads this package's
     // manifest from disk, which the update replaces on the fly — a
     // post-update read already sees the NEW version, and the restarted
@@ -327,8 +460,23 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
         updateStderr = '';
         updateCode = await runProcess(dsh, updateArgs, { shell: true, onStderr: capture });
     }
+    // Deterministic Linux tmp-rename race (issue #479): EEXIST never clears on
+    // a plain retry (the staging-dir collision reproduces every run), and a
+    // transient retry that failed again means the same leftover state. Both
+    // recover by removing the stale install + staging dirs, then rerunning —
+    // the field-verified workaround that takes pnpm down its fresh-install
+    // path instead of renaming over the collision.
+    if (updateCode !== 0 && (isEexistTmpRenameFailure(updateStderr) || isTransientUpdateFailure(updateStderr))) {
+        const flavor = isEexistTmpRenameFailure(updateStderr) ? 'EEXIST, issue #479' : 'retry failed, issue #225';
+        const removal = removeStalePackageInstall(profile);
+        const stagingNote = removal.tmpDirs.length > 0 ? ` + ${removal.tmpDirs.length} staging dir(s)` : '';
+        process.stderr.write(`dsh-tui: pnpm tmp-rename race (${flavor}) — cleared the stale install ` +
+            `(package dir: ${removal.packageDir}${stagingNote}) and rerunning the update…\n`);
+        updateStderr = '';
+        updateCode = await runProcess(dsh, updateArgs, { shell: true, onStderr: capture });
+    }
     if (updateCode !== 0)
-        return { updateCode, restartCode: updateCode };
+        return { code: updateCode, updatedFrom };
     // A --latest fallback (preflight failed) on a stale mirror can still land
     // on the 0.7.0–0.7.1 hard-inject range — restarting into it under an older
     // global-launcher patch is the permanent boot deadlock of issues
@@ -341,7 +489,7 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
             `(#183/#307) — NOT restarting into it. Repair with:\n` +
             `  dsh plugin --profile ${profile} add ${PACKAGE_NAME}@latest\n` +
             `(if the mirror has not synced the latest release yet, retry later)\n`);
-        return { updateCode: 1, restartCode: 1 };
+        return { code: 1, updatedFrom, installed: installedNow };
     }
     // Post-update verification (issue #225): pnpm can report success yet leave
     // the profile half-updated (manifest old / lockfile new). Verify against
@@ -358,7 +506,7 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
             process.stderr.write(`dsh-tui: update completed but the profile still runs ${installed ?? 'an unreadable version'} ` +
                 `(expected ${targetVersion}) — the profile is half-updated. Repair manually with:\n` +
                 `  dsh plugin --profile ${profile} add ${PACKAGE_NAME}@${targetVersion}\n`);
-            return { updateCode: 1, restartCode: 1 };
+            return { code: 1, updatedFrom, installed };
         }
     }
     // Launcher migration (0.8.7): the freshly installed profile carries the
@@ -368,15 +516,219 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
     if (migrateGlobalLauncher()) {
         process.stderr.write('dsh-tui: global launcher aligned to the delegating shim (no manual npm i -g needed anymore).\n');
     }
-    const restartCode = await runProcess(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
-        env: {
-            ...process.env,
-            // Dual-write the resume contract (issue #120): the cordis layer of a
-            // still-old TUI build reads only DSH_CC_RESUME_SESSION.
-            DSH_TUI_RESUME_SESSION: sessionId,
-            DSH_CC_RESUME_SESSION: sessionId,
-            [UPDATED_FROM_ENV]: updatedFrom,
-        },
+    return { code: 0, updatedFrom, installed: installedTuiVersion() };
+}
+/**
+ * Update the installed dsh-tui package and restart the same launcher while
+ * preserving the active session. The TUI must already be unmounted before
+ * this is called so pnpm output cannot corrupt the rendered terminal frame.
+ *
+ * When the preflight registry check resolved an exact target, pass that
+ * version to pnpm instead of resolving `latest` a second time. This avoids a
+ * stale mirror/dist-tag response between the check and install. If preflight
+ * failed, retain the `--latest` fallback: a plain `pnpm update` stays inside
+ * the manifest range and can restart unchanged across minor releases.
+ *
+ * @param sessionId - Session to resume in the replacement process.
+ * @param profile - The dsh profile this TUI was launched with; updating any
+ *   other profile would leave the running install untouched.
+ * @param targetVersion - Exact version returned by the preflight registry
+ *   check, or undefined when that check failed and pnpm should resolve latest.
+ * @returns Exit codes for the update run and the replacement process.
+ */
+export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
+    const outcome = await updateTui(profile, targetVersion);
+    const { updatedFrom } = outcome;
+    if (outcome.code !== 0)
+        return { updateCode: outcome.code, restartCode: outcome.code };
+    // Restart through the same hardened handoff as /restart (issues
+    // #284/#307/#483): wait for the replacement's natural exit (the outer
+    // interpreter must not reclaim the console under it), re-assert the
+    // stdin detach from a watchdog so a revived pump cannot swallow the
+    // child's keypresses, and capture a fast-death stderr report. The old
+    // plain inherit spawn raced the interpreter for input on Windows
+    // Terminal (issue #483: "cannot type anything after /update").
+    const restartCode = await restartTui(sessionId, {
+        env: { [UPDATED_FROM_ENV]: updatedFrom },
+        kind: 'update',
+    });
+    return { updateCode: 0, restartCode };
+}
+/**
+ * Headless `dsh-tui update`: the `/update` decision flow (preflight, deadlock
+ * refusal, mirror-lag note, `--latest` fallback) followed by the install-only
+ * half — no TUI, no restart. The bin launcher dynamic-imports this from the
+ * profile copy's compiled lib.
+ *
+ * @param profile - The dsh profile to update.
+ * @returns Process exit code: 0 on success or already-latest, 1 otherwise.
+ */
+export async function cliUpdate(profile) {
+    const target = await resolveTuiUpdateTarget();
+    if (target.kind === 'latest') {
+        process.stdout.write(`dsh-tui: already the latest version (${target.current}).\n`);
+        return 0;
+    }
+    let targetVersion;
+    if (target.kind === 'update') {
+        // Mirror the /update flow exactly: refuse the 0.7.0–0.7.1 hard-inject
+        // range (permanent boot deadlock under older launcher patches, #183/#307)
+        // instead of installing it.
+        if (isBootDeadlockTarget(target.latest)) {
+            process.stderr.write(`dsh-tui: refusing to update onto ${target.latest} — that range can permanently deadlock boot ` +
+                `(#183/#307). Latest on the official registry: ${target.authoritative ?? target.latest}. ` +
+                `If you use a mirror, retry after it syncs.\n`);
+            return 1;
+        }
+        if (target.authoritative !== undefined) {
+            process.stdout.write(`dsh-tui: note — your registry serves ${target.latest} while npmjs.org has ${target.authoritative} (mirror lag).\n`);
+        }
+        targetVersion = target.latest;
+        process.stdout.write(`dsh-tui: updating ${target.current} → ${target.latest}…\n`);
+    }
+    else {
+        process.stdout.write('dsh-tui: version check failed (offline or unreadable install) — falling back to `--latest`.\n');
+    }
+    const outcome = await updateTui(profile, targetVersion);
+    if (outcome.code === 0) {
+        // A preflight-less run (`--latest` fallback) can "succeed" as a pnpm
+        // no-op: same manifest before and after. Say so instead of printing a
+        // vacuous `updated X → X` — the /update path surfaces the same state via
+        // the DSH_TUI_UPDATED_FROM stamp on restart.
+        if (targetVersion === undefined && outcome.installed !== undefined && outcome.installed === outcome.updatedFrom) {
+            process.stdout.write(`dsh-tui: version did not advance (still ${outcome.installed}) — already the latest, or the registry has no newer release yet.\n`);
+        }
+        else {
+            process.stdout.write(`dsh-tui: updated ${outcome.updatedFrom || '(unknown)'} → ${outcome.installed ?? '(unreadable)'}.\n`);
+        }
+    }
+    return outcome.code;
+}
+export async function restartTui(sessionId, options = {}) {
+    const kind = options.kind ?? 'restart';
+    const tag = kind === 'update' ? 'update-restart' : 'restart';
+    const argv = [...process.execArgv, ...process.argv.slice(1)];
+    logRestartEvent(`${tag}: spawning replacement`, {
+        node: process.execPath,
+        argv,
+        cwd: process.cwd(),
+        stdinTty: process.stdin.isTTY === true,
+        stdoutTty: process.stdout.isTTY === true,
+        stderrTty: process.stderr.isTTY === true,
+        nodeOptions: process.env.NODE_OPTIONS ?? null,
+        dshHome: process.env.DSH_HOME ?? null,
+    });
+    const startedAt = Date.now();
+    return new Promise(resolve => {
+        const child = spawn(process.execPath, argv, {
+            env: {
+                ...process.env,
+                // Dual-write the resume contract (issue #120): the cordis layer of a
+                // still-old TUI build reads only DSH_CC_RESUME_SESSION.
+                DSH_TUI_RESUME_SESSION: sessionId,
+                DSH_CC_RESUME_SESSION: sessionId,
+                // Marks the replacement so its own boot logs to restart.log without
+                // noisy logging on every ordinary launch (/restart only).
+                ...(kind === 'restart' ? { [RESTART_CHILD_ENV]: '1' } : {}),
+                ...options.env,
+            },
+            // stdin/stdout stay inherited so the replacement owns the console the
+            // moment it boots; stderr is captured so a boot failure is reportable
+            // through THIS process (the terminal may already be mid-handoff when
+            // the child dies, and a raw inherit write can vanish).
+            stdio: ['inherit', 'inherit', 'pipe'],
+        });
+        logRestartEvent(`${tag}: replacement spawned`, { childPid: child.pid });
+        // Handoff watchdog (field evidence 2026-08-24: restarted TUI mounts but
+        // takes no input). Two jobs, both diagnosis-grade:
+        // 1. SAMPLE this process's stdin state every second — if anything
+        //    re-attaches a reader after the funnel's detachStdinForHandoff, the
+        //    sample (taken before the re-assert below) shows it in the log.
+        // 2. RE-ASSERT the detach and finally destroy the stream: this process
+        //    must never read the shared console again — every keypress belongs
+        //    to the replacement, and a resumed pump here is exactly the
+        //    "restarted TUI sees dropped or swallowed input" failure (#284/#307).
+        let watchdogTicks = 0;
+        const watchdog = setInterval(() => {
+            watchdogTicks += 1;
+            const stdin = process.stdin;
+            logRestartEvent('parent: stdin watchdog', {
+                tick: watchdogTicks,
+                readableListeners: stdin.listenerCount('readable'),
+                dataListeners: stdin.listenerCount('data'),
+                paused: stdin.isPaused,
+                raw: stdin.isRaw === true,
+                buffered: stdin.readableLength,
+            });
+            try {
+                stdin.removeAllListeners('readable');
+                stdin.removeAllListeners('data');
+                stdin.pause();
+            }
+            catch {
+                // Diagnosis/mitigation only.
+            }
+            if (watchdogTicks === 15) {
+                clearInterval(watchdog);
+                try {
+                    // Terminal safeguard: a destroyed stream can never be resumed by
+                    // any late re-attachment. The child holds its own inherited
+                    // handle, so closing ours does not affect it.
+                    process.stdin.destroy();
+                    logRestartEvent('parent: stdin destroyed after watchdog');
+                }
+                catch {
+                    // Best effort.
+                }
+            }
+        }, 1000);
+        watchdog.unref();
+        let childStderr = '';
+        let loggedStderrBytes = 0;
+        child.stderr?.on('data', (chunk) => {
+            childStderr += chunk.toString('utf8');
+            // Mirror chunks to the log capped: the full text still reaches the
+            // terminal report below, and unbounded output must not grow the file.
+            if (loggedStderrBytes < 4096) {
+                loggedStderrBytes += chunk.length;
+                logRestartEvent(`${tag}: replacement stderr`, { text: chunk.toString('utf8').slice(0, 2048) });
+            }
+        });
+        // Diagnosis marker only — never resolves: after the window the child owns
+        // the terminal, and this process must keep the launch chain open until
+        // the replacement exits (see the header comment).
+        const timer = setTimeout(() => {
+            logRestartEvent(`${tag}: survival window passed, following the replacement until it exits`);
+        }, 4000);
+        timer.unref();
+        child.once('error', error => {
+            clearTimeout(timer);
+            logRestartEvent(`${tag}: spawn error`, { message: error.message });
+            writeHandoffNotice(`dsh-tui: failed to spawn the restart: ${error.message}\n`);
+            resolve(127);
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            const elapsedMs = Date.now() - startedAt;
+            logRestartEvent(`${tag}: replacement exited`, {
+                code: code ?? null,
+                signal: signal ?? null,
+                elapsedMs,
+            });
+            if (elapsedMs < 4000) {
+                // Fast death: the TUI never came up. Synchronous stderr write —
+                // process.exit() right after an async stream write skips the flush,
+                // and a vanished diagnosis is indistinguishable from silent failure.
+                const suffix = childStderr.trim() === '' ? '' : `\n${childStderr.trimEnd()}`;
+                writeHandoffNotice(`dsh-tui: restart child exited during the handoff (code ${code ?? 'null'}` +
+                    `${signal === undefined || signal === null ? '' : `, signal ${signal}`}) — the TUI did not come up.` +
+                    `${suffix}\nYour session is preserved; resume with the launcher or retry the command.\n`);
+            }
+            else if (code !== 0 && code !== null) {
+                // Late nonzero exit: the session ended abnormally, say so briefly.
+                writeHandoffNotice(`\ndsh-tui: the restarted session exited with code ${code}.\n`);
+            }
+            resolve(code ?? 1);
+        });
     });
-    return { updateCode, restartCode };
 }

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

@@ -5,4 +5,14 @@
  * @param fields - Optional JSON-serialized fields appended to the line.
  */
 export declare function logForDebugging(message: string, fields?: Record<string, unknown>): void;
+/**
+ * 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 declare function logMouseDebug(message: string, fields?: Record<string, unknown>): void;
 //# sourceMappingURL=debug.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIvF"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../src/utils/debug.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASrF"}

package/lib/types/utils/debug.js

@@ -1,3 +1,6 @@
+import { appendFileSync } from 'node:fs';
+import { DATA_DIR } from './paths.js';
+import { join } from 'node:path';
 /**
  * Debug logger for the ported Ink core. Writes to stderr only when
  * `DSH_TUI_DEBUG` is set, so normal runs stay quiet.
@@ -10,3 +13,24 @@ export function logForDebugging(message, fields) {
     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`;
+        appendFileSync(join(DATA_DIR, 'mouse-debug.log'), line);
+    }
+    catch {
+        // ignore — see doc comment
+    }
+}

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

@@ -0,0 +1,46 @@
+/** Our custom OSC 8 scheme carrying a raw display path (URI-encoded). */
+export declare const FILE_LINK_SCHEME = "dsh-file:";
+/** Encode a display path into a `dsh-file:` link URL. */
+export declare function fileLinkUrl(path: string): string;
+/**
+ * Decode a `dsh-file:` link URL back to the raw display path. Returns
+ * undefined for anything that is not a well-formed dsh-file URL.
+ */
+export declare function parseFileLinkUrl(url: string): string | undefined;
+/**
+ * Resolve a target (raw display path) against the session's base directory:
+ * absolute paths and `~` pass through (with ~ expanded), everything else is
+ * joined onto the base. Pure, so it is unit-testable without a workspace.
+ */
+export declare function resolveTargetPath(path: string, baseDir: string): string;
+/**
+ * Convert a `file://` URL to a local path. Wraps node:url.fileURLToPath —
+ * undefined when the URL is not a valid file URL.
+ */
+export declare function fileUrlToPath(url: string): string | undefined;
+/**
+ * Conservative heuristic: does this text look like a file path worth
+ * making clickable? Requires a slash separator, no whitespace, no URL/email
+ * shape, and either a path anchor (`./`, `../`, `/`, `~/`, drive letter)
+ * with a real path shape (another separator or an extension — a bare
+ * anchored word like `/a` or `x.com/a` is too ambiguous), or a plausible
+ * file extension. Length-capped so huge tokens (base64, logs) never get
+ * linked.
+ */
+export declare function looksLikeFilePath(text: string): boolean;
+/**
+ * Best-effort existence hint: does `path` exist on disk? Used to decide
+ * whether to render a path as clickable in contexts where the raw text is
+ * ambiguous; never throws.
+ */
+export declare function pathExistsOnDisk(path: string): boolean;
+/**
+ * Replace every path-looking span in `text` via `wrap(path, display)`.
+ * Trailing sentence punctuation stays OUTSIDE the wrapped display (so
+ * "src/foo.ts." links `src/foo.ts` and keeps the period). Spans that fail
+ * `looksLikeFilePath` are returned unchanged.
+ * @param text - plain text to scan (no ANSI).
+ * @param wrap - builds the clickable rendering for one path.
+ */
+export declare function linkifyFilePaths(text: string, wrap: (path: string, display: string) => string): string;
+//# sourceMappingURL=fileTarget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fileTarget.d.ts","sourceRoot":"","sources":["../../../src/utils/fileTarget.ts"],"names":[],"mappings":"AAuBA,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,cAAc,CAAA;AAE3C,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM7D;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMtD;AAWD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAC9C,MAAM,CAcR"}