@archastro/astroshot-review 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchAstro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @archastro/astroshot-review
+
+The Astroshots review tray in your terminal. Streams `.astroshot/` captures
+across worktrees newest-first, draws them with the Kitty graphics protocol,
+plays movies through ffmpeg, and writes the same `review.json` Seen state and
+feedback as the macOS app.
+
+```bash
+npx astroshot review              # via the unified CLI (recommended)
+npx astroshot-review ~/projects   # this package's own bin
+```
+
+- Terminals: Ghostty, kitty, WezTerm (anything with the Kitty graphics protocol).
+  Others get labeled placeholders.
+- Movies need `ffmpeg` on `PATH`.
+- Keys: `↑↓` move · `⏎` open · `f` full screen · `s` seen · `c` feedback ·
+  `u` history · `m` movies · `1`/`2` tabs · `,` settings · `?` help · `q` quit.
+
+Full guide: [docs/review-tui.md](https://github.com/ArchAstro/astroshots/blob/main/docs/review-tui.md).

package/bin/astroshot-review.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+    // main() has torn the tray down, so the event loop should drain and the
+    // process exit on its own. If a stray handle is still referenced (a
+    // socket, a pipe), don't sit invisibly in the shell forever: exit. The
+    // timer is unref'd, so it never keeps the loop alive itself.
+    setTimeout(() => process.exit(code), 1000).unref();
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  },
+);

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+export declare function reviewHelp(): string;
+export interface ParsedArgs {
+    roots: string[];
+    graphics: boolean;
+    watch: boolean;
+    index: boolean;
+    help: boolean;
+    version: boolean;
+    rootsSource: "app" | "cli" | "cwd";
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import path from "node:path";
+import { render } from "ink";
+import { createElement } from "react";
+import { ReviewStore } from "./data/store.js";
+import { ImageService } from "./images/service.js";
+import { createGraphicsStdout } from "./terminal/graphics-stdout.js";
+import { HerdrSink, discoverHerdr, herdrAddress, probeHerdrSet } from "./terminal/herdr.js";
+import { ImageLayer } from "./terminal/image-layer.js";
+import { probeTerminal } from "./terminal/probe.js";
+import { App } from "./ui/app.js";
+import { ServicesContext } from "./ui/context.js";
+import { detectFfmpeg } from "./video/ffmpeg.js";
+export function reviewHelp() {
+    return `astroshot review — the Astroshots tray in your terminal
+
+Usage:
+  astroshot review [<dir>...] [options]
+
+Options:
+  --root <dir>       Folder to watch for .astroshot/ trees (repeatable)
+  --no-graphics      Skip terminal pictures (text only)
+  --no-watch         Do not follow filesystem changes
+  --no-index         Ignore the on-disk index (full scan every start)
+  -h, --help         Show this help
+
+Without roots, \`astroshot review\` uses the folders the Astroshots app
+watches (macOS) and otherwise the current directory. Images render pixel-
+perfect in Kitty-protocol terminals (Ghostty, kitty, WezTerm) and inside
+herdr (enable [experimental] kitty_graphics and reattach the client once);
+elsewhere — mosh, tmux, plain terminals — they render as truecolor
+half-block text. Movie playback needs ffmpeg on PATH.
+
+Keys: ↑↓ move · ⏎ open · f full screen · s seen · c feedback · u history ·
+      m movies · 1/2 tabs · , settings · ? help · q quit`;
+}
+export function parseArgs(argv) {
+    const parsed = { roots: [], graphics: true, watch: true, index: true, help: false, version: false, rootsSource: "cli" };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        switch (argument) {
+            case "-h":
+            case "--help":
+                parsed.help = true;
+                break;
+            case "-v":
+            case "--version":
+                parsed.version = true;
+                break;
+            case "--no-graphics":
+                parsed.graphics = false;
+                break;
+            case "--no-watch":
+                parsed.watch = false;
+                break;
+            case "--no-index":
+                parsed.index = false;
+                break;
+            case "--root": {
+                const value = argv[index + 1];
+                if (!value)
+                    throw new Error("--root requires a directory");
+                parsed.roots.push(value);
+                index += 1;
+                break;
+            }
+            case "--roots-source": {
+                const value = argv[index + 1];
+                if (value !== "app" && value !== "cli" && value !== "cwd")
+                    throw new Error("--roots-source must be app, cli, or cwd");
+                parsed.rootsSource = value;
+                index += 1;
+                break;
+            }
+            default:
+                if (argument.startsWith("-"))
+                    throw new Error(`Unknown option: ${argument}`);
+                parsed.roots.push(argument);
+        }
+    }
+    if (parsed.roots.length === 0) {
+        parsed.roots = [process.cwd()];
+        parsed.rootsSource = "cwd";
+    }
+    return parsed;
+}
+function readVersion() {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return packageJson.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export async function main(argv) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error("");
+        console.error(reviewHelp());
+        return 1;
+    }
+    if (args.help) {
+        console.log(reviewHelp());
+        return 0;
+    }
+    if (args.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    if (!process.stdout.isTTY || !process.stdin.isTTY) {
+        console.error("astroshot review needs an interactive terminal (stdin and stdout must be a TTY).");
+        return 1;
+    }
+    const roots = args.roots.map((root) => path.resolve(root)).filter((root) => {
+        try {
+            return fs.statSync(root).isDirectory();
+        }
+        catch {
+            console.error(`Ignoring missing folder: ${root}`);
+            return false;
+        }
+    });
+    const debugLog = process.env.ASTROSHOT_REVIEW_DEBUG
+        ? (message) => fs.appendFileSync("astroshot-review.log", `${new Date().toISOString()} ${message}\n`)
+        : null;
+    let capabilities = await probeTerminal({ stdin: process.stdin, stdout: process.stdout }, { env: args.graphics ? process.env : { ...process.env, ASTROSHOT_REVIEW_GRAPHICS: "none" } });
+    // Inside herdr, raw Kitty escapes are dropped; render through its socket
+    // graphics API instead (pixel-perfect), falling back to half-blocks with an
+    // actionable reason when herdr can't yet report the host cell size.
+    let herdrSink;
+    const herdr = args.graphics ? herdrAddress() : null;
+    if (herdr) {
+        const discovery = await discoverHerdr(herdr, {
+            onWaiting: () => debugLog?.("herdr: waiting for host cell size"),
+        });
+        if (discovery.ok && discovery.cellWidth && discovery.cellHeight) {
+            const setSupport = await probeHerdrSet(herdr);
+            if (setSupport.ok) {
+                herdrSink = new HerdrSink(herdr, (error) => debugLog?.(`herdr: ${error.message}`));
+                capabilities = {
+                    ...capabilities,
+                    graphics: "herdr",
+                    cellWidth: discovery.cellWidth,
+                    cellHeight: discovery.cellHeight,
+                    cellSource: "query",
+                    reason: undefined,
+                };
+            }
+            else {
+                // herdr can size images but not place per-image layers; half-blocks it is.
+                capabilities = { ...capabilities, reason: setSupport.reason ?? "herdr pane.graphics.set unavailable" };
+            }
+        }
+        else {
+            capabilities = { ...capabilities, reason: discovery.reason ?? capabilities.reason };
+        }
+    }
+    debugLog?.(`capabilities ${JSON.stringify(capabilities)}`);
+    const ffmpeg = detectFfmpeg();
+    const service = new ImageService();
+    const layer = new ImageLayer({
+        capabilities,
+        service,
+        herdr: herdrSink,
+        write: (data) => {
+            process.stdout.write(data);
+        },
+        onError: (src, error) => debugLog?.(`image ${src}: ${error.message}`),
+        onDebug: debugLog ? (message) => debugLog(`layer ${message}`) : undefined,
+    });
+    const store = new ReviewStore({
+        roots,
+        watch: args.watch,
+        useIndex: args.index,
+        onLog: (message) => debugLog?.(`store ${message}`),
+    });
+    void store.start();
+    const stdout = createGraphicsStdout(process.stdout, layer);
+    const services = { store, layer, service, capabilities, ffmpeg, rootsSource: args.rootsSource, version: readVersion() };
+    let cleared = false;
+    const clearPictures = () => {
+        if (cleared)
+            return;
+        cleared = true;
+        const output = layer.clear();
+        if (output)
+            process.stdout.write(output);
+        herdrSink?.dispose();
+    };
+    const instance = render(createElement(ServicesContext.Provider, { value: services }, createElement(App, { onQuit: clearPictures })), {
+        stdout,
+        stdin: process.stdin,
+        alternateScreen: true,
+        exitOnCtrlC: true,
+        patchConsole: true,
+        // Ink treats CI=true as "not interactive": no alternate screen, no key
+        // handling, frames appended instead of redrawn. The tray already refuses
+        // to run without a TTY on both ends, so a TTY is the only signal that
+        // matters — CI-flavoured shells and CI pty harnesses get the real UI.
+        interactive: true,
+    });
+    // `kill <pid>` or a closing terminal must not leave pictures or the
+    // alternate screen behind; Ink only handles Ctrl+C itself.
+    const onSignal = (signal) => {
+        clearPictures();
+        try {
+            process.stdout.write("\x1b[?1049l\x1b[?25h");
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+        }
+        catch {
+            // The terminal may already be gone.
+        }
+        instance.unmount();
+        process.exit(signal === "SIGHUP" ? 129 : 143);
+    };
+    process.once("SIGTERM", onSignal);
+    process.once("SIGHUP", onSignal);
+    process.once("SIGQUIT", onSignal);
+    process.once("SIGINT", onSignal);
+    // Last-ditch: closing the herdr sockets makes herdr drop the layers even if
+    // we never got to run a signal handler.
+    process.once("exit", () => herdrSink?.dispose());
+    try {
+        await instance.waitUntilExit();
+    }
+    finally {
+        process.off("SIGTERM", onSignal);
+        process.off("SIGHUP", onSignal);
+        clearPictures();
+        await store.dispose();
+        await service.dispose();
+    }
+    return 0;
+}

