inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

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;
@@ -39,106 +40,306 @@ function detectStorybookPaths(root) {
 }
 
 // ---------------------------------------------------------------------------
-// postinstall — called automatically after `pnpm add -D inkbridge`
+// Patch next.config.* to allow the Figma plugin UI (null origin) to fetch
+// assets from the dev server. Without this, <Image> srcs, SVGs, etc. fail CORS.
 // ---------------------------------------------------------------------------
-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");
+async function patchNextConfig(root) {
+  const candidates = ["next.config.ts", "next.config.js", "next.config.mjs", "next.config.cjs"];
+  let configPath = null;
+  for (const candidate of candidates) {
+    const full = join(root, candidate);
+    if (existsSync(full)) { configPath = full; break; }
+  }
+  if (!configPath) {
+    console.log("  ~ next.config not found — skipping CORS headers patch");
+    return;
+  }
 
-  console.log("");
-  console.log(`  ✓ inkbridge v${pkg.version} installed`);
-  console.log("");
-  console.log("  Next: run setup to wire up the scanner endpoint and scripts:");
-  console.log("    pnpm exec inkbridge 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("");
+  const source = await readFile(configPath, "utf8");
+  if (source.includes("Access-Control-Allow-Origin")) {
+    console.log("  ~ next.config already exposes CORS headers, skipping");
+    return;
+  }
+
+  const headersBlock = `
+  // 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: [
+          { key: "Access-Control-Allow-Origin", value: "*" },
+          { key: "Access-Control-Allow-Methods", value: "GET" },
+        ],
+      },
+    ];
+  },`;
+
+  // Inject right after the opening `{` of the config object. Matches either
+  // `const nextConfig: NextConfig = {` or `const nextConfig = {` or `module.exports = {`.
+  const patterns = [
+    /(const\s+\w+\s*(?::\s*\w+\s*)?=\s*)\{/,
+    /(module\.exports\s*=\s*)\{/,
+    /(export\s+default\s*)\{/,
+  ];
+  let patched = null;
+  for (const re of patterns) {
+    const match = source.match(re);
+    if (!match) continue;
+    const idx = match.index + match[0].length;
+    patched = source.slice(0, idx) + headersBlock + source.slice(idx);
+    break;
+  }
+
+  if (!patched) {
+    console.log("  ! could not locate config object in " + configPath + " — add CORS headers manually");
+    return;
+  }
+
+  await writeFile(configPath, patched, "utf8");
+  console.log("  ✓ patched " + configPath.replace(root + "/", "") + " with CORS headers");
 }
 
 // ---------------------------------------------------------------------------
 // setup — patches package.json + creates scanner route
 // ---------------------------------------------------------------------------
+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"],
+  };
+}
+
+function statusGlyph(present) { return present ? "✓" : "✗"; }
+
+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("");
+}
+
 async function setup() {
-  const scanRouteDest = join(PROJECT_ROOT, "src/app/api/figma/scan-components/route.ts");
+  const dryRun = process.argv.includes("--dry-run");
+  // `--force` re-creates the inkbridge-managed files (route templates,
+  // inkbridge.config.json) even when they already exist. Useful when a
+  // newer plugin version ships an updated template (e.g. the
+  // INKBRIDGE_LOCAL check in the scanner route) and the consumer wants
+  // to refresh without hand-editing. Never touches package.json or
+  // next.config — those are partial-edit territory and force-rewriting
+  // them would clobber consumer state.
+  const force = process.argv.includes("--force");
+  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/figma/patch-tokens/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)" : ""}${force ? " — force (overwrite existing inkbridge files)" : ""}`);
+  console.log("");
+
+  const env = detectEnvironment(PROJECT_ROOT);
+  printEnvironment(env);
+
+  // ------------------------------------------------------------------
+  // Plan phase: figure out which writes are needed.
+  // ------------------------------------------------------------------
+  const plan = [];
+
+  if (!existsSync(inkbridgeCfgPath) || force) {
+    plan.push({
+      kind: existsSync(inkbridgeCfgPath) ? "overwrite" : "create",
+      path: "inkbridge.config.json",
+      detail: `componentPaths: [${env.componentPaths.join(", ")}]`,
+    });
+  }
+  if (!existsSync(scanRouteDest) || force) {
+    plan.push({
+      kind: existsSync(scanRouteDest) ? "overwrite" : "create",
+      path: "src/app/api/inkbridge/scan-components/route.ts",
+    });
+  }
+  if (!existsSync(patchRouteDest) || force) {
+    plan.push({
+      kind: existsSync(patchRouteDest) ? "overwrite" : "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/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/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) {
+  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("; "),
+    });
+  }
+
+  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*",
+    });
+  }
+
+  // Make sure the scanner-output directory is gitignored. The API
+  // route writes `.inkbridge/component-definitions.json` on every
+  // plugin run; without this entry consumers see the file in their
+  // diff after every `pnpm inkbridge:scan`.
+  const gitignorePath = join(PROJECT_ROOT, ".gitignore");
+  const gitignoreSource = existsSync(gitignorePath)
+    ? readFileSync(gitignorePath, "utf8")
+    : "";
+  const gitignoreNeedsPatch = existsSync(join(PROJECT_ROOT, ".git"))
+    && !gitignoreSource.split("\n").some(line => {
+      const trimmed = line.trim();
+      return trimmed === ".inkbridge" || trimmed === ".inkbridge/";
+    });
+  if (gitignoreNeedsPatch) {
+    plan.push({
+      kind: "modify",
+      path: ".gitignore",
+      detail: "+ .inkbridge/   (scanner output)",
+    });
+  }
+
+  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"
+      : item.kind === "overwrite"
+        ? "↻ overwrite"
+        : "~ 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
+    } else if (item.path === ".gitignore") {
+      const existing = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, "utf8")
+        : "";
+      const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n");
+      const block = (needsLeadingNewline ? "\n" : "")
+        + "\n# Inkbridge scanner output (regenerated on every plugin run)\n.inkbridge/\n";
+      await writeFile(gitignorePath, existing + block, "utf8");
     }
