devendra-skill-package 1.0.2

package/.github/skills/figma-ui-mapper/scripts/generate-page-through-figma.js

@@ -0,0 +1,635 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+
+const DEFAULT_ASSET_PATH = 'src/assets';
+const MAX_SCAN_DEPTH = 5;
+const IGNORED_DIRS = new Set([
+  '.git', '.github', 'node_modules', '.next', '.nuxt', 'dist', 'build', 'coverage',
+  '.turbo', '.nx', '.dart_tool', 'Pods',
+]);
+
+const FRAMEWORK_ORDER = [
+  'expo', 'next', 'nuxt', 'angular', 'ionic', 'react-native', 'flutter', 'vue',
+  'svelte', 'capacitor', 'kotlin-multiplatform', 'native-android', 'native-ios', 'react',
+];
+
+const FRAMEWORK_RULE_PATH = framework => `.github/skills/figma-ui-mapper/references/frameworks/${framework}/rules.md`;
+const PLATFORM_REFERENCE_PATH = framework => `.github/skills/figma-ui-mapper/references/${framework}.md`;
+const FIGMA_URL_PATTERN = /https?:\/\/(?:www\.)?figma\.com\/(?:design|file)\/[A-Za-z0-9]+\/[^\s"'<>\]]+/;
+
+const ADAPTERS = {
+  react: {
+    displayName: 'React',
+    pageFile: pageName => `${pageName}.tsx`,
+    styleFile: pageName => `${pageName}Style.ts`,
+    tokenFile: pageName => `${pageName}Tokens.ts`,
+    pageTemplate: pageName => `import React from 'react';\n\nimport { styles } from './${pageName}Style';\n\nconst ${pageName} = () => <div style={styles.container} />;\n\nexport default ${pageName};\n`,
+    styleTemplate: () => `import React from 'react';\n\nexport const styles: Record<string, React.CSSProperties> = {\n  container: {\n    display: 'flex',\n    flexDirection: 'column',\n    flex: 1,\n  },\n};\n`,
+    tokenTemplate: () => `export const tokens = {\n  colors: {},\n  spacing: {},\n  typography: {},\n  radii: {},\n  shadows: {},\n};\n`,
+  },
+  'react-native': {
+    displayName: 'React Native',
+    pageFile: pageName => `${pageName}.tsx`,
+    styleFile: pageName => `${pageName}Style.ts`,
+    tokenFile: pageName => `${pageName}Tokens.ts`,
+    pageTemplate: pageName => `import React from 'react';\nimport { View } from 'react-native';\n\nimport { styles } from './${pageName}Style';\n\nconst ${pageName} = () => <View style={styles.container} />;\n\nexport default ${pageName};\n`,
+    styleTemplate: () => `import { StyleSheet } from 'react-native';\n\nexport const styles = StyleSheet.create({\n  container: {\n    flex: 1,\n  },\n});\n`,
+    tokenTemplate: () => `export const tokens = {\n  colors: {},\n  spacing: {},\n  typography: {},\n  radii: {},\n  shadows: {},\n};\n`,
+  },
+  flutter: {
+    displayName: 'Flutter',
+    pageFile: pageName => `${toKebab(pageName)}.dart`,
+    styleFile: pageName => `${toKebab(pageName)}_style.dart`,
+    tokenFile: pageName => `${toKebab(pageName)}_tokens.dart`,
+    pageTemplate: pageName => `import 'package:flutter/widgets.dart';\n\nclass ${pageName} extends StatelessWidget {\n  const ${pageName}({super.key});\n\n  @override\n  Widget build(BuildContext context) {\n    return const SizedBox.expand();\n  }\n}\n`,
+    styleTemplate: pageName => `class ${pageName}Style {}\n`,
+    tokenTemplate: () => `const tokens = <String, Object>{};\n`,
+  },
+  angular: {
+    displayName: 'Angular',
+    pageFile: pageName => `${toKebab(pageName)}.component.ts`,
+    styleFile: pageName => `${toKebab(pageName)}.component.scss`,
+    tokenFile: pageName => `${toKebab(pageName)}.tokens.ts`,
+    pageTemplate: pageName => `import { Component } from '@angular/core';\n\n@Component({\n  selector: 'app-${toKebab(pageName)}',\n  standalone: true,\n  templateUrl: './${toKebab(pageName)}.component.html',\n  styleUrl: './${toKebab(pageName)}.component.scss',\n})\nexport class ${pageName}Component {}\n`,
+    styleTemplate: () => `:host {\n  display: block;\n}\n`,
+    tokenTemplate: () => `export const tokens = {};\n`,
+    extras: pageName => [{name: `${toKebab(pageName)}.component.html`, content: '<section></section>\n'}],
+  },
+  vue: {
+    displayName: 'Vue',
+    pageFile: pageName => `${pageName}.vue`,
+    styleFile: pageName => `${pageName}.css`,
+    tokenFile: pageName => `${pageName}.tokens.ts`,
+    pageTemplate: pageName => `<template>\n  <section class=\"container\"></section>\n</template>\n\n<script setup lang=\"ts\">\n</script>\n\n<style scoped src=\"./${pageName}.css\"></style>\n`,
+    styleTemplate: () => `.container {\n  display: flex;\n  flex-direction: column;\n}\n`,
+    tokenTemplate: () => `export const tokens = {};\n`,
+  },
+  svelte: {
+    displayName: 'Svelte',
+    pageFile: pageName => `${pageName}.svelte`,
+    styleFile: pageName => `${pageName}.css`,
+    tokenFile: pageName => `${pageName}.tokens.ts`,
+    pageTemplate: pageName => `<section class=\"container\"></section>\n\n<style src=\"./${pageName}.css\"></style>\n`,
+    styleTemplate: () => `.container {\n  display: flex;\n}\n`,
+    tokenTemplate: () => `export const tokens = {};\n`,
+  },
+  'native-android': {
+    displayName: 'Native Android',
+    pageFile: pageName => `${pageName}Screen.kt`,
+    styleFile: pageName => `${toKebab(pageName)}_screen.xml`,
+    tokenFile: pageName => `${toKebab(pageName)}_tokens.json`,
+    pageTemplate: pageName => `package com.example.generated\n\nclass ${pageName}Screen\n`,
+    styleTemplate: () => `<FrameLayout xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\" />\n`,
+    tokenTemplate: () => `{\n  \"tokens\": {}\n}\n`,
+  },
+  'native-ios': {
+    displayName: 'Native iOS',
+    pageFile: pageName => `${pageName}View.swift`,
+    styleFile: pageName => `${pageName}Theme.swift`,
+    tokenFile: pageName => `${pageName}Tokens.json`,
+    pageTemplate: pageName => `import SwiftUI\n\nstruct ${pageName}View: View {\n    var body: some View {\n        VStack { }\n    }\n}\n`,
+    styleTemplate: pageName => `import SwiftUI\n\nenum ${pageName}Theme {}\n`,
+    tokenTemplate: () => `{\n  \"tokens\": {}\n}\n`,
+  },
+  'kotlin-multiplatform': {
+    displayName: 'Kotlin Multiplatform',
+    pageFile: pageName => `${pageName}Screen.kt`,
+    styleFile: pageName => `${pageName}Theme.kt`,
+    tokenFile: pageName => `${pageName}Tokens.json`,
+    pageTemplate: pageName => `package com.example.generated\n\nclass ${pageName}Screen\n`,
+    styleTemplate: pageName => `object ${pageName}Theme\n`,
+    tokenTemplate: () => `{\n  \"tokens\": {}\n}\n`,
+  },
+};
+ADAPTERS.next = ADAPTERS.react;
+ADAPTERS.nuxt = ADAPTERS.vue;
+ADAPTERS.expo = ADAPTERS['react-native'];
+ADAPTERS.ionic = ADAPTERS.react;
+ADAPTERS.capacitor = ADAPTERS.react;
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) out[key] = 'true';
+    else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(`\nFigma UI Mapper\n\nUsage:\n  node ./scripts/generate-page-through-figma.js [options]\n\nOptions:\n  --figmaUrl <url>\n  --pageName <PascalCase>\n  --pages <json-array>\n  --linksFile <path>\n  --pagePath <path>\n  --componentPath <path>\n  --assetPath <path>\n  --reusableComponentsPath <path>\n  --projectPath <path>\n  --nonInteractive\n  --dryRun\n  --allowOutsideProject\n  --help\n`);
+}
+
+function parseFigma(url) {
+  try {
+    const parsed = new URL(url);
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const idx = segments.findIndex(v => v === 'design' || v === 'file');
+    const fileKey = idx >= 0 ? segments[idx + 1] : '';
+    const title = idx >= 0 ? segments[idx + 2] : 'FigmaPage';
+    const nodeId = String(parsed.searchParams.get('node-id') || '').trim().replace(/-/g, ':');
+    return {fileKey, nodeId, title};
+  } catch {
+    return {fileKey: '', nodeId: '', title: ''};
+  }
+}
+
+function isUrl(v) {
+  try {
+    const u = new URL(v);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, {recursive: true});
+}
+
+function writeFileSafe(file, content, dryRun) {
+  if (dryRun) return {created: !fs.existsSync(file), file};
+  ensureDir(path.dirname(file));
+  if (fs.existsSync(file)) return {created: false, file};
+  fs.writeFileSync(file, content, 'utf8');
+  return {created: true, file};
+}
+
+function toPascal(input) {
+  return String(input)
+    .replace(/[^A-Za-z0-9]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(token => token.charAt(0).toUpperCase() + token.slice(1))
+    .join('') || 'FigmaPage';
+}
+
+function toKebab(input) {
+  return String(input)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+function readJson(file) {
+  try { return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null; }
+  catch { return null; }
+}
+
+function readText(file) {
+  try { return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''; }
+  catch { return ''; }
+}
+
+function dep(pkg, name) {
+  if (!pkg) return '';
+  return pkg.dependencies?.[name] || pkg.devDependencies?.[name] || pkg.peerDependencies?.[name] || '';
+}
+
+function detectArchitecture(projectRoot) {
+  const has = rel => fs.existsSync(path.join(projectRoot, rel));
+  if (has('src/domain') && has('src/data') && has('src/presentation')) return 'clean-architecture';
+  if (has('src/features')) return 'feature-first';
+  if (has('src/pages') || has('pages')) return 'page-first';
+  return 'standard';
+}
+
+function isLikelyProjectRoot(dir) {
+  const checks = [
+    'package.json', 'pubspec.yaml', 'angular.json', 'next.config.js', 'next.config.ts',
+    'nuxt.config.js', 'nuxt.config.ts', 'android', 'ios', 'build.gradle', 'build.gradle.kts', 'Podfile',
+  ];
+  return checks.some(item => fs.existsSync(path.join(dir, item)));
+}
+
+function scanProjects(rootDir, depth = 0, found = []) {
+  if (depth > MAX_SCAN_DEPTH) return found;
+  if (isLikelyProjectRoot(rootDir)) found.push(rootDir);
+  let entries = [];
+  try { entries = fs.readdirSync(rootDir, {withFileTypes: true}); }
+  catch { return found; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    scanProjects(path.join(rootDir, entry.name), depth + 1, found);
+  }
+  return found;
+}
+
+function uniquePaths(paths) {
+  return [...new Set(paths.map(p => path.resolve(p)))];
+}
+
+function detectFramework(projectRoot) {
+  const pkg = readJson(path.join(projectRoot, 'package.json'));
+  const gradle = [
+    readText(path.join(projectRoot, 'build.gradle')),
+    readText(path.join(projectRoot, 'build.gradle.kts')),
+    readText(path.join(projectRoot, 'settings.gradle')),
+    readText(path.join(projectRoot, 'settings.gradle.kts')),
+  ].join('\n');
+  const has = rel => fs.existsSync(path.join(projectRoot, rel));
+
+  const checks = {
+    expo: () => dep(pkg, 'expo') || has('app.json') || has('app.config.ts') || has('app.config.js'),
+    next: () => dep(pkg, 'next') || has('next.config.js') || has('next.config.ts') || has('next.config.mjs') || has('next.config.cjs'),
+    nuxt: () => dep(pkg, 'nuxt') || has('nuxt.config.js') || has('nuxt.config.ts') || has('nuxt.config.mjs') || has('nuxt.config.cjs'),
+    angular: () => dep(pkg, '@angular/core') || has('angular.json'),
+    ionic: () => dep(pkg, '@ionic/angular') || dep(pkg, '@ionic/react') || dep(pkg, '@ionic/vue') || has('ionic.config.json'),
+    'react-native': () => dep(pkg, 'react-native') || (has('android') && has('ios') && (has('App.tsx') || has('index.js'))),
+    flutter: () => has('pubspec.yaml') || has('main.dart') || has('lib/main.dart'),
+    vue: () => dep(pkg, 'vue'),
+    svelte: () => dep(pkg, 'svelte') || has('svelte.config.js') || has('svelte.config.ts'),
+    capacitor: () => dep(pkg, '@capacitor/core') || has('capacitor.config.ts') || has('capacitor.config.js') || has('capacitor.config.json'),
+    'kotlin-multiplatform': () => has('shared/src/commonMain') || /kotlin\("multiplatform"\)|org\.jetbrains\.kotlin\.multiplatform/.test(gradle),
+    'native-android': () => has('android') || has('build.gradle') || has('build.gradle.kts'),
+    'native-ios': () => has('ios') || has('Podfile') || has('ios/Podfile'),
+    react: () => dep(pkg, 'react') || dep(pkg, 'react-dom') || has('src/App.tsx') || has('src/App.jsx'),
+  };
+
+  for (const name of FRAMEWORK_ORDER) {
+    if (checks[name]()) {
+      return {
+        framework: name,
+        reason: `Detected ${name} by repository signals in ${path.relative(process.cwd(), projectRoot) || '.'}.`,
+        version: dep(pkg, name === 'react' ? 'react' : name) || 'unknown',
+        architecture: detectArchitecture(projectRoot),
+      };
+    }
+  }
+  return {
+    framework: 'react',
+    reason: `No explicit framework markers found in ${path.relative(process.cwd(), projectRoot) || '.'}. Defaulted to react adapter.`,
+    version: dep(pkg, 'react') || 'unknown',
+    architecture: detectArchitecture(projectRoot),
+  };
+}
+
+function parseLinksText(raw) {
+  const entries = [];
+  for (const lineRaw of raw.split(/\r?\n/)) {
+    const line = lineRaw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(FIGMA_URL_PATTERN);
+    if (!m) continue;
+    const figmaUrl = m[0];
+    const before = line.slice(0, m.index).trim();
+    const pageName = before ? toPascal(before) : undefined;
+    entries.push(pageName ? {pageName, figmaUrl} : {figmaUrl});
+  }
+  return entries;
+}
+
+function parsePagesFromArgs(args, projectRoot) {
+  if (args.pages) {
+    const parsed = JSON.parse(args.pages);
+    if (!Array.isArray(parsed)) throw new Error('--pages must be a JSON array');
+    return parsed;
+  }
+  if (args.linksFile) {
+    const file = path.resolve(projectRoot, args.linksFile);
+    if (!fs.existsSync(file)) throw new Error(`linksFile not found: ${file}`);
+    const raw = fs.readFileSync(file, 'utf8').trim();
+    if (file.toLowerCase().endsWith('.json')) {
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) throw new Error('linksFile JSON must be an array');
+      return parsed;
+    }
+    return parseLinksText(raw);
+  }
+  if (args.figmaUrl) return [{pageName: args.pageName, figmaUrl: args.figmaUrl}];
+  return null;
+}
+
+function resolveWithinProject(projectRoot, candidate, allowOutside) {
+  const resolved = path.resolve(projectRoot, candidate || '.');
+  if (allowOutside) return resolved;
+  const root = path.resolve(projectRoot);
+  if (resolved === root || resolved.startsWith(root + path.sep)) return resolved;
+  throw new Error(`Path is outside project root and blocked: ${candidate}`);
+}
+
+async function pickProjectRoot(args, reader) {
+  if (args.projectPath) {
+    const selected = path.resolve(process.cwd(), args.projectPath);
+    if (!fs.existsSync(selected)) throw new Error(`projectPath does not exist: ${selected}`);
+    return selected;
+  }
+  const projects = uniquePaths(scanProjects(process.cwd()));
+  if (projects.length <= 1) return projects[0] || process.cwd();
+  if (args.nonInteractive === 'true') throw new Error(`Multiple projects detected (${projects.length}). Use --projectPath.`);
+  console.log('\nMultiple candidate projects detected:');
+  projects.forEach((p, i) => console.log(`  ${i + 1}. ${path.relative(process.cwd(), p) || '.'}`));
+  while (true) {
+    const input = (await reader.question('Select project number: ')).trim();
+    const idx = Number.parseInt(input, 10) - 1;
+    if (!Number.isNaN(idx) && projects[idx]) return projects[idx];
+  }
+}
+
+async function promptPages(reader) {
+  const pages = [];
+  let i = 1;
+  while (true) {
+    const value = (await reader.question(`Page ${i} Figma URL (or done): `)).trim();
+    if (value.toLowerCase() === 'done') {
+      if (pages.length === 0) {
+        console.log('At least one page is required.');
+        continue;
+      }
+      return pages;
+    }
+    if (!isUrl(value)) {
+      console.log('Invalid URL. Provide a valid https URL.');
+      continue;
+    }
+    const info = parseFigma(value);
+    if (!info.fileKey || !info.nodeId) {
+      console.log('Figma URL must include file key and node-id query parameter.');
+      continue;
+    }
+    const inferred = toPascal(info.title);
+    const name = (await reader.question(`Page name [${inferred}]: `)).trim() || inferred;
+    pages.push({pageName: toPascal(name), figmaUrl: value});
+    i += 1;
+  }
+}
+
+function renderTemplate(templateText, values) {
+  let out = templateText;
+  for (const [k, v] of Object.entries(values)) out = out.split(`{{${k}}}`).join(String(v));
+  return out;
+}
+
+function buildReportValues(config, detection, rows, skipped, projectRoot) {
+  return {
+    generated_at: new Date().toISOString(),
+    project_root: projectRoot,
+    figma_urls: rows.map(r => r.figmaUrl).join(', '),
+    page_path: config.pagePath,
+    component_path: config.componentPath,
+    asset_path: config.assetPath,
+    reusable_components_path: config.reusableComponentsPath,
+    detected_framework: detection.framework,
+    framework_version: detection.version,
+    architecture_detected: detection.architecture,
+    detection_reason: detection.reason,
+    adapter_used: detection.framework,
+    platform_reference: PLATFORM_REFERENCE_PATH(detection.framework),
+    framework_rules: FRAMEWORK_RULE_PATH(detection.framework),
+    pages_requested: config.pages.length,
+    pages_generated: rows.length,
+    pages_skipped: skipped.length,
+    coverage_map_match: 'PENDING_IMPLEMENTATION_PHASE',
+    components_reused: 0,
+    components_generated: rows.length,
+    token_extraction: 'PENDING_MCP_PHASE',
+    assets_resolved_local: 0,
+    assets_downloaded_figma: 0,
+    asset_failures: 0,
+    component_first_generation: 'PENDING_MCP_PHASE',
+    accessibility_check: 'PENDING_IMPLEMENTATION_PHASE',
+    screenshot_comparison: 'PENDING_IMPLEMENTATION_PHASE',
+    iteration_count: 0,
+    qa_status: 'PENDING_IMPLEMENTATION_PHASE',
+    errors: 'none',
+    warnings: skipped.length ? skipped.map(s => `${s.pageName}: ${s.reason}`).join('; ') : 'none',
+    summary: 'Scaffold created. Continue with MCP-backed implementation workflow.',
+  };
+}
+
+function createScaffold(config, detection, options) {
+  const adapter = ADAPTERS[detection.framework] || ADAPTERS.react;
+  const dryRun = options.dryRun;
+  const projectRoot = options.projectRoot;
+
+  const reusableDir = resolveWithinProject(projectRoot, config.reusableComponentsPath, options.allowOutside);
+  const assetRoot = resolveWithinProject(projectRoot, config.assetPath, options.allowOutside);
+  const reportsRoot = path.join(projectRoot, '.figma-ui-mapper', 'reports');
+  const artifactsRoot = path.join(projectRoot, '.figma-ui-mapper', 'artifacts');
+
+  if (!dryRun) {
+    ensureDir(reusableDir);
+    ensureDir(path.join(assetRoot, 'images'));
+    ensureDir(path.join(assetRoot, 'svg'));
+    ensureDir(reportsRoot);
+    ensureDir(artifactsRoot);
+  }
+
+  const rows = [];
+  const skipped = [];
+  const componentMapTemplate = readText(path.join(__dirname, '..', 'assets', 'templates', 'component-map-template.md'));
+
+  for (const page of config.pages) {
+    try {
+      const pageDir = resolveWithinProject(projectRoot, path.join(config.pagePath, page.pageName), options.allowOutside);
+      const componentDir = resolveWithinProject(projectRoot, path.join(config.componentPath, page.pageName), options.allowOutside);
+      if (!dryRun) { ensureDir(pageDir); ensureDir(componentDir); }
+
+      const pageFile = path.join(pageDir, adapter.pageFile(page.pageName));
+      const styleFile = path.join(pageDir, adapter.styleFile(page.pageName));
+      const tokenFile = path.join(pageDir, adapter.tokenFile(page.pageName));
+
+      const createdPage = writeFileSafe(pageFile, adapter.pageTemplate(page.pageName), dryRun);
+      const createdStyle = writeFileSafe(styleFile, adapter.styleTemplate(page.pageName), dryRun);
+      const createdToken = writeFileSafe(tokenFile, adapter.tokenTemplate(page.pageName), dryRun);
+      for (const extra of (adapter.extras ? adapter.extras(page.pageName) : [])) writeFileSafe(path.join(pageDir, extra.name), extra.content, dryRun);
+
+      const row = {
+        pageName: page.pageName,
+        figmaUrl: page.figmaUrl,
+        fileKey: page.fileKey,
+        nodeId: page.nodeId,
+        pageFile,
+        styleFile,
+        tokenFile,
+        componentDir,
+        createdPage: createdPage.created,
+        createdStyle: createdStyle.created,
+        createdToken: createdToken.created,
+      };
+      rows.push(row);
+
+      const componentMap = renderTemplate(componentMapTemplate, {
+        page_name: page.pageName,
+        figma_url: page.figmaUrl,
+        file_key: page.fileKey,
+        node_id: page.nodeId,
+        frame_name: page.pageName,
+        size: 'PENDING_MCP',
+        sections_table: 'PENDING_MCP',
+        reusable_components_table: 'PENDING_MCP',
+        assets_table: 'PENDING_MCP',
+        inventory_reference: 'PENDING_MCP',
+        coverage_map_reference: 'PENDING_MCP',
+        generation_order: 'PENDING_MCP',
+        status_table: 'PENDING_MCP',
+      });
+      writeFileSafe(path.join(reportsRoot, `${page.pageName}-component-map.md`), componentMap, dryRun);
+    } catch (error) {
+      skipped.push({pageName: page.pageName, reason: error.message});
+    }
+  }
+
+  const reportTemplate = readText(path.join(__dirname, '..', 'assets', 'templates', 'generation-report-template.md'));
+  const reportValues = buildReportValues(config, detection, rows, skipped, projectRoot);
+  const reportMarkdown = renderTemplate(reportTemplate, reportValues);
+  writeFileSafe(path.join(reportsRoot, 'generation-report.md'), reportMarkdown, dryRun);
+
+  const artifact = {
+    generatedAt: reportValues.generated_at,
+    projectRoot,
+    framework: detection.framework,
+    version: detection.version,
+    architecture: detection.architecture,
+    detectionReason: detection.reason,
+    pagesRequested: config.pages.length,
+    pagesGenerated: rows.map(r => ({
+      pageName: r.pageName,
+      figmaUrl: r.figmaUrl,
+      fileKey: r.fileKey,
+      nodeId: r.nodeId,
+      pageFile: path.relative(projectRoot, r.pageFile).replace(/\\/g, '/'),
+      styleFile: path.relative(projectRoot, r.styleFile).replace(/\\/g, '/'),
+      tokenFile: path.relative(projectRoot, r.tokenFile).replace(/\\/g, '/'),
+      componentDir: path.relative(projectRoot, r.componentDir).replace(/\\/g, '/'),
+    })),
+    pagesSkipped: skipped,
+    workflowState: {
+      detection: 'DONE',
+      scaffolding: 'DONE',
+      mcpExtraction: 'PENDING',
+      componentFirstGeneration: 'PENDING',
+      validation: 'PENDING',
+      finalQa: 'PENDING',
+    },
+    references: {
+      workflow: '.github/skills/figma-ui-mapper/references/workflow.md',
+      frameworkRules: FRAMEWORK_RULE_PATH(detection.framework),
+      platformReference: PLATFORM_REFERENCE_PATH(detection.framework),
+    },
+    report: {
+      path: path.join('.figma-ui-mapper', 'reports', 'generation-report.md').replace(/\\/g, '/'),
+      warnings: reportValues.warnings,
+      errors: reportValues.errors,
+    },
+  };
+
+  const artifactPath = path.join(artifactsRoot, 'figma-generated-pages.json');
+  writeFileSafe(artifactPath, JSON.stringify(artifact, null, 2) + '\n', dryRun);
+  return {rows, skipped, artifact, artifactPath, reportsRoot, artifactsRoot};
+}
+
+function printSummary(detection, output, projectRoot, dryRun) {
+  const adapter = ADAPTERS[detection.framework] || ADAPTERS.react;
+  console.log('\nFigma UI Mapper scaffold prepared\n');
+  console.log(`Project Root: ${projectRoot}`);
+  console.log(`Detected Framework: ${adapter.displayName}`);
+  console.log(`Detection Reason: ${detection.reason}`);
+  console.log(`Framework Adapter Used: ${detection.framework}`);
+  console.log(`Framework Version: ${detection.version}`);
+  console.log(`Architecture Detected: ${detection.architecture}`);
+  console.log(`Rule File: ${FRAMEWORK_RULE_PATH(detection.framework)}`);
+  console.log(`Platform Reference: ${PLATFORM_REFERENCE_PATH(detection.framework)}`);
+  console.log(`Mode: ${dryRun ? 'DRY RUN' : 'WRITE'}`);
+  console.log('');
+
+  for (const row of output.rows) {
+    console.log(`Page: ${row.pageName}`);
+    console.log(`  Figma URL: ${row.figmaUrl}`);
+    console.log(`  fileKey: ${row.fileKey}`);
+    console.log(`  nodeId: ${row.nodeId}`);
+    console.log(`  Page File: ${row.pageFile}${row.createdPage ? ' (created)' : ' (existing)'}`);
+    console.log(`  Style File: ${row.styleFile}${row.createdStyle ? ' (created)' : ' (existing)'}`);
+    console.log(`  Token File: ${row.tokenFile}${row.createdToken ? ' (created)' : ' (existing)'}`);
+    console.log(`  Component Dir: ${row.componentDir}`);
+    console.log('');
+  }
+
+  if (output.skipped.length) {
+    console.log('Skipped pages:');
+    for (const item of output.skipped) console.log(`  - ${item.pageName}: ${item.reason}`);
+    console.log('');
+  }
+
+  console.log(`Reports Root: ${output.reportsRoot}`);
+  console.log(`Artifact Path: ${output.artifactPath}`);
+  console.log('');
+  console.log(`FIGMA_ARTIFACT:${JSON.stringify(output.artifact)}`);
+}
+
+async function collectConfig(args, reader, projectRoot) {
+  const incoming = parsePagesFromArgs(args, projectRoot);
+  const pagesRaw = incoming || (args.nonInteractive === 'true' ? null : await promptPages(reader));
+  if (!pagesRaw) throw new Error('No input pages. Provide --figmaUrl, --pages, or --linksFile in non-interactive mode.');
+
+  const pages = [];
+  const rejected = [];
+  for (const entry of pagesRaw) {
+    const figmaUrl = String(entry.figmaUrl || '').trim();
+    if (!isUrl(figmaUrl)) { rejected.push({entry, reason: 'Invalid URL'}); continue; }
+    const info = parseFigma(figmaUrl);
+    if (!info.fileKey || !info.nodeId) { rejected.push({entry, reason: 'Missing fileKey or node-id'}); continue; }
+    pages.push({ pageName: toPascal(entry.pageName || info.title), figmaUrl, fileKey: info.fileKey, nodeId: info.nodeId });
+  }
+  if (!pages.length) throw new Error('No valid Figma pages provided.');
+
+  const ask = async (label, fallback) => {
+    const v = (await reader.question(`${label}${fallback ? ` [${fallback}]` : ''}: `)).trim();
+    return v || fallback;
+  };
+
+  const pagePath = args.pagePath || (args.nonInteractive === 'true' ? null : await ask('Page path'));
+  const componentPath = args.componentPath || (args.nonInteractive === 'true' ? null : await ask('Component path'));
+  const assetPath = args.assetPath || (args.nonInteractive === 'true' ? DEFAULT_ASSET_PATH : await ask('Asset path', DEFAULT_ASSET_PATH));
+  const reusableComponentsPath = args.reusableComponentsPath || (args.nonInteractive === 'true' ? null : await ask('Reusable components path'));
+
+  if (!pagePath || !componentPath || !reusableComponentsPath) {
+    throw new Error('Missing required paths. In non-interactive mode provide --pagePath --componentPath --reusableComponentsPath.');
+  }
+
+  return {pages, rejected, pagePath, componentPath, assetPath, reusableComponentsPath};
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help === 'true') { printHelp(); return; }
+
+  const reader = readline.createInterface({input: process.stdin, output: process.stdout});
+  try {
+    const projectRoot = await pickProjectRoot(args, reader);
+    const detection = detectFramework(projectRoot);
+    const config = await collectConfig(args, reader, projectRoot);
+
+    const output = createScaffold(config, detection, {
+      dryRun: args.dryRun === 'true',
+      allowOutside: args.allowOutsideProject === 'true',
+      projectRoot,
+    });
+
+    printSummary(detection, output, projectRoot, args.dryRun === 'true');
+
+    if (config.rejected.length) {
+      console.log('\nRejected inputs:');
+      for (const item of config.rejected) console.log(`  - ${JSON.stringify(item.entry)} :: ${item.reason}`);
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  } finally {
+    reader.close();
+  }
+}
+
+main();

package/.github/skills/figma-ui-mapper/scripts/generate-react-page-through-figma.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.warn('[DEPRECATED] Use generate-page-through-figma.js. Redirecting to generic entrypoint.');
+require('./generate-page-through-figma.js');