@archastro/astroshot-review 0.2.1

package/dist/data/review-store.js

@@ -0,0 +1,237 @@
+/**
+ * `review.json` — the human side of the on-disk contract.
+ *
+ * Reads mirror the macOS app exactly: version gate, run-id gate, then hash
+ * scoping. Writes mirror it too: sorted keys, second-precision UTC
+ * timestamps, uppercase UUID comment ids, run reset on a run-id change, and
+ * an atomic temp-file rename.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const REVIEW_FILE = "review.json";
+export class UnsupportedReviewVersion extends Error {
+    constructor(version) {
+        super(`Unsupported review.json version ${String(version)}`);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function emptyDocument() {
+    return { version: 1, reviews: {} };
+}
+/** Missing file → empty document. Malformed JSON → null (treated as unreadable). */
+export async function readReviewDocument(directory) {
+    let raw;
+    try {
+        raw = await fs.promises.readFile(path.join(directory, REVIEW_FILE), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyDocument();
+        return null;
+    }
+    return parseReviewDocument(raw);
+}
+export function parseReviewDocument(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed.version !== 1)
+        throw new UnsupportedReviewVersion(parsed.version);
+    const reviews = {};
+    if (isRecord(parsed.reviews)) {
+        for (const [fileName, entry] of Object.entries(parsed.reviews)) {
+            if (!isRecord(entry))
+                continue;
+            const comments = Array.isArray(entry.comments)
+                ? entry.comments.filter(isRecord).map((comment) => ({
+                    id: String(comment.id ?? ""),
+                    body: String(comment.body ?? ""),
+                    created_at: String(comment.created_at ?? ""),
+                }))
+                : undefined;
+            reviews[fileName] = {
+                decision: typeof entry.decision === "string" ? entry.decision : undefined,
+                reviewed_at: typeof entry.reviewed_at === "string" ? entry.reviewed_at : undefined,
+                image_sha256: typeof entry.image_sha256 === "string" ? entry.image_sha256 : undefined,
+                comments,
+            };
+        }
+    }
+    return {
+        version: 1,
+        run_id: typeof parsed.run_id === "string" ? parsed.run_id : undefined,
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : undefined,
+        reviews,
+    };
+}
+export function sha256File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = fs.createReadStream(filePath);
+        stream.on("error", reject);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(hash.digest("hex")));
+    });
+}
+export function sha256Bytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** The entry that applies to `fileName`, or null when the run gate rejects it. */
+export function scopedEntry(document, fileName, expectedRunId) {
+    if (expectedRunId !== null && document.run_id !== expectedRunId)
+        return null;
+    return document.reviews[fileName] ?? null;
+}
+/** Whether validating this entry needs the image's current hash. */
+export function entryNeedsHash(entry) {
+    return Boolean(entry?.image_sha256);
+}
+/**
+ * The seen/stale truth table from the app's `ReviewSnapshot`:
+ * hash mismatch hides the decision but keeps comments and flags staleness.
+ */
+export function snapshotFromEntry(entry, currentSha256) {
+    const hashMatches = Boolean(entry?.image_sha256) && entry?.image_sha256 === currentSha256;
+    const decision = entry?.decision ?? null;
+    const effective = hashMatches ? decision : null;
+    return {
+        state: effective === "seen" || effective === "approved" ? "seen" : "pending",
+        decision,
+        hashMatches,
+        isStale: decision !== null && !hashMatches,
+        comments: (entry?.comments ?? []).map((comment) => ({
+            id: comment.id,
+            body: comment.body,
+            createdAt: comment.created_at,
+        })),
+        reviewedAt: entry?.reviewed_at ?? null,
+    };
+}
+export function nowIso(date = new Date()) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function newCommentId() {
+    return randomUUID().toUpperCase();
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (isRecord(value)) {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            const inner = value[key];
+            if (inner !== undefined)
+                sorted[key] = sortKeys(inner);
+        }
+        return sorted;
+    }
+    return value;
+}
+export function serializeReviewDocument(document) {
+    return `${JSON.stringify(sortKeys(document), null, 2)}\n`;
+}
+export async function writeReviewDocument(directory, document) {
+    const target = path.join(directory, REVIEW_FILE);
+    const temp = path.join(directory, `.review.tmp.${randomUUID()}`);
+    await fs.promises.writeFile(temp, serializeReviewDocument(document), { flag: "wx" });
+    try {
+        await fs.promises.rename(temp, target);
+    }
+    catch (error) {
+        await fs.promises.rm(temp, { force: true });
+        throw error;
+    }
+}
+/** A run-id change starts a fresh review map, exactly like the app. */
+export function resetReviewsIfNeeded(document, runId) {
+    if (runId !== null && document.run_id !== runId) {
+        document.run_id = runId;
+        document.reviews = {};
+    }
+}
+async function stampOf(filePath) {
+    try {
+        const stat = await fs.promises.stat(filePath);
+        return { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
+function sameStamp(a, b) {
+    return a?.mtimeMs === b?.mtimeMs && a?.size === b?.size;
+}
+async function loadForWrite(directory) {
+    const stamp = await stampOf(path.join(directory, REVIEW_FILE));
+    const document = await readReviewDocument(directory);
+    if (document === null) {
+        throw new Error(`review.json in ${directory} is not valid JSON; refusing to overwrite it`);
+    }
+    return { document, stamp };
+}
+/**
+ * Read → mutate → write, re-reading when another writer (the macOS app, a
+ * second tray) changed the file in between so neither side's update is lost.
+ */
+async function mutateReviewDocument(directory, mutate) {
+    const target = path.join(directory, REVIEW_FILE);
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const { document, stamp } = await loadForWrite(directory);
+        const result = await mutate(document);
+        if (!sameStamp(stamp, await stampOf(target)))
+            continue;
+        await writeReviewDocument(directory, document);
+        return result;
+    }
+    throw new Error(`review.json in ${directory} kept changing underneath this write; try again`);
+}
+function appendComment(entry, body, now) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        throw new Error("Feedback cannot be empty");
+    const comment = { id: newCommentId(), body: trimmed, created_at: now };
+    entry.comments = [...(entry.comments ?? []), comment];
+    return { id: comment.id, body: comment.body, createdAt: comment.created_at };
+}
+export async function markSeen(request, options = {}) {
+    const sha = await sha256File(request.targetPath);
+    return mutateReviewDocument(request.directory, (document) => {
+        resetReviewsIfNeeded(document, request.runId);
+        const now = nowIso(options.now);
+        const entry = document.reviews[request.fileName] ?? {};
+        if (options.comment?.trim())
+            appendComment(entry, options.comment, now);
+        entry.decision = "seen";
+        entry.reviewed_at = now;
+        entry.image_sha256 = sha;
+        document.reviews[request.fileName] = entry;
+        document.updated_at = now;
+        return snapshotFromEntry(entry, sha);
+    });
+}
+export async function addComment(request, body, options = {}) {
+    if (!body.trim())
+        throw new Error("Feedback cannot be empty");
+    const entry = await mutateReviewDocument(request.directory, (document) => {
+        resetReviewsIfNeeded(document, request.runId);
+        const now = nowIso(options.now);
+        const stored = document.reviews[request.fileName] ?? {};
+        appendComment(stored, body, now);
+        document.reviews[request.fileName] = stored;
+        document.updated_at = now;
+        return stored;
+    });
+    const sha = entry.image_sha256
+        ? (options.currentSha256 ?? (await sha256File(request.targetPath)))
+        : null;
+    return snapshotFromEntry(entry, sha);
+}

package/dist/data/scan.d.ts

@@ -0,0 +1,32 @@
+import type { HashCache } from "./hash-cache.js";
+import { type FeatureManifest } from "./manifest.js";
+import type { AstroshotTree, Shot } from "./model.js";
+import { type ReviewDocument } from "./review-store.js";
+export interface FindOptions {
+    maxDepth?: number;
+    skip?: Set<string>;
+    concurrency?: number;
+    onFound?: (astroshotDir: string) => void;
+    signal?: AbortSignal;
+}
+/** Breadth-first walk with bounded concurrency; never descends into a found tree. */
+export declare function findAstroshotDirs(roots: string[], options?: FindOptions): Promise<string[]>;
+export interface ShotContext {
+    worktreePath: string;
+    worktree: string;
+    feature: string;
+    featureDir: string;
+}
+interface FeatureListing {
+    files: Set<string>;
+}
+export declare function buildShot(imagePath: string, context: ShotContext, manifest: FeatureManifest | null, review: ReviewDocument | null, listing: FeatureListing, hashes: HashCache): Promise<Shot | null>;
+/** Every shot inside one feature directory, in directory order. */
+export declare function scanFeatureDir(featureDir: string, context: {
+    worktreePath: string;
+    worktree: string;
+}, hashes: HashCache): Promise<Shot[]>;
+/** Re-read one shot in place (after its image or sidecars changed). */
+export declare function rebuildShot(imagePath: string, context: ShotContext, hashes: HashCache): Promise<Shot | null>;
+export declare function scanTree(astroshotDir: string, hashes: HashCache): Promise<AstroshotTree>;
+export {};

package/dist/data/scan.js

@@ -0,0 +1,227 @@
+/**
+ * Discover `.astroshot` trees under the watch roots and load their shots.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadFrictionLogs } from "./friction.js";
+import { chaptersOf, matchManifestShot, parseFeatureStatus, parseIsoDate, readManifest, } from "./manifest.js";
+import { ASTROSHOT_DIR, FRICTION_DIR, MAX_SCAN_DEPTH, SKIP_DIRECTORIES, VIDEO_EXTENSIONS, frictionLogsDir, humanize, isImageFile, sequenceAndSlug, worktreeShort, } from "./paths.js";
+import { entryNeedsHash, readReviewDocument, scopedEntry, snapshotFromEntry, } from "./review-store.js";
+/** Breadth-first walk with bounded concurrency; never descends into a found tree. */
+export async function findAstroshotDirs(roots, options = {}) {
+    const maxDepth = options.maxDepth ?? MAX_SCAN_DEPTH;
+    const skip = options.skip ?? SKIP_DIRECTORIES;
+    const concurrency = options.concurrency ?? 16;
+    const found = [];
+    const queue = roots.map((root) => ({ dir: root, depth: 0 }));
+    let active = 0;
+    await new Promise((resolve) => {
+        const pump = () => {
+            if (options.signal?.aborted) {
+                if (active === 0)
+                    resolve();
+                return;
+            }
+            while (active < concurrency && queue.length > 0) {
+                const item = queue.shift();
+                active += 1;
+                void visit(item.dir, item.depth).finally(() => {
+                    active -= 1;
+                    if (queue.length === 0 && active === 0)
+                        resolve();
+                    else
+                        pump();
+                });
+            }
+            if (queue.length === 0 && active === 0)
+                resolve();
+        };
+        const visit = async (dir, depth) => {
+            let entries;
+            try {
+                entries = await fs.promises.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const name = entry.name;
+                // Follow a linked `.astroshot` itself, but never descend through other
+                // symlinks: they can loop and are rarely where captures live.
+                if (!entry.isDirectory() && !(name === ASTROSHOT_DIR && (await kindOf(dir, entry)) === "dir"))
+                    continue;
+                if (name === ASTROSHOT_DIR) {
+                    const astroshotDir = path.join(dir, name);
+                    found.push(astroshotDir);
+                    options.onFound?.(astroshotDir);
+                    continue;
+                }
+                if (name.startsWith(".") || skip.has(name))
+                    continue;
+                if (depth + 1 > maxDepth)
+                    continue;
+                queue.push({ dir: path.join(dir, name), depth: depth + 1 });
+            }
+        };
+        pump();
+    });
+    return found.sort();
+}
+/** Dirent kinds with symlinks resolved, so linked trees behave like real ones. */
+async function kindOf(parent, entry) {
+    if (entry.isFile())
+        return "file";
+    if (entry.isDirectory())
+        return "dir";
+    if (!entry.isSymbolicLink())
+        return "other";
+    try {
+        const stat = await fs.promises.stat(path.join(parent, entry.name));
+        return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "other";
+    }
+    catch {
+        return "other";
+    }
+}
+async function listFeature(featureDir) {
+    try {
+        const entries = await fs.promises.readdir(featureDir, { withFileTypes: true });
+        const files = new Set();
+        for (const entry of entries) {
+            if ((await kindOf(featureDir, entry)) === "file")
+                files.add(entry.name);
+        }
+        return { files };
+    }
+    catch {
+        return null;
+    }
+}
+function resolveVideo(entryVideo, fileName, files) {
+    if (entryVideo && entryVideo.trim())
+        return entryVideo;
+    const stem = fileName.replace(/\.[^.]+$/, "");
+    for (const extension of VIDEO_EXTENSIONS) {
+        const candidate = `${stem}.${extension}`;
+        if (files.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+async function reviewFor(document, fileName, runId, imagePath, stat, hashes) {
+    if (!document)
+        return null;
+    const entry = scopedEntry(document, fileName, runId);
+    let sha = null;
+    if (entryNeedsHash(entry)) {
+        try {
+            sha = await hashes.hash(imagePath, stat);
+        }
+        catch {
+            sha = null;
+        }
+    }
+    return snapshotFromEntry(entry, sha);
+}
+export async function buildShot(imagePath, context, manifest, review, listing, hashes) {
+    let stat;
+    try {
+        stat = await fs.promises.stat(imagePath);
+    }
+    catch {
+        return null;
+    }
+    const fileName = path.basename(imagePath);
+    const entry = matchManifestShot(manifest, fileName);
+    const parsed = sequenceAndSlug(fileName);
+    const slug = entry?.slug ?? parsed.slug;
+    const runId = manifest?.run_id ?? null;
+    const videoFileName = resolveVideo(entry?.video, fileName, listing.files);
+    const videoExists = videoFileName !== null && listing.files.has(videoFileName);
+    const durationMs = typeof entry?.duration_ms === "number" && entry.duration_ms > 0 ? entry.duration_ms : null;
+    return {
+        id: imagePath,
+        path: imagePath,
+        fileName,
+        worktreePath: context.worktreePath,
+        worktree: context.worktree,
+        worktreeShort: worktreeShort(context.worktree),
+        feature: context.feature,
+        featureDir: context.featureDir,
+        sequence: parsed.sequence ?? entry?.id ?? null,
+        slug,
+        title: entry?.title ?? humanize(slug),
+        description: entry?.description ?? "",
+        url: entry?.url ?? null,
+        runId,
+        status: parseFeatureStatus(manifest?.status),
+        capturedAt: parseIsoDate(entry?.captured_at) ?? stat.mtimeMs,
+        mtimeMs: stat.mtimeMs,
+        isMovie: (entry?.kind ?? "").toLowerCase() === "movie" || videoFileName !== null,
+        videoFileName,
+        videoPath: videoExists ? path.join(context.featureDir, videoFileName) : null,
+        durationMs,
+        source: entry?.source ?? null,
+        chapters: chaptersOf(entry),
+        review: await reviewFor(review, fileName, runId, imagePath, stat, hashes),
+    };
+}
+async function readReviewSafely(directory) {
+    try {
+        return await readReviewDocument(directory);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every shot inside one feature directory, in directory order. */
+export async function scanFeatureDir(featureDir, context, hashes) {
+    const listing = await listFeature(featureDir);
+    if (!listing)
+        return [];
+    const feature = path.basename(featureDir);
+    const [manifest, review] = await Promise.all([readManifest(featureDir), readReviewSafely(featureDir)]);
+    const shotContext = { ...context, feature, featureDir };
+    const shots = [];
+    for (const name of listing.files) {
+        if (!isImageFile(name))
+            continue;
+        const shot = await buildShot(path.join(featureDir, name), shotContext, manifest, review, listing, hashes);
+        if (shot)
+            shots.push(shot);
+    }
+    return shots;
+}
+/** Re-read one shot in place (after its image or sidecars changed). */
+export async function rebuildShot(imagePath, context, hashes) {
+    const listing = await listFeature(context.featureDir);
+    if (!listing)
+        return null;
+    const [manifest, review] = await Promise.all([
+        readManifest(context.featureDir),
+        readReviewSafely(context.featureDir),
+    ]);
+    return buildShot(imagePath, context, manifest, review, listing, hashes);
+}
+export async function scanTree(astroshotDir, hashes) {
+    const worktreePath = path.dirname(astroshotDir);
+    const worktree = path.basename(worktreePath);
+    const context = { worktreePath, worktree };
+    let entries = [];
+    try {
+        entries = await fs.promises.readdir(astroshotDir, { withFileTypes: true });
+    }
+    catch {
+        entries = [];
+    }
+    const shots = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === FRICTION_DIR)
+            continue;
+        if ((await kindOf(astroshotDir, entry)) !== "dir")
+            continue;
+        shots.push(...(await scanFeatureDir(path.join(astroshotDir, entry.name), context, hashes)));
+    }
+    const frictionLogs = await loadFrictionLogs(frictionLogsDir(astroshotDir), context, hashes);
+    return { astroshotDir, worktreePath, worktree, shots, frictionLogs };
+}

package/dist/data/store.d.ts

@@ -0,0 +1,92 @@
+import type { FrictionLog, FrictionRun, Shot } from "./model.js";
+import { type WatchEvent } from "./watcher.js";
+export type ScanPhase = "idle" | "warm" | "shallow" | "full";
+/** Depth of the quick pass that finds repo-level trees almost instantly. */
+export declare const SHALLOW_DEPTH = 3;
+/** A deep walk this recent is skipped at startup; `r` always forces one. */
+export declare const FULL_SCAN_TTL_MS: number;
+export interface StoreEvent {
+    kind: "new-shot" | "updated-shot";
+    shot: Shot;
+    at: number;
+}
+export interface StoreState {
+    roots: string[];
+    shots: Shot[];
+    frictionLogs: FrictionLog[];
+    treeCount: number;
+    scanning: boolean;
+    phase: ScanPhase;
+    watching: boolean;
+    unreadCount: number;
+    lastEvent: StoreEvent | null;
+    error: string | null;
+    revision: number;
+}
+export interface StoreOptions {
+    roots: string[];
+    indexPath?: string;
+    /** Skip the durable index (tests). */
+    useIndex?: boolean;
+    watch?: boolean;
+    settleMs?: number;
+    onLog?: (message: string) => void;
+}
+type Listener = () => void;
+export declare class ReviewStore {
+    private state;
+    private readonly listeners;
+    private readonly trees;
+    private readonly shotsByPath;
+    private arrivalOrder;
+    private readonly hashes;
+    private watcher;
+    private queue;
+    private readonly options;
+    private index;
+    private disposed;
+    private saveTimer;
+    private fullScanAt;
+    /** Arrival order frozen at scan start so batches do not reorder the stream. */
+    private scanBaseOrder;
+    constructor(options: StoreOptions);
+    getState(): StoreState;
+    subscribe(listener: Listener): () => void;
+    private publish;
+    private log;
+    /** Serialize mutations. */
+    private enqueue;
+    start(): Promise<void>;
+    /**
+     * Warm scan from the index, a shallow walk for repo-level trees, then a
+     * deep walk when the index is stale (or when forced by the user).
+     */
+    rescan(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    private scanTrees;
+    /** Rebuild the flat, ordered shot and friction lists from the trees. */
+    private recompute;
+    private orderedShots;
+    private scheduleSave;
+    private saveIndexNow;
+    handleEvent(event: WatchEvent): Promise<void>;
+    private treeFor;
+    private ingestShot;
+    private refreshFeature;
+    private refreshFriction;
+    private refreshTree;
+    /** The user opened the stream: clear the unread badge. */
+    markOpened(): void;
+    markShotSeen(shot: Shot, comment?: string): Promise<Shot>;
+    addShotComment(shot: Shot, body: string): Promise<Shot>;
+    private reloadShot;
+    /** Mark many shots seen; failures are counted, never fatal. */
+    markManySeen(shots: Shot[]): Promise<{
+        ok: number;
+        failed: number;
+    }>;
+    markFrictionRunSeen(log: FrictionLog, run: FrictionRun): Promise<void>;
+    dispose(): Promise<void>;
+}
+export {};