@zenera/cli 1.1.9 → 1.1.11

package/dist/commands/cache.js

@@ -0,0 +1,245 @@
+import { parse } from "../args.js";
+import { clear, items, kinds, sweep } from "../cache.js";
+import { paths } from "../home.js";
+import { ago, bold, bytes, confirm, count, cyan, dim, green, isInteractive, json, note, table, usageError, writeAll, } from "../term.js";
+const USAGE = 'zen cache [ls|prune|clear] [options]';
+/** Enough to see what is in there; the rest is a number. */
+const LISTED = 20;
+// ---------------------------------------------------------------------------
+// The cache, from outside
+//
+// Everything expensive and repeatable this machine has done is kept in one
+// place, and the reason it needs a command at all is that nothing evicts from
+// it on its own. That is deliberate: a store that quietly deletes things is
+// only ever noticed when it has deleted the wrong one. So retention is a
+// decision someone makes out loud, here.
+//
+// Nothing in it is precious. Every entry can be recomputed, which is why
+// `clear` is safe to reach for and why the only cost of being wrong is time.
+// ---------------------------------------------------------------------------
+export const cache = {
+    summary: 'What work has been kept, and getting rid of it.',
+    usage: USAGE,
+    details: [
+        '  ls                     What is stored, by kind. Changes nothing.',
+        '  prune                  Remove what the filters name.',
+        '  clear                  Remove everything, or one kind of everything.',
+        '',
+        '  --kind <name>          Just this kind. With `ls`, list its entries.',
+        '  --older-than <age>     Unused for longer than e.g. 30d, 12h, 2w.',
+        '  --max-size <size>      Ceiling on what is left, e.g. 500MB, 2GB.',
+        '  --limit <n>            Entries to list. Default 20.',
+        '  --yes                  Do not ask before removing.',
+        '',
+        'Age is when an entry was last *used*, not when it was written, so a',
+        'vector a rebuild reads every week is never old.',
+        '',
+        '`prune` with no filter is a usage error: deleting everything is what',
+        '`clear` is for, and it should have to be typed.',
+        '',
+        'Nothing here is precious. Every entry is work that can be done again,',
+        'so the only cost of removing one is paying for it a second time.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            kind: { type: 'string' },
+            'older-than': { type: 'string' },
+            'max-size': { type: 'string' },
+            limit: { type: 'string' },
+            yes: { type: 'boolean' },
+        }, USAGE);
+        const what = positionals[0] ?? 'ls';
+        if (!['ls', 'prune', 'clear'].includes(what)) {
+            throw usageError(`unknown subcommand: ${what}`, USAGE);
+        }
+        if (positionals.length > 1) {
+            throw usageError('one subcommand at a time', USAGE);
+        }
+        switch (what) {
+            case 'ls':
+                return list(values, ctx.json);
+            case 'prune':
+                return prune(values, ctx.json);
+            default:
+                return wipe(values, ctx.json);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+function list(values, asJson) {
+    if (values.kind) {
+        return listOne(values, asJson);
+    }
+    const rows = kinds();
+    if (asJson) {
+        json({ dir: paths.cache(), kinds: rows, ...totals(rows) });
+        return;
+    }
+    if (rows.length === 0) {
+        note(`nothing cached yet ${dim(paths.cache())}`);
+        return;
+    }
+    writeAll(table([
+        [bold('KIND'), bold('ENTRIES'), bold('SIZE'), bold('OLDEST'), bold('NEWEST')],
+        ...rows.map((row) => [
+            cyan(row.kind),
+            String(row.entries),
+            bytes(row.bytes),
+            dim(since(row.oldest)),
+            dim(since(row.newest)),
+        ]),
+    ]));
+    const all = totals(rows);
+    note('');
+    note(dim(`${count(all.entries, 'entry', 'entries')}, ${bytes(all.bytes)} in ${paths.cache()}`));
+}
+function listOne(values, asJson) {
+    const kind = values.kind;
+    const limit = number(values.limit, '--limit') ?? LISTED;
+    const { rows, found } = items(kind, { limit });
+    if (asJson) {
+        json({ kind, found, entries: rows });
+        return;
+    }
+    if (found === 0) {
+        note(`nothing cached under ${cyan(kind)}`);
+        return;
+    }
+    writeAll(table([
+        [bold('KEY'), bold('SIZE'), bold('USED')],
+        ...rows.map((row) => [shorten(row.key), bytes(row.bytes), dim(since(row.usedAt))]),
+    ]));
+    if (found > rows.length) {
+        note('');
+        note(dim(`${found - rows.length} more — raise --limit to see them`));
+    }
+}
+// ---------------------------------------------------------------------------
+// prune and clear
+// ---------------------------------------------------------------------------
+function prune(values, asJson) {
+    const olderThanMs = duration(values['older-than']);
+    const maxBytes = size(values['max-size']);
+    if (olderThanMs === undefined && maxBytes === undefined) {
+        throw usageError('prune needs something to go on', 'pass --older-than <age> or --max-size <size>, or run: zen cache clear');
+    }
+    report(sweep({ kind: values.kind, olderThanMs, maxBytes }), asJson);
+}
+async function wipe(values, asJson) {
+    const before = kinds().filter((row) => !values.kind || row.kind === values.kind);
+    const all = totals(before);
+    if (all.entries === 0) {
+        if (asJson) {
+            json({ removed: [], entries: 0, bytes: 0 });
+            return;
+        }
+        note(values.kind ? `nothing cached under ${cyan(values.kind)}` : 'nothing cached yet');
+        return;
+    }
+    if (!values.yes && !asJson && isInteractive()) {
+        const what = values.kind
+            ? `${count(all.entries, 'entry', 'entries')} under ${values.kind}`
+            : count(all.entries, 'entry', 'entries');
+        if (!(await confirm(`Remove ${what} (${bytes(all.bytes)})?`))) {
+            note('left alone');
+            return;
+        }
+    }
+    clear({ kind: values.kind });
+    report(before.map((row) => ({ kind: row.kind, removed: row.entries, bytes: row.bytes })), asJson);
+}
+function report(swept, asJson) {
+    const entries = swept.reduce((n, row) => n + row.removed, 0);
+    const freed = swept.reduce((n, row) => n + row.bytes, 0);
+    if (asJson) {
+        json({ removed: swept, entries, bytes: freed });
+        return;
+    }
+    if (entries === 0) {
+        note('nothing to remove');
+        return;
+    }
+    for (const row of swept) {
+        note(`${green('removed')} ${count(row.removed, 'entry', 'entries')} ${dim(`${row.kind} · ${bytes(row.bytes)}`)}`);
+    }
+    if (swept.length > 1) {
+        note('');
+        note(dim(`${count(entries, 'entry', 'entries')}, ${bytes(freed)} freed`));
+    }
+}
+// ---------------------------------------------------------------------------
+// Reading the filters
+// ---------------------------------------------------------------------------
+const DURATIONS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/** `30d`, `12h`, `2w`. A bare number is days: nobody means milliseconds. */
+export function duration(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(text.trim());
+    const unit = match ? (match[2] || 'd').toLowerCase() : '';
+    const scale = DURATIONS[unit];
+    if (!match || scale === undefined) {
+        throw usageError(`"${text}" is not an age`, 'try: 30d, 12h, 2w');
+    }
+    return Number(match[1]) * scale;
+}
+const SIZES = {
+    b: 1,
+    kb: 1000,
+    mb: 1000 ** 2,
+    gb: 1000 ** 3,
+    tb: 1000 ** 4,
+};
+/** `500MB`, `2GB`. Powers of 1000, the way `bytes()` prints them back. */
+export function size(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(text.trim());
+    const unit = match ? (match[2] || 'mb').toLowerCase() : '';
+    const scale = SIZES[unit];
+    if (!match || scale === undefined) {
+        throw usageError(`"${text}" is not a size`, 'try: 500MB, 2GB');
+    }
+    return Number(match[1]) * scale;
+}
+function number(text, flag) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const value = Number(text);
+    if (!Number.isInteger(value) || value < 1) {
+        throw usageError(`${flag} takes a whole number of at least 1`, `got "${text}"`);
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Small formatting
+// ---------------------------------------------------------------------------
+const totals = (rows) => ({
+    entries: rows.reduce((n, row) => n + row.entries, 0),
+    bytes: rows.reduce((n, row) => n + row.bytes, 0),
+});
+const since = (at) => at === undefined ? 'never' : ago(new Date(at).toISOString());
+/**
+ * A key holds every input that produced the value, so an embedding's key is a
+ * whole paragraph. One line of it says which entry this is; the rest is noise
+ * in a table.
+ */
+function shorten(key) {
+    const flat = key
+        .replace(/\u0000/g, ' · ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > 72 ? `${flat.slice(0, 71)}…` : flat || dim('(unreadable)');
+}
+//# sourceMappingURL=cache.js.map

package/dist/commands/check.js

@@ -35,9 +35,9 @@ export const check = {
     details: [
         '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.',
+        'and forks name agents that exist, every hand-off has a way back, 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, and --no-sandbox skips',
@@ -199,6 +199,9 @@ function render(report) {
     if (report.models.length) {
         push(...table(report.models.map((m) => [
             `  ${m.name}`,
+            // An alias names nothing the provider knows, so what it
+            // stands for is printed next to it.
+            dim(m.ref ?? ''),
             dim(m.provider ? `${m.provider} (${m.kind})` : red('unresolved')),
             dim(m.env ?? ''),
             credential(m.credential),

package/dist/commands/index.js

@@ -1,3 +1,4 @@
+import { cache } from "./cache.js";
 import { check } from "./check.js";
 import { init } from "./init.js";
 import { inspect } from "./inspect.js";
@@ -23,6 +24,7 @@ export const COMMANDS = {
     check,
     inspect,
     sandbox,
+    cache,
     version,
 };
 /** Names that are not listed in help but still work. */
@@ -51,7 +53,7 @@ export const EXTERNAL = {
         summary: 'Retrieval over a corpus: index it, then ask it something.',
         usage: 'zen rag <subject> <command> [args...]',
         install: 'npm i -g @zenera/rag',
-        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Api Retrieval' },
+        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Corpus Retrieval' },
     },
 };
 //# sourceMappingURL=index.js.map

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 { ambient, ambientId, assertNotEmpty, describe, envNames, envOf, keyId, KeyStore, mask, OWNERS, parseRef, SHAPES, } from "../keys.js";
+import { ambient, ambientId, assertNotEmpty, checkRegion, describe, envNames, envOf, formOf, 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]';
@@ -17,6 +17,32 @@ const MARK = {
 function state(entry) {
     return entry.check ? MARK[entry.check.state] : dim('unchecked');
 }
+/** Where a Vertex project id came from, since only one of the three was typed. */
+const ORIGIN = {
+    env: 'from $GOOGLE_CLOUD_PROJECT',
+    stored: 'from --gcp-project',
+    file: 'from the key file',
+};
+/**
+ * Only a Vertex service account addresses a project and a region. An unset
+ * region is shown as the `global` it will actually be, not left blank: it is
+ * the slow endpoint, and a blank column is how it goes unnoticed. The project
+ * is shown whether or not one was stored, because the file names one too and a
+ * blank there reads as "none" rather than "not written down here". Yellow when
+ * the environment supplied either, because then the stored one is not in play.
+ */
+function placed(store, entry) {
+    if (entry.provider !== 'vertex' || entry.holds !== 'file') {
+        return '';
+    }
+    const fromEnv = process.env.GOOGLE_CLOUD_LOCATION;
+    const where = fromEnv ?? entry.location ?? 'global';
+    const project = store.projectOf(entry);
+    const id = project ? project.id : '';
+    return [fromEnv ? yellow(where) : dim(where), project?.from === 'env' ? yellow(id) : dim(id)]
+        .join(' ')
+        .trimEnd();
+}
 /**
  * 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
@@ -35,7 +61,7 @@ function asEntry(cred) {
 }
 function rows(store, borrowed) {
     const out = [
-        [bold(''), bold('KEY'), bold('VALUE'), bold('STATE'), bold('CHECKED')],
+        [bold(''), bold('KEY'), bold('VALUE'), bold('GCP'), bold('STATE'), bold('CHECKED')],
     ];
     for (const provider of OWNERS) {
         for (const entry of store.for(provider)) {
@@ -44,6 +70,7 @@ function rows(store, borrowed) {
                 store.isActive(entry) ? green('*') : ' ',
                 keyId(entry),
                 dim(describe(store, entry)),
+                placed(store, entry),
                 state(entry),
                 dim(entry.check ? ago(entry.check.at) : '—') +
                     (shadow && store.isActive(entry) ? yellow(`  shadowed by $${shadow}`) : ''),
@@ -54,6 +81,7 @@ function rows(store, borrowed) {
                 dim('~'),
                 dim(ambientId(cred)),
                 dim(describe(store, entry)),
+                placed(store, entry),
                 state(entry),
                 dim(cred.env ? 'from the environment' : 'from gcloud'),
             ]);
@@ -133,9 +161,11 @@ const add = async (ctx, args) => {
     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]');
+        // Prefixed because every other command's --project is a Zenera one.
+        'gcp-project': { type: 'string' },
+        'gcp-location': { type: 'string' },
+    }, 'zen key add <provider>[/name] [--name <name>] [--gcp-project <id>] ' +
+        '[--gcp-location <region>] [--no-check]');
     const ref = positionals[0];
     if (!ref) {
         throw usageError('which provider?', `one of: ${OWNERS.join(', ')}`);
@@ -144,8 +174,14 @@ 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');
+    if ((values['gcp-project'] || values['gcp-location']) && provider !== 'vertex') {
+        throw usageError(`--gcp-project and --gcp-location mean nothing to ${shape.label}`, 'they configure a Vertex service account');
+    }
+    // Checked before the prompt, so a typo does not cost you pasting the key.
+    const region = values['gcp-location'];
+    if (region !== undefined && !checkRegion(region)) {
+        note(yellow(`${region} is not a region this build knows; storing it anyway`));
+        note(dim('  if it is new, this is fine; if it is a typo, Vertex answers 404'));
     }
     ensureHome();
     const store = await KeyStore.open();
@@ -164,9 +200,14 @@ const add = async (ctx, args) => {
     if (shape.forms.length === 1 && shape.forms[0].holds === 'file' && !existsSync(raw)) {
         throw usageError(`no such file: ${raw}`);
     }
+    // Which shape was given is only knowable now, and `add` would drop these
+    // two on an express key rather than store a combination Vertex refuses.
+    if (formOf(provider, raw).holds !== 'file' && (values['gcp-project'] || region)) {
+        throw usageError('--gcp-project and --gcp-location need a service-account file', 'the value given is an express-mode key, which addresses no project or region');
+    }
     const entry = store.add(provider, name, raw, {
-        project: values.project,
-        location: values.location,
+        project: values['gcp-project'],
+        location: values['gcp-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
@@ -186,6 +227,12 @@ const add = async (ctx, args) => {
                 note(dim(`  ${check.fix}`));
             }
         }
+        else if (check.state === 'unknown' && check.fix) {
+            // Most unknowns are a plane or a proxy and say nothing worth a
+            // line. One carrying a fix is different: we know what is wrong.
+            note(`${yellow('unverified')} ${check.detail}`);
+            note(dim(`  ${check.fix}`));
+        }
     }
     store.save();
     if (ctx.json) {
@@ -203,7 +250,10 @@ const add = async (ctx, args) => {
         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'));
+        const found = store.projectOf(entry);
+        note(dim(found
+            ? `no --gcp-project given; project ${found.id}, read from the key file`
+            : 'no --gcp-project given, and the key file names no project_id'));
     }
 };
 /**
@@ -329,12 +379,14 @@ const show = async (ctx, args) => {
         throw usageError(`no key ${ref}`, 'see: zen key ls');
     }
     const value = values.reveal ? store.reveal(entry) : describe(store, entry);
+    const project = store.projectOf(entry);
     if (ctx.json) {
         json({
             key: keyId(entry),
             env: envOf(entry),
             value,
             revealed: Boolean(values.reveal),
+            ...(project ? { project: project.id, projectFrom: project.from } : {}),
         });
         return;
     }
@@ -348,8 +400,10 @@ const show = async (ctx, args) => {
         [dim('key'), keyId(entry)],
         [dim('env'), envOf(entry)],
         [dim('value'), value],
-        ...(entry.project ? [[dim('project'), entry.project]] : []),
-        ...(entry.location ? [[dim('location'), entry.location]] : []),
+        ...(project
+            ? [[dim('gcp project'), `${project.id} ${dim(ORIGIN[project.from])}`]]
+            : []),
+        ...(entry.location ? [[dim('gcp location'), entry.location]] : []),
         [dim('state'), state(entry)],
         ...(entry.check?.fix ? [[dim('fix'), entry.check.fix]] : []),
         [dim('added'), ago(entry.addedAt)],
@@ -416,8 +470,8 @@ export const key = {
         '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.',
+        '--gcp-project and --gcp-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.',

package/dist/commands/models.js

@@ -393,6 +393,17 @@ function verdict(probe) {
             return dim('no answer');
     }
 }
+/**
+ * Which project and region a Vertex call was actually made in. A publisher
+ * model is only missing *somewhere*, and the somewhere is the part nobody
+ * typed: it comes off the key, or out of the service-account file itself.
+ */
+function vertexAt(where) {
+    const entry = where.fromEnv.has('vertex') ? undefined : where.store.active('vertex');
+    const id = entry ? where.store.projectOf(entry)?.id : process.env.GOOGLE_CLOUD_PROJECT;
+    const location = process.env.GOOGLE_CLOUD_LOCATION ?? entry?.location ?? 'global';
+    return `vertex: project ${id ?? 'unset'} · location ${location}`;
+}
 const test = async (ctx, args) => {
     const { values, positionals } = parse(args, ROLE_OPTIONS, 'zen models test <provider:model> … [--chat|--embedding]');
     if (positionals.length === 0) {
@@ -402,7 +413,7 @@ const test = async (ctx, args) => {
     // Every ref is split before anything is built, so a typo in the third one
     // does not arrive after two billable calls.
     const parsed = positionals.map((ref) => ({ ref, ...split(ref) }));
-    await credentials();
+    const where = await credentials();
     const probes = [];
     const bar = ctx.json ? undefined : progress();
     for (const { ref, provider, id } of parsed) {
@@ -425,6 +436,11 @@ const test = async (ctx, args) => {
                 note(dim(`${p.ref}: ${p.check.fix}`));
             }
         }
+        // A Vertex refusal is about a model *in a project*, and the project is
+        // the half of that nobody typed.
+        if (parsed.some((p) => p.provider === 'vertex')) {
+            note(dim(vertexAt(where)));
+        }
     }
     const failed = probes.filter((p) => p.check.state !== 'live');
     if (failed.length > 0) {

package/dist/commands/run.js

@@ -104,13 +104,14 @@ export const run = {
                 await start(engine, {
                     readOnly: Boolean(values['read-only']),
                     theme: values.theme,
+                    started: { created: where.created, freshWorkspace: where.freshWorkspace },
                 });
                 return;
             }
             if (!prompt) {
                 throw usageError('nothing to ask', 'give a prompt, or pipe one in');
             }
-            await once(engine, prompt, values, ctx.json, ctx.cwd);
+            await once(engine, prompt, values, ctx.json, ctx.cwd, where);
         }
         finally {
             await engine.close();
@@ -120,7 +121,7 @@ export const run = {
 // ---------------------------------------------------------------------------
 // One shot
 // ---------------------------------------------------------------------------
-async function once(engine, prompt, values, asJson, cwd) {
+async function once(engine, prompt, values, asJson, cwd, where) {
     const narrator = new Narrator({
         quiet: Boolean(values.quiet) || asJson,
         live: Boolean(process.stderr.isTTY),
@@ -131,7 +132,14 @@ async function once(engine, prompt, values, asJson, cwd) {
     const onInterrupt = () => stopping.abort();
     process.once('SIGINT', onInterrupt);
     if (!values.quiet && !asJson) {
-        note(`${bold(engine.name)} ${dim(engine.session.id)} ` + dim(display(engine.workspace, cwd)));
+        // Two questions were just answered, possibly without being asked. Say
+        // which way they went: a run that quietly resumed the wrong session, or
+        // wrote into the directory you were standing in, is only explainable
+        // afterwards, and this is the one line where it is cheap to say.
+        note(`${bold(engine.name)} ${dim(where.created ? 'new session' : 'continuing')} ` +
+            `${dim(engine.session.id)}`);
+        note(dim(`${where.freshWorkspace ? 'new directory' : 'workspace'} ` +
+            `${display(engine.workspace, cwd)}`));
     }
     let outcome;
     try {