slidemind 0.1.0 → 0.1.1

package/src/bridge/client.mjs

@@ -5,67 +5,111 @@
 // backend runs render/bundle in-process and relays insert/replace/engine to the
 // open PowerPoint pane. No localhost, no shared loopback token, no cert.
 
-import fs from "node:fs";
 import http from "node:http";
-import os from "node:os";
-import path from "node:path";
 import https from "node:https";
 
-import { readSessionConfig } from "./config.mjs";
+import {
+  deriveEnvLabel,
+  getSessionFor,
+  readSessions,
+} from "./config.mjs";
 
 function isLoopbackHostname(hostname) {
   return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
 }
 
-export function bridgeStateDir() {
-  if (process.platform === "win32") {
-    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-    return path.join(base, "slidemind");
-  }
-  const base = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
-  return path.join(base, "slidemind");
+// The fan-out probe (listing presentations across every paired backend) uses a
+// shorter timeout than ordinary calls so one dead/slow backend — a local relay
+// that isn't running — can't stall the whole sweep for the full 35s default.
+function listTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_LIST_TIMEOUT_MS || "8000", 10) || 8000
+  );
 }
 
-export function bridgeTokenPath() {
-  return path.join(bridgeStateDir(), "bridge-token");
+const NOT_PAIRED_MESSAGE =
+  'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
+  "and run the shown `slidemind pair …` command, then retry.";
+
+// One transient blip — a pane mid-reconnect after a backend deploy, a stale
+// registration the pane is about to refresh — should not fail a whole skill
+// step. Idempotent reads retry a couple of times; mutations never do (the
+// request may already have been delivered).
+function transientRetryDelays() {
+  const raw = process.env.SLIDEMIND_BRIDGE_RETRY_DELAYS_MS || "1500,4000";
+  return raw
+    .split(",")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n) && n >= 0);
 }
 
-export function readBridgeToken() {
-  const file = bridgeTokenPath();
-  let raw;
-  try {
-    raw = fs.readFileSync(file, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") {
+function isTransientBridgeError(err) {
+  if (!err) return false;
+  // pane_suspended needs the user (foreground PowerPoint), not a blind retry —
+  // the relay already waited for a reconnect before returning it.
+  if (err.code === "pane_suspended") return false;
+  if (err.status === 404 || err.status === 502 || err.status === 503) return true;
+  if (err.status === 409 && err.code === "pane_disconnected") return true;
+  return /relay unreachable/i.test(String(err.message || ""));
+}
+
+async function withTransientRetry(fn) {
+  const delays = transientRetryDelays();
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= delays.length || !isTransientBridgeError(err)) throw err;
+      await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
+    }
+  }
+}
+
+// The paired backends in scope for this invocation. Defaults to every paired
+// session (fan-out); `SLIDEMIND_BACKEND` narrows it to one (the CLI sets that
+// env from a `--backend <url|env>` flag) for speed or to disambiguate. Throws
+// the same actionable message as a missing pairing when nothing matches.
+function sessionsInScope() {
+  const all = readSessions();
+  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
+  const scope = process.env.SLIDEMIND_BACKEND;
+  if (scope && scope.trim()) {
+    const want = scope.trim();
+    const match = all.filter(
+      (s) =>
+        s.backendURL === want ||
+        s.label === want ||
+        deriveEnvLabel(s.backendURL) === want ||
+        s.backendURL.includes(want),
+    );
+    if (match.length === 0) {
       throw new Error(
-        `slidemind bridge token not found at ${file}. ` +
-          `Start the slidemind PowerPoint add-in first — it generates the token on first run.`,
+        `slidemind is not paired with '${want}'. Run 'slidemind whoami' to see paired environments.`,
       );
     }
-    throw err;
-  }
-  const token = raw.trim();
-  if (!token) {
-    throw new Error(`slidemind bridge token at ${file} is empty.`);
+    return match;
   }
-  return token;
+  return all;
 }
 
