@zenera/cli 1.1.0

package/dist/session.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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 { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
+import { CliError, EXIT, invalidError, usageError } from "./term.js";
+export function sessionPaths(projectDir, id) {
+    if (!isStamp(id)) {
+        throw usageError(`"${id}" is not a session id`, 'ids look like 20260825-143012-a7f3');
+    }
+    const dir = join(sessionsDir(projectDir), id);
+    const data = join(dir, '.data');
+    return {
+        id,
+        dir,
+        workspace: join(dir, 'workspace'),
+        data,
+        state: join(data, 'state.json'),
+        memory: join(data, 'memory'),
+        blobs: join(data, 'blobs'),
+        runs: join(dir, 'runs'),
+        lock: join(dir, '.lock'),
+        meta: join(data, 'session.json'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Creating and finding
+// ---------------------------------------------------------------------------
+export function createSession(projectDir, id, workspace) {
+    const p = sessionPaths(projectDir, id);
+    mkdirSync(p.data, { recursive: true });
+    mkdirSync(p.runs, { recursive: true });
+    mkdirSync(resolve(workspace), { recursive: true });
+    const meta = {
+        version: 1,
+        id: p.id,
+        createdAt: new Date().toISOString(),
+        workspace: resolve(workspace),
+    };
+    writeJson(p.meta, meta, 0o644);
+    return p;
+}
+export async function readSessionMeta(p) {
+    const meta = await readJson(p.meta, {});
+    return {
+        version: 1,
+        id: p.id,
+        createdAt: meta.createdAt ?? new Date().toISOString(),
+        // Sessions from before the workspace was recorded fall back to their
+        // own directory, which is where it would have been.
+        workspace: meta.workspace ?? p.workspace,
+        lastRunAt: meta.lastRunAt,
+        title: meta.title,
+    };
+}
+export function writeSessionMeta(p, meta) {
+    writeJson(p.meta, meta, 0o644);
+}
+/** Newest first — the order a picker wants. */
+export async function listSessions(projectDir) {
+    const out = [];
+    for (const id of sessionIds(projectDir).reverse()) {
+        const p = sessionPaths(projectDir, id);
+        const meta = await readSessionMeta(p);
+        const ids = runIds(p.dir);
+        out.push({
+            id,
+            createdAt: meta.createdAt,
+            runs: ids.length,
+            lastRunAt: meta.lastRunAt,
+            busy: isBusy(p.dir),
+            title: meta.title,
+        });
+    }
+    return out;
+}
+export function newestSession(projectDir) {
+    return sessionIds(projectDir).at(-1);
+}
+export function requireSession(projectDir, id) {
+    const p = sessionPaths(projectDir, id);
+    if (!existsSync(p.dir)) {
+        throw invalidError(`no session ${id}`, 'see: zen list --sessions');
+    }
+    return p;
+}
+export function acquire(p) {
+    const lock = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString() };
+    const body = `${JSON.stringify(lock, null, 2)}\n`;
+    try {
+        // 'wx' fails when the file exists — the create and the check are one
+        // operation, so two `zen run`s racing cannot both win.
+        writeFileSync(p.lock, body, { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST') {
+            throw err;
+        }
+        const held = current(p);
+        if (held && alive(held.pid) && held.host === hostname()) {
+            throw new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new');
+        }
+        // Stale, or from another machine's run that cannot be verified here.
+        writeFileSync(p.lock, body);
+    }
+    let released = false;
+    const release = () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        rmSync(p.lock, { force: true });
+    };
+    return { release };
+}
+function current(p) {
+    try {
+        return JSON.parse(readFileSync(p.lock, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function runPaths(session, id) {
+    if (!isStamp(id)) {
+        throw usageError(`"${id}" is not a run id`);
+    }
+    const dir = join(session.runs, id);
+    return {
+        id,
+        dir,
+        input: join(dir, 'input.md'),
+        output: join(dir, 'output.md'),
+        state: join(dir, 'state.json'),
+        report: join(dir, 'report.html'),
+        meta: join(dir, 'meta.json'),
+    };
+}
+export function createRun(session) {
+    const p = runPaths(session, stamp());
+    mkdirSync(p.dir, { recursive: true });
+    return p;
+}
+export function writeRunMeta(p, meta) {
+    writeJson(p.meta, meta, 0o644);
+}
+export function newestRun(session) {
+    return runIds(session.dir).at(-1);
+}
+/** A path to show a human: relative when that is shorter, absolute otherwise. */
+export function display(path, from = process.cwd()) {
+    const rel = relative(from, path);
+    return !rel.startsWith('..') && rel.length < path.length ? rel || '.' : path;
+}
+//# sourceMappingURL=session.js.map

package/dist/term.d.ts

@@ -0,0 +1,69 @@
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly invalid: 3;
+    readonly credentials: 4;
+    readonly sandbox: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/**
+ * An error that already knows what it means. Anything else reaching the top is
+ * a bug and exits `failed`, which is the distinction a script needs: a wrong
+ * invocation and a wrong answer are not the same failure.
+ */
+export declare class CliError extends Error {
+    readonly code: ExitCode;
+    readonly hint?: string;
+    constructor(message: string, code?: ExitCode, hint?: string);
+}
+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 declare const bold: (s: string) => string;
+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;
+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[];
+export declare function write(line?: string): void;
+export declare function writeAll(lines: readonly string[]): void;
+/** Machine-readable output. Pretty-printed: it is read by people too. */
+export declare function json(value: unknown): void;
+export declare function note(line?: string): void;
+/**
+ * One line of narration that rewrites itself while work is in flight, so a
+ * command that waits on the network says what it is waiting for. Without a
+ * terminal there is nothing to rewrite over, so each update is its own line —
+ * which is what a CI log wants anyway.
+ */
+export declare function progress(): {
+    update: (line: string) => void;
+    done: () => void;
+};
+export declare function warn(message: string): void;
+export declare function fail(message: string, hint?: string): void;
+export declare function isInteractive(): boolean;
+export declare function ask(question: string, fallback?: string): Promise<string>;
+/**
+ * Reads without echoing. `readline` writes what you type through its `output`
+ * stream, so the interface is built without one — there is then nothing for it
+ * to echo to, and no window in which the secret is on screen.
+ */
+export declare function askSecret(question: string): Promise<string>;
+export declare function confirm(question: string, fallback?: boolean): Promise<boolean>;
+export interface Choice<T> {
+    label: string;
+    detail?: string;
+    value: T;
+}
+/** A numbered list. The pretty picker is the TUI's; this is the fallback. */
+export declare function choose<T>(title: string, choices: readonly Choice<T>[]): Promise<T>;
+/** Piped input, or undefined when stdin is a terminal (i.e. nobody piped). */
+export declare function readStdin(): Promise<string | undefined>;
+export declare function ago(iso: string | undefined): string;
+export declare function count(n: number, singular: string, plural?: string): string;
+//# sourceMappingURL=term.d.ts.map

package/dist/term.js

@@ -0,0 +1,242 @@
+import { createInterface } from 'node:readline/promises';
+import { styleText } from 'node:util';
+// ---------------------------------------------------------------------------
+// Terminal I/O
+//
+// One rule decides where everything goes: **stdout is the answer, stderr is the
+// narration.** Prompts, progress, warnings and errors are narration, so a
+// pipeline that only wants the answer gets exactly that and nothing else.
+//
+// `styleText` no-ops when the stream is not a tty and honours NO_COLOR itself,
+// so there is no flag to thread through and no piped output to garble.
+// ---------------------------------------------------------------------------
+export const EXIT = {
+    ok: 0,
+    failed: 1,
+    usage: 2,
+    invalid: 3,
+    credentials: 4,
+    sandbox: 5,
+};
+/**
+ * An error that already knows what it means. Anything else reaching the top is
+ * a bug and exits `failed`, which is the distinction a script needs: a wrong
+ * invocation and a wrong answer are not the same failure.
+ */
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(message, code = EXIT.failed, hint) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+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);
+// ---------------------------------------------------------------------------
+// Styling
+// ---------------------------------------------------------------------------
+export const bold = (s) => styleText('bold', s);
+export const dim = (s) => styleText('dim', s);
+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);
+/** 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, '');
+export function pad(s, to) {
+    return s + ' '.repeat(Math.max(0, to - width(s).length));
+}
+/** Column-aligned rows. Trailing whitespace is trimmed so `diff` stays quiet. */
+export function table(rows, gap = 2) {
+    if (rows.length === 0) {
+        return [];
+    }
+    const columns = Math.max(...rows.map((r) => r.length));
+    const widths = [];
+    for (let c = 0; c < columns; c++) {
+        widths[c] = Math.max(...rows.map((r) => width(r[c] ?? '').length));
+    }
+    return rows.map((r) => r
+        .map((cell, c) => (c === r.length - 1 ? cell : pad(cell, widths[c])))
+        .join(' '.repeat(gap))
+        .trimEnd());
+}
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+export function write(line = '') {
+    process.stdout.write(`${line}\n`);
+}
+export function writeAll(lines) {
+    for (const l of lines) {
+        write(l);
+    }
+}
+/** Machine-readable output. Pretty-printed: it is read by people too. */
+export function json(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function note(line = '') {
+    process.stderr.write(`${line}\n`);
+}
+/**
+ * One line of narration that rewrites itself while work is in flight, so a
+ * command that waits on the network says what it is waiting for. Without a
+ * terminal there is nothing to rewrite over, so each update is its own line —
+ * which is what a CI log wants anyway.
+ */
+export function progress() {
+    const tty = Boolean(process.stderr.isTTY);
+    let painted = false;
+    return {
+        update(line) {
+            if (!tty) {
+                note(line);
+                return;
+            }
+            process.stderr.write(`\r\u001b[2K${line}`);
+            painted = true;
+        },
+        done() {
+            if (painted) {
+                process.stderr.write('\r\u001b[2K');
+            }
+            painted = false;
+        },
+    };
+}
+export function warn(message) {
+    note(`${yellow('warning')} ${message}`);
+}
+export function fail(message, hint) {
+    note(`${red('error')} ${message}`);
+    if (hint) {
+        note(`        ${dim(hint)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Asking
+//
+// Every prompt below refuses to run without a terminal rather than blocking on
+// a stdin that will never answer. A CLI that hangs in CI is worse than one that
+// fails in CI, because only one of the two tells you which flag you forgot.
+// ---------------------------------------------------------------------------
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+function requireTty(what, flag) {
+    if (!isInteractive()) {
+        throw usageError(`cannot ask for ${what} without a terminal`, `pass ${flag} instead`);
+    }
+}
+export async function ask(question, fallback) {
+    requireTty(question, '--yes or the matching flag');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const suffix = fallback ? dim(` [${fallback}]`) : '';
+        const answer = (await rl.question(`${question}${suffix} `)).trim();
+        return answer || fallback || '';
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Reads without echoing. `readline` writes what you type through its `output`
+ * stream, so the interface is built without one — there is then nothing for it
+ * to echo to, and no window in which the secret is on screen.
+ */
+export async function askSecret(question) {
+    requireTty('a secret', 'a piped value on stdin');
+    process.stderr.write(`${question} `);
+    const rl = createInterface({ input: process.stdin, terminal: true });
+    try {
+        const answer = await rl.question('');
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+        process.stderr.write('\n');
+    }
+}
+export async function confirm(question, fallback = false) {
+    requireTty(question, '--yes');
+    const answer = await ask(`${question} ${dim(fallback ? '(Y/n)' : '(y/N)')}`, '');
+    if (!answer) {
+        return fallback;
+    }
+    return /^y(es)?$/i.test(answer);
+}
+/** A numbered list. The pretty picker is the TUI's; this is the fallback. */
+export async function choose(title, choices) {
+    if (choices.length === 0) {
+        throw usageError(`nothing to choose from: ${title}`);
+    }
+    if (choices.length === 1) {
+        return choices[0].value;
+    }
+    requireTty(title, 'the matching flag');
+    note(bold(title));
+    const rows = choices.map((c, i) => [`  ${dim(`${i + 1}.`)}`, c.label, dim(c.detail ?? '')]);
+    for (const line of table(rows)) {
+        note(line);
+    }
+    for (;;) {
+        const answer = await ask('Choose', '1');
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
+            return choices[n - 1].value;
+        }
+        note(dim(`Enter a number between 1 and ${choices.length}.`));
+    }
+}
+// ---------------------------------------------------------------------------
+// stdin
+// ---------------------------------------------------------------------------
+/** Piped input, or undefined when stdin is a terminal (i.e. nobody piped). */
+export async function readStdin() {
+    if (process.stdin.isTTY) {
+        return undefined;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    const text = Buffer.concat(chunks).toString('utf8').trim();
+    return text || undefined;
+}
+// ---------------------------------------------------------------------------
+// Formatting helpers shared by several commands
+// ---------------------------------------------------------------------------
+export function ago(iso) {
+    if (!iso) {
+        return 'never';
+    }
+    const then = Date.parse(iso);
+    if (Number.isNaN(then)) {
+        return 'unknown';
+    }
+    const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+    const scale = [
+        [31536000, 'y'],
+        [86400, 'd'],
+        [3600, 'h'],
+        [60, 'm'],
+    ];
+    for (const [size, unit] of scale) {
+        if (seconds >= size) {
+            return `${Math.floor(seconds / size)}${unit} ago`;
+        }
+    }
+    return seconds < 5 ? 'just now' : `${seconds}s ago`;
+}
+export function count(n, singular, plural = `${singular}s`) {
+    return `${n} ${n === 1 ? singular : plural}`;
+}
+//# sourceMappingURL=term.js.map

package/dist/tui/app.d.ts

@@ -0,0 +1,8 @@
+import * as Engine from '../engine.ts';
+export interface AppOptions {
+    readOnly: boolean;
+    /** `dark`, `light` or `auto`. Unset means `auto`. */
+    theme?: string;
+}
+export declare function start(engine: Engine.Engine, options: AppOptions): Promise<void>;
+//# sourceMappingURL=app.d.ts.map