@zenera/cli 1.1.10 → 1.1.12

package/dist/projects.js

@@ -1,5 +1,5 @@
-import { ASSETS_MOUNT, assetsDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { paths, readJson, writeJson } from "./home.js";
 import { isStamp } from "./ids.js";
@@ -47,6 +47,14 @@ export function projectMounts(root, config) {
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
         mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
     }
+    const memory = memoryDir(root, config);
+    if (memory) {
+        // Created here because the mount is decided before the project is
+        // loaded, and podman would refuse a source that does not exist yet.
+        const files = join(memory, FILES_DIR);
+        mkdirSync(files, { recursive: true });
+        mounts.push({ host: realpathSync(files), at: MEMORY_MOUNT, readOnly: true });
+    }
     return mounts;
 }
 // ---------------------------------------------------------------------------

package/dist/resolve.d.ts

@@ -13,6 +13,10 @@ export interface Target {
     session: SessionPaths;
     /** true when this call created the session */
     created: boolean;
+    /** absolute path the agent's file tools are rooted at */
+    workspace: string;
+    /** true when that directory is the session's own, made by this call */
+    freshWorkspace: boolean;
 }
 export declare function project(want: Wanted): Promise<Projects.Project>;
 export declare function target(want: Wanted): Promise<Target>;

package/dist/resolve.js

@@ -2,8 +2,8 @@ import { existsSync } from 'node:fs';
 import { relative, resolve, sep } from 'node:path';
 import { stamp } from "./ids.js";
 import * as Projects from "./projects.js";
-import { createSession, listSessions, requireSession, sessionPaths, } from "./session.js";
-import { ago, choose, confirm, dim, isInteractive, usageError, warn, yellow } from "./term.js";
+import { createSession, listSessions, readSessionMeta, requireSession, sessionPaths, } from "./session.js";
+import { ago, bold, choose, confirm, cyan, dim, isInteractive, usageError, warn, yellow, } from "./term.js";
 // ---------------------------------------------------------------------------
 // Project
 // ---------------------------------------------------------------------------
@@ -36,44 +36,70 @@ export async function target(want) {
         throw usageError('--session and --new contradict each other');
     }
     if (want.session) {
-        return {
-            project: found,
-            session: requireSession(dir, want.session),
-            created: false,
-        };
+        return await resumed(found, requireSession(dir, want.session));
     }
     if (!want.fresh) {
         const existing = await pickExisting(dir);
         if (existing) {
-            return { project: found, session: existing, created: false };
+            return await resumed(found, existing);
         }
     }
-    return { project: found, session: await create(dir, want), created: true };
+    const made = await create(dir, want);
+    return {
+        project: found,
+        session: made.session,
+        created: true,
+        workspace: made.workspace,
+        freshWorkspace: contains(made.session.dir, made.workspace),
+    };
 }
