slidemind 0.3.12 → 0.3.14

package/src/bridge/client/presentations.mjs

@@ -0,0 +1,587 @@
+// The open-window registry: fan-out listing, readiness ladders, pane waits and
+// the presId → backend routing every pane-bound op rides on.
+
+import { deriveEnvLabel } from "../config.mjs";
+import { cliVersion, compareCliVersions, listTimeoutMs, engineTimeoutMs, readinessTimeoutMs, READY_HINT, withTransientRetry, sessionsInScope, bridgeFetch, envInt, sleep } from "./transport.mjs";
+
+// List one backend's open presentations, tagging each entry with its origin
+// (backendURL + a short env label) so the merged registry can be routed and
+// displayed per environment. Transient blips retry per-backend.
+export async function listPresentationsForBackend(backendURL) {
+  return withTransientRetry(async () => {
+    const res = await bridgeFetch(
+      "/api/cli/presentations",
+      { timeoutMs: listTimeoutMs() },
+      backendURL,
+    );
+    const data = await res.json();
+    const arr = Array.isArray(data?.presentations) ? data.presentations : [];
+    const env = deriveEnvLabel(backendURL);
+    return arr.map((p) => ({ ...p, backendURL, env }));
+  });
+}
+
+export async function readinessForBackend(backendURL) {
+  const env = deriveEnvLabel(backendURL);
+  try {
+    // Retry only a 503: the add-in answers that (code `backend_unavailable`)
+    // while its session store cannot respond, and a 404 here means an older
+    // add-in without the readiness route, which the fallback below handles
+    // without waiting out the retry delays.
+    const res = await withTransientRetry(
+      () =>
+        bridgeFetch(
+          "/api/cli/readiness",
+          { timeoutMs: listTimeoutMs() },
+          backendURL,
+        ),
+      (err) => err?.status === 503 && err?.code !== "pane_suspended",
+    );
+    const data = (await res.json()) ?? {};
+    const presentations = Array.isArray(data.presentations)
+      ? data.presentations.map((p) => ({ ...p, backendURL, env }))
+      : [];
+    // Version-floor check for diagnostics (doctor / connection_status): newer
+    // add-ins advertise minCliVersion in the readiness capabilities, so the
+    // skew is visible BEFORE a render trips over it.
+    const minCliVersion =
+      typeof data.capabilities?.minCliVersion === "string"
+        ? data.capabilities.minCliVersion
+        : null;
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: data.readinessV1 === true,
+      capabilities: data.capabilities ?? null,
+      minCliVersion,
+      cliUpdateRequired: Boolean(
+        minCliVersion && compareCliVersions(cliVersion(), minCliVersion) < 0,
+      ),
+      presentations,
+      summary: data.summary ?? null,
+    };
+  } catch (err) {
+    if (err?.status !== 404) throw err;
+    // Older add-ins do not serve /readiness. Fall back to the legacy
+    // presentations route and mark the result as a compatibility response.
+    const presentations = await listPresentationsForBackend(backendURL);
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: false,
+      capabilities: null,
+      presentations,
+      summary: null,
+    };
+  }
+}
+
+export async function connectionStatus() {
+  const sessions = sessionsInScope();
+  const settled = await Promise.allSettled(
+    sessions.map((s) => readinessForBackend(s.backendURL)),
+  );
+  const backends = settled.map((r, i) => {
+    const backendURL = sessions[i].backendURL;
+    const env = deriveEnvLabel(backendURL);
+    if (r.status === "fulfilled") return r.value;
+    return {
+      env,
+      backendURL,
+      ok: false,
+      error: r.reason?.message ? r.reason.message : String(r.reason),
+      // Machine code of the failure (`backend_unavailable`, `session_invalid`,
+      // …) so the readiness ladder can tell "retry shortly" from "re-pair".
+      code: typeof r.reason?.code === "string" ? r.reason.code : null,
+      // The HTTP status too: a proxy's 503 carries no machine code (or only a
+      // prose `error`), and the ladder must still read it as "wait".
+      status: typeof r.reason?.status === "number" ? r.reason.status : null,
+      presentations: [],
+    };
+  });
+  return {
+    paired: sessions.length > 0,
+    backendCount: sessions.length,
+    backends,
+    presentations: backends.flatMap((b) => b.presentations ?? []),
+  };
+}
+
+// Fan out across every backend in scope, concurrently. Never rejects: each
+// backend's outcome is partitioned into merged presentations vs. a failure
+// record, so one unreachable environment can't hide the others.
+export async function fanOutPresentations() {
+  const sessions = sessionsInScope();
+  const settled = await Promise.allSettled(
+    sessions.map((s) => listPresentationsForBackend(s.backendURL)),
+  );
+  const presentations = [];
+  const failures = [];
+  let fulfilledCount = 0;
+  settled.forEach((r, i) => {
+    const backendURL = sessions[i].backendURL;
+    if (r.status === "fulfilled") {
+      fulfilledCount += 1;
+      presentations.push(...r.value);
+    } else {
+      failures.push({
+        backendURL,
+        env: deriveEnvLabel(backendURL),
+        err: r.reason,
+      });
+    }
+  });
+  return { presentations, failures, fulfilledCount };
+}
+
+// Merged registry across all paired backends. Stays a flat array (every caller
+// expects one). Preserves single-backend behaviour: when nothing is reachable
+// AND no backend answered, the underlying bridge error propagates (so a typed
+// code like `pane_suspended` or a 401 still surfaces) — for several failing
+// backends it's an aggregate message.
+export async function listOpenPresentations() {
+  const { presentations, failures, fulfilledCount } =
+    await fanOutPresentations();
+  if (presentations.length === 0 && fulfilledCount === 0 && failures.length > 0) {
+    if (failures.length === 1) throw failures[0].err;
+    const err = new Error(
+      "slidemind: every paired backend failed to list presentations:\n" +
+        failures
+          .map((f) => `  ${f.env}: ${f.err.message}`)
+          .join("\n"),
+    );
+    throw err;
+  }
+  return presentations;
+}
+
+// The user/agent-facing shape of a presentation entry. `backendURL` is internal
+// routing state — every caller targets a presentation by `presId` (the backend
+// is re-resolved server-side from it), so the URL must never leave the process
+// in any printed line or command output. Keeps everything else — presId, title,
+// fileName, connected, suspendedAt, the short `env` label, and the readiness
+// fields (connectionState, designState, capabilities, nextAction) that agents
+// parse from `presentations --json` to decide whether/how to target a pane.
+export function toPublicPresentation(p) {
+  const { backendURL, ...rest } = p;
+  return rest;
+}
+
+// Like listOpenPresentations but never throws on per-backend failures — returns
+// the merged registry plus which backends were unreachable, for callers that
+// want to report partial results (requireHost, whoami).
+export async function listOpenPresentationsDetailed() {
+  const { presentations, failures } = await fanOutPresentations();
+  return {
+    presentations,
+    unreachable: failures.map((f) => ({
+      backendURL: f.backendURL,
+      env: f.env,
+      error: f.err?.message ? f.err.message : String(f.err),
+    })),
+  };
+}
+
+// Probe the bridge for an open PowerPoint host across every paired backend.
+// Returns the merged registry, or throws a single actionable message — the
+// shared precondition for every author/render command now that the design truth
+// lives in the add-in. Suspended entries (task-pane socket dropped, e.g.
+// PowerPoint backgrounded) count as registered: render + bundle work without
+// the pane, and a push waits server-side for the pane to reconnect.
+export async function requireHost() {
+  const { presentations, unreachable } = await listOpenPresentationsDetailed();
+  if (Array.isArray(presentations) && presentations.length > 0) {
+    return presentations;
+  }
+  // Nothing registered. Distinguish "a backend was unreachable" from "backends
+  // answered but no window is open" so the user gets the right next step.
+  if (unreachable.length > 0) {
+    throw new Error(
+      "Open PowerPoint with the slidemind add-in and an active corporate design, then retry.\n" +
+        unreachable
+          .map((u) => `  (bridge: ${u.env}: ${u.error})`)
+          .join("\n") +
+        `\n${READY_HINT}`,
+    );
+  }
+  throw new Error(
+    "No PowerPoint window is registered with the slidemind add-in.\n" +
+      "If PowerPoint is already open, bring it to the foreground and click the slidemind pane once so it re-registers, then retry.\n" +
+      "Otherwise open PowerPoint with the slidemind add-in and an active corporate design, then retry.\n" +
+      READY_HINT,
+  );
+}
+
+export function hasReadinessFields(p) {
+  return (
+    p &&
+    (typeof p.connectionState === "string" ||
+      typeof p.designState === "string" ||
+      (p.capabilities && typeof p.capabilities === "object"))
+  );
+}
+
+export function isRenderReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return true;
+  if (p.capabilities?.render === true) return true;
+  if (p.designState === "ready" && p.capabilities?.render !== false) return true;
+  return false;
+}
+
+export function isPaneReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return p.connected !== false && !p.suspendedAt;
+  if (p.capabilities?.paneOps === true) return true;
+  return (
+    p.connectionState === "connected" &&
+    p.connected !== false &&
+    !p.suspendedAt &&
+    p.connectionState !== "stale"
+  );
+}
+
+export async function waitForReadyPresentation(predicate, { timeoutMs = null } = {}) {
+  const waitMs = timeoutMs ?? readinessTimeoutMs();
+  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const { presentations, unreachable } = await listOpenPresentationsDetailed();
+    if (presentations.some(predicate)) return presentations;
+    // Do not wait when nothing is registered at all. Waiting helps only for an
+    // already-open pane that is still hydrating brand/readiness metadata.
+    if (presentations.length === 0 || Date.now() >= deadline) {
+      return { presentations, unreachable, timedOut: presentations.length > 0 };
+    }
+    await sleep(pollMs);
+  }
+}
+
+// The bounded poll behind the window listings. Unlike
+// waitForReadyPresentation it PURPOSELY does NOT early-return on an empty
+// registry: the empty window right after a pane reload / PowerPoint wake is
+// exactly the flaky case this papers over. Polls the merged registry every
+// SLIDEMIND_BRIDGE_READY_POLL_MS (default 1.5s) up to
+// SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS (default 6s), stopping as soon as at
+// least one pane is pane-ready. A `timeoutMs` of 0 means single-shot — one
+// fetch, no sleep. Returns { all, ready } so the caller can list EVERY entry
+// (suspended included, with its status) yet still know which are live. Does not
+// touch waitForReadyPresentation / requirePaneHost — agent target selection
+// still uses only ready panes.
+export async function listReadyPresentationsWithWait({ timeoutMs = null } = {}) {
+  const waitMs =
+    timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS", 6000);
+  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const all = await listOpenPresentations();
+    const ready = all.filter(isPaneReadyPresentation);
+    if (ready.length > 0 || waitMs <= 0 || Date.now() >= deadline) {
+      return { all, ready };
+    }
+    await sleep(pollMs);
+  }
+}
+
+export async function requireRenderHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isRenderReadyPresentation)) {
+    return first.presentations;
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isRenderReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited;
+    if (waited.presentations.some(isRenderReadyPresentation)) {
+      return waited.presentations;
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but no window is render-ready yet. " +
+        "Wait for the corporate design to finish matching, or pick/create a corporate design in the add-in, then retry. " +
+        READY_HINT,
+    );
+  }
+  return requireHost();
+}
+
+export async function requirePaneHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isPaneReadyPresentation)) {
+    return first.presentations.filter(isPaneReadyPresentation);
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isPaneReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited.filter(isPaneReadyPresentation);
+    if (waited.presentations.some(isPaneReadyPresentation)) {
+      return waited.presentations.filter(isPaneReadyPresentation);
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but the task pane is not ready for pane operations. " +
+        "Bring PowerPoint forward and click or reopen the slidemind pane, then retry. " +
+        READY_HINT,
+    );
+  }
+  return requireHost();
+}
+
+// "Is a task pane available RIGHT NOW?" — the non-throwing twin of
+// requirePaneHost, for paths where an open pane is an OPTION rather than a
+// precondition (a stale permission snapshot can be routed around by relaying
+// through a live pane, which signs each request with a fresh browser token).
+// Never waits for hydration and never authors a blocker: an empty array means
+// "no, carry on with what you were doing", not "stop".
+export async function paneReadyPresentations() {
+  try {
+    const { presentations } = await listOpenPresentationsDetailed();
+    return presentations.filter(isPaneReadyPresentation);
+  } catch {
+    return [];
+  }
+}
+
+// Tie-break a multi-backend presId collision without bothering the user when
+// only one candidate can actually serve the deck:
+//   (a) exactly one CONNECTED pane whose active CD matches the deck's bundle
+//       ref (`preferBrandId` — the deck's presFP, which equals the pane's
+//       brandId by the bundle-cache contract);
+//   (b) else exactly one connected pane with ANY active CD (brandId set) —
+//       e.g. a local dev backend connected without a CD next to prod with one.
+// Returns the winning entry or null when genuinely ambiguous.
+export function tieBreakMatches(matches, preferBrandId) {
+  const live = matches.filter(isPaneReadyPresentation);
+  if (preferBrandId) {
+    const want = live.filter((m) => m.brandId === preferBrandId);
+    if (want.length === 1) return want[0];
+  }
+  const withCd = live.filter((m) => m.brandId);
+  if (withCd.length === 1) return withCd[0];
+  return null;
+}
+
+// Resolve which backend a presId lives on via a LIVE fan-out list (never a
+// cached map — a presId can move backends on re-pair/redeploy). Throws an
+// actionable message on a miss, or an ambiguity error when the same presId is
+// open on more than one reachable backend and no tie-break rule settles it.
+export async function resolveBackendForPres(
+  presId,
+  { preferBrandId = null } = {},
+) {
+  if (!presId) throw new Error("resolveBackendForPres: presId is required");
+  const { presentations } = await fanOutPresentations();
+  const matches = presentations.filter((p) => p.presId === presId);
+  if (matches.length === 1) return matches[0].backendURL;
+  if (matches.length > 1) {
+    const winner = tieBreakMatches(matches, preferBrandId);
+    if (winner) return winner.backendURL;
+    const envs = matches.map((m) => m.env).join(", ");
+    throw new Error(
+      `Presentation '${presId}' 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).",
+    );
+  }
+  throw new Error(
+    `No open PowerPoint window registered with presId='${presId}' on any paired backend. ` +
+      "Run 'slidemind ready --diagnose' to see what's open.",
+  );
+}
+
+// Wait for a presentation's task pane to come back after a `pane_suspended`
+// (PowerPoint backgrounded → webview suspended → socket dropped). Polls the
+// live registry; succeeds on the same presId reconnecting, OR on a CONNECTED
+// entry matching `fileName` + `brandId` — a pane reconnect can mint a NEW
+// presId for the same window, so identity-by-content covers the churn. Returns
+// the live registry entry (caller re-targets from it), or null on timeout.
+// `onWait` fires once with the wait budget in seconds — the caller's single
+// actionable "click the pane" line.
+//
+// `otherPresIds` are windows the caller already knows are NOT the target (the
+// rest of the registry it picked from). They are excluded from the last-resort
+// design-fingerprint match — see below.
+export async function waitForPaneReady(
+  presId,
+  {
+    backendURL = null,
+    fileName = null,
+    brandId = null,
+    otherPresIds = null,
+    timeoutMs = null,
+    pollMs = null,
+    onWait = null,
+  } = {},
+) {
+  const notTheTarget = new Set(otherPresIds ?? []);
+  const waitMs =
+    timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_TIMEOUT_MS", 120000);
+  const stepMs = pollMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_POLL_MS", 3000);
+  const deadline = Date.now() + waitMs;
+  let notified = false;
+  for (;;) {
+    let list = [];
+    try {
+      list = backendURL
+        ? await listPresentationsForBackend(backendURL)
+        : (await fanOutPresentations()).presentations;
+    } catch {
+      /* transient list failure — poll again until the deadline */
+    }
+    const connected = list.filter(
+      (p) => isPaneReadyPresentation(p),
+    );
+    const same = connected.find((p) => p.presId === presId);
+    if (same) return same;
+    if (fileName || brandId) {
+      const rematch = connected.find(
+        (p) =>
+          (!fileName || p.fileName === fileName || p.title === fileName) &&
+          (!brandId || p.brandId === brandId),
+      );
+      if (rematch) return rematch;
+      // Last resort: match on the design fingerprint alone (presFP == brandId).
+      // A reconnect can report a different name for the same window — the user
+      // hit Save As, or the pane reports the title where it used to report the
+      // file name — but the active corporate design does not change with it.
+      // Only when EXACTLY one connected window carries it: two windows on the
+      // same design are indistinguishable, and pushing into the wrong one is
+      // worse than waiting.
+      //
+      // A window the caller ALREADY saw next to the target is not a churned
+      // target — it is a different presentation that merely shares the design
+      // (most tenants run exactly one), and retargeting to it would append the
+      // deck's slides to an unrelated file. Most tenants run a single corporate
+      // design, so brandId alone is not window identity.
+      if (fileName && brandId) {
+        const byBrand = connected.filter(
+          (p) => p.brandId === brandId && !notTheTarget.has(p.presId),
+        );
+        if (byBrand.length === 1) return byBrand[0];
+      }
+    }
+    if (Date.now() >= deadline) return null;
+    if (!notified) {
+      notified = true;
+      onWait?.(Math.round(waitMs / 1000));
+    }
+    await sleep(stepMs);
+  }
+}
+
+// The one actionable line a human needs when a pane op is waiting. stderr so
+// it reaches the terminal from the CLI.
+export function paneWaitNotice(seconds) {
+  process.stderr.write(
+    "task pane suspended — click the slidemind pane in PowerPoint to wake it " +
+      `(waiting up to ${seconds}s)…\n`,
+  );
+}
+
+// The window is gone from the registry but its pane may already be back under a
+// new presId (churn on every reconnect) — nothing for the user to do here, so
+// say what the CLI is doing rather than asking for a click.
+export function paneRetargetNotice(seconds) {
+  process.stderr.write(
+    "the target PowerPoint window re-registered — re-matching it by corporate " +
+      `design (up to ${seconds}s)…\n`,
+  );
+}
+
+// A 404 the RELAY emitted about the presId itself (the window is no longer in
+// the registry — a pane reconnect mints a new presId for the same window)
+// rather than one a ROUTE emitted about something else it was asked for (a
+// stale `unknown_search`, an unimplemented route). Only the former is worth
+// re-targeting: the same window is probably back under a new id.
+//
+// Read the PARSED code, never `err.code`: bridgeFetch falls that back to the
+// human error string, and the relay's vanished-presId 404 carries prose only
+// ("No PowerPoint window registered for presId='X'") — so testing `err.code`
+// saw a truthy, unmatched value and never retargeted anything.
+export function isMissingPresentationError(err) {
+  if (err?.status !== 404) return false;
+  const code = err?.body?.code ?? null;
+  return !code || code === "unknown_presentation" || code === "presentation_not_found";
+}
+
+// Run a pane-relayed engine op; on `pane_suspended` (the server already waited
+// ~25s for a reconnect) OR `pane_timeout` (the pane looked connected but never
+// acked within the server's 60s window — the server marks it suspended on the
+// way out, so the same wake applies) wait CLIENT-side for the pane to wake —
+// one actionable line, then a single retry against the live entry (covers
+// presId churn too). Engine ops are idempotent reads, and the one mutation
+// (live insert) rides the SAME operationId through the retry so the pane-side
+// dedup makes a re-send safe.
+//
+// `fileName`/`brandId` identify the WINDOW so the wait can re-match it after a
+// presId churn (see waitForPaneReady). `retargetOnMissing` additionally treats a
+// vanished presId as recoverable — opt-in, because for most engine ops a 404 is
+// the search record talking, not the window: it re-lists the registry, re-matches
+// by presFP and retries ONCE on a short budget before the caller surfaces the
+// wake-PowerPoint blocker.
+export async function engineOpWithPaneWait(
+  presId,
+  backendURL,
+  attempt,
+  {
+    fileName = null,
+    brandId = null,
+    otherPresIds = null,
+    retargetOnMissing = false,
+  } = {},
+) {
+  try {
+    return await attempt(presId, backendURL);
+  } catch (err) {
+    const suspended =
+      err?.code === "pane_suspended" || err?.code === "pane_timeout";
+    const churned = retargetOnMissing && isMissingPresentationError(err);
+    if (!suspended && !churned) throw err;
+    const live = await waitForPaneReady(presId, {
+      backendURL,
+      fileName,
+      brandId,
+      otherPresIds,
+      // A churned presId needs a re-list, not a user: the window is already
+      // there under a new id, so poll briefly instead of holding the full
+      // click-the-pane budget. A suspended pane keeps that budget.
+      timeoutMs: churned && !suspended ? envInt("SLIDEMIND_BRIDGE_PANE_RETARGET_TIMEOUT_MS", 15000) : null,
+      onWait: churned && !suspended ? paneRetargetNotice : paneWaitNotice,
+    });
+    if (!live) throw err;
+    return attempt(live.presId, live.backendURL ?? backendURL);
+  }
+}
+
+// Read the CURRENT content of an open presentation (the "pull content" path
+// behind `slidemind read`). `mode` selects the
+// depth: "summary" returns a per-slide outline (index, layout, title, subtitle);
+// "raw" (default) returns each slide's full plain text — NOT the add-in's editing
+// markup. Unlike engine ops, content is WINDOW-BOUND: it reads THAT presentation,
+// so we resolve the origin backend from the presId and relay through that
+// window's pane. It's an idempotent read, so engineOpWithPaneWait's single
+// pane_suspended client-wait + retry against the live entry is safe (like viewSlide).
+export async function getPresentationContent({
+  presId,
+  mode = "raw",
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("getPresentationContent: presId is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { mode: mode === "summary" ? "summary" : "raw" };
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/content`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return res.json(); // { ok, mode, slideCount, slides }
+  });
+}