@zenera/cli 1.1.0

package/dist/commands/models.js

@@ -0,0 +1,120 @@
+import { loadProject, readProjectConfig } from '@zenera/neo';
+import { parse } from "../args.js";
+import { KeyStore, PROVIDERS, SHAPES } 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";
+const USAGE = 'zen models [--project <name|dir>]';
+/**
+ * Everything a run would resolve, resolved — and nothing called. Loading a
+ * project constructs the model clients, so a config that names an impossible
+ * provider or an agent that hands off to nobody fails here, in a command that
+ * costs nothing, instead of three seconds into a run that costs money.
+ */
+export const models = {
+    summary: 'Resolve providers and models and validate the config, calling nothing.',
+    usage: USAGE,
+    run: async (ctx) => {
+        const { values } = parse(ctx.args, { project: { type: 'string' } }, USAGE);
+        const found = await resolveProject({ cwd: ctx.cwd, project: values.project });
+        const dir = found.dir;
+        const store = await KeyStore.open();
+        // 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]));
+        store.materialize();
+        let project;
+        try {
+            // The same tools a run would register. Without them every
+            // `workspace:*` or `sandbox:*` selector in the config resolves
+            // against an empty list and the project fails to load with
+            // "no tools in group" — a report about this command, not about
+            // the project.
+            const { config } = readProjectConfig(dir);
+            project = await loadProject(dir, { tools: availableTools(dir, config) });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Constructing a client needs a credential, so a keyless machine
+            // cannot get far enough to validate anything. Saying "invalid
+            // project" there would be a lie about whose fault it is.
+            if (!fromEnv.size && !PROVIDERS.some((p) => store.active(p))) {
+                throw credentialError(message, 'add a key: zen key add openai');
+            }
+            throw invalidError(message, dir);
+        }
+        const agents = project.agents.map((a) => ({
+            name: a.name,
+            entry: a.name === project.entry,
+            model: a.model?.id ?? project.config.model ?? null,
+            tools: a.tools.map((t) => t.name),
+            handoffs: a.handoffs,
+        }));
+        // Resolved through the registry, which proves the ref parses and the
+        // provider exists without any call being made.
+        const embeddings = Object.keys(project.config.embeddings ?? {})
+            .concat(project.config.embedding && !project.config.embeddings?.[project.config.embedding]
+            ? [project.config.embedding]
+            : [])
+            .map((name) => ({
+            name,
+            model: project.embedder(name)?.id ?? null,
+            default: name === project.config.embedding,
+        }));
+        const credentials = PROVIDERS.map((p) => ({
+            provider: p,
+            env: SHAPES[p].env,
+            source: fromEnv.has(p)
+                ? 'environment'
+                : store.active(p)
+                    ? 'keyring'
+                    : 'missing',
+        }));
+        if (ctx.json) {
+            json({
+                project: found.name,
+                source: project.source,
+                providers: project.models.names(),
+                agents,
+                embeddings,
+                credentials,
+            });
+            return;
+        }
+        note(`${bold(found.name)} ${dim(project.source)}`);
+        note('');
+        note(bold('Agents'));
+        writeAll(table(agents.map((a) => [
+            `  ${a.entry ? green('→') : ' '} ${a.name}`,
+            cyan(a.model ?? dim('inherited')),
+            dim(a.tools.length ? a.tools.join(' ') : 'no tools'),
+            dim(a.handoffs.length ? `→ ${a.handoffs.join(', ')}` : ''),
+        ])));
+        if (embeddings.length) {
+            note('');
+            note(bold('Embeddings'));
+            writeAll(table(embeddings.map((e) => [
+                `  ${e.default ? green('→') : ' '} ${e.name}`,
+                cyan(e.model ?? dim('unresolved')),
+            ])));
+        }
+        note('');
+        note(bold('Credentials'));
+        writeAll(table(credentials.map((c) => [
+            `  ${c.provider}`,
+            dim(c.env),
+            c.source === 'missing' ? red('missing') : green(c.source),
+        ])));
+        const declared = project.models.names();
+        if (declared.length) {
+            note('');
+            note(`${bold('Providers')} ${dim(declared.join(', '))}`);
+        }
+        if (credentials.every((c) => c.source === 'missing')) {
+            note('');
+            note(yellow('nothing can be reached — add a key: zen key add openai'));
+        }
+    },
+};
+//# sourceMappingURL=models.js.map

