@zenera/cli 1.1.0 → 1.1.3

package/dist/scaffold.js

@@ -1,21 +1,64 @@
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // Scaffolding
 //
-// What `zen init` writes. Deliberately close to empty: a template full of
+// What `zen init` writes and `zen open` refreshes — none of which is in this
+// file. `templates/` holds the real thing, laid out the way it lands, so
+// changing what a project starts life as is editing a file rather than a string
+// literal escaping every backtick and `${...}` it contains:
+//
+//   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,
+//                        which describe this version of `zen` to the editor and
+//                        are replaced every time.
+//   templates/parts/     fragments spliced into a template above.
+//
+// The trees are copied whole and nothing enumerates them, so adding a file to
+// a new project is adding a file to `templates/project/` and nothing else.
+//
+// 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 here works as written, and every other knob is in `docs/`.
+// one agent works as written, and every other knob is in `docs/`.
 // ---------------------------------------------------------------------------
-const INSTRUCTIONS_MD = `# House rules
-
-Everything in this file is prepended to every agent's prompt, so it is the
-place for the things that are true regardless of who is answering: tone,
-constraints, what to do when the answer is not knowable.
-
-Replace this with yours.
-`;
+const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
+/** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
+const TEMPLATE = '.tmpl';
+/**
+ * Fills the `{{name}}` in a template, in the two shapes templates use.
+ *
+ * A placeholder alone on a line takes a whole fragment: its own indentation is
+ * applied to every line of the value, and an empty value takes the line with
+ * 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.
+ */
+function render(text, vars) {
+    const value = (name) => {
+        const found = vars[name];
+        if (found === undefined) {
+            throw new Error(`template asks for {{${name}}}, which nothing supplies`);
+        }
+        return found;
+    };
+    return text
+        .replace(/^([ \t]*)\{\{(\w+)\}\}[ \t]*\r?\n/gm, (_, indent, name) => {
+        const body = value(name).trimEnd();
+        if (!body) {
+            return '';
+        }
+        const lines = body.split('\n').map((line) => (line ? indent + line : ''));
+        return `${lines.join('\n')}\n`;
+    })
+        .replace(/\{\{(\w+)\}\}/g, (_, name) => value(name));
+}
+/** Reads one fragment from `templates/parts/`, without its trailing newline. */
+function part(name, vars = {}) {
+    const text = readFileSync(join(TEMPLATES, 'parts', `${name}${TEMPLATE}`), 'utf8');
+    return render(text, vars).trimEnd();
+}
 /**
  * The `model:` section, which is one line until it has to say more.
  *
@@ -24,93 +67,58 @@ Replace this with yours.
  * reasoning means splitting the ref back into the two fields and giving the
  * configuration a name to be referred to by.
  */
-const MODEL_SECTION = (ref, options) => {
+function modelSection(ref, options) {
     const colon = ref.indexOf(':');
     if (!options || colon < 0) {
-        return ('# The model an agent uses when it does not pin its own. Change it here and the\n' +
-            '# whole project moves. The prefix is the *provider* name, not the vendor — drop\n' +
-            '# it and the id goes to the default provider, whatever the id looks like.\n' +
-            `model: ${ref}`);
+        return part('model.yaml', { ref });
     }
-    const indented = options
-        .trimEnd()
-        .split('\n')
-        .map((line) => (line ? `        ${line}` : ''))
-        .join('\n');
-    return ('# The model an agent uses when it does not pin its own. Change it here and the\n' +
-        '# whole project moves. A named configuration is what gives the knobs below\n' +
-        '# somewhere to live; a bare `model: <provider>:<id>` works when there are none.\n' +
-        'models:\n' +
-        '    main:\n' +
-        `        provider: ${ref.slice(0, colon)}\n` +
-        `        model: ${ref.slice(colon + 1)}\n` +
-        `${indented}\n` +
-        '\n' +
-        'model: main');
-};
+    return part('models.yaml', {
+        provider: ref.slice(0, colon),
+        id: ref.slice(colon + 1),
+        options,
+    });
+}
 /**
- * Added above the tool list when the project is scaffolded with web access.
- * The group is registered whether or not a key exists, so this only ever
- * changes what the agent is allowed to reach for.
+ * The name a template file lands under.
+ *
+ * `gitignore` gains its dot here because it cannot have one in the repository:
+ * npm strips a `.gitignore` out of a published tarball, and git would read this
+ * one as rules about `packages/cli/templates/` rather than as content.
  */
