@mrpatronz/nexusflow 0.1.12 → 0.2.1

package/src/generators/map-generator.ts

@@ -0,0 +1,405 @@
+/**
+ * @module generators/map-generator
+ * Generates a nexusflow-map-<repo>.md file for each repository in the workspace.
+ * Provides a localized, token-efficient architectural map for AI assistants.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { globby } from 'globby';
+import type { ProjectAnalysis, RepoInfo } from '../types.js';
+import { loadConfig } from '../core/config.js';
+
+interface PatternRule {
+  name: string;
+  label: string;
+  regex: RegExp;
+  description: string;
+}
+
+const LANG_PATTERNS: Record<string, PatternRule[]> = {
+  csharp: [
+    {
+      name: 'FluentValidation',
+      label: 'FluentValidation Validator subclasses',
+      regex: /:\s*AbstractValidator\s*</g,
+      description: 'Used for domain/command validation rules.'
+    },
+    {
+      name: 'MediatR Handlers',
+      label: 'MediatR Request Handlers',
+      regex: /:\s*IRequestHandler\s*</g,
+      description: 'Used for CQRS command/query handler pattern.'
+    },
+    {
+      name: 'MediatR Requests',
+      label: 'MediatR Requests/Commands',
+      regex: /:\s*IRequest\b(?!Handler)/g,
+      description: 'Used for MediatR command/query dispatching.'
+    },
+    {
+      name: 'AutoMapper Profiles',
+      label: 'AutoMapper Mapping Profiles',
+      regex: /:\s*Profile\b/g,
+      description: 'Used for object-to-object mappings.'
+    },
+    {
+      name: 'DataAnnotations',
+      label: 'DataAnnotations Validation Attributes',
+      regex: /using\s+System\.ComponentModel\.DataAnnotations;/g,
+      description: 'Used for property-level attribute validation.'
+    }
+  ],
+  typescript: [
+    {
+      name: 'Zod Schemas',
+      label: 'Zod Object Schemas',
+      regex: /z\.object\s*\(/g,
+      description: 'Used for schema parsing/validation.'
+    },
+    {
+      name: 'NestJS Controllers',
+      label: 'NestJS Routing Controllers',
+      regex: /@Controller\s*\(/g,
+      description: 'Used for controller routing endpoints.'
+    },
+    {
+      name: 'NestJS Injectables',
+      label: 'NestJS Injectable Services',
+      regex: /@Injectable\s*\(\)/g,
+      description: 'Used for dependency injection services.'
+    },
+    {
+      name: 'React Components',
+      label: 'React Functional Components',
+      regex: /React\.FC/g,
+      description: 'Used for component UI views.'
+    }
+  ],
+  javascript: [
+    {
+      name: 'Zod Schemas',
+      label: 'Zod Object Schemas',
+      regex: /z\.object\s*\(/g,
+      description: 'Used for schema parsing/validation.'
+    }
+  ],
+  python: [
+    {
+      name: 'Pydantic Models',
+      label: 'Pydantic BaseModel subclasses',
+      regex: /class\s+\w+\s*\(\s*BaseModel\s*\)/g,
+      description: 'Used for data schemas and validation.'
+    },
+    {
+      name: 'FastAPI Routers',
+      label: 'FastAPI APIRouter instances',
+      regex: /=([\s\S]*?)APIRouter\s*\(/g,
+      description: 'Used for endpoint routing.'
+    }
+  ],
+  go: [
+    {
+      name: 'Go JSON tags',
+      label: 'Go JSON struct tags',
+      regex: /`json:"[^"]+"`/g,
+      description: 'Used for struct serialization/deserialization.'
+    }
+  ]
+};
+
+/**
+ * Generates a `nexusflow-map-<repo>.md` file in the workspace root.
+ *
+ * @param repo          - The repository metadata.
+ * @param analysis      - The repository analysis result.
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateRepoMap(
+  repo: RepoInfo,
+  analysis: ProjectAnalysis,
+  workspacePath: string,
+): Promise<void> {
+  const repoName = repo.name;
+  const worktreePath = path.join(workspacePath, repoName);
+
+  const md: string[] = [];
+
+  md.push(`# Repository Architecture Map — ${repoName}`);
+  md.push('');
+  md.push(`> **Repository Path**: \`${worktreePath}\``);
+  md.push(`> **Generated At**: ${new Date().toISOString()} (UTC)`);
+  md.push(`> **Regeneration Command**: Run \`nexusflow sync\` to update this map and workspace planning files.`);
+  md.push(`> **Note**: Maps are advisory snapshots of the codebase. Always verify route parameters, patterns, and filenames before relying on them.`);
+  md.push('');
+
+  const config = await loadConfig();
+  if (config.packContextXml) {
+    const contextXmlPath = path.join(workspacePath, `nexusflow-context-${repoName}.xml`).replace(/\\/g, '/');
+    md.push(`> **AI-friendly Packed Context**: [nexusflow-context-${repoName}.xml](file:///${contextXmlPath})`);
+    md.push(`> — **Instruction**: If you need a complete, AI-friendly XML snapshot of this repository's codebase, read this file.`);
+    md.push('');
+  }
+
+  // 1. Solution/Project Layout
+  md.push('## 🏗️ Project Layout');
+  md.push('');
+
+  try {
+    const slnFiles = await globby('**/*.sln', {
+      cwd: worktreePath,
+      ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+    });
+
+    const csprojFiles = await globby('**/*.csproj', {
+      cwd: worktreePath,
+      ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+    });
+
+    const packageJsons = await globby('**/package.json', {
+      cwd: worktreePath,
+      ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+    });
+
+    if (slnFiles.length > 0) {
+      md.push('### .NET Solutions');
+      for (const sln of slnFiles) {
+        md.push(`- **Solution**: \`${sln}\``);
+      }
+      md.push('');
+    }
+
+    if (csprojFiles.length > 0) {
+      md.push('### .NET Projects');
+      for (const csproj of csprojFiles) {
+        const isTest = csproj.toLowerCase().includes('test') || csproj.toLowerCase().includes('spec');
+        const role = isTest ? 'Test Suite' : 'App/Library';
+        md.push(`- \`${csproj}\` (${role})`);
+      }
+      md.push('');
+    }
+
+    if (packageJsons.length > 0) {
+      md.push('### npm Packages & Modules');
+      for (const pj of packageJsons) {
+        md.push(`- \`${pj}\``);
+      }
+      md.push('');
+    }
+  } catch {
+    md.push('_No project layout files discovered or error occurred._');
+    md.push('');
+  }
+
+  // 2. Extensible Usage Pattern Scanning
+  md.push('## 💡 Detected Architectural Patterns & Usages');
+  md.push('');
+
+  const detectedLanguages = analysis.techStack.languages;
+  const patternCounts = new Map<string, { label: string; count: number; description: string }>();
+
+  // Initialize counts
+  for (const lang of detectedLanguages) {
+    const rules = LANG_PATTERNS[lang] || [];
+    for (const rule of rules) {
+      patternCounts.set(rule.name, { label: rule.label, count: 0, description: rule.description });
+    }
+  }
+
+  // Scan files for pattern usage
+  try {
+    const extensions = detectedLanguages.map(l => {
+      if (l === 'csharp') return 'cs';
+      if (l === 'typescript') return 'ts';
+      if (l === 'javascript') return 'js';
+      if (l === 'python') return 'py';
+      if (l === 'go') return 'go';
+      return '';
+    }).filter(ext => ext !== '');
+
+    if (extensions.length > 0) {
+      const globPattern = extensions.length === 1 ? `**/*.${extensions[0]}` : `**/*.{${extensions.join(',')}}`;
+      const srcFiles = await globby(globPattern, {
+        cwd: worktreePath,
+        ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+      });
+
+      for (const file of srcFiles) {
+        const fullPath = path.join(worktreePath, file);
+        const content = await fs.readFile(fullPath, 'utf-8');
+
+        for (const lang of detectedLanguages) {
+          const rules = LANG_PATTERNS[lang] || [];
+          for (const rule of rules) {
+            rule.regex.lastIndex = 0;
+            const matches = content.match(rule.regex);
+            if (matches) {
+              const val = patternCounts.get(rule.name)!;
+              val.count += matches.length;
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  md.push('### Static Analysis Findings');
+  if (patternCounts.size > 0) {
+    for (const [, v] of patternCounts) {
+      md.push(`- **${v.label}**: Found ${v.count} occurrence(s). _(${v.description})_`);
+    }
+  } else {
+    md.push('_No architectural usage patterns detected via static analysis._');
+  }
+  md.push('');
+
+  md.push('### Packages Present (Dependencies)');
+  if (analysis.dependencies.length > 0) {
+    for (const dep of analysis.dependencies) {
+      md.push(`- \`${dep.name}\` (${dep.version || 'unknown version'})`);
+    }
+  } else {
+    md.push('_No package dependencies detected._');
+  }
+  md.push('');
+
+  // 3. Endpoint Inventory
+  md.push('## 🔌 API Endpoints');
+  md.push('');
+  if (analysis.endpoints.length > 0) {
+    md.push('| Method | Route | Controller/Source File |');
+    md.push('|:---|:---|:---|');
+    for (const ep of analysis.endpoints) {
+      const sourceLink = ep.source
+        ? `[${path.basename(ep.source)}](file:///${path.join(worktreePath, ep.source)})`
+        : '—';
+      md.push(`| \`${ep.method}\` | \`${ep.path}\` | ${sourceLink} |`);
+    }
+  } else {
+    md.push('_No endpoints detected._');
+  }
+  md.push('');
+
+  // 4. Test Landscape
+  md.push('## 🧪 Test Landscape & Command');
+  md.push('');
+  const testFrameworks: string[] = [];
+  let testCommand = '';
+
+  for (const dep of analysis.dependencies) {
+    const name = dep.name.toLowerCase();
+    if (name.includes('xunit')) testFrameworks.push('xUnit');
+    if (name.includes('mstest') || name.includes('microsoft.testplatform')) testFrameworks.push('MSTest');
+    if (name.includes('nunit')) testFrameworks.push('NUnit');
+    if (name.includes('jest')) testFrameworks.push('Jest');
+    if (name.includes('vitest')) testFrameworks.push('Vitest');
+    if (name.includes('cypress')) testFrameworks.push('Cypress');
+    if (name.includes('playwright')) testFrameworks.push('Playwright');
+  }
+
+  if (analysis.techStack.languages.includes('csharp')) {
+    testCommand = 'dotnet test';
+    try {
+      const slns = await globby('**/*.sln', {
+        cwd: worktreePath,
+        ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+      });
+      if (slns.length > 0) {
+        testCommand = `dotnet test ${slns[0]}`;
+      }
+    } catch {}
+  } else if (analysis.techStack.languages.includes('typescript') || analysis.techStack.languages.includes('javascript')) {
+    testCommand = 'npm test';
+  }
+
+  if (testFrameworks.length > 0) {
+    md.push(`- **Frameworks**: ${testFrameworks.join(', ')}`);
+  } else {
+    md.push('- **Frameworks**: None explicitly detected');
+  }
+  if (testCommand) {
+    md.push(`- **Run Command**: \`${testCommand}\``);
+  }
+  md.push('');
+
+  // 5. Custom Skills
+  md.push('## 🛠️ Custom Agent Skills');
+  md.push('');
+  try {
+    const skills = await globby('**/SKILL.md', {
+      cwd: worktreePath,
+      absolute: true,
+      ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+    });
+
+    if (skills.length > 0) {
+      md.push('The following custom agent skills are available in this repository:');
+      for (const skill of skills) {
+        const relativeSkill = path.relative(worktreePath, skill);
+        const skillName = path.basename(path.dirname(skill));
+        md.push(`- **${skillName}**: [${relativeSkill}](file:///${skill})`);
+      }
+    } else {
+      md.push('_No custom agent skills found in this repository._');
+    }
+  } catch {
+    md.push('_No custom agent skills found in this repository._');
+  }
+  md.push('');
+
+  // 6. AI Configurations
+  md.push('## 📄 AI Assistant Configurations');
+  md.push('');
+  if (analysis.existingAIConfigs.length > 0) {
+    md.push('Incorporate instructions from these local configurations:');
+    for (const config of analysis.existingAIConfigs) {
+      md.push(`- [${config.relativePath}](file:///${path.join(worktreePath, config.relativePath)}) (${config.assistant})`);
+    }
+  } else {
+    md.push('_No pre-existing AI configurations found in this repository._');
+  }
+  md.push('');
+
+  // 7. Project-Specific Conventions (Agent-Defined)
+  const conventionsFile = path.join(workspacePath, `nexusflow-conventions-${repoName}.md`);
+  let hasConventions = false;
+  try {
+    await fs.access(conventionsFile);
+    hasConventions = true;
+  } catch {}
+
+  if (!hasConventions) {
+    const starterContent = [
+      `# Project Conventions — ${repoName}`,
+      '',
+      `<!--`,
+      `This file is dedicated for the AI assistant and developers to document project-specific conventions.`,
+      `Any corrections or guidelines discovered during implementation should be appended here.`,
+      `The NexusFlow generator will automatically merge these into the architecture map during sync.`,
+      `-->`,
+      '',
+      `## 📌 Custom Rules & Discovered Conventions`,
+      '- ',
+    ].join('\n');
+    try {
+      await fs.writeFile(conventionsFile, starterContent, 'utf-8');
+    } catch {}
+  }
+
+  let customConventions = '';
+  try {
+    customConventions = await fs.readFile(conventionsFile, 'utf-8');
+  } catch {}
+
+  if (customConventions) {
+    md.push('## 📝 Project-Specific Conventions (Agent-Defined)');
+    md.push('');
+    md.push(customConventions);
+    md.push('');
+  }
+
+  const outPath = path.join(workspacePath, `nexusflow-map-${repoName}.md`);
+  await fs.writeFile(outPath, md.join('\n'), 'utf-8');
+}

package/src/generators/plan-generator.ts

@@ -59,19 +59,48 @@ export function buildDependencyGraph(
     if (a) analysisByName.set(repo.name, a);
   }
 
-  const repoNames = new Set(repos.map((r) => r.name));
+  // ── 1. Produced/consumed package dependencies ──────────────────────────
+  // Map each produced package name to the repo name that produces it
+  const packageToRepo = new Map<string, string>();
+  for (const repo of repos) {
+    const a = analysisByName.get(repo.name);
+    if (!a) continue;
+
+    // Map the repo name itself as a produced product (for direct matching)
+    packageToRepo.set(repo.name.toLowerCase(), repo.name);
+
+    if (a.produces) {
+      for (const product of a.produces) {
+        packageToRepo.set(product.name.toLowerCase(), repo.name);
+        // Map basename (e.g. Hogia.EmploymentService.Client -> Client)
+        const base = product.name.split('.').pop() ?? product.name;
+        if (base && base.length > 3) {
+          packageToRepo.set(base.toLowerCase(), repo.name);
+        }
+      }
+    }
+  }
 
-  // ── 1. Shared-package dependencies ───────────────────────────────────
   for (const repo of repos) {
     const a = analysisByName.get(repo.name);
     if (!a) continue;
 
     for (const dep of a.dependencies) {
-      // Direct name match — e.g. "@acme/shared-contracts" contains "shared-contracts"
-      for (const otherName of repoNames) {
-        if (otherName === repo.name) continue;
-        if (dep.name === otherName || dep.name.includes(otherName)) {
-          addEdge(graph, repo.name, otherName);
+      const depNameLower = dep.name.toLowerCase();
+
+      // 1. Direct match with a produced package
+      if (packageToRepo.has(depNameLower)) {
+        const targetRepo = packageToRepo.get(depNameLower)!;
+        if (targetRepo !== repo.name) {
+          addEdge(graph, repo.name, targetRepo);
+        }
+      } else {
+        // 2. Check if the dependency contains or is contained by a produced package name
+        for (const [prodPkg, targetRepo] of packageToRepo) {
+          if (targetRepo === repo.name) continue;
+          if (depNameLower.includes(prodPkg) || prodPkg.includes(depNameLower)) {
+            addEdge(graph, repo.name, targetRepo);
+          }
         }
       }
     }
@@ -191,6 +220,8 @@ export function topologicalSort(graph: DependencyGraph): string[][] {
  * - A Mermaid dependency diagram
  * - Phased implementation order derived from topological sort
  * - A dependency cross-reference table
+ * - A package relations table
+ * - Actionable local dev tips
  *
  * @param ctx            The current workspace context (feature + repos + analysis).
  * @param workspacePath  Absolute path to the workspace root directory.
@@ -328,6 +359,85 @@ export async function generateImplementationPlan(
 
     md.push('');
 
+    // ── Contracts & Clients Table ───────────────────────────────────────
+    md.push('## 📦 Contracts & Clients');
+    md.push('');
+    md.push('| Package | Contributing Projects | Producing Repo | Consuming Repos (Version) | Feed Source | Type |');
+    md.push('|:---|:---|:---|:---|:---|:---|');
+
+    // Build package relations
+    interface PackageRelation {
+      pkgName: string;
+      contributing?: string[];
+      producer: string;
+      consumers: { repoName: string; version?: string }[];
+      type: 'npm' | 'nuget' | 'other';
+      feeds?: { name: string; url: string }[];
+    }
+
+    const packageRelations: PackageRelation[] = [];
+
+    // Find all produced packages
+    for (const [repoPath, a] of analysis) {
+      if (a.produces) {
+        for (const product of a.produces) {
+          // Find consumers
+          const consumers: { repoName: string; version?: string }[] = [];
+          for (const [otherPath, otherA] of analysis) {
+            if (otherPath === repoPath) continue;
+            for (const dep of otherA.dependencies) {
+              if (dep.name.toLowerCase() === product.name.toLowerCase()) {
+                consumers.push({ repoName: otherA.name, version: dep.version });
+              }
+            }
+          }
+          packageRelations.push({
+            pkgName: product.name,
+            contributing: (product as any).contributing,
+            producer: a.name,
+            consumers,
+            type: product.type,
+            feeds: a.nugetFeeds,
+          });
+        }
+      }
+    }
+
+    if (packageRelations.length > 0) {
+      for (const rel of packageRelations) {
+        const contribStr = rel.contributing && rel.contributing.length > 0
+          ? rel.contributing.map(c => `\`${c}\``).join(', ')
+          : '—';
+        const consumerStr = rel.consumers.length > 0
+          ? rel.consumers.map(c => `\`${c.repoName}\` (${c.version || 'pinned'})`).join(', ')
+          : '_None_';
+        const feedStr = rel.feeds && rel.feeds.length > 0
+          ? rel.feeds.map(f => `\`${f.name}\` (${f.url})`).join('<br>')
+          : '—';
+        md.push(`| \`${rel.pkgName}\` | ${contribStr} | \`${rel.producer}\` | ${consumerStr} | ${feedStr} | \`${rel.type}\` |`);
+      }
+    } else {
+      md.push('| _No package relations detected_ | | | | | |');
+    }
+    md.push('');
+
+    // ── Local Package Development Loop Tip ──────────────────────────────
+    md.push('## 💡 Local Package Development Loop');
+    md.push('');
+    md.push('When making changes to a shared contract or client library package, follow this standard local feed loop to test and verify consumers before pushing:');
+    md.push('');
+    md.push('### For .NET / NuGet packages:');
+    md.push('1. **Pack locally**: Run `dotnet pack -c Release -o ./local-packages` inside the producing project folder.');
+    md.push('2. **Add local feed**: Configure a local feed in your consumer project\'s `NuGet.config` pointing to the `./local-packages` directory.');
+    md.push('3. **Reference local version**: Reference the package with a local development version (e.g. `3.41.0-local`) in the consuming `.csproj`.');
+    md.push('4. **Revert before merging**: Verify changes compile and tests pass, then **revert** the consuming project\'s package version reference to the official release before merging to master.');
+    md.push('');
+    md.push('### For Node.js / npm packages:');
+    md.push('1. **Link locally**: Run `npm link` inside the producing package folder.');
+    md.push('2. **Use link**: Run `npm link <package-name>` inside the consuming folder to link it.');
+    md.push('3. **Revert before merging**: Uninstall the linked package and install the official package version before committing.');
+    md.push('');
+
     // ── Write file ──────────────────────────────────────────────────────
     const outPath = path.join(workspacePath, 'nexusflow-plan.md');
     await fse.outputFile(outPath, md.join('\n'));

package/src/server.ts

@@ -897,15 +897,18 @@ app.get('/', async (c) => {
 // Serve static assets from GUI build folder
 app.use('/*', serveStatic({ root: path.relative(process.cwd(), guiPath) }));
 
-/**
- * Starts the local GUI web server.
- *
- * @param port - Port to run on.
- */
 export function startServer(port = 3000): Promise<{ port: number; server: any }> {
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     const server = serve({ fetch: app.fetch, port }, (info) => {
       resolve({ port: info.port, server });
+    }) as import('node:http').Server;
+    
+    server.on('error', (e: any) => {
+      if (e.code === 'EADDRINUSE') {
+        resolve(startServer(port + 1));
+      } else {
+        reject(e);
+      }
     });
   });
 }

package/src/types.ts

@@ -23,6 +23,12 @@ export interface NexusFlowConfig {
   /** How many directory levels deep to scan for git repos. Default: 2 */
   scanDepth: number;
 
+  /** Global patterns to exclude when packing/analyzing repositories. */
+  excludePatterns?: string[];
+
+  /** Whether to pack codebase context into XML format. Default: true */
+  packContextXml?: boolean;
+
   /** ISO timestamp of the last update check. */
   lastUpdateCheck?: string;
 
@@ -112,6 +118,9 @@ export interface Feature {
   /** Absolute paths to the repos included in this feature. */
   repos: string[];
 
+  /** Absolute paths to the original repositories. */
+  originalRepos?: string[];
+
   /** AI assistants enabled for this feature workspace. */
   assistants: AIAssistant[];
 
@@ -235,6 +244,10 @@ export interface ProjectAnalysis {
   readmeSummary: string | null;
   /** Existing AI config files found in the repo. */
   existingAIConfigs: ExistingAIConfig[];
+  /** Produced/published packages by this repo. */
+  produces?: { name: string; type: 'npm' | 'nuget' | 'other'; version?: string; contributing?: string[] }[];
+  /** NuGet feeds detected in the repo's NuGet.config files. */
+  nugetFeeds?: { name: string; url: string }[];
 }
 
 /** An existing AI configuration file found in a repo. */

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/cypress/**',
+      '**/.{idea,git,cache,output,temp}/**',
+      '**/scratch/**'
+    ]
+  }
+});