@zenera/cli 1.1.2 → 1.1.3

package/dist/commands/key.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { parse } from "../args.js";
 import { ensureHome } from "../home.js";
-import { assertNotEmpty, describe, keyId, KeyStore, mask, OWNERS, parseRef, SHAPES, } from "../keys.js";
+import { ambient, ambientId, assertNotEmpty, describe, envNames, envOf, keyId, KeyStore, mask, OWNERS, parseRef, SHAPES, } from "../keys.js";
 import { probe, probeAll } from "../liveness.js";
 import { ago, ask, askSecret, bold, confirm, credentialError, cyan, dim, green, isInteractive, json, note, progress, readStdin, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 const USAGE = 'zen key <ls|add|use|check|rm|show|env> [ref] [options]';
@@ -16,35 +16,59 @@ const MARK = {
 function state(entry) {
     return entry.check ? MARK[entry.check.state] : dim('unchecked');
 }
-function rows(store) {
+/**
+ * An ambient credential borrowed into the shape the rest of this file works
+ * in. It is not in the store and never will be: `store.find` misses it, so
+ * `store.record` drops its check and nothing is written to disk. That is the
+ * intent — it can be listed and probed, not chosen or forgotten.
+ */
+function asEntry(cred) {
+    return {
+        provider: cred.provider,
+        name: cred.env ? `$${cred.env}` : 'adc',
+        holds: cred.holds,
+        value: cred.value,
+        env: cred.env,
+        addedAt: new Date().toISOString(),
+    };
+}
+function rows(store, borrowed) {
     const out = [
         [bold(''), bold('KEY'), bold('VALUE'), bold('STATE'), bold('CHECKED')],
     ];
     for (const provider of OWNERS) {
         for (const entry of store.for(provider)) {
-            const shadowed = Boolean(process.env[SHAPES[provider].env]);
+            const shadow = envNames(provider).find((name) => process.env[name]);
             out.push([
                 store.isActive(entry) ? green('*') : ' ',
                 keyId(entry),
                 dim(describe(store, entry)),
                 state(entry),
                 dim(entry.check ? ago(entry.check.at) : '—') +
-                    (shadowed && store.isActive(entry)
-                        ? yellow(`  shadowed by $${SHAPES[provider].env}`)
-                        : ''),
+                    (shadow && store.isActive(entry) ? yellow(`  shadowed by $${shadow}`) : ''),
+            ]);
+        }
+        for (const [cred, entry] of borrowed.filter(([c]) => c.provider === provider)) {
+            out.push([
+                dim('~'),
+                dim(ambientId(cred)),
+                dim(describe(store, entry)),
+                state(entry),
+                dim(cred.env ? 'from the environment' : 'from gcloud'),
             ]);
         }
     }
     return table(out);
 }
 /**
- * Checking is a network round trip per key, so it says which one it is waiting
- * on. Silence for ten seconds is indistinguishable from a hang.
+ * Checking is a network round trip per key, so it says which ones have come
+ * back. Silence for ten seconds is indistinguishable from a hang.
  */
 async function checkAll(ctx, store, targets) {
     const bar = ctx.json ? undefined : progress();
+    bar?.update(dim(`checking ${targets.length} key${targets.length === 1 ? '' : 's'} …`));
     try {
-        return await probeAll(store, targets, (entry, index, total) => bar?.update(dim(`checking ${keyId(entry)} … ${index + 1}/${total}`)));
+        return await probeAll(store, targets, (entry, done, total) => bar?.update(dim(`checked ${keyId(entry)} … ${done}/${total}`)));
     }
     finally {
         bar?.done();
@@ -53,29 +77,47 @@ async function checkAll(ctx, store, targets) {
 const ls = async (ctx, args) => {
     const { values } = parse(args, { check: { type: 'boolean' } }, USAGE);
     const store = await KeyStore.open();
+    const borrowed = ambient(store).map((cred) => [cred, asEntry(cred)]);
     if (values.check) {
-        const checks = await checkAll(ctx, store, store.entries);
+        // Ambient credentials are checked alongside the stored ones and, unlike
+        // them, forgotten again: there is nowhere to write the result, and a
+        // variable that changes between runs would make a cached one a lie.
+        const checks = await checkAll(ctx, store, [
+            ...store.entries,
+            ...borrowed.map(([, entry]) => entry),
+        ]);
         for (const [entry, check] of checks) {
             store.record(entry, check);
+            entry.check = check;
         }
         store.save();
     }
     if (ctx.json) {
-        json(store.entries.map((e) => ({
-            ...e,
-            value: e.holds === 'file' ? store.fileOf(e) : mask(e.value),
-            active: store.isActive(e),
-            env: SHAPES[e.provider].env,
-        })));
+        json({
+            keys: store.entries.map((e) => ({
+                ...e,
+                value: e.holds === 'file' ? store.fileOf(e) : mask(e.value),
+                active: store.isActive(e),
+                env: envOf(e),
+            })),
+            ambient: borrowed.map(([cred, entry]) => ({
+                provider: cred.provider,
+                id: ambientId(cred),
+                env: cred.env ?? null,
+                holds: cred.holds,
+                value: cred.holds === 'file' ? cred.value : mask(cred.value),
+                check: entry.check,
+            })),
+        });
         return;
     }
-    if (store.entries.length === 0) {
+    if (store.entries.length === 0 && borrowed.length === 0) {
         note('the keyring is empty');
         note(dim('add one: zen key add openai'));
         return;
     }
-    writeAll(rows(store));
-    const missing = OWNERS.filter((p) => !store.active(p) && !process.env[SHAPES[p].env]);
+    writeAll(rows(store, borrowed));
+    const missing = OWNERS.filter((p) => !store.active(p) && !borrowed.some(([c]) => c.provider === p));
     if (missing.length) {
         note('');
         note(dim(`no key for: ${missing.join(', ')}`));
@@ -87,7 +129,12 @@ const ls = async (ctx, args) => {
  * Piped stdin or an echo-off prompt are the only two ways in.
  */
 const add = async (ctx, args) => {
-    const { values, positionals } = parse(args, { name: { type: 'string' }, 'no-check': { type: 'boolean' } }, 'zen key add <provider>[/name] [--name <name>] [--no-check]');
+    const { values, positionals } = parse(args, {
+        name: { type: 'string' },
+        'no-check': { type: 'boolean' },
+        project: { type: 'string' },
+        location: { type: 'string' },
+    }, 'zen key add <provider>[/name] [--name <name>] [--project <id>] [--location <region>] [--no-check]');
     const ref = positionals[0];
     if (!ref) {
         throw usageError('which provider?', `one of: ${OWNERS.join(', ')}`);
@@ -96,6 +143,9 @@ const add = async (ctx, args) => {
     const provider = parsed.provider;
     const name = values.name ?? parsed.name ?? 'default';
     const shape = SHAPES[provider];
+    if ((values.project || values.location) && provider !== 'vertex') {
+        throw usageError(`--project and --location mean nothing to ${shape.label}`, 'they configure a Vertex service account');
+    }
     ensureHome();
     const store = await KeyStore.open();
     if (store.find(provider, name) && isInteractive()) {
@@ -103,14 +153,20 @@ const add = async (ctx, args) => {
             throw usageError('cancelled');
         }
     }
-    const raw = (await readStdin()) ?? (await promptFor(shape.holds, shape.label, shape.where));
+    const raw = (await readStdin()) ?? (await promptFor(shape));
     if (!raw) {
         throw usageError('no value given');
     }
-    if (shape.holds === 'file' && !existsSync(raw)) {
+    // A provider with one form can say up front that a path is wrong. One with
+    // two cannot: a value that is not a path is not a mistake there, it is the
+    // other kind of credential, and `add` decides which by looking.
+    if (shape.forms.length === 1 && shape.forms[0].holds === 'file' && !existsSync(raw)) {
         throw usageError(`no such file: ${raw}`);
     }
-    const entry = store.add(provider, name, raw);
+    const entry = store.add(provider, name, raw, {
+        project: values.project,
+        location: values.location,
+    });
     // Verified before it is trusted, but stored either way: a key that cannot
     // be checked right now — offline, behind a proxy — is not a key that is
     // wrong, and refusing to save it would make `zen key add` fail on a plane.
@@ -128,20 +184,37 @@ const add = async (ctx, args) => {
     if (ctx.json) {
         json({
             key: keyId(entry),
-            env: shape.env,
+            env: envOf(entry),
             active: store.isActive(entry),
             check: entry.check,
         });
         return;
     }
-    note(`${green('added')} ${bold(keyId(entry))} ${dim(describe(store, entry))} ${state(entry)}`);
-    if (process.env[shape.env]) {
-        note(yellow(`$${shape.env} is set and will win over this`));
+    note(`${green('added')} ${bold(keyId(entry))} ${dim(describe(store, entry))} ` +
+        `${dim(`→ $${envOf(entry)}`)} ${state(entry)}`);
+    if (process.env[envOf(entry)]) {
+        note(yellow(`$${envOf(entry)} is set and will win over this`));
+    }
+    if (provider === 'vertex' && entry.holds === 'file' && !entry.project) {
+        note(dim('no --project given; the project_id inside the file will be used'));
     }
 };
-async function promptFor(holds, label, where) {
-    note(dim(`${label} — ${where}`));
-    return holds === 'file'
+/**
+ * A provider with two forms cannot ask for one of them. It asks with the echo
+ * off, because one of the two answers is a secret and there is no way to know
+ * which is coming until it arrives.
+ */
+async function promptFor(shape) {
+    const [first, ...rest] = shape.forms;
+    if (rest.length) {
+        note(dim(`${shape.label} — ${first.where},`));
+        for (const form of rest) {
+            note(dim(`  or ${form.where}`));
+        }
+        return askSecret('Paste the key, or a path to the file:');
+    }
+    note(dim(`${shape.label} — ${first.where}`));
+    return first.holds === 'file'
         ? ask('Path to the credentials file:')
         : askSecret('Paste the key (it will not be shown):');
 }
@@ -159,7 +232,7 @@ const use = async (ctx, args) => {
     const entry = store.use(provider, name);
     store.save();
     if (ctx.json) {
-        json({ key: keyId(entry), env: SHAPES[provider].env });
+        json({ key: keyId(entry), env: envOf(entry) });
         return;
     }
     note(`${green('using')} ${bold(keyId(entry))} for ${SHAPES[provider].label}`);
@@ -242,7 +315,7 @@ const show = async (ctx, args) => {
     if (ctx.json) {
         json({
             key: keyId(entry),
-            env: SHAPES[entry.provider].env,
+            env: envOf(entry),
             value,
             revealed: Boolean(values.reveal),
         });
@@ -256,8 +329,10 @@ const show = async (ctx, args) => {
     }
     writeAll(table([
         [dim('key'), keyId(entry)],
-        [dim('env'), SHAPES[entry.provider].env],
+        [dim('env'), envOf(entry)],
         [dim('value'), value],
+        ...(entry.project ? [[dim('project'), entry.project]] : []),
+        ...(entry.location ? [[dim('location'), entry.location]] : []),
         [dim('state'), state(entry)],
         [dim('added'), ago(entry.addedAt)],
     ]));
@@ -278,8 +353,18 @@ const env = async (ctx, args) => {
     const vars = {};
     for (const provider of only ?? OWNERS) {
         const entry = store.active(provider);
-        if (entry) {
-            vars[SHAPES[provider].env] = store.reveal(entry);
+        if (!entry) {
+            continue;
+        }
+        vars[envOf(entry)] = store.reveal(entry);
+        // A service account says which project it belongs to but not which
+        // region to call, and a shell that has the file and not the region is
+        // still a shell that cannot reach a model.
+        if (entry.project) {
+            vars.GOOGLE_CLOUD_PROJECT = entry.project;
+        }
+        if (entry.location) {
+            vars.GOOGLE_CLOUD_LOCATION = entry.location;
         }
     }
     if (ctx.json) {
@@ -306,11 +391,16 @@ export const key = {
     usage: USAGE,
     details: [
         'Keys live in ~/.zenera/neo/keys.json (0600) and are materialised into',
-        'the environment before a run. A real environment variable always wins.',
+        'the environment before a run. A real environment variable always wins,',
+        'and is listed as ~ so it is clear where a working provider comes from.',
         '',
         'Model providers: openai, anthropic, google, vertex, openrouter.',
         'Services the tools call: exa.',
         '',
+        'Vertex takes either shape: a service-account JSON file, which wants',
+        '--project and --location too, or an express-mode API key, which wants',
+        'neither. Which one you gave is read off the value.',
+        '',
         '  zen key ls [--check]              Everything stored, and its state.',
         '  zen key add <provider>[/name]     Read a key from stdin, or ask for it.',
         '  zen key use <provider>/<name>     Choose which one a run uses.',

package/dist/commands/models.js

@@ -1,6 +1,6 @@
 import { loadProject, readProjectConfig } from '@zenera/neo';
 import { parse } from "../args.js";
-import { KeyStore, PROVIDERS, SHAPES } from "../keys.js";
+import { envNames, form, KeyStore, PROVIDERS } from "../keys.js";
 import { project as resolveProject } from "../resolve.js";
 import { bold, credentialError, cyan, dim, green, invalidError, json, note, red, table, writeAll, yellow, } from "../term.js";
 import { availableTools } from "../validate.js";
@@ -22,7 +22,7 @@ export const models = {
         // Asked before materialising, because materialising is exactly what
         // erases the difference between "the environment had it" and "the
         // keyring supplied it".
-        const fromEnv = new Set(PROVIDERS.filter((p) => process.env[SHAPES[p].env]));
+        const fromEnv = new Set(PROVIDERS.filter((p) => envNames(p).some((name) => process.env[name])));
         store.materialize();
         let project;
         try {
@@ -64,7 +64,7 @@ export const models = {
         }));
         const credentials = PROVIDERS.map((p) => ({
             provider: p,
-            env: SHAPES[p].env,
+            env: envNames(p).find((name) => process.env[name]) ?? form(p).env,
             source: fromEnv.has(p)
                 ? 'environment'
                 : store.active(p)

package/dist/commands/open.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { delimiter, join, resolve, sep } from 'node:path';
 import { one, parse } from "../args.js";
 import { project as resolveProject } from "../resolve.js";
-import { copilotInstructions, editorSettings } from "../scaffold.js";
+import { editorFiles } from "../scaffold.js";
 import { CliError, cyan, dim, EXIT, json, note, usageError } from "../term.js";
 const USAGE = 'zen open [project] [--editor <cmd>] [--wait]';
 /**
@@ -42,7 +42,7 @@ export const open = {
         // opened on, and a project may predate either of them — or the version
         // this `zen` writes. They are ours, so they are written fresh before
         // the window is there to read them.
-        const written = [editorSettings(dir), ...copilotInstructions(dir)];
+        const written = editorFiles(dir);
         if (ctx.json) {
             json({
                 name: found.name,

package/dist/commands/run.js

@@ -19,6 +19,7 @@ export const run = {
         '  --model <ref>          Override the default model.',
         '  --image <ref>          Override the sandbox image commands run in.',
         '  --read-only            Give the agent no way to write.',
+        '  --no-keys              Keep the API keys out of the sandbox.',
         '  --quiet                Answer only; no narration.',
         '  --plain                One shot, even on a terminal.',
         '  --theme <dark|light>   Force the palette. Detected otherwise; $ZENERA_THEME.',
@@ -43,6 +44,7 @@ export const run = {
             workspace: { type: 'string' },
             model: { type: 'string' },
             image: { type: 'string' },
+            'no-keys': { type: 'boolean' },
             'read-only': { type: 'boolean' },
             yes: { type: 'boolean' },
             quiet: { type: 'boolean' },
@@ -84,6 +86,7 @@ export const run = {
             readOnly: values['read-only'],
             model: values.model,
             image: values.image,
+            keys: values['no-keys'] ? false : undefined,
             yes: values.yes || ctx.json,
         });
         try {

package/dist/engine.d.ts

@@ -10,6 +10,8 @@ export interface EngineOptions {
     model?: string;
     /** sandbox image override — `--image` */
     image?: string;
+    /** whether credentials reach the sandbox — `--no-keys` sets this false */
+    keys?: boolean;
     /** answer the sandbox's install question without asking — `--yes` */
     yes?: boolean;
 }

package/dist/engine.js

@@ -46,6 +46,7 @@ export async function open(opts) {
             workspace,
             readOnly: opts.readOnly,
             image: opts.image,
+            keys: opts.keys,
             mounts,
         });
         project = await loadProject(opts.project.dir, {

package/dist/keys.d.ts

@@ -17,24 +17,49 @@ export type Service = (typeof SERVICES)[number];
 /** Anything the keyring can hold a credential for. */
 export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa"];
 export type KeyOwner = Provider | Service;
-interface ProviderShape {
-    /** whether this is somewhere a model lives, or something a tool calls */
-    kind: 'model' | 'service';
-    /** environment variable the library reads */
-    env: string;
+/**
+ * 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';
-    label: string;
+    /** 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, or something a tool calls */
+    kind: 'model' | 'service';
+    label: string;
+    /** the ways in, first being the one this provider is usually reached by */
+    forms: [CredentialForm, ...CredentialForm[]];
+}
 /**
- * Vertex is the odd one. The GenAI SDK resolves Application Default
- * Credentials itself, so what is stored is a service-account *file* and what is
- * exported is a path — not a key. Pretending otherwise would mean inventing a
- * credential shape Google does not have.
+ * 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[];
+/** 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 assertOwner(name: string): KeyOwner;
@@ -52,6 +77,11 @@ export interface KeyEntry {
     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;
     addedAt: string;
     check?: KeyCheck;
 }
@@ -65,6 +95,13 @@ export declare function parseRef(ref: string): {
     provider: KeyOwner;
     name?: string;
 };
+/** 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;
+}
 export declare class KeyStore {
     #private;
     private constructor();
@@ -81,13 +118,21 @@ export declare class KeyStore {
      * 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): KeyEntry;
+    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;
     save(): void;
-    /** Absolute path behind a file-shaped entry. */
+    /**
+     * 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;
@@ -110,6 +155,44 @@ export declare class KeyStore {
  */
 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.