+    const prefix = item.kind === "create"
+      ? "✓ created"
+      : item.kind === "overwrite"
+        ? "✓ overwrote"
+        : "✓ modified";
+    console.log(`  ${prefix}  ${item.path}`);
   }
 
-  // 5. Print manifest path
+  console.log("");
+  printPostSetupHint();
+}
+
+function printPostSetupHint() {
   const manifestPath = resolve(PROJECT_ROOT, "node_modules/inkbridge/manifest.json");
+  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");
+  console.log("        (the plugin calls this every time you click Generate).");
+  console.log("    src/app/api/inkbridge/patch-tokens/route.ts");
+  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 figma:dev    (starts Next.js dev server for scan + token patch routes)");
-  console.log("    pnpm figma:scan   (manually re-scan components)");
+  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("");
 }
 
@@ -150,22 +351,92 @@ function printPath() {
   console.log(manifestPath);
 }
 
+// ---------------------------------------------------------------------------
+// skill — install the Inkbridge AI skill into the consuming project's
+// .claude/skills/ folder. Maintainer-only convenience: lets developers who
+// extend the plugin (us, the starter, future internal projects) get the
+// canonical agent context without copy-pasting Markdown around.
+//
+// Two modes, picked automatically:
+//   - **Sibling mode**: if `../inkbridge/.claude/skills/inkbridge-figma-plugin`
+//     exists relative to PROJECT_ROOT, create a symlink. Edits in inkbridge
+//     propagate immediately. This is what the starter / co-located projects
+//     should use.
+//   - **Fetch mode**: otherwise, clone the skill folder from
+//     github.com/inkn9ne/inkbridge via degit. Snapshot install — re-run to
+//     update. This is what non-co-located projects should use.
+// ---------------------------------------------------------------------------
+import { symlink, rm } from "fs/promises";
+
+const SKILL_REL_PATH = ".claude/skills/inkbridge-figma-plugin";
+
+async function installSkill() {
+  const target = join(PROJECT_ROOT, SKILL_REL_PATH);
+  const siblingSource = resolve(PROJECT_ROOT, "..", "inkbridge", SKILL_REL_PATH);
+
+  await mkdir(dirname(target), { recursive: true });
+
+  if (existsSync(siblingSource)) {
+    // Sibling mode — symlink for live updates from the inkbridge repo
+    if (existsSync(target)) {
+      console.log(`  ~ ${SKILL_REL_PATH} already exists — removing to relink`);
+      await rm(target, { recursive: true, force: true });
+    }
+    const relativeSource = resolve(siblingSource);
+    await symlink(relativeSource, target, "dir");
+    console.log(`  ✓ symlinked ${SKILL_REL_PATH} → ${relativeSource}`);
+    console.log("");
+    console.log("  Sibling-mode install. Edits in the inkbridge repo's");
+    console.log("  .claude/skills/inkbridge-figma-plugin/ will propagate here");
+    console.log("  immediately. Reload Claude Code to pick up the skill.");
+    return;
+  }
+
+  // Fetch mode — pull the current main from GitHub via degit
+  if (existsSync(target)) {
+    console.log(`  ~ ${SKILL_REL_PATH} already exists — re-fetching to update`);
+    await rm(target, { recursive: true, force: true });
+  }
+  const { spawn } = await import("child_process");
+  const args = ["degit", "inkn9ne/inkbridge/.claude/skills/inkbridge-figma-plugin", target];
+  console.log(`  ↓ npx ${args.join(" ")}`);
+  await new Promise((resolve, reject) => {
+    const child = spawn("npx", args, { stdio: "inherit" });
+    child.on("exit", code => (code === 0 ? resolve() : reject(new Error(`degit exited ${code}`))));
+    child.on("error", reject);
+  });
+  console.log(`  ✓ installed ${SKILL_REL_PATH} from inkn9ne/inkbridge`);
+  console.log("");
+  console.log("  Fetch-mode install (snapshot from main). Re-run");
+  console.log("  `pnpm exec inkbridge skill install` to update.");
+}
+
 // ---------------------------------------------------------------------------
 // dispatch
 // ---------------------------------------------------------------------------
 switch (command) {
-  case "postinstall":
-    await postinstall();
-    break;
   case "setup":
     await setup();
     break;
   case "path":
     printPath();
     break;
+  case "skill": {
+    const sub = process.argv[3];
+    if (sub === "install") {
+      await installSkill();
+    } else {
+      console.log("Usage:");
+      console.log("  inkbridge skill install   Install the AI skill into .claude/skills/");
+      console.log("                            (symlinks to ../inkbridge if co-located,");
+      console.log("                            otherwise fetches via degit from GitHub)");
+    }
+    break;
+  }
   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 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)");
     break;
 }