@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/sdk.mjs

@@ -1,117 +1,117 @@
-// muscat-pk sdk <list|update [version]> — manage the rainbow-rb-sdk version.
-//
-// C++ backends (cpp, ros2 rclcpp) pin it in CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); the
-// versions come from the rb-sdk apt repository and the dev image installs the pinned one.
-//
-// Python backends:
-// Pins requirements.txt — the real install happens in the `dev`/`dev:back`
-// Docker container. If a local .venv exists (see devBack.mjs's syncIdeVenv,
-// for editor/linter support), also update it in place so pylint/pyright see
-// the new version immediately; this is best-effort only.
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { cppSdkFiles, cppSdkPin, ensureIdeVenv, findPluginRoot, log, setCppSdkPin, venvPython } from "./util.mjs";
-import { readManifest } from "./manifest.mjs";
-
-const PKG = "rainbow-rb-sdk";
-
-async function fetchPypi() {
-  try {
-    const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
-    return res.ok ? await res.json() : null;
-  } catch {
-    return null;
-  }
-}
-
-async function fetchVersions() {
-  const data = await fetchPypi();
-  return Object.keys(data?.releases || {}).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-}
-
-// Stable releases of rainbow-rb-sdk-dev, newest first. Pre-releases (0.1.4~dev1) are skipped: CMake
-// versions are numeric only.
-const APT_PACKAGES = "https://rainbowrobotics.github.io/rb-sdk/dists/stable/main/binary-amd64/Packages";
-
-export async function fetchAptVersions() {
-  try {
-    const res = await fetch(APT_PACKAGES);
-    if (!res.ok) return [];
-    const text = await res.text();
-    const versions = [...text.matchAll(/^Package: rainbow-rb-sdk-dev\n(?:.*\n)*?Version: (\S+)/gm)].map((m) => m[1]);
-    return [...new Set(versions)].filter((v) => /^[0-9]+(\.[0-9]+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
-  } catch {
-    return [];
-  }
-}
-
-async function runCppSdk(sub, version, root) {
-  if (sub === "list") {
-    const versions = await fetchAptVersions();
-    if (!versions.length) return log.warn("could not fetch versions (offline?).");
-    log.info(`rainbow-rb-sdk-dev versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
-    return;
-  }
-  if (sub === "update") {
-    if (!cppSdkFiles(root).length) throw new Error("no find_package(rb_sdk ...) in cpp/CMakeLists.txt or ros2_ws/src/*/CMakeLists.txt");
-    if (!version) {
-      version = (await fetchAptVersions())[0];
-      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
-    }
-    if (!/^[0-9]+(\.[0-9]+)*$/.test(version)) throw new Error(`"${version}" is not a CMake version (digits and dots only)`);
-    const before = cppSdkPin(root);
-    const files = setCppSdkPin(root, version);
-    log.ok(`rb_sdk ${before ?? "(unpinned)"} → ${version} in ${files.map((f) => f.slice(root.length + 1)).join(", ")}`);
-    log.info("The dev image is rebuilt with this SDK on the next `muscat-pk build` / `dev:back`.");
-    return;
-  }
-  log.info("Usage: muscat-pk sdk <list|update [version]>");
-}
-
-export async function runSdk(args = []) {
-  const sub = args[0];
-  const root = findPluginRoot();
-  const runtime = readManifest(root)?.runtime ?? {};
-  if (runtime.type === "cpp" || (runtime.type === "ros2" && runtime.rosClient === "rclcpp")) return runCppSdk(sub, args[1], root);
-  const reqs = resolve(root, "requirements.txt");
-
-  if (sub === "list") {
-    const versions = await fetchVersions();
-    if (!versions.length) {
-      log.warn("could not fetch versions (offline?).");
-      return;
-    }
-    log.info(`${PKG} versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
-    return;
-  }
-
-  if (sub === "update") {
-    let version = args[1];
-    if (!version) {
-      // info.version = latest stable
-      version = (await fetchPypi())?.info?.version;
-      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
-    }
-    // rainbow-rb-* pin each other exactly — bump them together.
-    let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
-    const pinned = /^(rainbow-rb-[\w-]+)\s*==.*$/gim;
-    const bumped = [...content.matchAll(pinned)].map((m) => m[1]);
-    content = content.replace(pinned, (_m, name) => `${name}==${version}`);
-    if (!bumped.some((n) => n.toLowerCase() === PKG)) {
-      content = (content ? content.trimEnd() + "\n" : "") + `${PKG}==${version}\n`;
-      bumped.push(PKG);
-    }
-    writeFileSync(reqs, content);
-    log.ok(`requirements.txt → ${bumped.map((n) => `${n}==${version}`).join(", ")}`);
-
-    if (existsSync(venvPython(resolve(root, ".venv")))) {
-      log.step("refreshing .venv (for your editor)…");
-      if (!ensureIdeVenv(root)) log.warn(".venv refresh failed — the Docker dev container is unaffected.");
-    } else {
-      log.info("Installed automatically on the next `muscat-pk dev` / `dev:back` (Docker container).");
-    }
-    return;
-  }
-
-  log.info("Usage: muscat-pk sdk <list|update [version]>");
-}
+// muscat-pk sdk <list|update [version]> — manage the rainbow-rb-sdk version.
+//
+// C++ backends (cpp, ros2 rclcpp) pin it in CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); the
+// versions come from the rb-sdk apt repository and the dev image installs the pinned one.
+//
+// Python backends:
+// Pins requirements.txt — the real install happens in the `dev`/`dev:back`
+// Docker container. If a local .venv exists (see devBack.mjs's syncIdeVenv,
+// for editor/linter support), also update it in place so pylint/pyright see
+// the new version immediately; this is best-effort only.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cppSdkFiles, cppSdkPin, ensureIdeVenv, findPluginRoot, log, setCppSdkPin, venvPython } from "./util.mjs";
+import { readManifest } from "./manifest.mjs";
+
+const PKG = "rainbow-rb-sdk";
+
+async function fetchPypi() {
+  try {
+    const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchVersions() {
+  const data = await fetchPypi();
+  return Object.keys(data?.releases || {}).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+}
+
+// Stable releases of rainbow-rb-sdk-dev, newest first. Pre-releases (0.1.4~dev1) are skipped: CMake
+// versions are numeric only.
+const APT_PACKAGES = "https://rainbowrobotics.github.io/rb-sdk/dists/stable/main/binary-amd64/Packages";
+
+export async function fetchAptVersions() {
+  try {
+    const res = await fetch(APT_PACKAGES);
+    if (!res.ok) return [];
+    const text = await res.text();
+    const versions = [...text.matchAll(/^Package: rainbow-rb-sdk-dev\n(?:.*\n)*?Version: (\S+)/gm)].map((m) => m[1]);
+    return [...new Set(versions)].filter((v) => /^[0-9]+(\.[0-9]+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  } catch {
+    return [];
+  }
+}
+
+async function runCppSdk(sub, version, root) {
+  if (sub === "list") {
+    const versions = await fetchAptVersions();
+    if (!versions.length) return log.warn("could not fetch versions (offline?).");
+    log.info(`rainbow-rb-sdk-dev versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
+    return;
+  }
+  if (sub === "update") {
+    if (!cppSdkFiles(root).length) throw new Error("no find_package(rb_sdk ...) in cpp/CMakeLists.txt or ros2_ws/src/*/CMakeLists.txt");
+    if (!version) {
+      version = (await fetchAptVersions())[0];
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
+    }
+    if (!/^[0-9]+(\.[0-9]+)*$/.test(version)) throw new Error(`"${version}" is not a CMake version (digits and dots only)`);
+    const before = cppSdkPin(root);
+    const files = setCppSdkPin(root, version);
+    log.ok(`rb_sdk ${before ?? "(unpinned)"} → ${version} in ${files.map((f) => f.slice(root.length + 1)).join(", ")}`);
+    log.info("The dev image is rebuilt with this SDK on the next `muscat-pk build` / `dev:back`.");
+    return;
+  }
+  log.info("Usage: muscat-pk sdk <list|update [version]>");
+}
+
+export async function runSdk(args = []) {
+  const sub = args[0];
+  const root = findPluginRoot();
+  const runtime = readManifest(root)?.runtime ?? {};
+  if (runtime.type === "cpp" || (runtime.type === "ros2" && runtime.rosClient === "rclcpp")) return runCppSdk(sub, args[1], root);
+  const reqs = resolve(root, "requirements.txt");
+
+  if (sub === "list") {
+    const versions = await fetchVersions();
+    if (!versions.length) {
+      log.warn("could not fetch versions (offline?).");
+      return;
+    }
+    log.info(`${PKG} versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
+    return;
+  }
+
+  if (sub === "update") {
+    let version = args[1];
+    if (!version) {
+      // info.version = latest stable
+      version = (await fetchPypi())?.info?.version;
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
+    }
+    // rainbow-rb-* pin each other exactly — bump them together.
+    let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
+    const pinned = /^(rainbow-rb-[\w-]+)\s*==.*$/gim;
+    const bumped = [...content.matchAll(pinned)].map((m) => m[1]);
+    content = content.replace(pinned, (_m, name) => `${name}==${version}`);
+    if (!bumped.some((n) => n.toLowerCase() === PKG)) {
+      content = (content ? content.trimEnd() + "\n" : "") + `${PKG}==${version}\n`;
+      bumped.push(PKG);
+    }
+    writeFileSync(reqs, content);
+    log.ok(`requirements.txt → ${bumped.map((n) => `${n}==${version}`).join(", ")}`);
+
+    if (existsSync(venvPython(resolve(root, ".venv")))) {
+      log.step("refreshing .venv (for your editor)…");
+      if (!ensureIdeVenv(root)) log.warn(".venv refresh failed — the Docker dev container is unaffected.");
+    } else {
+      log.info("Installed automatically on the next `muscat-pk dev` / `dev:back` (Docker container).");
+    }
+    return;
+  }
+
+  log.info("Usage: muscat-pk sdk <list|update [version]>");
+}

package/cli/src/storybook.mjs

@@ -1,168 +1,168 @@
-// muscat-pk storybook — serve the bundled Storybook (foundations + muscat) so
-// plugin authors can browse the real rb-components UI while developing.
-//
-// The static build is produced from apps/storybook (MUSCAT_STORYBOOK=true → only
-// the 1.foundations + 4.muscat sections, ordering-number prefixes stripped) and
-// staged into cli/storybook-dist so it ships inside the published muscat-pk.
-// In the monorepo it's built on demand if missing (or with --rebuild).
-import { createServer } from "node:http";
-import {
-  cpSync,
-  createReadStream,
-  existsSync,
-  mkdirSync,
-  rmSync,
-  statSync,
-} from "node:fs";
-import { execSync, spawn } from "node:child_process";
-import { copyFileSync } from "node:fs";
-import { extname, join, resolve } from "node:path";
-import { kitRoot, log, parseArgs } from "./util.mjs";
-
-// Shipped location (under cli/ → included in the npm "files" list).
-const SHIPPED_DIST = resolve(kitRoot, "cli/storybook-dist");
-// Raw .stories.tsx sources, staged alongside the compiled build — the `mcp`
-// command's get_component_example tool reads these directly (real usage
-// code, not just prop types) without needing a Storybook runtime.
-export const SHIPPED_STORIES_SRC = resolve(SHIPPED_DIST, "_stories-src");
-// Monorepo source (absent in an external install).
-const REPO_ROOT = resolve(kitRoot, "../..");
-const REPO_STORYBOOK = resolve(REPO_ROOT, "apps/storybook");
-const REPO_BUILD_OUT = resolve(REPO_STORYBOOK, "storybook-static-muscat");
-const REPO_MUSCAT_STORIES = resolve(REPO_STORYBOOK, "stories/4.muscat");
-const REPO_DESIGN_TOKENS = resolve(
-  REPO_ROOT,
-  "packages/rb-styles/css/output/rb-token.css",
-);
-// Generated Tailwind v4 token file (@theme colors + @utility typo-*), staged so
-// the `mcp` command's *_design_tokens tools work in an external install too.
-export const SHIPPED_DESIGN_TOKENS = resolve(SHIPPED_DIST, "_design-tokens.css");
-
-const CONTENT_TYPE = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".webp": "image/webp",
-  ".gif": "image/gif",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".wasm": "application/wasm",
-};
-
-// Build apps/storybook (muscat subset) and stage it into cli/storybook-dist.
-// Monorepo only. Outside the monorepo (e.g. re-packing an already-published
-// copy) it's a no-op — the shipped cli/storybook-dist is already in place.
-export function buildStorybook() {
-  if (!existsSync(REPO_STORYBOOK)) {
-    log.info("apps/storybook not found — using the pre-staged storybook-dist.");
-    return;
-  }
-  log.step("building Storybook (foundations + muscat)…");
-  execSync("yarn workspace storybook storybook:build:muscat", {
-    cwd: REPO_ROOT,
-    stdio: "inherit",
-    env: { ...process.env, MUSCAT_STORYBOOK: "true" },
-  });
-  rmSync(SHIPPED_DIST, { recursive: true, force: true });
-  mkdirSync(SHIPPED_DIST, { recursive: true });
-  cpSync(REPO_BUILD_OUT, SHIPPED_DIST, { recursive: true });
-
-  // Stage raw .stories.tsx sources (not just the compiled JS bundle) for the
-  // `mcp` command's get_component_example tool.
-  if (existsSync(REPO_MUSCAT_STORIES)) {
-    cpSync(REPO_MUSCAT_STORIES, SHIPPED_STORIES_SRC, {
-      recursive: true,
-      filter: (src) => statSync(src).isDirectory() || src.endsWith(".stories.tsx"),
-    });
-  }
-
-  // Stage the design-token CSS for the `mcp` command's *_design_tokens tools.
-  if (existsSync(REPO_DESIGN_TOKENS)) {
-    copyFileSync(REPO_DESIGN_TOKENS, SHIPPED_DESIGN_TOKENS);
-  }
-
-  log.ok(`storybook → ${SHIPPED_DIST}`);
-}
-
-function openBrowser(url) {
-  const cmd =
-    process.platform === "darwin"
-      ? "open"
-      : process.platform === "win32"
-        ? "start"
-        : "xdg-open";
-  try {
-    spawn(cmd, [url], {
-      stdio: "ignore",
-      detached: true,
-      shell: process.platform === "win32",
-    }).unref();
-  } catch {
-    /* headless / no browser — the URL is printed anyway */
-  }
-}
-
-function serve(distDir, port) {
-  const server = createServer((req, res) => {
-    const url = decodeURIComponent((req.url || "/").split("?")[0]);
-    const rel = url === "/" ? "/index.html" : url;
-    const filePath = resolve(distDir, `.${rel}`);
-
-    // Serve the file if it's inside distDir and exists; otherwise fall back to
-    // index.html (Storybook is a single-page app).
-    if (
-      filePath.startsWith(distDir) &&
-      existsSync(filePath) &&
-      statSync(filePath).isFile()
-    ) {
-      const type = CONTENT_TYPE[extname(filePath)];
-      if (type) res.setHeader("Content-Type", type);
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      createReadStream(filePath).pipe(res);
-      return;
-    }
-    res.setHeader("Content-Type", "text/html; charset=utf-8");
-    createReadStream(join(distDir, "index.html")).pipe(res);
-  });
-
-  server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-      log.error(`port ${port} is in use — pass a free one with --port <n>.`);
-      process.exit(1);
-    }
-    throw err;
-  });
-
-  server.listen(port, () => {
-    const url = `http://localhost:${port}`;
-    log.ok(`Storybook → ${url}`);
-    openBrowser(url);
-  });
-}
-
-export async function runStorybook(args = []) {
-  const { port = "6007", rebuild } = parseArgs(args, { booleans: ["rebuild"] });
-
-  const staged = existsSync(join(SHIPPED_DIST, "index.html"));
-  if (rebuild || !staged) {
-    if (existsSync(REPO_STORYBOOK)) {
-      buildStorybook();
-    } else if (!staged) {
-      throw new Error(
-        `Storybook build not found at ${SHIPPED_DIST}.\n` +
-          "  This build of muscat-pk was published without the bundled Storybook.",
-      );
-    }
-  }
-
-  serve(SHIPPED_DIST, Number(port));
-}
+// muscat-pk storybook — serve the bundled Storybook (foundations + muscat) so
+// plugin authors can browse the real rb-components UI while developing.
+//
+// The static build is produced from apps/storybook (MUSCAT_STORYBOOK=true → only
+// the 1.foundations + 4.muscat sections, ordering-number prefixes stripped) and
+// staged into cli/storybook-dist so it ships inside the published muscat-pk.
+// In the monorepo it's built on demand if missing (or with --rebuild).
+import { createServer } from "node:http";
+import {
+  cpSync,
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { execSync, spawn } from "node:child_process";
+import { copyFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { kitRoot, log, parseArgs } from "./util.mjs";
+
+// Shipped location (under cli/ → included in the npm "files" list).
+const SHIPPED_DIST = resolve(kitRoot, "cli/storybook-dist");
+// Raw .stories.tsx sources, staged alongside the compiled build — the `mcp`
+// command's get_component_example tool reads these directly (real usage
+// code, not just prop types) without needing a Storybook runtime.
+export const SHIPPED_STORIES_SRC = resolve(SHIPPED_DIST, "_stories-src");
+// Monorepo source (absent in an external install).
+const REPO_ROOT = resolve(kitRoot, "../..");
+const REPO_STORYBOOK = resolve(REPO_ROOT, "apps/storybook");
+const REPO_BUILD_OUT = resolve(REPO_STORYBOOK, "storybook-static-muscat");
+const REPO_MUSCAT_STORIES = resolve(REPO_STORYBOOK, "stories/4.muscat");
+const REPO_DESIGN_TOKENS = resolve(
+  REPO_ROOT,
+  "packages/rb-styles/css/output/rb-token.css",
+);
+// Generated Tailwind v4 token file (@theme colors + @utility typo-*), staged so
+// the `mcp` command's *_design_tokens tools work in an external install too.
+export const SHIPPED_DESIGN_TOKENS = resolve(SHIPPED_DIST, "_design-tokens.css");
+
+const CONTENT_TYPE = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".wasm": "application/wasm",
+};
+
+// Build apps/storybook (muscat subset) and stage it into cli/storybook-dist.
+// Monorepo only. Outside the monorepo (e.g. re-packing an already-published
+// copy) it's a no-op — the shipped cli/storybook-dist is already in place.
+export function buildStorybook() {
+  if (!existsSync(REPO_STORYBOOK)) {
+    log.info("apps/storybook not found — using the pre-staged storybook-dist.");
+    return;
+  }
+  log.step("building Storybook (foundations + muscat)…");
+  execSync("yarn workspace storybook storybook:build:muscat", {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    env: { ...process.env, MUSCAT_STORYBOOK: "true" },
+  });
+  rmSync(SHIPPED_DIST, { recursive: true, force: true });
+  mkdirSync(SHIPPED_DIST, { recursive: true });
+  cpSync(REPO_BUILD_OUT, SHIPPED_DIST, { recursive: true });
+
+  // Stage raw .stories.tsx sources (not just the compiled JS bundle) for the
+  // `mcp` command's get_component_example tool.
+  if (existsSync(REPO_MUSCAT_STORIES)) {
+    cpSync(REPO_MUSCAT_STORIES, SHIPPED_STORIES_SRC, {
+      recursive: true,
+      filter: (src) => statSync(src).isDirectory() || src.endsWith(".stories.tsx"),
+    });
+  }
+
+  // Stage the design-token CSS for the `mcp` command's *_design_tokens tools.
+  if (existsSync(REPO_DESIGN_TOKENS)) {
+    copyFileSync(REPO_DESIGN_TOKENS, SHIPPED_DESIGN_TOKENS);
+  }
+
+  log.ok(`storybook → ${SHIPPED_DIST}`);
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  try {
+    spawn(cmd, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    /* headless / no browser — the URL is printed anyway */
+  }
+}
+
+function serve(distDir, port) {
+  const server = createServer((req, res) => {
+    const url = decodeURIComponent((req.url || "/").split("?")[0]);
+    const rel = url === "/" ? "/index.html" : url;
+    const filePath = resolve(distDir, `.${rel}`);
+
+    // Serve the file if it's inside distDir and exists; otherwise fall back to
+    // index.html (Storybook is a single-page app).
+    if (
+      filePath.startsWith(distDir) &&
+      existsSync(filePath) &&
+      statSync(filePath).isFile()
+    ) {
+      const type = CONTENT_TYPE[extname(filePath)];
+      if (type) res.setHeader("Content-Type", type);
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      createReadStream(filePath).pipe(res);
+      return;
+    }
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    createReadStream(join(distDir, "index.html")).pipe(res);
+  });
+
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      log.error(`port ${port} is in use — pass a free one with --port <n>.`);
+      process.exit(1);
+    }
+    throw err;
+  });
+
+  server.listen(port, () => {
+    const url = `http://localhost:${port}`;
+    log.ok(`Storybook → ${url}`);
+    openBrowser(url);
+  });
+}
+
+export async function runStorybook(args = []) {
+  const { port = "6007", rebuild } = parseArgs(args, { booleans: ["rebuild"] });
+
+  const staged = existsSync(join(SHIPPED_DIST, "index.html"));
+  if (rebuild || !staged) {
+    if (existsSync(REPO_STORYBOOK)) {
+      buildStorybook();
+    } else if (!staged) {
+      throw new Error(
+        `Storybook build not found at ${SHIPPED_DIST}.\n` +
+          "  This build of muscat-pk was published without the bundled Storybook.",
+      );
+    }
+  }
+
+  serve(SHIPPED_DIST, Number(port));
+}