inkbridge 0.1.0-beta.24 → 0.1.0-beta.25

package/README.md

@@ -41,10 +41,17 @@ pnpm exec inkbridge setup
 - 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)
 - Appends `.inkbridge/` to your `.gitignore` so the scanner-output JSON doesn't show up in every diff
 
+No `package.json` scripts are added by default — the plugin works through the API routes via your normal `pnpm dev`. If you're developing the plugin source itself and want the maintainer local-link scripts, pass `--dev`:
+
+```bash
+pnpm exec inkbridge setup --dev
+```
+
+That adds five maintainer scripts to `package.json`: `inkbridge:plugin:which`, `inkbridge:plugin:use-beta`, `inkbridge:plugin:use-local`, `inkbridge:dev:local`, `inkbridge:scan:local`.
+
 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
@@ -58,7 +65,7 @@ Figma remembers this path — you only do this once.
 ### 3. Start your dev server
 
 ```bash
-pnpm inkbridge:dev
+pnpm dev
 ```
 
 The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
@@ -71,7 +78,7 @@ The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
 
 ### Generate Design System Page
 
-1. Start dev server: `pnpm inkbridge:dev`
+1. Start dev server: `pnpm dev`
 2. Open any Figma file
 3. **Plugins → Development → Inkbridge → Generate Design System Page**
 4. The plugin scans your Storybook stories and builds a "Design System" page with token tables, themed columns, grouped component sections, and responsive/state preview blocks where relevant