-// The CLI talks to the cloud relay endpoint stored by `slidemind pair`. The
-// session token is the credential — no localhost, no shared loopback token.
-function requireSession() {
-  const session = readSessionConfig();
-  if (!session) {
-    throw new Error(
-      'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
-        "and run the shown `slidemind pair …` command, then retry.",
-    );
+// Resolve the credential for one backend (or the default session when no
+// backendURL is given — the back-compat single-session path).
+function sessionForBackend(backendURL) {
+  if (backendURL) {
+    const s = getSessionFor(backendURL);
+    if (!s)
+      throw new Error(
+        `slidemind is not paired with '${deriveEnvLabel(backendURL)}'.`,
+      );
+    return s;
   }
-  return session;
+  const all = readSessions();
+  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
+  return all[0];
 }
 
-async function bridgeFetch(pathPart, init = {}) {
-  const session = requireSession();
+async function bridgeFetch(pathPart, init = {}, backendURL = null) {
+  const session = sessionForBackend(backendURL);
   const url = `${session.backendURL}${pathPart}`;
   const headers = {
     accept: "application/json",
@@ -79,7 +123,7 @@ async function bridgeFetch(pathPart, init = {}) {
   } catch (err) {
     if (err && /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(String(err.message || err))) {
       throw new Error(
-        `slidemind relay unreachable at ${url}. Check your connection; ` +
+        `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
           "if it persists, re-pair with `slidemind pair`.",
       );
     }
@@ -158,10 +202,11 @@ function nodeRequest(urlString, init = {}) {
         });
       },
     );
-    // Default 35s > the add-in's 30s emitWithAck, so a suspended pane surfaces a
-    // typed `pane_suspended` rather than a client timeout. A real timeout is
-    // tagged `bridge_timeout` so non-idempotent callers (insert) know the request
-    // may already have been delivered and must NOT auto-retry it.
+    // Default 35s > the relay's 25s wait-for-pane-reconnect, so a suspended
+    // pane surfaces a typed `pane_suspended` rather than a client timeout. A
+    // real timeout is tagged `bridge_timeout` so non-idempotent callers
+    // (insert) know the request may already have been delivered and must NOT
+    // auto-retry it.
     req.setTimeout(timeoutMs, () => {
       const err = new Error(
         `slidemind bridge request timed out after ${timeoutMs}ms`,
@@ -175,42 +220,159 @@ function nodeRequest(urlString, init = {}) {
   });
 }
 
+// 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.
+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 }));
+  });
+}
+
+// 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.
+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 res = await bridgeFetch("/api/cli/presentations");
-  const data = await res.json();
-  return Array.isArray(data?.presentations) ? data.presentations : [];
+  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;
 }
 
-// Probe the bridge for an open PowerPoint host. Returns the live 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.
+// 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 MCP payload. Keeps presId, title, fileName, connected,
+// suspendedAt, and the short `env` label (the only discriminator a user sees).
+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() {
-  let registry;
-  try {
-    registry = await listOpenPresentations();
-  } catch (err) {
+  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" +
-        `  (bridge: ${err.message})`,
+        unreachable
+          .map((u) => `  (bridge: ${u.env}: ${u.error})`)
+          .join("\n"),
     );
   }
-  if (!Array.isArray(registry) || registry.length === 0) {
+  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.",
+  );
+}
+
+// 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.
+export async function resolveBackendForPres(presId) {
+  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 envs = matches.map((m) => m.env).join(", ");
     throw new Error(
-      "No PowerPoint window is registered with the slidemind add-in.\n" +
-        "Open PowerPoint with the slidemind add-in and an active corporate design, then retry.",
+      `Presentation '${presId}' is open on multiple environments: ${envs}. ` +
+        "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
     );
   }
-  return registry;
+  throw new Error(
+    `No open PowerPoint window registered with presId='${presId}' on any paired backend. ` +
+      "Run 'slidemind presentations' to see what's open.",
+  );
 }
 
 // GET the full design bundle (tokens, css, layouts, designRules, signed asset
 // URLs, engines) for the presentation's active corporate design.
-export async function getDesignBundle(presId) {
+export async function getDesignBundle(presId, { backendURL = null } = {}) {
   if (!presId) throw new Error("getDesignBundle: presId is required");
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
-  );
-  return res.json();
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return withTransientRetry(async () => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
+      {},
+      be,
+    );
+    return res.json();
+  });
 }
 
 // Server-side OOXML render: ship authored slide JSX (+ deck-local assets) and
@@ -221,11 +383,13 @@ export async function renderPptx({
   slides,
   deckAssets = null,
   etag = null,
+  backendURL = null,
 }) {
   if (!presId) throw new Error("renderPptx: presId is required");
   if (!slides || Object.keys(slides).length === 0) {
     throw new Error("renderPptx: slides is required");
   }
+  const be = backendURL || (await resolveBackendForPres(presId));
   const body = { slides };
   if (deckAssets && Object.keys(deckAssets).length > 0) {
     body.deckAssets = deckAssets;
@@ -237,7 +401,14 @@ export async function renderPptx({
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      // Server-side OOXML render is a heavy operation — a full deck of richly
+      // composed slides routinely runs well past the 35s default. Treat it like
+      // a mutation: give it a generous default and let env override it.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
+        300000,
     },
+    be,
   );
   return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
 }
@@ -245,17 +416,25 @@ export async function renderPptx({
 // Brand-engine search through the local bridge. New add-ins run this
 // server-side with the relayed user token; older add-ins may fall back to a
 // task-pane proxy. Returns a searchId + numbered result thumbnails.
-export async function engineSearch({ presId, engineId, query }) {
+export async function engineSearch({ presId, engineId, query, backendURL = null }) {
   if (!presId) throw new Error("engineSearch: presId is required");
   if (!engineId) throw new Error("engineSearch: engineId is required");
   if (!query) throw new Error("engineSearch: query is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
   const res = await bridgeFetch(
     `/api/cli/presentations/${encodeURIComponent(presId)}/engine/search`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ engineId, query }),
+      // Engine ops relay through the pane: the server may wait up to ~25s for
+      // a suspended pane to reconnect, then up to 60s for the pane's ack —
+      // stay above that sum so typed errors win over client timeouts.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+        90000,
     },
+    be,
   );
   return res.json(); // { ok, searchId, resultCount, gridDataUri, thumbnails }
 }
@@ -268,6 +447,7 @@ export async function engineDownload({
   searchId,
   selection,
   iconColor = null,
+  backendURL = null,
 }) {
   if (!presId) throw new Error("engineDownload: presId is required");
   if (typeof searchId !== "number") {
@@ -276,6 +456,7 @@ export async function engineDownload({
   if (typeof selection !== "number") {
     throw new Error("engineDownload: selection (number) is required");
   }
+  const be = backendURL || (await resolveBackendForPres(presId));
   const body = { searchId, selection };
   if (iconColor) body.iconColor = iconColor;
   const res = await bridgeFetch(
@@ -284,7 +465,13 @@ export async function engineDownload({
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      // Same relay path as engine/search — outlast the server's reconnect
+      // wait + pane ack timeout.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+        90000,
     },
+    be,
   );
   return res.json(); // { ok, base64, mimeType, svgMarkup }
 }
@@ -295,9 +482,11 @@ export async function insertSlides({
   insertAt = null,
   sourceSlideIds = null,
   operationId = 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 };
   const res = await bridgeFetch(
     `/api/cli/presentations/${encodeURIComponent(presId)}/insert`,
@@ -309,13 +498,20 @@ export async function insertSlides({
         parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
         1805000,
     },
+    be,
   );
   return res.json().catch(() => ({}));
 }
 
-export async function replaceSlides({ presId, base64, operationId = null }) {
+export async function replaceSlides({
+  presId,
+  base64,
+  operationId = 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 res = await bridgeFetch(
     `/api/cli/presentations/${encodeURIComponent(presId)}/replace`,
     {
@@ -326,23 +522,33 @@ export async function replaceSlides({ presId, base64, operationId = null }) {
         parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
         1805000,
     },
+    be,
   );
   return res.json().catch(() => ({}));
 }
 
-// Pick a target presentation given the live registry and an optional explicit
-// presId. Returns the presId to push to, or throws with a helpful message if
-// the choice is ambiguous.
-export function pickPresentation(registry, explicitPresId) {
+// 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.
+export function pickPresentationEntry(registry, explicitPresId) {
   if (explicitPresId) {
-    const match = registry.find((p) => p.presId === explicitPresId);
-    if (!match) {
+    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}`,
       );
     }
-    return match.presId;
+    if (matches.length > 1) {
+      const envs = matches.map((m) => m.env || "?").join(", ");
+      throw new Error(
+        `Presentation '${explicitPresId}' is open on multiple environments: ${envs}. ` +
+          "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
+      );
+    }
+    return matches[0];
   }
   if (registry.length === 0) {
     throw new Error(
@@ -350,11 +556,21 @@ export function pickPresentation(registry, explicitPresId) {
         "Open a presentation, ensure the add-in is loaded, and try again.",
     );
   }
-  if (registry.length === 1) return registry[0].presId;
+  if (registry.length === 1) return registry[0];
   const list = registry
-    .map((p) => `  ${p.presId}\t${p.title || p.fileName || "(untitled)"}`)
+    .map(
+      (p) =>
+        `  ${p.presId}\t${p.env ? `[${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}`,
   );
 }
+
+// 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;
+}