-const EXA_NOTE = `
-      #
-      # exa:* is web search and page reading, here because this machine has an
-      # Exa key. The key is read from the environment when a tool is called,
-      # so a clone of this project without one still loads and only the call
-      # fails.`;
-const AGENTS_YAML = (model, options, web) => `# Who exists, and what they may reach for.
-#
-version: 1
-
-${MODEL_SECTION(model, options)}
-
-# The container \`sandbox:*\` commands run in. \`persist: true\` keeps it between
-# runs instead of throwing it away, so what the agent installs is still there
-# next time — otherwise only /workspace and its home directory survive, and an
-# \`apt-get\` or a root \`pip install\` is repeated on every run. \`zen sandbox
-# clean\` removes the ones left behind. Everything else has a default; see the
-# sandbox: block in docs/agents-yaml.md to size or pin the image.
-sandbox:
-    persist: true
-
-agents:
-    - name: default
-      description: The entry point.
-      # Instructions live in agents/prompts/<name>.md and are picked up by
-      # convention — no need to name the file here.
-      #
-      # workspace:* is every file tool at once, sandbox:* is the shell. Name
-      # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
-      #
-      # sandbox:* runs commands in a container, not on this machine, so it
-      # needs podman — \`zen run\` installs and starts what it can on its own,
-      # and \`zen sandbox status\` says where that got to. Drop the line if you
-      # would rather this agent never reached a shell.${web ? EXA_NOTE : ''}
-      tools:
-          - workspace:*
-          - sandbox:*${web ? '\n          - exa:*' : ''}
-`;
-const PROMPT = `You are a helpful assistant working inside a project workspace.
-
-You have tools to read, search and edit files. The workspace is the only
-place you can see; paths are relative to its root.
-
-You can also run shell commands. They run in a container over the same
-workspace, not on the user's machine, so a command that fails there has cost
-them nothing — but it is still their work in the directory, so read before you
-overwrite and say what you ran.
-
-Read a file before you change it: \`apply_patch\` matches the surrounding text
-exactly, so a patch written from memory will not apply. Use \`apply_patch\` to
-change part of a file and \`write_file\` only for a new one.
-
-Say what you changed.
-`;
-const GITIGNORE = `# Sessions hold run state, memory, blobs and whatever the agent wrote.
-# None of it is source.
-sessions/
-`;
+function target(name) {
+    if (name.endsWith(TEMPLATE)) {
+        return name.slice(0, -TEMPLATE.length);
+    }
+    return name === 'gitignore' ? '.gitignore' : name;
+}
+/**
+ * Copies one template directory into `dir` at `rel`, depth first, sorted so the
+ * list it returns is the same on every machine. Only a `.tmpl` is read as text;
+ * everything else is copied byte for byte.
+ */
+function copyTree(from, dir, rel, opts) {
+    const written = [];
+    mkdirSync(join(dir, rel), { recursive: true });
+    const entries = readdirSync(from, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const source = join(from, entry.name);
+        if (entry.isDirectory()) {
+            written.push(...copyTree(source, dir, join(rel, entry.name), opts));
+            continue;
+        }
+        const child = join(rel, target(entry.name));
+        if (opts.keep && existsSync(join(dir, child))) {
+            continue;
+        }
+        const body = entry.name.endsWith(TEMPLATE)
+            ? render(readFileSync(source, 'utf8'), opts.vars ?? {})
+            : readFileSync(source);
+        writeFileSync(join(dir, child), body);
+        written.push(child);
+    }
+    return written;
+}
 // ---------------------------------------------------------------------------
 // Telling the editor which instructions are not for it
 //
@@ -127,94 +135,52 @@ sessions/
 // up whatever `AGENTS.md` a run happened to leave behind. It is a *restricted*
 // setting, so it applies only in a trusted workspace; that is the right way
 // round, since an untrusted folder is not one to run agents in either.
