@zenera/cli 1.1.0 → 1.1.3

package/dist/podman.js

@@ -1,10 +1,14 @@
-import { platform } from 'node:os';
 import { runProcess, SandboxError } from '@zenera/neo';
+import { readdirSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
 import { CliError, confirm, dim, EXIT, isInteractive, note } from "./term.js";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
 /** Starting a virtual machine and pulling an image are both slow on purpose. */
 const SLOW_MS = 600_000;
+/** ...and a build from a cold cache is slower than either. */
+const BUILD_MS = 900_000;
 // One process asks once. Several agents starting containers in the same run
 // must not each decide to boot a virtual machine.
 const settled = new Map();
@@ -62,7 +66,10 @@ async function preflight(opts) {
     }
     // 4. The image, so the first command is not a five-minute pull that looks
     //    like a hung model.
-    if (opts.image) {
+    if (opts.build) {
+        await build(engine, opts.build, run, opts.rebuild);
+    }
+    else if (opts.image) {
         const present = await call(['image', 'exists', opts.image], 30_000);
         if (present.code !== 0) {
             note(dim(`pulling ${opts.image} — this happens once`));
@@ -158,6 +165,52 @@ function parseMachines(stdout) {
     }
 }
 // ---------------------------------------------------------------------------
+// The image
+// ---------------------------------------------------------------------------
+/**
+ * Builds the project's Dockerfile under its tag.
+ *
+ * Run every time rather than skipped when the tag already exists, because the
+ * tag is a hash of the Dockerfile and its context and the engine's layer cache
+ * is a hash of the same thing plus the base image. Asking it is cheap, and it
+ * is the only thing that notices when `FROM node:24` starts meaning a different
+ * node:24.
+ */
+/**
+ * A build that ran and failed, rather than a host that could not be asked.
+ *
+ * The difference is invisible at the command line — both stop the run and
+ * print why — but it decides everything for `zen check`: a Dockerfile that
+ * does not build is a broken project, and a laptop without podman on it is
+ * not. Only one of them is an error.
+ */
+export class BuildError extends CliError {
+}
+/**
+ * Builds the project's Dockerfile under its tag, unless that tag is already on
+ * disk.
+ *
+ * Skipping is safe here in a way it would not be for an ordinary tag, because
+ * this one is a hash of the Dockerfile and its context: the image existing
+ * *means* the content is unchanged. What it does not cover is a moved base
+ * image — `podman build` defaults to `--pull=missing` and reuses whatever
+ * `FROM node:24` resolved to last time — so `zen sandbox pull` forces the
+ * build, and `--pull` is where that would be fixed if it ever needs to be.
+ */
+async function build(engine, spec, run, force = false) {
+    if (!force) {
+        const present = await run(engine, ['image', 'exists', spec.tag], { timeoutMs: 30_000 });
+        if (present.code === 0) {
+            return;
+        }
+    }
+    note(dim(`building ${spec.tag} from ${spec.dockerfile}`));
+    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, BUILD_MS);
+    if (built.code !== 0) {
+        throw new BuildError(`could not build ${spec.dockerfile}`, EXIT.sandbox, last(built) || 'run the build by hand to see what the engine says');
+    }
+}
+// ---------------------------------------------------------------------------
 // Reporting
 // ---------------------------------------------------------------------------
 /** What `zn sandbox status` prints. Changes nothing, and never throws. */
@@ -210,19 +263,41 @@ function safeMachines(stdout) {
  * *stopped* container behind, and a listing that only showed running ones
  * would say nothing is there while the disk says otherwise.
  */
-export async function ownedContainers(engine = 'podman', exec = runProcess) {
-    const res = await exec(engine, ['ps', '--all', '--filter', 'label=zenera=1', '--format', '{{.Names}}\t{{.State}}'], { timeoutMs: 30_000 }).catch(() => undefined);
+export async function ownedContainers(engine = 'podman', exec = runProcess, opts = {}) {
+    const args = ['ps', '--all', '--filter', 'label=zenera=1', '--format', 'json'];
+    // Asked for by name only: podman works a size out by diffing the layer,
+    // which costs more than everything else `status` does put together.
+    if (opts.sizes) {
+        args.push('--size');
+    }
+    const res = await exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
     if (!res || res.code !== 0) {
         return [];
     }
-    return res.stdout
-        .split('\n')
-        .map((l) => l.trim())
-        .filter(Boolean)
-        .map((line) => {
-        const [name, state] = line.split('\t');
-        return { name, state: state?.trim() || 'unknown' };
-    });
+    return parseContainers(res.stdout);
+}
+/** Newest first, which is the order someone reading a list of them wants. */
+function parseContainers(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout.trim() || '[]');
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw
+        .map((c) => ({
+        name: c.Names?.[0] ?? '',
+        state: c.State?.trim() || 'unknown',
+        key: c.Labels?.['zenera.key'],
+        createdAt: c.Created ? new Date(c.Created * 1000).toISOString() : undefined,
+        size: c.Size?.rwSize,
+    }))
+        .filter((c) => c.name)
+        .sort((a, b) => (b.createdAt ?? '').localeCompare(a.createdAt ?? ''));
 }
 export async function removeContainers(names, engine = 'podman', exec = runProcess) {
     if (names.length === 0) {
@@ -230,6 +305,91 @@ export async function removeContainers(names, engine = 'podman', exec = runProce
     }
     await exec(engine, ['rm', '--force', '--volumes', ...names], { timeoutMs: 120_000 });
 }
+/** What the engine is using. Never throws: a disk report is not worth a crash. */
+export async function engineDisk(engine = 'podman', exec = runProcess) {
+    const call = (args) => exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
+    const res = await call(['system', 'df', '--format', 'json']);
+    if (!res || res.code !== 0) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(res.stdout.trim() || '[]');
+    }
+    catch {
+        return undefined;
+    }
+    const rows = Array.isArray(raw) ? raw : [];
+    const pick = (type) => {
+        const row = rows.find((r) => r.Type === type);
+        return {
+            count: row?.TotalCount ?? row?.Total ?? 0,
+            active: row?.Active ?? 0,
+            size: row?.RawSize ?? 0,
+            reclaimable: row?.RawReclaimable ?? 0,
+        };
+    };
+    const info = await call([
+        'info',
+        '--format',
+        '{{.Store.GraphRootUsed}}\t{{.Store.GraphRootAllocated}}',
+    ]);
+    const [used, capacity] = (info?.code === 0 ? info.stdout.trim() : '').split('\t').map(Number);
+    return {
+        images: pick('Images'),
+        containers: pick('Containers'),
+        volumes: pick('Local Volumes'),
+        store: used > 0 && capacity > 0 ? { used, capacity } : undefined,
+        image: platform() === 'linux' ? undefined : await machineImage(engine, exec),
+    };
+}
+/**
+ * What the machine costs the host, which is not what it says it costs: the
+ * disk image is created sparse at its full size, so only its allocated blocks
+ * are real, and blocks freed inside the machine are not handed back until
+ * something trims them. That is why this can exceed the machine's own `used`.
+ *
+ * The path is not something podman will tell us — `machine inspect` stopped
+ * carrying it — so this is the documented default location and nothing is
+ * reported when the file is not there.
+ */
+async function machineImage(engine, exec) {
+    const listed = await exec(engine, ['machine', 'list', '--format', 'json'], {
+        timeoutMs: 30_000,
+    }).catch(() => undefined);
+    if (!listed || listed.code !== 0) {
+        return undefined;
+    }
+    const machines = safeMachines(listed.stdout);
+    const name = (machines.find((m) => m.Default) ?? machines[0])?.Name;
+    if (!name) {
+        return undefined;
+    }
+    const base = join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'containers', 'podman', 'machine');
+    for (const provider of children(base)) {
+        for (const file of children(join(base, provider))) {
+            if (!file.startsWith(name) || !/\.(raw|qcow2|img)$/.test(file)) {
+                continue;
+            }
+            const path = join(base, provider, file);
+            try {
+                return { name, path, allocated: statSync(path).blocks * 512 };
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+function children(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
 // ---------------------------------------------------------------------------
 /**
  * Long steps print as they go. A five-minute pull with no output is
@@ -248,6 +408,11 @@ async function stream(bin, args, run, timeoutMs = SLOW_MS) {
 function first(res) {
     return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
 }
+/** A build says what went wrong on its last line, not its first. */
+function last(res) {
+    const lines = (res.stderr.trim() || res.stdout.trim()).split('\n').filter((l) => l.trim());
+    return lines.slice(-2).join(' — ');
+}
 function sandboxError(message, hint) {
     return new CliError(message, EXIT.sandbox, hint);
 }

package/dist/projects.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectConfig, type SandboxMount } from '@zenera/neo';
 /** Whether a directory is a project: whether the loader has something to read. */
 export declare function isProjectDir(dir: string): boolean;
 /** A project resolved on disk. */
@@ -6,6 +7,16 @@ export interface Project {
     /** what it is called: the registry's name, or the directory's own */
     name: string;
 }
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export declare function projectMounts(root: string, config: ProjectConfig): SandboxMount[];
 /** Walks up from `start` looking for a project configuration. */
 export declare function findUp(start: string): Promise<Project | undefined>;
 export declare function openDir(dir: string): Promise<Project>;
@@ -59,6 +70,13 @@ export declare const sessionsDir: (projectDir: string) => string;
 /** Session ids, oldest first. Only well-formed stamps count as sessions. */
 export declare function sessionIds(projectDir: string): string[];
 export declare function runIds(sessionDir: string): string[];
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export declare function dirSize(dir: string): number;
 /** True when a session's lock names a process that is still alive. */
 export declare function isBusy(sessionDir: string): boolean;
 /**

package/dist/projects.js

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { ASSETS_MOUNT, assetsDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { existsSync, lstatSync, 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";
@@ -25,6 +26,29 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 export function isProjectDir(dir) {
     return CONFIG_NAMES.some((name) => existsSync(join(dir, name)));
 }
+/**
+ * The trees a run mounts besides the workspace itself.
+ *
+ * One array, handed to the file tools and to the container both, because the
+ * two have to agree on the name: a path `run_command` prints has to be a path
+ * `read_file` takes. Everything here is read-only — material an agent consults
+ * and does not edit — and the paths are resolved, because the podman machine on
+ * macOS shares the real path or nothing.
+ */
+export function projectMounts(root, config) {
+    const mounts = [];
+    const assets = assetsDir(root, config);
+    if (assets) {
+        mounts.push({ host: realpathSync(assets), at: ASSETS_MOUNT, readOnly: true });
+    }
+    // The catalog goes in whole, at fixed names, before anything is loaded: a
+    // container's mounts are decided when it is created, so a skill folder
+    // cannot be added at the moment `skill_load` asks for it.
+    for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
+        mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
+    }
+    return mounts;
+}
 // ---------------------------------------------------------------------------
 // The project directory
 // ---------------------------------------------------------------------------
@@ -201,6 +225,41 @@ function stampedChildren(dir) {
         .map((e) => e.name)
         .sort();
 }
+/**
+ * What a tree occupies, in allocated blocks rather than in bytes, because a
+ * sparse file costs what it was given and not what it claims. Symlinks are
+ * counted and never followed: a link out of the tree is not part of it, and
+ * one that points back in would otherwise be counted twice — or forever.
+ */
+export function dirSize(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const at = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(path);
+                continue;
+            }
+            try {
+                total += lstatSync(path).blocks * 512;
+            }
+            catch {
+                // Gone between the listing and the stat: a live session is
+                // writing, which is normal and not worth failing a report for.
+            }
+        }
+    }
+    return total;
+}
 /** True when a session's lock names a process that is still alive. */
 export function isBusy(sessionDir) {
     const path = join(sessionDir, '.lock');

package/dist/sandbox.d.ts

@@ -1,10 +1,13 @@
-import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxSpec } from '@zenera/neo';
+import { SandboxPool, type AgentProject, type ProjectConfig, type SandboxMount, type SandboxSpec } from '@zenera/neo';
+import { type ResolvedBuild } from './image.ts';
 import type { SessionPaths } from './session.ts';
 export interface SandboxSetup {
     pool: SandboxPool;
     /** the resolved base spec, for `zn sandbox status` and the image pre-warm */
     spec: SandboxSpec;
     image: string;
+    /** the Dockerfile behind `image`, when it came from one */
+    build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
 }
@@ -12,9 +15,19 @@ export interface SandboxInputs {
     config: ProjectConfig;
     session: SessionPaths;
     workspace: string;
+    /** the project directory, which `build:` paths are relative to */
+    root: string;
     readOnly?: boolean;
+    /**
+     * Trees to mount besides the workspace and the home — the project's assets
+     * and its skill catalog. The same array goes to the file tools, so a path
+     * a command prints is a path `read_file` accepts.
+     */
+    mounts?: readonly SandboxMount[];
     /** `--image` */
     image?: string;
+    /** `--no-keys`: refuse to forward credentials, whatever the config says */
+    keys?: boolean;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -1,6 +1,8 @@
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
 import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
+import { mkdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { resolveBuild } from "./image.js";
+import { credentials } from "./keys.js";
 import { ensurePodmanReady } from "./podman.js";
 import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
@@ -22,15 +24,75 @@ import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
 /** Where the persistent home lives, inside the container. */
 const HOME = '/home/agent';
+/** Where a credential *file* is mounted, inside the container. */
+const KEY_MOUNT = '/run/zenera/keys';
+/**
+ * The credentials the run is using, in the form a container takes.
+ *
+ * Two shapes, two mechanisms. A secret is forwarded by *name* — podman reads
+ * the value from its own environment, so nothing is written into an argv that
+ * `ps` will show. A service-account file has to be present as a file, so the
+ * one file is bind-mounted read-only and the variable is rewritten to where it
+ * landed; mounting the directory it came from would drag in whatever else the
+ * user keeps beside it.
+ *
+ * This is the part of the design that gives something away, and it should be
+ * said plainly: the sandbox runs code the model wrote, and a key it can read
+ * is a key it can send. `keys: false`, or `network: none`, is the answer for a
+ * project where that is not an acceptable trade.
+ */
+function forwarded() {
+    const secrets = [];
+    const env = {};
+    const mounts = [];
+    for (const cred of credentials()) {
+        if (cred.holds === 'file') {
+            const at = `${KEY_MOUNT}/${basename(cred.value)}`;
+            mounts.push({ host: cred.value, at, readOnly: true });
+            env[cred.env] = at;
+            continue;
+        }
+        secrets.push(cred.env);
+    }
+    // Not secrets, and useless without one: a service account says which
+    // project it belongs to but never which region to call.
+    for (const name of ['GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION']) {
+        const value = process.env[name];
+        if (value) {
+            env[name] = value;
+        }
+    }
+    return { secrets, env, mounts };
+}
 export function buildSandbox(opts) {
-    const base = { ...(opts.config.sandbox ?? {}), ...(opts.image ? { image: opts.image } : {}) };
+    // An explicit --image is an answer, so there is nothing left to build.
+    const build = opts.image ? undefined : resolveBuild(opts.root, opts.config.sandbox);
+    const base = {
+        ...(opts.config.sandbox ?? {}),
+        ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
+        ...(opts.keys === false ? { keys: false } : {}),
+    };
     const home = join(opts.session.data, 'sandbox', 'home');
-    const mounts = [{ host: home, at: HOME }];
-    const spec = toSpec(base, { HOME });
+    const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
+    const keys = base.keys === false ? undefined : forwarded();
+    if (keys) {
+        mounts.push(...keys.mounts);
+    }
+    // Skills and assets are mounted read-only, and a python script run from a
+    // read-only directory fails on writing its own `__pycache__` — a confusing
+    // error about a file nobody asked for.
+    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
+    const spec = toSpec(base, extra, keys?.secrets);
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
-            agents[agent.name] = toSpec({ ...base, ...agent.sandbox }, { HOME });
+            const merged = merge(base, agent.sandbox);
+            // An agent that opts out gets neither the variables nor the mount,
+            // but the mount is on the pool and cannot be taken back per agent —
+            // so the variable is what actually decides, and without it the file
+            // sitting there is not a credential anything will look for.
+            const own = merged.keys === false ? undefined : keys;
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own?.secrets);
         }
     }
     const pool = new SandboxPool({
@@ -41,14 +103,30 @@ export function buildSandbox(opts) {
         readOnly: opts.readOnly,
         mounts,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, home };
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home };
+}
+/**
+ * An agent's overrides on the project's block. `image` and `build` answer the
+ * same question, so naming either one drops the other: a plain spread would
+ * leave an agent's `image` sitting next to the project's `build`, and the
+ * schema forbids exactly that combination when it is written down.
+ */
+function merge(base, agent) {
+    const merged = { ...base, ...agent };
+    if (agent.image !== undefined) {
+        delete merged.build;
+    }
+    if (agent.build !== undefined) {
+        delete merged.image;
+    }
+    return merged;
 }
 /**
  * Config names a variable; this reads it. A name that is not set on this host
  * is simply not forwarded — an empty string in the container is a different
  * thing from an absent one, and tools test for absence.
  */
-function toSpec(config, extra) {
+function toSpec(config, extra, secrets) {
     const env = { ...extra };
     for (const name of config.env ?? []) {
         const value = process.env[name];
@@ -66,6 +144,7 @@ function toSpec(config, extra) {
         user: config.user,
         persist: config.persist,
         env,
+        secrets,
     };
 }
 /**
@@ -87,6 +166,7 @@ export async function preflight(setup, yes) {
     mkdirSync(setup.home, { recursive: true });
     await ensurePodmanReady({
         image: setup.image,
+        build: setup.build,
         cpus: setup.spec.cpus,
         memory: setup.spec.memory,
         yes,

package/dist/scaffold.d.ts

@@ -1,16 +1,11 @@
 /**
- * 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.
+ * 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.
  */
-export declare function editorSettings(dir: string): string;
-/**
- * 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 declare function copilotInstructions(dir: string): string[];
+export declare function editorFiles(dir: string): string[];
 export interface ScaffoldOptions {
     /** the project directory */
     dir: string;
@@ -20,10 +15,21 @@ export interface ScaffoldOptions {
     /** give the default agent `exa:*` — set when a key for it is on hand */
     web?: boolean;
 }
+export interface Scaffolded {
+    /** the project's own files, in the order they were written */
+    files: string[];
+    /** `.vscode/` and `.github/` — written alongside, and nobody's to edit */
+    editor: string[];
+}
 /**
- * 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 declare function scaffold(opts: ScaffoldOptions): string[];
+export declare function scaffold(opts: ScaffoldOptions): Scaffolded;
 //# sourceMappingURL=scaffold.d.ts.map