@zenera/cli 1.1.0 → 1.1.3

package/README.md

@@ -22,12 +22,11 @@ carries your keys with it.
 
 ## 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.
+Node.js 24+. One command — the OpenAI, Anthropic, Google and OpenRouter SDKs
+all ship with the CLI, so any provider works out of the box.
 
 ```sh
-npm i -g @zenera/cli openai
-#                or @anthropic-ai/sdk, @google/genai, @openrouter/sdk — any mix of them
+npm i -g @zenera/cli
 ```
 
 Or without installing anything:
@@ -41,7 +40,7 @@ npx @zenera/cli --help
 Four commands, from nothing to an answer:
 
 ```sh
-npm i -g @zenera/cli openai   # the CLI, plus one vendor SDK
+npm i -g @zenera/cli         # every vendor SDK comes with it
 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"
@@ -199,6 +198,87 @@ 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`.
 
+## Credentials
+
+One keyring serves every provider, and a key goes in the same way whatever it
+is for:
+
+```sh
+zen key add <provider>              # prompts with the echo off
+zen key add <provider> < key.txt    # or pipe it
+```
+
+The value never comes from argv — a command line lands in `ps`, in shell
+history and in CI logs — so piped stdin and the echo-off prompt are the only
+two ways in. Entries live in `~/.zenera/neo/keys.json` (mode `0600`) and are
+materialised into the environment just before a run, so a real environment
+variable always wins and a project checked out on a machine without `zen` still
+runs.
+
+| Provider     | The value is                          | Exported as                      |
+| ------------ | ------------------------------------- | -------------------------------- |
+| `openai`     | a secret                              | `OPENAI_API_KEY`                 |
+| `anthropic`  | a secret                              | `ANTHROPIC_API_KEY`              |
+| `google`     | a secret — AI Studio                  | `GEMINI_API_KEY`                 |
+| `vertex`     | a path to a service-account JSON file | `GOOGLE_APPLICATION_CREDENTIALS` |
+| `openrouter` | a secret                              | `OPENROUTER_API_KEY`             |
+| `exa`        | a secret — for the search tool        | `EXA_API_KEY`                    |
+
+`zen key add` verifies the credential against the provider before it finishes,
+but stores it either way: a key that cannot be checked right now — offline,
+behind a proxy — is not a key that is wrong. `--no-check` skips the call.
+
+### Which key a model uses
+
+A model reference is `[provider[/api]:]model`, and the first segment names a
+**provider, not a vendor**. So `vertex:gemini-3.5-flash` and
+`google:gemini-3.5-flash` are the same model reached through two different
+services, needing two different credentials — and a bare `gpt-5.4-mini` goes to
+the default provider, `openai`. `zen models` resolves every reference in a
+project against what is stored, and calls nothing.
+
+### Vertex AI
+
+Vertex accepts either shape, and which one you gave is read off the value.
+
+The usual one is a **service-account JSON file** — give its path, not its
+contents:
+
+```sh
+printf '%s' ~/keys/vertex-sa.json | zen key add vertex --location us-central1
+```
+
+The file is copied into `~/.zenera/neo/keys/` at mode `0600`, so moving or
+cleaning up the original later cannot break it.
+
+- `--location <region>` is worth setting. It must be `global` or a **concrete
+  region**; multi-region names like `us` are rejected with a 404. `global`
+  routes across regions and pays about ten seconds of cold start on the first
+  request each process makes — a region answers in about two.
+- `--project <id>` is only needed when the `project_id` inside the file is not
+  the project you want.
+
+The alternative is an **express-mode API key**, an ordinary secret under
+`VERTEX_API_KEY`. Express mode addresses no project, so `--project` and
+`--location` mean nothing there and are not stored.
+
+### More than one key per provider
+
+Entries are named, so a provider can hold several and one of them is active:
+
+```sh
+zen key add openai/work         # a second entry
+zen key use openai/work         # which one runs use
+zen key ls --check              # everything stored, and whether it still works
+zen key show vertex/default     # masked — --reveal prints the secret
+zen key env openai              # shell exports, for other tools
+zen key rm openai/work
+```
+
+`zen key ls` marks the active entry with `*`, and something it found in your
+real environment or in `gcloud`'s ADC with `~`, so it is always clear where a
+working provider actually comes from.
+
 ## Concepts
 
 - **Project** — a named directory holding a complete agent definition and the
@@ -225,13 +305,10 @@ want the runtime inside your own application rather than on a terminal:
 
 ## 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).
