@zenera/cli 1.1.36 → 1.1.39

package/dist/audit.d.ts

@@ -1,58 +0,0 @@
-import { type ModelRequirement } from '@zenera/neo';
-import { type KeyOwner, type KeyStore } from './keys.ts';
-/** Which key of the config named a reference: `model:`/`models:` or `embedding:`/`embeddings:`. */
-export type DeclaredRole = 'model' | 'embedding';
-export interface ModelIssue {
-    /** the model as the config names it: an alias, or the ref itself */
-    name: string;
-    /** what the config declared it for */
-    role: DeclaredRole;
-    /** the provider it resolves to */
-    provider: string;
-    /** the variable that would carry the credential */
-    env: string;
-    /** `missing` — nothing to authenticate with. `dead` — rejected when checked.
-     *  `blocked` — accepted, and then refused by the account behind it. */
-    reason: 'missing' | 'dead' | 'blocked';
-    /** the provider's own words, when it was the one to say no */
-    detail?: string;
-    /** what to do about a refusal that a new key would not fix */
-    fix?: string;
-    /** the keyring provider the fix names, when the kind is one of them */
-    add?: KeyOwner;
-}
-/**
- * Whether a requirement is actually met, and under which variable.
- *
- * `satisfied` is the library's answer and it is about api keys, which is the
- * wrong question for Vertex: that kind is `keyOptional` because it can
- * authenticate from a service-account file instead. So both of its variables
- * are looked for, along with the file `gcloud` leaves behind.
- *
- * The variable named back is the one that is actually set, because a report
- * that named `VERTEX_API_KEY` while the audit silently checked
- * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
- * the wrong one is the one people would act on. With nothing set there is no
- * such answer, so it names the form the provider is usually reached by.
- */
-export declare function credentialFor(need: ModelRequirement): {
-    env: string;
-    present: boolean;
-};
-/**
- * Reports the models a run could not reach. Best effort by design: a config
- * that will not parse, or that names a provider that does not exist, is the
- * loader's to report — precisely, and with the offending key named. Guessing
- * at it here would only produce a worse version of the same message.
- *
- * Call *after* `KeyStore.materialize()`, so the keyring's keys are as visible
- * here as they will be to the library.
- */
-export declare function auditModels(projectDir: string, store: KeyStore): ModelIssue[];
-/**
- * One line, and the command that fixes it. A warning nobody can act on is
- * noise, so the fix is part of the sentence rather than something to go and
- * look up.
- */
-export declare function describeIssue(issue: ModelIssue): string;
-//# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -1,148 +0,0 @@
-import { projectRegistry, readProjectConfig, } from '@zenera/neo';
-import { envNames, form, gcloudAdc, isOwner, isProvider, SHAPES, } from "./keys.js";
-import { bold, dim } from "./term.js";
-/**
- * Every model the project names, keyed by how one would refer to it.
- *
- * The `models:` table comes first so a declared alias keeps its own name in the
- * report; a `model:` that names one collapses onto it rather than appearing
- * twice, and a `model:` that names no alias is a shorthand standing for itself.
- *
- * Embeddings are walked the same way and kept in their own list: an alias may
- * legitimately appear under both keys meaning two different things, and they
- * are two credentials to check either way.
- */
-function declared(config) {
-    // The schema widens `reasoningEffort` to `string` on purpose, which is the
-    // one thing keeping a config's model spec from being a `ModelSpec`. The
-    // loader hands the same cast to `models.model()` for the same reason.
-    const models = new Map(Object.entries(config.models ?? {}));
-    const add = (into, ref) => {
-        if (ref && !into.has(ref)) {
-            into.set(ref, ref);
-        }
-    };
-    add(models, config.model);
-    for (const agent of config.agents) {
-        add(models, agent.model);
-    }
-    const embeddings = new Map(Object.entries(config.embeddings ?? {}));
-    add(embeddings, config.embedding);
-    return new Map([
-        ['model', models],
-        ['embedding', embeddings],
-    ]);
-}
-/**
- * Whether a requirement is actually met, and under which variable.
- *
- * `satisfied` is the library's answer and it is about api keys, which is the
- * wrong question for Vertex: that kind is `keyOptional` because it can
- * authenticate from a service-account file instead. So both of its variables
- * are looked for, along with the file `gcloud` leaves behind.
- *
- * The variable named back is the one that is actually set, because a report
- * that named `VERTEX_API_KEY` while the audit silently checked
- * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
- * the wrong one is the one people would act on. With nothing set there is no
- * such answer, so it names the form the provider is usually reached by.
- */
-export function credentialFor(need) {
-    if (need.gateway) {
-        return { env: need.apiKeyEnv, present: need.satisfied };
-    }
-    const provider = isProvider(need.kind) ? need.kind : undefined;
-    // A provider with a file form can authenticate without an api key, which is
-    // the only thing `satisfied` knows how to look for.
-    if (provider && SHAPES[provider].forms.some((f) => f.holds === 'file')) {
-        const set = envNames(provider).find((name) => process.env[name]);
-        return { env: set ?? form(provider).env, present: Boolean(set) || Boolean(gcloudAdc()) };
-    }
-    return { env: need.apiKeyEnv, present: need.satisfied };
-}
-/**
- * Reports the models a run could not reach. Best effort by design: a config
- * that will not parse, or that names a provider that does not exist, is the
- * loader's to report — precisely, and with the offending key named. Guessing
- * at it here would only produce a worse version of the same message.
- *
- * Call *after* `KeyStore.materialize()`, so the keyring's keys are as visible
- * here as they will be to the library.
- */
-export function auditModels(projectDir, store) {
-    let config;
-    try {
-        config = readProjectConfig(projectDir).config;
-    }
-    catch {
-        return [];
-    }
-    const registry = projectRegistry(config);
-    const issues = [];
-    for (const [role, refs] of declared(config)) {
-        for (const [name, ref] of refs) {
-            let need;
-            try {
-                need = registry.requirement(ref);
-            }
-            catch {
-                continue;
-            }
-            const { env, present } = credentialFor(need);
-            const provider = need.gateway && isOwner(need.gateway)
-                ? need.gateway
-                : isProvider(need.kind)
-                    ? need.kind
-                    : undefined;
-            if (!present) {
-                issues.push({
-                    name,
-                    role,
-                    provider: need.provider,
-                    env,
-                    reason: 'missing',
-                    add: provider,
-                });
-                continue;
-            }
-            // A key that the provider itself rejected last time it was asked.
-            // Said as a warning rather than an error because a key can be
-            // reinstated between the check and the run, and a stale verdict must
-            // not be the thing that stops a run from being attempted.
-            const check = provider ? store.active(provider)?.check : undefined;
-            if (check?.state === 'dead' || check?.state === 'blocked') {
-                issues.push({
-                    name,
-                    role,
-                    provider: need.provider,
-                    env,
-                    reason: check.state,
-                    detail: check.detail,
-                    fix: check.fix,
-                    add: provider,
-                });
-            }
-        }
-    }
-    return issues;
-}
-/**
- * One line, and the command that fixes it. A warning nobody can act on is
- * noise, so the fix is part of the sentence rather than something to go and
- * look up.
- */
-export function describeIssue(issue) {
-    const what = `${bold(issue.name)} (${issue.provider}${issue.role === 'embedding' ? ', embedding' : ''})`;
-    if (issue.reason === 'missing') {
-        const fix = issue.add ? `zen key add ${issue.add}` : `set ${issue.env}`;
-        return `${what} has no credential — ${issue.env} is not set; ${dim(fix)}`;
-    }
-    const why = issue.detail ? `: ${issue.detail}` : '';
-    if (issue.reason === 'blocked') {
-        const list = `zen models ls --${issue.role === 'embedding' ? 'embeddings' : 'chat'}`;
-        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? list)}`;
-    }
-    const fix = `zen key check ${issue.add ?? ''}`.trim();
-    return `${what} was rejected when last checked${why} — ${dim(fix)}`;
-}
-//# sourceMappingURL=audit.js.map

package/dist/env.d.ts

@@ -1,20 +0,0 @@
-/** The file, relative to the project directory. */
-export declare const ENV_FILE = ".env";
-export interface ProjectEnv {
-    /** the file it was read from */
-    path: string;
-    /** every name the file declares, whether or not its value won */
-    names: string[];
-}
-/**
- * Reads `<dir>/.env` into `process.env`, without overwriting anything already
- * set, and returns the names it found. A project with no such file is not a
- * problem to report — most have none — so the answer is simply `undefined`.
- *
- * The names are returned in full, including the ones the environment already
- * answered: the variable is in play either way, and the sandbox forwards by
- * name, so what it needs to know is which names matter and not which of the
- * two sources supplied them.
- */
-export declare function loadProjectEnv(dir: string): ProjectEnv | undefined;
-//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -1,65 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-import { parseEnv } from 'node:util';
-import { FILE_ENVS } from "./keys.js";
-// ---------------------------------------------------------------------------
-// The project's `.env`
-//
-// A project is a directory, and some of what it needs to run is particular to
-// it: the token for the service it talks to, the base url of the environment
-// it talks to it in. The keyring answers "what can this machine pay for"; this
-// answers "what does this project need", and the two are different questions
-// often enough to be worth two places.
-//
-// Precedence is the same one everything else here uses — the real environment
-// always wins. What is already set in the shell is left alone, this file fills
-// the gaps, and the keyring fills whatever is still missing after that. So a
-// variable exported for one command still overrides the file, which is the
-// behaviour anybody typing `FOO=bar zen run` is expecting.
-//
-// The names, not the values, are what leaves this module: they are what the
-// sandbox forwards, and forwarding by name is what keeps a secret out of an
-// argv. See `forwarded()` in sandbox.ts for the rest of that story.
-// ---------------------------------------------------------------------------
-/** The file, relative to the project directory. */
-export const ENV_FILE = '.env';
-/**
- * Reads `<dir>/.env` into `process.env`, without overwriting anything already
- * set, and returns the names it found. A project with no such file is not a
- * problem to report — most have none — so the answer is simply `undefined`.
- *
- * The names are returned in full, including the ones the environment already
- * answered: the variable is in play either way, and the sandbox forwards by
- * name, so what it needs to know is which names matter and not which of the
- * two sources supplied them.
- */
-export function loadProjectEnv(dir) {
-    const path = join(dir, ENV_FILE);
-    if (!existsSync(path)) {
-        return undefined;
-    }
-    const names = [];
-    for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
-        if (value === undefined) {
-            continue;
-        }
-        names.push(name);
-        // An empty string is not an answer: tools test for absence, and a
-        // commented-out line someone half-filled in should not shadow a key
-        // the keyring has.
-        if (!process.env[name]) {
-            process.env[name] = located(dir, name, value);
-        }
-    }
-    return { path, names };
-}
-/**
- * A service-account file is normally kept beside the `.env` that names it, so
- * a relative path there means relative to the *project* — not to wherever the
- * command happened to be run, which is what both the Google SDK and podman's
- * bind mount would otherwise make of it.
- */
-function located(dir, name, value) {
-    return FILE_ENVS.includes(name) && !isAbsolute(value) ? resolve(dir, value) : value;
-}
-//# sourceMappingURL=env.js.map

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