slidemind 0.2.2 → 0.2.4

package/src/bridge/config.mjs

@@ -1,5 +1,5 @@
-// CLI session config: where `slidemind pair` stores the cloud relay endpoint(s)
-// + the opaque session token each was issued. The CLI talks to
+// CLI session config: connecting stores the cloud relay endpoint(s) + the
+// opaque session token each was issued. The CLI talks to
 // <backendURL>/api/cli/* with `Authorization: Bearer <sessionToken>`; no
 // localhost, no cert.
 //

package/src/bridge/engine-download.mjs

@@ -141,6 +141,25 @@ export function resolveAssetExt(mimeType, buf) {
   return extFromBytes(buf) ?? declared;
 }
 
+// The recolour descriptor, with a pane-free TINT REFUSAL folded in: the bytes
+// on disk are then the original ones, so `applied` has to read false and the
+// note has to name the one route that does bake a colour in.
+function describeRecolorWithRefusal(markup, mimeType, iconColor, refusedColor) {
+  const described = describeRecolor(
+    markup,
+    mimeType,
+    refusedColor ? null : (iconColor ?? null),
+  );
+  if (!refusedColor) return described;
+  return {
+    ...described,
+    note:
+      `Saved in its ORIGINAL colours — recolouring to ${refusedColor} runs in the slidemind add-in. ` +
+      "Re-run this download with --to <presId> (a PowerPoint window with the slidemind pane open) " +
+      "to bake the colour in.",
+  };
+}
+
 // Stream one result into assetsDir via the add-in's streaming route.
 //
 // Returns the same shape as `downloadOneResult`, or null when the paired add-in