@@ -88,11 +95,15 @@ When a story instance uses non-default style/behavior props (for example `classN
 
 ### Manual scan
 
+Scans happen automatically every time you click **Generate Design System Page** — the plugin calls `GET /api/inkbridge/scan-components` on your dev server and reads the response live. There is no manual step in the normal workflow.
+
+For debugging scanner output, you can invoke the scanner CLI directly:
+
 ```bash
-pnpm inkbridge:scan
+pnpm tsx node_modules/inkbridge/scanner/cli.ts
 ```
 
-Writes `.inkbridge/component-definitions.json`. Useful for debugging scanner output.
+That writes `.inkbridge/component-definitions.json` to disk. (If you ran `inkbridge setup --dev`, the `inkbridge:scan:local` script gives you the sibling-repo variant.)
 
 ### Push to Code
 
@@ -238,13 +249,13 @@ Full reference at [inkbridge.ink/docs/responsive-previews](https://inkbridge.ink
 
 The plugin cannot connect to `localhost:4000`, `:3000`, or `:5173`.
 
-- Make sure `pnpm inkbridge:dev` is running
+- Make sure `pnpm dev` is running
 - Check the terminal for errors in the Next.js server
 - Make sure you're using **Figma Desktop** — the browser version blocks localhost
 
 ### "Create Pull Request" does nothing / no PR opens
 
-- Restart your dev server (`pnpm inkbridge:dev`) so `/api/inkbridge/patch-tokens` is available
+- Restart your dev server (`pnpm dev`) so `/api/inkbridge/patch-tokens` is available
 - Re-import the plugin from `node_modules/inkbridge/manifest.json` after updating
 - Re-open the plugin and retry **Push Tokens to Code**
 

package/bin/inkbridge.mjs

@@ -165,6 +165,13 @@ async function setup() {
   // next.config — those are partial-edit territory and force-rewriting
   // them would clobber consumer state.
   const force = process.argv.includes("--force");
+  // `--dev` opts the consumer into maintainer/dev-loop scripts (local-link
+  // mode, version probes, `:use-beta` / `:use-local` switches). The default
+  // setup writes no package.json scripts at all — the plugin works
+  // end-to-end via the scan + patch API routes alone. Use `--dev` only when
+  // you're working on the plugin source itself (sibling `../inkbridge/`
+  // checkout) and need the local-link toggle.
+  const devMode = process.argv.includes("--dev");
   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");
@@ -173,7 +180,7 @@ async function setup() {
   const inkbridgeCfgPath = join(PROJECT_ROOT, "inkbridge.config.json");
 
   console.log("");
-  console.log(`  inkbridge setup${dryRun ? " — dry run (no files will be written)" : ""}${force ? " — force (overwrite existing inkbridge files)" : ""}`);
+  console.log(`  inkbridge setup${dryRun ? " — dry run (no files will be written)" : ""}${force ? " — force (overwrite existing inkbridge files)" : ""}${devMode ? " — dev (install maintainer scripts)" : ""}`);
   console.log("");
 
   const env = detectEnvironment(PROJECT_ROOT);
@@ -208,10 +215,21 @@ async function setup() {
   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",
-  };
+  // Default consumer setup writes no package.json scripts — the plugin
+  // works via the scan + patch API routes alone. `--dev` adds the
+  // maintainer-only loop (local-link toggle, version probe, `:use-beta` /
+  // `:use-local` switches). Anyone working on the plugin source itself
+  // (sibling `../inkbridge/` checkout) wants these; ordinary consumers
+  // should not see them in their package.json.
+  const scriptsToAdd = devMode
+    ? {
+        "inkbridge:dev:local": "INKBRIDGE_LOCAL=1 next dev",
+        "inkbridge:scan:local": "tsx ../inkbridge/tools/figma-plugin/scanner/cli.ts",
+        "inkbridge:plugin:which": "node -e \"const p=require('./package.json'); console.log('inkbridge =>', (p.devDependencies&&p.devDependencies.inkbridge)||(p.dependencies&&p.dependencies.inkbridge)||'not-set')\"",
+        "inkbridge:plugin:use-beta": "pnpm add -D inkbridge@beta",
+        "inkbridge:plugin:use-local": "pnpm add -D inkbridge@file:../inkbridge/tools/figma-plugin",
+      }
+    : {};
   const pkgScriptAdditions = pkg
     ? Object.entries(scriptsToAdd).filter(([k]) => !(pkg.scripts && pkg.scripts[k]))
     : [];
@@ -338,8 +356,16 @@ function printPostSetupHint() {
   console.log(`    ${manifestPath}`);
   console.log("");
   console.log("  Start developing:");
-  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("    pnpm dev              (your project's Next.js dev server — also serves the scan + token patch routes)");
+  if (devMode) {
+    console.log("");
+    console.log("  Maintainer scripts installed (--dev):");
+    console.log("    pnpm inkbridge:plugin:which        Print the installed inkbridge version");
+    console.log("    pnpm inkbridge:plugin:use-beta     Switch back to the npm beta tag");
+    console.log("    pnpm inkbridge:plugin:use-local    Switch to file:../inkbridge/tools/figma-plugin");
+    console.log("    pnpm inkbridge:dev:local           Next.js dev with INKBRIDGE_LOCAL=1 (sibling repo scanner)");
+    console.log("    pnpm inkbridge:scan:local          Manually re-scan via sibling repo's scanner");
+  }
   console.log("");
 }
 
@@ -435,8 +461,11 @@ switch (command) {
   }
   default:
     console.log("Usage:");
-    console.log("  inkbridge setup           Wire up scanner/token-patch routes + scripts (run once after install)");
-    console.log("  inkbridge path            Print the manifest.json path for Figma Desktop");
-    console.log("  inkbridge skill install   Install the AI development skill (maintainers only)");
+    console.log("  inkbridge setup            Wire up scanner/token-patch routes (run once after install)");
+    console.log("    --dev                    Also install maintainer-only scripts (local-link, version probe, use-beta/use-local)");
+    console.log("    --force                  Overwrite the route templates + inkbridge.config.json from this plugin version");
+    console.log("    --dry-run                Print the plan without writing files");
+    console.log("  inkbridge path             Print the manifest.json path for Figma Desktop");
+    console.log("  inkbridge skill install    Install the AI development skill (maintainers only)");
     break;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inkbridge",
-  "version": "0.1.0-beta.24",
+  "version": "0.1.0-beta.25",
   "description": "Generate a Figma design system from your Storybook stories — Tailwind React components rendered as native frames, design tokens, component states, and round-trip code sync.",
   "type": "module",
   "bin": {

package/scanner/cli.ts

@@ -141,10 +141,9 @@ async function main() {
     // wrote in their own files — no leaked Tailwind defaults like
     // `serif: ui-serif, Georgia, Cambria, …` or the lone Tailwind
     // `spacing: 0.25rem` baseline value.
-    const finalOutput: typeof output & {
-      tokens?: ReturnType<typeof readTokenSourceMap>;
-      consumerTokens?: ReturnType<typeof readConsumerOwnedTokenMap>;
-    } = output;
+    //
+    // Both fields are declared optional on `ComponentDefinitions`, so they
+    // assign straight onto `output` — no inline intersection type needed.
     if (CLI_INCLUDE_TOKENS) {
       const baseOpts = {
         projectRoot: process.cwd(),
@@ -152,8 +151,8 @@ async function main() {
         cssTokenPath: CLI_CSS_TOKEN_PATH,
         dtcgTokenPath: CLI_DTCG_TOKEN_PATH,
       };
-      finalOutput.tokens = readTokenSourceMap(baseOpts);
-      finalOutput.consumerTokens = readConsumerOwnedTokenMap(baseOpts);
+      output.tokens = readTokenSourceMap(baseOpts);
+      output.consumerTokens = readConsumerOwnedTokenMap(baseOpts);
     }
 
     // Write to JSON file. Default matches the consumer-side path used by
@@ -172,7 +171,7 @@ async function main() {
     // programmatically by the plugin runtime — the indentation cost was
     // ~30% of the file size for no functional benefit. If you need to
     // hand-inspect it, pipe through `jq` (`jq . component-definitions.json`).
-    fs.writeFileSync(outputPath, JSON.stringify(finalOutput));
+    fs.writeFileSync(outputPath, JSON.stringify(output));
 
     const totalStories = analyses.reduce((sum, a) => sum + (a.stories?.length || 0), 0);
 

package/scanner/types.ts

@@ -5,6 +5,8 @@
  * will use to generate design system components.
  */
 
+import type { ScannedTokenMap } from '../src/tokens/token-source';
+
 // ============================================================================
 // Component Analysis Types
 // ============================================================================
@@ -289,6 +291,21 @@ export interface ComponentDefinitions {
 
   /** Tailwind class -> CSS declaration map */
   styleMap?: Record<string, StyleRuleEntry[]>;
+
+  /**
+   * Token maps, emitted only when the scanner runs with `--include-tokens`.
+   *
+   * `tokens` — full merged map (Tailwind/tw-animate-css defaults pulled in via
+   * `@import "tailwindcss"` + consumer overrides). Drives the runtime token
+   * resolver so utilities like `text-sm` keep resolving when unoverridden.
+   *
+   * `consumerTokens` — consumer-only scan (bare `@import`s skipped). Drives the
+   * Design Tokens panel so it shows only what the consumer wrote, not leaked
+   * Tailwind defaults. See `scanner/cli.ts` and the "two scans" section in
+   * `.ai/architecture.md`.
+   */
+  tokens?: ScannedTokenMap;
+  consumerTokens?: ScannedTokenMap;
 }
 
 export interface StyleRuleEntry {

package/templates/patch-tokens-route.ts

@@ -155,6 +155,15 @@ function patchCssVariables(cssText: string, updatesByTheme: ThemeUpdateMap): str
 }
 
 export async function POST(request: Request): Promise<NextResponse> {
+  // Production guard. The Figma plugin only ever calls this on localhost
+  // during design work. Exposing the route on a deployed app gains
+  // nothing but adds a DoS vector (postcss-parses arbitrary `cssText`,
+  // CORS `*`, no auth). Returning 404 (rather than 403) makes the route
+  // indistinguishable from a missing endpoint — no signal to attackers
+  // that something is here.
+  if (process.env.NODE_ENV === 'production') {
+    return new NextResponse(null, { status: 404 });
+  }
   try {
     const payload = (await request.json()) as PatchPayload;
     const cssText = typeof payload.cssText === 'string' ? payload.cssText : '';
@@ -180,5 +189,8 @@ export async function POST(request: Request): Promise<NextResponse> {
 }
 
 export async function OPTIONS(): Promise<NextResponse> {
+  if (process.env.NODE_ENV === 'production') {
+    return new NextResponse(null, { status: 404 });
+  }
   return new NextResponse(null, { headers: CORS });
 }

package/templates/scan-components-route.ts

@@ -46,6 +46,15 @@ const CORS = {
 type ScannerOutput = Record<string, unknown>;
 
 export async function GET(request: Request): Promise<NextResponse> {
+  // Production guard. The Figma plugin only ever calls this on localhost
+  // during design work, so exposing the route on a deployed app gains
+  // nothing but adds a DoS vector (every call spawns `tsx` running the
+  // scanner CLI — CPU-heavy, no rate limit, CORS `*`). Returning 404
+  // (rather than 403) makes the route indistinguishable from a missing
+  // endpoint — no signal to attackers that something is here.
+  if (process.env.NODE_ENV === 'production') {
+    return new NextResponse(null, { status: 404 });
+  }
   try {
     const url = new URL(request.url);
     const tokenSourceMode = url.searchParams.get('tokenSourceMode') || 'auto';
@@ -82,5 +91,8 @@ export async function GET(request: Request): Promise<NextResponse> {
 }
 
 export async function OPTIONS(): Promise<NextResponse> {
+  if (process.env.NODE_ENV === 'production') {
+    return new NextResponse(null, { status: 404 });
+  }
   return new NextResponse(null, { headers: CORS });
 }