+/** A session that already exists brings its own workspace; it is never re-asked. */
+async function resumed(project, session) {
+    const meta = await readSessionMeta(session);
+    return {
+        project,
+        session,
+        created: false,
+        workspace: resolve(meta.workspace),
+        freshWorkspace: false,
+    };
+}
+/**
+ * Past this many, you are looking for a session by name rather than scrolling
+ * to it — and `--session <id>` is how you say a name.
+ */
+const MAX_SESSIONS = 25;
 /**
- * Resuming is the default: the common case is continuing what you were doing.
- * With one session it is taken without asking; with several, the others are
- * offered, because "the most recent" is only usually what you meant.
+ * Starting fresh is first, and it is the default: `zen run` followed by Enter
+ * should be a new conversation in a new directory, because that is what the
+ * command is asked for most often and the only answer that cannot go wrong.
+ * Everything already here is offered under it, newest first.
  *
  * A session that has never run has nothing to continue — it is indistinguishable
  * from a fresh one, so it is left out rather than offered as a choice.
  */
 async function pickExisting(projectDir) {
-    const sessions = (await listSessions(projectDir)).filter((s) => s.runs > 0 || s.busy);
-    if (sessions.length === 0) {
+    const all = (await listSessions(projectDir)).filter((s) => s.runs > 0 || s.busy);
+    if (all.length === 0) {
         return undefined;
     }
     if (!isInteractive()) {
-        return sessionPaths(projectDir, sessions[0].id);
+        return sessionPaths(projectDir, all[0].id);
     }
+    const sessions = all.slice(0, MAX_SESSIONS);
     const choice = await choose('Session', [
+        {
+            key: '0',
+            label: bold(cyan('New session…')),
+            detail: dim('a fresh conversation, in a directory of its own'),
+            value: undefined,
+        },
         ...sessions.map((s) => ({
             label: s.title ?? s.id,
             detail: `${s.id}  ${ago(s.lastRunAt ?? s.createdAt)}  ` +
                 `${s.runs} run${s.runs === 1 ? '' : 's'}${s.busy ? yellow('  running') : ''}`,
             value: s.id,
         })),
-        { key: '0', label: dim('New session…'), value: undefined },
     ]);
     return choice ? sessionPaths(projectDir, choice) : undefined;
 }
@@ -86,7 +112,7 @@ async function create(projectDir, want) {
     const id = stamp();
     const planned = sessionPaths(projectDir, id);
     const workspace = await chooseWorkspace(planned, want);
-    return createSession(projectDir, id, workspace);
+    return { session: createSession(projectDir, id, workspace), workspace };
 }
 // ---------------------------------------------------------------------------
 // Workspace

package/dist/scaffold.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
@@ -22,6 +22,12 @@ import { fileURLToPath } from 'node:url';
 // What is there is deliberately close to empty: a template full of
 // commented-out options is a template nobody reads and everybody deletes. The
 // one agent works as written, and every other knob is in `docs/`.
+//
+// `SPECIFICATION.md` is the exception, and is written out in full. It states
+// what the project that was just scaffolded is for and what it may do, and it
+// is *true as written* — so the first thing anyone sees is a specification
+// standing next to the files that implement it, which is the shape every
+// change to the project is then made in.
 // ---------------------------------------------------------------------------
 const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
@@ -42,6 +48,11 @@ function ownVersion() {
  * it — which is how an optional block leaves nothing behind. Anywhere else it
  * takes a word. A name nothing supplies throws, so a typo in a template is a
  * failing test rather than a `{{provider}}` sitting in somebody's agents.yaml.
+ *
+ * Only the value is trimmed at the end, never the start, so a fragment that has
+ * to be a paragraph of its own carries its own blank line as its first line.
+ * That way the template needs no blank line around the placeholder, and dropping
+ * the fragment leaves the surrounding paragraphs exactly as they were.
  */
 function render(text, vars) {
     const value = (name) => {
@@ -123,6 +134,10 @@ function copyTree(from, dir, rel, opts) {
             ? render(readFileSync(source, 'utf8'), opts.vars ?? {})
             : readFileSync(source);
         writeFileSync(join(dir, child), body);
+        // The bytes are copied, not the file, so a script arrives unrunnable.
+        if (child.endsWith('.sh')) {
+            chmodSync(join(dir, child), 0o755);
+        }
         written.push(child);
     }
     return written;
@@ -176,7 +191,13 @@ export function scaffold(opts) {
         keep: true,
         vars: {
             model: modelSection(opts.model, opts.modelOptions),
+            modelRef: opts.model,
             exa: opts.web ? part('exa.yaml') : '',
+            // The same capability stated three times, because the grant, the
+            // specification of it and the instruction to use it are read by
+            // different readers — and a tool nothing says to use is not one.
+            web: opts.web ? part('exa.spec.md') : '',
+            webPrompt: opts.web ? part('exa.prompt.md') : '',
             version: ownVersion(),
         },
     });

package/dist/term.d.ts

@@ -62,8 +62,29 @@ export interface Choice<T> {
     /** Listed and picked by this instead of its position, e.g. `0` for an escape hatch. */
     key?: string;
 }
-/** A numbered list. The pretty picker is the TUI's; this is the fallback. */
-export declare function choose<T>(title: string, choices: readonly Choice<T>[]): Promise<T>;
+export interface ChooseOptions {
+    /**
+     * The choice Enter takes, as an index. It is marked `*`, because a default
+     * nobody can see is a default nobody uses.
+     */
+    initial?: number;
+    /** How many rows stay on screen at once; anything beyond them scrolls. */
+    window?: number;
+}
+/**
+ * A list, arrow-driven where the terminal allows it and numbered where it does
+ * not. Both forms agree on the two things that matter: every row has a stable
+ * number you can type, and one of them is the default Enter takes.
+ */
+export declare function choose<T>(title: string, choices: readonly Choice<T>[], options?: ChooseOptions): Promise<T>;
+/** A chunk of raw input, split into one string per keystroke. */
+export declare function keysIn(data: string): Generator<string>;
+/**
+ * Cut to a visible width, carrying the style codes over. Styling is invisible
+ * to the terminal's column count but not to `String.length`, so a naive slice
+ * either cuts too early or leaves a colour turned on.
+ */
+export declare function cut(s: string, max: number): string;
 /** Piped input, or undefined when stdin is a terminal (i.e. nobody piped). */
 export declare function readStdin(): Promise<string | undefined>;
 export declare function ago(iso: string | undefined): string;

package/dist/term.js

@@ -173,8 +173,14 @@ export async function confirm(question, fallback = false) {
     }
     return /^y(es)?$/i.test(answer);
 }
-/** A numbered list. The pretty picker is the TUI's; this is the fallback. */
-export async function choose(title, choices) {
+/** Rows kept on screen when the caller does not say. */
+const WINDOW = 10;
+/**
+ * A list, arrow-driven where the terminal allows it and numbered where it does
+ * not. Both forms agree on the two things that matter: every row has a stable
+ * number you can type, and one of them is the default Enter takes.
+ */
+export async function choose(title, choices, options = {}) {
     if (choices.length === 0) {
         throw usageError(`nothing to choose from: ${title}`);
     }
@@ -182,20 +188,43 @@ export async function choose(title, choices) {
         return choices[0].value;
     }
     requireTty(title, 'the matching flag');
-    note(bold(title));
+    const initial = Math.min(Math.max(options.initial ?? 0, 0), choices.length - 1);
     // A keyed choice is out of the sequence, so it does not consume a number.
     let seq = 0;
     const keys = choices.map((c) => c.key ?? String(++seq));
-    const rows = choices.map((c, i) => [`  ${dim(`${keys[i]}.`)}`, c.label, dim(c.detail ?? '')]);
-    for (const line of table(rows)) {
-        note(line);
+    // A terminal that cannot move its own cursor gets the list printed once and
+    // answers with a number; anything else gets the arrows.
+    const dumb = typeof process.stdin.setRawMode !== 'function' ||
+        (process.env['TERM'] ?? 'dumb') === 'dumb';
+    if (dumb) {
+        return await numbered(title, choices, keys, initial);
+    }
+    return await pick(title, choices, keys, initial, options.window ?? WINDOW);
+}
+/** The rows themselves, column-aligned once and then reused every frame. */
+function listOf(choices, keys, initial) {
+    // A key that is not where counting would have put it is the one thing on
+    // the row you have to be told, so it is the one that takes a colour.
+    return table(choices.map((c, i) => [
+        `${i === initial ? cyan('*') : ' '} ` +
+            (c.key === undefined ? dim(`${keys[i]}.`) : cyan(`${keys[i]}.`)),
+        c.label,
+        dim(c.detail ?? ''),
+    ]));
+}
+/** The fallback: print everything, read a number. No raw mode, no repainting. */
+async function numbered(title, choices, keys, initial) {
+    note(bold(title));
+    for (const line of listOf(choices, keys, initial)) {
+        note(`  ${line}`);
     }
     const extra = keys.filter((_, i) => choices[i].key !== undefined);
-    const hint = `Enter a number between 1 and ${seq}` +
+    const counted = keys.length - extra.length;
+    const hint = `Enter a number between 1 and ${counted}` +
         (extra.length ? `, or ${extra.join(' / ')}` : '') +
         '.';
     for (;;) {
-        const answer = await ask('Choose', '1');
+        const answer = await ask('Choose', keys[initial]);
         const at = keys.indexOf(answer);
         if (at >= 0) {
             return choices[at].value;
@@ -203,6 +232,184 @@ export async function choose(title, choices) {
         note(dim(hint));
     }
 }
+/**
+ * The arrow-driven form. A long list is shown through a window rather than all
+ * at once: twenty-five sessions printed in full push the question itself off
+ * the screen, and the question is the part being answered.
+ *
+ * The frame is a fixed number of lines so it can be erased by counting them
+ * back, which is also why every line is cut to the terminal's width — a row
+ * that wraps is two rows the erase does not know about. When it is over the
+ * whole frame is replaced by the one line saying what was chosen.
+ */
+async function pick(title, choices, keys, initial, window) {
+    const out = process.stderr;
+    const stdin = process.stdin;
+    const rows = listOf(choices, keys, initial);
+    const shown = Math.max(1, Math.min(window, choices.length, (out.rows ?? 24) - 3));
+    const height = shown + 2;
+    let at = initial;
+    let top = Math.min(Math.max(0, at - shown + 1), Math.max(0, choices.length - shown));
+    let typed = '';
+    let painted = false;
+    let done = false;
+    const columns = Math.max(20, (out.columns ?? 80) - 1);
+    const paint = () => {
+        if (painted) {
+            out.write(`\u001b[${height}A`);
+        }
+        const lines = [bold(title)];
+        for (let i = top; i < top + shown; i++) {
+            lines.push(`${i === at ? cyan('\u276f') : ' '} ${rows[i]}`);
+        }
+        lines.push(dim('  \u2191\u2193 move \u00b7 enter choose \u00b7 esc cancel' +
+            (typed ? ` \u00b7 ${typed}` : '') +
+            (choices.length > shown ? `   ${at + 1}/${choices.length}` : '')));
+        for (const line of lines) {
+            out.write(`\u001b[2K${cut(line, columns)}\n`);
+        }
+        painted = true;
+    };
+    const goto = (i) => {
+        at = Math.min(Math.max(i, 0), choices.length - 1);
+        top = Math.min(Math.max(top, at - shown + 1), at);
+        paint();
+    };
+    const move = (delta) => {
+        typed = '';
+        goto(at + delta);
+    };
+    return await new Promise((settle, reject) => {
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        out.write('\u001b[?25l');
+        const close = (summary) => {
+            stdin.off('data', onData);
+            stdin.setRawMode(Boolean(wasRaw));
+            if (!wasRaw) {
+                stdin.pause();
+            }
+            // The list has served its purpose; the answer has not.
+            out.write(`\u001b[${height}A\u001b[0J\u001b[?25h`);
+            out.write(`${cut(`${bold(title)} ${cyan('\u276f')} ${summary}`, columns)}\n`);
+        };
+        const jump = (digit) => {
+            const next = typed + digit;
+            const to = keys.indexOf(next);
+            typed = to >= 0 ? next : digit;
+            const found = to >= 0 ? to : keys.indexOf(digit);
+            goto(found >= 0 ? found : at);
+        };
+        const onData = (data) => {
+            // One read can carry several keystrokes — held keys, a paste, or a
+            // fast typist — so it is split into keys before any of it is acted
+            // on. Reading the chunk as one key loses everything after the first.
+            for (const key of keysIn(data)) {
+                if (done) {
+                    return;
+                }
+                act(key);
+            }
+        };
+        const act = (key) => {
+            switch (key) {
+                case '\r':
+                case '\n': {
+                    const picked = choices[at];
+                    done = true;
+                    close(picked.detail ? `${picked.label} ${dim(picked.detail)}` : picked.label);
+                    settle(picked.value);
+                    return;
+                }
+                case '\u0003':
+                case '\u001b':
+                case 'q':
+                    done = true;
+                    close(dim('cancelled'));
+                    reject(usageError('cancelled'));
+                    return;
+                case '\u001b[A':
+                case '\u001bOA':
+                case 'k':
+                    return move(-1);
+                case '\u001b[B':
+                case '\u001bOB':
+                case 'j':
+                    return move(1);
+                case '\u001b[5~':
+                    return move(-shown);
+                case '\u001b[6~':
+                    return move(shown);
+                case '\u001b[H':
+                case '\u001b[1~':
+                    return move(-choices.length);
+                case '\u001b[F':
+                case '\u001b[4~':
+                    return move(choices.length);
+                case '\u007f':
+                case '\u0008':
+                    typed = '';
+                    return paint();
+                default:
+                    // Typing digits is how a two-digit row is reached without
+                    // twelve keystrokes, so they accumulate until one matches.
+                    if (key >= '0' && key <= '9') {
+                        jump(key);
+                    }
+            }
+        };
+        stdin.on('data', onData);
+        paint();
+    });
+}
+/** Escape sequences a keyboard sends: CSI (`ESC [ … final`) and SS3 (`ESC O x`). */
+const SEQUENCE = /^\u001b(?:\[[0-9;]*[A-Za-z~]|O[A-Za-z])/;
+/** A chunk of raw input, split into one string per keystroke. */
+export function* keysIn(data) {
+    let i = 0;
+    while (i < data.length) {
+        if (data[i] === '\u001b') {
+            const found = SEQUENCE.exec(data.slice(i));
+            if (found) {
+                yield found[0];
+                i += found[0].length;
+                continue;
+            }
+        }
+        yield data[i++];
+    }
+}
+/**
+ * Cut to a visible width, carrying the style codes over. Styling is invisible
+ * to the terminal's column count but not to `String.length`, so a naive slice
+ * either cuts too early or leaves a colour turned on.
+ */
+export function cut(s, max) {
+    if (width(s).length <= max) {
+        return s;
+    }
+    let out = '';
+    let seen = 0;
+    for (let i = 0; i < s.length;) {
+        if (s[i] === '\u001b') {
+            const end = s.indexOf('m', i);
+            if (end < 0) {
+                break;
+            }
+            out += s.slice(i, end + 1);
+            i = end + 1;
+            continue;
+        }
+        if (seen === max - 1) {
+            break;
+        }
+        out += s[i++];
+        seen++;
+    }
+    return `${out}\u2026\u001b[0m`;
+}
 // ---------------------------------------------------------------------------
 // stdin
 // ---------------------------------------------------------------------------

package/dist/tui/app.d.ts

@@ -3,6 +3,16 @@ export interface AppOptions {
     readOnly: boolean;
     /** `dark`, `light` or `auto`. Unset means `auto`. */
     theme?: string;
+    /**
+     * How this session was arrived at. The two questions before the first
+     * frame can be answered with two keystrokes, so the header repeats which
+     * way they went — a run that resumed when you meant to start over should
+     * say so before the first turn, not after it.
+     */
+    started?: {
+        created: boolean;
+        freshWorkspace: boolean;
+    };
 }
 export declare function start(engine: Engine.Engine, options: AppOptions): Promise<void>;
 //# sourceMappingURL=app.d.ts.map