@illuminis/comprism 0.1.2 → 0.1.4

package/out/lib/keyboard.js

@@ -0,0 +1,383 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Keyboard = exports.LINE_BREAK = void 0;
+exports.asOneLine = asOneLine;
+/**
+ * The keystrokes a session's reader never sees on their own (manual 6.2, 6.3,
+ * 6.5).
+ *
+ * Node's line reader edits one line well and knows nothing about a paste: every
+ * line break inside a pasted stack trace reached it as Enter, so a 240 line
+ * paste was sent as 240 requests, each billed. It also has no Alt+Enter and no
+ * search of earlier requests.
+ *
+ * So the session's reader reads from this filter instead of from the keyboard.
+ * The filter passes ordinary typing straight through and handles four things
+ * itself:
+ *
+ * * A paste, bracketed by the terminal, becomes one piece of the request. The
+ *   reader is given a short label, `[pasted 240 lines]`, that can be edited
+ *   around like any word, and the label is swapped back for the exact text,
+ *   tabs and trailing spaces included, when the request is sent.
+ * * A terminal that does not bracket pastes still delivers a paste in one read,
+ *   so several lines arriving in one read are treated the same way. A person
+ *   typing never produces a line break followed by more text in one read.
+ * * Alt+Enter continues the request on a new line, exactly as `\` then Enter.
+ * * Ctrl+R searches earlier requests; Enter puts the match at the prompt to be
+ *   edited or sent, and Esc or Ctrl+C puts back what was there.
+ *
+ * Nothing here is written anywhere. Pieces live in memory for the session.
+ */
+const node_stream_1 = require("node:stream");
+const node_string_decoder_1 = require("node:string_decoder");
+const PASTE_ON = '\x1b[?2004h';
+const PASTE_OFF = '\x1b[?2004l';
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+/** Stands for a line break inside a request shown on one line, such as a
+ *  recalled request. Turned back into a line break when it is sent. */
+exports.LINE_BREAK = '␤';
+/** A request as it is shown on one editable line. */
+function asOneLine(text) {
+    return text.replace(/\r\n?|\n/g, exports.LINE_BREAK);
+}
+class Keyboard {
+    history;
+    /** What the session's reader reads. */
+    input = new node_stream_1.PassThrough();
+    decoder = new node_string_decoder_1.StringDecoder('utf8');
+    pieces = [];
+    pasting = null;
+    carry = '';
+    continued = false;
+    search = null;
+    reader = null;
+    listening = false;
+    onData = (chunk) => this.take(typeof chunk === 'string' ? chunk : this.decoder.write(chunk));
+    /** Esc on its own (manual 6.7). Returns true when it was used, so the key
+     *  goes no further; false passes it to the reader as before. */
+    onEscape = null;
+    /** Ctrl+O, the short or full view (manual 6.9). */
+    onFullView = null;
+    /** Ctrl+G, the request in your own editor (manual 6.6). */
+    onEditor = null;
+    /** Ctrl+V, the clipboard's picture, where the terminal passes it (3.4). */
+    onPasteImage = null;
+    /** `keys vi` (manual 6.10): Esc at the prompt enters normal mode. */
+    vi = false;
+    normal = false;
+    pendingD = false;
+    /** `history` is the session's earlier requests, newest first, as shown. */
+    constructor(history) {
+        this.history = history;
+    }
+    /** The reader whose line a search edits. */
+    bind(reader) {
+        this.reader = reader;
+    }
+    /**
+     * Start reading the keyboard. Raw, because the reader no longer holds the
+     * keyboard itself and so cannot switch it; bracketed, so the terminal marks
+     * where a paste begins and ends.
+     */
+    attach() {
+        if (this.listening || !process.stdin.isTTY)
+            return;
+        this.listening = true;
+        process.stdin.setRawMode(true);
+        process.stdin.on('data', this.onData);
+        process.stdin.resume();
+        process.stdout.write(PASTE_ON);
+    }
+    /**
+     * Stop reading, and give the keyboard back exactly as it was found, for a
+     * command that asks its own question and for the shell afterwards. A shell
+     * left with bracketed paste on prints markers around everything pasted.
+     */
+    detach() {
+        if (!this.listening)
+            return;
+        this.listening = false;
+        process.stdin.off('data', this.onData);
+        process.stdout.write(PASTE_OFF);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(false);
+        process.stdin.pause();
+        this.search = null;
+    }
+    /** True once after Alt+Enter, so the line just ended continues the request. */
+    takeContinued() {
+        const was = this.continued;
+        this.continued = false;
+        return was;
+    }
+    /** The request as it will be sent: every paste label swapped for its text,
+     *  and every shown line break made a real one again. */
+    expand(text) {
+        let out = text;
+        for (const p of this.pieces)
+            out = out.split(p.label).join(p.text);
+        return out.split(exports.LINE_BREAK).join('\n');
+    }
+    /** Feed raw keyboard text. Public so a test can type without a terminal. */
+    take(s) {
+        s = this.carry + s;
+        this.carry = '';
+        while (s) {
+            if (this.pasting !== null) {
+                const end = s.indexOf(PASTE_END);
+                if (end === -1) {
+                    const keep = partialTail(s, PASTE_END);
+                    this.pasting += s.slice(0, s.length - keep);
+                    this.carry = s.slice(s.length - keep);
+                    return;
+                }
+                const pasted = this.pasting + s.slice(0, end);
+                this.pasting = null;
+                s = s.slice(end + PASTE_END.length);
+                this.paste(pasted);
+                continue;
+            }
+            const start = s.indexOf(PASTE_START);
+            if (start === -1) {
+                // Only a tail that is clearly the start of a marker is held back. A
+                // lone Esc is a key of its own and must not wait for the next read.
+                const keep = partialTail(s, PASTE_START);
+                const held = keep >= 3 ? keep : 0;
+                this.keys(s.slice(0, s.length - held));
+                this.carry = s.slice(s.length - held);
+                return;
+            }
+            this.keys(s.slice(0, start));
+            s = s.slice(start + PASTE_START.length);
+            this.pasting = '';
+        }
+    }
+    forward(s) {
+        if (s)
+            this.input.write(s);
+    }
+    /** Typing, outside a bracketed paste. */
+    keys(s) {
+        if (!s)
+            return;
+        if (this.search)
+            return this.searchKeys(s);
+        // A lone Esc is a key of its own; a longer read starting with it is an
+        // arrow or another sequence and goes to the reader.
+        if (s === '\x1b' && this.onEscape?.())
+            return;
+        if (this.vi) {
+            if (s === '\x1b') {
+                this.normal = true;
+                return;
+            }
+            if (this.normal)
+                return this.viKeys(s);
+        }
+        // Several lines in one read is a paste from a terminal that does not mark
+        // them. An escape sequence is a key, never a paste.
+        if (s.length > 1 && !s.startsWith('\x1b') && /[\r\n]/.test(s.slice(0, -1))) {
+            return this.paste(s);
+        }
+        for (let i = 0; i < s.length; i += 1) {
+            const ch = s[i];
+            if (ch === '\x1b' && (s[i + 1] === '\r' || s[i + 1] === '\n')) {
+                this.continued = true;
+                this.forward('\r');
+                i += 1;
+                continue;
+            }
+            if (ch === '\x12') {
+                this.startSearch();
+                return this.keys(s.slice(i + 1));
+            }
+            if (ch === '\x0f' && this.onFullView) {
+                this.onFullView();
+                continue;
+            }
+            if (ch === '\x07' && this.onEditor) {
+                this.onEditor();
+                continue;
+            }
+            if (ch === '\x16' && this.onPasteImage) {
+                this.onPasteImage();
+                continue;
+            }
+            // One character at a time only up to the next special key; the rest is
+            // passed on whole so escape sequences stay together.
+            const next = nextSpecial(s, i);
+            this.forward(s.slice(i, next));
+            i = next - 1;
+        }
+    }
+    paste(raw) {
+        const text = raw.replace(/\r\n?/g, '\n');
+        // A paste of plain words is typing that arrived quickly. A tab would
+        // reach the reader as Tab and ask for completion, and a line break as
+        // Enter and send, so either makes it a piece.
+        if (!/[\n\t]/.test(text))
+            return this.keys(text);
+        const lines = text.replace(/\n$/, '').split('\n').length;
+        let label = `[pasted ${lines} line${lines === 1 ? '' : 's'}]`;
+        const same = this.pieces.filter((p) => p.label.startsWith(label.slice(0, -1))).length;
+        if (same > 0)
+            label = `${label.slice(0, -1)} #${same + 1}]`;
+        this.pieces.push({ label, text });
+        this.forward(label);
+    }
+    // ── keys vi ─────────────────────────────────────────────────────────────
+    // Normal mode, the handful of keys a line needs. Each is turned into the
+    // key the line editor already understands, so there is one editor, not two.
+    viKeys(s) {
+        const KEY = {
+            h: '\x1b[D', l: '\x1b[C', '0': '\x01', '$': '\x05', w: '\x1bf', b: '\x1bb',
+            x: '\x1b[3~', k: '\x1b[A', j: '\x1b[B', D: '\x0b',
+        };
+        for (let at = 0; at < s.length; at += 1) {
+            const ch = s[at];
+            // Back to typing: whatever follows in this read is typed as it is.
+            if (!this.normal)
+                return this.keys(s.slice(at));
+            if (this.pendingD) {
+                this.pendingD = false;
+                if (ch === 'd')
+                    this.forward('\x01\x0b');
+                continue;
+            }
+            if (ch === 'd') {
+                this.pendingD = true;
+                continue;
+            }
+            if (ch === 'i') {
+                this.normal = false;
+                continue;
+            }
+            if (ch === 'a') {
+                this.forward('\x1b[C');
+                this.normal = false;
+                continue;
+            }
+            if (ch === 'A') {
+                this.forward('\x05');
+                this.normal = false;
+                continue;
+            }
+            if (ch === 'I') {
+                this.forward('\x01');
+                this.normal = false;
+                continue;
+            }
+            if (ch === '\r' || ch === '\n') {
+                this.normal = false;
+                this.forward('\r');
+                continue;
+            }
+            if (ch === '\x03') {
+                this.normal = false;
+                this.forward(ch);
+                continue;
+            }
+            const key = KEY[ch];
+            if (key)
+                this.forward(key);
+        }
+    }
+    // ── Ctrl+R ────────────────────────────────────────────────────────────────
+    editable() {
+        return this.reader;
+    }
+    startSearch() {
+        const r = this.editable();
+        if (!r)
+            return;
+        this.search = { query: '', skip: 0, before: r.line, prompt: r.getPrompt() };
+        this.drawSearch();
+    }
+    match() {
+        const s = this.search;
+        if (!s)
+            return null;
+        const q = s.query.toLowerCase();
+        const hits = this.history().filter((h) => h.toLowerCase().includes(q));
+        return hits[Math.min(s.skip, hits.length - 1)] ?? null;
+    }
+    drawSearch() {
+        const r = this.editable();
+        const s = this.search;
+        if (!r || !s)
+            return;
+        const hit = this.match();
+        r.setPrompt(`  search earlier requests: ${s.query}${hit === null && s.query ? ' (no match)' : ''}  > `);
+        this.setLine(hit ?? '');
+    }
+    setLine(text) {
+        const r = this.editable();
+        if (!r)
+            return;
+        r.line = text;
+        r.cursor = text.length;
+        r._refreshLine();
+    }
+    endSearch(keep) {
+        const r = this.editable();
+        const s = this.search;
+        const hit = keep ? this.match() : null;
+        this.search = null;
+        if (!r || !s)
+            return;
+        r.setPrompt(s.prompt);
+        this.setLine(keep ? (hit ?? s.before) : s.before);
+    }
+    searchKeys(s) {
+        const state = this.search;
+        for (let i = 0; i < s.length; i += 1) {
+            const ch = s[i];
+            if (ch === '\x1b') {
+                // A lone Esc cancels. An arrow or any other key sequence accepts the
+                // match and is then handled as that key.
+                if (i === s.length - 1)
+                    return this.endSearch(false);
+                this.endSearch(true);
+                return this.keys(s.slice(i));
+            }
+            if (ch === '\r' || ch === '\n') {
+                this.endSearch(true);
+                return this.keys(s.slice(i + 1));
+            }
+            if (ch === '\x03' || ch === '\x07')
+                return this.endSearch(false);
+            if (ch === '\x12')
+                state.skip += 1;
+            else if (ch === '\x7f' || ch === '\b') {
+                state.query = state.query.slice(0, -1);
+                state.skip = 0;
+            }
+            else if (ch >= ' ') {
+                state.query += ch;
+                state.skip = 0;
+            }
+        }
+        this.drawSearch();
+    }
+}
+exports.Keyboard = Keyboard;
+/** How many characters at the end of `s` could be the start of `marker`. */
+function partialTail(s, marker) {
+    for (let n = Math.min(marker.length - 1, s.length); n > 0; n -= 1) {
+        if (marker.startsWith(s.slice(s.length - n)))
+            return n;
+    }
+    return 0;
+}
+/** Where the next key this filter handles itself begins, from `i + 1`. */
+function nextSpecial(s, i) {
+    for (let j = i + 1; j < s.length; j += 1) {
+        const ch = s[j];
+        if (ch === '\x12' || ch === '\x0f' || ch === '\x07' || ch === '\x16')
+            return j;
+        if (ch === '\x1b' && (s[j + 1] === '\r' || s[j + 1] === '\n'))
+            return j;
+    }
+    return s.length;
+}

