slidemind 0.3.12 → 0.3.14

package/src/bridge/client/pane-ops.mjs

@@ -0,0 +1,335 @@
+// Ops relayed through one PowerPoint window (insert / export / replace / ping)
+// and the design-source + window pickers.
+
+import { isMultiEnv } from "../config.mjs";
+import { isRenderReadyPresentation, isPaneReadyPresentation, tieBreakMatches, resolveBackendForPres } from "./presentations.mjs";
+import { READY_HINT_PICK, bridgeFetch } from "./transport.mjs";
+
+// Ask the pane whether its host document is actually still alive (the
+// `ping-document` op — one PowerPoint.run in the webview). This exists for
+// `ready`'s zombie check: a webview whose document was closed keeps its socket
+// (and thus its registry lease) alive, so only a host round-trip tells the
+// truth. Deliberately NOT engineOpWithPaneWait — a probe must fail fast, never
+// park in the 120s pane wait. Callers decide what a failure means; this just
+// returns the ack or throws the transport error.
+export async function pingPresentation({ presId, backendURL, timeoutMs = 12000 }) {
+  if (!presId) throw new Error("pingPresentation: presId is required");
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/ping`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+      timeoutMs,
+    },
+    backendURL,
+  );
+  return res.json(); // { ok, presId?, fileName? } | { ok: false, code, error }
+}
+
+export function ensurePaneAckOk(data, operation) {
+  if (!data || data.ok !== false) return data ?? {};
+  const detail = data.error || `${operation} failed`;
+  const err = new Error(detail);
+  err.code = data.code || `${operation}_failed`;
+  err.body = data;
+  throw err;
+}
+
+export async function insertSlides({
+  presId,
+  base64,
+  insertAt = null,
+  sourceSlideIds = null,
+  operationId = null,
+  sourceTagsBySlide = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("insertSlides: presId is required");
+  if (!base64) throw new Error("insertSlides: base64 is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { base64, insertAt, sourceSlideIds, operationId };
+  // Deck-embedded source payloads for the pane's post-insert tag write,
+  // aligned with the inserted slides in document order.
+  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
+    body.sourceTagsBySlide = sourceTagsBySlide;
+  }
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/insert`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
+    },
+    be,
+  );
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "insert");
+}
+
+// Read-only sibling of the mutation ops: export the LIVE slides carrying the
+// given GUIDs, so a `--replace` push can see what the user changed on screen
+// BEFORE it wipes it (plan Phase C1). `guids` omitted ⇒ the whole deck.
+//
+// The ack's `tags` come from the Office.js tag API, NOT from the exported
+// bytes: exportAsBase64 strips custom tags (office-js #6104), so a slide's
+// drift BASELINE is recoverable only from `tags` — never from `base64`, which
+// carries the CURRENT state and nothing else. `deck.unmatched` lists the live
+// slides that are not in the requested set (what a whole-deck replace would
+// delete); `truncated` names GUIDs that matched but did not fit the relay
+// frame, to be re-requested.
+export async function exportSlides({
+  presId,
+  guids = null,
+  presentationId = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("exportSlides: presId is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = {};
+  if (Array.isArray(guids) && guids.length > 0) body.guids = guids;
+  if (presentationId) body.presentationId = presentationId;
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/export-slides`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      // Same pane round trip as the mutations (a suspended pane has to wake),
+      // and the payload is slide bytes.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
+    },
+    be,
+  );
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "export-slides");
+}
+
+export async function replaceSlides({
+  presId,
+  base64,
+  operationId = null,
+  sourceTagsBySlide = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("replaceSlides: presId is required");
+  if (!base64) throw new Error("replaceSlides: base64 is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const replaceBody = { base64, operationId };
+  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
+    replaceBody.sourceTagsBySlide = sourceTagsBySlide;
+  }
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/replace`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(replaceBody),
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
+    },
+    be,
+  );
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "replace");
+}
+
+// Non-throwing, PURE (no network) sibling of pickPresentationEntry that answers
+// the one question `slidemind ready` needs: which corporate design should this
+// session bind to? Where pickPresentationEntry PROMPTS the user by throwing,
+// resolveDesignSource returns a STRUCTURED verdict the CLI turns into a bound
+// bundle, a single blocker, or a "which design?" question — no exceptions as
+// control flow.
+//
+// The bar is RENDER-ready, never pane-ready: the add-in is the source of truth
+// for the design, and a backgrounded (pane-suspended) window still serves its
+// bundle and still renders — so it is a valid design source (the caller reports
+// `paneSuspended` but stays exit 0). Pane readiness only matters later, when a
+// push/search actually needs the live pane.
+//
+// The ONE user-facing ambiguity is ≥2 render-ready windows on DISTINCT designs
+// (distinct `brandId`). We deliberately do NOT let the deck's own bundle ref
+// (`deckPresFP`) break that tie — the open add-in wins; a deck never pins a
+// design preference. The deck ref only:
+//   (a) tie-breaks ONE window mirrored across paired backends (same presId on
+//       dev+prod) via tieBreakMatches — the SAME rule pickPresentationEntry
+//       uses, and its only sanctioned use here; and
+//   (b) surfaces the matching candidate as `suggested`, so the agent can say
+//       "this deck was last built against X" WITHOUT the CLI silently deciding.
+//
+// Returns exactly one of:
+//   { status: "none" }                    — nothing render-ready is open.
+//   { status: "unknown_presid", presId }  — an explicit --to names no
+//                                            render-ready window.
+//   { status: "resolved", entry }         — the RAW registry entry (backendURL
+//                                            intact; the caller strips it before
+//                                            any user-facing output).
+//   { status: "ambiguous", candidates, suggested }
+//                                          — candidates deduped to ONE entry per
+//                                            distinct design; suggested is the
+//                                            presId of the deck-ref match, else
+//                                            null.
+export function resolveDesignSource(
+  registry,
+  { explicitPresId = null, deckPresFP = null } = {},
+) {
+  const all = (Array.isArray(registry) ? registry : []).filter(
+    isRenderReadyPresentation,
+  );
+  if (all.length === 0) return { status: "none" };
+
+  // Group by DESIGN. A render-ready pane always carries a brandId, but be
+  // defensive: a missing brandId is treated as its OWN pseudo-design keyed by
+  // presId so two CD-less windows never collapse into one false match.
+  const designKey = (p) =>
+    p.brandId != null && p.brandId !== ""
+      ? `brand:${p.brandId}`
+      : `pres:${p.presId}`;
+
+  // Collapse a set of entries to one representative per distinct design,
+  // preferring a live (pane-ready) pane over a suspended mirror, then compute
+  // the deck-ref `suggested` presId over those representatives.
+  const dedupeCandidates = (entries) => {
+    const byKey = new Map();
+    for (const p of entries) {
+      const k = designKey(p);
+      const cur = byKey.get(k);
+      if (!cur || (!isPaneReadyPresentation(cur) && isPaneReadyPresentation(p))) {
+        byKey.set(k, p);
+      }
+    }
+    const candidates = [...byKey.values()];
+    const suggested =
+      (deckPresFP && candidates.find((c) => c.brandId === deckPresFP)?.presId) ||
+      null;
+    return { candidates, suggested };
+  };
+
+  if (explicitPresId) {
+    const matches = all.filter((p) => p.presId === explicitPresId);
+    if (matches.length === 0) {
+      return { status: "unknown_presid", presId: explicitPresId };
+    }
+    if (matches.length === 1) return { status: "resolved", entry: matches[0] };
+    // >1 render-ready match == ONE window mirrored across paired backends.
+    // Tie-break exactly as pickPresentationEntry; only a genuine tie is asked.
+    const winner = tieBreakMatches(matches, deckPresFP);
+    if (winner) return { status: "resolved", entry: winner };
+    return { status: "ambiguous", ...dedupeCandidates(matches) };
+  }
+
+  // A live pane outranks a suspended one for the DESIGN decision: a
+  // backgrounded — or closed and not yet purged — window must not turn the one
+  // design the user actually has in front of them into a question. Only when
+  // nothing is live do the suspended windows decide.
+  const live = all.filter(isPaneReadyPresentation);
+  const pool = live.length > 0 ? live : all;
+  const distinctDesigns = new Set(pool.map(designKey));
+  if (distinctDesigns.size === 1) {
+    // One design open (possibly one window mirrored across backends, or several
+    // windows on the SAME CD). Pick via the mirror tie-break, else a live pane,
+    // else the first — the design is unambiguous either way.
+    const entry =
+      tieBreakMatches(pool, deckPresFP) ??
+      pool.find(isPaneReadyPresentation) ??
+      pool[0];
+    return { status: "resolved", entry };
+  }
+  // ≥2 distinct designs open — the only case that asks the user (the deck ref
+  // does NOT auto-pick; it only annotates `suggested`).
+  return { status: "ambiguous", ...dedupeCandidates(pool) };
+}
+
+// Pick a target presentation given the (possibly multi-backend) registry and an
+// optional explicit presId. Returns the matched registry ENTRY (which carries
+// `backendURL`/`env` after a fan-out list), or throws with a helpful message if
+// the choice is ambiguous. Callers that already hold the entry can pass its
+// `backendURL` straight to the targeted ops, skipping a second fan-out.
+// `preferBrandId` (the deck's bundle-ref presFP) tie-breaks a presId open on
+// several backends — see tieBreakMatches.
+export function pickPresentationEntry(
+  registry,
+  explicitPresId,
+  { preferBrandId = null } = {},
+) {
+  if (explicitPresId) {
+    const matches = registry.filter((p) => p.presId === explicitPresId);
+    if (matches.length === 0) {
+      const ids = registry.map((p) => p.presId).join(", ") || "(none registered)";
+      throw new Error(
+        `No open PowerPoint window registered with presId='${explicitPresId}'. Live: ${ids}`,
+      );
+    }
+    if (matches.length > 1) {
+      const winner = tieBreakMatches(matches, preferBrandId);
+      if (winner) return winner;
+      const envs = matches.map((m) => m.env || "?").join(", ");
+      throw new Error(
+        `Presentation '${explicitPresId}' is open on multiple environments: ${envs}, ` +
+          "and no single connected one has the deck's corporate design active. " +
+          "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
+      );
+    }
+    return matches[0];
+  }
+  if (registry.length === 0) {
+    throw new Error(
+      "No PowerPoint windows registered with the slidemind add-in. " +
+        "Open a presentation, ensure the add-in is loaded, and try again.",
+    );
+  }
+  if (registry.length === 1) return registry[0];
+  // ONE window mirrored across several paired backends is not a user choice —
+  // apply the same tie-break as the explicit-presId path. Several DIFFERENT
+  // windows stay a user decision.
+  if (new Set(registry.map((p) => p.presId)).size === 1) {
+    const winner = tieBreakMatches(registry, preferBrandId);
+    if (winner) return winner;
+  }
+  const list = registry
+    .map(
+      (p) =>
+        `  ${p.presId}\t${p.env && isMultiEnv() ? `[${p.env}]\t` : ""}${p.title || p.fileName || "(untitled)"}` +
+        (p.connected === false || p.suspendedAt ? "\t(suspended — PowerPoint in background)" : ""),
+    )
+    .join("\n");
+  throw new Error(
+    `Multiple PowerPoint windows are open. Pick one with --to <presId>:\n${list}\n${READY_HINT_PICK}`,
+  );
+}
+
+// Window-AGNOSTIC picker for engine ops (discovery / search / result view). The
+// engine catalog is per-user and NOT bound to any window, so any connected pane
+// can run the search — there is nothing for the caller to disambiguate. When no
+// explicit presId is given we attach to one automatically (preferring a live,
+// non-suspended pane so we don't have to wake a backgrounded one) instead of
+// throwing the "multiple windows, pick --to" error pickPresentationEntry raises.
+// An explicit presId still resolves exactly as pickPresentationEntry.
+//
+// CAVEAT: the searchId the add-in returns is bound to the pane that ran the
+// search (each window keeps its own search-context store). So follow-up
+// view/extract/insert must target the SAME entry this returns — surface its
+// presId to the caller so it can thread it back.
+export function pickAnyPresentationEntry(registry, explicitPresId, opts = {}) {
+  if (explicitPresId) return pickPresentationEntry(registry, explicitPresId, opts);
+  if (!Array.isArray(registry) || registry.length === 0) {
+    throw new Error(
+      "No PowerPoint windows registered with the slidemind add-in. " +
+        "Open a presentation, ensure the add-in is loaded, and try again.",
+    );
+  }
+  return (
+    registry.find(isPaneReadyPresentation) ??
+    registry.find((p) => p.connected !== false && !p.suspendedAt) ??
+    registry[0]
+  );
+}
+
+// Back-compat shim: returns just the presId string. Prefer
+// pickPresentationEntry when you need the origin backend.
+export function pickPresentation(registry, explicitPresId) {
+  return pickPresentationEntry(registry, explicitPresId).presId;
+}