termcut 1.0.2 → 1.0.3

package/README.md

@@ -19,14 +19,14 @@ Or a standalone binary for macOS, Linux or Windows from [Releases](https://githu
 
 ## Record
 
-**Live.** Your shell opens — your prompt, config and aliases; type; `exit`. You get the video, the exact recording (`demo.cast`) and an editable script of what you typed (`demo.video.ts`). `--clean` opens a plain shell with a `>` prompt instead.
+**Live.** Your own shell opens — prompt, config, aliases; type; `exit`. You get the video, the exact recording (`demo.cast`) and an editable script of what you typed (`demo.video.ts`): it reopens your shell (`shell: "user"`), waits for your prompt (`promptPattern`, detected from the recording) and replays the commands as `run()` calls. `--clean` opens a plain shell with a `>` prompt instead.
 
 ```sh
 tcut rec -o demo.gif
 tcut rec -o demo.mp4 -- npm create vite     # one command, ends when it exits
 ```
 
-`-- command` runs through that same shell, so `tcut rec -- ls` records what *your* `ls` shows — aliases, functions and colours included. `--raw` runs the binary directly.
+`-- command` runs through that same shell, so `tcut rec -- ls` records what *your* `ls` shows — aliases, functions, fish abbreviations and colours included. `--raw` runs the binary directly.
 
 **Scripted.** Plain TypeScript, so loops, helpers and imports work, and the script lives in the repo next to the code it shows.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",

package/src/cli.ts

@@ -6,6 +6,7 @@ import { readCast, writeCast } from "./cast";
 import { applyOverrides, resolveConfig } from "./config";
 import * as api from "./index";
 import { recordLive } from "./live";
+import { detectPromptPattern } from "./promptguess";
 import { throughShell, userShell } from "./usershell";
 import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig, type Published } from "./publish";
 import { diffCasts, type DiffResult } from "./diff";
@@ -71,8 +72,8 @@ Options (override the script's config):
       --gap <dur>          concat: still time between parts
       --preset <name>      readme | x | youtube | square
       --browser <url>      rec: record a browser window too (--browser-position right|left|top|bottom|overlay)
-      --raw                rec: run the command directly instead of through your shell (no aliases/functions)
-      --clean              rec: open tcut's clean shell (plain > prompt, no personal config) instead of yours
+      --clean              rec: a clean shell with a plain > prompt instead of your own (also: run -- command bare)
+      --raw                rec: run -- command as a bare binary, not through your shell (no aliases/functions)
       --at <seconds>       diff: compare the screen at this time instead of the end
       --images <dir>       diff: also write a.png / b.png
       --cast <path>        where to read/write the .cast
@@ -475,26 +476,28 @@ async function main(): Promise<void> {
       const overrides = overridesFromFlags();
       const rawOutputs = overrides.output ?? ["rec.mp4"];
       const outputs = Array.isArray(rawOutputs) ? rawOutputs : [rawOutputs];
-      const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast });
-      // The shell tcut was typed into: `-- cmd` runs through it (aliases, functions, colours) unless --raw;
-      // with no command it IS the session — your prompt and config — unless --clean or an explicit --shell.
-      const clean = Boolean(values.clean) || overrides.shell !== undefined;
-      const shell = (rest.length > 0 ? !values.raw : !clean) ? userShell() : null;
+      // The shell tcut was typed into is the session (your prompt, config, aliases) and what `-- cmd` runs
+      // through. --clean / --raw opt out: a plain shell with a `>` prompt, or the bare binary.
+      const shell = values.clean || values.raw ? null : userShell();
+      const config = resolveConfig({ ...overrides, output: outputs, cast: overrides.cast, ...(rest.length === 0 && shell && { shell: "user" }) });
       let command: string[] | undefined;
