@onesi/genesis-cli 0.1.13 → 0.2.0

package/dist/onboard/index.js

@@ -0,0 +1,562 @@
+/**
+ * `genesis setup`: from a fresh install to a live call in about a minute. Six steps, each skippable and resumable:
+ * sign in with One, pick the organization, project and environment, optionally create a scoped API key, put the MCP
+ * server into your agents, make a first live call, and see what to do next.
+ *
+ * Loaded only by `genesis setup` and a bare `genesis` on a terminal (dynamic import in ../index.ts), so no other
+ * command pays for any of it. `--json`, pipes and CI never animate and never prompt.
+ */
+import { hostname } from 'node:os';
+import { spawn } from 'node:child_process';
+import { safe } from '../output.js';
+import { detect, probe, systemPreferences } from './caps.js';
+import { Term, Interrupted } from './term.js';
+import { Style, welcome, select, confirm, input, pick, waitBeside, delight, busy, typeLines } from './ui.js';
+import { SetupStore, STEPS, nextStep } from './state.js';
+import { defaultMcpEnv, detectClients, install, MCP_PACKAGE } from './mcp.js';
+import { play } from './sound.js';
+const TITLES = { signin: 'Sign in', context: 'Organization and project', key: 'API key', mcp: 'Your agents', try: 'First live call', next: 'Next' };
+const COMMANDS = {
+    signin: 'genesis login', context: 'genesis context select --organization <o_…> --workspace <w_…> --project <pr_…>',
+    key: 'genesis keys create <name> --scopes hives:read', mcp: `claude mcp add genesis -- npx -y ${MCP_PACKAGE}`, try: 'genesis status', next: 'genesis --help',
+};
+export async function capsFor(d) {
+    const stdout = d.stdout ?? process.stdout, stdin = d.stdin ?? process.stdin;
+    let caps = detect({ env: d.env, stdoutTTY: !!stdout.isTTY && !d.flags.json, stdinTTY: !!stdin.isTTY, columns: stdout.columns, rows: stdout.rows,
+        flags: { animation: d.flags.animation, screenReader: d.flags.screenReader, sound: d.flags.sound, screencast: d.flags.screencast } });
+    if (!caps.interactive || d.flags.probe === false)
+        return caps;
+    const [probed, prefs] = await Promise.all([probe(caps, { stdin, stdout }), systemPreferences()]);
+    caps = probed;
+    // GENESIS_SETUP_TRACE=<file>: what was detected and why, for bug reports (never secrets: only terminal facts).
+    if (d.env.GENESIS_SETUP_TRACE)
+        await import('node:fs/promises').then((fs) => fs.writeFile(d.env.GENESIS_SETUP_TRACE, JSON.stringify({ caps, prefs }, null, 2))).catch(() => { });
+    if (prefs.screenReader)
+        caps = { ...caps, screenReader: true, motion: false, stillBecause: caps.stillBecause ?? 'screen reader' };
+    if (prefs.reducedMotion)
+        caps = { ...caps, motion: false, stillBecause: caps.stillBecause ?? 'reduced motion (system setting)' };
+    return caps;
+}
+export async function runSetup(d) {
+    const setup = SetupStore.for(d.env);
+    if (d.flags.restart)
+        await setup.write({ version: 1, steps: {} });
+    const state = await setup.read();
+    const only = d.flags.step;
+    if (only && !STEPS.includes(only))
+        throw new Error(`Unknown setup step "${safe(only)}". Steps: ${STEPS.join(', ')}.`);
+    // --json: where setup is up to, for scripts. Never prompts, never draws.
+    if (d.flags.json) {
+        d.log(JSON.stringify({ config: setup.path, next: nextStep(state), steps: STEPS.map((id) => ({ id, title: TITLES[id], ...(state.steps[id] ?? { state: 'pending' }), command: COMMANDS[id] })) }, null, 2));
+        return 0;
+    }
+    const caps = await capsFor(d);
+    if (!caps.interactive) {
+        // A pipe or CI: say what setup would do, as commands, and change nothing.
+        d.log('Genesis setup needs an interactive terminal. In scripts and CI, use an API key (GENESIS_API_KEY) and these commands:');
+        for (const id of STEPS)
+            d.log(`  ${state.steps[id]?.state === 'done' ? 'done   ' : 'pending'}  ${TITLES[id].padEnd(25)} ${COMMANDS[id]}`);
+        return 0;
+    }
+    const term = new Term(caps, d.stdout ?? process.stdout, d.stdin ?? process.stdin);
+    const style = new Style(term);
+    term.start('Genesis · setup');
+    term.onInterrupt = () => {
+        void setup.read().then((s) => {
+            term.say();
+            term.margin = '  ';
+            term.say(style.muted(`Paused. Run ${style.bold('genesis setup')} to pick up at ${TITLES[nextStep(s) ?? 'signin'].toLowerCase()}.`));
+        }).finally(() => { term.restore(); process.exit(130); });
+    };
+    try {
+        if (!only) {
+            await welcome(term, style, { short: !!state.welcomed, seed: d.seed ?? (d.env.GENESIS_DEMO_SEED ? Number(d.env.GENESIS_DEMO_SEED) : undefined), tagline: [
+                    `${style.bold('Genesis')}  ${style.muted('the developer tools for OneOS')}`,
+                    style.muted(`Six steps, about a minute. Enter takes the default, s skips, Ctrl-C pauses.`),
+                ] });
+            await setup.write({ ...(await setup.read()), welcomed: state.welcomed ?? new Date().toISOString() });
+        }
+        const order = only ? [only] : STEPS.filter((id) => state.steps[id]?.state !== 'done');
+        if (!order.length) {
+            term.say(`${style.check} ${style.bold('Setup is complete.')} ${style.muted('Redo a step with genesis setup <step>: ' + STEPS.join(', ') + '.')}`);
+            return 0;
+        }
+        const ctx = new Steps(d, term, style, setup);
+        for (const id of order) {
+            const n = STEPS.indexOf(id) + 1;
+            term.progress(1, ((n - 1) / STEPS.length) * 100);
+            term.title(`Genesis · ${TITLES[id]}`);
+            term.say();
+            term.margin = '  ';
+            term.say(`${style.muted(`${n}/${STEPS.length}`)}  ${style.bold(TITLES[id])}`);
+            term.margin = '    ';
+            let result;
+            try {
+                result = await ctx[id]();
+            }
+            catch (e) {
+                if (e instanceof Interrupted)
+                    throw e;
+                // One step failing never ends setup: say why, keep it for next time, and carry on.
+                term.say(`${style.error(caps.unicode ? '✗' : 'x')} ${safe(e.message)}`);
+                term.say(style.muted(`This step stays open; run genesis setup ${id} to try it again.`));
+                result = { state: 'skipped', note: 'failed' };
+            }
+            await setup.mark(id, result.state, result.note);
+            term.margin = '  ';
+        }
+        term.progress(1, 100);
+        if (!only) {
+            term.say();
+            await delight(term, style, `${style.bold("You're set.")} ${style.muted('Build something.')}`);
+            if (caps.sound)
+                await play();
+        }
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof Interrupted) {
+            const s = await setup.read();
+            term.say();
+            term.margin = '  ';
+            term.say(style.muted(`Paused. Run ${style.bold('genesis setup')} to pick up at ${TITLES[nextStep(s) ?? 'signin'].toLowerCase()}.`));
+            return 130;
+        }
+        throw e;
+    }
+    finally {
+        term.restore();
+    }
+}
+class Steps {
+    d;
+    term;
+    style;
+    setup;
+    store;
+    lastKey;
+    constructor(d, term, style, setup) {
+        this.d = d;
+        this.term = term;
+        this.style = style;
+        this.setup = setup;
+    }
+    async getStore() { return (this.store ??= await this.d.getStore()); }
+    /** A name from the account (an organization, project or workspace), masked to its length in screencast mode. */
+    nameOf(v) {
+        // A fixed width, so the mask says nothing about the name's length.
+        return this.term.caps.screencast ? '••••••' : safe(v.name ?? v.id);
+    }
+    ok(line) { this.term.say(`${this.style.check} ${line}`); }
+    note(line) { this.term.say(this.style.muted(line)); }
+    // ── 1. sign in ──
+    async signin() {
+        const { term, style, d } = this;
+        let store;
+        try {
+            store = await this.getStore();
+        }
+        catch (e) {
+            this.note(`${safe(e.message)}`);
+            return { state: 'skipped', note: 'keychain unavailable' };
+        }
+        const saved = await store.get();
+        if (saved) {
+            const who = await busy(term, style, 'Checking your saved sign-in', (async () => (await d.client()).whoami())().catch(() => null));
+            if (who) {
+                const name = this.term.mask(safe(saved.user?.email ?? saved.user?.id ?? who.principal ?? 'you'));
+                const keep = await select(term, style, { title: `Signed in as ${name}.`, options: [
+                        { label: 'Keep this sign-in', value: true }, { label: 'Sign in as someone else', value: false }
+                    ] });
+                if (keep !== false)
+                    return { state: 'done' };
+            }
+            else
+                this.note('Your saved sign-in has expired. Sign in again:');
+        }
+        const remote = !!(d.env.SSH_CONNECTION || d.env.SSH_TTY) || (process.platform === 'linux' && !d.env.DISPLAY && !d.env.WAYLAND_DISPLAY);
+        const how = await select(term, style, { title: 'How do you want to sign in with One?', skippable: true, initial: remote ? 1 : 0, options: [
+                { label: 'In this browser', value: 'browser', hint: remote ? 'this looks like a remote machine' : undefined },
+                { label: 'With a code, on any device', value: 'device' },
+            ] });
+        if (how === 'skip')
+            return { state: 'skipped' };
+        const s = how === 'browser' ? await this.browserLogin() : await this.deviceLogin();
+        if (!s)
+            return { state: 'skipped' };
+        await store.set(s);
+        const who = safe(s.user?.email ?? s.user?.id ?? 'you');
+        term.notify('Genesis', `Signed in as ${term.mask(who)}`);
+        await delight(term, style, `Signed in as ${style.bold(who)}`);
+        if (term.caps.sound)
+            void play();
+        return { state: 'done' };
+    }
+    async browserLogin() {
+        const { term, style, d } = this;
+        const attempt = await d.login.startLogin(d.auth, {});
+        try {
+            d.openBrowser(attempt.browserUrl);
+            const done = d.login.completeLogin(d.auth, attempt);
+            done.catch(() => { });
+            let copied = false;
+            for (;;) {
+                const r = await waitBeside(term, style, () => [
+                    style.bold('Finish signing in with One in your browser.'),
+                    `${term.link(attempt.browserUrl, 'Open the sign-in page')} ${style.muted('if it did not open')}`,
+                    style.muted(copied ? 'Link copied.  d use a code instead' : 'o open again  c copy the link  d use a code instead'),
+                ], done, ['o', 'c', 'd']);
+                if (r.value)
+                    return r.value;
+                if (r.key?.name === 'o')
+                    d.openBrowser(attempt.browserUrl);
+                if (r.key?.name === 'c')
+                    copied = await copy(attempt.browserUrl);
+                if (r.key?.name === 'd') {
+                    attempt.close();
+                    return this.deviceLogin();
+                }
+            }
+        }
+        finally {
+            attempt.close();
+        }
+    }
+    async deviceLogin() {
+        const { term, style, d } = this;
+        // One signal for the whole device sign-in: leaving this step for any reason (Ctrl-C, an error) stops the polling,
+        // so a paused setup exits at once instead of waiting out the code.
+        const ac = new AbortController();
+        try {
+            const start = await busy(term, style, 'Asking One for a code', d.login.startDeviceLogin(d.auth, ac.signal));
+            const code = safe(start.userCode), uri = safe(start.verificationUri), full = safe(start.verificationUriComplete);
+            // A screencast shows the shape of the code, never the code itself.
+            const shownCode = term.caps.screencast ? code.replace(/[A-Za-z0-9]/g, '•') : code;
+            const done = d.login.completeDeviceLogin(d.auth, start, ac.signal);
+            done.catch(() => { });
+            let copied = false;
+            for (;;) {
+                const r = await waitBeside(term, style, () => [
+                    `On any device, open ${term.link(full, style.bold(uri))}`,
+                    `and enter ${style.bold(shownCode.split('').join(term.caps.screenReader ? ' ' : ''))}`,
+                    style.muted(copied ? 'Code copied.  o open it here' : `o open it here  c copy the code  ${Math.round(start.expiresIn / 60)} min to approve`),
+                ], done, ['o', 'c']);
+                if (r.value)
+                    return r.value;
+                if (r.key?.name === 'o')
+                    d.openBrowser(full);
+                if (r.key?.name === 'c')
+                    copied = await copy(code);
+            }
+        }
+        finally {
+            ac.abort();
+        }
+    }
+    // ── 2. organization, project, environment ──
+    async context() {
+        const { term, style, d } = this;
+        const store = await this.getStore().catch(() => undefined);
+        const saved = await store?.get();
+        if (!store || !saved) {
+            this.note('Sign in first; this step comes back next time.');
+            return { state: 'skipped' };
+        }
+        const token = () => d.login.savedLoginProvider(d.auth, store)().then((t) => t ?? '');
+        const iam = new Iam(secureUrl(d.env.GENESIS_IAM_URL ?? 'https://iam.l1fe.ai', 'GENESIS_IAM_URL'), d.fetch, token);
+        const orgs = await busy(term, style, 'Finding your organizations', iam.list('/v4/iam/orgs').catch((e) => {
+            this.note(`Your organizations could not be listed (${safe(e.message)}); using the one you signed in to.`);
+            return [];
+        }));
+        const known = orgs.length ? orgs : saved.organization_id ? [{ id: saved.organization_id, name: saved.organization_id }] : [];
+        if (!known.length) {
+            this.note('No organization on this sign-in yet. Create one at ' + term.link('https://os.one.ml', 'os.one.ml') + '.');
+            return { state: 'skipped' };
+        }
+        let org = known.find((o) => o.id === saved.organization_id) ?? known[0];
+        if (known.length > 1) {
+            const chosen = await select(term, style, { title: 'Organization', skippable: true, initial: Math.max(0, known.indexOf(org)),
+                options: known.map((o) => ({ label: this.nameOf(o), value: o, hint: safe(o.id) })) });
+            if (chosen === 'skip')
+                return { state: 'skipped' };
+            org = chosen;
+        }
+        else
+            this.ok(`Organization  ${style.bold(this.nameOf(org))} ${style.muted(safe(org.id))}`);
+        if (org.id !== saved.organization_id)
+            await busy(term, style, 'Switching organization', d.login.selectSavedContext(d.auth, store, { organizationId: org.id }));
+        const lists = async () => Promise.all([iam.list(`/v4/iam/orgs/${encodeURIComponent(org.id)}/projects`), iam.list(`/v4/iam/orgs/${encodeURIComponent(org.id)}/workspaces`)]);
+        let projects = [], workspaces = [];
+        try {
+            [projects, workspaces] = await busy(term, style, 'Reading projects', lists().catch(async (e) => {
+                // A sign-in with no tenant bound yet: bind the organization, then read again.
+                if (!(e instanceof IamError) || e.status >= 500)
+                    throw e;
+                await d.login.selectSavedContext(d.auth, store, { organizationId: org.id });
+                return lists();
+            }));
+        }
+        catch (e) {
+            this.note(`Projects could not be read (${safe(e.message)}). Choose one later with:`);
+            this.note(COMMANDS.context);
+            return { state: 'skipped', note: 'iam unavailable' };
+        }
+        projects = projects.filter((p) => /^pr_[A-Za-z0-9_-]+$/.test(p.id));
+        if (!projects.length) {
+            this.note(`No projects in ${this.nameOf(org)} yet. Create one in the ${term.link('https://os.one.ml', 'Console')}, then run genesis setup context.`);
+            return { state: 'skipped', note: 'no projects' };
+        }
+        let project = projects[0];
+        if (projects.length > 1) {
+            const chosen = await select(term, style, { title: 'Project', skippable: true, options: projects.map((p) => ({ label: this.nameOf(p), value: p, hint: safe(p.id) })) });
+            if (chosen === 'skip')
+                return { state: 'skipped' };
+            project = chosen;
+        }
+        else
+            this.ok(`Project  ${style.bold(this.nameOf(project))} ${style.muted(safe(project.id))}`);
+        const valid = workspaces.filter((w) => /^w_[A-Za-z0-9_-]+$/.test(w.id));
+        const mine = valid.filter((w) => (w.project_id ?? w.projectId ?? project.id) === project.id);
+        const pool = mine.length ? mine : valid;
+        if (!pool.length) {
+            this.note('This project has no workspace yet. Create one in the Console, then run genesis setup context.');
+            return { state: 'skipped', note: 'no workspace' };
+        }
+        let ws = pool[0];
+        if (pool.length > 1) {
+            const chosen = await select(term, style, { title: 'Workspace', skippable: true, options: pool.map((w) => ({ label: this.nameOf(w), value: w, hint: safe(w.id) })) });
+            if (chosen === 'skip')
+                return { state: 'skipped' };
+            ws = chosen;
+        }
+        this.ok(`Environment  ${style.bold('Sandbox')}`);
+        await busy(term, style, 'Binding your sign-in to this project', d.login.selectSavedContext(d.auth, store, {
+            organizationId: org.id, workspaceId: ws.id, projectId: project.id, platformId: 'pf_console', fleetId: null, environmentId: 'sandbox'
+        }));
+        this.ok(`Using ${style.bold(this.nameOf(project))} ${style.muted('/')} ${this.nameOf(ws)} ${style.muted('/ Sandbox')}`);
+        return { state: 'done', note: `${org.id} ${ws.id} ${project.id}` };
+    }
+    // ── 3. API key ──
+    async key() {
+        const { term, style, d } = this;
+        this.note('Your sign-in already works here. A key is for CI, servers and other machines.');
+        if (!(await confirm(term, style, 'Create an API key now?', false)))
+            return { state: 'done', note: 'declined' };
+        const name = await input(term, style, { label: 'Name', initial: `${hostname().split('.')[0].toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'my'}-genesis`,
+            validate: (v) => /^[\w .-]{1,64}$/.test(v) ? null : 'Use up to 64 letters, numbers, spaces, dots, dashes or underscores.' });
+        const access = await select(term, style, { title: 'Access', options: [
+                { label: 'Read only', value: 'read', hint: 'hives, traces, beacons, flocks, fleets, …' },
+                { label: 'Same as you', value: 'all', hint: 'every scope your sign-in has' },
+                { label: 'Choose scopes', value: 'custom' },
+            ] });
+        let scopes;
+        if (access === 'read')
+            scopes = READ_SCOPES;
+        if (access === 'custom')
+            scopes = (await input(term, style, { label: 'Scopes', initial: 'hives:read',
+                validate: (v) => v.split(',').every((x) => /^[a-z]+:(read|write|admin)$/.test(x.trim())) ? null : 'Comma-separated, like hives:read,relays:write.' })).split(',').map((x) => x.trim());
+        const custody = await select(term, style, { title: 'Where should the key live?', options: [
+                { label: 'Show it once', value: 'reveal', hint: 'copy it into your CI secrets' },
+                { label: 'Keep it in Blinds', value: 'blinds', hint: 'nobody, human or agent, ever sees it' },
+            ] });
+        if (access === 'skip' || custody === 'skip')
+            return { state: 'skipped' };
+        const gen = await d.client();
+        const who = await gen.whoami();
+        const k = await busy(term, style, 'Creating the key', gen.keys.create(who.org, { name, custody, ...(scopes ? { scopes } : {}) }));
+        if (custody === 'blinds')
+            this.ok(`Key ${style.bold(safe(k.id))} is in Blinds as ${style.bold(safe(String(k.blinds_credential_ref)))}.`);
+        else if (typeof k.value !== 'string' || !k.value) {
+            this.note(`Key ${safe(k.id)} was created, but its value did not come back. Revoke it with genesis keys revoke ${safe(k.id)} and create another.`);
+            return { state: 'skipped', note: 'no value returned' };
+        }
+        else {
+            this.ok(`Key ${style.bold(safe(k.id))} created. Copy it now; it will not be shown again:`);
+            // Recordings outlive "shown once": a screencast never shows the value; the clipboard still gets it.
+            term.say();
+            term.say(`  ${style.bold(term.caps.screencast ? '•'.repeat(24) : safe(String(k.value)))}`);
+            term.say();
+            if (await confirm(term, style, 'Copy it to the clipboard?', true)) {
+                if (await copy(String(k.value)))
+                    this.note('Copied.');
+            }
+        }
+        this.lastKey = { id: k.id };
+        return { state: 'done', note: k.id };
+    }
+    // ── 4. MCP ──
+    async mcp() {
+        const { term, style, d } = this;
+        const env = d.mcpEnv ?? defaultMcpEnv(d.version);
+        const clients = await busy(term, style, 'Looking for your agents', detectClients(env));
+        const found = clients.filter((c) => c.present);
+        if (!found.length) {
+            this.note('No MCP clients found here. Add Genesis to any client as a stdio server:');
+            this.note(`npx -y ${MCP_PACKAGE}@${d.version}`);
+            return { state: 'done', note: 'no clients' };
+        }
+        const chosen = await pick(term, style, { title: 'Add Genesis to', options: found.map((c) => ({
+                label: c.name, value: c.id, checked: !c.installed, disabled: c.installed, hint: c.installed ? 'already added' : undefined
+            })) });
+        if (!chosen.length)
+            return { state: found.every((c) => c.installed) ? 'done' : 'skipped' };
+        term.say(style.muted('These change:'));
+        for (const id of chosen)
+            term.say(`  ${style.muted(safe(clients.find((c) => c.id === id).target))}`);
+        term.say(style.muted('Each JSON file keeps its other servers and a .genesis-backup copy. It uses your genesis login; no key is written.'));
+        if (!(await confirm(term, style, 'Make these changes?', true)))
+            return { state: 'skipped' };
+        let okAll = true;
+        for (const id of chosen) {
+            const c = clients.find((x) => x.id === id);
+            try {
+                const msg = await busy(term, style, `Adding to ${c.name}`, install(env, id));
+                this.ok(`${style.bold(c.name)} ${style.muted(safe(msg))}`);
+            }
+            catch (e) {
+                okAll = false;
+                term.say(`${style.error('✗')} ${c.name} ${style.muted(safe(e.message))}`);
+            }
+        }
+        if (chosen.includes('claude-desktop'))
+            this.note('Restart Claude Desktop to load it.');
+        return { state: okAll ? 'done' : 'skipped' };
+    }
+    // ── 5. first live call ──
+    async try() {
+        const { term, style, d } = this;
+        term.say(style.muted(`$ genesis status`));
+        const url = `${secureUrl(d.baseUrl, 'base URL').replace(/\/+$/, '')}/v1/status`;
+        const report = await busy(term, style, 'Asking every service how it is', (async () => {
+            const r = await d.fetch(url, { headers: { accept: 'application/json', 'user-agent': `genesis-cli/${d.version} (setup)` }, signal: AbortSignal.timeout(15_000) });
+            if (!r.ok)
+                throw new Error(`HTTP ${r.status}`);
+            return await r.json();
+        })()).catch((e) => { this.note(`The gateway did not answer (${safe(e.message)}). Try genesis status later.`); return null; });
+        if (!report?.services?.length)
+            return { state: 'skipped' };
+        // Only what the gateway is documented to send reaches the terminal: names and states through safe(), latency
+        // only when it is a finite number.
+        const rows = report.services.map((r) => ({ service: String(r.service), state: String(r.state),
+            latency_ms: typeof r.latency_ms === 'number' && Number.isFinite(r.latency_ms) ? Math.round(r.latency_ms) : undefined }));
+        const healthy = (r) => r.state === 'ok' || r.state === 'up';
+        const nameW = Math.max(...rows.map((r) => safe(r.service).length));
+        const msW = Math.max(...rows.map((r) => (r.latency_ms !== undefined ? `${r.latency_ms} ms` : '').length));
+        const stateW = Math.max(0, ...rows.filter((r) => !healthy(r)).map((r) => safe(r.state).length));
+        // Ink for services that answered, muted for the rest with their state; latencies right-aligned.
+        const cell = (r) => {
+            const name = safe(r.service).padEnd(nameW), ms = (r.latency_ms !== undefined ? `${r.latency_ms} ms` : '').padStart(msW);
+            const state = (healthy(r) ? '' : safe(r.state)).padEnd(stateW);
+            return { text: healthy(r) ? `${name}  ${style.muted(ms)}${' '.repeat(stateW ? stateW + 2 : 0)}` : style.muted(`${name}  ${ms}${stateW ? '  ' + state : ''}`),
+                width: nameW + 2 + msW + (stateW ? stateW + 2 : 0) };
+        };
+        // A grid of columns, filled down then across, as wide as the window allows.
+        const cells = rows.map(cell), colW = cells[0].width + 4;
+        const perRow = Math.max(1, Math.min(4, Math.floor((term.columns - 6) / colW)));
+        const height = Math.ceil(cells.length / perRow);
+        const lines = Array.from({ length: height }, (_, y) => Array.from({ length: perRow }, (_, x) => cells[x * height + y]).filter(Boolean)
+            .map((c, i, all) => c.text + (i < all.length - 1 ? ' '.repeat(colW - c.width) : '')).join(''));
+        if (term.caps.motion) {
+            // The rows arrive one after another, 40 ms apart: a live answer, not a printout.
+            for (let i = 0; i < lines.length; i++) {
+                term.frame(lines.slice(0, i + 1));
+                await new Promise((r) => setTimeout(r, 40));
+            }
+            term.commit();
+        }
+        else
+            for (const l of lines)
+                term.say(l);
+        const up = rows.filter(healthy).length;
+        const who = await (async () => (await d.client()).whoami())().catch(() => null);
+        this.ok(`${up} of ${rows.length} services answering${who ? ` ${style.muted(`for ${safe(who.org)}`)}` : ''}`);
+        return { state: 'done' };
+    }
+    // ── 6. next ──
+    async next() {
+        const { term, style } = this;
+        const cmd = (c, what) => `${style.bold(c.padEnd(46))} ${style.muted(what)}`;
+        await typeLines(term, style, [
+            cmd('genesis hives projects create my-app', 'start a project'),
+            cmd('genesis foundry models', 'the models you can call'),
+            cmd('genesis traces search "…" --idempotency-key k1', 'research with evidence'),
+            cmd('genesis --help', 'everything else'),
+        ]);
+        term.say();
+        term.say(`${term.link('https://os.one.ml', 'Console')}  ${style.dot}  ${term.link('https://os.one.ml/docs', 'Docs')}  ${style.dot}  ${style.muted('genesis setup <step> redoes a step')}`);
+        return { state: 'done' };
+    }
+}
+const READ_SCOPES = ['hives:read', 'traces:read', 'beacons:read', 'lanes:read', 'flocks:read', 'flares:read', 'fleets:read', 'gears:read', 'rigs:read', 'runner:read', 'blinds:read'];
+class IamError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** IAM v4's directory, the one the Console's picker reads: paged lists, bearer = your own sign-in. */
+class Iam {
+    base;
+    f;
+    token;
+    constructor(base, f, token) {
+        this.base = base;
+        this.f = f;
+        this.token = token;
+    }
+    async list(path) {
+        const out = [];
+        let cursor;
+        for (let page = 0; page < 20; page++) {
+            const u = new URL(path, this.base);
+            u.searchParams.set('limit', '100');
+            if (cursor)
+                u.searchParams.set('cursor', cursor);
+            const r = await this.f(u, { headers: { authorization: `Bearer ${await this.token()}`, accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(15_000) });
+            if (!r.ok) {
+                void r.body?.cancel().catch(() => { });
+                throw new IamError(r.status, `IAM ${r.status}`);
+            }
+            const body = await r.json();
+            const items = body.items ?? body.data ?? [];
+            out.push(...items.filter((x) => x && typeof x.id === 'string'));
+            cursor = body.next_cursor ?? body.nextCursor;
+            if (!cursor)
+                break;
+        }
+        return out;
+    }
+}
+/** https, or http only on an exact loopback host (the SDK's transport rule), before any request or bearer leaves. */
+function secureUrl(value, what) {
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        throw new Error(`${what} is not a URL: ${safe(value)}`);
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback))
+        throw new Error(`Refusing ${what} ${safe(value)}: use https.`);
+    if (u.username || u.password)
+        throw new Error(`Refusing ${what} with credentials in it.`);
+    return u.href;
+}
+/** Copy with the platform's clipboard tool. Returns false when there is none. */
+function copy(text) {
+    const tool = process.platform === 'darwin' ? ['pbcopy', []] : process.platform === 'win32' ? ['clip', []]
+        : process.env.WAYLAND_DISPLAY ? ['wl-copy', []] : ['xclip', ['-selection', 'clipboard']];
+    return new Promise((resolve) => {
+        try {
+            const p = spawn(tool[0], tool[1], { stdio: ['pipe', 'ignore', 'ignore'] });
+            p.on('error', () => resolve(false));
+            p.on('close', (c) => resolve(c === 0));
+            p.stdin.end(text);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/onboard/mcp.d.ts

@@ -0,0 +1,35 @@
+export type ClientId = 'claude-code' | 'claude-desktop' | 'cursor' | 'vscode' | 'windsurf' | 'codex';
+export interface Client {
+    id: ClientId;
+    name: string;
+    /** What changes, in words the confirmation shows: a file path or a command line. */
+    target: string;
+    installed: boolean;
+    present: boolean;
+}
+export interface McpEnv {
+    home: string;
+    platform: NodeJS.Platform;
+    appData?: string;
+    execPath: string;
+    version: string;
+    run(cmd: string, args: string[]): Promise<{
+        code: number;
+        stdout: string;
+    }>;
+}
+export declare function defaultMcpEnv(version: string): McpEnv;
+/** The npm package of the MCP server: the one place setup names the package scope. */
+export declare const MCP_PACKAGE = "@onesi/genesis-mcp";
+export declare function paths(e: McpEnv): {
+    readonly 'claude-desktop': string;
+    readonly cursor: string;
+    readonly vscode: string;
+    readonly windsurf: string;
+    readonly codex: string;
+};
+/** An absolute npx for GUI clients, when one sits next to this Node; otherwise plain npx. */
+export declare function npxFor(e: McpEnv, gui: boolean): Promise<string>;
+export declare function detectClients(e: McpEnv): Promise<Client[]>;
+/** Install into one client. Returns a sentence for the summary, or throws with the reason. */
+export declare function install(e: McpEnv, id: ClientId): Promise<string>;