plotlink-ows 1.0.33 → 1.2.94

package/app/lib/clean-image-sync.ts

@@ -0,0 +1,245 @@
+import type { Cut } from "./cuts";
+
+export interface CleanImageSyncResult {
+  cuts: Cut[];
+  changed: boolean;
+  synced: number[];
+  /** Cut ids whose stale recorded `cleanImagePath` was cleared back to null
+   *  because the referenced file no longer exists and no valid candidate was
+   *  found (#302). */
+  cleared: number[];
+}
+
+/** A recorded cut asset path that no longer points to a valid local image. */
+export interface StaleAssetIssue {
+  cutId: number;
+  field: "cleanImagePath" | "finalImagePath";
+  path: string;
+  message: string;
+}
+
+/** Preference order for clean-image extensions when several files exist. */
+export const CLEAN_IMAGE_EXTENSIONS = ["webp", "jpg", "jpeg"] as const;
+
+/** Image type detected from a file's leading magic bytes. */
+export type SniffedType = "webp" | "jpeg" | "png" | "unknown";
+
+/**
+ * Detect an image type from leading magic bytes. Pure (no filesystem). Returns
+ * "unknown" for non-image / mismatched / too-short input.
+ *
+ *  - JPEG: FF D8 FF
+ *  - PNG:  89 50 4E 47 0D 0A 1A 0A
+ *  - WebP: bytes 0-3 = "RIFF" (52 49 46 46) AND bytes 8-11 = "WEBP" (57 45 42 50)
+ */
+export function sniffImageType(bytes: Uint8Array): SniffedType {
+  // JPEG: FF D8 FF
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return "jpeg";
+  }
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47 &&
+    bytes[4] === 0x0d &&
+    bytes[5] === 0x0a &&
+    bytes[6] === 0x1a &&
+    bytes[7] === 0x0a
+  ) {
+    return "png";
+  }
+  // WebP: "RIFF" .... "WEBP"
+  if (
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  ) {
+    return "webp";
+  }
+  return "unknown";
+}
+
+/**
+ * Validate that an uploaded file's actual magic bytes match its claimed image
+ * MIME type. Pure (no fs). Used by the manual `upload-clean` route (#266) so a
+ * renamed text/PNG file labeled `image/webp` cannot be recorded as a clean
+ * image. Only the cartoon clean-image formats (WebP/JPEG) are accepted.
+ */
+export function cleanImageBytesMatchMime(bytes: Uint8Array, mime: string): boolean {
+  const expected: SniffedType | null =
+    mime === "image/webp" ? "webp" : mime === "image/jpeg" ? "jpeg" : null;
+  if (expected === null) return false;
+  return sniffImageType(bytes) === expected;
+}
+
+/** Canonical clean-image relative paths for a cut, in preference order. */
+export function cleanImageCandidates(plotFile: string, cutId: number): string[] {
+  const padded = String(cutId).padStart(2, "0");
+  return CLEAN_IMAGE_EXTENSIONS.map((ext) => `assets/${plotFile}/cut-${padded}-clean.${ext}`);
+}
+
+/**
+ * Pure detector that records `cleanImagePath` for cuts whose clean image
+ * actually exists on disk. The caller injects `fileExists(relPath)` so this
+ * function performs no filesystem access and no mime/size validation — those
+ * are the route's responsibility (the route's `fileExists` should return true
+ * ONLY for files that exist AND pass validation).
+ *
+ * Rules (idempotent, only-if-exists, never fake):
+ *  - For each cut, find the first existing canonical candidate (webp > jpg >
+ *    jpeg > png).
+ *  - Set `cleanImagePath` to the found file ONLY when:
+ *      (a) the cut's current path is null and a file is found; or
+ *      (b) the cut's current path is set but no longer exists on disk (stale/
+ *          broken) AND a different existing file is found.
+ *  - A cut whose current `cleanImagePath` still exists on disk is preserved
+ *    (manual uploads are never clobbered).
+ *  - A recorded `cleanImagePath` whose file no longer exists/validates is
+ *    cleared back to null when no valid candidate is found, so the cut plan
+ *    stops claiming a clean image that isn't there (#302). A cut already null
+ *    stays null.
+ *
+ * Returns a new array; the input is not mutated.
+ */
+export function syncCleanImages(
+  cuts: Cut[],
+  plotFile: string,
+  fileExists: (relPath: string) => boolean,
+): CleanImageSyncResult {
+  const synced: number[] = [];
+  const cleared: number[] = [];
+  let changed = false;
+
+  const next = cuts.map((cut) => {
+    const current = cut.cleanImagePath;
+    const currentExists = current != null && fileExists(current);
+
+    // Preserve a still-valid manual/existing path.
+    if (currentExists) return cut;
+
+    const candidates = cleanImageCandidates(plotFile, cut.id);
+    const found = candidates.find((rel) => fileExists(rel)) ?? null;
+    if (!found) {
+      // No valid file for this cut. If a path was recorded but the file is
+      // gone/invalid (stale), clear it back to null rather than preserving a
+      // reference to a missing asset. Already-null cuts are untouched.
+      if (current !== null) {
+        changed = true;
+        cleared.push(cut.id);
+        return { ...cut, cleanImagePath: null };
+      }
+      return cut;
+    }
+
+    // (a) null → found, or (b) stale/broken path replaced by a different file.
+    if (current === null || current !== found) {
+      changed = true;
+      synced.push(cut.id);
+      return { ...cut, cleanImagePath: found };
+    }
+
+    return cut;
+  });
+
+  return { cuts: next, changed, synced, cleared };
+}
+
+/**
+ * Pure detector for cut asset paths recorded in cuts.json that no longer point
+ * to a valid local image (#302). The caller injects `assetExists(relPath)`,
+ * which must return true only when the file exists AND validates (exists, image
+ * bytes, size). Reports both `cleanImagePath` and `finalImagePath`; the cut
+ * label uses 1-based position to match the readiness messaging ("Cut N ...").
+ *
+ * Pure: no filesystem access, no mutation. Cuts with null paths produce no
+ * issue (an absent path is a normal not-yet-generated state, not staleness).
+ */
+const STALE_FIELDS = ["cleanImagePath", "finalImagePath"] as const;
+
+/** Build the precise stale-path issue for a cut field (1-based "Cut N" label). */
+function staleAssetIssue(
+  cut: Cut,
+  index: number,
+  field: "cleanImagePath" | "finalImagePath",
+  path: string,
+): StaleAssetIssue {
+  const noun = field === "cleanImagePath" ? "clean" : "final";
+  return {
+    cutId: cut.id,
+    field,
+    path,
+    message: `Cut ${index + 1} ${noun} image path is recorded but the file is missing`,
+  };
+}
+
+export function findStaleAssetPaths(
+  cuts: Cut[],
+  assetExists: (relPath: string) => boolean,
+): StaleAssetIssue[] {
+  const issues: StaleAssetIssue[] = [];
+  cuts.forEach((cut, i) => {
+    for (const field of STALE_FIELDS) {
+      const recorded = cut[field];
+      if (recorded && !assetExists(recorded)) {
+        issues.push(staleAssetIssue(cut, i, field, recorded));
+      }
+    }
+  });
+  return issues;
+}
+
+export interface ClearStaleResult {
+  cuts: Cut[];
+  changed: boolean;
+  cleared: StaleAssetIssue[];
+}
+
+/**
+ * Repair stale recorded asset paths (#302): clear any `cleanImagePath` /
+ * `finalImagePath` that no longer points to a valid local image back to null,
+ * while preserving valid paths. This is the real per-cut repair behind the UI's
+ * "Clear stale path" action — unlike `syncCleanImages` (clean-only), it also
+ * clears a stale `finalImagePath`, so a final-only stale cut is actually
+ * repairable rather than left blocking publish.
+ *
+ * Already-uploaded cuts (`uploadedUrl` set) are left untouched — their content
+ * is on IPFS, so a missing LOCAL file is not a defect to repair, and their
+ * `uploadedCid`/`uploadedUrl` are never modified.
+ *
+ * Pure: no filesystem access. `assetExists(relPath)` must return true only for a
+ * real, valid image on disk.
+ */
+export function clearStaleAssetPaths(
+  cuts: Cut[],
+  assetExists: (relPath: string) => boolean,
+): ClearStaleResult {
+  const cleared: StaleAssetIssue[] = [];
+  let changed = false;
+
+  const next = cuts.map((cut, i) => {
+    // Preserve already-uploaded cuts (content is on IPFS).
+    if (cut.uploadedUrl) return cut;
+
+    let result = cut;
+    for (const field of STALE_FIELDS) {
+      const recorded = cut[field];
+      if (recorded && !assetExists(recorded)) {
+        cleared.push(staleAssetIssue(cut, i, field, recorded));
+        result = { ...result, [field]: null };
+        changed = true;
+      }
+    }
+    return result;
+  });
+
+  return { cuts: next, changed, cleared };
+}

