@archastro/astroshot-review 0.2.1

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

@@ -0,0 +1,22 @@
+import type { HashRecord } from "./hash-cache.js";
+export interface IndexDocument {
+    version: 1;
+    roots: string[];
+    astroshotDirs: string[];
+    arrivalOrder: string[];
+    hashes: Record<string, HashRecord>;
+    updatedAt: string;
+    /** When the last deep walk of every root finished (ISO), if ever. */
+    fullScanAt?: string;
+}
+export declare function indexCachePath(env?: NodeJS.ProcessEnv): string;
+export declare function loadIndex(roots: string[], filePath?: string): Promise<IndexDocument | null>;
+export declare function saveIndex(document: IndexDocument, filePath?: string): Promise<void>;
+/**
+ * Keep known paths in their prior relative order; new paths go first, sorted
+ * newest capture first. Paths that vanished are dropped.
+ */
+export declare function reconcileArrivalOrder(previous: string[], shots: Array<{
+    path: string;
+    capturedAt: number;
+}>): string[];

package/dist/data/index-cache.js

@@ -0,0 +1,64 @@
+/**
+ * Durable index so the tray opens instantly: known `.astroshot` directories,
+ * the newest-first arrival order, and memoized image hashes.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function indexCachePath(env = process.env) {
+    if (env.ASTROSHOT_REVIEW_CACHE_DIR)
+        return path.join(env.ASTROSHOT_REVIEW_CACHE_DIR, "index.json");
+    const base = env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+    return path.join(base, "astroshot-review", "index.json");
+}
+function normalizedRoots(roots) {
+    return [...roots].sort();
+}
+export async function loadIndex(roots, filePath = indexCachePath()) {
+    let raw;
+    try {
+        raw = await fs.promises.readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !Array.isArray(parsed.roots))
+            return null;
+        if (JSON.stringify(normalizedRoots(parsed.roots)) !== JSON.stringify(normalizedRoots(roots)))
+            return null;
+        return {
+            version: 1,
+            roots: parsed.roots,
+            astroshotDirs: Array.isArray(parsed.astroshotDirs) ? parsed.astroshotDirs : [],
+            arrivalOrder: Array.isArray(parsed.arrivalOrder) ? parsed.arrivalOrder : [],
+            hashes: parsed.hashes && typeof parsed.hashes === "object" ? parsed.hashes : {},
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+            fullScanAt: typeof parsed.fullScanAt === "string" ? parsed.fullScanAt : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveIndex(document, filePath = indexCachePath()) {
+    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    const temp = `${filePath}.${process.pid}.tmp`;
+    await fs.promises.writeFile(temp, JSON.stringify(document));
+    await fs.promises.rename(temp, filePath);
+}
+/**
+ * Keep known paths in their prior relative order; new paths go first, sorted
+ * newest capture first. Paths that vanished are dropped.
+ */
+export function reconcileArrivalOrder(previous, shots) {
+    const present = new Map(shots.map((shot) => [shot.path, shot.capturedAt]));
+    const kept = previous.filter((entry) => present.has(entry));
+    const known = new Set(kept);
+    const fresh = shots
+        .filter((shot) => !known.has(shot.path))
+        .sort((a, b) => b.capturedAt - a.capturedAt)
+        .map((shot) => shot.path);
+    return [...fresh, ...kept];
+}

package/dist/data/manifest.d.ts

@@ -0,0 +1,41 @@
+import type { Chapter, FeatureStatus } from "./model.js";
+export interface ManifestChapter {
+    slug?: string;
+    title?: string;
+    t_ms?: number;
+    tMs?: number;
+}
+export interface ManifestShot {
+    id?: string;
+    file?: string;
+    slug?: string;
+    title?: string;
+    description?: string;
+    captured_at?: string;
+    url?: string;
+    viewport?: unknown;
+    kind?: string;
+    video?: string;
+    poster?: string;
+    duration_ms?: number;
+    source?: string;
+    chapters?: ManifestChapter[];
+}
+export interface FeatureManifest {
+    version?: number;
+    feature?: string;
+    run_id?: string;
+    status?: string;
+    description?: string;
+    shots?: ManifestShot[];
+}
+export declare function readManifest(featureDir: string): Promise<FeatureManifest | null>;
+/** First match wins: file, poster, id (sequence), slug. */
+export declare function matchManifestShot(manifest: FeatureManifest | null, fileName: string): ManifestShot | null;
+export declare function parseFeatureStatus(raw: string | undefined | null): FeatureStatus | null;
+export declare function parseIsoDate(value: string | undefined | null): number | null;
+export declare function chaptersOf(entry: ManifestShot | null): Chapter[];
+/** `2.8s` under a minute, `m:ss` above; null when unknown. */
+export declare function durationLabel(durationMs: number | null | undefined): string | null;
+/** Chapter timestamp label used by the detail card. */
+export declare function chapterTimeLabel(tMs: number | undefined): string;