package/dist/commands/open.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../command.ts';
+/**
+ * A project is resolved by name or from the cwd, and the path is handed to an
+ * editor. It exists because opening the project is the thing everybody does
+ * second, and because getting the editor right — which one, with which
+ * arguments, attached or detached — is fiddly enough to be worth settling once.
+ */
+export declare const open: Command;
+//# sourceMappingURL=open.d.ts.map

package/dist/commands/open.js

@@ -0,0 +1,270 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
+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 { CliError, cyan, dim, EXIT, json, note, usageError } from "../term.js";
+const USAGE = 'zen open [project] [--editor <cmd>] [--wait]';
+/**
+ * A project is resolved by name or from the cwd, and the path is handed to an
+ * editor. It exists because opening the project is the thing everybody does
+ * second, and because getting the editor right — which one, with which
+ * arguments, attached or detached — is fiddly enough to be worth settling once.
+ */
+export const open = {
+    summary: 'Open a project in your editor.',
+    usage: USAGE,
+    details: [
+        'Editor: --editor, then $ZENERA_EDITOR, then the editor this terminal',
+        'belongs to, then $VISUAL or $EDITOR, then a known editor on PATH or',
+        'installed, then the platform opener.',
+        'The editor files `zen init` writes (.vscode/settings.json and the',
+        '.github/ tree) are refreshed in the directory being opened; edits to',
+        'them do not survive.',
+        'VS Code and its forks are launched with --disable-workspace-trust so',
+        'the settings written there apply to the window straight away.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            editor: { type: 'string' },
+            wait: { type: 'boolean' },
+        }, USAGE);
+        const found = await resolveProject({
+            cwd: ctx.cwd,
+            project: one(positionals, 'project', USAGE),
+        });
+        const dir = found.dir;
+        const editor = choose(values.editor, values.wait === true);
+        verify(editor);
+        // The editor reads the settings and instructions of the folder it was
+        // 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)];
+        if (ctx.json) {
+            json({
+                name: found.name,
+                path: dir,
+                editor: [editor.command, ...editor.args].join(' '),
+                from: editor.from,
+                files: written,
+            });
+        }
+        else {
+            note(`opening ${cyan(dir)} with ${editor.label} ${dim(`(${editor.from})`)}`);
+            for (const file of written) {
+                note(`  ${dim(`wrote ${file}`)}`);
+            }
+        }
+        await launch(editor, dir);
+    },
+};
+// ---------------------------------------------------------------------------
+// Choosing one
+// ---------------------------------------------------------------------------
+/**
+ * The window would otherwise open untrusted, and the settings `zen init`
+ * writes into the project are restricted ones: they are ignored until someone
+ * clicks through the trust dialog. This is a directory the user just asked to
+ * open by name, so answering that question for them is the point.
+ */
+const TRUST = '--disable-workspace-trust';
+/** Guessed only when nothing was asked for, in the order they are tried. */
+const KNOWN = [
+    { command: 'code', label: 'VS Code', app: 'Visual Studio Code', trusts: true },
+    { command: 'cursor', label: 'Cursor', app: 'Cursor', trusts: true },
+    {
+        command: 'code-insiders',
+        label: 'VS Code Insiders',
+        app: 'Visual Studio Code - Insiders',
+        trusts: true,
+    },
+    { command: 'windsurf', label: 'Windsurf', app: 'Windsurf', trusts: true },
+    { command: 'zed', label: 'Zed', app: 'Zed', waits: '-w' },
+    { command: 'subl', label: 'Sublime Text', app: 'Sublime Text', waits: '-w' },
+    { command: 'idea', label: 'IntelliJ IDEA', app: 'IntelliJ IDEA' },
+];
+function choose(asked, wait) {
+    const explicit = asked ?? process.env.ZENERA_EDITOR;
+    if (explicit !== undefined && explicit.trim() !== '') {
+        return {
+            ...split(explicit),
+            from: asked !== undefined ? '--editor' : '$ZENERA_EDITOR',
+            attached: wait,
+        };
+    }
+    // Before $EDITOR, deliberately. $EDITOR conventionally names something to
+    // edit *a file* with — it is very often `vim`, set once years ago — and
+    // this command opens a directory as a project. The editor you are already
+    // sitting in is the better answer to that, and $ZENERA_EDITOR above is the
+    // way to say otherwise.
+    const host = hosting(wait);
+    if (host !== undefined)
+        return host;
+    // $VISUAL and $EDITOR are, by convention, editors that run *in* the
+    // terminal, so they are attached and waited for unless proven otherwise.
+    for (const name of ['VISUAL', 'EDITOR']) {
+        const value = process.env[name];
+        if (value !== undefined && value.trim() !== '') {
+            return { ...split(value), from: `$${name}`, attached: true };
+        }
+    }
+    for (const known of KNOWN) {
+        if (lookup(known.command) !== undefined) {
+            return {
+                command: known.command,
+                args: [
+                    ...(known.trusts === true ? [TRUST] : []),
+                    ...(wait ? [known.waits ?? '--wait'] : []),
+                ],
+                label: known.label,
+                from: 'PATH',
+                attached: wait,
+            };
+        }
+    }
+    // Installed but never asked to add itself to PATH — which is the default
+    // for VS Code on macOS, and so the case this whole branch exists for.
+    // LaunchServices can open it without any of that.
+    for (const known of KNOWN) {
+        const bundle = known.app === undefined ? undefined : installed(known.app);
+        if (bundle !== undefined) {
+            return {
+                command: 'open',
+                args: wait ? ['-W', '-a', bundle] : ['-a', bundle],
+                label: known.label,
+                from: 'Applications',
+                attached: wait,
+            };
+        }
+    }
+    // Nothing named an editor, so hand the directory to the desktop and let it
+    // decide. On macOS that is Finder unless a folder handler is registered.
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'explorer'
+            : 'xdg-open';
+    return { command, args: [], label: command, from: 'system', attached: false };
+}
+/**
+ * The editor whose integrated terminal this is. VS Code and every fork of it
+ * export `VSCODE_GIT_ASKPASS_MAIN`, which points inside the running
+ * installation, so the app root is four directories up from it and
+ * `product.json` there names both the CLI and the product. That is exact where
+ * guessing is not: it picks Cursor when you are in Cursor, and it works when
+ * the shell command was never installed, which on macOS is the default.
+ */
+function hosting(wait) {
+    const askpass = process.env.VSCODE_GIT_ASKPASS_MAIN;
+    if (process.env.TERM_PROGRAM !== 'vscode' || askpass === undefined)
+        return undefined;
+    // <appRoot>/extensions/git/dist/askpass-main.js
+    const appRoot = resolve(askpass, '..', '..', '..', '..');
+    let product;
+    try {
+        product = JSON.parse(readFileSync(join(appRoot, 'product.json'), 'utf8'));
+    }
+    catch {
+        return undefined; // not a layout we recognise; fall through to the guesses
+    }
+    if (product.applicationName === undefined)
+        return undefined;
+    const cli = join(appRoot, 'bin', product.applicationName);
+    for (const candidate of [cli, `${cli}.cmd`]) {
+        if (!existsSync(candidate))
+            continue;
+        return {
+            command: candidate,
+            args: wait ? [TRUST, '--wait'] : [TRUST],
+            label: product.nameLong ?? product.applicationName,
+            from: 'this terminal',
+            attached: wait,
+        };
+    }
+    return undefined;
+}
+/** The macOS bundle for an application name, in either place they live. */
+function installed(app) {
+    if (process.platform !== 'darwin')
+        return undefined;
+    for (const dir of ['/Applications', join(homedir(), 'Applications')]) {
+        const bundle = join(dir, `${app}.app`);
+        if (existsSync(bundle))
+            return bundle;
+    }
+    return undefined;
+}
+/**
+ * `$EDITOR` may carry arguments — `code -n`, `emacsclient -c`. Splitting on
+ * whitespace rather than handing the string to a shell: the path is always an
+ * argument, so nothing in it is ever interpreted.
+ */
+function split(value) {
+    const parts = value.trim().split(/\s+/);
+    return { command: parts[0], args: parts.slice(1), label: parts[0] };
+}
+/**
+ * PATH lookup without shelling out to `which`, so the resolution failure can
+ * be reported before anything is spawned rather than as an ENOENT nobody sees
+ * on a detached child.
+ */
+function lookup(command) {
+    if (command.includes(sep) || command.includes('/')) {
+        return existsSync(command) ? command : undefined;
+    }
+    const extensions = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+        if (dir === '')
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(dir, command + extension);
+            try {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // not here, keep walking
+            }
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Running it
+// ---------------------------------------------------------------------------
+/**
+ * Both ways this can be wrong, settled before anything is spawned and before
+ * anything is said: an ENOENT on a detached child is a failure nobody would
+ * ever see, and a terminal editor with no terminal to take over would hang.
+ */
+function verify(editor) {
+    if (editor.from !== 'system' && lookup(editor.command) === undefined) {
+        throw usageError(`no such editor: ${editor.command}`, editor.from === 'PATH'
+            ? 'name one with --editor, or set $ZENERA_EDITOR'
+            : `${editor.from} names a command that is not on PATH`);
+    }
+    if ((editor.from === '$VISUAL' || editor.from === '$EDITOR') && !process.stdin.isTTY) {
+        throw usageError(`${editor.from} names a terminal editor and there is no terminal here`, 'name a windowed one with --editor, or set $ZENERA_EDITOR');
+    }
+}
+async function launch(editor, dir) {
+    const args = [...editor.args, dir];
+    if (!editor.attached) {
+        // Detached and unreferenced: the window outlives this process, which is
+        // the whole point of a GUI editor.
+        spawn(editor.command, args, { stdio: 'ignore', detached: true }).unref();
+        return;
+    }
+    const code = await new Promise((settle, reject) => {
+        const child = spawn(editor.command, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (status) => settle(status ?? 0));
+    });
+    if (code !== 0) {
+        throw new CliError(`${editor.label} exited with ${code}`, EXIT.failed);
+    }
+}
+//# sourceMappingURL=open.js.map

package/dist/commands/run.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const run: Command;
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/run.js

@@ -0,0 +1,167 @@
+import { writeFile } from 'node:fs/promises';
+import { parse } from "../args.js";
+import * as Engine from "../engine.js";
+import { duration, Narrator, stopMark, summary } from "../narrate.js";
+import * as Projects from "../projects.js";
+import { target } from "../resolve.js";
+import { display } from "../session.js";
+import { bold, cyan, dim, json, note, readStdin, usageError, write } from "../term.js";
+import { parseChoice } from "../tui/theme.js";
+const USAGE = 'zen run [project] [prompt] [options]';
+export const run = {
+    summary: 'Run the project — the TUI on a terminal, one shot otherwise.',
+    usage: USAGE,
+    details: [
+        '  --project <name|dir>   Which project. Inferred from the directory.',
+        '  --session <id>         Continue a particular session.',
+        '  --new                  Start a fresh one.',
+        '  --workspace <dir>      What the agent can read and write.',
+        '  --model <ref>          Override the default model.',
+        '  --image <ref>          Override the sandbox image commands run in.',
+        '  --read-only            Give the agent no way to write.',
+        '  --quiet                Answer only; no narration.',
+        '  --plain                One shot, even on a terminal.',
+        '  --theme <dark|light>   Force the palette. Detected otherwise; $ZENERA_THEME.',
+        '  --out <file>           Write the answer here as well as to stdout.',
+        '  --yes                  Accept the questions this would otherwise ask.',
+        '',
+        'The first word is the project when it names one, as in `zen run acme`,',
+        'and the first word of the prompt when it does not. --project settles it.',
+        '',
+        'The prompt comes from the argument, or stdin, or the TUI. There is no',
+        '`resume`: a session continues itself, because its state is what it is.',
+        '',
+        'With a prompt on the command line nothing is asked: a fresh session, the',
+        'directory you are in as the workspace, writable. --session, --workspace',
+        'and --read-only override that; the TUI still asks.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            project: { type: 'string' },
+            session: { type: 'string' },
+            new: { type: 'boolean' },
+            workspace: { type: 'string' },
+            model: { type: 'string' },
+            image: { type: 'string' },
+            'read-only': { type: 'boolean' },
+            yes: { type: 'boolean' },
+            quiet: { type: 'boolean' },
+            plain: { type: 'boolean' },
+            theme: { type: 'string' },
+            out: { type: 'string' },
+        }, USAGE);
+        const piped = await readStdin();
+        // `zen run acme` is what everyone types before finding --project, and a
+        // project name is a bare word where a prompt is a sentence. So the
+        // first positional is read as a project when it names one and as the
+        // first word of the prompt when it does not — which also makes
+        // `zen run acme "what changed?"` mean what it looks like. --project is
+        // there for the day a project is called "why".
+        const [head, ...rest] = positionals;
+        const named = !values.project && head ? await Projects.find(head) : undefined;
+        const prompt = (named ? rest : positionals).join(' ').trim() || piped;
+        if (values.theme !== undefined && !parseChoice(values.theme)) {
+            throw usageError(`unknown theme: ${values.theme}`, 'dark, light or auto');
+        }
+        // A prompt on the command line is a request for an answer, not a
+        // conversation to pick up. So it answers the three questions itself:
+        // a fresh session, the directory it was typed in as the workspace,
+        // and no confirmation for it — `zen run acme "what changed?"` should
+        // read the code that is right there. Every flag still wins, and the
+        // TUI, where there is someone to ask, still asks.
+        const shot = Boolean(prompt);
+        const where = await target({
+            cwd: ctx.cwd,
+            project: values.project ?? (named ? head : undefined),
+            session: values.session,
+            fresh: values.new || (shot && !values.session),
+            workspace: values.workspace ?? (shot ? ctx.cwd : undefined),
+            yes: values.yes || shot,
+        });
+        const engine = await Engine.open({
+            project: where.project,
+            session: where.session,
+            readOnly: values['read-only'],
+            model: values.model,
+            image: values.image,
+            yes: values.yes || ctx.json,
+        });
+        try {
+            // The TUI is for the case it is actually good at: a person at a
+            // terminal, with nothing to say yet. A prompt on the command line
+            // is a request for an answer, and drawing a full-screen interface
+            // over it would be worse than not drawing one.
+            const drawing = !prompt &&
+                !values.plain &&
+                !values.quiet &&
+                !ctx.json &&
+                Boolean(process.stdout.isTTY && process.stdin.isTTY);
+            if (drawing) {
+                const { start } = await import("../tui/app.js");
+                await start(engine, {
+                    readOnly: Boolean(values['read-only']),
+                    theme: values.theme,
+                });
+                return;
+            }
+            if (!prompt) {
+                throw usageError('nothing to ask', 'give a prompt, or pipe one in');
+            }
+            await once(engine, prompt, values, ctx.json, ctx.cwd);
+        }
+        finally {
+            await engine.close();
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// One shot
+// ---------------------------------------------------------------------------
+async function once(engine, prompt, values, asJson, cwd) {
+    const narrator = new Narrator({
+        quiet: Boolean(values.quiet) || asJson,
+        live: Boolean(process.stderr.isTTY),
+    });
+    // Ctrl-C asks the run to stop rather than killing the process, so the turn
+    // still lands on disk and the session stays resumable.
+    const stopping = new AbortController();
+    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)));
+    }
+    let outcome;
+    try {
+        outcome = await Engine.run(engine, prompt, narrator.handle, stopping.signal);
+    }
+    finally {
+        narrator.done();
+        process.off('SIGINT', onInterrupt);
+    }
+    if (values.out) {
+        await writeFile(values.out, `${outcome.text}\n`, 'utf8');
+    }
+    if (asJson) {
+        json({
+            session: engine.session.id,
+            run: outcome.run.id,
+            agent: outcome.result.agent,
+            stopReason: outcome.result.stopReason,
+            durationMs: outcome.durationMs,
+            usage: outcome.result.usage,
+            output: outcome.text,
+            report: outcome.run.report,
+        });
+        return;
+    }
+    write(outcome.text);
+    if (!values.quiet) {
+        note('');
+        note(`${stopMark(outcome.result.stopReason)} ${dim(duration(outcome.durationMs))}  ` +
+            dim(summary(outcome.result.usage)));
+        if (outcome.report) {
+            note(dim(`report: ${cyan(display(outcome.report, cwd))}`));
+        }
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/sandbox.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const sandbox: Command;
+//# sourceMappingURL=sandbox.d.ts.map