-// ---------------------------------------------------------------------------
-const VSCODE_SETTINGS = `{
-    "chat.useNestedAgentsMdFiles": false,
-    "chat.tools.terminal.autoApprove": {
-        "zen": true
-    }
-}
-`;
-/**
- * Writes `.vscode/settings.json` under `dir`, replacing what is there. The file
- * is ours: it says how the editor is to treat a directory the agents write
- * into, and a stale copy of that answer is worse than none. Returns the
- * relative path.
- */
-export function editorSettings(dir) {
-    const rel = join('.vscode', 'settings.json');
-    mkdirSync(join(dir, '.vscode'), { recursive: true });
-    writeFileSync(join(dir, rel), VSCODE_SETTINGS);
-    return rel;
-}
-// ---------------------------------------------------------------------------
-// The other half of the editor story
 //
 // `INSTRUCTIONS.md` addresses the *project's* agents. The editor's assistant
 // still needs a brief of its own, and what it needs to know is how this kind
 // of project is put together — the file formats, how a prompt is written, when
-// to add a skill rather than an agent. That is a whole `.github/` tree — the
-// standing brief, plus the prompt files and skills the editor picks up from
-// the same place — kept as files rather than template literals in here: they
-// are full of backticks and `${...}` examples, which a TS template literal
-// cannot hold without escaping every one of them into illegibility.
-//
-// `templates/.github/` mirrors what lands in the project one for one, so
-// adding a skill or a prompt file is adding a file there and nothing else.
+// to add a skill rather than an agent. That is what the `.github/` tree is: the
+// standing brief, plus the prompt files and skills the editor picks up from the
+// same place.
 // ---------------------------------------------------------------------------
-const GITHUB_TEMPLATE = fileURLToPath(new URL('../templates/.github', import.meta.url));
-/**
- * Writes the `.github/` tree under `dir`, replacing what is there — it
- * describes the file formats of the version of `zen` in hand, so the current
- * one is the only one worth having. Returns the relative paths written.
- */
-export function copilotInstructions(dir) {
-    return copyTree(GITHUB_TEMPLATE, dir, '.github');
-}
 /**
- * Copies one template directory into `dir` at `rel`, depth first, sorted so
- * the list it returns is the same on every machine.
+ * 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,
+ * and they describe the file formats of the version of `zen` in hand, so the
+ * current answer is the only one worth having and a stale one is worse than
+ * none. Returns the relative paths written.
  */
-function copyTree(from, dir, rel) {
-    const written = [];
-    mkdirSync(join(dir, rel), { recursive: true });
-    const entries = readdirSync(from, { withFileTypes: true });
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-        const child = join(rel, entry.name);
-        if (entry.isDirectory()) {
-            written.push(...copyTree(join(from, entry.name), dir, child));
-        }
-        else {
-            writeFileSync(join(dir, child), readFileSync(join(from, entry.name)));
-            written.push(child);
-        }
-    }
-    return written;
+export function editorFiles(dir) {
+    return copyTree(join(TEMPLATES, 'editor'), dir, '', {});
 }
 /**
- * Writes a project. Never overwrites the project's own files: the caller
- * decides whether it may. The editor files are the exception — they are ours,
- * and are replaced.
+ * 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
+ * editor files are ours, and are replaced.
+ *
+ * The two are returned apart because they are read differently: the project's
+ * files are the thing that was just made, and worth listing; the editor's are
+ * plumbing for a tool that may not even be installed, and listing them buries
+ * the first set under twice as many lines about the second.
  */
 export function scaffold(opts) {
-    const written = [];
-    const put = (rel, body) => {
-        const path = join(opts.dir, rel);
-        mkdirSync(join(path, '..'), { recursive: true });
-        writeFileSync(path, body, { flag: 'wx' });
-        written.push(rel);
-    };
-    mkdirSync(join(opts.dir, 'agents', 'prompts'), { recursive: true });
+    const files = copyTree(join(TEMPLATES, 'project'), opts.dir, '', {
+        keep: true,
+        vars: {
+            model: modelSection(opts.model, opts.modelOptions),
+            exa: opts.web ? part('exa.yaml') : '',
+        },
+    });
+    // The directories with no file to put in them: a skill is a folder someone
+    // adds, sessions is written into on the first run, and `.tmp` is scratch —
+    // there so an agent has somewhere inside the workspace to put a working
+    // file, which is somewhere the sandbox can still reach after the container
+    // it was written from is gone.
     mkdirSync(join(opts.dir, 'agents', 'skills'), { recursive: true });
     mkdirSync(join(opts.dir, 'sessions'), { recursive: true });
-    put('INSTRUCTIONS.md', INSTRUCTIONS_MD);
-    put('agents.yaml', AGENTS_YAML(opts.model, opts.modelOptions, opts.web));
-    put(join('agents', 'prompts', 'default.md'), PROMPT);
-    put('.gitignore', GITIGNORE);
+    mkdirSync(join(opts.dir, '.tmp'), { recursive: true });
     // The project directory is what `zen open` opens, so this is where the
     // editor actually reads them.
-    written.push(editorSettings(opts.dir), ...copilotInstructions(opts.dir));
-    return written;
+    return { files, editor: editorFiles(opts.dir) };
 }
 //# sourceMappingURL=scaffold.js.map

