@zenera/cli 1.1.19 → 1.1.20

package/README.md

@@ -377,6 +377,12 @@ clones it types `zen init repo-notes` once - a directory that is already a
 project is registered, not rebuilt, and nothing in it is touched - and the name
 is a command on their machine too.
 
+When a newer `zen` is installed, `zen check --fix` brings a project's copies of
+_our_ files up to date: the memory and tool house rules under `agents/`, and the
+`.vscode/` and `.github/` trees. They restate how the version in hand behaves,
+so a copy left behind by an upgrade is worse than none. Nothing that describes
+_your_ project is touched.
+
 ## A project is a folder
 
 Prompts, agent wiring, skills and tool selections are all files - Markdown and

package/dist/banner.d.ts

@@ -4,6 +4,10 @@ declare const ACCENTS: {
         readonly face: "\u001B[1;38;5;208m";
         readonly shade: "\u001B[0;38;5;130m";
     };
+    readonly green: {
+        readonly face: "\u001B[1;38;5;41m";
+        readonly shade: "\u001B[0;38;5;29m";
+    };
     readonly cyan: {
         readonly face: "\u001B[1;38;5;51m";
         readonly shade: "\u001B[0;38;5;37m";
@@ -12,6 +16,10 @@ declare const ACCENTS: {
         readonly face: "\u001B[1;38;5;121m";
         readonly shade: "\u001B[0;38;5;78m";
     };
+    readonly gold: {
+        readonly face: "\u001B[1;38;5;220m";
+        readonly shade: "\u001B[0;38;5;178m";
+    };
 };
 export type Hue = keyof typeof ACCENTS;
 export interface BannerText {

package/dist/banner.js

@@ -72,8 +72,10 @@ const HEADS = {
 /** One per sub-brand, so two of them are told apart before the word is read. */
 const ACCENTS = {
     orange: { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' },
+    green: { face: '\u001b[1;38;5;41m', shade: '\u001b[0;38;5;29m' },
     cyan: { face: '\u001b[1;38;5;51m', shade: '\u001b[0;38;5;37m' },
     mint: { face: '\u001b[1;38;5;121m', shade: '\u001b[0;38;5;78m' },
+    gold: { face: '\u001b[1;38;5;220m', shade: '\u001b[0;38;5;178m' },
 };
 /** Runs of stroke and runs of bevel, alternating; spaces stay unstyled. */
 const RUNS = /[█▀▄]+|[^█▀▄ ]+/g;

package/dist/commands/cache.js

@@ -20,6 +20,7 @@ const LISTED = 20;
 export const cache = {
     summary: 'What work has been kept, and getting rid of it.',
     usage: USAGE,
+    banner: { head: 'Zenera', accent: 'Cache', subtitle: 'Stored Work', hue: 'gold' },
     details: [
         '  ls                     What is stored, by kind. Changes nothing.',
         '  prune                  Remove what the filters name.',

package/dist/commands/check.js

@@ -6,9 +6,10 @@ import { KeyStore } from "../keys.js";
 import { duration } from "../narrate.js";
 import { Registry } from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
+import { refreshShared } from "../scaffold.js";
 import { bold, count, cyan, dim, green, invalidError, json, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 import { validateProject, } from "../validate.js";
-const USAGE = 'zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]';
+const USAGE = 'zen check [name|dir] [--project <name|dir>] [--fix] [--no-sandbox] [--no-models] [--strict] [--quiet]';
 // ---------------------------------------------------------------------------
 // zen check
 //
@@ -52,6 +53,14 @@ export const check = {
         'Unlike a run, it does not stop at the first problem — the report lists',
         'everything it found, each with a code and the fix for it.',
         '',
+        '--fix rewrites the files that are ours rather than the project\u2019s: the',
+        'memory and tool house rules under agents/, and the editor tree',
+        '(.vscode/ and .github/). They restate how this version of zen behaves,',
+        'so a copy left behind by an upgrade is worse than none — they are',
+        'replaced whether or not they were edited, and the report that follows is',
+        'of the project as repaired. Nothing else is touched: agents.yaml, the',
+        'prompts, the specification and agents/instructions.md are yours.',
+        '',
         'The argument is a directory if one is there and a registered project',
         'name otherwise; with neither, the project you are standing in.',
         '',
@@ -61,6 +70,7 @@ export const check = {
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
+            fix: { type: 'boolean' },
             'no-sandbox': { type: 'boolean' },
             'no-models': { type: 'boolean' },
             strict: { type: 'boolean' },
@@ -74,6 +84,11 @@ export const check = {
         // read here and handed to the check rather than looked up inside it.
         const entry = (await Registry.open()).findPath(dir);
         const name = entry?.name ?? basename(dir);
+        // Before the report rather than after it, so what it says is true of
+        // the files that are there now and the exit code answers the repaired
+        // project. A fix that left an error behind in the output would be read
+        // as a fix that failed.
+        const fixed = values.fix ? refreshShared(dir) : [];
         // Materialised first, so the credential verdicts are the ones a run
         // would reach: a key in the environment and a key in the keyring are
         // the same key by the time the library asks. The project's own `.env`
@@ -99,13 +114,15 @@ export const check = {
         });
         bar.done();
         if (ctx.json) {
-            json(report);
+            json({ ...report, fixed });
         }
         else if (values.quiet) {
+            writeAll(fixedLines(fixed));
             writeAll(findingLines(report.findings));
             write(verdict(report, Boolean(values.strict)));
         }
         else {
+            writeAll(fixedLines(fixed));
             writeAll(render(report));
         }
         const failed = report.counts.errors > 0 || (Boolean(values.strict) && report.counts.warnings > 0);
@@ -303,6 +320,21 @@ function agentBlock(agent) {
     }
     return [head, ...table(rows)];
 }
+/**
+ * What `--fix` replaced, said before the report so the two read in the order
+ * they happened. Silent when nothing was asked for, so the only difference
+ * between `zen check` and `zen check --fix` on a healthy project is these lines.
+ */
+function fixedLines(fixed) {
+    if (fixed.length === 0) {
+        return [];
+    }
+    return [
+        `${bold('Replaced')} ${dim(`${count(fixed.length, 'file')} \u2014 ours, not the project's`)}`,
+        ...fixed.map((f) => `  ${green('wrote')} ${f}`),
+        '',
+    ];
+}
 /**
  * One finding, three lines at most: what and where, then why, then the fix.
  * The code is printed because it is the part a script — or a model asked to

package/dist/commands/index.js

@@ -59,7 +59,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: 'Corpus Retrieval' },
+        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Corpus Retrieval', hue: 'green' },
     },
 };
 //# sourceMappingURL=index.js.map

package/dist/commands/init.js

@@ -130,7 +130,7 @@ export const init = {
         'Writes SPECIFICATION.md, agents.yaml, agents/ (house rules, the memory',
         'rules and one role prompt) and scripts/, then records the directory so',
         '`zen list` and `zen open` can find it by name. Editor files',
-        '(.vscode/settings.json and the .github/ tree) are written alongside,',
+        '(.vscode/ and the .github/ tree) are written alongside,',
         'replacing any already there.',
         '',
         'A directory that is already a project is adopted rather than rebuilt:',

package/dist/commands/meta.js

@@ -56,7 +56,7 @@ export const meta = {
         'Nothing it needs is put on a command line: every credential reaches it',
         'through the environment, where other processes cannot read it.',
         '',
-        'The editor files `zen init` writes (.vscode/settings.json and the .github/',
+        'The editor files `zen init` writes (.vscode/ and the .github/',
         'tree) are refreshed in the project first, the way `zen open` refreshes',
         'them: the agent is about to read that brief, and it describes this version',
         'of zen. Edits to them do not survive.',

package/dist/commands/open.js

@@ -20,7 +20,7 @@ export const open = {
         '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',
+        'The editor files `zen init` writes (.vscode/ 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',

package/dist/main.js

@@ -6,7 +6,7 @@ import { NEO_BANNER, printBanner } from "./banner.js";
 import { ALIASES, COMMANDS, EXTERNAL } from "./commands/index.js";
 import { cliManifest, versionOf } from "./commands/version.js";
 import { hasExternal, loadExternal } from "./external.js";
-import { CliError, EXIT, bold, cyan, dim, fail, note, pad, write } from "./term.js";
+import { CliError, EXIT, bold, cyan, dim, fail, note, pad, title, write } from "./term.js";
 /** What the user typed: `zen`, `zn` or `zenera` all arrive here. */
 const NAME = invokedAs('zen');
 /** Usage lines are written against `zen`. Say them back in the reader's word. */
@@ -22,6 +22,8 @@ const spell = (usage) => (NAME === 'zen' ? usage : usage.replace(/^zen\b/, NAME)
 // inside `run`. Everything on this path is Node's own, which is why `zen --help`
 // starts instantly and why the CLI adds no weight to the library.
 // ---------------------------------------------------------------------------
+/** Commands whose name is not simply its first letter capitalised. */
+const TITLES = { rag: 'RAG' };
 const GLOBAL = {
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'v' },
@@ -54,6 +56,11 @@ async function main(argv) {
     const name = parts.name ? (ALIASES[parts.name] ?? parts.name) : undefined;
     const command = name ? COMMANDS[name] : undefined;
     const external = name && !command ? EXTERNAL[name] : undefined;
+    // Named before anything is printed, so a run that takes an hour is
+    // identifiable in `ps` and on its own tab for the whole of it.
+    if (name && (command || external)) {
+        title(`Zen ${TITLES[name] ?? name.replace(/^./, (c) => c.toUpperCase())}`);
+    }
     // Narration, so `--json` and every pipe are untouched by it. A command
     // living in another package brings its own brand, but only once it is
     // actually there — a banner over "not installed" is a claim about nothing.

package/dist/meta.js

@@ -6,7 +6,7 @@ import { invokedAs } from "./args.js";
 import { paths, readJson, writeJson } from "./home.js";
 import { envOf } from "./keys.js";
 import { credentialError, cut, cyan, dim, note, pad, plain, red, styled, usageError, write, yellow, } from "./term.js";
-import { answerWidth, segmentsOf, wrap } from "./tui/wrap.js";
+import { blocksOf, boxWidth, textOf, wrap } from "./tui/wrap.js";
 export const PROMPT_DIR = '.github/prompts';
 const PROMPT_SUFFIX = '.prompt.md';
 // ---------------------------------------------------------------------------
@@ -492,19 +492,31 @@ export function answerBox(text, columns = process.stdout.columns ?? 80) {
     if (!process.stdout.isTTY) {
         return text.split('\n');
     }
-    const outer = answerWidth(columns);
+    const outer = boxWidth(text, columns);
     const inner = outer - 4;
     const body = [];
-    for (const segment of segmentsOf(text)) {
-        if (segment.code) {
+    let previous;
+    for (const block of blocksOf(text)) {
+        if (previous && !(block.kind === 'item' && previous.kind === 'item')) {
+            body.push('');
+        }
+        previous = block;
+        if (block.kind === 'code') {
             // Indentation is the meaning of a fenced block, so it is cut rather
             // than reflowed.
-            body.push(dim(`\u250c\u2500${segment.title ? ` ${segment.title}` : ''}`));
-            body.push(...segment.lines.map((l) => `${dim('\u2502')} ${cut(l, inner - 2)}`));
+            body.push(dim(`\u250c\u2500${block.title ? ` ${block.title}` : ''}`));
+            body.push(...(block.lines ?? []).map((l) => `${dim('\u2502')} ${cut(l, inner - 2)}`));
             body.push(dim('\u2514\u2500'));
         }
+        else if (block.lines || block.kind === 'table') {
+            body.push(...textOf(block)
+                .split('\n')
+                .map((l) => cut(l, inner)));
+        }
         else {
-            body.push(...wrap(segment.lines.join('\n'), inner));
+            // Plain, not styled: `wrap` counts characters, and a bold run
+            // measured with its escape codes in it folds the line early.
+            body.push(...wrap(textOf(block, inner), inner));
         }
     }
     const rule = BOX.h.repeat(outer - 2);

package/dist/scaffold.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The project files that are ours rather than the project's.
+ *
+ * Everything else under `templates/project/` describes *this project* and is
+ * written once. These describe *this version of `zen`* — how the memory graph
+ * works, how its tools are called, what survives a join — and land under
+ * `agents/` only because that is where house rules have to be to reach a
+ * prompt. A copy that has fallen behind the runtime is worse than none, so
+ * `zen check --fix` replaces them, and nothing in them is worth editing in
+ * place: project policy on any of those subjects goes in a topic file of its
+ * own beside them.
+ */
+export declare const SHARED_RULES: readonly string[];
 /**
  * Writes the editor's files under `dir`, replacing what is there. They are
  * ours: they say how the editor is to treat a directory the agents write into,
@@ -6,6 +19,30 @@
  * none. Returns the relative paths written.
  */
 export declare function editorFiles(dir: string): string[];
+/**
+ * Replaces every file in a project that nobody is meant to be maintaining:
+ * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the
+ * relative paths written, project files first.
+ *
+ * This is the other half of `keep: true`. A scaffold never overwrites, which is
+ * right for the files a project goes on to make its own and wrong for the ones
+ * that only ever restate how this version of `zen` behaves — those a project
+ * upgrades into, and before this there was no way to get them except by hand.
+ */
+export declare function refreshShared(dir: string): string[];
+/**
+ * Which of a project's `SHARED_RULES` are not the bytes this `zen` ships.
+ *
+ * The comparison is the whole file rather than anything read out of it,
+ * because there is no reading that would have caught the copies that went
+ * stale in practice: prose describing a tool that was renamed, a section about
+ * behaviour that changed, frontmatter added after the copy was written. All of
+ * it parses, all of it loads, and all of it is wrong. A file that is not there
+ * is not stale — what must exist is checked where it is required, not here.
+ *
+ * Paths come back with forward slashes, the way a report names a file.
+ */
+export declare function staleShared(dir: string): string[];
 export interface ScaffoldOptions {
     /** the project directory */
     dir: string;

package/dist/scaffold.js

@@ -1,5 +1,5 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // Scaffolding
@@ -11,7 +11,7 @@ import { fileURLToPath } from 'node:url';
 //
 //   templates/project/   the project's own files. Written once and edited from
 //                        then on, so anything already there is left alone.
-//   templates/editor/    ours: `.vscode/settings.json` and the `.github/` tree,
+//   templates/editor/    ours: the `.vscode/` and `.github/` trees,
 //                        which describe this version of `zen` to the editor and
 //                        are replaced every time.
 //   templates/parts/     fragments spliced into a template above.
@@ -35,6 +35,23 @@ const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 const TEMPLATE = '.tmpl';
 /** How to use the memory graph: a house rules file, landing under `agents/`. */
 const MEMORY_RULES = join('agents', 'memory-instructions.md');
+/** How tools are called: the same, and equally not the project's to maintain. */
+const TOOL_RULES = join('agents', 'tools-instructions.md');
+/** How forking behaves: the same again, reaching only agents that declare `fork:`. */
+const FORK_RULES = join('agents', 'fork-instructions.md');
+/**
+ * The project files that are ours rather than the project's.
+ *
+ * Everything else under `templates/project/` describes *this project* and is
+ * written once. These describe *this version of `zen`* — how the memory graph
+ * works, how its tools are called, what survives a join — and land under
+ * `agents/` only because that is where house rules have to be to reach a
+ * prompt. A copy that has fallen behind the runtime is worse than none, so
+ * `zen check --fix` replaces them, and nothing in them is worth editing in
+ * place: project policy on any of those subjects goes in a topic file of its
+ * own beside them.
+ */
+export const SHARED_RULES = [FORK_RULES, MEMORY_RULES, TOOL_RULES];
 /** The same bytes, kept in the `zen-memory` skill to restore or diff against. */
 const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', 'memory-instructions.md');
 /**
@@ -194,7 +211,7 @@ function copyTree(from, dir, rel, opts) {
 export function editorFiles(dir) {
     const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
     // The one file that belongs to both trees. It is a project file first —
-    // house rules prepended to every agent that can see the graph — and it is
+    // house rules reaching every agent that can see the graph — and it is
     // written once and edited from then on, like every other project file. But
     // a project whose copy drifted, or that deleted it and turned memory back
     // on later, needs somewhere to get the current text from, and the editor
@@ -208,6 +225,53 @@ export function editorFiles(dir) {
     written.push(MEMORY_REFERENCE);
     return written;
 }
+/**
+ * Replaces every file in a project that nobody is meant to be maintaining:
+ * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the
+ * relative paths written, project files first.
+ *
+ * This is the other half of `keep: true`. A scaffold never overwrites, which is
+ * right for the files a project goes on to make its own and wrong for the ones
+ * that only ever restate how this version of `zen` behaves — those a project
+ * upgrades into, and before this there was no way to get them except by hand.
+ */
+export function refreshShared(dir) {
+    const written = [];
+    for (const rel of SHARED_RULES) {
+        const path = join(dir, rel);
+        mkdirSync(dirname(path), { recursive: true });
+        copyFileSync(join(TEMPLATES, 'project', rel), path);
+        written.push(rel);
+    }
+    written.push(...editorFiles(dir));
+    return written;
+}
+/**
+ * Which of a project's `SHARED_RULES` are not the bytes this `zen` ships.
+ *
+ * The comparison is the whole file rather than anything read out of it,
+ * because there is no reading that would have caught the copies that went
+ * stale in practice: prose describing a tool that was renamed, a section about
+ * behaviour that changed, frontmatter added after the copy was written. All of
+ * it parses, all of it loads, and all of it is wrong. A file that is not there
+ * is not stale — what must exist is checked where it is required, not here.
+ *
+ * Paths come back with forward slashes, the way a report names a file.
+ */
+export function staleShared(dir) {
+    const stale = [];
+    for (const rel of SHARED_RULES) {
+        const path = join(dir, rel);
+        if (!existsSync(path)) {
+            continue;
+        }
+        const ours = readFileSync(join(TEMPLATES, 'project', rel), 'utf8');
+        if (readFileSync(path, 'utf8') !== ours) {
+            stale.push(rel.split(sep).join('/'));
+        }
+    }
+    return stale;
+}
 /**
  * Writes a project. Never overwrites the project's own files — a second `init`
  * over a directory fills in what is missing and leaves the rest alone — but the

package/dist/term.d.ts

@@ -66,6 +66,8 @@ export declare function progress(): {
     done: () => void;
 };
 export declare function warn(message: string): void;
+/** What this run calls itself, in the process table and on the terminal's tab. */
+export declare function title(text: string): void;
 export declare function fail(message: string, hint?: string): void;
 export declare function isInteractive(): boolean;
 export declare function ask(question: string, fallback?: string): Promise<string>;

package/dist/term.js

@@ -186,6 +186,31 @@ export function progress() {
 export function warn(message) {
     note(`${yellow('warning')} ${message}`);
 }
+// ---------------------------------------------------------------------------
+// Naming the run
+//
+// Two different things answer to the word "title", and a long run wants both.
+// `process.title` is what the process table says, which is how `ps` and
+// Activity Monitor tell one `zen` from another. The tab is the terminal's own,
+// and nothing a process does to itself reaches it — macOS reads the tab name
+// from the executable — so it takes an OSC sequence, written to stderr with the
+// rest of the narration and only when there is a terminal to read it.
+// ---------------------------------------------------------------------------
+let restores = false;
+/** What this run calls itself, in the process table and on the terminal's tab. */
+export function title(text) {
+    process.title = text;
+    if (!process.stderr.isTTY) {
+        return;
+    }
+    // Push what the shell had there first, so leaving puts it back.
+    if (!restores) {
+        restores = true;
+        process.stderr.write('\u001b[22;0t');
+        process.on('exit', () => process.stderr.write('\u001b[23;0t'));
+    }
+    process.stderr.write(`\u001b]0;${text}\u0007`);
+}
 export function fail(message, hint) {
     note(`${red('error')} ${message}`);
     if (hint) {