slidemind 0.0.28 → 0.1.0

package/bin/slidemind.mjs

@@ -59,6 +59,9 @@ function printHelp() {
       `                                     --at <index>    insert after slide N (0-based); default = append\n` +
       `                                     --replace       delete existing slides first (destructive)\n` +
       `                                     --slides <ids>  comma-separated source slide ids to push\n` +
+      `  slidemind pair <code>            Pair with an add-in (copy the code from its "Connect CLI")\n` +
+      `  slidemind whoami                 Show the paired account\n` +
+      `  slidemind logout                 Unpair this machine\n` +
       `  slidemind init --for <t>         Set up slidemind in a harness (registers the MCP server + skill)\n` +
       `  slidemind uninstall --for <t>    Remove a previously-installed skill\n` +
       `  slidemind update [--for <t>]     Fetch the latest release and redeploy\n` +
@@ -321,6 +324,82 @@ async function cmdPresentations(rest) {
   }
 }
 
+async function loadBridgeModule(name) {
+  return import(pathToFileURL(path.join(SRC_DIR, "bridge", `${name}.mjs`)).href);
+}
+
+async function cmdPair(rest) {
+  const code = rest.find((a) => !a.startsWith("--"));
+  if (!code) {
+    fail('usage: slidemind pair <code>   (copy the command from the add-in\'s "Connect CLI")');
+  }
+  const pairMod = await loadBridgeModule("pair");
+  const decoded = pairMod.decodePairingCode(code);
+  if (!decoded) {
+    fail("invalid pairing code — copy the exact `slidemind pair …` command shown in the add-in");
+  }
+  const res = await pairMod.httpJson(
+    "POST",
+    `${decoded.backendURL}/api/cli/pair/redeem`,
+    { body: { secret: decoded.secret } },
+  );
+  if (res.status !== 200 || !res.json?.sessionToken) {
+    fail(
+      `pairing failed (${res.status}): ${res.json?.error || "no session returned"}\n` +
+        "the code may have expired — generate a fresh one in the add-in's \"Connect CLI\"",
+    );
+  }
+  const cfg = await loadBridgeModule("config");
+  cfg.writeSessionConfig({
+    backendURL: decoded.backendURL,
+    sessionToken: res.json.sessionToken,
+  });
+  process.stdout.write(
+    `Paired with ${decoded.backendURL}. Run 'slidemind presentations' to verify.\n`,
+  );
+}
+
+async function cmdWhoami() {
+  const cfg = await loadBridgeModule("config");
+  const session = cfg.readSessionConfig();
+  if (!session) {
+    process.stderr.write(
+      'Not paired. Run `slidemind pair <code>` using the add-in\'s "Connect CLI".\n',
+    );
+    return;
+  }
+  const pairMod = await loadBridgeModule("pair");
+  const res = await pairMod.httpJson("GET", `${session.backendURL}/api/cli/whoami`, {
+    token: session.sessionToken,
+  });
+  if (res.status === 200 && res.json) {
+    process.stdout.write(
+      `Paired with ${session.backendURL}\n  user:   ${res.json.oid}\n  tenant: ${res.json.tid ?? "(n/a)"}\n`,
+    );
+  } else {
+    process.stderr.write(
+      `Session invalid (${res.status}). Re-pair via the add-in's "Connect CLI".\n`,
+    );
+  }
+}
+
+async function cmdLogout() {
+  const cfg = await loadBridgeModule("config");
+  const session = cfg.readSessionConfig();
+  if (session) {
+    try {
+      const pairMod = await loadBridgeModule("pair");
+      await pairMod.httpJson("POST", `${session.backendURL}/api/cli/logout`, {
+        token: session.sessionToken,
+      });
+    } catch {
+      /* best-effort server-side revoke; we still clear the local session */
+    }
+  }
+  const cleared = cfg.clearSessionConfig();
+  process.stdout.write(cleared ? "Logged out.\n" : "Already logged out.\n");
+}
+
 async function cmdPush(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "push");
   let to = null;
