@zenera/cli 1.1.0

package/dist/liveness.js

@@ -0,0 +1,221 @@
+import { EXA_BASE_URL, ModelRegistry } from '@zenera/neo';
+import { SHAPES, } from "./keys.js";
+// ---------------------------------------------------------------------------
+// Liveness
+//
+// The distinction that matters in the output is *dead* — the provider looked at
+// the credential and said no — versus *unknown* — we could not ask. Collapsing
+// them into one red mark is the classic way to send someone hunting for the
+// wrong bug: rotating a perfectly good key because the office wifi was down.
+// ---------------------------------------------------------------------------
+/** Words a provider uses when the credential itself is the problem. */
+const REJECTED = [
+    'invalid_api_key',
+    'invalid api key',
+    'incorrect api key',
+    'authentication',
+    'unauthenticated',
+    'unauthorized',
+    'permission_denied',
+    'permission denied',
+    'api key not valid',
+    'could not load the default credentials',
+];
+/** Words that mean the question never arrived. */
+const UNREACHED = [
+    'enotfound',
+    'econnrefused',
+    'econnreset',
+    'etimedout',
+    'eai_again',
+    'fetch failed',
+    'network',
+    'timeout',
+    'socket hang up',
+];
+function classify(err) {
+    const at = new Date().toISOString();
+    // OpenAI, Anthropic and the GenAI SDK all say `status`; OpenRouter's says
+    // `statusCode`. Reading only the first would classify a revoked key as
+    // *unknown*, which is the one confusion this module exists to prevent.
+    const e = err;
+    const status = e?.status ?? e?.statusCode;
+    const message = err instanceof Error ? err.message : String(err);
+    const haystack = `${status ?? ''} ${message}`.toLowerCase();
+    if (status === 401 || status === 403) {
+        return { state: 'dead', at, detail: `${status} ${firstLine(message)}` };
+    }
+    if (REJECTED.some((needle) => haystack.includes(needle))) {
+        return { state: 'dead', at, detail: firstLine(message) };
+    }
+    if (UNREACHED.some((needle) => haystack.includes(needle))) {
+        return { state: 'unknown', at, detail: 'could not reach the provider' };
+    }
+    // 429 means the credential authenticated and then got rate limited, which
+    // is a live key having a bad day.
+    if (status === 429) {
+        return { state: 'live', at, detail: 'rate limited, but authenticated' };
+    }
+    return { state: 'unknown', at, detail: firstLine(message) };
+}
+const firstLine = (s) => s.split('\n')[0].slice(0, 160);
+// ---------------------------------------------------------------------------
+// Deadline
+//
+// Every SDK here retries, and some of them retry a connection that will never
+// be answered — a proxy that swallows packets, a VPN half up. Left alone that
+// is a `zen key check` which never returns, and a command that hangs teaches
+// nobody anything. The credential question is one round trip; if it has not
+// been answered by now, the honest answer is *unknown*.
+// ---------------------------------------------------------------------------
+const DEADLINE_MS = 15_000;
+class Deadline extends Error {
+}
+async function within(work) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Deadline()), DEADLINE_MS);
+                // The abandoned request must not keep the process alive.
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The cheapest authenticated call each SDK has. Nothing here reads a model or
+ * spends a token: the question is only whether the credential is accepted.
+ *
+ * The client is built through the library's own registry rather than by
+ * requiring the SDKs directly, so a missing optional dependency produces the
+ * library's "run: npm i openai" message instead of a raw MODULE_NOT_FOUND.
+ */
+export async function probe(store, entry) {
+    const shape = SHAPES[entry.provider];
+    if (shape.kind === 'service') {
+        return probeService(entry.provider, store.reveal(entry));
+    }
+    const previous = process.env[shape.env];
+    process.env[shape.env] = store.reveal(entry);
+    try {
+        const registry = new ModelRegistry();
+        registry.provider('probe', { kind: entry.provider });
+        await within(authenticate(entry.provider, registry.client('probe')));
+        return { state: 'live', at: new Date().toISOString() };
+    }
+    catch (err) {
+        if (err instanceof Deadline) {
+            return {
+                state: 'unknown',
+                at: new Date().toISOString(),
+                detail: `no answer in ${DEADLINE_MS / 1000}s`,
+            };
+        }
+        return classify(err);
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env[shape.env];
+        }
+        else {
+            process.env[shape.env] = previous;
+        }
+    }
+}
+/**
+ * A service has no model catalog to list, and its cheapest endpoint is one that
+ * bills. So the question is asked with a request that cannot succeed: an empty
+ * body. Authentication is checked before the body is, which makes the two
+ * refusals say different things — a rejected key never gets far enough to be
+ * told its body is wrong, and a good key is told nothing else.
+ *
+ *   401 INVALID_API_KEY     → dead
+ *   400 INVALID_REQUEST_BODY → live, and free
+ *
+ * Anything else is left to `classify`, which already knows how to tell a
+ * refusal from an unreachable host.
+ */
+async function probeService(service, key) {
+    const at = new Date().toISOString();
+    // One service so far, and a switch rather than an `if`, so the next one is
+    // added where it belongs instead of alongside.
+    const url = { exa: `${EXA_BASE_URL}/contents` }[service];
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-api-key': key },
+            body: '{}',
+            signal: AbortSignal.timeout(DEADLINE_MS),
+        });
+        if (res.status === 401 || res.status === 403) {
+            return { state: 'dead', at, detail: `${res.status} ${await said(res)}` };
+        }
+        // 402 is a key the vendor recognised and then declined to serve. It
+        // authenticated; the account behind it is out of money, which is a
+        // different problem and one no amount of rotating the key will fix.
+        if (res.status === 402) {
+            return { state: 'live', at, detail: await said(res) };
+        }
+        if (res.status === 400 || res.ok) {
+            return { state: 'live', at };
+        }
+        return { state: 'unknown', at, detail: `${res.status} ${await said(res)}` };
+    }
+    catch (err) {
+        return classify(err);
+    }
+}
+/** The vendor's own sentence about a refusal, when the body carries one. */
+async function said(res) {
+    try {
+        const body = (await res.json());
+        return firstLine(body.error ?? res.statusText);
+    }
+    catch {
+        return res.statusText;
+    }
+}
+async function authenticate(provider, client) {
+    // OpenRouter's model catalog is *public*: it answers 200 to a request
+    // carrying no key at all, so listing it would report every credential live,
+    // including a revoked one. `/key` describes the key that asked and is the
+    // only cheap call that actually looks at it.
+    if (provider === 'openrouter') {
+        await client.apiKeys.getCurrentKeyMetadata();
+        return;
+    }
+    const args = provider === 'anthropic'
+        ? { limit: 1 }
+        : provider === 'google' || provider === 'vertex'
+            ? { config: { pageSize: 1 } }
+            : undefined;
+    const result = await client.models.list(args);
+    // OpenAI and Anthropic resolve to a page; the GenAI SDK resolves to a lazy
+    // pager whose first fetch has already happened by the time we get here.
+    void result;
+}
+/**
+ * Probes many entries, one at a time. In flight together would be quicker, but
+ * `probe` reaches the SDKs the only way they can be reached — through
+ * `process.env` — and two probes sharing that variable would each read the
+ * other's key. One at a time is also what makes progress reportable: there is
+ * exactly one answer being waited on, and `onProbe` can name it.
+ *
+ * Pairs rather than a map, because the caller needs the entry itself to record
+ * the result against, and a map keyed by a string would only have to be
+ * un-joined again.
+ */
+export async function probeAll(store, entries, onProbe) {
+    const out = [];
+    for (const [index, entry] of entries.entries()) {
+        onProbe?.(entry, index, entries.length);
+        out.push([entry, await probe(store, entry)]);
+    }
+    return out;
+}
+//# sourceMappingURL=liveness.js.map

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { extract, invokedAs, split } from "./args.js";
+import { NEO_BANNER, printBanner } from "./banner.js";
+import { ALIASES, COMMANDS, EXTERNAL } from "./commands/index.js";
+import { cliManifest, versionOf } from "./commands/version.js";
+import { hasExternal, loadExternal } from "./external.js";
+import { CliError, EXIT, bold, cyan, dim, fail, note, pad, write } from "./term.js";
+/** What the user typed: `zen`, `zn` or `zenera` all arrive here. */
+const NAME = invokedAs('zen');
+/** Usage lines are written against `zen`. Say them back in the reader's word. */
+const spell = (usage) => (NAME === 'zen' ? usage : usage.replace(/^zen\b/, NAME));
+// ---------------------------------------------------------------------------
+// zen — the command line over `@zenera/neo`
+//
+// A shell, deliberately. Argument parsing, help, version and exit codes are
+// settled here so that adding a command is a matter of writing one function and
+// naming it in `COMMANDS` — nothing about the frame has to be revisited.
+//
+// Only the drawing surface has a dependency, and it is behind a dynamic import
+// inside `run`. Everything on this path is Node's own, which is why `zen --help`
+// starts instantly and why the CLI adds no weight to the library.
+// ---------------------------------------------------------------------------
+const GLOBAL = {
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+    json: { type: 'boolean' },
+    // Uppercase, like make, tar and git: it changes where the command applies,
+    // not what it does.
+    directory: { type: 'string', short: 'C' },
+};
+async function main(argv) {
+    const parts = split(argv);
+    const { rest, global } = extract(parts.after);
+    let values;
+    try {
+        values = parseArgs({
+            args: [...parts.before, ...global],
+            options: GLOBAL,
+            strict: true,
+            allowPositionals: false,
+        }).values;
+    }
+    catch (e) {
+        fail(e.message, `run ${bold(`${NAME} --help`)} for the options`);
+        return EXIT.usage;
+    }
+    const json = Boolean(values.json);
+    if (values.version && !parts.name) {
+        write(await versionOf(cliManifest));
+        return EXIT.ok;
+    }
+    const name = parts.name ? (ALIASES[parts.name] ?? parts.name) : undefined;
+    const command = name ? COMMANDS[name] : undefined;
+    const external = name && !command ? EXTERNAL[name] : undefined;
+    // Narration, so `--json` and every pipe are untouched by it. A command
+    // living in another package brings its own brand, but only once it is
+    // actually there — a banner over "not installed" is a claim about nothing.
+    if (!json) {
+        const brand = external && hasExternal(external) ? external.banner : undefined;
+        printBanner(brand ?? NEO_BANNER);
+    }
+    if (parts.name === 'help') {
+        await usage(rest[0]);
+        return EXIT.ok;
+    }
+    if (!name) {
+        await usage();
+        return values.help ? EXIT.ok : EXIT.usage;
+    }
+    if (!command && !external) {
+        fail(`unknown command "${parts.name}"`, `run ${bold(`${NAME} --help`)} for the list`);
+        return EXIT.usage;
+    }
+    if (values.help) {
+        await usage(name);
+        return EXIT.ok;
+    }
+    // `-C` is consumed here so no command ever reads `process.cwd()` itself,
+    // and every relative path in every command means the same thing.
+    const cwd = resolve(values.directory ?? process.cwd());
+    try {
+        const one = command ?? (await loadExternal(name, external));
+        await one.run({ args: rest, json, cwd });
+        return EXIT.ok;
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            fail(e.message, e.hint ? spell(e.hint) : undefined);
+            return e.code;
+        }
+        fail(e instanceof Error ? e.message : String(e));
+        if (process.env.ZENERA_DEBUG && e instanceof Error && e.stack) {
+            note(dim(e.stack));
+        }
+        return EXIT.failed;
+    }
+}
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+async function usage(name) {
+    const resolved = name ? (ALIASES[name] ?? name) : undefined;
+    const ext = resolved ? EXTERNAL[resolved] : undefined;
+    // Asking for one command's help is already asking for that package, so
+    // loading it here costs nothing the reader did not request.
+    const one = resolved
+        ? (COMMANDS[resolved] ??
+            (ext && hasExternal(ext)
+                ? await loadExternal(resolved, ext).catch(() => undefined)
+                : undefined))
+        : undefined;
+    if (one) {
+        write(bold(spell(one.usage)));
+        write(`\n  ${one.summary}`);
+        if (ext) {
+            write(`\n  ${dim(`Provided by ${cyan(ext.package)}.`)}`);
+        }
+        if (one.details?.length) {
+            write('');
+            for (const line of one.details) {
+                write(line ? `  ${line}` : '');
+            }
+        }
+        return;
+    }
+    // Not installed: the table is all there is to say, and it is enough.
+    if (ext) {
+        write(bold(spell(ext.usage)));
+        write(`\n  ${ext.summary}`);
+        write(`\n  ${dim(`Provided by ${cyan(ext.package)} — run ${cyan(ext.install)}.`)}`);
+        return;
+    }
+    write(`${bold(NAME)} ${dim('— run agent projects from the command line')}`);
+    write(`\n${bold('Usage')}\n  ${NAME} <command> [options]`);
+    write(`\n${bold('Commands')}`);
+    const names = [...Object.keys(COMMANDS), ...Object.keys(EXTERNAL)];
+    const width = Math.max(...names.map((k) => k.length));
+    for (const [key, cmd] of Object.entries(COMMANDS)) {
+        write(`  ${pad(key, width)}  ${dim(cmd.summary)}`);
+    }
+    for (const [key, ext] of Object.entries(EXTERNAL)) {
+        const tail = hasExternal(ext) ? '' : dim(` (${ext.install})`);
+        write(`  ${pad(key, width)}  ${dim(ext.summary)}${tail}`);
+    }
+    write(`\n${bold('Options')}`);
+    write(`  -h, --help          ${dim('This, or a command’s own.')}`);
+    write(`  -v, --version       ${dim('Print the version.')}`);
+    write(`      --json          ${dim('Machine-readable output.')}`);
+    write(`  -C, --directory <d> ${dim('Act as if run in <d>.')}`);
+    write(`\n${dim(`Start with ${cyan(`${NAME} init`)}, then ${cyan(`${NAME} run`)}.`)}`);
+}
+process.exitCode = await main(process.argv.slice(2));
+//# sourceMappingURL=main.js.map

