slidemind 0.3.20 → 0.4.1

package/src/lib/image-assets.mjs

@@ -0,0 +1,465 @@
+// The deck's image registry: immutable bytes, durably stored, identified by
+// their own digest.
+//
+//   <workspace>/assets/local/<assetId>.<ext>   the copied source, never rewritten
+//   <workspace>/state/image-assets.json        {version: 1, assets: [ImageAsset]}
+//
+// An entry says what bytes ARE (digest, sniffed MIME, intrinsic size, where
+// they came from). It says nothing about what they are FOR — that is an
+// AssetUse in the plan (src/lib/image-intent.mjs). Importing an image creates
+// no obligation to place it anywhere; that separation is the whole point of
+// having two records.
+//
+// Three rules the implementation exists to keep:
+//
+//   * **The bytes decide.** The MIME type and the dimensions are read from the
+//     header, never from the extension or a caller's claim — the same stance
+//     `extFromBytes` already takes for engine downloads, and for the same
+//     reason: a mislabelled asset renders wrong or not at all.
+//   * **Bytes first, manifest last.** The copy is written and its digest
+//     verified BEFORE the manifest is swapped in. A kill in between leaves an
+//     unreferenced file (harmless, nothing reads it) — never a committed entry
+//     pointing at bytes that are not there (design decision 8).
+//   * **Entries are immutable.** The same bytes keep the identity they were
+//     first given, so a use bound to an assetId can never come to mean a
+//     different picture. A replacement is a new import with a new ID.
+
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { extFromBytes } from "../bridge/engine-download.mjs";
+import { imageSizeFromBuffer, svgSizeFromMarkup } from "../bridge/image-dimensions.mjs";
+import { statePath } from "./deck-paths.mjs";
+import { exifOrientation, imageRenderPlan } from "./image-derivatives.mjs";
+import {
+  IMAGE_INTENT_VERSION,
+  SUPPORTED_IMAGE_MIME_TYPES,
+  parseImageAsset,
+  parseImageAssetManifest,
+} from "./image-intent.mjs";
+
+export const MANIFEST_FILE = "image-assets.json";
+/** Workspace-relative, POSIX, and the only shape `workspacePath` may take. */
+export const LOCAL_ASSET_DIR = "assets/local";
+
+// The same ceiling the add-in's image pipeline enforces (sharp's default pixel
+// limit, 0x3FFF²). A header declaring more is refused HERE, before any of it is
+// copied — `test/fixtures/image-intent/oversized-header.png` is 69 bytes
+// claiming 60000x60000.
+export const MAX_IMAGE_PIXELS = 268402689;
+
+// Sniffed extension → the MIME the contract speaks. bmp/tiff are listed on
+// purpose: `extFromBytes` recognises them, and naming them produces "this
+// pipeline cannot ship a BMP" instead of "unrecognised file".
+const EXT_MIME = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  tiff: "image/tiff",
+};
+
+// The recovery line for each code this module raises. The KEYS are drawn from
+// the contract's `IMAGE_INTENT_ISSUE_CODES` — this module declares no code of
+// its own, and `test/image-assets.test.mjs` fails if one appears here that the
+// shared vocabulary does not have.
+export const IMAGE_ASSET_ACTIONS = {
+  image_asset_unsupported: "Supply a source in a supported image format (PNG, JPEG, GIF, WebP or SVG).",
+  image_asset_too_large: "Supply an appropriately sized source; the original is never silently downsampled.",
+  image_asset_missing: "Restore or re-import the source file, then rebind anything that referenced it.",
+  image_asset_changed: "Re-import the new bytes as their own asset and update the use through the plan.",
+  image_intent_invalid: "Correct the named field and re-record the entry.",
+};
+
+/** A typed failure: `err.code` for machines, `err.issue` for the contract's issue list. */
+export function imageAssetError(code, message, extra = {}) {
+  const err = new Error(message);
+  err.code = code;
+  const action = IMAGE_ASSET_ACTIONS[code] ?? IMAGE_ASSET_ACTIONS.image_intent_invalid;
+  err.issue = { code, message, action, ...extra };
+  return err;
+}
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+// ---------------------------------------------------------------------------
+// inspection — the bytes decide
+// ---------------------------------------------------------------------------
+
+let crcTable = null;
+function crc32(bytes) {
+  if (!crcTable) {
+    crcTable = new Int32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      crcTable[n] = c;
+    }
+  }
+  let c = -1;
+  for (let i = 0; i < bytes.length; i++) c = crcTable[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+// A PNG signature is eight bytes anyone can write; the IHDR's CRC is what says
+// the header is really a header. Without this check a file whose "header" is
+// the word "nonsense" registers happily and then renders as nothing anywhere.
+function pngHeaderIntact(bytes) {
+  if (bytes.length < 33) return false;
+  if (bytes.readUInt32BE(8) !== 13 || bytes.toString("latin1", 12, 16) !== "IHDR") return false;
+  return crc32(bytes.subarray(12, 29)) === bytes.readUInt32BE(29);
+}
+
+// SVG has no magic number — it is XML — so it is identified the way the rest of
+// this CLI identifies it: the markup has to actually open an <svg> element.
+function svgMarkup(bytes) {
+  if (bytes.length > 4 * 1024 * 1024) return null; // a text scan has to stay bounded
+  const text = bytes.toString("utf8");
+  return /<svg[\s>]/i.test(text) ? text : null;
+}
+
+/**
+ * What these bytes are: `{mimeType, ext, width, height}`. The size is the one a
+ * viewer sees: a JPEG whose EXIF turns it a quarter turn reports its sides
+ * swapped (the add-in's registry reads the same), because crops, `<img>` boxes
+ * and the concept's image room are all expressed in it.
+ *
+ * Throws `image_asset_unsupported` for anything the pipeline cannot decode or
+ * ship, and `image_asset_too_large` for a header declaring more pixels than the
+ * renderer accepts. Pure — no filesystem, no manifest.
+ */
+export function inspectImageBytes(bytes, { displayName = "the file" } = {}) {
+  const unsupported = (why) =>
+    imageAssetError("image_asset_unsupported", `${displayName}: ${why}`);
+
+  if (!bytes || bytes.length === 0) throw unsupported("it is empty");
+
+  const markup = svgMarkup(bytes);
+  const ext = extFromBytes(bytes) ?? (markup ? "svg" : null);
+  const mimeType = ext ? (EXT_MIME[ext] ?? null) : null;
+  if (!mimeType) {
+    throw unsupported("its bytes are not a recognisable image (they decode as no supported format)");
+  }
+  if (!SUPPORTED_IMAGE_MIME_TYPES.includes(mimeType)) {
+    throw unsupported(
+      `${mimeType} is not one of the formats this pipeline can ship (${SUPPORTED_IMAGE_MIME_TYPES.join(", ")})`,
+    );
+  }
+  if (mimeType === "image/png" && !pngHeaderIntact(bytes)) {
+    throw unsupported("its PNG header is corrupt (the IHDR checksum does not match)");
+  }
+
+  const size = mimeType === "image/svg+xml" ? svgSizeFromMarkup(markup) : imageSizeFromBuffer(bytes);
+  if (!size) throw unsupported("its intrinsic dimensions could not be read from the header");
+
+  // An SVG states its size in user units, which a viewBox may write as
+  // fractions; the contract wants positive integers.
+  const turned = mimeType === "image/jpeg" && (exifOrientation(bytes) ?? 1) >= 5;
+  const width = Math.max(1, Math.round(turned ? size.height : size.width));
+  const height = Math.max(1, Math.round(turned ? size.width : size.height));
+  if (width * height > MAX_IMAGE_PIXELS) {
+    throw imageAssetError(
+      "image_asset_too_large",
+      `${displayName}: ${width}x${height} is past the ${MAX_IMAGE_PIXELS}-pixel limit the renderer accepts`,
+    );
+  }
+  return { mimeType, ext, width, height };
+}
+
+// ---------------------------------------------------------------------------
+// the manifest
+// ---------------------------------------------------------------------------
+
+export function manifestPath(workspaceDir) {
+  return statePath(workspaceDir, MANIFEST_FILE);
+}
+
+const EMPTY_MANIFEST = () => ({ version: IMAGE_INTENT_VERSION, assets: [] });
+
+/**
+ * The deck's registry. An absent file is an empty registry; a present one that
+ * does not parse is an error, never an empty one — silently starting over
+ * would orphan every use already bound to it.
+ */
+export function readImageAssetManifest(workspaceDir) {
+  const file = manifestPath(workspaceDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return EMPTY_MANIFEST();
+    throw imageAssetError("image_asset_missing", `${file} could not be read: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw imageAssetError("image_intent_invalid", `${file} is not valid JSON: ${err.message}`);
+  }
+  const result = parseImageAssetManifest(parsed);
+  if (!result.value) {
+    const first = result.issues[0];
+    throw imageAssetError(first?.code ?? "image_intent_invalid", `${file}: ${first?.message ?? "invalid manifest"}`);
+  }
+  return result.value;
+}
+
+/** Absolute path of an entry's stored bytes, from its portable workspace path. */
+export function assetFilePath(workspaceDir, asset) {
+  return path.join(workspaceDir, ...asset.workspacePath.split("/"));
+}
+
+export function findAssetById(manifest, assetId) {
+  return manifest.assets.find((a) => a.assetId === assetId) ?? null;
+}
+
+/**
+ * An entry plus its verified bytes.
+ *
+ * `image_asset_missing` when the file is gone, `image_asset_changed` when what
+ * is on disk no longer hashes to the registered digest — the two failures the
+ * contract's error table distinguishes, because their repairs differ.
+ */
+export function resolveImageAsset(workspaceDir, assetId, { verify = true } = {}) {
+  const manifest = readImageAssetManifest(workspaceDir);
+  const asset = findAssetById(manifest, assetId);
+  if (!asset) {
+    throw imageAssetError("image_asset_missing", `no image asset ${assetId} in this deck`, { assetId });
+  }
+  const file = assetFilePath(workspaceDir, asset);
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch {
+    throw imageAssetError("image_asset_missing", `${asset.displayName}: ${asset.workspacePath} is missing`, {
+      assetId,
+    });
+  }
+  if (verify && sha256(bytes) !== asset.sha256) {
+    throw imageAssetError(
+      "image_asset_changed",
+      `${asset.displayName}: ${asset.workspacePath} no longer matches the digest it was registered with`,
+      { assetId },
+    );
+  }
+  return { asset, file, bytes };
+}
+
+function publishManifest(workspaceDir, manifest) {
+  const file = manifestPath(workspaceDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Write-then-rename, the same swap `revision.mjs` uses for the accepted base:
+  // a reader sees the old registry or the new one, never half of either.
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// Copy bytes to their workspace path and prove the copy landed. A verification
+// failure removes the half-written file: nothing has been committed yet, so the
+// deck is left exactly as it was.
+function writeAssetBytes(workspaceDir, asset, bytes) {
+  const file = assetFilePath(workspaceDir, asset);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  const fd = fs.openSync(tmp, "w");
+  try {
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  if (sha256(fs.readFileSync(file)) !== asset.sha256) {
+    fs.rmSync(file, { force: true });
+    throw imageAssetError(
+      "image_asset_changed",
+      `${asset.displayName}: the copy written to ${asset.workspacePath} did not match the source digest; nothing was recorded`,
+      { assetId: asset.assetId },
+    );
+  }
+  return file;
+}
+
+function mintAssetId(manifest) {
+  for (;;) {
+    const id = `asset_${randomBytes(8).toString("hex")}`;
+    if (!findAssetById(manifest, id)) return id;
+  }
+}
+
+/**
+ * Adopt registry entries whose identity was minted ELSEWHERE — the only way an
+ * assetId this deck did not allocate may enter its manifest.
+ *
+ * It exists for one caller: re-adopting a .pptx that slidemind rendered, whose
+ * slides carry their own image provenance (src/lib/image-intent-tags.mjs). The
+ * uses baked into that file name their assets by ID, so re-minting one would
+ * leave every obligation dangling — the identity has to survive the round trip
+ * or nothing does.
+ *
+ * Every entry is proved before it is committed: the record parses against the
+ * contract, and the bytes already on disk at its `workspacePath` hash to the
+ * digest it claims. An assetId this deck already has is only accepted when it
+ * names the same bytes; a different digest behind a known ID is refused, never
+ * overwritten (entries are immutable). Refusals come back as `rejected`, not as
+ * a throw: a partial restore reports what it could not take.
+ *
+ * @returns {{added: string[], reused: string[], rejected: Array<{assetId, reason}>}}
+ */
+export function registerImageAssets(workspaceDir, entries) {
+  const manifest = readImageAssetManifest(workspaceDir);
+  const byId = new Map(manifest.assets.map((a) => [a.assetId, a]));
+  const added = [];
+  const reused = [];
+  const rejected = [];
+  const fresh = [];
+  for (const raw of entries ?? []) {
+    const parsed = parseImageAsset(raw);
+    if (!parsed.value) {
+      rejected.push({
+        assetId: raw?.assetId ?? null,
+        reason: parsed.issues[0]?.message ?? "invalid registry entry",
+      });
+      continue;
+    }
+    const entry = parsed.value;
+    const existing = byId.get(entry.assetId);
+    if (existing) {
+      if (existing.sha256 === entry.sha256) reused.push(entry.assetId);
+      else {
+        rejected.push({
+          assetId: entry.assetId,
+          reason: `this deck already registers ${entry.assetId} for different bytes; a registry entry is never rewritten`,
+        });
+      }
+      continue;
+    }
+    let bytes;
+    try {
+      bytes = fs.readFileSync(assetFilePath(workspaceDir, entry));
+    } catch {
+      rejected.push({ assetId: entry.assetId, reason: `${entry.workspacePath} is not in the deck` });
+      continue;
+    }
+    if (sha256(bytes) !== entry.sha256) {
+      rejected.push({
+        assetId: entry.assetId,
+        reason: `${entry.workspacePath} does not hash to the digest the record claims`,
+      });
+      continue;
+    }
+    byId.set(entry.assetId, entry);
+    fresh.push(entry);
+    added.push(entry.assetId);
+  }
+  if (fresh.length) {
+    publishManifest(workspaceDir, {
+      version: IMAGE_INTENT_VERSION,
+      assets: [...manifest.assets, ...fresh],
+    });
+  }
+  return { added, reused, rejected };
+}
+
+// ---------------------------------------------------------------------------
+// import
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a file's bytes with this deck.
+ *
+ * Filesystem paths only — acquiring bytes (an engine download, the harness's
+ * attachment access, the user's own browser) happens before this call, and this
+ * command never fetches. It infers no intent either: the returned entry obliges
+ * nothing until a plan gives it a use.
+ *
+ * Deduplicates by digest WITHIN the deck: re-importing the same bytes returns
+ * the entry they already have (`reused: true`), which is what makes a repeated
+ * flag or a re-run idempotent.
+ *
+ * @param {string} workspaceDir the deck workspace
+ * @param {string} sourcePath a readable file
+ * @param {{displayName?: string, provenance?: {kind: string, sourceId?: string}, fault?: Function}} [opts]
+ *   `fault` is the interruption seam: it runs after the bytes are on disk and
+ *   before the manifest is swapped, so a test can prove that order holds.
+ *   (Same idiom as `stageWorkspace().activate({fault})`.)
+ * @returns {Promise<{asset: object, reused: boolean, plan: object}>}
+ */
+export async function importImageAsset(
+  workspaceDir,
+  sourcePath,
+  { displayName = null, provenance = { kind: "local" }, fault = null } = {},
+) {
+  const file = path.resolve(sourcePath);
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch (err) {
+    if (err?.code === "EISDIR") {
+      throw imageAssetError("image_asset_unsupported", `${file} is a directory, not an image`);
+    }
+    throw imageAssetError("image_asset_missing", `no file to import at ${file}`);
+  }
+
+  const name = String(displayName ?? path.basename(file)).trim().slice(0, 200) || path.basename(file);
+  // Inspection first: an undecodable source is refused before anything is
+  // copied, let alone committed.
+  const probe = inspectImageBytes(bytes, { displayName: name });
+  const digest = sha256(bytes);
+
+  // The deck's own lock, so two imports cannot both read the registry, append
+  // to it and write it back. Re-enters under an existing SLIDEMIND_OWNER token.
+  const { acquireOwner } = await import("./revision.mjs");
+  const held = acquireOwner(workspaceDir, { command: "assets import" });
+  try {
+    const manifest = readImageAssetManifest(workspaceDir);
+
+    const existing = manifest.assets.find((a) => a.sha256 === digest);
+    if (existing) {
+      // Immutable: the first identity stands, display name and all. Only the
+      // stored copy is restored, in case it was deleted since.
+      if (!fs.existsSync(assetFilePath(workspaceDir, existing))) {
+        writeAssetBytes(workspaceDir, existing, bytes);
+      }
+      return { asset: existing, reused: true, plan: imageRenderPlan(existing, bytes) };
+    }
+
+    const assetId = mintAssetId(manifest);
+    const entry = {
+      assetId,
+      sha256: digest,
+      mimeType: probe.mimeType,
+      width: probe.width,
+      height: probe.height,
+      byteLength: bytes.length,
+      displayName: name,
+      workspacePath: `${LOCAL_ASSET_DIR}/${assetId}.${probe.ext}`,
+      provenance: {
+        kind: provenance?.kind ?? "local",
+        ...(provenance?.sourceId ? { sourceId: String(provenance.sourceId) } : {}),
+      },
+    };
+    // Our own record goes through the contract's parser: one validator, so the
+    // registry can never hold something the plan side would reject.
+    const parsed = parseImageAsset(entry);
+    if (!parsed.value) {
+      const first = parsed.issues[0];
+      throw imageAssetError(first?.code ?? "image_intent_invalid", `${name}: ${first?.message ?? "invalid entry"}`);
+    }
+
+    writeAssetBytes(workspaceDir, parsed.value, bytes);
+    if (fault) fault(parsed.value);
+    publishManifest(workspaceDir, {
+      version: IMAGE_INTENT_VERSION,
+      assets: [...manifest.assets, parsed.value],
+    });
+    return { asset: parsed.value, reused: false, plan: imageRenderPlan(parsed.value, bytes) };
+  } finally {
+    held.release();
+  }
+}