@onesi/genesis-cli 0.1.13 → 0.2.0

package/dist/onboard/mcp.js

@@ -0,0 +1,118 @@
+/**
+ * Put the Genesis MCP server into the user's agents. Each client is found by its own config home; nothing is written
+ * until the user has seen exactly which file or command changes and said yes. JSON files keep every other server,
+ * are written atomically, and the previous file is kept beside it as <name>.genesis-backup. A file we cannot parse is
+ * never touched.
+ *
+ * GUI apps (Claude Desktop) do not inherit the shell's PATH, so they get the absolute path of the npx next to the
+ * Node that is running this CLI; terminal clients get plain `npx`.
+ */
+import { execFile } from 'node:child_process';
+import { access, chmod, copyFile, mkdir, readFile, realpath, rename, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function defaultMcpEnv(version) {
+    return { home: homedir(), platform: process.platform, appData: process.env.APPDATA, execPath: process.execPath, version,
+        run: (cmd, args) => new Promise((resolve) => { try {
+            execFile(cmd, args, { timeout: 15_000, windowsHide: true }, (e, out) => resolve({ code: !e ? 0 : e.code === 'ENOENT' ? 127 : typeof e.code === 'number' ? e.code : 1, stdout: String(out ?? '') }));
+        }
+        catch {
+            resolve({ code: 127, stdout: '' });
+        } }) };
+}
+/** The npm package of the MCP server: the one place setup names the package scope. */
+export const MCP_PACKAGE = '@onesi/genesis-mcp';
+const exists = (p) => access(p).then(() => true, () => false);
+const pkg = (e) => `${MCP_PACKAGE}@${e.version}`;
+function appSupport(e, ...rest) {
+    if (e.platform === 'darwin')
+        return join(e.home, 'Library', 'Application Support', ...rest);
+    if (e.platform === 'win32')
+        return join(e.appData ?? join(e.home, 'AppData', 'Roaming'), ...rest);
+    return join(e.home, '.config', ...rest);
+}
+export function paths(e) {
+    return {
+        'claude-desktop': join(appSupport(e, 'Claude'), 'claude_desktop_config.json'),
+        cursor: join(e.home, '.cursor', 'mcp.json'),
+        vscode: join(appSupport(e, 'Code', 'User'), 'mcp.json'),
+        windsurf: join(e.home, '.codeium', 'windsurf', 'mcp_config.json'),
+        codex: join(e.home, '.codex', 'config.toml'),
+    };
+}
+/** An absolute npx for GUI clients, when one sits next to this Node; otherwise plain npx. */
+export async function npxFor(e, gui) {
+    if (!gui)
+        return 'npx';
+    const candidate = join(dirname(e.execPath), e.platform === 'win32' ? 'npx.cmd' : 'npx');
+    return (await exists(candidate)) ? candidate : 'npx';
+}
+async function readJson(path) {
+    try {
+        const text = await readFile(path, 'utf8');
+        if (!text.trim())
+            return { ok: true, value: {} };
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' && !Array.isArray(v) ? { ok: true, value: v } : { ok: false };
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? { ok: true, value: {} } : { ok: false };
+    }
+}
+export async function detectClients(e) {
+    const p = paths(e);
+    const claudeCode = await e.run('claude', ['mcp', 'get', 'genesis']);
+    const has = async (file, key) => { const j = await readJson(file); return j.ok && !!j.value[key]?.genesis; };
+    const codexText = await readFile(p.codex, 'utf8').catch(() => '');
+    return [
+        { id: 'claude-code', name: 'Claude Code', target: `claude mcp add --scope user genesis -- npx -y ${pkg(e)}`,
+            present: claudeCode.code !== 127, installed: claudeCode.code === 0 },
+        { id: 'claude-desktop', name: 'Claude Desktop', target: p['claude-desktop'], present: await exists(dirname(p['claude-desktop'])), installed: await has(p['claude-desktop'], 'mcpServers') },
+        { id: 'cursor', name: 'Cursor', target: p.cursor, present: await exists(dirname(p.cursor)), installed: await has(p.cursor, 'mcpServers') },
+        { id: 'vscode', name: 'VS Code', target: p.vscode, present: await exists(dirname(p.vscode)), installed: await has(p.vscode, 'servers') },
+        { id: 'windsurf', name: 'Windsurf', target: p.windsurf, present: await exists(dirname(p.windsurf)), installed: await has(p.windsurf, 'mcpServers') },
+        { id: 'codex', name: 'Codex', target: p.codex, present: await exists(dirname(p.codex)), installed: /^\[mcp_servers\.genesis\]/m.test(codexText) },
+    ];
+}
+/** Write beside the real file (a dotfiles symlink stays a symlink) and keep the file's own mode; new files get 0600. */
+async function writeAtomic(path, text) {
+    await mkdir(dirname(path), { recursive: true });
+    const target = await realpath(path).catch(() => path);
+    const mode = await stat(target).then((s) => s.mode & 0o777, () => 0o600);
+    if (await exists(target))
+        await copyFile(target, `${target}.genesis-backup`);
+    const tmp = `${target}.${process.pid}.tmp`;
+    await writeFile(tmp, text, { mode });
+    await chmod(tmp, mode);
+    await rename(tmp, target);
+}
+/** Install into one client. Returns a sentence for the summary, or throws with the reason. */
+export async function install(e, id) {
+    const p = paths(e);
+    const args = ['-y', pkg(e)];
+    if (id === 'claude-code') {
+        const r = await e.run('claude', ['mcp', 'add', '--scope', 'user', 'genesis', '--', 'npx', ...args]);
+        if (r.code !== 0)
+            throw new Error('`claude mcp add` did not succeed');
+        return 'added with `claude mcp add` (user scope)';
+    }
+    if (id === 'codex') {
+        const text = await readFile(p.codex, 'utf8').catch((err) => { if (err.code === 'ENOENT')
+            return ''; throw err; });
+        if (/^\[mcp_servers\.genesis\]/m.test(text))
+            return 'already there';
+        const block = `\n[mcp_servers.genesis]\ncommand = "npx"\nargs = [${args.map((a) => JSON.stringify(a)).join(', ')}]\n`;
+        await writeAtomic(p.codex, text.replace(/\n*$/, '\n') + block);
+        return `added to ${p.codex}`;
+    }
+    const file = p[id];
+    const j = await readJson(file);
+    if (!j.ok)
+        throw new Error(`${file} is not valid JSON; left it untouched`);
+    const command = await npxFor(e, id === 'claude-desktop');
+    const entry = id === 'vscode' ? { type: 'stdio', command, args } : { command, args };
+    const key = id === 'vscode' ? 'servers' : 'mcpServers';
+    const next = { ...j.value, [key]: { ...(j.value[key] ?? {}), genesis: entry } };
+    await writeAtomic(file, JSON.stringify(next, null, 2) + '\n');
+    return `added to ${file}`;
+}

package/dist/onboard/raster.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A tiny vector rasterizer: SVG paths (M L H V Q A Z, absolute and relative) flattened to polygons, filled with
+ * analytic-quality anti-aliasing by supersampling scanlines (S×S samples a pixel, crossings sorted once a row).
+ * The canvas is premultiplied linear-light RGBA, so blended edges come out the way a browser draws the same SVG.
+ */
+export type Pt = [number, number];
+export type Poly = Pt[];
+export type Rule = 'nonzero' | 'evenodd';
+/** Affine transform [a, b, c, d, e, f]: x' = a x + c y + e, y' = b x + d y + f. */
+export type Mat = [number, number, number, number, number, number];
+export declare const IDENTITY: Mat;
+export declare const mul: (m: Mat, n: Mat) => Mat;
+export declare const translate: (x: number, y: number) => Mat;
+export declare const scale: (sx: number, sy?: number) => Mat;
+/** Flatten a path to polygons in its own units. Arcs and curves get enough segments to stay smooth at 8× zoom. */
+export declare function parsePath(d: string): Poly[];
+/** A rounded rectangle centred on (cx, cy), as a polygon. */
+export declare function roundRect(cx: number, cy: number, w: number, h: number, r: number): Poly;
+export declare function circle(cx: number, cy: number, r: number, reverse?: boolean): Poly;
+export interface Color {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function hex(h: string): Color;
+export declare const mix: (a: Color, b: Color, t: number) => Color;
+/** Premultiplied linear RGBA. */
+export declare class Canvas {
+    readonly width: number;
+    readonly height: number;
+    readonly samples: number;
+    readonly data: Float32Array;
+    constructor(width: number, height: number, samples?: number);
+    /** Fill polygons (already in pixel space after `m`) with a colour at opacity `alpha`. */
+    fill(polys: Poly[], color: Color, m?: Mat, rule?: Rule, alpha?: number): this;
+    /** Per-pixel coverage 0..1 of the polygons, S×S samples a pixel, crossings found once per sample row. */
+    coverage(polys: Poly[], rule: Rule): Float32Array;
+    /** The pixel as straight sRGB and alpha. */
+    pixel(x: number, y: number): {
+        c: Color;
+        a: number;
+    };
+}

package/dist/onboard/raster.js

@@ -0,0 +1,253 @@
+/**
+ * A tiny vector rasterizer: SVG paths (M L H V Q A Z, absolute and relative) flattened to polygons, filled with
+ * analytic-quality anti-aliasing by supersampling scanlines (S×S samples a pixel, crossings sorted once a row).
+ * The canvas is premultiplied linear-light RGBA, so blended edges come out the way a browser draws the same SVG.
+ */
+export const IDENTITY = [1, 0, 0, 1, 0, 0];
+export const mul = (m, n) => [
+    m[0] * n[0] + m[2] * n[1], m[1] * n[0] + m[3] * n[1],
+    m[0] * n[2] + m[2] * n[3], m[1] * n[2] + m[3] * n[3],
+    m[0] * n[4] + m[2] * n[5] + m[4], m[1] * n[4] + m[3] * n[5] + m[5],
+];
+export const translate = (x, y) => [1, 0, 0, 1, x, y];
+export const scale = (sx, sy = sx) => [sx, 0, 0, sy, 0, 0];
+const cache = new Map();
+/** Flatten a path to polygons in its own units. Arcs and curves get enough segments to stay smooth at 8× zoom. */
+export function parsePath(d) {
+    const hit = cache.get(d);
+    if (hit)
+        return hit;
+    const tokens = d.match(/[a-zA-Z]|-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/g) ?? [];
+    const polys = [];
+    let cur = [];
+    let i = 0, cmd = '', x = 0, y = 0, sx = 0, sy = 0;
+    const num = () => Number(tokens[i++]);
+    const close = () => { if (cur.length > 2)
+        polys.push(cur); cur = []; };
+    while (i < tokens.length) {
+        if (/[a-zA-Z]/.test(tokens[i]))
+            cmd = tokens[i++];
+        const rel = cmd === cmd.toLowerCase();
+        switch (cmd.toUpperCase()) {
+            case 'M': {
+                close();
+                const nx = num(), ny = num();
+                x = rel ? x + nx : nx;
+                y = rel ? y + ny : ny;
+                sx = x;
+                sy = y;
+                cur.push([x, y]);
+                cmd = rel ? 'l' : 'L';
+                break;
+            }
+            case 'L': {
+                const nx = num(), ny = num();
+                x = rel ? x + nx : nx;
+                y = rel ? y + ny : ny;
+                cur.push([x, y]);
+                break;
+            }
+            case 'H': {
+                const nx = num();
+                x = rel ? x + nx : nx;
+                cur.push([x, y]);
+                break;
+            }
+            case 'V': {
+                const ny = num();
+                y = rel ? y + ny : ny;
+                cur.push([x, y]);
+                break;
+            }
+            case 'Q': {
+                let cx = num(), cy = num(), ex = num(), ey = num();
+                if (rel) {
+                    cx += x;
+                    cy += y;
+                    ex += x;
+                    ey += y;
+                }
+                for (let k = 1; k <= 12; k++) {
+                    const t = k / 12, u = 1 - t;
+                    cur.push([u * u * x + 2 * u * t * cx + t * t * ex, u * u * y + 2 * u * t * cy + t * t * ey]);
+                }
+                x = ex;
+                y = ey;
+                break;
+            }
+            case 'A': {
+                const rx = num(), ry = num(), rot = num(), large = num(), sweep = num();
+                let ex = num(), ey = num();
+                if (rel) {
+                    ex += x;
+                    ey += y;
+                }
+                cur.push(...arc(x, y, rx, ry, rot, large, sweep, ex, ey));
+                x = ex;
+                y = ey;
+                break;
+            }
+            case 'Z': {
+                x = sx;
+                y = sy;
+                close();
+                break;
+            }
+            default: i++; // unknown token: skip rather than loop forever
+        }
+    }
+    close();
+    cache.set(d, polys);
+    return polys;
+}
+/** SVG endpoint arc → points (SVG 1.1 F.6.5), excluding the start point. */
+function arc(x1, y1, rx, ry, rotDeg, large, sweep, x2, y2) {
+    if (rx === 0 || ry === 0)
+        return [[x2, y2]];
+    const phi = (rotDeg * Math.PI) / 180, cos = Math.cos(phi), sin = Math.sin(phi);
+    const dx = (x1 - x2) / 2, dy = (y1 - y2) / 2;
+    const x1p = cos * dx + sin * dy, y1p = -sin * dx + cos * dy;
+    rx = Math.abs(rx);
+    ry = Math.abs(ry);
+    const lambda = (x1p * x1p) / (rx * rx) + (y1p * y1p) / (ry * ry);
+    if (lambda > 1) {
+        rx *= Math.sqrt(lambda);
+        ry *= Math.sqrt(lambda);
+    }
+    const num = rx * rx * ry * ry - rx * rx * y1p * y1p - ry * ry * x1p * x1p;
+    const den = rx * rx * y1p * y1p + ry * ry * x1p * x1p;
+    const coef = (large === sweep ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+    const cxp = (coef * rx * y1p) / ry, cyp = (-coef * ry * x1p) / rx;
+    const cx = cos * cxp - sin * cyp + (x1 + x2) / 2, cy = sin * cxp + cos * cyp + (y1 + y2) / 2;
+    const ang = (ux, uy, vx, vy) => Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+    const t1 = ang(1, 0, (x1p - cxp) / rx, (y1p - cyp) / ry);
+    let dt = ang((x1p - cxp) / rx, (y1p - cyp) / ry, (-x1p - cxp) / rx, (-y1p - cyp) / ry);
+    if (!sweep && dt > 0)
+        dt -= 2 * Math.PI;
+    else if (sweep && dt < 0)
+        dt += 2 * Math.PI;
+    const n = Math.max(4, Math.ceil(Math.abs(dt) / (Math.PI / 48)));
+    const pts = [];
+    for (let k = 1; k <= n; k++) {
+        const t = t1 + (dt * k) / n;
+        pts.push([cx + rx * Math.cos(t) * cos - ry * Math.sin(t) * sin, cy + rx * Math.cos(t) * sin + ry * Math.sin(t) * cos]);
+    }
+    pts[pts.length - 1] = [x2, y2];
+    return pts;
+}
+/** A rounded rectangle centred on (cx, cy), as a polygon. */
+export function roundRect(cx, cy, w, h, r) {
+    r = Math.max(0, Math.min(r, w / 2, h / 2));
+    const pts = [], seg = 6;
+    const corner = (ox, oy, a0) => {
+        for (let k = 0; k <= seg; k++) {
+            const a = a0 + (k / seg) * (Math.PI / 2);
+            pts.push([ox + r * Math.cos(a), oy + r * Math.sin(a)]);
+        }
+    };
+    corner(cx + w / 2 - r, cy - h / 2 + r, -Math.PI / 2);
+    corner(cx + w / 2 - r, cy + h / 2 - r, 0);
+    corner(cx - w / 2 + r, cy + h / 2 - r, Math.PI / 2);
+    corner(cx - w / 2 + r, cy - h / 2 + r, Math.PI);
+    return pts;
+}
+export function circle(cx, cy, r, reverse = false) {
+    const n = Math.max(24, Math.ceil(r * 6)), pts = [];
+    for (let k = 0; k < n; k++) {
+        const a = ((reverse ? -k : k) / n) * Math.PI * 2;
+        pts.push([cx + r * Math.sin(a), cy - r * Math.cos(a)]);
+    }
+    return pts;
+}
+export function hex(h) {
+    const v = Number.parseInt(h.replace('#', ''), 16);
+    return { r: (v >> 16) & 255, g: (v >> 8) & 255, b: v & 255 };
+}
+const toLin = (c) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+const toSrgb = (l) => Math.round(255 * (l <= 0.0031308 ? l * 12.92 : 1.055 * l ** (1 / 2.4) - 0.055));
+export const mix = (a, b, t) => ({
+    r: toSrgb(toLin(a.r) + (toLin(b.r) - toLin(a.r)) * t), g: toSrgb(toLin(a.g) + (toLin(b.g) - toLin(a.g)) * t), b: toSrgb(toLin(a.b) + (toLin(b.b) - toLin(a.b)) * t),
+});
+/** Premultiplied linear RGBA. */
+export class Canvas {
+    width;
+    height;
+    samples;
+    data;
+    constructor(width, height, samples = 4) {
+        this.width = width;
+        this.height = height;
+        this.samples = samples;
+        this.data = new Float32Array(width * height * 4);
+    }
+    /** Fill polygons (already in pixel space after `m`) with a colour at opacity `alpha`. */
+    fill(polys, color, m = IDENTITY, rule = 'nonzero', alpha = 1) {
+        const cov = this.coverage(polys.map((p) => p.map(([x, y]) => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]])), rule);
+        const lr = toLin(color.r), lg = toLin(color.g), lb = toLin(color.b);
+        for (let i = 0; i < cov.length; i++) {
+            const a = cov[i] * alpha;
+            if (a <= 0)
+                continue;
+            const o = i * 4, k = 1 - a;
+            this.data[o] = lr * a + this.data[o] * k;
+            this.data[o + 1] = lg * a + this.data[o + 1] * k;
+            this.data[o + 2] = lb * a + this.data[o + 2] * k;
+            this.data[o + 3] = a + this.data[o + 3] * k;
+        }
+        return this;
+    }
+    /** Per-pixel coverage 0..1 of the polygons, S×S samples a pixel, crossings found once per sample row. */
+    coverage(polys, rule) {
+        const { width: W, height: H, samples: S } = this;
+        const out = new Float32Array(W * H);
+        const edges = [];
+        let minY = Infinity, maxY = -Infinity;
+        for (const p of polys)
+            for (let k = 0; k < p.length; k++) {
+                const [x0, y0] = p[k], [x1, y1] = p[(k + 1) % p.length];
+                if (y0 === y1)
+                    continue;
+                edges.push(y0 < y1 ? [x0, y0, x1, y1, 1] : [x1, y1, x0, y0, -1]);
+                minY = Math.min(minY, y0, y1);
+                maxY = Math.max(maxY, y0, y1);
+            }
+        if (!edges.length)
+            return out;
+        const inc = 1 / (S * S);
+        const y0 = Math.max(0, Math.floor(minY * S)), y1 = Math.min(H * S - 1, Math.ceil(maxY * S));
+        const xs = [];
+        for (let sy = y0; sy <= y1; sy++) {
+            const yy = (sy + 0.5) / S;
+            xs.length = 0;
+            for (const [ax, ay, bx, by, w] of edges)
+                if (yy >= ay && yy < by)
+                    xs.push([ax + ((yy - ay) / (by - ay)) * (bx - ax), w]);
+            if (xs.length < 2)
+                continue;
+            xs.sort((a, b) => a[0] - b[0]);
+            const row = Math.floor(sy / S) * W;
+            let wind = 0;
+            for (let k = 0; k < xs.length - 1; k++) {
+                wind += xs[k][1];
+                const inside = rule === 'evenodd' ? (k + 1) % 2 === 1 : wind !== 0;
+                if (!inside)
+                    continue;
+                // samples sx with centre (sx+.5)/S in [xs[k], xs[k+1])
+                const from = Math.max(0, Math.ceil(xs[k][0] * S - 0.5)), to = Math.min(W * S - 1, Math.ceil(xs[k + 1][0] * S - 0.5) - 1);
+                for (let sx = from; sx <= to; sx++)
+                    out[row + Math.floor(sx / S)] += inc;
+            }
+        }
+        for (let i = 0; i < out.length; i++)
+            if (out[i] > 1)
+                out[i] = 1;
+        return out;
+    }
+    /** The pixel as straight sRGB and alpha. */
+    pixel(x, y) {
+        const o = (y * this.width + x) * 4, a = this.data[o + 3];
+        if (a <= 1e-4)
+            return { c: { r: 0, g: 0, b: 0 }, a: 0 };
+        return { c: { r: toSrgb(this.data[o] / a), g: toSrgb(this.data[o + 1] / a), b: toSrgb(this.data[o + 2] / a) }, a: Math.min(1, a) };
+    }
+}

package/dist/onboard/sound.d.ts

@@ -0,0 +1,2 @@
+export declare function chime(rate?: number): Buffer;
+export declare function play(): Promise<void>;

package/dist/onboard/sound.js

@@ -0,0 +1,54 @@
+/**
+ * The one sound setup can make, only with --sound or GENESIS_SOUND=1: a soft two-note chime (a fifth, 660 → 990 Hz)
+ * synthesised here as a 0.5 s WAV and played by the system's own player (afplay, paplay or aplay). If none is
+ * present, there is simply no sound.
+ */
+import { execFile } from 'node:child_process';
+import { writeFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export function chime(rate = 22050) {
+    const n = Math.floor(rate * 0.55), data = Buffer.alloc(n * 2);
+    for (let i = 0; i < n; i++) {
+        const t = i / rate;
+        const note = (f, at) => { const u = t - at; if (u < 0)
+            return 0; const env = Math.min(1, u / 0.006) * Math.exp(-u * 7); return env * (Math.sin(2 * Math.PI * f * u) + 0.18 * Math.sin(4 * Math.PI * f * u)); };
+        const v = 0.16 * (note(660, 0) + 0.85 * note(990, 0.09));
+        data.writeInt16LE(Math.max(-32767, Math.min(32767, Math.round(v * 32767))), i * 2);
+    }
+    const h = Buffer.alloc(44);
+    h.write('RIFF', 0);
+    h.writeUInt32LE(36 + data.length, 4);
+    h.write('WAVE', 8);
+    h.write('fmt ', 12);
+    h.writeUInt32LE(16, 16);
+    h.writeUInt16LE(1, 20);
+    h.writeUInt16LE(1, 22);
+    h.writeUInt32LE(rate, 24);
+    h.writeUInt32LE(rate * 2, 28);
+    h.writeUInt16LE(2, 32);
+    h.writeUInt16LE(16, 34);
+    h.write('data', 36);
+    h.writeUInt32LE(data.length, 40);
+    return Buffer.concat([h, data]);
+}
+export async function play() {
+    const file = join(tmpdir(), `genesis-chime-${process.pid}.wav`);
+    try {
+        await writeFile(file, chime());
+        const players = process.platform === 'darwin' ? [['afplay', [file]]] : [['paplay', [file]], ['aplay', ['-q', file]]];
+        for (const [cmd, args] of players) {
+            const ok = await new Promise((r) => { try {
+                execFile(cmd, args, { timeout: 3000 }, (e) => r(!e));
+            }
+            catch {
+                r(false);
+            } });
+            if (ok)
+                break;
+        }
+    }
+    finally {
+        await unlink(file).catch(() => { });
+    }
+}

package/dist/onboard/state.d.ts

@@ -0,0 +1,24 @@
+export declare const STEPS: readonly ["signin", "context", "key", "mcp", "try", "next"];
+export type StepId = typeof STEPS[number];
+export type StepState = 'done' | 'skipped';
+export interface SetupState {
+    version: 1;
+    steps: Partial<Record<StepId, {
+        state: StepState;
+        at: string;
+        note?: string;
+    }>>;
+    welcomed?: string;
+}
+export declare function configDir(env: Record<string, string | undefined>, platform?: NodeJS.Platform, home?: string): string;
+export declare class SetupStore {
+    readonly path: string;
+    constructor(path: string);
+    static for(env: Record<string, string | undefined>): SetupStore;
+    read(): Promise<SetupState>;
+    write(s: SetupState): Promise<void>;
+    mark(step: StepId, state: StepState, note?: string): Promise<void>;
+}
+/** The first step not yet done (skipped steps are offered again), or null when setup is complete. */
+export declare function nextStep(s: SetupState): StepId | null;
+export declare const complete: (s: SetupState) => boolean;

package/dist/onboard/state.js

@@ -0,0 +1,48 @@
+/**
+ * Where setup is up to, so it can stop at any step and pick up there: a small JSON file in the user's config dir
+ * (XDG_CONFIG_HOME/genesis, ~/.config/genesis, or %APPDATA%\genesis). It never holds a credential; the login stays
+ * in the OS keychain and an API key is shown once or kept in Blinds.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const STEPS = ['signin', 'context', 'key', 'mcp', 'try', 'next'];
+export function configDir(env, platform = process.platform, home = homedir()) {
+    if (env.GENESIS_CONFIG_DIR)
+        return env.GENESIS_CONFIG_DIR;
+    if (platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, 'genesis');
+    return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'genesis');
+}
+export class SetupStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    static for(env) { return new SetupStore(join(configDir(env), 'setup.json')); }
+    async read() {
+        try {
+            const v = JSON.parse(await readFile(this.path, 'utf8'));
+            if (v && v.version === 1 && v.steps && typeof v.steps === 'object')
+                return v;
+        }
+        catch { /* first run, or unreadable: start fresh */ }
+        return { version: 1, steps: {} };
+    }
+    async write(s) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(s, null, 2) + '\n', { mode: 0o600 });
+        await rename(tmp, this.path);
+    }
+    async mark(step, state, note) {
+        const s = await this.read();
+        s.steps[step] = { state, at: new Date().toISOString(), ...(note ? { note } : {}) };
+        await this.write(s);
+    }
+}
+/** The first step not yet done (skipped steps are offered again), or null when setup is complete. */
+export function nextStep(s) {
+    return STEPS.find((id) => s.steps[id]?.state !== 'done') ?? null;
+}
+export const complete = (s) => STEPS.every((id) => s.steps[id]);

