slidemind 0.1.8 → 0.1.9

package/bin/slidemind.mjs

@@ -60,6 +60,10 @@ function printHelp() {
       `                                     as a markdown editor + live preview + overall feedback box,\n` +
       `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
       `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
+      `  slidemind concepts <deck>        After plan sign-off, generate one concept mockup PNG per planned\n` +
+      `                                     slide into <deck>/concepts/concept-slide-NN.png (requires a host).\n` +
+      `                                     Read each as a design target, then rebuild it as slide JSX.\n` +
+      `                                     Optional aid — skips cleanly (exit 0) if unavailable.\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
       `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
       `                                     approves or leaves comments (host-free)\n` +
@@ -95,11 +99,12 @@ function printHelp() {
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --to <presId>   target window (required if >1 open)\n` +
       `                                     --at <N>        insert after slide N (0-based); default = append\n` +
-      `  slidemind add-slide [opts]       Fold reused slide search results into a deck as native .pptx\n` +
-      `                                     --search <id>   searchId from 'slidemind search'\n` +
+      `  slidemind add-slide [opts]       Fold reused slide(s) into a deck as native .pptx\n` +
+      `                                     --search <id>   searchId from 'slidemind search' (requires a host)\n` +
+      `                                     --from <file.pptx>  fold slide(s) from a local .pptx instead (host-free)\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --deck <deck>   deck to add the slides to\n` +
-      `                                     --to <presId>   target the window the search ran on (required if >1 open)\n` +
+      `                                     --to <presId>   target the window the search ran on (required if >1 open; ignored with --from)\n` +
       `                                     --at <N>        numeric prefix to start at (default: append)\n` +
       `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/ (requires a host)\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
@@ -114,7 +119,8 @@ function printHelp() {
       `                                     --all          include retained suspended entries\n` +
       `  slidemind doctor                 Diagnose CLI/add-in pairing, backend, and pane readiness\n` +
       `                                     --json          print machine-readable status\n` +
-      `  slidemind read [presId]          Pull the current content of an open presentation (requires a host)\n` +
+      `  slidemind read [presId|file.pptx]  Pull the content of an open presentation (requires a host),\n` +
+      `                                     or of a local .pptx path (read host-free from disk)\n` +
       `                                     --mode <m>      summary | raw (default: raw)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --json          print the raw content payload\n` +
@@ -149,6 +155,15 @@ function fail(msg, code = 1) {
   process.exit(code);
 }
 
+// The local PowerPoint files `read` and `add-slide --from` accept host-free.
+// All are OPC (zip) OOXML packages with the same ppt/presentation.xml +
+// ppt/slides/ structure — presentation (.pptx/.pptm), template (.potx/.potm),
+// slideshow (.ppsx/.ppsm) — so the src/pptx/ reader/swapper handle them
+// identically. Presentation IDs are opaque and never carry these extensions,
+// so this stays a safe discriminator for "positional is a local file, not a
+// presId".
+const LOCAL_PPTX_RE = /\.(pptx|pptm|potx|potm|ppsx|ppsm)$/i;
+
 function resolveDecksDir() {
   if (process.env.SLIDEMIND_DECKS) {
     return path.resolve(process.env.SLIDEMIND_DECKS);
@@ -168,12 +183,25 @@ function resolveDeckArg(arg) {
   return path.join(decksDir, arg);
 }
 
-// Best-effort human name of a materialized design: the first `# ` heading in
-// the bundle's design.md, with the add-in's trailing " — design rules" suffix
-// stripped. Returns null on any failure (missing file, no heading) so callers
-// fall back to the raw presFP. Shared by `ready` and `new`'s auto-bind.
+// Best-effort human name of a materialized design. Prefers the live `name`
+// the wire carries (persisted into bundle.json by materializeBundle) — the
+// owner-set brand name, which survives renames. Falls back to the first `# `
+// heading in design.md (frozen at authoring time, so it may still show the
+// original auto codename), with the " — design rules" suffix stripped.
+// Returns null on any failure so callers fall back to the raw presFP.
+// Shared by `ready` and `new`'s auto-bind.
 function readDesignName(bundleDir) {
   if (!bundleDir) return null;
+  try {
+    const meta = JSON.parse(
+      fs.readFileSync(path.join(bundleDir, "bundle.json"), "utf8"),
+    );
+    if (typeof meta.name === "string" && meta.name.trim()) {
+      return meta.name.trim();
+    }
+  } catch {
+    /* no meta or unreadable — fall through to the design.md heading */
+  }
   try {
     const md = fs.readFileSync(path.join(bundleDir, "design.md"), "utf8");
     for (const raw of md.split("\n")) {
@@ -484,10 +512,19 @@ async function cmdSearch(rest) {
       );
     }
     const mat = await bundle.materializeBundle(presId, { backendURL });
-    const pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
+    let pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
+    if (!pick) {
+      // New backends no longer ship engines[] on the bundle wire — discovery
+      // is live-only. Fall back to the catalog the add-in's own design agent
+      // uses (its list_engines tool ≙ `slidemind ls engines`).
+      const live = await client
+        .listEngines({ subtype: "image", backendURL })
+        .catch(() => ({ engines: [] }));
+      pick = bundle.pickImageEngine(live.engines);
+    }
     if (!pick) {
       fail(
-        "This corporate design has no brand engines to search. Ask the add-in owner to wire an image/icon engine.",
+        "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;
@@ -713,6 +750,7 @@ async function cmdAddSlide(rest) {
   let deck = null;
   let at = null;
   let to = null;
+  let from = null;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
@@ -720,6 +758,9 @@ async function cmdAddSlide(rest) {
       const n = parseInt(next, 10);
       if (!Number.isFinite(n)) fail(`--search expects a searchId, got '${next}'`);
       searchId = n;
+    } else if (a === "--from") {
+      from = rest[++i];
+      if (!from) fail("--from expects a path to a .pptx file");
     } else if (a === "--pick") {
       picks = parsePicks(rest[++i]);
     } else if (a === "--deck") {
@@ -741,8 +782,69 @@ async function cmdAddSlide(rest) {
       fail(`unexpected argument: ${a}`);
     }
   }
+
+  // Host-free local source: fold picked slides from a .pptx on disk (no bridge
+  // client, no requirePaneHost). Mutually exclusive with --search; --to is
+  // accepted-but-ignored here (symmetric with the other reuse commands — there's
+  // no window to target when the source is a local file).
+  if (from !== null) {
+    if (searchId !== null) fail("--from and --search are mutually exclusive");
+    if (!picks || !deck) {
+      fail("usage: slidemind add-slide --from <file.pptx> --pick <n[,n,...]> --deck <deck> [--at <N>]");
+    }
+    const fromPath = path.isAbsolute(from)
+      ? from
+      : path.resolve(process.cwd(), from);
+    let st = null;
+    try {
+      st = fs.statSync(fromPath);
+    } catch {
+      st = null;
+    }
+    if (!st || !st.isFile() || !LOCAL_PPTX_RE.test(fromPath)) {
+      fail(`--from: '${from}' is not an existing PowerPoint file (.pptx/.pptm/.potx/.potm/.ppsx/.ppsm)`);
+    }
+    const deckDir = resolveDeckArg(deck);
+    const slidesDir = path.join(deckDir, "slides");
+    fs.mkdirSync(slidesDir, { recursive: true });
+
+    const { foldPickedSlides } = await import(
+      pathToFileURL(path.join(SRC_DIR, "pptx", "slide-swap.mjs")).href
+    );
+    let results;
+    try {
+      results = foldPickedSlides(fs.readFileSync(fromPath), picks, {
+        sourceName: path.basename(fromPath),
+      });
+    } catch (err) {
+      fail(`add-slide failed: ${err.message}`);
+    }
+
+    // Same filename math + write loop as the --search branch; results already
+    // carry a `.slideId` and `.bytes` (a Uint8Array of a one-slide package).
+    const reused = await import(
+      pathToFileURL(path.join(SRC_DIR, "lib", "reused-slides.mjs")).href
+    );
+    const existing = fs
+      .readdirSync(slidesDir)
+      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"));
+    const targets = reused.reusedSlideTargets(existing, results, at);
+    const written = [];
+    results.forEach((r, i) => {
+      const target = path.join(slidesDir, targets[i].filename);
+      fs.writeFileSync(target, Buffer.from(r.bytes));
+      written.push(path.relative(process.cwd(), target));
+    });
+    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`,
+    );
+    return;
+  }
+
   if (searchId === null || !picks || !deck) {
-    fail("usage: slidemind add-slide --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]");
+    fail("usage: slidemind add-slide (--search <id> | --from <file.pptx>) --pick <n[,n,...]> --deck <deck> [--to <presId>] [--at <N>]");
   }
   const deckDir = resolveDeckArg(deck);
   const slidesDir = path.join(deckDir, "slides");
@@ -975,6 +1077,178 @@ async function cmdDownloadResult(rest) {
   if (ok === 0) process.exit(1);
 }
 
+// Strip the `data:<mime>;base64,` prefix off a data URI and return the raw
+// base64 payload (or null when the URI isn't a base64 data URI we can decode).
+function base64FromDataUri(dataUri) {
+  if (typeof dataUri !== "string") return null;
+  const m = /^data:[^;,]*;base64,(.*)$/s.exec(dataUri.trim());
+  return m ? m[1] : null;
+}
+
+async function cmdConceptImages(rest) {
+  let deck = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--deck") {
+      deck = rest[++i];
+      if (!deck) fail("--deck expects a deck name or path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (deck === null) {
+      deck = a;
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (!deck) fail("usage: slidemind concepts <deck>");
+
+  const deckDir = resolveDeckArg(deck);
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) {
+    fail(
+      `no plan.md in ${path.relative(process.cwd(), deckDir) || deckDir}. ` +
+        `Run \`slidemind plan ${deck}\` to compose and sign off a plan first.`,
+    );
+  }
+  const planMarkdown = fs.readFileSync(planPath, "utf8");
+
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  const brandId = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
+  if (!brandId) {
+    fail(
+      `deck ${deck} is not bound to a corporate design (no .bundle-ref.json). ` +
+        `Run \`slidemind ready ${deck}\` to bind it first.`,
+    );
+  }
+
+  // Plan sign-off is advisory here, not a hard gate: warn but proceed if the
+  // plan wasn't approved, so an agent can still fetch mockups while iterating.
+  const plan = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "plan.mjs")).href
+  );
+  const planState = plan.loadPlanState(deckDir);
+  if (planState?.decision !== "approved") {
+    process.stderr.write(
+      `slidemind: note — ${deck}'s plan is not signed off yet ` +
+        `(run \`slidemind plan ${deck}\`); generating concept mockups from the current plan.md anyway.\n`,
+    );
+  }
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+
+  const skipNote = () => {
+    process.stdout.write(
+      "no concept mockups generated — continuing without " +
+        "(this add-in doesn't generate concept mockups; author from the storyboards).\n",
+    );
+    process.exit(0);
+  };
+
+  // First request learns slideCount (and pins the serving backend for the rest).
+  let first;
+  try {
+    first = await client.generateConceptImagesForBrand(brandId, {
+      planMarkdown,
+      slideNumbers: [1],
+    });
+  } catch (err) {
+    if (err?.code === "concept_route_unavailable") skipNote();
+    throw err;
+  }
+
+  const backendURL = first.backendURL ?? null;
+  const slideCount = Number.isFinite(first.slideCount) ? first.slideCount : 0;
+  const images = [];
+  const collect = (res) => {
+    if (Array.isArray(res?.images)) images.push(...res.images);
+  };
+  collect(first);
+
+  // Family variants depend on their lowest-numbered anchor. Run independent
+  // slides + anchors first, then variants; the server cache remains a safety
+  // net for older clients and retries.
+  const families = await import(
+    pathToFileURL(path.join(BUILDERS_DIR, "visual-families.mjs")).href
+  );
+  const waves = families.conceptGenerationWaves(planMarkdown, slideCount);
+  const CONCURRENCY = 3;
+  async function runWave(slides) {
+    let cursor = 0;
+    async function worker() {
+      for (;;) {
+        const idx = cursor++;
+        if (idx >= slides.length) return;
+        const n = slides[idx];
+        try {
+          const res = await client.generateConceptImagesForBrand(brandId, {
+            planMarkdown,
+            slideNumbers: [n],
+            backendURL,
+          });
+          collect(res);
+        } catch (err) {
+          process.stderr.write(
+            `slidemind: concept mockup for slide ${n} failed: ${err?.message ?? err}\n`,
+          );
+        }
+      }
+    }
+    await Promise.all(
+      Array.from({ length: Math.min(CONCURRENCY, slides.length) }, () => worker()),
+    );
+  }
+  await runWave(waves.firstWave);
+  await runWave(waves.variants);
+
+  if (images.length === 0) {
+    process.stdout.write(
+      "no concept mockups generated — continuing without.\n",
+    );
+    process.exit(0);
+  }
+
+  const conceptsDir = path.join(deckDir, "concepts");
+  fs.mkdirSync(conceptsDir, { recursive: true });
+  const written = [];
+  for (const img of images) {
+    const n = Number(img?.slideNumber);
+    if (!Number.isFinite(n) || n < 1) continue;
+    const b64 = base64FromDataUri(img?.dataUri);
+    if (!b64) continue;
+    const name = `concept-slide-${String(n).padStart(2, "0")}.png`;
+    const abs = path.join(conceptsDir, name);
+    fs.writeFileSync(abs, Buffer.from(b64, "base64"));
+    written.push(abs);
+  }
+
+  // Drop stale mockups from a previous, longer plan — any concept-slide-NN.png
+  // whose slide number now exceeds the plan's slideCount.
+  for (const entry of fs.readdirSync(conceptsDir)) {
+    const m = /^concept-slide-(\d+)\.png$/.exec(entry);
+    if (m && Number(m[1]) > slideCount) {
+      fs.rmSync(path.join(conceptsDir, entry), { force: true });
+    }
+  }
+
+  if (written.length === 0) {
+    process.stdout.write(
+      "no concept mockups generated — continuing without.\n",
+    );
+    process.exit(0);
+  }
+
+  written.sort();
+  process.stdout.write(
+    written.join("\n") +
+      `\nWrote ${written.length} concept mockup(s) to ${conceptsDir} — ` +
+      "Read each, then rebuild as slide JSX (workflow/create.md → Preconditions).\n",
+  );
+}
+
 async function cmdDownloadBundle(rest) {
   let to = null;
   let force = false;
@@ -1652,14 +1926,54 @@ async function cmdDoctor(rest) {
   process.stdout.write(`Next action: ${status.nextAction}\n`);
 }
 
+// Print a read result — the `{ ok, mode, slideCount, slides[] }` shape, whether
+// it came from the add-in (open presentation) or a local .pptx. Shared by both
+// `cmdRead` branches so their output is byte-for-byte identical.
+function printReadResult(res, asJson) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+    return;
+  }
+  const slides = Array.isArray(res.slides) ? res.slides : [];
+  if (slides.length === 0) {
+    process.stderr.write("(presentation has no slides)\n");
+    return;
+  }
+  if (res.mode === "summary") {
+    for (const s of slides) {
+      const label = s.title || "(untitled)";
+      const sub = s.subtitle ? ` — ${s.subtitle}` : "";
+      const layout = s.layout ? `  [${s.layout}]` : "";
+      process.stdout.write(
+        `${String(s.index).padStart(3)}.${layout}  ${label}${sub}\n`,
+      );
+    }
+  } else {
+    slides.forEach((s, i) => {
+      if (i > 0) process.stdout.write("\n");
+      const layout = s.layout ? ` (${s.layout})` : "";
+      process.stdout.write(`── Slide ${s.index}${layout} ──\n`);
+      process.stdout.write(`${s.text && s.text.length ? s.text : "(no text)"}\n`);
+    });
+  }
+}
+
 // Pull the current content of an open presentation. Content is window-bound, so
 // pick exactly one window (positional presId or --to; pickPresentationEntry errors
 // listing the windows if several are open and none was named). `--mode summary`
 // prints a per-slide outline; default `raw` prints each slide's plain text.
+//
+// A positional arg with a local PowerPoint extension (LOCAL_PPTX_RE: .pptx and
+// its .pptm/.potx/.potm/.ppsx/.ppsm siblings) AND resolving to an existing
+// regular file is read host-free from disk instead (no bridge). The gate is
+// strict: a nonexistent path or a real presId falls through to the host path
+// unchanged, and it is skipped when --to is given (--to targets an open window).
 async function cmdRead(rest) {
   let presId = null;
   let mode = "raw";
   let asJson = false;
+  let toGiven = false;
+  let fileArg = null; // the positional (a candidate local .pptx path)
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--mode") {
@@ -1671,16 +1985,47 @@ async function cmdRead(rest) {
     } else if (a === "--to") {
       presId = rest[++i];
       if (!presId) fail("--to expects a presId");
+      toGiven = true;
     } else if (a === "--json") {
       asJson = true;
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else if (!presId) {
-      presId = a; // positional presId
+      presId = a; // positional presId (or local .pptx path)
+      fileArg = a;
     } else {
       fail(`unexpected argument: ${a}`);
     }
   }
+
+  // Local-file gate: applies ONLY to the positional, and never when --to is set.
+  // The positional must end in .pptx and resolve to an existing regular file;
+  // anything else (missing path, real presId) falls through to the host path.
+  if (fileArg && !toGiven && LOCAL_PPTX_RE.test(fileArg)) {
+    const p = path.isAbsolute(fileArg)
+      ? fileArg
+      : path.resolve(process.cwd(), fileArg);
+    let st = null;
+    try {
+      st = fs.statSync(p);
+    } catch {
+      st = null;
+    }
+    if (st && st.isFile()) {
+      const { readLocalPptx } = await import(
+        pathToFileURL(path.join(SRC_DIR, "pptx", "read-local.mjs")).href
+      );
+      let res;
+      try {
+        res = readLocalPptx(fs.readFileSync(p), { mode });
+      } catch (err) {
+        fail(`read failed: ${err.message}`);
+      }
+      printReadResult(res, asJson);
+      return;
+    }
+  }
+
   const client = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
   );
@@ -1694,32 +2039,7 @@ async function cmdRead(rest) {
   if (!res?.ok) {
     fail(`read failed: ${res?.error ?? "unknown error"}`);
   }
-  if (asJson) {
-    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
-    return;
-  }
-  const slides = Array.isArray(res.slides) ? res.slides : [];
-  if (slides.length === 0) {
-    process.stderr.write("(presentation has no slides)\n");
-    return;
-  }
-  if (res.mode === "summary") {
-    for (const s of slides) {
-      const label = s.title || "(untitled)";
-      const sub = s.subtitle ? ` — ${s.subtitle}` : "";
-      const layout = s.layout ? `  [${s.layout}]` : "";
-      process.stdout.write(
-        `${String(s.index).padStart(3)}.${layout}  ${label}${sub}\n`,
-      );
-    }
-  } else {
-    slides.forEach((s, i) => {
-      if (i > 0) process.stdout.write("\n");
-      const layout = s.layout ? ` (${s.layout})` : "";
-      process.stdout.write(`── Slide ${s.index}${layout} ──\n`);
-      process.stdout.write(`${s.text && s.text.length ? s.text : "(no text)"}\n`);
-    });
-  }
+  printReadResult(res, asJson);
 }
 
 async function loadBridgeModule(name) {
@@ -2221,7 +2541,22 @@ async function cmdUpdate(rest) {
     : "slidemind@latest";
   await ui.section("release", ref ? `pinned ${spec}` : "latest");
   ui.step({ label: "install", value: spec, note: "global (npm)" });
-  await spawnInherit(npmBin(), ["install", "-g", "--loglevel=error", spec]);
+  try {
+    await spawnInherit(npmBin(), ["install", "-g", "--loglevel=error", spec]);
+  } catch (err) {
+    console.error(
+      "\nslidemind update could not write to npm's global package directory.\n" +
+        "This usually happens on macOS/Linux when Node was installed with a system-owned npm prefix.\n\n" +
+        "Avoid `sudo npm`. Use Homebrew/nvm, or move npm's global prefix into your home directory:\n\n" +
+        "  mkdir -p ~/.npm-global\n" +
+        "  npm config set prefix ~/.npm-global\n" +
+        "  echo 'export PATH=\"$HOME/.npm-global/bin:$PATH\"' >> ~/.zshrc\n" +
+        "  source ~/.zshrc\n" +
+        "  npm install -g slidemind\n\n" +
+        "Then run `slidemind init --for all`.\n",
+    );
+    throw err;
+  }
 
   if (target !== "none") {
     await spawnInherit("slidemind", ["init", "--for", target]);
@@ -2299,6 +2634,9 @@ async function main(rawArgv) {
     case "download-result":
       await cmdDownloadResult(rest);
       return 0;
+    case "concepts":
+      await cmdConceptImages(rest);
+      return 0;
     case "download-bundle":
       await cmdDownloadBundle(rest);
       return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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": {
@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
+    "fflate": "^0.8.3",
     "puppeteer": "24.43.0"
   },
   "engines": {