slidemind 0.3.12 → 0.3.14

package/src/cli/workspace.mjs

@@ -0,0 +1,302 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fail, requireReviewApproved, LOCAL_PPTX_RE, resolveDecksDir, resolveDeckArg, splitDeckArg, renderProgressPrinter, freshenDeckBundle, loadBridgeModule, SRC_DIR } from "./common.mjs";
+import { readDesignName } from "./designs.mjs";
+
+// `slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]`
+// — reconstruct a local deck workspace from a presentation's deck-embedded
+// source tags (slides authored with slidemind carry their jsx inside the file).
+// Slides with no source are handed to the add-in's deterministic PPTX→JSX
+// conversion route where it is available (`docs/slidemind-cli-connect/
+// 14-foreign-slide-conversion.md`); whatever it declines folds in as native
+// reused .pptx. See also intern-slidemind docs/deck-embedded-source-spec.md.
+export async function cmdAdopt(rest) {
+  const args = [...rest];
+  let deckSlug = null;
+  let brand = null;
+  let convert = true;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--deck") {
+      deckSlug = args[++i] ?? null;
+      if (!deckSlug) fail("--deck expects a deck slug");
+    } else if (a === "--brand") {
+      brand = args[++i] ?? null;
+      if (!brand) fail("--brand expects a design id (presFP)");
+    } else if (a === "--no-convert") {
+      convert = false;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  const pptxArg = positional[0];
+  if (!pptxArg) {
+    fail("usage: slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]");
+  }
+  // v1 is FILE decks only. A presId (or any non-file argument) would mean
+  // converting a LIVE presentation, which needs slide-export and tag-read
+  // events the relay does not have — say so instead of "no such file".
+  const {
+    LIVE_DECK_UNSUPPORTED,
+    adoptDeckFromPptx,
+    convertUntaggedSlides,
+    readSourceDeck,
+  } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "adopt.mjs")).href);
+  if (!LOCAL_PPTX_RE.test(pptxArg)) fail(LIVE_DECK_UNSUPPORTED);
+  const pptxPath = path.resolve(pptxArg);
+  if (!fs.existsSync(pptxPath)) fail(`no such file: ${pptxArg}`);
+  const slug = deckSlug ?? path.basename(pptxPath).replace(/\.pptx$/i, "");
+  // The decks dir, not a hardcoded ./decks — otherwise `adopt` writes where no
+  // other subcommand looks whenever SLIDEMIND_DECKS is set. A RELATIVE slug
+  // must stay inside it (an explicit absolute path is the user's own choice) —
+  // every other untrusted name in this feature is escape-guarded, and this one
+  // rides agent-authored command lines.
+  const decksRoot = path.resolve(resolveDecksDir());
+  const deckDir = path.isAbsolute(slug) ? slug : path.resolve(decksRoot, slug);
+  if (
+    !path.isAbsolute(slug) &&
+    (deckDir === decksRoot || !deckDir.startsWith(decksRoot + path.sep))
+  ) {
+    fail(
+      `--deck '${slug}' escapes the decks directory (${decksRoot}) — ` +
+        "pass an absolute path to adopt somewhere else on purpose",
+    );
+  }
+  // ONE read/unzip/tag-decode of the source file, threaded into both halves —
+  // they must see the same snapshot (and a 40 MB deck decodes slowly).
+  const source = readSourceDeck(pptxPath);
+  const converted = convert
+    ? await convertUntaggedSlides({
+        pptxPath,
+        deckDir,
+        brandId: brand,
+        note: (line) => process.stderr.write(`${line}\n`),
+        source,
+      })
+    : null;
+  const result = adoptDeckFromPptx({ pptxPath, deckDir, converted, source });
+  // A decks dir outside the cwd (SLIDEMIND_DECKS) relativizes to ../../.. noise
+  // — print the absolute path there instead.
+  const shown = path.relative(process.cwd(), deckDir);
+  process.stdout.write(
+    `Adopted ${result.adopted.length} slide(s) with embedded source` +
+      (result.converted.length
+        ? `, converted ${result.converted.length} foreign slide(s) to editable jsx`
+        : "") +
+      (result.native.length
+        ? ` and folded ${result.native.length} untagged slide(s) as native .pptx`
+        : "") +
+      ` into ${shown.startsWith("..") ? deckDir : shown}/.\n` +
+      (result.skipped.length
+        ? `${result.skipped.length} slide(s) stayed native: ` +
+          `${result.skipped
+            .map((s) => `#${s.index ?? "?"} ${s.reason ?? "unknown"}`)
+            .join(", ")}\n`
+        : "") +
+      (result.bundle?.presFP && result.bundle.presFP !== "unknown"
+        ? `Deck bound to bundle ${result.bundle.presFP}.\n`
+        : `No bundle reference found in the file — run 'slidemind download-bundle ${slug}' before rendering.\n`) +
+      `Edit slides/*.jsx and run 'slidemind push ${slug}' or 'slidemind build-pptx ${slug}'.\n`,
+  );
+}
+
+export async function cmdPush(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "push");
+  let to = null;
+  let at = null;
+  let replace = false;
+  let slides = null;
+  let acceptConversions = false;
+  let force = false;
+  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 === "--accept-conversions") {
+      acceptConversions = true;
+    } else if (a === "--force") {
+      force = 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}`);
+  }
+  await requireReviewApproved(deckDir);
+  await freshenDeckBundle(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,
+    acceptConversions,
+    force,
+    onProgress: renderProgressPrinter(),
+  });
+  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`);
+  }
+  if (result.paneSuspended) {
+    process.stdout.write(
+      `The deck rendered, but no PowerPoint window was ready to receive it.\n` +
+        `Open PowerPoint with the slidemind pane (or click the pane once to wake it), ` +
+        `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`,
+  );
+}
+
+export async function cmdNew(rest) {
+  let to = null;
+  let brand = null;
+  let noBind = 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 === "--brand") {
+      brand = rest[++i];
+      if (!brand) fail("--brand expects a design id (presFP)");
+    } else if (a === "--no-bind") {
+      noBind = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (brand && to) {
+    fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
+  }
+  const name = positional[0];
+  if (!name) fail("usage: slidemind new <name> [--brand <presFP> | --to <presId>] [--no-bind]");
+  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` +
+      `as NN-<topic>.jsx (zero-padded prefix — slide order is filename order).\n`,
+  );
+  process.stdout.write(`Created ${path.relative(process.cwd(), deckDir)}\n`);
+  process.stdout.write(
+    `Next: ask your agent to author "${name}", then \`slidemind view-draft ${name}\`\n`,
+  );
+
+  // Stateless auto-bind: bind the fresh deck to whatever design is OPEN so the
+  // agent skips a follow-up `download-bundle`. Best-effort — a bind miss (no
+  // host, ambiguous designs, bundle not yet materialized, any network error)
+  // NEVER fails the scaffold; it just drops a soft hint. Fully offline when
+  // unpaired: no network attempted, no hint. `--no-bind` opts out entirely.
+  if (noBind) return;
+  const cfg = await loadBridgeModule("config");
+  if (cfg.readSessions().length === 0) return;
+  let boundMsg = null;
+  // --brand: the user picked a design (the Clarify question) — bind to THAT,
+  // never to whatever window happens to be open. Cache-only, so it needs the
+  // bundle `ready` already materialized; a miss names the command that does.
+  if (brand) {
+    const bundle = await loadBridgeModule("bundle");
+    const meta = bundle.readMaterializedBundleMeta(brand);
+    if (!meta?.presFP) {
+      process.stdout.write(
+        `not bound — design '${brand}' is not materialized here; run \`slidemind ready ${name} --brand ${brand}\`\n`,
+      );
+      return;
+    }
+    bundle.writeDeckBundleRef(deckDir, { presFP: meta.presFP, etag: meta.etag ?? null });
+    const label = readDesignName(bundle.bundleDirForPresFP(meta.presFP)) ?? meta.presFP;
+    process.stdout.write(`bound to design ${label}\n`);
+    return;
+  }
+  try {
+    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 { presentations } = await client.listOpenPresentationsDetailed();
+    const resolution = client.resolveDesignSource(presentations, {
+      explicitPresId: to,
+    });
+    // The same order as ready: the one design open, else the one design
+    // cached here. (No liveness ping — a zombie's false ambiguity just leaves
+    // the deck unbound, and `ready <name>` prunes it.)
+    const cached = bundle.listCachedBundles();
+    const presFP =
+      resolution.status === "resolved"
+        ? resolution.entry.brandId
+        : resolution.status === "none" && !to && cached.length === 1
+          ? cached[0].presFP
+          : null;
+    if (presFP) {
+      const meta = bundle.readMaterializedBundleMeta(presFP);
+      if (meta?.presFP) {
+        bundle.writeDeckBundleRef(deckDir, {
+          presFP: meta.presFP,
+          etag: meta.etag ?? null,
+        });
+        const label =
+          readDesignName(bundle.bundleDirForPresFP(meta.presFP)) ?? meta.presFP;
+        boundMsg = `bound to design ${label}`;
+      }
+    }
+  } catch {
+    /* best-effort — fall through to the soft hint */
+  }
+  process.stdout.write(
+    boundMsg
+      ? `${boundMsg}\n`
+      : `UNBOUND — ${name} has no corporate design yet, so every render would need an open window. ` +
+        `Bind it: \`slidemind ready ${name}\` (one design at hand) or \`slidemind ready ${name} --brand <presFP>\` (pick from \`slidemind ls designs\`).\n`,
+  );
+}