package/out/lib/machine.d.ts

@@ -0,0 +1,21 @@
+export interface MachineKey {
+    values: string[] | null;
+    fallback: string;
+    what: string;
+}
+/** Every machine setting, its allowed values, and its default. `editor` takes
+ *  any command. */
+export declare const MACHINE_KEYS: Record<string, MachineKey>;
+export declare function machineSettings(): Record<string, string>;
+/** Whether a value was stored for this key, rather than the default. */
+export declare function isSet(key: string): boolean;
+/** Store one value. Returns why not, or null when it was stored. */
+export declare function setMachine(key: string, value: string): string | null;
+export declare function unsetMachine(key: string): string | null;
+/**
+ * Apply the look before anything is drawn (manual 6.10, 6.12). `NO_COLOR`,
+ * `--plain`, `plain true` and `theme plain` all mean the same thing: no color
+ * and every update on a new line.
+ */
+export declare function applyLook(plainFlag: boolean): void;
+export declare function isPlain(): boolean;

package/out/lib/machine.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACHINE_KEYS = void 0;
+exports.machineSettings = machineSettings;
+exports.isSet = isSet;
+exports.setMachine = setMachine;
+exports.unsetMachine = unsetMachine;
+exports.applyLook = applyLook;
+exports.isPlain = isPlain;
+/**
+ * Settings that describe this machine and nothing else (manual 2.10, 6.5,
+ * 6.10 to 6.12): how it looks, which keys edit a line, how it tells you a job
+ * finished, and whether requests are remembered.
+ *
+ * Kept in the tool's own `config.json`, never on the service, because none of
+ * them changes what the agent does: two people sharing a project can each have
+ * their own theme. Settings that do change what the agent does are the
+ * service's and the project's (manual 2.10), and are not written here.
+ */
+const config_1 = require("./config");
+/** Every machine setting, its allowed values, and its default. `editor` takes
+ *  any command. */
+exports.MACHINE_KEYS = {
+    theme: { values: ['dark', 'light', 'plain'], fallback: 'dark', what: 'colors for a dark or light terminal, or none' },
+    keys: { values: ['emacs', 'vi'], fallback: 'emacs', what: 'line editing keys' },
+    notify: { values: ['desktop', 'bell', 'off'], fallback: 'bell', what: 'how you are told a long job finished' },
+    plain: { values: ['true', 'false'], fallback: 'false', what: 'no color and no redrawn lines' },
+    history: { values: ['on', 'off'], fallback: 'on', what: 'remember earlier requests' },
+    editor: { values: null, fallback: '', what: 'editor for Ctrl+G when VISUAL and EDITOR are not set' },
+};
+function machineSettings() {
+    const stored = ((0, config_1.loadConfig)().machine ?? {});
+    const out = {};
+    for (const [k, spec] of Object.entries(exports.MACHINE_KEYS)) {
+        const v = stored[k];
+        out[k] = typeof v === 'string' && (spec.values === null || spec.values.includes(v)) ? v : spec.fallback;
+    }
+    return out;
+}
+/** Whether a value was stored for this key, rather than the default. */
+function isSet(key) {
+    const stored = ((0, config_1.loadConfig)().machine ?? {});
+    return typeof stored[key] === 'string';
+}
+/** Store one value. Returns why not, or null when it was stored. */
+function setMachine(key, value) {
+    const spec = exports.MACHINE_KEYS[key];
+    if (!spec)
+        return `${key} is not a setting for this machine.`;
+    if (spec.values !== null && !spec.values.includes(value)) {
+        return `${key} is one of ${spec.values.join(', ')}.`;
+    }
+    const cfg = (0, config_1.loadConfig)();
+    cfg.machine = { ...(cfg.machine ?? {}), [key]: value };
+    (0, config_1.saveConfig)(cfg);
+    return null;
+}
+function unsetMachine(key) {
+    if (!exports.MACHINE_KEYS[key])
+        return `${key} is not a setting for this machine.`;
+    const cfg = (0, config_1.loadConfig)();
+    const next = { ...(cfg.machine ?? {}) };
+    delete next[key];
+    cfg.machine = next;
+    (0, config_1.saveConfig)(cfg);
+    return null;
+}
+/**
+ * Apply the look before anything is drawn (manual 6.10, 6.12). `NO_COLOR`,
+ * `--plain`, `plain true` and `theme plain` all mean the same thing: no color
+ * and every update on a new line.
+ */
+function applyLook(plainFlag) {
+    let m;
+    try {
+        m = machineSettings();
+    }
+    catch {
+        m = { theme: 'dark', plain: 'false' };
+    }
+    const plain = plainFlag || m.plain === 'true' || m.theme === 'plain'
+        || (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '');
+    if (plain) {
+        process.env.NO_COLOR = process.env.NO_COLOR || '1';
+        process.env.COMPRISM_PLAIN = '1';
+    }
+    process.env.COMPRISM_THEME = m.theme === 'light' ? 'light' : 'dark';
+}
+function isPlain() {
+    return process.env.COMPRISM_PLAIN === '1';
+}