package/dist/data/friction.d.ts

@@ -0,0 +1,22 @@
+import type { HashCache } from "./hash-cache.js";
+import type { FrictionLog, FrictionRun, FrictionStep } from "./model.js";
+export declare const PROMPT_FILE = "prompt.md";
+export declare const META_FILE = "meta.json";
+export declare const RUNS_DIR = "runs";
+export declare const LOG_FILE = "log.jsonl";
+/** Parse JSONL text into ordered steps; screenshots are resolved against `runDir`. */
+export declare function parseJsonl(text: string, runDir: string): Promise<FrictionStep[]>;
+export declare function loadRun(runDir: string, runId: string, hashes: HashCache): Promise<FrictionRun | null>;
+export declare function loadRuns(logDir: string, hashes: HashCache): Promise<FrictionRun[]>;
+export declare function loadFrictionLog(logDir: string, context: {
+    worktreePath: string;
+    worktree: string;
+}, hashes: HashCache): Promise<FrictionLog | null>;
+export declare function loadFrictionLogs(frictionDir: string, context: {
+    worktreePath: string;
+    worktree: string;
+}, hashes: HashCache): Promise<FrictionLog[]>;
+/** `MMM d · HH:mm` in local time for `yyyyMMddTHHmmssZ(-N)` run ids. */
+export declare function runDisplayTitle(runId: string): string;
+export declare function stepCountLabel(count: number): string;
+export declare function frictionStatusLabel(status: string | null): string | null;

