lynkeus 0.4.0 → 0.5.0

package/lib/cases/coverage.d.ts

@@ -0,0 +1,31 @@
+import type { Affected } from '../knowledge/query.js';
+import type { Case } from './format.js';
+/** The routes a case names in its steps. */
+export declare const routesNamed: (c: Case) => string[];
+/** What `case run --seen <dir>` kept: each passing case's screens, by case id. */
+export declare const readSeen: (dir: string | undefined) => Record<string, string[]>;
+export type Coverage = {
+    routes: number;
+    covered: string[];
+    uncovered: string[];
+    /** Routes a case names that the graph does not know: renamed, or a typo. */
+    unknown: string[];
+    byRoute: Record<string, string[]>;
+    files: Record<string, string>;
+};
+/** Which cases touch which of the app's routes, by what they name and what they went through last time they passed. */
+export declare const coverageOf: (cases: Case[], graphRoutes: string[], seen?: Record<string, string[]>) => Coverage;
+export type Impact = {
+    /** Each case to run, with the reached routes it touches, nearest first. */
+    cases: {
+        id: string;
+        file: string;
+        routes: string[];
+        distance: number;
+        via: string;
+    }[];
+    /** Routes the change reaches that no case touches. */
+    untested: string[];
+};
+/** The cases a change reaches: the screens it touches or imports, crossed with what each case covers. */
+export declare const impactOf: (affected: Affected[], coverage: Coverage) => Impact;

package/lib/cases/coverage.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const ROUTE = /^[A-Z][\w.]+$/;
+// A step names a route when it goes there, waits for it or checks it is on screen.
+const routeOf = (step) => {
+    const v = step.value;
+    const named = (x) => (typeof x === 'string' && ROUTE.test(x) ? x : undefined);
+    if (step.verb === 'app.nav' || step.verb === 'app.wait')
+        return (named(v) ??
+            (v && typeof v === 'object' && !Array.isArray(v) ? named(v.route ?? v.what) : undefined));
+    if (step.verb === 'app.see')
+        return v && typeof v === 'object' && !Array.isArray(v) ? named(v.route) : undefined;
+    return undefined;
+};
+/** The routes a case names in its steps. */
+export const routesNamed = (c) => [...new Set([...c.setup, ...c.steps].map(routeOf).filter((r) => !!r))];
+/** What `case run --seen <dir>` kept: each passing case's screens, by case id. */
+export const readSeen = (dir) => {
+    if (!dir || !fs.existsSync(dir))
+        return {};
+    const seen = {};
+    for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+        try {
+            const s = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+            if (typeof s.id === 'string' && Array.isArray(s.routes))
+                seen[s.id] = s.routes.filter((r) => typeof r === 'string');
+        }
+        catch { }
+    }
+    return seen;
+};
+/** Which cases touch which of the app's routes, by what they name and what they went through last time they passed. */
+export const coverageOf = (cases, graphRoutes, seen = {}) => {
+    const byRoute = {};
+    const files = {};
+    const add = (route, id) => {
+        byRoute[route] ??= [];
+        if (!byRoute[route].includes(id))
+            byRoute[route].push(id);
+    };
+    for (const c of cases) {
+        files[c.id] = c.file;
+        for (const r of routesNamed(c))
+            add(r, c.id);
+        for (const r of seen[c.id] ?? [])
+            add(r, c.id);
+    }
+    const known = new Set(graphRoutes);
+    const covered = graphRoutes.filter((r) => byRoute[r]?.length);
+    return {
+        routes: graphRoutes.length,
+        covered,
+        uncovered: graphRoutes.filter((r) => !byRoute[r]?.length),
+        unknown: Object.keys(byRoute)
+            .filter((r) => !known.has(r))
+            .sort(),
+        byRoute,
+        files,
+    };
+};
+/** The cases a change reaches: the screens it touches or imports, crossed with what each case covers. */
+export const impactOf = (affected, coverage) => {
+    const nearest = new Map();
+    for (const a of affected)
+        if (!nearest.has(a.route) || nearest.get(a.route).distance > a.distance)
+            nearest.set(a.route, a);
+    const byCase = new Map();
+    const untested = [];
+    for (const [route, hit] of nearest) {
+        const ids = coverage.byRoute[route] ?? [];
+        if (!ids.length)
+            untested.push(route);
+        for (const id of ids) {
+            const c = byCase.get(id) ?? { id, file: coverage.files[id] ?? '', routes: [], distance: hit.distance, via: hit.via };
+            c.routes.push(route);
+            if (hit.distance < c.distance)
+                Object.assign(c, { distance: hit.distance, via: hit.via });
+            byCase.set(id, c);
+        }
+    }
+    return { cases: [...byCase.values()].sort((a, b) => a.distance - b.distance || a.id.localeCompare(b.id)), untested: untested.sort() };
+};