package/out/lib/notify.d.ts

@@ -0,0 +1,4 @@
+/** The way this machine will notify, after falling back. */
+export declare function howNotified(): 'desktop' | 'bell' | 'off';
+/** Tell the person. `say` prints a line in the session. */
+export declare function notify(message: string, say: (line: string) => void): void;

package/out/lib/notify.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.howNotified = howNotified;
+exports.notify = notify;
+/**
+ * Being told when it finishes (manual 6.11).
+ *
+ * `notify desktop` asks the operating system to show a notification: the
+ * built in `osascript` on macOS, `notify-send` on Linux. Where neither is
+ * there, the terminal bell rings instead and the session says so once. `bell`
+ * rings the bell, `off` does nothing. What to say is decided by the caller;
+ * this only reaches the operating system.
+ */
+const node_child_process_1 = require("node:child_process");
+const machine_1 = require("./machine");
+let saidFallback = false;
+function hasProgram(name) {
+    const r = (0, node_child_process_1.spawnSync)(process.platform === 'win32' ? 'where' : 'which', [name], { stdio: 'ignore' });
+    return r.status === 0;
+}
+/** The way this machine will notify, after falling back. */
+function howNotified() {
+    const wanted = (0, machine_1.machineSettings)().notify;
+    if (wanted === 'off')
+        return 'off';
+    if (wanted === 'desktop') {
+        if (process.platform === 'darwin' && hasProgram('osascript'))
+            return 'desktop';
+        if (process.platform === 'linux' && hasProgram('notify-send'))
+            return 'desktop';
+    }
+    return 'bell';
+}
+/** Tell the person. `say` prints a line in the session. */
+function notify(message, say) {
+    const how = howNotified();
+    if (how === 'off')
+        return;
+    if (how === 'desktop') {
+        const args = process.platform === 'darwin'
+            ? ['-e', `display notification ${JSON.stringify(message)} with title "comprism"`]
+            : ['comprism', message];
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        (0, node_child_process_1.spawn)(process.platform === 'darwin' ? 'osascript' : 'notify-send', args, { stdio: 'ignore', detached: true }).unref();
+        return;
+    }
+    if ((0, machine_1.machineSettings)().notify === 'desktop' && !saidFallback) {
+        saidFallback = true;
+        say('  desktop notifications are not available here, so the terminal bell is used instead');
+    }
+    process.stdout.write('\x07');
+}

