slidemind 0.3.13 → 0.3.14

package/src/cli/engine-helpers.mjs

@@ -0,0 +1,429 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { envTag } from "../bridge/config.mjs";
+import { fail, loadBridgeModule, SRC_DIR } from "./common.mjs";
+
+// Turn the add-in's deliberately terse search failures into something actionable.
+// It withholds detail on purpose: the raw message used to carry the built OData
+// filter and physical index names, and "Engine not found" doubles as a permission
+// denial so engine existence stays undisclosed. So the CLI can't diagnose — it can
+// only name the next move.
+export function searchFailureHint(error, engineId) {
+  const raw = error ?? "unknown error";
+  if (/engine not found/i.test(raw)) {
+    return (
+      `${raw} — '${engineId}' is unknown or not visible to you. ` +
+      `Re-run 'slidemind ls engines' (ids can be retired) and pick from the live list, ` +
+      `or search 'scope:all' to skip engines entirely.`
+    );
+  }
+  if (/^search failed$/i.test(raw)) {
+    return (
+      `${raw} — the add-in withholds the reason (it can leak index internals); ` +
+      `the detail is in the add-in's logs. Retry once, then try 'scope:all'.`
+    );
+  }
+  return raw;
+}
+
+// Zero results is now a routine, ambiguous outcome: the add-in answers "success,
+// nothing" for a corpus that isn't connected, one that is still embedding, and a
+// folder filter that matches nothing — all indistinguishable on the wire. Say that
+// instead of letting an empty list read as "this content does not exist".
+export function writeEmptySearchDiagnostic(engineId, bundleMod) {
+  const isScope = bundleMod.isSearchScopeId(engineId);
+  const lines = [
+    `  No results — this does NOT mean the content doesn't exist. Any of these looks identical here:`,
+    `    · nothing is connected yet, so there is no corpus to search`,
+    `    · the corpus is still indexing (content appears progressively)`,
+  ];
+  if (!isScope) {
+    lines.push(
+      `    · this engine is a saved FOLDER FILTER and the content sits outside it`,
+    );
+  }
+  lines.push(`  Next:`);
+  if (!isScope) {
+    lines.push(
+      `    · widen to the unfiltered corpus: slidemind search "<query>" --engine ${bundleMod.SCOPE_ALL} --result-type slide`,
+    );
+  }
+  lines.push(
+    `    · re-word the query (content search matches phrasing, so a synonym can decide a hit)`,
+    `    · slidemind ls engines — see every engine and scope you can reach`,
+  );
+  if (isScope) {
+    lines.push(
+      `    · if the unfiltered corpus is also empty, report it as "not found" and name what you searched — don't author a replacement as if reuse had been tried`,
+    );
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+// Write the search's numbered collage to a file and tell the agent to look at it.
+//
+// The add-in composes ONE bounded 800x600 image showing every candidate with its
+// selection number burned in — the same picture the in-app agent sees. That is the
+// intended way to choose a visual result: one look at one file, rather than N
+// per-result previews (which is also why the relay ack carries no per-result bytes
+// — a corpus image is multi-megabyte and N of them can't cross the relay).
+//
+// Best-effort by design: a missing/…unparseable grid must never fail a search that
+// otherwise returned usable results. Content-intent searches have no grid at all —
+// their signal is the printed text.
+export function writeSearchGrid(gridDataUri, searchId, resolveExt) {
+  if (typeof gridDataUri !== "string" || !gridDataUri.startsWith("data:")) {
+    return null;
+  }
+  try {
+    const m = /^data:([^;]+);base64,(.+)$/.exec(gridDataUri);
+    if (!m) return null;
+    const bytes = Buffer.from(m[2], "base64");
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-grid-"));
+    const target = path.join(dir, `grid-${searchId}.${resolveExt(m[1], bytes)}`);
+    fs.writeFileSync(target, bytes);
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+// Where an engine op runs. Newer add-ins serve the engine surface off the CLI
+// session itself (`/api/cli/engines`, `/api/cli/searches/*`), so discovery,
+// search, download and extraction need no PowerPoint window at all; older ones
+// relay every one of them through a task-pane webview, which is what
+// requirePaneHost gates. The DIRECT path is preferred whenever it exists and the
+// pane path stays as the compat fallback, so both add-in generations work.
+//
+// `--to <presId>` stops being a REQUIREMENT — the searchId is server-owned
+// rather than bound to a window, so nothing has to be targeted — but it is still
+// honoured, and naming a window means "relay through THAT pane". That is the
+// escape hatch for the two things the pane-free routes refuse (`asset_needs_host`
+// for SharePoint-hosted bytes, `recolor_needs_host` for an icon tint), both of
+// which the pane can do; ignoring --to made their own remediation unreachable.
+// `brandId` is the deck's bound design — the only thing that routes an engine op
+// in a multi-environment session when no window is involved.
+// No connected environment holds a server-owned search record. Authored once
+// because every consumer of an opaque searchId reaches the same dead end and
+// the same way out — the record's own environment is the only thing that can
+// serve it, so a re-search is the fix regardless of who asked.
+export function expiredSearchMessage(searchId) {
+  return (
+    `search ${searchId} was not found on any connected environment — server-side ` +
+    "search records expire after ~2 hours. Re-run 'slidemind search' and pick again."
+  );
+}
+
+export async function resolveEngineRouting(client, { to = null, brandId = null, pick = "one", searchId = null } = {}) {
+  // An opaque (server-minted) searchId pins the route by itself: the record
+  // lives on the environment that minted it, and the pane relay can never
+  // serve it — its handler only knows its own per-window numeric ids. So the
+  // record's origin outranks the deck's design AND --to, and when no connected
+  // environment holds the record the only honest answer is "search again",
+  // not a pane fallback that is guaranteed to 4xx.
+  if (client.isOpaqueSearchId?.(searchId)) {
+    if (to) {
+      // Agents thread `--to` from a window-bound habit; on a server-held
+      // record it is meaningless, not wrong — say so once and carry on.
+      process.stderr.write(
+        `  note: --to ${to} ignored — searchId ${searchId} is held by the add-in, not by a window.\n`,
+      );
+    }
+    let origin = null;
+    try {
+      origin = await client.resolveSearchBackend(searchId);
+    } catch (err) {
+      // The probe distinguishes "no environment holds this record" from the
+      // failures that only LOOK like it — a dead session, a missing sign-in —
+      // and hands the latter back for their own remediation.
+      await failOnEngineBlocker(client, err, { to });
+    }
+    if (origin) {
+      return { direct: true, backendURL: origin, presId: null, registry: null, entry: null };
+    }
+    fail(expiredSearchMessage(searchId));
+  }
+  let backendURL = null;
+  if (!to) {
+    backendURL = await client.resolveEngineBackend({ brandId });
+  }
+  if (backendURL) {
+    return { direct: true, backendURL, presId: null, registry: null, entry: null };
+  }
+  const registry = await client.requirePaneHost();
+  const entry =
+    pick === "any"
+      ? client.pickAnyPresentationEntry(registry, to)
+      : client.pickPresentationEntry(registry, to);
+  return {
+    direct: false,
+    backendURL: entry.backendURL ?? null,
+    presId: entry.presId,
+    registry,
+    entry,
+  };
+}
+
+// The design a deck is bound to (presFP == brandId), or null when it isn't bound
+// / isn't a deck. Routing state only — never printed.
+export async function deckBrandId(deckDir) {
+  if (!deckDir) return null;
+  const bundleMod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  return bundleMod.readDeckBundleRef(deckDir)?.presFP ?? null;
+}
+
+// A pane-ready window, or null — never a throw, and never a wait. Used by the
+// login_required paths below, where an open pane is an OPTION rather than a
+// precondition. `to` is honoured only when it names a window that is actually
+// registered; a stale --to must not cost the caller its fallback.
+export async function openPaneEntry(client, to = null) {
+  const registry = (await client.paneReadyPresentations?.()) ?? [];
+  if (registry.length === 0) return null;
+  const explicit = registry.some((p) => p.presId === to) ? to : null;
+  try {
+    return { registry, entry: client.pickAnyPresentationEntry(registry, explicit) };
+  } catch {
+    // Several windows and no way to choose — no automatic fallback from here.
+    return null;
+  }
+}
+
+// The ONE rendering of a corpus-identity refusal: the pane-free routes run as
+// the USER and answer `login_required` without the delegated tokens `slidemind
+// login` mints (the CLI attempts that sign-in itself before ever sending a
+// token-less request, so reaching this means the browser step was refused or
+// abandoned). The refusal backs the PANE-FREE path only: an open task pane
+// signs every request with a live browser token, so when a pane-ready window
+// is already open, that window can serve a fresh search right now — say so.
+// Returns the message, or null for any other failure.
+export async function loginRequiredMessage(client, err, { to = null } = {}) {
+  const blocker = client.loginRequiredBlocker?.(err);
+  if (!blocker) return null;
+  const pane = await openPaneEntry(client, to);
+  if (!pane) return blocker.message;
+  const env = envTag(pane.entry.env);
+  return (
+    `${blocker.message} A slidemind pane is already open${env} and signs each request live, so a fresh ` +
+    `search through that window works now: slidemind search "<query>" --to ${pane.entry.presId}.`
+  );
+}
+
+// Engine-route failures the USER has to clear get one actionable line instead of
+// a relay error. `login_required` means the corpus routes want the user's own
+// Microsoft 365 sign-in. Only corpus search stops; render and bundle don't.
+// Anything else is re-thrown for the top-level handler.
+export async function failOnEngineBlocker(client, err, { to = null } = {}) {
+  const message = await loginRequiredMessage(client, err, { to });
+  if (message) fail(message);
+  throw err;
+}
+
+// A login_required refusal that an OPEN PANE can simply route around. Only an
+// operation that can be replayed pane-side qualifies — creating a NEW search,
+// whose id the pane mints itself. A record-bound op on an opaque searchId
+// cannot: the pane's handler only understands its own per-window numeric ids,
+// so those get loginRequiredMessage's extended blocker instead. Returns
+// { registry, entry } or null.
+export async function paneRelayForLoginRequired(client, err, { to = null } = {}) {
+  if (!client.loginRequiredBlocker?.(err)) return null;
+  return openPaneEntry(client, to);
+}
+
+// The pane-free routes refuse exactly one thing outright: bytes that live in
+// SharePoint (`asset_needs_host`, which needs a delegated token only a browser
+// can mint). An open pane has one, so the remediation is the RELAY — name it,
+// rather than echoing a 409 whose "retry" would take the identical route.
+// (Icon tints are baked locally — the CLI never asks the pane-free route for
+// one.) Returns null for anything else.
+export function describeHostOnlyEngineFailure(err) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code !== "asset_needs_host") return null;
+  const detail =
+    typeof err?.body?.error === "string" ? err.body.error : (err?.message ?? "");
+  return (
+    `${detail} Run 'slidemind search "<query>" --to <presId>' against an open window and ` +
+    "re-pick, then repeat this download with the same --to — that relays it through the pane."
+  );
+}
+
+// The other half of the same boundary: a SharePoint-backed SLIDE. The extract
+// route fetches it with the caller's identity, so without a delegated token the
+// add-in falls back to a managed identity that is not configured for the corpus
+// site and the fetch dies inside the provider. That route answers a plain 400
+// with no discrete code, so the provider text is the only signal there is.
+export function isSharePointProviderFailure(err) {
+  const text = `${err?.body?.error ?? ""} ${err?.message ?? ""}`;
+  return /sharepoint provider/i.test(text);
+}
+
+// `slidemind login` as the WINDOW-FREE way past both — named only on a backend
+// that honours the delegated token and only while no sign-in is stored, so the
+// sentence never appears where following it would change nothing. Null
+// otherwise, which keeps every pre-existing message byte-identical.
+export async function graphLoginRemediation(client, backendURL) {
+  if (!backendURL) return null;
+  try {
+    if (!(await client.backendSupportsGraphDelegated?.(backendURL))) return null;
+    const graph = await loadBridgeModule("graph-auth");
+    if (graph.hasGraphSession(backendURL)) return null;
+  } catch {
+    // A capability probe that fails is not a reason to withhold the download's
+    // real error — just say nothing extra.
+    return null;
+  }
+  return (
+    "Or run 'slidemind login' once: it signs this CLI in to Microsoft 365 with your own " +
+    "identity, and SharePoint-backed content then downloads with no window at all."
+  );
+}
+
+// The user-facing text for an engine byte fetch that failed for want of an
+// identity — either refusal shape. Returns null when the failure is something
+// else entirely (the caller keeps its own message).
+export async function describeEngineByteFailure(client, err, { backendURL = null } = {}) {
+  const paneAdvice = describeHostOnlyEngineFailure(err);
+  if (!paneAdvice && !isSharePointProviderFailure(err)) return null;
+  const login = await graphLoginRemediation(client, backendURL);
+  if (!login) return paneAdvice;
+  return paneAdvice ? `${paneAdvice} ${login}` : `${err.message} ${login}`;
+}
+
+// A searchId is a number when the pane minted it (the relay path) and an opaque
+// server-minted id on the pane-free engine routes, where the search record lives
+// on the backend. Accept both so a pick round-trips whichever search produced it.
+export function parseSearchIdArg(raw, flag = "--search") {
+  if (!raw || raw.startsWith("-")) fail(`${flag} expects a searchId, got '${raw}'`);
+  return /^\d+$/.test(raw) ? parseInt(raw, 10) : raw;
+}
+
+export function parsePicks(raw, flag = "--pick") {
+  if (!raw) fail(`${flag} expects a comma-separated list of selection numbers`);
+  // Tolerate a trailing/empty segment ("1," or "1,,2") by dropping blank parts
+  // rather than turning them into NaN that fails the whole call; dedupe so the
+  // same selection isn't extracted twice.
+  const segments = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    fail(`${flag} expects a comma-separated list of selection numbers`);
+  }
+  const picks = [...new Set(segments.map((s) => parseInt(s, 10)))];
+  if (picks.some((n) => !Number.isFinite(n) || n <= 0)) {
+    fail(`${flag} expects positive selection numbers, got '${raw}'`);
+  }
+  return picks;
+}
+
+/**
+ * Turn a live-insert failure into the action that actually fixes it. The client
+ * has already re-listed the registry and retried ONCE against the live window
+ * (a pane reconnect churns the presId), so a pane error that reaches here is one
+ * only the user can clear — and the way around it is the window-free fold.
+ *
+ * A login_required refusal is NOT among them: it is authored once, in
+ * loginRequiredMessage, which the caller consults first.
+ */
+
+export function describeInsertSlideFailure(err, searchId) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  if (code === "unknown_search") {
+    return `searchId ${searchId} is no longer available. Run 'slidemind search' again, then re-pick.`;
+  }
+  if (code === "searchId_required") {
+    // The pane was handed an id it cannot resolve — its search context is
+    // per-window and numeric, and a server-minted id was never in it.
+    return (
+      `searchId ${searchId} belongs to the add-in, not to that PowerPoint window. ` +
+      `Re-run 'slidemind search' (the CLI picks the reuse route from where the search ran), then re-pick.`
+    );
+  }
+  const paneAsleep =
+    code === "pane_suspended" ||
+    code === "pane_timeout" ||
+    // A relay 404 about the presId itself carries prose and no machine code,
+    // and bridgeFetch falls `code` back to that prose — so read the PARSED one.
+    (err?.status === 404 &&
+      (!err?.body?.code || err.body.code === "unknown_presentation"));
+  if (paneAsleep) {
+    return (
+      "the slidemind task pane in that PowerPoint window is not responding (already retried once). " +
+      "Foreground PowerPoint and click the slidemind pane to wake it, then re-run — or reuse the same " +
+      `result with no window at all: slidemind add-slide --search ${searchId} --pick <n> --deck <deck>.`
+    );
+  }
+  return `insert-slide failed: ${err?.message ?? "unknown error"}`;
+}
+
+// One line per written slide, plus the machine-readable twin. The searchId is
+// echoed on purpose: an agent interrupted between picks can resume from the JSON
+// without re-running the search (the record lives on the backend now).
+export function writeAddSlideResult({ asJson, searchId, deckDir, deck, written, slides }) {
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          searchId,
+          deck: path.relative(process.cwd(), deckDir),
+          slides,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `Added ${written.length} reused slide(s) to ${path.relative(process.cwd(), deckDir)}:\n` +
+      written.map((w) => `  ${w}`).join("\n") +
+      `\nThey are native .pptx in slides/ — re-run 'slidemind build-pptx ${deck}' or 'slidemind push ${deck}' to render the deck with them spliced in.\n`,
+  );
+}
+
+// Map a `--icon-color` value onto the `--pick` list. Accepts either one colour
+// (applied to every pick) or exactly one per pick (positional); an empty
+// segment means "no colour for this pick". Returns an array aligned to picks.
+export function parseIconColors(raw, pickCount) {
+  if (!raw) return new Array(pickCount).fill(null);
+  const colors = raw
+    .split(",")
+    .map((s) => s.trim())
+    .map((s) => (s.length ? s : null));
+  for (const c of colors) {
+    if (c !== null && !/^#[0-9a-fA-F]{3,8}$/.test(c)) {
+      fail(`--icon-color expects hex colours like #0A7E8C, got '${c}'`);
+    }
+  }
+  if (colors.length === 1) return new Array(pickCount).fill(colors[0]);
+  if (colors.length !== pickCount) {
+    fail(
+      `--icon-color takes one colour (applied to all) or exactly ${pickCount} (one per --pick); got ${colors.length}`,
+    );
+  }
+  return colors;
+}
+
+export function describeReadSourceFailure(err, searchId, pick) {
+  const code = err?.code ?? err?.body?.code ?? null;
+  switch (code) {
+    case "unknown_search":
+      return `searchId ${searchId} is no longer available on that window. Run 'slidemind search' again, then re-pick.`;
+    case "wrong_result_type":
+      return `result ${pick} has no source presentation — only slide search results come from a deck (image and collection results do not).`;
+    case "access_denied":
+      return "you do not have access to that result's source presentation.";
+    case "no_indexed_content":
+      return "that presentation has no indexed slides yet. It may still be syncing — try again later.";
+    case "invalid_source":
+      return `result ${pick} carries no source file reference. Re-run the search, or pick a different result.`;
+    case "source_presentation_unsupported":
+      return err.message;
+    default:
+      return `read-source failed: ${err?.message ?? "unknown error"}`;
+  }
+}