@zenera/cli 1.1.0 → 1.1.2

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>[];

package/dist/validate.js

@@ -1,8 +1,11 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, exaTools, projectRegistry, readProjectConfig, sandboxTools, selectTools, workspaceTools, } from '@zenera/neo';
+import { EXA_GROUP, FileSkillProvider, SANDBOX_MOUNT, Sandbox, exaTools, projectRegistry, readProjectConfig, sandboxTools, selectTools, workspaceTools, } from '@zenera/neo';
+import { existsSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { auditModels, credentialFor } from "./audit.js";
+import { resolveBuild } from "./image.js";
 import { SHAPES } from "./keys.js";
+import { BuildError, ensurePodmanReady } from "./podman.js";
 // Mirrors the loader's own constants (`packages/neo/src/project/load.ts`).
 // Duplicated rather than exported, because a check that agreed with the loader
 // by construction could not report that the two had diverged.
@@ -10,6 +13,8 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 const HOUSE_RULES = 'INSTRUCTIONS.md';
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
+const SKILL_FILE = 'SKILL.md';
+const ASSETS_DIR = 'assets';
 /** What `allow:` and `preload:` accept, so a skill outside it cannot be named. */
 const REFERABLE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
 export async function validateProject(opts) {
@@ -27,6 +32,8 @@ export async function validateProject(opts) {
     let entry = null;
     let registered = opts.registered ?? false;
     let name = opts.name ?? null;
+    let build;
+    let probed = false;
     const add = (f) => {
         findings.push(f);
     };
@@ -54,7 +61,7 @@ export async function validateProject(opts) {
         skillDirs,
         providers,
         models,
-        sandbox: sandboxSummary(config, agents),
+        sandbox: sandboxSummary(config, agents, build, probed),
         findings,
     });
     // -----------------------------------------------------------------------
@@ -181,12 +188,26 @@ export async function validateProject(opts) {
     skills.push(...catalog.entries);
     bindSkills(config, skills, catalog.names, add);
     // -----------------------------------------------------------------------
+    // Assets
+    // -----------------------------------------------------------------------
+    checkAssets(root, config, record, add);
+    // -----------------------------------------------------------------------
+    // The sandbox
+    // -----------------------------------------------------------------------
+    build = checkSandbox(root, config, record, add);
+    // -----------------------------------------------------------------------
     // Models and credentials
     // -----------------------------------------------------------------------
     const resolved = checkModels(root, config, opts.keys, add);
     providers = resolved.providers;
     models.push(...resolved.models);
     checkServices(agents, available, opts.keys, add);
+    // Last, because it is the only step that starts anything: everything a
+    // reading of the files can tell you is already on the report by now, so an
+    // interrupted check is still a useful one.
+    if (opts.sandbox?.enabled && sandboxSummary(config, agents).used) {
+        probed = await probeSandbox(config, build, opts.sandbox, add);
+    }
     return done();
 }
 /**
@@ -562,9 +583,9 @@ async function checkSkills(root, config, available, record, add) {
         try {
             const skill = await provider.load(summary.name);
             report.path = display(root, skill.file ?? '');
-            const resources = Object.keys(skill.resources ?? {});
-            if (resources.length) {
-                report.resources = resources;
+            const files = siblings(skill.file);
+            if (files.length) {
+                report.files = files;
             }
             if (skill.tools?.length) {
                 report.tools = skill.tools.map((t) => t.name);
@@ -625,7 +646,7 @@ function locate(root, dirs, name) {
     }
     return undefined;
 }
-/** Directories in a catalog that hold no `SKILL.md`, and are therefore not skills. */ function ignored(root, dirs, known) {
+/** Anything in a catalog that is not a `<name>/SKILL.md` folder. */ function ignored(root, dirs, known) {
     const out = [];
     for (const dir of dirs) {
         let items;
@@ -636,10 +657,25 @@ function locate(root, dirs, name) {
             continue;
         }
         for (const item of items) {
+            // A bare `<name>.md` is still indexed, so this is not a skill that
+            // went missing — it is one that can never grow a file of its own.
+            if (item.isFile() && item.name.endsWith('.md')) {
+                const folder = join(dir, item.name.slice(0, -'.md'.length));
+                out.push({
+                    severity: 'error',
+                    code: 'skill.flat',
+                    where: join(dir, item.name),
+                    message: 'a skill is a folder holding SKILL.md — a bare markdown file has no ' +
+                        'directory of its own, so it can never ship the table, example or ' +
+                        'script that is half of what a skill is for',
+                    fix: `move it to ${join(folder, SKILL_FILE)}`,
+                });
+                continue;
+            }
             if (!item.isDirectory() || known.has(item.name)) {
                 continue;
             }
-            if (existsSync(join(root, dir, item.name, 'SKILL.md'))) {
+            if (existsSync(join(root, dir, item.name, SKILL_FILE))) {
                 // It has one; it is in the catalog under a frontmatter name.
                 continue;
             }
@@ -745,6 +781,262 @@ function bindSkills(config, entries, known, add) {
     }
 }
 // ---------------------------------------------------------------------------
+// Assets
+//
+// The folder every agent can read and none can write. It is a convention, so
+// not having one is not a finding — but *naming* one that is not there is, and
+// so is naming one so wide that the run's own working files are inside it.
+// ---------------------------------------------------------------------------
+function checkAssets(root, config, record, add) {
+    const named = config.assets !== undefined;
+    const ref = config.assets ?? ASSETS_DIR;
+    const rel = normalise(root, ref);
+    if (rel === undefined) {
+        add({
+            severity: 'error',
+            code: 'assets.outside',
+            where: 'assets',
+            message: `"${ref}" resolves outside the project root, which is refused`,
+            fix: 'keep the material inside the project, or copy it in',
+        });
+        return;
+    }
+    // The conventional folder is optional; a project with nothing to share has
+    // nothing to say about it.
+    if (!named && !existsSync(join(root, rel))) {
+        return;
+    }
+    const role = 'reference material, mounted read-only at /assets';
+    if (!record(rel, role, 'directory', named, named ? 'assets' : undefined)) {
+        add({
+            severity: 'error',
+            code: 'assets.missing',
+            where: 'assets',
+            message: `no such directory: ${rel} — the project will not load`,
+            fix: `create ${rel}, or drop the \`assets:\` key`,
+        });
+        return;
+    }
+    const at = join(root, rel);
+    // Mounting the project root, or anything holding the sessions directory,
+    // hands every agent the transcripts of every run — including this one.
+    if (rel === '' || rel === '.' || existsSync(join(at, 'sessions'))) {
+        add({
+            severity: 'warning',
+            code: 'assets.overbroad',
+            where: 'assets',
+            message: `${rel || '.'} contains the project's own files, so every run's ` +
+                'transcripts, prompts and configuration are readable by every agent',
+            fix: 'point `assets:` at a directory that holds only what agents should read',
+        });
+        return;
+    }
+    if (contents(at).length === 0) {
+        add({
+            severity: 'note',
+            code: 'assets.empty',
+            where: 'assets',
+            message: `${rel} is empty, so /assets is mounted with nothing in it`,
+            fix: 'put something in it, or remove it',
+        });
+    }
+}
+function contents(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// The sandbox
+//
+// Two halves. The first reads the `build:` block and says whether the files it
+// names are there — cheap, and true on any machine. The second builds the
+// image and runs one command in it, which is the only way to find out whether
+// the Dockerfile works, and is the only thing in this module that starts
+// anything.
+// ---------------------------------------------------------------------------
+/**
+ * Resolves `sandbox.build:` and records the files it names. Returns what the
+ * probe would build, or nothing when the project pulls an image instead.
+ */
+function checkSandbox(root, config, record, add) {
+    const spec = config.sandbox?.build;
+    if (!spec) {
+        return undefined;
+    }
+    const file = normalise(root, spec.dockerfile);
+    const context = spec.context === undefined ? undefined : normalise(root, spec.context);
+    if (file === undefined || (spec.context !== undefined && context === undefined)) {
+        add({
+            severity: 'error',
+            code: 'sandbox.outside',
+            where: 'sandbox.build',
+            message: 'the build resolves outside the project root, which is refused',
+            fix: 'keep the Dockerfile and its context inside the project',
+        });
+        return undefined;
+    }
+    let ok = record(file, 'the sandbox image is built from this', 'file', true, 'sandbox.build');
+    if (!ok) {
+        add({
+            severity: 'error',
+            code: 'sandbox.dockerfile.missing',
+            where: 'sandbox.build.dockerfile',
+            message: `no such file: ${file} — the project will not load`,
+            fix: `create ${file}, or replace \`build:\` with \`image: <ref>\``,
+        });
+    }
+    if (context !== undefined) {
+        const found = record(context, 'what the sandbox build may COPY from', 'directory', true, 'sandbox.build.context');
+        if (!found) {
+            add({
+                severity: 'error',
+                code: 'sandbox.context.missing',
+                where: 'sandbox.build.context',
+                message: `no such directory: ${context} — the project will not load`,
+                fix: `create ${context}, or drop \`context:\` to use the Dockerfile's own folder`,
+            });
+        }
+        ok &&= found;
+    }
+    if (!ok) {
+        return undefined;
+    }
+    try {
+        return resolveBuild(root, config.sandbox);
+    }
+    catch (err) {
+        add({
+            severity: 'error',
+            code: 'sandbox.build.invalid',
+            where: 'sandbox.build',
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+/** Written by the smoke test and read back, to prove the mount is real. */
+const SMOKE = 'zen-check';
+/**
+ * Builds the image and runs one command in it.
+ *
+ * The container is given a temporary directory rather than anybody's
+ * workspace: this is a check, and a check that can write to the work is not
+ * one. `persist` is off, so closing it removes it — a `zen check` that left a
+ * container behind would be a slow leak nobody attributed to it.
+ */
+async function probeSandbox(config, build, opts, add) {
+    const image = build?.tag ?? config.sandbox?.image;
+    const engine = opts.engine ?? 'podman';
+    // The pre-flight narrates the build and the pull itself, so this only has
+    // to cover the silence before it: installing, and starting a machine.
+    opts.onProgress?.('checking the sandbox');
+    try {
+        await ensurePodmanReady({ image, build, engine, exec: opts.exec, yes: true });
+    }
+    catch (err) {
+        if (err instanceof BuildError) {
+            const rel = config.sandbox?.build?.dockerfile ?? 'the Dockerfile';
+            add({
+                severity: 'error',
+                code: 'sandbox.build',
+                where: 'sandbox.build.dockerfile',
+                message: `${rel} does not build: ${err.hint ?? reason(err)}`,
+                fix: 'run the build by hand to see the whole log',
+            });
+            return false;
+        }
+        // A laptop with no container engine is not a broken project, and this
+        // report is most valuable on exactly that laptop.
+        add({
+            severity: 'warning',
+            code: 'sandbox.unchecked',
+            where: 'sandbox',
+            message: `${reason(err)} — so the sandbox was not tried`,
+            fix: 'run `zen sandbox up`, or pass --no-sandbox to skip this',
+        });
+        return false;
+    }
+    const root = realpathSync(mkdtempSync(join(tmpdir(), 'zen-check-')));
+    const box = new Sandbox({
+        root,
+        key: 'check',
+        image,
+        cpus: config.sandbox?.cpus,
+        memory: config.sandbox?.memory,
+        network: config.sandbox?.network,
+        workdir: config.sandbox?.workdir,
+        user: config.sandbox?.user,
+        engine,
+        exec: opts.exec,
+        // Not the project's: a check forwards no host values, and keeping the
+        // container is the caller's choice about their work, not about this.
+        env: {},
+        persist: false,
+    });
+    opts.onProgress?.(`starting ${image ?? 'the container'}`);
+    try {
+        const res = await box.exec([
+            `printf '%s\\n' ${SMOKE} > ${SMOKE}.txt`,
+            `cat ${SMOKE}.txt`,
+            `rm ${SMOKE}.txt`,
+            'pwd',
+        ].join('\n'), { timeout: 60 });
+        if (res.exit_code !== 0 || !res.stdout.includes(SMOKE)) {
+            add({
+                severity: 'error',
+                code: 'sandbox.smoke',
+                where: 'sandbox',
+                message: `${image} starts, but the workspace is not usable inside it: ` +
+                    (res.stderr.trim().split('\n')[0] || `exit ${res.exit_code}`),
+                fix: 'check `workdir:` and `user:` — the image must be able to write there',
+            });
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        add({
+            severity: 'error',
+            code: 'sandbox.start',
+            where: 'sandbox',
+            message: `could not start a container from ${image}: ${reason(err)}`,
+            fix: 'run `zen sandbox status` to see what the engine says',
+        });
+        return false;
+    }
+    finally {
+        await box.dispose().catch(() => undefined);
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+function reason(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * What else is in a skill's folder — the files the agent reaches under /skills,
+ * and the reason a skill can ship a script instead of describing one. A bare
+ * `<name>.md` has no folder of its own, and its neighbours are other skills.
+ */
+function siblings(skillFile) {
+    if (!skillFile || basename(skillFile) !== SKILL_FILE) {
+        return [];
+    }
+    const folder = dirname(skillFile);
+    try {
+        return readdirSync(folder, { withFileTypes: true })
+            .filter((e) => e.name !== SKILL_FILE)
+            .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
 // Models
 // ---------------------------------------------------------------------------
 function checkModels(root, config, keys, add) {
@@ -890,12 +1182,15 @@ function whereFor(config, role, name, usedBy) {
 // ---------------------------------------------------------------------------
 // Odds and ends
 // ---------------------------------------------------------------------------
-function sandboxSummary(config, agents) {
+function sandboxSummary(config, agents, build, probed = false) {
     const used = agents.some((a) => a.tools.some((t) => SANDBOX_TOOLS.has(t)));
     return {
-        image: config?.sandbox?.image ?? null,
+        image: build?.tag ?? config?.sandbox?.image ?? null,
+        // As written, not as resolved: this is read by someone about to edit it.
+        dockerfile: config?.sandbox?.build?.dockerfile ?? null,
         declared: Boolean(config?.sandbox) || agents.some((a) => a.ownSandbox),
         used,
+        probed,
     };
 }
 const SANDBOX_TOOLS = new Set([

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.0"
+        "@zenera/neo": "^1.1.2"
     },
     "peerDependencies": {
         "@anthropic-ai/sdk": "^0.120.0",