@sun-asterisk/sungen 2.4.6 → 2.5.1

package/src/tools/figma/figma-image-downloader.ts

@@ -0,0 +1,112 @@
+/**
+ * Download a Figma-signed image URL to disk.
+ *
+ * - Streams response body to a .tmp file then atomically renames to destPath.
+ * - Verifies the final file is non-zero bytes before committing.
+ * - Enforces a configurable timeout (default 30 s).
+ * - Surfaces all failures as FigmaNetworkError.
+ *
+ * Security: signed S3 URLs are consumed transiently — never logged.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { FigmaNetworkError } from './figma-errors';
+
+export interface DownloadOptions {
+  /** Request timeout in milliseconds. Default: 30 000. */
+  timeoutMs?: number;
+}
+
+/**
+ * Download the image at `url` and write it to `destPath`.
+ *
+ * Uses atomic write: streams to `<destPath>.tmp`, verifies size > 0,
+ * then renames to `destPath`. Cleans up .tmp on failure.
+ *
+ * @throws FigmaNetworkError on any network, timeout, or I/O failure.
+ * @throws FigmaNetworkError when the downloaded file has zero bytes.
+ */
+export async function downloadToPath(
+  url: string,
+  destPath: string,
+  options: DownloadOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const tmpPath = `${destPath}.tmp`;
+
+  // Ensure destination directory exists
+  const dir = path.dirname(destPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response: Response;
+  try {
+    response = await fetch(url, { signal: controller.signal });
+  } catch (cause) {
+    clearTimeout(timer);
+    cleanupTmp(tmpPath);
+    const isTimeout =
+      cause instanceof Error && cause.name === 'AbortError';
+    throw new FigmaNetworkError(
+      isTimeout
+        ? `Image download timed out after ${timeoutMs}ms.`
+        : 'Image download failed due to a network error.',
+      cause,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!response.ok) {
+    cleanupTmp(tmpPath);
+    throw new FigmaNetworkError(
+      `Image download received HTTP ${response.status}.`,
+    );
+  }
+
+  if (!response.body) {
+    cleanupTmp(tmpPath);
+    throw new FigmaNetworkError('Image download response has no body.');
+  }
+
+  // Stream to .tmp file
+  const writeStream = fs.createWriteStream(tmpPath);
+  try {
+    await pipeline(Readable.fromWeb(response.body as import('stream/web').ReadableStream), writeStream);
+  } catch (cause) {
+    cleanupTmp(tmpPath);
+    throw new FigmaNetworkError('Failed to write image to disk.', cause);
+  }
+
+  // Verify non-zero file size
+  const stat = fs.statSync(tmpPath);
+  if (stat.size === 0) {
+    cleanupTmp(tmpPath);
+    throw new FigmaNetworkError('Downloaded image file is empty (0 bytes).');
+  }
+
+  // Atomic rename
+  try {
+    fs.renameSync(tmpPath, destPath);
+  } catch (cause) {
+    cleanupTmp(tmpPath);
+    throw new FigmaNetworkError('Failed to finalize image file on disk.', cause);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function cleanupTmp(tmpPath: string): void {
+  try {
+    if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath);
+  } catch {
+    // Best-effort cleanup — ignore errors
+  }
+}

package/src/tools/figma/figma-node-filter.ts

@@ -0,0 +1,198 @@
+/**
+ * Prune raw Figma node trees to a minimal shape for LLM / test-generation use.
+ *
+ * Drops: vectors, fills, effects, strokes, constraints, style references.
+ * Keeps: id, name, type, text content, component/variant metadata, bounding box, children.
+ *
+ * Role inference: component name suffix → button | textbox | link | image | null.
+ */
+
+import { z } from 'zod';
+import type {
+  FilteredFigmaNode,
+  FigmaNodeRole,
+  FigmaTextLabel,
+  FigmaVariantDefinition,
+} from './figma-client-types';
+
+// ---------------------------------------------------------------------------
+// Zod schema — loose, unknown fields allowed via passthrough
+// ---------------------------------------------------------------------------
+
+// Zod v4: z.record() requires explicit key schema (z.string())
+const RawNodeSchema: z.ZodType<Record<string, unknown>> = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    type: z.string(),
+    characters: z.string().optional(),
+    componentPropertyDefinitions: z.record(z.string(), z.unknown()).optional(),
+    componentProperties: z
+      .record(z.string(), z.object({ value: z.string(), type: z.string() }))
+      .optional(),
+    absoluteBoundingBox: z
+      .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+      .optional(),
+    children: z.array(z.lazy((): z.ZodType<Record<string, unknown>> => RawNodeSchema)).optional(),
+  })
+  .passthrough();
+
+// ---------------------------------------------------------------------------
+// Role inference
+// ---------------------------------------------------------------------------
+
+const ROLE_SUFFIX_MAP: Array<[RegExp, FigmaNodeRole]> = [
+  [/button$/i, 'button'],
+  [/input|textbox|text.?field|text.?input/i, 'textbox'],
+  [/link$/i, 'link'],
+  [/icon|image|img|illustration/i, 'image'],
+];
+
+function inferRole(name: string): FigmaNodeRole {
+  for (const [pattern, role] of ROLE_SUFFIX_MAP) {
+    if (pattern.test(name)) return role;
+  }
+  return null;
+}
+
+// Node types to skip entirely (leaf-only visual noise)
+const SKIP_TYPES = new Set([
+  'VECTOR',
+  'STAR',
+  'POLYGON',
+  'BOOLEAN_OPERATION',
+  'ELLIPSE',
+  'LINE',
+]);
+
+// ---------------------------------------------------------------------------
+// Core filter
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively prune a raw Figma node to the minimal FilteredFigmaNode shape.
+ * Returns null when the node type should be dropped entirely.
+ *
+ * @param raw     Validated (but loosely typed) raw Figma node object.
+ * @param maxDepth  Maximum recursion depth (default 30 — safety guard).
+ */
+function filterNode(
+  raw: Record<string, unknown>,
+  depth = 0,
+  maxDepth = 30,
+): FilteredFigmaNode | null {
+  const id = raw['id'] as string;
+  const name = raw['name'] as string;
+  const type = raw['type'] as string;
+
+  if (SKIP_TYPES.has(type)) return null;
+  if (depth > maxDepth) return null;
+
+  // Bounding box
+  let boundingBox: FilteredFigmaNode['boundingBox'];
+  const bb = raw['absoluteBoundingBox'] as
+    | { x: number; y: number; width: number; height: number }
+    | undefined;
+  if (bb) {
+    boundingBox = { x: bb.x, y: bb.y, w: bb.width, h: bb.height };
+  }
+
+  // Text content
+  const text =
+    type === 'TEXT' ? (raw['characters'] as string | undefined) : undefined;
+
+  // Component / variant metadata
+  let componentName: string | undefined;
+  let variantProps: Record<string, string> | undefined;
+
+  if (type === 'COMPONENT' || type === 'COMPONENT_SET' || type === 'INSTANCE') {
+    componentName = name;
+    const props = raw['componentProperties'] as
+      | Record<string, { value: string; type: string }>
+      | undefined;
+    if (props) {
+      variantProps = Object.fromEntries(
+        Object.entries(props).map(([k, v]) => [k, v.value]),
+      );
+    }
+  }
+
+  // Role (only meaningful for component-like nodes)
+  const role: FigmaNodeRole =
+    componentName != null ? inferRole(name) : null;
+
+  // Recurse into children
+  const rawChildren = (raw['children'] as Record<string, unknown>[] | undefined) ?? [];
+  const children: FilteredFigmaNode[] = rawChildren
+    .map((child) => filterNode(child, depth + 1, maxDepth))
+    .filter((n): n is FilteredFigmaNode => n !== null);
+
+  const node: FilteredFigmaNode = { id, name, type, children };
+  if (text !== undefined) node.text = text;
+  if (componentName !== undefined) node.componentName = componentName;
+  if (variantProps !== undefined) node.variantProps = variantProps;
+  if (role) node.role = role;
+  if (boundingBox !== undefined) node.boundingBox = boundingBox;
+
+  return node;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and filter a raw Figma node tree.
+ *
+ * @throws ZodError when the input fails basic structural validation.
+ */
+export function filterFigmaNode(rawNode: unknown): FilteredFigmaNode {
+  const validated = RawNodeSchema.parse(rawNode);
+  const result = filterNode(validated);
+  // Root node should never be null (root type is never in SKIP_TYPES)
+  if (!result) {
+    const id = (rawNode as Record<string, unknown>)['id'] ?? 'unknown';
+    throw new Error(`Root node (id=${id}) was filtered out — unexpected type.`);
+  }
+  return result;
+}
+
+/**
+ * Recursively collect all text labels from a filtered node tree.
+ * Returns a flat list of { text, nodePath } pairs.
+ */
+export function extractTextLabels(
+  node: FilteredFigmaNode,
+  _path = '',
+): FigmaTextLabel[] {
+  const currentPath = _path ? `${_path} > ${node.name}` : node.name;
+  const labels: FigmaTextLabel[] = [];
+
+  if (node.text) {
+    labels.push({ text: node.text, nodePath: currentPath });
+  }
+
+  for (const child of node.children) {
+    labels.push(...extractTextLabels(child, currentPath));
+  }
+
+  return labels;
+}
+
+/**
+ * Extract variant definitions from a COMPONENT_SET node.
+ * Each direct child COMPONENT represents one variant combination.
+ */
+export function extractVariants(
+  componentSetNode: FilteredFigmaNode,
+): FigmaVariantDefinition[] {
+  if (componentSetNode.type !== 'COMPONENT_SET') return [];
+
+  return componentSetNode.children
+    .filter((child) => child.type === 'COMPONENT')
+    .map((child) => ({
+      nodeId: child.id,
+      name: child.name,
+      variantProps: child.variantProps ?? {},
+    }));
+}

package/src/tools/figma/figma-rest-client.ts

@@ -0,0 +1,183 @@
+/**
+ * Minimal Figma REST client.
+ *
+ * - Base URL: https://api.figma.com
+ * - Auth header: X-Figma-Token (PAT — never logged)
+ * - Retry: 429 → honor Retry-After (cap 3 attempts); 5xx → retry once
+ * - All HTTP errors mapped to typed FigmaError subclasses
+ */
+
+import {
+  FigmaAuthError,
+  FigmaAccessError,
+  FigmaRateLimitError,
+  FigmaNetworkError,
+} from './figma-errors';
+import type {
+  FigmaMeResponse,
+  FigmaFileNodesResponse,
+  FigmaImageUrlsResponse,
+  FigmaImageOptions,
+} from './figma-client-types';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const BASE_URL = 'https://api.figma.com';
+/**
+ * Per-request timeout (ms). Figma can stall on very large nodes; without this,
+ * node fetch hangs the CLI indefinitely. Override via SUNGEN_FIGMA_TIMEOUT_MS.
+ */
+const DEFAULT_REQUEST_TIMEOUT_MS = 90_000;
+function getRequestTimeoutMs(): number {
+  const raw = process.env.SUNGEN_FIGMA_TIMEOUT_MS;
+  const n = raw ? parseInt(raw, 10) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Build headers with PAT — never expose PAT in logs/errors. */
+function makeHeaders(pat: string): Record<string, string> {
+  return { 'X-Figma-Token': pat };
+}
+
+/** Parse Retry-After header into seconds (default 60 when missing/invalid). */
+function parseRetryAfter(headers: Headers): number {
+  const value = headers.get('Retry-After');
+  if (!value) return 60;
+  const parsed = parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 60;
+}
+
+/** Sleep for `ms` milliseconds. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Map a non-2xx HTTP status to a typed error.
+ * `url` is included only in a generic way — never includes PAT.
+ */
+function mapHttpError(status: number, url: string): never {
+  const safeUrl = url.replace(/\?.*$/, ''); // strip query params (may contain ids)
+  if (status === 401) throw new FigmaAuthError();
+  if (status === 403) throw new FigmaAccessError(403);
+  if (status === 404) throw new FigmaAccessError(404);
+  throw new FigmaNetworkError(`Figma API error ${status} at ${safeUrl}`);
+}
+
+/**
+ * Core fetch wrapper with retry logic.
+ *
+ * Retry rules:
+ *   - 429: up to MAX_RATE_LIMIT_RETRIES attempts, sleeping Retry-After seconds between each.
+ *   - 5xx: retry once after 2 s.
+ *   - Other errors: throw immediately.
+ */
+async function figmaFetch(pat: string, url: string): Promise<Response> {
+  let serverErrorRetried = false;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    let response: Response;
+    const timeoutMs = getRequestTimeoutMs();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      response = await fetch(url, { headers: makeHeaders(pat), signal: controller.signal });
+    } catch (cause) {
+      const aborted = (cause as { name?: string } | undefined)?.name === 'AbortError';
+      if (aborted) {
+        throw new FigmaNetworkError(
+          `Figma API request timed out after ${Math.round(timeoutMs / 1000)}s. ` +
+            'The node may be very large. Retry with --refresh, pick a smaller frame, ' +
+            'or raise SUNGEN_FIGMA_TIMEOUT_MS.',
+          cause,
+        );
+      }
+      throw new FigmaNetworkError('Network request to Figma API failed.', cause);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (response.ok) return response;
+
+    // 429: fail fast. Figma rate-limit windows are per-minute, so in-CLI
+    // retries typically waste time. Surface the Retry-After hint and let
+    // the caller re-run after waiting.
+    if (response.status === 429) {
+      const retryAfter = parseRetryAfter(response.headers);
+      const planTier = response.headers.get('x-figma-plan-tier') ?? undefined;
+      const bucket = response.headers.get('x-figma-rate-limit-type') ?? undefined;
+      const upgradeLink = response.headers.get('x-figma-upgrade-link') ?? undefined;
+      throw new FigmaRateLimitError(retryAfter, undefined, { planTier, bucket, upgradeLink });
+    }
+
+    if (response.status >= 500 && !serverErrorRetried) {
+      serverErrorRetried = true;
+      await sleep(2000);
+      continue;
+    }
+
+    // For all other non-2xx, delegate to mapHttpError (throws)
+    mapHttpError(response.status, url);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * GET /v1/me — validate PAT and return user info.
+ */
+export async function getMe(pat: string): Promise<FigmaMeResponse> {
+  const url = `${BASE_URL}/v1/me`;
+  const response = await figmaFetch(pat, url);
+  return response.json() as Promise<FigmaMeResponse>;
+}
+
+/**
+ * GET /v1/files/:key/nodes?ids=<id,id,...>
+ * Returns the raw node document and current file version.
+ */
+export async function getFileNodes(
+  pat: string,
+  fileKey: string,
+  nodeIds: string[],
+): Promise<FigmaFileNodesResponse> {
+  if (nodeIds.length === 0) {
+    throw new Error('getFileNodes: nodeIds must be a non-empty array.');
+  }
+  const ids = nodeIds.join(',');
+  const url = `${BASE_URL}/v1/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(ids)}`;
+  const response = await figmaFetch(pat, url);
+  return response.json() as Promise<FigmaFileNodesResponse>;
+}
+
+/**
+ * GET /v1/images/:key?ids=<id,id>&scale=<n>&format=<fmt>
+ * Returns signed S3 URLs — consume immediately, do not persist.
+ */
+export async function getImageUrls(
+  pat: string,
+  fileKey: string,
+  nodeIds: string[],
+  options: FigmaImageOptions = {},
+): Promise<FigmaImageUrlsResponse> {
+  if (nodeIds.length === 0) {
+    throw new Error('getImageUrls: nodeIds must be a non-empty array.');
+  }
+  const scale = options.scale ?? 2;
+  const format = options.format ?? 'png';
+  const ids = nodeIds.join(',');
+  const url =
+    `${BASE_URL}/v1/images/${encodeURIComponent(fileKey)}` +
+    `?ids=${encodeURIComponent(ids)}&scale=${scale}&format=${format}`;
+  const response = await figmaFetch(pat, url);
+  return response.json() as Promise<FigmaImageUrlsResponse>;
+}

package/src/tools/figma/figma-url-parser.ts

@@ -0,0 +1,55 @@
+/**
+ * Offline Figma URL parser.
+ * Converts Figma share URLs → { fileKey, nodeId } without any network call.
+ *
+ * Supported URL forms:
+ *   https://www.figma.com/design/<KEY>/<name>?node-id=1-23
+ *   https://www.figma.com/file/<KEY>/<name>?node-id=1%3A23   (legacy + percent-encoded)
+ *   https://www.figma.com/design/<KEY>/<name>                (no node selected)
+ */
+
+import type { FigmaNodeRef } from './figma-client-types';
+
+/**
+ * Regex captures:
+ *   group 1 → path type: "design" | "file"
+ *   group 2 → fileKey (alphanumeric)
+ *   group 3 → raw node-id query param value (may be absent)
+ */
+const FIGMA_URL_RE =
+  /^https?:\/\/(?:www\.)?figma\.com\/(design|file)\/([A-Za-z0-9]+)(?:\/[^?#]*)?(?:[?&].*?node-id=([\w%:.-]+))?/;
+
+/**
+ * Convert URL-form node-id to Figma API form.
+ *   "1-23"   → "1:23"
+ *   "1%3A23" → "1:23"  (percent-encoded colon)
+ *   "1:23"   → "1:23"  (already correct)
+ */
+function normalizeNodeId(raw: string): string {
+  const decoded = decodeURIComponent(raw);
+  // Replace dash separator only between two digit groups (Figma node-id pattern)
+  return decoded.replace(/^(\d+)-(\d+)$/, '$1:$2');
+}
+
+/**
+ * Parse a Figma share URL into a structured reference.
+ *
+ * @param url - Full Figma URL string.
+ * @returns `{ fileKey, nodeId? }` on success, `null` if URL is not a valid Figma URL.
+ */
+export function parseFigmaUrl(url: string): FigmaNodeRef | null {
+  if (!url || typeof url !== 'string') return null;
+
+  const match = FIGMA_URL_RE.exec(url.trim());
+  if (!match) return null;
+
+  const fileKey = match[2];
+  const rawNodeId = match[3];
+
+  const result: FigmaNodeRef = { fileKey };
+  if (rawNodeId) {
+    result.nodeId = normalizeNodeId(rawNodeId);
+  }
+
+  return result;
+}

package/src/utils/exec-file-no-throw.ts

@@ -0,0 +1,45 @@
+/**
+ * Safe execFile wrapper — uses execFile (not exec) to prevent shell injection.
+ * Handles Windows compatibility and provides structured output.
+ */
+
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+export interface ExecFileResult {
+  stdout: string;
+  stderr: string;
+  /** Process exit code; 0 = success. */
+  status: number;
+}
+
+/**
+ * Run a command safely using execFile (no shell expansion).
+ * Never throws — all errors are captured in the result.
+ *
+ * @param cmd  - Executable name or path (no shell features).
+ * @param args - Arguments as an array (each arg is passed verbatim).
+ * @param cwd  - Optional working directory.
+ */
+export async function execFileNoThrow(
+  cmd: string,
+  args: string[],
+  cwd?: string,
+): Promise<ExecFileResult> {
+  try {
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+      cwd,
+      // Prevent accidental shell expansion on Windows too
+      shell: false,
+    });
+    return { stdout: stdout ?? '', stderr: stderr ?? '', status: 0 };
+  } catch (err: any) {
+    return {
+      stdout: err.stdout ?? '',
+      stderr: err.stderr ?? '',
+      status: typeof err.code === 'number' ? err.code : 1,
+    };
+  }
+}