@zenera/cli 1.1.0

package/dist/podman.js

@@ -0,0 +1,254 @@
+import { platform } from 'node:os';
+import { runProcess, SandboxError } from '@zenera/neo';
+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;
+// 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();
+export async function ensurePodmanReady(opts = {}) {
+    const key = `${opts.engine ?? 'podman'}::${opts.image ?? ''}`;
+    const pending = settled.get(key);
+    if (pending) {
+        return pending;
+    }
+    const attempt = preflight(opts).catch((err) => {
+        // A failure is not a settled answer: the user may well go and install
+        // the thing we just complained about and try again in the same TUI.
+        settled.delete(key);
+        throw err;
+    });
+    settled.set(key, attempt);
+    return attempt;
+}
+async function preflight(opts) {
+    const engine = opts.engine ?? 'podman';
+    const run = opts.exec ?? runProcess;
+    const call = async (args, timeoutMs = 60_000) => {
+        try {
+            return await run(engine, args, { timeoutMs });
+        }
+        catch (err) {
+            if (err instanceof SandboxError) {
+                return {
+                    code: 127,
+                    stdout: '',
+                    stderr: err.message,
+                    truncated: false,
+                    timedOut: false,
+                };
+            }
+            throw err;
+        }
+    };
+    // 1. The binary.
+    const version = await call([`--version`], 15_000);
+    if (version.code !== 0) {
+        await install(engine, opts, run);
+    }
+    // 2. The virtual machine, on the platforms that have one. Linux runs
+    //    containers natively and has no machine to list, so asking would fail
+    //    with a message about an unknown command rather than about anything
+    //    true.
+    if (platform() !== 'linux') {
+        await machine(engine, call, opts, run);
+    }
+    // 3. The socket. Everything above can be true while the engine is wedged.
+    const info = await call(['info'], 60_000);
+    if (info.code !== 0) {
+        throw sandboxError(`${engine} is installed but not responding`, first(info) || `try: ${engine} machine start`);
+    }
+    // 4. The image, so the first command is not a five-minute pull that looks
+    //    like a hung model.
+    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`));
+            const pulled = await stream(engine, ['pull', opts.image], run);
+            if (pulled.code !== 0) {
+                throw sandboxError(`could not pull ${opts.image}`, first(pulled) || 'check the image name and your network');
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Installing
+// ---------------------------------------------------------------------------
+async function install(engine, opts, run) {
+    if (engine !== 'podman') {
+        throw sandboxError(`${engine} is not installed`, `install ${engine} and try again`);
+    }
+    const how = instructions();
+    if (platform() !== 'darwin' || opts.yes || !isInteractive()) {
+        throw sandboxError('podman is not installed', how);
+    }
+    const brew = await run('brew', ['--version'], { timeoutMs: 15_000 }).catch(() => undefined);
+    if (!brew || brew.code !== 0) {
+        throw sandboxError('podman is not installed', how);
+    }
+    if (!(await confirm('Podman is not installed. Install it with Homebrew now?', true))) {
+        throw sandboxError('podman is not installed', how);
+    }
+    note(dim('installing podman — this takes a few minutes'));
+    const done = await stream('brew', ['install', 'podman'], run);
+    if (done.code !== 0) {
+        throw sandboxError('could not install podman', first(done) || how);
+    }
+}
+function instructions() {
+    switch (platform()) {
+        case 'darwin':
+            return 'install it with: brew install podman';
+        case 'win32':
+            return 'install it with: winget install RedHat.Podman';
+        default:
+            return 'install it with your package manager, e.g. apt install podman';
+    }
+}
+// ---------------------------------------------------------------------------
+// The machine
+// ---------------------------------------------------------------------------
+async function machine(engine, call, opts, run) {
+    const listed = await call(['machine', 'list', '--format', 'json'], 30_000);
+    if (listed.code !== 0) {
+        throw sandboxError(`${engine} machine list failed`, first(listed));
+    }
+    const machines = parseMachines(listed.stdout);
+    if (machines.length === 0) {
+        const cpus = String(opts.cpus ?? DEFAULT_MACHINE_CPUS);
+        const memory = String(opts.memory ?? DEFAULT_MACHINE_MEMORY);
+        note(dim(`initialising the podman machine (${cpus} cpus, ${memory} MiB) — once per host`));
+        const created = await stream(engine, ['machine', 'init', '--cpus', cpus, '--memory', memory], run);
+        if (created.code !== 0) {
+            throw sandboxError('could not create the podman machine', first(created));
+        }
+    }
+    const chosen = machines.find((m) => m.Default) ?? machines[0];
+    if (machines.length > 0 && chosen?.Running) {
+        return;
+    }
+    // A machine that is already starting is not a machine to start again;
+    // `machine start` on one mid-boot is an error, not a no-op.
+    const args = ['machine', 'start'];
+    if (chosen && !chosen.Starting) {
+        args.push(chosen.Name);
+    }
+    note(dim('starting the podman machine'));
+    const started = await stream(engine, args, run, SLOW_MS);
+    if (started.code !== 0 && !/already running/i.test(started.stderr)) {
+        throw sandboxError('could not start the podman machine', first(started));
+    }
+}
+function parseMachines(stdout) {
+    const text = stdout.trim();
+    if (!text) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        // A podman that answers `--format json` with something else is a podman
+        // we cannot reason about; treating it as "no machines" would try to
+        // create a second one.
+        throw sandboxError('could not read `podman machine list --format json`');
+    }
+}
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+/** What `zn sandbox status` prints. Changes nothing, and never throws. */
+export async function podmanStatus(opts = {}) {
+    const engine = opts.engine ?? 'podman';
+    const run = opts.exec ?? runProcess;
+    const call = (args) => run(engine, args, { timeoutMs: 30_000 }).catch(() => undefined);
+    const version = await call(['--version']);
+    if (!version || version.code !== 0) {
+        return { engine, installed: false, ready: false };
+    }
+    const status = {
+        engine,
+        installed: true,
+        version: version.stdout.trim().split(' ').at(-1),
+        ready: false,
+    };
+    if (platform() !== 'linux') {
+        const listed = await call(['machine', 'list', '--format', 'json']);
+        const machines = listed?.code === 0 ? safeMachines(listed.stdout) : [];
+        const chosen = machines.find((m) => m.Default) ?? machines[0];
+        if (chosen) {
+            status.machine = {
+                name: chosen.Name,
+                running: Boolean(chosen.Running),
+                starting: Boolean(chosen.Starting),
+            };
+        }
+    }
+    const info = await call(['info']);
+    status.ready = info?.code === 0;
+    if (opts.image) {
+        status.image = opts.image;
+        const exists = status.ready ? await call(['image', 'exists', opts.image]) : undefined;
+        status.imagePresent = exists?.code === 0;
+    }
+    return status;
+}
+function safeMachines(stdout) {
+    try {
+        return parseMachines(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Containers this CLI created, whatever session they belong to, and whether
+ * each is up. `--all` is the point: with `persist: true` a session leaves a
+ * *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);
+    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' };
+    });
+}
+export async function removeContainers(names, engine = 'podman', exec = runProcess) {
+    if (names.length === 0) {
+        return;
+    }
+    await exec(engine, ['rm', '--force', '--volumes', ...names], { timeoutMs: 120_000 });
+}
+// ---------------------------------------------------------------------------
+/**
+ * Long steps print as they go. A five-minute pull with no output is
+ * indistinguishable from a hang, and the one thing worse than waiting is not
+ * knowing whether you are waiting.
+ */
+async function stream(bin, args, run, timeoutMs = SLOW_MS) {
+    const res = await run(bin, args, { timeoutMs });
+    for (const line of res.stderr.split('\n').slice(-3)) {
+        if (line.trim()) {
+            note(dim(`  ${line.trim()}`));
+        }
+    }
+    return res;
+}
+function first(res) {
+    return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
+}
+function sandboxError(message, hint) {
+    return new CliError(message, EXIT.sandbox, hint);
+}
+//# sourceMappingURL=podman.js.map

package/dist/projects.d.ts

@@ -0,0 +1,70 @@
+/** 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. */
+export interface Project {
+    dir: string;
+    /** what it is called: the registry's name, or the directory's own */
+    name: string;
+}
+/** 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>;
+/**
+ * A name from the registry, or a path. A value that looks like either is tried
+ * as both, path first, because a directory that exists is unambiguous evidence
+ * and a stale registry entry is not.
+ */
+export declare function open(nameOrDir: string): Promise<Project>;
+/**
+ * `open` where a miss is an answer rather than an error. It exists for the one
+ * place a word might be a project name and might be something else entirely —
+ * `zen run <project>` against `zen run <prompt>` — and the difference decides
+ * how the rest of the line is read.
+ */
+export declare function find(nameOrDir: string): Promise<Project | undefined>;
+/** The project a bare command means: the one you are standing in. */
+export declare function current(cwd?: string): Promise<Project | undefined>;
+export interface RegistryEntry {
+    name: string;
+    path: string;
+    addedAt: string;
+}
+export declare class Registry {
+    #private;
+    private constructor();
+    static open(): Promise<Registry>;
+    get entries(): readonly RegistryEntry[];
+    find(name: string): RegistryEntry | undefined;
+    findPath(dir: string): RegistryEntry | undefined;
+    /** Idempotent: re-registering the same directory refreshes it in place. */
+    add(name: string, dir: string): RegistryEntry;
+    remove(name: string): boolean;
+    /** Drops entries whose directory is gone. Returns what it dropped. */
+    prune(): RegistryEntry[];
+    save(): void;
+}
+export interface ProjectSummary {
+    name: string;
+    path: string;
+    /** false when the directory has gone away since it was registered */
+    present: boolean;
+    sessions: number;
+    runs: number;
+    lastRunAt?: string;
+    /** a session currently held by a live process */
+    busy: boolean;
+}
+export declare function summarize(entry: RegistryEntry): Promise<ProjectSummary>;
+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[];
+/** True when a session's lock names a process that is still alive. */
+export declare function isBusy(sessionDir: string): boolean;
+/**
+ * `kill(pid, 0)` sends no signal and only asks whether the process exists.
+ * EPERM means it exists and belongs to someone else, which still counts.
+ */
+export declare function alive(pid: number): boolean;
+export declare function projectName(dir: string): string;
+//# sourceMappingURL=projects.d.ts.map

package/dist/projects.js

@@ -0,0 +1,232 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { paths, readJson, writeJson } from "./home.js";
+import { isStamp } from "./ids.js";
+import { invalidError, usageError } from "./term.js";
+// ---------------------------------------------------------------------------
+// Projects
+//
+// The directory is the truth, and what makes a directory a project is the one
+// file the runtime cannot do without: `agents.yaml`. There is no marker file
+// beside it — that would be a second thing to keep in sync, holding a name the
+// directory already has.
+//
+// `~/.zenera/neo/projects.json` is an index so that `zen list` and `zen open` do
+// not have to search the filesystem, and it is allowed to be wrong: every entry
+// can be rebuilt by pointing `zen` at the directory again, and an entry whose
+// path has vanished is reported, not fatal.
+// ---------------------------------------------------------------------------
+/**
+ * The loader's own names, in its own order — `packages/neo/src/project/load.ts`.
+ * Anything the library would load, `zen` finds.
+ */
+const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents/agents.yml'];
+/** Whether a directory is a project: whether the loader has something to read. */
+export function isProjectDir(dir) {
+    return CONFIG_NAMES.some((name) => existsSync(join(dir, name)));
+}
+// ---------------------------------------------------------------------------
+// The project directory
+// ---------------------------------------------------------------------------
+/**
+ * What a project answers to. The registry is asked first, so one registered
+ * under a name of its own keeps it; the directory's name answers for a project
+ * that was never registered — which is a working project, just not a listed one.
+ */
+async function nameOf(dir) {
+    return (await Registry.open()).findPath(dir)?.name ?? basename(dir);
+}
+// ---------------------------------------------------------------------------
+// Finding one
+// ---------------------------------------------------------------------------
+/** Walks up from `start` looking for a project configuration. */
+export async function findUp(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (isProjectDir(dir)) {
+            return { dir, name: await nameOf(dir) };
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+export async function openDir(dir) {
+    const at = resolve(dir);
+    if (!isProjectDir(at)) {
+        throw invalidError(`${at} is not a project`, `no ${CONFIG_NAMES[0]} — run: zen init`);
+    }
+    return { dir: at, name: await nameOf(at) };
+}
+/**
+ * A name from the registry, or a path. A value that looks like either is tried
+ * as both, path first, because a directory that exists is unambiguous evidence
+ * and a stale registry entry is not.
+ */
+export async function open(nameOrDir) {
+    if (isAbsolute(nameOrDir) || nameOrDir.startsWith('.') || existsSync(nameOrDir)) {
+        return openDir(nameOrDir);
+    }
+    const entry = (await Registry.open()).find(nameOrDir);
+    if (!entry) {
+        throw usageError(`no project named "${nameOrDir}"`, 'see: zen list');
+    }
+    return openDir(entry.path);
+}
+/**
+ * `open` where a miss is an answer rather than an error. It exists for the one
+ * place a word might be a project name and might be something else entirely —
+ * `zen run <project>` against `zen run <prompt>` — and the difference decides
+ * how the rest of the line is read.
+ */
+export async function find(nameOrDir) {
+    if (isAbsolute(nameOrDir) || nameOrDir.startsWith('.') || existsSync(nameOrDir)) {
+        const dir = resolve(nameOrDir);
+        return isProjectDir(dir) ? { dir, name: await nameOf(dir) } : undefined;
+    }
+    const entry = (await Registry.open()).find(nameOrDir);
+    return entry ? openDir(entry.path) : undefined;
+}
+/** The project a bare command means: the one you are standing in. */
+export async function current(cwd = process.cwd()) {
+    return findUp(cwd);
+}
+export class Registry {
+    #file;
+    constructor(file) {
+        this.#file = file;
+    }
+    static async open() {
+        const file = await readJson(paths.projects(), {
+            version: 1,
+            projects: [],
+        });
+        return new Registry({ version: 1, projects: file.projects ?? [] });
+    }
+    get entries() {
+        return this.#file.projects;
+    }
+    find(name) {
+        return this.#file.projects.find((p) => p.name === name);
+    }
+    findPath(dir) {
+        const at = resolve(dir);
+        return this.#file.projects.find((p) => resolve(p.path) === at);
+    }
+    /** Idempotent: re-registering the same directory refreshes it in place. */
+    add(name, dir) {
+        const path = resolve(dir);
+        const existing = this.find(name);
+        if (existing && resolve(existing.path) !== path) {
+            throw usageError(`a different project is already named "${name}"`, `it lives at ${existing.path} — use --name`);
+        }
+        const byPath = this.findPath(path);
+        if (byPath) {
+            byPath.name = name;
+            return byPath;
+        }
+        const entry = { name, path, addedAt: new Date().toISOString() };
+        this.#file.projects.push(entry);
+        return entry;
+    }
+    remove(name) {
+        const at = this.#file.projects.findIndex((p) => p.name === name);
+        if (at < 0) {
+            return false;
+        }
+        this.#file.projects.splice(at, 1);
+        return true;
+    }
+    /** Drops entries whose directory is gone. Returns what it dropped. */
+    prune() {
+        const gone = this.#file.projects.filter((p) => !isProjectDir(p.path));
+        this.#file.projects = this.#file.projects.filter((p) => !gone.includes(p));
+        return gone;
+    }
+    save() {
+        writeJson(paths.projects(), this.#file, 0o600);
+    }
+}
+export async function summarize(entry) {
+    const base = {
+        name: entry.name,
+        path: entry.path,
+        present: false,
+        sessions: 0,
+        runs: 0,
+        busy: false,
+    };
+    if (!isProjectDir(entry.path)) {
+        return base;
+    }
+    const summary = { ...base, present: true };
+    for (const session of sessionIds(entry.path)) {
+        summary.sessions++;
+        const dir = join(entry.path, 'sessions', session);
+        if (isBusy(dir)) {
+            summary.busy = true;
+        }
+        const ids = runIds(dir);
+        summary.runs += ids.length;
+        const newest = ids.at(-1);
+        if (newest && (!summary.lastRunAt || newest > summary.lastRunAt)) {
+            summary.lastRunAt = newest;
+        }
+    }
+    return summary;
+}
+// ---------------------------------------------------------------------------
+// Sessions and runs
+//
+// Kept here rather than in session.ts because listing them is a read-only
+// question about a directory, and `zen list` must be able to ask it without
+// pulling in the runtime.
+// ---------------------------------------------------------------------------
+export const sessionsDir = (projectDir) => join(projectDir, 'sessions');
+/** Session ids, oldest first. Only well-formed stamps count as sessions. */
+export function sessionIds(projectDir) {
+    return stampedChildren(sessionsDir(projectDir));
+}
+export function runIds(sessionDir) {
+    return stampedChildren(join(sessionDir, 'runs'));
+}
+function stampedChildren(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && isStamp(e.name))
+        .map((e) => e.name)
+        .sort();
+}
+/** True when a session's lock names a process that is still alive. */
+export function isBusy(sessionDir) {
+    const path = join(sessionDir, '.lock');
+    try {
+        const { pid } = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof pid === 'number' && alive(pid);
+    }
+    catch {
+        // Absent, unreadable or malformed: nothing is holding it.
+        return false;
+    }
+}
+/**
+ * `kill(pid, 0)` sends no signal and only asks whether the process exists.
+ * EPERM means it exists and belongs to someone else, which still counts.
+ */
+export function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+export function projectName(dir) {
+    return basename(resolve(dir));
+}
+//# sourceMappingURL=projects.js.map

package/dist/resolve.d.ts

@@ -0,0 +1,27 @@
+import * as Projects from './projects.ts';
+import { type SessionPaths } from './session.ts';
+export interface Wanted {
+    project?: string;
+    session?: string;
+    fresh?: boolean;
+    workspace?: string;
+    yes?: boolean;
+    cwd: string;
+}
+export interface Target {
+    project: Projects.Project;
+    session: SessionPaths;
+    /** true when this call created the session */
+    created: boolean;
+}
+export declare function project(want: Wanted): Promise<Projects.Project>;
+export declare function target(want: Wanted): Promise<Target>;
+/**
+ * The workspace is what the agent can read and write, so pointing it outside
+ * the session is the useful case and the dangerous one. It is confirmed once,
+ * explicitly, naming the path — and a script has to say `--yes` to skip that.
+ * An agent with file tools rooted at `$HOME` should take more than one
+ * keystroke to arrange.
+ */
+export declare function chooseWorkspace(session: SessionPaths, want: Wanted): Promise<string>;
+//# sourceMappingURL=resolve.d.ts.map