package/out/lib/output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a one request job writes its result for a script (manual 10.2, 10.3,
+ * Appendix B).
+ *
+ * Nothing here decides how a job ended. The service sends a reason word and
+ * the table that turns reason words into exit numbers, and this looks the word
+ * up. The only numbers known here are for the endings that happen when the
+ * service never answered: a typing mistake, no sign in, no connection, Ctrl+C.
+ */
+export type Format = 'text' | 'json' | 'stream';
+export interface OutputChoice {
+    format: Format;
+    /** Only the answer on standard output, even at a terminal (10.2). */
+    quiet: boolean;
+    /** Standard output is a file or a pipe: only the result goes there. */
+    plain: boolean;
+}
+export declare const FORMATS: Format[];
+/** Read `--output` and `--quiet`. Null format means a value nobody accepts. */
+export declare function outputChoice(args: string[]): OutputChoice | {
+    bad: string;
+};
+/** Whether progress belongs on standard error rather than standard output. */
+export declare function progressToErr(o: OutputChoice): boolean;
+/** The exit number for a reason, from the service's table when it sent one. */
+export declare function exitFor(reason: string, table?: Record<string, number> | null): number;
+/** The result object for an ending the service never saw, in its published
+ *  shape: every field present, nothing known left as anything but null. */
+export declare function localResult(reason: string, error: string): Record<string, unknown>;
+/**
+ * Read a JSON file named on the line (`--schema`, `--config`): a permitted
+ * local read. The service decides what the contents mean.
+ */
+export declare function readJsonFile(path: string, flagName: string): {
+    value: Record<string, unknown>;
+} | {
+    bad: string;
+};
+/** Print the result object as one line of JSON on standard output. */
+export declare function printJson(result: Record<string, unknown>): void;
+/**
+ * Refuse a flag this command does not know (Appendix B, exit 2).
+ *
+ * `known` lists flags that take a value; `switches` lists flags that do not.
+ * A word that is a flag's value is skipped, so a request that happens to
+ * follow `--model` is never read as a flag.
+ */
+export declare function unknownFlag(args: string[], known: string[], switches: string[]): string | null;