tui-cap 0.1.0

package/dist/cli.js

@@ -0,0 +1,648 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const parse_1 = require("./parse");
+const paths_1 = require("./paths");
+const svg_1 = require("./svg");
+const edits_1 = require("./edits");
+const record_1 = require("./record");
+const server_1 = require("./server");
+const asciinema_1 = require("./asciinema");
+const meta_1 = require("./meta");
+const fonts_1 = require("./fonts");
+const version_1 = require("./version");
+const HELP = `tui-cap — turn terminal output into editable, branded SVG
+
+USAGE
+  tui-cap gui [options]
+  tui-cap render <input.ans> [options]
+  tui-cap asciinema <input.cast> [options]
+  tui-cap record -o <out.ans> -- <command...>
+  tui-cap update
+  tui-cap --version
+
+GUI
+  Open a local web app to browse your captures library, flip through the frames
+  of a recording, tweak the look, export SVG/PNG, and edit + export a timed MP4
+  animation — no flag-guessing required.
+  tui-cap gui
+      --port <n>         Port to serve on (default: 4787; auto-increments if busy)
+      --no-open          Don't auto-open the browser; just print the URL
+
+RENDER OPTIONS
+  -o, --out <file>       Output SVG path (bare name → captures folder;
+                         otherwise default: <input>.svg)
+      --cols <n>         Replay width in columns (default: capture meta or 120)
+      --rows <n>         Replay height in rows (default: capture meta or 50)
+      --mode <name>      auto | final-frame | full-scroll (default: auto)
+                         auto: final-frame for full-screen TUIs, else full-scroll
+      --max-rows <n>     Cap rows kept in full-scroll (default: 1000)
+      --theme <name>     dark | light (default: dark)
+      --font <stack>     CSS font-family for the text
+      --font-url <src>   Embed a font via @font-face (local file path or URL).
+                         Local files are base64-embedded so the SVG stays
+                         portable; matching --font names the @font-face family.
+      --embed-font       Force embedding a local --font-url (default: on).
+                         Use --no-embed-font to reference the path instead.
+      --font-size <px>   Font size in px (default: 14)
+      --advance <ratio>  Column advance as a fraction of font size (default: 0.618164).
+                         Auto-set from --font when it's a known monospace family.
+      --line-height <r>  Line height as a fraction of font size (default: 1.25)
+      --padding <px>     Padding around the text (default: 24)
+      --title <text>     Window title (default: "GitHub Copilot CLI")
+      --no-chrome        Omit the window frame / title bar
+      --chrome-style <os>  Title-bar layout: mac | mac-inactive | windows | windows-inactive (default: mac)
+      --radius <px>      Window corner radius (default: 20 mac / 7 windows)
+
+FRAME SELECTION
+  A full-screen TUI (like the Copilot CLI) paints into the alternate screen and
+  wipes it on exit, so the capture holds many frames — one per paint cycle. By
+  default render picks the settled full-screen frame the TUI held on, skipping
+  the exit teardown and never the blank post-exit screen.
+      --frame <n>        Render frame n (1-based; -1 = last, -2 = second-last)
+      --list-frames      List the captured frames and exit (writes no SVG)
+      --all-frames       Write every frame as <out>-01.svg, <out>-02.svg, …
+
+  If a sibling <input>.meta.json sidecar exists (written by 'record'), its
+  cols/rows are used automatically unless --cols/--rows are given.
+
+CONTENT EDITS
+  Recolours, rewrites, and spacing tweaks made in the GUI are saved to a sibling
+  <input>.edits.json sidecar. render applies them automatically (when the saved
+  capture size still matches), so CLI exports match the GUI.
+      --no-edits         Ignore the .edits.json sidecar and render the raw capture
+
+RECORD OPTIONS
+  -o, --out <file>       Output .ans path (bare name → captures folder)
+      --backend <name>   auto | script | pty (default: auto). auto uses the
+                         node-pty backend for interactive keystroke capture when
+                         node-pty is installed, and falls back to the system
+                         script backend if it isn't (or can't start a PTY).
+                         Only the pty backend writes the <out>.input.json
+                         keystroke sidecar; script relies on the parser's
+                         content-based typing detection.
+      --no-meta          Don't write the <out>.meta.json size + .timing.json
+                         sidecars (timing powers the GUI animation export)
+      --no-input         Don't record keystrokes to the <out>.input.json sidecar
+                         (keystroke timing powers the typing cursor + smoothing)
+      --no-gui           Don't auto-launch the GUI when the recording finishes
+      --gui-port <n>     Port for the auto-launched GUI (default: ${server_1.DEFAULT_GUI_PORT})
+
+  When a recording finishes, the GUI is opened automatically so you can scrub
+  frames and export SVG right away. If a GUI is already listening on the port
+  it's reused instead of starting a second server. Use --no-gui to opt out.
+
+ASCIINEMA OPTIONS
+  -o, --out <file>       Output SVG path (default: <input>.svg)
+      --at <seconds>     Render the frame at this time (default: end of cast)
+      Cols/rows come from the cast header (and resize events); all RENDER
+      OPTIONS above also apply.
+
+UPDATING
+  tui-cap checks npm for a newer release each time the GUI launches and shows a
+  banner with an "Update now" button. You can also update from the terminal:
+  tui-cap update            Upgrade a global install to the latest published
+                            version (runs npm install -g tui-cap@latest). Run
+                            via npx? It always fetches the latest, so just re-run
+                            npx tui-cap@latest.
+  tui-cap --version         Print the installed version and exit.
+
+OUTPUT LOCATION
+  Omit -o or pass a bare filename (no slash) and the file is written to your
+  captures folder: $GHCP_CAPTURE_DIR, or ~/captures by default. Pass a path
+  containing a slash (./shot.ans, /tmp/x.ans) to write relative to the current
+  directory instead.
+
+EXAMPLES
+  tui-cap gui                                    # browse + export in the browser
+  tui-cap record -o shot.ans -- copilot
+  tui-cap render shot.ans -o shot.svg --theme dark
+  tui-cap render shot.ans --list-frames          # inspect captured frames
+  tui-cap render shot.ans -o f.svg --frame -2    # the second-to-last frame
+  tui-cap asciinema demo.cast -o demo.svg --at 4.2
+  # then drag the .svg into Figma or Illustrator — text stays editable
+`;
+function parseArgs(args) {
+    const positionals = [];
+    const flags = {};
+    const short = { o: 'out', h: 'help' };
+    // A leading '-' usually marks the next flag, but a negative number (e.g.
+    // `--frame -2`) is a value, not a flag.
+    const isValue = (s) => s !== undefined && (!s.startsWith('-') || /^-\d/.test(s));
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--') {
+            positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            if (key.startsWith('no-')) {
+                flags[key.slice(3)] = false;
+                continue;
+            }
+            const next = args[i + 1];
+            if (!isValue(next))
+                flags[key] = true;
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else if (a.startsWith('-') && a.length === 2) {
+            const key = short[a[1]] ?? a[1];
+            const next = args[i + 1];
+            if (!isValue(next))
+                flags[key] = true;
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags };
+}
+function num(value, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : fallback;
+}
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Resolve `--mode` / `--max-rows` shared by the render and asciinema commands. */
+function parseModeFlags(flags) {
+    const validModes = ['auto', 'final-frame', 'full-scroll'];
+    const modeFlag = str(flags.mode);
+    let mode = 'auto';
+    if (modeFlag !== undefined) {
+        if (validModes.includes(modeFlag)) {
+            mode = modeFlag;
+        }
+        else {
+            console.error(`Unknown --mode "${modeFlag}"; using auto. Valid: ${validModes.join(', ')}.`);
+        }
+    }
+    const maxRows = flags['max-rows'] !== undefined ? num(flags['max-rows'], 1000) : undefined;
+    return { mode, maxRows };
+}
+/**
+ * Build RenderOptions from the shared render flags. Throws on an unreadable
+ * `--font-url` so the caller can surface a clear error and exit non-zero.
+ */
+function resolveRenderOptions(flags, themeName) {
+    const overrides = {};
+    if (flags.chrome === false)
+        overrides.chrome = false;
+    const chromeStyle = str(flags['chrome-style']);
+    if (chromeStyle === 'windows' ||
+        chromeStyle === 'windows-inactive' ||
+        chromeStyle === 'mac' ||
+        chromeStyle === 'mac-inactive')
+        overrides.chromeStyle = chromeStyle;
+    if (str(flags.title) !== undefined)
+        overrides.title = str(flags.title);
+    if (str(flags.font) !== undefined)
+        overrides.fontFamily = str(flags.font);
+    if (flags['font-size'] !== undefined)
+        overrides.fontSize = num(flags['font-size'], 14);
+    if (flags.advance !== undefined)
+        overrides.advance = num(flags.advance, 0.618164);
+    if (flags['line-height'] !== undefined)
+        overrides.lineHeight = num(flags['line-height'], 1.25);
+    if (flags.padding !== undefined)
+        overrides.padding = num(flags.padding, 24);
+    if (flags.radius !== undefined)
+        overrides.radius = num(flags.radius, 20);
+    const opts = (0, svg_1.defaultRenderOptions)(themeName, overrides);
+    // Auto-tune the column advance for known monospace fonts, unless the user
+    // pinned it explicitly with --advance.
+    if (str(flags.font) !== undefined && flags.advance === undefined) {
+        const auto = (0, fonts_1.advanceForFont)(opts.fontFamily);
+        if (auto !== undefined)
+            opts.advance = auto;
+    }
+    // Embed a font face when requested so non-Figma targets resolve exact metrics.
+    const fontUrl = str(flags['font-url']);
+    if (fontUrl !== undefined) {
+        const embed = flags['embed-font'] !== false;
+        try {
+            opts.fontFace = (0, fonts_1.buildFontFaceCss)((0, fonts_1.primaryFamily)(opts.fontFamily), fontUrl, { embed });
+        }
+        catch (err) {
+            throw new Error(`Could not read font for --font-url "${fontUrl}": ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    return opts;
+}
+/**
+ * Load the content edits that apply to a render, mirroring the server's
+ * `applicableEdits`: none when `--no-edits` is set or the sidecar is missing,
+ * and none (with a warning) when the saved capture size no longer matches —
+ * so stale anchors are never smeared across a re-recorded capture.
+ */
+async function loadRenderEdits(input, cols, rows, flags) {
+    if (flags.edits === false)
+        return [];
+    const doc = await (0, edits_1.readEdits)(input);
+    if (!doc || doc.edits.length === 0)
+        return [];
+    if (!(0, edits_1.fingerprintMatches)(doc, { ansMtime: 0, cols, rows })) {
+        const n = doc.edits.length;
+        console.error(`Skipping ${n} saved content edit${n === 1 ? '' : 's'}: they were made for a ` +
+            `different capture size. Re-open the recording in the GUI to refresh them, ` +
+            `or pass --no-edits to silence this.`);
+        return [];
+    }
+    return doc.edits;
+}
+async function runRender(args) {
+    const { positionals, flags } = parseArgs(args);
+    const inputArg = positionals[0];
+    if (!inputArg) {
+        console.error('render: missing input file\n');
+        console.log(HELP);
+        process.exitCode = 1;
+        return;
+    }
+    const input = await (0, paths_1.resolveInput)(inputArg);
+    const data = await (0, promises_1.readFile)(input);
+    // Default the replay size to the recorded PTY size when a sidecar is present,
+    // so --cols/--rows become optional. Explicit flags still win.
+    const meta = await (0, meta_1.readMeta)(input);
+    const cols = num(flags.cols, meta?.cols ?? 120);
+    const rows = num(flags.rows, meta?.rows ?? 50);
+    if (meta && flags.cols === undefined && flags.rows === undefined) {
+        console.error(`Using capture size ${cols}×${rows} from ${node_path_1.default.basename((0, meta_1.metaPathFor)(input))}`);
+    }
+    const themeName = str(flags.theme) === 'light' ? 'light' : 'dark';
+    // Content edits saved by the GUI live in a sibling .edits.json sidecar. Apply
+    // them through the same pure Grid→Grid transform the server uses, so non-GUI
+    // exports match the preview. `--no-edits` opts out; a size mismatch (re-record)
+    // is skipped with a warning rather than smeared across new content.
+    const edits = await loadRenderEdits(input, cols, rows, flags);
+    const applyEdits = (grid) => (edits.length ? (0, edits_1.toDisplayGrid)(grid, edits) : grid);
+    let opts;
+    try {
+        opts = resolveRenderOptions(flags, themeName);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    const out = (0, paths_1.resolveOut)(str(flags.out), node_path_1.default.basename(input, node_path_1.default.extname(input)) + '.svg');
+    await (0, promises_1.mkdir)(node_path_1.default.dirname(out), { recursive: true });
+    // Two rendering models share this command:
+    //  • Scrollback model (--mode / --max-rows): one tall grid via parseAnsiToGrid,
+    //    preserving scrolled history for plain (non-alt-screen) output.
+    //  • Frame model (default): discrete frames via extractFrames, capturing the
+    //    live alt-screen frames of a TUI (the Copilot CLI) and powering --frame /
+    //    --list-frames / --all-frames and the GUI scrubber.
+    if (flags.mode !== undefined || flags['max-rows'] !== undefined) {
+        const { mode, maxRows } = parseModeFlags(flags);
+        const grid = await (0, parse_1.parseAnsiToGrid)(data, { cols, rows, theme: themeName, mode, maxRows });
+        await (0, promises_1.writeFile)(out, (0, svg_1.renderSvg)(applyEdits(grid), opts), 'utf8');
+        console.error(`Wrote ${out}`);
+        return;
+    }
+    const frames = await (0, parse_1.extractFrames)(data, {
+        cols,
+        rows,
+        theme: themeName,
+    });
+    if (flags['list-frames'] === true) {
+        console.error(`${frames.length} frame${frames.length === 1 ? '' : 's'} captured:`);
+        frames.forEach((f, i) => {
+            const tag = f.inAlt ? 'full-screen' : 'normal     ';
+            console.error(`  ${String(i + 1).padStart(3)}  ${tag}  ${(0, parse_1.framePreview)(f.grid)}`);
+        });
+        console.error('\nRender one with  --frame <n>,  or every frame with  --all-frames.');
+        return;
+    }
+    if (flags['all-frames'] === true) {
+        const ext = node_path_1.default.extname(out) || '.svg';
+        const stem = out.slice(0, out.length - ext.length);
+        const pad = String(frames.length).length;
+        for (let i = 0; i < frames.length; i++) {
+            const file = `${stem}-${String(i + 1).padStart(pad, '0')}${ext}`;
+            await (0, promises_1.writeFile)(file, (0, svg_1.renderSvg)((0, parse_1.trimBackgroundBleed)(applyEdits(frames[i].grid)), opts), 'utf8');
+            console.error(`Wrote ${file}`);
+        }
+        return;
+    }
+    const which = flags.frame !== undefined ? num(flags.frame, 0) : undefined;
+    const { grid, index } = (0, parse_1.chooseFrame)(frames, which);
+    await (0, promises_1.writeFile)(out, (0, svg_1.renderSvg)((0, parse_1.trimBackgroundBleed)(applyEdits(grid)), opts), 'utf8');
+    const suffix = frames.length > 1 ? `  (frame ${index + 1} of ${frames.length})` : '';
+    console.error(`Wrote ${out}${suffix}`);
+}
+async function runAsciinema(args) {
+    const { positionals, flags } = parseArgs(args);
+    const input = positionals[0];
+    if (!input) {
+        console.error('asciinema: missing input .cast file\n');
+        console.log(HELP);
+        process.exitCode = 1;
+        return;
+    }
+    const raw = await (0, promises_1.readFile)(input, 'utf8');
+    const at = flags.at !== undefined ? num(flags.at, NaN) : undefined;
+    if (at !== undefined && !Number.isFinite(at)) {
+        console.error(`asciinema: --at must be a number (seconds), got "${str(flags.at)}"`);
+        process.exitCode = 1;
+        return;
+    }
+    let frame;
+    try {
+        frame = (0, asciinema_1.extractFrame)(raw, at);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    // The cast header (and any resize events) carry the terminal size, so
+    // --cols/--rows are optional here too but still win when provided.
+    const cols = num(flags.cols, frame.cols);
+    const rows = num(flags.rows, frame.rows);
+    const themeName = str(flags.theme) === 'light' ? 'light' : 'dark';
+    const { mode, maxRows } = parseModeFlags(flags);
+    const grid = await (0, parse_1.parseAnsiToGrid)(Buffer.from(frame.ansi, 'utf8'), {
+        cols,
+        rows,
+        theme: themeName,
+        mode,
+        maxRows,
+    });
+    let opts;
+    try {
+        opts = resolveRenderOptions(flags, themeName);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    const svg = (0, svg_1.renderSvg)(grid, opts);
+    const out = str(flags.out) ??
+        node_path_1.default.join(node_path_1.default.dirname(input), node_path_1.default.basename(input, node_path_1.default.extname(input)) + '.svg');
+    await (0, promises_1.writeFile)(out, svg, 'utf8');
+    console.error(`Wrote ${out} (frame at ${at ?? 'end'}, ${cols}×${rows})`);
+}
+async function hasNodePty() {
+    // node-pty is an optional native dependency, loaded via a variable specifier
+    // so tsc/bundlers don't hard-require it. A successful import means it built.
+    const moduleName = 'node-pty';
+    try {
+        await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pick the record backend. An explicit `--backend script|pty` always wins.
+ * Otherwise (`auto`, the default) prefer node-pty for interactive keystroke
+ * capture — the `script` backend can't tee stdin (it requires the controlling
+ * TTY) — and fall back to `script` when node-pty isn't installed or there are
+ * no keystrokes to capture (non-interactive / `--no-input`).
+ */
+async function resolveRecordBackend(requested, wantInput) {
+    if (requested === 'pty')
+        return 'pty';
+    if (requested === 'script')
+        return 'script';
+    if (wantInput && Boolean(process.stdin.isTTY) && (await hasNodePty()))
+        return 'pty';
+    return 'script';
+}
+async function runRecord(args) {
+    const { positionals, flags } = parseArgs(args);
+    if (positionals.length === 0) {
+        console.error('record: provide a command after `--`, e.g. `record -o shot.ans -- copilot`\n');
+        process.exitCode = 1;
+        return;
+    }
+    const outFlag = str(flags.out);
+    const defaultName = outFlag === undefined ? await (0, paths_1.nextCaptureName)() : 'capture.ans';
+    const out = (0, paths_1.resolveOut)(outFlag, defaultName);
+    await (0, promises_1.mkdir)(node_path_1.default.dirname(out), { recursive: true });
+    const requested = str(flags.backend);
+    const explicitPty = requested === 'pty';
+    const backend = await resolveRecordBackend(requested, flags.input !== false);
+    const recordOpts = { meta: flags.meta !== false, input: flags.input !== false };
+    try {
+        let code;
+        if (backend === 'pty') {
+            try {
+                console.error(`Recording to ${out} via pty — exit the program to finish.`);
+                const { recordSessionPty } = await Promise.resolve().then(() => __importStar(require('./record-pty')));
+                code = await recordSessionPty(positionals, out, recordOpts);
+            }
+            catch (ptyErr) {
+                // An explicit `--backend pty` should surface the failure; an
+                // auto-selected pty (node-pty present but unable to start a PTY in this
+                // environment) falls back to `script` so recording still works.
+                if (explicitPty)
+                    throw ptyErr;
+                const why = ptyErr instanceof Error ? ptyErr.message.split('\n')[0] : String(ptyErr);
+                console.error(`  pty backend couldn't start (${why}); falling back to script.`);
+                console.error(`Recording to ${out} via script — exit the program to finish.`);
+                code = await (0, record_1.recordSession)(positionals, out, recordOpts);
+            }
+        }
+        else {
+            console.error(`Recording to ${out} via script — exit the program to finish.`);
+            code = await (0, record_1.recordSession)(positionals, out, recordOpts);
+        }
+        console.error(`\nSaved ${out}.`);
+        process.exitCode = code;
+        await maybeLaunchGui(flags);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    }
+}
+/**
+ * After a recording finishes, make the GUI available so the capture can be
+ * scrubbed and exported immediately. Reuses an already-running server (detected
+ * by a quick port probe) so repeated recordings don't spawn duplicates, and
+ * otherwise launches `gui` as a detached child that outlives this process.
+ * Opt out with --no-gui; choose the port with --gui-port.
+ */
+async function maybeLaunchGui(flags) {
+    if (flags.gui === false)
+        return;
+    const host = '127.0.0.1';
+    const port = flags['gui-port'] !== undefined ? num(flags['gui-port'], server_1.DEFAULT_GUI_PORT) : server_1.DEFAULT_GUI_PORT;
+    const url = `http://${host}:${port}`;
+    if (await (0, server_1.isPortInUse)(port, host)) {
+        console.error(`  GUI already running → ${url}  (open it to view this capture)`);
+        return;
+    }
+    // Re-exec ourselves as a detached `gui` process so the server keeps running
+    // after this record command exits and frees the terminal. The child opens the
+    // browser once it has bound, avoiding a race on the port.
+    let child;
+    try {
+        child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'gui', '--port', String(port)], {
+            detached: true,
+            stdio: 'ignore',
+        });
+    }
+    catch (err) {
+        console.error(`  Could not launch GUI: ${err instanceof Error ? err.message : err}`);
+        console.error(`  Start it yourself with:  tui-cap gui`);
+        return;
+    }
+    child.on('error', () => {
+        /* surfaced via the waitForPort check below */
+    });
+    child.unref();
+    const up = await (0, server_1.waitForPort)(port, host);
+    if (up)
+        console.error(`  Launched GUI → ${url}`);
+    else
+        console.error(`  Starting GUI at ${url} … (give it a moment, then refresh)`);
+}
+async function runGui(args) {
+    const { flags } = parseArgs(args);
+    const port = flags.port !== undefined ? num(flags.port, server_1.DEFAULT_GUI_PORT) : undefined;
+    const open = flags.open !== false;
+    const { url } = await (0, server_1.startServer)({ port, open });
+    console.error(`\n  GHCP Capture GUI  →  ${url}`);
+    console.error(`  Library: ${(0, paths_1.capturesDir)()}`);
+    console.error(`  Press Ctrl+C to stop.\n`);
+    // Surface a newer release without delaying startup; the server is already up.
+    void noteUpdateIfAvailable();
+}
+/**
+ * Fire-and-forget check that prints a one-line note when a newer version is
+ * published. Best-effort: any network/parse failure is swallowed so it never
+ * interferes with the running GUI.
+ */
+async function noteUpdateIfAvailable() {
+    try {
+        const info = await (0, version_1.checkForUpdate)();
+        if (!info.updateAvailable || !info.latest)
+            return;
+        console.error(`  ⬆ Update available: v${info.current} → v${info.latest}. ` +
+            `Run 'tui-cap update' or use the button in the GUI.\n`);
+    }
+    catch {
+        // offline / registry hiccup — stay quiet
+    }
+}
+/**
+ * `tui-cap update` — upgrade a global install to the latest published version.
+ * Skips the work when already current, and points npx users at the re-run they
+ * actually need (there's nothing persistent to upgrade).
+ */
+async function runUpdateCmd() {
+    const current = (0, version_1.currentVersion)();
+    const kind = (0, version_1.installKind)();
+    const latest = await fetchLatestForUpdate();
+    if (latest && !(0, version_1.isNewer)(latest, current)) {
+        console.error(`tui-cap is already up to date (v${current}).`);
+        return;
+    }
+    if (kind === 'npx') {
+        console.error(`You're running tui-cap via npx, which fetches the latest on demand.\n` +
+            `  Re-run:  npx tui-cap@latest`);
+        return;
+    }
+    const target = latest ? `v${latest}` : 'the latest version';
+    console.error(`Updating tui-cap (v${current}) → ${target} …`);
+    console.error(`  ${(0, version_1.updateCommand)()}\n`);
+    const result = await (0, version_1.runSelfUpdate)();
+    if (result.ok) {
+        console.error(`\n✓ Updated to ${target}. Restart any running 'tui-cap gui' to use it.`);
+    }
+    else {
+        console.error(`\n✗ Update failed. Run it yourself:\n  ${(0, version_1.updateCommand)()}`);
+        const tail = result.output.split('\n').filter(Boolean).slice(-6).join('\n');
+        if (tail)
+            console.error(`\n${tail}`);
+        process.exitCode = 1;
+    }
+}
+/** Latest version lookup for the update command, tolerant of being offline. */
+async function fetchLatestForUpdate() {
+    const info = await (0, version_1.checkForUpdate)().catch(() => null);
+    return info?.latest ?? null;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+        console.log((0, version_1.currentVersion)());
+        return;
+    }
+    if (cmd === 'gui')
+        return runGui(argv.slice(1));
+    if (cmd === 'render')
+        return runRender(argv.slice(1));
+    if (cmd === 'asciinema')
+        return runAsciinema(argv.slice(1));
+    if (cmd === 'record')
+        return runRecord(argv.slice(1));
+    if (cmd === 'update')
+        return runUpdateCmd();
+    console.error(`Unknown command: ${cmd}\n`);
+    console.log(HELP);
+    process.exitCode = 1;
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});