slidemind 0.3.13 → 0.3.14

package/src/cli/search.mjs

@@ -0,0 +1,608 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { envTag, isMultiEnv } from "../bridge/config.mjs";
+import { fail, resolveDeckArg, SRC_DIR } from "./common.mjs";
+import { readDesignName, readThemeColors, designRows } from "./designs.mjs";
+import { searchFailureHint, writeEmptySearchDiagnostic, writeSearchGrid, resolveEngineRouting, deckBrandId, failOnEngineBlocker, paneRelayForLoginRequired } from "./engine-helpers.mjs";
+
+export async function cmdSearch(rest) {
+  let asJson = false;
+  let to = null;
+  let deck = null;
+  let engineId = null;
+  let resultType = null;
+  let intent = null;
+  let top = null;
+  const queryParts = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--json") {
+      asJson = true;
+    } else if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
+    } else if (a === "--engine" || a === "-e" || a === "--engineId") {
+      engineId = rest[++i];
+      if (!engineId) fail("--engine expects an engineId");
+    } else if (a === "--result-type" || a === "--resultType") {
+      resultType = rest[++i];
+      if (!resultType) fail("--result-type expects slide|image");
+      if (!["slide", "image"].includes(resultType)) {
+        fail(`--result-type expects slide|image, got '${resultType}'`);
+      }
+    } else if (a === "--intent") {
+      intent = rest[++i];
+      if (!intent) fail("--intent expects auto|content|visual");
+      if (!["auto", "content", "visual"].includes(intent)) {
+        fail(`--intent expects auto|content|visual, got '${intent}'`);
+      }
+    } else if (a === "--top") {
+      const next = rest[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n <= 0) {
+        fail(`--top expects a positive integer, got '${next}'`);
+      }
+      top = n;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      queryParts.push(a);
+    }
+  }
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    fail(
+      `usage: slidemind search "<query>" [--engine <id|scope:all|scope:sharepoint>] [--result-type slide|image] [--intent auto|content|visual] [--top <N>] [--deck <deck>] [--to <presId>] [--json]`,
+    );
+  }
+
+  // Engine search runs against the add-in's live engine over the bridge —
+  // pane-free where the add-in serves the direct routes, relayed through an open
+  // window (host required) where it doesn't.
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  const { resolveAssetExt } = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "engine-download.mjs")).href
+  );
+  // The engine catalog is per-user, not window-bound. On the pane path search
+  // attaches to any connected window (preferring a live one) and the chosen
+  // window is printed below, because the searchId lives on that pane; on the
+  // direct path the searchId is the backend's and no window is involved.
+  const routing = await resolveEngineRouting(client, {
+    to,
+    brandId: await deckBrandId(deck ? resolveDeckArg(deck) : null),
+    pick: "any",
+  });
+  const presId = routing.presId;
+  const backendURL = routing.backendURL;
+  // Mutable, because a login_required refusal can push a direct search onto
+  // the pane relay below — and once it does, the searchId belongs to a WINDOW
+  // and every next-step hint has to name it.
+  let direct = routing.direct;
+  let registry = routing.registry;
+  let entry = routing.entry;
+
+  // An explicit content/visual intent means "search slides", not imagery.
+  const slideIntent = intent === "content" || intent === "visual";
+  // Thread the engine subtype on the wire only when the CLI actually KNOWS it:
+  // `--intent content` is slide-only by contract (image engines are
+  // visual-only), the pickImageEngine default branch is an image engine by
+  // construction, and a scope search names its index below. `--intent visual`
+  // asserts NOTHING — it is a valid intent for image AND slide engines, and
+  // asserting "slide" from it made the backend record an icon-engine search
+  // as slide results (the footer then taught add-slide instead of
+  // download-result). Omitted subtype → the backend derives it from what the
+  // results actually are.
+  let subtype = intent === "content" ? "slide" : null;
+  // `--engine Icons` — a display name straight off `ls engines` — would reach
+  // the backend verbatim and 404 as "Engine not found". Humans type names,
+  // agents paste ids; when the value cannot be an id (spaces, non-hex), look it
+  // up in the live catalog by label. Best-effort on purpose: no unique match
+  // passes the value through so the existing unknown-engine hint still fires.
+  if (
+    engineId &&
+    !bundle.isSearchScopeId(engineId) &&
+    !/^[0-9a-f-]{8,}$/i.test(engineId)
+  ) {
+    const live = await client.listEngines({ backendURL }).catch(() => null);
+    const wanted = engineId.toLowerCase();
+    const ids = new Set(
+      (live?.engines ?? [])
+        .filter((e) => String(e.label ?? "").toLowerCase() === wanted)
+        .map((e) => e.id),
+    );
+    if (ids.size === 1) {
+      const [id] = ids;
+      process.stderr.write(`engine '${engineId}' resolved to ${id}\n`);
+      engineId = id;
+    } else if (ids.size > 1) {
+      fail(
+        `--engine '${engineId}' names ${ids.size} different engines across your connected environments — pass the id from 'slidemind ls engines', or scope with --backend.`,
+      );
+    }
+  }
+  if (!engineId) {
+    if (slideIntent) {
+      // Slide search with no engine named: search the corpus UNFILTERED rather
+      // than refusing. An engine is a saved folder filter over the add-in's
+      // shared corpus, so a workspace can hold a full corpus and zero slide
+      // engines — demanding --engine here dead-ended exactly that case.
+      engineId = bundle.SCOPE_ALL;
+      resultType = resultType ?? "slide";
+    } else {
+      // Imagery: resolve a real image engine (a scope is not a brand image
+      // source). Ask the LIVE catalog first — the same one the add-in's own
+      // design agent reads — and fall back to the materialized bundle only when
+      // the host can't answer. Bundle-first would be stale: engine ids can be
+      // retired server-side, and a dead id surfaces as "Engine not found".
+      const live = await client
+        .listEngines({ subtype: "image", backendURL })
+        .catch(() => ({ engines: [] }));
+      let pick = bundle.pickImageEngine(live.engines);
+      if (!pick) {
+        // Best-effort: a bundle that can't be materialized (e.g. an incomplete
+        // one) must not replace the actionable "wire an image engine" message
+        // below with a bundle error — the live catalog is the real answer here.
+        // Pane path: fetch by the window's presId. Direct path: there is no
+        // window, so only a bound deck (--deck) can name the design; without one
+        // there is nothing to fall back to and the live catalog's answer stands.
+        const brandId = presId
+          ? null
+          : await deckBrandId(deck ? resolveDeckArg(deck) : null);
+        const mat =
+          presId || brandId
+            ? await bundle
+                .materializeBundle(presId, { backendURL, brandId })
+                .catch(() => null)
+            : null;
+        if (mat) pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
+      }
+      if (!pick) {
+        fail(
+          "This corporate design has no image engines to search. Run 'slidemind ls engines' to see what exists, or ask the add-in owner to wire an image/icon engine.",
+        );
+      }
+      engineId = pick.id;
+      subtype = "image";
+    }
+  }
+
+  // A scope has no subtype of its own, so the index must be named explicitly —
+  // the add-in rejects a scope search without it. Default to slides: reusing an
+  // existing slide is what an unfiltered corpus search is overwhelmingly for.
+  if (bundle.isSearchScopeId(engineId)) {
+    resultType = resultType ?? "slide";
+    subtype = resultType;
+  } else if (resultType) {
+    // Harmless but meaningless on an engine, whose own subtype is authoritative.
+    process.stderr.write(
+      `note: --result-type is ignored for engine '${engineId}' (it applies to scope:* targets); the engine's own type decides.\n`,
+    );
+    resultType = null;
+  }
+
+  // Direct: one pane-free call against the backend that owns the searchId.
+  // Pane: window-agnostic — tries the picked pane, then fails over to any other
+  // live window on the same backend if it's suspended/frozen. The answering
+  // window (res.presId) is what reuse must target there, since the searchId is
+  // bound to it.
+  const relaySearch = (reg) =>
+    client.engineSearchAnyPane({
+      registry: reg,
+      explicitPresId: to,
+      engineId,
+      query,
+      subtype,
+      resultType,
+      intent: intent ?? null,
+      top: top ?? null,
+    });
+  let res;
+  try {
+    res = direct
+      ? await client.engineSearch({
+          engineId,
+          query,
+          subtype,
+          resultType,
+          intent: intent ?? null,
+          top: top ?? null,
+          backendURL,
+        })
+      : await relaySearch(routing.registry);
+  } catch (err) {
+    // login_required stops the PANE-FREE path only — an open pane signs each
+    // request with the browser's live token. Creating a new search is exactly
+    // the operation the pane can replay (it mints its own searchId), so relay
+    // it rather than parking the search on a sign-in the user hasn't finished.
+    const relay = direct ? await paneRelayForLoginRequired(client, err, { to }) : null;
+    if (!relay) await failOnEngineBlocker(client, err, { to });
+    process.stderr.write(
+      `note: this CLI is not signed in to Microsoft 365, so the search ran through the open ` +
+        `slidemind pane${envTag(relay.entry.env)} instead (it signs each request live).\n`,
+    );
+    direct = false;
+    registry = relay.registry;
+    entry = relay.entry;
+    try {
+      res = await relaySearch(registry);
+    } catch (relayErr) {
+      await failOnEngineBlocker(client, relayErr, { to });
+    }
+  }
+  const ranPresId = res?.presId ?? entry?.presId ?? presId;
+  const ranEntry = direct
+    ? { env: res?.env ?? null }
+    : (registry.find((p) => p.presId === ranPresId) ?? entry);
+  if (asJson) {
+    // The searchId rides the JSON so an interrupted agent can resume its picks
+    // without re-searching. The backendURL never does — env label only.
+    const { backendURL: _routingOnly, ...pub } = res ?? {};
+    process.stdout.write(`${JSON.stringify(pub, null, 2)}\n`);
+    return;
+  }
+  if (!res?.ok) {
+    process.stderr.write(`search failed: ${searchFailureHint(res?.error, engineId)}\n`);
+    return;
+  }
+  // Prefer the new `results` array (image + slide engines); fall back to the
+  // legacy `thumbnails` shape older add-ins still return for image engines.
+  const results = Array.isArray(res.results)
+    ? res.results
+    : (res.thumbnails ?? []).map((t, i) => ({ selection: i + 1, title: t.title }));
+  const count = res.resultCount ?? results.length;
+  const targetLabel = bundle.isSearchScopeId(engineId)
+    ? `scope ${engineId}`
+    : `engine ${engineId}`;
+  process.stdout.write(
+    `searchId ${res.searchId} — ${count} result(s) from ${targetLabel}` +
+      (res.intent ? ` (${res.intent})` : "") +
+      `\n`,
+  );
+  if (count === 0) {
+    writeEmptySearchDiagnostic(engineId, bundle);
+    return;
+  }
+  const isContent = res.intent === "content";
+  // A SharePoint-indexed result carries the source file's browser link. Print
+  // it under the title so the user can open the original presentation — the
+  // add-in only stamps it where the index has one, so its absence is normal.
+  const writeSourceLink = (r) => {
+    if (typeof r.sourceUrl === "string" && r.sourceUrl) {
+      process.stdout.write(`     source: ${r.sourceUrl}\n`);
+    }
+  };
+  results.forEach((r, i) => {
+    const sel = r.selection ?? i + 1;
+    if (isContent) {
+      // Content results: per-result header + the bare extracted text block.
+      const score = typeof r.score === "number" ? ` · ${r.score.toFixed(3)}` : "";
+      process.stdout.write(`  ${sel}. ${r.title ?? "(untitled)"}${score}\n`);
+      writeSourceLink(r);
+      if (r.text) {
+        for (const line of String(r.text).split("\n")) {
+          process.stdout.write(`     ${line}\n`);
+        }
+      }
+    } else {
+      // Visual / image results: the numbered list. An image result carries its
+      // intrinsic size from the engine index — show it, so the box can be sized
+      // to the real aspect ratio at authoring time rather than after the fetch.
+      const dims =
+        r.kind === "image" && Number.isFinite(r.width) && Number.isFinite(r.height)
+          ? `  ${r.width}×${r.height}`
+          : "";
+      process.stdout.write(`  ${sel}. ${r.title ?? "(untitled)"}${dims}\n`);
+      writeSourceLink(r);
+    }
+  });
+  // Tailor the next-step hint to the result kind: slide verbs (insert-slide /
+  // add-slide) for slide results, the image-download hint otherwise. The
+  // per-result `kind`s are authoritative — the top-level subtype echo has been
+  // observed WRONG on live backends (icon-engine searches echoing
+  // subtype:"slide" over kind:"image" results, which pointed agents at
+  // add-slide instead of download-result) — with the subtype as the fallback
+  // for add-ins that don't stamp per-result kinds.
+  const resultKinds = results.map((r) => r.kind).filter(Boolean);
+  const isSlideResults = resultKinds.length
+    ? resultKinds.some((k) => k === "slide")
+    : res.subtype === "slide";
+  // Visual results: point at the ONE collage rather than making the caller pull
+  // each preview separately. The numbers burned into it match the list above.
+  if (!isContent) {
+    const gridPath = writeSearchGrid(res.gridDataUri, res.searchId, resolveAssetExt);
+    if (gridPath) {
+      process.stdout.write(
+        `Contact sheet of all ${count} result(s) — LOOK AT THIS FILE to choose, ` +
+          `don't fetch previews one by one: ${gridPath}\n`,
+      );
+    } else if (direct && isSlideResults) {
+      // The pane composes the collage in a DOM; the pane-free route may not
+      // have one to hand back (`gridUnavailable`, or simply no grid field on an
+      // add-in that hasn't grown it yet). Say where previews come from instead
+      // — otherwise an agent that has learned to expect a contact sheet quietly
+      // issues N thumbnail fetches to rebuild it.
+      process.stdout.write(
+        `No contact sheet on this path — preview candidates one at a time instead: ` +
+          `slidemind view-slide --search ${res.searchId} --pick <n>\n`,
+      );
+    } else if (direct) {
+      // Image/icon results carry NO preview on the pane-free path (view-slide
+      // answers "no image returned" for them). The download IS the preview:
+      // fetch the pick, look at the saved file, re-search once if wrong.
+      process.stdout.write(
+        `No preview for image results on this path — download the pick(s) and look at the saved file(s) ` +
+          `(cheap; re-search once if wrong; two misses = mark it (no result)).\n`,
+      );
+    }
+  }
+  const envLabel = envTag(ranEntry?.env);
+  if (direct) {
+    // The searchId belongs to the BACKEND here, not to a window: picks work with
+    // PowerPoint closed, so the follow-up commands carry no --to. Live insert is
+    // the one step that still names a window (it types into an open deck).
+    if (isSlideResults) {
+      process.stdout.write(
+        `searchId ${res.searchId}${envLabel} is held by the add-in — reuse it with no PowerPoint window:\n` +
+          `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck>\n` +
+          `  slidemind insert-slide --search ${res.searchId} --pick <n> --to <presId>   (live insert needs an open window)\n`,
+      );
+    } else {
+      process.stdout.write(
+        `searchId ${res.searchId}${envLabel} is held by the add-in — download image result(s) into a deck (no window needed):\n` +
+          `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck>\n`,
+      );
+    }
+  } else if (isSlideResults) {
+    // The searchId is bound to the window the search ran on — reuse must target
+    // that same window, so spell out its presId in the next-step commands.
+    process.stdout.write(
+      `searchId ${res.searchId} ran on window ${ranPresId}${envLabel} — reuse from THIS window:\n` +
+        `  slidemind insert-slide --search ${res.searchId} --pick <n> --to ${ranPresId}\n` +
+        `  slidemind add-slide --search ${res.searchId} --pick <n> --deck <deck> --to ${ranPresId}\n`,
+    );
+  } else {
+    // The searchId is bound to the window the search ran on — download must
+    // target that same window, so spell out its presId in the next-step command.
+    process.stdout.write(
+      `searchId ${res.searchId} ran on window ${ranPresId}${envLabel} — download image result(s) into a deck:\n` +
+        `  slidemind download-result --search ${res.searchId} --pick <n[,n,...]> --deck <deck> --to ${ranPresId}\n`,
+    );
+  }
+}
+
+// Every corporate design this machine can materialize a bundle for: the ones
+// already cached here, plus the ones the connected backends list. This is the
+// discovery half of bundle management — without it the only way to learn a
+// presFP was to run `ready` and read its menu (or its ambiguous blocker), which
+// also resolves and binds. Listing is read-only: no design is picked, no bundle
+// is fetched, no deck is touched. Pair it with `download-bundle --brand <fp>`.
+export async function cmdLsDesigns(rest) {
+  let asJson = false;
+  for (const a of rest) {
+    if (a === "--json") asJson = true;
+    else if (a.startsWith("-")) fail(`unknown flag: ${a}`);
+    else fail(`unexpected argument: ${a}`);
+  }
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  const rows = new Map();
+  for (const b of bundle.listCachedBundles()) {
+    rows.set(b.presFP, {
+      presFP: b.presFP,
+      name: readDesignName(b.dir),
+      colors: readThemeColors(b.dir),
+      cached: true,
+      etag: b.meta?.etag ?? null,
+      dir: b.dir,
+      envs: [],
+    });
+  }
+  // The backend list is a bonus, never a precondition: an unreachable or older
+  // add-in (no brandsList capability) still leaves every cached design listed.
+  let listed = [];
+  try {
+    const client = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+    );
+    client.setDiagnosticMode(true);
+    listed = await client.listBrands();
+  } catch {
+    listed = [];
+  }
+  for (const b of listed) {
+    if (!rows.has(b.presFP)) {
+      rows.set(b.presFP, {
+        presFP: b.presFP,
+        name: b.name ?? null,
+        colors: null,
+        cached: false,
+        etag: null,
+        dir: null,
+        envs: [],
+      });
+    }
+    const row = rows.get(b.presFP);
+    row.name ??= b.name ?? null;
+    if (b.env && !row.envs.includes(b.env)) row.envs.push(b.env);
+  }
+  const designs = [...rows.values()];
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(designs, null, 2)}\n`);
+    return;
+  }
+  if (designs.length === 0) {
+    process.stderr.write(
+      "No corporate design is cached here and no connected add-in lists one. " +
+        "Run `slidemind ready` with PowerPoint open to materialize the active design.\n",
+    );
+    return;
+  }
+  process.stdout.write(`${designRows(designs).join("\n")}\n`);
+  process.stdout.write(
+    "Materialize or refresh one with: slidemind download-bundle --brand <presFP>\n" +
+      "Refresh every cached design with: slidemind download-bundle --all\n",
+  );
+}
+
+export async function cmdLs(rest) {
+  const [sub, ...subRest] = rest;
+  if (sub === "designs" || sub === "brands") {
+    await cmdLsDesigns(subRest);
+    return;
+  }
+  if (sub !== "engines") {
+    fail(
+      "usage: slidemind ls engines [--type collection|search|scope] [--subtype image|slide|template|content] [--json]\n" +
+        "       slidemind ls designs [--json]",
+    );
+  }
+  let type = null;
+  let subtype = null;
+  let to = null;
+  let all = false;
+  let asJson = false;
+  for (let i = 0; i < subRest.length; i++) {
+    const a = subRest[i];
+    if (a === "--type") {
+      type = subRest[++i];
+      if (!type) fail("--type expects collection|search|scope");
+      // "scope" narrows to the non-engine targets (scope:all / scope:sharepoint).
+      if (!["collection", "search", "scope"].includes(type)) {
+        fail(`--type expects collection|search|scope, got '${type}'`);
+      }
+    } else if (a === "--subtype") {
+      subtype = subRest[++i];
+      if (!subtype) fail("--subtype expects image|slide|template|content");
+      if (!["image", "slide", "template", "content"].includes(subtype)) {
+        fail(`--subtype expects image|slide|template|content, got '${subtype}'`);
+      }
+    } else if (a === "--to") {
+      to = subRest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--all") {
+      all = true;
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  if (all && to) fail("--all cannot be combined with --to");
+  let backendURL = null;
+  if (!all) {
+    // Pane-free where the add-in serves the direct routes; otherwise the catalog
+    // is relayed through a window, so a live pane is still the precondition.
+    try {
+      backendURL = (await resolveEngineRouting(client, { to, pick: "any" }))
+        .backendURL;
+    } catch (err) {
+      // Listing is the one engine op that can simply show EVERY environment
+      // (each engine is tagged with its env), so an ambiguous multi-environment
+      // session fans out here rather than demanding --backend.
+      if (err?.code !== "engine_backend_ambiguous") throw err;
+      backendURL = null;
+    }
+  }
+  let engines;
+  // The pane-free route's summary of the catalog BEFORE the type/subtype
+  // filter; null on older add-ins and on the pane-relay path.
+  let catalog = null;
+  // Which environments answered. The catalog is POOLED, and pooling dedupes the
+  // scopes every environment repeats — so a second environment can contribute
+  // no row of its own, and the surviving rows can no longer be counted to learn
+  // whether more than one answered.
+  let envs = [];
+  let failures = [];
+  try {
+    ({ engines, catalog, envs = [], failures = [] } = await client.listEngines({
+      type,
+      subtype,
+      backendURL,
+    }));
+  } catch (err) {
+    // No pane fallback here: `GET /api/cli/engines` is the catalog route on both
+    // add-in generations (newer ones answer it directly, older ones relay it
+    // themselves), so there is no second route to retry on. The message does
+    // name the open pane, because searching THROUGH it still works.
+    await failOnEngineBlocker(client, err, { to });
+  }
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify({ engines, catalog, envs, failures }, null, 2)}\n`);
+    return;
+  }
+  // A fanned-out listing never opens the browser sign-in for an environment
+  // nobody asked about; an environment that refused for that reason is named
+  // here instead of silently missing from the pooled catalog.
+  for (const f of failures ?? []) {
+    process.stderr.write(`  note: ${f.env} did not answer — ${f.message}\n`);
+  }
+  if (engines.length === 0) {
+    // A filter that matched nothing is NOT an empty deployment — the summary is
+    // the only thing that tells the two apart, so say which one this is and the
+    // next move follows (drop the filter vs. search the corpus unfiltered).
+    const unfiltered = catalog ? catalog.totalEngines + catalog.totalScopes : 0;
+    if (catalog?.filtered && unfiltered > 0) {
+      process.stderr.write(
+        `No engine or scope matched this filter, but ${catalog.totalEngines} engine(s) ` +
+          `and ${catalog.totalScopes} scope(s) exist. Re-run 'slidemind ls engines' ` +
+          "without --type/--subtype to see them.\n",
+      );
+      return;
+    }
+    // Deliberately not "nothing to search": an engine is a saved folder filter
+    // over the add-in's shared corpus, so an empty catalog says only that nobody
+    // saved a filter. An older add-in that predates scopes lands here too.
+    const { SCOPE_ALL } = await import(
+      pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+    );
+    process.stderr.write(
+      "No engines or scopes matched. An engine is a saved folder filter over the corpus, " +
+        "so an empty list does NOT mean there is nothing to search — try " +
+        `'slidemind search "<query>" --engine ${SCOPE_ALL} --result-type slide' ` +
+        "to search it unfiltered.\n",
+    );
+    return;
+  }
+  // Show the env tag only when more than one environment contributed. Two
+  // environments can carry identically-named engines, and without the tag the
+  // pooled list gives no way to tell them apart. Deduped scope rows carry no env
+  // of their own (they exist on every environment), so they stay untagged.
+  const multiEnv =
+    isMultiEnv() || envs.length > 1 || new Set(engines.map((e) => e.env)).size > 1;
+  for (const e of engines) {
+    const kind = [e.type, e.subtype].filter(Boolean).join("/");
+    const env = multiEnv && e.env ? `[${e.env}] ` : "";
+    const desc = e.description ? ` — ${e.description}` : "";
+    // A scope takes --result-type instead of having a subtype of its own; spell
+    // that out so the agent doesn't have to infer it from the missing subtype.
+    const hint =
+      e.type === "scope"
+        ? ` (needs --result-type ${(e.capabilities?.resultTypes ?? ["slide", "image"]).join("|")})`
+        : "";
+    // An engine that exists but has nothing indexed yet returns zero hits for
+    // every query; say so here so an empty search isn't read as a bad engine id.
+    const state =
+      e.content?.state === "empty"
+        ? " (nothing indexed yet)"
+        : e.content?.state === "indexing"
+          ? " (indexing)"
+          : "";
+    process.stdout.write(
+      `${env}${e.id} · ${e.label ?? e.id} · ${kind}${hint}${state}${desc}\n`,
+    );
+  }
+}