@sun-asterisk/sungen 2.5.0 → 2.5.1

package/src/tools/figma/figma-auth.ts

@@ -0,0 +1,161 @@
+/**
+ * Figma PAT lifecycle: load, save, clear, and safety checks.
+ *
+ * Storage: <cwd>/.env  key=FIGMA_PAT
+ * Override: process.env.FIGMA_PAT (CI path — skips file read)
+ *
+ * Safeguards enforced on every save AND every assertSafeToUse call:
+ *   1. .env must appear in .gitignore (abort if not).
+ *   2. No tracked file may contain "FIGMA_PAT=" (git grep scan).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileNoThrow } from '../../utils/exec-file-no-throw';
+
+const PAT_KEY = 'FIGMA_PAT';
+const ENV_FILE = '.env';
+const GITIGNORE_FILE = '.gitignore';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function envFilePath(cwd: string): string {
+  return path.join(cwd, ENV_FILE);
+}
+
+function gitignorePath(cwd: string): string {
+  return path.join(cwd, GITIGNORE_FILE);
+}
+
+/**
+ * Read .env file lines, return empty array when file does not exist.
+ */
+function readEnvLines(cwd: string): string[] {
+  const fp = envFilePath(cwd);
+  if (!fs.existsSync(fp)) return [];
+  return fs.readFileSync(fp, 'utf8').split('\n');
+}
+
+/**
+ * Write lines back to .env, preserving a trailing newline.
+ */
+function writeEnvLines(cwd: string, lines: string[]): void {
+  fs.writeFileSync(envFilePath(cwd), lines.join('\n'), 'utf8');
+}
+
+/**
+ * Check whether .env (or .env.*) is covered by .gitignore.
+ */
+function isEnvIgnored(cwd: string): boolean {
+  const gp = gitignorePath(cwd);
+  if (!fs.existsSync(gp)) return false;
+  const content = fs.readFileSync(gp, 'utf8');
+  // Accept ".env", ".env.local", ".env.*", or "*.env" patterns
+  return /^\s*(\.env[\w.*]*|\*\.env)\s*$/m.test(content);
+}
+
+/**
+ * Run `git grep -l "FIGMA_PAT="` in cwd.
+ * Returns list of matching tracked file paths (empty = safe).
+ */
+async function findTrackedFilesWithPat(cwd: string): Promise<string[]> {
+  const result = await execFileNoThrow('git', ['grep', '-l', `${PAT_KEY}=`], cwd);
+  if (result.status === 0 && result.stdout.trim()) {
+    return result.stdout.trim().split('\n').filter(Boolean);
+  }
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the Figma PAT.
+ * Priority: process.env.FIGMA_PAT > .env file.
+ * Returns undefined when no PAT is configured.
+ */
+export function loadPat(cwd: string): string | undefined {
+  if (process.env[PAT_KEY]) return process.env[PAT_KEY];
+
+  const lines = readEnvLines(cwd);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(`${PAT_KEY}=`)) {
+      return trimmed.slice(PAT_KEY.length + 1).trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Persist PAT to <cwd>/.env, upserting only the FIGMA_PAT key.
+ * Aborts with an actionable error if safeguards are violated.
+ *
+ * @throws Error with remediation instructions on safeguard failure.
+ */
+export async function savePat(cwd: string, token: string): Promise<void> {
+  // Safeguard 1: .env must be gitignored
+  if (!isEnvIgnored(cwd)) {
+    throw new Error(
+      `Refusing to save FIGMA_PAT: ".env" is not listed in ${GITIGNORE_FILE}.\n` +
+        `Add the following line to ${path.join(cwd, GITIGNORE_FILE)} and re-run:\n\n  .env\n`,
+    );
+  }
+
+  // Safeguard 2: no tracked file may contain FIGMA_PAT=
+  const leakedFiles = await findTrackedFilesWithPat(cwd);
+  if (leakedFiles.length > 0) {
+    throw new Error(
+      `Refusing to save FIGMA_PAT: token key found in tracked file(s):\n` +
+        leakedFiles.map((f) => `  ${f}`).join('\n') +
+        `\n\nRemove FIGMA_PAT from those files, commit the removal, then re-run.\n`,
+    );
+  }
+
+  // Upsert: replace existing line or append
+  const lines = readEnvLines(cwd);
+  const idx = lines.findIndex((l) => l.trim().startsWith(`${PAT_KEY}=`));
+  const newLine = `${PAT_KEY}=${token}`;
+  if (idx >= 0) {
+    lines[idx] = newLine;
+  } else {
+    // Ensure file ends with newline before appending
+    if (lines.length > 0 && lines[lines.length - 1] !== '') {
+      lines.push('');
+    }
+    lines.push(newLine);
+  }
+  writeEnvLines(cwd, lines);
+}
+
+/**
+ * Remove FIGMA_PAT line from <cwd>/.env.
+ * No-op when key is not present.
+ */
+export function clearPat(cwd: string): void {
+  const lines = readEnvLines(cwd);
+  const filtered = lines.filter((l) => !l.trim().startsWith(`${PAT_KEY}=`));
+  if (filtered.length !== lines.length) {
+    writeEnvLines(cwd, filtered);
+  }
+}
+
+/**
+ * Run tracked-file scan on every Figma CLI / skill invocation.
+ * Aborts with actionable message if FIGMA_PAT= is found in any tracked file.
+ *
+ * @throws Error with remediation instructions on safeguard failure.
+ */
+export async function assertSafeToUse(cwd: string): Promise<void> {
+  const leakedFiles = await findTrackedFilesWithPat(cwd);
+  if (leakedFiles.length > 0) {
+    throw new Error(
+      `Security check failed: FIGMA_PAT found in tracked file(s):\n` +
+        leakedFiles.map((f) => `  ${f}`).join('\n') +
+        `\n\nRemove FIGMA_PAT from those files and commit the removal before using Figma commands.\n`,
+    );
+  }
+}

package/src/tools/figma/figma-cache.ts

@@ -0,0 +1,184 @@
+/**
+ * Version-keyed disk cache for Figma node JSON and rendered images.
+ *
+ * Layout:
+ *   <cwd>/.sungen/figma-cache/<fileKey>/<versionId>/<safeNodeId>.json       (filtered node)
+ *   <cwd>/.sungen/figma-cache/<fileKey>/<versionId>/<safeNodeId>-raw.json   (unfiltered API response)
+ *   <cwd>/.sungen/figma-cache/<fileKey>/<versionId>/<safeNodeId>-<scale>.png
+ *
+ * Cache directory is created on first write (permissions 0o700 on Unix).
+ * `bustOldVersions` retains the N most recently modified version dirs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { FigmaCacheKind } from './figma-client-types';
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+const CACHE_ROOT = path.join('.sungen', 'figma-cache');
+
+/** Replace characters unsafe for filenames (colons, slashes, spaces). */
+function safeId(id: string): string {
+  return id.replace(/[:/\\s]/g, '_');
+}
+
+function cacheDir(cwd: string, fileKey: string, versionId: string): string {
+  return path.join(cwd, CACHE_ROOT, safeId(fileKey), safeId(versionId));
+}
+
+function cacheFilename(nodeId: string, kind: FigmaCacheKind): string {
+  const safe = safeId(nodeId);
+  if (kind === 'json') return `${safe}.json`;
+  if (kind === 'raw') return `${safe}-raw.json`;
+  // kind is like "2x", "1x", etc.
+  return `${safe}-${kind}.png`;
+}
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a cached entry. Returns `undefined` on cache miss.
+ *
+ * @param kind  'json' for filtered node data, '<n>x' for PNG images.
+ */
+export function get(
+  cwd: string,
+  fileKey: string,
+  versionId: string,
+  nodeId: string,
+  kind: FigmaCacheKind,
+): Buffer | undefined {
+  const filePath = path.join(
+    cacheDir(cwd, fileKey, versionId),
+    cacheFilename(nodeId, kind),
+  );
+  if (!fs.existsSync(filePath)) return undefined;
+  try {
+    return fs.readFileSync(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write data to the cache.
+ * Creates the version directory (mode 0o700) if it does not exist.
+ *
+ * @param kind  'json' for filtered node data, '<n>x' for PNG images.
+ */
+export function put(
+  cwd: string,
+  fileKey: string,
+  versionId: string,
+  nodeId: string,
+  kind: FigmaCacheKind,
+  data: Buffer | string,
+): void {
+  const dir = cacheDir(cwd, fileKey, versionId);
+  ensureDir(dir);
+  const filePath = path.join(dir, cacheFilename(nodeId, kind));
+  const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+  // Atomic write: tmp → rename
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, payload, { mode: 0o600 });
+  fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Find the newest on-disk version that has a cached raw node JSON for `nodeId`.
+ * Returns `undefined` when no usable cache exists.
+ *
+ * Lets the scaffolder skip an expensive `/v1/files/:key/nodes` call on Starter
+ * plans where REST quota is severely restricted.
+ */
+export function findLatestCachedVersion(
+  cwd: string,
+  fileKey: string,
+  nodeId: string,
+): string | undefined {
+  const keyDir = path.join(cwd, CACHE_ROOT, safeId(fileKey));
+  if (!fs.existsSync(keyDir)) return undefined;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(keyDir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+
+  const rawFilename = cacheFilename(nodeId, 'raw');
+  const candidates = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const rawPath = path.join(keyDir, e.name, rawFilename);
+      if (!fs.existsSync(rawPath)) return undefined;
+      let mtime = 0;
+      try { mtime = fs.statSync(rawPath).mtimeMs; } catch { /* ignore */ }
+      return { versionDir: e.name, mtime };
+    })
+    .filter((x): x is { versionDir: string; mtime: number } => x !== undefined)
+    .sort((a, b) => b.mtime - a.mtime);
+
+  return candidates[0]?.versionDir;
+}
+
+/**
+ * Remove all version directories for `fileKey` except the `keep` most recent.
+ *
+ * Directories are ordered by mtime descending; oldest are deleted first.
+ * No-op when fewer than `keep` versions exist.
+ *
+ * @param keep  Number of versions to retain (default 3).
+ */
+export function bustOldVersions(
+  cwd: string,
+  fileKey: string,
+  currentVersion: string,
+  options: { keep?: number } = {},
+): void {
+  const keep = options.keep ?? 3;
+  const keyDir = path.join(cwd, CACHE_ROOT, safeId(fileKey));
+
+  if (!fs.existsSync(keyDir)) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(keyDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  const versionDirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const fullPath = path.join(keyDir, e.name);
+      let mtime = 0;
+      try {
+        mtime = fs.statSync(fullPath).mtimeMs;
+      } catch { /* ignore */ }
+      return { name: e.name, fullPath, mtime };
+    })
+    // Ensure current version is always kept (bump its mtime artificially)
+    .map((d) =>
+      d.name === safeId(currentVersion)
+        ? { ...d, mtime: Number.MAX_SAFE_INTEGER }
+        : d,
+    )
+    .sort((a, b) => b.mtime - a.mtime); // newest first
+
+  const toDelete = versionDirs.slice(keep);
+  for (const dir of toDelete) {
+    try {
+      fs.rmSync(dir.fullPath, { recursive: true, force: true });
+    } catch { /* best-effort */ }
+  }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Shared types for Figma integration.
+ * Used by figma-auth.ts, figma-url-parser.ts, and REST client modules.
+ */
+
+/** Authentication configuration for Figma API. */
+export interface FigmaAuthConfig {
+  /** Personal Access Token — never log this value. */
+  pat: string;
+}
+
+/** Parsed reference to a specific Figma node. */
+export interface FigmaNodeRef {
+  /** Figma file key extracted from URL (alphanumeric, 20+ chars). */
+  fileKey: string;
+  /** Node ID in API form: "1:23" (colon-separated). Absent when URL has no node-id param. */
+  nodeId?: string;
+}
+
+/** Minimal /v1/me response shape used for PAT validation. */
+export interface FigmaMeResponse {
+  id: string;
+  email: string;
+  handle: string;
+}
+
+/** Result of a PAT validation call. */
+export interface FigmaAuthCheckResult {
+  valid: boolean;
+  handle?: string;
+  email?: string;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// REST client response types (added in Phase 2)
+// ---------------------------------------------------------------------------
+
+/** Raw Figma node as returned by the API (loose — unknown fields allowed). */
+export interface FigmaRawNode {
+  id: string;
+  name: string;
+  type: string;
+  /** Text content for TEXT nodes. */
+  characters?: string;
+  /** Component set variant properties. */
+  componentPropertyDefinitions?: Record<string, unknown>;
+  /** Variant property values for COMPONENT nodes. */
+  componentProperties?: Record<string, { value: string; type: string }>;
+  /** Bounding box from absoluteBoundingBox. */
+  absoluteBoundingBox?: { x: number; y: number; width: number; height: number };
+  /** Child nodes. */
+  children?: FigmaRawNode[];
+  /** Allow any additional Figma fields. */
+  [key: string]: unknown;
+}
+
+/** Response from GET /v1/files/:key/nodes */
+export interface FigmaFileNodesResponse {
+  nodes: Record<string, { document: FigmaRawNode } | null>;
+  /** Current file version ID. */
+  version: string;
+}
+
+/** Response from GET /v1/images/:key */
+export interface FigmaImageUrlsResponse {
+  /** Map of nodeId → signed S3 URL (transient — do not persist). */
+  images: Record<string, string | null>;
+  err: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Filtered node types (output of figma-node-filter.ts)
+// ---------------------------------------------------------------------------
+
+/** Role inferred from component name suffix. */
+export type FigmaNodeRole = 'button' | 'textbox' | 'link' | 'image' | null;
+
+/** Pruned, minimal Figma node for downstream LLM / test generation. */
+export interface FilteredFigmaNode {
+  id: string;
+  name: string;
+  type: string;
+  /** Text content (TEXT nodes only). */
+  text?: string;
+  /** Component set name (COMPONENT / COMPONENT_SET nodes). */
+  componentName?: string;
+  /** Variant property map from componentProperties. */
+  variantProps?: Record<string, string>;
+  /** Inferred accessibility / interaction role. */
+  role?: FigmaNodeRole;
+  /** Bounding rectangle in file coordinates. */
+  boundingBox?: { x: number; y: number; w: number; h: number };
+  children: FilteredFigmaNode[];
+}
+
+/** A single text label extracted from the node tree. */
+export interface FigmaTextLabel {
+  text: string;
+  nodePath: string;
+}
+
+/** A single variant definition extracted from a COMPONENT_SET. */
+export interface FigmaVariantDefinition {
+  nodeId: string;
+  name: string;
+  variantProps: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Image options
+// ---------------------------------------------------------------------------
+
+export interface FigmaImageOptions {
+  /** Render scale. Default 2. */
+  scale?: number;
+  /** Image format. Default 'png'. */
+  format?: 'png' | 'jpg' | 'svg' | 'pdf';
+}
+
+// ---------------------------------------------------------------------------
+// Cache types
+// ---------------------------------------------------------------------------
+
+export type FigmaCacheKind = 'json' | 'raw' | `${number}x`;

package/src/tools/figma/figma-errors.ts

@@ -0,0 +1,127 @@
+/**
+ * Typed error classes for Figma API failures.
+ * Each error carries an actionable remediation message for CLI output.
+ *
+ * Never include PAT values in error messages or remediation text.
+ */
+
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+
+/** Common base for all Figma errors. */
+abstract class FigmaBaseError extends Error {
+  /** Human-readable instruction shown to the user on failure. */
+  readonly remediation: string;
+
+  constructor(message: string, remediation: string) {
+    super(message);
+    this.name = this.constructor.name;
+    this.remediation = remediation;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Concrete error types
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP 401 — PAT is missing, expired, or invalid.
+ */
+export class FigmaAuthError extends FigmaBaseError {
+  constructor(message = 'Figma authentication failed (401).') {
+    super(
+      message,
+      'Your Figma PAT is invalid or expired. Re-authenticate by running: sungen figma auth set',
+    );
+  }
+}
+
+/**
+ * HTTP 403 / 404 — PAT valid but insufficient access, or resource not found.
+ */
+export class FigmaAccessError extends FigmaBaseError {
+  readonly statusCode: 403 | 404;
+
+  constructor(statusCode: 403 | 404, message?: string) {
+    const defaultMsg =
+      statusCode === 403
+        ? 'Figma access denied (403).'
+        : 'Figma resource not found (404).';
+    const remediation =
+      statusCode === 403
+        ? 'Request view access to the Figma file, or ensure your PAT has the file:read scope.'
+        : 'Check the Figma URL — the file key or node ID may be incorrect.';
+    super(message ?? defaultMsg, remediation);
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * HTTP 429 — Rate limited by Figma API.
+ */
+export class FigmaRateLimitError extends FigmaBaseError {
+  /** Seconds to wait before retrying, parsed from Retry-After header. */
+  readonly retryAfter: number;
+  readonly planTier?: string;
+  readonly bucket?: string;
+  readonly upgradeLink?: string;
+
+  constructor(
+    retryAfter: number,
+    message?: string,
+    opts: { planTier?: string; bucket?: string; upgradeLink?: string } = {},
+  ) {
+    const human = formatRetryAfter(retryAfter);
+    const tierSuffix = opts.planTier ? ` (plan: ${opts.planTier}${opts.bucket ? `, bucket: ${opts.bucket}` : ''})` : '';
+    const msg = message ?? `Figma API rate limit hit (429)${tierSuffix}. Retry after ${human}.`;
+
+    // Multi-day Retry-After → almost certainly the Starter-tier daily quota.
+    const multiDay = retryAfter > 24 * 60 * 60;
+    const remediation = multiDay
+      ? [
+          `This is a Figma ${opts.planTier ?? 'Starter'}-tier daily/multi-day REST quota (not a transient burst).`,
+          'To continue today you must either:',
+          '  1) Re-run with a cached version: sungen add --screen <name> --figma <url>  (no --refresh)',
+          '     → reuses .sungen/figma-cache raw JSON; skips the /nodes API call entirely.',
+          opts.upgradeLink ? `  2) Upgrade the Figma account: ${opts.upgradeLink}` : '  2) Upgrade the Figma account to a paid tier.',
+          '  3) Wait for the quota window to reset.',
+        ].join('\n')
+      : 'Wait and retry, or reduce request frequency. In the meantime you can re-run without --refresh to reuse cached node JSON.';
+
+    super(msg, remediation);
+    this.retryAfter = retryAfter;
+    this.planTier = opts.planTier;
+    this.bucket = opts.bucket;
+    this.upgradeLink = opts.upgradeLink;
+  }
+}
+
+/** Turn `369943` → `4d 6h 45m`. */
+function formatRetryAfter(secs: number): string {
+  if (!Number.isFinite(secs) || secs <= 0) return `${secs}s`;
+  const d = Math.floor(secs / 86400);
+  const h = Math.floor((secs % 86400) / 3600);
+  const m = Math.floor((secs % 3600) / 60);
+  const parts: string[] = [];
+  if (d) parts.push(`${d}d`);
+  if (h) parts.push(`${h}h`);
+  if (m && !d) parts.push(`${m}m`);
+  if (!parts.length) parts.push(`${secs}s`);
+  return `${parts.join(' ')} (${secs}s)`;
+}
+
+/**
+ * Network / transport failure (timeout, DNS, stream error, etc.).
+ */
+export class FigmaNetworkError extends FigmaBaseError {
+  readonly cause: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(
+      message,
+      'Check your internet connection and verify api.figma.com is reachable. If the issue persists, retry.',
+    );
+    this.cause = cause;
+  }
+}