@zenera/cli 1.1.0

package/dist/ids.js

@@ -0,0 +1,44 @@
+import { randomBytes } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Identifiers
+//
+// `YYYYMMDD-HHMMSS-xxxx`, local time, four hex characters of entropy.
+//
+// Sortable as a plain string, readable without a decoder, and collision-free
+// when two runs start inside the same second. An epoch integer gives up the
+// first two properties and a uuid gives up all three.
+// ---------------------------------------------------------------------------
+const STAMP = /^\d{8}-\d{6}-[0-9a-f]{4}$/;
+export function stamp(now = new Date()) {
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    const date = `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}`;
+    const time = `${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+    return `${date}-${time}-${randomBytes(2).toString('hex')}`;
+}
+/**
+ * Ids arrive from `--session` and `--run` and become path segments, so they are
+ * checked rather than trusted. The shape has no `.` and no separator, which
+ * makes traversal unrepresentable rather than merely rejected.
+ */
+export function isStamp(value) {
+    return STAMP.test(value);
+}
+/** Human-readable form of a stamp: `2026-08-25 14:30:12`. */
+export function stampDate(id) {
+    if (!isStamp(id)) {
+        return id;
+    }
+    const [d, t] = id.split('-');
+    return (`${d.slice(0, 4)}-${d.slice(4, 6)}-${d.slice(6, 8)} ` +
+        `${t.slice(0, 2)}:${t.slice(2, 4)}:${t.slice(4, 6)}`);
+}
+/** ISO instant a stamp names, for `ago()`. Local time in, local time out. */
+export function stampInstant(id) {
+    if (!isStamp(id)) {
+        return undefined;
+    }
+    const [d, t] = id.split('-');
+    const at = new Date(Number(d.slice(0, 4)), Number(d.slice(4, 6)) - 1, Number(d.slice(6, 8)), Number(t.slice(0, 2)), Number(t.slice(2, 4)), Number(t.slice(4, 6)));
+    return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+//# sourceMappingURL=ids.js.map

package/dist/keys.d.ts

@@ -0,0 +1,124 @@
+/** The vendors a *model* can come from — the library's provider kinds, verbatim. */
+export declare const PROVIDERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter"];
+export type Provider = (typeof PROVIDERS)[number];
+/**
+ * Credentials that are not a way to reach a model.
+ *
+ * A tool can need a key as much as a model can, and the reasons a keyring
+ * exists — one place, 0600, materialised into the environment before a run —
+ * do not care which. What does care is everything that reasons about *models*:
+ * a machine holding nothing but an Exa key cannot run an agent, and saying it
+ * can would move the failure from `zen run`'s first line to its first turn.
+ * Hence two lists rather than one longer one, and `kind` on the shape so the
+ * few places that must tell them apart are made to say which they mean.
+ */
+export declare const SERVICES: readonly ["exa"];
+export type Service = (typeof SERVICES)[number];
+/** Anything the keyring can hold a credential for. */
+export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa"];
+export type KeyOwner = Provider | Service;
+interface ProviderShape {
+    /** whether this is somewhere a model lives, or something a tool calls */
+    kind: 'model' | 'service';
+    /** environment variable the library reads */
+    env: string;
+    /** what the value is: a secret string, or a path to a credentials file */
+    holds: 'secret' | 'file';
+    label: string;
+    /** where to get one, printed when there is none */
+    where: string;
+}
+/**
+ * Vertex is the odd one. The GenAI SDK resolves Application Default
+ * Credentials itself, so what is stored is a service-account *file* and what is
+ * exported is a path — not a key. Pretending otherwise would mean inventing a
+ * credential shape Google does not have.
+ */
+export declare const SHAPES: Record<KeyOwner, ProviderShape>;
+export declare function isProvider(name: string): name is Provider;
+export declare function isOwner(name: string): name is KeyOwner;
+export declare function assertOwner(name: string): KeyOwner;
+export type Liveness = 'live' | 'dead' | 'unknown';
+export interface KeyCheck {
+    state: Liveness;
+    at: string;
+    /** the provider's own words when it said no, or ours when we could not ask */
+    detail?: string;
+}
+export interface KeyEntry {
+    provider: KeyOwner;
+    /** unique within a provider; `default` unless the user says otherwise */
+    name: string;
+    holds: 'secret' | 'file';
+    /** the secret itself, or a path relative to the key directory */
+    value: string;
+    addedAt: string;
+    check?: KeyCheck;
+}
+export declare const keyId: (e: Pick<KeyEntry, "provider" | "name">) => string;
+/**
+ * `provider` or `provider/name`. Returned separately rather than as a string so
+ * callers cannot accidentally re-split it, and so a name that is not a legal
+ * path segment is rejected here, once, before it can become a filename.
+ */
+export declare function parseRef(ref: string): {
+    provider: KeyOwner;
+    name?: string;
+};
+export declare class KeyStore {
+    #private;
+    private constructor();
+    static open(): Promise<KeyStore>;
+    get entries(): readonly KeyEntry[];
+    /** Every entry for a provider, the active one first. */
+    for(provider: KeyOwner): KeyEntry[];
+    find(provider: KeyOwner, name: string): KeyEntry | undefined;
+    /** The entry a run would use, or undefined when the provider has none. */
+    active(provider: KeyOwner): KeyEntry | undefined;
+    isActive(entry: KeyEntry): boolean;
+    /**
+     * Adds or replaces. A file-shaped credential is *copied* into the key
+     * directory: the point of a store is that the credential survives the
+     * original being moved, renamed or cleaned up, and a stored path that
+     * silently stops resolving is worse than no store at all.
+     */
+    add(provider: KeyOwner, name: string, raw: string): KeyEntry;
+    remove(provider: KeyOwner, name: string): boolean;
+    use(provider: KeyOwner, name: string): KeyEntry;
+    record(entry: KeyEntry, check: KeyCheck): void;
+    save(): void;
+    /** Absolute path behind a file-shaped entry. */
+    fileOf(entry: KeyEntry): string;
+    /** The plaintext an entry stands for — the only way out of the store. */
+    reveal(entry: KeyEntry): string;
+    /**
+     * What the library would see. Real environment variables win, so CI,
+     * `docker run -e` and a one-off `OPENAI_API_KEY=… zen run` all behave
+     * exactly as they did before the store existed.
+     *
+     * Services are included by default, because a tool reads its key from the
+     * environment for exactly the same reason a model adapter does.
+     */
+    environment(only?: KeyOwner[]): Record<string, string>;
+    /** Applies `environment()` to this process. Returns what it set. */
+    materialize(only?: KeyOwner[]): Record<string, string>;
+}
+/**
+ * Enough of a secret to recognise it, never enough to use it. Short values are
+ * hidden outright rather than half-shown — a twelve-character secret with eight
+ * characters visible is not masked, it is inconvenienced.
+ */
+export declare function mask(secret: string): string;
+export declare function describe(store: KeyStore, entry: KeyEntry): string;
+/**
+ * Called before a run: says plainly that there is no way to reach a model,
+ * rather than letting the SDK raise it three frames deeper as a 401.
+ *
+ * Only model providers count. A keyring holding nothing but an Exa key can
+ * search the web and cannot think, and reporting that as usable would trade
+ * one clear error here for an obscure one on the first turn.
+ */
+export declare function assertUsable(store: KeyStore): void;
+export declare function assertNotEmpty(store: KeyStore): void;
+export {};
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.js

@@ -0,0 +1,309 @@
+import { chmodSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXA_API_KEY_ENV } from '@zenera/neo';
+import { assertPrivate, ensureDir, paths, readJson, writeJson } from "./home.js";
+import { CliError, EXIT, credentialError, usageError } from "./term.js";
+// ---------------------------------------------------------------------------
+// The keyring
+//
+// The library reads credentials from the environment and from `${VAR}`
+// expansion in `agents.yaml`, and it will keep doing so. This store is a CLI
+// feature the library never learns about: before any command touches
+// `loadProject`, the selected credentials are materialized into `process.env`.
+//
+// That single decision buys three things. Nothing downstream changes.
+// `${OPENAI_API_KEY}` in a config keeps working. And a project checked out on a
+// machine that has never seen `zen` still runs, because the environment is
+// still the interface.
+// ---------------------------------------------------------------------------
+/** The vendors a *model* can come from — the library's provider kinds, verbatim. */
+export const PROVIDERS = ['openai', 'anthropic', 'google', 'vertex', 'openrouter'];
+/**
+ * Credentials that are not a way to reach a model.
+ *
+ * A tool can need a key as much as a model can, and the reasons a keyring
+ * exists — one place, 0600, materialised into the environment before a run —
+ * do not care which. What does care is everything that reasons about *models*:
+ * a machine holding nothing but an Exa key cannot run an agent, and saying it
+ * can would move the failure from `zen run`'s first line to its first turn.
+ * Hence two lists rather than one longer one, and `kind` on the shape so the
+ * few places that must tell them apart are made to say which they mean.
+ */
+export const SERVICES = ['exa'];
+/** Anything the keyring can hold a credential for. */
+export const OWNERS = [...PROVIDERS, ...SERVICES];
+/**
+ * Vertex is the odd one. The GenAI SDK resolves Application Default
+ * Credentials itself, so what is stored is a service-account *file* and what is
+ * exported is a path — not a key. Pretending otherwise would mean inventing a
+ * credential shape Google does not have.
+ */
+export const SHAPES = {
+    openai: {
+        kind: 'model',
+        env: 'OPENAI_API_KEY',
+        holds: 'secret',
+        label: 'OpenAI',
+        where: 'https://platform.openai.com/api-keys',
+    },
+    anthropic: {
+        kind: 'model',
+        env: 'ANTHROPIC_API_KEY',
+        holds: 'secret',
+        label: 'Anthropic',
+        where: 'https://console.anthropic.com/settings/keys',
+    },
+    google: {
+        kind: 'model',
+        env: 'GEMINI_API_KEY',
+        holds: 'secret',
+        label: 'Google AI Studio',
+        where: 'https://aistudio.google.com/apikey',
+    },
+    vertex: {
+        kind: 'model',
+        env: 'GOOGLE_APPLICATION_CREDENTIALS',
+        holds: 'file',
+        label: 'Vertex AI',
+        where: 'a service-account JSON key from the GCP console',
+    },
+    openrouter: {
+        kind: 'model',
+        env: 'OPENROUTER_API_KEY',
+        holds: 'secret',
+        label: 'OpenRouter',
+        where: 'https://openrouter.ai/settings/keys',
+    },
+    exa: {
+        kind: 'service',
+        env: EXA_API_KEY_ENV,
+        holds: 'secret',
+        label: 'Exa',
+        where: 'https://dashboard.exa.ai/api-keys',
+    },
+};
+export function isProvider(name) {
+    return PROVIDERS.includes(name);
+}
+export function isOwner(name) {
+    return OWNERS.includes(name);
+}
+export function assertOwner(name) {
+    if (!isOwner(name)) {
+        throw usageError(`unknown provider "${name}"`, `known providers: ${OWNERS.join(', ')}`);
+    }
+    return name;
+}
+const EMPTY = { version: 1, entries: [], active: {} };
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export const keyId = (e) => `${e.provider}/${e.name}`;
+/**
+ * `provider` or `provider/name`. Returned separately rather than as a string so
+ * callers cannot accidentally re-split it, and so a name that is not a legal
+ * path segment is rejected here, once, before it can become a filename.
+ */
+export function parseRef(ref) {
+    const [head, ...rest] = ref.split('/');
+    if (rest.length > 1) {
+        throw usageError(`"${ref}" is not a key reference`, 'use provider or provider/name');
+    }
+    const provider = assertOwner(head);
+    const name = rest[0];
+    if (name !== undefined && !NAME.test(name)) {
+        throw usageError(`"${name}" is not a usable key name`, 'letters, digits, - and _ only');
+    }
+    return { provider, name };
+}
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+export class KeyStore {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    static async open() {
+        const path = paths.keys();
+        assertPrivate(path);
+        const file = await readJson(path, EMPTY);
+        return new KeyStore({ ...EMPTY, ...file });
+    }
+    get entries() {
+        return this.#file.entries;
+    }
+    /** Every entry for a provider, the active one first. */
+    for(provider) {
+        const active = this.#file.active[provider];
+        return this.#file.entries
+            .filter((e) => e.provider === provider)
+            .sort((a, b) => Number(b.name === active) - Number(a.name === active));
+    }
+    find(provider, name) {
+        return this.#file.entries.find((e) => e.provider === provider && e.name === name);
+    }
+    /** The entry a run would use, or undefined when the provider has none. */
+    active(provider) {
+        const chosen = this.#file.active[provider];
+        if (chosen) {
+            const hit = this.find(provider, chosen);
+            if (hit) {
+                return hit;
+            }
+        }
+        return this.#file.entries.find((e) => e.provider === provider);
+    }
+    isActive(entry) {
+        return this.active(entry.provider)?.name === entry.name;
+    }
+    /**
+     * Adds or replaces. A file-shaped credential is *copied* into the key
+     * directory: the point of a store is that the credential survives the
+     * original being moved, renamed or cleaned up, and a stored path that
+     * silently stops resolving is worse than no store at all.
+     */
+    add(provider, name, raw) {
+        if (!NAME.test(name)) {
+            throw usageError(`"${name}" is not a usable key name`, 'letters, digits, - and _ only');
+        }
+        const shape = SHAPES[provider];
+        const entry = {
+            provider,
+            name,
+            holds: shape.holds,
+            value: shape.holds === 'file' ? this.#absorb(provider, name, raw) : raw,
+            addedAt: new Date().toISOString(),
+        };
+        const at = this.#file.entries.findIndex((e) => e.provider === provider && e.name === name);
+        if (at >= 0) {
+            this.#file.entries[at] = entry;
+        }
+        else {
+            this.#file.entries.push(entry);
+        }
+        this.#file.active[provider] ??= name;
+        return entry;
+    }
+    remove(provider, name) {
+        const at = this.#file.entries.findIndex((e) => e.provider === provider && e.name === name);
+        if (at < 0) {
+            return false;
+        }
+        this.#file.entries.splice(at, 1);
+        if (this.#file.active[provider] === name) {
+            delete this.#file.active[provider];
+            const next = this.#file.entries.find((e) => e.provider === provider);
+            if (next) {
+                this.#file.active[provider] = next.name;
+            }
+        }
+        return true;
+    }
+    use(provider, name) {
+        const entry = this.find(provider, name);
+        if (!entry) {
+            throw usageError(`no key ${provider}/${name}`, 'see: zen key ls');
+        }
+        this.#file.active[provider] = name;
+        return entry;
+    }
+    record(entry, check) {
+        const hit = this.find(entry.provider, entry.name);
+        if (hit) {
+            hit.check = check;
+        }
+    }
+    save() {
+        ensureDir(paths.home());
+        writeJson(paths.keys(), this.#file);
+    }
+    /** Absolute path behind a file-shaped entry. */
+    fileOf(entry) {
+        return join(paths.keyDir(), entry.value);
+    }
+    /** The plaintext an entry stands for — the only way out of the store. */
+    reveal(entry) {
+        return entry.holds === 'file' ? this.fileOf(entry) : entry.value;
+    }
+    /**
+     * What the library would see. Real environment variables win, so CI,
+     * `docker run -e` and a one-off `OPENAI_API_KEY=… zen run` all behave
+     * exactly as they did before the store existed.
+     *
+     * Services are included by default, because a tool reads its key from the
+     * environment for exactly the same reason a model adapter does.
+     */
+    environment(only) {
+        const env = {};
+        for (const provider of only ?? OWNERS) {
+            const entry = this.active(provider);
+            if (!entry) {
+                continue;
+            }
+            const { env: name } = SHAPES[provider];
+            if (process.env[name]) {
+                continue;
+            }
+            env[name] = this.reveal(entry);
+        }
+        return env;
+    }
+    /** Applies `environment()` to this process. Returns what it set. */
+    materialize(only) {
+        const env = this.environment(only);
+        Object.assign(process.env, env);
+        return env;
+    }
+    #absorb(provider, name, raw) {
+        const source = resolve(raw);
+        if (!existsSync(source) || !statSync(source).isFile()) {
+            throw usageError(`${SHAPES[provider].label} credentials must be a file`, `no such file: ${source}`);
+        }
+        const target = `${provider}-${name}.json`;
+        ensureDir(paths.keyDir());
+        const path = join(paths.keyDir(), target);
+        copyFileSync(source, path);
+        // copyFile keeps the source's mode, which may well be group-readable.
+        chmodSync(path, 0o600);
+        return target;
+    }
+}
+// ---------------------------------------------------------------------------
+// Display
+// ---------------------------------------------------------------------------
+/**
+ * Enough of a secret to recognise it, never enough to use it. Short values are
+ * hidden outright rather than half-shown — a twelve-character secret with eight
+ * characters visible is not masked, it is inconvenienced.
+ */
+export function mask(secret) {
+    if (secret.length <= 12) {
+        return '•'.repeat(8);
+    }
+    return `${secret.slice(0, 4)}…${secret.slice(-4)}`;
+}
+export function describe(store, entry) {
+    return entry.holds === 'file' ? store.fileOf(entry) : mask(entry.value);
+}
+// ---------------------------------------------------------------------------
+// Gate
+// ---------------------------------------------------------------------------
+/**
+ * Called before a run: says plainly that there is no way to reach a model,
+ * rather than letting the SDK raise it three frames deeper as a 401.
+ *
+ * Only model providers count. A keyring holding nothing but an Exa key can
+ * search the web and cannot think, and reporting that as usable would trade
+ * one clear error here for an obscure one on the first turn.
+ */
+export function assertUsable(store) {
+    const reachable = PROVIDERS.filter((p) => process.env[SHAPES[p].env] || store.active(p) !== undefined);
+    if (reachable.length === 0) {
+        throw credentialError('no credentials for any provider', 'add one with: zen key add openai');
+    }
+}
+export function assertNotEmpty(store) {
+    if (store.entries.length === 0) {
+        throw new CliError('the keyring is empty', EXIT.credentials, 'add one: zen key add openai');
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/lib.d.ts

@@ -0,0 +1,9 @@
+export { extract, invokedAs, one, parse, split, type Parsed, type Split } from './args.ts';
+export { printBanner, type BannerText } from './banner.ts';
+export type { Command, Context } from './command.ts';
+export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from './home.ts';
+export { assertNotEmpty, assertOwner, assertUsable, describe, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, type KeyCheck, type KeyEntry, type KeyOwner, type Liveness, type Provider, type Service, } from './keys.ts';
+export { probe, probeAll } from './liveness.ts';
+export { ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, type OwnedContainer, type PodmanOptions, type PodmanStatus, } from './podman.ts';
+export { ago, bold, CliError, count, credentialError, cyan, dim, EXIT, fail, green, invalidError, isInteractive, json, note, pad, red, table, usageError, warn, write, writeAll, yellow, type ExitCode, } from './term.ts';
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// The library face of the CLI
+//
+// `zen` is a program, not a library, and everything in `src/` is written that
+// way: it prints, it prompts, it carries process exit codes. But the keyring is
+// a machine-level thing rather than a command-level one — where credentials
+// live, how they are stored 0600, how they reach `process.env` before a run —
+// and a second front end on this machine has to agree with `zen` about all
+// three or the two disagree about which key is active.
+//
+// `Command` is here for the other direction: a sibling package implements it
+// and `zen` loads it by name, so a new package is a subcommand rather than a
+// new binary.
+//
+// So this file, and only this file, is what another package may import. It is
+// deliberately a hand-written list rather than a `export *`: every name here is
+// public API of a published package and is bound by its version, which is a
+// reason to add to it slowly.
+//
+// One caveat travels with `term.ts`: `CliError` carries an exit code and the
+// writers go to stdout/stderr. That vocabulary belongs to startup. A server
+// must not let a `CliError` escape into a request handler.
+// ---------------------------------------------------------------------------
+export { extract, invokedAs, one, parse, split } from "./args.js";
+export { printBanner } from "./banner.js";
+export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from "./home.js";
+export { assertNotEmpty, assertOwner, assertUsable, describe, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, } from "./keys.js";
+export { probe, probeAll } from "./liveness.js";
+export { ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "./podman.js";
+export { ago, bold, CliError, count, credentialError, cyan, dim, EXIT, fail, green, invalidError, isInteractive, json, note, pad, red, table, usageError, warn, write, writeAll, yellow, } from "./term.js";
+//# sourceMappingURL=lib.js.map

package/dist/liveness.d.ts

@@ -0,0 +1,23 @@
+import { type KeyCheck, type KeyEntry, type KeyStore } from './keys.ts';
+/**
+ * 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 declare function probe(store: KeyStore, entry: KeyEntry): Promise<KeyCheck>;
+/**
+ * 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 declare function probeAll(store: KeyStore, entries: readonly KeyEntry[], onProbe?: (entry: KeyEntry, index: number, total: number) => void): Promise<[KeyEntry, KeyCheck][]>;
+//# sourceMappingURL=liveness.d.ts.map