@zenera/cli 1.1.36 → 1.1.37

package/dist/home.d.ts

@@ -1,35 +0,0 @@
-export declare function home(): string;
-export declare const paths: {
-    home: typeof home;
-    projects: () => string;
-    keys: () => string;
-    keyDir: () => string;
-    faker: () => string;
-    /** what the meta agent runs on, which is a choice about a tool, not a project */
-    meta: () => string;
-    /** work already done and worth keeping: vectors, parses, model listings */
-    cache: () => string;
-};
-/** Creates a directory owner-only, and leaves an existing one's mode alone. */
-export declare function ensureDir(dir: string, mode?: number): string;
-export declare function ensureHome(): string;
-/**
- * Refuses to read a credential file that anyone else can read, the way `ssh`
- * does. A world-readable key is not a warning-level event: warnings are
- * ignored, and the whole point of the store is that the secret is not lying
- * around in the open.
- *
- * Windows reports a mode that means nothing here, so the check is POSIX-only.
- */
-export declare function assertPrivate(path: string): void;
-export declare function readJson<T>(path: string, fallback: T): Promise<T>;
-/**
- * Write to a sibling and rename. A crash then leaves either the old file or the
- * new one, never a half-written registry — which matters more here than it
- * looks, because the alternative is a corrupt `keys.json` locking someone out
- * of every provider at once.
- *
- * Synchronous on purpose: this is also called from exit paths.
- */
-export declare function writeJson(path: string, value: unknown, mode?: number): void;
-//# sourceMappingURL=home.d.ts.map

package/dist/home.js