package/dist/data/friction.js

@@ -0,0 +1,278 @@
+/**
+ * Friction logs: `.astroshot/friction-logs/<slug>/{prompt.md,meta.json,runs/<run>/log.jsonl}`.
+ * Mirrors the macOS loader, including field aliases and silent skipping of
+ * malformed lines and missing screenshots.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { humanize, worktreeShort } from "./paths.js";
+import { entryNeedsHash, readReviewDocument, scopedEntry, snapshotFromEntry, } from "./review-store.js";
+export const PROMPT_FILE = "prompt.md";
+export const META_FILE = "meta.json";
+export const RUNS_DIR = "runs";
+export const LOG_FILE = "log.jsonl";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringList(value) {
+    if (Array.isArray(value)) {
+        return value
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+    }
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function firstString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string")
+            return value;
+    }
+    return null;
+}
+async function exists(filePath) {
+    try {
+        await fs.promises.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectoryEntry(parent, entry) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return (await fs.promises.stat(path.join(parent, entry.name))).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function mtimeOf(filePath) {
+    try {
+        return (await fs.promises.stat(filePath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse JSONL text into ordered steps; screenshots are resolved against `runDir`. */
+export async function parseJsonl(text, runDir) {
+    const steps = [];
+    let index = 0;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(parsed))
+            continue;
+        index += 1;
+        const step = typeof parsed.step === "number" ? parsed.step : index;
+        const stepId = firstString(parsed, "id") ?? `step-${step}`;
+        const screenshots = [];
+        for (const name of stringList(parsed.screenshots ?? parsed.screenshot)) {
+            const byBasename = path.join(runDir, path.basename(name));
+            const asWritten = path.resolve(runDir, name);
+            if (await exists(byBasename))
+                screenshots.push(byBasename);
+            else if (await exists(asWritten))
+                screenshots.push(asWritten);
+        }
+        steps.push({
+            id: `${step}-${stepId}`,
+            step,
+            stepId,
+            title: firstString(parsed, "title") ?? humanize(stepId),
+            description: firstString(parsed, "description") ?? "",
+            transcript: firstString(parsed, "transcript", "narration", "voiceover") ?? "",
+            screenshots,
+            good: stringList(parsed.good ?? parsed.looks_good),
+            improve: stringList(parsed.improve ?? parsed.can_improve ?? parsed.improvements),
+            url: firstString(parsed, "url"),
+            capturedAt: firstString(parsed, "captured_at"),
+        });
+    }
+    return steps.sort((a, b) => a.step - b.step);
+}
+async function runReview(runDir, runId, hashes) {
+    const logPath = path.join(runDir, LOG_FILE);
+    let document;
+    try {
+        document = await readReviewDocument(runDir);
+    }
+    catch {
+        return null;
+    }
+    if (!document)
+        return null;
+    const entry = scopedEntry(document, LOG_FILE, runId);
+    let sha = null;
+    if (entryNeedsHash(entry)) {
+        try {
+            sha = await hashes.hash(logPath);
+        }
+        catch {
+            sha = null;
+        }
+    }
+    return snapshotFromEntry(entry, sha);
+}
+export async function loadRun(runDir, runId, hashes) {
+    const logPath = path.join(runDir, LOG_FILE);
+    const hasLog = await exists(logPath);
+    let steps = [];
+    if (hasLog) {
+        steps = await parseJsonl(await fs.promises.readFile(logPath, "utf8"), runDir);
+    }
+    else {
+        let entries;
+        try {
+            entries = await fs.promises.readdir(runDir);
+        }
+        catch {
+            return null;
+        }
+        if (!entries.some((entry) => /\.(png|jpe?g|webp|gif)$/i.test(entry)))
+            return null;
+    }
+    const capturedAt = (await mtimeOf(runDir)) ?? (await mtimeOf(logPath)) ?? Date.now();
+    return {
+        runId,
+        directory: runDir,
+        logPath: hasLog ? logPath : null,
+        capturedAt,
+        status: null,
+        steps,
+        review: hasLog ? await runReview(runDir, runId, hashes) : null,
+    };
+}
+export async function loadRuns(logDir, hashes) {
+    const runsDir = path.join(logDir, RUNS_DIR);
+    const runs = [];
+    let entries = [];
+    try {
+        entries = await fs.promises.readdir(runsDir, { withFileTypes: true });
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || !(await isDirectoryEntry(runsDir, entry)))
+            continue;
+        const run = await loadRun(path.join(runsDir, entry.name), entry.name, hashes);
+        if (run)
+            runs.push(run);
+    }
+    if (runs.length === 0 && (await exists(path.join(logDir, LOG_FILE)))) {
+        const flat = await loadRun(logDir, "latest", hashes);
+        if (flat)
+            runs.push(flat);
+    }
+    return runs.sort((a, b) => b.capturedAt - a.capturedAt);
+}
+export async function loadFrictionLog(logDir, context, hashes) {
+    const slug = path.basename(logDir);
+    const promptPath = path.join(logDir, PROMPT_FILE);
+    const metaPath = path.join(logDir, META_FILE);
+    const hasPrompt = await exists(promptPath);
+    const runs = await loadRuns(logDir, hashes);
+    if (!hasPrompt && runs.length === 0)
+        return null;
+    let meta = {};
+    try {
+        const parsed = JSON.parse(await fs.promises.readFile(metaPath, "utf8"));
+        if (isRecord(parsed))
+            meta = parsed;
+    }
+    catch {
+        meta = {};
+    }
+    const metaTitle = firstString(meta, "title")?.trim();
+    const candidates = [
+        await mtimeOf(logDir),
+        hasPrompt ? await mtimeOf(promptPath) : null,
+        await mtimeOf(metaPath),
+        runs[0]?.capturedAt ?? null,
+        typeof meta.updated_at === "string" ? Date.parse(meta.updated_at) : null,
+    ].filter((value) => typeof value === "number" && Number.isFinite(value));
+    return {
+        id: `${context.worktreePath}::${slug}`,
+        slug,
+        directory: logDir,
+        worktreePath: context.worktreePath,
+        worktree: context.worktree,
+        worktreeShort: worktreeShort(context.worktree),
+        title: metaTitle || humanize(slug),
+        description: firstString(meta, "description") ?? "",
+        status: firstString(meta, "status") ?? runs[0]?.status ?? null,
+        updatedAt: candidates.length ? Math.max(...candidates) : Date.now(),
+        promptPath: hasPrompt ? promptPath : null,
+        runs,
+    };
+}
+export async function loadFrictionLogs(frictionDir, context, hashes) {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(frictionDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const logs = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || !(await isDirectoryEntry(frictionDir, entry)))
+            continue;
+        const log = await loadFrictionLog(path.join(frictionDir, entry.name), context, hashes);
+        if (log)
+            logs.push(log);
+    }
+    return logs.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/** `MMM d · HH:mm` in local time for `yyyyMMddTHHmmssZ(-N)` run ids. */
+export function runDisplayTitle(runId) {
+    const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z(?:-\d+)?$/.exec(runId);
+    if (match) {
+        const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), Number(match[4]), Number(match[5]), Number(match[6])));
+        const month = date.toLocaleString("en-US", { month: "short" });
+        const hours = String(date.getHours()).padStart(2, "0");
+        const minutes = String(date.getMinutes()).padStart(2, "0");
+        return `${month} ${date.getDate()} · ${hours}:${minutes}`;
+    }
+    return runId.length > 16 ? runId.slice(-14) : runId;
+}
+export function stepCountLabel(count) {
+    return count === 1 ? "1 step" : `${count} steps`;
+}
+export function frictionStatusLabel(status) {
+    switch ((status ?? "").toLowerCase()) {
+        case "draft":
+            return "Draft";
+        case "ready":
+            return "Ready";
+        case "running":
+            return "Running";
+        case "complete":
+        case "completed":
+        case "done":
+            return "Complete";
+        case "failed":
+        case "fail":
+        case "error":
+            return "Failed";
+        default:
+            return status ? humanize(status) : null;
+    }
+}

