yap2app 1.0.0 → 1.1.0

package/bin/cli-esm.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { startBridge } from '../bridge.js';
+import { runMcpServer } from '../mcp.js';
+import { scanCodebase } from '../scanner.js';
+
+const command = process.argv[2] || 'start';
+
+async function main() {
+  if (command === 'mcp') {
+    // Run stdio MCP server for Cursor / Claude Desktop / VS Code
+    await runMcpServer();
+  } else if (command === 'scan') {
+    // Run standalone shallow scanner and print summary
+    console.log(`\n🔍 Yap2App Codebase Context Scanner:`);
+    const context = await scanCodebase(process.cwd());
+    console.log(`\nProject: ${context.project_name}`);
+    console.log(`Framework: ${context.framework} (${context.router_type})`);
+    console.log(`Path Alias: ${context.path_alias}`);
+    console.log(`Dependencies Detected: ${context.dependencies.length}`);
+    console.log(`UI Components Catalog: ${context.component_names.join(', ') || 'None'}`);
+    console.log(`\nFull Context JSON:\n`, JSON.stringify(context, null, 2));
+  } else if (command === 'start' || command === 'bridge' || command === 'server') {
+    // Start Localhost Bridge for Web Studio UI
+    startBridge();
+  } else if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(`
+⚡ Yap2App CLI & MCP Toolkit ⚡
+
+Usage:
+  npx yap2app [command]
+
+Commands:
+  start | bridge   Start the Localhost Bridge with W3C PNA for 1-click Web Studio Sync (Default)
+  mcp              Run the Model Context Protocol (MCP) Server over stdio for Cursor/Claude
+  scan             Run a shallow codebase scan and print detected standards & UI primitives
+  help             Display this help guide
+`);
+  } else {
+    // Default fallback to bridge
+    startBridge();
+  }
+}
+
+main().catch(err => {
+  console.error("Yap2App CLI Error:", err);
+  process.exit(1);
+});

package/bin/cli.js

@@ -1,48 +1,19 @@
 #!/usr/bin/env node
 
-import { startBridge } from '../bridge.js';
-import { runMcpServer } from '../mcp.js';
-import { scanCodebase } from '../scanner.js';
+var nodeVersion = process.version;
+var majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
 
