tui-cap 0.1.0

package/dist/paths.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CAPTURE_PREFIX = void 0;
+exports.capturesDir = capturesDir;
+exports.isExplicitPath = isExplicitPath;
+exports.resolveOut = resolveOut;
+exports.resolveInput = resolveInput;
+exports.nextCaptureName = nextCaptureName;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Default base name for captures recorded without an explicit `-o`. */
+exports.DEFAULT_CAPTURE_PREFIX = 'copilot-capture';
+/**
+ * The folder where captures and exports live by default, so files land in one
+ * place regardless of which repo you run from: `$GHCP_CAPTURE_DIR`, or
+ * `~/captures` when that isn't set.
+ */
+function capturesDir() {
+    const fromEnv = process.env.GHCP_CAPTURE_DIR;
+    if (fromEnv && fromEnv.trim() !== '')
+        return fromEnv;
+    return node_path_1.default.join(node_os_1.default.homedir(), 'captures');
+}
+/**
+ * True when a name is an explicit location the user clearly meant to be
+ * relative to the current directory — an absolute path or one containing a path
+ * separator — rather than a bare filename destined for the captures folder.
+ */
+function isExplicitPath(name) {
+    return node_path_1.default.isAbsolute(name) || name.includes('/') || name.includes(node_path_1.default.sep);
+}
+/**
+ * Resolve an output path so captures land in one place regardless of the repo
+ * you run from. A bare filename (or an omitted value) goes in the captures
+ * folder; a value containing a path separator (or an absolute path) is kept
+ * as-is, relative to the current working directory.
+ */
+function resolveOut(value, defaultName) {
+    const name = value ?? defaultName;
+    if (isExplicitPath(name))
+        return name;
+    return node_path_1.default.join(capturesDir(), name);
+}
+/**
+ * Resolve an input path. An explicit path (absolute or containing a separator)
+ * is used as-is. A bare filename is looked up in the current directory first,
+ * then in the captures folder, so `render shot.ans` finds a capture recorded
+ * with `record -o shot.ans` regardless of where you run it.
+ */
+async function resolveInput(value) {
+    if (isExplicitPath(value))
+        return value;
+    try {
+        await (0, promises_1.stat)(value);
+        return value;
+    }
+    catch {
+        // not in the current directory
+    }
+    const inCaptures = node_path_1.default.join(capturesDir(), value);
+    try {
+        await (0, promises_1.stat)(inCaptures);
+        return inCaptures;
+    }
+    catch {
+        // fall through so readFile reports a clear error for the original name
+    }
+    return value;
+}
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The next un-taken auto name in the captures folder — `copilot-capture_01.ans`,
+ * `copilot-capture_02.ans`, and so on. Used when `record` runs without an
+ * explicit `-o` so repeated captures don't clobber a single fixed filename.
+ * Scans the folder and picks the lowest free index (2-digit zero-padded).
+ */
+async function nextCaptureName(prefix = exports.DEFAULT_CAPTURE_PREFIX, ext = '.ans') {
+    const used = new Set();
+    const re = new RegExp(`^${escapeRegExp(prefix)}_(\\d+)${escapeRegExp(ext)}$`, 'i');
+    try {
+        for (const entry of await (0, promises_1.readdir)(capturesDir())) {
+            const match = entry.match(re);
+            if (match)
+                used.add(Number.parseInt(match[1], 10));
+        }
+    }
+    catch {
+        // captures folder doesn't exist yet → start at 1
+    }
+    let n = 1;
+    while (used.has(n))
+        n += 1;
+    return `${prefix}_${String(n).padStart(2, '0')}${ext}`;
+}

package/dist/record-pty.js