package/dist/data/hash-cache.d.ts

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+export interface HashRecord {
+    mtimeMs: number;
+    size: number;
+    sha256: string;
+}
+/** Memoizes file hashes by (path, mtime, size) so rescans stay cheap. */
+export declare class HashCache {
+    private readonly records;
+    private readonly inFlight;
+    constructor(initial?: Record<string, HashRecord>);
+    hash(filePath: string, stat?: fs.Stats): Promise<string>;
+    seed(records: Record<string, HashRecord>): void;
+    /** Drop records for files that are no longer part of the stream. */
+    retain(keep: Set<string>, alsoKeep?: (filePath: string) => boolean): void;
+    toJSON(): Record<string, HashRecord>;
+}

package/dist/data/hash-cache.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import { sha256File } from "./review-store.js";
+/** Memoizes file hashes by (path, mtime, size) so rescans stay cheap. */
+export class HashCache {
+    records = new Map();
+    inFlight = new Map();
+    constructor(initial = {}) {
+        for (const [filePath, record] of Object.entries(initial)) {
+            this.records.set(filePath, record);
+        }
+    }
+    async hash(filePath, stat) {
+        const info = stat ?? (await fs.promises.stat(filePath));
+        const cached = this.records.get(filePath);
+        if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) {
+            return cached.sha256;
+        }
+        const pending = this.inFlight.get(filePath);
+        if (pending)
+            return pending;
+        const job = sha256File(filePath).then((sha256) => {
+            this.records.set(filePath, { mtimeMs: info.mtimeMs, size: info.size, sha256 });
+            this.inFlight.delete(filePath);
+            return sha256;
+        });
+        this.inFlight.set(filePath, job);
+        try {
+            return await job;
+        }
+        catch (error) {
+            this.inFlight.delete(filePath);
+            throw error;
+        }
+    }
+    seed(records) {
+        for (const [filePath, record] of Object.entries(records)) {
+            if (!this.records.has(filePath))
+                this.records.set(filePath, record);
+        }
+    }
+    /** Drop records for files that are no longer part of the stream. */
+    retain(keep, alsoKeep = () => false) {
+        for (const filePath of [...this.records.keys()]) {
+            if (!keep.has(filePath) && !alsoKeep(filePath))
+                this.records.delete(filePath);
+        }
+    }
+    toJSON() {
+        return Object.fromEntries(this.records);
+    }
+}