@zenera/cli 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ryabov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# @zenera/cli
+
+**`zen` — put a team of AI agents to work on your problem, in one command.**
+
+Describe the job in plain language and you get back a working multi-agent
+system: specialists that reason, read and write files, run real commands, look
+things up when they need to, and hand work to each other until the job is done.
+No framework to learn, no application to build, no glue code to maintain.
+
+The system is a folder — so it is yours. Commit it, review it, improve it, send
+it to a colleague, or start from one someone else already built and make it your
+own. It runs the same everywhere, on whichever models you prefer, and it never
+carries your keys with it.
+
+[![npm](https://img.shields.io/npm/v/@zenera/cli.svg)](https://www.npmjs.com/package/@zenera/cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+
+> Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). This is an
+> open-source side project for experimentation and chore work — **not** the
+> official Zenera AI Platform. It carries no support or stability promises.
+
+## Install
+
+Node.js 24+. Install the CLI together with at least one vendor SDK — they are
+**optional peer dependencies**, so you only pay for the ones you use.
+
+```sh
+npm i -g @zenera/cli openai
+#                or @anthropic-ai/sdk, @google/genai, @openrouter/sdk — any mix of them
+```
+
+Or without installing anything:
+
+```sh
+npx @zenera/cli --help
+```
+
+## Quickstart
+
+Four commands, from nothing to an answer:
+
+```sh
+npm i -g @zenera/cli openai   # the CLI, plus one vendor SDK
+zen key add openai           # prompts with the echo off; stored in ~/.zenera
+zen init my-project          # scaffolds a project and registers it
+cd my-project && zen run "introduce yourself"
+```
+
+Then the rest of the loop:
+
+```sh
+zen run                         # nothing to say yet — a TUI on a terminal
+zen check                       # validate the project and every file it names
+zen inspect                     # open the last run's report.html
+zen list --sessions             # every project, its sessions and last run
+echo "triage this" | zen run --quiet | jq
+```
+
+Or ask a question from wherever you are and get an answer back:
+
+```sh
+cd ~/code/some-repo
+zen run my-project "summarise this repo and write NOTES.md"
+```
+
+A prompt on the command line asks nothing: a fresh session, the directory you
+are standing in as the workspace, writable. `--session`, `--workspace` and
+`--read-only` override that.
+
+Then open the folder in your editor and tell your coding agent what the system
+should do. It writes the agents; `zen run` runs them; `zen inspect` shows you
+every request, tool call and token it spent.
+
+## A worked example
+
+A two-agent system that reads a repository and writes a note about it — the
+whole thing, in three files.
+
+```sh
+zen init repo-notes && cd repo-notes
+```
+
+`agents.yaml` — who exists, and what each may reach for:
+
+```yaml
+default: reader
+model: openai:gpt-5.4-mini
+
+agents:
+    - name: reader
+      description: Reads the workspace and summarises what is in it.
+      system: agents/prompts/reader.md
+      tools: [workspace:read_file, workspace:list_dir, workspace:find_files]
+      handoffs: [writer]
+
+    - name: writer
+      description: Turns a summary into a file on disk.
+      system: agents/prompts/writer.md
+      tools: [workspace:*]
+```
+
+`agents/prompts/reader.md`:
+
+```markdown
+You explore a codebase and describe it plainly: what it is, how it is laid out,
+how it is built and tested. Read before you conclude. When you have a picture,
+hand off to `writer`.
+```
+
+`agents/prompts/writer.md`:
+
+```markdown
+You write the summary you were handed to `NOTES.md`, in Markdown, under 40
+lines. Then say where you put it and stop.
+```
+
+Check it, then point it at a real directory:
+
+```sh
+zen check                                  # every file it names, validated
+cd ~/code/some-repo
+zen run repo-notes "summarise this repo"   # this directory is the workspace
+zen inspect --project repo-notes --open    # what it actually did
+```
+
+## The idea
+
+An **agentic project is a folder**. Prompts, agent wiring, skills and tool
+selections are files — Markdown and YAML — not code buried inside an
+application. That folder can be committed, copied to another machine, reviewed
+in a pull request, and handed to someone else who runs it with one command.
+Credentials live in `$HOME`, so the project never contains a secret.
+
+```
+my-project/
+    INSTRUCTIONS.md              house rules, prepended to every agent
+    agents.yaml                  who exists, what they may reach for
+    agents/
+        prompts/<name>.md        each agent's own brief
+        skills/<name>/           knowledge loaded on demand, not always-on
+    sessions/                    one workspace, memory and trajectory each
+        <id>/
+            workspace/           what the agents can read and write
+            runs/<id>/           input, output, state, report.html, meta
+```
+
+`zen init` also writes `.github/copilot-instructions.md` — a standing brief that
+explains this runtime to whatever coding agent you have open in that folder, so
+you are not expected to hand-author `agents.yaml`.
+
+## Commands
+
+| Command   | Does                                                                     |
+| --------- | ------------------------------------------------------------------------ |
+| `init`    | Creates a project here, or in `<dir>`, and registers it.                 |
+| `list`    | Every known project: sessions, last run, whether one is live.            |
+| `open`    | Opens a project in your editor.                                          |
+| `key`     | The credential keyring — add, check, switch, remove.                     |
+| `run`     | Runs the project — the TUI on a terminal, one shot otherwise.            |
+| `inspect` | Opens or rebuilds a run's `report.html`.                                 |
+| `models`  | Resolves providers and models and validates the config, calling nothing. |
+| `sandbox` | Checks and prepares the container that command-line tools run in.        |
+| `version` | CLI, library and Node versions.                                          |
+
+Commands can also come from a package installed alongside this one, so a new
+capability is a subcommand rather than a new binary to remember — one thing on
+your path, one keyring, one name. `zen --help` lists them whether or not they
+are installed and says what to run if not; nothing is imported until you type
+the command, so an uninstalled one costs nothing and an installed one costs
+nothing until it is used.
+
+| Command | Package         | Does                                           |
+| ------- | --------------- | ---------------------------------------------- |
+| `faker` | `@zenera/faker` | A mock API from an openapi/swagger document.   |
+| `rag`   | `@zenera/rag`   | Search an openapi/swagger document as a graph. |
+
+```sh
+npm i -g @zenera/faker
+zen faker serve api/openapi.yaml --port 8787   # a working mock, bodies written by a model
+
+npm i -g @zenera/rag
+zen rag schema index --embedding openai:text-embedding-3-small ./specs/*.yaml
+zen rag schema search --output-property "user billing history" --format ts
+```
+
+They use this keyring and these credentials, so there is nothing new to
+configure. Details:
+[@zenera/faker](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md)
+·
+[@zenera/rag](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md).
+
+Global flags: `-h/--help`, `-v/--version`, `--json`, `-C <dir>`. Exit codes: `0`
+ok, `1` the run failed, `2` bad invocation, `3` invalid project, `4` no usable
+credential, `5` sandbox unavailable.
+
+`stdout` is the answer, `stderr` is the narration, and `--json` is on every
+command — so `zen run … | jq` is a supported way to use it, not an accident.
+
+The binary is installed under three names: `zen`, `zn` and `zenera`.
+
+## Concepts
+
+- **Project** — a named directory holding a complete agent definition and the
+  sessions that ran against it. Self-describing: `agents.yaml` is what makes it
+  one, so moving or cloning the directory loses nothing.
+- **Session** — a context that persists: one workspace, one memory, one blob
+  store, one accumulating trajectory. Resumable.
+- **Run** — one prompt in, one answer out, inside a session. Recorded in full,
+  whether or not you were watching.
+- **Workspace** — the directory the agents may read and write. A prompt given on
+  the command line uses the current directory; the TUI offers the session's own
+  empty folder and confirms anything outside it.
+- **Keyring** — `~/.zenera/neo`, mode `0700`. Keys are materialised into the
+  environment just before a run, so a real env var always wins and a project
+  checked out on a machine without `zen` still runs.
+
+## The library underneath
+
+This is a shell over
+[`@zenera/neo`](https://www.npmjs.com/package/@zenera/neo) — agents, models,
+tools, skills, memory and an append-only trajectory. Use it directly when you
+want the runtime inside your own application rather than on a terminal:
+[its README](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/neo/README.md).
+
+## Documentation
+
+Full specification:
+[packages/cli/DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/DESIGN.md).
+Also
+[DESIGN.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/DESIGN.md) ·
+[docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md)
+·
+[docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md).
+
+## License
+
+Early days and moving fast — issues, questions and pull requests are welcome.
+[MIT](LICENSE).

package/dist/args.d.ts

@@ -0,0 +1,40 @@
+import { type ParseArgsConfig } from 'node:util';
+type Options = NonNullable<ParseArgsConfig['options']>;
+/**
+ * The name the program was launched under. One file is reached by several of
+ * them — `zen`, `zn`, `zenera` — and help that names a command the reader did
+ * not type is help about a different program.
+ *
+ * `argv[1]` keeps the symlink `bin` installed rather than its target, which is
+ * exactly the name that was typed. Running the file directly, or through a
+ * Windows shim, lands on `main.js` instead: there is no name to honour then,
+ * so the canonical one stands.
+ */
+export declare function invokedAs(fallback: string): string;
+export interface Parsed<T> {
+    values: T;
+    positionals: string[];
+}
+export declare function parse<T>(args: readonly string[], options: Options, usage: string): Parsed<T>;
+/** Exactly one positional, or none. More than one is a mistake worth naming. */
+export declare function one(positionals: string[], what: string, usage: string): string | undefined;
+export interface Split {
+    /** everything before the command name */
+    before: string[];
+    name?: string;
+    /** everything after it, verbatim */
+    after: string[];
+}
+/** The command name is the first bare word. */
+export declare function split(argv: readonly string[]): Split;
+/**
+ * Pulls the global flags back out of a command's arguments — `zen list --json`
+ * reads better than `zen --json list`, and both must work — and returns what is
+ * left for the command's own parser. Nothing after `--` is touched.
+ */
+export declare function extract(after: readonly string[]): {
+    rest: string[];
+    global: string[];
+};
+export {};
+//# sourceMappingURL=args.d.ts.map

package/dist/args.js

@@ -0,0 +1,99 @@
+import { basename } from 'node:path';
+import { parseArgs } from 'node:util';
+import { usageError } from "./term.js";
+/**
+ * The name the program was launched under. One file is reached by several of
+ * them — `zen`, `zn`, `zenera` — and help that names a command the reader did
+ * not type is help about a different program.
+ *
+ * `argv[1]` keeps the symlink `bin` installed rather than its target, which is
+ * exactly the name that was typed. Running the file directly, or through a
+ * Windows shim, lands on `main.js` instead: there is no name to honour then,
+ * so the canonical one stands.
+ */
+export function invokedAs(fallback) {
+    const name = basename(process.argv[1] ?? '').replace(/\.[cm]?js$/, '');
+    return name && name !== 'main' && name !== 'index' ? name : fallback;
+}
+export function parse(args, options, usage) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: [...args],
+            options,
+            strict: true,
+            allowPositionals: true,
+        });
+        return { values: values, positionals };
+    }
+    catch (err) {
+        throw usageError(err.message, usage);
+    }
+}
+/** Exactly one positional, or none. More than one is a mistake worth naming. */
+export function one(positionals, what, usage) {
+    if (positionals.length > 1) {
+        throw usageError(`expected at most one ${what}, got ${positionals.length}`, usage);
+    }
+    return positionals[0];
+}
+// ---------------------------------------------------------------------------
+// Splitting the command line
+//
+// Lives here rather than in `main.ts` because it is the part with the sharp
+// edge: `parseArgs` in non-strict mode silently turns an unrecognised
+// `--no-check` into an *option*, so a frame that parsed the whole line would
+// swallow every flag belonging to a command. Nothing after the command name is
+// parsed here at all.
+// ---------------------------------------------------------------------------
+/** Flags the frame owns, wherever they appear. */
+const GLOBAL_FLAGS = new Set(['--json', '--help', '-h']);
+const GLOBAL_VALUED = new Set(['-C', '--directory']);
+/** The command name is the first bare word. */
+export function split(argv) {
+    const before = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            return { before, name: argv[i + 1], after: argv.slice(i + 2) };
+        }
+        if (!arg.startsWith('-')) {
+            return { before, name: arg, after: argv.slice(i + 1) };
+        }
+        before.push(arg);
+        if (GLOBAL_VALUED.has(arg) && i + 1 < argv.length) {
+            before.push(argv[++i]);
+        }
+    }
+    return { before, after: [] };
+}
+/**
+ * Pulls the global flags back out of a command's arguments — `zen list --json`
+ * reads better than `zen --json list`, and both must work — and returns what is
+ * left for the command's own parser. Nothing after `--` is touched.
+ */
+export function extract(after) {
+    const rest = [];
+    const global = [];
+    for (let i = 0; i < after.length; i++) {
+        const arg = after[i];
+        if (arg === '--') {
+            rest.push(...after.slice(i + 1));
+            break;
+        }
+        if (GLOBAL_FLAGS.has(arg)) {
+            global.push(arg);
+            continue;
+        }
+        if (GLOBAL_VALUED.has(arg)) {
+            global.push(arg, after[++i] ?? '');
+            continue;
+        }
+        if (arg.startsWith('--directory=') || arg.startsWith('--json=')) {
+            global.push(arg);
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { rest, global };
+}
+//# sourceMappingURL=args.js.map

package/dist/audit.d.ts

@@ -0,0 +1,53 @@
+import { type ModelRequirement } from '@zenera/neo';
+import { type KeyStore, type Provider } 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. */
+    reason: 'missing' | 'dead';
+    /** the provider's own words, when it was the one to say no */
+    detail?: string;
+    /** the keyring provider the fix names, when the kind is one of them */
+    add?: Provider;
+}
+/**
+ * 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
+ * authenticates from a service-account file instead. So the file-shaped
+ * credential is looked for where the keyring keeps it.
+ *
+ * Exported 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.
+ */
+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

@@ -0,0 +1,144 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { projectRegistry, readProjectConfig, } from '@zenera/neo';
+import { SHAPES, isProvider } 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],
+    ]);
+}
+/**
+ * `gcloud auth application-default login` writes here, and the GenAI SDK finds
+ * it with no variable set — so without this check every developer using ADC
+ * would be told their working Vertex setup is broken.
+ */
+function hasGcloudAdc() {
+    const dir = process.env.CLOUDSDK_CONFIG ?? join(homedir(), '.config', 'gcloud');
+    return existsSync(join(dir, 'application_default_credentials.json'));
+}
+/**
+ * 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
+ * authenticates from a service-account file instead. So the file-shaped
+ * credential is looked for where the keyring keeps it.
+ *
+ * Exported 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.
+ */
+export function credentialFor(need) {
+    const provider = isProvider(need.kind) ? need.kind : undefined;
+    const shape = provider ? SHAPES[provider] : undefined;
+    if (shape?.holds === 'file') {
+        return { env: shape.env, present: Boolean(process.env[shape.env]) || hasGcloudAdc() };
+    }
+    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 = 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') {
+                issues.push({
+                    name,
+                    role,
+                    provider: need.provider,
+                    env,
+                    reason: 'dead',
+                    detail: check.detail,
+                    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}` : '';
+    const fix = `zen key check ${issue.add ?? ''}`.trim();
+    return `${what} was rejected when last checked${why} — ${dim(fix)}`;
+}
+//# sourceMappingURL=audit.js.map

package/dist/banner.d.ts

@@ -0,0 +1,13 @@
+export interface BannerText {
+    /** drawn white */
+    head: string;
+    /** drawn in the neon accent */
+    accent: string;
+    /** the line underneath, dim */
+    subtitle: string;
+}
+export declare const NEO_BANNER: BannerText;
+export declare function bannerLines(text: BannerText, columns?: number): string[];
+/** Narration, and only for someone watching. */
+export declare function printBanner(text: BannerText): void;
+//# sourceMappingURL=banner.d.ts.map