@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/gitflow/cli/sync/validate.ts

@@ -0,0 +1,34 @@
+/**
+ * sync CLI validate — Pure validation, no I/O
+ */
+
+import { SyncSpecSchema, type SyncSpec } from './types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  data?: SyncSpec;
+  blockers: string[];
+  warnings: string[];
+}
+
+export function validate(spec: unknown): ValidationResult {
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+
+  let data: SyncSpec | undefined;
+  try {
+    data = SyncSpecSchema.parse(spec);
+  } catch (err: unknown) {
+    const e = err as any;
+    if (e.errors) {
+      for (const error of e.errors) {
+        blockers.push(`${error.path?.join('.')}: ${error.message}`);
+      }
+    } else {
+      blockers.push(`Spec parse failed: ${(err as Error).message}`);
+    }
+    return { valid: false, blockers, warnings };
+  }
+
+  return { valid: blockers.length === 0, data, blockers, warnings };
+}

package/templates/skills/gitflow/commit-message.md

@@ -0,0 +1,46 @@
+---
+name: commit-message
+description: Generate structured Conventional Commits messages from staged changes
+group: gitflow
+---
+
+# Commit Message Generator
+
+## Your role
+
+You are a commit message generator. Your job is to produce clear, structured
+commit messages following the Conventional Commits specification.
+
+## Steps
+
+1. Run `git status` and `git diff --stat` to see what changed.
+2. Read the key changed files to understand the nature of the changes.
+3. Output the commit message using the format below.
+
+## Output format
+
+Your FINAL text output must start with `COMMIT_MSG:` followed by the message.
+The message format is:
+
+```
+type(scope): short title
+
+- bullet point 1
+- bullet point 2
+- bullet point 3
+```
+
+Types: `feat` | `fix` | `chore` | `refactor` | `docs` | `test`
+
+## Contextual rules
+
+- If ALL files are new/untracked (initial scaffold): describe what the project
+  contains (stack, architecture, tooling)
+- If files are modified: describe what was changed and why
+- Keep bullet points concise (max 10 words each)
+- 3 to 6 bullet points max
+
+## Output rules
+
+- Do NOT output explanations, analysis, or reasoning
+- Output ONLY: `COMMIT_MSG:` followed by the formatted message

package/templates/skills/init/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: init
+description: SmartStack project initialization via ss init
+group: A
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Skill: SmartStack Project Initialization
+
+## Objective
+Guide the initialization of a new SmartStack project via `ss init`.
+
+## Command
+```bash
+ss init <app-name>
+ss init --here
+ss init --yes
+ss init --preview
+ss init --dry-run
+```
+
+## Initialization Steps
+
+### 1. Prerequisites
+- .NET SDK >= 10.0 (required)
+- Docker (optional)
+
+### 2. Context Detection
+- GitFlow worktree (`.bare/` in parent)
+- C# namespace validation (PascalCase)
+
+### 3. Configuration
+- Database: SQL Server
+- Email: Development | Mailgun | AzureAcs | Disabled
+
+### 4. Backend Structure (.NET Clean Architecture)
+```
+src/{App}.Domain/ | {App}.Application/ | {App}.Infrastructure/ | {App}.Api/
+```
+
+### 5. Frontend Structure (React)
+```
+web/{app-lower}-web/src/
+```
+
+### 6. Docker
+- Dockerfile.api, Dockerfile.web, docker-compose.yml
+
+### 7. Config Files
+- `.smartstack/config.json`, `.gitignore`, `.vscode/`, `CLAUDE.md`
+
+## Summary
+- Checkpoint via `.smartstack/init-state.json`
+- `safeWriteFile` with SHA-256

