@gigaflow/gmux 0.15.0

package/dist/cli/overlay.js

@@ -0,0 +1,149 @@
+/**
+ * Draw every pane's summary card in place. Pure: given resolved cells and the
+ * clock, produce one string of ANSI cursor moves that paints a full-screen
+ * overlay. The command layer supplies the cells and the terminal; nothing here
+ * reads tmux, stdin, or the clock on its own.
+ *
+ * A compact sibling of `formatCard`: same summary fields and section names,
+ * sized to a rectangle with a degradation ladder — full card, then title +
+ * what-landed, then just the title, then a muted placeholder for a pane with no
+ * agent. Monochrome: the structure is carried by layout, so it survives a pane
+ * that cannot render colour.
+ */
+import { relativeAge, truncate, wrapText } from "../core/text.js";
+import { indent, sessionLabel } from "./format.js";
+const CLEAR = "\x1b[2J\x1b[H";
+/**
+ * When the summary last landed, and whether one is regenerating now — shown
+ * together, so a card that says `refreshing…` still tells you how old the summary
+ * you're reading is.
+ */
+function freshnessLine(cell, now) {
+    const summary = cell.view?.summary;
+    const age = summary ? `updated ${relativeAge(summary.generatedAt, now)} ago` : "no summary yet";
+    return cell.refreshing ? `refreshing… · ${age}` : age;
+}
+function section(label, body, width) {
+    if (!body)
+        return [];
+    const wrapped = wrapText(body, Math.max(1, width - 2)).map((l) => indent(l));
+    return [label, ...wrapped, ""];
+}
+function placeholder(cell, width, height) {
+    const lines = ["· no agent here ·"];
+    if (height > 1)
+        lines.push(truncate(cell.pane.command, width));
+    return lines.slice(0, Math.max(1, height));
+}
+/** The normal summary card (title, freshness, the widening-zoom sections). */
+function summaryCard(cell, w, h, now) {
+    const { record, summary } = cell.view;
+    const title = truncate(sessionLabel(record), w);
+    if (h <= 1)
+        return [title];
+    const fresh = freshnessLine(cell, now);
+    const landed = summary?.landed || summary?.headline || record.lastUserPrompt || "";
+    if (h <= 4) {
+        const lines = [title];
+        if (h >= 3)
+            lines.push(...wrapText(landed, w).slice(0, h - 2));
+        lines.push(fresh);
+        return lines.slice(0, h);
+    }
+    const body = [title];
+    if (record.endedMidTask)
+        body.push("⚠ ended mid-task");
+    body.push(fresh, "");
+    if (summary) {
+        body.push(...section("HEADLINE", summary.headline, w));
+        body.push(...section("OVERVIEW", summary.overview, w));
+        body.push(...section("SUMMARY", summary.summary ?? "", w));
+        body.push(...section("RECENT WORK", summary.landed, w));
+        body.push(...section("STILL OPEN", summary.open, w));
+        body.push(...section("NEXT STEP", summary.nextStep, w));
+    }
+    else {
+        body.push("no summary yet — gmux summarize " + record.sessionId.slice(0, 8));
+    }
+    return body.slice(0, h);
+}
+/** The broadcast-answer block appended under the summary: `asking…`, or the answer. */
+function askBlock(cell, w) {
+    return cell.asking ? ["▸ asking…"] : ["▸ answer", ...wrapText(cell.answer ?? "", w).map(indent)];
+}
+export function cellLines(cell, width, height, now) {
+    const w = Math.max(1, Math.floor(width));
+    const h = Math.max(1, Math.floor(height));
+    if (!cell.view)
+        return placeholder(cell, w, h);
+    if (h <= 1)
+        return [truncate(sessionLabel(cell.view.record), w)];
+    // No question in flight: the whole card is the summary.
+    if (!cell.asking && cell.answer == null)
+        return summaryCard(cell, w, h, now);
+    // A broadcast question: keep the summary and APPEND the answer beneath it,
+    // reserving room so both show (the summary is clipped, not swallowed).
+    const ask = askBlock(cell, w);
+    const askRows = Math.min(ask.length, Math.max(1, h - 2)); // always leave the card ≥2 rows
+    const cardRows = Math.max(1, h - askRows - 1); // −1 for the blank separator
+    return [...summaryCard(cell, w, cardRows, now), "", ...ask.slice(0, askRows)].slice(0, h);
+}
+/**
+ * Strip C0 control bytes and DEL — including ESC (0x1b) — from untrusted card
+ * text. Summary fields, prompts and pane commands all originate outside this
+ * process; a stray control byte among them could otherwise move the cursor out
+ * of the pane's rectangle (absolute positioning) or emit an OSC sequence to the
+ * terminal. Replaced with a space rather than dropped, so columns still line up.
+ */
+function sanitize(line) {
+    return line.replace(/[\x00-\x1f\x7f]/g, " ");
+}
+/** Clip one line to `width` display columns (no wrapping — the card already wrapped). */
+function clip(line, width) {
+    const clean = sanitize(line);
+    return clean.length > width ? clean.slice(0, width) : clean;
+}
+/**
+ * A box outline around a pane's rectangle, so adjacent cards read as separate
+ * panes rather than one blur of text. Drawn with box-drawing glyphs at absolute
+ * coordinates; the card content is inset one cell inside it. `left`/`top` are
+ * 0-based (tmux geometry); terminal coordinates are 1-based.
+ */
+function borderBox(left, top, width, height) {
+    const out = [];
+    const inner = "─".repeat(Math.max(0, width - 2));
+    const colLeft = left + 1;
+    const colRight = left + width;
+    const rowTop = top + 1;
+    const rowBottom = top + height;
+    out.push(`\x1b[${rowTop};${colLeft}H┌${inner}┐`);
+    for (let row = rowTop + 1; row <= rowBottom - 1; row++) {
+        out.push(`\x1b[${row};${colLeft}H│`);
+        out.push(`\x1b[${row};${colRight}H│`);
+    }
+    out.push(`\x1b[${rowBottom};${colLeft}H└${inner}┘`);
+    return out;
+}
+export function renderOverlay(cells, now = new Date()) {
+    const out = [CLEAR];
+    for (const cell of cells) {
+        const { left, top, width, height } = cell.pane;
+        // Big enough for a frame with at least a 1×1 interior: draw the border and
+        // inset the card by one cell on every side.
+        if (width >= 3 && height >= 3) {
+            out.push(...borderBox(left, top, width, height));
+            const lines = cellLines(cell, width - 2, height - 2, now);
+            lines.forEach((line, i) => {
+                out.push(`\x1b[${top + 2 + i};${left + 2}H${clip(line, width - 2)}`);
+            });
+            continue;
+        }
+        // Too small to frame — just paint the content at the pane origin.
+        const lines = cellLines(cell, width, height, now);
+        lines.forEach((line, i) => {
+            out.push(`\x1b[${top + i + 1};${left + 1}H${clip(line, width)}`);
+        });
+    }
+    return out.join("");
+}
+//# sourceMappingURL=overlay.js.map

