@zenera/cli 1.1.27 → 1.1.29

package/dist/commands/meta.js

@@ -5,17 +5,20 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parse } from "../args.js";
+import { matching, projectNames } from "../candidates.js";
 import { loadProjectEnv } from "../env.js";
 import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
-import { assertOwner, KeyStore, PROVIDERS } from "../keys.js";
+import { assertOwner, isProvider, KeyStore, PROVIDERS } from "../keys.js";
 import { probeChat, probeModel } from "../liveness.js";
-import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, RECOMMENDED, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
+import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, defaultRef, editorFiles, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, writeMeta, } from "../meta/index.js";
 import { splitRef } from "../modelref.js";
 import { duration } from "../narrate.js";
 import * as Projects from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
-import { bold, choose, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, readStdin, table, usageError, warn, write, writeAll, } from "../term.js";
+import { TEMPLATES } from "../scaffold.js";
+import { bold, choose, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, pad, progress, readStdin, table, usageError, warn, write, writeAll, } from "../term.js";
+import { wrap } from "../tui/wrap.js";
 import { appendUsage, LEDGER_ENV, ledgerPath, META_PROMPT_ENV, META_SESSION_ENV, } from "../usage.js";
 const USAGE = 'zen meta run [project] [prompt] [options]';
 const VERBS = new Set(['model', 'run', 'prompts', 'resume', 'dataset', 'finetune']);
@@ -55,15 +58,76 @@ function page(p) {
         write(line ? `  ${line}` : '');
     }
 }