@@ -572,6 +651,15 @@ async function main(argv) {
     case "new":
       await cmdNew(rest);
       return 0;
+    case "pair":
+      await cmdPair(rest);
+      break;
+    case "whoami":
+      await cmdWhoami(rest);
+      break;
+    case "logout":
+      await cmdLogout(rest);
+      break;
     case "presentations":
       await cmdPresentations(rest);
       return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.0.28",
+  "version": "0.1.0",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -13,18 +13,15 @@ This skill is **thin workflow glue for the local harness**. Everything that dete
 
 So this file owns only what is genuinely CLI-specific: the **host precondition**, a compact **intake/plan**, the **create flow**, and the **command mapping** that translates the add-in's in-app tool names (used throughout the bundle's `workflow/*.md`) into your `slidemind` commands and MCP tools. Read the workflow + brand from the bundle; never restate or duplicate them here.
 
-## Make sure the slidemind CLI is installed (npm)
+## Bootstrap (set yourself up — don't make the user do it)
 
-This skill drives the `slidemind` CLI and its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). If `slidemind` isn't on `PATH` — or those `slidemind_*` MCP tools aren't available — install the package from npm, then register it with the harness:
+This skill drives the `slidemind` CLI + its MCP server (`slidemind_list_open_presentations`, `slidemind_push_deck`, `slidemind_search_engine`, `slidemind_download_result`). The CLI reaches PowerPoint through the add-in's **cloud relay** — it doesn't run any local server. Patch what's missing yourself, but the **pairing** step needs the user once (they hold the add-in's identity):
 