-const command = process.argv[2] || 'start';
-
-async function main() {
-  if (command === 'mcp') {
-    // Run stdio MCP server for Cursor / Claude Desktop / VS Code
-    await runMcpServer();
-  } else if (command === 'scan') {
-    // Run standalone shallow scanner and print summary
-    console.log(`\n🔍 Yap2App Codebase Context Scanner:`);
-    const context = await scanCodebase(process.cwd());
-    console.log(`\nProject: ${context.project_name}`);
-    console.log(`Framework: ${context.framework} (${context.router_type})`);
-    console.log(`Path Alias: ${context.path_alias}`);
-    console.log(`Dependencies Detected: ${context.dependencies.length}`);
-    console.log(`UI Components Catalog: ${context.component_names.join(', ') || 'None'}`);
-    console.log(`\nFull Context JSON:\n`, JSON.stringify(context, null, 2));
-  } else if (command === 'start' || command === 'bridge' || command === 'server') {
-    // Start Localhost Bridge for Web Studio UI
-    startBridge();
-  } else if (command === 'help' || command === '--help' || command === '-h') {
-    console.log(`
-⚡ Yap2App CLI & MCP Toolkit ⚡
-
-Usage:
-  npx @yap2app/cli [command]
-
-Commands:
-  start | bridge   Start the Localhost Bridge with W3C PNA for 1-click Web Studio Sync (Default)
-  mcp              Run the Model Context Protocol (MCP) Server over stdio for Cursor/Claude
-  scan             Run a shallow codebase scan and print detected standards & UI primitives
-  help             Display this help guide
-`);
-  } else {
-    // Default fallback to bridge
-    startBridge();
-  }
+if (majorVersion < 18) {
+  console.error('\n============================================================');
+  console.error('❌ Yap2App requires Node.js v18+ (Current: ' + nodeVersion + ')');
+  console.error('👉 Please switch to a modern Node version by running:');
+  console.error('   nvm use 20    (or: nvm use 18)');
+  console.error('============================================================\n');
+  process.exit(1);
 }
 
-main().catch(err => {
-  console.error("Yap2App CLI Error:", err);
+// Dynamically import the ES module entrypoint for Node 18+
+import('./cli-esm.js').catch(function(err) {
+  console.error('Yap2App Execution Error:', err);
   process.exit(1);
 });

package/bridge.js

@@ -9,14 +9,18 @@ import { scanCodebase } from './scanner.js';
 const PORT = process.env.YAP2APP_PORT || 10420;
 const PROJECT_ROOT = process.cwd();
 
-// Bulletproof W3C Private Network Access (PNA) and CORS Headers
-const HEADERS = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Authorization, Access-Control-Request-Private-Network, X-Requested-With',
-  'Access-Control-Allow-Private-Network': 'true',
-  'Content-Type': 'application/json'
-};
+// Bulletproof W3C Private Network Access (PNA) and Dynamic Origin CORS Headers
+function getCorsHeaders(req) {
+  const origin = req?.headers?.origin || '*';
+  return {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS, PUT, DELETE, HEAD',
+    'Access-Control-Allow-Headers': req?.headers?.['access-control-request-headers'] || 'Content-Type, Authorization, Access-Control-Request-Private-Network, X-Requested-With, *',
+    'Access-Control-Allow-Private-Network': 'true',
+    'Access-Control-Max-Age': '86400',
+    'Content-Type': 'application/json'
+  };
+}
 
 /**
  * Computes a lightweight line-by-line diff between original disk file and new content.
@@ -64,16 +68,18 @@ function computeDiff(originalText, newText) {
 }
 
 const server = http.createServer(async (req, res) => {
+  const headers = getCorsHeaders(req);
+
   // 1. Handle Preflight OPTIONS requests (PNA + CORS)
   if (req.method === 'OPTIONS') {
-    res.writeHead(204, HEADERS);
+    res.writeHead(204, headers);
     res.end();
     return;
   }
 
   // 2. Health & Root Info
   if (req.method === 'GET' && (req.url === '/' || req.url === '/health' || req.url === '/api/health')) {
-    res.writeHead(200, HEADERS);
+    res.writeHead(200, headers);
     res.end(JSON.stringify({
       status: 'healthy',
       service: 'Yap2App-Localhost-Bridge',
@@ -90,11 +96,11 @@ const server = http.createServer(async (req, res) => {
     try {
       console.log(`[Yap2App Bridge] 🔍 Scanning shallow codebase context in: ${PROJECT_ROOT}`);
       const context = await scanCodebase(PROJECT_ROOT);
-      res.writeHead(200, HEADERS);
+      res.writeHead(200, headers);
       res.end(JSON.stringify(context));
     } catch (e) {
       console.error('[Yap2App Bridge] Context scan error:', e);
-      res.writeHead(500, HEADERS);
+      res.writeHead(500, headers);
       res.end(JSON.stringify({ error: e.message }));
     }
     return;
@@ -129,7 +135,7 @@ const server = http.createServer(async (req, res) => {
           });
         }
 
-        res.writeHead(200, HEADERS);
+        res.writeHead(200, headers);
         res.end(JSON.stringify({
           success: true,
           files_count: diffResults.length,
@@ -137,7 +143,7 @@ const server = http.createServer(async (req, res) => {
         }));
       } catch (e) {
         console.error('[Yap2App Bridge] Diff error:', e);
-        res.writeHead(500, HEADERS);
+        res.writeHead(500, headers);
         res.end(JSON.stringify({ error: e.message }));
       }
     });
@@ -166,7 +172,7 @@ const server = http.createServer(async (req, res) => {
           written.push(file.path);
         }
 
-        res.writeHead(200, HEADERS);
+        res.writeHead(200, headers);
         res.end(JSON.stringify({
           success: true,
           written_count: written.length,
@@ -176,7 +182,7 @@ const server = http.createServer(async (req, res) => {
         }));
       } catch (e) {
         console.error('[Yap2App Bridge] Write to disk error:', e);
-        res.writeHead(500, HEADERS);
+        res.writeHead(500, headers);
         res.end(JSON.stringify({ error: e.message }));
       }
     });
@@ -184,7 +190,7 @@ const server = http.createServer(async (req, res) => {
   }
 
   // 404 Fallback
-  res.writeHead(404, HEADERS);
+  res.writeHead(404, headers);
   res.end(JSON.stringify({ error: 'Endpoint Not Found' }));
 });
 

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "yap2app",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Autonomous Vibe-to-Prod Localhost Bridge & Model Context Protocol (MCP) Server",
   "main": "bridge.js",
   "type": "module",
   "bin": {
     "yap2app": "./bin/cli.js"
   },
+  "files": [
+    "bin",
+    "bridge.js",
+    "mcp.js",
+    "scanner.js",
+    "v2p.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "start": "node ./bin/cli.js start",
     "bridge": "node ./bin/cli.js bridge",

package/scanner.js

@@ -2,180 +2,420 @@ import fs from 'fs/promises';
 import fsSync from 'fs';
 import path from 'path';
 
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.next',
+  '.nuxt',
+  'dist',
+  'build',
+  'out',
+  '.vscode',
+  '.idea',
+  'venv',
+  '.venv',
+  '__pycache__',
+  '.pytest_cache',
+  'coverage',
+  '.turbo',
+  'wheels'
+]);
+
 /**
- * Shallow Codebase Scanner for Yap2App.
- * Rapidly inspects package.json, tsconfig.json, and component directories
- * to extract project standards, path aliases, and reusable UI primitives.
+ * Universal recursive file walker across project hierarchies up to depth 6.
  */
-export async function scanCodebase(targetDir = process.cwd()) {
-  const projectRoot = path.resolve(targetDir);
-  const projectName = path.basename(projectRoot) || 'local-project';
+async function walkDir(dir, baseDir, maxDepth = 6, currentDepth = 0) {
+  if (currentDepth > maxDepth) return [];
+  let results = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(baseDir, fullPath);
+
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          const sub = await walkDir(fullPath, baseDir, maxDepth, currentDepth + 1);
+          results = results.concat(sub);
+        }
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if ([
+          '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.hbs', '.handlebars',
+          '.html', '.css', '.scss', '.sass', '.less', '.vm', '.ftl', '.jsp', '.php',
+          '.blade.php', '.twig', '.erb', '.liquid', '.astro',
+          '.py', '.go', '.rs', '.java', '.kt', '.rb', '.cs',
+          '.json', '.yaml', '.yml', '.toml', '.xml'
+        ].includes(ext)) {
+          results.push({
+            relative: relativePath,
+            name: entry.name,
+            ext,
+            dir: path.relative(baseDir, dir)
+          });
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore unreadable paths
+  }
+  return results;
+}
+
+/**
+ * Parses package.json safely and returns dependencies dictionary.
+ */
+function parsePackageJson(content) {
+  try {
+    const pkg = JSON.parse(content);
+    return {
+      name: pkg.name,
+      dependencies: pkg.dependencies || {},
+      devDependencies: pkg.devDependencies || {},
+      allDeps: { ...(pkg.devDependencies || {}), ...(pkg.dependencies || {}) }
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deterministic, 100% verified framework detection.
+ * Returns null if no verified signature matches with high confidence.
+ */
+function detectVerifiedFramework(manifests, allFiles, extensionHistogram) {
+  // 1. Google Brightspot / Glue-Bundle
+  if (manifests['louhi.json'] || manifests['_fields.config.json'] || (manifests['package.json'] && manifests['package.json'].includes('google-marketing-bundle-glue'))) {
+    return {
+      framework: 'brightspot_glue',
+      displayName: 'Google Brightspot CMS / Glue-Bundle'
+    };
+  }
+
+  // 2. Node / JS Ecosystem (Exact dependency inspection)
+  if (manifests['package.json']) {
+    const pkg = parsePackageJson(manifests['package.json']);
+    if (pkg && pkg.allDeps) {
+      const deps = pkg.allDeps;
+      if (deps['next']) return { framework: 'nextjs', displayName: `Next.js (${deps['next'].replace(/[\^~]/g, '')})` };
+      if (deps['@angular/core']) return { framework: 'angular', displayName: `Angular (${deps['@angular/core'].replace(/[\^~]/g, '')})` };
+      if (deps['nuxt'] || deps['nuxt3']) return { framework: 'nuxt', displayName: 'Nuxt' };
+      if (deps['vue']) return { framework: 'vue', displayName: `Vue (${deps['vue'].replace(/[\^~]/g, '')})` };
+      if (deps['@sveltejs/kit'] || deps['svelte']) return { framework: 'svelte', displayName: 'Svelte' };
+      if (deps['astro']) return { framework: 'astro', displayName: 'Astro' };
+      if (deps['@remix-run/react']) return { framework: 'remix', displayName: 'Remix' };
+      if (deps['react']) return { framework: 'react', displayName: `React (${deps['react'].replace(/[\^~]/g, '')})` };
+      if (deps['express']) return { framework: 'express', displayName: 'Express.js' };
+      if (deps['hono']) return { framework: 'hono', displayName: 'Hono' };
+      if (deps['fastify']) return { framework: 'fastify', displayName: 'Fastify' };
+    }
+  }
+
+  // 3. Angular project config
+  if (manifests['angular.json']) {
+    return { framework: 'angular', displayName: 'Angular Project' };
+  }
+
+  // 4. Python Ecosystem
+  if (manifests['requirements.txt'] || manifests['pyproject.toml']) {
+    const pyReqs = (manifests['requirements.txt'] || '') + (manifests['pyproject.toml'] || '');
+    if (/django/i.test(pyReqs)) return { framework: 'django', displayName: 'Django' };
+    if (/fastapi/i.test(pyReqs)) return { framework: 'fastapi', displayName: 'FastAPI' };
+    if (/flask/i.test(pyReqs)) return { framework: 'flask', displayName: 'Flask' };
+  }
+
+  // 5. PHP Ecosystem
+  if (manifests['composer.json']) {
+    if (manifests['composer.json'].includes('laravel/framework')) return { framework: 'laravel', displayName: 'Laravel' };
+    if (manifests['composer.json'].includes('symfony/')) return { framework: 'symfony', displayName: 'Symfony' };
+  }
+
+  // 6. Java Ecosystem
+  if (manifests['pom.xml'] || manifests['build.gradle']) {
+    const jContent = (manifests['pom.xml'] || '') + (manifests['build.gradle'] || '');
+    if (jContent.includes('spring-boot')) return { framework: 'spring_boot', displayName: 'Spring Boot' };
+  }
+
+  // If not 100% verified, return null (do NOT guess or display inaccurate tags)
+  return null;
+}
 
-  let dependencies = [];
-  let devDependencies = [];
-  let framework = 'react';
-  let routerType = 'spa';
-  let iconLibrary = 'lucide-react';
-  let stylingSystem = 'tailwindcss';
-  let baseAlias = '@/;';
-  baseAlias = '@/;'.replace(';', ''); // '@/ '
-  let existingComponents = [];
-  let componentNames = [];
-  let designTokens = {
-    primary: '#2563EB',
-    neutral: '#0F172A',
+/**
+ * Extracts design tokens, CSS variables, Tailwind configurations, and color palettes.
+ */
+async function extractDesignTokens(projectRoot, allFiles) {
+  const tokens = {
+    primary: '#1A73E8',
+    neutral: '#202124',
     background: '#FFFFFF',
-    font: 'Plus Jakarta Sans',
-    radius: '0.75rem'
+    colors: {},
+    cssVariables: [],
+    tailwindTheme: null
   };
 
-  // 1. Shallow Scan: package.json
-  try {
-    const pkgPath = path.join(projectRoot, 'package.json');
-    if (fsSync.existsSync(pkgPath)) {
-      const pkgJson = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-      dependencies = Object.keys(pkgJson.dependencies || {});
-      devDependencies = Object.keys(pkgJson.devDependencies || {});
-      const allDeps = new Set([...dependencies, ...devDependencies]);
-
-      // Detect Framework
-      if (allDeps.has('next')) {
-        framework = 'nextjs';
-        const hasAppDir = fsSync.existsSync(path.join(projectRoot, 'app')) || fsSync.existsSync(path.join(projectRoot, 'src', 'app'));
-        routerType = hasAppDir ? 'app_router' : 'pages_router';
-      } else if (allDeps.has('vite')) {
-        framework = 'vite_react';
-        routerType = 'spa';
-      } else if (allDeps.has('@remix-run/react')) {
-        framework = 'remix';
-      } else if (allDeps.has('vue') || allDeps.has('nuxt')) {
-        framework = 'vue';
-      } else if (allDeps.has('svelte') || allDeps.has('@sveltejs/kit')) {
-        framework = 'svelte';
-      }
+  // 1. Inspect Tailwind configuration
+  const tailwindConfigFile = allFiles.find(f => f.name.startsWith('tailwind.config'));
+  if (tailwindConfigFile) {
+    try {
+      const fullP = path.join(projectRoot, tailwindConfigFile.relative);
+      const content = await fs.readFile(fullP, 'utf8');
+      tokens.tailwindTheme = content.slice(0, 1000);
+    } catch {}
+  }
+
+  // 2. Extract CSS/SCSS variables & Hex Palettes
+  const styleFiles = allFiles.filter(f => 
+    ['.css', '.scss', '.less'].includes(f.ext) || 
+    f.name.includes('theme') ||
+    f.name.includes('_colorPalette') ||
+    f.name.includes('variables')
+  ).slice(0, 8);
 
-      // Detect Icons
-      if (allDeps.has('lucide-react')) {
-        iconLibrary = 'lucide-react';
-      } else if (allDeps.has('@heroicons/react')) {
-        iconLibrary = '@heroicons/react';
-      } else if (allDeps.has('@tabler/icons-react')) {
-        iconLibrary = '@tabler/icons-react';
-      } else if (allDeps.has('react-icons')) {
-        iconLibrary = 'react-icons';
+  for (const sf of styleFiles) {
+    try {
+      const fullP = path.join(projectRoot, sf.relative);
+      const content = await fs.readFile(fullP, 'utf8');
+      
+      // Extract CSS custom properties: --color-primary: #... or --bg-...
+      const varMatches = content.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g);
+      for (const m of varMatches) {
+        const varName = m[1].trim();
+        const varVal = m[2].trim();
+        if (tokens.cssVariables.length < 35) {
+          tokens.cssVariables.push({ name: varName, value: varVal });
+        }
+        if (/primary|brand|accent/i.test(varName) && /^#[0-9a-fA-F]{3,8}$/.test(varVal)) {
+          tokens.primary = varVal;
+        }
       }
 
-      // Detect Styling
-      if (allDeps.has('tailwindcss') || allDeps.has('@tailwindcss/vite')) {
-        stylingSystem = 'tailwindcss';
+      // Extract Hex colors
+      const hexMatches = content.matchAll(/#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g);
+      for (const hm of hexMatches) {
+        const hex = hm[0].toUpperCase();
+        tokens.colors[hex] = (tokens.colors[hex] || 0) + 1;
       }
-    }
-  } catch (e) {
-    console.warn('[Yap2App Scanner] package.json scan skipped:', e.message);
+    } catch {}
   }
 
-  // 2. Shallow Scan: tsconfig.json or jsconfig.json (for Path Aliases)
-  try {
-    let tsconfigRaw = null;
-    const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
-    const jsconfigPath = path.join(projectRoot, 'jsconfig.json');
-
-    if (fsSync.existsSync(tsconfigPath)) {
-      tsconfigRaw = await fs.readFile(tsconfigPath, 'utf8');
-    } else if (fsSync.existsSync(jsconfigPath)) {
-      tsconfigRaw = await fs.readFile(jsconfigPath, 'utf8');
+  return tokens;
+}
+
+/**
+ * Extracts UI libraries (Radix, Lucide, Tailwind, MUI) and utility functions (cn, clsx).
+ */
+async function extractUtilitiesAndIcons(projectRoot, allFiles, manifests) {
+  const uiEcosystem = {
+    ui_library: null,
+    icon_library: null,
+    utility_helpers: [],
+    detected_icons: []
+  };
+
+  // Inspect package dependencies
+  if (manifests['package.json']) {
+    const pkg = parsePackageJson(manifests['package.json']);
+    if (pkg && pkg.allDeps) {
+      const deps = pkg.allDeps;
+      if (deps['lucide-react']) uiEcosystem.icon_library = 'lucide-react';
+      else if (deps['@heroicons/react']) uiEcosystem.icon_library = '@heroicons/react';
+      else if (deps['react-icons']) uiEcosystem.icon_library = 'react-icons';
+      else if (deps['@tabler/icons-react']) uiEcosystem.icon_library = '@tabler/icons-react';
+
+      if (deps['@radix-ui/react-dialog'] || deps['@radix-ui/react-slot']) uiEcosystem.ui_library = 'shadcn/ui & Radix UI';
+      else if (deps['@mui/material']) uiEcosystem.ui_library = 'Material UI (MUI)';
+      else if (deps['@chakra-ui/react']) uiEcosystem.ui_library = 'Chakra UI';
+      else if (deps['antd']) uiEcosystem.ui_library = 'Ant Design';
     }
+  }
+
+  // Detect cn/clsx utility files
+  const utilFile = allFiles.find(f => 
+    f.relative.includes('utils') || f.name === 'cn.ts' || f.name === 'cn.js' || f.name === 'utils.ts'
+  );
+  if (utilFile) {
+    uiEcosystem.utility_helpers.push({
+      name: 'cn / classnames helper',
+      path: utilFile.relative
+    });
+  }
+
+  return uiEcosystem;
+}
 
-    if (tsconfigRaw) {
-      const cleaned = tsconfigRaw.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
-      const config = JSON.parse(cleaned);
-      const paths = config.compilerOptions?.paths || {};
+/**
+ * Extracts reusable UI components with their export signatures and interface snippets.
+ */
+async function extractComponentSignatures(projectRoot, allFiles) {
+  const catalog = [];
+  const candidateExtensions = ['.hbs', '.tsx', '.jsx', '.vue', '.svelte', '.vm', '.ftl', '.html'];
+  
+  const componentCandidates = allFiles.filter(file => {
+    const baseName = path.basename(file.name, file.ext);
+    return candidateExtensions.includes(file.ext) &&
+      !baseName.startsWith('_') &&
+      !baseName.includes('.test') &&
+      !baseName.includes('.spec') &&
+      !baseName.includes('.story') &&
+      !['index', 'main', 'app', 'layout'].includes(baseName.toLowerCase());
+  }).slice(0, 45);
+
+  for (const file of componentCandidates) {
+    const baseName = path.basename(file.name, file.ext);
+    try {
+      const fullP = path.join(projectRoot, file.relative);
+      const rawCode = await fs.readFile(fullP, 'utf8');
       
-      const aliasKeys = Object.keys(paths);
-      if (aliasKeys.length > 0) {
-        const primaryKey = aliasKeys.find(k => k.startsWith('@/') || k.startsWith('~/*') || k === '@/*') || aliasKeys[0];
-        baseAlias = primaryKey.replace(/\*$/, '');
+      // Extract Interface/Props or parameters if present
+      let propsSnippet = '';
+      const interfaceMatch = rawCode.match(/(?:interface|type)\s+[\w]+\s*=?\s*\{[\s\S]*?\}/);
+      if (interfaceMatch) {
+        propsSnippet = interfaceMatch[0].slice(0, 350);
       }
+
+      // Extract function signature: export function ComponentName(props: ...)
+      let signatureSnippet = '';
+      const sigMatch = rawCode.match(/export\s+(?:default\s+)?(?:function|const)\s+([A-Z]\w+)[^{]*/);
+      if (sigMatch) {
+        signatureSnippet = sigMatch[0].trim().slice(0, 150);
+      }
+
+      catalog.push({
+        name: baseName,
+        path: file.relative,
+        extension: file.ext,
+        signature: signatureSnippet || null,
+        props: propsSnippet || null
+      });
+    } catch {
+      catalog.push({
+        name: baseName,
+        path: file.relative,
+        extension: file.ext,
+        signature: null,
+        props: null
+      });
     }
-  } catch (e) {
-    console.warn('[Yap2App Scanner] tsconfig scan fallback to default alias (@/):', e.message);
   }
 
-  // 3. Shallow Scan: Component Inventory in standard directories
-  const candidateDirs = [
-    path.join(projectRoot, 'src', 'components', 'ui'),
-    path.join(projectRoot, 'components', 'ui'),
-    path.join(projectRoot, 'src', 'components'),
-    path.join(projectRoot, 'components'),
-    path.join(projectRoot, 'src', 'ui'),
-    path.join(projectRoot, 'ui')
-  ];
+  return catalog;
+}
+
+/**
+ * Extracts tsconfig path aliases (e.g. @/ -> src/).
+ */
+function extractPathAliases(manifests) {
+  if (manifests['tsconfig.json']) {
+    try {
+      const cleaned = manifests['tsconfig.json'].replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+      const parsed = JSON.parse(cleaned);
+      const paths = parsed.compilerOptions?.paths || {};
+      const firstKey = Object.keys(paths)[0];
+      if (firstKey) {
+        return firstKey.replace('*', '');
+      }
+    } catch {}
+  }
+  return '@/;';
+}
+
+/**
+ * AI-Driven Universal Codebase Analyzer for Yap2App.
+ */
+export async function scanCodebase(targetDir = process.cwd()) {
+  const projectRoot = path.resolve(targetDir);
+  const projectName = path.basename(projectRoot) || 'local-project';
+
+  // 1. Traverse actual workspace files
+  const allFiles = await walkDir(projectRoot, projectRoot, 6, 0);
+  const discoveredFiles = allFiles.map(f => f.relative);
+
+  // 2. Compute File Extension Histogram
+  const extensionHistogram = {};
+  for (const f of allFiles) {
+    if (f.ext) {
+      extensionHistogram[f.ext] = (extensionHistogram[f.ext] || 0) + 1;
+    }
+  }
 
-  const foundFiles = new Set();
+  // 3. Extract Manifest Snippets
+  const manifestFiles = [
+    'package.json', 'louhi.json', '_fields.config.json', 'pom.xml', 'build.gradle',
+    'requirements.txt', 'pyproject.toml', 'Gemfile', 'Cargo.toml', 'composer.json',
+    'tsconfig.json', 'angular.json', 'nuxt.config.ts', 'svelte.config.js', 'astro.config.mjs'
+  ];
 
-  for (const dir of candidateDirs) {
-    if (fsSync.existsSync(dir)) {
+  const manifestsFound = {};
+  for (const mf of manifestFiles) {
+    const match = allFiles.find(f => f.name === mf);
+    if (match) {
       try {
-        const files = await fs.readdir(dir);
-        for (const file of files) {
-          if (file.endsWith('.tsx') || file.endsWith('.jsx') || file.endsWith('.vue') || file.endsWith('.svelte')) {
-            const baseName = file.replace(/\.[^/.]+$/, '');
-            if (!foundFiles.has(baseName.toLowerCase()) && !baseName.startsWith('index') && !baseName.includes('.test') && !baseName.includes('.stories')) {
-              foundFiles.add(baseName.toLowerCase());
-              
-              const pascalName = baseName
-                .split(/[-_]/)
-                .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-                .join('');
-              
-              componentNames.push(pascalName);
-              
-              const isUiDir = dir.includes('ui');
-              const relativeImport = isUiDir ? `${baseAlias}components/ui/${baseName}` : `${baseAlias}components/${baseName}`;
-              existingComponents.push(relativeImport);
-            }
-          }
-        }
-      } catch (e) {
-        // Ignore read errors
-      }
+        const fullP = path.join(projectRoot, match.relative);
+        const content = await fs.readFile(fullP, 'utf8');
+        manifestsFound[mf] = content.slice(0, 1500);
+      } catch (e) {}
     }
   }
 
-  // Fallback sensible UI defaults if project has no local UI components yet
-  if (existingComponents.length === 0) {
-    componentNames = ['Button', 'Card', 'Input', 'Badge', 'Dialog', 'Tabs'];
-    existingComponents = [
-      `${baseAlias}components/ui/button`,
-      `${baseAlias}components/ui/card`,
-      `${baseAlias}components/ui/input`,
-      `${baseAlias}components/ui/badge`,
-      `${baseAlias}components/ui/dialog`,
-      `${baseAlias}components/ui/tabs`
-    ];
-  }
-
-  // 4. Custom Architectural Guidelines tailored to detected stack
-  const customGuidelines = `STRICT ENTERPRISE STANDARDS:
-- Re-use detected local UI primitives (${componentNames.slice(0, 8).join(', ')}) from ${baseAlias}components/ui/
-- Use ${iconLibrary} for all icon rendering
-- Target Framework: ${framework.toUpperCase()} (${routerType})
-- Styling: Modern Tailwind CSS with Clean White/Slate enterprise palette
-- Full WCAG 2.2 AAA accessibility compliance (aria-labels, keyboard focus rings, role attributes)
-- Zero-Trust input sanitization (no direct dangerouslySetInnerHTML)`;
+  // 4. Extract Real Code Samples from the User's Workspace for Few-Shot Grounding
+  const codeSamples = [];
+  const candidateSampleExtensions = ['.hbs', '.tsx', '.jsx', '.vue', '.svelte', '.vm', '.ftl', '.jsp', '.html', '.blade.php', '.liquid'];
+  const sampleFiles = allFiles.filter(f => candidateSampleExtensions.includes(f.ext) && !f.name.startsWith('_') && !f.name.includes('.test.')).slice(0, 4);
+
+  for (const sf of sampleFiles) {
+    try {
+      const fullP = path.join(projectRoot, sf.relative);
+      const rawCode = await fs.readFile(fullP, 'utf8');
+      const lines = rawCode.split('\n').slice(0, 50).join('\n');
+      codeSamples.push({
+        file_path: sf.relative,
+        extension: sf.ext,
+        snippet: lines
+      });
+    } catch (e) {}
+  }
+
+  // 5. Deep Catalog of Component Signatures & Primitives
+  const componentSignatures = await extractComponentSignatures(projectRoot, allFiles);
+  const componentNames = componentSignatures.map(c => c.name);
+  const realComponents = componentSignatures.map(c => c.path);
+
+  // 6. Extract Real Design Tokens & Theme Config
+  const designTokens = await extractDesignTokens(projectRoot, allFiles);
+
+  // 7. Extract UI Library Ecosystem & Helpers
+  const uiEcosystem = await extractUtilitiesAndIcons(projectRoot, allFiles, manifestsFound);
+
+  // 8. Deterministic Framework Detection (Strict Verification)
+  const verified = detectVerifiedFramework(manifestsFound, allFiles, extensionHistogram);
+  const inferredFramework = verified ? verified.framework : null;
+  const frameworkDisplayName = verified ? verified.displayName : null;
+
+  // 9. Path Aliases
+  const pathAlias = extractPathAliases(manifestsFound);
+
+  // 10. Extract Routes & Pages
+  const routesDiscovered = allFiles
+    .filter(f => f.relative.includes('pages/') || f.relative.includes('app/') || f.name.startsWith('page.'))
+    .map(f => f.relative)
+    .slice(0, 15);
 
   return {
     project_name: projectName,
     project_root: projectRoot,
-    framework,
-    router_type: routerType,
-    path_alias: baseAlias.endsWith('/') ? baseAlias : baseAlias + '/',
-    dependencies: [...dependencies, ...devDependencies],
-    existing_components: existingComponents,
+    framework: inferredFramework,
+    framework_display_name: frameworkDisplayName,
+    extension_histogram: extensionHistogram,
+    manifests: manifestsFound,
+    codebase_samples: codeSamples,
+    existing_components: realComponents,
+    component_signatures: componentSignatures,
     component_names: componentNames,
-    design_tokens: designTokens,
-    icon_library: iconLibrary,
-    styling_system: stylingSystem,
-    custom_guidelines: customGuidelines
+    ui_ecosystem: uiEcosystem,
+    routes_discovered: routesDiscovered,
+    discovered_files: discoveredFiles.slice(0, 80),
+    total_files_count: discoveredFiles.length,
+    path_alias: pathAlias,
+    design_tokens: designTokens
   };
 }