inkbridge 0.1.0-beta.19 → 0.1.0-beta.20

package/README.md

@@ -23,7 +23,7 @@ Generates native Figma frames and reusable Figma component instances from your T
 
 - **Figma Desktop** (not the browser — the plugin needs localhost access)
 - **Node.js 18+** and **pnpm**
-- A project with Next.js, Tailwind CSS, and Storybook stories (`.stories.tsx`)
+- A project with Next.js, Tailwind CSS, and Storybook stories (`.stories.tsx` or `.stories.ts`)
 
 ---
 
@@ -36,11 +36,15 @@ pnpm add -D inkbridge
 pnpm exec inkbridge setup
 ```
 
-`setup` does three things automatically:
-- Creates `inkbridge.config.json` in your project root (auto-detects component paths from `.storybook/main.ts`)
+`pnpm exec inkbridge setup` is the only required step after install. It prints exactly what it will change before writing anything (run with `--dry-run` to preview without applying):
+
+- Creates `inkbridge.config.json` in your project root (auto-detects component paths from `.storybook/main.*`)
 - Creates the scanner API route at `src/app/api/inkbridge/scan-components/route.ts`
 - Creates the token patch API route at `src/app/api/inkbridge/patch-tokens/route.ts`
 - Adds `inkbridge:dev` and `inkbridge:scan` scripts to your `package.json`
+- Adds `headers()` to your `next.config.*` exposing CORS on `/api/inkbridge/:path*` so the Figma plugin iframe can reach those routes (scoped — your other routes are untouched)
+
+Inkbridge does not modify your ESLint config or any other tooling. The recommended `react/forbid-dom-props` rule for inline styles is suggested in "Recommended lint rules" below, but never written by setup.
 
 ### 2. Load the plugin in Figma Desktop
 
@@ -128,7 +132,7 @@ Edit `inkbridge.config.json` in your project root:
 |---|---|---|
 | `componentPaths` | auto-detected | Directories to scan for components |
 | `exclude` | `[]` | Directory or file names to skip |
-| `onlyWithStories` | `true` | Only include components with a `.stories.tsx` file |
+| `onlyWithStories` | `true` | Only include components with a `.stories.tsx` or `.stories.ts` file |
 
 The scanner re-reads this file on every scan — no server restart needed.
 

package/bin/inkbridge.mjs

@@ -7,8 +7,9 @@ import { fileURLToPath } from "url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = join(__dirname, "..");
 
-// When running via postinstall, INIT_CWD is the consumer project root.
-// Fall back to process.cwd() for direct invocations.
+// `INIT_CWD` is set by package managers to the project where the user
+// invoked the command (vs `process.cwd()` which can be `node_modules/inkbridge`
+// when called via `pnpm exec`). Fall back for direct node invocations.
 const PROJECT_ROOT = process.env.INIT_CWD || process.cwd();
 
 const [, , command = "help"] = process.argv;
@@ -61,9 +62,28 @@ async function patchNextConfig(root) {
   }
 
   const headersBlock = `