package/templates/skills/lib/__tests__/canonical-hash.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { canonicalHash, canonicalize } from '../canonical-hash.js'
+
+describe('canonicalHash', () => {
+  it('is deterministic — same input yields the same hash (test 1)', () => {
+    const spec = { screenCode: 'SCR-X-001', entity: 'TypeAffaire', view: 'list', columns: [{ key: 'code' }] }
+    expect(canonicalHash(spec)).toBe(canonicalHash(spec))
+    expect(canonicalHash(spec)).toMatch(/^sha256-/)
+  })
+
+  it('is insensitive to object key order (test 2)', () => {
+    const a = { entity: 'TypeAffaire', view: 'list', permission: 'gaf.x.read' }
+    const b = { permission: 'gaf.x.read', view: 'list', entity: 'TypeAffaire' }
+    expect(canonicalHash(a)).toBe(canonicalHash(b))
+  })
+
+  it('is sensitive to value changes (test 3)', () => {
+    const base = { entity: 'TypeAffaire', view: 'list', columns: [{ key: 'code', labelKey: 'list.columns.code' }] }
+    const changed = { entity: 'TypeAffaire', view: 'list', columns: [{ key: 'code', labelKey: 'list.columns.libelle' }] }
+    expect(canonicalHash(base)).not.toBe(canonicalHash(changed))
+  })
+
+  it('treats array order as significant (display order matters)', () => {
+    expect(canonicalHash({ columns: [{ key: 'a' }, { key: 'b' }] })).not.toBe(
+      canonicalHash({ columns: [{ key: 'b' }, { key: 'a' }] }),
+    )
+  })
+
+  it('ignores undefined values (an absent key === an explicit undefined)', () => {
+    expect(canonicalHash({ a: 1, b: undefined })).toBe(canonicalHash({ a: 1 }))
+  })
+})
+
+describe('canonicalize', () => {
+  it('sorts nested object keys recursively', () => {
+    const out = canonicalize({ b: { d: 2, c: 1 }, a: 0 }) as Record<string, unknown>
+    expect(JSON.stringify(out)).toBe('{"a":0,"b":{"c":1,"d":2}}')
+  })
+
+  it('passes primitives and null through untouched', () => {
+    expect(canonicalize('s')).toBe('s')
+    expect(canonicalize(42)).toBe(42)
+    expect(canonicalize(null)).toBeNull()
+  })
+})

