inkbridge 0.1.0-beta.23 → 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;
 }