-  // Allow Figma plugin UI iframe (null origin) to fetch static assets
+  // Allow the Figma plugin UI iframe (null origin) to read the dev
+  // server. Two scopes:
+  //   - /api/inkbridge/* gets full CORS (POST/OPTIONS) for the token
+  //     patch route. The inkbridge API routes also set per-response
+  //     CORS headers, so this is mostly belt-and-suspenders for
+  //     CORS preflight handling.
+  //   - /:path* gets GET-only CORS so the plugin can fetch the
+  //     static assets your components reference (e.g.
+  //     <Image src="/assets/logo.svg">). GET-only on all paths means
+  //     other origins can READ your local dev server — that's fine
+  //     for design-system assets and matches what every Storybook
+  //     and Next.js dev server does in practice.
   async headers() {
     return [
+      {
+        source: "/api/inkbridge/:path*",
+        headers: [
+          { key: "Access-Control-Allow-Origin", value: "*" },
+          { key: "Access-Control-Allow-Methods", value: "GET, POST, OPTIONS" },
+          { key: "Access-Control-Allow-Headers", value: "Content-Type" },
+        ],
+      },
       {
         source: "/:path*",
         headers: [
@@ -100,124 +120,156 @@ async function patchNextConfig(root) {
 }
 
 // ---------------------------------------------------------------------------
-// postinstall — called automatically after `pnpm add -D inkbridge`
+// setup — patches package.json + creates scanner route
 // ---------------------------------------------------------------------------
-async function postinstall() {
-  const pkg = JSON.parse(await readFile(join(PACKAGE_DIR, "package.json"), "utf8"));
-  const manifestPath = join(PROJECT_ROOT, "node_modules/inkbridge/manifest.json");
+function detectEnvironment(root) {
+  // Read consumer package.json to detect Next.js, Tailwind, Storybook.
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); } catch (_e) {}
+  const deps = pkg ? { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) } : {};
+  const nextConfigCandidates = ["next.config.ts", "next.config.js", "next.config.mjs", "next.config.cjs"];
+  const nextConfig = nextConfigCandidates.find(f => existsSync(join(root, f))) || null;
+  const storybookMain = ["main.ts", "main.js", "main.mjs", "main.cjs"]
+    .map(f => `.storybook/${f}`)
+    .find(p => existsSync(join(root, p))) || null;
+  const storybookPaths = storybookMain ? detectStorybookPaths(root) : [];
+  return {
+    nextVersion: deps.next || null,
+    nextConfig,
+    tailwindVersion: deps.tailwindcss || null,
+    storybookMain,
+    storybookPaths,
+    componentPaths: storybookPaths.length > 0 ? storybookPaths : ["src"],
+  };
+}
 
-  // If setup has already run, the scanner route file exists. Re-installs and
-  // version bumps shouldn't shout "RUN SETUP" again — that's misleading.
-  const scanRouteExists = existsSync(
-    join(PROJECT_ROOT, "src/app/api/inkbridge/scan-components/route.ts")
-  );
+function statusGlyph(present) { return present ? "✓" : "✗"; }
 
-  console.log("");
-  console.log(`  ✓ inkbridge v${pkg.version} installed`);
-
-  if (scanRouteExists) {
-    console.log("");
-    console.log("  Setup already done. Run `pnpm inkbridge:dev` and open the plugin in Figma.");
-    console.log("");
-    return;
-  }
-
-  // First install — the next step is non-obvious and easy to miss in a long
-  // install log. Make it loud.
-  console.log("");
-  console.log("  ┌─────────────────────────────────────────────────────────────┐");
-  console.log("  │  ⚠  One more step — wire up the scanner API routes:        │");
-  console.log("  │                                                             │");
-  console.log("  │      pnpm exec inkbridge setup                              │");
-  console.log("  │                                                             │");
-  console.log("  │  Without this the plugin will show \"Dev server not          │");
-  console.log("  │  running\" because the routes it calls don't exist yet.      │");
-  console.log("  └─────────────────────────────────────────────────────────────┘");
-  console.log("");
-  console.log("  After setup, load the plugin in Figma Desktop:");
-  console.log("    Plugins → Development → Import plugin from manifest");
-  console.log(`    ${manifestPath}`);
+function printEnvironment(env) {
+  console.log("  Detected:");
+  console.log(`    ${statusGlyph(!!env.nextVersion)} Next.js          ${env.nextVersion || "(missing — install `next` first)"}`);
+  console.log(`    ${statusGlyph(!!env.nextConfig)} next.config      ${env.nextConfig || "(missing)"}`);
+  console.log(`    ${statusGlyph(!!env.tailwindVersion)} Tailwind CSS     ${env.tailwindVersion || "(missing — install `tailwindcss` first)"}`);
+  console.log(`    ${statusGlyph(!!env.storybookMain)} Storybook config ${env.storybookMain || "(none — design generation needs .stories.tsx files to scan)"}`);
+  console.log(`    • Component paths  ${env.componentPaths.join(", ")}${env.storybookPaths.length === 0 ? " (default — edit inkbridge.config.json to customise)" : ""}`);
   console.log("");
 }
 
-// ---------------------------------------------------------------------------
-// setup — patches package.json + creates scanner route
-// ---------------------------------------------------------------------------
 async function setup() {
+  const dryRun = process.argv.includes("--dry-run");
   const scanRouteDest = join(PROJECT_ROOT, "src/app/api/inkbridge/scan-components/route.ts");
   const scanRouteSrc = join(PACKAGE_DIR, "templates/scan-components-route.ts");
   const patchRouteDest = join(PROJECT_ROOT, "src/app/api/inkbridge/patch-tokens/route.ts");
   const patchRouteSrc = join(PACKAGE_DIR, "templates/patch-tokens-route.ts");
   const pkgPath = join(PROJECT_ROOT, "package.json");
-
-  // 1. Create inkbridge.config.json
   const inkbridgeCfgPath = join(PROJECT_ROOT, "inkbridge.config.json");
-  if (existsSync(inkbridgeCfgPath)) {
-    console.log("  ~ inkbridge.config.json already exists, skipping");
-  } else {
-    const detectedPaths = detectStorybookPaths(PROJECT_ROOT);
-    const componentPaths = detectedPaths.length > 0 ? detectedPaths : ["src"];
-    const cfg = {
-      componentPaths,
-      exclude: [],
-      onlyWithStories: true,
-    };
-    await writeFile(inkbridgeCfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
-    if (detectedPaths.length > 0) {
-      console.log(`  ✓ created inkbridge.config.json (detected paths: ${detectedPaths.join(", ")})`);
-    } else {
-      console.log("  ✓ created inkbridge.config.json (defaulting to src/ — edit to customise)");
-    }
+
+  console.log("");
+  console.log(`  inkbridge setup${dryRun ? " — dry run (no files will be written)" : ""}`);
+  console.log("");
+
+  const env = detectEnvironment(PROJECT_ROOT);
+  printEnvironment(env);
+
+  // ------------------------------------------------------------------
+  // Plan phase: figure out which writes are needed.
+  // ------------------------------------------------------------------
+  const plan = [];
+
+  if (!existsSync(inkbridgeCfgPath)) {
+    plan.push({ kind: "create", path: "inkbridge.config.json", detail: `componentPaths: [${env.componentPaths.join(", ")}]` });
+  }
+  if (!existsSync(scanRouteDest)) {
+    plan.push({ kind: "create", path: "src/app/api/inkbridge/scan-components/route.ts" });
+  }
+  if (!existsSync(patchRouteDest)) {
+    plan.push({ kind: "create", path: "src/app/api/inkbridge/patch-tokens/route.ts" });
   }
 
-  // 3. Copy scanner route
-  if (existsSync(scanRouteDest)) {
-    console.log("  ~ scanner route already exists, skipping: src/app/api/inkbridge/scan-components/route.ts");
-  } else {
-    await mkdir(dirname(scanRouteDest), { recursive: true });
-    await copyFile(scanRouteSrc, scanRouteDest);
-    console.log("  ✓ created src/app/api/inkbridge/scan-components/route.ts");
+  let pkg = null;
+  if (existsSync(pkgPath)) {
+    try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch (_e) {}
+  }
+  const scriptsToAdd = {
+    "inkbridge:dev": "next dev",
+    "inkbridge:scan": "tsx node_modules/inkbridge/scanner/cli.ts",
+  };
+  const pkgScriptAdditions = pkg
+    ? Object.entries(scriptsToAdd).filter(([k]) => !(pkg.scripts && pkg.scripts[k]))
+    : [];
+  if (pkgScriptAdditions.length > 0) {
+    plan.push({
+      kind: "modify",
+      path: "package.json",
+      detail: pkgScriptAdditions.map(([k, v]) => `scripts.${k} = "${v}"`).join("; "),
+    });
   }
 
-  if (existsSync(patchRouteDest)) {
-    console.log("  ~ token patch route already exists, skipping: src/app/api/inkbridge/patch-tokens/route.ts");
-  } else {
-    await mkdir(dirname(patchRouteDest), { recursive: true });
-    await copyFile(patchRouteSrc, patchRouteDest);
-    console.log("  ✓ created src/app/api/inkbridge/patch-tokens/route.ts");
+  const nextConfigSource = env.nextConfig ? await readFile(join(PROJECT_ROOT, env.nextConfig), "utf8") : null;
+  const nextConfigNeedsPatch = !!env.nextConfig && !nextConfigSource.includes("Access-Control-Allow-Origin");
+  if (nextConfigNeedsPatch) {
+    plan.push({
+      kind: "modify",
+      path: env.nextConfig,
+      detail: "headers() → Access-Control-Allow-* on /api/inkbridge/:path*",
+    });
   }
 
-  // 4. Patch package.json scripts
-  if (!existsSync(pkgPath)) {
-    console.warn("  ! package.json not found at project root — skipping script injection");
-  } else {
-    const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
-    pkg.scripts = pkg.scripts || {};
-    const toAdd = {
-      "inkbridge:dev": "next dev",
-      "inkbridge:scan": "tsx node_modules/inkbridge/scanner/cli.ts",
-    };
-    const added = [];
-    for (const [k, v] of Object.entries(toAdd)) {
-      if (!pkg.scripts[k]) {
-        pkg.scripts[k] = v;
-        added.push(k);
-      }
-    }
-    if (added.length > 0) {
+  if (plan.length === 0) {
+    console.log("  Nothing to do — setup is already complete.");
+    console.log("");
+    printPostSetupHint();
+    return;
+  }
+
+  console.log("  Setup will make these changes:");
+  for (const item of plan) {
+    const prefix = item.kind === "create" ? "+ create" : "~ modify";
+    console.log(`    ${prefix}  ${item.path}${item.detail ? `   (${item.detail})` : ""}`);
+  }
+  console.log("");
+
+  if (dryRun) {
+    console.log("  Dry run — no changes written. Re-run without --dry-run to apply.");
+    console.log("");
+    return;
+  }
+
+  // ------------------------------------------------------------------
+  // Apply phase.
+  // ------------------------------------------------------------------
+  for (const item of plan) {
+    if (item.path === "inkbridge.config.json") {
+      const cfg = {
+        componentPaths: env.componentPaths,
+        exclude: [],
+        onlyWithStories: true,
+      };
+      await writeFile(inkbridgeCfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    } else if (item.path === "src/app/api/inkbridge/scan-components/route.ts") {
+      await mkdir(dirname(scanRouteDest), { recursive: true });
+      await copyFile(scanRouteSrc, scanRouteDest);
+    } else if (item.path === "src/app/api/inkbridge/patch-tokens/route.ts") {
+      await mkdir(dirname(patchRouteDest), { recursive: true });
+      await copyFile(patchRouteSrc, patchRouteDest);
+    } else if (item.path === "package.json") {
+      pkg.scripts = pkg.scripts || {};
+      for (const [k, v] of pkgScriptAdditions) pkg.scripts[k] = v;
       await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
-      for (const k of added) console.log(`  ✓ added script: ${k}`);
-    } else {
-      console.log("  ~ scripts already present, skipping");
+    } else if (env.nextConfig && item.path === env.nextConfig) {
+      await patchNextConfig(PROJECT_ROOT);
+      continue;  // patchNextConfig already prints
     }
+    const prefix = item.kind === "create" ? "✓ created" : "✓ modified";
+    console.log(`  ${prefix}  ${item.path}`);
   }
 
-  // 5. Patch next.config to expose CORS headers for the Figma plugin iframe
-  await patchNextConfig(PROJECT_ROOT);
+  console.log("");
+  printPostSetupHint();
+}
 
-  // 6. Print manifest path
+function printPostSetupHint() {
   const manifestPath = resolve(PROJECT_ROOT, "node_modules/inkbridge/manifest.json");
-  console.log("");
   console.log("  About the routes:");
   console.log("    src/app/api/inkbridge/scan-components/route.ts");
   console.log("        runs the scanner and returns your component definitions");
@@ -226,12 +278,12 @@ async function setup() {
   console.log("        writes Figma-edited tokens back to your CSS source on Push.");
   console.log("    Don't move or delete these — the plugin won't work without them.");
   console.log("");
-  console.log("  Setup complete. Load the plugin in Figma Desktop:");
+  console.log("  Load the plugin in Figma Desktop:");
   console.log("    Plugins → Development → Import plugin from manifest");
   console.log(`    ${manifestPath}`);
   console.log("");
   console.log("  Start developing:");
-  console.log("    pnpm inkbridge:dev    (starts Next.js dev server for scan + token patch routes)");
+  console.log("    pnpm inkbridge:dev    (Next.js dev server for the scan + token patch routes)");
   console.log("    pnpm inkbridge:scan   (manually re-scan components)");
   console.log("");
 }
@@ -308,9 +360,6 @@ async function installSkill() {
 // dispatch
 // ---------------------------------------------------------------------------
 switch (command) {
-  case "postinstall":
-    await postinstall();
-    break;
   case "setup":
     await setup();
     break;