@atelier-ui/create-workspace 0.2.41 → 0.2.43

package/src/generators/preset/files/tools/scripts/preflight.mjs

@@ -13,7 +13,7 @@
 
 import { execSync, spawnSync } from 'node:child_process';
 import { createServer } from 'node:net';
-import { readFileSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
@@ -23,7 +23,8 @@ const __dirname = dirname(__filename);
 const ROOT = resolve(__dirname, '../..');
 
 // ── Styling ──────────────────────────────────────────────────────────
-const supportsColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+const supportsColor =
+  process.stdout.isTTY && process.env.NO_COLOR === undefined;
 const c = (code, s) => (supportsColor ? `\x1b[${code}m${s}\x1b[0m` : s);
 const red = (s) => c('31', s);
 const green = (s) => c('32', s);
@@ -54,7 +55,8 @@ const warn = (label, detail, fix) => record('warn', label, detail, fix);
 function which(cmd) {
   const finder = process.platform === 'win32' ? 'where' : 'which';
   const res = spawnSync(finder, [cmd], { encoding: 'utf8' });
-  if (res.status === 0 && res.stdout.trim()) return res.stdout.trim().split('\n')[0];
+  if (res.status === 0 && res.stdout.trim())
+    return res.stdout.trim().split('\n')[0];
   return null;
 }
 
@@ -101,7 +103,10 @@ async function mcpPost(url, body, sessionId, timeoutMs = 10000) {
       sessionId: res.headers.get('mcp-session-id') ?? undefined,
     };
   } catch (err) {
-    return { error: err?.name === 'AbortError' ? 'timeout' : String(err?.message ?? err) };
+    return {
+      error:
+        err?.name === 'AbortError' ? 'timeout' : String(err?.message ?? err),
+    };
   } finally {
     clearTimeout(timer);
   }
@@ -141,16 +146,28 @@ async function probeMcp(url) {
   if (init.error) return { level: 'unreachable', detail: init.error };
   const session = init.sessionId;
   if (session) {
-    await mcpPost(url, { jsonrpc: '2.0', method: 'notifications/initialized' }, session, 5000);
+    await mcpPost(
+      url,
+      { jsonrpc: '2.0', method: 'notifications/initialized' },
+      session,
+      5000,
+    );
   }
 
   // 2. tools/list — must be HTTP 200 with a parseable JSON-RPC tools array.
-  const list = await mcpPost(url, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }, session);
-  if (list.error) return { level: 'broken', detail: `tools/list failed (${list.error})` };
-  if (list.status !== 200) return { level: 'broken', detail: `tools/list → HTTP ${list.status}` };
+  const list = await mcpPost(
+    url,
+    { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} },
+    session,
+  );
+  if (list.error)
+    return { level: 'broken', detail: `tools/list failed (${list.error})` };
+  if (list.status !== 200)
+    return { level: 'broken', detail: `tools/list → HTTP ${list.status}` };
   const listMsg = parseJsonRpc(list.contentType, list.text, 2);
   const tools = listMsg?.result?.tools;
-  if (!Array.isArray(tools)) return { level: 'broken', detail: 'tools/list → no parseable result' };
+  if (!Array.isArray(tools))
+    return { level: 'broken', detail: 'tools/list → no parseable result' };
 
   // 3. On an Atelier Storybook MCP, exercise one real tool call: manifests
   //    are only fetched inside tool calls, and a broken manifest fetch comes
@@ -166,14 +183,21 @@ async function probeMcp(url) {
       },
       session,
     );
-    if (call.error) return { level: 'broken', detail: `docs-list failed (${call.error})` };
-    if (call.status !== 200) return { level: 'broken', detail: `docs-list → HTTP ${call.status}` };
+    if (call.error)
+      return { level: 'broken', detail: `docs-list failed (${call.error})` };
+    if (call.status !== 200)
+      return { level: 'broken', detail: `docs-list → HTTP ${call.status}` };
     const callMsg = parseJsonRpc(call.contentType, call.text, 3);
     if (!callMsg?.result || callMsg.result.isError) {
       const reason =
-        callMsg?.result?.content?.[0]?.text ?? callMsg?.error?.message ?? 'no parseable result';
+        callMsg?.result?.content?.[0]?.text ??
+        callMsg?.error?.message ??
+        'no parseable result';
       const oneLine = String(reason).replace(/\s+/g, ' ').trim();
-      return { level: 'broken', detail: `docs-list → ${oneLine.slice(0, 120)}` };
+      return {
+        level: 'broken',
+        detail: `docs-list → ${oneLine.slice(0, 120)}`,
+      };
     }
   }
 
