@jevitate/cli 0.1.0 → 0.3.0

package/dist/log-sources.js

@@ -0,0 +1,236 @@
+import { spawn } from "node:child_process";
+import { createReadStream, statSync } from "node:fs";
+import { clock } from "@jevitate/domain";
+export class LogSourceSpecError extends Error {
+    code = "E_LOG_SOURCE_SPEC";
+    constructor(message) {
+        super(message);
+        this.name = "LogSourceSpecError";
+    }
+}
+/** Parses one `--log-source` value. Throws `LogSourceSpecError` on an unrecognized/empty spec. */
+export function parseLogSourceSpec(raw) {
+    const i = raw.indexOf(":");
+    if (i < 0)
+        throw new LogSourceSpecError(`--log-source must be file:<path>, docker:<container> or cmd:<command>: got ${JSON.stringify(raw)}`);
+    const kind = raw.slice(0, i);
+    const rest = raw.slice(i + 1);
+    if (rest.trim() === "")
+        throw new LogSourceSpecError(`--log-source ${kind}: missing value`);
+    if (kind === "file")
+        return { kind: "file", path: rest, raw };
+    if (kind === "docker")
+        return { kind: "docker", container: rest, raw };
+    if (kind === "cmd")
+        return { kind: "cmd", command: rest, raw };
+    throw new LogSourceSpecError(`--log-source: unknown source kind ${JSON.stringify(kind)} (want file:, docker: or cmd:)`);
+}
+/**
+ * Validates every spec up front, INCLUDING the `cmd:` + `--allow-log-cmd` gate — so a run refuses
+ * before any browser opens, the same fail-closed discipline as `--invariants`.
+ */
+export function parseLogSourceSpecs(raw, allowLogCmd) {
+    const specs = raw.map(parseLogSourceSpec);
+    for (const s of specs) {
+        if (s.kind === "cmd" && !allowLogCmd) {
+            throw new LogSourceSpecError(`--log-source ${s.raw} needs --allow-log-cmd (an operator-declared command is run as a subprocess)`);
+        }
+    }
+    return specs;
+}
+const DEFAULT_MAX_LINES = 20_000;
+const DEFAULT_FILE_POLL_MS = 250;
+function lineSplitter(onLine) {
+    let carry = "";
+    return (chunk) => {
+        carry += chunk.toString("utf8");
+        const lines = carry.split(/\r?\n/);
+        carry = lines.pop() ?? "";
+        for (const line of lines)
+            if (line !== "")
+                onLine(line, clock.now());
+    };
+}
+function boundedOnLine(handle, opts) {
+    const max = opts.maxLines ?? DEFAULT_MAX_LINES;
+    return (raw, epochMs) => {
+        if (handle.linesRead >= max) {
+            handle.truncated = true;
+            return;
+        }
+        handle.linesRead += 1;
+        opts.onLine(raw, epochMs);
+    };
+}
+/**
+ * `file:` — tails from the CURRENT end by polling the file's size (no `fs.watch`: flaky across
+ * filesystems, notably over WSL's `/mnt/c` drvfs — AGENTS.md). Handles truncation/rotation, AND a
+ * file that does not exist yet at open time (a backend that has not logged anything until later in
+ * the run is the common case, not an error): if the file already exists, its EXISTING content is
+ * history and skipped (`position` starts at its current size); if it does not exist yet, nothing
+ * can predate this run, so `position` starts at 0 and the first line written after the source
+ * opened is the first one delivered, however long the file takes to appear.
+ */
+function openFileSource(spec, opts) {
+    let closed = false;
+    let timer;
+    let position = 0;
+    const handle = {
+        spec,
+        opened: false,
+        linesRead: 0,
+        truncated: false,
+        close: async () => {
+            closed = true;
+            if (timer !== undefined)
+                clock.clearInterval(timer);
+            if (!handle.opened)
+                handle.error = `${spec.path}: never appeared during the run`;
+        },
+        killSync: () => {
+            closed = true;
+            if (timer !== undefined)
+                clock.clearInterval(timer);
+        },
+    };
+    const deliver = lineSplitter(boundedOnLine(handle, opts));
+    try {
+        // The file already exists: its content predates this source and is skipped (never replayed).
+        position = statSync(spec.path).size;
+        handle.opened = true;
+    }
+    catch {
+        // Does not exist yet: `position` stays 0, so whatever is written once it appears is ALL new.
+    }
+    const poll = () => {
+        if (closed)
+            return;
+        let size;
+        try {
+            size = statSync(spec.path).size;
+        }
+        catch {
+            return; // still not there, or a transient stat failure — the next poll tries again
+        }
+        handle.opened = true; // confirmed readable now, even if it appeared after the initial check
+        if (size <= position) {
+            if (size < position)
+                position = 0; // truncated/rotated: resume from the new start
+            return;
+        }
+        const stream = createReadStream(spec.path, { start: position, end: size - 1 });
+        stream.on("data", (chunk) => deliver(chunk));
+        stream.on("error", () => undefined);
+        position = size;
+    };
+    timer = clock.setInterval(poll, opts.filePollMs ?? DEFAULT_FILE_POLL_MS);
+    timer.unref?.();
+    return handle;
+}
+/** Kills a spawned child's whole process GROUP (POSIX): `docker logs`/`cmd:`'s own children die
+ *  too, not just the immediate process. Falls back to killing just the child if the group send fails. */
+function killGroup(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+function openProcessSource(spec, command, args, opts, useShell) {
+    let child;
+    // #199: set the moment WE ask the child to stop (mission end) — BEFORE `killGroup` sends the
+    // signal, so the (always-async) `exit` event below, whenever it lands, can tell "we stopped this"
+    // from "it died on its own". A source jevitate stopped itself is a normal end of tailing, not a
+    // failure, no matter what exit code the child reports for its own signal handling (a `docker logs
+    // -f`/`cmd:` child commonly self-exits 143 for SIGTERM rather than dying to the raw signal).
+    let stopRequested = false;
+    const handle = {
+        spec,
+        opened: false,
+        linesRead: 0,
+        truncated: false,
+        close: async () => {
+            stopRequested = true;
+            if (child === undefined)
+                return;
+            killGroup(child);
+            await new Promise((resolve) => {
+                if (child === undefined || child.exitCode !== null || child.signalCode !== null) {
+                    resolve();
+                    return;
+                }
+                const done = () => resolve();
+                child.once("exit", done);
+                const t = clock.setTimeout(done, 2000);
+                t.unref?.();
+            });
+        },
+        killSync: () => {
+            stopRequested = true;
+            if (child !== undefined)
+                killGroup(child);
+        },
+    };
+    try {
+        child = spawn(command, args, { detached: true, shell: useShell, stdio: ["ignore", "pipe", "pipe"] });
+    }
+    catch (e) {
+        handle.error = `cannot start ${spec.raw}: ${e instanceof Error ? e.message : String(e)}`;
+        return handle;
+    }
+    handle.opened = true;
+    const deliver = lineSplitter(boundedOnLine(handle, opts));
+    child.stdout.on("data", deliver);
+    child.stderr.on("data", deliver); // most backends interleave logs on stderr too (docker logs does)
+    child.on("error", (e) => {
+        handle.error = `${spec.raw}: ${e.message}`;
+    });
+    // Startup health check (#169): `docker logs -f <container>` on a container that isn't running (or
+    // doesn't exist) exits almost immediately with a non-zero code — its stderr ("Error: No such
+    // container: …") would otherwise just look like an ordinary, if odd, log line and count toward
+    // `linesRead`, hiding the failure. An early non-zero exit is decisive regardless of what was piped
+    // through in the meantime: this source was never actually tailing the backend.
+    //
+    // #199: BUT only when the child died on its own. `close()`/`killSync()` set `stopRequested` before
+    // signaling, so an exit that lands after WE asked this source to stop (mission end) is a normal
+    // end of tailing — never a failure, whatever code/signal the child reports for handling its own
+    // termination (SIGTERM commonly comes back as a self-reported exit code like 143, not `signal`).
+    child.on("exit", (code, signal) => {
+        if (stopRequested)
+            return;
+        if (code !== null && code !== 0 && handle.error === undefined) {
+            handle.error = `${spec.raw}: exited with code ${code}${signal === null ? "" : ` (signal ${signal})`} — the source may not be running`;
+        }
+    });
+    child.unref();
+    return handle;
+}
+/**
+ * Opens one already-validated `--log-source`. Never throws: an unreadable/unspawnable source comes
+ * back with `.error` set rather than aborting a run that has other sources (the caller decides
+ * whether that's fatal — a `--log-defect` oracle must not count an unreadable source as "held").
+ */
+export function openLogSource(spec, opts) {
+    if (spec.kind === "file")
+        return openFileSource(spec, opts);
+    if (spec.kind === "docker")
+        return openProcessSource(spec, "docker", ["logs", "-f", "--since", "0s", spec.container], opts, false);
+    return openProcessSource(spec, spec.command, [], opts, true);
+}
+export function openLogSources(specs, opts) {
+    return specs.map((spec) => openLogSource(spec, opts));
+}
+/** Closes every handle, best-effort, in parallel. Never throws. */
+export async function closeLogSources(handles) {
+    await Promise.all(handles.map((h) => h.close().catch(() => undefined)));
+}
+//# sourceMappingURL=log-sources.js.map

package/dist/log-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-sources.js","sourceRoot":"","sources":["../src/log-sources.ts"],"names":[],"mappings":"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"}

package/dist/log-trace.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Request ↔ backend-log correlation by TRACE / CORRELATION ID (#204), instead of by time window.
+ *
+ * The browser side (`RequestIdLedger`) records, for every request the run's page sends, the ids it
+ * carries: W3C `traceparent` (its trace-id), `x-request-id`, `x-correlation-id`, `request-id`,
+ * `x-amzn-trace-id` (its `Root`), `x-b3-traceid`, `x-cloud-trace-context` (its trace) — on the
+ * REQUEST (a frontend with OpenTelemetry) or the RESPONSE (a server-generated request id) — plus
+ * any operator-named header (`--log-correlation-header`). The log side (`lineIds`) finds those
+ * ids in a backend log line: any whitespace/punctuation-delimited token equal to a recorded id
+ * (exact — never a prefix or a substring of a longer token).
+ *
+ * `ServerLogRuntime` then attaches a line that carries a run's id to EXACTLY that request (method,
+ * URL, status) and to the step that sent it — whatever time the line landed — and falls back to the
+ * time window only for lines with no id. Once ids demonstrably correlate (at least one line matched
+ * a run's id), a line carrying a DIFFERENT id (`foreignIds`: a `trace_id=`/`request_id=` key, a
+ * `traceparent`, or an operator `--log-id-pattern`) belongs to other work — another user, a
+ * background job — and is never attributed to this run.
+ *
+ * Ids are not secrets, but every URL is redacted and every attached line is redacted with the run's
+ * secrets, as before.
+ */
+/** Headers whose value identifies a request across the browser and the backend (lower-case). */
+export declare const DEFAULT_CORRELATION_HEADERS: readonly string[];
+/** The correlation id(s) a header value carries. */
+export declare function idsFromHeader(name: string, value: string): string[];
+/** One request the run's page sent, with the ids that identify it to the backend. */
+export interface CorrelatedRequest {
+    readonly method: string;
+    /** Redacted URL (the shared `redactUrl` rule). */
+    readonly url: string;
+    /** The response status; null while (or if never) answered. */
+    status: number | null;
+    /** When it was sent (epoch ms). */
+    readonly startedAtMs: number;
+    readonly ids: string[];
+}
+/** The page surface the ledger listens on (Playwright's `Page`, structurally). */
+export interface RequestEvents {
+    on(event: "request", fn: (r: LedgerRequest) => void): unknown;
+    on(event: "response", fn: (r: {
+        request(): LedgerRequest;
+        status(): number;
+        headers(): Record<string, string>;
+    }) => void): unknown;
+}
+export interface LedgerRequest {
+    url(): string;
+    method(): string;
+    headers(): Record<string, string>;
+}
+/** Validates `--log-correlation-header` names (fails closed on the first bad one). */
+export declare function parseCorrelationHeaders(raw: readonly string[]): string[];
+/**
+ * Parses `--log-id-pattern` values: `/regex/flags` whose first capture group (or whole match) is a
+ * correlation id in a log line of the operator's own format. Bounded and compiled once.
+ */
+export declare function parseLogIdPatterns(raw: readonly string[]): RegExp[];
+/** Records every request a run's page sends with its correlation ids (#204). */
+export declare class RequestIdLedger {
+    #private;
+    constructor(opts?: {
+        readonly headers?: readonly string[];
+        readonly now?: () => number;
+    });
+    /** Starts listening on a page (call before its first navigation). */
+    observe(page: RequestEvents): void;
+    /** How many requests carried at least one id. */
+    get requestsWithIds(): number;
+    /** The request a log line belongs to (by an id it carries), or undefined. */
+    requestFor(raw: string): {
+        readonly request: CorrelatedRequest;
+        readonly id: string;
+    } | undefined;
+}
+/**
+ * The correlation ids a log line DECLARES (#204): a keyed id (`trace_id=`, `"requestId":`, …), a
+ * `traceparent`, or an operator `--log-id-pattern` match. Used to tell another request's line
+ * (foreign) from one with no id at all (time-window fallback).
+ */
+export declare function declaredIds(raw: string, patterns?: readonly RegExp[]): string[];

package/dist/log-trace.js

@@ -0,0 +1,210 @@
+import { redactUrl } from "@jevitate/ai-core";
+import { LogSpecError } from "./log-lines.js";
+import { clock } from "@jevitate/domain";
+/**
+ * Request ↔ backend-log correlation by TRACE / CORRELATION ID (#204), instead of by time window.
+ *
+ * The browser side (`RequestIdLedger`) records, for every request the run's page sends, the ids it
+ * carries: W3C `traceparent` (its trace-id), `x-request-id`, `x-correlation-id`, `request-id`,
+ * `x-amzn-trace-id` (its `Root`), `x-b3-traceid`, `x-cloud-trace-context` (its trace) — on the
+ * REQUEST (a frontend with OpenTelemetry) or the RESPONSE (a server-generated request id) — plus
+ * any operator-named header (`--log-correlation-header`). The log side (`lineIds`) finds those
+ * ids in a backend log line: any whitespace/punctuation-delimited token equal to a recorded id
+ * (exact — never a prefix or a substring of a longer token).
+ *
+ * `ServerLogRuntime` then attaches a line that carries a run's id to EXACTLY that request (method,
+ * URL, status) and to the step that sent it — whatever time the line landed — and falls back to the
+ * time window only for lines with no id. Once ids demonstrably correlate (at least one line matched
+ * a run's id), a line carrying a DIFFERENT id (`foreignIds`: a `trace_id=`/`request_id=` key, a
+ * `traceparent`, or an operator `--log-id-pattern`) belongs to other work — another user, a
+ * background job — and is never attributed to this run.
+ *
+ * Ids are not secrets, but every URL is redacted and every attached line is redacted with the run's
+ * secrets, as before.
+ */
+/** Headers whose value identifies a request across the browser and the backend (lower-case). */
+export const DEFAULT_CORRELATION_HEADERS = [
+    "traceparent",
+    "x-request-id",
+    "x-correlation-id",
+    "request-id",
+    "x-amzn-trace-id",
+    "x-b3-traceid",
+    "x-cloud-trace-context",
+];
+/** An id shorter than this would match unrelated tokens (a "1", a "200"): never used. */
+const MIN_ID_CHARS = 8;
+const MAX_ID_CHARS = 128;
+const ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const TRACEPARENT = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/i;
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+/** Most requests the ledger keeps (the oldest are dropped past it). */
+const MAX_REQUESTS = 5_000;
+/** Normalizes an id for comparison (hex trace ids are case-insensitive in practice). */
+const norm = (id) => id.toLowerCase();
+function usable(id) {
+    const v = id.trim();
+    if (v.length < MIN_ID_CHARS || v.length > MAX_ID_CHARS || !ID_SHAPE.test(v))
+        return null;
+    // An all-zero trace id is the W3C "invalid" value: it identifies nothing.
+    if (/^0+$/.test(v.replace(/[-:.]/g, "")))
+        return null;
+    return v;
+}
+/** The correlation id(s) a header value carries. */
+export function idsFromHeader(name, value) {
+    const n = name.toLowerCase();
+    const v = value.trim();
+    let candidates;
+    if (n === "traceparent") {
+        const m = TRACEPARENT.exec(v);
+        candidates = m === null ? [] : [m[1]];
+    }
+    else if (n === "x-amzn-trace-id") {
+        const root = /(?:^|;)\s*Root=([^;]+)/i.exec(v);
+        candidates = root === null ? [] : [root[1]];
+    }
+    else if (n === "x-cloud-trace-context") {
+        candidates = [v.split("/")[0] ?? ""];
+    }
+    else {
+        candidates = v.split(",").map((s) => s.trim());
+    }
+    return candidates.map(usable).filter((x) => x !== null);
+}
+/** Validates `--log-correlation-header` names (fails closed on the first bad one). */
+export function parseCorrelationHeaders(raw) {
+    return raw.map((h) => {
+        const v = h.trim().toLowerCase();
+        if (!HEADER_NAME.test(v))
+            throw new LogSpecError(`--log-correlation-header: not a header name: ${JSON.stringify(h)}`);
+        return v;
+    });
+}
+/**
+ * Parses `--log-id-pattern` values: `/regex/flags` whose first capture group (or whole match) is a
+ * correlation id in a log line of the operator's own format. Bounded and compiled once.
+ */
+export function parseLogIdPatterns(raw) {
+    return raw.map((p) => {
+        const m = /^\/(.+)\/([a-z]*)$/s.exec(p);
+        if (m === null)
+            throw new LogSpecError(`--log-id-pattern must be /regex/flags, got ${JSON.stringify(p)}`);
+        if (m[1].length > 500)
+            throw new LogSpecError("--log-id-pattern is too long (max 500 chars)");
+        try {
+            const flags = m[2].replace(/[gy]/g, "");
+            return new RegExp(m[1], `${flags}g`);
+        }
+        catch (e) {
+            throw new LogSpecError(`--log-id-pattern: invalid regex ${JSON.stringify(p)}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+}
+/** Records every request a run's page sends with its correlation ids (#204). */
+export class RequestIdLedger {
+    #headers;
+    #now;
+    #byRequest = new WeakMap();
+    #byId = new Map();
+    #requests = [];
+    constructor(opts = {}) {
+        this.#headers = new Set([...DEFAULT_CORRELATION_HEADERS, ...(opts.headers ?? []).map((h) => h.toLowerCase())]);
+        this.#now = opts.now ?? clock.now;
+    }
+    /** Starts listening on a page (call before its first navigation). */
+    observe(page) {
+        page.on("request", (r) => {
+            let rec;
+            let headers;
+            try {
+                rec = { method: r.method().toUpperCase(), url: redactUrl(r.url()), status: null, startedAtMs: this.#now(), ids: [] };
+                headers = r.headers();
+            }
+            catch {
+                return; // a request whose page is already gone: nothing to correlate
+            }
+            this.#byRequest.set(r, rec);
+            this.#requests.push(rec);
+            if (this.#requests.length > MAX_REQUESTS) {
+                const old = this.#requests.shift();
+                for (const id of old?.ids ?? [])
+                    if (this.#byId.get(norm(id)) === old)
+                        this.#byId.delete(norm(id));
+            }
+            this.#addIds(rec, headers);
+        });
+        page.on("response", (res) => {
+            try {
+                const rec = this.#byRequest.get(res.request());
+                if (rec === undefined)
+                    return;
+                rec.status = res.status();
+                this.#addIds(rec, res.headers());
+            }
+            catch {
+                // a response whose page is already gone: nothing more to learn
+            }
+        });
+    }
+    #addIds(rec, headers) {
+        for (const [name, value] of Object.entries(headers)) {
+            if (!this.#headers.has(name.toLowerCase()))
+                continue;
+            for (const id of idsFromHeader(name, value)) {
+                if (rec.ids.includes(id))
+                    continue;
+                rec.ids.push(id);
+                // The same id on two requests (a trace spanning several calls): the first sender owns it.
+                if (!this.#byId.has(norm(id)))
+                    this.#byId.set(norm(id), rec);
+            }
+        }
+    }
+    /** How many requests carried at least one id. */
+    get requestsWithIds() {
+        return this.#requests.filter((r) => r.ids.length > 0).length;
+    }
+    /** The request a log line belongs to (by an id it carries), or undefined. */
+    requestFor(raw) {
+        if (this.#byId.size === 0)
+            return undefined;
+        for (const token of tokens(raw)) {
+            const hit = this.#byId.get(norm(token));
+            if (hit !== undefined)
+                return { request: hit, id: token };
+            const tp = TRACEPARENT.exec(token);
+            if (tp !== null) {
+                const t = this.#byId.get(norm(tp[1]));
+                if (t !== undefined)
+                    return { request: t, id: tp[1] };
+            }
+        }
+        return undefined;
+    }
+}
+/** The tokens of a log line an id can be (delimited by anything an id cannot contain). */
+function tokens(raw) {
+    return raw.split(/[^A-Za-z0-9._:-]+/).filter((t) => t.length >= MIN_ID_CHARS && t.length <= 200);
+}
+/** Built-in id keys: `trace_id=…`, `"traceId": "…"`, `request-id: …`, `correlationId=…`, `x-request-id=…`. */
+const KEYED_ID = /(?:^|[^A-Za-z0-9])(?:x-)?(?:trace|request|req|correlation|corr)[_.-]?id["']?\s*[:=]\s*["']?([A-Za-z0-9][A-Za-z0-9._:-]{7,127})/gi;
+const TRACEPARENT_IN_TEXT = /\b[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}\b/gi;
+/**
+ * The correlation ids a log line DECLARES (#204): a keyed id (`trace_id=`, `"requestId":`, …), a
+ * `traceparent`, or an operator `--log-id-pattern` match. Used to tell another request's line
+ * (foreign) from one with no id at all (time-window fallback).
+ */
+export function declaredIds(raw, patterns = []) {
+    const out = new Set();
+    for (const re of [KEYED_ID, TRACEPARENT_IN_TEXT, ...patterns]) {
+        re.lastIndex = 0;
+        for (const m of raw.matchAll(re)) {
+            const id = usable(m[1] ?? m[0]);
+            if (id !== null)
+                out.add(id);
+        }
+    }
+    return [...out];
+}
+//# sourceMappingURL=log-trace.js.map

package/dist/log-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-trace.js","sourceRoot":"","sources":["../src/log-trace.ts"],"names":[],"mappings":"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"}

package/dist/logs-cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+export declare function registerLogsCommands(program: Command, deps: CliDeps): void;

package/dist/logs-cli.js

@@ -0,0 +1,51 @@
+import { ok, fail } from "./envelope.js";
+import { LogsConfigError, loadLogsRetention, pruneLogs } from "./logs-retention.js";
+import { logsRoot } from "./project-dir.js";
+import { resolveDataDir } from "./data-dir.js";
+import { emitJson } from "./cli-shared.js";
+/** The commands that write run output under `.jevitate/logs` — pruned before, when auto-prune is on. */
+const LOG_WRITING_COMMANDS = new Set(["explore", "explore-author-journey", "record", "ux", "check", "run", "verify-fix", "capture"]);
+export function registerLogsCommands(program, deps) {
+    const configPath = deps.logs?.configPath ?? resolveDataDir(["config.json"]);
+    if (deps.logs?.autoPrune === true) {
+        program.hook("preAction", (_root, action) => {
+            if (!LOG_WRITING_COMMANDS.has(action.name()))
+                return;
+            // A malformed retention config fails closed (the command is refused); a file that cannot be
+            // deleted is housekeeping, not the run's business: it is reported and the command goes on.
+            const retention = loadLogsRetention(configPath);
+            try {
+                pruneLogs(deps.logs?.logsRoot ?? logsRoot(), retention);
+            }
+            catch (e) {
+                process.stderr.write(`warning: log pruning skipped: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        });
+    }
+    const logs = program.command("logs").description("run output under .jevitate/logs (dated; pruned by retention)");
+    logs
+        .command("prune")
+        .description("delete runs older than the retention TTL, always keeping the newest runs (config.json logs.ttlDays / logs.keepLatest; defaults 14 and 50)")
+        .option("--dir <dir>", "logs root to prune (default: the project's .jevitate/logs, else ~/.jevitate/logs)")
+        .option("--dry-run", "list what would be deleted, deleting nothing")
+        .option("--json", "emit a JSON envelope")
+        .action(function () {
+        const o = this.opts();
+        try {
+            const retention = loadLogsRetention(configPath);
+            const report = pruneLogs(o.dir ?? deps.logs?.logsRoot ?? logsRoot(), retention, { ...(o.dryRun === true ? { dryRun: true } : {}) });
+            const data = { ...report, retention, dryRun: o.dryRun === true };
+            if (o.json === true)
+                emitJson(program, ok(data));
+            else
+                program.configureOutput().writeOut?.(`${o.dryRun === true ? "would remove" : "removed"} ${report.removed.length} run(s); kept ${report.keptRuns} (ttl ${retention.ttlDays}d, keep latest ${retention.keepLatest})\n`);
+        }
+        catch (err) {
+            if (err instanceof LogsConfigError)
+                emitJson(program, fail(err.code, err.message));
+            else
+                emitJson(program, fail("E_LOGS_PRUNE", err instanceof Error ? err.message : String(err)));
+        }
+    });
+}
+//# sourceMappingURL=logs-cli.js.map

package/dist/logs-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs-cli.js","sourceRoot":"","sources":["../src/logs-cli.ts"],"names":[],"mappings":"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"}

package/dist/logs-retention.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Retention for run output under `.jevitate/logs/<date>/` (0.2.0): a run older than `ttlDays` is
+ * deleted, but the newest `keepLatest` runs are always kept, so a quiet project is never wiped.
+ * A run is every file and folder sharing its artifact stem (`explore-2026-09-25T01-26-29-787Z.*`).
+ * Pruned at the start of each command that writes logs, or on demand with `jevitate logs prune`.
+ * Configured in `~/.jevitate/config.json`: `{ "logs": { "ttlDays": 14, "keepLatest": 50 } }`.
+ */
+export interface LogsRetention {
+    readonly ttlDays: number;
+    readonly keepLatest: number;
+}
+export declare const DEFAULT_LOGS_RETENTION: LogsRetention;
+export declare class LogsConfigError extends Error {
+    readonly code: "E_LOGS_CONFIG";
+}
+/** The `logs` section of the config file; the defaults when the file or section is absent. A malformed value fails closed. */
+export declare function loadLogsRetention(path?: string): LogsRetention;
+export interface PruneReport {
+    readonly root: string;
+    /** Runs deleted (`<date>/<stem>`). */
+    readonly removed: string[];
+    readonly keptRuns: number;
+}
+/** Applies `retention` to the logs under `root`. `dryRun` reports what would go, deleting nothing. */
+export declare function pruneLogs(root: string, retention: LogsRetention, opts?: {
+    readonly nowMs?: number;
+    readonly dryRun?: boolean;
+}): PruneReport;