package/templates/skills/lib/__tests__/page-spec-actions.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect } from 'vitest'
+import {
+  PageCustomActionSchema,
+  STANDARD_CRUD_CODES,
+  defaultEndpoint,
+  controllerMethodNameFromEndpoint,
+  serviceMethodNameFromEndpoint,
+  lastPermissionSegment,
+  expectedUrlPath,
+  expectedControllerRoute,
+  customActionsOnly,
+  normalizePageCustomAction,
+  type PageCustomAction,
+} from '../page-spec-actions.js'
+
+function apiAction(overrides: Partial<PageCustomAction> = {}): PageCustomAction {
+  return PageCustomActionSchema.parse({
+    code: 'syncFromPce',
+    kind: 'api',
+    scope: 'header',
+    endpoint: 'sync-from-proconcept',
+    httpMethod: 'POST',
+    labelKey: 'list.actions.syncFromPce',
+    permission: 'referentiels.types-affaire.execute',
+    ucReference: 'UC-APP-REF-TYPEAFFAIRE-007',
+    ...overrides,
+  })
+}
+
+function navAction(overrides: Partial<PageCustomAction> = {}): PageCustomAction {
+  return PageCustomActionSchema.parse({
+    code: 'open',
+    kind: 'navigate',
+    scope: 'row',
+    targetScreen: 'SCR-APP-REF-TYPEAFFAIRE-002',
+    labelKey: 'list.actions.open',
+    permission: 'referentiels.types-affaire.read',
+    ...overrides,
+  })
+}
+
+describe('lib/page-spec-actions — helpers', () => {
+  it('defaultEndpoint kebabifies camelCase codes', () => {
+    expect(defaultEndpoint('syncFromPce')).toBe('sync-from-pce')
+    expect(defaultEndpoint('analyzeImpact')).toBe('analyze-impact')
+    expect(defaultEndpoint('archive')).toBe('archive')
+    expect(defaultEndpoint('mapToPce')).toBe('map-to-pce')
+  })
+
+  it('controllerMethodNameFromEndpoint returns PascalCase', () => {
+    expect(controllerMethodNameFromEndpoint('sync-from-proconcept')).toBe('SyncFromProconcept')
+    expect(controllerMethodNameFromEndpoint('archive')).toBe('Archive')
+    expect(controllerMethodNameFromEndpoint('analyze-impact')).toBe('AnalyzeImpact')
+  })
+
+  it('serviceMethodNameFromEndpoint returns camelCase', () => {
+    expect(serviceMethodNameFromEndpoint('sync-from-proconcept')).toBe('syncFromProconcept')
+    expect(serviceMethodNameFromEndpoint('archive')).toBe('archive')
+    expect(serviceMethodNameFromEndpoint('analyze-impact')).toBe('analyzeImpact')
+  })
+
+  it('lastPermissionSegment returns the action segment', () => {
+    expect(lastPermissionSegment('referentiels.types-affaire.execute')).toBe('execute')
+    expect(lastPermissionSegment('budgets.budgets.update')).toBe('update')
+  })
+
+  it('expectedUrlPath builds the right path per scope', () => {
+    expect(expectedUrlPath('header', 'sync-from-pce')).toBe('/sync-from-pce')
+    expect(expectedUrlPath('row', 'archive')).toBe('/{id}/archive')
+    expect(expectedUrlPath('bulk', 'export-csv')).toBe('/bulk/export-csv')
+  })
+
+  it('expectedControllerRoute mirrors with {id:guid} for row scope', () => {
+    expect(expectedControllerRoute('header', 'sync-from-pce')).toBe('sync-from-pce')
+    expect(expectedControllerRoute('row', 'archive')).toBe('{id:guid}/archive')
+    expect(expectedControllerRoute('bulk', 'export-csv')).toBe('bulk/export-csv')
+  })
+
+  it('STANDARD_CRUD_CODES excludes custom actions only', () => {
+    expect(STANDARD_CRUD_CODES.has('create')).toBe(true)
+    expect(STANDARD_CRUD_CODES.has('edit')).toBe(true)
+    expect(STANDARD_CRUD_CODES.has('delete')).toBe(true)
+    expect(STANDARD_CRUD_CODES.has('syncFromPce')).toBe(false)
+    expect(STANDARD_CRUD_CODES.has('archive')).toBe(false)
+  })
+
+  it('customActionsOnly filters out CRUD codes', () => {
+    const all = [
+      { code: 'create' },
+      { code: 'edit' },
+      { code: 'syncFromPce' },
+      { code: 'archive' },
+    ]
+    expect(customActionsOnly(all).map(a => a.code)).toEqual(['syncFromPce', 'archive'])
+  })
+})
+
+describe('lib/page-spec-actions — schema validation (kind:api)', () => {
+  it('accepts a minimal valid api action', () => {
+    expect(() => apiAction()).not.toThrow()
+  })
+
+  it('accepts api action WITHOUT explicit endpoint (filled by normalize)', () => {
+    const parsed = PageCustomActionSchema.parse({
+      code: 'archive',
+      kind: 'api',
+      scope: 'row',
+      labelKey: 'list.actions.archive',
+      permission: 'budgets.budgets.update',
+    })
+    expect(parsed.endpoint).toBeUndefined()
+    const normalized = normalizePageCustomAction(parsed)
+    expect(normalized.endpoint).toBe('archive')
+  })
+
+  it('rejects code in kebab-case (must be camelCase)', () => {
+    expect(() => apiAction({ code: 'sync-from-pce' as unknown as string })).toThrow(/camelCase/)
+  })
+
+  it('rejects endpoint in camelCase (must be kebab-case)', () => {
+    expect(() => apiAction({ endpoint: 'syncFromPce' })).toThrow(/kebab-case/)
+  })
+
+  it('rejects malformed permission (must be 3 segments)', () => {
+    expect(() => apiAction({ permission: 'flat' })).toThrow()
+    expect(() => apiAction({ permission: 'two.segments' })).toThrow()
+  })
+
+  it('accepts httpMethod GET/PUT/PATCH/DELETE', () => {
+    for (const m of ['GET', 'PUT', 'PATCH', 'DELETE'] as const) {
+      expect(() => apiAction({ httpMethod: m })).not.toThrow()
+    }
+  })
+
+  it('rejects api action carrying targetScreen', () => {
+    expect(() =>
+      apiAction({ targetScreen: 'SCR-APP-REF-TYPEAFFAIRE-002' }),
+    ).toThrow(/api action must NOT carry targetScreen/)
+  })
+
+  it('accepts optional ucReference and guardRules', () => {
+    expect(() =>
+      apiAction({
+        ucReference: 'UC-APP-REF-TYPEAFFAIRE-007',
+        guardRules: ['BR-001', 'BR-007'],
+      }),
+    ).not.toThrow()
+  })
+
+  it('accepts workflowTransition shape', () => {
+    expect(() =>
+      apiAction({
+        workflowTransition: {
+          fromStatus: ['pending'],
+          toStatus: 'approved',
+          flowParameters: ['reason'],
+        },
+      }),
+    ).not.toThrow()
+  })
+})
+
+describe('lib/page-spec-actions — schema validation (kind:navigate)', () => {
+  it('accepts a minimal navigate action with targetScreen', () => {
+    expect(() => navAction()).not.toThrow()
+  })
+
+  it('accepts navigate action with targetRoute instead of targetScreen', () => {
+    expect(() =>
+      navAction({
+        targetScreen: undefined,
+        targetRoute: 'routes.referentiels.typesAffaire.detail(item.id)',
+      }),
+    ).not.toThrow()
+  })
+
+  it('rejects navigate action without targetScreen or targetRoute', () => {
+    expect(() =>
+      navAction({ targetScreen: undefined, targetRoute: undefined }),
+    ).toThrow(/navigate action requires targetRoute or targetScreen/)
+  })
+
+  it('rejects navigate action carrying endpoint', () => {
+    expect(() =>
+      navAction({ endpoint: 'open' }),
+    ).toThrow(/navigate action must NOT carry endpoint/)
+  })
+
+  it('rejects navigate action carrying payloadDto', () => {
+    expect(() =>
+      navAction({ payloadDto: 'OpenRequest' }),
+    ).toThrow(/navigate action must NOT carry payloadDto/)
+  })
+
+  it('rejects navigate action carrying workflowTransition', () => {
+    expect(() =>
+      navAction({
+        workflowTransition: {
+          fromStatus: ['pending'],
+          toStatus: 'approved',
+          flowParameters: [],
+        },
+      }),
+    ).toThrow(/navigate action must NOT carry workflowTransition/)
+  })
+})
+
+describe('lib/page-spec-actions — normalizePageCustomAction', () => {
+  it('fills endpoint via defaultEndpoint when missing for kind:api', () => {
+    const parsed = PageCustomActionSchema.parse({
+      code: 'analyzeImpact',
+      kind: 'api',
+      scope: 'header',
+      httpMethod: 'GET',
+      labelKey: 'list.actions.analyzeImpact',
+      permission: 'referentiels.types-affaire.read',
+    })
+    expect(normalizePageCustomAction(parsed).endpoint).toBe('analyze-impact')
+  })
+
+  it('mirrors payloadType/responseType from C# names when missing', () => {
+    const parsed = apiAction({ payloadDto: 'SyncRequest', responseDto: 'SyncResultDto' })
+    const norm = normalizePageCustomAction(parsed)
+    expect(norm.payloadType).toBe('SyncRequest')
+    expect(norm.responseType).toBe('SyncResultDto')
+  })
+
+  it('returns navigate actions unchanged', () => {
+    const parsed = navAction()
+    expect(normalizePageCustomAction(parsed)).toEqual(parsed)
+  })
+})