@@ -0,0 +1,148 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordSessionPty = recordSessionPty;
+const node_fs_1 = require("node:fs");
+const meta_1 = require("./meta");
+const timing_1 = require("./timing");
+const input_1 = require("./input");
+/**
+ * Opt-in capture backend built on `node-pty`. Unlike the default `script`
+ * wrapper, node-pty lets us own the PTY directly: we set its size, stream raw
+ * bytes straight to the output file, and record the dimensions together with the
+ * bytes — no reliance on the system `script` arg quirks.
+ *
+ * `node-pty` is an OPTIONAL native dependency (it needs a compile step), so it's
+ * imported lazily through a variable specifier; tsc won't require it to be
+ * installed, and a missing install yields a clear, actionable error.
+ */
+async function recordSessionPty(command, outFile, opts = {}) {
+    if (command.length === 0) {
+        throw new Error('record: no command provided (use `-- <command...>`)');
+    }
+    // A variable specifier keeps tsc from resolving (and thus requiring) the
+    // optional native module at build time.
+    const moduleName = 'node-pty';
+    let pty;
+    try {
+        pty = await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+    }
+    catch {
+        throw new Error('The pty backend needs the optional `node-pty` dependency.\n' +
+            '  Install it with:  npm install node-pty\n' +
+            '  Then re-run with: --backend pty\n' +
+            '(node-pty is native; the default `script` backend needs no build step.)');
+    }
+    const { cols, rows } = (0, meta_1.terminalSize)();
+    const [file, ...args] = command;
+    const out = (0, node_fs_1.createWriteStream)(outFile);
+    // One shared clock for both sidecars so keystroke times line up with the
+    // frame appearance times derived from the timing checkpoints.
+    const startMs = Date.now();
+    const tracker = new timing_1.TimingTracker(startMs);
+    const captureInput = opts.input !== false && Boolean(process.stdin.isTTY);
+    const inputTracker = captureInput ? new input_1.InputTracker(startMs) : null;
+    const child = pty.spawn(file, args, {
+        name: process.env.TERM ?? 'xterm-256color',
+        cols,
+        rows,
+        cwd: process.cwd(),
+        env: process.env,
+    });
+    // Tee the child's output to both the file (raw, for replay) and our stdout
+    // (so the user sees the live session while it records), timestamping each
+    // chunk so the timing sidecar can map byte offsets back to wall-clock time.
+    child.onData((data) => {
+        tracker.mark(Buffer.byteLength(data, 'utf8'));
+        out.write(data);
+        process.stdout.write(data);
+    });
+    const isTTY = Boolean(process.stdin.isTTY);
+    // Record a printable-count of each keystroke burst before forwarding it, so
+    // the parser can tell which output frames were produced by user typing.
+    const onStdin = (d) => {
+        inputTracker?.mark(d);
+        child.write(d.toString('utf8'));
+    };
+    if (isTTY) {
+        process.stdin.setRawMode?.(true);
+        process.stdin.resume();
+        process.stdin.on('data', onStdin);
+    }
+    const onResize = () => {
+        const s = (0, meta_1.terminalSize)();
+        try {
+            child.resize(s.cols, s.rows);
+        }
+        catch {
+            /* child may have exited */
+        }
+    };
+    process.stdout.on('resize', onResize);
+    return new Promise((resolve) => {
+        child.onExit(({ exitCode }) => {
+            if (isTTY) {
+                process.stdin.setRawMode?.(false);
+                process.stdin.pause();
+                process.stdin.off('data', onStdin);
+            }
+            process.stdout.off('resize', onResize);
+            const finish = () => resolve(exitCode ?? 0);
+            if (opts.meta === false) {
+                out.end(finish);
+                return;
+            }
+            // Flush the capture file before writing sidecars so they describe the
+            // complete stream and a reader sees the full `.ans`.
+            out.end(() => {
+                const capturedAt = new Date().toISOString();
+                const sidecars = [
+                    (0, meta_1.writeMeta)(outFile, {
+                        schemaVersion: meta_1.META_SCHEMA_VERSION,
+                        cols,
+                        rows,
+                        capturedAt,
+                        command: command.join(' '),
+                    }),
+                    (0, timing_1.writeTiming)(outFile, tracker.build()),
+                ];
+                if (inputTracker && inputTracker.length > 0) {
+                    sidecars.push((0, input_1.writeInput)(outFile, inputTracker.build()));
+                }
+                Promise.all(sidecars).then(finish, finish); // sidecars are best-effort
+            });
+        });
+    });
+}