@@ -156,21 +175,29 @@ async function streamOneResult({
   iconColor,
 }) {
   if (typeof client.engineDownloadToFile !== "function") return null;
+  // `presId: null` + a resolved backendURL is the pane-free route (the client
+  // picks the direct stream); a presId relays through that window's pane.
   // Write under a provisional name: the true extension is only knowable from the
   // bytes, and buffering the image just to sniff its header would defeat the
   // purpose of streaming.
   const tempPath = path.join(assetsDir, `.engine-${searchId}-${selection}.part`);
-  let res;
-  try {
-    res = await client.engineDownloadToFile({
+  const fetchOnce = (color) =>
+    client.engineDownloadToFile({
       presId,
       backendURL,
       searchId,
       selection,
       destPath: tempPath,
-      iconColor: iconColor ?? null,
+      iconColor: color ?? null,
       onProgress: createTransferProgress(`downloading result ${selection}`),
     });
+  let res;
+  // Set when the pane-free route refused the TINT (not the asset): the download
+  // then repeats without a colour so the caller still gets the icon, and the
+  // recolour is reported as not applied instead of silently claimed.
+  let recolorRefused = null;
+  try {
+    res = await fetchOnce(iconColor);
   } catch (err) {
     fs.rmSync(tempPath, { force: true });
     // Route absent → this add-in predates streaming; let the caller fall back.
@@ -178,7 +205,13 @@ async function streamOneResult({
     // for a stale selection), not Express saying "no such path" — retrying that
     // on the capped path would just fail again, more slowly.
     if ((err?.status === 404 && !err?.code) || err?.status === 501) return null;
-    throw err;
+    // The recolour classifier is DOM-based and lives in the add-in, so the
+    // pane-free route refuses a tint rather than guessing at one. Refusing the
+    // whole DOWNLOAD over it would be worse: the icon is fetchable, only the
+    // colour is not. Take the bytes and say so.
+    if (err?.code !== "recolor_needs_host" || !iconColor) throw err;
+    recolorRefused = iconColor;
+    res = await fetchOnce(null);
   }
 
   try {
@@ -193,7 +226,12 @@ async function streamOneResult({
         path: target,
         reference: `./assets/${filename}`,
         mimeType: res.mimeType ?? "image/svg+xml",
-        recolor: describeRecolor(res.svgMarkup, res.mimeType, iconColor ?? null),
+        recolor: describeRecolorWithRefusal(
+          res.svgMarkup,
+          res.mimeType,
+          iconColor,
+          recolorRefused,
+        ),
         size: svgSizeFromMarkup(res.svgMarkup),
       };
     }
@@ -222,7 +260,12 @@ async function streamOneResult({
       path: target,
       reference: `./assets/${filename}`,
       mimeType: res.mimeType ?? null,
-      recolor: describeRecolor(null, res.mimeType, iconColor ?? null),
+      recolor: describeRecolorWithRefusal(
+        null,
+        res.mimeType,
+        iconColor,
+        recolorRefused,
+      ),
       size: imageSizeFromBuffer(probe),
     };
   } catch (err) {
@@ -237,7 +280,7 @@ async function streamOneResult({
 // the rest.
 export async function downloadOneResult({
   client,
-  presId,
+  presId = null,
   backendURL = null,
   searchId,
   assetsDir,
@@ -259,6 +302,16 @@ export async function downloadOneResult({
   });
   if (streamed) return streamed;
 
+  // The capped base64 fallback below is a PANE route. On the pane-free path
+  // there is no window to relay through — and an add-in that serves the direct
+  // routes always serves the direct stream — so a missing stream there is a real
+  // failure, not a reason to reach for a window that may not exist.
+  if (!presId) {
+    throw new Error(
+      "the add-in's engine routes returned no bytes for that result — re-run the search, then pick again",
+    );
+  }
+
   // Fallback for an add-in that predates the streaming route: bytes ride the
   // pane's Socket.IO ack, capped by its 10 MB frame limit.
   const res = await client.engineDownload({

package/src/bridge/{pair.mjs → http-json.mjs}

@@ -1,18 +1,14 @@
-// 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.
+// Minimal JSON-over-HTTP transport shared by setup-claim redemption and session
+// management. Validates real TLS certificates; loopback development may use a
+// self-signed HTTPS certificate or plain HTTP.
 
 import http from "node:http";
 import https from "node:https";
 
-function isLoopbackHostname(h) {
-  return h === "127.0.0.1" || h === "localhost" || h === "::1";
+function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::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;
@@ -30,11 +26,13 @@ export function httpJson(method, urlStr, { body = null, token = null } = {}) {
         method,
         headers,
         rejectUnauthorized:
-          url.protocol === "https:" ? !isLoopbackHostname(url.hostname) : undefined,
+          url.protocol === "https:"
+            ? !isLoopbackHostname(url.hostname)
+            : undefined,
       },
       (res) => {
         const chunks = [];
-        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
         res.on("end", () => {
           const text = Buffer.concat(chunks).toString("utf8");
           let json = null;
@@ -52,16 +50,3 @@ export function httpJson(method, urlStr, { body = null, token = null } = {}) {
     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/bridge/setup-claim.mjs

@@ -0,0 +1,127 @@
+// One-command setup claims — the CLI half of "click Connect CLI in PowerPoint,
+// paste one command".
+//
+// Why the add-in mints this rather than the CLI: the CLI cannot discover WHICH slidemind
+// deployment a user belongs to. Every customer runs its own backend, so an
+// anonymous CLI has no address to start an approval at. The authenticated
+// add-in already knows its deployment, so it mints a claim that carries the
+// backend URL alongside a one-time secret; the user pastes it once and the CLI
+// learns both at the same moment. This is the ONLY way a CLI gets a session.
+//
+// Wire shape: `smc1_<base64url({ v: 1, u: <backendURL>, s: <secret> })>`.
+// The secret is the credential — it is one-time, short-lived, and bound
+// server-side to the identity that minted it. Nothing here is a bearer token
+// for anything else, and the claim is worthless once redeemed.
+
+import os from "node:os";
+
+import { httpJson } from "./http-json.mjs";
+
+export const SETUP_CLAIM_PREFIX = "smc1_";
+
+function isLoopback(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+function invalid(detail) {
+  return new Error(
+    `${detail}\n\n` +
+      "Open PowerPoint → slidemind → Settings → General → Connect CLI and copy a fresh setup command.",
+  );
+}
+
+/**
+ * Decode + validate a setup claim into { backendURL, secret }.
+ *
+ * Tolerates the shapes a copied terminal command actually arrives in: wrapping
+ * whitespace, surrounding quotes, and the whole `npx --yes slidemind@latest
+ * setup <claim>` line pasted as one argument.
+ */
+export function decodeSetupClaim(raw) {
+  let text = String(raw ?? "").trim();
+  // A user who quotes the argument, or pastes the entire command as one shell
+  // word, still gets what they meant.
+  text = text.replace(/^['"]|['"]$/g, "").trim();
+  if (text.includes(SETUP_CLAIM_PREFIX) && !text.startsWith(SETUP_CLAIM_PREFIX)) {
+    const match = text.match(/smc1_[A-Za-z0-9_-]+/);
+    if (match) text = match[0];
+  }
+
+  if (!text.startsWith(SETUP_CLAIM_PREFIX)) {
+    throw invalid(
+      "that does not look like a slidemind setup command (it should end with a smc1_… claim).",
+    );
+  }
+
+  const body = text.slice(SETUP_CLAIM_PREFIX.length);
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+  } catch {
+    throw invalid("this setup command is damaged — it was probably copied only in part.");
+  }
+
+  if (!parsed || parsed.v !== 1) {
+    throw invalid(
+      "this setup command was made by a newer slidemind add-in than this CLI understands. Run `npm install -g slidemind@latest` and try again.",
+    );
+  }
+
+  const secret = typeof parsed.s === "string" ? parsed.s : "";
+  if (!secret) throw invalid("this setup command carries no connection secret.");
+
+  let url;
+  try {
+    url = new URL(String(parsed.u ?? ""));
+  } catch {
+    throw invalid("this setup command carries no valid slidemind address.");
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) {
+    throw invalid(
+      "this setup command points at a non-HTTPS slidemind address (HTTP is allowed only for loopback development).",
+    );
+  }
+
+  return { backendURL: url.toString().replace(/\/$/, ""), secret };
+}
+
+/**
+ * Spend the one-time secret at its own deployment and receive the CLI session.
+ * The claim is consumed server-side whether or not this process survives, so a
+ * failure here always means "get a fresh command", never "retry".
+ */
+export async function redeemSetupClaim({ backendURL, secret, cliVersion }) {
+  let result;
+  try {
+    result = await httpJson("POST", `${backendURL}/api/cli/connect/redeem`, {
+      body: {
+        secret,
+        deviceName: os.hostname() || "CLI device",
+        platform: `${process.platform}-${process.arch}`,
+        cliVersion,
+      },
+    });
+  } catch (error) {
+    throw new Error(
+      `could not reach slidemind to complete setup: ${error?.message || error}`,
+    );
+  }
+
+  if (result.status === 200 && result.json?.sessionToken) {
+    return String(result.json.sessionToken);
+  }
+  // Discriminate on the error CODE, not the status. A deployment that predates
+  // one-command setup has no such route, so the request falls through to that
+  // router's session guard and comes back 401 `no_session` — the same status a
+  // spent claim returns. Only the body tells the two apart.
+  if (result.status === 401 && result.json?.error === "setup_claim_invalid_or_expired") {
+    throw invalid("this setup command has already been used or has expired.");
+  }
+  if (result.status === 401 || result.status === 404 || result.status === 405) {
+    throw new Error(
+      "this slidemind add-in is too old for one-command setup — it needs an add-in update before the CLI can connect to it.",
+    );
+  }
+  const detail = result.json?.error || result.text || `HTTP ${result.status}`;
+  throw new Error(`slidemind could not complete setup: ${detail}`);
+}

package/src/builders/resolve-skill.mjs

@@ -68,8 +68,11 @@ function firstExistingOr(candidates, fallback) {
   return firstExisting(candidates) ?? fallback;
 }
 
-export function resolveSkillForDeck(deckDir) {
+export function resolveSkillForDeck(deckDir, opts = {}) {
   const planMeta = readPlanFrontmatter(deckDir);
+  if (opts.packDir) {
+    return resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+  }
   const skillName = planMeta.skill || DEFAULT_SKILL;
   const bundleDir = deckDir ? resolveBundleDirForDeck(deckDir) : null;
   return resolveSkill(skillName, planMeta, { deckDir, bundleDir });
@@ -80,7 +83,12 @@ export function resolveSkillForDeck(deckDir) {
 // fill-template) must not pay resolveSkill's design-root requirement — a
 // compose deck with an unmaterialized bundle self-heals inside the render
 // path, and an early resolver throw here would break that.
-export function resolveDeckMode(deckDir) {
+export function resolveDeckMode(deckDir, opts = {}) {
+  if (opts.packDir) {
+    const planMeta = readPlanFrontmatter(deckDir);
+    const pack = resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+    return { skillName: pack.skillName, mode: pack.mode, skillDir: pack.skillDir };
+  }
   try {
     const planMeta = readPlanFrontmatter(deckDir);
     const skillName = planMeta.skill || DEFAULT_SKILL;
@@ -92,6 +100,60 @@ export function resolveDeckMode(deckDir) {
   }
 }
 
+// Resolve a runtime template pack from an explicit directory. This path is
+// deliberately independent of agent/harness installation and of the compose
+// design-bundle resolver below. A plugin can locate its own pack and pass this
+// path to the CLI without the CLI knowing the plugin exists.
+export function resolveTemplatePack(packDir, planMeta = {}, opts = {}) {
+  const skillDir = path.resolve(String(packDir));
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    throw new Error(`template pack directory does not exist: ${skillDir}`);
+  }
+  const manifest = readManifest(skillDir);
+  if (!manifest || typeof manifest !== "object" || !manifest.mode) {
+    throw new Error(`template pack ${skillDir} has no valid skill.json manifest`);
+  }
+
+  let templateKey = null;
+  let templatePath = null;
+  if (manifest.templates) {
+    templateKey =
+      planMeta.template ||
+      manifest.defaultTemplate ||
+      Object.keys(manifest.templates)[0];
+    const rel = templateKey ? manifest.templates[templateKey] : null;
+    if (rel) {
+      const candidate = path.resolve(skillDir, rel);
+      const relative = path.relative(skillDir, candidate);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`template path escapes pack directory: ${rel}`);
+      }
+      if (fs.existsSync(candidate)) templatePath = candidate;
+    }
+  }
+
+  return {
+    skillName: manifest.name || path.basename(skillDir),
+    skillDir,
+    manifest,
+    mode: manifest.mode || "compose",
+    // Fill-template callers only need the pack payload. These legacy design
+    // fields remain null so callers can distinguish this path from compose
+    // skill resolution without paying a design-root requirement.
+    cssFile: null,
+    layoutsDir: null,
+    layoutsCssFile: null,
+    assetsDir: opts.deckDir ? path.join(opts.deckDir, "assets") : null,
+    brand: null,
+    templateKey,
+    templatePath,
+    locale: planMeta.locale || null,
+    planMeta,
+    packageRoot: PACKAGE_ROOT,
+    bundleDir: opts.deckDir ? resolveBundleDirForDeck(opts.deckDir) : null,
+  };
+}
+
 // Skill packs can live outside the npm package: private, org-internal packs
 // (templates, brand-specific assets) are distributed on their own and this
 // package never carries them. Lookup order:

package/src/installers/claude.mjs

@@ -14,6 +14,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import {
+  binaryOnPath,
   expandHome,
   installDir,
   isForce,
@@ -91,6 +92,29 @@ function pluginInstallDetected() {
   }
 }
 
+// Is Claude Code on this machine, and would deploying here duplicate a plugin?
+// `--for auto` (what `slidemind setup` uses) installs only where the harness
+// actually exists AND its plugin has not already supplied the skills — copying
+// over a plugin's skills plants a second set that drifts on the next plugin
+// update, which is the one thing plugin users must not do.
+//
+// Two signals, because either alone misses a real install: the config dir is
+// created the first time the agent RUNS (so a just-installed, never-launched
+// Claude Code has none), while the binary is missing for a desktop-app-only
+// install. Present if either says so.
+export function detect() {
+  const root = claudeRoot();
+  const configured = fs.existsSync(root);
+  const onPath = binaryOnPath("claude");
+  return {
+    root,
+    configured,
+    onPath,
+    present: configured || onPath,
+    pluginInstalled: pluginInstallDetected(),
+  };
+}
+
 export async function install({ packageRoot, flags }) {
   const link = isLinkMode(flags);
   const force = isForce(flags);

package/src/installers/codex.mjs

@@ -25,6 +25,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import {
+  binaryOnPath,
   expandHome,
   installDir,
   isForce,
@@ -81,6 +82,33 @@ function agentsFile() {
   return path.join(codexRoot(), "AGENTS.md");
 }
 
+// `$CODEX_HOME/plugins/cache/<marketplace>/slidemind/<version>/` — a non-empty
+// plugin directory means the Codex plugin is also installed, so the skills
+// copied by `init` duplicate the ones the plugin already carries (and will
+// drift the next time either side updates). Mirrors the Claude installer's
+// check. A marketplace-only `cache/slidemind/` (added but never installed from)
+// holds no `slidemind` child, so it correctly reads as "not installed".
+export function pluginInstallDetected() {
+  const cacheRoot = path.join(codexRoot(), "plugins", "cache");
+  try {
+    return fs.readdirSync(cacheRoot).some((mp) => {
+      const dir = path.join(cacheRoot, mp, NAMESPACE);
+      try {
+        return (
+          fs.statSync(dir).isDirectory() &&
+          fs
+            .readdirSync(dir)
+            .some((entry) => !entry.startsWith("."))
+        );
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
 function configTomlFile() {
   return path.join(codexRoot(), "config.toml");
 }
@@ -119,13 +147,18 @@ function writeAgentsBlock() {
   const block =
     `${AGENTS_MARK_BEGIN}\n` +
     `## slidemind\n` +
-    `Slide-deck authoring skill installed via slidemind.\n` +
+    `Slide-deck authoring and slide-reuse skills installed via slidemind.\n` +
     `\n` +
     `When the user asks to create, plan, or edit a slide deck or presentation, load\n` +
     `the \`slidemind-create-slides\` skill (auto-discovered from\n` +
-    `${skillTarget("create-slides")}/SKILL.md) and follow it. The skill drives the\n` +
-    `slidemind PowerPoint add-in and reads every brand rule — tokens, layout\n` +
-    `palette, brand imagery — from the design bundle the add-in serves.\n` +
+    `${skillTarget("create-slides")}/SKILL.md) and follow it.\n` +
+    `\n` +
+    `When the user asks to find or reuse an existing slide or brand image — from the\n` +
+    `corporate design's engines or from a \`.pptx\` on disk — load the\n` +
+    `\`slidemind-search\` skill (${skillTarget("search")}/SKILL.md) instead.\n` +
+    `\n` +
+    `Both drive the slidemind PowerPoint add-in and read every brand rule — tokens,\n` +
+    `layout palette, brand imagery — from the design bundle the add-in serves.\n` +
     `\n` +
     `Build with: \`slidemind build <deck>\` (HTML) or \`slidemind build-pptx <deck>\` (PPTX).\n` +
     `${AGENTS_MARK_END}\n`;
@@ -155,6 +188,20 @@ function clearAgentsBlock() {
   fs.writeFileSync(file, existing);
 }
 
+// See claude.mjs `detect()` — same two-signal contract, Codex roots.
+export function detect() {
+  const root = codexRoot();
+  const configured = fs.existsSync(root);
+  const onPath = binaryOnPath("codex");
+  return {
+    root,
+    configured,
+    onPath,
+    present: configured || onPath,
+    pluginInstalled: pluginInstallDetected(),
+  };
+}
+
 export async function install({ packageRoot, flags }) {
   const link = isLinkMode(flags);
   const force = isForce(flags);
@@ -202,6 +249,15 @@ export async function install({ packageRoot, flags }) {
     ui.step({ status: "remove", label: "mcp server", value: mcpNote });
   }
 
+  if (pluginInstallDetected()) {
+    ui.step({
+      status: "info",
+      label: "plugin",
+      value:
+        "the slidemind Codex plugin is also installed — these copied skills duplicate its skills; plugin users only need `npm install -g slidemind` and can drop them with `slidemind uninstall --for codex`",
+    });
+  }
+
   ui.note("restart Codex to pick up the skill");
 }