slidemind 0.0.27

package/bin/slidemind.mjs

@@ -0,0 +1,603 @@
+#!/usr/bin/env node
+// slidemind — single CLI entry point for the slidemind npm package.
+//
+// Subcommands:
+//   slidemind init [--for <target>]   set up slidemind in a coding harness
+//                                       (register the MCP server + skill);
+//                                       targets: claude | codex | opencode | all
+//                                       (`install` is a back-compat alias)
+//   slidemind new <name>              scaffold ./decks/<name>/{plan.md,slides/}
+//   slidemind build <deck>            build self-contained HTML deck
+//   slidemind build-pptx <deck>       render the deck as native .pptx (via the add-in)
+//   slidemind uninstall --for <target>
+//   slidemind update [--for <target>] [--ref <version>]
+//                                       npm install -g slidemind@latest + redeploy
+//   slidemind --help | -h | --version
+//
+// All deck paths are resolved against the user's current working directory.
+// The brand-agnostic skill (skills/create-slides/) is found relative to this
+// script; the design itself comes from the add-in's bundle over the bridge.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const SRC_DIR = path.join(PACKAGE_ROOT, "src");
+const BUILDERS_DIR = path.join(SRC_DIR, "builders");
+const INSTALLERS_DIR = path.join(SRC_DIR, "installers");
+
+function readPackageJson() {
+  return JSON.parse(
+    fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+  );
+}
+
+function printHelp() {
+  const pkg = readPackageJson();
+  process.stdout.write(
+    `slidemind ${pkg.version} — drive the slidemind PowerPoint add-in to build native, on-brand decks\n` +
+      `\n` +
+      `Usage:\n` +
+      `  slidemind new <name>             Scaffold ./decks/<name>/\n` +
+      `  slidemind build <deck>           Build self-contained HTML\n` +
+      `  slidemind build-pptx <deck>      Export native .pptx via the add-in (requires an open host)\n` +
+      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
+      `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
+      `  slidemind search "<query>"       Search the brand engine for icons/images (requires an open host)\n` +
+      `                                     --engine <id>   engine to search (default: first image engine)\n` +
+      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
+      `  slidemind download-bundle [deck] Materialize the active corporate design's bundle locally\n` +
+      `                                     --to <presId>   target a specific window\n` +
+      `                                     --force         re-download even if the cached bundle is current\n` +
+      `  slidemind presentations          List PowerPoint windows registered with the add-in\n` +
+      `  slidemind push <deck> [opts]     Build deck and push slides into a running PowerPoint\n` +
+      `                                     --to <presId>   target a specific window (required if >1 open)\n` +
+      `                                     --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 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` +
+      `                                     --for <t>     harness to redeploy into (default: all)\n` +
+      `                                     --ref <ver>   pin to a release version (e.g. v0.1.0)\n` +
+      `  slidemind --help                 Show this help\n` +
+      `  slidemind --version              Print version\n` +
+      `\n` +
+      `Install targets: claude | codex | opencode | all\n` +
+      `Decks live in ./decks/ relative to your current directory.\n` +
+      `Override with env: SLIDEMIND_DECKS=/abs/path/to/decks\n`,
+  );
+}
+
+function fail(msg, code = 1) {
+  process.stderr.write(`slidemind: ${msg}\n`);
+  process.exit(code);
+}
+
+function resolveDecksDir() {
+  if (process.env.SLIDEMIND_DECKS) {
+    return path.resolve(process.env.SLIDEMIND_DECKS);
+  }
+  return path.resolve(process.cwd(), "decks");
+}
+
+function resolveDeckArg(arg) {
+  // A user can pass either "decks/foo" (relative to CWD), "/abs/path/foo",
+  // or just "foo" — in which case we look it up under the resolved decks dir.
+  if (!arg) return null;
+  if (path.isAbsolute(arg)) return arg;
+  if (fs.existsSync(path.resolve(process.cwd(), arg))) {
+    return path.resolve(process.cwd(), arg);
+  }
+  const decksDir = resolveDecksDir();
+  return path.join(decksDir, arg);
+}
+
+function runNode(script, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${path.basename(script)} exited with code ${code}`));
+    });
+  });
+}
+
+// ---------- subcommands ----------
+
+function splitDeckArg(rest, cmd) {
+  // The first non-flag positional is the deck. Everything else passes
+  // through to the underlying script verbatim.
+  const passthrough = [...rest];
+  let deck = null;
+  for (let i = 0; i < passthrough.length; i++) {
+    if (!passthrough[i].startsWith("-")) {
+      deck = passthrough.splice(i, 1)[0];
+      break;
+    }
+  }
+  if (!deck) fail(`usage: slidemind ${cmd} <deck>`);
+  return { deck, passthrough };
+}
+
+async function cmdBuild(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "build");
+  await runNode(path.join(BUILDERS_DIR, "build.mjs"), [
+    "--deck",
+    resolveDeckArg(deck),
+    ...passthrough,
+  ]);
+}
+
+async function cmdBuildPptx(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "build-pptx");
+  let to = null;
+  let outPath = null;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--to") {
+      to = passthrough[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--out" || a === "-o") {
+      outPath = passthrough[++i];
+      if (!outPath) fail("--out expects a path");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  const deckDir = resolveDeckArg(deck);
+  if (!fs.existsSync(path.join(deckDir, "slides"))) {
+    fail(`expected 'slides/' folder in ${deckDir}`);
+  }
+  // The .pptx is rendered server-side by the add-in (one exporter, one truth);
+  // this requires an open PowerPoint host with an active corporate design.
+  const mod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
+  );
+  const result = await mod.buildPptxFile({
+    deckDir,
+    presentationId: to,
+    outPath,
+  });
+  process.stdout.write(
+    `Wrote ${result.outPath} (${result.slideCount ?? "?"} slides) via the slidemind add-in\n`,
+  );
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
+  }
+  for (const s of result.skippedSlides ?? []) {
+    process.stderr.write(`  skipped ${s.stem}: ${s.reason}\n`);
+  }
+}
+
+async function cmdSearch(rest) {
+  let asJson = false;
+  let to = null;
+  let engineId = 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 === "--engine" || a === "-e") {
+      engineId = rest[++i];
+      if (!engineId) fail("--engine expects an engineId");
+    } 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>] [--to <presId>] [--json]`,
+    );
+  }
+
+  // Icon/image search now runs against the add-in's live brand engine over the
+  // bridge — an open host is required, and the engine comes from the active
+  // corporate design's bundle.
+  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 registry = await client.requireHost();
+  const presId = client.pickPresentation(registry, to);
+
+  if (!engineId) {
+    const mat = await bundle.materializeBundle(presId);
+    const pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));
+    if (!pick) {
+      fail(
+        "This corporate design has no brand engines to search. Ask the add-in owner to wire an image/icon engine.",
+      );
+    }
+    engineId = pick.id;
+  }
+
+  const res = await client.engineSearch({ presId, engineId, query });
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    return;
+  }
+  if (!res?.ok) {
+    process.stderr.write(`search failed: ${res?.error ?? "unknown error"}\n`);
+    return;
+  }
+  const count = res.resultCount ?? (res.thumbnails?.length ?? 0);
+  process.stdout.write(
+    `searchId ${res.searchId} — ${count} result(s) from engine ${engineId}\n`,
+  );
+  (res.thumbnails ?? []).forEach((t, i) => {
+    process.stdout.write(`  ${i + 1}. ${t.title ?? "(untitled)"}\n`);
+  });
+  process.stdout.write(
+    `Download a result by selection number via the agent (slidemind_download_result).\n`,
+  );
+}
+
+async function cmdDownloadBundle(rest) {
+  let to = null;
+  let force = false;
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--force") {
+      force = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  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 registry = await client.requireHost();
+  const presId = client.pickPresentation(registry, to);
+  const result = await bundle.materializeBundle(presId, { force });
+
+  // Optionally bind a deck to this bundle so build-pptx/push pass the right
+  // etag and the local HTML/editor read the right design files.
+  const deckArg = positional[0];
+  if (deckArg) {
+    const deckDir = resolveDeckArg(deckArg);
+    bundle.writeDeckBundleRef(deckDir, {
+      presFP: result.presFP,
+      etag: result.etag,
+    });
+  }
+  process.stdout.write(
+    `${result.cached ? "Bundle already current" : "Materialized bundle"} for ${result.presFP} (etag ${result.etag ?? "?"})\n  ${result.dir}\n`,
+  );
+  // Asset downloads are best-effort (a signed URL may have expired); surface any
+  // failures so the user knows the local preview bundle is incomplete.
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
+  }
+}
+
+async function cmdPresentations(rest) {
+  const asJson = rest.includes("--json");
+  const mod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  const list = await mod.listOpenPresentations();
+  if (asJson) {
+    process.stdout.write(JSON.stringify(list, null, 2) + "\n");
+    return;
+  }
+  if (list.length === 0) {
+    process.stderr.write(
+      "No PowerPoint windows registered with the slidemind add-in.\n",
+    );
+    return;
+  }
+  for (const p of list) {
+    const label = p.title || p.fileName || "(untitled)";
+    process.stdout.write(`${p.presId}\t${label}\n`);
+  }
+}
+
+async function cmdPush(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "push");
+  let to = null;
+  let at = null;
+  let replace = false;
+  let slides = null;
+  for (let i = 0; i < passthrough.length; i++) {
+    const a = passthrough[i];
+    if (a === "--to") {
+      to = passthrough[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--at") {
+      const next = passthrough[++i];
+      const n = parseInt(next, 10);
+      if (!Number.isFinite(n) || n < 0) {
+        fail(`--at expects a non-negative integer, got '${next}'`);
+      }
+      at = n;
+    } else if (a === "--replace") {
+      replace = true;
+    } else if (a === "--slides") {
+      const next = passthrough[++i];
+      if (!next) fail("--slides expects a comma-separated list of slide ids");
+      slides = next.split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      fail(`unexpected argument: ${a}`);
+    }
+  }
+  if (replace && (at !== null || slides)) {
+    fail("--replace cannot be combined with --at or --slides");
+  }
+
+  const deckDir = resolveDeckArg(deck);
+  if (!fs.existsSync(path.join(deckDir, "slides"))) {
+    fail(`expected 'slides/' folder in ${deckDir}`);
+  }
+
+  const mod = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "build-and-push.mjs")).href
+  );
+  const result = await mod.buildAndPush({
+    deckDir,
+    presentationId: to,
+    insertAt: at,
+    replace,
+    slideIds: slides,
+  });
+  if (result.paneSuspended) {
+    process.stdout.write(
+      `PowerPoint is backgrounded — the deck rendered but couldn't be pushed.\n` +
+        `Click the slidemind task pane once to bring PowerPoint to the foreground, ` +
+        `then re-run: slidemind push ${deck}\n` +
+        `The rendered deck was saved to ${path.relative(process.cwd(), result.fallbackFile)} in the meantime.\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `Pushed ${result.bytes} bytes (${result.mode}) to presentation ${result.presId}\n`,
+  );
+}
+
+async function cmdNew(rest) {
+  const positional = rest.filter((a) => !a.startsWith("--"));
+  const name = positional[0];
+  if (!name) fail("usage: slidemind new <name>");
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
+    fail(`deck name must be kebab-case alphanumerics, got '${name}'`);
+  }
+  const decksDir = resolveDecksDir();
+  const deckDir = path.join(decksDir, name);
+  if (fs.existsSync(deckDir)) {
+    fail(`deck already exists: ${deckDir}`);
+  }
+  fs.mkdirSync(path.join(deckDir, "slides"), { recursive: true });
+  fs.writeFileSync(
+    path.join(deckDir, "plan.md"),
+    `# ${name}\n\n` +
+      `Ask your agent (Claude Code / Codex / opencode) to plan and author this deck —\n` +
+      `the slidemind-create-slides skill fills this in, then writes slides under ./slides/.\n`,
+  );
+  process.stdout.write(`Created ${path.relative(process.cwd(), deckDir)}\n`);
+  process.stdout.write(
+    `Next: ask your agent to author "${name}", then \`slidemind build ${name}\`\n`,
+  );
+}
+
+function parseTargetFlag(rest) {
+  const idx = rest.findIndex((a) => a === "--for" || a === "-f");
+  if (idx < 0 || !rest[idx + 1]) {
+    fail("missing --for <claude|codex|opencode|all>");
+  }
+  const target = rest[idx + 1];
+  if (!["claude", "codex", "opencode", "all"].includes(target)) {
+    fail(`unknown install target: ${target}`);
+  }
+  return target;
+}
+
+async function runInstaller(target, action, rest) {
+  const targets = target === "all" ? ["claude", "codex", "opencode"] : [target];
+  for (const t of targets) {
+    const mod = await import(
+      pathToFileURL(path.join(INSTALLERS_DIR, `${t}.mjs`)).href
+    );
+    const fn = mod[action];
+    if (typeof fn !== "function") {
+      fail(`installer for '${t}' does not implement '${action}'`);
+    }
+    await fn({
+      packageRoot: PACKAGE_ROOT,
+      flags: rest,
+    });
+  }
+}
+
+async function loadInstallerUi() {
+  const mod = await import(
+    pathToFileURL(path.join(INSTALLERS_DIR, "lib.mjs")).href
+  );
+  return mod.ui;
+}
+
+async function cmdInstall(rest) {
+  const target = parseTargetFlag(rest);
+  const ui = await loadInstallerUi();
+  ui.banner(readPackageJson().version, "init");
+  await runInstaller(target, "install", rest);
+  ui.done(
+    target === "all"
+      ? "ready — ask your agent to plan, create, or edit a deck"
+      : `ready — ${target} can now plan, create, or edit decks`,
+  );
+}
+
+async function cmdUninstall(rest) {
+  const target = parseTargetFlag(rest);
+  const ui = await loadInstallerUi();
+  ui.banner(readPackageJson().version, "uninstall");
+  await runInstaller(target, "uninstall", rest);
+  ui.done(target === "all" ? "removed from all harnesses" : `removed from ${target}`);
+}
+
+function spawnInherit(file, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      stdio: "inherit",
+      env: process.env,
+      shell: process.platform === "win32",
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${file} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+
+// ---------- distribution (public npm) ----------
+//
+// slidemind is published to public npm as `slidemind`. First install is
+// `npm install -g slidemind` (then `slidemind init` to register the MCP
+// server + skill; `install` stays as a back-compat alias); `slidemind update`
+// is a thin wrapper over `npm install -g slidemind@latest`.
+
+// Resolve the `npm` that sits next to the node running this process, so an
+// update lands the global into the same prefix slidemind was launched from.
+function npmBin() {
+  const dir = path.dirname(process.execPath);
+  const candidates =
+    process.platform === "win32"
+      ? [path.join(dir, "npm.cmd"), path.join(dir, "npm")]
+      : [path.join(dir, "npm")];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return "npm"; // PATH fallback
+}
+
+async function cmdUpdate(rest) {
+  let target = "all";
+  let ref = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--for" || a === "-f") {
+      target = rest[++i];
+      if (!target) fail("--for expects a target");
+      if (!["claude", "codex", "opencode", "all", "none"].includes(target)) {
+        fail(`unknown install target: ${target}`);
+      }
+    } else if (a === "--ref") {
+      ref = rest[++i];
+      if (!ref) fail("--ref expects a version tag (e.g. v0.1.0)");
+    } else {
+      fail(`unknown flag: ${a}`);
+    }
+  }
+
+  const pkg = readPackageJson();
+  const ui = await loadInstallerUi();
+  ui.banner(pkg.version, "update");
+
+  // Upgrade the global install straight from public npm. `@latest` (or a pinned
+  // version) lets npm resolve + verify the tarball — no SAS, no checksum dance.
+  const spec = ref
+    ? `slidemind@${ref.replace(/^v/, "")}`
+    : "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]);
+
+  if (target !== "none") {
+    await spawnInherit("slidemind", ["init", "--for", target]);
+  }
+
+  ui.done(
+    target === "none"
+      ? "updated — skill files unchanged (run 'slidemind init --for all' when ready)"
+      : `updated and redeployed into ${target === "all" ? "all harnesses" : target}`,
+  );
+}
+
+// ---------- main ----------
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    printHelp();
+    return 0;
+  }
+  if (cmd === "--version" || cmd === "-v") {
+    process.stdout.write(`${readPackageJson().version}\n`);
+    return 0;
+  }
+  switch (cmd) {
+    case "build":
+      await cmdBuild(rest);
+      return 0;
+    case "build-pptx":
+      await cmdBuildPptx(rest);
+      return 0;
+    case "search":
+      await cmdSearch(rest);
+      return 0;
+    case "download-bundle":
+      await cmdDownloadBundle(rest);
+      return 0;
+    case "new":
+      await cmdNew(rest);
+      return 0;
+    case "presentations":
+      await cmdPresentations(rest);
+      return 0;
+    case "push":
+      await cmdPush(rest);
+      return 0;
+    case "init":
+    case "install":
+      // Set slidemind up in a coding harness (register the MCP server + skill).
+      // `install` stays as a back-compat alias for the documented `init`.
+      await cmdInstall(rest);
+      return 0;
+    case "uninstall":
+      await cmdUninstall(rest);
+      return 0;
+    case "update":
+    case "upgrade":
+    case "self-update":
+      await cmdUpdate(rest);
+      return 0;
+    default:
+      fail(`unknown command: ${cmd}\nrun 'slidemind --help' for usage`);
+  }
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`slidemind: ${err.message || err}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "slidemind",
+  "version": "0.0.27",
+  "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": {
+    "slidemind": "bin/slidemind.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STATWORX/intern-slidemind-cli.git"
+  },
+  "homepage": "https://github.com/STATWORX/intern-slidemind-cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    ".claude-plugin/",
+    "CLAUDE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node bin/slidemind.mjs build",
+    "build-pptx": "node bin/slidemind.mjs build-pptx",
+    "lint:parity": "node scripts/check-skill-parity.mjs",
+    "release": "node scripts/release.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.5",
+    "@babel/traverse": "^7.26.5",
+    "@babel/types": "^7.26.5",
+    "@clack/prompts": "^1.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.1",
+    "recast": "^0.23.9",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "slides",
+    "presentation",
+    "powerpoint",
+    "pptx",
+    "office-addin",
+    "powerpoint-addin",
+    "slidemind",
+    "claude-code",
+    "claude-plugin",
+    "codex",
+    "opencode",
+    "mcp",
+    "skill"
+  ],
+  "author": "statworx",
+  "license": "UNLICENSED"
+}