@@ -205,6 +229,31 @@ function loadMcpEndpoints() {
   }
 }
 
+/**
+ * Reads the exact `figma-console-mcp@<version>` pin off the `figma-console`
+ * server's `args` in `.mcp.json` — the same file `loadMcpEndpoints()` reads,
+ * just a different server shape (`command: npx`, not `type: http`). Returns
+ * null when `.mcp.json` is missing, has no `figma-console` entry, or that
+ * entry isn't pinned to an exact version (e.g. `@latest`) — every caller
+ * treats null as "nothing to compare against," not as a failure.
+ */
+function getPinnedFigmaConsoleVersion() {
+  const mcpPath = resolve(ROOT, '.mcp.json');
+  if (!existsSync(mcpPath)) return null;
+  try {
+    const config = JSON.parse(readFileSync(mcpPath, 'utf8'));
+    const args = config.mcpServers?.['figma-console']?.args;
+    if (!Array.isArray(args)) return null;
+    for (const arg of args) {
+      const match = /^figma-console-mcp@(\d+\.\d+\.\d+)$/.exec(arg);
+      if (match) return match[1];
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 // ── Checks ───────────────────────────────────────────────────────────
 function checkNode() {
   const required = { major: 22, minor: 12, patch: 0 };
@@ -224,7 +273,11 @@ function checkNpm() {
   const required = { major: 10, minor: 0, patch: 0 };
   const path = which('npm');
   if (!path) {
-    fail('npm', 'not found on PATH', 'npm ships with Node.js — reinstall Node if missing');
+    fail(
+      'npm',
+      'not found on PATH',
+      'npm ships with Node.js — reinstall Node if missing',
+    );
     return;
   }
   try {
@@ -233,7 +286,11 @@ function checkNpm() {
     if (isAtLeast(actual, required)) {
       ok('npm', `v${version}`);
     } else {
-      warn('npm', `found v${version}, recommend >= 10.0.0`, 'Run `npm install -g npm@latest`');
+      warn(
+        'npm',
+        `found v${version}, recommend >= 10.0.0`,
+        'Run `npm install -g npm@latest`',
+      );
     }
   } catch (err) {
     fail('npm', String(err?.message ?? err), 'Reinstall Node.js');
@@ -243,14 +300,22 @@ function checkNpm() {
 function checkGit() {
   const path = which('git');
   if (!path) {
-    fail('git', 'not found on PATH', 'Install from https://git-scm.com or `brew install git`');
+    fail(
+      'git',
+      'not found on PATH',
+      'Install from https://git-scm.com or `brew install git`',
+    );
     return;
   }
   try {
     const version = execSync('git --version', { encoding: 'utf8' }).trim();
     ok('git', version);
   } catch {
-    warn('git', 'installed but version check failed', 'Verify install with `git --version`');
+    warn(
+      'git',
+      'installed but version check failed',
+      'Verify install with `git --version`',
+    );
   }
 }
 
@@ -265,36 +330,96 @@ function checkClaudeCli() {
     return;
   }
   try {
-    const version = execSync('claude --version', { encoding: 'utf8', timeout: 5000 }).trim();
+    const version = execSync('claude --version', {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
     ok('Claude Code CLI', version);
   } catch {
-    warn('Claude Code CLI', 'installed but `claude --version` failed', 'Try `claude doctor`');
+    warn(
+      'Claude Code CLI',
+      'installed but `claude --version` failed',
+      'Try `claude doctor`',
+    );
   }
 }
 
 async function checkFigmaSetup() {
   // 1. Desktop Bridge plugin manifest — the primary channel.
-  const manifestPath = join(homedir(), '.figma-console-mcp', 'plugin', 'manifest.json');
+  const manifestPath = join(
+    homedir(),
+    '.figma-console-mcp',
+    'plugin',
+    'manifest.json',
+  );
+  const pinnedVersion = getPinnedFigmaConsoleVersion();
+  const pinnedSpec = pinnedVersion
+    ? `figma-console-mcp@${pinnedVersion}`
+    : 'figma-console-mcp@latest';
   if (existsSync(manifestPath)) {
     ok('Figma Desktop Bridge plugin', `manifest at ${manifestPath}`);
   } else {
     warn(
       'Figma Desktop Bridge plugin',
       'manifest not found',
-      'Run `npx -y figma-console-mcp@latest --help` once, then Figma → Plugins → Development → Import plugin from manifest…',
+      `Run \`npx -y ${pinnedSpec} --help\` once, then Figma → Plugins → Development → Import plugin from manifest…`,
     );
   }
 
+  // 1b. .version marker vs. the exact version .mcp.json pins. The package
+  // writes this file (setupStablePluginDir(), dist/local.js) specifically so
+  // staleness between "what the npm package installed on disk" and "what
+  // this workspace is pinned to" can be detected — nothing read it back
+  // until now. This is a warning, not a hard failure: a stale on-disk build
+  // does not block the workshop (the Bridge still connects and runs), and
+  // the files self-heal on the next `figma-console-mcp` server start anyway
+  // — treating it as fatal would fail preflight over something that fixes
+  // itself the moment Claude Code (re)starts the MCP.
+  if (existsSync(manifestPath)) {
+    const versionPath = join(
+      homedir(),
+      '.figma-console-mcp',
+      'plugin',
+      '.version',
+    );
+    if (!existsSync(versionPath)) {
+      warn(
+        'Plugin files .version marker',
+        'manifest exists but no .version file next to it',
+        `Run \`npx -y ${pinnedSpec} --help\` once to refresh ~/.figma-console-mcp/plugin/ with a current build`,
+      );
+    } else if (pinnedVersion) {
+      const diskVersion = readFileSync(versionPath, 'utf8').trim();
+      if (diskVersion === pinnedVersion) {
+        ok('Plugin files vs. .mcp.json pin', `both ${diskVersion}`);
+      } else {
+        warn(
+          'Plugin files vs. .mcp.json pin',
+          `on-disk .version is ${diskVersion}, .mcp.json pins ${pinnedVersion}`,
+          `Run \`npx -y ${pinnedSpec} --help\` once to refresh the files, then re-run (or re-import) the plugin in Figma Desktop — see https://atelier.pieper.io/runbook#plugin-update`,
+        );
+      }
+    }
+  }
+
   // 2. Bridge WebSocket port range — at least one port must be usable.
-  const bridgePorts = [9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230, 9231, 9232];
+  const bridgePorts = [
+    9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230, 9231, 9232,
+  ];
   let freeCount = 0;
   for (const p of bridgePorts) {
     if (await portFree(p)) freeCount += 1;
   }
   if (freeCount === bridgePorts.length) {
-    ok('Bridge port range 9223–9232', 'all free (MCP will bind on first launch)');
+    ok(
+      'Bridge port range 9223–9232',
+      'all free (MCP will bind on first launch)',
+    );
   } else if (freeCount > 0) {
-    ok('Bridge port range 9223–9232', `${freeCount}/10 free (bridge connection OK)`);
+    ok(
+      'Bridge port range 9223–9232',
+      `${freeCount}/10 free (bridge connection OK)`,
+    );
   } else {
     warn(
       'Bridge port range 9223–9232',
@@ -403,7 +528,8 @@ function isDir(path) {
 }
 
 function detectEnvironment() {
-  const isClone = isDir(resolve(ROOT, 'libs/spec')) && isDir(resolve(ROOT, 'plan/adr'));
+  const isClone =
+    isDir(resolve(ROOT, 'libs/spec')) && isDir(resolve(ROOT, 'plan/adr'));
   return isClone ? 'clone' : 'scaffold';
 }
 
@@ -427,6 +553,50 @@ const PORTS_BY_ENV = {
   ],
 };
 
+// ── Playwright Chromium (scaffold only) ─────────────────────────────
+// The scaffold's `npm run check:stories` runs every story headless in
+// Chromium via @storybook/addon-vitest + @vitest/browser-playwright — a
+// browser Playwright manages itself, downloaded by `npx playwright install
+// chromium` (never as a postinstall hook: a workshop attendee's first
+// `npm install` should not silently spend minutes downloading a browser).
+// This is a best-effort, dependency-free heuristic (no `require('playwright')`
+// here — this script has zero non-builtin imports and should keep working
+// even before `npm install` has finished) — it looks for a `chromium-*`
+// directory in Playwright's own browser cache, respecting
+// `PLAYWRIGHT_BROWSERS_PATH` the same way Playwright itself does. A warning,
+// not a hard failure: this only blocks `check:stories`, not the workshop.
+function playwrightBrowsersDir() {
+  if (process.env.PLAYWRIGHT_BROWSERS_PATH)
+    return process.env.PLAYWRIGHT_BROWSERS_PATH;
+  const home = homedir();
+  if (process.platform === 'darwin')
+    return join(home, 'Library', 'Caches', 'ms-playwright');
+  if (process.platform === 'win32')
+    return join(home, 'AppData', 'Local', 'ms-playwright');
+  return join(home, '.cache', 'ms-playwright');
+}
+
+function checkPlaywrightChromium() {
+  const dir = playwrightBrowsersDir();
+  let hasChromium = false;
+  try {
+    hasChromium =
+      existsSync(dir) &&
+      readdirSync(dir).some((name) => name.startsWith('chromium'));
+  } catch {
+    hasChromium = false;
+  }
+  if (hasChromium) {
+    ok('Playwright Chromium', 'installed');
+  } else {
+    warn(
+      'Playwright Chromium',
+      'not found',
+      'Run `npx playwright install chromium` — needed for `npm run check:stories`',
+    );
+  }
+}
+
 async function checkPorts(env) {
   ok(
     'Environment',
@@ -437,7 +607,12 @@ async function checkPorts(env) {
   for (const { port, label } of PORTS_BY_ENV[env]) {
     const free = await portFree(port);
     if (free) ok(`Port ${port} (${label})`, 'free');
-    else warn(`Port ${port} (${label})`, 'in use', `Run \`lsof -ti :${port} | xargs kill\` (macOS/Linux)`);
+    else
+      warn(
+        `Port ${port} (${label})`,
+        'in use',
+        `Run \`lsof -ti :${port} | xargs kill\` (macOS/Linux)`,
+      );
   }
 }
 
@@ -471,6 +646,11 @@ async function main() {
   header('Local ports');
   await checkPorts(env);
 
+  if (env === 'scaffold') {
+    header('Storybook browser tests');
+    checkPlaywrightChromium();
+  }
+
   // Summary
   const failures = results.filter((r) => r.level === 'fail').length;
   const warnings = results.filter((r) => r.level === 'warn').length;
@@ -479,19 +659,29 @@ async function main() {
   console.log('');
   if (failures === 0) {
     console.log(
-      green(`All hard checks passed`) + dim(` · ${passes} ok, ${warnings} warning(s)`),
+      green(`All hard checks passed`) +
+        dim(` · ${passes} ok, ${warnings} warning(s)`),
     );
     if (warnings > 0) {
-      console.log(dim('Warnings are non-blocking — see https://atelier.pieper.io/troubleshooting'));
+      console.log(
+        dim(
+          'Warnings are non-blocking — see https://atelier.pieper.io/troubleshooting',
+        ),
+      );
     }
     console.log('');
     process.exit(0);
   } else {
     console.log(
-      red(`${failures} check(s) failed`) + dim(` · ${passes} ok, ${warnings} warning(s)`),
+      red(`${failures} check(s) failed`) +
+        dim(` · ${passes} ok, ${warnings} warning(s)`),
     );
     console.log(dim('Fix the items above, then re-run `npm run preflight`.'));
-    console.log(dim('Full troubleshooting guide: https://atelier.pieper.io/troubleshooting'));
+    console.log(
+      dim(
+        'Full troubleshooting guide: https://atelier.pieper.io/troubleshooting',
+      ),
+    );
     console.log('');
     process.exit(1);
   }

package/src/generators/preset/files/tools/stylelint-rules/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Local stylelint plugin for this repo's own CSS-discipline invariants —
+ * the stylelint counterpart of `tools/eslint-rules/`. A stylelint plugin
+ * module may export a single rule definition or an array of them (stylelint
+ * flattens either shape when loading `plugins`); this file exports the
+ * array so `stylelint.config.mjs` only needs one entry in `plugins` to pick
+ * up every rule below.
+ *
+ * Each rule file calls `stylelint.createPlugin(ruleName, rule)` itself and
+ * is `require()`-able on its own — this index just collects them, the same
+ * relationship `tools/eslint-rules/index.js` has to its own rule files.
+ */
+
+module.exports = [
+  require('./no-raw-color-literal'),
+  require('./no-undeclared-token'),
+  require('./no-primitive-token'),
+  require('./no-token-bypass'),
+];