package/app/lib/codex-images.ts

@@ -0,0 +1,152 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Codex generated-image cache handoff (#403).
+ *
+ * Built-in image generation drops finished art into a CACHE such as
+ * `~/.codex/generated_images/.../ig_<hash>.png` — a PNG, often > 1MB — which the
+ * OWS clean-image slot cannot accept directly (it requires WebP/JPEG < 1MB) and
+ * the agent terminal cannot convert (image tooling is banned). Rather than make
+ * the writer hunt through that hidden cache in an OS file dialog, OWS surfaces
+ * the cache contents so they can import a generated image into a specific cut in
+ * one click; the browser then converts/compresses it exactly like a manual
+ * upload.
+ *
+ * This module is the path-safety + listing core for that handoff. It is pure
+ * path math + read-only fs, so the traversal guards are unit-testable without a
+ * running server.
+ */
+
+export interface CodexImageEntry {
+  /** Opaque, URL-safe token encoding the path RELATIVE to the cache root. */
+  token: string;
+  /** Base file name for display, e.g. `ig_0f26….png`. */
+  name: string;
+  /** File size in bytes. */
+  size: number;
+  /** Last-modified time (ms since epoch) — listings are newest first. */
+  mtimeMs: number;
+}
+
+/** Max images returned by a single listing (newest first). */
+export const CODEX_LIST_LIMIT = 40;
+/**
+ * Max raw bytes served for one cache image. A generated PNG is a few MB; this is
+ * a generous upper bound that still refuses to stream something pathological
+ * before the browser converts it down to the < 1MB final asset.
+ */
+export const CODEX_MAX_RAW_BYTES = 25 * 1024 * 1024;
+/** Bounded recursion so a huge or symlink-looping cache tree can't stall a scan. */
+const MAX_SCAN_DEPTH = 4;
+const MAX_SCAN_FILES = 2000;
+
+const IMAGE_EXTS = new Set(["png", "webp", "jpg", "jpeg"]);
+
+function hasImageExt(name: string): boolean {
+  return IMAGE_EXTS.has(path.extname(name).slice(1).toLowerCase());
+}
+
+/** URL-safe base64 of a cache-relative path (no `+`/`/`/`=` to break a URL). */
+export function encodeCodexToken(relPath: string): string {
+  return Buffer.from(relPath, "utf8").toString("base64url");
+}
+
+/**
+ * Decode a token back to a cache-relative path, returning null for anything
+ * unsafe up front: empty, undecodable to text, NUL-bearing, absolute, or
+ * containing a `..` segment. This is the FIRST of two traversal guards — the
+ * caller must still resolve against the cache root and re-check the boundary
+ * (see {@link resolveCodexImagePath}), because base64url decoding is lenient and
+ * a crafted token could still decode to a path that escapes the root.
+ */
+export function decodeCodexToken(token: string): string | null {
+  if (!token) return null;
+  let rel: string;
+  try {
+    rel = Buffer.from(token, "base64url").toString("utf8");
+  } catch {
+    return null;
+  }
+  if (!rel || rel.includes("\0")) return null;
+  if (path.isAbsolute(rel)) return null;
+  if (rel.split(/[\\/]/).some((seg) => seg === "..")) return null;
+  return rel;
+}
+
+/**
+ * Resolve a token to an absolute path that is GUARANTEED to sit inside the cache
+ * root, or null when the token is unsafe or escapes the root. Pure path math (no
+ * fs) so the boundary guard is unit-testable; the route layer adds a
+ * realpath/symlink re-check plus the image-content and size checks.
+ */
+export function resolveCodexImagePath(
+  root: string,
+  token: string,
+): { abs: string; relPath: string } | null {
+  const relPath = decodeCodexToken(token);
+  if (relPath == null) return null;
+  const rootResolved = path.resolve(root);
+  const abs = path.resolve(rootResolved, relPath);
+  // Boundary check on the resolved path — not a bare path.join — so a token that
+  // decodes to something escaping the root is rejected even if it slipped the
+  // up-front `..` check via odd separators.
+  if (abs !== rootResolved && !abs.startsWith(rootResolved + path.sep)) return null;
+  // A token decoding to "" resolves to the root dir itself, which is not a file.
+  if (abs === rootResolved) return null;
+  return { abs, relPath };
+}
+
+/**
+ * List recent image files under the Codex generated-image cache, newest first.
+ * Read-only and best-effort: a missing root yields `[]`, unreadable subtrees are
+ * skipped, and both recursion depth and file count are bounded so a pathological
+ * cache tree cannot stall the request.
+ */
+export function listCodexImages(root: string, limit: number = CODEX_LIST_LIMIT): CodexImageEntry[] {
+  const rootResolved = path.resolve(root);
+  if (!fs.existsSync(rootResolved)) return [];
+
+  const found: { relPath: string; name: string; size: number; mtimeMs: number }[] = [];
+  let scanned = 0;
+
+  const walk = (dir: string, depth: number) => {
+    if (depth > MAX_SCAN_DEPTH || scanned >= MAX_SCAN_FILES) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      if (scanned >= MAX_SCAN_FILES) return;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (ent.isFile() && hasImageExt(ent.name)) {
+        scanned++;
+        let st: fs.Stats;
+        try {
+          st = fs.statSync(full);
+        } catch {
+          continue;
+        }
+        found.push({
+          relPath: path.relative(rootResolved, full),
+          name: ent.name,
+          size: st.size,
+          mtimeMs: st.mtimeMs,
+        });
+      }
+    }
+  };
+
+  walk(rootResolved, 0);
+  found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return found.slice(0, limit).map((f) => ({
+    token: encodeCodexToken(f.relPath),
+    name: f.name,
+    size: f.size,
+    mtimeMs: f.mtimeMs,
+  }));
+}