package/dist/narrate.d.ts

@@ -0,0 +1,19 @@
+import { type AgentEvent, type TokenUsage } from '@zenera/neo';
+export interface NarratorOptions {
+    /** print nothing at all */
+    quiet?: boolean;
+    /** print text deltas as they arrive, for a terminal that is watching */
+    live?: boolean;
+}
+export declare class Narrator {
+    #private;
+    constructor(opts?: NarratorOptions);
+    handle: (event: AgentEvent) => void;
+    done(): void;
+    get agent(): string | undefined;
+}
+export declare function summary(usage: TokenUsage): string;
+export declare function format(n: number): string;
+export declare function duration(ms: number): string;
+export declare const stopMark: (reason: string) => string;
+//# sourceMappingURL=narrate.d.ts.map

package/dist/narrate.js

@@ -0,0 +1,124 @@
+import { isCheckpoint } from '@zenera/neo';
+import { cyan, dim, green, note, red, yellow } from "./term.js";
+export class Narrator {
+    #quiet;
+    #live;
+    #streaming;
+    #agent;
+    constructor(opts = {}) {
+        this.#quiet = Boolean(opts.quiet);
+        this.#live = Boolean(opts.live);
+    }
+    handle = (event) => {
+        if (this.#quiet) {
+            return;
+        }
+        if (!isCheckpoint(event)) {
+            this.#delta(event);
+            return;
+        }
+        this.#break();
+        const where = event.branch ? dim(`[${event.branch.name}] `) : '';
+        switch (event.type) {
+            case 'run_created':
+                this.#agent = event.agent;
+                note(`${dim('·')} ${cyan(event.agent)}`);
+                break;
+            case 'before_tool_call':
+                note(`${where}${dim('→')} ${event.call.name}`);
+                break;
+            case 'after_tool_call':
+                if (event.node.isError) {
+                    note(`${where}${red('  failed')} ${dim(event.node.name)}`);
+                }
+                break;
+            case 'handoff':
+                this.#agent = event.to;
+                note(`${where}${dim('⇢')} ${cyan(event.to)} ${dim(`from ${event.from}`)}`);
+                break;
+            case 'before_fork':
+                note(`${where}${dim('⑂')} ${event.node.branches.map((b) => b.name).join(', ')}`);
+                break;
+            case 'branch_finished':
+                note(`${dim('  ⑂')} ${event.child.name} ` +
+                    (event.status === 'ok' ? green('ok') : red(event.status)));
+                break;
+            case 'run_finished':
+                if (event.branch) {
+                    break;
+                }
+                note(`${dim('·')} ${summary(event.result.usage)}`);
+                break;
+            default:
+                break;
+        }
+    };
+    #delta(event) {
+        if (!this.#live) {
+            return;
+        }
+        const kind = event.type === 'text_delta'
+            ? 'text'
+            : event.type === 'thinking_delta'
+                ? 'thinking'
+                : undefined;
+        if (!kind) {
+            return;
+        }
+        const { delta } = event;
+        if (!delta) {
+            return;
+        }
+        // Reasoning and the answer are two different streams; run together they
+        // read as one confused paragraph, so a switch between them breaks the
+        // line first.
+        if (this.#streaming && this.#streaming !== kind) {
+            process.stderr.write('\n');
+        }
+        this.#streaming = kind;
+        process.stderr.write(dim(delta));
+    }
+    /** Closes an open delta line before a checkpoint line lands on top of it. */
+    #break() {
+        if (this.#streaming) {
+            process.stderr.write('\n');
+            this.#streaming = undefined;
+        }
+    }
+    done() {
+        this.#break();
+    }
+    get agent() {
+        return this.#agent;
+    }
+}
+export function summary(usage) {
+    const cached = usage.cachedInputTokens
+        ? dim(` (${format(usage.cachedInputTokens)} cached)`)
+        : '';
+    const thinking = usage.reasoningTokens
+        ? dim(` (${format(usage.reasoningTokens)} thinking)`)
+        : '';
+    return `${format(usage.inputTokens)} in${cached}  ${format(usage.outputTokens)} out${thinking}`;
+}
+export function format(n) {
+    if (n < 1000) {
+        return String(n);
+    }
+    if (n < 1_000_000) {
+        return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
+    }
+    return `${(n / 1_000_000).toFixed(1)}M`;
+}
+export function duration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60_000) {
+        return `${(ms / 1000).toFixed(1)}s`;
+    }
+    const minutes = Math.floor(ms / 60_000);
+    return `${minutes}m ${Math.round((ms % 60_000) / 1000)}s`;
+}
+export const stopMark = (reason) => reason === 'final' ? green('done') : reason === 'aborted' ? yellow('aborted') : red('failed');
+//# sourceMappingURL=narrate.js.map

