astroshot 0.2.1 → 0.2.2

package/node_modules/@archastro/astroshot-review/dist/data/paths.d.ts

@@ -0,0 +1,27 @@
+export declare const ASTROSHOT_DIR = ".astroshot";
+export declare const FRICTION_DIR = "friction-logs";
+/** Directories the scanner never descends into (mirrors the macOS app). */
+export declare const SKIP_DIRECTORIES: Set<string>;
+export declare const MAX_SCAN_DEPTH = 10;
+export declare const IMAGE_EXTENSIONS: Set<string>;
+export declare const VIDEO_EXTENSIONS: string[];
+export declare function extensionOf(fileName: string): string;
+export declare function isImageFile(fileName: string): boolean;
+export interface ShotPath {
+    worktreePath: string;
+    worktree: string;
+    feature: string;
+    featureDir: string;
+    fileName: string;
+}
+/** Accept only `<worktree>/.astroshot/<feature>/<image>`; friction logs are excluded. */
+export declare function parseShotPath(imagePath: string): ShotPath | null;
+export declare function sequenceAndSlug(fileName: string): {
+    sequence: string | null;
+    slug: string;
+};
+export declare function humanize(slug: string): string;
+export declare function worktreeShort(name: string): string;
+export declare function isInsideFrictionLogs(filePath: string): boolean;
+export declare function frictionLogsDir(astroshotDir: string): string;
+export declare function abbreviateHome(filePath: string, home: string): string;

package/node_modules/@archastro/astroshot-review/dist/data/paths.js

