@zenera/cli 1.1.24 → 1.1.26

package/dist/narrate.js

@@ -117,8 +117,11 @@ export function duration(ms) {
     if (ms < 60_000) {
         return `${(ms / 1000).toFixed(1)}s`;
     }
-    const minutes = Math.floor(ms / 60_000);
-    return `${minutes}m ${Math.round((ms % 60_000) / 1000)}s`;
+    const totalSeconds = Math.round(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return hours > 0 ? `${hours}h ${minutes}m ${seconds}s` : `${minutes}m ${seconds}s`;
 }
 export const stopMark = (reason) => reason === 'final' ? green('done') : reason === 'aborted' ? yellow('aborted') : red('failed');
 //# sourceMappingURL=narrate.js.map

package/dist/podman.d.ts

@@ -41,6 +41,8 @@ export interface PodmanStatus {
         swap: number;
         cpus: number;
     };
+    /** containers the engine can still create; a stopped one holds a lock too */
+    freeLocks?: number;
     image?: string;
     imagePresent?: boolean;
 }
@@ -62,6 +64,30 @@ export declare class BuildError extends CliError {
 }
 /** What `zn sandbox status` prints. Changes nothing, and never throws. */
 export declare function podmanStatus(opts?: PodmanOptions): Promise<PodmanStatus>;
+/** Containers the engine can still create; undefined when it will not say. */
+export declare function freeLocks(engine?: string, exec?: import("@zenera/neo").Runner): Promise<number | undefined>;
+export interface LockOptions {
+    engine?: string;
+    exec?: typeof runProcess;
+    /** a container that may already exist, and so needs no new lock */
+    reuses?: string;
+    /** session id -> its directory; read from the registry when absent */
+    owners?: ReadonlyMap<string, string>;
+}
+/**
+ * Refuses a run the engine cannot hold before anything is spent on it. Every
+ * container takes a lock, stopped ones included, and at zero the failure would
+ * otherwise land on the first shell command — mid-turn, or once per item.
+ */
+export declare function assertLocks(need: number, opts?: LockOptions): Promise<void>;
+/** Every session on this machine, by id, from the projects the registry knows. */
+export declare function sessionOwners(): Promise<Map<string, string>>;
+/**
+ * Containers no live process is using: every stopped one, and a running one
+ * whose run exited without tearing it down (a kill, a crash, a closed lid).
+ * A running container that cannot be traced to its owner is left alone.
+ */
+export declare function idleContainers(containers: readonly OwnedContainer[], owners: ReadonlyMap<string, string>): OwnedContainer[];
 export interface OwnedContainer {
     name: string;
     /** podman's own word: `running`, `exited`, `created`, `paused` */

package/dist/podman.js

@@ -1,7 +1,8 @@
-import { runProcess, SandboxError } from '@zenera/neo';
+import { pidAlive, runProcess, SandboxError } from '@zenera/neo';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
+import { isBusy, isProjectDir, Registry, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
@@ -409,6 +410,9 @@ export async function podmanStatus(opts = {}) {
                 cpus: Number.isFinite(cpus) ? cpus : 0,
             };
         }
+        // Asked apart from the line above: an engine without the field fails
+        // the whole template, and that must not cost the report its memory.
+        status.freeLocks = await freeLocks(engine, run);
     }
     if (opts.image) {
         status.image = opts.image;
@@ -425,6 +429,76 @@ function safeMachines(stdout) {
         return [];
     }
 }
