@mrpatronz/nexusflow 0.2.0 → 0.2.2

package/src/generators/plan-generator.ts

@@ -15,22 +15,11 @@ import type {
   DependencyGraph,
 } from '../types.js';
 
-// ─── Constants ────────────────────────────────────────────────────────────
-
-/** Repo-name substrings that signal a shared/foundation package. */
-const SHARED_PACKAGE_KEYWORDS = ['shared', 'common', 'contracts', 'types'];
-
-/** Project types that act as backend producers. */
-const BACKEND_TYPES = ['api', 'backend', 'service'];
-
-/** Project types that act as frontend consumers. */
-const FRONTEND_TYPES = ['frontend', 'webapp', 'app'];
-
 // ─── Dependency Graph Builder ─────────────────────────────────────────────
 
 /**
- * Build a dependency graph by analysing package dependencies, API
- * relationships and shared-package conventions across the workspace repos.
+ * Build a dependency graph by analysing package dependencies
+ * across the workspace repos.
  *
  * @param analysis  Per-repo analysis results, keyed by repo path.
  * @param repos     Metadata for every repo in the workspace.
@@ -88,67 +77,16 @@ export function buildDependencyGraph(
     for (const dep of a.dependencies) {
       const depNameLower = dep.name.toLowerCase();
 
-      // 1. Direct match with a produced package
+      // 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);
-          }
-        }
-      }
-    }
-  }
-
-  // ── 2. API relationships (frontend → backend heuristic) ─────────────
-  for (const repoA of repos) {
-    const analysisA = analysisByName.get(repoA.name);
-    if (!analysisA) continue;
-
-    const typeA = analysisA.techStack.projectType;
-
-    if (!BACKEND_TYPES.includes(typeA)) continue;
-
-    for (const repoB of repos) {
-      if (repoB.name === repoA.name) continue;
-
-      const analysisB = analysisByName.get(repoB.name);
-      if (!analysisB) continue;
-
-      const typeB = analysisB.techStack.projectType;
-      if (FRONTEND_TYPES.includes(typeB)) {
-        // B (frontend) depends on A (backend)
-        addEdge(graph, repoB.name, repoA.name);
       }
     }
   }
 
-  // ── 3. Shared-type packages are always foundation ───────────────────
-  for (const repo of repos) {
-    const isShared = SHARED_PACKAGE_KEYWORDS.some((kw) =>
-      repo.name.toLowerCase().includes(kw),
-    );
-    if (!isShared) continue;
-
-    const node = graph.get(repo.name);
-    if (!node) continue;
-
-    // Ensure no outgoing deps (it's a leaf producer)
-    node.dependsOn = [];
-
-    // Every other repo that doesn't already depend on it — add edge
-    for (const other of repos) {
-      if (other.name === repo.name) continue;
-      addEdge(graph, other.name, repo.name);
-    }
-  }
-
   return graph;
 }
 
@@ -297,25 +235,19 @@ export async function generateImplementationPlan(
 
     md.push('```');
     md.push('');
+    md.push('> ⚠️ This diagram is derived from detected package dependencies (`package.json`, `.csproj`, etc.) only.');
+    md.push('> If you changed a package, the producing repo must release/build before consumer repos can merge.');
+    md.push('');
 
     // ── Phase descriptions ──────────────────────────────────────────────
     md.push('## Suggested Implementation Order');
     md.push('');
 
-    const phaseLabels = [
-      'Foundation',
-      'Core Services',
-      'Integration Layer',
-      'Consumers',
-      'Final',
-    ];
-
     for (let i = 0; i < phases.length; i++) {
       const phase = phases[i];
-      const label = phaseLabels[Math.min(i, phaseLabels.length - 1)];
       const ordinal = ordinalWord(i + 1);
 
-      md.push(`### Phase ${i + 1}: ${label}`);
+      md.push(`### Phase ${i + 1}`);
       md.push('');
       md.push(`**Repos:** ${phase.join(', ')}`);
       md.push('');
@@ -421,6 +353,52 @@ export async function generateImplementationPlan(
     }
     md.push('');
 
+    // ── Cross-Repo Messaging Roll-up ────────────────────────────────────
+    md.push('## 📨 Cross-Repo Messaging');
+    md.push('');
+    md.push('| Publisher Repo | Message | → Subscriber Repo | Handler |');
+    md.push('|---|---|---|---|');
+
+    interface CrossRepoMessage {
+      pubRepo: string;
+      message: string;
+      subRepo: string;
+      handler: string;
+    }
+    const crossRepoMessages: CrossRepoMessage[] = [];
+
+    for (const [pubPath, pubA] of analysis) {
+      if (!pubA.messaging || !pubA.messaging.publishers) continue;
+      for (const pub of pubA.messaging.publishers) {
+        // Find subscribers in other repos matching this contract type
+        for (const [subPath, subA] of analysis) {
+          if (subPath === pubPath) continue;
+          if (!subA.messaging || !subA.messaging.subscribers) continue;
+          for (const sub of subA.messaging.subscribers) {
+            const pubContract = pub.contractType.toLowerCase().trim();
+            const subContract = sub.contractType.toLowerCase().trim();
+            if (pubContract === subContract && pubContract !== 'goservicebusmessage' && pubContract !== 'servicebusmessage') {
+              crossRepoMessages.push({
+                pubRepo: pubA.name,
+                message: pub.contractType,
+                subRepo: subA.name,
+                handler: sub.handlerFile,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (crossRepoMessages.length > 0) {
+      for (const m of crossRepoMessages) {
+        md.push(`| \`${m.pubRepo}\` | \`${m.message}\` | \`${m.subRepo}\` | \`${m.handler}\` |`);
+      }
+    } else {
+      md.push('| _No cross-repo messaging detected_ | | | |');
+    }
+    md.push('');
+
     // ── Local Package Development Loop Tip ──────────────────────────────
     md.push('## 💡 Local Package Development Loop');
     md.push('');

package/src/generators/skills-generator.ts

@@ -0,0 +1,255 @@
+/**
+ * @module generators/skills-generator
+ * Generates harness-specific agent skills/rules (e.g. for Claude, Cursor, Copilot, Codex)
+ * dynamically based on workspace analysis.
+ */
+
+import * as fse from 'fs-extra';
+import * as path from 'node:path';
+import type { AIAssistant, WorkspaceContext, ProjectAnalysis } from '../types.js';
+
+/**
+ * Checks if the workspace has cross-repo package dependencies.
+ */
+function hasCrossRepoDependencies(analysis: Map<string, ProjectAnalysis>): boolean {
+  const produced = new Set<string>();
+  for (const [, a] of analysis) {
+    if (a.produces) {
+      for (const p of a.produces) {
+        produced.add(p.name.toLowerCase());
+      }
+    }
+  }
+
+  for (const [, a] of analysis) {
+    for (const dep of a.dependencies) {
+      if (produced.has(dep.name.toLowerCase())) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Checks if any workspace project produces packages that have consumer repos.
+ */
+function hasProducedPackagesWithConsumers(analysis: Map<string, ProjectAnalysis>): boolean {
+  return hasCrossRepoDependencies(analysis); // Same logic: at least one consumer depends on a producer
+}
+
+/**
+ * Generates local package loop skill instructions.
+ */
+function getLocalPackageLoopSkill(analysis: Map<string, ProjectAnalysis>): string {
+  let pkgManagerInfo = '';
+  const hasNuget = Array.from(analysis.values()).some(a => a.techStack.languages.includes('csharp'));
+  const hasNpm = Array.from(analysis.values()).some(a => a.techStack.languages.includes('typescript') || a.techStack.languages.includes('javascript'));
+
+  if (hasNuget) {
+    pkgManagerInfo += `### NuGet / C# local loop:
+1. **Pack locally**: Run \`dotnet pack -c Release -o ./local-packages\` inside the producing project folder.
+2. **Add local feed**: Ensure the consumer project's directory has a local NuGet feed configured pointing to the \`local-packages\` directory at the workspace root.
+3. **Reference local version**: Update the consumer's package reference in its \`.csproj\` to point to the local version (e.g., \`1.0.0-local\`).
+4. **Revert**: Ensure you revert the package reference to the official release version before submitting code.
+`;
+  }
+  if (hasNpm) {
+    pkgManagerInfo += `### npm / JS/TS local loop:
+1. **Pack locally**: Run \`npm pack\` inside the producing package directory.
+2. **Copy / Reference**: Copy the generated \`.tgz\` file to a \`local-packages/\` directory.
+3. **Reference local version**: Run \`npm install ../local-packages/my-package-1.0.0.tgz\` or reference it in \`package.json\`.
+4. **Revert**: Revert the local reference to the official registry package before submitting code.
+`;
+  }
+
+  return `# Local Package Development Loop
+
+This skill guides the AI assistant through local package testing across repositories in this workspace.
+
+## Workflow
+
+When modifying a shared package in one repository, you must test its effect on downstream consumer repositories before pushing.
+
+${pkgManagerInfo}
+
+## Guidelines
+- **Leave a TODO comment**: Always write a \`// TODO: Revert local package loop reference\` comment in the consumer code so you don't commit temporary local reference modifications.
+- **Do not commit local-packages**: The \`local-packages/\` folder is workspace-local and must not be committed to Git.
+`;
+}
+
+/**
+ * Generates release ordering skill instructions.
+ */
+function getReleaseOrderingSkill(ctx: WorkspaceContext): string {
+  const { analysis } = ctx;
+  const lines: string[] = [];
+
+  lines.push('# Release and Merge Ordering Guidelines');
+  lines.push('');
+  lines.push('This guideline answers what repositories must be merged and released in what order when cross-repo dependencies are modified.');
+  lines.push('');
+  lines.push('## Dependency Chains');
+
+  if (analysis) {
+    for (const [path, a] of analysis) {
+      if (a.produces && a.produces.length > 0) {
+        for (const p of a.produces) {
+          const consumers: string[] = [];
+          for (const [otherPath, otherA] of analysis) {
+            if (otherPath === path) continue;
+            for (const dep of otherA.dependencies) {
+              if (dep.name.toLowerCase() === p.name.toLowerCase()) {
+                consumers.push(otherA.name);
+              }
+            }
+          }
+          if (consumers.length > 0) {
+            lines.push(`- **Product**: \`${p.name}\``);
+            lines.push(`  - **Producer**: \`${a.name}\` (Must build and release first)`);
+            lines.push(`  - **Consumers**: ${consumers.map(c => `\`${c}\``).join(', ')} (Must be bumped and released after the producer)`);
+          }
+        }
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('## Reversion Check');
+  lines.push('- Before merging a consumer branch, verify that all local package loop references are replaced by official versions.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generates local runtime verifier instructions.
+ */
+function getVerifierSkill(ctx: WorkspaceContext): string {
+  const { analysis } = ctx;
+  const lines: string[] = [];
+
+  lines.push('# Workspace Local Runtime Verifier');
+  lines.push('');
+  lines.push('Guidelines to safely launch, mock, and verify services locally in this workspace.');
+  lines.push('');
+
+  let hasInfraWarnings = false;
+
+  if (analysis) {
+    for (const [, a] of analysis) {
+      if (a.runConfig && a.runConfig.sharedInfraWarnings.length > 0) {
+        if (!hasInfraWarnings) {
+          lines.push('## ⚠️ Shared Infrastructure Warnings');
+          hasInfraWarnings = true;
+        }
+        for (const warning of a.runConfig.sharedInfraWarnings) {
+          lines.push(`- **${a.name}**: ${warning.warning}`);
+        }
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('## Verification Recipe');
+  lines.push('1. **Check local ports**: Ensure target ports do not conflict.');
+  lines.push('2. **Run mocks**: Spin up local databases/caches before starting services.');
+  lines.push('3. **Watch out for shared staging environment**: Never publish messages or write data to staging infrastructure while testing locally unless explicitly requested.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Deploys skills files to the specified harness's directory structure.
+ */
+async function deploySkill(
+  workspacePath: string,
+  assistant: AIAssistant,
+  skillName: string,
+  content: string,
+): Promise<void> {
+  const titleMap: Record<string, string> = {
+    'nexusflow-local-package-loop': 'Local Package Development Loop',
+    'nexusflow-release-ordering': 'Release and Merge Ordering',
+    'verifier-workspace': 'Local Runtime Verifier',
+  };
+  const title = titleMap[skillName] || skillName;
+
+  if (assistant === 'claude' || assistant === 'antigravity') {
+    const skillDir = path.join(workspacePath, '.claude', 'skills', skillName);
+    await fse.ensureDir(skillDir);
+    await fse.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+  } else if (assistant === 'cursor') {
+    const ruleDir = path.join(workspacePath, '.cursor', 'rules');
+    await fse.ensureDir(ruleDir);
+    const mdcContent = `---
+description: "Guidelines and instructions for ${title}"
+alwaysApply: false
+---
+
+${content}`;
+    await fse.writeFile(path.join(ruleDir, `${skillName}.mdc`), mdcContent, 'utf-8');
+  } else if (assistant === 'copilot') {
+    const copilotDir = path.join(workspacePath, '.github', 'instructions');
+    await fse.ensureDir(copilotDir);
+    await fse.writeFile(path.join(copilotDir, `${skillName}.instructions.md`), content, 'utf-8');
+  } else if (assistant === 'codex') {
+    const codexDir = path.join(workspacePath, '.codex', 'skills', skillName);
+    await fse.ensureDir(codexDir);
+    await fse.writeFile(path.join(codexDir, 'SKILL.md'), content, 'utf-8');
+  }
+}
+
+/**
+ * Generates custom skills/rules for each selected AI assistant.
+ *
+ * @param ctx           - The workspace context.
+ * @param assistants    - The active AI assistant harnesses.
+ * @param workspacePath - The workspace root directory.
+ */
+export async function generateSkills(
+  ctx: WorkspaceContext,
+  assistants: AIAssistant[],
+  workspacePath: string,
+): Promise<void> {
+  const { analysis } = ctx;
+  if (!analysis) return;
+
+  const hasDeps = hasCrossRepoDependencies(analysis);
+  const hasProds = hasProducedPackagesWithConsumers(analysis);
+  const hasRunConfig = Array.from(analysis.values()).some(a => a.runConfig && a.runConfig.entryPoints.length > 0);
+
+  const skillsToDeploy: { name: string; content: string }[] = [];
+
+  if (hasDeps) {
+    skillsToDeploy.push({
+      name: 'nexusflow-local-package-loop',
+      content: getLocalPackageLoopSkill(analysis),
+    });
+  }
+
+  if (hasProds) {
+    skillsToDeploy.push({
+      name: 'nexusflow-release-ordering',
+      content: getReleaseOrderingSkill(ctx),
+    });
+  }
+
+  if (hasRunConfig) {
+    skillsToDeploy.push({
+      name: 'verifier-workspace',
+      content: getVerifierSkill(ctx),
+    });
+  }
+
+  for (const assistant of assistants) {
+    for (const skill of skillsToDeploy) {
+      try {
+        await deploySkill(workspacePath, assistant, skill.name, skill.content);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`  ✖ Failed to deploy skill ${skill.name} for ${assistant}: ${msg}`);
+      }
+    }
+  }
+}

package/src/mcp/server.ts

@@ -216,98 +216,25 @@ export async function startMcpServer(workspacePath?: string) {
     }
 
     if (name === 'get_workspace_graph') {
-      try {
-        const graphPath = path.join(resolvedWorkspacePath, 'nexusflow-graph.json');
-        
-        try {
-          await fs.access(graphPath);
-        } catch {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Workspace graph file not found at ${graphPath}. Run "nexusflow sync" or rebuild the workspace to generate it.`,
-              },
-            ],
-            isError: true,
-          };
-        }
-
-        const content = await fs.readFile(graphPath, 'utf8');
-        return {
-          content: [
-            {
-              type: 'text',
-              text: content,
-            },
-          ],
-        };
-      } catch (error: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Error reading workspace graph: ${error.message}`,
-            },
-          ],
-          isError: true,
-        };
-      }
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'This tool has been deprecated. Use nexusflow-plan.md for dependency information.',
+          },
+        ],
+      };
     }
 
     if (name === 'query_workspace_graph') {
-      const nodeType = (args as any).nodeType;
-      const edgeType = (args as any).edgeType;
-
-      try {
-        const graphPath = path.join(resolvedWorkspacePath, 'nexusflow-graph.json');
-        
-        try {
-          await fs.access(graphPath);
-        } catch {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Workspace graph file not found at ${graphPath}. Run "nexusflow sync" or rebuild the workspace to generate it.`,
-              },
-            ],
-            isError: true,
-          };
-        }
-
-        const content = await fs.readFile(graphPath, 'utf8');
-        const graph = JSON.parse(content);
-
-        let nodes = graph.nodes;
-        let edges = graph.edges;
-
-        if (nodeType) {
-          nodes = nodes.filter((n: any) => n.type === nodeType);
-        }
-        if (edgeType) {
-          edges = edges.filter((e: any) => e.type === edgeType);
-        }
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify({ nodes, edges }, null, 2),
-            },
-          ],
-        };
-      } catch (error: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Error querying workspace graph: ${error.message}`,
-            },
-          ],
-          isError: true,
-        };
-      }
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'This tool has been deprecated. Use nexusflow-plan.md for dependency information.',
+          },
+        ],
+      };
     }
 
     throw new Error(`Tool not found: ${name}`);

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

@@ -248,6 +248,60 @@ export interface ProjectAnalysis {
   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 }[];
+  /** Detected messaging topology. */
+  messaging?: MessagingTopology;
+  /** Detected run configurations. */
+  runConfig?: RunConfig;
+}
+
+export interface MessagePublisher {
+  contractType: string;
+  topicOrQueue: string;
+  publisherFile: string;
+}
+
+export interface MessageSubscriber {
+  contractType: string;
+  handlerFile: string;
+  registrationFile: string;
+}
+
+export interface MessagingTopology {
+  publishers: MessagePublisher[];
+  subscribers: MessageSubscriber[];
+}
+
+export interface RunConfigEntryPoint {
+  projectPath: string;
+  type: string;
+  command?: string;
+  port?: number;
+}
+
+export interface RunConfigDatabase {
+  provider: string;
+  host: string;
+  configFile: string;
+}
+
+export interface RunConfigSharedInfraWarning {
+  resource: string;
+  host: string;
+  configFile: string;
+  warning: string;
+}
+
+export interface RunConfigSecret {
+  file: string;
+  lineHint: string;
+}
+
+export interface RunConfig {
+  entryPoints: RunConfigEntryPoint[];
+  databases: RunConfigDatabase[];
+  sharedInfraWarnings: RunConfigSharedInfraWarning[];
+  committedSecrets: RunConfigSecret[];
+  externalDependencies: string[];
 }
 
 /** An existing AI configuration file found in a repo. */