@polymorphism-tech/morph-spec 4.15.0 → 4.17.0

package/src/lib/generators/architecture-scanner.js

@@ -1,640 +1,640 @@
-/**
- * Architecture Scanner - Generates rich architectural context from project filesystem.
- *
- * Performs fast (<5s) glob-based scanning to produce a snapshot of:
- * - .NET entities (sealed class/record)
- * - API endpoints (IApiEndpoint implementations)
- * - Next.js pages and components
- * - Integrations (from appsettings.json)
- * - Database schema (from EF migrations)
- * - Stack dependencies (.csproj + package.json)
- *
- * All scanning is regex-based (no AST parsing) for speed.
- *
- * @module architecture-scanner
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { existsSync, readFileSync } from 'fs';
-import { renderTemplate } from '../../core/templates/template-renderer.js';
-
-const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', '.worktrees']);
-const MAX_FILES_PER_SCANNER = 200;
-
-/**
- * Recursively walk a directory, returning files matching a filter.
- * Skips known heavy directories for performance.
- *
- * @param {string} dir - Directory to walk
- * @param {function} filter - (relativePath) => boolean
- * @param {string} [base] - Base path for relative calculation
- * @param {number} [limit] - Max files to return
- * @returns {Promise<Array<{abs: string, rel: string}>>}
- */
-async function walkDir(dir, filter, base = dir, limit = MAX_FILES_PER_SCANNER) {
-  const results = [];
-
-  async function recurse(currentDir) {
-    if (results.length >= limit) return;
-
-    let entries;
-    try {
-      entries = await fs.readdir(currentDir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    for (const entry of entries) {
-      if (results.length >= limit) break;
-
-      if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name)) continue;
-        await recurse(path.join(currentDir, entry.name));
-      } else if (entry.isFile()) {
-        const abs = path.join(currentDir, entry.name);
-        const rel = path.relative(base, abs).replace(/\\/g, '/');
-        if (filter(rel, entry.name)) {
-          results.push({ abs, rel });
-        }
-      }
-    }
-  }
-
-  await recurse(dir);
-  return results;
-}
-
-/**
- * Scan .NET entities from Entities/ or Features/ directories.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, type: string, path: string}>>}
- */
-export async function scanEntities(projectPath) {
-  try {
-    const files = await walkDir(
-      projectPath,
-      (rel, name) => name.endsWith('.cs') && (rel.includes('Entities/') || rel.includes('Features/') || rel.includes('Models/'))
-    );
-
-    const entities = [];
-    const entityRegex = /(?:public\s+)?(?:sealed\s+)?(class|record)\s+(\w+)/g;
-
-    for (const file of files) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        let match;
-        entityRegex.lastIndex = 0;
-        while ((match = entityRegex.exec(content)) !== null) {
-          const line = content.slice(Math.max(0, match.index - 80), match.index + match[0].length);
-          // Only capture sealed/record types or classes in entity-like directories
-          if (/sealed|record/.test(line) || file.rel.includes('Entities/')) {
-            entities.push({
-              name: match[2],
-              type: match[1],
-              path: file.rel
-            });
-          }
-        }
-      } catch { /* skip unreadable files */ }
-    }
-
-    return entities;
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Scan API endpoints implementing IApiEndpoint.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, route: string, method: string, path: string}>>}
- */
-export async function scanEndpoints(projectPath) {
-  try {
-    const files = await walkDir(
-      projectPath,
-      (rel, name) => name.endsWith('.cs') && (rel.includes('Endpoints/') || rel.includes('Features/'))
-    );
-
-    const endpoints = [];
-    const classRegex = /class\s+(\w+)[^{]*(?:IApiEndpoint|IEndpoint|Endpoint)/;
-    const routeRegex = /Route\s*(?:=>|=)\s*"([^"]+)"/;
-    const methodRegex = /(?:Http(Get|Post|Put|Delete|Patch))|(?:\.Map(Get|Post|Put|Delete|Patch))/i;
-
-    for (const file of files) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        const classMatch = classRegex.exec(content);
-        if (!classMatch) continue;
-
-        const routeMatch = routeRegex.exec(content);
-        const methodMatch = methodRegex.exec(content);
-
-        endpoints.push({
-          name: classMatch[1],
-          route: routeMatch ? routeMatch[1] : '(unknown)',
-          method: methodMatch ? (methodMatch[1] || methodMatch[2] || '').toUpperCase() : '',
-          path: file.rel
-        });
-      } catch { /* skip */ }
-    }
-
-    return endpoints;
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Scan Next.js pages and components.
- *
- * @param {string} projectPath
- * @returns {Promise<{pages: Array<{route: string, path: string}>, layouts: Array<{path: string}>, components: Array<{name: string, path: string}>}>}
- */
-export async function scanNextjsComponents(projectPath) {
-  try {
-    const result = { pages: [], layouts: [], components: [] };
-
-    // Scan pages and layouts from app directory
-    const appFiles = await walkDir(
-      projectPath,
-      (rel, name) =>
-        (name === 'page.tsx' || name === 'page.jsx' || name === 'layout.tsx' || name === 'layout.jsx') &&
-        (rel.startsWith('app/') || rel.startsWith('src/app/'))
-    );
-
-    for (const file of appFiles) {
-      const isLayout = file.rel.includes('layout.');
-      const routeDir = path.dirname(file.rel).replace(/^(?:src\/)?app/, '').replace(/\\/g, '/');
-      const route = routeDir || '/';
-
-      if (isLayout) {
-        result.layouts.push({ path: file.rel });
-      } else {
-        result.pages.push({ route: route === '' ? '/' : route, path: file.rel });
-      }
-    }
-
-    // Scan components
-    const componentFiles = await walkDir(
-      projectPath,
-      (rel, name) =>
-        (name.endsWith('.tsx') || name.endsWith('.jsx')) &&
-        (rel.startsWith('src/components/') || rel.startsWith('components/') || rel.includes('/components/'))
-    );
-
-    for (const file of componentFiles) {
-      const name = path.basename(file.rel, path.extname(file.rel));
-      // Skip index files and test files
-      if (name === 'index' || name.includes('.test') || name.includes('.spec')) continue;
-      result.components.push({ name, path: file.rel });
-    }
-
-    return result;
-  } catch {
-    return { pages: [], layouts: [], components: [] };
-  }
-}
-
-/**
- * Scan integrations from appsettings*.json files.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, type: string, configured: boolean}>>}
- */
-export async function scanIntegrations(projectPath) {
-  try {
-    const files = await walkDir(
-      projectPath,
-      (rel, name) => /^appsettings(?:\.\w+)?\.json$/.test(name),
-      projectPath,
-      20
-    );
-
-    // Also check .env files for common integrations
-    const envFiles = await walkDir(
-      projectPath,
-      (rel, name) => name === '.env' || name === '.env.local' || name === '.env.production',
-      projectPath,
-      5
-    );
-
-    const knownServices = {
-      'Clerk': 'auth',
-      'AsaaS': 'payment',
-      'Resend': 'email',
-      'Hangfire': 'background-jobs',
-      'Supabase': 'database/auth',
-      'ConnectionStrings': 'database',
-      'Redis': 'cache',
-      'SendGrid': 'email',
-      'Stripe': 'payment',
-      'AzureAd': 'auth',
-      'OpenAI': 'ai',
-      'AzureOpenAI': 'ai'
-    };
-
-    const detected = new Map();
-
-    // Scan appsettings files
-    for (const file of files) {
-      try {
-        const content = JSON.parse(await fs.readFile(file.abs, 'utf8'));
-        for (const [service, type] of Object.entries(knownServices)) {
-          if (content[service] || content[service.toLowerCase()]) {
-            const hasValues = content[service] && typeof content[service] === 'object'
-              ? Object.values(content[service]).some(v => v && v !== '' && !String(v).startsWith('{{'))
-              : true;
-            if (!detected.has(service) || hasValues) {
-              detected.set(service, { name: service, type, configured: hasValues });
-            }
-          }
-        }
-        // Check ConnectionStrings specifically
-        if (content.ConnectionStrings) {
-          for (const [key, val] of Object.entries(content.ConnectionStrings)) {
-            if (val && !String(val).startsWith('{{')) {
-              detected.set(`DB:${key}`, { name: `ConnectionString:${key}`, type: 'database', configured: true });
-            }
-          }
-        }
-      } catch { /* skip invalid JSON */ }
-    }
-
-    // Scan .env files for known prefixes
-    const envPrefixes = {
-      'NEXT_PUBLIC_CLERK': 'Clerk',
-      'CLERK_': 'Clerk',
-      'NEXT_PUBLIC_SUPABASE': 'Supabase',
-      'SUPABASE_': 'Supabase',
-      'RESEND_': 'Resend',
-      'STRIPE_': 'Stripe',
-      'OPENAI_': 'OpenAI',
-      'ASAAS_': 'AsaaS'
-    };
-
-    for (const file of envFiles) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        for (const [prefix, service] of Object.entries(envPrefixes)) {
-          if (content.includes(prefix)) {
-            const type = knownServices[service] || 'integration';
-            if (!detected.has(service)) {
-              detected.set(service, { name: service, type, configured: true });
-            }
-          }
-        }
-      } catch { /* skip */ }
-    }
-
-    return Array.from(detected.values());
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Scan database schema from EF Core migrations.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{table: string, migration: string}>>}
- */
-export async function scanDatabaseSchema(projectPath) {
-  try {
-    const files = await walkDir(
-      projectPath,
-      (rel, name) => name.endsWith('.cs') && rel.includes('Migrations/') && !name.endsWith('.Designer.cs'),
-      projectPath,
-      100
-    );
-
-    const tables = new Map();
-    const toTableRegex = /\.ToTable\("(\w+)"/g;
-    const createTableRegex = /migrationBuilder\.CreateTable\(\s*name:\s*"(\w+)"/g;
-
-    for (const file of files) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        const migrationName = path.basename(file.rel, '.cs');
-
-        for (const regex of [toTableRegex, createTableRegex]) {
-          regex.lastIndex = 0;
-          let match;
-          while ((match = regex.exec(content)) !== null) {
-            if (!tables.has(match[1])) {
-              tables.set(match[1], { table: match[1], migration: migrationName });
-            }
-          }
-        }
-      } catch { /* skip */ }
-    }
-
-    // Also scan Supabase migrations (SQL)
-    const sqlFiles = await walkDir(
-      projectPath,
-      (rel, name) => name.endsWith('.sql') && (rel.includes('migrations/') || rel.includes('supabase/migrations/')),
-      projectPath,
-      100
-    );
-
-    const createSqlRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?/gi;
-
-    for (const file of sqlFiles) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        const migrationName = path.basename(file.rel, '.sql');
-        createSqlRegex.lastIndex = 0;
-        let match;
-        while ((match = createSqlRegex.exec(content)) !== null) {
-          if (!tables.has(match[1])) {
-            tables.set(match[1], { table: match[1], migration: migrationName });
-          }
-        }
-      } catch { /* skip */ }
-    }
-
-    return Array.from(tables.values());
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Detect stack from .csproj PackageReference and package.json dependencies.
- *
- * @param {string} projectPath
- * @returns {Promise<{dotnet: Array<{name: string, version: string}>, npm: Array<{name: string, version: string}>}>}
- */
-export async function scanStackDependencies(projectPath) {
-  try {
-    const result = { dotnet: [], npm: [] };
-
-    // Scan .csproj files
-    const csprojFiles = await walkDir(
-      projectPath,
-      (rel, name) => name.endsWith('.csproj'),
-      projectPath,
-      10
-    );
-
-    const packageRefRegex = /<PackageReference\s+Include="([^"]+)"\s+Version="([^"]+)"/g;
-
-    for (const file of csprojFiles) {
-      try {
-        const content = await fs.readFile(file.abs, 'utf8');
-        packageRefRegex.lastIndex = 0;
-        let match;
-        while ((match = packageRefRegex.exec(content)) !== null) {
-          result.dotnet.push({ name: match[1], version: match[2] });
-        }
-      } catch { /* skip */ }
-    }
-
-    // Scan package.json (root only)
-    const pkgPath = path.join(projectPath, 'package.json');
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-        for (const [name, version] of Object.entries(allDeps)) {
-          result.npm.push({ name, version: String(version) });
-        }
-      } catch { /* skip */ }
-    }
-
-    // Also check web/ or frontend/ subdirectory package.json
-    for (const subdir of ['web', 'frontend', 'client', 'src']) {
-      const subPkgPath = path.join(projectPath, subdir, 'package.json');
-      if (existsSync(subPkgPath)) {
-        try {
-          const pkg = JSON.parse(await fs.readFile(subPkgPath, 'utf8'));
-          const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-          for (const [name, version] of Object.entries(allDeps)) {
-            // Avoid duplicates
-            if (!result.npm.some(d => d.name === name)) {
-              result.npm.push({ name, version: String(version) });
-            }
-          }
-        } catch { /* skip */ }
-      }
-    }
-
-    return result;
-  } catch {
-    return { dotnet: [], npm: [] };
-  }
-}
-
-/**
- * Master scan — runs all scanners in parallel.
- *
- * @param {string} projectPath
- * @returns {Promise<Object>} ArchitectureScanResult
- */
-export async function scanArchitecture(projectPath) {
-  const [entities, endpoints, nextjs, integrations, database, stack] = await Promise.all([
-    scanEntities(projectPath),
-    scanEndpoints(projectPath),
-    scanNextjsComponents(projectPath),
-    scanIntegrations(projectPath),
-    scanDatabaseSchema(projectPath),
-    scanStackDependencies(projectPath)
-  ]);
-
-  return {
-    timestamp: new Date().toISOString(),
-    entities,
-    endpoints,
-    nextjs,
-    integrations,
-    database,
-    stack
-  };
-}
-
-/**
- * Resolve a template path: check .morph/framework/templates/ first, then framework/templates/,
- * then fall back to the CLI package's own framework/templates/.
- *
- * @param {string} projectPath
- * @param {string} templateRelPath
- * @returns {string|null}
- */
-function resolveTemplatePath(projectPath, templateRelPath) {
-  // 1. Project-local override
-  const projectLocal = path.join(projectPath, '.morph/framework/templates', templateRelPath);
-  if (existsSync(projectLocal)) return projectLocal;
-
-  // 2. CLI package framework/ (for running from source or during init)
-  const cliFramework = path.join(
-    path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
-    '..', '..', '..', 'framework', 'templates', templateRelPath
-  );
-  if (existsSync(cliFramework)) return cliFramework;
-
-  return null;
-}
-
-/**
- * Render architecture context to .morph/context/README.md
- *
- * @param {string} projectPath
- * @param {Object} scanResult - Result from scanArchitecture()
- * @param {Object} [options]
- * @param {string} [options.projectName] - Override project name
- * @returns {Promise<string>} Path to written file
- */
-export async function renderArchitectureContext(projectPath, scanResult, options = {}) {
-  const templatePath = resolveTemplatePath(projectPath, 'context/ARCHITECTURE.md');
-
-  // Determine project name
-  let projectName = options.projectName;
-  if (!projectName) {
-    // Try config.json
-    const configPath = path.join(projectPath, '.morph/config/config.json');
-    if (existsSync(configPath)) {
-      try {
-        const config = JSON.parse(readFileSync(configPath, 'utf8'));
-        projectName = config.project?.name;
-      } catch { /* ignore */ }
-    }
-    // Fallback to directory name
-    if (!projectName) {
-      projectName = path.basename(projectPath);
-    }
-  }
-
-  // Get morph-spec version
-  let morphVersion = 'unknown';
-  try {
-    const pkgPath = path.join(
-      path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
-      '..', '..', '..', 'package.json'
-    );
-    if (existsSync(pkgPath)) {
-      morphVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
-    }
-  } catch { /* ignore */ }
-
-  const variables = {
-    projectName,
-    timestamp: new Date().toISOString().replace('T', ' ').split('.')[0],
-    morphVersion,
-    // Entities
-    hasDotnet: scanResult.entities.length > 0 || scanResult.endpoints.length > 0,
-    entities: scanResult.entities,
-    entityCount: scanResult.entities.length,
-    endpoints: scanResult.endpoints,
-    endpointCount: scanResult.endpoints.length,
-    // Next.js
-    hasNextjs: scanResult.nextjs.pages.length > 0 || scanResult.nextjs.components.length > 0,
-    pages: scanResult.nextjs.pages,
-    pageCount: scanResult.nextjs.pages.length,
-    layouts: scanResult.nextjs.layouts,
-    components: scanResult.nextjs.components,
-    componentCount: scanResult.nextjs.components.length,
-    // Integrations
-    hasIntegrations: scanResult.integrations.length > 0,
-    integrations: scanResult.integrations,
-    // Database
-    hasTables: scanResult.database.length > 0,
-    tables: scanResult.database,
-    tableCount: scanResult.database.length,
-    // Stack
-    hasDotnetPackages: scanResult.stack.dotnet.length > 0,
-    dotnetPackages: scanResult.stack.dotnet,
-    hasNpmPackages: scanResult.stack.npm.length > 0,
-    npmPackages: scanResult.stack.npm
-  };
-
-  let content;
-  if (templatePath) {
-    content = renderTemplate(templatePath, variables);
-  } else {
-    // Fallback: generate minimal markdown without template
-    content = generateFallbackMarkdown(variables);
-  }
-
-  // Write to .morph/context/README.md
-  const contextDir = path.join(projectPath, '.morph/context');
-  await fs.mkdir(contextDir, { recursive: true });
-  const outputPath = path.join(contextDir, 'README.md');
-  await fs.writeFile(outputPath, content, 'utf8');
-
-  return outputPath;
-}
-
-/**
- * Generate minimal markdown when template is not available.
- * @param {Object} vars
- * @returns {string}
- */
-function generateFallbackMarkdown(vars) {
-  const lines = [`# ${vars.projectName} — Architecture Context\n`];
-  lines.push(`> Auto-generated by morph-spec context refresh`);
-  lines.push(`> Last updated: ${vars.timestamp}\n`);
-
-  if (vars.hasDotnet) {
-    lines.push('## .NET Entities\n');
-    for (const e of vars.entities) {
-      lines.push(`- \`${e.name}\` (${e.type}) — ${e.path}`);
-    }
-    lines.push('\n## API Endpoints\n');
-    for (const ep of vars.endpoints) {
-      lines.push(`- ${ep.method ? ep.method + ' ' : ''}\`${ep.route}\` — ${ep.name} (${ep.path})`);
-    }
-    lines.push('');
-  }
-
-  if (vars.hasNextjs) {
-    lines.push('## Next.js Pages\n');
-    for (const p of vars.pages) {
-      lines.push(`- \`${p.route}\` — ${p.path}`);
-    }
-    if (vars.components.length > 0) {
-      lines.push('\n## Components\n');
-      for (const c of vars.components) {
-        lines.push(`- \`${c.name}\` — ${c.path}`);
-      }
-    }
-    lines.push('');
-  }
-
-  if (vars.hasIntegrations) {
-    lines.push('## Integrations\n');
-    for (const i of vars.integrations) {
-      lines.push(`- **${i.name}** (${i.type}) — ${i.configured ? 'configured' : 'not configured'}`);
-    }
-    lines.push('');
-  }
-
-  if (vars.hasTables) {
-    lines.push('## Database Tables\n');
-    for (const t of vars.tables) {
-      lines.push(`- \`${t.table}\` (from ${t.migration})`);
-    }
-    lines.push('');
-  }
-
-  if (vars.hasDotnetPackages) {
-    lines.push('## .NET Packages\n');
-    for (const p of vars.dotnetPackages) {
-      lines.push(`- \`${p.name}\` ${p.version}`);
-    }
-    lines.push('');
-  }
-
-  if (vars.hasNpmPackages) {
-    lines.push('## NPM Packages\n');
-    for (const p of vars.npmPackages) {
-      lines.push(`- \`${p.name}\` ${p.version}`);
-    }
-    lines.push('');
-  }
-
-  lines.push(`---\n*Generated by morph-spec v${vars.morphVersion}*`);
-  return lines.join('\n');
-}
+/**
+ * Architecture Scanner - Generates rich architectural context from project filesystem.
+ *
+ * Performs fast (<5s) glob-based scanning to produce a snapshot of:
+ * - .NET entities (sealed class/record)
+ * - API endpoints (IApiEndpoint implementations)
+ * - Next.js pages and components
+ * - Integrations (from appsettings.json)
+ * - Database schema (from EF migrations)
+ * - Stack dependencies (.csproj + package.json)
+ *
+ * All scanning is regex-based (no AST parsing) for speed.
+ *
+ * @module architecture-scanner
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { renderTemplate } from '../../core/templates/template-renderer.js';
+
+const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', '.worktrees']);
+const MAX_FILES_PER_SCANNER = 200;
+
+/**
+ * Recursively walk a directory, returning files matching a filter.
+ * Skips known heavy directories for performance.
+ *
+ * @param {string} dir - Directory to walk
+ * @param {function} filter - (relativePath) => boolean
+ * @param {string} [base] - Base path for relative calculation
+ * @param {number} [limit] - Max files to return
+ * @returns {Promise<Array<{abs: string, rel: string}>>}
+ */
+async function walkDir(dir, filter, base = dir, limit = MAX_FILES_PER_SCANNER) {
+  const results = [];
+
+  async function recurse(currentDir) {
+    if (results.length >= limit) return;
+
+    let entries;
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (results.length >= limit) break;
+
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await recurse(path.join(currentDir, entry.name));
+      } else if (entry.isFile()) {
+        const abs = path.join(currentDir, entry.name);
+        const rel = path.relative(base, abs).replace(/\\/g, '/');
+        if (filter(rel, entry.name)) {
+          results.push({ abs, rel });
+        }
+      }
+    }
+  }
+
+  await recurse(dir);
+  return results;
+}
+
+/**
+ * Scan .NET entities from Entities/ or Features/ directories.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<Array<{name: string, type: string, path: string}>>}
+ */
+export async function scanEntities(projectPath) {
+  try {
+    const files = await walkDir(
+      projectPath,
+      (rel, name) => name.endsWith('.cs') && (rel.includes('Entities/') || rel.includes('Features/') || rel.includes('Models/'))
+    );
+
+    const entities = [];
+    const entityRegex = /(?:public\s+)?(?:sealed\s+)?(class|record)\s+(\w+)/g;
+
+    for (const file of files) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        let match;
+        entityRegex.lastIndex = 0;
+        while ((match = entityRegex.exec(content)) !== null) {
+          const line = content.slice(Math.max(0, match.index - 80), match.index + match[0].length);
+          // Only capture sealed/record types or classes in entity-like directories
+          if (/sealed|record/.test(line) || file.rel.includes('Entities/')) {
+            entities.push({
+              name: match[2],
+              type: match[1],
+              path: file.rel
+            });
+          }
+        }
+      } catch { /* skip unreadable files */ }
+    }
+
+    return entities;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan API endpoints implementing IApiEndpoint.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<Array<{name: string, route: string, method: string, path: string}>>}
+ */
+export async function scanEndpoints(projectPath) {
+  try {
+    const files = await walkDir(
+      projectPath,
+      (rel, name) => name.endsWith('.cs') && (rel.includes('Endpoints/') || rel.includes('Features/'))
+    );
+
+    const endpoints = [];
+    const classRegex = /class\s+(\w+)[^{]*(?:IApiEndpoint|IEndpoint|Endpoint)/;
+    const routeRegex = /Route\s*(?:=>|=)\s*"([^"]+)"/;
+    const methodRegex = /(?:Http(Get|Post|Put|Delete|Patch))|(?:\.Map(Get|Post|Put|Delete|Patch))/i;
+
+    for (const file of files) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        const classMatch = classRegex.exec(content);
+        if (!classMatch) continue;
+
+        const routeMatch = routeRegex.exec(content);
+        const methodMatch = methodRegex.exec(content);
+
+        endpoints.push({
+          name: classMatch[1],
+          route: routeMatch ? routeMatch[1] : '(unknown)',
+          method: methodMatch ? (methodMatch[1] || methodMatch[2] || '').toUpperCase() : '',
+          path: file.rel
+        });
+      } catch { /* skip */ }
+    }
+
+    return endpoints;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan Next.js pages and components.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<{pages: Array<{route: string, path: string}>, layouts: Array<{path: string}>, components: Array<{name: string, path: string}>}>}
+ */
+export async function scanNextjsComponents(projectPath) {
+  try {
+    const result = { pages: [], layouts: [], components: [] };
+
+    // Scan pages and layouts from app directory
+    const appFiles = await walkDir(
+      projectPath,
+      (rel, name) =>
+        (name === 'page.tsx' || name === 'page.jsx' || name === 'layout.tsx' || name === 'layout.jsx') &&
+        (rel.startsWith('app/') || rel.startsWith('src/app/'))
+    );
+
+    for (const file of appFiles) {
+      const isLayout = file.rel.includes('layout.');
+      const routeDir = path.dirname(file.rel).replace(/^(?:src\/)?app/, '').replace(/\\/g, '/');
+      const route = routeDir || '/';
+
+      if (isLayout) {
+        result.layouts.push({ path: file.rel });
+      } else {
+        result.pages.push({ route: route === '' ? '/' : route, path: file.rel });
+      }
+    }
+
+    // Scan components
+    const componentFiles = await walkDir(
+      projectPath,
+      (rel, name) =>
+        (name.endsWith('.tsx') || name.endsWith('.jsx')) &&
+        (rel.startsWith('src/components/') || rel.startsWith('components/') || rel.includes('/components/'))
+    );
+
+    for (const file of componentFiles) {
+      const name = path.basename(file.rel, path.extname(file.rel));
+      // Skip index files and test files
+      if (name === 'index' || name.includes('.test') || name.includes('.spec')) continue;
+      result.components.push({ name, path: file.rel });
+    }
+
+    return result;
+  } catch {
+    return { pages: [], layouts: [], components: [] };
+  }
+}
+
+/**
+ * Scan integrations from appsettings*.json files.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<Array<{name: string, type: string, configured: boolean}>>}
+ */
+export async function scanIntegrations(projectPath) {
+  try {
+    const files = await walkDir(
+      projectPath,
+      (rel, name) => /^appsettings(?:\.\w+)?\.json$/.test(name),
+      projectPath,
+      20
+    );
+
+    // Also check .env files for common integrations
+    const envFiles = await walkDir(
+      projectPath,
+      (rel, name) => name === '.env' || name === '.env.local' || name === '.env.production',
+      projectPath,
+      5
+    );
+
+    const knownServices = {
+      'Clerk': 'auth',
+      'AsaaS': 'payment',
+      'Resend': 'email',
+      'Hangfire': 'background-jobs',
+      'Neon': 'database',
+      'ConnectionStrings': 'database',
+      'Redis': 'cache',
+      'SendGrid': 'email',
+      'Stripe': 'payment',
+      'AzureAd': 'auth',
+      'OpenAI': 'ai',
+      'AzureOpenAI': 'ai'
+    };
+
+    const detected = new Map();
+
+    // Scan appsettings files
+    for (const file of files) {
+      try {
+        const content = JSON.parse(await fs.readFile(file.abs, 'utf8'));
+        for (const [service, type] of Object.entries(knownServices)) {
+          if (content[service] || content[service.toLowerCase()]) {
+            const hasValues = content[service] && typeof content[service] === 'object'
+              ? Object.values(content[service]).some(v => v && v !== '' && !String(v).startsWith('{{'))
+              : true;
+            if (!detected.has(service) || hasValues) {
+              detected.set(service, { name: service, type, configured: hasValues });
+            }
+          }
+        }
+        // Check ConnectionStrings specifically
+        if (content.ConnectionStrings) {
+          for (const [key, val] of Object.entries(content.ConnectionStrings)) {
+            if (val && !String(val).startsWith('{{')) {
+              detected.set(`DB:${key}`, { name: `ConnectionString:${key}`, type: 'database', configured: true });
+            }
+          }
+        }
+      } catch { /* skip invalid JSON */ }
+    }
+
+    // Scan .env files for known prefixes
+    const envPrefixes = {
+      'NEXT_PUBLIC_CLERK': 'Clerk',
+      'CLERK_': 'Clerk',
+      'DATABASE_URL': 'Neon',
+      'NEON_': 'Neon',
+      'RESEND_': 'Resend',
+      'STRIPE_': 'Stripe',
+      'OPENAI_': 'OpenAI',
+      'ASAAS_': 'AsaaS'
+    };
+
+    for (const file of envFiles) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        for (const [prefix, service] of Object.entries(envPrefixes)) {
+          if (content.includes(prefix)) {
+            const type = knownServices[service] || 'integration';
+            if (!detected.has(service)) {
+              detected.set(service, { name: service, type, configured: true });
+            }
+          }
+        }
+      } catch { /* skip */ }
+    }
+
+    return Array.from(detected.values());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan database schema from EF Core migrations.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<Array<{table: string, migration: string}>>}
+ */
+export async function scanDatabaseSchema(projectPath) {
+  try {
+    const files = await walkDir(
+      projectPath,
+      (rel, name) => name.endsWith('.cs') && rel.includes('Migrations/') && !name.endsWith('.Designer.cs'),
+      projectPath,
+      100
+    );
+
+    const tables = new Map();
+    const toTableRegex = /\.ToTable\("(\w+)"/g;
+    const createTableRegex = /migrationBuilder\.CreateTable\(\s*name:\s*"(\w+)"/g;
+
+    for (const file of files) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        const migrationName = path.basename(file.rel, '.cs');
+
+        for (const regex of [toTableRegex, createTableRegex]) {
+          regex.lastIndex = 0;
+          let match;
+          while ((match = regex.exec(content)) !== null) {
+            if (!tables.has(match[1])) {
+              tables.set(match[1], { table: match[1], migration: migrationName });
+            }
+          }
+        }
+      } catch { /* skip */ }
+    }
+
+    // Also scan database migrations (SQL)
+    const sqlFiles = await walkDir(
+      projectPath,
+      (rel, name) => name.endsWith('.sql') && rel.includes('migrations/'),
+      projectPath,
+      100
+    );
+
+    const createSqlRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:public\.)?["']?(\w+)["']?/gi;
+
+    for (const file of sqlFiles) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        const migrationName = path.basename(file.rel, '.sql');
+        createSqlRegex.lastIndex = 0;
+        let match;
+        while ((match = createSqlRegex.exec(content)) !== null) {
+          if (!tables.has(match[1])) {
+            tables.set(match[1], { table: match[1], migration: migrationName });
+          }
+        }
+      } catch { /* skip */ }
+    }
+
+    return Array.from(tables.values());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Detect stack from .csproj PackageReference and package.json dependencies.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<{dotnet: Array<{name: string, version: string}>, npm: Array<{name: string, version: string}>}>}
+ */
+export async function scanStackDependencies(projectPath) {
+  try {
+    const result = { dotnet: [], npm: [] };
+
+    // Scan .csproj files
+    const csprojFiles = await walkDir(
+      projectPath,
+      (rel, name) => name.endsWith('.csproj'),
+      projectPath,
+      10
+    );
+
+    const packageRefRegex = /<PackageReference\s+Include="([^"]+)"\s+Version="([^"]+)"/g;
+
+    for (const file of csprojFiles) {
+      try {
+        const content = await fs.readFile(file.abs, 'utf8');
+        packageRefRegex.lastIndex = 0;
+        let match;
+        while ((match = packageRefRegex.exec(content)) !== null) {
+          result.dotnet.push({ name: match[1], version: match[2] });
+        }
+      } catch { /* skip */ }
+    }
+
+    // Scan package.json (root only)
+    const pkgPath = path.join(projectPath, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [name, version] of Object.entries(allDeps)) {
+          result.npm.push({ name, version: String(version) });
+        }
+      } catch { /* skip */ }
+    }
+
+    // Also check web/ or frontend/ subdirectory package.json
+    for (const subdir of ['web', 'frontend', 'client', 'src']) {
+      const subPkgPath = path.join(projectPath, subdir, 'package.json');
+      if (existsSync(subPkgPath)) {
+        try {
+          const pkg = JSON.parse(await fs.readFile(subPkgPath, 'utf8'));
+          const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+          for (const [name, version] of Object.entries(allDeps)) {
+            // Avoid duplicates
+            if (!result.npm.some(d => d.name === name)) {
+              result.npm.push({ name, version: String(version) });
+            }
+          }
+        } catch { /* skip */ }
+      }
+    }
+
+    return result;
+  } catch {
+    return { dotnet: [], npm: [] };
+  }
+}
+
+/**
+ * Master scan — runs all scanners in parallel.
+ *
+ * @param {string} projectPath
+ * @returns {Promise<Object>} ArchitectureScanResult
+ */
+export async function scanArchitecture(projectPath) {
+  const [entities, endpoints, nextjs, integrations, database, stack] = await Promise.all([
+    scanEntities(projectPath),
+    scanEndpoints(projectPath),
+    scanNextjsComponents(projectPath),
+    scanIntegrations(projectPath),
+    scanDatabaseSchema(projectPath),
+    scanStackDependencies(projectPath)
+  ]);
+
+  return {
+    timestamp: new Date().toISOString(),
+    entities,
+    endpoints,
+    nextjs,
+    integrations,
+    database,
+    stack
+  };
+}
+
+/**
+ * Resolve a template path: check .morph/framework/templates/ first, then framework/templates/,
+ * then fall back to the CLI package's own framework/templates/.
+ *
+ * @param {string} projectPath
+ * @param {string} templateRelPath
+ * @returns {string|null}
+ */
+function resolveTemplatePath(projectPath, templateRelPath) {
+  // 1. Project-local override
+  const projectLocal = path.join(projectPath, '.morph/framework/templates', templateRelPath);
+  if (existsSync(projectLocal)) return projectLocal;
+
+  // 2. CLI package framework/ (for running from source or during init)
+  const cliFramework = path.join(
+    path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
+    '..', '..', '..', 'framework', 'templates', templateRelPath
+  );
+  if (existsSync(cliFramework)) return cliFramework;
+
+  return null;
+}
+
+/**
+ * Render architecture context to .morph/context/README.md
+ *
+ * @param {string} projectPath
+ * @param {Object} scanResult - Result from scanArchitecture()
+ * @param {Object} [options]
+ * @param {string} [options.projectName] - Override project name
+ * @returns {Promise<string>} Path to written file
+ */
+export async function renderArchitectureContext(projectPath, scanResult, options = {}) {
+  const templatePath = resolveTemplatePath(projectPath, 'context/ARCHITECTURE.md');
+
+  // Determine project name
+  let projectName = options.projectName;
+  if (!projectName) {
+    // Try config.json
+    const configPath = path.join(projectPath, '.morph/config/config.json');
+    if (existsSync(configPath)) {
+      try {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        projectName = config.project?.name;
+      } catch { /* ignore */ }
+    }
+    // Fallback to directory name
+    if (!projectName) {
+      projectName = path.basename(projectPath);
+    }
+  }
+
+  // Get morph-spec version
+  let morphVersion = 'unknown';
+  try {
+    const pkgPath = path.join(
+      path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')),
+      '..', '..', '..', 'package.json'
+    );
+    if (existsSync(pkgPath)) {
+      morphVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+    }
+  } catch { /* ignore */ }
+
+  const variables = {
+    projectName,
+    timestamp: new Date().toISOString().replace('T', ' ').split('.')[0],
+    morphVersion,
+    // Entities
+    hasDotnet: scanResult.entities.length > 0 || scanResult.endpoints.length > 0,
+    entities: scanResult.entities,
+    entityCount: scanResult.entities.length,
+    endpoints: scanResult.endpoints,
+    endpointCount: scanResult.endpoints.length,
+    // Next.js
+    hasNextjs: scanResult.nextjs.pages.length > 0 || scanResult.nextjs.components.length > 0,
+    pages: scanResult.nextjs.pages,
+    pageCount: scanResult.nextjs.pages.length,
+    layouts: scanResult.nextjs.layouts,
+    components: scanResult.nextjs.components,
+    componentCount: scanResult.nextjs.components.length,
+    // Integrations
+    hasIntegrations: scanResult.integrations.length > 0,
+    integrations: scanResult.integrations,
+    // Database
+    hasTables: scanResult.database.length > 0,
+    tables: scanResult.database,
+    tableCount: scanResult.database.length,
+    // Stack
+    hasDotnetPackages: scanResult.stack.dotnet.length > 0,
+    dotnetPackages: scanResult.stack.dotnet,
+    hasNpmPackages: scanResult.stack.npm.length > 0,
+    npmPackages: scanResult.stack.npm
+  };
+
+  let content;
+  if (templatePath) {
+    content = renderTemplate(templatePath, variables);
+  } else {
+    // Fallback: generate minimal markdown without template
+    content = generateFallbackMarkdown(variables);
+  }
+
+  // Write to .morph/context/README.md
+  const contextDir = path.join(projectPath, '.morph/context');
+  await fs.mkdir(contextDir, { recursive: true });
+  const outputPath = path.join(contextDir, 'README.md');
+  await fs.writeFile(outputPath, content, 'utf8');
+
+  return outputPath;
+}
+
+/**
+ * Generate minimal markdown when template is not available.
+ * @param {Object} vars
+ * @returns {string}
+ */
+function generateFallbackMarkdown(vars) {
+  const lines = [`# ${vars.projectName} — Architecture Context\n`];
+  lines.push(`> Auto-generated by morph-spec context refresh`);
+  lines.push(`> Last updated: ${vars.timestamp}\n`);
+
+  if (vars.hasDotnet) {
+    lines.push('## .NET Entities\n');
+    for (const e of vars.entities) {
+      lines.push(`- \`${e.name}\` (${e.type}) — ${e.path}`);
+    }
+    lines.push('\n## API Endpoints\n');
+    for (const ep of vars.endpoints) {
+      lines.push(`- ${ep.method ? ep.method + ' ' : ''}\`${ep.route}\` — ${ep.name} (${ep.path})`);
+    }
+    lines.push('');
+  }
+
+  if (vars.hasNextjs) {
+    lines.push('## Next.js Pages\n');
+    for (const p of vars.pages) {
+      lines.push(`- \`${p.route}\` — ${p.path}`);
+    }
+    if (vars.components.length > 0) {
+      lines.push('\n## Components\n');
+      for (const c of vars.components) {
+        lines.push(`- \`${c.name}\` — ${c.path}`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (vars.hasIntegrations) {
+    lines.push('## Integrations\n');
+    for (const i of vars.integrations) {
+      lines.push(`- **${i.name}** (${i.type}) — ${i.configured ? 'configured' : 'not configured'}`);
+    }
+    lines.push('');
+  }
+
+  if (vars.hasTables) {
+    lines.push('## Database Tables\n');
+    for (const t of vars.tables) {
+      lines.push(`- \`${t.table}\` (from ${t.migration})`);
+    }
+    lines.push('');
+  }
+
+  if (vars.hasDotnetPackages) {
+    lines.push('## .NET Packages\n');
+    for (const p of vars.dotnetPackages) {
+      lines.push(`- \`${p.name}\` ${p.version}`);
+    }
+    lines.push('');
+  }
+
+  if (vars.hasNpmPackages) {
+    lines.push('## NPM Packages\n');
+    for (const p of vars.npmPackages) {
+      lines.push(`- \`${p.name}\` ${p.version}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`---\n*Generated by morph-spec v${vars.morphVersion}*`);
+  return lines.join('\n');
+}