slidemind 0.3.20 → 0.4.1

package/src/lib/image-use-overrides.mjs

@@ -0,0 +1,279 @@
+// Image uses recorded by a TARGETED EDIT — a change to a slide that already
+// exists, made without a plan stage.
+//
+//   <workspace>/state/image-use-overrides.json
+//   { "version": 1, "slides": [ { "slideId", "assetUses": [...], "revision" } ] }
+//
+// Three rules, all of them load-bearing:
+//
+//   * **Keyed by the slide's durable identity, never its number.** `slideId` is
+//     the deck's own slide GUID (src/lib/slide-guids.mjs), which survives the
+//     rename-every-file reorder that IS the common deck edit. A positional key
+//     would silently re-point an obligation at a different slide the first time
+//     someone drags a card (design decision 8).
+//   * **An entry REPLACES, it does not patch.** The list is that slide's whole
+//     set of uses. An explicit `[]` is therefore meaningful: it is the record
+//     of an authorized clearing, and it is exactly what keeps a removed
+//     obligation removed — deleting the entry instead would fall back to the
+//     plan's uses and resurrect it.
+//   * **The plan wins again at the next approval.** `reconcileImageUseOverrides`
+//     (src/builders/image-use-reconcile.mjs, where the plan markdown lives)
+//     folds each entry into its slide's storyboard and clears only the entries
+//     it superseded. Everything here is the file half of that.
+//
+// Effective uses for a slide = its override if it has one, else its storyboard
+// uses. That selection is `selectImageIntent` in the shared contract module;
+// this file only supplies it the right slideId.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { statePath } from "./deck-paths.mjs";
+import { imageAssetError, readImageAssetManifest } from "./image-assets.mjs";
+import {
+  IMAGE_INTENT_VERSION,
+  parseImageUseOverrides,
+  selectImageIntent,
+  validateSlideUses,
+} from "./image-intent.mjs";
+import { readRevision, slideFileOrder } from "./revision.mjs";
+import { reconcileSlideGuids } from "./slide-guids.mjs";
+
+export const OVERRIDES_FILE = "image-use-overrides.json";
+
+export function overridesPath(workspaceDir) {
+  return statePath(workspaceDir, OVERRIDES_FILE);
+}
+
+const EMPTY = () => ({ version: IMAGE_INTENT_VERSION, slides: [] });
+
+function readRaw(workspaceDir) {
+  const file = overridesPath(workspaceDir);
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return null;
+    throw imageAssetError("image_asset_missing", `${file} could not be read: ${err.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw imageAssetError("image_intent_invalid", `${file} is not valid JSON: ${err.message}`);
+  }
+}
+
+/**
+ * The deck's overrides. An absent file is an empty set; a present one that does
+ * not parse is an error, never an empty set — starting over silently would drop
+ * every obligation a targeted edit recorded.
+ *
+ * Cross-references the deck's image registry, so an override can never point at
+ * an asset this deck does not have.
+ */
+export function readImageUseOverrides(workspaceDir) {
+  const raw = readRaw(workspaceDir);
+  if (raw === null) return EMPTY();
+  const assetIds = readImageAssetManifest(workspaceDir).assets.map((a) => a.assetId);
+  const result = parseImageUseOverrides(raw, { assetIds });
+  if (!result.value) {
+    const first = result.issues[0];
+    throw imageAssetError(
+      first?.code ?? "image_intent_invalid",
+      `${overridesPath(workspaceDir)}: ${first?.message ?? "invalid overrides"}`,
+    );
+  }
+  return result.value;
+}
+
+/**
+ * Which edit each entry was recorded by:
+ * `{ [slideId]: {generation, recordedAt} }`.
+ *
+ * Read off the raw file, because the contract's parser returns the obligation
+ * and nothing else — provenance is per-client bookkeeping, not part of the
+ * record both repositories validate. It lives under one agreed key, `revision`,
+ * so neither side has to widen the shared schema to carry its own fields: the
+ * CLI writes the deck's revision `generation`, the add-in writes its run and
+ * operation ids, and each ignores the other's. Best effort: a missing or
+ * malformed stamp costs nothing that an obligation depends on.
+ */
+export function readOverrideProvenance(workspaceDir) {
+  const raw = readRaw(workspaceDir);
+  const out = {};
+  for (const entry of raw?.slides ?? []) {
+    if (!entry || typeof entry.slideId !== "string") continue;
+    const revision = entry.revision ?? {};
+    out[entry.slideId] = {
+      generation: Number.isInteger(revision.generation) ? revision.generation : null,
+      recordedAt: typeof revision.recordedAt === "string" ? revision.recordedAt : null,
+    };
+  }
+  return out;
+}
+
+/** Write-then-rename, so a reader sees the old set or the new one, never half. */
+export function writeImageUseOverrides(workspaceDir, doc) {
+  const file = overridesPath(workspaceDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(doc, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// ---------------------------------------------------------------------------
+// slide identity
+// ---------------------------------------------------------------------------
+
+/**
+ * The deck's slides in play order with the GUID each one is known by:
+ * `[{ slide, file, slideId }]`.
+ *
+ * Play order is filename order over jsx AND native .pptx alike
+ * (`slideFileOrder`), so slide numbers here are the numbers every other
+ * boundary means. A native slide has no GUID and simply has no `slideId` — it
+ * carries no authored image uses either.
+ *
+ * Reconciled, not merely read: the NN- prefix is the play order, so reordering
+ * a deck renames every slide file, and `reconcileSlideGuids` is what re-binds a
+ * renamed file to its GUID by content hash. Reading the sidecar raw would lose
+ * exactly the identity an override depends on, at exactly the edit it is
+ * supposed to survive. (It is the same call every bake and render already makes,
+ * and it writes only when something moved.)
+ */
+export function slideIdentities(workspaceDir) {
+  const guids = reconcileSlideGuids(workspaceDir);
+  return slideFileOrder(workspaceDir).map((file, index) => ({
+    slide: index + 1,
+    file,
+    slideId: guids[`slides/${file}`] ?? null,
+  }));
+}
+
+/** The durable ID of slide number `n`, or null (new slide, native slide). */
+export function slideIdForNumber(workspaceDir, slide) {
+  return slideIdentities(workspaceDir).find((s) => s.slide === slide)?.slideId ?? null;
+}
+
+/** The current number of the slide `slideId` names, or null if it is gone. */
+export function slideNumberForId(workspaceDir, slideId) {
+  return slideIdentities(workspaceDir).find((s) => s.slideId === slideId)?.slide ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// reading and writing one slide's uses
+// ---------------------------------------------------------------------------
+
+/**
+ * The uses that actually apply to a slide: its override if one exists (an empty
+ * one included — that is a deliberate clearing), otherwise the storyboard uses
+ * the caller read out of the plan.
+ *
+ * @param {string} workspaceDir
+ * @param {{slide?: number, slideId?: string|null, storyboardUses?: Array}} args
+ * @returns {{uses: Array, source: "override"|"storyboard", slideId: string|null}}
+ */
+export function effectiveSlideUses(workspaceDir, { slide, slideId, storyboardUses = [] }) {
+  const id = slideId ?? (slide ? slideIdForNumber(workspaceDir, slide) : null);
+  const selected = selectImageIntent({
+    slideId: id,
+    storyboardUses,
+    overrides: readImageUseOverrides(workspaceDir),
+  });
+  return { ...selected, slideId: id };
+}
+
+/**
+ * Record one slide's complete use list.
+ *
+ * `uses` is validated through the contract's own parser against this deck's
+ * registry and against every OTHER entry's use IDs, so an override can neither
+ * invent an asset nor collide with an obligation elsewhere in the deck. An
+ * empty list is accepted and stored: it is the authorized clearing.
+ *
+ * The edit that recorded it is stamped alongside from the deck's existing
+ * revision metadata, which is what lets a later reader say which generation an
+ * obligation came from.
+ */
+export function setSlideImageUses(
+  workspaceDir,
+  slideId,
+  uses,
+  {
+    generation = readRevision(workspaceDir)?.generation ?? null,
+    recordedAt = new Date().toISOString(),
+  } = {},
+) {
+  const id = String(slideId ?? "").trim();
+  if (!id) throw imageAssetError("image_intent_invalid", "an image use override needs a slideId");
+
+  const current = readImageUseOverrides(workspaceDir);
+  const manifest = readImageAssetManifest(workspaceDir);
+  // Deck-wide useId uniqueness, minus this slide's own current entry — which is
+  // being replaced, so re-recording the same list is not a collision.
+  const seenUseIds = new Set();
+  for (const entry of current.slides) {
+    if (entry.slideId === id) continue;
+    for (const use of entry.assetUses) seenUseIds.add(use.useId);
+  }
+  const parsed = validateSlideUses(uses ?? [], {
+    assetIds: manifest.assets.map((a) => a.assetId),
+    seenUseIds,
+  });
+  if (!parsed.value) {
+    const first = parsed.issues[0];
+    throw imageAssetError(first?.code ?? "image_intent_invalid", first?.message ?? "invalid image uses");
+  }
+
+  // Other slides' entries are carried over from the RAW file, not from the
+  // parsed value: the contract's parser returns the obligation only, and
+  // rewriting parsed entries would strip the provenance stamp off every other
+  // slide as a side effect of touching this one.
+  const kept = (readRaw(workspaceDir)?.slides ?? []).filter(
+    (entry) => entry?.slideId !== id,
+  );
+  const doc = {
+    version: IMAGE_INTENT_VERSION,
+    slides: [
+      ...kept,
+      {
+        slideId: id,
+        assetUses: parsed.value,
+        revision: { ...(generation == null ? {} : { generation }), recordedAt },
+      },
+    ],
+  };
+  writeImageUseOverrides(workspaceDir, doc);
+  return { slideId: id, assetUses: parsed.value, generation, recordedAt };
+}
+
+/**
+ * Forget a slide's override entirely, so its plan storyboard governs again.
+ *
+ * This is NOT how an obligation is cleared — clearing is
+ * `setSlideImageUses(dir, id, [])`, which records that the slide is to carry no
+ * image. Dropping the entry falls back to the plan and would bring a use back.
+ */
+export function removeSlideOverride(workspaceDir, slideId) {
+  return clearSlideOverrides(workspaceDir, [slideId]) > 0;
+}
+
+/**
+ * Drop several entries in ONE write — what an approved plan revision does to
+ * the overrides it just superseded. Returns how many were dropped.
+ */
+export function clearSlideOverrides(workspaceDir, slideIds) {
+  const drop = new Set(slideIds);
+  if (!drop.size) return 0;
+  // readImageUseOverrides first: a file that does not parse must fail loudly
+  // rather than be quietly rewritten from its own unreadable contents.
+  readImageUseOverrides(workspaceDir);
+  // Kept entries are carried over from the RAW file so their provenance stamp
+  // survives a fold that had nothing to do with them.
+  const raw = readRaw(workspaceDir)?.slides ?? [];
+  const kept = raw.filter((entry) => !drop.has(entry?.slideId));
+  if (kept.length === raw.length) return 0;
+  writeImageUseOverrides(workspaceDir, { version: IMAGE_INTENT_VERSION, slides: kept });
+  return raw.length - kept.length;
+}