mini-figma-code-connect 0.1.1 → 0.1.4

package/LICENSE

@@ -1,16 +1,18 @@
-MIT License
+Proprietary License
 
 Copyright (c) 2026 elaine.ma
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+All rights reserved.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+This software and associated documentation files (the "Software") are the
+proprietary property of the copyright holder.
+
+Permission is granted to install and use the Software via the published npm
+package for your own projects, subject to the npm package terms.
+
+You may not copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software source code, except as allowed by applicable law or
+with prior written permission from the copyright holder.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
@@ -19,3 +21,5 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Issues and feedback: https://github.com/elainema0215/mini-figma-code-connect/issues

package/README.md

@@ -2,8 +2,9 @@
 
 **Local Code Connect for Figma Professional** — 无 Org / Enterprise 也能做确定性的 `f(instance) → snippet`。
 
-面向 Pro 档团队的轻量替代引擎：Figma 插件 + 将设计组件映射到消费方真实代码库的工作流。
+> 源码未开源。npm 仅分发编译产物（`dist/`）。问题与反馈请到 [GitHub Issues](https://github.com/elainema0215/mini-figma-code-connect/issues)。
 
+面向 Pro 档团队的轻量替代引擎：Figma 插件 + 将设计组件映射到消费方真实代码库的工作流。
 官方 Code Connect 与 Builder.io Design System Intelligence 均要求 Organization / Enterprise 订阅；团队当前为 Professional，相关 MCP 绑定工具不可用。本引擎在本地实现等价的「组件绑定 + 属性映射」：映射进消费方仓库、执行在 Figma 插件，不依赖云端 publish。插件沙箱无法读写本地代码，因此映射生成在沙箱外（agent / CLI）完成，再经构建打包进插件。
 
 ---
@@ -56,7 +57,7 @@ pnpm add -D mini-figma-code-connect
 # 或：npm install -D mini-figma-code-connect
 ```
 
-本地开发引擎时仍可用 `link:` / `file:` 指向仓库路径。包尚未安装时，后续 CLI 命令均不存在。
+包尚未安装时，后续 CLI 命令均不存在。
 
 #### 2. 执行一次性脚手架
 
@@ -107,7 +108,7 @@ pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id>
 
 无 agent 可用时，`pnpm exec figma-mapping <schema.json>` 提供本地正则打分作为兜底方案（同样支持批量 schema 数组与 `--ai` 模式），判断准确度低于 agent 现场读取代码，但落盘规则保持一致。
 
-### 常见问题
+## 常见问题
 
 1. **Q:** 命令找不到 / `EACCES: spawn …`  
    **A:** 先在已安装依赖的目录执行 `pnpm install`，刷新 `node_modules/.bin`。若仍报错，多半是引擎包脚本权限问题，反馈给引擎仓库。
@@ -120,3 +121,13 @@ pnpm exec mini-code-connect-scaffold-manifest --id <manifest-id>
 
 4. **Q:** 改了 manifest，Figma 没变化？  
    **A:** `editorType` / `capabilities` 在导入时缓存。需在 Figma 里删掉该开发插件后重新导入。`figma-plugin-dist/` 下的 `code.js` / `ui.html` 每次运行都会重读，改构建产物不必重导。
+
+5. **Q:** 导入/运行插件时报 `EPERM: operation not permitted, open '…/figma-plugin-dist/code.js'`，或提示 *Unable to load code* / *loading the plugin environment*？  
+   **A:** 这通常不是包本身坏了，而是 **macOS 隐私权限拦住了 Figma 读取本地文件**（项目在 `Desktop` / `Documents` 下时很常见）。处理：
+   1. **系统设置 → 隐私与安全性 → 文件与文件夹**（必要时再开「完全磁盘访问权限」），给 **Figma** 勾选桌面 / 文稿等对应目录。
+   2. 完全退出并重启 Figma。
+   3. 在 Development 里删掉旧插件后，重新 **Import plugin from manifest…**。  
+   也可把消费方仓库挪出受保护目录（例如 `~/Projects/`）再导入。
+
+6. **Q:** `pnpm exec mini-code-connect-scaffold-plugin --id …` 报 `generate-registry: glob 里没有 *: "--id"`？  
+   **A:** `0.1.3` 打包把多个 CLI 打进同一文件，导致 `generate-registry` 误跑并把 `--id` 当成 glob。请升级到 **`>=0.1.4`** 后重试。

package/dist/build.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+// scripts/build-plugin.mjs
+import * as esbuild from "esbuild";
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path4 from "node:path";
+
+// scripts/is-cli-entrypoint.mjs
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function isCliEntrypoint(importMetaUrl, entryName) {
+  if (!process.argv[1]) return false;
+  try {
+    const argvPath = realpathSync(process.argv[1]);
+    const metaPath = realpathSync(fileURLToPath(importMetaUrl));
+    if (argvPath !== metaPath) return false;
+    if (entryName) {
+      return path.basename(argvPath).includes(entryName);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function findPackageRoot(importMetaUrl) {
+  let dir = path.dirname(fileURLToPath(importMetaUrl));
+  while (true) {
+    const pkgPath = path.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.name === "mini-figma-code-connect") return dir;
+      } catch {
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      throw new Error("[mini-figma-code-connect] \u627E\u4E0D\u5230\u5305\u6839\u76EE\u5F55\uFF08package.json\uFF09");
+    }
+    dir = parent;
+  }
+}
+
+// scripts/generate-registry.mjs
+import fs from "node:fs";
+import path2 from "node:path";
+function parseGlob(glob) {
+  const starIdx = glob.indexOf("*");
+  if (starIdx === -1) throw new Error(`generate-registry: glob \u91CC\u6CA1\u6709 *\uFF1A"${glob}"`);
+  const dir = glob.slice(0, starIdx).replace(/\/$/, "");
+  const recursive = glob.includes("**");
+  return { dir, recursive };
+}
+function findFigmaFiles(dir, recursive) {
+  const results = [];
+  function walk(d) {
+    if (!fs.existsSync(d)) return;
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const full = path2.join(d, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive) walk(full);
+      } else if (entry.name.endsWith(".figma.ts")) {
+        results.push(full);
+      }
+    }
+  }
+  walk(dir);
+  return results.sort();
+}
+function identifierFor(filePath, index) {
+  const base = path2.basename(filePath).replace(/\.figma\.ts$/, "").replace(/[^a-zA-Z0-9]/g, "");
+  const safe = base && /^[a-zA-Z_]/.test(base) ? base : `M${base}`;
+  return `${safe || "Mapping"}_${index}`;
+}
+function generateRegistry({ cwd, mappingsGlob, outFile, typesImport = "./types" }) {
+  const { dir, recursive } = parseGlob(mappingsGlob);
+  const files = findFigmaFiles(path2.resolve(cwd, dir), recursive);
+  const outDir = path2.dirname(outFile);
+  const imports = files.map((f, i) => {
+    const id = identifierFor(f, i);
+    let rel = path2.relative(outDir, f).replace(/\.ts$/, "");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    rel = rel.split(path2.sep).join("/");
+    return { id, importPath: rel };
+  });
+  const typeLine = typesImport == null ? "" : `import type { Template } from '${typesImport}'
+`;
+  const templatesAnn = typesImport == null ? "" : ": Template[]";
+  const body = `// \u81EA\u52A8\u751F\u6210\uFF0C\u4E0D\u8981\u624B\u6539 \u2014\u2014 \u7531 scripts/generate-registry.mjs \u626B .figma.ts \u751F\u6210\uFF0C\u6BCF\u6B21 build \u524D\u91CD\u8DD1
+` + typeLine + imports.map((i) => `import ${i.id} from '${i.importPath}'`).join("\n") + (imports.length ? "\n\n" : "\n") + `export const templates${templatesAnn} = [${imports.map((i) => i.id).join(", ")}]
+`;
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(outFile, body);
+  return { count: files.length, files };
+}
+if (isCliEntrypoint(import.meta.url, "generate-registry")) {
+  const [, , mappingsGlob, outFile] = process.argv;
+  if (!mappingsGlob || !outFile) {
+    console.error("\u7528\u6CD5: node scripts/generate-registry.mjs <mappingsGlob> <outFile>");
+    process.exit(1);
+  }
+  const result = generateRegistry({ cwd: process.cwd(), mappingsGlob, outFile: path2.resolve(outFile) });
+  console.log(`[generate-registry] \u5199\u5165 ${result.count} \u6761\u6620\u5C04\u5230 ${outFile}`);
+}
+
+// scripts/copy-mapping-table.mjs
+import fs2 from "node:fs";
+import path3 from "node:path";
+function copyMappingTable({ cwd, mappingTablePath, outFile }) {
+  const src = path3.resolve(cwd, mappingTablePath);
+  const content = fs2.existsSync(src) ? fs2.readFileSync(src, "utf8") : "[]\n";
+  fs2.mkdirSync(path3.dirname(outFile), { recursive: true });
+  fs2.writeFileSync(outFile, content);
+  return { found: fs2.existsSync(src) };
+}
+
+// scripts/build-plugin.mjs
+var PACKAGE_ROOT = findPackageRoot(import.meta.url);
+function resolvePluginEntries(packageRoot) {
+  const main = path4.join(packageRoot, "dist/main/code.js");
+  const ui = path4.join(packageRoot, "dist/ui/ui.js");
+  const html = path4.join(packageRoot, "dist/ui/ui.html");
+  for (const file of [main, ui, html]) {
+    if (!existsSync2(file)) {
+      throw new Error(
+        `[build-plugin] \u7F3A\u5C11 ${file}\u3002\u8BF7\u5148\u5728\u5F15\u64CE\u5305\u76EE\u5F55\u6267\u884C npm run build\uFF08\u53EA\u4F7F\u7528 dist/\uFF0C\u4E0D\u56DE\u9000 src/\uFF09\u3002`
+      );
+    }
+  }
+  return { main, ui, html };
+}
+function consumerGeneratedPlugin(genDir) {
+  const registryFile = path4.join(genDir, "registry.generated.ts");
+  const mappingTableFile = path4.join(genDir, "mapping-table.generated.json");
+  return {
+    name: "consumer-generated",
+    setup(build2) {
+      build2.onResolve({ filter: /(?:^|[\\/])registry\.generated(?:\.(?:ts|js))?$/ }, () => ({
+        path: registryFile
+      }));
+      build2.onResolve({ filter: /(?:^|[\\/])mapping-table\.generated\.json$/ }, () => ({
+        path: mappingTableFile
+      }));
+    }
+  };
+}
+async function buildPlugin({
+  cwd,
+  mappingsGlob,
+  mappingTablePath = "figma-mapping-table.json",
+  outDir = "dist",
+  watch = false
+}) {
+  const { main: mainEntry, ui: uiEntry, html: uiHtml } = resolvePluginEntries(PACKAGE_ROOT);
+  const absOutDir = path4.resolve(cwd, outDir);
+  const genDir = path4.join(absOutDir, ".generated");
+  const registryOut = path4.join(genDir, "registry.generated.ts");
+  const mappingTableOut = path4.join(genDir, "mapping-table.generated.json");
+  const { count } = generateRegistry({
+    cwd,
+    mappingsGlob,
+    outFile: registryOut,
+    typesImport: null
+  });
+  console.log(`[build-plugin] \u626B\u5230 ${count} \u6761\u6620\u5C04\uFF08${mappingsGlob}\uFF09`);
+  const { found } = copyMappingTable({ cwd, mappingTablePath, outFile: mappingTableOut });
+  if (!found) console.log(`[build-plugin] \u6CA1\u627E\u5230 ${mappingTablePath}\uFF0C\u4E0B\u8F7D\u6309\u94AE\u4F1A\u7ED9\u7A7A\u6570\u7EC4`);
+  const generatedPlugin = consumerGeneratedPlugin(genDir);
+  const inlineUi = {
+    name: "inline-ui",
+    setup(build2) {
+      build2.onEnd(async (res) => {
+        if (res.errors.length) return;
+        const js = res.outputFiles ? res.outputFiles[0].text : await readFile(path4.join(absOutDir, ".ui.tmp.js"), "utf8");
+        const html = await readFile(uiHtml, "utf8");
+        await mkdir(absOutDir, { recursive: true });
+        await writeFile(path4.join(absOutDir, "ui.html"), html.replace("/*__UI_JS__*/", () => js));
+        console.log(`[inline-ui] ${path4.join(outDir, "ui.html")} \u5DF2\u66F4\u65B0`);
+      });
+    }
+  };
+  const codeOpts = {
+    entryPoints: [mainEntry],
+    bundle: true,
+    format: "iife",
+    target: "es2020",
+    outfile: path4.join(absOutDir, "code.js"),
+    logLevel: "info",
+    plugins: [generatedPlugin]
+  };
+  const uiOpts = {
+    entryPoints: [uiEntry],
+    bundle: true,
+    format: "iife",
+    target: "es2020",
+    outfile: path4.join(absOutDir, ".ui.tmp.js"),
+    logLevel: "warning",
+    plugins: [inlineUi, generatedPlugin]
+  };
+  if (watch) {
+    const a = await esbuild.context(codeOpts);
+    const b = await esbuild.context(uiOpts);
+    await Promise.all([a.watch(), b.watch()]);
+    console.log("[build-plugin] watching...");
+    return { watching: true };
+  }
+  await esbuild.build(codeOpts);
+  await esbuild.build(uiOpts);
+  return { watching: false };
+}
+if (isCliEntrypoint(import.meta.url, "build")) {
+  const args = process.argv.slice(2);
+  const watch = args.includes("--watch");
+  const outIdx = args.indexOf("--out");
+  const outDir = outIdx !== -1 ? args[outIdx + 1] : "dist";
+  const mappingsGlob = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--out");
+  if (!mappingsGlob) {
+    console.error("\u7528\u6CD5: node scripts/build-plugin.mjs <mappingsGlob> [--out dist] [--watch]");
+    process.exit(1);
+  }
+  await buildPlugin({ cwd: process.cwd(), mappingsGlob, outDir, watch });
+}
+export {
+  buildPlugin
+};