+— the folder a project is ·
+[docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
+— every key in the configuration file.
 
 ## License
 

package/dist/audit.d.ts

@@ -22,13 +22,15 @@ export interface ModelIssue {
  * 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.
+ * 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.
  *
- * 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.
+ * 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;

package/dist/audit.js

@@ -1,8 +1,5 @@
-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 { envNames, form, gcloudAdc, isProvider, SHAPES, } from "./keys.js";
 import { bold, dim } from "./term.js";
 /**
  * Every model the project names, keyed by how one would refer to it.
@@ -36,32 +33,27 @@ function declared(config) {
         ['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.
+ * 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.
  *
- * 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.
+ * 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) {
     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() };
+    // 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 };
 }

package/dist/commands/check.js

@@ -1,11 +1,12 @@
-import { basename, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
 import { one, parse } from "../args.js";
 import { KeyStore } from "../keys.js";
 import { Registry } from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
-import { bold, count, cyan, dim, green, invalidError, json, red, table, write, writeAll, yellow, } from "../term.js";
+import { bold, count, cyan, dim, green, invalidError, json, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 import { validateProject, } from "../validate.js";
-const USAGE = 'zen check [dir] [--project <name|dir>] [--strict] [--quiet]';
+const USAGE = 'zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--strict] [--quiet]';
 // ---------------------------------------------------------------------------
 // zen check
 //
@@ -16,38 +17,47 @@ const USAGE = 'zen check [dir] [--project <name|dir>] [--strict] [--quiet]';
 // stable code and a fix, and the whole thing goes to stdout — it is the answer,
 // not narration.
 //
-// Nothing here is contacted, started or paid for. That is the point: the check
-// has to work on the machine that is not set up yet, which is the machine that
-// most needs it.
+// Nothing is contacted or paid for. The one thing that *runs* is the sandbox:
+// the project's image is built and one command is executed in it, because a
+// Dockerfile that does not build is a broken project and nothing short of
+// building it says so. It happens against a temporary directory, the container
+// is removed on the way out, and `--no-sandbox` skips it — so the report is
+// still worth having on the machine that has no container engine at all.
 // ---------------------------------------------------------------------------
 export const check = {
     summary: 'Validate agents.yaml and every file it names, and report in full.',
     usage: USAGE,
     details: [
-        'Checks the whole project without running anything: the configuration',
-        'parses and satisfies the schema, every prompt, skill and catalog it',
-        'names is on disk, hand-offs and forks name agents that exist, tool',
-        'selectors resolve, skills bind to a catalog that holds them, and the',
-        'models it declares have a credential on this machine.',
+        'Checks the whole project: the configuration parses and satisfies the',
+        'schema, every prompt, skill and catalog it names is on disk, hand-offs',
+        'and forks name agents that exist, tool selectors resolve, skills bind to',
+        'a catalog that holds them, and the models it declares have a credential',
+        'on this machine.',
+        '',
+        'It also builds the sandbox image and runs one command in it, against a',
+        'temporary directory rather than your workspace. That is the only thing',
+        'it starts, and --no-sandbox skips it. No container engine is a warning,',
+        'not an error.',
         '',
         'Unlike a run, it does not stop at the first problem — the report lists',
         'everything it found, each with a code and the fix for it.',
         '',
+        'The argument is a directory if one is there and a registered project',
+        'name otherwise; with neither, the project you are standing in.',
+        '',
         'Exit codes: 0 nothing wrong, 3 at least one error (or, with --strict,',
         'at least one warning). --quiet prints the findings and nothing else.',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
+            'no-sandbox': { type: 'boolean' },
             strict: { type: 'boolean' },
             quiet: { type: 'boolean' },
         }, USAGE);
-        // A bare directory is accepted so an unregistered folder — a checkout,
-        // a scaffold in progress — can be checked at all. `--project` goes
-        // through the registry, like everywhere else.
-        const here = one(positionals, 'directory', USAGE);
+        const here = one(positionals, 'project or directory', USAGE);
         const dir = here
-            ? resolve(ctx.cwd, here)
+            ? await locate(ctx.cwd, here)
             : await resolveProject({ cwd: ctx.cwd, project: values.project }).then((p) => p.dir);
         // Being listed is the registry's answer, not the directory's, so it is
         // read here and handed to the check rather than looked up inside it.
@@ -58,12 +68,18 @@ export const check = {
         // the same key by the time the library asks.
         const keys = await KeyStore.open();
         keys.materialize();
+        const bar = progress();
         const report = await validateProject({
             dir,
             name,
             registered: entry !== undefined,
             keys,
+            sandbox: {
+                enabled: !values['no-sandbox'],
+                onProgress: (what) => bar.update(dim(what)),
+            },
         });
+        bar.done();
         if (ctx.json) {
             json(report);
         }
@@ -81,6 +97,32 @@ export const check = {
         }
     },
 };
+/**
+ * What a bare argument means: a directory when one is there, a registered name
+ * otherwise. A directory is tried first, and it does not have to be a project
+ * yet — an unregistered folder, a checkout, a scaffold in progress is exactly
+ * what there is to check.
+ *
+ * A word that is neither is a usage error and stops here. The check itself
+ * would answer it too, but it would answer at the length of a full report, and
+ * a page of empty sections about a directory that does not exist buries the one
+ * line that matters: there is nothing by that name.
+ */
+async function locate(cwd, arg) {
+    const at = resolve(cwd, arg);
+    if (existsSync(at) && statSync(at).isDirectory()) {
+        return at;
+    }
+    const entry = (await Registry.open()).find(arg);
+    if (!entry) {
+        throw usageError(`no project or directory named "${arg}"`, 'see what is registered: zen list');
+    }
+    const path = resolve(entry.path);
+    if (!existsSync(path)) {
+        throw usageError(`project "${entry.name}" is registered at ${path}, which is gone`, 'forget it: zen list --prune');
+    }
+    return path;
+}
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
@@ -121,12 +163,22 @@ function render(report) {
         ? `${count(report.skills.entries.length, 'skill')} in ${report.skills.dirs.join(', ')}`
         : 'no catalog')}`);
     if (report.skills.entries.length) {
-        push(...table(report.skills.entries.map((s) => [
+        // A folder skill's own files travel with it: they are mounted at
+        // /skills/<folder> and the body may point the model straight at them,
+        // so say what is there and under which name.
+        const rows = table(report.skills.entries.map((s) => [
             `  ${s.name}`,
             dim(s.path),
             dim(s.tools?.length ? `unlocks ${s.tools.join(' ')}` : ''),
             dim(s.usedBy.length ? `used by ${s.usedBy.join(', ')}` : 'unused'),
-        ])));
+        ]));
+        report.skills.entries.forEach((s, i) => {
+            push(rows[i] ?? '');
+            if (s.files?.length) {
+                const at = basename(dirname(s.path));
+                push(dim(`    /skills/${at}/  ${s.files.join('  ')}`));
+            }
+        });
     }
     // Models ----------------------------------------------------------------
     push('', bold('Models'));
@@ -156,13 +208,21 @@ function render(report) {
         push('', bold('Sandbox'));
         push(...table([
             ['  image', report.sandbox.image ?? dim('the default image')],
+            ...(report.sandbox.dockerfile
+                ? [['  built from', report.sandbox.dockerfile]]
+                : []),
             [
                 '  reached by',
                 report.sandbox.used
                     ? 'at least one agent has the shell tools'
                     : dim('nothing — the block is declared but no agent can run a command'),
             ],
-            ['  requires', dim('podman on this machine: zen sandbox status')],
+            [
+                '  tried',
+                report.sandbox.probed
+                    ? green('built, started, and a command ran in it')
+                    : dim('no — nothing was built or started'),
+            ],
         ]));
     }
     // Findings --------------------------------------------------------------

package/dist/commands/init.js

@@ -1,9 +1,12 @@
+import { readProjectConfig } from '@zenera/neo';
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { one, parse } from "../args.js";
 import { ensureHome } from "../home.js";
-import { isProvider, keyId, KeyStore, PROVIDERS, SHAPES } from "../keys.js";
+import { resolveBuild } from "../image.js";
+import { envNames, isProvider, keyId, KeyStore, PROVIDERS } from "../keys.js";
 import { probeAll } from "../liveness.js";
+import { ensurePodmanReady } from "../podman.js";
 import { isProjectDir, Registry } from "../projects.js";
 import { scaffold } from "../scaffold.js";
 import { bold, cyan, dim, green, invalidError, json, note, progress, usageError, write, yellow, } from "../term.js";
@@ -55,7 +58,7 @@ const DEFAULT_MODEL = {
  * the wifi is down.
  */
 async function reachableProvider(store) {
-    const fromEnv = PROVIDERS.find((p) => process.env[SHAPES[p].env]);
+    const fromEnv = PROVIDERS.find((p) => envNames(p).some((name) => process.env[name]));
     if (fromEnv) {
         return fromEnv;
     }
@@ -64,7 +67,8 @@ async function reachableProvider(store) {
         return undefined;
     }
     const bar = progress();
-    const checks = await probeAll(store, active, (entry, index, total) => bar.update(dim(`checking ${keyId(entry)} … ${index + 1}/${total}`)));
+    bar.update(dim(`checking ${active.length} key${active.length === 1 ? '' : 's'} …`));
+    const checks = await probeAll(store, active, (entry, done, total) => bar.update(dim(`checked ${keyId(entry)} … ${done}/${total}`)));
     bar.done();
     for (const [entry, check] of checks) {
         store.record(entry, check);
@@ -86,7 +90,7 @@ async function reachableProvider(store) {
  * `init`.
  */
 function hasExa(store) {
-    return Boolean(process.env[SHAPES.exa.env]) || store.active('exa') !== undefined;
+    return envNames('exa').some((name) => process.env[name]) || store.active('exa') !== undefined;
 }
 export const init = {
     summary: 'Create a project here, or in <dir>, and register it.',
@@ -101,6 +105,9 @@ export const init = {
         '`exa:*` when the keyring holds an Exa key. Without --model, the',
         'keyring is checked and the model is picked from a credential the',
         'provider accepts.',
+        '',
+        'The sandbox image is built here too, so the first run does not have',
+        'to. A machine without a container engine is told, and carries on.',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
@@ -126,19 +133,31 @@ export const init = {
             : DEFAULT_MODEL[provider ?? 'openai'];
         const model = choice.ref;
         const web = hasExa(store);
-        const files = scaffold({ dir, model, modelOptions: choice.options, web });
+        const written = scaffold({ dir, model, modelOptions: choice.options, web });
         const registry = await Registry.open();
         registry.add(name, dir);
         registry.save();
+        if (!ctx.json) {
+            note(`${green('created')} ${bold(name)} ${dim(dir)}`);
+            for (const file of written.files.filter((f) => !f.startsWith('.'))) {
+                note(`  ${dim(file)}`);
+            }
+            note();
+        }
+        const sandbox = await prepareSandbox(dir, ctx.json);
         if (ctx.json) {
-            json({ name, path: dir, model, files, credential: provider ?? null, web });
+            json({
+                name,
+                path: dir,
+                model,
+                files: written.files,
+                editor: written.editor,
+                credential: provider ?? null,
+                web,
+                sandbox,
+            });
             return;
         }
-        note(`${green('created')} ${bold(name)} ${dim(dir)}`);
-        for (const file of files) {
-            note(`  ${dim(file)}`);
-        }
-        note();
         if (web) {
             note(`${green('exa key found')} ${dim('— the default agent gets web search')}`);
             note();
@@ -154,4 +173,45 @@ export const init = {
         write(dir);
     },
 };
+/**
+ * Builds the sandbox image the project was just given, here rather than on the
+ * first run.
+ *
+ * It has to happen once either way, and the two moments are not equally good:
+ * a build during `init` is a command that is visibly setting a project up,
+ * while the same minutes during `zen run` land in the middle of a question
+ * somebody asked and read as a hung model.
+ *
+ * Never fatal. A machine with no container engine has a perfectly good project
+ * on it — one whose agent cannot start a shell yet — and refusing to finish
+ * `init` over that would throw away everything already written.
+ */
+async function prepareSandbox(dir, quiet) {
+    let image;
+    try {
+        const { root, config } = readProjectConfig(dir);
+        const build = resolveBuild(root, config.sandbox);
+        image = build?.tag ?? config.sandbox?.image;
+        if (!build && !image) {
+            return false;
+        }
+        // Nothing to answer: `init` is not the place to be asked whether to
+        // install a package manager's worth of software.
+        await ensurePodmanReady({ image, build, yes: true });
+        if (!quiet) {
+            note(`${green('sandbox ready')} ${dim(image ?? '')}`);
+            note();
+        }
+        return true;
+    }
+    catch (err) {
+        if (!quiet) {
+            const why = err instanceof Error ? err.message : String(err);
+            note(`${yellow('sandbox not ready')} ${dim(`— ${why}`)}`);
+            note(`  ${cyan('zen sandbox up')} ${dim('— or the first run will try again')}`);
+            note();
+        }
+        return false;
+    }
+}
 //# sourceMappingURL=init.js.map