package/dist/podman.d.ts

@@ -0,0 +1,46 @@
+import { runProcess } from '@zenera/neo';
+export interface PodmanOptions {
+    /** the image the project needs on disk before the first run */
+    image?: string;
+    /** machine size, when one has to be created */
+    cpus?: number;
+    /** MiB */
+    memory?: number;
+    engine?: string;
+    /** never prompt; `--yes`, `--json`, or no terminal */
+    yes?: boolean;
+    /** so the tests can watch the sequence without a container engine */
+    exec?: typeof runProcess;
+}
+export interface PodmanStatus {
+    engine: string;
+    installed: boolean;
+    version?: string;
+    /** absent on Linux, where there is no machine to have */
+    machine?: {
+        name: string;
+        running: boolean;
+        starting: boolean;
+    };
+    /** whether `podman info` answered */
+    ready: boolean;
+    image?: string;
+    imagePresent?: boolean;
+}
+export declare function ensurePodmanReady(opts?: PodmanOptions): Promise<void>;
+/** What `zn sandbox status` prints. Changes nothing, and never throws. */
+export declare function podmanStatus(opts?: PodmanOptions): Promise<PodmanStatus>;
+export interface OwnedContainer {
+    name: string;
+    /** podman's own word: `running`, `exited`, `created`, `paused` */
+    state: string;
+}
+/**
+ * Containers this CLI created, whatever session they belong to, and whether
+ * each is up. `--all` is the point: with `persist: true` a session leaves a
+ * *stopped* container behind, and a listing that only showed running ones
+ * would say nothing is there while the disk says otherwise.
+ */
+export declare function ownedContainers(engine?: string, exec?: import("@zenera/neo").Runner): Promise<OwnedContainer[]>;
+export declare function removeContainers(names: readonly string[], engine?: string, exec?: import("@zenera/neo").Runner): Promise<void>;
+//# sourceMappingURL=podman.d.ts.map