package/templates/skills/lib/canonical-hash.ts

@@ -0,0 +1,40 @@
+/**
+ * lib/canonical-hash.ts — Deterministic content hash for pagespec JSON.
+ *
+ * Used by `ba-develop/cli/compute-page-diff` (Phase 3a targeted re-runs) to
+ * detect whether a pagespec's machine block changed since the last successful
+ * run. The hash is stable regardless of object **key order** — re-serialising
+ * the same spec with keys in a different order yields the same hash, so a
+ * cosmetic reorder by `ba-create-prd` never reads as a false "modified".
+ *
+ * Array order IS significant (columns / actions / filters carry display order),
+ * so `[a, b]` and `[b, a]` intentionally hash differently.
+ *
+ * Pure: no I/O, no clock, no randomness — same input → same output forever.
+ */
+import { createHash } from 'node:crypto'
+
+/**
+ * Recursively sort object keys and drop `undefined` values so that
+ * `JSON.stringify` produces a canonical, order-independent string. Arrays keep
+ * their element order; primitives pass through untouched.
+ */
+export function canonicalize(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(canonicalize)
+  const sorted: Record<string, unknown> = {}
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    const v = (value as Record<string, unknown>)[key]
+    if (v !== undefined) sorted[key] = canonicalize(v)
+  }
+  return sorted
+}
+
+/**
+ * Deterministic sha256 (base64) of any JSON-serialisable value, prefixed
+ * `sha256-` so the algorithm is self-describing in the snapshot file.
+ */
+export function canonicalHash(value: unknown): string {
+  const json = JSON.stringify(canonicalize(value))
+  return 'sha256-' + createHash('sha256').update(json).digest('base64')
+}

package/templates/skills/lib/detector.ts