package/dist/term.d.ts

@@ -66,4 +66,6 @@ export declare function choose<T>(title: string, choices: readonly Choice<T>[]):
 export declare function readStdin(): Promise<string | undefined>;
 export declare function ago(iso: string | undefined): string;
 export declare function count(n: number, singular: string, plural?: string): string;
+/** Powers of 1000, as the container engine prints them, so the two agree. */
+export declare function bytes(n: number): string;
 //# sourceMappingURL=term.d.ts.map

package/dist/term.js

@@ -239,4 +239,18 @@ export function ago(iso) {
 export function count(n, singular, plural = `${singular}s`) {
     return `${n} ${n === 1 ? singular : plural}`;
 }
+/** Powers of 1000, as the container engine prints them, so the two agree. */
+export function bytes(n) {
+    if (!Number.isFinite(n) || n <= 0) {
+        return '0 B';
+    }
+    const units = ['B', 'kB', 'MB', 'GB', 'TB'];
+    let value = n;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit++;
+    }
+    return `${unit > 0 && value < 100 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
 //# sourceMappingURL=term.js.map

package/dist/validate.d.ts

@@ -1,4 +1,4 @@
-import { type AnyTool, type ProjectConfig } from '@zenera/neo';
+import { type AnyTool, type ProjectConfig, type Runner } from '@zenera/neo';
 import { type DeclaredRole } from './audit.ts';
 import { type KeyStore } from './keys.ts';
 /**
@@ -65,8 +65,8 @@ export interface SkillReport {
     /** the SKILL.md, relative to the project root */
     path: string;
     tools?: string[];
-    /** other files in the skill folder, which the agent gets as resources */
-    resources?: string[];
+    /** other files in the skill folder, which the agent can reach under /skills */
+    files?: string[];
     /** agents whose binding can see it */
     usedBy: string[];
 }
@@ -111,8 +111,12 @@ export interface Report {
     models: ModelReport[];
     sandbox: {
         image: string | null;
+        /** the Dockerfile that image is built from, when it is built rather than pulled */
+        dockerfile: string | null;
         declared: boolean;
         used: boolean;
+        /** whether the image was actually built and a container started */
+        probed: boolean;
     };
     findings: Finding[];
     counts: {
@@ -139,6 +143,19 @@ export interface ValidateOptions {
      * pay for it.
      */
     keys?: KeyStore;
+    /**
+     * Whether to build the image and start a container. Everything else here
+     * is a reading of files; this is the one part that runs something, so it
+     * is named separately and can be turned off.
+     */
+    sandbox?: {
+        enabled: boolean;
+        engine?: string;
+        /** the test seam, as elsewhere — a check can be watched without an engine */
+        exec?: Runner;
+        /** called with each slow step, so the caller can narrate one */
+        onProgress?: (what: string) => void;
+    };
 }
 export declare function validateProject(opts: ValidateOptions): Promise<Report>;
 export declare function availableTools(root: string, config: ProjectConfig): AnyTool<unknown>[];