slidemind 0.3.13 → 0.3.14

package/src/cli/connection.mjs

@@ -0,0 +1,147 @@
+import { isClaudePluginInstall, updateCliInstruction } from "../install-channel.mjs";
+
+export function publicConnectionStatus(status, client) {
+  return {
+    paired: status.paired,
+    backendCount: status.backendCount,
+    backends: (status.backends ?? []).map((b) => ({
+      env: b.env,
+      ok: b.ok,
+      readinessV1: b.readinessV1 === true,
+      capabilities: b.capabilities ?? null,
+      minCliVersion: b.minCliVersion ?? null,
+      cliUpdateRequired: b.cliUpdateRequired === true,
+      error: b.error,
+      code: b.code ?? null,
+      status: b.status ?? null,
+      summary: b.summary ?? null,
+      presentations: (b.presentations ?? []).map(client.toPublicPresentation),
+    })),
+    presentations: (status.presentations ?? []).map(client.toPublicPresentation),
+  };
+}
+
+// The readiness ladder splits in two, because the two halves fail
+// independently: BACKEND AUTHORING readiness (a session, a reachable add-in
+// backend, a supported CLI — everything render, bundle and the pane-free engine
+// routes need) and LIVE POWERPOINT readiness (a registered window, render-ready
+// metadata, an awake pane — what push/insert-slide and reading an open deck
+// need). Keeping them apart is the whole point of doc 13: a dead pane is no
+// longer "cannot work", it only defers the last mile.
+//
+// Each rung is a STRUCTURED blocker: `code` is the machine-copeable reason an
+// agent switches on; `actor` says who can clear it — only `cli_update_required`
+// is the AGENT's to fix (it can run `slidemind update`), every other rung needs
+// a human at the add-in. The one exception is a plugin-installed CLI:
+// `/plugin` is the only updater that replaces the binary on the session's PATH,
+// and the agent cannot drive it, so that rung hands back to the user (see
+// src/install-channel.mjs).
+export function backendBlocker(pub) {
+  if (!pub.paired) {
+    return {
+      code: "not_paired",
+      actor: "user",
+      message:
+        "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.",
+    };
+  }
+  if ((pub.backends ?? []).every((b) => !b.ok)) {
+    // Something answered 503 (already retried by the probe): the add-in whose
+    // session store did not answer (code `backend_unavailable`), or a proxy in
+    // front of it with no machine code at all. The session is intact, so the
+    // remedy is to wait — never to re-pair, which is what the generic wording
+    // below invites. Same predicate as the probe's retry.
+    const unavailable = (b) =>
+      b.code === "backend_unavailable" || (b.status === 503 && b.code !== "pane_suspended");
+    if ((pub.backends ?? []).every(unavailable)) {
+      return {
+        code: "backend_unavailable",
+        actor: "agent",
+        message:
+          "The add-in backend is temporarily unavailable (its session store did not answer). " +
+          "Wait a minute and run `slidemind ready` again; the CLI session itself is fine, do not reconnect.",
+      };
+    }
+    return {
+      code: "all_unreachable",
+      actor: "user",
+      message:
+        "Every paired backend is unreachable. Check network/VPN/backend status, or re-pair if the environment moved.",
+    };
+  }
+  // Version skew explains most downstream failures — surface it before pane
+  // readiness so the user fixes the right thing first.
+  const outdated = (pub.backends ?? []).find((b) => b.cliUpdateRequired);
+  if (outdated) {
+    return {
+      code: "cli_update_required",
+      actor: isClaudePluginInstall() ? "user" : "agent",
+      message:
+        `This CLI is older than the minimum the '${outdated.env}' add-in supports` +
+        `${outdated.minCliVersion ? ` (${outdated.minCliVersion})` : ""}. ` +
+        updateCliInstruction(),
+    };
+  }
+  return null;
+}
+
+// The live-PowerPoint half. Never gates render, bundle or the pane-free engine
+// routes — it only says whether the ops that genuinely type into an open deck
+// (push's insert, insert-slide, reading an unsaved presentation) can run now.
+// The `message` strings are BYTE-IDENTICAL to the pre-split ladder so the
+// diagnostic's
+// printed output never churns.
+export function paneBlocker(pub) {
+  if ((pub.presentations ?? []).length === 0) {
+    return {
+      code: "no_window",
+      actor: "user",
+      message:
+        "No PowerPoint window is registered. If PowerPoint is already open with the slidemind pane, bring it to the foreground (click the pane) and re-run. Otherwise open PowerPoint, load the slidemind add-in, and activate or create a corporate design.",
+    };
+  }
+  const renderReady = pub.presentations.some(
+    (p) =>
+      p.capabilities?.render === true ||
+      (!p.connectionState && p.connected !== false) ||
+      p.designState === "ready",
+  );
+  if (!renderReady) {
+    return {
+      code: "not_render_ready",
+      actor: "user",
+      message:
+        "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+    };
+  }
+  const paneReady = pub.presentations.some(
+    (p) =>
+      p.capabilities?.paneOps === true ||
+      ((!p.connectionState || p.connectionState === "connected") &&
+        p.connected !== false &&
+        !p.suspendedAt),
+  );
+  if (!paneReady) {
+    return {
+      code: "pane_suspended",
+      actor: "user",
+      message:
+        "Rendering is available, but pane operations are suspended. Bring PowerPoint forward and click/reopen the slidemind pane before push, insert-slide, or reading this window.",
+    };
+  }
+  return null;
+}
+
+// The two ladders end-to-end, in the order a user hits them: nothing about a
+// window matters while the backend half is unmet. `slidemind ready` layers
+// `ambiguous_design` on top and treats `pane_suspended` as non-blocking (a
+// render-ready-but-suspended window is still a design source).
+export function connectionBlocker(pub) {
+  return backendBlocker(pub) ?? paneBlocker(pub);
+}
+
+// Back-compat projection for the diagnostic: just the blocker's message, or "Ready."
+// when the ladder is clear. Keeps the ladder authored in ONE place.
+export function connectionNextAction(pub) {
+  return connectionBlocker(pub)?.message ?? "Ready.";
+}