package/dist/data/manifest.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { sequenceAndSlug } from "./paths.js";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export async function readManifest(featureDir) {
+    let raw;
+    try {
+        raw = await fs.promises.readFile(path.join(featureDir, "manifest.json"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            return null;
+        const manifest = parsed;
+        if (manifest.shots !== undefined && !Array.isArray(manifest.shots))
+            manifest.shots = [];
+        return manifest;
+    }
+    catch {
+        return null;
+    }
+}
+/** First match wins: file, poster, id (sequence), slug. */
+export function matchManifestShot(manifest, fileName) {
+    const shots = manifest?.shots ?? [];
+    if (shots.length === 0)
+        return null;
+    const { sequence, slug } = sequenceAndSlug(fileName);
+    return (shots.find((shot) => shot.file === fileName) ??
+        shots.find((shot) => shot.poster === fileName) ??
+        (sequence ? shots.find((shot) => shot.id === sequence) : undefined) ??
+        shots.find((shot) => shot.slug === slug) ??
+        null);
+}
+export function parseFeatureStatus(raw) {
+    switch ((raw ?? "").toLowerCase()) {
+        case "running":
+        case "run":
+        case "in_progress":
+        case "in-progress":
+            return "running";
+        case "pass":
+        case "passed":
+        case "ok":
+        case "success":
+            return "pass";
+        case "fail":
+        case "failed":
+        case "error":
+            return "fail";
+        case "idle":
+        case "pending":
+            return "idle";
+        default:
+            return null;
+    }
+}
+export function parseIsoDate(value) {
+    if (!value)
+        return null;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? time : null;
+}
+export function chaptersOf(entry) {
+    if (!entry?.chapters || !Array.isArray(entry.chapters))
+        return [];
+    return entry.chapters.filter(isRecord).map((chapter) => ({
+        slug: typeof chapter.slug === "string" ? chapter.slug : undefined,
+        title: typeof chapter.title === "string" ? chapter.title : undefined,
+        tMs: typeof chapter.t_ms === "number"
+            ? chapter.t_ms
+            : typeof chapter.tMs === "number"
+                ? chapter.tMs
+                : undefined,
+    }));
+}
+/** `2.8s` under a minute, `m:ss` above; null when unknown. */
+export function durationLabel(durationMs) {
+    if (durationMs === null || durationMs === undefined || durationMs <= 0)
+        return null;
+    const seconds = durationMs / 1000;
+    if (seconds < 60) {
+        const rounded = Math.round(seconds * 10) / 10;
+        return Number.isInteger(rounded) ? `${rounded}s` : `${rounded.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const rest = Math.floor(seconds % 60);
+    return `${minutes}:${String(rest).padStart(2, "0")}`;
+}
+/** Chapter timestamp label used by the detail card. */
+export function chapterTimeLabel(tMs) {
+    if (tMs === undefined || tMs < 0)
+        return "—";
+    const seconds = tMs / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = Math.floor(seconds % 60);
+    return `${minutes}:${String(rest).padStart(2, "0")}`;
+}

package/dist/data/model.d.ts

@@ -0,0 +1,96 @@
+export type FeatureStatus = "running" | "pass" | "fail" | "idle";
+export interface Chapter {
+    slug?: string;
+    title?: string;
+    tMs?: number;
+}
+export interface ReviewComment {
+    id: string;
+    body: string;
+    createdAt: string;
+}
+export type ReviewState = "seen" | "pending";
+export interface ReviewSnapshot {
+    state: ReviewState;
+    /** Raw decision from disk, before hash scoping. */
+    decision: string | null;
+    hashMatches: boolean;
+    /** A decision exists but the bytes changed since it was recorded. */
+    isStale: boolean;
+    comments: ReviewComment[];
+    reviewedAt: string | null;
+}
+export interface Shot {
+    /** Absolute image path; stable identity. */
+    id: string;
+    path: string;
+    fileName: string;
+    worktreePath: string;
+    worktree: string;
+    worktreeShort: string;
+    feature: string;
+    featureDir: string;
+    sequence: string | null;
+    slug: string;
+    title: string;
+    description: string;
+    url: string | null;
+    runId: string | null;
+    status: FeatureStatus | null;
+    /** Epoch milliseconds. */
+    capturedAt: number;
+    mtimeMs: number;
+    isMovie: boolean;
+    videoFileName: string | null;
+    /** Absolute path when the video exists on disk. */
+    videoPath: string | null;
+    durationMs: number | null;
+    source: string | null;
+    chapters: Chapter[];
+    review: ReviewSnapshot | null;
+}
+export interface FrictionStep {
+    id: string;
+    step: number;
+    stepId: string;
+    title: string;
+    description: string;
+    transcript: string;
+    /** Absolute paths that exist on disk. */
+    screenshots: string[];
+    good: string[];
+    improve: string[];
+    url: string | null;
+    capturedAt: string | null;
+}
+export interface FrictionRun {
+    runId: string;
+    directory: string;
+    logPath: string | null;
+    capturedAt: number;
+    status: string | null;
+    steps: FrictionStep[];
+    review: ReviewSnapshot | null;
+}
+export interface FrictionLog {
+    /** `<worktreePath>::<slug>` */
+    id: string;
+    slug: string;
+    directory: string;
+    worktreePath: string;
+    worktree: string;
+    worktreeShort: string;
+    title: string;
+    description: string;
+    status: string | null;
+    updatedAt: number;
+    promptPath: string | null;
+    runs: FrictionRun[];
+}
+export interface AstroshotTree {
+    astroshotDir: string;
+    worktreePath: string;
+    worktree: string;
+    shots: Shot[];
+    frictionLogs: FrictionLog[];
+}

package/dist/data/model.js

@@ -0,0 +1 @@
+export {};

package/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/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/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 {};