devlens-mcp 0.4.2 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +211 -35
  2. package/RELEASE_NOTES.md +3 -7
  3. package/dist/bin/cli.js +41 -14
  4. package/dist/bin/cli.js.map +1 -1
  5. package/dist/bin/setup.d.ts +14 -0
  6. package/dist/bin/setup.d.ts.map +1 -0
  7. package/dist/bin/setup.js +272 -0
  8. package/dist/bin/setup.js.map +1 -0
  9. package/dist/src/figma/figma-api.d.ts +108 -0
  10. package/dist/src/figma/figma-api.d.ts.map +1 -0
  11. package/dist/src/figma/figma-api.js +284 -0
  12. package/dist/src/figma/figma-api.js.map +1 -0
  13. package/dist/src/figma/figma-cache.d.ts +57 -0
  14. package/dist/src/figma/figma-cache.d.ts.map +1 -0
  15. package/dist/src/figma/figma-cache.js +266 -0
  16. package/dist/src/figma/figma-cache.js.map +1 -0
  17. package/dist/src/figma/figma-client.d.ts +62 -0
  18. package/dist/src/figma/figma-client.d.ts.map +1 -0
  19. package/dist/src/figma/figma-client.js +224 -0
  20. package/dist/src/figma/figma-client.js.map +1 -0
  21. package/dist/src/figma/figma-rate-limiter.d.ts +46 -0
  22. package/dist/src/figma/figma-rate-limiter.d.ts.map +1 -0
  23. package/dist/src/figma/figma-rate-limiter.js +153 -0
  24. package/dist/src/figma/figma-rate-limiter.js.map +1 -0
  25. package/dist/src/figma/figma-retry.d.ts +19 -0
  26. package/dist/src/figma/figma-retry.d.ts.map +1 -0
  27. package/dist/src/figma/figma-retry.js +57 -0
  28. package/dist/src/figma/figma-retry.js.map +1 -0
  29. package/dist/src/figma/figma-structure.d.ts +1 -1
  30. package/dist/src/figma/figma-structure.d.ts.map +1 -1
  31. package/dist/src/figma/figma-structure.js +11 -1
  32. package/dist/src/figma/figma-structure.js.map +1 -1
  33. package/dist/src/figma/figma-types.d.ts +54 -0
  34. package/dist/src/figma/figma-types.d.ts.map +1 -0
  35. package/dist/src/figma/figma-types.js +33 -0
  36. package/dist/src/figma/figma-types.js.map +1 -0
  37. package/dist/src/figma/url-parser.d.ts +40 -0
  38. package/dist/src/figma/url-parser.d.ts.map +1 -0
  39. package/dist/src/figma/url-parser.js +107 -0
  40. package/dist/src/figma/url-parser.js.map +1 -0
  41. package/dist/src/platform/device-manager.d.ts +5 -0
  42. package/dist/src/platform/device-manager.d.ts.map +1 -1
  43. package/dist/src/platform/device-manager.js +18 -0
  44. package/dist/src/platform/device-manager.js.map +1 -1
  45. package/dist/src/platform/device-pool.d.ts +105 -0
  46. package/dist/src/platform/device-pool.d.ts.map +1 -0
  47. package/dist/src/platform/device-pool.js +328 -0
  48. package/dist/src/platform/device-pool.js.map +1 -0
  49. package/dist/src/platform/device-profiles.d.ts +50 -0
  50. package/dist/src/platform/device-profiles.d.ts.map +1 -0
  51. package/dist/src/platform/device-profiles.js +155 -0
  52. package/dist/src/platform/device-profiles.js.map +1 -0
  53. package/dist/src/platform/ios/ios-device.d.ts +0 -2
  54. package/dist/src/platform/ios/ios-device.d.ts.map +1 -1
  55. package/dist/src/platform/ios/ios-device.js +8 -18
  56. package/dist/src/platform/ios/ios-device.js.map +1 -1
  57. package/dist/src/platform/ios/simctl.d.ts +0 -5
  58. package/dist/src/platform/ios/simctl.d.ts.map +1 -1
  59. package/dist/src/platform/ios/simctl.js +0 -4
  60. package/dist/src/platform/ios/simctl.js.map +1 -1
  61. package/dist/src/platform/simulator-factory.d.ts +85 -0
  62. package/dist/src/platform/simulator-factory.d.ts.map +1 -0
  63. package/dist/src/platform/simulator-factory.js +396 -0
  64. package/dist/src/platform/simulator-factory.js.map +1 -0
  65. package/dist/src/platform/system-resources.d.ts +44 -0
  66. package/dist/src/platform/system-resources.d.ts.map +1 -0
  67. package/dist/src/platform/system-resources.js +103 -0
  68. package/dist/src/platform/system-resources.js.map +1 -0
  69. package/dist/src/prototype/browser-engine.d.ts +62 -0
  70. package/dist/src/prototype/browser-engine.d.ts.map +1 -0
  71. package/dist/src/prototype/browser-engine.js +199 -0
  72. package/dist/src/prototype/browser-engine.js.map +1 -0
  73. package/dist/src/prototype/figma-navigator.d.ts +40 -0
  74. package/dist/src/prototype/figma-navigator.d.ts.map +1 -0
  75. package/dist/src/prototype/figma-navigator.js +95 -0
  76. package/dist/src/prototype/figma-navigator.js.map +1 -0
  77. package/dist/src/prototype/flow-reporter.d.ts +47 -0
  78. package/dist/src/prototype/flow-reporter.d.ts.map +1 -0
  79. package/dist/src/prototype/flow-reporter.js +255 -0
  80. package/dist/src/prototype/flow-reporter.js.map +1 -0
  81. package/dist/src/prototype/screen-analyzer.d.ts +31 -0
  82. package/dist/src/prototype/screen-analyzer.d.ts.map +1 -0
  83. package/dist/src/prototype/screen-analyzer.js +114 -0
  84. package/dist/src/prototype/screen-analyzer.js.map +1 -0
  85. package/dist/src/prototype/web-crawler.d.ts +31 -0
  86. package/dist/src/prototype/web-crawler.d.ts.map +1 -0
  87. package/dist/src/prototype/web-crawler.js +88 -0
  88. package/dist/src/prototype/web-crawler.js.map +1 -0
  89. package/dist/src/reports/cross-device-report.d.ts +84 -0
  90. package/dist/src/reports/cross-device-report.d.ts.map +1 -0
  91. package/dist/src/reports/cross-device-report.js +342 -0
  92. package/dist/src/reports/cross-device-report.js.map +1 -0
  93. package/dist/src/server.d.ts.map +1 -1
  94. package/dist/src/server.js +9 -1
  95. package/dist/src/server.js.map +1 -1
  96. package/dist/src/snapshot/formatter.d.ts +5 -13
  97. package/dist/src/snapshot/formatter.d.ts.map +1 -1
  98. package/dist/src/snapshot/formatter.js +19 -28
  99. package/dist/src/snapshot/formatter.js.map +1 -1
  100. package/dist/src/tools/interaction-tools.d.ts +6 -6
  101. package/dist/src/tools/interaction-tools.d.ts.map +1 -1
  102. package/dist/src/tools/interaction-tools.js +2 -12
  103. package/dist/src/tools/interaction-tools.js.map +1 -1
  104. package/dist/src/tools/metro-tools.d.ts +2 -2
  105. package/dist/src/tools/multi-device-tools.d.ts +133 -0
  106. package/dist/src/tools/multi-device-tools.d.ts.map +1 -0
  107. package/dist/src/tools/multi-device-tools.js +365 -0
  108. package/dist/src/tools/multi-device-tools.js.map +1 -0
  109. package/dist/src/tools/navigation-tools.d.ts.map +1 -1
  110. package/dist/src/tools/navigation-tools.js +1 -6
  111. package/dist/src/tools/navigation-tools.js.map +1 -1
  112. package/dist/src/tools/prototype-tools.d.ts +102 -0
  113. package/dist/src/tools/prototype-tools.d.ts.map +1 -0
  114. package/dist/src/tools/prototype-tools.js +391 -0
  115. package/dist/src/tools/prototype-tools.js.map +1 -0
  116. package/dist/src/tools/screenshot-tools.d.ts +7 -74
  117. package/dist/src/tools/screenshot-tools.d.ts.map +1 -1
  118. package/dist/src/tools/screenshot-tools.js +19 -286
  119. package/dist/src/tools/screenshot-tools.js.map +1 -1
  120. package/dist/src/tools/vqa-tools.d.ts +2 -2
  121. package/dist/src/tools/vqa-tools.d.ts.map +1 -1
  122. package/dist/src/tools/vqa-tools.js +4 -69
  123. package/dist/src/tools/vqa-tools.js.map +1 -1
  124. package/docs/figma-workflow.md +58 -6
  125. package/docs/installation-guide.md +302 -0
  126. package/docs/setup-guide.md +77 -79
  127. package/docs/tool-reference.md +152 -69
  128. package/install.sh +119 -0
  129. package/package.json +5 -2
  130. package/setup.sh +320 -0
  131. package/tsconfig.json +1 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"figma-api.js","sourceRoot":"","sources":["../../../src/figma/figma-api.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Two-tier cache: in-memory LRU + disk persistence.
3
+ * Memory tier provides sub-ms reads. Disk tier survives MCP restarts.
4
+ */
5
+ import type { CacheStats } from "./figma-types.js";
6
+ export declare class FigmaCache {
7
+ private memory;
8
+ private memoryUsedBytes;
9
+ private readonly memoryMaxBytes;
10
+ private readonly cacheDir;
11
+ private diskIndex;
12
+ private hits;
13
+ private misses;
14
+ constructor(config?: {
15
+ cacheDir?: string;
16
+ memoryMaxBytes?: number;
17
+ });
18
+ private initDiskCache;
19
+ private saveDiskIndex;
20
+ private hashKey;
21
+ private estimateSize;
22
+ private evictMemoryIfNeeded;
23
+ /**
24
+ * Get a value. Checks memory first, then disk. Returns undefined on miss.
25
+ */
26
+ get<T>(key: string): T | undefined;
27
+ /**
28
+ * Store a value in both memory and disk caches.
29
+ */
30
+ set(key: string, value: unknown, ttlMs: number): void;
31
+ /**
32
+ * Check if key exists and is not expired.
33
+ */
34
+ has(key: string): boolean;
35
+ /**
36
+ * Get value even if expired — for stale-while-revalidate fallback.
37
+ */
38
+ getStale<T>(key: string): {
39
+ value: T;
40
+ ageMs: number;
41
+ } | undefined;
42
+ /**
43
+ * Invalidate all entries matching a prefix.
44
+ * Used for version-gated invalidation: invalidatePrefix(`file:${fileKey}`)
45
+ */
46
+ invalidatePrefix(prefix: string): number;
47
+ /**
48
+ * Clear all caches.
49
+ */
50
+ clear(): void;
51
+ /**
52
+ * Get cache statistics.
53
+ */
54
+ stats(): CacheStats;
55
+ private removeDiskEntry;
56
+ }
57
+ //# sourceMappingURL=figma-cache.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"figma-cache.d.ts","sourceRoot":"","sources":["../../../src/figma/figma-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkBnD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,SAAS,CAAqC;IAEtD,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAMnE,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,mBAAmB;IAW3B;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IA+ClC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAmCrD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQzB;;OAEG;IACH,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAgCjE;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAuBxC;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,KAAK,IAAI,UAAU;IAYnB,OAAO,CAAC,eAAe;CAWxB"}
@@ -0,0 +1,266 @@
1
+ "use strict";
2
+ /**
3
+ * Two-tier cache: in-memory LRU + disk persistence.
4
+ * Memory tier provides sub-ms reads. Disk tier survives MCP restarts.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.FigmaCache = void 0;
8
+ const node_crypto_1 = require("node:crypto");
9
+ const node_fs_1 = require("node:fs");
10
+ const node_path_1 = require("node:path");
11
+ const node_os_1 = require("node:os");
12
+ const DEFAULT_CACHE_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".devlens", "cache");
13
+ const DEFAULT_MEMORY_MAX_BYTES = 50 * 1024 * 1024; // 50MB
14
+ const INDEX_FILE = "index.json";
15
+ class FigmaCache {
16
+ memory = new Map();
17
+ memoryUsedBytes = 0;
18
+ memoryMaxBytes;
19
+ cacheDir;
20
+ diskIndex = new Map();
21
+ hits = 0;
22
+ misses = 0;
23
+ constructor(config) {
24
+ this.cacheDir = config?.cacheDir ?? process.env.DEVLENS_CACHE_DIR ?? DEFAULT_CACHE_DIR;
25
+ this.memoryMaxBytes = config?.memoryMaxBytes ?? DEFAULT_MEMORY_MAX_BYTES;
26
+ this.initDiskCache();
27
+ }
28
+ initDiskCache() {
29
+ try {
30
+ if (!(0, node_fs_1.existsSync)(this.cacheDir)) {
31
+ (0, node_fs_1.mkdirSync)(this.cacheDir, { recursive: true });
32
+ }
33
+ const indexPath = (0, node_path_1.join)(this.cacheDir, INDEX_FILE);
34
+ if ((0, node_fs_1.existsSync)(indexPath)) {
35
+ const raw = JSON.parse((0, node_fs_1.readFileSync)(indexPath, "utf-8"));
36
+ if (Array.isArray(raw)) {
37
+ for (const [key, entry] of raw) {
38
+ this.diskIndex.set(key, entry);
39
+ }
40
+ }
41
+ }
42
+ }
43
+ catch {
44
+ // Disk cache unavailable — memory-only mode
45
+ }
46
+ }
47
+ saveDiskIndex() {
48
+ try {
49
+ const indexPath = (0, node_path_1.join)(this.cacheDir, INDEX_FILE);
50
+ const data = JSON.stringify([...this.diskIndex.entries()]);
51
+ (0, node_fs_1.writeFileSync)(indexPath, data, "utf-8");
52
+ }
53
+ catch {
54
+ // Ignore disk write failures
55
+ }
56
+ }
57
+ hashKey(key) {
58
+ return (0, node_crypto_1.createHash)("sha256").update(key).digest("hex").slice(0, 32);
59
+ }
60
+ estimateSize(value) {
61
+ if (Buffer.isBuffer(value))
62
+ return value.length;
63
+ const json = JSON.stringify(value);
64
+ return json ? json.length * 2 : 64;
65
+ }
66
+ evictMemoryIfNeeded(requiredBytes) {
67
+ if (this.memoryUsedBytes + requiredBytes <= this.memoryMaxBytes)
68
+ return;
69
+ // Evict oldest entries first (Map preserves insertion order)
70
+ for (const [key, entry] of this.memory) {
71
+ this.memory.delete(key);
72
+ this.memoryUsedBytes -= entry.sizeBytes;
73
+ if (this.memoryUsedBytes + requiredBytes <= this.memoryMaxBytes)
74
+ break;
75
+ }
76
+ }
77
+ /**
78
+ * Get a value. Checks memory first, then disk. Returns undefined on miss.
79
+ */
80
+ get(key) {
81
+ const now = Date.now();
82
+ // Memory check
83
+ const memEntry = this.memory.get(key);
84
+ if (memEntry) {
85
+ if (memEntry.expiresAt > now) {
86
+ this.hits++;
87
+ // Move to end for LRU
88
+ this.memory.delete(key);
89
+ this.memory.set(key, memEntry);
90
+ return memEntry.value;
91
+ }
92
+ // Expired — remove
93
+ this.memory.delete(key);
94
+ this.memoryUsedBytes -= memEntry.sizeBytes;
95
+ }
96
+ // Disk check (don't remove expired entries — getStale() needs them)
97
+ const diskEntry = this.diskIndex.get(key);
98
+ if (diskEntry && diskEntry.expiresAt > now) {
99
+ try {
100
+ const filePath = diskEntry.filePath;
101
+ if ((0, node_fs_1.existsSync)(filePath)) {
102
+ const value = diskEntry.isBinary
103
+ ? (0, node_fs_1.readFileSync)(filePath)
104
+ : JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
105
+ // Promote to memory
106
+ const sizeBytes = this.estimateSize(value);
107
+ this.evictMemoryIfNeeded(sizeBytes);
108
+ this.memory.set(key, { value, expiresAt: diskEntry.expiresAt, sizeBytes });
109
+ this.memoryUsedBytes += sizeBytes;
110
+ this.hits++;
111
+ return value;
112
+ }
113
+ }
114
+ catch {
115
+ // Corrupted disk entry — remove it
116
+ this.removeDiskEntry(key);
117
+ }
118
+ }
119
+ this.misses++;
120
+ return undefined;
121
+ }
122
+ /**
123
+ * Store a value in both memory and disk caches.
124
+ */
125
+ set(key, value, ttlMs) {
126
+ const now = Date.now();
127
+ const expiresAt = now + ttlMs;
128
+ const sizeBytes = this.estimateSize(value);
129
+ // Memory tier
130
+ const existing = this.memory.get(key);
131
+ if (existing) {
132
+ this.memoryUsedBytes -= existing.sizeBytes;
133
+ this.memory.delete(key);
134
+ }
135
+ this.evictMemoryIfNeeded(sizeBytes);
136
+ this.memory.set(key, { value, expiresAt, sizeBytes });
137
+ this.memoryUsedBytes += sizeBytes;
138
+ // Disk tier
139
+ try {
140
+ const hash = this.hashKey(key);
141
+ const isBinary = Buffer.isBuffer(value);
142
+ const ext = isBinary ? ".bin" : ".json";
143
+ const filePath = (0, node_path_1.join)(this.cacheDir, `${hash}${ext}`);
144
+ if (isBinary) {
145
+ (0, node_fs_1.writeFileSync)(filePath, value);
146
+ }
147
+ else {
148
+ (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(value), "utf-8");
149
+ }
150
+ this.diskIndex.set(key, { expiresAt, filePath, isBinary });
151
+ this.saveDiskIndex();
152
+ }
153
+ catch {
154
+ // Disk write failure — value is still in memory
155
+ }
156
+ }
157
+ /**
158
+ * Check if key exists and is not expired.
159
+ */
160
+ has(key) {
161
+ const now = Date.now();
162
+ const memEntry = this.memory.get(key);
163
+ if (memEntry && memEntry.expiresAt > now)
164
+ return true;
165
+ const diskEntry = this.diskIndex.get(key);
166
+ return !!diskEntry && diskEntry.expiresAt > now;
167
+ }
168
+ /**
169
+ * Get value even if expired — for stale-while-revalidate fallback.
170
+ */
171
+ getStale(key) {
172
+ const now = Date.now();
173
+ // Check memory (even expired)
174
+ const memEntry = this.memory.get(key);
175
+ if (memEntry) {
176
+ const ttlMs = memEntry.expiresAt - now;
177
+ const ageMs = ttlMs < 0 ? -ttlMs : 0;
178
+ return { value: memEntry.value, ageMs };
179
+ }
180
+ // Check disk (even expired)
181
+ const diskEntry = this.diskIndex.get(key);
182
+ if (diskEntry) {
183
+ try {
184
+ const filePath = diskEntry.filePath;
185
+ if ((0, node_fs_1.existsSync)(filePath)) {
186
+ const value = diskEntry.isBinary
187
+ ? (0, node_fs_1.readFileSync)(filePath)
188
+ : JSON.parse((0, node_fs_1.readFileSync)(filePath, "utf-8"));
189
+ const ttlMs = diskEntry.expiresAt - now;
190
+ const ageMs = ttlMs < 0 ? -ttlMs : 0;
191
+ return { value: value, ageMs };
192
+ }
193
+ }
194
+ catch {
195
+ // Corrupted
196
+ }
197
+ }
198
+ return undefined;
199
+ }
200
+ /**
201
+ * Invalidate all entries matching a prefix.
202
+ * Used for version-gated invalidation: invalidatePrefix(`file:${fileKey}`)
203
+ */
204
+ invalidatePrefix(prefix) {
205
+ const invalidatedKeys = new Set();
206
+ for (const [key, entry] of this.memory) {
207
+ if (key.startsWith(prefix)) {
208
+ this.memoryUsedBytes -= entry.sizeBytes;
209
+ this.memory.delete(key);
210
+ invalidatedKeys.add(key);
211
+ }
212
+ }
213
+ for (const [key] of this.diskIndex) {
214
+ if (key.startsWith(prefix)) {
215
+ this.removeDiskEntry(key);
216
+ invalidatedKeys.add(key);
217
+ }
218
+ }
219
+ const count = invalidatedKeys.size;
220
+ if (count > 0)
221
+ this.saveDiskIndex();
222
+ return count;
223
+ }
224
+ /**
225
+ * Clear all caches.
226
+ */
227
+ clear() {
228
+ this.memory.clear();
229
+ this.memoryUsedBytes = 0;
230
+ for (const [key] of this.diskIndex) {
231
+ this.removeDiskEntry(key);
232
+ }
233
+ this.saveDiskIndex();
234
+ this.hits = 0;
235
+ this.misses = 0;
236
+ }
237
+ /**
238
+ * Get cache statistics.
239
+ */
240
+ stats() {
241
+ const total = this.hits + this.misses;
242
+ return {
243
+ memoryEntries: this.memory.size,
244
+ diskEntries: this.diskIndex.size,
245
+ memoryBytes: this.memoryUsedBytes,
246
+ hitRate: total > 0 ? this.hits / total : 0,
247
+ hits: this.hits,
248
+ misses: this.misses,
249
+ };
250
+ }
251
+ removeDiskEntry(key) {
252
+ const entry = this.diskIndex.get(key);
253
+ if (entry) {
254
+ try {
255
+ if ((0, node_fs_1.existsSync)(entry.filePath))
256
+ (0, node_fs_1.unlinkSync)(entry.filePath);
257
+ }
258
+ catch {
259
+ // Ignore deletion failure
260
+ }
261
+ this.diskIndex.delete(key);
262
+ }
263
+ }
264
+ }
265
+ exports.FigmaCache = FigmaCache;
266
+ //# sourceMappingURL=figma-cache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"figma-cache.js","sourceRoot":"","sources":["../../../src/figma/figma-cache.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Unified Figma API client with cache → dedup → rate limit → retry pipeline.
3
+ * Every Figma interaction should go through this class.
4
+ */
5
+ import { type FigmaClientConfig, type CacheStats, type RateLimiterStatus } from "./figma-types.js";
6
+ export declare class FigmaClient {
7
+ private cache;
8
+ private rateLimiter;
9
+ private inflight;
10
+ private maxRetries;
11
+ constructor(config?: FigmaClientConfig);
12
+ /**
13
+ * Resolve a Figma node → PNG Buffer.
14
+ * Main entry point for comparison/VQA tools.
15
+ */
16
+ resolveImage(params: {
17
+ fileKey: string;
18
+ nodeId: string;
19
+ scale?: number;
20
+ token: string;
21
+ }): Promise<{
22
+ buffer: Buffer;
23
+ cached: boolean;
24
+ error?: never;
25
+ } | {
26
+ error: string;
27
+ buffer?: never;
28
+ cached?: never;
29
+ }>;
30
+ /**
31
+ * Fetch file data (shallow, depth=2).
32
+ */
33
+ fetchFileData(fileKey: string, token: string): Promise<unknown>;
34
+ /**
35
+ * Fetch full file data (no depth limit, for prototype analysis).
36
+ */
37
+ fetchFileDataFull(fileKey: string, token: string): Promise<unknown>;
38
+ /**
39
+ * Fetch node layout structure.
40
+ */
41
+ fetchStructure(fileKey: string, nodeId: string, token: string): Promise<unknown>;
42
+ /**
43
+ * Batch export multiple node images (single API call).
44
+ */
45
+ exportImages(fileKey: string, nodeIds: string[], scale: number, token: string): Promise<Map<string, string>>;
46
+ /**
47
+ * Generic API GET with full pipeline: cache → dedup → rate limit → retry.
48
+ */
49
+ apiGet<T>(path: string, token: string, opts?: {
50
+ ttlMs?: number;
51
+ skipCache?: boolean;
52
+ cacheKey?: string;
53
+ }): Promise<T>;
54
+ getStats(): {
55
+ cache: CacheStats;
56
+ rateLimiter: RateLimiterStatus;
57
+ };
58
+ logStats(): void;
59
+ private executeFetch;
60
+ }
61
+ export declare function getFigmaClient(config?: FigmaClientConfig): FigmaClient;
62
+ //# sourceMappingURL=figma-client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"figma-client.d.ts","sourceRoot":"","sources":["../../../src/figma/figma-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAU1B,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,CAAC,EAAE,iBAAiB;IAatC;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,CAAA;KAAE,CAAC;IAsEnH;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrE;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzE;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQtF;;OAEG;IACG,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAyB/B;;OAEG;IACG,MAAM,CAAC,CAAC,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAChE,OAAO,CAAC,CAAC,CAAC;IAgCb,QAAQ,IAAI;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,iBAAiB,CAAA;KAAE;IAOjE,QAAQ,IAAI,IAAI;YAYF,YAAY;CAkC3B;AAKD,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW,CAKtE"}
@@ -0,0 +1,224 @@
1
+ "use strict";
2
+ /**
3
+ * Unified Figma API client with cache → dedup → rate limit → retry pipeline.
4
+ * Every Figma interaction should go through this class.
5
+ */
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.FigmaClient = void 0;
8
+ exports.getFigmaClient = getFigmaClient;
9
+ const figma_cache_js_1 = require("./figma-cache.js");
10
+ const figma_rate_limiter_js_1 = require("./figma-rate-limiter.js");
11
+ const figma_retry_js_1 = require("./figma-retry.js");
12
+ const figma_types_js_1 = require("./figma-types.js");
13
+ const url_parser_js_1 = require("./url-parser.js");
14
+ const API_BASE = "https://api.figma.com/v1";
15
+ const REQUEST_TIMEOUT_MS = 20_000;
16
+ const TTL_METADATA = 24 * 60 * 60 * 1000; // 24 hours
17
+ const TTL_IMAGE = 24 * 60 * 60 * 1000; // 24 hours
18
+ const TTL_VERSION = 5 * 60 * 1000; // 5 minutes
19
+ class FigmaClient {
20
+ cache;
21
+ rateLimiter;
22
+ inflight = new Map();
23
+ maxRetries;
24
+ constructor(config) {
25
+ this.cache = new figma_cache_js_1.FigmaCache({
26
+ cacheDir: config?.cacheDir,
27
+ memoryMaxBytes: config?.memoryCacheMaxBytes,
28
+ });
29
+ this.rateLimiter = new figma_rate_limiter_js_1.FigmaRateLimiter({
30
+ initialBudget: config?.rateLimitBudget,
31
+ });
32
+ this.maxRetries = config?.maxRetries ?? 3;
33
+ }
34
+ // --- High-level methods ---
35
+ /**
36
+ * Resolve a Figma node → PNG Buffer.
37
+ * Main entry point for comparison/VQA tools.
38
+ */
39
+ async resolveImage(params) {
40
+ const { fileKey, nodeId, scale = 2, token } = params;
41
+ const normalizedId = (0, url_parser_js_1.normalizeNodeId)(nodeId);
42
+ const imageKey = `img:${fileKey}:${normalizedId}:${scale}`;
43
+ try {
44
+ // Check cache
45
+ const cached = this.cache.get(imageKey);
46
+ if (cached) {
47
+ console.error(`[figma] cache hit: image ${fileKey}/${normalizedId}@${scale}x`);
48
+ return { buffer: cached, cached: true };
49
+ }
50
+ // Step 1: Get image export URL
51
+ const urlKey = `imgurl:${fileKey}:${normalizedId}:${scale}`;
52
+ let imageUrl = this.cache.get(urlKey);
53
+ if (!imageUrl) {
54
+ const idsParam = encodeURIComponent(normalizedId);
55
+ const data = await this.apiGet(`/images/${fileKey}?ids=${idsParam}&format=png&scale=${scale}`, token, {
56
+ skipCache: true, // We cache the URL separately
57
+ });
58
+ if (data.err) {
59
+ return { error: `Figma API: ${data.err}` };
60
+ }
61
+ imageUrl = Object.values(data.images)[0] ?? undefined;
62
+ if (!imageUrl) {
63
+ return { error: `No image returned for node ${normalizedId}` };
64
+ }
65
+ this.cache.set(urlKey, imageUrl, TTL_IMAGE);
66
+ }
67
+ // Step 2: Download the image from CDN (no rate limiting needed)
68
+ const imgResponse = await fetch(imageUrl);
69
+ if (!imgResponse.ok) {
70
+ return { error: `Failed to download Figma image: ${imgResponse.status}` };
71
+ }
72
+ const buffer = Buffer.from(await imgResponse.arrayBuffer());
73
+ this.cache.set(imageKey, buffer, TTL_IMAGE);
74
+ return { buffer, cached: false };
75
+ }
76
+ catch (err) {
77
+ if (err instanceof figma_types_js_1.FigmaRateLimitError) {
78
+ // Try stale cache
79
+ const stale = this.cache.getStale(imageKey);
80
+ if (stale) {
81
+ console.error(`[figma] serving stale cache (${Math.round(stale.ageMs / 60000)}m old) — rate limited`);
82
+ return { buffer: stale.value, cached: true };
83
+ }
84
+ const info = err.info;
85
+ let msg = `Figma API rate limit exceeded. Try again in ${info.retryAfterSeconds}s.`;
86
+ if (info.rateLimitType === "low") {
87
+ msg = `Your Figma seat has limited API access (View/Collab: ~6 req/month). ` +
88
+ `Upgrade to Full/Dev seat for 10-20 req/min.`;
89
+ if (info.upgradeLink)
90
+ msg += `\nUpgrade: ${info.upgradeLink}`;
91
+ }
92
+ return { error: msg };
93
+ }
94
+ const msg = err instanceof Error ? err.message : String(err);
95
+ return { error: `Figma fetch failed: ${msg}` };
96
+ }
97
+ }
98
+ /**
99
+ * Fetch file data (shallow, depth=2).
100
+ */
101
+ async fetchFileData(fileKey, token) {
102
+ return this.apiGet(`/files/${fileKey}?depth=2`, token, {
103
+ ttlMs: TTL_METADATA,
104
+ cacheKey: `file:${fileKey}:shallow`,
105
+ });
106
+ }
107
+ /**
108
+ * Fetch full file data (no depth limit, for prototype analysis).
109
+ */
110
+ async fetchFileDataFull(fileKey, token) {
111
+ return this.apiGet(`/files/${fileKey}`, token, {
112
+ ttlMs: TTL_METADATA,
113
+ cacheKey: `file:${fileKey}:full`,
114
+ });
115
+ }
116
+ /**
117
+ * Fetch node layout structure.
118
+ */
119
+ async fetchStructure(fileKey, nodeId, token) {
120
+ const cacheKey = `struct:${fileKey}:${nodeId}`;
121
+ return this.apiGet(`/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`, token, {
122
+ ttlMs: TTL_METADATA,
123
+ cacheKey,
124
+ });
125
+ }
126
+ /**
127
+ * Batch export multiple node images (single API call).
128
+ */
129
+ async exportImages(fileKey, nodeIds, scale, token) {
130
+ const idsParam = nodeIds.map((id) => encodeURIComponent((0, url_parser_js_1.normalizeNodeId)(id))).join(",");
131
+ const data = await this.apiGet(`/images/${fileKey}?ids=${idsParam}&format=png&scale=${scale}`, token, {
132
+ skipCache: true,
133
+ });
134
+ if (data.err) {
135
+ throw new Error(`Figma image export error: ${data.err}`);
136
+ }
137
+ const result = new Map();
138
+ for (const [id, url] of Object.entries(data.images)) {
139
+ if (url) {
140
+ result.set(id, url);
141
+ this.cache.set(`imgurl:${fileKey}:${id}:${scale}`, url, TTL_IMAGE);
142
+ }
143
+ }
144
+ return result;
145
+ }
146
+ // --- Low-level ---
147
+ /**
148
+ * Generic API GET with full pipeline: cache → dedup → rate limit → retry.
149
+ */
150
+ async apiGet(path, token, opts) {
151
+ const cacheKey = opts?.cacheKey ?? `api:${path}`;
152
+ const ttlMs = opts?.ttlMs ?? TTL_METADATA;
153
+ // 1. Cache check
154
+ if (!opts?.skipCache) {
155
+ const cached = this.cache.get(cacheKey);
156
+ if (cached !== undefined) {
157
+ console.error(`[figma] cache hit: ${path}`);
158
+ return cached;
159
+ }
160
+ }
161
+ // 2. Dedup: piggyback on in-flight request
162
+ const existing = this.inflight.get(cacheKey);
163
+ if (existing) {
164
+ return existing;
165
+ }
166
+ // 3. Execute with rate limiting + retry
167
+ const promise = this.executeFetch(path, token, cacheKey, ttlMs);
168
+ this.inflight.set(cacheKey, promise);
169
+ try {
170
+ return await promise;
171
+ }
172
+ finally {
173
+ this.inflight.delete(cacheKey);
174
+ }
175
+ }
176
+ // --- Observability ---
177
+ getStats() {
178
+ return {
179
+ cache: this.cache.stats(),
180
+ rateLimiter: this.rateLimiter.getStatus(),
181
+ };
182
+ }
183
+ logStats() {
184
+ const stats = this.getStats();
185
+ console.error(`[figma] cache: ${stats.cache.memoryEntries} mem / ${stats.cache.diskEntries} disk, ` +
186
+ `hit rate: ${(stats.cache.hitRate * 100).toFixed(0)}% | ` +
187
+ `rate limiter: ${stats.rateLimiter.tokens}/${stats.rateLimiter.budget} tokens, ` +
188
+ `${stats.rateLimiter.throttledRequests} throttled`);
189
+ }
190
+ // --- Private ---
191
+ async executeFetch(path, token, cacheKey, ttlMs) {
192
+ const response = await (0, figma_retry_js_1.figmaRetry)(() => {
193
+ const controller = new AbortController();
194
+ const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
195
+ return fetch(`${API_BASE}${path}`, {
196
+ headers: { "X-Figma-Token": token },
197
+ signal: controller.signal,
198
+ }).finally(() => clearTimeout(timeout));
199
+ }, {
200
+ rateLimiter: this.rateLimiter,
201
+ maxAttempts: this.maxRetries,
202
+ onRetry: (attempt, delayMs, reason) => {
203
+ console.error(`[figma] retry #${attempt} in ${delayMs}ms: ${reason}`);
204
+ },
205
+ });
206
+ if (!response.ok) {
207
+ const body = await response.text().catch(() => "");
208
+ throw new Error(`Figma API ${response.status}: ${body || response.statusText}`);
209
+ }
210
+ const result = (await response.json());
211
+ this.cache.set(cacheKey, result, ttlMs);
212
+ return result;
213
+ }
214
+ }
215
+ exports.FigmaClient = FigmaClient;
216
+ /** Singleton instance, created lazily. */
217
+ let defaultClient;
218
+ function getFigmaClient(config) {
219
+ if (!defaultClient) {
220
+ defaultClient = new FigmaClient(config);
221
+ }
222
+ return defaultClient;
223
+ }
224
+ //# sourceMappingURL=figma-client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"figma-client.js","sourceRoot":"","sources":["../../../src/figma/figma-client.ts"],"names":[],"mappings":"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"}