slidemind 0.2.1 → 0.2.3

package/bin/slidemind.mjs

@@ -2,6 +2,9 @@
 // slidemind — single CLI entry point for the slidemind npm package.
 //
 // Subcommands:
+//   slidemind setup <claim>           one-command onboarding from the add-in's
+//                                       "Connect CLI" button: connect + global
+//                                       install + skills + ready (run via npx)
 //   slidemind init [--for <target>]   set up slidemind in a coding harness
 //                                       (deploy the skill);
 //                                       targets: claude | codex | opencode | all
@@ -52,8 +55,17 @@ function printHelp() {
     `slidemind ${pkg.version} — drive the slidemind PowerPoint add-in to build native, on-brand decks\n` +
       `\n` +
       `Usage:\n` +
+      `  slidemind setup <claim>          One-command onboarding. Copy the command from PowerPoint →\n` +
+      `                                     slidemind → Settings → General → Connect CLI and paste it:\n` +
+      `                                     it connects this machine, installs slidemind globally, deploys\n` +
+      `                                     the skills, and runs 'ready'. Designed for 'npx slidemind@latest'.\n` +
+      `                                     --for <target>  harness to deploy skills into (default: auto — every\n` +
+      `                                                     coding agent found on this machine; none to skip)\n` +
+      `                                     --no-install    skip the global npm install (already installed)\n` +
+      `                                     --no-ready      skip the closing readiness check\n` +
+      `                                     --json          machine-readable result\n` +
       `  slidemind ready [deck]           One-command session setup — run this FIRST each session.\n` +
-      `                                     Verifies pairing/connection/CLI version, resolves the open\n` +
+      `                                     Verifies authorization/connection/CLI version, resolves the open\n` +
       `                                     design, materializes its bundle, and (with a deck) binds it.\n` +
       `                                     Exit 0 = ready; non-zero prints one actionable blocker.\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
@@ -132,7 +144,7 @@ function printHelp() {
       `                                     --force         re-download even if the cached bundle is current\n` +
       `  slidemind presentations          List active PowerPoint panes registered with the add-in\n` +
       `                                     --all          include retained suspended entries\n` +
-      `  slidemind doctor                 Diagnose CLI/add-in pairing, backend, and pane readiness\n` +
+      `  slidemind doctor                 Diagnose CLI/add-in authorization, backend, and pane readiness\n` +
       `                                     --json          print machine-readable status\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` +
@@ -144,13 +156,12 @@ 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` +
-      `                                     --label <name>  name this environment (default: derived from URL)\n` +
-      `                                   Pair once per environment; commands fan out across all of them.\n` +
-      `  slidemind whoami                 Show every paired environment (* = default)\n` +
+      `  slidemind whoami                 Show every connected environment (* = default)\n` +
       `  slidemind use <url|env>          Set the default environment\n` +
       `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
       `  slidemind init --for <t>         Set up slidemind in a harness (deploys the skill; clears the bundle cache)\n` +
+      `                                     <t> = claude | codex | opencode | all | auto (every harness found here)\n` +
+      `                                     'setup' already does this — only needed after installing a new agent\n` +
       `  slidemind uninstall --for <t>    Remove a previously-installed skill (clears the bundle cache)\n` +
       `  slidemind update [--for <t>]     Fetch the latest release and redeploy\n` +
       `                                     --for <t>     harness to redeploy into (default: all)\n` +
@@ -468,6 +479,13 @@ async function cmdBuildPptx(rest) {
       deckDir,
       locale: skill.locale ?? "en",
       srcDir: SRC_DIR,
+      // Both are the PACK's contract, read from its skill.json — this CLI
+      // knows no layout names and no template-fixed titles of its own.
+      components: {
+        ...(skill.manifest?.components ?? {}),
+        skillDir: skill.skillDir,
+      },
+      policy: skill.manifest?.policy ?? {},
       onLog: (line) => process.stdout.write(`  ${line}\n`),
     });
     for (const w of ff.warnings) process.stderr.write(`  warning: ${w}\n`);
@@ -1799,7 +1817,7 @@ function connectionBlocker(pub) {
       code: "not_paired",
       actor: "user",
       message:
-        "Not paired. In the add-in open Settings → General → Connect CLI, press Pair, then run the shown `slidemind pair <code>`.",
+        "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.",
     };
   }
   if ((pub.backends ?? []).every((b) => !b.ok)) {
@@ -1869,6 +1887,226 @@ function connectionNextAction(pub) {
   return connectionBlocker(pub)?.message ?? "Ready.";
 }
 
+// ---------- one-command setup (npx bootstrap) ----------
+//
+// `npx --yes slidemind@latest setup <claim>` is the whole onboarding: the user
+// clicks "Connect CLI" in the add-in, pastes ONE command, and ends up with a
+// connected, globally-installed CLI. npx only runs the package from its cache —
+// it never installs it — so this command performs the persistent
+// `npm install -g` itself.
+//
+// Order matters: redeem FIRST. The claim is short-lived and one-time, while a
+// global npm install can take a while or hit an EACCES prefix problem. Spending
+// the claim up front means a failed install leaves a connected CLI the user can
+// fix at their leisure, instead of forcing them back to PowerPoint for a fresh
+// command.
+async function cmdSetup(rest) {
+  let claimArg = null;
+  // `auto` is the whole point: setup finishes onboarding by itself, so it
+  // deploys into the coding agents this machine actually has instead of asking
+  // the user to run `init` afterwards.
+  let target = "auto";
+  let doInstall = true;
+  let doReady = true;
+  let asJson = false;
+  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 (![...HARNESS_TARGETS, "all", "auto", "none"].includes(target)) {
+        fail(`unknown install target: ${target}`);
+      }
+    } else if (a === "--no-install") {
+      doInstall = false;
+    } else if (a === "--no-ready") {
+      doReady = false;
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else if (claimArg === null) {
+      claimArg = a;
+    } else {
+      fail("setup takes exactly one setup claim");
+    }
+  }
+
+  if (!claimArg) {
+    fail(
+      "setup needs the connection command from the add-in.\n" +
+        "  Open PowerPoint → slidemind → Settings → General → Connect CLI, copy the command, and paste it here.\n" +
+        "  Already have the CLI? The panel's `CLI already installed?` toggle gives the short `slidemind setup …` form.",
+    );
+  }
+
+  const pkg = readPackageJson();
+  const claims = await loadBridgeModule("setup-claim");
+  // Decode before any UI so a mistyped/partial paste fails in one clean line.
+  const { backendURL, secret } = claims.decodeSetupClaim(claimArg);
+  const cfg = await loadBridgeModule("config");
+  const envLabel = cfg.deriveEnvLabel(backendURL);
+
+  // The installers paint their own progress rail. In --json mode stdout is
+  // reserved for the payload, so silence the whole UI rather than letting it
+  // corrupt what the caller parses.
+  const ui = await loadInstallerUi();
+  if (asJson) ui.silence();
+  ui.banner(pkg.version, "setup");
+
+  // --- 1. spend the claim -------------------------------------------------
+  await ui.section("connect", envLabel);
+  const sessionToken = await claims.redeemSetupClaim({
+    backendURL,
+    secret,
+    cliVersion: pkg.version,
+  });
+  cfg.upsertSession({ backendURL, sessionToken, label: envLabel });
+  ui.step({ label: "authorize", value: envLabel, note: "session saved" });
+
+  // --- 2. make this CLI permanent ----------------------------------------
+  // Without this the whole thing evaporates with npx's cache: the user would be
+  // connected but have no `slidemind` on PATH.
+  let installed = false;
+  let installError = null;
+  const pluginInstall = isClaudePluginInstall();
+  if (doInstall && pluginInstall) {
+    ui.step({
+      status: "warn",
+      label: "install",
+      value: "skipped",
+      note: "this slidemind came from the Claude Code plugin — update it with /plugin",
+    });
+  } else if (doInstall) {
+    await ui.section("install", "npm global");
+    ui.step({ label: "install", value: "slidemind@latest", note: "global (npm)" });
+    try {
+      await spawnInherit(npmBin(), [
+        "install",
+        "-g",
+        "--loglevel=error",
+        "slidemind@latest",
+      ]);
+      installed = true;
+    } catch (err) {
+      installError = err?.message || String(err);
+      ui.step({
+        status: "warn",
+        label: "install",
+        value: "failed",
+        note: "the connection is saved — see the note below",
+      });
+    }
+  }
+
+  // --- 3. deploy the skills ----------------------------------------------
+  // In-process, from THIS package copy: the npx copy and the global install are
+  // the same published version, and going through PATH here would fail on a
+  // shell that has not rehashed yet.
+  //
+  // With the default `auto` this is what removes `slidemind init` from
+  // onboarding: the skills land in every coding agent present on the machine,
+  // and skip any whose plugin already supplies them (copying over a plugin's
+  // skills plants a second set that drifts on the next plugin update).
+  let skills = [];
+  let skippedPlugins = [];
+  if (target !== "none") {
+    if (target === "auto") {
+      const harnesses = await detectHarnesses();
+      skippedPlugins = harnesses
+        .filter((h) => h.present && h.pluginInstalled)
+        .map((h) => h.target);
+    }
+    await ui.section(
+      "skills",
+      target === "auto"
+        ? "detected harnesses"
+        : target === "all"
+          ? "all harnesses"
+          : target,
+    );
+    skills = await runInstaller(target, "install", []);
+    for (const t of skippedPlugins) {
+      ui.step({
+        status: "warn",
+        label: t,
+        value: "skipped",
+        note: "its slidemind plugin already supplies the skills",
+      });
+    }
+    if (skills.length === 0 && skippedPlugins.length === 0) {
+      ui.step({
+        status: "warn",
+        label: "harnesses",
+        value: "none detected",
+        note: "install a coding agent, then run `slidemind init --for auto`",
+      });
+    }
+    const bundleMod = await loadBridgeModule("bundle");
+    bundleMod.clearBundleCache();
+  }
+
+  if (asJson) {
+    const globalInstall =
+      doInstall && !pluginInstall
+        ? installed
+          ? "installed"
+          : "failed"
+        : "skipped";
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          connected: true,
+          env: envLabel,
+          globalInstall,
+          skills,
+          // Present-but-plugin-served harnesses, so an agent can tell "nothing
+          // deployed because nothing is installed" from "nothing needed".
+          skippedPlugins,
+          nextAction: "slidemind ready",
+          // Only on the unhappy path: the session IS saved, so `ok` stays true,
+          // but an agent needs to know the binary did not land.
+          ...(installError ? { installError } : {}),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+
+  ui.done(
+    target === "none" || (skills.length === 0 && skippedPlugins.length === 0)
+      ? `connected to ${envLabel} — run 'slidemind ready' to start`
+      : `connected to ${envLabel} and ready to use`,
+  );
+
+  if (installError) {
+    process.stderr.write(
+      "\nslidemind is connected, but the global install 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" +
+        `(details: ${installError})\n`,
+    );
+    return;
+  }
+
+  // --- 4. finish the session the user actually came for -------------------
+  // `ready` exits non-zero for every legitimate not-yet blocker (PowerPoint
+  // closed, no design activated). Setup already succeeded at that point, so its
+  // blocker is information, not a failure — run it for the message and the
+  // warmed bundle, and never inherit its exit code.
+  if (doReady) {
+    await spawnStatus(process.execPath, [__filename, "ready"]);
+  }
+}
+
 // The one-command agent preflight. Collapses the old 4-call session start
 // (presentations → pick → download-bundle → download-bundle-to-bind) into a
 // single verb: check pairing/reachability/CLI-version/windows, resolve the OPEN
@@ -1947,10 +2185,20 @@ async function cmdReady(rest) {
     fail(blocker.message);
   };
 
-  // --- Local: not paired short-circuits before any network. ---
+  // --- First use: there is nothing this process can do on its own. Connecting
+  // starts in the add-in because the claim it mints carries the deployment's
+  // address, and an unconnected CLI has no way to learn which backend its user
+  // belongs to. So name the one action that works and stop. ---
   const cfg = await loadBridgeModule("config");
   if (cfg.readSessions().length === 0) {
-    finishBlocker({ blocker: connectionBlocker({ paired: false }) });
+    finishBlocker({
+      blocker: {
+        code: "not_connected",
+        actor: "user",
+        message:
+          "Connect this CLI first: in PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, copy the command it shows, and run it here.",
+      },
+    });
     return;
   }
 
@@ -2449,93 +2697,23 @@ async function loadBridgeModule(name) {
   return import(pathToFileURL(path.join(SRC_DIR, "bridge", `${name}.mjs`)).href);
 }
 
-async function cmdPair(rest) {
-  let code = null;
-  let label = null;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a === "--label") {
-      label = rest[++i];
-      if (!label) fail("--label expects a name");
-    } else if (!a.startsWith("--") && !code) {
-      code = a;
-    }
-  }
-  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");
-  const sessions = cfg.upsertSession({
-    backendURL: decoded.backendURL,
-    sessionToken: res.json.sessionToken,
-    label,
-  });
-  const env = cfg.deriveEnvLabel(decoded.backendURL);
-  const others = sessions.length - 1;
-  const suffix =
-    others > 0
-      ? ` (${sessions.length} environments connected — commands now fan out across all of them)`
-      : "";
-  let verify = "";
-  try {
-    const client = await import(
-      pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
-    );
-    const deadline = Date.now() + 8000;
-    for (;;) {
-      const status = await client.connectionStatus();
-      if ((status.presentations ?? []).length > 0) {
-        verify = " Pane is registered.";
-        break;
-      }
-      if (Date.now() >= deadline) {
-        verify =
-          " No pane is registered yet; if PowerPoint is already open, reopen or click the slidemind task pane, then run 'slidemind doctor'.";
-        break;
-      }
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-    }
-  } catch {
-    // Pairing itself succeeded; diagnostics remain available via doctor.
-  }
-  process.stdout.write(
-    `Paired with ${label || env}${suffix}.${verify} Run 'slidemind doctor' to verify.\n`,
-  );
-}
-
 async function cmdWhoami() {
   const cfg = await loadBridgeModule("config");
   const sessions = cfg.readSessions();
   if (sessions.length === 0) {
     process.stderr.write(
-      'Not paired. Run `slidemind pair <code>` using the add-in\'s "Connect CLI".\n',
+      "Not connected. In PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, and run the command it shows.\n",
     );
     return;
   }
-  const pairMod = await loadBridgeModule("pair");
+  const { httpJson } = await loadBridgeModule("http-json");
   const def = cfg.getDefaultBackend();
   const lines = await Promise.all(
     sessions.map(async (s) => {
       const marker = s.backendURL === def ? "*" : " ";
       let detail;
       try {
-        const res = await pairMod.httpJson(
+        const res = await httpJson(
           "GET",
           `${s.backendURL}/api/cli/whoami`,
           { token: s.sessionToken },
@@ -2543,15 +2721,15 @@ async function cmdWhoami() {
         detail =
           res.status === 200 && res.json
             ? `user ${res.json.oid} · tenant ${res.json.tid ?? "(n/a)"}`
-            : `session invalid (${res.status}) — re-pair`;
+            : `session invalid (${res.status}) — authorize again`;
       } catch {
-        detail = "unreachable — check your connection or re-pair";
+        detail = "unreachable — check your connection or authorize again";
       }
       return `${marker} ${s.label}\n    ${detail}`;
     }),
   );
   process.stdout.write(
-    `Paired environments (${sessions.length}):\n${lines.join("\n")}\n`,
+    `Connected environments (${sessions.length}):\n${lines.join("\n")}\n`,
   );
 }
 
@@ -2586,10 +2764,10 @@ async function cmdLogout(rest) {
     toRemove = sessions.filter((s) => s.backendURL === def);
   }
 
-  const pairMod = await loadBridgeModule("pair");
+  const { httpJson } = await loadBridgeModule("http-json");
   for (const s of toRemove) {
     try {
-      await pairMod.httpJson("POST", `${s.backendURL}/api/cli/logout`, {
+      await httpJson("POST", `${s.backendURL}/api/cli/logout`, {
         token: s.sessionToken,
       });
     } catch {
@@ -2600,7 +2778,7 @@ async function cmdLogout(rest) {
   const remaining = cfg.readSessions().length;
   process.stdout.write(
     `Logged out of ${toRemove.map((s) => s.label).join(", ")}.` +
-      (remaining > 0 ? ` ${remaining} environment(s) still paired.\n` : "\n"),
+      (remaining > 0 ? ` ${remaining} environment(s) still connected.\n` : "\n"),
   );
 }
 
@@ -2778,20 +2956,56 @@ async function cmdNew(rest) {
   );
 }
 
-function parseTargetFlag(rest) {
+const HARNESS_TARGETS = ["claude", "codex", "opencode"];
+
+function parseTargetFlag(rest, { allowAuto = false } = {}) {
   const idx = rest.findIndex((a) => a === "--for" || a === "-f");
   if (idx < 0 || !rest[idx + 1]) {
-    fail("missing --for <claude|codex|opencode|all>");
+    fail(
+      `missing --for <claude|codex|opencode|all${allowAuto ? "|auto" : ""}>`,
+    );
   }
   const target = rest[idx + 1];
-  if (!["claude", "codex", "opencode", "all"].includes(target)) {
+  const allowed = allowAuto
+    ? [...HARNESS_TARGETS, "all", "auto"]
+    : [...HARNESS_TARGETS, "all"];
+  if (!allowed.includes(target)) {
     fail(`unknown install target: ${target}`);
   }
   return target;
 }
 
+// Which coding agents are actually on this machine, and which of them already
+// get their skills from a plugin. This is what lets `slidemind setup` finish the
+// job on its own: it deploys where a harness exists and stays out of the way
+// where a plugin already supplies the skills, so a separate `init` is no longer
+// part of onboarding.
+async function detectHarnesses() {
+  const found = [];
+  for (const target of HARNESS_TARGETS) {
+    const mod = await import(
+      pathToFileURL(path.join(INSTALLERS_DIR, `${target}.mjs`)).href
+    );
+    const info =
+      typeof mod.detect === "function"
+        ? mod.detect()
+        : { present: false, pluginInstalled: false, root: null };
+    found.push({ target, ...info });
+  }
+  return found;
+}
+
+/** Expand a `--for` value into the concrete harness list to act on. */
+async function resolveInstallTargets(target) {
+  if (target === "all") return [...HARNESS_TARGETS];
+  if (target !== "auto") return [target];
+  return (await detectHarnesses())
+    .filter((h) => h.present && !h.pluginInstalled)
+    .map((h) => h.target);
+}
+
 async function runInstaller(target, action, rest) {
-  const targets = target === "all" ? ["claude", "codex", "opencode"] : [target];
+  const targets = await resolveInstallTargets(target);
   for (const t of targets) {
     const mod = await import(
       pathToFileURL(path.join(INSTALLERS_DIR, `${t}.mjs`)).href
@@ -2805,6 +3019,7 @@ async function runInstaller(target, action, rest) {
       flags: rest,
     });
   }
+  return targets;
 }
 
 async function loadInstallerUi() {
@@ -2815,10 +3030,18 @@ async function loadInstallerUi() {
 }
 
 async function cmdInstall(rest) {
-  const target = parseTargetFlag(rest);
+  const target = parseTargetFlag(rest, { allowAuto: true });
   const ui = await loadInstallerUi();
   ui.banner(readPackageJson().version, "init");
-  await runInstaller(target, "install", rest);
+  const deployed = await runInstaller(target, "install", rest);
+  if (deployed.length === 0) {
+    ui.step({
+      status: "warn",
+      label: "harnesses",
+      value: "none detected",
+      note: "install a coding agent, then rerun with --for <claude|codex|opencode>",
+    });
+  }
 
   // Force every design bundle to re-download from the add-in on the next
   // build/push/download by wiping the materialized cache. init is the
@@ -2836,9 +3059,11 @@ async function cmdInstall(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`,
+    deployed.length === 0
+      ? "no coding agent found — the CLI is installed, skills are not"
+      : deployed.length === HARNESS_TARGETS.length
+        ? "ready — ask your agent to plan, create, or edit a deck"
+        : `ready — ${deployed.join(", ")} can now plan, create, or edit decks`,
   );
 }
 
@@ -2893,6 +3118,16 @@ function spawnInherit(file, args) {
   });
 }
 
+// Like spawnInherit, but resolves with the child's exit code instead of
+// rejecting — for a step whose failure is a message to the user rather than a
+// failure of the command that ran it (see `setup` → `ready`).
+function spawnStatus(file, args) {
+  return spawnInherit(file, args).then(
+    () => 0,
+    () => 1,
+  );
+}
+
 // ---------- distribution (public npm) ----------
 //
 // slidemind is published to public npm as `slidemind`. First install is
@@ -3063,12 +3298,12 @@ async function main(rawArgv) {
     case "ready":
       await cmdReady(rest);
       return 0;
+    case "setup":
+      await cmdSetup(rest);
+      return 0;
     case "new":
       await cmdNew(rest);
       return 0;
-    case "pair":
-      await cmdPair(rest);
-      break;
     case "whoami":
       await cmdWhoami(rest);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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": {
@@ -20,7 +20,9 @@
     "skills/",
     ".claude-plugin/",
     ".codex-plugin/",
-    "CLAUDE.md",
+    ".agents/plugins/",
+    "assets/",
+    "AGENTS.md",
     "README.md"
   ],
   "scripts": {