package/lib/cases/draft.d.ts

@@ -0,0 +1,21 @@
+import type { FixtureCommand } from 'lynkeus-protocol';
+import type { PlanStep } from '../knowledge/plan.js';
+export type DraftInput = {
+    id: string;
+    title?: string;
+    from: string;
+    to: string;
+    /** The way from `from` to `to`, as `map plan` finds it; undefined when no path is known. */
+    path: PlanStep[] | undefined;
+    /** What the project's fixtures server says it can do, offered as the setup to pick from. */
+    fixtures?: FixtureCommand[];
+    /** The project's macros (`app.login`…), offered too. */
+    macros?: string[];
+    /** The project declares a fixtures server that did not describe itself. */
+    fixturesSilent?: boolean;
+};
+/**
+ * A case to finish: its frontmatter with the questions a reader needs answered, the backend's setup offered (never
+ * chosen: what state the case needs is the author's call), the way to the screen, and the checks left to write.
+ */
+export declare const draftCase: (d: DraftInput) => string;

package/lib/cases/draft.js

@@ -0,0 +1,53 @@
+const quote = (s) => JSON.stringify(s);
+const paramsHint = (c) => {
+    const params = Object.entries(c.params ?? {}).map(([k, p]) => `${k}${p.values ? ` (${p.values.join('|')})` : ''}`);
+    return params.length ? ` — ${params.join(', ')}` : '';
+};
+/**
+ * A case to finish: its frontmatter with the questions a reader needs answered, the backend's setup offered (never
+ * chosen: what state the case needs is the author's call), the way to the screen, and the checks left to write.
+ */
+export const draftCase = (d) => {
+    const lines = [
+        '---',
+        `id: ${d.id}`,
+        `title: ${quote(d.title ?? `[What a person can do on ${d.to}]`)}`,
+        'description: >',
+        '  [What this case proves, in a sentence or two.]',
+        'why: >',
+        '  [What breaks for a person if it fails.]',
+        'given: >',
+        `  [Who the user is and what is true when it starts, on ${d.from}.]`,
+        '---',
+        'setup:',
+    ];
+    if (d.fixtures?.length) {
+        lines.push('  # Pick what the case needs; the backend answers these (lynkeus fixtures describe):');
+        for (const c of d.fixtures) {
+            const example = c.example ? ` ${JSON.stringify(c.example).replace(/"(\w+)":/g, '$1: ')}` : ' {}';
+            lines.push(`  # - ${c.name}:${example}${c.summary ? `    # ${c.summary}` : ''}${paramsHint(c)}`);
+        }
+    }
+    else if (d.fixturesSilent)
+        lines.push('  # The fixtures server did not answer lynkeus.describe (lynkeus fixtures check says why): the setup options are not listed.');
+    else
+        lines.push('  # The state the case needs, through the project’s fixtures (cases.fixtures).');
+    lines.push('', 'steps:');
+    if (d.macros?.length)
+        lines.push(`  # The project's own steps: ${d.macros.join(', ')}`);
+    if (!d.path) {
+        lines.push(`  # No known way from ${d.from} to ${d.to}: \`lynkeus crawl --to ${d.to}\` learns one.`);
+        lines.push(`  - app.nav: ${d.to}`);
+    }
+    else {
+        for (const s of d.path) {
+            if (s.press)
+                lines.push(`  - app.press: ${quote(`#${s.press}`)}${s.source === 'static' ? '    # from the source: confirm it on screen' : ''}`);
+            else
+                lines.push(`  # ${s.from} → ${s.to}: ${s.hint ?? 'find the control that leads here'}`);
+            lines.push(`  - app.wait: { what: ${s.opens ? quote(s.opens) : s.to}, timeoutMs: 10000 }`);
+        }
+    }
+    lines.push(`  - app.see: { route: ${d.to} }`, '  # [What the person does here, and what must be on screen after.]', '', 'expected: |', '  [What must be true when it ends, on screen and in the backend.]', '');
+    return lines.join('\n');
+};

package/lib/cases/fixtures.d.ts

@@ -1,3 +1,4 @@
+import type { FixtureCommand } from 'lynkeus-protocol';
 export type FixturesConfig = {
     command: string;
     cwd?: string;
@@ -7,12 +8,22 @@ export type FixturesConfig = {
 export type Answer = Record<string, unknown>;
 /** The one command that is lynkeus's own and not the project's. */
 export declare const DESCRIBE = "lynkeus.describe";
+/** What the server answers: the names, with each command's description where it gave one. */
 export type Description = {
     commands: string[];
+    details: FixtureCommand[];
     down?: string;
+    protocol?: number;
 };
+/** A description as the server sent it, names and descriptions mixed, made one shape; anything else is no description. */
+export declare const readDescription: (answer: Record<string, unknown> | undefined) => Description | undefined;
 /** lynkeus's second own command: this connection works ahead of the cases. */
 export declare const AHEAD = "lynkeus.ahead";
+/** What the server last said it answers, and how long ago; undefined when it never did for this command. */
+export declare const lastDescription: (root: string, command: string) => {
+    at: number;
+    description: Description;
+} | undefined;
 export declare class Fixtures {
     #private;
     constructor(config: FixturesConfig, root: string);

package/lib/cases/fixtures.js

@@ -13,7 +13,8 @@
  *
  *   {"command": "lynkeus.describe", "params": {}, "env": {}}
  *
- * — and a server that knows answers `{"commands": ["create_user", …]}`. With
+ * — and a server that knows answers `{"commands": ["create_user", …]}`, each entry a name or a description
+ * (`FixtureCommand` in lynkeus-protocol: summary, params, example). The contract is docs/FIXTURES.md. With
  * that, a case naming a fixture nobody answers is refused before anything
  * runs. A server that answers `"ok": false`, as one written before this did,
  * is taken to describe nothing, and its cases run unchecked. A server that is
@@ -26,15 +27,45 @@
  * answer anything.
  */
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 /** The one command that is lynkeus's own and not the project's. */
 export const DESCRIBE = 'lynkeus.describe';
+/** A description as the server sent it, names and descriptions mixed, made one shape; anything else is no description. */
+export const readDescription = (answer) => {
+    const list = answer?.commands;
+    if (!Array.isArray(list))
+        return undefined;
+    const details = [];
+    for (const c of list) {
+        if (typeof c === 'string' && c)
+            details.push({ name: c });
+        else if (c && typeof c === 'object' && typeof c.name === 'string' && c.name)
+            details.push(c);
+        else
+            return undefined;
+    }
+    const down = typeof answer?.down === 'string' && answer.down ? answer.down : undefined;
+    const protocol = typeof answer?.protocol === 'number' ? answer.protocol : undefined;
+    return { commands: details.map((d) => d.name), details, ...(down ? { down } : {}), ...(protocol !== undefined ? { protocol } : {}) };
+};
 /** lynkeus's second own command: this connection works ahead of the cases. */
 export const AHEAD = 'lynkeus.ahead';
 const envOf = (params) => Object.fromEntries(Object.entries(params)
     .filter(([, v]) => v !== undefined && v !== null)
     .map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(), typeof v === 'object' ? JSON.stringify(v) : String(v)]));
+const describedFile = (root) => path.join(root, '.lynkeus', 'fixtures-described.json');
+/** What the server last said it answers, and how long ago; undefined when it never did for this command. */
+export const lastDescription = (root, command) => {
+    try {
+        const kept = JSON.parse(fs.readFileSync(describedFile(root), 'utf8'));
+        return kept.command === command ? { at: kept.at, description: kept.description } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 export class Fixtures {
     #config;
     #root;
@@ -42,6 +73,10 @@ export class Fixtures {
     #lines = [];
     #waiting = null;
     #stderr = '';
+    // Ends in a row without one answer. A command that cannot start (a wrong path, a backend that is not
+    // there) would otherwise be started again for every case, and each case would wait out its own start.
+    #silentEnds = 0;
+    #broken = null;
     constructor(config, root) {
         this.#config = config;
         this.#root = root;
@@ -56,6 +91,8 @@ export class Fixtures {
             cwd: path.resolve(this.#root, this.#config.cwd ?? '.'),
             env: { ...process.env, ...this.#config.env },
         });
+        // Writing to a command that already ended fails here; its close says so to whoever waits.
+        child.stdin.on('error', () => undefined);
         child.stderr.on('data', (chunk) => {
             this.#stderr = (this.#stderr + chunk.toString()).slice(-4000);
         });
@@ -63,6 +100,7 @@ export class Fixtures {
         reader.on('line', (line) => {
             if (!line.trim().startsWith('{'))
                 return;
+            this.#silentEnds = 0;
             if (this.#waiting) {
                 const resolve = this.#waiting;
                 this.#waiting = null;
@@ -72,6 +110,8 @@ export class Fixtures {
                 this.#lines.push(line);
         });
         child.on('close', () => {
+            if (this.#child === child)
+                this.#silentEnds += 1;
             this.#child = null;
             this.#waiting?.(null);
             this.#waiting = null;
@@ -80,6 +120,8 @@ export class Fixtures {
         return child;
     }
     async call(command, params) {
+        if (this.#broken)
+            throw new Error(`${command}: ${this.#broken}`);
         const child = this.#start();
         child.stdin.write(`${JSON.stringify({ command, params, env: envOf(params) })}\n`);
         const timeoutMs = this.#config.timeoutMs ?? 120_000;
@@ -96,8 +138,12 @@ export class Fixtures {
                 resolve(answer);
             };
         });
-        if (line === null)
-            throw new Error(`${command}: the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`);
+        if (line === null) {
+            const ended = `the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`;
+            if (this.#silentEnds >= 2)
+                this.#broken = `${ended} (it ended twice without answering, so it is not started again in this run)`;
+            throw new Error(`${command}: ${ended}`);
+        }
         const answer = JSON.parse(line);
         if (answer.ok === false)
             throw new Error(`${command}: ${String(answer.error ?? answer.message ?? 'ok=false')}`);
@@ -105,11 +151,16 @@ export class Fixtures {
     }
     /** What the server says it answers, or nothing when it does not say. */
     async describe() {
-        const answer = await this.call(DESCRIBE, {}).catch(() => undefined);
-        const commands = answer?.commands;
-        if (!Array.isArray(commands) || !commands.every((c) => typeof c === 'string'))
-            return undefined;
-        return typeof answer?.down === 'string' && answer.down ? { commands, down: answer.down } : { commands };
+        const d = readDescription(await this.call(DESCRIBE, {}).catch(() => undefined));
+        // Kept for `fixtures describe`: a server that boots a backend's framework takes longer to start than an MCP
+        // client waits, and what it answers changes only with its code.
+        if (d && !d.down)
+            try {
+                fs.mkdirSync(path.dirname(describedFile(this.#root)), { recursive: true });
+                fs.writeFileSync(describedFile(this.#root), JSON.stringify({ at: Date.now(), command: this.#config.command, description: d }));
+            }
+            catch { }
+        return d;
     }
     /** Says this connection works ahead of the cases being run. Whatever the server answers, it goes on. */
     async ahead() {

package/lib/cases/frames.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A simulator or emulator gives its frames as PNG (`simctl io screenshot` cannot write AVIF or WebP, nor can
+ * `screencap`): a report frame is encoded again as AVIF, about 4% of the PNG's bytes in some 70 ms, and the
+ * PNG removed. Answers the frame's path, the PNG's when it could not be encoded.
+ */
+export declare const compactFrame: (png: string) => Promise<string>;

package/lib/cases/frames.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+let encoder;
+// sharp is optional: a CLI installed without it keeps the PNG the host took.
+const load = () => {
+    const name = 'sharp';
+    encoder ??= import(name).then((m) => m.default).catch(() => null);
+    return encoder;
+};
+/**
+ * A simulator or emulator gives its frames as PNG (`simctl io screenshot` cannot write AVIF or WebP, nor can
+ * `screencap`): a report frame is encoded again as AVIF, about 4% of the PNG's bytes in some 70 ms, and the
+ * PNG removed. Answers the frame's path, the PNG's when it could not be encoded.
+ */
+export const compactFrame = async (png) => {
+    const sharp = await load();
+    if (!sharp || !png.endsWith('.png'))
+        return png;
+    const avif = `${png.slice(0, -'.png'.length)}.avif`;
+    try {
+        await sharp(png).avif({ quality: 60, effort: 2 }).toFile(avif);
+        fs.unlinkSync(png);
+        return avif;
+    }
+    catch {
+        fs.rmSync(avif, { force: true });
+        return png;
+    }
+};

package/lib/cases/nativeLogs.d.ts

@@ -0,0 +1,14 @@
+import type { DeviceInfo } from '../device/devices.js';
+import type { LogLine } from './runner.js';
+/** The app's native log while a run goes on: `take` hands over what came since the last take. */
+export type NativeLogs = {
+    take: () => LogLine[];
+    stop: () => void;
+};
+export declare const parseOsLog: (line: string) => LogLine | undefined;
+export declare const parseLogcat: (line: string, uid: string) => LogLine | undefined;
+/**
+ * Streams the app's native log on a simulator or an emulator. A device lynkeus cannot read a log from, or an app it
+ * cannot find there, gives none: the run goes on without it.
+ */
+export declare const startNativeLogs: (device: DeviceInfo, appId: string) => Promise<NativeLogs | undefined>;

package/lib/cases/nativeLogs.js

@@ -0,0 +1,111 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const KEEP = 5000;
+const LONG = 4000;
+const cut = (text) => (text.length > LONG ? `${text.slice(0, LONG)}…` : text);
+// `log stream --style ndjson`: one JSON object a line. React Native's own console lines (category javascript)
+// come from the agent already, with their stacks.
+export const parseOsLog = (line) => {
+    if (!line.startsWith('{'))
+        return undefined;
+    let e;
+    try {
+        e = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (!e.eventMessage || !e.timestamp)
+        return undefined;
+    if (e.subsystem === 'com.facebook.react.log' && e.category === 'javascript')
+        return undefined;
+    // "2026-10-16 14:55:01.123456-0300" → an instant.
+    const at = Date.parse(e.timestamp
+        .replace(' ', 'T')
+        .replace(/(\.\d{3})\d*/, '$1')
+        .replace(/([+-]\d\d)(\d\d)$/, '$1:$2'));
+    if (Number.isNaN(at))
+        return undefined;
+    const type = (e.messageType ?? '').toLowerCase();
+    const level = type === 'error' || type === 'fault' ? 'error' : type === 'debug' ? 'debug' : 'info';
+    return { at, level, source: 'native', text: cut(e.eventMessage) };
+};
+// `logcat -v epoch,uid`: "  1760637301.123  10123  4521  4533 E Tag: message". ReactNativeJS repeats the console.
+export const parseLogcat = (line, uid) => {
+    const m = /^\s*(\d+\.\d+)\s+(\S+)\s+\d+\s+\d+\s+([VDIWEF])\s+([^:]*?)\s*:\s?(.*)$/.exec(line);
+    if (!m || m[2] !== uid)
+        return undefined;
+    const [, seconds, , priority, tag, message] = m;
+    if (tag === 'ReactNativeJS')
+        return undefined;
+    const level = priority === 'E' || priority === 'F' ? 'error' : priority === 'W' ? 'warn' : priority === 'I' ? 'info' : 'debug';
+    return { at: Math.round(Number(seconds) * 1000), level, source: 'native', text: cut(`${tag}: ${message}`) };
+};
+const executable = async (udid, bundleId) => {
+    const { stdout } = await run('xcrun', ['simctl', 'appinfo', udid, bundleId]);
+    return /CFBundleExecutable = "?([^";\n]+)"?;/.exec(stdout)?.[1];
+};
+const androidUid = async (serial, appId) => {
+    const { stdout } = await run('adb', ['-s', serial, 'shell', 'cmd', 'package', 'list', 'packages', '-U', appId]);
+    const line = stdout.split('\n').find((l) => l.startsWith(`package:${appId} `));
+    return line ? /uid:(\d+)/.exec(line)?.[1] : undefined;
+};
+/**
+ * Streams the app's native log on a simulator or an emulator. A device lynkeus cannot read a log from, or an app it
+ * cannot find there, gives none: the run goes on without it.
+ */
+export const startNativeLogs = async (device, appId) => {
+    if (device.type === 'physical' || device.id === 'headless')
+        return undefined;
+    const lines = [];
+    let child;
+    let parse;
+    try {
+        if (device.platform === 'ios') {
+            const name = await executable(device.id, appId);
+            if (!name)
+                return undefined;
+            // Inside the app's process every Apple framework logs too, thousands of lines a launch: keep its errors, and
+            // the rest only from the app's own code (NSLog and print have no subsystem) and React Native's native side.
+            const own = `subsystem == "" OR subsystem BEGINSWITH "${appId.replaceAll('"', '')}" OR subsystem BEGINSWITH "com.facebook.react"`;
+            const predicate = `process == "${name.replaceAll('"', '')}" AND (messageType == error OR messageType == fault OR ${own})`;
+            child = spawn('xcrun', ['simctl', 'spawn', device.id, 'log', 'stream', '--style', 'ndjson', '--level', 'default', '--predicate', predicate], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            parse = parseOsLog;
+        }
+        else {
+            const uid = await androidUid(device.id, appId);
+            if (!uid)
+                return undefined;
+            // From now on: `-T 1` starts at the newest line instead of replaying the buffer.
+            child = spawn('adb', ['-s', device.id, 'logcat', '-v', 'epoch,uid', '-T', '1'], { stdio: ['ignore', 'pipe', 'ignore'] });
+            parse = (line) => parseLogcat(line, uid);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    let rest = '';
+    child.stdout?.on('data', (chunk) => {
+        const text = rest + chunk.toString('utf8');
+        const parts = text.split('\n');
+        rest = parts.pop() ?? '';
+        for (const part of parts) {
+            const line = parse(part);
+            if (!line)
+                continue;
+            lines.push(line);
+            if (lines.length > KEEP)
+                lines.shift();
+        }
+    });
+    child.on('error', () => undefined);
+    return {
+        take: () => lines.splice(0, lines.length),
+        stop: () => {
+            child.kill();
+        },
+    };
+};

package/lib/cases/runDirs.d.ts

@@ -0,0 +1,13 @@
+/** Bytes under a directory, its files and their subfolders'. */
+export declare const sizeOf: (dir: string) => number;
+export declare const megabytes: (bytes: number) => string;
+/** `7d`, `12h`, `30m` as milliseconds; anything else is refused. */
+export declare const ageOf: (text: string) => number | undefined;
+/**
+ * The runs `case run --out` left, at `root` itself or one level under it, that ended longer than `olderMs` ago.
+ * Only folders that hold a run are touched; `dry` lists them without removing anything.
+ */
+export declare const pruneRuns: (root: string, olderMs: number, dry?: boolean, now?: number) => {
+    removed: string[];
+    bytes: number;
+};

package/lib/cases/runDirs.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Bytes under a directory, its files and their subfolders'. */
+export const sizeOf = (dir) => {
+    let total = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const at = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            total += sizeOf(at);
+        else if (entry.isFile())
+            total += fs.statSync(at).size;
+    }
+    return total;
+};
+export const megabytes = (bytes) => `${(bytes / 1024 / 1024).toFixed(bytes < 10 * 1024 * 1024 ? 1 : 0)} MB`;
+/** `7d`, `12h`, `30m` as milliseconds; anything else is refused. */
+export const ageOf = (text) => {
+    const m = /^(\d+)([dhm])$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    return Number(m[1]) * { d: 86_400_000, h: 3_600_000, m: 60_000 }[m[2]];
+};
+/** A directory `case run --out` wrote: it holds the run's manifest and its cases. */
+const isRun = (dir) => fs.existsSync(path.join(dir, 'run.json')) && fs.existsSync(path.join(dir, 'cases.jsonl'));
+/**
+ * The runs `case run --out` left, at `root` itself or one level under it, that ended longer than `olderMs` ago.
+ * Only folders that hold a run are touched; `dry` lists them without removing anything.
+ */
+export const pruneRuns = (root, olderMs, dry = false, now = Date.now()) => {
+    const candidates = isRun(root)
+        ? [root]
+        : fs
+            .readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(root, e.name))
+            .filter(isRun);
+    const removed = [];
+    let bytes = 0;
+    for (const dir of candidates) {
+        if (now - fs.statSync(path.join(dir, 'run.json')).mtimeMs < olderMs)
+            continue;
+        bytes += sizeOf(dir);
+        removed.push(dir);
+        if (!dry)
+            fs.rmSync(dir, { recursive: true, force: true });
+    }
+    return { removed, bytes };
+};

package/lib/cases/runfile.d.ts

@@ -1,4 +1,4 @@
-import { type RunCase } from 'lynkeus-protocol';
+import { type RunCase, type RunManifest } from 'lynkeus-protocol';
 import type { Case } from './format.js';
 import type { CaseReport } from './runner.js';
 export type Attempt = {
@@ -7,6 +7,10 @@ export type Attempt = {
     startedAt: Date;
 };
 export declare const toRunCase: (c: Case, { report, attempt, startedAt }: Attempt, root: string, dir?: string) => RunCase;
+/** The branch and commit the run was made from, so a report can say which code it tested. */
+export declare const gitOf: (root: string) => RunManifest["git"];
+/** A remote as a web address a report can link commits to, without any credentials it carried. */
+export declare const webOf: (url: string | undefined) => string | undefined;
 export declare class RunFile {
     private readonly dir;
     private readonly root;