@zenera/cli 1.1.17 → 1.1.19

package/dist/podman.js

@@ -1,5 +1,5 @@
 import { runProcess, SandboxError } from '@zenera/neo';
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
@@ -111,9 +111,71 @@ function instructions() {
         case 'win32':
             return 'install it with: winget install RedHat.Podman';
         default:
-            return 'install it with your package manager, e.g. apt install podman';
+            return linuxInstructions();
     }
 }
+/**
+ * How podman gets installed, by distribution — podman.io/docs/installation,
+ * which is where any of these should be checked against.
+ *
+ * "Install it with your package manager" is advice nobody needs and everybody
+ * has to translate; the host already says which one it has, so the message may
+ * as well be the line to paste. It stops at the line: `sudo` wants a terminal
+ * to ask for a password on and `runProcess` gives it a pipe, so running this
+ * for the user would hang rather than help.
+ */
+const LINUX_INSTALL = {
+    alpine: 'install it with: sudo apk add podman',
+    arch: 'install it with: sudo pacman -S podman',
+    centos: 'install it with: sudo dnf -y install podman',
+    debian: 'install it with: sudo apt-get -y install podman',
+    fedora: 'install it with: sudo dnf -y install podman',
+    gentoo: 'install it with: sudo emerge app-containers/podman',
+    // Nix installs nothing imperatively worth keeping: the podman that works
+    // rootless is the one the module turns on.
+    nixos: 'enable it with: virtualisation.podman.enable = true; then: sudo nixos-rebuild switch',
+    opensuse: 'install it with: sudo zypper install podman',
+    rhel: 'install it with: sudo dnf -y install podman',
+    sles: 'install it with: sudo zypper install podman',
+    suse: 'install it with: sudo zypper install podman',
+    ubuntu: 'install it with: sudo apt-get update && sudo apt-get -y install podman',
+    void: 'install it with: sudo xbps-install -S podman',
+};
+function linuxInstructions() {
+    for (const id of osRelease()) {
+        // `opensuse-leap` and `rhel-9` name the same package manager as their
+        // family does, so a miss on the whole id is worth one on its stem.
+        const how = LINUX_INSTALL[id] ?? LINUX_INSTALL[id.split(/[-.]/)[0] ?? ''];
+        if (how) {
+            return how;
+        }
+    }
+    return 'install it with your package manager, e.g. apt-get install podman';
+}
+/**
+ * `ID` first, then `ID_LIKE` — the distribution's own name, then the families
+ * it claims to behave like, which is how Rocky, Alma and Mint get answered
+ * without being listed.
+ */
+function osRelease() {
+    let text;
+    try {
+        text = readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const read = (key) => {
+        const line = new RegExp(`^${key}=(.*)$`, 'm').exec(text)?.[1] ?? '';
+        return line
+            .trim()
+            .replace(/^["']|["']$/g, '')
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(Boolean);
+    };
+    return [...read('ID'), ...read('ID_LIKE')];
+}
 // ---------------------------------------------------------------------------
 // The machine
 // ---------------------------------------------------------------------------

package/dist/projects.d.ts

@@ -16,7 +16,7 @@ export interface Project {
  * 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[];
+export declare function projectMounts(root: string, config: ProjectConfig, memoryAt?: string): 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>;
@@ -70,6 +70,14 @@ 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[];
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export declare function lastUsedAt(projectDir: string): string | undefined;
 /**
  * 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

package/dist/projects.js

@@ -35,7 +35,7 @@ export function isProjectDir(dir) {
  * 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) {
+export function projectMounts(root, config, memoryAt) {
     const mounts = [];
     const assets = assetsDir(root, config);
     if (assets) {
@@ -47,7 +47,7 @@ export function projectMounts(root, config) {
     for (const dir of skillMounts(skillDirs(root, config), SKILLS_MOUNT)) {
         mounts.push({ host: realpathSync(dir.path), at: dir.at, readOnly: true });
     }
-    const memory = memoryDir(root, config);
+    const memory = memoryDir(root, config, memoryAt);
     if (memory) {
         // Created here because the mount is decided before the project is
         // loaded, and podman would refuse a source that does not exist yet.
@@ -224,6 +224,23 @@ export function sessionIds(projectDir) {
 export function runIds(sessionDir) {
     return stampedChildren(join(sessionDir, 'runs'));
 }
+/**
+ * When this project was last worked in, as a stamp, or `undefined` for one
+ * that never has been. Session and run ids are stamps in the same format, so
+ * the newest of either compares directly — and reading directory NAMES is what
+ * keeps this cheap enough to ask of every registered project before drawing a
+ * chooser.
+ */
+export function lastUsedAt(projectDir) {
+    let last;
+    for (const id of sessionIds(projectDir)) {
+        const newest = runIds(join(sessionsDir(projectDir), id)).at(-1) ?? id;
+        if (!last || newest > last) {
+            last = newest;
+        }
+    }
+    return last;
+}
 function stampedChildren(dir) {
     if (!existsSync(dir)) {
         return [];

package/dist/resolve.js

@@ -23,7 +23,13 @@ export async function project(want) {
     if (!isInteractive()) {
         throw usageError('not inside a project', 'name one with --project');
     }
-    const chosen = await choose('Which project?', known.map((e) => ({ label: e.name, detail: e.path, value: e })));
+    // Most recently worked in first: the answer to "which project" is nearly
+    // always the one from last time, and registration order is nothing to a
+    // person. A project never run sorts last, by name.
+    const ranked = known
+        .map((entry) => ({ entry, used: Projects.lastUsedAt(entry.path) ?? '' }))
+        .sort((a, b) => b.used.localeCompare(a.used) || a.entry.name.localeCompare(b.entry.name));
+    const chosen = await choose('Which project?', ranked.map(({ entry }) => ({ label: entry.name, detail: entry.path, value: entry })));
     return Projects.openDir(chosen.path);
 }
 // ---------------------------------------------------------------------------

package/dist/sandbox.d.ts

@@ -10,6 +10,8 @@ export interface SandboxSetup {
     build?: ResolvedBuild;
     /** host side of the container's `$HOME`, created only if it is ever needed */
     home: string;
+    /** every tree bound into the container besides the workspace itself */
+    mounts: readonly SandboxMount[];
 }
 export interface SandboxInputs {
     config: ProjectConfig;

package/dist/sandbox.js

@@ -103,7 +103,7 @@ export function buildSandbox(opts) {
         readOnly: opts.readOnly,
         mounts,
     });
-    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home };
+    return { pool, spec, image: spec.image ?? DEFAULT_SANDBOX_IMAGE, build, home, mounts };
 }
 /**
  * An agent's overrides on the project's block. `image` and `build` answer the

package/dist/scaffold.js

@@ -244,7 +244,7 @@ export function scaffold(opts) {
     mkdirSync(join(opts.dir, 'agents', 'skills'), { recursive: true });
     mkdirSync(join(opts.dir, 'sessions'), { recursive: true });
     mkdirSync(join(opts.dir, '.tmp'), { recursive: true });
-    // Where `/sync-with-spec` records what it applied, so the next pass works
+    // Where `/spec-sync-project` records what it applied, so the next pass works
     // the difference rather than the whole specification again. Empty here, and
     // git does not carry an empty directory: what says a pass has completed is
     // `baseline/manifest.txt`, never the directory itself.

package/dist/session.d.ts

@@ -71,6 +71,16 @@ export interface RunMeta {
     error?: string;
 }
 export declare function writeRunMeta(p: RunPaths, meta: RunMeta): void;
+export interface RunSummary {
+    id: string;
+    startedAt?: string;
+    finishedAt?: string;
+    agent?: string;
+    stopReason?: string;
+    error?: string;
+}
+/** Newest first — the order a picker wants. */
+export declare function listRuns(session: SessionPaths): Promise<RunSummary[]>;
 export declare function newestRun(session: SessionPaths): string | undefined;
 /** A path to show a human: relative when that is shorter, absolute otherwise. */
 export declare function display(path: string, from?: string): string;

package/dist/session.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { hostname } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
-import { isStamp, stamp } from "./ids.js";
+import { isStamp, stamp, stampInstant } from "./ids.js";
 import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
@@ -145,6 +145,24 @@ export function createRun(session) {
 export function writeRunMeta(p, meta) {
     writeJson(p.meta, meta, 0o644);
 }
+/** Newest first — the order a picker wants. */
+export async function listRuns(session) {
+    const out = [];
+    for (const id of runIds(session.dir).reverse()) {
+        // A run killed before it recorded anything still has an id, and the id
+        // says when it started, so it is listable without its meta.
+        const meta = await readJson(runPaths(session, id).meta, {});
+        out.push({
+            id,
+            startedAt: meta.startedAt ?? stampInstant(id),
+            finishedAt: meta.finishedAt,
+            agent: meta.agent,
+            stopReason: meta.stopReason,
+            error: meta.error,
+        });
+    }
+    return out;
+}
 export function newestRun(session) {
     return runIds(session.dir).at(-1);
 }

package/dist/term.d.ts

@@ -20,12 +20,33 @@ export declare class CliError extends Error {
 export declare const usageError: (m: string, hint?: string) => CliError;
 export declare const invalidError: (m: string, hint?: string) => CliError;
 export declare const credentialError: (m: string, hint?: string) => CliError;
+export type Appearance = 'dark' | 'light';
+/** One grey per background. The only 256-colour indices in the CLI. */
+export declare const CHROME: Record<Appearance, number>;
+/** What the terminal looks like, as far as can be known without asking it. */
+export declare function appearance(): Appearance;
 export declare const bold: (s: string) => string;
+/**
+ * One step quieter, which is half of everything this tool prints: paths,
+ * counts, hints, the second column of every table.
+ *
+ * A stated grey rather than SGR 2. `dim` is not a colour, it is a request, and
+ * how far it is honoured is the terminal's own business — iTerm2 takes a step,
+ * Apple Terminal goes most of the way to the background and takes the quiet
+ * half of the output with it.
+ */
 export declare const dim: (s: string) => string;
 export declare const red: (s: string) => string;
 export declare const green: (s: string) => string;
 export declare const yellow: (s: string) => string;
 export declare const cyan: (s: string) => string;
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export declare const styled: () => boolean;
+/** The text as it reads without styling, which is what a file wants. */
+export declare const plain: (s: string) => string;
 export declare function pad(s: string, to: number): string;
 /** Column-aligned rows. Trailing whitespace is trimmed so `diff` stays quiet. */
 export declare function table(rows: readonly (readonly string[])[], gap?: number): string[];

package/dist/term.js

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { styleText } from 'node:util';
 // ---------------------------------------------------------------------------
@@ -36,19 +37,90 @@ export class CliError extends Error {
 export const usageError = (m, hint) => new CliError(m, EXIT.usage, hint);
 export const invalidError = (m, hint) => new CliError(m, EXIT.invalid, hint);
 export const credentialError = (m, hint) => new CliError(m, EXIT.credentials, hint);
+/** One grey per background. The only 256-colour indices in the CLI. */
+export const CHROME = { dark: 245, light: 242 };
+let sniffed;
+/** What the terminal looks like, as far as can be known without asking it. */
+export function appearance() {
+    sniffed ??= fromEnv() ?? fromColorFgBg() ?? fromAppleTerminal() ?? 'dark';
+    return sniffed;
+}
+function fromEnv() {
+    const v = process.env['ZENERA_THEME']?.trim().toLowerCase();
+    return v === 'dark' || v === 'light' ? v : undefined;
+}
+/**
+ * `COLORFGBG` is `fg;bg` or `fg;<something>;bg`; the background is the last
+ * field. Anything non-numeric (notably `default`) tells us nothing.
+ */
+function fromColorFgBg() {
+    const parts = process.env['COLORFGBG']?.split(';');
+    const bg = parts?.[parts.length - 1];
+    if (bg === undefined || !/^\d+$/.test(bg)) {
+        return undefined;
+    }
+    const n = Number(bg);
+    return n === 7 || n >= 9 ? 'light' : 'dark';
+}
+/** The shipped Apple Terminal profiles that are paper rather than ink. */
+const APPLE_LIGHT = new Set(['basic', 'man page', 'novel', 'silver aerogel']);
+/**
+ * Ask `defaults` which profile Terminal.app opens with. A subprocess during
+ * startup is a real cost, so it is paid last, once per process, and only on
+ * the one terminal that leaves us nothing else to go on. A custom profile is
+ * not in the table and falls through to the guess.
+ */
+function fromAppleTerminal() {
+    if (process.env['TERM_PROGRAM'] !== 'Apple_Terminal') {
+        return undefined;
+    }
+    try {
+        const name = execFileSync('defaults', ['read', 'com.apple.Terminal', 'Default Window Settings'], { encoding: 'utf8', timeout: 300, stdio: ['ignore', 'pipe', 'ignore'] })
+            .trim()
+            .toLowerCase();
+        return APPLE_LIGHT.has(name) ? 'light' : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Styling
 // ---------------------------------------------------------------------------
 export const bold = (s) => styleText('bold', s);
-export const dim = (s) => styleText('dim', s);
+/**
+ * One step quieter, which is half of everything this tool prints: paths,
+ * counts, hints, the second column of every table.
+ *
+ * A stated grey rather than SGR 2. `dim` is not a colour, it is a request, and
+ * how far it is honoured is the terminal's own business — iTerm2 takes a step,
+ * Apple Terminal goes most of the way to the background and takes the quiet
+ * half of the output with it.
+ */
+export const dim = (s) => {
+    if (!styled()) {
+        return s;
+    }
+    const open = `\u001b[38;5;${CHROME[appearance()]}m`;
+    // A colour nested inside closes with `39m`, which would drop the grey for
+    // whatever follows it.
+    return `${open}${s.replaceAll('\u001b[39m', `\u001b[39m${open}`)}\u001b[39m`;
+};
 export const red = (s) => styleText('red', s);
 export const green = (s) => styleText('green', s);
 export const yellow = (s) => styleText('yellow', s);
 export const cyan = (s) => styleText('cyan', s);
+/**
+ * Whether anything should be coloured at all — `styleText`'s own answer, asked
+ * by the places that write escape codes directly and so cannot inherit it.
+ */
+export const styled = () => styleText('dim', '.') !== '.';
 /** Visible width — style codes must not count towards column alignment. */
 // eslint-disable-next-line no-control-regex
 const ANSI = /\u001b\[[0-9;]*m/g;
-const width = (s) => s.replace(ANSI, '');
+/** The text as it reads without styling, which is what a file wants. */
+export const plain = (s) => s.replace(ANSI, '');
+const width = plain;
 export function pad(s, to) {
     return s + ' '.repeat(Math.max(0, to - width(s).length));
 }