@@ -1,112 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { chmodSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { CliError, EXIT } from "./term.js";
-// ---------------------------------------------------------------------------
-// The home directory
-//
-// ~/.zenera/neo holds exactly two kinds of thing: credentials, which belong to
-// the machine and never to a project, and an index of where projects are, which
-// is a convenience and is allowed to be wrong.
-//
-// `ZENERA_HOME` moves the whole tree. That is what makes any of this testable
-// and what lets CI start from an empty one.
-// ---------------------------------------------------------------------------
-const DIR_MODE = 0o700;
-const FILE_MODE = 0o600;
-export function home() {
-    const override = process.env.ZENERA_HOME?.trim();
-    return override ? override : join(homedir(), '.zenera', 'neo');
-}
-export const paths = {
-    home,
-    projects: () => join(home(), 'projects.json'),
-    keys: () => join(home(), 'keys.json'),
-    keyDir: () => join(home(), 'keys'),
-    faker: () => join(home(), 'faker'),
-    /** what the meta agent runs on, which is a choice about a tool, not a project */
-    meta: () => join(home(), 'meta.json'),
-    /** work already done and worth keeping: vectors, parses, model listings */
-    cache: () => join(home(), 'cache'),
-};
-/** Creates a directory owner-only, and leaves an existing one's mode alone. */
-export function ensureDir(dir, mode = DIR_MODE) {
-    mkdirSync(dir, { recursive: true, mode });
-    return dir;
-}
-export function ensureHome() {
-    return ensureDir(home());
-}
-// ---------------------------------------------------------------------------
-// Permissions
-// ---------------------------------------------------------------------------
-/**
- * Refuses to read a credential file that anyone else can read, the way `ssh`
- * does. A world-readable key is not a warning-level event: warnings are
- * ignored, and the whole point of the store is that the secret is not lying
- * around in the open.
- *
- * Windows reports a mode that means nothing here, so the check is POSIX-only.
- */
-export function assertPrivate(path) {
-    if (process.platform === 'win32') {
-        return;
-    }
-    let mode;
-    try {
-        mode = statSync(path).mode;
-    }
-    catch {
-        return; // absent is fine; it will be created with the right mode
-    }
-    const open = mode & 0o077;
-    if (open !== 0) {
-        const octal = (mode & 0o777).toString(8).padStart(3, '0');
-        throw new CliError(`permissions ${octal} on ${path} are too open`, EXIT.credentials, `run: chmod 600 ${path}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// JSON files
-// ---------------------------------------------------------------------------
-export async function readJson(path, fallback) {
-    let text;
-    try {
-        text = await readFile(path, 'utf8');
-    }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            return fallback;
-        }
-        throw err;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new CliError(`${path} is not valid JSON`, EXIT.invalid, 'fix or delete the file');
-    }
-}
-/**
- * Write to a sibling and rename. A crash then leaves either the old file or the
- * new one, never a half-written registry — which matters more here than it
- * looks, because the alternative is a corrupt `keys.json` locking someone out
- * of every provider at once.
- *
- * Synchronous on purpose: this is also called from exit paths.
- */
-export function writeJson(path, value, mode = FILE_MODE) {
-    ensureDir(dirname(path));
-    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    try {
-        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });
-        chmodSync(tmp, mode);
-        renameSync(tmp, path);
-    }
-    catch (err) {
-        rmSync(tmp, { force: true });
-        throw err;
-    }
-}
-//# sourceMappingURL=home.js.map

package/dist/ids.d.ts

@@ -1,12 +0,0 @@
-export declare function stamp(now?: Date): string;
-/**
- * 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 declare function isStamp(value: string): boolean;
-/** Human-readable form of a stamp: `2026-08-25 14:30:12`. */
-export declare function stampDate(id: string): string;
-/** ISO instant a stamp names, for `ago()`. Local time in, local time out. */
-export declare function stampInstant(id: string): string | undefined;
-//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -1,44 +0,0 @@
-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/image.d.ts

@@ -1,16 +0,0 @@
-import { type SandboxConfig } from '@zenera/neo';
-export interface ResolvedBuild {
-    /** the image reference to run, and to build under */
-    tag: string;
-    /** absolute path to the Dockerfile */
-    dockerfile: string;
-    /** absolute path to the build context */
-    context: string;
-}
-/**
- * What the config's `build:` block means on this machine, or nothing if it has
- * none. Both paths are resolved against the project root and refused if they
- * escape it — a project is data someone else may have written.
- */
-export declare function resolveBuild(root: string, config?: SandboxConfig): ResolvedBuild | undefined;
-//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -1,85 +0,0 @@
-import { projectDir, projectFile } from '@zenera/neo';
-import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
-import { dirname, join, relative, sep } from 'node:path';
-// ---------------------------------------------------------------------------
-// Building the sandbox image
-//
-// `image:` names something to pull; `build:` names a Dockerfile to build. The
-// library never learns the difference — it is handed a resolved reference and
-// runs it — because building is a host concern with a container engine
-// attached to it, and that is the line this CLI exists on the other side of.
-//
-// The tag is a function of what goes into the image, and it has to be: the
-// container's name in @zenera/neo hashes `spec.image`, so a tag that stayed put
-// while the Dockerfile changed would leave a `persist: true` container running
-// last week's filesystem, with nothing anywhere saying so. Hashing the context
-// as well as the Dockerfile means an edit to either yields a new tag, a new
-// container name, and a build — which is the only honest answer.
-// ---------------------------------------------------------------------------
-/** Not scoped: a `/` or an `@` is not a legal image tag. */
-const TAG = 'localhost/zenera-sandbox';
-/**
- * A build context is meant to be small — a Dockerfile and whatever it copies.
- * Hashing a directory someone pointed at their whole home folder would hang
- * before it was wrong, so it stops and says which key to narrow.
- */
-const MAX_CONTEXT_FILES = 2_000;
-/**
- * What the config's `build:` block means on this machine, or nothing if it has
- * none. Both paths are resolved against the project root and refused if they
- * escape it — a project is data someone else may have written.
- */
-export function resolveBuild(root, config) {
-    if (!config?.build) {
-        return undefined;
-    }
-    const dockerfile = projectFile(root, config.build.dockerfile, 'sandbox.build.dockerfile');
-    const context = config.build.context
-        ? projectDir(root, config.build.context, 'sandbox.build.context')
-        : dirname(dockerfile);
-    return { tag: `${TAG}:${digest(dockerfile, context)}`, dockerfile, context };
-}
-/**
- * The content address of a build: the Dockerfile, then every file the build can
- * see, by path and by content.
- *
- * `.dockerignore` is not read. The engine honours it and we do not, so an
- * ignored file that changes yields a new tag and a build that produces the same
- * image — wasteful, never wrong, and the alternative is reimplementing a match
- * syntax whose disagreements would be silent.
- */
-function digest(dockerfile, context) {
-    const hash = createHash('sha256');
-    hash.update(readFileSync(dockerfile));
-    for (const rel of walk(context)) {
-        // The separator is hashed as posix so the same tree tags the same on
-        // any host.
-        hash.update(`\0${rel.split(sep).join('/')}\0`);
-        hash.update(readFileSync(join(context, rel)));
-    }
-    return hash.digest('hex').slice(0, 12);
-}
-/** Every file under `dir`, relative and sorted, so the digest is stable. */
-function walk(dir) {
-    const found = [];
-    const pending = [dir];
-    while (pending.length > 0) {
-        const at = pending.pop();
-        for (const entry of readdirSync(at, { withFileTypes: true })) {
-            const path = join(at, entry.name);
-            if (entry.isDirectory()) {
-                pending.push(path);
-            }
-            else if (entry.isFile()) {
-                found.push(relative(dir, path));
-            }
-        }
-        if (found.length > MAX_CONTEXT_FILES) {
-            throw new Error(`sandbox.build.context: ${dir} holds more than ${MAX_CONTEXT_FILES} files — ` +
-                'point `context:` at the directory the build actually copies from');
-        }
-    }
-    return found.sort();
-}
-//# sourceMappingURL=image.js.map

package/dist/keys.d.ts

@@ -1,269 +0,0 @@
-/** 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];
-/**
- * Somewhere every model can be reached through, with one key. Its own list for
- * the same reason as `SERVICES`: it is neither a vendor a model comes from nor
- * a tool, and a gateway entry only counts while the keyring is in its mode.
- */
-export declare const GATEWAYS: readonly ["bifrost"];
-export type GatewayOwner = (typeof GATEWAYS)[number];
-/** `direct` calls each vendor with its own key; `bifrost` sends everything through the gateway. */
-export type KeyMode = 'direct' | GatewayOwner;
-export declare const MODES: readonly KeyMode[];
-/** Anything the keyring can hold a credential for. */
-export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa", "bifrost"];
-export type KeyOwner = Provider | Service | GatewayOwner;
-/**
- * One way a credential can arrive.
- *
- * A provider that accepts two accepts two of these, and they agree about
- * nothing: not the variable, not whether the value is the secret or a path to
- * it, not where you go to get one. So the alternative is a whole form rather
- * than a wider `holds`.
- */
-export interface CredentialForm {
-    /** what the value is: a secret string, or a path to a credentials file */
-    holds: 'secret' | 'file';
-    /** environment variable the library reads */
-    env: string;
-    /** where to get one, printed when there is none */
-    where: string;
-}
-interface ProviderShape {
-    /** whether this is somewhere a model lives, something a tool calls, or a way to every model */
-    kind: 'model' | 'service' | 'gateway';
-    label: string;
-    /** the ways in, first being the one this provider is usually reached by */
-    forms: [CredentialForm, ...CredentialForm[]];
-}
-/**
- * Vertex is the odd one, and it is odd twice.
- *
- * Its usual credential is not a key at all: the GenAI SDK resolves Application
- * Default Credentials itself, so what is stored is a service-account *file* and
- * what is exported is a path. But it also accepts an express-mode api key,
- * which is an ordinary secret under an entirely different variable. The two are
- * alternatives — express mode addresses no project — so which form a credential
- * is gets decided per entry rather than per provider.
- */
-export declare const SHAPES: Record<KeyOwner, ProviderShape>;
-/**
- * The form a provider is usually reached by — for the questions that have to
- * have one answer, like which variable to name when nothing is set yet.
- */
-export declare function form(provider: KeyOwner): CredentialForm;
-/** Every variable a provider's credential could arrive in, usual one first. */
-export declare function envNames(provider: KeyOwner): string[];
-/** Variables that name a credential *file* rather than carrying the secret. */
-export declare const FILE_ENVS: string[];
-/** The variable this particular credential occupies. */
-export declare function envOf(entry: Pick<KeyEntry, 'provider' | 'holds' | 'env'>): string;
-export declare function isProvider(name: string): name is Provider;
-export declare function isOwner(name: string): name is KeyOwner;
-export declare function isGateway(name: string): name is GatewayOwner;
-export declare function assertOwner(name: string): KeyOwner;
-/**
- * `blocked` is the credential being fine and the *account* not: an api switched
- * off in the project, a spent balance, a model this key was never granted. It
- * is split out of `dead` because the two want opposite actions — rotating a key
- * that authenticated perfectly is the wrong afternoon.
- */
-export type Liveness = 'live' | 'dead' | 'blocked' | '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;
-    /** what to actually do about it, when the refusal implies something specific */
-    fix?: 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;
-    /** the variable it is exported as; absent on entries written before providers had two */
-    env?: string;
-    /** vertex, file-shaped only: what the library would otherwise have to be told twice */
-    project?: string;
-    location?: string;
-    /** gateway only: where it listens */
-    url?: 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;
-};
-/** Which of a provider's forms a raw value is, decided by the value itself. */
-export declare function formOf(provider: KeyOwner, raw: string): CredentialForm;
-/**
- * Throws on a name that is neither an endpoint nor shaped like a region — `usa`,
- * or `us-central` with its digit missing — because those are 404s at the first
- * call, a long way from the command that caused them. Returns false for a
- * well-formed name that is merely unrecognised, which the caller reports and
- * stores anyway: Google adds regions, and a list compiled here would be wrong
- * before it was old.
- */
-export declare function checkRegion(region: string): boolean;
-/** What a credential cannot say about itself. */
-export interface KeyMeta {
-    /** GCP project id, for a Vertex service account */
-    project?: string;
-    /** GCP region, or `global` */
-    location?: string;
-    /** gateway base url */
-    url?: 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.
-     *
-     * Which form a value is, when the provider accepts two, is read off the
-     * value: a path that is there is a credentials file, and anything else is a
-     * secret. Asking would be a flag to get wrong, and a service-account key
-     * and an api key are not mistakable for one another.
-     */
-    add(provider: KeyOwner, name: string, raw: string, meta?: KeyMeta): KeyEntry;
-    remove(provider: KeyOwner, name: string): boolean;
-    use(provider: KeyOwner, name: string): KeyEntry;
-    record(entry: KeyEntry, check: KeyCheck): void;
-    /** A `BIFROST_BASE_URL` in the environment wins over the keyring, as it does for the runtime. */
-    get mode(): KeyMode;
-    get modeFrom(): 'env' | 'keyring';
-    /** Refuses a gateway mode with no gateway to send anything to. */
-    setMode(mode: KeyMode): void;
-    save(): void;
-    /**
-     * Absolute path behind a file-shaped entry. Stored entries name a file in
-     * the key directory; an ambient one already knows where it is.
-     */
-    fileOf(entry: KeyEntry): string;
-    /** The plaintext an entry stands for — the only way out of the store. */
-    reveal(entry: KeyEntry): string;
-    /**
-     * Which GCP project a Vertex entry addresses, and how that was decided —
-     * the same order the library resolves it in, so what is shown is what will
-     * be called. A service-account file states its own project, and nothing was
-     * ever stored for it, so an entry with no `project` is not an entry with no
-     * project: it is one whose project is only knowable by reading the file.
-     */
-    projectOf(entry: KeyEntry): {
-        id: string;
-        from: 'env' | 'stored' | 'file';
-    } | undefined;
-    /**
-     * 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.
-     *
-     * In a gateway mode the gateway's key replaces every vendor's, so those are
-     * withheld: nothing would read them, and the sandbox would be handed keys
-     * the run never needed. In `direct` mode it is the gateway that is withheld,
-     * since its url alone is what switches the library over.
-     */
-    environment(only?: KeyOwner[]): Record<string, string>;
-    /**
-     * Copies the keyring's active credentials into `process.env`, the only
-     * place the library looks. Must run before anything that reads them —
-     * in `bifrost` mode this is what sets `BIFROST_BASE_URL`, so `gatewayOf()`
-     * returns undefined until it has. 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;
-/**
- * A credential the keyring does not hold but the libraries will nonetheless
- * find: a variable already in the environment, or the file `gcloud auth
- * application-default login` writes.
- *
- * These have to be listed, because they are the reason a provider works when
- * `zen key ls` says there is nothing for it — and the reason one keeps working
- * after its entry is removed.
- */
-export interface Ambient {
-    provider: KeyOwner;
-    /** the variable it arrived in; absent when it was found where the SDK looks */
-    env?: string;
-    holds: 'secret' | 'file';
-    value: string;
-}
-/** How an ambient credential is named on the command line: it has no key name. */
-export declare function ambientId(cred: Ambient): string;
-/**
- * Where `gcloud auth application-default login` leaves its credentials. The
- * GenAI SDK reads this without being told to, so it counts even though nothing
- * in the environment mentions it.
- */
-export declare function gcloudAdc(): string | undefined;
-export declare function ambient(store: KeyStore, only?: KeyOwner[]): Ambient[];
-/**
- * Every credential variable this process is carrying, whatever put it there.
- *
- * Read off the environment rather than off the store, and deliberately: by the
- * time anyone asks, `materialize()` has already run, so the environment is the
- * union of the keyring and whatever the shell brought — which is exactly the
- * set of credentials the run is actually using.
- */
-export declare function credentials(): {
-    env: string;
-    holds: 'secret' | 'file';
-    value: 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