+/** Kept apart from `run` so that shell completion offers exactly what is parsed. */
+const OPTIONS = {
+    project: { type: 'string' },
+    provider: { type: 'string' },
+    model: { type: 'string' },
+    prompt: { type: 'string', short: 'p' },
+    'prompt-file': { type: 'string' },
+    agent: { type: 'string' },
+    effort: { type: 'string' },
+    share: { type: 'string' },
+    events: { type: 'string' },
+    resume: { type: 'string' },
+    continue: { type: 'boolean' },
+    'session-id': { type: 'string' },
+    retries: { type: 'string' },
+    'allow-all': { type: 'boolean' },
+    'allow-tool': { type: 'string' },
+    ask: { type: 'boolean' },
+    'add-dir': { type: 'string', multiple: true },
+    'dry-run': { type: 'boolean' },
+    local: { type: 'boolean' },
+    pick: { type: 'boolean' },
+    clear: { type: 'boolean' },
+    force: { type: 'boolean' },
+    'no-refresh': { type: 'boolean' },
+};
+const RUN_FORMS = [
+    '  zen meta run [project] "<question>"      ask it something',
+    '  zen meta run [project] /<name> [words]   run a stored prompt',
+    '  zen meta run [project]                   pick one of its stored prompts',
+];
+const RUN_ARGUMENTS = [
+    'Arguments:',
+    '  [project]   Name of a project. Default: the one you are in.',
+    '  [prompt]    Your question, in quotes. Or --prompt, or piped in when neither',
+    '              it nor --prompt-file is given.',
+    '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
+    '  [words]     Appended to that prompt as a final line.',
+];
+const RUN_OPTIONS = [
+    'Options:',
+    '  --project <name|dir>   Which project to work in. The agent is rooted there.',
+    '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
+    '  --provider <name>      Force the key to use. Default: the model ref says.',
+    '  -p, --prompt <text>    The question, in place of [prompt].',
+    '                         Ignored with /<name>: put words after it instead.',
+    '  --prompt-file <file>   Added after the question - or after /<name> and its',
+    '                         words - past a blank line. Alone, it is the question.',
+    '  --agent <name>         A .github/agents/<name>.agent.md.',
+    '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
+    '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
+    '  --ask                  Have it ask before each tool. Default: it does not.',
+    '  --add-dir <dir>        Another directory it may touch. Repeatable.',
+    '  --resume <id>          Continue a copilot session. --continue takes the last.',
+    '  --session-id <uuid>    Start a new session under this id. Default: a random one.',
+    `  --retries <n>          Resume after a rate limit or outage. Default ${DEFAULT_RESUMES}, 0 = off.`,
+    '  --share <file>         Write the transcript to a markdown file.',
+    '  --events <file>        Append what the agent does to this file as it does it:',
+    '                         one JSON line per model call, tool call and message.',
+    '  --dry-run              Print what would run, secrets masked, and stop.',
+    '  --no-refresh           Leave the editor files as they are (parallel runs).',
+    '  --json                 Print one object: answer, answerFile, sessionId, exitCode, tokens.',
+];
 export const meta = {
     summary: 'Run the meta agent over this project, on your own keys.',
     usage: USAGE,
     banner: { head: 'Zenera', accent: 'Meta', subtitle: 'Meta Agent', hue: 'cyan' },
     details: [
         'Forms:',
-        '  zen meta run [project] "<question>"      ask it something',
-        '  zen meta run [project] /<name> [words]   run a stored prompt',
-        '  zen meta run [project]                   pick one of its stored prompts',
+        ...RUN_FORMS,
         '  zen meta prompts [project]               list the stored prompts',
         '  zen meta resume [project] [session]      carry on a run that stopped',
         '  zen meta model [ref]                     show or set the model it uses',
@@ -71,33 +135,12 @@ export const meta = {
         '  zen meta finetune <verb>                 tune the project on those cases',
         '',
         'The project may come before the verb instead: `zen meta acme run`.',
-        '`zen meta dataset --help` and `zen meta finetune --help` have their own pages.',
+        '`zen meta dataset --help`, `zen meta finetune --help` and `zen meta run --help`',
+        'have their own pages; the last lists the stored prompts.',
         '',
-        'Arguments:',
-        '  [project]   Name of a project. Default: the one you are in.',
-        '  [prompt]    Your question, in quotes. Also --prompt, or piped in.',
-        '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
-        '  [words]     Appended to that prompt as a final line.',
+        ...RUN_ARGUMENTS,
         '',
-        'Options:',
-        '  --project <name|dir>   Which project to work in. The agent is rooted there.',
-        '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
-        '  --provider <name>      Force the key to use. Default: the model ref says.',
-        '  --prompt-file <file>   Append this file to the prompt, after any words.',
-        '  --agent <name>         A .github/agents/<name>.agent.md.',
-        '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
-        '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
-        '  --ask                  Have it ask before each tool. Default: it does not.',
-        '  --add-dir <dir>        Another directory it may touch. Repeatable.',
-        '  --resume <id>          Continue a copilot session. --continue takes the last.',
-        '  --session-id <uuid>    Start a new session under this id. Default: a random one.',
-        `  --retries <n>          Resume after a rate limit or outage. Default ${DEFAULT_RESUMES}, 0 = off.`,
-        '  --share <file>         Write the transcript to a markdown file.',
-        '  --events <file>        Append what the agent does to this file as it does it:',
-        '                         one JSON line per model call, tool call and message.',
-        '  --dry-run              Print what would run, secrets masked, and stop.',
-        '  --no-refresh           Leave the editor files as they are (parallel runs).',
-        '  --json                 Print one object: answer, answerFile, sessionId, exitCode, tokens.',
+        ...RUN_OPTIONS,
         '',
         'It always uses your own keys — `zen key add` — and never a coding-agent',
         'subscription. The answer goes to stdout and the progress to stderr, so',
@@ -131,6 +174,9 @@ export const meta = {
         'Setting one asks the provider a one-word question first, so a model that',
         'will not answer is never stored. --force skips that.',
         '',
+        '`zen meta model --pick` browses every model your keys reach: / filters,',
+        't asks one a question, p takes it.',
+        '',
         'Examples:',
         '  zen meta run "what does this project do?"',
         '  zen meta run acme "review the last commit"',
@@ -144,9 +190,16 @@ export const meta = {
         '  zen meta model --pick',
         '  zen meta run --dry-run "hello"',
     ],
-    help: (ctx) => {
+    help: async (ctx) => {
         const sub = subcommand(ctx.args);
-        page(sub ? SUBCOMMANDS[sub.name].page : { ...meta, details: meta.details ?? [] });
+        if (sub) {
+            return page(SUBCOMMANDS[sub.name].page);
+        }
+        const words = ctx.args.filter((a) => !a.startsWith('-'));
+        if (words[0] === 'run' || words[1] === 'run') {
+            return await runHelp(ctx, words);
+        }
+        page({ ...meta, details: meta.details ?? [] });
     },
     run: async (ctx) => {
         // These own their flags, so they are routed before the meta agent's are parsed.
@@ -160,31 +213,7 @@ export const meta = {
             });
             return await run({ args, json: ctx.json, cwd: ctx.cwd }, found);
         }
-        const { values, positionals } = parse(ctx.args, {
-            project: { type: 'string' },
-            provider: { type: 'string' },
-            model: { type: 'string' },
-            prompt: { type: 'string', short: 'p' },
-            'prompt-file': { type: 'string' },
-            agent: { type: 'string' },
-            effort: { type: 'string' },
-            share: { type: 'string' },
-            events: { type: 'string' },
-            resume: { type: 'string' },
-            continue: { type: 'boolean' },
-            'session-id': { type: 'string' },
-            retries: { type: 'string' },
-            'allow-all': { type: 'boolean' },
-            'allow-tool': { type: 'string' },
-            ask: { type: 'boolean' },
-            'add-dir': { type: 'string', multiple: true },
-            'dry-run': { type: 'boolean' },
-            local: { type: 'boolean' },
-            pick: { type: 'boolean' },
-            clear: { type: 'boolean' },
-            force: { type: 'boolean' },
-            'no-refresh': { type: 'boolean' },
-        }, USAGE);
+        const { values, positionals } = parse(ctx.args, OPTIONS, USAGE);
         // `zen meta acme run` is typed at least as often as `zen meta run acme`,
         // and read literally it asks the agent the one-word question "run" —
         // a whole model call spent on a typo, with nothing on screen to say so.
@@ -216,6 +245,45 @@ export const meta = {
         throw usageError(first === undefined ? 'nothing to run' : 'a prompt goes through `run`', `try: zen meta run ${positionals.map(requote).join(' ') || '"what does this project do?"'}`);
     },
 };
+// ---------------------------------------------------------------------------
+// zen meta run --help
+//
+// The prompts are the reason to type `run`, so its page names them. The
+// shipped ones come from the templates, which `run` refreshes into the project
+// first; a project's own additions are read from the project.
+// ---------------------------------------------------------------------------
+async function runHelp(ctx, words) {
+    const at = ctx.args.indexOf('--project');
+    const flag = ctx.args.find((a) => a.startsWith('--project='))?.slice('--project='.length) ??
+        (at >= 0 ? ctx.args[at + 1] : undefined);
+    const named = flag ?? (words[1] === 'run' ? words[0] : words[1]);
+    const project = (named && !named.startsWith('/') ? await Projects.find(named) : undefined) ??
+        (await Projects.current(ctx.cwd));
+    const shipped = join(TEMPLATES, 'editor');
+    const ours = new Set(await listPrompts(shipped));
+    const theirs = project ? await listPrompts(project.dir) : [];
+    const names = [...new Set([...ours, ...theirs])].sort();
+    const found = await Promise.all(names.map((n) => loadPrompt(ours.has(n) ? shipped : project.dir, n)));
+    const lines = [
+        'Forms:',
+        ...RUN_FORMS,
+        '',
+        project ? `Prompts in ${project.name}:` : 'Prompts:',
+    ];
+    const nameWidth = Math.max(...found.map((p) => p.name.length + 1));
+    const room = Math.max(30, Math.min(process.stdout.columns ?? 80, 100) - nameWidth - 6);
+    for (const p of found) {
+        const [first = '', ...more] = wrap(p.description ?? '', room);
+        lines.push(`  ${pad(`/${p.name}`, nameWidth)}  ${first}`.trimEnd());
+        lines.push(...more.map((l) => `  ${' '.repeat(nameWidth)}  ${l}`));
+    }
+    lines.push('', ...RUN_ARGUMENTS, '', ...RUN_OPTIONS, '', 'Examples:', '  zen meta run "what does this project do?"', '  zen meta run acme /project-review', '  zen meta run acme /spec-sync-project agents/triage.md', '  zen meta run acme /analyze --json');
+    page({
+        usage: 'zen meta run [project] [/<name> [words] | "<question>"] [options]',
+        summary: 'Ask the meta agent a question, or run one of the stored prompts.',
+        details: lines,
+    });
+}
 /** Words the shell would have split are shown back the way they were typed. */
 const requote = (s) => (/\s/.test(s) ? JSON.stringify(s) : s);
 // ---------------------------------------------------------------------------
@@ -327,6 +395,104 @@ async function pickPrompt(ctx, project) {
     return await choose('Which prompt?', names.map((n) => ({ label: `/${n}`, value: n })));
 }
 // ---------------------------------------------------------------------------
+// Completing it
+//
+// `zen meta run acme /<Tab>` is where a terminal can show what an editor's menu
+// shows. It reads the line the way `stored` does — a leading slash is a prompt,
+// a bare word that names a project is the project — and it only ever reads:
+// the editor files are not refreshed for the sake of a Tab.
+// ---------------------------------------------------------------------------
+async function findProject(name) {
+    try {
+        return await Projects.find(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function promptsOf(project) {
+    if (!project) {
+        return [];
+    }
+    const names = await listPrompts(project.dir);
+    return await Promise.all(names.map(async (name) => ({
+        value: `/${name}`,
+        description: (await loadPrompt(project.dir, name).catch(() => undefined))?.description,
+    })));
+}
+/** `args` is what came after `meta`, without the word being completed. */
+export async function completeMeta(args, cur, cwd) {
+    const words = [];
+    let flagged;
+    let waiting;
+    for (const arg of args) {
+        if (waiting) {
+            if (waiting === 'project') {
+                flagged = arg;
+            }
+            waiting = undefined;
+        }
+        else if (arg.startsWith('--')) {
+            const [flag, value] = arg.slice(2).split(/=(.*)/s);
+            if (value !== undefined) {
+                flagged = flag === 'project' ? value : flagged;
+            }
+            else if (OPTIONS[flag]?.type === 'string') {
+                waiting = flag;
+            }
+        }
+        else if (arg === '-p') {
+            waiting = 'prompt';
+        }
+        else if (!arg.startsWith('-')) {
+            words.push(arg);
+        }
+    }
+    // A flag's value is the flag's to name, and most of them are free text or a
+    // path — which is the shell's.
+    if (waiting === 'provider') {
+        return matching(PROVIDERS.map((value) => ({ value })), cur);
+    }
+    if (waiting === 'project') {
+        return matching(await projectNames(), cur);
+    }
+    if (waiting) {
+        return [];
+    }
+    const at = words.findIndex((w) => VERBS.has(w));
+    const named = at === 1 ? words[0] : undefined;
+    const verb = at === 0 || (named && (await findProject(named))) ? words[at] : undefined;
+    if (cur.startsWith('-')) {
+        return verb === 'dataset' || verb === 'finetune'
+            ? []
+            : matching(Object.keys(OPTIONS).map((flag) => ({ value: `--${flag}` })), cur);
+    }
+    if (!verb) {
+        const verbs = [...VERBS].map((value) => ({ value }));
+        if (words.length === 0) {
+            return matching([...verbs, ...(await projectNames())], cur);
+        }
+        return words.length === 1 && (await findProject(words[0])) ? matching(verbs, cur) : [];
+    }
+    const rest = words.slice(at + 1);
+    if (verb === 'prompts' || verb === 'resume') {
+        return flagged || named || rest.length > 0 ? [] : matching(await projectNames(), cur);
+    }
+    if (verb !== 'run' || rest.some((w) => w.startsWith('/'))) {
+        // Past the prompt's name, what follows is files and words.
+        return [];
+    }
+    const given = flagged ?? named ?? rest[0];
+    if (given === undefined) {
+        const here = await Projects.current(cwd).catch(() => undefined);
+        return matching([...(await promptsOf(here)), ...(await projectNames())], cur);
+    }
+    const project = await findProject(given);
+    const fromRest = !flagged && !named;
+    const free = rest.length - (fromRest && project ? 1 : 0);
+    return free > 0 ? [] : matching(await promptsOf(project), cur);
+}
+// ---------------------------------------------------------------------------
 // zen meta prompts [project]
 //
 // A slash command is only discoverable inside an editor, where a menu drops
@@ -728,7 +894,7 @@ function count(text, flag) {
 }
 function asProvider(name) {
     const owner = assertOwner(name);
-    if (owner === 'exa') {
+    if (!isProvider(owner)) {
         throw usageError(`${name} is not a model provider`);
     }
     return owner;
@@ -898,8 +1064,15 @@ async function pickModel(ctx) {
     if (known.length === 0) {
         throw credentialError('no keys to choose from', 'add one: zen key add openai');
     }
-    const suggestions = [...new Set(known)].flatMap((p) => (RECOMMENDED[p] ?? []).map((id) => `${p}/${id}`));
-    note(dim(bold('Models zen knows how to wire, for providers you hold a key for')));
-    return await choose('Which model?', suggestions.map((ref) => ({ label: ref, value: ref })));
+    const held = [...new Set(known)];
+    const { browseModels } = await import("./models.js");
+    const chosen = await browseModels({
+        initial: held.length === 1 ? held[0] : undefined,
+        role: 'chat',
+    });
+    if (!chosen) {
+        throw usageError('nothing picked', 'name the model instead: zen meta model <provider>/<id>');
+    }
+    return `${chosen.provider}/${chosen.id}`;
 }
 //# sourceMappingURL=meta.js.map

package/dist/commands/models.d.ts

@@ -1,3 +1,15 @@
+import { type CatalogEntry, type Role } from '../catalog.ts';
 import type { Command } from '../command.ts';
+import { type Provider } from '../keys.ts';
+export interface BrowseRequest {
+    /** opens straight into this provider's listing */
+    initial?: Provider;
+    /** the role filter each listing opens on; tab still cycles */
+    role?: Role;
+    refresh?: boolean;
+    theme?: string;
+}
+/** The browser, for any command that wants a person to pick a model. */
+export declare function browseModels(request?: BrowseRequest): Promise<CatalogEntry | undefined>;
 export declare const models: Command;
 //# sourceMappingURL=models.d.ts.map