slidemind 0.0.27

package/src/installers/codex.mjs

@@ -0,0 +1,229 @@
+// Install slidemind into OpenAI Codex.
+//
+// Codex 0.128+ auto-discovers skills at `$CODEX_HOME/skills/<name>/SKILL.md`
+// (mirroring Claude Code at `~/.claude/skills/<name>/SKILL.md`). It loads the
+// frontmatter `description` to decide when to surface them. We:
+//
+//   1. Copy each skill to `~/.codex/skills/slidemind-<skill>/` so codex picks
+//      it up natively. The `slidemind-` prefix namespaces our skills and
+//      matches the convention used by the Claude installer.
+//   2. Append a slidemind block to `~/.codex/AGENTS.md` documenting the
+//      skill name so the agent has a reliable handle.
+//
+// We do NOT install custom prompts to `~/.codex/prompts/` because:
+//   - they are officially deprecated in favour of skills, AND
+//   - they are broken in codex 0.117+ — see openai/codex#15941. The prompt
+//     files land on disk but never appear in the `/prompts:` menu.
+// Past installs may have left stale `slidemind-*.md` files there; we wipe
+// them on every install/uninstall.
+//
+// Earlier versions installed the skill payload at `~/.codex/slidemind/` which
+// Codex never scanned. We delete that legacy directory on every install so
+// upgraders converge to the correct layout.
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  expandHome,
+  installDir,
+  isForce,
+  isLinkMode,
+  listSkills,
+  rmIfExists,
+  ui,
+} from "./lib.mjs";
+
+const NAMESPACE = "slidemind";
+const AGENTS_MARK_BEGIN = "<!-- slidemind:begin -->";
+const AGENTS_MARK_END = "<!-- slidemind:end -->";
+const TOML_MARK_BEGIN = "# slidemind:begin";
+const TOML_MARK_END = "# slidemind:end";
+
+function codexRoot() {
+  return expandHome("~/.codex");
+}
+
+function promptsDir() {
+  return path.join(codexRoot(), "prompts");
+}
+
+// Sweep every ~/.codex/prompts/slidemind-*.md a past install left behind.
+function removeStalePrompts() {
+  const dir = promptsDir();
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    if (entry.startsWith(`${NAMESPACE}-`) && entry.endsWith(".md")) {
+      const target = path.join(dir, entry);
+      rmIfExists(target);
+      ui.step({ status: "remove", label: "stale prompt", value: target });
+    }
+  }
+}
+
+function skillsRoot() {
+  return path.join(codexRoot(), "skills");
+}
+
+function skillTarget(skillName) {
+  return path.join(skillsRoot(), `${NAMESPACE}-${skillName}`);
+}
+
+// Pre-0.128 install layout. Removed on every install/uninstall.
+function legacySkillsRoot() {
+  return path.join(codexRoot(), NAMESPACE);
+}
+
+function agentsFile() {
+  return path.join(codexRoot(), "AGENTS.md");
+}
+
+function configTomlFile() {
+  return path.join(codexRoot(), "config.toml");
+}
+
+function writeMcpServerBlock(packageRoot) {
+  const mcpServer = path.join(packageRoot, "src", "mcp", "server.mjs");
+  const block =
+    `${TOML_MARK_BEGIN}\n` +
+    `[mcp_servers.slidemind]\n` +
+    `command = "node"\n` +
+    `args = ["${mcpServer.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n` +
+    `${TOML_MARK_END}\n`;
+
+  const file = configTomlFile();
+  let existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const re = new RegExp(
+    `${TOML_MARK_BEGIN}[\\s\\S]*?${TOML_MARK_END}\\n?`,
+    "g",
+  );
+  if (re.test(existing)) {
+    existing = existing.replace(re, "");
+  }
+  const sep = existing.length && !existing.endsWith("\n") ? "\n\n" : existing.length ? "\n" : "";
+  fs.writeFileSync(file, existing + sep + block);
+}
+
+function clearMcpServerBlock() {
+  const file = configTomlFile();
+  if (!fs.existsSync(file)) return;
+  let existing = fs.readFileSync(file, "utf8");
+  const re = new RegExp(
+    `${TOML_MARK_BEGIN}[\\s\\S]*?${TOML_MARK_END}\\n?`,
+    "g",
+  );
+  existing = existing.replace(re, "");
+  fs.writeFileSync(file, existing);
+}
+
+function writeAgentsBlock() {
+  const block =
+    `${AGENTS_MARK_BEGIN}\n` +
+    `## slidemind\n` +
+    `Slide-deck authoring skill installed via slidemind.\n` +
+    `\n` +
+    `When the user asks to create, plan, or edit a slide deck or presentation, load\n` +
+    `the \`slidemind-create-slides\` skill (auto-discovered from\n` +
+    `${skillTarget("create-slides")}/SKILL.md) and follow it. The skill drives the\n` +
+    `slidemind PowerPoint add-in and reads every brand rule — tokens, layout\n` +
+    `palette, brand imagery — from the design bundle the add-in serves.\n` +
+    `\n` +
+    `Build with: \`slidemind build <deck>\` (HTML) or \`slidemind build-pptx <deck>\` (PPTX).\n` +
+    `${AGENTS_MARK_END}\n`;
+
+  const file = agentsFile();
+  let existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const re = new RegExp(
+    `${AGENTS_MARK_BEGIN}[\\s\\S]*?${AGENTS_MARK_END}\\n?`,
+    "g",
+  );
+  if (re.test(existing)) {
+    existing = existing.replace(re, "");
+  }
+  const sep = existing.length && !existing.endsWith("\n") ? "\n\n" : existing.length ? "\n" : "";
+  fs.writeFileSync(file, existing + sep + block);
+}
+
+function clearAgentsBlock() {
+  const file = agentsFile();
+  if (!fs.existsSync(file)) return;
+  let existing = fs.readFileSync(file, "utf8");
+  const re = new RegExp(
+    `${AGENTS_MARK_BEGIN}[\\s\\S]*?${AGENTS_MARK_END}\\n?`,
+    "g",
+  );
+  existing = existing.replace(re, "");
+  fs.writeFileSync(file, existing);
+}
+
+export async function install({ packageRoot, flags }) {
+  const link = isLinkMode(flags);
+  const force = isForce(flags);
+
+  await ui.section("Codex", codexRoot());
+
+  // Clean up the pre-0.128 layout if it's still on disk — Codex never
+  // scanned it, so leaving it would just waste space.
+  if (fs.existsSync(legacySkillsRoot())) {
+    rmIfExists(legacySkillsRoot());
+    ui.step({ status: "remove", label: "legacy", value: legacySkillsRoot() });
+  }
+
+  // Skill files: copy/symlink each skill into ~/.codex/skills/slidemind-<name>/
+  // so codex auto-discovers them via SKILL.md frontmatter.
+  fs.mkdirSync(skillsRoot(), { recursive: true });
+  for (const skill of listSkills(packageRoot)) {
+    const dest = skillTarget(skill.name);
+    await ui.spin(
+      {
+        label: "skill",
+        value: dest,
+        note: link ? "linking" : "copying",
+        finalNote: link ? "linked" : "copied",
+      },
+      () => installDir({ src: skill.path, dest, link, force }),
+    );
+  }
+
+  // Wipe any stale slidemind-* prompts a prior install left behind. Codex
+  // 0.117+ no longer surfaces ~/.codex/prompts/ entries (openai/codex#15941),
+  // and the mechanism is officially deprecated in favour of skills.
+  removeStalePrompts();
+
+  writeAgentsBlock();
+  ui.step({ status: "ok", label: "AGENTS.md", value: agentsFile() });
+
+  // Register the slidemind MCP server so agents can list/push into open
+  // PowerPoint windows via slidemind_list_open_presentations / slidemind_push_deck.
+  writeMcpServerBlock(packageRoot);
+  ui.step({ status: "ok", label: "mcp server", value: configTomlFile() });
+
+  ui.note("restart Codex to pick up the skill + MCP server");
+}
+
+export async function uninstall() {
+  await ui.section("Codex", codexRoot());
+
+  // Remove any prompts a prior install wrote (we no longer install them, but
+  // older versions did).
+  removeStalePrompts();
+  // Remove our installed skills (only the ones we own — leave other entries
+  // in ~/.codex/skills/ alone).
+  if (fs.existsSync(skillsRoot())) {
+    for (const entry of fs.readdirSync(skillsRoot())) {
+      if (entry.startsWith(`${NAMESPACE}-`)) {
+        const target = path.join(skillsRoot(), entry);
+        rmIfExists(target);
+        ui.step({ status: "remove", label: "skill", value: target });
+      }
+    }
+  }
+  // Drop the legacy ~/.codex/slidemind/ payload if present.
+  if (fs.existsSync(legacySkillsRoot())) {
+    rmIfExists(legacySkillsRoot());
+    ui.step({ status: "remove", label: "legacy", value: legacySkillsRoot() });
+  }
+  clearAgentsBlock();
+  ui.step({ status: "remove", label: "AGENTS.md", value: agentsFile() });
+  clearMcpServerBlock();
+  ui.step({ status: "info", label: "mcp server", value: "unregistered" });
+}

