@sun-asterisk/sungen 2.5.0 → 2.5.2

package/dist/tools/figma/figma-node-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-node-filter.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-node-filter.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-rest-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { FigmaMeResponse, FigmaFileNodesResponse, FigmaImageUrlsResponse, FigmaImageOptions } from './figma-client-types';
+/**
+ * GET /v1/me — validate PAT and return user info.
+ */
+export declare function getMe(pat: string): Promise<FigmaMeResponse>;
+/**
+ * GET /v1/files/:key/nodes?ids=<id,id,...>
+ * Returns the raw node document and current file version.
+ */
+export declare function getFileNodes(pat: string, fileKey: string, nodeIds: string[]): Promise<FigmaFileNodesResponse>;
+/**
+ * GET /v1/images/:key?ids=<id,id>&scale=<n>&format=<fmt>
+ * Returns signed S3 URLs — consume immediately, do not persist.
+ */
+export declare function getImageUrls(pat: string, fileKey: string, nodeIds: string[], options?: FigmaImageOptions): Promise<FigmaImageUrlsResponse>;
+//# sourceMappingURL=figma-rest-client.d.ts.map

package/dist/tools/figma/figma-rest-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-rest-client.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-rest-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAkH9B;;GAEG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIjE;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CAYjC"}

package/dist/tools/figma/figma-rest-client.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMe = getMe;
+exports.getFileNodes = getFileNodes;
+exports.getImageUrls = getImageUrls;
+const figma_errors_1 = require("./figma-errors");
+// ---------------------------------------------------------------------------
+// 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 = 90000;
+function getRequestTimeoutMs() {
+    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) {
+    return { 'X-Figma-Token': pat };
+}
+/** Parse Retry-After header into seconds (default 60 when missing/invalid). */
+function parseRetryAfter(headers) {
+    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) {
+    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, url) {
+    const safeUrl = url.replace(/\?.*$/, ''); // strip query params (may contain ids)
+    if (status === 401)
+        throw new figma_errors_1.FigmaAuthError();
+    if (status === 403)
+        throw new figma_errors_1.FigmaAccessError(403);
+    if (status === 404)
+        throw new figma_errors_1.FigmaAccessError(404);
+    throw new figma_errors_1.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, url) {
+    let serverErrorRetried = false;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        let 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?.name === 'AbortError';
+            if (aborted) {
+                throw new figma_errors_1.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 figma_errors_1.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 figma_errors_1.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.
+ */
+async function getMe(pat) {
+    const url = `${BASE_URL}/v1/me`;
+    const response = await figmaFetch(pat, url);
+    return response.json();
+}
+/**
+ * GET /v1/files/:key/nodes?ids=<id,id,...>
+ * Returns the raw node document and current file version.
+ */
+async function getFileNodes(pat, fileKey, nodeIds) {
+    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();
+}
+/**
+ * GET /v1/images/:key?ids=<id,id>&scale=<n>&format=<fmt>
+ * Returns signed S3 URLs — consume immediately, do not persist.
+ */
+async function getImageUrls(pat, fileKey, nodeIds, options = {}) {
+    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();
+}
+//# sourceMappingURL=figma-rest-client.js.map

package/dist/tools/figma/figma-rest-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-rest-client.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-rest-client.ts"],"names":[],"mappings":"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"}

package/dist/tools/figma/figma-url-parser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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';
+/**
+ * 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 declare function parseFigmaUrl(url: string): FigmaNodeRef | null;
+//# sourceMappingURL=figma-url-parser.d.ts.map

package/dist/tools/figma/figma-url-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-url-parser.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-url-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAuBzD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAe9D"}

package/dist/tools/figma/figma-url-parser.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFigmaUrl = parseFigmaUrl;
+/**
+ * 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) {
+    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.
+ */
+function parseFigmaUrl(url) {
+    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 = { fileKey };
+    if (rawNodeId) {
+        result.nodeId = normalizeNodeId(rawNodeId);
+    }
+    return result;
+}
+//# sourceMappingURL=figma-url-parser.js.map

package/dist/tools/figma/figma-url-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-url-parser.js","sourceRoot":"","sources":["../../../src/tools/figma/figma-url-parser.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA+BH,sCAeC;AA1CD;;;;;GAKG;AACH,MAAM,YAAY,GAChB,6GAA6G,CAAC;AAEhH;;;;;GAKG;AACH,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACxC,+EAA+E;IAC/E,OAAO,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3B,MAAM,MAAM,GAAiB,EAAE,OAAO,EAAE,CAAC;IACzC,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/exec-file-no-throw.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Safe execFile wrapper — uses execFile (not exec) to prevent shell injection.
+ * Handles Windows compatibility and provides structured output.
+ */
+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 declare function execFileNoThrow(cmd: string, args: string[], cwd?: string): Promise<ExecFileResult>;
+//# sourceMappingURL=exec-file-no-throw.d.ts.map

package/dist/utils/exec-file-no-throw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-file-no-throw.d.ts","sourceRoot":"","sources":["../../src/utils/exec-file-no-throw.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CAezB"}

package/dist/utils/exec-file-no-throw.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Safe execFile wrapper — uses execFile (not exec) to prevent shell injection.
+ * Handles Windows compatibility and provides structured output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execFileNoThrow = execFileNoThrow;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * 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.
+ */
+async function execFileNoThrow(cmd, args, cwd) {
+    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) {
+        return {
+            stdout: err.stdout ?? '',
+            stderr: err.stderr ?? '',
+            status: typeof err.code === 'number' ? err.code : 1,
+        };
+    }
+}
+//# sourceMappingURL=exec-file-no-throw.js.map

package/dist/utils/exec-file-no-throw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-file-no-throw.js","sourceRoot":"","sources":["../../src/utils/exec-file-no-throw.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAsBH,0CAmBC;AAvCD,iDAAyC;AACzC,+BAAiC;AAEjC,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,wBAAQ,CAAC,CAAC;AAS1C;;;;;;;GAOG;AACI,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,IAAc,EACd,GAAY;IAEZ,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE;YACxD,GAAG;YACH,oDAAoD;YACpD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACnE,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;YACxB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;YACxB,MAAM,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SACpD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/commands/add.ts

@@ -1,4 +1,6 @@
 import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
 export function registerAddCommand(program: Command): void {
   program
@@ -9,6 +11,10 @@ export function registerAddCommand(program: Command): void {
     .option('-c, --capture', 'Auto-capture a live-page screenshot to requirements/ui/ (requires --path)')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
+    .option('--figma <url>', "Figma share URL — fetch design node and generate spec_figma.md + ui/*.png. QUOTE the URL ('...'): the '&' in Figma links backgrounds the shell otherwise.")
+    .option('--refresh', 'Bypass Figma cache and re-fetch from API (use with --figma)')
+    .option('--scale <n>', 'PNG export scale factor (default: 2)', parseFloat, 2)
+    .option('--hi-res', 'Export at 4× scale (shorthand for --scale 4)')
     .action(async (options) => {
       try {
         if (options.capture && !options.path) {
@@ -16,16 +22,81 @@ export function registerAddCommand(program: Command): void {
           process.exit(1);
         }
 
-        const { ScreenManager } = require('../../orchestrator/screen-manager');
-        const manager = new ScreenManager();
+        // When --figma is set on an existing screen, skip scaffolding and
+        // just refresh Figma-derived files (spec_figma.md, ui/*.png).
+        const screenDir = path.join(process.cwd(), 'qa', 'screens', options.screen);
+        const featureFile = path.join(screenDir, 'features', `${options.screen}.feature`);
+        const screenAlreadyExists = fs.existsSync(featureFile);
 
-        await manager.addScreen({
-          name: options.screen,
-          path: options.path,
-          capture: options.capture,
-          feature: options.feature,
-          description: options.description,
-        });
+        if (!(options.figma && screenAlreadyExists)) {
+          const { ScreenManager } = require('../../orchestrator/screen-manager');
+          const manager = new ScreenManager();
+
+          await manager.addScreen({
+            name: options.screen,
+            path: options.path,
+            capture: options.capture,
+            feature: options.feature,
+            description: options.description,
+          });
+        } else {
+          console.log(`Screen "${options.screen}" already exists — refreshing Figma assets only.`);
+        }
+
+        // Figma branch: run after directory scaffolding is complete
+        if (options.figma) {
+          const { FigmaScaffolder } = require('../../orchestrator/figma/figma-scaffolder');
+          const scale: number = options.hiRes ? 4 : (options.scale ?? 2);
+
+          try {
+            const result = await FigmaScaffolder.run({
+              screenName: options.screen,
+              figmaUrl: options.figma,
+              cwd: process.cwd(),
+              refresh: options.refresh ?? false,
+              scale,
+            });
+
+            console.log('\nFigma import complete:');
+            console.log(`  ${result.specFigmaPath}`);
+            for (const img of result.imagePaths) {
+              console.log(`  qa/screens/${options.screen}/requirements/${img}`);
+            }
+            if (result.specMdCreated) {
+              console.log(`  qa/screens/${options.screen}/requirements/spec.md (stub created)`);
+            }
+
+            // Loud banner: Tell the calling agent to
+            // invoke the `sungen-figma-source` skill to synthesize the narrative sections in spec_figma.md, since
+            // the CLI cannot do this (synthesis is LLM-driven off the cached raw JSON).
+            console.log('');
+            console.log('==============================================================');
+            console.log('  NEXT STEP (REQUIRED — DO NOT SKIP)');
+            console.log('==============================================================');
+            console.log('  spec_figma.md envelope is written but narrative is EMPTY.');
+            console.log('  Invoke the `sungen-figma-source` skill NOW to synthesize');
+            console.log('  the 7 sections (Purpose / ASCII Layout / Regions / Actions /');
+            console.log('  Form Fields / Data Columns / Navigation) below the');
+            console.log('  `<!-- SYNTHESIS-BELOW -->` marker.');
+            console.log('');
+            console.log('  Read the cached raw node JSON at:');
+            console.log(`    .sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json`);
+            console.log('  and append the narrative below the marker in:');
+            console.log(`    ${result.specFigmaPath}`);
+            console.log('==============================================================');
+          } catch (figmaError) {
+            const msg = figmaError instanceof Error ? figmaError.message : String(figmaError);
+            // Surface remediation hint when available
+            const remediation =
+              figmaError instanceof Error &&
+              'remediation' in figmaError &&
+              typeof (figmaError as { remediation: unknown }).remediation === 'string'
+                ? `\nHint: ${(figmaError as { remediation: string }).remediation}`
+                : '';
+            console.error(`\nFigma import failed: ${msg}${remediation}`);
+            process.exit(1);
+          }
+        }
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/figma.ts

@@ -0,0 +1,162 @@
+/**
+ * `sungen figma` subcommand dispatcher.
+ *
+ * Subcommands:
+ *   sungen figma auth set   — prompt for PAT, validate via /v1/me, persist to .env
+ *   sungen figma auth check — load PAT, call /v1/me, print handle + email
+ *   sungen figma auth clear — remove FIGMA_PAT from .env
+ */
+
+import { Command } from 'commander';
+import * as readline from 'readline';
+import { loadPat, savePat, clearPat, assertSafeToUse } from '../../tools/figma/figma-auth';
+import type { FigmaMeResponse } from '../../tools/figma/figma-client-types';
+
+const FIGMA_API_BASE = 'https://api.figma.com';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Read a line from stdin without echoing characters (hidden input). */
+function readHiddenInput(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // Disable echoing by replacing the _writeToOutput method
+    (rl as any)._writeToOutput = (str: string) => {
+      // Only write the prompt, not the typed characters
+      if (str === prompt) (rl as any).output.write(str);
+    };
+    rl.question(prompt, (answer) => {
+      (rl as any).output.write('\n');
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Call GET /v1/me with the given PAT.
+ * Returns parsed body on 2xx, throws with a scrubbed error message on failure.
+ */
+async function callFigmaMe(pat: string): Promise<FigmaMeResponse> {
+  let response: Response;
+  try {
+    response = await fetch(`${FIGMA_API_BASE}/v1/me`, {
+      headers: { 'X-Figma-Token': pat },
+    });
+  } catch (err: any) {
+    throw new Error(`Network error reaching Figma API: ${err.message ?? 'unknown'}`);
+  }
+
+  if (!response.ok) {
+    const status = response.status;
+    if (status === 403 || status === 401) {
+      throw new Error(`Figma API returned ${status}: token is invalid or lacks read scope.`);
+    }
+    throw new Error(`Figma API returned unexpected status ${status}.`);
+  }
+
+  return response.json() as Promise<FigmaMeResponse>;
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+async function handleAuthSet(options: { token?: string }, cwd: string): Promise<void> {
+  let pat = options.token;
+
+  if (!pat) {
+    pat = await readHiddenInput('Enter Figma Personal Access Token: ');
+  }
+
+  if (!pat) {
+    console.error('Error: token cannot be empty.');
+    process.exit(1);
+  }
+
+  console.log('Validating token with Figma API…');
+  let me: FigmaMeResponse;
+  try {
+    me = await callFigmaMe(pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  try {
+    await savePat(cwd, pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Token validated and saved. Authenticated as: ${me.handle} <${me.email}>`);
+}
+
+async function handleAuthCheck(cwd: string): Promise<void> {
+  try {
+    await assertSafeToUse(cwd);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const pat = loadPat(cwd);
+  if (!pat) {
+    console.error('Error: No FIGMA_PAT configured. Run `sungen figma auth set` first.');
+    process.exit(1);
+  }
+
+  let me: FigmaMeResponse;
+  try {
+    me = await callFigmaMe(pat);
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`Authenticated as: ${me.handle} <${me.email}>`);
+}
+
+async function handleAuthClear(cwd: string): Promise<void> {
+  clearPat(cwd);
+  console.log('FIGMA_PAT removed from .env.');
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerFigmaCommand(program: Command): void {
+  const figma = program
+    .command('figma')
+    .description('Figma integration — manage authentication and (future) asset fetching');
+
+  const auth = figma
+    .command('auth')
+    .description('Manage Figma Personal Access Token');
+
+  auth
+    .command('set')
+    .description('Validate and save a Figma PAT to .env')
+    .option('--token <token>', 'PAT value (for scripting; prefer interactive prompt)')
+    .action(async (options) => {
+      await handleAuthSet(options, process.cwd());
+    });
+
+  auth
+    .command('check')
+    .description('Verify saved PAT by calling /v1/me and print account info')
+    .action(async () => {
+      await handleAuthCheck(process.cwd());
+    });
+
+  auth
+    .command('clear')
+    .description('Remove FIGMA_PAT from .env')
+    .action(async () => {
+      await handleAuthClear(process.cwd());
+    });
+}

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
 import { registerUpdateCommand } from './commands/update';
 import { registerDeliveryCommand } from './commands/delivery';
+import { registerFigmaCommand } from './commands/figma';
 
 async function main() {
   const program = new Command();
@@ -18,19 +19,20 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.5.0');
+    .version('2.5.2');
 
   // Global options
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (6)
+  // Register commands (7)
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
   registerUpdateCommand(program);
   registerDeliveryCommand(program);
+  registerFigmaCommand(program);
 
   await program.parseAsync(process.argv);
 }