@zenera/cli 1.1.0

package/dist/commands/inspect.js

@@ -0,0 +1,158 @@
+import { spawn } from 'node:child_process';
+import { createReadStream, existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, normalize, resolve, sep } from 'node:path';
+import { assertState, buildRunReport, FilePayloadStore, PayloadResolver, renderReportHtml, } from '@zenera/neo';
+import { parse } from "../args.js";
+import { project as resolveProject } from "../resolve.js";
+import { display, newestRun, newestSession, requireSession, runPaths, sessionPaths, } from "../session.js";
+import { bold, cyan, dim, invalidError, json, note, write } from "../term.js";
+const USAGE = 'zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]';
+export const inspect = {
+    summary: "Open or rebuild a run's report.html.",
+    usage: USAGE,
+    details: [
+        'With no arguments: the newest run of the newest session.',
+        '--serve starts a local server, which the report needs for its assets.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            project: { type: 'string' },
+            session: { type: 'string' },
+            open: { type: 'boolean' },
+            rebuild: { type: 'boolean' },
+            serve: { type: 'string' },
+        }, USAGE);
+        const found = await resolveProject({ cwd: ctx.cwd, project: values.project });
+        const dir = found.dir;
+        const session = pickSession(dir, values.session);
+        const run = pickRun(session, positionals[0]);
+        if (values.rebuild || !existsSync(run.report)) {
+            await rebuild(session, run);
+        }
+        if (ctx.json) {
+            json({ session: session.id, run: run.id, report: run.report });
+            return;
+        }
+        if (values.serve !== undefined) {
+            await serve(run, Number(values.serve) || 0, Boolean(values.open));
+            return;
+        }
+        write(run.report);
+        note(`${bold(run.id)} ${dim(display(run.report, ctx.cwd))}`);
+        if (values.open) {
+            reveal(`file://${run.report}`);
+        }
+        else {
+            note(dim(`open it: ${cyan('zen inspect --open')}`));
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Choosing what to show
+// ---------------------------------------------------------------------------
+function pickSession(dir, asked) {
+    if (asked) {
+        return requireSession(dir, asked);
+    }
+    const newest = newestSession(dir);
+    if (!newest) {
+        throw invalidError('nothing has been run here yet', 'start one: zen run');
+    }
+    return sessionPaths(dir, newest);
+}
+function pickRun(session, asked) {
+    const id = asked ?? newestRun(session);
+    if (!id) {
+        throw invalidError(`session ${session.id} has no runs`);
+    }
+    const run = runPaths(session, id);
+    if (!existsSync(run.dir)) {
+        throw invalidError(`no run ${id} in session ${session.id}`);
+    }
+    return run;
+}
+/**
+ * A report is derived, so it can always be thrown away and remade from the run
+ * state — which is what makes `--rebuild` safe and what makes an old run
+ * readable by a newer renderer.
+ */
+async function rebuild(session, run) {
+    if (!existsSync(run.state)) {
+        throw invalidError(`run ${run.id} has no state to rebuild from`);
+    }
+    let state;
+    try {
+        state = assertState(JSON.parse(await readFile(run.state, 'utf8')));
+    }
+    catch (err) {
+        throw invalidError(`${run.state}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
+    const report = await buildRunReport(state, payloads, { title: run.id });
+    await writeFile(run.report, renderReportHtml(report), 'utf8');
+}
+// ---------------------------------------------------------------------------
+// Serving
+//
+// `file://` is enough for the report itself, but not for anything it fetches:
+// browsers treat every local file as its own origin. A server exists only so
+// those requests resolve, and so it binds to the loopback address — a run
+// report is a transcript of everything the model was sent.
+// ---------------------------------------------------------------------------
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+};
+async function serve(run, port, open) {
+    const root = resolve(run.dir);
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const rel = decodeURIComponent(url.pathname);
+        const path = rel === '/' ? run.report : resolve(root, `.${normalize(rel)}`);
+        // Containment, not obscurity: anything resolving outside the run
+        // directory is refused, so a crafted path cannot walk to $HOME.
+        if (path !== root && !path.startsWith(root + sep)) {
+            res.writeHead(403).end('forbidden');
+            return;
+        }
+        if (!existsSync(path)) {
+            res.writeHead(404).end('not found');
+            return;
+        }
+        res.writeHead(200, { 'content-type': TYPES[extname(path)] ?? 'application/octet-stream' });
+        createReadStream(path).pipe(res);
+    });
+    await new Promise((ok) => server.listen(port, '127.0.0.1', ok));
+    const address = server.address();
+    const at = typeof address === 'object' && address ? `http://127.0.0.1:${address.port}/` : '';
+    write(at);
+    note(`${bold('serving')} ${dim(display(run.dir))}`);
+    note(dim('ctrl-c to stop'));
+    if (open) {
+        reveal(at);
+    }
+    await new Promise((done) => {
+        const stop = () => {
+            server.close(() => done());
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+    });
+}
+/**
+ * Handing a URL to the platform opener. `spawn` without a shell, so the path
+ * is an argument rather than something a shell gets to interpret.
+ */
+function reveal(target) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'explorer'
+            : 'xdg-open';
+    spawn(command, [target], { stdio: 'ignore', detached: true }).unref();
+}
+//# sourceMappingURL=inspect.js.map

package/dist/commands/key.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const key: Command;
+//# sourceMappingURL=key.d.ts.map

package/dist/commands/key.js

@@ -0,0 +1,335 @@
+import { existsSync } from 'node:fs';
+import { parse } from "../args.js";
+import { ensureHome } from "../home.js";
+import { assertNotEmpty, describe, keyId, KeyStore, mask, OWNERS, parseRef, SHAPES, } from "../keys.js";
+import { probe, probeAll } from "../liveness.js";
+import { ago, ask, askSecret, bold, confirm, credentialError, cyan, dim, green, isInteractive, json, note, progress, readStdin, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen key <ls|add|use|check|rm|show|env> [ref] [options]';
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+const MARK = {
+    live: green('live'),
+    dead: red('dead'),
+    unknown: dim('unknown'),
+};
+function state(entry) {
+    return entry.check ? MARK[entry.check.state] : dim('unchecked');
+}
+function rows(store) {
+    const out = [
+        [bold(''), bold('KEY'), bold('VALUE'), bold('STATE'), bold('CHECKED')],
+    ];
+    for (const provider of OWNERS) {
+        for (const entry of store.for(provider)) {
+            const shadowed = Boolean(process.env[SHAPES[provider].env]);
+            out.push([
+                store.isActive(entry) ? green('*') : ' ',
+                keyId(entry),
+                dim(describe(store, entry)),
+                state(entry),
+                dim(entry.check ? ago(entry.check.at) : '—') +
+                    (shadowed && store.isActive(entry)
+                        ? yellow(`  shadowed by $${SHAPES[provider].env}`)
+                        : ''),
+            ]);
+        }
+    }
+    return table(out);
+}
+/**
+ * Checking is a network round trip per key, so it says which one it is waiting
+ * on. Silence for ten seconds is indistinguishable from a hang.
+ */
+async function checkAll(ctx, store, targets) {
+    const bar = ctx.json ? undefined : progress();
+    try {
+        return await probeAll(store, targets, (entry, index, total) => bar?.update(dim(`checking ${keyId(entry)} … ${index + 1}/${total}`)));
+    }
+    finally {
+        bar?.done();
+    }
+}
+const ls = async (ctx, args) => {
+    const { values } = parse(args, { check: { type: 'boolean' } }, USAGE);
+    const store = await KeyStore.open();
+    if (values.check) {
+        const checks = await checkAll(ctx, store, store.entries);
+        for (const [entry, check] of checks) {
+            store.record(entry, check);
+        }
+        store.save();
+    }
+    if (ctx.json) {
+        json(store.entries.map((e) => ({
+            ...e,
+            value: e.holds === 'file' ? store.fileOf(e) : mask(e.value),
+            active: store.isActive(e),
+            env: SHAPES[e.provider].env,
+        })));
+        return;
+    }
+    if (store.entries.length === 0) {
+        note('the keyring is empty');
+        note(dim('add one: zen key add openai'));
+        return;
+    }
+    writeAll(rows(store));
+    const missing = OWNERS.filter((p) => !store.active(p) && !process.env[SHAPES[p].env]);
+    if (missing.length) {
+        note('');
+        note(dim(`no key for: ${missing.join(', ')}`));
+    }
+};
+/**
+ * The secret never comes from argv. A command line is visible in `ps`, lands in
+ * shell history and is captured by CI logs — three places a key must not be.
+ * Piped stdin or an echo-off prompt are the only two ways in.
+ */
+const add = async (ctx, args) => {
+    const { values, positionals } = parse(args, { name: { type: 'string' }, 'no-check': { type: 'boolean' } }, 'zen key add <provider>[/name] [--name <name>] [--no-check]');
+    const ref = positionals[0];
+    if (!ref) {
+        throw usageError('which provider?', `one of: ${OWNERS.join(', ')}`);
+    }
+    const parsed = parseRef(ref);
+    const provider = parsed.provider;
+    const name = values.name ?? parsed.name ?? 'default';
+    const shape = SHAPES[provider];
+    ensureHome();
+    const store = await KeyStore.open();
+    if (store.find(provider, name) && isInteractive()) {
+        if (!(await confirm(`Replace ${provider}/${name}?`))) {
+            throw usageError('cancelled');
+        }
+    }
+    const raw = (await readStdin()) ?? (await promptFor(shape.holds, shape.label, shape.where));
+    if (!raw) {
+        throw usageError('no value given');
+    }
+    if (shape.holds === 'file' && !existsSync(raw)) {
+        throw usageError(`no such file: ${raw}`);
+    }
+    const entry = store.add(provider, name, raw);
+    // Verified before it is trusted, but stored either way: a key that cannot
+    // be checked right now — offline, behind a proxy — is not a key that is
+    // wrong, and refusing to save it would make `zen key add` fail on a plane.
+    if (!values['no-check']) {
+        const bar = ctx.json ? undefined : progress();
+        bar?.update(dim(`checking ${keyId(entry)} …`));
+        const check = await probe(store, entry);
+        bar?.done();
+        store.record(entry, check);
+        if (check.state === 'dead') {
+            note(`${red('rejected')} ${check.detail ?? 'the provider refused this key'}`);
+        }
+    }
+    store.save();
+    if (ctx.json) {
+        json({
+            key: keyId(entry),
+            env: shape.env,
+            active: store.isActive(entry),
+            check: entry.check,
+        });
+        return;
+    }
+    note(`${green('added')} ${bold(keyId(entry))} ${dim(describe(store, entry))} ${state(entry)}`);
+    if (process.env[shape.env]) {
+        note(yellow(`$${shape.env} is set and will win over this`));
+    }
+};
+async function promptFor(holds, label, where) {
+    note(dim(`${label} — ${where}`));
+    return holds === 'file'
+        ? ask('Path to the credentials file:')
+        : askSecret('Paste the key (it will not be shown):');
+}
+const use = async (ctx, args) => {
+    const { positionals } = parse(args, {}, 'zen key use <provider>/<name>');
+    const ref = positionals[0];
+    if (!ref) {
+        throw usageError('which key?', 'see: zen key ls');
+    }
+    const { provider, name } = parseRef(ref);
+    if (!name) {
+        throw usageError(`"${ref}" names a provider, not a key`, 'use provider/name');
+    }
+    const store = await KeyStore.open();
+    const entry = store.use(provider, name);
+    store.save();
+    if (ctx.json) {
+        json({ key: keyId(entry), env: SHAPES[provider].env });
+        return;
+    }
+    note(`${green('using')} ${bold(keyId(entry))} for ${SHAPES[provider].label}`);
+};
+const check = async (ctx, args) => {
+    const { positionals } = parse(args, {}, 'zen key check [provider[/name]]');
+    const store = await KeyStore.open();
+    assertNotEmpty(store);
+    const targets = positionals[0] ? select(store, positionals[0]) : store.entries;
+    const checks = await checkAll(ctx, store, targets);
+    for (const [entry, result] of checks) {
+        store.record(entry, result);
+    }
+    store.save();
+    if (ctx.json) {
+        json(checks.map(([entry, result]) => ({ key: keyId(entry), ...result })));
+        return;
+    }
+    writeAll(table(checks.map(([entry, result]) => [
+        keyId(entry),
+        MARK[result.state],
+        dim(result.detail ?? ''),
+    ])));
+    if (checks.some(([, r]) => r.state === 'dead')) {
+        throw credentialError('at least one key was refused');
+    }
+};
+function select(store, ref) {
+    const { provider, name } = parseRef(ref);
+    if (!name) {
+        return store.for(provider);
+    }
+    const entry = store.find(provider, name);
+    if (!entry) {
+        throw usageError(`no key ${ref}`, 'see: zen key ls');
+    }
+    return [entry];
+}
+const rm = async (ctx, args) => {
+    const { values, positionals } = parse(args, { yes: { type: 'boolean' } }, 'zen key rm <provider>/<name> [--yes]');
+    const ref = positionals[0];
+    if (!ref) {
+        throw usageError('which key?', 'see: zen key ls');
+    }
+    const { provider, name } = parseRef(ref);
+    if (!name) {
+        throw usageError(`"${ref}" names a provider, not a key`, 'use provider/name');
+    }
+    const store = await KeyStore.open();
+    if (!store.find(provider, name)) {
+        throw usageError(`no key ${ref}`, 'see: zen key ls');
+    }
+    if (!values.yes && isInteractive() && !(await confirm(`Forget ${ref}?`))) {
+        throw usageError('cancelled');
+    }
+    store.remove(provider, name);
+    store.save();
+    // The stored file is left behind on purpose: it was copied from somewhere,
+    // and deleting a service-account key nobody asked us to delete is not the
+    // CLI's call to make.
+    if (ctx.json) {
+        json({ removed: ref });
+        return;
+    }
+    note(`${green('forgot')} ${ref}`);
+};
+/** The one deliberate way a secret leaves the store, and it has to be asked for. */
+const show = async (ctx, args) => {
+    const { values, positionals } = parse(args, { reveal: { type: 'boolean' } }, 'zen key show <provider>[/name] [--reveal]');
+    const ref = positionals[0];
+    if (!ref) {
+        throw usageError('which key?', 'see: zen key ls');
+    }
+    const store = await KeyStore.open();
+    const entry = select(store, ref)[0];
+    if (!entry) {
+        throw usageError(`no key ${ref}`, 'see: zen key ls');
+    }
+    const value = values.reveal ? store.reveal(entry) : describe(store, entry);
+    if (ctx.json) {
+        json({
+            key: keyId(entry),
+            env: SHAPES[entry.provider].env,
+            value,
+            revealed: Boolean(values.reveal),
+        });
+        return;
+    }
+    if (values.reveal) {
+        // stdout, alone, unstyled — so `zen key show openai --reveal | pbcopy`
+        // copies the key and nothing else.
+        write(value);
+        return;
+    }
+    writeAll(table([
+        [dim('key'), keyId(entry)],
+        [dim('env'), SHAPES[entry.provider].env],
+        [dim('value'), value],
+        [dim('state'), state(entry)],
+        [dim('added'), ago(entry.addedAt)],
+    ]));
+    note(dim('--reveal prints the secret itself'));
+};
+/**
+ * `eval "$(zen key env)"` puts the active keys into a shell — for the tools that
+ * are not `zen`. Real environment variables still win inside `zen` itself, so
+ * this changes nothing about how a run resolves credentials.
+ */
+const env = async (ctx, args) => {
+    const { positionals } = parse(args, {}, 'zen key env [provider …]');
+    const store = await KeyStore.open();
+    const only = positionals.length
+        ? positionals.map((p) => parseRef(p).provider)
+        : undefined;
+    // Ignore what is already exported: the point is to produce the exports.
+    const vars = {};
+    for (const provider of only ?? OWNERS) {
+        const entry = store.active(provider);
+        if (entry) {
+            vars[SHAPES[provider].env] = store.reveal(entry);
+        }
+    }
+    if (ctx.json) {
+        json(vars);
+        return;
+    }
+    for (const [name, value] of Object.entries(vars)) {
+        write(`export ${name}=${shellQuote(value)}`);
+    }
+    if (Object.keys(vars).length === 0) {
+        note(dim('nothing to export'));
+    }
+};
+/** Single quotes, with the one escape single quotes cannot express. */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+const SUBS = { ls, list: ls, add, use, check, rm, remove: rm, show, env };
+export const key = {
+    summary: 'The credential store: add, choose, verify and export API keys.',
+    usage: USAGE,
+    details: [
+        'Keys live in ~/.zenera/neo/keys.json (0600) and are materialised into',
+        'the environment before a run. A real environment variable always wins.',
+        '',
+        'Model providers: openai, anthropic, google, vertex, openrouter.',
+        'Services the tools call: exa.',
+        '',
+        '  zen key ls [--check]              Everything stored, and its state.',
+        '  zen key add <provider>[/name]     Read a key from stdin, or ask for it.',
+        '  zen key use <provider>/<name>     Choose which one a run uses.',
+        '  zen key check [provider[/name]]   Ask the provider whether it still works.',
+        '  zen key rm <provider>/<name>      Forget one.',
+        '  zen key show <ref> [--reveal]     Masked by default.',
+        '  zen key env [provider …]          Shell exports, for other tools.',
+    ],
+    run: async (ctx) => {
+        const [name, ...rest] = ctx.args;
+        if (!name) {
+            await ls(ctx, []);
+            return;
+        }
+        const sub = SUBS[name];
+        if (!sub) {
+            throw usageError(`unknown: zen key ${name}`, `try: ${cyan(Object.keys(SUBS).slice(0, 7).join(', '))}`);
+        }
+        await sub(ctx, rest);
+    },
+};
+//# sourceMappingURL=key.js.map

package/dist/commands/list.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const list: Command;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/list.js

@@ -0,0 +1,101 @@
+import { parse } from "../args.js";
+// Run ids are timestamps by construction, so the newest id *is* the last-run
+// time — no file has to be opened to learn it.
+import { stampInstant } from "../ids.js";
+import { openDir, Registry, summarize } from "../projects.js";
+import { listSessions } from "../session.js";
+import { ago, bold, count, dim, json, note, table, write, writeAll, yellow } from "../term.js";
+const USAGE = 'zen list [--sessions] [--prune]';
+export const list = {
+    summary: 'Every known project: sessions, last run, whether one is live.',
+    usage: USAGE,
+    details: [
+        'The registry is an index, not the truth. An entry whose directory has',
+        'gone away is shown dimmed rather than hidden; --prune forgets them.',
+    ],
+    run: async (ctx) => {
+        const { values } = parse(ctx.args, { sessions: { type: 'boolean' }, prune: { type: 'boolean' } }, USAGE);
+        const registry = await Registry.open();
+        if (values.prune) {
+            const gone = registry.prune();
+            registry.save();
+            if (!ctx.json) {
+                note(gone.length ? `forgot ${count(gone.length, 'project')}` : 'nothing to prune');
+            }
+        }
+        const summaries = [];
+        for (const entry of registry.entries) {
+            summaries.push(await summarize(entry));
+        }
+        summaries.sort((a, b) => (b.lastRunAt ?? '').localeCompare(a.lastRunAt ?? ''));
+        if (ctx.json) {
+            json(values.sessions ? await withSessions(summaries) : summaries);
+            return;
+        }
+        if (summaries.length === 0) {
+            note('no projects yet');
+            note(dim('create one: zen init'));
+            return;
+        }
+        const rows = [
+            [bold('NAME'), bold('SESSIONS'), bold('RUNS'), bold('LAST'), bold('PATH')],
+        ];
+        for (const s of summaries) {
+            const style = s.present ? (x) => x : dim;
+            rows.push([
+                style(s.name) + (s.busy ? yellow(' •') : ''),
+                style(String(s.sessions)),
+                style(String(s.runs)),
+                style(ago(s.lastRunAt ? stampInstant(s.lastRunAt) : undefined)),
+                dim(s.present ? s.path : `${s.path} (missing)`),
+            ]);
+        }
+        writeAll(table(rows));
+        if (values.sessions) {
+            for (const s of summaries.filter((p) => p.present)) {
+                write('');
+                write(bold(s.name));
+                writeAll(await sessionRows(s));
+            }
+        }
+    },
+};
+/**
+ * Run ids are timestamps by construction, so the newest id *is* the last-run
+ * time — no file has to be opened to learn it.
+ */
+function stampToIso(id) {
+    const m = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})/.exec(id);
+    if (!m) {
+        return undefined;
+    }
+    const [, y, mo, d, h, mi, s] = m;
+    return new Date(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)).toISOString();
+}
+async function sessionRows(summary) {
+    const project = await openDir(summary.path);
+    const sessions = await listSessions(project.dir);
+    if (sessions.length === 0) {
+        return [dim('  no sessions')];
+    }
+    return table(sessions.map((s) => [
+        `  ${s.id}`,
+        s.title ?? dim('—'),
+        String(s.runs),
+        ago(s.lastRunAt ?? s.createdAt),
+        s.busy ? yellow('running') : '',
+    ]));
+}
+async function withSessions(summaries) {
+    const out = [];
+    for (const s of summaries) {
+        if (!s.present) {
+            out.push({ ...s, sessionList: [] });
+            continue;
+        }
+        const project = await openDir(s.path);
+        out.push({ ...s, sessionList: await listSessions(project.dir) });
+    }
+    return out;
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/models.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../command.ts';
+/**
+ * Everything a run would resolve, resolved — and nothing called. Loading a
+ * project constructs the model clients, so a config that names an impossible
+ * provider or an agent that hands off to nobody fails here, in a command that
+ * costs nothing, instead of three seconds into a run that costs money.
+ */
+export declare const models: Command;
+//# sourceMappingURL=models.d.ts.map