package/dist/record.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordSession = recordSession;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
+const meta_1 = require("./meta");
+const timing_1 = require("./timing");
+/**
+ * Record a live program's raw terminal output (escape codes intact) to a file
+ * using the system `script` utility, which allocates a real PTY so the target
+ * still behaves like it's attached to a terminal.
+ *
+ * Rather than let `script` write the capture file directly, we point its own
+ * output at `/dev/null` and **pipe its stdout** to ourselves: every chunk is
+ * timestamped (for the timing sidecar that powers animation), written to the
+ * `.ans` file, and echoed to our stdout so the live session is still visible.
+ * Capturing the bytes ourselves keeps the `.ans` offsets and the timing
+ * checkpoints perfectly aligned. The child still sees a genuine PTY from
+ * `script`, sized from the controlling terminal.
+ *
+ * The PTY dimensions are written to a `<out>.meta.json` sidecar (so `render`
+ * replays at the recorded size) and the chunk timing to `<out>.timing.json`.
+ *
+ * The resulting `.ans` file can be replayed with `parseAnsiToGrid`.
+ */
+function recordSession(command, outFile, opts = {}) {
+    if (command.length === 0) {
+        throw new Error('record: no command provided (use `-- <command...>`)');
+    }
+    // Snapshot the terminal size now: `script` sizes the child PTY to the current
+    // controlling terminal, so this matches the dimensions the program renders at.
+    const { cols, rows } = (0, meta_1.terminalSize)();
+    // Send `script`'s own typescript to the bit bucket — we capture the session
+    // from its stdout instead (see above). The platforms differ only in flag shape.
+    const sink = '/dev/null';
+    let bin;
+    let args;
+    if (node_os_1.default.platform() === 'darwin') {
+        // BSD/macOS: script [-q] file [command ...]
+        bin = 'script';
+        args = ['-q', sink, ...command];
+    }
+    else {
+        // util-linux: script -q -e -c "<cmd>" file
+        bin = 'script';
+        args = ['-q', '-e', '-c', command.join(' '), sink];
+    }
+    return new Promise((resolve, reject) => {
+        const out = (0, node_fs_1.createWriteStream)(outFile);
+        const tracker = new timing_1.TimingTracker();
+        // Inherit stdin only when we're attached to a real TTY (interactive
+        // recording, where a human drives the program). For non-interactive
+        // captures (piped stdin, or commands like `copilot -p "..."` that exit on
+        // their own), inheriting a non-TTY pipe makes `script` abort before running
+        // the command, so fall back to /dev/null via 'ignore'.
+        //
+        // NB: `script` requires its stdin to be the controlling terminal — it calls
+        // tcgetattr on stdin and aborts ("Operation not supported on socket") if
+        // handed a pipe. So we never pipe its stdin, which means the `script`
+        // backend can't tee keystrokes. Keystroke capture (the `.input.json`
+        // sidecar that powers precise typing correlation) lives in the node-pty
+        // backend instead; the `script` backend still gets typing detection via the
+        // parser's content-growth fallback.
+        const stdin = process.stdin.isTTY ? 'inherit' : 'ignore';
+        const child = (0, node_child_process_1.spawn)(bin, args, { stdio: [stdin, 'pipe', 'inherit'] });
+        child.stdout.on('data', (chunk) => {
+            tracker.mark(chunk.length);
+            out.write(chunk);
+            process.stdout.write(chunk);
+        });
+        child.on('error', reject);
+        child.on('exit', (code) => {
+            // Flush the capture file before writing sidecars / resolving so callers
+            // (and tests) that read it immediately see the full stream.
+            out.end(() => {
+                const finish = () => resolve(code ?? 0);
+                if (opts.meta === false) {
+                    finish();
+                    return;
+                }
+                const capturedAt = new Date().toISOString();
+                const sidecars = [
+                    (0, meta_1.writeMeta)(outFile, {
+                        schemaVersion: meta_1.META_SCHEMA_VERSION,
+                        cols,
+                        rows,
+                        capturedAt,
+                        command: command.join(' '),
+                    }),
+                    (0, timing_1.writeTiming)(outFile, tracker.build()),
+                ];
+                Promise.all(sidecars).then(finish, finish); // sidecars are best-effort
+            });
+        });
+    });
+}