-      let interactive = false;
+      let portable: string[] | undefined;
       if (rest.length > 0) {
-        command = shell ? throughShell(rest, shell) : rest;
-        if (shell) log(dim(`  via ${shell.name} — your aliases and functions apply (--raw to run the binary directly)`));
+        if (shell) {
+          const through = throughShell(rest, shell);
+          command = through.argv;
+          portable = through.portable;
+          log(dim(`  via ${shell.name} — your aliases and functions apply (--raw runs the binary directly)`));
+        } else {
+          command = rest;
+        }
       } else if (shell) {
-        command = [shell.path, "-il"];
-        interactive = true;
         log(dim(`  your ${shell.name}, with its config (--clean for a plain shell with a > prompt)`));
       }
       // Size: --cols/--rows if given, else derived from --width/--height, else the terminal tcut runs in.
       const sized = overrides.width !== undefined || overrides.height !== undefined;
       const recording = await recordLive(config, {
         command,
-        interactive,
         describe: rest.length > 0 ? rest.join(" ") : shell ? `your ${shell.name}` : undefined,
         log,
         cols: overrides.cols ?? (sized ? config.cols : undefined),
@@ -508,7 +511,9 @@ async function main(): Promise<void> {
       ok(`wrote ${config.cast}`, `${recording.events.length} events, ${(recording.header.duration ?? 0).toFixed(1)}s`);
       if (!values["no-script"]) {
         const scriptPath = config.cast.replace(/\.cast$/, "") + ".video.ts";
-        await Bun.write(scriptPath, generateScript(recording, { output: outputs, cleanShell: !command, command, castPath: config.cast }));
+        // A session in the user's own shell replays with run(): wait for whatever their prompt ends with.
+        const promptPattern = !command && config.shell === "user" ? ((await detectPromptPattern(recording, config.core)) ?? undefined) : undefined;
+        await Bun.write(scriptPath, generateScript(recording, { output: outputs, cleanShell: !command, command: portable ?? command, castPath: config.cast, promptPattern }));
         ok(`wrote ${scriptPath}`, "editable script — tweak it, then `tcut " + scriptPath + "`");
       }
       if (values["record-only"]) {

package/src/config.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { USER_PROMPT_PATTERN } from "./promptguess";
 import { toMs } from "./duration";
 import { applyPreset } from "./presets";
 import { resolveTheme } from "./themes";
@@ -83,7 +84,7 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     cast: config.cast ?? castDefault,
     shell: config.shell ?? "bash",
     prompt,
-    promptPattern: (config.promptPattern ?? defaultPromptPattern(prompt)).source,
+    promptPattern: (config.promptPattern ?? (config.shell === "user" ? new RegExp(USER_PROMPT_PATTERN) : defaultPromptPattern(prompt))).source,
     cwd: config.cwd ?? process.cwd(),
     env: config.env ?? {},
     cols: cols ?? 80,

package/src/live.ts

@@ -1,6 +1,7 @@
 import { startBrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { shellSetup } from "./recorder";
+import { CURSOR_QUERY, hasCursorReport, stripTerminalReplies } from "./replies";
 import type { CastEvent, Recording, ResolvedConfig } from "./types";
 
 /** What live recording needs from a keystroke source: `process.stdin`, or any readable stream (a PassThrough in tests). */
@@ -26,8 +27,6 @@ export interface LiveOptions {
   log?: (message: string) => void;
   /** How to name the command in status lines (defaults to the argv). */
   describe?: string;
-  /** The command is a shell the user types into (ends on `exit`), not a program that runs and exits. */
-  interactive?: boolean;
 }
 
 /**
@@ -44,10 +43,11 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   const events: CastEvent[] = [];
   const startedAt = performance.now();
 
-  const stamp = (): number => {
-    const t = (performance.now() - startedAt) / 1000;
-    return config.quantize ? Math.ceil(t * config.fps - 1e-6) / config.fps : Number(t.toFixed(6));
-  };
+  const stampAt = (seconds: number): number => (config.quantize ? Math.ceil(seconds * config.fps - 1e-6) / config.fps : Number(seconds.toFixed(6)));
+  const elapsed = (): number => (performance.now() - startedAt) / 1000;
+  const stamp = (): number => stampAt(elapsed());
+  // The program asked where the cursor is: the next position report on stdin is the terminal's answer, not a key.
+  let cursorQueried = false;
   const push = (type: CastEvent[1], data: string): void => {
     events.push([stamp(), type, data]);
   };
@@ -76,6 +76,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
       data(_terminal, chunk) {
         const text = decoder.decode(chunk, { stream: true });
         if (!text) return;
+        if (text.includes(CURSOR_QUERY)) cursorQueried = true;
         stdout.write(chunk);
         push("o", text);
       },
@@ -92,7 +93,12 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
   const onData = (chunk: Buffer | string): void => {
     if (exited || terminal.closed) return;
     terminal.write(chunk);
-    push("i", chunk instanceof Uint8Array ? chunk.toString("utf8") : chunk);
+    // Everything goes to the program, but only keystrokes are recorded: the terminal's answers to its queries
+    // would otherwise show up as key chips and be typed back on replay.
+    const text = chunk instanceof Uint8Array ? chunk.toString("utf8") : chunk;
+    const keys = stripTerminalReplies(text, { cursorQueried });
+    if (cursorQueried && hasCursorReport(text)) cursorQueried = false;
+    if (keys) push("i", keys);
   };
   const onResize = (): void => {
     const c = process.stdout.columns ?? cols;
@@ -108,13 +114,13 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     stdin.on("data", onData);
   }
   process.on("SIGWINCH", onResize);
-  log(`recording ${opts.describe ?? setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command && !opts.interactive ? "ends when the command exits" : "type exit to stop"}`);
+  log(`recording ${opts.describe ?? setup.cmd.join(" ")} at ${cols}×${rows} — ${opts.command ? "ends when the command exits" : "type exit to stop"}`);
 
   try {
     await Promise.race([exitedPromise, proc.exited]);
     // Hold the final screen for `endPause`, like a scripted recording does — otherwise a command that exits in
     // 20 ms (`tcut rec -- ls`) becomes a three-frame video. The timeline is virtual: stamp it, don't sleep.
-    events.push([Number((stamp() + config.endPause / 1000).toFixed(6)), "m", MARKER.end]);
+    events.push([stampAt(elapsed() + config.endPause / 1000), "m", MARKER.end]);
   } finally {
     await browser?.stop();
     const emitter: NodeJS.EventEmitter = process; // @types/bun's process.off() lacks the signal overload; the generic emitter has it

package/src/promptguess.ts

@@ -0,0 +1,34 @@
+import { loadCore } from "./screen";
+import type { Recording } from "./types";
+
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Prompts end in a symbol: what a generated script waits for when the user's own shell is recorded. */
+export const USER_PROMPT_PATTERN = "[❯>$%#»➜λ]\\s*$";
+
+/**
+ * What the user's prompt ends with, read from the recording: the text up to the cursor just before the first
+ * keystroke is the prompt; its final symbol (`❯`, `$`, `%`, …) is what `run()` should wait for. Replaying through
+ * the headless core handles right-hand prompts and cursor movement that a plain text scan would misread.
+ */
+export async function detectPromptPattern(rec: Recording, core: "ghostty" | "lite" = "ghostty"): Promise<string | null> {
+  const firstInput = rec.events.findIndex((e) => e[1] === "i");
+  const before = (firstInput < 0 ? rec.events : rec.events.slice(0, firstInput)).filter((e) => e[1] === "o");
+  if (before.length === 0) return null;
+  const term = await loadCore(core);
+  term.init(rec.header.width, rec.header.height);
+  for (const e of before) term.writeString(e[2]);
+  const { row, col } = term.getCursor();
+  let line = "";
+  for (let x = 0; x < col; x++) {
+    const cell = term.getCell(row, x);
+    if (cell.width === 0) continue;
+    line += cell.chars ?? (cell.char === 0 ? " " : String.fromCodePoint(cell.char));
+  }
+  const trimmed = line.trimEnd();
+  if (!trimmed) return null;
+  const ender = [...trimmed].at(-1)!;
+  // A letter or digit is not a prompt symbol (a bare path, say); fall back to the generic pattern.
+  if (/[\p{L}\p{N}]/u.test(ender)) return null;
+  return `${escapeRegExp(ender)}\\s*$`;
+}

package/src/recorder.ts

@@ -1,4 +1,5 @@
 import { MarkdownRenderer } from "@wterm/markdown";
+import { userShell } from "./usershell";
 import { startBrowserCapture, type BrowserCapture } from "./browser";
 import { MARKER } from "./cast";
 import { toMs } from "./duration";
@@ -45,6 +46,13 @@ export function shellSetup(config: ResolvedConfig): ShellSetup {
   const { shell, prompt } = config;
   if (Array.isArray(shell)) return { cmd: shell, env: {} };
   switch (shell) {
+    case "user": {
+      // The user's own shell, interactive + login, so its config, prompt and aliases apply. No known shell
+      // (Windows, or tcut launched from something that is not bash/zsh/fish) → the clean bash below.
+      const own = userShell();
+      if (own) return { cmd: [own.path, "-il"], env: {} };
+      return shellSetup({ ...config, shell: "bash" });
+    }
     case "bash":
       return {
         cmd: ["bash", "--norc", "--noprofile"],

package/src/replies.ts

@@ -0,0 +1,37 @@
+// Answers a terminal sends to a program's queries — device attributes, kitty keyboard flags, colours via OSC,
+// XTGETTCAP via DCS, cursor position reports. In a live recording they arrive on stdin together with the
+// user's keystrokes, but they are not keystrokes: the key overlay must not show them and a replay must not
+// type them (tcut answers the queries itself then).
+
+const ESC = String.fromCharCode(0x1b);
+const BEL = String.fromCharCode(0x07);
+
+const REPLIES = new RegExp(
+  [
+    `${ESC}\\[\\?[\\d;]*[cu]`, // primary DA, kitty keyboard flags
+    `${ESC}\\[>[\\d;]*c`, // secondary DA
+    `${ESC}\\][\\d;]*[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, // OSC (colour queries)
+    `${ESC}P[^${ESC}]*${ESC}\\\\`, // DCS (XTGETTCAP)
+  ].join("|"),
+  "g",
+);
+
+/** Cursor position report `ESC [ row ; col R` — the same bytes as a modified F3 key (`ESC [ 1 ; 2-8 R`). */
+const CPR = new RegExp(`${ESC}\\[\\d+;\\d+R`, "g");
+/** A CPR whose parameters cannot be a modifier-encoded F3: row other than 1, or a "modifier" outside 2–8. */
+const UNAMBIGUOUS_CPR = new RegExp(`${ESC}\\[(?!1;[2-8]R)\\d+;\\d+R`, "g");
+
+/** The program asked for the cursor position; the next CPR-shaped input is an answer, not a key. */
+export const CURSOR_QUERY = `${ESC}[6n`;
+
+export interface StripOptions {
+  /** The program asked `ESC[6n`, so any CPR in this chunk is a reply; without it, only unambiguous reports are removed. */
+  cursorQueried?: boolean;
+}
+
+export function stripTerminalReplies(input: string, opts: StripOptions = {}): string {
+  return input.replace(REPLIES, "").replace(opts.cursorQueried ? CPR : UNAMBIGUOUS_CPR, "");
+}
+
+/** Does this input chunk carry a cursor position report (or the look-alike modified F3)? */
+export const hasCursorReport = (input: string): boolean => new RegExp(CPR.source).test(input);

package/src/scriptgen.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { stripTerminalReplies } from "./replies";
 import { keySequence } from "./keys";
 import type { Recording } from "./types";
 
@@ -9,6 +10,8 @@ export interface ScriptGenOptions {
   cleanShell: boolean;
   /** The command that was recorded in `-- command` mode (becomes `shell: [...]`). */
   command?: string[];
+  /** Regex source `run()` should wait for — detected from the user's prompt when their own shell was recorded. */
+  promptPattern?: string;
   /** Gaps between keystrokes longer than this become `sleep()` calls. Default 400 ms. */
   pauseThresholdMs?: number;
   /** Where the cast lives, for the header comment. */
@@ -128,24 +131,6 @@ function formatMs(ms: number): string {
 
 const q = (s: string) => JSON.stringify(s);
 
-/**
- * Answers the terminal sent to the program's queries (device attributes, kitty keyboard, colours via OSC,
- * XTGETTCAP via DCS, cursor position). They arrive on stdin and get recorded as input, but they are not
- * keystrokes: when a script replays, tcut answers the queries itself.
- */
-const ESC = String.fromCharCode(0x1b);
-const BEL = String.fromCharCode(0x07);
-const TERMINAL_REPLIES = new RegExp(
-  [
-    `${ESC}\\[\\?[\\d;]*[cu]`, // primary DA, kitty keyboard flags
-    `${ESC}\\[>[\\d;]*c`, // secondary DA
-    `${ESC}\\][\\d;]*[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, // OSC (colour queries)
-    `${ESC}P[^${ESC}]*${ESC}\\\\`, // DCS (XTGETTCAP)
-    `${ESC}\\[\\d+;\\d+R`, // cursor position report
-  ].join("|"),
-  "g",
-);
-export const stripTerminalReplies = (input: string): string => input.replace(TERMINAL_REPLIES, "");
 
 /** Turn the `i` (input) events of a recording into a list of script operations. */
 export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
@@ -259,6 +244,7 @@ export function generateScript(rec: Recording, opts: ScriptGenOptions): string {
   const config: string[] = [`output: ${JSON.stringify(opts.output)}`];
   if (opts.command) config.push(`shell: ${JSON.stringify(opts.command)}`);
   else if (cfg && cfg.shell !== "bash") config.push(`shell: ${JSON.stringify(cfg.shell)}`);
+  if (opts.promptPattern) config.push(`promptPattern: /${opts.promptPattern.replace(/\//g, "\\/")}/`);
   config.push(`cols: ${rec.header.width}`, `rows: ${rec.header.height}`);
   if (cfg) {
     if (cfg.theme?.name) config.push(`theme: ${q(cfg.theme.name)}`);
@@ -271,7 +257,9 @@ export function generateScript(rec: Recording, opts: ScriptGenOptions): string {
   const castNote = opts.castPath ? ` The exact recording is in ${path.basename(opts.castPath)}.` : "";
   const modeNote = opts.command
     ? "It opens the same program and replays your keys; waits are the pauses you took, so adjust them if it is slower elsewhere."
-    : "Typed commands became run(), which waits for the prompt instead of guessing.";
+    : cfg?.shell === "user"
+      ? "It opens your own shell; typed commands became run(), which waits for your prompt (promptPattern) instead of guessing."
+      : "Typed commands became run(), which waits for the prompt instead of guessing.";
 
   return `import { defineVideo } from "tcut";
 

package/src/types.ts

@@ -29,7 +29,8 @@ export interface Theme {
  */
 export type ThemeName = "catppuccin-mocha" | "dracula" | "github-dark" | "tokyo-night" | "one-dark" | (string & {});
 
-export type ShellName = "bash" | "zsh" | "fish" | "sh";
+/** `user` is the shell tcut was launched from (interactive login, with its config); the others are clean shells with the configured prompt. */
+export type ShellName = "bash" | "zsh" | "fish" | "sh" | "user";
 /** Terminal emulator core: libghostty (full VT, answers queries) or wterm's lite Zig core (faster, fewer features). */
 export type CoreName = "ghostty" | "lite";
 export type WindowBar = "none" | "colorful" | "colorfulRight" | "rings" | "ringsRight";

package/src/usershell.ts

@@ -1,33 +1,64 @@
 import path from "node:path";
 
-// `tcut rec -- ls` should record what the user sees when they type `ls`: their shell's alias, function or
-// abbreviation, with their colour settings. Running the bare binary gives none of that ("Executable not
-// found" for an alias, plain output for a coloured one). So the command goes through the shell tcut was
-// launched from, interactively, the way the user's own terminal runs it.
+// `tcut rec` should record what the user sees in their own terminal: their shell, with its prompt, aliases,
+// functions, abbreviations and colour settings. Running the bare binary or a clean shell gives none of that
+// ("Executable not found" for an alias, plain output for a coloured one).
 
 export interface UserShell {
   path: string;
-  /** bash | zsh | fish — the shells whose `-ic <command>` form loads the interactive config. */
+  /** bash | zsh | fish — the shells whose `-ic <command>` / `-il` forms load the interactive config. */
   name: string;
 }
 
 const INTERACTIVE_SHELLS = new Set(["bash", "zsh", "fish"]);
 
-/** The process that launched tcut, by executable name (macOS/Linux `ps`). Null when that cannot be read. */
-function parentCommand(): string | null {
+interface ParentProcess {
+  /** Executable as reported by `ps -o comm=` (login shells show a leading dash: "-fish"). */
+  command: string;
+  /** Full command line as reported by `ps -o args=`. */
+  args: string;
+}
+
+/** The process that launched tcut (macOS/Linux `ps`). Null when that cannot be read. */
+function parentProcess(): ParentProcess | null {
+  const field = (name: string): string => Bun.spawnSync(["ps", "-o", `${name}=`, "-p", String(process.ppid)], { env: process.env }).stdout.toString().trim();
   try {
-    const r = Bun.spawnSync(["ps", "-o", "comm=", "-p", String(process.ppid)]);
-    const comm = r.stdout.toString().trim().replace(/^-/, ""); // login shells report as "-fish"
-    return comm || null;
+    const command = field("comm");
+    if (!command) return null;
+    return { command, args: field("args") };
   } catch {
     return null;
   }
 }
 
-/** The shell the user typed tcut into, falling back to $SHELL. Null on Windows or when neither is a known shell. */
+/**
+ * Is this shell invocation the user's interactive session, rather than a script runner? A shell running a
+ * script (`bash run.sh`) or a one-liner (`bash -c …`) is not the shell the user lives in — its rc files and
+ * aliases are the wrong ones — so only flag-only invocations (`fish`, `-zsh`, `/bin/bash -il`) count.
+ */
+export function isInteractiveInvocation(comm: string, args: string): boolean {
+  if (comm.startsWith("-")) return true; // login shell
+  const words = args.split(/\s+/).filter(Boolean);
+  const rest = words[0] && !words[0].startsWith("-") ? words.slice(1) : words; // drop argv[0] if present
+  for (const w of rest) {
+    if (w === "-c" || !w.startsWith("-")) return false;
+  }
+  return true;
+}
+
+/**
+ * The shell the user typed tcut into: the parent process when it is an interactive bash/zsh/fish, else $SHELL.
+ * Null on Windows or when neither is a known shell.
+ */
 export function userShell(): UserShell | null {
   if (process.platform === "win32") return null;
-  const candidates = [parentCommand(), process.env.SHELL].filter((c): c is string => Boolean(c));
+  const candidates: string[] = [];
+  const parent = parentProcess();
+  if (parent) {
+    const comm = parent.command.replace(/^-/, "");
+    if (INTERACTIVE_SHELLS.has(path.basename(comm)) && isInteractiveInvocation(parent.command, parent.args)) candidates.push(comm);
+  }
+  if (process.env.SHELL) candidates.push(process.env.SHELL);
   for (const candidate of candidates) {
     const name = path.basename(candidate);
     if (!INTERACTIVE_SHELLS.has(name)) continue;
@@ -37,22 +68,118 @@ export function userShell(): UserShell | null {
   return null;
 }
 
-/** Join argv into one command line; single quotes are understood the same way by bash, zsh and fish. */
-export function shellQuote(args: string[]): string {
-  return args.map((a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`)).join(" ");
+/** One argument, single-quoted for the given shell. POSIX shells take everything literally; fish reads `\'` and `\\`. */
+export function quoteArg(arg: string, shellName: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)) return arg;
+  const inner = shellName === "fish" ? arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'") : arg.replace(/'/g, `'\\''`);
+  return `'${inner}'`;
+}
+
+export function shellQuote(args: string[], shellName: string): string {
+  return args.map((a) => quoteArg(a, shellName)).join(" ");
+}
+
+export interface FishAbbreviation {
+  name: string;
+  expansion: string;
 }
 
-/** fish abbreviations expand only at the prompt, not in `fish -c`; expand a leading one ourselves. */
+/** Fish's own quoting, as `abbr --show` prints it: bare, '…' (escapes \' \\) or "…" (escapes \" \\ \$). */
+function fishTokens(line: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let quote: "'" | '"' | null = null;
+  let inWord = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]!;
+    if (quote) {
+      if (ch === "\\" && i + 1 < line.length) {
+        const next = line[i + 1]!;
+        const escapable = quote === "'" ? "\\'" : '\\"$';
+        if (escapable.includes(next)) {
+          cur += next;
+          i++;
+          continue;
+        }
+      }
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (inWord) out.push(cur);
+      cur = "";
+      inWord = false;
+      continue;
+    }
+    cur += ch;
+    inWord = true;
+  }
+  if (inWord) out.push(cur);
+  return out;
+}
+
+/**
+ * One `abbr --show` line → the abbreviation it declares, or null for the kinds that cannot be expanded up
+ * front (regex names, function-computed expansions, anywhere-position). `--set-cursor` markers are removed.
+ */
+export function parseAbbrLine(line: string): FishAbbreviation | null {
+  const tokens = fishTokens(line.trim());
+  if (tokens[0] !== "abbr") return null;
+  let cursorMarker: string | null = null;
+  let i = 1;
+  for (; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (t === "--") {
+      i++;
+      break;
+    }
+    if (t === "-a" || t === "--add" || t === "-g" || t === "--global" || t === "-U" || t === "--universal") continue;
+    if (t === "--regex" || t === "--function" || t === "-f" || t === "--command") return null;
+    if (t === "--position") {
+      if (tokens[i + 1] !== "command") return null;
+      i++;
+      continue;
+    }
+    if (t.startsWith("--position=")) {
+      if (t !== "--position=command") return null;
+      continue;
+    }
+    if (t === "--set-cursor") {
+      cursorMarker = "%";
+      continue;
+    }
+    if (t.startsWith("--set-cursor=")) {
+      cursorMarker = t.slice("--set-cursor=".length) || "%";
+      continue;
+    }
+    if (t.startsWith("--regex=") || t.startsWith("--function=") || t.startsWith("--command=")) return null;
+    if (t.startsWith("-")) continue; // unknown flag: ignore
+    break; // name without a `--` separator (older fish)
+  }
+  const name = tokens[i];
+  const expansion = tokens[i + 1];
+  if (!name || expansion === undefined) return null;
+  return { name, expansion: cursorMarker ? expansion.split(cursorMarker).join("") : expansion };
+}
+
+/**
+ * fish abbreviations expand only at the prompt, never in `fish -c`; expand a leading one ourselves. The list is
+ * read from an interactive fish, because the stock config.fish declares them inside `if status is-interactive`.
+ */
 export function fishAbbreviation(shell: UserShell, word: string): string | null {
   if (shell.name !== "fish") return null;
   try {
-    const r = Bun.spawnSync([shell.path, "-c", "abbr --show"]);
+    // env is passed explicitly: Bun.spawnSync otherwise uses the environment as it was at startup.
+    const r = Bun.spawnSync([shell.path, "-ic", "abbr --show"], { stdin: "ignore", env: process.env });
     for (const line of r.stdout.toString().split("\n")) {
-      // `abbr -a -- lzg lazygit` (options may precede `--`; the expansion may be quoted)
-      const m = /^abbr .*-- (\S+) (.+)$/.exec(line.trim());
-      if (!m || m[1] !== word) continue;
-      const expansion = m[2]!;
-      return expansion.startsWith("'") && expansion.endsWith("'") ? expansion.slice(1, -1).replace(/\\'/g, "'") : expansion;
+      const abbr = parseAbbrLine(line);
+      if (abbr && abbr.name === word) return abbr.expansion;
     }
   } catch {
     /* no abbreviations available */
@@ -60,10 +187,17 @@ export function fishAbbreviation(shell: UserShell, word: string): string | null
   return null;
 }
 
-/** `args` as the user's shell would run them when typed: interactive, so aliases, functions and abbreviations apply. */
-export function throughShell(args: string[], shell: UserShell): string[] {
+export interface ShellCommand {
+  /** What to spawn. */
+  argv: string[];
+  /** The same command with the shell by name, for scripts that should run on other machines. */
+  portable: string[];
+}
+
+/** `args` the way the user's shell runs them when typed: interactive, so aliases, functions and abbreviations apply. */
+export function throughShell(args: string[], shell: UserShell): ShellCommand {
   const [first, ...rest] = args;
   const expanded = first ? fishAbbreviation(shell, first) : null;
-  const line = expanded ? `${expanded} ${shellQuote(rest)}`.trim() : shellQuote(args);
-  return [shell.path, "-ic", line];
+  const line = expanded ? `${expanded} ${shellQuote(rest, shell.name)}`.trim() : shellQuote(args, shell.name);
+  return { argv: [shell.path, "-ic", line], portable: [shell.name, "-ic", line] };
 }