package/app/lib/cut-asset-diagnostics.ts

@@ -0,0 +1,120 @@
+// Read-only per-cut asset diagnostics (#427).
+//
+// After an agent generates clean images on disk (outside the React UI), the app
+// needs a reliable way to NOTICE and EXPLAIN each cut's asset state — otherwise a
+// writer sees "image missing" or a prose preview even though files exist (the
+// god-cell pilot). `getCutStatus` in the UI trusts the recorded cuts.json fields
+// and never checks disk, so a recorded-but-missing/typoed path looks "ready".
+//
+// This classifies each cut's REAL asset state against the local story folder and
+// surfaces a precise per-cut reason when a recorded path doesn't resolve. Pure +
+// framework-free (the disk check is injected) so it's unit-testable and works for
+// genesis.cuts.json and plot-NN.cuts.json equally. Read-only: never mutates cuts.
+
+import { isTextPanel, type Cut } from "./cuts";
+
+export type CutAssetState =
+  | "planned"          // no recorded image path yet (or a text panel awaiting export)
+  | "needs-conversion" // a PNG clean image exists but must be converted to WebP/JPEG (#441)
+  | "missing"          // a path IS recorded in cuts.json but the file is absent/invalid on disk
+  | "clean-ready"      // a valid clean image exists on disk
+  | "final-ready"      // a valid exported final/lettered image exists on disk
+  | "uploaded";        // an uploaded URL/CID exists (content is on IPFS)
+
+export interface CutAssetDiagnostic {
+  cutId: number;
+  /** "image" | "text" — text panels need no clean image. */
+  kind: "image" | "text";
+  state: CutAssetState;
+  /**
+   * Precise reason when state is "missing", OR the raw unsupported-extension
+   * detail for "needs-conversion" (the UI hides it under "Technical details").
+   * Null otherwise.
+   */
+  issue: string | null;
+  /**
+   * For "needs-conversion": the relative path of the PNG clean image to convert
+   * (the client fetches + converts it to WebP). Null for every other state.
+   */
+  convertiblePng: string | null;
+}
+
+export interface AssetDiagnosticsSummary {
+  planned: number;
+  needsConversion: number;
+  missing: number;
+  cleanReady: number;
+  finalReady: number;
+  uploaded: number;
+}
+
+/**
+ * Classify one cut's asset state against disk. `assetIssue(relPath)` returns null
+ * when the recorded path is a valid local image asset, else a precise reason
+ * (missing file, wrong type, too large, traversal) — typically `imageAssetIssue`.
+ *
+ * Precedence mirrors the production pipeline AND the existing stale-path logic:
+ * an uploaded cut is "uploaded" regardless of local files (content is on IPFS);
+ * otherwise the most-advanced recorded path wins, and a recorded-but-broken path
+ * is surfaced as "missing" with the precise reason rather than silently trusted.
+ */
+/**
+ * Classify one cut's asset state against disk. `assetIssue(relPath)` returns the
+ * publish-strict validity (WebP/JPEG, ≤1MB, magic-byte match). `pngClean(cut)`
+ * returns the relative path of a convertible PNG clean image for this cut (or
+ * null) — when a cut has no VALID clean image but a PNG one exists, that is a
+ * friendly "needs-conversion" step (#441), not a red unsupported-extension
+ * error. Defaults to no-PNG so existing callers/tests are unaffected.
+ */
+export function diagnoseCutAsset(
+  cut: Cut,
+  assetIssue: (relPath: string) => string | null,
+  pngClean: (cut: Cut) => string | null = () => null,
+): CutAssetDiagnostic {
+  const kind: "image" | "text" = isTextPanel(cut) ? "text" : "image";
+  const label = `Cut ${cut.id}`;
+  // Text panels never need a clean image, so they are never "needs-conversion".
+  const png = kind === "image" ? pngClean(cut) : null;
+
+  if (cut.uploadedUrl || cut.uploadedCid) {
+    return { cutId: cut.id, kind, state: "uploaded", issue: null, convertiblePng: null };
+  }
+  if (cut.finalImagePath) {
+    const issue = assetIssue(cut.finalImagePath);
+    return issue
+      ? { cutId: cut.id, kind, state: "missing", issue: `${label}: final image "${cut.finalImagePath}" — ${issue}`, convertiblePng: null }
+      : { cutId: cut.id, kind, state: "final-ready", issue: null, convertiblePng: null };
+  }
+  if (cut.cleanImagePath) {
+    const issue = assetIssue(cut.cleanImagePath);
+    if (!issue) return { cutId: cut.id, kind, state: "clean-ready", issue: null, convertiblePng: null };
+    // Recorded clean path is invalid. A real PNG (the usual cause) is a normal
+    // conversion step; keep the raw reason as a hide-able technical detail.
+    if (png) return { cutId: cut.id, kind, state: "needs-conversion", issue: `${label}: clean image "${cut.cleanImagePath}" — ${issue}`, convertiblePng: png };
+    return { cutId: cut.id, kind, state: "missing", issue: `${label}: clean image "${cut.cleanImagePath}" — ${issue}`, convertiblePng: null };
+  }
+  // No recorded path: a PNG clean image may still be sitting on disk (the agent
+  // wrote it but didn't record it) — offer conversion rather than "image missing".
+  if (png) return { cutId: cut.id, kind, state: "needs-conversion", issue: null, convertiblePng: png };
+  // Otherwise a not-yet-produced image cut or a text panel awaiting export.
+  return { cutId: cut.id, kind, state: "planned", issue: null, convertiblePng: null };
+}
+
+export function diagnoseCutAssets(
+  cuts: Cut[],
+  assetIssue: (relPath: string) => string | null,
+  pngClean: (cut: Cut) => string | null = () => null,
+): CutAssetDiagnostic[] {
+  return cuts.map((cut) => diagnoseCutAsset(cut, assetIssue, pngClean));
+}
+
+export function summarizeAssetDiagnostics(diags: CutAssetDiagnostic[]): AssetDiagnosticsSummary {
+  return {
+    planned: diags.filter((d) => d.state === "planned").length,
+    needsConversion: diags.filter((d) => d.state === "needs-conversion").length,
+    missing: diags.filter((d) => d.state === "missing").length,
+    cleanReady: diags.filter((d) => d.state === "clean-ready").length,
+    finalReady: diags.filter((d) => d.state === "final-ready").length,
+    uploaded: diags.filter((d) => d.state === "uploaded").length,
+  };
+}