+/** Containers the engine can still create; undefined when it will not say. */
+export async function freeLocks(engine = 'podman', exec = runProcess) {
+    const res = await exec(engine, ['info', '--format', '{{.Host.FreeLocks}}'], {
+        timeoutMs: 30_000,
+    }).catch(() => undefined);
+    const free = res?.code === 0 ? res.stdout.trim() : '';
+    return /^\d+$/.test(free) ? Number(free) : undefined;
+}
+/**
+ * Refuses a run the engine cannot hold before anything is spent on it. Every
+ * container takes a lock, stopped ones included, and at zero the failure would
+ * otherwise land on the first shell command — mid-turn, or once per item.
+ */
+export async function assertLocks(need, opts = {}) {
+    const engine = opts.engine ?? 'podman';
+    const exec = opts.exec ?? runProcess;
+    const free = await freeLocks(engine, exec);
+    if (free === undefined || free >= need) {
+        return;
+    }
+    if (opts.reuses) {
+        const there = await exec(engine, ['container', 'exists', opts.reuses], {
+            timeoutMs: 30_000,
+        }).catch(() => undefined);
+        if (there?.code === 0) {
+            return;
+        }
+    }
+    const idle = idleContainers(await ownedContainers(engine, exec), opts.owners ?? (await sessionOwners())).length;
+    throw new CliError(`the container engine has ${free} locks free and this run needs ${need} — ` +
+        'every container holds one, stopped ones included', EXIT.sandbox, idle > 0
+        ? `zen sandbox clean --idle frees ${idle}`
+        : `every container zen made is in use — \`${engine} ps --all\` shows what holds them`);
+}
+/** Every session on this machine, by id, from the projects the registry knows. */
+export async function sessionOwners() {
+    const owners = new Map();
+    for (const entry of (await Registry.open()).entries) {
+        if (isProjectDir(entry.path)) {
+            for (const id of sessionIds(entry.path)) {
+                owners.set(id, join(sessionsDir(entry.path), id));
+            }
+        }
+    }
+    return owners;
+}
+/**
+ * Containers no live process is using: every stopped one, and a running one
+ * whose run exited without tearing it down (a kill, a crash, a closed lid).
+ * A running container that cannot be traced to its owner is left alone.
+ */
+export function idleContainers(containers, owners) {
+    return containers.filter((c) => {
+        if (c.state !== 'running') {
+            return true;
+        }
+        const faker = /^faker-(\d+)$/.exec(c.key ?? '');
+        if (faker) {
+            return !pidAlive(Number(faker[1]));
+        }
+        const dir = c.key === undefined ? undefined : owners.get(c.key);
+        return dir !== undefined && !isBusy(dir);
+    });
+}
+/**
+ * `ps --format json` is ~1 kB a container, so the runner's default 64 kB cap cut
+ * the listing at about sixty, the JSON stopped parsing, and every report said
+ * "none" while two thousand sat on the machine.
+ */
+const LISTING_BYTES = 64 * 1024 * 1024;
 /**
  * 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
@@ -438,7 +512,7 @@ export async function ownedContainers(engine = 'podman', exec = runProcess, opts
     if (opts.sizes) {
         args.push('--size');
     }
-    const res = await exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
+    const res = await exec(engine, args, { timeoutMs: 120_000, maxBytes: LISTING_BYTES }).catch(() => undefined);
     if (!res || res.code !== 0) {
         return [];
     }
@@ -471,8 +545,14 @@ export async function removeContainers(names, engine = 'podman', exec = runProce
     if (names.length === 0) {
         return;
     }
-    await exec(engine, ['rm', '--force', '--volumes', ...names], { timeoutMs: 120_000 });
+    // In slices, so two thousand of them get a timeout each slice can meet.
+    for (let i = 0; i < names.length; i += REMOVE_SLICE) {
+        await exec(engine, ['rm', '--force', '--volumes', ...names.slice(i, i + REMOVE_SLICE)], {
+            timeoutMs: 120_000,
+        });
+    }
 }
+const REMOVE_SLICE = 100;
 /** 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);

package/dist/projects.d.ts

@@ -87,10 +87,5 @@ export declare function lastUsedAt(projectDir: string): string | undefined;
 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;
-/**
- * `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

@@ -1,4 +1,4 @@
-import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, pidAlive, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { paths, readJson, writeJson } from "./home.js";
@@ -290,26 +290,13 @@ export function isBusy(sessionDir) {
     const path = join(sessionDir, '.lock');
     try {
         const { pid } = JSON.parse(readFileSync(path, 'utf8'));
-        return typeof pid === 'number' && alive(pid);
+        return typeof pid === 'number' && pidAlive(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));
 }

package/dist/resources.d.ts

@@ -0,0 +1,215 @@
+import { runProcess } from '@zenera/neo';
+import { type OwnedContainer } from './podman.ts';
+type Exec = typeof runProcess;
+export interface HostProcess {
+    pid: number;
+    /** `vm` holds the machine's memory; the others run beside it */
+    role: 'vm' | 'hypervisor' | 'network';
+    name: string;
+    /** in RAM this moment */
+    rss: number;
+    /** macOS: what Activity Monitor's Memory column shows — RAM, compressed and swapped */
+    footprint?: number;
+    peak?: number;
+    /** cumulative, since it started */
+    cpuSeconds: number;
+}
+export interface GuestMemory {
+    total: number;
+    free: number;
+    available: number;
+    swapTotal: number;
+    swapFree: number;
+    cpus: number;
+}
+export interface ContainerStat {
+    id: string;
+    name: string;
+    cpuNano: number;
+    /** wall clock of the reading, in nanoseconds */
+    systemNano: number;
+    /** percent of one core, averaged over the container's whole life */
+    avgCpu: number;
+    memory: number;
+    limit: number;
+    pids: number;
+    netIn: number;
+    netOut: number;
+    blockIn: number;
+    blockOut: number;
+}
+export interface Sample {
+    at: number;
+    platform: NodeJS.Platform;
+    engine: string;
+    ready: boolean;
+    machine?: string;
+    host: {
+        memory: number;
+        cpus: number;
+        processes: HostProcess[];
+    };
+    guest?: GuestMemory;
+    stats: ContainerStat[];
+    owned: OwnedContainer[];
+    /** running containers whose zen run is gone */
+    orphans: string[];
+    /** session id -> project name */
+    projects: ReadonlyMap<string, string>;
+    problems: string[];
+}
+export interface ProcessView {
+    pid: number;
+    role: HostProcess['role'];
+    name: string;
+    /** the footprint where there is one, else what is in RAM */
+    memory: number;
+    rss: number;
+    footprint?: number;
+    peak?: number;
+    /** percent of one core over the interval; absent on the first sample */
+    cpu?: number;
+}
+export interface MachineView {
+    name?: string;
+    total: number;
+    /** held by programs: total minus available */
+    used: number;
+    /** page cache and other memory Linux gives back on demand */
+    cache: number;
+    free: number;
+    available: number;
+    swapTotal: number;
+    swapUsed: number;
+    cpus: number;
+    /**
+     * macOS counts this much for the machine beyond what anything inside uses,
+     * cache included: memory used once, freed inside, and never handed back.
+     */
+    held?: number;
+}
+export interface ContainerView {
+    name: string;
+    id: string;
+    kind: 'zen' | 'faker' | 'other';
+    project?: string;
+    orphaned: boolean;
+    /** percent of one core */
+    cpu: number;
+    /** whether `cpu` is over the last interval or the container's whole life */
+    cpuOver: 'interval' | 'lifetime';
+    memory: number;
+    /** absent when the container may use the whole machine */
+    limit?: number;
+    pids: number;
+    netIn: number;
+    netOut: number;
+    blockIn: number;
+    blockOut: number;
+    createdAt?: string;
+}
+export interface ResourceView {
+    at: string;
+    /** seconds between the two samples the cpu figures are taken over */
+    interval?: number;
+    platform: NodeJS.Platform;
+    engine: string;
+    ready: boolean;
+    host: {
+        memory: number;
+        cpus: number;
+        vm?: ProcessView;
+        helpers: ProcessView[];
+    };
+    machine?: MachineView;
+    containers: ContainerView[];
+    /** containers that exist but are not running, which cost disk and no memory */
+    stopped: number;
+    totals: {
+        running: number;
+        zen: number;
+        faker: number;
+        other: number;
+        orphaned: number;
+        memory: number;
+        cpu: number;
+    };
+    hints: string[];
+    problems: string[];
+}
+export interface SamplerOptions {
+    engine?: string;
+    exec?: Exec;
+    /** so the tests can be macOS on Linux and the other way round */
+    platform?: NodeJS.Platform;
+    /** session id -> {dir, project}; read from the registry when absent */
+    owners?: () => Promise<Owners>;
+    now?: () => number;
+}
+export interface Owners {
+    dirs: ReadonlyMap<string, string>;
+    names: ReadonlyMap<string, string>;
+}
+/** Reads one sample at a time and remembers the last, so each view has an interval. */
+export declare class ResourceSampler {
+    #private;
+    readonly engine: string;
+    constructor(opts?: SamplerOptions);
+    next(): Promise<ResourceView>;
+    sample(): Promise<Sample>;
+}
+/** Every session on this machine, by id: where it lives and which project it is in. */
+export declare function registryOwners(): Promise<Owners>;
+export declare function parseInfo(stdout: string): GuestMemory | undefined;
+export declare function parseStats(stdout: string): ContainerStat[];
+interface PsRow {
+    pid: number;
+    rss: number;
+    cpuSeconds: number;
+    ageSeconds: number;
+    command: string;
+}
+export declare function parsePs(stdout: string): PsRow[];
+/** `[[dd-]hh:]mm:ss[.cc]` — how `ps` prints both cpu time and elapsed time. */
+export declare function clock(text: string): number;
+/**
+ * Picks the machine out of every process on the host. A Mac can run more than
+ * one virtual machine through the same framework, so the Apple service and
+ * the network helper are matched to the hypervisor by when they started.
+ */
+export declare function machineProcesses(rows: readonly PsRow[]): HostProcess[];
+/** `footprint -f bytes` output: one block per process. */
+export declare function parseFootprint(stdout: string): Map<number, {
+    footprint: number;
+    peak?: number;
+}>;
+export declare function viewOf(now: Sample, before?: Sample): ResourceView;
+export type Tone = 'plain' | 'strong' | 'dim' | 'good' | 'warn' | 'bad' | 'accent' | 'heading';
+export interface Span {
+    readonly text: string;
+    readonly tone?: Tone;
+}
+export type Line = readonly Span[];
+export type Sort = 'memory' | 'cpu' | 'name';
+export declare const SORTS: readonly Sort[];
+export interface LayoutOptions {
+    width: number;
+    /** the most lines to return; containers are cut first, with a count of the rest */
+    rows?: number;
+    /** a note beside every figure saying what it means, and a sentence under each heading */
+    explain: boolean;
+    sort?: Sort;
+    /** seconds between refreshes, for the live screen's header */
+    live?: number;
+    /** wrap a long note onto the next line instead of letting the edge cut it */
+    wrapNotes?: boolean;
+    /**
+     * The sentence under each heading and the column legend. On by default
+     * with `explain`; the live screen turns it off before it cuts any figure.
+     */
+    intros?: boolean;
+}
+export declare function pct(n: number): string;
+export declare function layout(view: ResourceView, o: LayoutOptions): Line[];
+export {};
+//# sourceMappingURL=resources.d.ts.map