package/dist/onboard/term.d.ts

@@ -0,0 +1,69 @@
+import type { Caps } from './caps.js';
+export declare const strip: (s: string) => string;
+/** Display width: wide East Asian and emoji count two. Enough for our own copy and server names passed through safe(). */
+export declare function width(s: string): number;
+export type Key = {
+    name: string;
+    ch?: string;
+    ctrl?: boolean;
+};
+export declare function parseKeys(data: string): Key[];
+export declare class Interrupted extends Error {
+    constructor();
+}
+export declare class Term {
+    readonly caps: Caps;
+    readonly stdout: NodeJS.WriteStream;
+    readonly stdin: NodeJS.ReadStream;
+    private live;
+    private liveWidth;
+    private liveEmpty;
+    private cleanups;
+    private keyWaiters;
+    private onData;
+    /** Every line setup draws sits two columns in from the edge; a step's own lines sit four in, under its header. */
+    margin: string;
+    focused: boolean;
+    focusListeners: Set<(focused: boolean) => void>;
+    /** Ctrl-C while nothing reads keys (a network wait). Setup replaces it to say where it will pick up. */
+    onInterrupt: () => void;
+    private restored;
+    constructor(caps: Caps, stdout: NodeJS.WriteStream, stdin: NodeJS.ReadStream);
+    write(s: string): void;
+    get columns(): number;
+    /** Start the session: raw keys, focus events, bracketed paste, hidden cursor, our title pushed onto the stack. */
+    start(title: string): void;
+    title(t: string): void;
+    /** Tab/taskbar progress (OSC 9;4): 0 hidden, 1 value, 3 indeterminate. */
+    progress(state: 0 | 1 | 3, value?: number): void;
+    /** A desktop notification, only when the window is not in front (the user went to the browser). */
+    notify(title: string, body: string): void;
+    /** DECSCUSR: 6 steady bar (the emblem's bar as the caret), 0 the user's default. */
+    cursorShape(n: 0 | 2 | 6): void;
+    cursor(show: boolean): void;
+    /** OSC 8 where the terminal supports it; elsewhere the label and the address, so the URL is never hidden. */
+    link(url: string, text?: string): string;
+    /**
+     * 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: string[]): void;
+    /** Freeze the live region into scrollback; the next frame starts below it. */
+    commit(): void;
+    /** Plain append, for screen readers and still mode: never rewrites what was said. */
+    say(line?: string): void;
+    /** In screencast mode, every identifier (h_…, o_…, w_…, pr_…, sess_…, keys) and email that setup prints is masked. */
+    mask(line: string): string;
+    private dispatch;
+    /** The next key; Ctrl-C rejects with Interrupted so every step can stop cleanly and be resumed. */
+    key(signal?: AbortSignal): Promise<Key>;
+    /** Any pending key, without waiting (for "press any key to skip" during animations). */
+    pollKey(): Promise<Key>;
+    restore(): void;
+}
+/** Masks the text between escape sequences, so an identifier right after a colour code (…m o_…) is still found. */
+export declare function maskIdentifiers(line: string): string;
+/** Clip to `cols` display columns, keeping escape sequences intact and closing any open style and link. */
+export declare function clip(line: string, cols: number): string;
+/** A steady clock: calls `draw(t)` at `fps` until it returns false, sleeping the remainder of each frame. */
+export declare function animate(fps: number, draw: (t: number) => boolean | Promise<boolean>, signal?: AbortSignal): Promise<void>;