@@ -0,0 +1,243 @@
+/**
+ * lib/detector.ts — SmartStack project structure detection.
+ * Ported from SmartStack.cli/src/mcp/lib/detector.ts — MCP logger removed,
+ * findSmartStackStructure kept as the primary API for dev CLIs.
+ *
+ * Given an absolute path to a SmartStack project, this module locates:
+ *   - The Clean Architecture layers (Domain, Application, Infrastructure, Api)
+ *   - The web/frontend folder (searches common conventions)
+ *   - The EF Core migrations folder
+ *
+ * Configuration overrides can be declared in `.smartstack/config.json` under a
+ * `paths` key. Auto-detection fills the gaps.
+ */
+import path from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { directoryExists, fileExists, readText } from './fs.js';
+import { findCsprojFiles, hasEfCore, findDbContextName, getTargetFramework } from './dotnet.js';
+import { isGitRepo, getCurrentBranch } from './git.js';
+
+export interface SmartStackStructure {
+  root: string;
+  domain?: string;
+  application?: string;
+  infrastructure?: string;
+  /** Primary API (prefers *.Api.Core over *.Api) */
+  api?: string;
+  /** *.Api.Core project (core controllers) if present */
+  apiCore?: string;
+  /** *.Api project without Core (extension controllers) if present */
+  apiExtensions?: string;
+  web?: string;
+  migrations?: string;
+}
+
+export interface ProjectInfo {
+  name: string;
+  version: string;
+  isGitRepo: boolean;
+  currentBranch?: string;
+  hasDotNet: boolean;
+  hasEfCore: boolean;
+  hasReact: boolean;
+  csprojFiles: string[];
+  dbContextName?: string;
+  targetFramework?: string;
+}
+
+/**
+ * Search for a web/frontend project folder under the SmartStack root.
+ * Priority order matches common conventions (never hardcoded to "smartstack-web").
+ */
+async function findWebProjectFolder(projectPath: string): Promise<string | null> {
+  // 1) web/<name>/package.json (any subfolder of web/)
+  const webDir = path.join(projectPath, 'web');
+  if (await directoryExists(webDir)) {
+    try {
+      const entries = await readdir(webDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const folder = path.join(webDir, entry.name);
+          if (await fileExists(path.join(folder, 'package.json'))) return folder;
+        }
+      }
+    } catch {
+      // Unreadable — fall through
+    }
+  }
+
+  // 2) web/package.json (monorepo style)
+  if (await fileExists(path.join(webDir, 'package.json'))) return webDir;
+
+  // 3) client/ or frontend/ or ui/
+  for (const folderName of ['client', 'frontend', 'ui']) {
+    const altPath = path.join(projectPath, folderName);
+    if (await fileExists(path.join(altPath, 'package.json'))) return altPath;
+  }
+
+  // 4) src/web/
+  const srcWeb = path.join(projectPath, 'src', 'web');
+  if (await fileExists(path.join(srcWeb, 'package.json'))) return srcWeb;
+
+  return null;
+}
+
+/**
+ * Detect basic metadata about a SmartStack project (git, .NET, React, version).
+ */
+export async function detectProject(projectPath: string): Promise<ProjectInfo> {
+  const info: ProjectInfo = {
+    name: path.basename(projectPath),
+    version: '0.0.0',
+    isGitRepo: false,
+    hasDotNet: false,
+    hasEfCore: false,
+    hasReact: false,
+    csprojFiles: [],
+  };
+
+  if (!(await directoryExists(projectPath))) return info;
+
+  info.isGitRepo = await isGitRepo(projectPath);
+  if (info.isGitRepo) {
+    info.currentBranch = (await getCurrentBranch(projectPath)) || undefined;
+  }
+
+  info.csprojFiles = await findCsprojFiles(projectPath);
+  info.hasDotNet = info.csprojFiles.length > 0;
+
+  if (info.hasDotNet) {
+    for (const csproj of info.csprojFiles) {
+      if (await hasEfCore(csproj)) {
+        info.hasEfCore = true;
+        info.dbContextName = (await findDbContextName(path.dirname(csproj))) || undefined;
+        break;
+      }
+    }
+  }
+
+  const webFolder = await findWebProjectFolder(projectPath);
+  if (webFolder) {
+    const packageJsonPath = path.join(webFolder, 'package.json');
+    if (await fileExists(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(await readText(packageJsonPath)) as {
+          dependencies?: Record<string, string>;
+          version?: string;
+        };
+        info.hasReact = !!pkg.dependencies?.react;
+        info.version = pkg.version || info.version;
+      } catch {
+        // parse error — ignore
+      }
+    }
+  }
+
+  if (info.csprojFiles.length > 0) {
+    const mainCsproj =
+      info.csprojFiles.find((f) => /\.Api\.csproj$/i.test(f)) ||
+      info.csprojFiles.find((f) => /Api\.csproj$/i.test(f)) ||
+      info.csprojFiles[0];
+    const tf = await getTargetFramework(mainCsproj);
+    if (tf) info.targetFramework = tf;
+  }
+
+  return info;
+}
+
+/**
+ * Find the physical folders that make up a SmartStack project.
+ * Reads optional overrides from `.smartstack/config.json` → `paths`, then
+ * auto-detects from .csproj files to fill the gaps.
+ */
+export async function findSmartStackStructure(projectPath: string): Promise<SmartStackStructure> {
+  const structure: SmartStackStructure = { root: projectPath };
+
+  // Config override
+  const configPath = path.join(projectPath, '.smartstack', 'config.json');
+  if (await fileExists(configPath)) {
+    try {
+      const cfg = JSON.parse(await readText(configPath)) as {
+        paths?: Partial<Record<'api' | 'domain' | 'application' | 'infrastructure' | 'web', string>>;
+      };
+      const paths = cfg.paths;
+      if (paths) {
+        if (paths.api) structure.api = path.resolve(projectPath, paths.api);
+        if (paths.domain) structure.domain = path.resolve(projectPath, paths.domain);
+        if (paths.application) structure.application = path.resolve(projectPath, paths.application);
+        if (paths.infrastructure)
+          structure.infrastructure = path.resolve(projectPath, paths.infrastructure);
+        if (paths.web) structure.web = path.resolve(projectPath, paths.web);
+      }
+    } catch {
+      // parse error — fall through to auto-detect
+    }
+  }
+
+  // Auto-detect from .csproj files
+  const csprojFiles = await findCsprojFiles(projectPath);
+
+  for (const csproj of csprojFiles) {
+    const projectName = path.basename(csproj, '.csproj').toLowerCase();
+    const projectDir = path.dirname(csproj);
+
+    if (!structure.domain && projectName.includes('domain')) {
+      structure.domain = projectDir;
+    } else if (!structure.application && projectName.includes('application')) {
+      structure.application = projectDir;
+    } else if (!structure.infrastructure && projectName.includes('infrastructure')) {
+      structure.infrastructure = projectDir;
+    } else if (projectName.includes('api.core')) {
+      if (!structure.apiCore) structure.apiCore = projectDir;
+      if (!structure.api) structure.api = projectDir;
+    } else if (projectName.includes('api') && !projectName.includes('api.core')) {
+      if (!structure.apiExtensions) structure.apiExtensions = projectDir;
+      if (!structure.api) structure.api = projectDir;
+    }
+  }
+
+  // Migrations folder
+  if (structure.infrastructure) {
+    const migrationsPath = path.join(structure.infrastructure, 'Persistence', 'Migrations');
+    if (await directoryExists(migrationsPath)) structure.migrations = migrationsPath;
+  }
+
+  // Web folder
+  if (!structure.web) {
+    const webFolder = await findWebProjectFolder(projectPath);
+    if (webFolder) structure.web = webFolder;
+  }
+
+  return structure;
+}
+
+/**
+ * Find all entity files in the domain layer (classes/records with an Id property).
+ */
+export async function findEntityFiles(domainPath: string): Promise<string[]> {
+  const { findFiles } = await import('./fs.js');
+  const entityFiles = await findFiles('**/*.cs', { cwd: domainPath });
+  const entities: string[] = [];
+  for (const file of entityFiles) {
+    const content = await readText(file);
+    if (
+      content.match(/public\s+(?:class|record)\s+\w+/) &&
+      content.match(/public\s+(?:int|long|Guid|string)\s+Id\s*\{/)
+    ) {
+      entities.push(file);
+    }
+  }
+  return entities;
+}
+
+/** Find all service interfaces in the application layer. */
+export async function findServiceInterfaces(applicationPath: string): Promise<string[]> {
+  const { findFiles } = await import('./fs.js');
+  return findFiles('**/I*Service.cs', { cwd: applicationPath });
+}
+
+/** Find all controller files in the API layer. */
+export async function findControllerFiles(apiPath: string): Promise<string[]> {
+  const { findFiles } = await import('./fs.js');
+  return findFiles('**/*Controller.cs', { cwd: apiPath });
+}