@onesi/genesis-cli 0.0.1-stage → 0.2.0

package/dist/onboard/term.js

@@ -0,0 +1,292 @@
+/**
+ * The terminal for one setup run: a live region redrawn in place (never the alternate screen, so the whole setup
+ * stays in scrollback), frames bracketed in synchronized output (DECSET 2026) so nothing tears, a steady frame clock,
+ * and one cleanup that always runs (Ctrl-C, an error, a normal exit) and puts back the cursor, its shape, the window
+ * title, focus reporting, raw mode and the tab's progress indicator.
+ */
+import { homedir } from 'node:os';
+const ESC = '\x1b';
+export const strip = (s) => s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b_[^\x1b]*\x1b\\|\x1bP[^\x1b]*\x1b\\/g, '');
+/** Display width: wide East Asian and emoji count two. Enough for our own copy and server names passed through safe(). */
+export function width(s) {
+    let w = 0;
+    for (const ch of strip(s)) {
+        const cp = ch.codePointAt(0);
+        if (cp < 32 || (cp >= 0x300 && cp < 0x370) || cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f))
+            continue;
+        w += (cp >= 0x1100 && (cp <= 0x115f || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60) || (cp >= 0x1f300 && cp <= 0x1faff))) ? 2 : 1;
+    }
+    return w;
+}
+export function parseKeys(data) {
+    const keys = [];
+    let i = 0;
+    while (i < data.length) {
+        const rest = data.slice(i);
+        // A reply to setup's own probe that arrived after its deadline (a slow SSH link): OSC 11, DECRQM, CSI … t,
+        // DA1, or a Kitty graphics answer. It is the terminal talking, not the user typing, so it is dropped.
+        const reply = /^(?:\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[\?[\d;]*\$y|\x1b\[\d+;\d+;\d+t|\x1b\[\?[\d;]*c|\x1b_[^\x1b]*\x1b\\)/.exec(rest);
+        if (reply) {
+            i += reply[0].length;
+            continue;
+        }
+        const paste = /^\x1b\[200~([\s\S]*?)\x1b\[201~/.exec(rest);
+        if (paste) {
+            keys.push({ name: 'paste', ch: paste[1] });
+            i += paste[0].length;
+            continue;
+        }
+        const m = /^\x1b\[(\d*)(?:;(\d+))?([A-DHFIOZ~])/.exec(rest);
+        if (m) {
+            const map = { A: 'up', B: 'down', C: 'right', D: 'left', H: 'home', F: 'end', I: 'focus-in', O: 'focus-out', Z: 'backtab' };
+            keys.push({ name: m[3] === '~' ? ({ '3': 'delete', '1': 'home', '4': 'end', '5': 'pageup', '6': 'pagedown' }[m[1]] ?? 'unknown') : map[m[3]] });
+            i += m[0].length;
+            continue;
+        }
+        const ss3 = /^\x1bO([A-DHF])/.exec(rest);
+        if (ss3) {
+            keys.push({ name: { A: 'up', B: 'down', C: 'right', D: 'left', H: 'home', F: 'end' }[ss3[1]] });
+            i += 3;
+            continue;
+        }
+        const c = rest[0];
+        if (c === '\x1b') {
+            keys.push({ name: 'escape' });
+            i += rest.length > 1 && rest[1] !== '\x1b' && rest[1] !== '[' ? 2 : 1;
+            continue;
+        }
+        if (c === '\r' || c === '\n')
+            keys.push({ name: 'enter' });
+        else if (c === '\x7f' || c === '\b')
+            keys.push({ name: 'backspace' });
+        else if (c === '\t')
+            keys.push({ name: 'tab' });
+        else if (c === ' ')
+            keys.push({ name: 'space', ch: ' ' });
+        else if (c === '\x03')
+            keys.push({ name: 'c', ctrl: true });
+        else if (c === '\x04')
+            keys.push({ name: 'd', ctrl: true });
+        else if (c.charCodeAt(0) < 32)
+            keys.push({ name: String.fromCharCode(c.charCodeAt(0) + 96), ctrl: true });
+        else {
+            const cp = rest.codePointAt(0);
+            const ch = String.fromCodePoint(cp);
+            keys.push({ name: ch.toLowerCase(), ch });
+            i += ch.length;
+            continue;
+        }
+        i++;
+    }
+    return keys;
+}
+export class Interrupted extends Error {
+    constructor() { super('Setup paused.'); }
+}
+export class Term {
+    caps;
+    stdout;
+    stdin;
+    live = 0; // rows the live region occupies
+    liveWidth = 0;
+    liveEmpty = false;
+    cleanups = [];
+    keyWaiters = [];
+    onData = (b) => { for (const k of parseKeys(b.toString('utf8')))
+        this.dispatch(k); };
+    /** Every line setup draws sits two columns in from the edge; a step's own lines sit four in, under its header. */
+    margin = '  ';
+    focused = true;
+    focusListeners = new Set();
+    /** Ctrl-C while nothing reads keys (a network wait). Setup replaces it to say where it will pick up. */
+    onInterrupt = () => { this.restore(); process.exit(130); };
+    restored = false;
+    constructor(caps, stdout, stdin) {
+        this.caps = caps;
+        this.stdout = stdout;
+        this.stdin = stdin;
+    }
+    write(s) { this.stdout.write(s); }
+    get columns() { return Math.max(20, this.stdout.columns || this.caps.columns || 80); }
+    /** Start the session: raw keys, focus events, bracketed paste, hidden cursor, our title pushed onto the stack. */
+    start(title) {
+        if (!this.caps.interactive)
+            return;
+        this.stdin.setRawMode(true);
+        this.stdin.resume();
+        this.stdin.on('data', this.onData);
+        let s = `${ESC}[?1004h${ESC}[?2004h`;
+        if (this.caps.motion)
+            s += `${ESC}[?25l`;
+        s += `${ESC}[22;0t${ESC}]2;${title}\x07`;
+        this.write(s);
+        const restore = () => this.restore();
+        const sig = () => { this.restore(); process.exit(130); };
+        process.once('exit', restore);
+        process.once('SIGTERM', sig);
+        this.cleanups.push(() => { process.off('exit', restore); process.off('SIGTERM', sig); });
+    }
+    title(t) { if (this.caps.interactive)
+        this.write(`${ESC}]2;${t}\x07`); }
+    /** Tab/taskbar progress (OSC 9;4): 0 hidden, 1 value, 3 indeterminate. */
+    progress(state, value = 0) {
+        if (this.caps.progress)
+            this.write(`${ESC}]9;4;${state};${Math.round(value)}\x07`);
+    }
+    /** A desktop notification, only when the window is not in front (the user went to the browser). */
+    notify(title, body) {
+        if (this.focused || !this.caps.notify)
+            return;
+        const clean = (s) => s.replace(/[\x00-\x1f\x7f;]/g, ' ');
+        if (this.caps.notify === 'osc9')
+            this.write(`${ESC}]9;${clean(title)}: ${clean(body)}\x07`);
+        else if (this.caps.notify === 'osc777')
+            this.write(`${ESC}]777;notify;${clean(title)};${clean(body)}\x07`);
+        else
+            this.write(`${ESC}]99;i=1:d=0;${clean(title)}${ESC}\\${ESC}]99;i=1:d=1:p=body;${clean(body)}${ESC}\\`);
+    }
+    /** DECSCUSR: 6 steady bar (the emblem's bar as the caret), 0 the user's default. */
+    cursorShape(n) { if (this.caps.interactive)
+        this.write(`${ESC}[${n} q`); }
+    cursor(show) { if (this.caps.interactive)
+        this.write(show ? `${ESC}[?25h` : `${ESC}[?25l`); }
+    /** OSC 8 where the terminal supports it; elsewhere the label and the address, so the URL is never hidden. */
+    link(url, text = url) {
+        if (this.caps.hyperlinks)
+            return `${ESC}]8;;${url}${ESC}\\${text}${ESC}]8;;${ESC}\\`;
+        // A label that is itself an address (the device page) stands alone; a word label gets the address after it.
+        return text === url || /^https?:\/\//.test(strip(text)) ? text : `${text} ${url}`;
+    }
+    /**
+     * Replace the live region with `lines`, in one synchronized frame. The region shrinks and grows as needed; lines are
+     * clipped to the window so a narrow terminal never wraps a frame into garbage.
+     */
+    frame(lines) {
+        const cols = this.columns;
+        let s = `${ESC}[?2026h`;
+        if (this.live > 0)
+            s += `\r${this.live > 1 ? `${ESC}[${this.live - 1}A` : ''}`;
+        const fitted = (lines.length ? lines : ['']).map((l) => (l ? this.margin + this.mask(l) : l)).map((l) => (width(l) > cols - 1 ? clip(l, cols - 1) : l));
+        for (let i = 0; i < Math.max(fitted.length, this.live); i++) {
+            s += `${ESC}[2K${fitted[i] ?? ''}`;
+            if (i < Math.max(fitted.length, this.live) - 1)
+                s += '\n';
+        }
+        // Leave the cursor on the last line of the new region.
+        const extra = Math.max(0, this.live - fitted.length);
+        if (extra)
+            s += `${ESC}[${extra}A`;
+        s += `${ESC}[?2026l`;
+        this.write(s);
+        this.live = Math.max(1, fitted.length);
+        this.liveEmpty = fitted.every((l) => l === '');
+        this.liveWidth = cols;
+    }
+    /** Freeze the live region into scrollback; the next frame starts below it. */
+    commit() {
+        // An empty region (a finished one-line wait) is reused rather than left as a blank line.
+        if (this.live > 0)
+            this.write(this.liveEmpty ? `\r${this.live > 1 ? `${ESC}[${this.live - 1}A` : ''}` : '\n');
+        this.live = 0;
+        this.liveEmpty = false;
+    }
+    /** Plain append, for screen readers and still mode: never rewrites what was said. */
+    say(line = '') { this.commit(); this.write((line ? this.margin + this.mask(line) : '') + '\n'); }
+    /** In screencast mode, every identifier (h_…, o_…, w_…, pr_…, sess_…, keys) and email that setup prints is masked. */
+    mask(line) { return this.caps.screencast ? maskIdentifiers(line) : line; }
+    dispatch(k) {
+        if (k.name === 'focus-in' || k.name === 'focus-out') {
+            this.focused = k.name === 'focus-in';
+            for (const f of this.focusListeners)
+                f(this.focused);
+            return;
+        }
+        if (k.ctrl && (k.name === 'c' || k.name === 'd')) {
+            // Ctrl-C always works: it stops whatever is waiting on a key, or, mid-request with nothing listening, the run.
+            if (this.keyWaiters.length) {
+                for (const w of this.keyWaiters.splice(0))
+                    w(k);
+                return;
+            }
+            this.onInterrupt();
+            return;
+        }
+        const w = this.keyWaiters.shift();
+        if (w)
+            w(k);
+    }
+    /** The next key; Ctrl-C rejects with Interrupted so every step can stop cleanly and be resumed. */
+    key(signal) {
+        return new Promise((resolve, reject) => {
+            const done = (k) => { signal?.removeEventListener('abort', abort); if (k.ctrl && (k.name === 'c' || k.name === 'd'))
+                reject(new Interrupted());
+            else
+                resolve(k); };
+            const abort = () => { this.keyWaiters = this.keyWaiters.filter((w) => w !== done); resolve({ name: 'abort' }); };
+            signal?.addEventListener('abort', abort, { once: true });
+            this.keyWaiters.push(done);
+        });
+    }
+    /** Any pending key, without waiting (for "press any key to skip" during animations). */
+    pollKey() { return this.key(); }
+    restore() {
+        if (this.restored)
+            return;
+        this.restored = true;
+        for (const c of this.cleanups.splice(0))
+            c();
+        if (!this.caps.interactive)
+            return;
+        this.progress(0);
+        this.write(`${ESC}[?2026l${ESC}[0m${ESC}[?1004l${ESC}[?2004l${ESC}[0 q${ESC}[?25h${ESC}[23;0t`);
+        try {
+            this.stdin.off('data', this.onData);
+            this.stdin.setRawMode(false);
+            this.stdin.pause();
+        }
+        catch { /* closed */ }
+    }
+}
+const ID = /(?<![A-Za-z0-9])(h|o|w|pr|pf|fl|sess|key|sk|gk|org|user)_[A-Za-z0-9_-]{4,}/g;
+// The home directory (and so the OS user name) in a config path becomes ~.
+const HOME = new RegExp(homedir().replace(/[.*+?^${}()|[\]\\]/g, '\\$&') || '\\0nohome', 'g');
+const EMAIL = /\b[\w.+-]+@[\w-]+(?:\.[\w-]+)+\b/g;
+const SGR_OR_OSC = /(\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\))/;
+/** Masks the text between escape sequences, so an identifier right after a colour code (…m o_…) is still found. */
+export function maskIdentifiers(line) {
+    return line.split(SGR_OR_OSC).map((part, i) => i % 2 ? part
+        : part.replace(ID, (_, p) => `${p}_••••••••`).replace(EMAIL, '•••@•••').replace(HOME, '~')).join('');
+}
+/** Clip to `cols` display columns, keeping escape sequences intact and closing any open style and link. */
+export function clip(line, cols) {
+    let out = '', w = 0, i = 0;
+    while (i < line.length && w < cols) {
+        const esc = /^(?:\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\))/.exec(line.slice(i));
+        if (esc) {
+            out += esc[0];
+            i += esc[0].length;
+            continue;
+        }
+        const ch = String.fromCodePoint(line.codePointAt(i));
+        const cw = width(ch);
+        if (w + cw > cols)
+            break;
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return out + '\x1b[0m\x1b]8;;\x1b\\';
+}
+/** A steady clock: calls `draw(t)` at `fps` until it returns false, sleeping the remainder of each frame. */
+export async function animate(fps, draw, signal) {
+    const start = performance.now(), period = 1000 / fps;
+    for (let n = 0;; n++) {
+        if (signal?.aborted)
+            return;
+        const t = (performance.now() - start) / 1000;
+        if (!(await draw(t)))
+            return;
+        const next = start + (n + 1) * period, wait = next - performance.now();
+        await new Promise((r) => setTimeout(r, Math.max(0, wait)));
+    }
+}

package/dist/onboard/ui.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Setup's pieces: the welcome (the hybrid ONE drawing itself, its O waking as One's eye and hopping through the Ones),
+ * type that arrives, choices with a rail that glides between rows in eighth-cell steps, a confirmation, a text field
+ * whose caret is the emblem's bar, and a waiting card where One's eye keeps you company.
+ *
+ * Every piece has a still form that is the same words in the same order, so reduced motion, screen readers, NO_COLOR,
+ * TERM=dumb and pipes get exactly the same setup.
+ */
+import { type Color } from './raster.js';
+import { type LogoState, type Tone } from './art.js';
+import { type OneShape } from './brand.js';
+import { kittyDelete } from './encode.js';
+import { type Key, type Term } from './term.js';
+export declare class Style {
+    readonly term: Term;
+    readonly tone: Tone;
+    readonly ink: Color | null;
+    readonly mutedColor: Color | null;
+    constructor(term: Term);
+    private sgr;
+    bold: (s: string) => string;
+    muted: (s: string) => string;
+    /** Text partway through arriving: from the background toward ink, in linear light. */
+    arriving(s: string, k: number): string;
+    error: (s: string) => string;
+    get check(): "✓" | "ok";
+    get dot(): "-" | "·";
+}
+/** Pick three Ones for the parade: random per run, fixed by GENESIS_DEMO_SEED so recordings repeat. */
+export declare function paradeCast(seed?: number): OneShape[];
+/** The logotype's state at time t of the welcome. Pure, so the tests can check any frame. */
+export declare function welcomeAt(t: number, cast: OneShape[], short?: boolean): LogoState & {
+    done: boolean;
+};
+export interface Hero {
+    rows: number;
+    px: number;
+    draw(state: LogoState): string[];
+}
+export declare function hero(term: Term, style: Style): Hero | null;
+export declare function welcome(term: Term, style: Style, opts: {
+    short: boolean;
+    tagline: string[];
+    seed?: number;
+}): Promise<void>;
+/** Lines that type themselves in: a little faster on spaces, a breath at punctuation, each glyph fading up to ink. */
+export declare function typeLines(term: Term, style: Style, lines: string[]): Promise<void>;
+export interface Option<T> {
+    label: string;
+    value: T;
+    hint?: string;
+    disabled?: boolean;
+}
+/**
+ * One row's rail cell when the rail (one row tall) sits at fractional row `pos`. Lower eighths draw the rail coming in
+ * from below; reverse video of the same glyphs draws it leaving through the bottom (the terminal swaps its own ink
+ * and paper, so this works without knowing either).
+ */
+export declare function railCell(row: number, pos: number): string;
+export declare function select<T>(term: Term, style: Style, q: {
+    title: string;
+    options: Option<T>[];
+    initial?: number;
+    skippable?: boolean;
+}): Promise<T | 'skip'>;
+export declare function confirm(term: Term, style: Style, question: string, initial: boolean): Promise<boolean>;
+/** A one-line field. The caret is a steady bar (DECSCUSR 6), the emblem's bar; typed letters fade up to ink. */
+export declare function input(term: Term, style: Style, q: {
+    label: string;
+    initial: string;
+    validate?: (v: string) => string | null;
+}): Promise<string>;
+export interface WaitResult<T> {
+    value?: T;
+    key?: Key;
+}
+/**
+ * Wait for `task` beside One's eye. The eye idles as on the site (blinks, glances at the text), turns to look at you
+ * when you come back to the window, and the tab shows indeterminate progress. Keys in `keys` end the wait early and
+ * are returned (e.g. "d" to switch to a device code); Ctrl-C stops setup, resumably.
+ */
+export declare function waitBeside<T>(term: Term, style: Style, lines: () => string[], task: Promise<T>, keys?: string[]): Promise<WaitResult<T>>;
+/** The moment it works: One smiles, and the light fills the eye and leaves. */
+export declare function delight(term: Term, style: Style, line: string): Promise<void>;
+export { kittyDelete };
+/** Several choices at once (space toggles, a selects all, enter confirms). Screen readers type numbers. */
+export declare function pick<T>(term: Term, style: Style, q: {
+    title: string;
+    options: (Option<T> & {
+        checked: boolean;
+    })[];
+}): Promise<T[]>;
+/**
+ * A short wait on one line: the emblem's bar blinking on agent-eye's timing (its lid closing as lower eighth blocks),
+ * then the line resolves to its result. Still terminals print the label once.
+ */
+export declare function busy<T>(term: Term, style: Style, label: string, task: Promise<T>): Promise<T>;