-```bash
-npm install -g slidemind
-slidemind init --for <claude|codex|opencode|all>   # registers the MCP server + (re)deploys this skill
-```
+- **CLI missing** (`slidemind` not on `PATH`, or the `slidemind_*` MCP tools absent): `npm install -g slidemind`, then `slidemind init --for <claude|codex|opencode|all>` (registers the MCP server + (re)deploys this skill). The harness may need a restart for the `slidemind_*` tools to appear.
+- **Not paired** (a command says *slidemind is not paired*): this is the one step you can't do for the user. Tell them: in the slidemind add-in click **"Connect CLI"**, then paste the shown `slidemind pair …` command into this terminal. It's one-time per machine (the code carries the backend URL + a session token — no hardcoded URLs, no separate login; the add-in's own session is the auth). `slidemind whoami` confirms the pairing.
+- `npx slidemind <command>` runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update` upgrades (`--ref <version>` to pin).
 
-- For a one-off command without a global install, `npx slidemind <command>` works.
-- `slidemind --version` confirms it's on `PATH`. `slidemind update` upgrades to the latest npm release (`--ref <version>` to pin).
-- If `slidemind init` just registered the MCP server, the harness may need a restart before the `slidemind_*` tools appear.
+After pairing once: **CLI paired + the add-in open ≡ it just works**, against whatever environment (dev / prod / a client deployment) the add-in is wired to.
 
 ## Precondition gate (check this first, every time)
 
@@ -34,6 +31,8 @@ Authoring and rendering hard-require an **open PowerPoint host with the slidemin
 2. One registered → that's your target `presentation_id`. **Several → ask the user which**, by `title`/`fileName` (never raw ids) — once for **which presentation's corporate design to download**, and again at render time for **which presentation to push into** (the CD source and the push target may be different presentations).
 3. **None registered → stop.** Tell the user: *open PowerPoint, load the slidemind add-in, and pick or create a corporate design, then retry.*
 
+> **Empty list vs. not paired — different fixes.** An *empty* registry means no PowerPoint is connected (step 3 → ask the user to open it / enable Connect CLI). A *not paired* error means this machine has no session — ask the user to pair once via the add-in's **"Connect CLI"** (see Bootstrap); don't ask them to open PowerPoint for that.
+
 **Backgrounded PowerPoint is expected to work.** Do not pre-emptively ask the user to focus PowerPoint or the task pane. The bridge retains the registered presentation and pane-free routes keep working; live push/replace waits for the task-pane socket to reconnect if it truly dropped. Only if a command fails with *no host registered* (or a bridge wait timeout) do you ask the user to click the slidemind task pane once so it reconnects, then retry the same command — the deck and bundle are already prepared. Reserve the full "open PowerPoint…" instruction in (3) for when nothing is registered at all.
 
 Local HTML preview (`slidemind build`) runs offline, but it reads a **previously materialized bundle** — so the host must have been available at least once.

package/src/bridge/bundle.mjs

@@ -358,16 +358,27 @@ export function loadEnginesForDeck(deckDir) {
   return readEnginesFromDir(resolveBundleDirForDeck(deckDir));
 }
 
-// Pick the default engine to search: the first image/icon engine, else the
-// first engine. Single source of truth for the heuristic shared by the CLI
-// dispatcher (`slidemind search`) and the MCP `slidemind_search_engine` tool.
+// Image-producing engine kinds — the modality "image" plus the finer image
+// content kinds an authored bundle may carry. Excludes "slide" (a slide-search
+// engine returns whole slides, not insertable bytes). Mirrors the add-in's
+// local-bridge `engine_not_image` gate so the CLI never picks an engine the
+// bridge would reject.
+const IMAGE_ENGINE_KIND_RE = /^(image|icon|photo|illustration|vector)$/i;
+
+// True when an engine produces insertable image bytes. Gates on the engine's
+// real `kind` (its modality from the design bundle) — NOT a guess over its
+// label/description.
+export function isImageEngine(engine) {
+  return IMAGE_ENGINE_KIND_RE.test(engine?.kind ?? "");
+}
+
+// Pick the default engine to search: the first image engine, by its real
+// `kind`. Returns null when the CD exposes no image engine (e.g. only a
+// slide-search engine) — callers surface a "wire an image engine" message
+// rather than falling back to an engine the bridge can't insert. Single source
+// of truth for the heuristic shared by the CLI dispatcher (`slidemind search`)
+// and the MCP `slidemind_search_engine` tool.
 export function pickImageEngine(engines) {
   const list = Array.isArray(engines) ? engines : [];
-  return (
-    list.find((e) =>
-      /image|icon/i.test(`${e.kind ?? ""} ${e.label ?? ""} ${e.description ?? ""}`),
-    ) ||
-    list[0] ||
-    null
-  );
+  return list.find(isImageEngine) ?? null;
 }

package/src/bridge/client.mjs

@@ -1,13 +1,9 @@
-// Client for the slidemind PowerPoint add-in's local bridge.
+// Client for the slidemind cloud relay.
 //
-// The add-in's Express middle-tier (port 3001 by default) exposes a localhost-
-// only, token-gated `/local/*` surface that lets a sibling local process —
-// this CLI, the bundled MCP server, anything running on the same machine —
-// enumerate the open PowerPoint windows and push slides into a specific one.
-//
-// The shared token is generated on add-in start and written to a state file.
-// Reading it is sufficient auth; the add-in's middleware also rejects any
-// non-loopback caller, so this is intentionally a same-machine-only surface.
+// The CLI talks to `<backendURL>/api/cli/*` with a Bearer session token — both
+// established once by `slidemind pair` (see config.mjs). The add-in's cloud
+// 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";
@@ -15,9 +11,11 @@ import os from "node:os";
 import path from "node:path";
 import https from "node:https";
 
-const DEFAULT_HOST = "127.0.0.1";
-const DEFAULT_PORT = 3001;
-const TOKEN_HEADER = "x-slidemind-bridge-token";
+import { readSessionConfig } from "./config.mjs";
+
+function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+}
 
 export function bridgeStateDir() {
   if (process.platform === "win32") {
@@ -53,23 +51,26 @@ export function readBridgeToken() {
   return token;
 }
 
-function bridgeBaseUrl() {
-  const host = process.env.SLIDEMIND_BRIDGE_HOST || DEFAULT_HOST;
-  const port = parseInt(process.env.SLIDEMIND_BRIDGE_PORT || `${DEFAULT_PORT}`, 10);
-  // The add-in's dev backend uses HTTPS with self-signed certs; production
-  // (Azure Container Apps) terminates TLS upstream and exposes HTTP. Default
-  // to HTTPS but allow override.
-  const scheme = process.env.SLIDEMIND_BRIDGE_SCHEME || "https";
-  return `${scheme}://${host}:${port}`;
+// 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.",
+    );
+  }
+  return session;
 }
 
 async function bridgeFetch(pathPart, init = {}) {
-  const url = `${bridgeBaseUrl()}${pathPart}`;
-  const token = readBridgeToken();
+  const session = requireSession();
+  const url = `${session.backendURL}${pathPart}`;
   const headers = {
     accept: "application/json",
     ...init.headers,
-    [TOKEN_HEADER]: token,
+    authorization: `Bearer ${session.sessionToken}`,
   };
 
   let response;
@@ -78,12 +79,18 @@ 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 bridge unreachable at ${url}. ` +
-          `Is the slidemind PowerPoint add-in running? (npm run dev:backend in src/ui)`,
+        `slidemind relay unreachable at ${url}. Check your connection; ` +
+          "if it persists, re-pair with `slidemind pair`.",
       );
     }
     throw err;
   }
+  if (response.status === 401) {
+    throw new Error(
+      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
+        'click "Connect CLI", and run the shown `slidemind pair …`.',
+    );
+  }
   if (response.status < 200 || response.status >= 300) {
     let parsed = null;
     try {
@@ -135,7 +142,9 @@ function nodeRequest(urlString, init = {}) {
       {
         method: init.method ?? "GET",
         headers,
-        rejectUnauthorized: isHttps ? false : undefined,
+        // Validate the cloud's real cert; only skip for a loopback dev backend
+        // (self-signed) when pointing the CLI at a local add-in for development.
+        rejectUnauthorized: isHttps ? !isLoopbackHostname(url.hostname) : undefined,
       },
       (res) => {
         const chunks = [];
@@ -167,7 +176,7 @@ function nodeRequest(urlString, init = {}) {
 }
 
 export async function listOpenPresentations() {
-  const res = await bridgeFetch("/local/presentations");
+  const res = await bridgeFetch("/api/cli/presentations");
   const data = await res.json();
   return Array.isArray(data?.presentations) ? data.presentations : [];
 }
@@ -199,7 +208,7 @@ export async function requireHost() {
 export async function getDesignBundle(presId) {
   if (!presId) throw new Error("getDesignBundle: presId is required");
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/design-bundle`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
   );
   return res.json();
 }
@@ -223,7 +232,7 @@ export async function renderPptx({
   }
   if (etag) body.etag = etag;
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/render-pptx`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/render-pptx`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -241,7 +250,7 @@ export async function engineSearch({ presId, engineId, query }) {
   if (!engineId) throw new Error("engineSearch: engineId is required");
   if (!query) throw new Error("engineSearch: query is required");
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/engine/search`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/engine/search`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -270,7 +279,7 @@ export async function engineDownload({
   const body = { searchId, selection };
   if (iconColor) body.iconColor = iconColor;
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/engine/download`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/engine/download`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -291,7 +300,7 @@ export async function insertSlides({
   if (!base64) throw new Error("insertSlides: base64 is required");
   const body = { base64, insertAt, sourceSlideIds, operationId };
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/insert`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/insert`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -308,7 +317,7 @@ export async function replaceSlides({ presId, base64, operationId = null }) {
   if (!presId) throw new Error("replaceSlides: presId is required");
   if (!base64) throw new Error("replaceSlides: base64 is required");
   const res = await bridgeFetch(
-    `/local/presentations/${encodeURIComponent(presId)}/replace`,
+    `/api/cli/presentations/${encodeURIComponent(presId)}/replace`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },

package/src/bridge/config.mjs

@@ -0,0 +1,71 @@
+// CLI session config: where `slidemind pair` stores the cloud relay endpoint +
+// the opaque session token it was issued. The CLI talks to <backendURL>/api/cli/*
+// with `Authorization: Bearer <sessionToken>`; no localhost, no cert.
+//
+// Stored under XDG_CONFIG_HOME (config, not cache/state) so it persists and is
+// clearly user-scoped. 0600 — it holds a bearer credential.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function sessionConfigDir() {
+  if (process.platform === "win32") {
+    const base =
+      process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(base, "slidemind");
+  }
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "slidemind");
+}
+
+export function sessionConfigPath() {
+  return path.join(sessionConfigDir(), "session.json");
+}
+
+// Returns { backendURL, sessionToken } or null if not paired / unreadable.
+export function readSessionConfig() {
+  let raw;
+  try {
+    raw = fs.readFileSync(sessionConfigPath(), "utf8");
+  } catch {
+    return null; // ENOENT or unreadable → treat as not paired
+  }
+  try {
+    const obj = JSON.parse(raw);
+    if (
+      obj &&
+      typeof obj.backendURL === "string" &&
+      typeof obj.sessionToken === "string" &&
+      obj.backendURL &&
+      obj.sessionToken
+    ) {
+      return { backendURL: obj.backendURL, sessionToken: obj.sessionToken };
+    }
+  } catch {
+    /* malformed JSON */
+  }
+  return null;
+}
+
+export function writeSessionConfig({ backendURL, sessionToken }) {
+  if (!backendURL || !sessionToken) {
+    throw new Error("writeSessionConfig: backendURL and sessionToken are required");
+  }
+  fs.mkdirSync(sessionConfigDir(), { recursive: true });
+  fs.writeFileSync(
+    sessionConfigPath(),
+    `${JSON.stringify({ backendURL, sessionToken }, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+}
+
+// Remove the stored session. Returns true if a file was deleted.
+export function clearSessionConfig() {
+  try {
+    fs.rmSync(sessionConfigPath());
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/bridge/pair.mjs

@@ -0,0 +1,67 @@
+// Pairing + session helpers for the CLI side of the cloud relay.
+//
+// `slidemind pair <blob>` decodes {u: backendURL, s: secret} and redeems the
+// one-time secret for an opaque session token, stored by config.mjs. whoami/
+// logout call the session-gated endpoints with that token.
+
+import http from "node:http";
+import https from "node:https";
+
+function isLoopbackHostname(h) {
+  return h === "127.0.0.1" || h === "localhost" || h === "::1";
+}
+
+// Minimal JSON request. Validates the cloud's real cert; skips only for a
+// loopback dev backend (self-signed).
+export function httpJson(method, urlStr, { body = null, token = null } = {}) {
+  const url = new URL(urlStr);
+  const transport = url.protocol === "https:" ? https : http;
+  const payload = body != null ? JSON.stringify(body) : null;
+  const headers = { accept: "application/json" };
+  if (payload) {
+    headers["content-type"] = "application/json";
+    headers["content-length"] = Buffer.byteLength(payload);
+  }
+  if (token) headers.authorization = `Bearer ${token}`;
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      url,
+      {
+        method,
+        headers,
+        rejectUnauthorized:
+          url.protocol === "https:" ? !isLoopbackHostname(url.hostname) : undefined,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          let json = null;
+          try {
+            json = text ? JSON.parse(text) : null;
+          } catch {
+            /* non-JSON body */
+          }
+          resolve({ status: res.statusCode ?? 0, json, text });
+        });
+      },
+    );
+    req.on("error", reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+// Decode a `slidemind pair <blob>` code → { backendURL, secret } or null.
+export function decodePairingCode(code) {
+  try {
+    const obj = JSON.parse(Buffer.from(code, "base64url").toString("utf8"));
+    if (obj && typeof obj.u === "string" && typeof obj.s === "string") {
+      return { backendURL: obj.u, secret: obj.s };
+    }
+  } catch {
+    /* malformed */
+  }
+  return null;
+}

package/src/builders/resolve-skill.mjs

@@ -44,6 +44,26 @@ function firstExisting(candidates) {
   return null;
 }
 
+// Does a design root actually carry brand files? A root qualifies if it has the
+// corporate-design CSS or a layouts dir that holds at least one real layout
+// (a `*.jsx` or `layouts.css`). A bare/junk-only `layouts/` — e.g. one left
+// behind on disk holding only a macOS `.DS_Store` — must NOT count, or it would
+// mask the "materialize the bundle first" guidance for a deck that hasn't
+// downloaded one yet.
+function carriesDesign(root, cssName) {
+  if (!root) return false;
+  if (fs.existsSync(path.join(root, cssName))) return true;
+  const layoutsDir = path.join(root, "layouts");
+  if (!fs.existsSync(layoutsDir)) return false;
+  try {
+    return fs
+      .readdirSync(layoutsDir)
+      .some((f) => f.endsWith(".jsx") || f === "layouts.css");
+  } catch {
+    return false;
+  }
+}
+
 // First existing candidate, or `fallback` when none exist. Encodes the
 // deck-override → bundle → skill precedence in one place so every resolved path
 // shares the same lookup rule.
@@ -73,12 +93,7 @@ export function resolveSkill(skillName, planMeta = {}, opts = {}) {
   const designRoots = [
     bundleDir,
     fs.existsSync(skillDir) ? skillDir : null,
-  ].filter(
-    (r) =>
-      r &&
-      (fs.existsSync(path.join(r, cssName)) ||
-        fs.existsSync(path.join(r, "layouts"))),
-  );
+  ].filter((r) => carriesDesign(r, cssName));
   if (designRoots.length === 0) {
     throw new Error(
       `No design source for skill "${skillName}". The corporate design now lives ` +