@@ -0,0 +1,98 @@
+import path from "node:path";
+export const ASTROSHOT_DIR = ".astroshot";
+export const FRICTION_DIR = "friction-logs";
+/** Directories the scanner never descends into (mirrors the macOS app). */
+export const SKIP_DIRECTORIES = new Set([
+    "node_modules",
+    ".git",
+    "DerivedData",
+    "build",
+    ".build",
+    "Pods",
+    ".next",
+    "dist",
+    "out",
+    "target",
+    "vendor",
+    "Checkouts",
+    "xcuserdata",
+    ".turbo",
+    ".cache",
+    "coverage",
+    "tmp",
+    ".pnpm-store",
+    "Carthage",
+    "bazel-bin",
+    "bazel-out",
+    "bazel-testlogs",
+    ".gradle",
+]);
+export const MAX_SCAN_DEPTH = 10;
+export const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "webp", "gif"]);
+export const VIDEO_EXTENSIONS = ["webm", "mp4", "mov", "m4v"];
+export function extensionOf(fileName) {
+    return path.extname(fileName).slice(1).toLowerCase();
+}
+export function isImageFile(fileName) {
+    return IMAGE_EXTENSIONS.has(extensionOf(fileName));
+}
+/** Accept only `<worktree>/.astroshot/<feature>/<image>`; friction logs are excluded. */
+export function parseShotPath(imagePath) {
+    const fileName = path.basename(imagePath);
+    if (!isImageFile(fileName))
+        return null;
+    const featureDir = path.dirname(imagePath);
+    const feature = path.basename(featureDir);
+    if (!feature || feature === ASTROSHOT_DIR || feature === FRICTION_DIR)
+        return null;
+    const astroshotDir = path.dirname(featureDir);
+    if (path.basename(astroshotDir) !== ASTROSHOT_DIR)
+        return null;
+    if (imagePath.split(path.sep).includes(FRICTION_DIR))
+        return null;
+    const worktreePath = path.dirname(astroshotDir);
+    return {
+        worktreePath,
+        worktree: path.basename(worktreePath),
+        feature,
+        featureDir,
+        fileName,
+    };
+}
+export function sequenceAndSlug(fileName) {
+    const stem = fileName.replace(/\.[^.]+$/, "");
+    const dash = stem.indexOf("-");
+    if (dash > 0) {
+        const head = stem.slice(0, dash);
+        if (/^\d+$/.test(head))
+            return { sequence: head, slug: stem.slice(dash + 1) };
+    }
+    return { sequence: null, slug: stem };
+}
+export function humanize(slug) {
+    return slug
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export function worktreeShort(name) {
+    const match = /wt\d+/.exec(name);
+    if (match)
+        return match[0];
+    return name.length <= 8 ? name : name.slice(0, 6);
+}
+export function isInsideFrictionLogs(filePath) {
+    const parts = filePath.split(path.sep);
+    const index = parts.indexOf(ASTROSHOT_DIR);
+    return index !== -1 && parts[index + 1] === FRICTION_DIR;
+}
+export function frictionLogsDir(astroshotDir) {
+    return path.join(astroshotDir, FRICTION_DIR);
+}
+export function abbreviateHome(filePath, home) {
+    if (filePath === home)
+        return "~";
+    const prefix = home.endsWith(path.sep) ? home : `${home}${path.sep}`;
+    return filePath.startsWith(prefix) ? `~${path.sep}${filePath.slice(prefix.length)}` : filePath;
+}

package/node_modules/@archastro/astroshot-review/dist/data/review-store.d.ts

@@ -0,0 +1,67 @@
+import type { ReviewComment, ReviewSnapshot } from "./model.js";
+export declare const REVIEW_FILE = "review.json";
+export interface ReviewEntry {
+    decision?: string;
+    reviewed_at?: string;
+    image_sha256?: string;
+    comments?: ReviewComment[];
+}
+export interface ReviewDocument {
+    version: number;
+    run_id?: string;
+    updated_at?: string;
+    reviews: Record<string, StoredEntry>;
+}
+interface StoredComment {
+    id: string;
+    body: string;
+    created_at: string;
+}
+interface StoredEntry {
+    decision?: string;
+    reviewed_at?: string;
+    image_sha256?: string;
+    comments?: StoredComment[];
+}
+export declare class UnsupportedReviewVersion extends Error {
+    constructor(version: unknown);
+}
+export declare function emptyDocument(): ReviewDocument;
+/** Missing file → empty document. Malformed JSON → null (treated as unreadable). */
+export declare function readReviewDocument(directory: string): Promise<ReviewDocument | null>;
+export declare function parseReviewDocument(raw: string): ReviewDocument | null;
+export declare function sha256File(filePath: string): Promise<string>;
+export declare function sha256Bytes(bytes: Buffer): string;
+/** The entry that applies to `fileName`, or null when the run gate rejects it. */
+export declare function scopedEntry(document: ReviewDocument, fileName: string, expectedRunId: string | null): StoredEntry | null;
+/** Whether validating this entry needs the image's current hash. */
+export declare function entryNeedsHash(entry: StoredEntry | null): boolean;
+/**
+ * The seen/stale truth table from the app's `ReviewSnapshot`:
+ * hash mismatch hides the decision but keeps comments and flags staleness.
+ */
+export declare function snapshotFromEntry(entry: StoredEntry | null, currentSha256: string | null): ReviewSnapshot;
+export declare function nowIso(date?: Date): string;
+export declare function newCommentId(): string;
+export declare function serializeReviewDocument(document: ReviewDocument): string;
+export declare function writeReviewDocument(directory: string, document: ReviewDocument): Promise<void>;
+/** A run-id change starts a fresh review map, exactly like the app. */
+export declare function resetReviewsIfNeeded(document: ReviewDocument, runId: string | null): void;
+export interface ReviewWriteRequest {
+    /** Directory holding review.json (feature dir, or friction run dir). */
+    directory: string;
+    /** Key inside `reviews` (image file name, or `log.jsonl`). */
+    fileName: string;
+    runId: string | null;
+    /** Absolute path of the bytes to hash when marking seen. */
+    targetPath: string;
+}
+export declare function markSeen(request: ReviewWriteRequest, options?: {
+    comment?: string;
+    now?: Date;
+}): Promise<ReviewSnapshot>;
+export declare function addComment(request: ReviewWriteRequest, body: string, options?: {
+    currentSha256?: string | null;
+    now?: Date;
+}): Promise<ReviewSnapshot>;
+export {};

package/node_modules/@archastro/astroshot-review/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/node_modules/@archastro/astroshot-review/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/node_modules/@archastro/astroshot-review/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 };
+}