package/src/installers/lib.mjs

@@ -0,0 +1,435 @@
+// Shared helpers for the per-harness installers.
+//
+// Every installer copies (or symlinks) the package's `skills/` folder into
+// the harness's expected location. The skill itself owns the user-facing
+// plan / create / edit workflow, so we no longer ship separate slash commands.
+// We support --link (symlink instead of copy) so contributors hacking on
+// slidemind see edits live without re-running install.
+
+import { brand, ANIMATE } from "./brand-theme.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import * as tui from "./tui.mjs";
+
+// Brand-colored glyphs injected into clack's log.message via the
+// `symbol` option. Pre-wrapped in our own truecolor escapes
+// (terminated with `\x1b[39m`) so they override whatever 16-color name
+// clack's util.styleText would otherwise apply.
+//
+// Palette is tuned for readability on dark terminals — full-saturation
+// tech blue (#0000FF) and ink (#283440) disappear on dark backgrounds,
+// so we use techBlue40 (#9999FF) as the canonical accent and let bold
+// + terminal default foreground carry the body text.
+const SYM = {
+  step:    brand.techBlue40("◇"),  // section header
+  success: brand.techBlue40("◆"),  // step complete
+  info:    brand.techBlue40("●"),  // neutral info (same hue, shape distinguishes)
+  warn:    brand.magenta("▲"),     // call-out / heads-up
+  error:   brand.magenta("■"),     // remove / failure
+};
+
+const SPINNER_FRAMES = ["◐", "◓", "◑", "◒"];
+
+// Brand wordmark in a small ASCII block style. "mind" sits nudged right
+// of "slide" — same vertical-stagger move the brand uses in print.
+const SLIDE_ART = [
+  ".--.  |    o  .--|  .---.",
+  "`--.  |    |  |  |  |---",
+  "`--'  `--  '  `--'  `---'",
+];
+// "mind" is offset further right so it visibly overhangs "slide"'s right
+// edge — same vertical-stagger move the brand uses on print decks.
+const MIND_ART = [
+  "              .-.-.  o  .--.  .--|",
+  "              | | |  |  |  |  |  |",
+  "              ' ' '  '  '  '  `--'",
+];
+const ART_BLOCK_WIDTH = Math.max(SLIDE_ART[0].length, MIND_ART[0].length); // 34
+
+// Three-tier vertical gradient applied to every wordmark frame.
+const WORDMARK_TIERS = [
+  (s) => brand.bold(brand.techBlue20(s)), // #CCCCFF — top, brightest
+  (s) => brand.techBlue40(s),             // #9999FF — middle
+  (s) => brand.dim(brand.techBlue40(s)),  // dimmed bottom
+];
+
+// Compose one frame of the wordmark at a given separation. `apart` is
+// in [0,1] where 0 = closed (rest) and 1 = maximally apart. Slide and
+// mind drift symmetrically — both move the same number of cols, in
+// opposite directions, off a shared base indent that gives slide
+// enough room to travel left.
+const WORDMARK_BASE_INDENT = 10;
+const WORDMARK_MAX_SHIFT = 8;
+
+function wordmarkFrame(apart) {
+  const shift = Math.round(apart * WORDMARK_MAX_SHIFT);
+  const slideIndent = Math.max(0, WORDMARK_BASE_INDENT - shift);
+  const mindIndent = WORDMARK_BASE_INDENT + shift;
+
+  const slidePad = " ".repeat(slideIndent);
+  const mindPad = " ".repeat(mindIndent);
+
+  const lines = [];
+  for (let i = 0; i < SLIDE_ART.length; i++) {
+    lines.push(slidePad + WORDMARK_TIERS[i](SLIDE_ART[i]));
+  }
+  lines.push("");
+  for (let i = 0; i < MIND_ART.length; i++) {
+    lines.push(mindPad + WORDMARK_TIERS[i](MIND_ART[i]));
+  }
+  return lines;
+}
+
+// Maximum visible width any animation frame can render at.
+const WORDMARK_MAX_WIDTH = WORDMARK_BASE_INDENT + WORDMARK_MAX_SHIFT + MIND_ART[0].length;
+
+// Static render — used in non-TTY paths and as the settled fallback.
+function renderStaticWordmark() {
+  const cols = process.stdout.columns || 80;
+  if (cols < ART_BLOCK_WIDTH + 4) return null;
+  return wordmarkFrame(0).join("\n");
+}
+
+const CURSOR_HIDE = "\x1b[?25l";
+const CURSOR_SHOW = "\x1b[?25h";
+
+// Render the wordmark inline at the start of the install. We tried
+// pinning it via DECSTBM scroll regions so it could animate while the
+// install streamed below, but Terminal.app discards content that
+// scrolls off the top of a scroll region — that lost older install
+// output, which the user (correctly) didn't want. Inline rendering
+// preserves everything in scrollback at the cost of dropping the
+// concurrent animation. Returns a no-op stop fn so callers can stay
+// uniform.
+function startWordmarkAnimation() {
+  const lines = wordmarkFrame(0);
+  process.stdout.write("\n" + lines.join("\n") + "\n\n");
+  return () => {};
+}
+
+export function isLinkMode(flags) {
+  return flags.includes("--link") || flags.includes("-l");
+}
+
+export function isForce(flags) {
+  return flags.includes("--force") || flags.includes("-F");
+}
+
+export function expandHome(p) {
+  if (p.startsWith("~/")) return path.join(process.env.HOME || "", p.slice(2));
+  return p;
+}
+
+export function rmIfExists(target) {
+  if (!fs.existsSync(target) && !isSymlink(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function copyDir(src, dest) {
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+export function linkDir(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.symlinkSync(src, dest, "dir");
+}
+
+// Install one folder (src) into dest. If link mode, symlink; otherwise copy.
+// Replaces an existing target. Async so a spinner can tick while the copy
+// runs (the skill payload can carry many files).
+export async function installDir({ src, dest, link, force }) {
+  const exists = fs.existsSync(dest) || isSymlink(dest);
+  if (exists) {
+    if (!force) {
+      // Replace existing slidemind installs unconditionally — they are
+      // generated artifacts. We surface the action so the user sees what
+      // happened.
+    }
+    rmIfExists(dest);
+  }
+  ensureDir(path.dirname(dest));
+  if (link) linkDir(src, dest);
+  else await fs.promises.cp(src, dest, { recursive: true });
+  return { exists, mode: link ? "linked" : "copied" };
+}
+
+// ---------- pretty terminal output ----------
+
+export function tildify(p) {
+  if (typeof p !== "string") return p;
+  const home = process.env.HOME || "";
+  if (home && (p === home || p.startsWith(home + path.sep))) {
+    return "~" + p.slice(home.length);
+  }
+  return p;
+}
+
+const LABEL_WIDTH = 12;
+
+// Visible (printable) length: strips CSI escape sequences before counting
+// so right-aligned timing badges line up correctly even when the line is
+// peppered with colour escapes.
+function visibleLength(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+function termWidth(cap = 72) {
+  const cols = process.stdout.columns;
+  if (!cols || cols < 40) return cap;
+  return Math.min(cols, cap);
+}
+
+// Compose the right-hand portion of a step line. Body text stays at the
+// terminal's default foreground (bold-only) so it renders on both light
+// and dark backgrounds. The leading glyph is supplied by clack via
+// `log.message({ symbol })`, so we only return the content here. When
+// `time` is provided (ms), append a right-aligned dim badge so completed
+// spinner steps read like a CI line: "skill ...        (0.4s)".
+function fmtStep({ label, value, note, time }) {
+  const lab = brand.bold(String(label).padEnd(LABEL_WIDTH));
+  const valStr = value ? brand.slate(tildify(value)) : "";
+  const noteStr = note ? "  " + brand.dim("(" + note + ")") : "";
+  const left = `${lab}${valStr}${noteStr}`;
+  if (time == null) return left;
+
+  const timeStr = brand.dim(`${(time / 1000).toFixed(1)}s`);
+  if (process.stdout.isTTY && process.stdout.columns) {
+    // Clack's log.message prepends "X  " (3 cols) before our message, so
+    // pad against (columns - 3) to land timing flush against the right edge.
+    const target = termWidth(120) - 3;
+    const pad = Math.max(2, target - visibleLength(left) - visibleLength(timeStr));
+    return left + " ".repeat(pad) + timeStr;
+  }
+  return left + "  " + timeStr;
+}
+
+const _sections = []; // recorded for the summary card
+let _startedAt = 0;
+let _stopWordmark = null;
+
+export const ui = {
+  // `wordmark: false` skips painting the wordmark — used when the caller
+  // (e.g. the install.sh bootstrap) already printed it, so we only emit the
+  // `v… · action` intro line and continue the rail.
+  banner(version, action, { wordmark = true } = {}) {
+    _startedAt = Date.now();
+    _sections.length = 0;
+    const v = brand.dim("v" + version);
+    const sep = brand.dim("·");
+    const act = brand.bold(action);
+    if (!wordmark) {
+      tui.intro(`${v} ${sep} ${act}`);
+      return;
+    }
+    const cols = process.stdout.columns || 80;
+    if (cols >= ART_BLOCK_WIDTH + 4) {
+      // Pin an animated wordmark above the install. Returns a no-op
+      // stop fn for static fallbacks, so we always have something to
+      // call in `done()`.
+      _stopWordmark = startWordmarkAnimation();
+      tui.intro(`${v} ${sep} ${act}`);
+    } else {
+      // Very narrow terminals: skip the wordmark entirely.
+      const name = brand.bold(brand.techBlue40("slidemind"));
+      tui.intro(`${name} ${brand.dim(version)} ${sep} ${act}`);
+    }
+  },
+  // Async so we can run a left→right shimmer across the harness name
+  // before settling on the final colour. Callers must `await` this.
+  async section(title, sub) {
+    // Capture for the summary card rendered by `done()`.
+    _sections.push({ title, sub: sub ? tildify(sub) : "" });
+
+    if (!ANIMATE) {
+      const head = brand.bold(title);
+      const subStr = sub ? "  " + brand.slate(tildify(sub)) : "";
+      tui.message(head + subStr, { symbol: SYM.step });
+      return;
+    }
+
+    // Manual emission so we can animate the title in place. Symbol
+    // sits at col 1; "  " padding lands the title at col 4.
+    tui.bumpRow(1);
+    process.stdout.write(tui.rail() + "\n");
+    tui.bumpRow(1);
+    process.stdout.write(SYM.step + "  ");
+    await tui.shimmer(title, { startCol: 4, restColor: (s) => s });
+    if (sub) process.stdout.write("  " + brand.slate(tildify(sub)));
+    process.stdout.write("\n");
+  },
+  step({ status = "ok", label, value, note }) {
+    const symbol =
+      status === "ok"
+        ? SYM.success
+        : status === "warn"
+          ? SYM.warn
+          : status === "remove"
+            ? SYM.error
+            : SYM.info;
+    tui.message(fmtStep({ label, value, note }), { symbol });
+  },
+  note(msg) {
+    tui.message(brand.magenta(msg), { symbol: SYM.warn });
+  },
+  done(msg) {
+    const elapsed = _startedAt
+      ? ((Date.now() - _startedAt) / 1000).toFixed(1)
+      : null;
+    const action = msg;
+
+    if (_sections.length === 0) {
+      // No sections to summarise — fall back to a plain outro. Emit
+      // first so it lands inside the still-active scroll region (the
+      // wordmark stays pinned), then stop the animation last.
+      tui.outro(brand.bold(action) + (elapsed ? `  ${brand.dim(`(${elapsed}s)`)}` : ""));
+      if (_stopWordmark) {
+        _stopWordmark();
+        _stopWordmark = null;
+      }
+      _startedAt = 0;
+      return;
+    }
+
+    // Boxed summary card. Replaces clack's `└ <msg>` outro.
+    const W = termWidth(72);
+    const inner = W - 2;
+    const slate = brand.slate;
+    const dim = brand.dim;
+    const titleColW = Math.max(
+      ..._sections.map((s) => s.title.length),
+      8,
+    );
+
+    const boxLine = (content) => {
+      const pad = Math.max(0, inner - visibleLength(content));
+      process.stdout.write(slate("│") + content + " ".repeat(pad) + slate("│") + "\n");
+    };
+
+    process.stdout.write("\n");
+
+    // Top: ╭─ installed ────╮
+    const labelText = " installed ";
+    const fillerLen = Math.max(2, inner - 1 - labelText.length);
+    process.stdout.write(
+      slate("╭─") +
+        dim(labelText) +
+        slate("─".repeat(fillerLen)) +
+        slate("╮") +
+        "\n",
+    );
+
+    boxLine("");
+    for (const sec of _sections) {
+      const tit = brand.bold(sec.title.padEnd(titleColW));
+      const sub = sec.sub ? slate(sec.sub) : "";
+      boxLine("  " + tit + "   " + sub);
+    }
+    boxLine("");
+
+    const count = _sections.length;
+    const stats =
+      `${count} ${count === 1 ? "harness" : "harnesses"}` +
+      (elapsed ? `  ${dim("·")}  ${elapsed}s` : "");
+    boxLine("  " + dim(stats));
+
+    // Bottom: ╰────────╯
+    process.stdout.write(slate("╰" + "─".repeat(inner) + "╯") + "\n");
+
+    process.stdout.write("\n");
+    process.stdout.write(`${SYM.success}  ${brand.bold(action)}\n`);
+
+    // Stop the wordmark animation last — that resets the scroll region
+    // and shows the cursor. The wordmark itself stays painted at the
+    // top of the screen because we don't scroll any further.
+    if (_stopWordmark) {
+      _stopWordmark();
+      _stopWordmark = null;
+    }
+
+    _startedAt = 0;
+    _sections.length = 0;
+  },
+  // Run `fn` while a small dot-circle animates on the step line. The
+  // frames carry brand color so the spinner reads as on-brand rather
+  // than "random package default". Falls back to a static step in
+  // non-TTY contexts (CI logs, piped output).
+  async spin({ label, value, note, finalNote }, fn) {
+    const start = Date.now();
+    if (!ANIMATE) {
+      try {
+        const result = await fn();
+        const time = Date.now() - start;
+        tui.message(
+          fmtStep({ label, value, note: finalNote ?? note, time }),
+          { symbol: SYM.success },
+        );
+        return result;
+      } catch (err) {
+        tui.message(
+          fmtStep({ label, value, note: "failed" }),
+          { symbol: SYM.error },
+        );
+        throw err;
+      }
+    }
+    // Reserve two rows: rail spacer + the active spinner line. Both
+    // count toward the gradient row counter.
+    tui.bumpRow(1);
+    process.stdout.write(tui.rail() + "\n");
+    tui.bumpRow(1);
+    process.stdout.write(
+      `${brand.techBlue40(SPINNER_FRAMES[0])}  ${fmtStep({ label, value, note })}`,
+    );
+    let frame = 0;
+    const timer = setInterval(() => {
+      frame = (frame + 1) % SPINNER_FRAMES.length;
+      process.stdout.write("\r\x1b[2K");
+      process.stdout.write(
+        `${brand.techBlue40(SPINNER_FRAMES[frame])}  ${fmtStep({ label, value, note })}`,
+      );
+    }, 80);
+    try {
+      const result = await fn();
+      const time = Date.now() - start;
+      clearInterval(timer);
+      process.stdout.write("\r\x1b[2K");
+      process.stdout.write(
+        `${SYM.success}  ${fmtStep({ label, value, note: finalNote ?? note, time })}\n`,
+      );
+      return result;
+    } catch (err) {
+      clearInterval(timer);
+      process.stdout.write("\r\x1b[2K");
+      process.stdout.write(
+        `${SYM.error}  ${fmtStep({ label, value, note: "failed" })}\n`,
+      );
+      throw err;
+    }
+  },
+};
+
+// Read every skill folder under skills/ and return their names + paths.
+export function listSkills(packageRoot) {
+  const skillsDir = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs
+    .readdirSync(skillsDir)
+    .filter((name) => {
+      const stat = fs.statSync(path.join(skillsDir, name));
+      return stat.isDirectory();
+    })
+    .map((name) => ({ name, path: path.join(skillsDir, name) }));
+}
+