package/src/installers/codex.mjs

@@ -160,7 +160,7 @@ function writeAgentsBlock() {
     `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` +
+    `Build with: \`slidemind view-draft <deck>\` (draft PNGs) or \`slidemind build-pptx <deck>\` (PPTX).\n` +
     `${AGENTS_MARK_END}\n`;
 
   const file = agentsFile();

package/src/update-check.mjs

@@ -0,0 +1,231 @@
+// "Your slidemind is out of date" — the nudge, and the background self-update.
+//
+// The add-in's version floor (`x-slidemind-min-cli`) only fires once a CLI is
+// too old for the backend to talk to it at all: by then the user is hard
+// blocked. This is the softer, earlier signal — a plain npm dist-tag check
+// against the registry, so a user or an agent learns about a release the day it
+// lands instead of on the next breaking floor bump.
+//
+// Cost control: the registry is contacted at most once per interval (default
+// 6h) per config dir; every other run reads the cached answer off disk (a few
+// hundred microseconds). The check runs AFTER the command has finished, so it
+// never delays real work and a background `npm install -g` can never swap the
+// package directory out from under a running command.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareCliVersions } from "./bridge/client.mjs";
+import { sessionConfigDir } from "./bridge/config.mjs";
+import { isClaudePluginInstall, updateCliInstruction } from "./install-channel.mjs";
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+// Commands that either ARE the update, or are about to install a fresh copy
+// anyway. Nudging inside them is noise at best and contradictory at worst.
+const SKIP_COMMANDS = new Set([
+  "update",
+  "upgrade",
+  "self-update",
+  "setup",
+  "init",
+  "install",
+  "uninstall",
+]);
+
+function intervalMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_UPDATE_CHECK_INTERVAL_MS || "", 10) ||
+    6 * 60 * 60 * 1000
+  );
+}
+
+function registryUrl() {
+  return (
+    process.env.SLIDEMIND_REGISTRY_URL ||
+    "https://registry.npmjs.org/slidemind/latest"
+  );
+}
+
+function cachePath() {
+  return path.join(sessionConfigDir(), "update-check.json");
+}
+
+function readCache() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(cachePath(), "utf8"));
+    return raw && typeof raw === "object" ? raw : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeCache(next) {
+  try {
+    fs.mkdirSync(sessionConfigDir(), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify(next, null, 2) + "\n");
+  } catch {
+    // A read-only or unwritable config dir just means we re-check next run.
+  }
+}
+
+// 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.
+export 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
+}
+
+// npx runs the package straight out of its own cache and is expected to be
+// throwaway — a global install from inside one would surprise the user and
+// would not change what the next `npx slidemind@latest` runs.
+function isNpxRun(root = PACKAGE_ROOT) {
+  return path.resolve(root).split(/[\\/]+/).includes("_npx");
+}
+
+// Who can actually replace THIS binary?
+//   npm    — a background `npm install -g slidemind@latest` does it
+//   plugin — only `/plugin`; a global install lands a second, unused copy
+//   npx    — nobody; the next npx invocation resolves its own version
+//   dev    — a checkout (`npm link`): an install would REPLACE the developer's
+//            symlink with the registry copy, so this channel is never nudged
+export function updateChannel() {
+  if (fs.existsSync(path.join(PACKAGE_ROOT, ".git"))) return "dev";
+  if (isClaudePluginInstall()) return "plugin";
+  if (isNpxRun()) return "npx";
+  return "npm";
+}
+
+function autoUpdateEnabled(channel) {
+  if (channel !== "npm") return false;
+  if (process.env.SLIDEMIND_NO_AUTO_UPDATE) return false;
+  if (process.env.CI) return false;
+  return true;
+}
+
+// The message, as one pure function — everything above it decides WHETHER to
+// call it, this decides WHAT it says. `auto` is what we actually kicked off.
+export function updateNotice({ current, latest, channel, auto, stalled }) {
+  if (!latest || compareCliVersions(current, latest) >= 0) return null;
+  const head = `slidemind ${current} is out of date — ${latest} is on npm.`;
+  if (stalled) {
+    return (
+      `${head} A background auto-update to ${latest} was started earlier but this ` +
+      `binary is still ${current} — ${updateCliInstruction()}`
+    );
+  }
+  if (auto) {
+    return `${head} Updating in the background — the next \`slidemind\` run uses ${latest}.`;
+  }
+  return `${head} ${updateCliInstruction()}`;
+}
+
+async function fetchLatestVersion() {
+  try {
+    const res = await fetch(registryUrl(), {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(
+        parseInt(process.env.SLIDEMIND_UPDATE_CHECK_TIMEOUT_MS || "", 10) || 2000,
+      ),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body?.version === "string" ? body.version : null;
+  } catch {
+    return null; // offline, blocked, slow — never a reason to bother the user
+  }
+}
+
+function startBackgroundUpdate(latest) {
+  const logPath = path.join(sessionConfigDir(), "update.log");
+  let out = "ignore";
+  try {
+    fs.mkdirSync(sessionConfigDir(), { recursive: true });
+    out = fs.openSync(logPath, "a");
+    fs.writeSync(out, `\n[${new Date().toISOString()}] auto-update -> ${latest}\n`);
+  } catch {
+    out = "ignore";
+  }
+  try {
+    const child = spawn(
+      npmBin(),
+      ["install", "-g", "--loglevel=error", "slidemind@latest"],
+      { detached: true, stdio: ["ignore", out, out] },
+    );
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Called once, after the command has run. Never throws, never blocks longer
+// than the fetch timeout, and writes only to stderr so `--json` stdout payloads
+// stay clean.
+//
+// `force` is set when the command just hit the add-in's version floor
+// (`cli_update_required`): the cached registry answer may predate the release
+// that raised the floor, so re-fetch now and re-attempt the auto-update even
+// if one was already tried for this version.
+export async function announceUpdate({ command, current, force = false }) {
+  try {
+    if (process.env.SLIDEMIND_NO_UPDATE_CHECK) return;
+    if (!command || SKIP_COMMANDS.has(command)) return;
+
+    const channel = updateChannel();
+    // A checkout is never auto-updated or nudged (it would clobber `npm link`);
+    // SLIDEMIND_UPDATE_CHECK=1 forces the path on so the suite can drive it.
+    if (channel === "dev" && !process.env.SLIDEMIND_UPDATE_CHECK) return;
+
+    const cache = readCache();
+    let latest = typeof cache.latest === "string" ? cache.latest : null;
+    if (force || Date.now() - (Number(cache.checkedAt) || 0) > intervalMs()) {
+      const fetched = await fetchLatestVersion();
+      latest = fetched ?? latest;
+      writeCache({ ...cache, checkedAt: Date.now(), latest });
+    }
+    if (!latest || compareCliVersions(current, latest) >= 0) return;
+
+    // One auto-update attempt per released version per interval: if the install
+    // failed (a root-owned npm prefix is the usual reason) we must not respawn
+    // it on every single command — we say so instead.
+    const prior = cache.autoUpdate;
+    const attempted =
+      !force &&
+      prior?.version === latest &&
+      Date.now() - (Number(prior.at) || 0) < intervalMs();
+    let auto = false;
+    if (autoUpdateEnabled(channel) && !attempted) {
+      auto = startBackgroundUpdate(latest);
+      if (auto) {
+        writeCache({
+          ...readCache(),
+          autoUpdate: { version: latest, at: Date.now() },
+        });
+      }
+    }
+
+    const notice = updateNotice({
+      current,
+      latest,
+      channel,
+      auto,
+      stalled: attempted,
+    });
+    if (notice) process.stderr.write(`slidemind: ${notice}\n`);
+  } catch {
+    // An update nudge must never be the thing that fails a command.
+  }
+}