package/dist/cli/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../src/cli/overlay.ts"],"names":[],"mappings":"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"}

package/dist/cli/picker.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Session picker.
+ *
+ * fzf is used when installed — it gives fuzzy matching and a live preview pane
+ * for free. When it is absent we fall back to a numbered prompt rather than
+ * failing: gmux must work on a machine with nothing but Node.
+ *
+ * Rows WRAP rather than being chopped at the right edge, in both modes. In fzf
+ * that needs multi-line items: records are NUL-delimited (`--read0`) so a single
+ * session can span several display lines and still be selected as one thing.
+ * fzf gained multi-line display in 0.46, so older versions fall back to
+ * single-line rows rather than rendering one session as several bogus entries.
+ */
+import type { SessionView } from "../core/types.js";
+import { type InProgress } from "./format.js";
+export declare function hasFzf(): boolean;
+/** fzf's version as [major, minor, patch], or null if it cannot be determined. */
+export declare function fzfVersion(): number[] | null;
+/**
+ * Is `version` at least `want`, comparing component by component?
+ *
+ * A null version — `fzf --version` unreadable — is NOT enough. Every caller
+ * gates a feature on this, and assuming a feature we cannot see makes fzf exit
+ * non-zero at startup for exactly the people we could not probe.
+ *
+ * Missing components read as 0, so a want longer than the version still
+ * decides: [0, 46] is not [0, 46, 1].
+ */
+export declare function atLeast(version: number[] | null, want: readonly number[]): boolean;
+/** True when this fzf can display one item across several lines. */
+export declare function supportsMultiline(version: number[] | null): boolean;
+/** True when this fzf can tell a binding which input mode it is in. */
+export declare function supportsSplitChat(version: number[] | null): boolean;
+/**
+ * Which ask experience this environment gets.
+ *
+ * The tiers below `split` are what shipped before it, and they are load-bearing
+ * rather than politeness: an fzf flag leaked into a tier that does not
+ * understand it does not degrade the picker, it deletes it — fzf exits non-zero
+ * at startup, for exactly the people the fallback exists to protect and for
+ * nobody else. Hence a named ladder with a truth table over it.
+ */
+export type AskTier = 
+/** The chat under the card, in the preview pane. */
+"split"
+/** Today's full-screen `execute` REPL: fzf suspends, the list comes back after. */
+ | "execute"
+/** The numbered fallback's `a` key. No fzf to bind anything in. */
+ | "prompt"
+/** No ask at all — the key is not bound and not advertised. */
+ | "none";
+export declare function askTier(input: {
+    hasFzf: boolean;
+    fzfVersion: number[] | null;
+    askAvailable: boolean;
+    selfCommand: string | null;
+}): AskTier;
+/** How wide the list column is inside fzf, once the preview pane is taken out. */
+export declare function listWidth(width?: number): number;
+/**
+ * The records fed to fzf, NUL-delimited.
+ *
+ * Each record is `<session-id>\t<display>`, where `<display>` may contain
+ * newlines. fzf shows fields 2.. and hands field 1 to the preview command and
+ * back to us on selection, so the id never appears on screen twice and the
+ * mapping back to a session survives wrapping.
+ */
+export declare function buildFzfRecords(views: readonly SessionView[], multiline: boolean, width?: number, now?: Date, inProgress?: InProgress): string;
+/** A freshly loaded list, and what the worker is writing as of that moment. */
+export interface PickRefresh {
+    views: readonly SessionView[];
+    inProgress: InProgress;
+}
+export interface PickOptions {
+    /** argv reproducing this filter set, for fzf's reload binding. */
+    reloadArgs?: readonly string[];
+    /**
+     * Re-load for the no-fzf path, which has no subprocess to shell out to.
+     *
+     * Returns the markers as well as the rows: carrying the `inProgress` set from
+     * open would re-render it stale, showing `○` for a row the worker has since
+     * picked up.
+     */
+    reload?: () => Promise<PickRefresh>;
+    /**
+     * Look up a session id the picker did not open with.
+     *
+     * REQUIRED for ctrl-r to be useful. After a reload, fzf's list contains
+     * sessions that did not exist when we built our id map, and those are exactly
+     * the ones you refreshed in order to find.
+     */
+    resolve?: (id: string) => Promise<SessionView | null>;
+    /** Rows the worker is writing right now, rendered `◐`. */
+    inProgress?: InProgress;
+    /**
+     * argv reproducing this filter set for fzf's ctrl-o binding, or undefined
+     * when ask is unavailable — which leaves the key unbound and unadvertised.
+     *
+     * Carries the filters for the same reason `reloadArgs` does: the child builds
+     * its own window, and a window built from defaults may not contain the
+     * session you are pointing at.
+     */
+    askArgs?: readonly string[];
+    /**
+     * Open the chat layer. `a` in the numbered fallback; ctrl-o in fzf does NOT
+     * come through here — fzf runs its own `execute` binding against this build.
+     *
+     * A callback rather than a direct import, so the picker keeps knowing nothing
+     * about providers.
+     */
+    ask?: () => Promise<void>;
+    /**
+     * The chat pane's opaque strings, or undefined when it cannot be offered.
+     *
+     * Used only on the `split` tier — every other tier ignores it — so a caller can
+     * build it unconditionally and let the fzf version decide.
+     *
+     * Strings in, shell commands out, and that is the whole contract: the picker
+     * never opens the transcript, never learns it is a file, never learns where it
+     * lives, and never learns a provider exists. Exactly as `askArgs` already
+     * works, and for the same reason.
+     */
+    chat?: ChatSpec;
+    /**
+     * Run when the picker is done with the terminal, however it ended.
+     *
+     * The thread's files, its lock and the worker's process group all have to go,
+     * and NONE of that is the picker's to know — `rm` needs `node:fs`, the lock
+     * name is a convention in a service, and the group kill needs the lock's shape.
+     * `pick.ts` owns the transcript, so `pick.ts` owns the cleanup and the picker's
+     * import list stays free of every one of them.
+     */
+    onClose?: () => Promise<void>;
+}
+/**
+ * The session behind the id fzf handed back.
+ *
+ * Checks the list we opened with first, then falls back to a fresh lookup. That
+ * fallback is what makes ctrl-r work: selecting a session that appeared *during*
+ * the refresh would otherwise miss the map built at open and report "Nothing
+ * selected" — refusing to resume the very session you refreshed to find.
+ */
+export declare function resolvePicked(id: string, views: readonly SessionView[], resolve?: (id: string) => Promise<SessionView | null>): Promise<SessionView | null>;
+/** Returns the chosen session, or null if the user cancelled. */
+export declare function pickSession(views: readonly SessionView[], options?: PickOptions): Promise<SessionView | null>;
+/**
+ * How to re-invoke *this* build, as a shell command string.
+ *
+ * fzf runs the preview and reload commands through a shell, and they must hit
+ * this build — not whatever `gmux` happens to be on PATH. During development
+ * there may be no `gmux` on PATH at all, and both would silently render nothing.
+ *
+ * `execArgv` MUST be forwarded, for the same reason `spawnWorker` forwards it:
+ * under `npm run dev` the entry point is `src/cli/main.ts` and execArgv carries
+ * tsx's loader flags. Drop them and the command becomes `node src/cli/main.ts`,
+ * which Node 20 cannot run — so the preview pane and ctrl-r both die in
+ * development while working perfectly from `dist/`. (Node 22 strips types
+ * natively and hides this, which is exactly what makes it worth a comment.)
+ *
+ * Returns null when the entry point is unavailable, leaving callers to decide
+ * on a fallback.
+ */
+export declare function selfCommand(execPath: string, execArgv: readonly string[], entry: string | undefined): string | null;
+/** `selfCommand` for the running process. */
+export declare function selfCommandHere(): string | null;
+/**
+ * Everything the chat tier needs, as opaque strings the picker never interprets.
+ *
+ * Built by `pick.ts`, which owns the transcript and the provider question. The
+ * picker interpolates these into shell strings and does nothing else with them.
+ */
+export interface ChatSpec {
+    /** Baked into the preview command and the send/cancel commands. Never opened here. */
+    transcript: string;
+    /** Full shell command for `enter` in ask mode, minus the appended `--port`. */
+    sendCmd: string;
+    /** Full shell command for `esc` in ask mode, minus the appended `--port`. */
+    cancelCmd: string;
+}
+/**
+ * `ChatSpec` plus the two headers the mode toggle swaps between.
+ *
+ * The headers are not in `ChatSpec` because `pick.ts` cannot know them: the
+ * browse header depends on whether `ctrl-r` got bound at all, which is `fzfArgs`'
+ * decision and nobody else's. esc must restore the EXACT header the picker
+ * started with, so it has to be handed the one that was actually set.
+ */
+export interface AskModeSpec extends ChatSpec {
+    browseHeader: string;
+    askHeader: string;
+}
+/**
+ * The ctrl-o transform body: browse → ask.
+ *
+ * **POSIX `[ … ]` and `if … fi`, no `[[ ]]` and no braces.** fzf runs child
+ * commands with `$SHELL -c`, not `sh -c` (`man fzf` says so twice, lines
+ * 1400-1402 and 2133-2135). Reproduced: `/bin/dash -c '[[ x = x ]]'` is
+ * `[[: not found`, which makes ctrl-o a DEAD KEY with no error anywhere. The
+ * `--with-shell 'sh -c'` on the arg list and these bodies are one fix, not two —
+ * csh cannot parse `if …; then` either, so the bodies alone are not sufficient
+ * and `--with-shell` alone leaves a bash-ism that is simply wrong.
+ *
+ * **`!= disabled`, never `= enabled`.** The oracle is TERNARY — `man fzf`:1462,
+ * *"Current input state (enabled, disabled, hidden)"* — and `--no-input` yields
+ * `hidden`. A ctrl-o guarded on `= enabled` is silently inert under `--no-input`.
+ * Every spelling here treats `hidden` as browse, which is the fail-safe
+ * direction.
+ *
+ * **No `else`, because a transform that emits nothing is a no-op** — verified:
+ * ctrl-o twice does not double-enter or crash.
+ */
+export declare function enterAskActions(spec: AskModeSpec): string;
+/**
+ * The esc transform body: ask → browse, and abort in browse mode.
+ *
+ * The exact inverse of `enterAskActions`, which is why the two are split: for
+ * every stateful action there, the undo is here. Two independent
+ * `askModeBindings`/`browseModeBindings` could not be tested for that, and the
+ * bug they invite is asymmetry — ask fires `disable-search`, browse forgets
+ * `enable-search`, and the filter is dead with no error anywhere.
+ */
+export declare function exitAskActions(spec: AskModeSpec): string;
+/**
+ * The enter transform body.
+ *
+ * **Enter means two things, and that is the sharpest edge in this design.** In
+ * browse mode it resumes a session, replacing your terminal. In ask mode it
+ * sends. A misfire is not cosmetic: enter that resumes when you meant send drops
+ * you into someone else's harness and the picker is gone. That is why the prompt
+ * changes, why the header changes, and why the oracle is fzf's own state rather
+ * than a file that can go stale.
+ *
+ * **`rebind` cannot give enter a new meaning** — it only restores a binding after
+ * `unbind` — so enter is bound ONCE, to a transform that branches.
+ *
+ * `--port "$FZF_PORT"`, `--focus {1}` and `--question "$FZF_QUERY"` are appended
+ * HERE rather than built into `sendCmd`, and never routed through `shellQuote`:
+ * its allowed class is `/^[A-Za-z0-9_./:@-]+$/`, so `$FZF_PORT` would be
+ * single-quoted and the child would receive the literal string — every
+ * `refresh-preview` would then silently miss.
+ *
+ * `{1}`, not `$FZF_CURRENT_ITEM`: the latter is 0.73.0, and on that exact version
+ * a NUL-containing item does not degrade gracefully — it breaks the preview and
+ * every other child command outright (fixed in 0.73.1). We use `--read0`.
+ * `{1}` is also what makes the focus model free: fzf re-substitutes it every time
+ * the binding fires, so this is already "the focus at send time", with no state
+ * and no race.
+ */
+export declare function sendActions(spec: AskModeSpec): string;
+/**
+ * The three bindings the mode toggle is made of.
+ *
+ * `transform:` and not `transform(…)`: the colon form takes the rest of the
+ * argument, and every body below contains parentheses.
+ *
+ * **Mode is not stored anywhere.** fzf already tracks it, and a mode file would
+ * be a second source of truth that can disagree with the first.
+ */
+export declare function chatBindings(spec: AskModeSpec): string[];
+/**
+ * fzf's environment.
+ *
+ * **`FZF_DEFAULT_OPTS` is stripped, and that is a correctness fix rather than
+ * hygiene.** fzf reads it from the environment, and picker.ts used to spawn with
+ * no `env` at all — so a user with `FZF_DEFAULT_OPTS=--disabled` handed us a
+ * picker whose `$FZF_INPUT_STATE` is `disabled` at the very first frame: the
+ * bindings believe they are already in ask mode, enter never resumes, and ctrl-o
+ * cannot get you back. gmux builds its full arg set anyway, and a user `--bind`
+ * colliding with ours is the same class of problem.
+ *
+ * **The api key rides here and NOWHERE else.** `--listen` is an
+ * arbitrary-command-execution surface — verified against a plain localhost
+ * `--listen` on 0.74, `POST execute-silent(touch pwned)` returned HTTP 200 and
+ * created the file — and `FZF_API_KEY` turns an unauthenticated POST into a 401.
+ * It must never reach an argv: measured, `ps -ww -o args=` prints another user's
+ * argv, while `ps e` on their environment needs their uid. So argv is strictly
+ * worse than the env here, which is the opposite of the usual instinct. Honestly:
+ * this raises the bar against a different-user or non-local attacker and does
+ * NOT stop a same-uid one, who can read fzf's environment and POST as us. The
+ * only real boundary there is a unix socket, whose 0.66.0 floor is out of reach
+ * under a 0.59 gate. Known and accepted.
+ */
+export declare function fzfSpawnEnv(env?: NodeJS.ProcessEnv, apiKey?: string | null): NodeJS.ProcessEnv;
+/**
+ * Everything the fzf arg set is built from.
+ *
+ * An options object rather than positionals because the chat tier adds a
+ * transcript and two more commands to this list, and eight positionals read as
+ * `fzfArgs(true, "p", null, null, "split", …)` at every call site.
+ */
+export interface FzfSpec {
+    multiline: boolean;
+    preview: string;
+    /** The already-built shell command, or null when ctrl-r cannot be offered. */
+    reloadCmd: string | null;
+    /** The `execute()` REPL behind ctrl-o, or null when ask cannot be offered. */
+    askCmd: string | null;
+    tier: AskTier;
+    /** Required iff `tier === "split"`. Absent, the split tier degrades to browse. */
+    chat?: ChatSpec;
+}
+/**
+ * Everything we hand fzf on the command line.
+ *
+ * Split out from the spawn so it is testable: pressing a key needs a terminal,
+ * but the args that decide what the key *does* are just data.
+ */
+export declare function fzfArgs(spec: FzfSpec): string[];