@mrpatronz/nexusflow 0.2.1 → 0.2.2

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/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. */