inkhouse 0.1.0-beta.0

package/README.md

@@ -0,0 +1,201 @@
+# Inkhouse
+
+Generates native Figma frames from your Tailwind React components and syncs design tokens back to your codebase via GitHub PRs.
+
+## What it does
+
+| Feature | Description |
+|---|---|
+| **Generate Design System Page** | Scans your Storybook stories and builds a pixel-accurate Figma page from your Tailwind classes |
+| **Push to Code** | Creates a GitHub PR from Figma token changes. Source can be CSS-first (`auto`/`css`) or DTCG (`dtcg`). |
+| **Detect & Sync Changes** | Detects class-level changes in Figma frames and proposes them as a GitHub PR |
+| **Dev Mode codegen** | Shows Tailwind class names for any selected node in Figma Dev Mode |
+
+---
+
+## Requirements
+
+- **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`)
+
+---
+
+## Installation
+
+### 1. Install the package
+
+```bash
+pnpm add -D inkhouse
+pnpm exec inkhouse setup
+```
+
+`setup` does three things automatically:
+- Creates `inkhouse.config.json` in your project root (auto-detects component paths from `.storybook/main.ts`)
+- Creates the scanner API route at `src/app/api/figma/scan-components/route.ts`
+- Creates the token patch API route at `src/app/api/figma/patch-tokens/route.ts`
+- Adds `figma:dev` and `figma:scan` scripts to your `package.json`
+
+### 2. Load the plugin in Figma Desktop
+
+1. Open Figma Desktop
+2. Go to **Plugins → Development → Import plugin from manifest...**
+3. Select `node_modules/inkhouse/manifest.json` from your project root
+
+Figma remembers this path — you only do this once.
+
+### 3. Start your dev server
+
+```bash
+pnpm figma:dev
+```
+
+The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
+
+> **The plugin will not work without the dev server running.**
+
+---
+
+## Usage
+
+### Generate Design System Page
+
+1. Start dev server: `pnpm figma:dev`
+2. Open any Figma file
+3. **Plugins → Development → Inkhouse → Generate Design System Page**
+4. The plugin scans your Storybook stories and builds a "Design System" page
+
+Component data is always scanned live on every run — never stale. Re-run at any time to pick up changes.
+
+### Manual scan
+
+```bash
+pnpm figma:scan
+```
+
+Writes `.inkhouse/component-definitions.json`. Useful for debugging scanner output.
+
+### Push to Code (Pro)
+
+Requires a Pro license and GitHub configuration.
+
+1. **Plugins → Development → Inkhouse → Settings**
+2. Fill in:
+   - **GitHub owner** — your org or username (e.g. `acme-corp`)
+   - **Repository** — repo name (e.g. `my-app`)
+   - **Base branch** — default `main`
+   - **Token Source Mode** — `auto` (default), `css`, or `dtcg`
+   - **CSS Token Path** — optional override (e.g. `src/app/tokens.css`)
+   - **DTCG Token Path** — used in `dtcg` mode and as fallback in `auto`
+   - **Also update DTCG on Push to Code** — optional; includes DTCG artifact in CSS-first pushes
+   - **Allow New Tokens from Figma** — optional; permits creating new token keys on push (off by default)
+   - **New Token Prefixes** — optional comma-separated allowlist (for example `chart-, brand-`)
+   - **GitHub token** — a [fine-grained PAT](https://github.com/settings/tokens?type=beta) with `Contents` and `Pull requests` read & write
+   - **License key** — from your Inkhouse account
+3. **Save Settings**
+4. **Plugins → Development → Inkhouse → Push to Code**
+5. Enter a commit message and click **Push Tokens to Code** (it auto-detects token changes and opens the PR step)
+6. Review the detected changes and click **Create Pull Request**
+
+---
+
+## Configuration
+
+Edit `inkhouse.config.json` in your project root:
+
+```json
+{
+  "componentPaths": ["src/components", "src/features"],
+  "exclude": ["ui", "index"],
+  "onlyWithStories": true
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `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 |
+
+The scanner re-reads this file on every scan — no server restart needed.
+
+---
+
+## Troubleshooting
+
+### "Dev server not reachable"
+
+The plugin cannot connect to `localhost:4000`, `:3000`, or `:5173`.
+
+- Make sure `pnpm figma: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 figma:dev`) so `/api/figma/patch-tokens` is available
+- Re-import the plugin from `node_modules/inkhouse/manifest.json` after updating
+- Re-open the plugin and retry **Push Tokens to Code**
+
+### Theme rename/new theme only commits one changed token
+
+- Ensure your project route `src/app/api/figma/patch-tokens/route.ts` is up to date:
+
+```bash
+pnpm exec inkhouse setup
+```
+
+- Restart the dev server after route/template updates
+- Expected behavior:
+  - stale theme blocks are removed (for example `secondary`)
+  - new/missing theme blocks are written as full blocks (for example full `client2`), not sparse one-line patches
+
+### "Incompatible scanner contract"
+
+The plugin and scanner are out of sync. Update to the latest version:
+
+```bash
+pnpm update inkhouse
+```
+
+Then close and re-open the plugin in Figma.
+
+### Design system page looks wrong after code changes
+
+Re-run **Generate Design System Page** — it always reflects the current state of your components.
+
+### Font weight/style looks different in Figma
+
+The plugin uses a nearest-weight fallback strategy. Make sure the target font family is installed/enabled in Figma.
+
+---
+
+## Updating
+
+```bash
+pnpm update inkhouse
+```
+
+Component data is always scanned live — you only need to update when a new `inkhouse` version ships rendering improvements.
+
+---
+
+## Architecture
+
+```
+Figma plugin (sandboxed)
+    └── code.js            Main logic — cannot make network requests directly
+    └── ui.html            Hidden iframe — relays all network requests to code.js
+
+code.js  →  ui.html  →  localhost:4000/api/figma/scan-components
+                     →  localhost:4000/api/figma/patch-tokens
+                     →  https://api.github.com
+```
+
+All network I/O is relayed through the UI iframe via `postMessage` due to the Figma sandbox restriction.
+
+---
+
+## License
+
+MIT

package/bin/inkhouse.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+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.
+const PROJECT_ROOT = process.env.INIT_CWD || process.cwd();
+
+const [, , command = "help"] = process.argv;
+
+function detectStorybookPaths(root) {
+  const candidates = [
+    ".storybook/main.ts",
+    ".storybook/main.js",
+    ".storybook/main.mjs",
+    ".storybook/main.cjs",
+  ];
+  for (const candidate of candidates) {
+    const fullPath = join(root, candidate);
+    if (!existsSync(fullPath)) continue;
+    const content = readFileSync(fullPath, "utf-8");
+    const storiesMatch = content.match(/stories\s*:\s*\[([^\]]+)\]/s);
+    if (!storiesMatch) continue;
+    const globs = [...storiesMatch[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map(m => m[1]);
+    const dirs = new Set();
+    for (const glob of globs) {
+      const normalized = glob.replace(/^\.\.\//, "");
+      const first = normalized.split("/")[0];
+      if (first && !first.includes("*") && !first.includes("{")) dirs.add(first);
+    }
+    if (dirs.size > 0) return [...dirs];
+  }
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// postinstall — called automatically after `pnpm add -D inkhouse`
+// ---------------------------------------------------------------------------
+async function postinstall() {
+  const pkg = JSON.parse(await readFile(join(PACKAGE_DIR, "package.json"), "utf8"));
+  const manifestPath = join(PROJECT_ROOT, "node_modules/inkhouse/manifest.json");
+
+  console.log("");
+  console.log(`  ✓ inkhouse v${pkg.version} installed`);
+  console.log("");
+  console.log("  Next: run setup to wire up the scanner endpoint and scripts:");
+  console.log("    pnpm exec inkhouse setup");
+  console.log("");
+  console.log("  Then load the plugin in Figma Desktop:");
+  console.log("    Plugins → Development → Import plugin from manifest");
+  console.log(`    ${manifestPath}`);
+  console.log("");
+}
+
+// ---------------------------------------------------------------------------
+// setup — patches package.json + creates scanner route
+// ---------------------------------------------------------------------------
+async function setup() {
+  const scanRouteDest = join(PROJECT_ROOT, "src/app/api/figma/scan-components/route.ts");
+  const scanRouteSrc = join(PACKAGE_DIR, "templates/scan-components-route.ts");
+  const patchRouteDest = join(PROJECT_ROOT, "src/app/api/figma/patch-tokens/route.ts");
+  const patchRouteSrc = join(PACKAGE_DIR, "templates/patch-tokens-route.ts");
+  const pkgPath = join(PROJECT_ROOT, "package.json");
+
+  // 1. Create inkhouse.config.json
+  const inkhouseCfgPath = join(PROJECT_ROOT, "inkhouse.config.json");
+  if (existsSync(inkhouseCfgPath)) {
+    console.log("  ~ inkhouse.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(inkhouseCfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    if (detectedPaths.length > 0) {
+      console.log(`  ✓ created inkhouse.config.json (detected paths: ${detectedPaths.join(", ")})`);
+    } else {
+      console.log("  ✓ created inkhouse.config.json (defaulting to src/ — edit to customise)");
+    }
+  }
+
+  // 3. Copy scanner route
+  if (existsSync(scanRouteDest)) {
+    console.log("  ~ scanner route already exists, skipping: src/app/api/figma/scan-components/route.ts");
+  } else {
+    await mkdir(dirname(scanRouteDest), { recursive: true });
+    await copyFile(scanRouteSrc, scanRouteDest);
+    console.log("  ✓ created src/app/api/figma/scan-components/route.ts");
+  }
+
+  if (existsSync(patchRouteDest)) {
+    console.log("  ~ token patch route already exists, skipping: src/app/api/figma/patch-tokens/route.ts");
+  } else {
+    await mkdir(dirname(patchRouteDest), { recursive: true });
+    await copyFile(patchRouteSrc, patchRouteDest);
+    console.log("  ✓ created src/app/api/figma/patch-tokens/route.ts");
+  }
+
+  // 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 = {
+      "figma:dev": "next dev",
+      "figma:scan": "tsx node_modules/inkhouse/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) {
+      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");
+    }
+  }
+
+  // 5. Print manifest path
+  const manifestPath = resolve(PROJECT_ROOT, "node_modules/inkhouse/manifest.json");
+  console.log("");
+  console.log("  Setup complete. 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 figma:dev    (starts Next.js dev server for scan + token patch routes)");
+  console.log("    pnpm figma:scan   (manually re-scan components)");
+  console.log("");
+}
+
+// ---------------------------------------------------------------------------
+// path — print manifest path (useful reference)
+// ---------------------------------------------------------------------------
+function printPath() {
+  const manifestPath = resolve(PROJECT_ROOT, "node_modules/inkhouse/manifest.json");
+  console.log(manifestPath);
+}
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+switch (command) {
+  case "postinstall":
+    await postinstall();
+    break;
+  case "setup":
+    await setup();
+    break;
+  case "path":
+    printPath();
+    break;
+  default:
+    console.log("Usage:");
+    console.log("  inkhouse setup    Wire up scanner/token-patch routes + scripts (run once after install)");
+    console.log("  inkhouse path     Print the manifest.json path for Figma Desktop");
+    break;
+}