slidemind 0.0.27

package/src/bridge/bundle.mjs

@@ -0,0 +1,373 @@
+// Materialize the add-in's design bundle into a local cache directory the
+// skill and the HTML builder can read.
+//
+// The bundle is the per-corporate-design source of truth (tokens, css,
+// layouts, design.md, brand assets, engines). The add-in serves it over the
+// bridge as a wire response with short-lived (~15 min) signed URLs for binary
+// assets; we download those immediately and lay everything out on disk keyed by
+// the presentation fingerprint (`presFP`) so multiple decks sharing a CD share
+// one materialized bundle.
+//
+//   ${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/
+//   ├── corporate-design.css      (from wire.css)
+//   ├── design.md                 (from wire.designRules)
+//   ├── layouts/layouts.css       (from wire.layoutsCss, when present)
+//   ├── layouts/*.jsx             (one per wire.layouts[])
+//   ├── assets/*                  (downloaded from wire.assets[].url)
+//   ├── samples/*                 (downloaded from wire.samples[].url — brand reference slides)
+//   ├── fonts/*                   (downloaded from wire.fonts[].url, optional)
+//   ├── master/empty-layout.pptx  (downloaded from wire.master.url, optional)
+//   ├── engines.json              (wire.engines[])
+//   ├── workflow/*.md             (wire.workflowRefs — add-in-owned authoring craft)
+//   └── bundle.json               ({ presFP, version, etag, tokenRoleMap, … })
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import http from "node:http";
+import https from "node:https";
+
+import { getDesignBundle } from "./client.mjs";
+
+// Highest bundle wire-contract version this CLI understands. The add-in stamps
+// `schemaVersion` on every bundle; a higher value means the CLI is too old.
+const CLI_MAX_BUNDLE_SCHEMA = 1;
+
+export function bundleCacheRoot() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "slidemind", "bundles");
+}
+
+function sanitizeKey(value) {
+  return String(value).replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+export function bundleDirForPresFP(presFP) {
+  if (!presFP) throw new Error("bundleDirForPresFP: presFP is required");
+  return path.join(bundleCacheRoot(), sanitizeKey(presFP));
+}
+
+// Plain HTTPS/HTTP GET → Buffer. Follows a few redirects and tolerates the
+// add-in's self-signed dev certificate on loopback hosts (the same posture the
+// bridge client uses). Azure blob SAS URLs are public HTTPS and need no special
+// handling beyond a normal GET.
+function getBuffer(url, { redirects = 4 } = {}) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      u = new URL(url);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    const isHttps = u.protocol === "https:";
+    const transport = isHttps ? https : http;
+    const isLoopback =
+      u.hostname === "127.0.0.1" ||
+      u.hostname === "localhost" ||
+      u.hostname === "::1";
+    const req = transport.request(
+      u,
+      {
+        method: "GET",
+        rejectUnauthorized: isHttps && isLoopback ? false : undefined,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if (status >= 300 && status < 400 && res.headers.location && redirects > 0) {
+          res.resume();
+          const next = new URL(res.headers.location, u).href;
+          getBuffer(next, { redirects: redirects - 1 }).then(resolve, reject);
+          return;
+        }
+        if (status < 200 || status >= 300) {
+          res.resume();
+          reject(new Error(`download ${status} for ${u.pathname}`));
+          return;
+        }
+        const chunks = [];
+        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+      },
+    );
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+async function downloadInto(targetPath, url) {
+  const buf = await getBuffer(url);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, buf);
+}
+
+// File extension for a sample image, derived from its wire `contentType`. The
+// sample's stable `id` is the basename; samples carry no `filename` on the wire.
+function sampleExt(contentType) {
+  switch (contentType) {
+    case "image/jpeg":
+      return ".jpg";
+    case "image/webp":
+      return ".webp";
+    case "image/svg+xml":
+      return ".svg";
+    case "image/png":
+    default:
+      return ".png";
+  }
+}
+
+// Fetch + write the bundle for `presId`. Returns { dir, presFP, etag, version,
+// cached }. Skips the re-download when the cached bundle's etag already matches
+// (unless `force`).
+export async function materializeBundle(presId, { force = false } = {}) {
+  const wire = await getDesignBundle(presId);
+  if (!wire || !wire.presFP) {
+    throw new Error("design-bundle response is missing presFP");
+  }
+  // Forward-compat guard: a bundle stamped with a newer wire-contract version
+  // than this CLI knows would be mis-parsed; fail with an actionable message.
+  if (
+    typeof wire.schemaVersion === "number" &&
+    wire.schemaVersion > CLI_MAX_BUNDLE_SCHEMA
+  ) {
+    throw new Error(
+      `This corporate design needs a newer slidemind (bundle schemaVersion ` +
+        `${wire.schemaVersion}; this CLI supports ${CLI_MAX_BUNDLE_SCHEMA}).\n` +
+        `  Run 'slidemind update' (or re-run the install one-liner), then retry.`,
+    );
+  }
+  const presFP = wire.presFP;
+  const dir = bundleDirForPresFP(presFP);
+  const metaPath = path.join(dir, "bundle.json");
+
+  if (!force && fs.existsSync(metaPath)) {
+    try {
+      const prev = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+      // Prefer etag equality; fall back to version equality for CDs whose
+      // effective etag is empty (no stored blob etag), so the cache can still
+      // short-circuit instead of re-downloading on every call.
+      const sameEtag = prev.etag && wire.etag && prev.etag === wire.etag;
+      const sameVersion =
+        !wire.etag &&
+        prev.version != null &&
+        wire.version != null &&
+        prev.version === wire.version;
+      if (sameEtag || sameVersion) {
+        return {
+          dir,
+          presFP,
+          etag: wire.etag ?? null,
+          version: wire.version ?? null,
+          cached: true,
+          warnings: [],
+        };
+      }
+    } catch {
+      /* unreadable metadata — fall through and rewrite the bundle */
+    }
+  }
+
+  // Rewrite from scratch so a stale layout/asset can never linger.
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(path.join(dir, "layouts"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "assets"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "samples"), { recursive: true });
+
+  fs.writeFileSync(
+    path.join(dir, "corporate-design.css"),
+    wire.css ?? "",
+    "utf8",
+  );
+  fs.writeFileSync(path.join(dir, "design.md"), wire.designRules ?? "", "utf8");
+  if (typeof wire.layoutsCss === "string" && wire.layoutsCss.length > 0) {
+    fs.writeFileSync(
+      path.join(dir, "layouts", "layouts.css"),
+      wire.layoutsCss,
+      "utf8",
+    );
+  }
+
+  for (const layout of wire.layouts ?? []) {
+    const name = layout.name || layout.componentName;
+    if (!name || typeof layout.source !== "string") continue;
+    const file = name.endsWith(".jsx") ? name : `${name}.jsx`;
+    fs.writeFileSync(
+      path.join(dir, "layouts", path.basename(file)),
+      layout.source,
+      "utf8",
+    );
+  }
+
+  fs.writeFileSync(
+    path.join(dir, "engines.json"),
+    JSON.stringify(wire.engines ?? [], null, 2),
+    "utf8",
+  );
+
+  // Brand-agnostic authoring workflow craft (create/edit/composition/layouts/
+  // authoring/build-export) — owned by the add-in, served on the bundle so the
+  // local agent reads the SAME workflow guidance the in-app design persona does.
+  if (wire.workflowRefs && typeof wire.workflowRefs === "object") {
+    fs.mkdirSync(path.join(dir, "workflow"), { recursive: true });
+    for (const [name, text] of Object.entries(wire.workflowRefs)) {
+      if (typeof text !== "string") continue;
+      fs.writeFileSync(
+        path.join(dir, "workflow", path.basename(name)),
+        text,
+        "utf8",
+      );
+    }
+  }
+
+  // Download signed URLs IMMEDIATELY and in PARALLEL — they expire ~15 min
+  // after the wire response is minted, so serializing N independent GETs only
+  // raises the odds a late one races an expiring URL. Failures are non-fatal
+  // (a missing brand asset degrades local HTML preview but never the server
+  // render) but are NOT silent: each is collected into `warnings` so the caller
+  // can tell the user the materialized bundle is incomplete.
+  const downloads = [];
+  for (const asset of wire.assets ?? []) {
+    if (!asset?.url || !asset?.filename) continue;
+    downloads.push({
+      label: `asset ${asset.filename}`,
+      target: path.join(dir, "assets", path.basename(asset.filename)),
+      url: asset.url,
+    });
+  }
+  for (const font of wire.fonts ?? []) {
+    if (!font?.url) continue;
+    const fname = font.filename || `${font.role || font.family || "font"}.bin`;
+    downloads.push({
+      label: `font ${fname}`,
+      target: path.join(dir, "fonts", path.basename(fname)),
+      url: font.url,
+    });
+  }
+  if (wire.master?.url) {
+    downloads.push({
+      label: "master empty-layout.pptx",
+      target: path.join(dir, "master", "empty-layout.pptx"),
+      url: wire.master.url,
+    });
+  }
+  // Per-CD sample slides (the brand's own reference slides) — the offline agent
+  // studies a random few before composing. Keyed by the sample's stable `id`;
+  // extension derived from `contentType`. Same non-fatal degradation as assets.
+  for (const sample of wire.samples ?? []) {
+    if (!sample?.url || !sample?.id) continue;
+    downloads.push({
+      label: `sample ${sample.id}`,
+      target: path.join(
+        dir,
+        "samples",
+        `${path.basename(sample.id)}${sampleExt(sample.contentType)}`,
+      ),
+      url: sample.url,
+    });
+  }
+
+  const warnings = [];
+  const settled = await Promise.allSettled(
+    downloads.map((d) => downloadInto(d.target, d.url)),
+  );
+  settled.forEach((r, i) => {
+    if (r.status === "rejected") {
+      const reason =
+        r.reason instanceof Error ? r.reason.message : String(r.reason);
+      warnings.push(
+        `failed to download ${downloads[i].label}: ${reason} (signed URL may have expired — re-run with --force)`,
+      );
+    }
+  });
+
+  const meta = {
+    presFP,
+    version: wire.version ?? null,
+    etag: wire.etag ?? null,
+    scope: wire.scope ?? null,
+    tokenRoleMap: wire.tokenRoleMap ?? null,
+    engines: wire.engines ?? [],
+    fetchedAt: new Date().toISOString(),
+    incompleteAssets: warnings.length > 0,
+  };
+  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), "utf8");
+
+  return {
+    dir,
+    presFP,
+    etag: wire.etag ?? null,
+    version: wire.version ?? null,
+    cached: false,
+    warnings,
+  };
+}
+
+// Per-deck record of which CD bundle (presFP + etag) the deck was authored
+// against — lets `render-pptx` pass the etag for skew detection, and lets the
+// local HTML/editor resolve the right materialized bundle.
+export function deckBundleRefPath(deckDir) {
+  return path.join(deckDir, ".bundle-ref.json");
+}
+
+export function writeDeckBundleRef(deckDir, { presFP, etag }) {
+  fs.mkdirSync(deckDir, { recursive: true });
+  fs.writeFileSync(
+    deckBundleRefPath(deckDir),
+    JSON.stringify(
+      { presFP, etag: etag ?? null, updatedAt: new Date().toISOString() },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
+export function readDeckBundleRef(deckDir) {
+  try {
+    return JSON.parse(fs.readFileSync(deckBundleRefPath(deckDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the materialized bundle directory a deck should read its design files
+// from (via the deck's .bundle-ref.json). Returns null when no bundle has been
+// materialized for the deck's CD yet.
+export function resolveBundleDirForDeck(deckDir) {
+  const ref = readDeckBundleRef(deckDir);
+  if (!ref?.presFP) return null;
+  const dir = bundleDirForPresFP(ref.presFP);
+  return fs.existsSync(dir) ? dir : null;
+}
+
+// Read the engines[] descriptor list from a materialized bundle directory.
+export function readEnginesFromDir(dir) {
+  if (!dir) return [];
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(dir, "engines.json"), "utf8"),
+    );
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+export function loadEnginesForDeck(deckDir) {
+  return readEnginesFromDir(resolveBundleDirForDeck(deckDir));
+}
+
+// Pick the default engine to search: the first image/icon engine, else the
+// first engine. Single source of truth for the heuristic shared by the CLI
+// dispatcher (`slidemind search`) and the MCP `slidemind_search_engine` tool.
+export function pickImageEngine(engines) {
+  const list = Array.isArray(engines) ? engines : [];
+  return (
+    list.find((e) =>
+      /image|icon/i.test(`${e.kind ?? ""} ${e.label ?? ""} ${e.description ?? ""}`),
+    ) ||
+    list[0] ||
+    null
+  );
+}