@mrpatronz/nexusflow 0.1.5 → 0.1.7

package/src/core/graph.ts

@@ -0,0 +1,345 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execa } from 'execa';
+import type { WorkspaceContext, RepoInfo } from '../types.js';
+
+export interface GraphNode {
+  id: string;
+  type: 'repo' | 'package' | 'endpoint' | 'port';
+  name: string;
+  metadata: Record<string, any>;
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  type: 'CONTAINS' | 'DEPENDS_ON' | 'EXPOSES' | 'CALLS';
+  metadata?: Record<string, any>;
+}
+
+export interface WorkspaceGraph {
+  workspaceId: string;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+/**
+ * Builds a structural and API interaction graph across all repos in a workspace.
+ */
+export async function buildWorkspaceGraph(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<WorkspaceGraph> {
+  const { feature, repos, analysis } = ctx;
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+
+  // 1. Add Repository Nodes
+  for (const repo of repos) {
+    const a = analysis?.get(repo.path);
+    nodes.push({
+      id: `repo:${repo.name}`,
+      type: 'repo',
+      name: repo.name,
+      metadata: {
+        path: repo.path,
+        techStack: a?.techStack || null,
+        description: a?.readmeSummary || '',
+      },
+    });
+  }
+
+  // 2. Add API Endpoint and Port Nodes, and EXPOSES Edges
+  const allEndpoints: { endpointId: string; method: string; path: string; repoName: string }[] = [];
+  
+  if (analysis) {
+    for (const repo of repos) {
+      const a = analysis.get(repo.path);
+      if (!a) continue;
+
+      // Add Ports
+      for (const p of a.ports) {
+        const portId = `port:${repo.name}:${p.port}`;
+        nodes.push({
+          id: portId,
+          type: 'port',
+          name: `${p.port}`,
+          metadata: {
+            protocol: p.protocol,
+            source: p.source,
+          },
+        });
+        edges.push({
+          source: `repo:${repo.name}`,
+          target: portId,
+          type: 'EXPOSES',
+        });
+      }
+
+      // Add API Endpoints
+      for (const ep of a.endpoints) {
+        const endpointId = `endpoint:${repo.name}:${ep.method}:${ep.path}`;
+        nodes.push({
+          id: endpointId,
+          type: 'endpoint',
+          name: `${ep.method} ${ep.path}`,
+          metadata: {
+            method: ep.method,
+            path: ep.path,
+            source: ep.source,
+          },
+        });
+        edges.push({
+          source: `repo:${repo.name}`,
+          target: endpointId,
+          type: 'EXPOSES',
+        });
+
+        allEndpoints.push({
+          endpointId,
+          method: ep.method,
+          path: ep.path,
+          repoName: repo.name,
+        });
+      }
+
+      // Add package dependencies
+      for (const dep of a.dependencies) {
+        const packageId = `package:${dep.type}:${dep.name}`;
+        if (!nodes.some((n) => n.id === packageId)) {
+          nodes.push({
+            id: packageId,
+            type: 'package',
+            name: dep.name,
+            metadata: {
+              manager: dep.type,
+              version: dep.version || 'latest',
+            },
+          });
+        }
+        edges.push({
+          source: `repo:${repo.name}`,
+          target: packageId,
+          type: 'DEPENDS_ON',
+        });
+      }
+    }
+  }
+
+  // 3. Add inter-repo DEPENDS_ON edges
+  if (analysis) {
+    const repoAnalyses = new Map(repos.map((r) => [r.path, analysis.get(r.path)?.dependencies || []]));
+    const repoNames = new Map(repos.map((r) => [r.path, r.name]));
+    const { findInterRepoDependencies } = await import('../analyzers/detect-deps.js');
+    const interDeps = findInterRepoDependencies(repoAnalyses, repoNames);
+
+    for (const [caller, callees] of interDeps) {
+      for (const callee of callees) {
+        edges.push({
+          source: `repo:${caller}`,
+          target: `repo:${callee}`,
+          type: 'DEPENDS_ON',
+          metadata: { relation: 'repo-to-repo' },
+        });
+      }
+    }
+  }
+
+  // 4. Detect CALLS Edges using git grep inside worktrees
+  for (const ep of allEndpoints) {
+    const pathQuery = ep.path;
+    // Skip very short or generic paths to avoid false positives and noise
+    if (!pathQuery || pathQuery.length < 4 || pathQuery === '/api' || pathQuery === '/dev') continue;
+
+    for (const repo of repos) {
+      if (repo.name === ep.repoName) continue; // Skip self
+
+      const worktreePath = path.join(workspacePath, repo.name);
+      try {
+        await fs.access(worktreePath);
+        // Use git grep to find references to this endpoint path in other worktrees
+        const { stdout } = await execa('git', ['grep', '-l', '-F', pathQuery], {
+          cwd: worktreePath,
+          reject: false,
+        });
+
+        if (stdout && stdout.trim()) {
+          const files = stdout.split('\n').filter(Boolean);
+          edges.push({
+            source: `repo:${repo.name}`,
+            target: ep.endpointId,
+            type: 'CALLS',
+            metadata: {
+              files,
+              reason: `References endpoint path '${pathQuery}'`,
+            },
+          });
+        }
+      } catch {
+        // Ignore git grep failures
+      }
+    }
+  }
+
+  return {
+    workspaceId: feature.id,
+    nodes,
+    edges,
+  };
+}
+
+/**
+ * Builds a Mermaid Flowchart representation of the workspace architecture graph.
+ */
+export function buildMermaidDiagram(graph: WorkspaceGraph): string {
+  const lines: string[] = ['flowchart TD'];
+
+  lines.push('  classDef repo fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#fff;');
+  lines.push('  classDef endpoint fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff;');
+  lines.push('  classDef port fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff;');
+  lines.push('  classDef package fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff;');
+
+  // Render Repo nodes
+  for (const n of graph.nodes) {
+    if (n.type === 'repo') {
+      lines.push(`  ${n.id}["📦 ${n.name}"]:::repo`);
+    }
+  }
+
+  // Render edges between repos
+  const repoEdges = graph.edges.filter(
+    (e) => e.source.startsWith('repo:') && e.target.startsWith('repo:'),
+  );
+  for (const e of repoEdges) {
+    lines.push(`  ${e.source} -->|depends on| ${e.target}`);
+  }
+
+  // Render API calls and endpoint interactions
+  const callsEdges = graph.edges.filter((e) => e.type === 'CALLS');
+  const referencedEndpointIds = new Set(callsEdges.map((e) => e.target));
+
+  for (const n of graph.nodes) {
+    if (n.type === 'endpoint' && referencedEndpointIds.has(n.id)) {
+      lines.push(`  ${n.id}["🔌 ${n.name}"]:::endpoint`);
+    }
+  }
+
+  for (const e of callsEdges) {
+    lines.push(`  ${e.source} -->|calls| ${e.target}`);
+  }
+
+  // Render exposures from endpoints to their parent repos
+  const exposesEdges = graph.edges.filter(
+    (e) => e.type === 'EXPOSES' && referencedEndpointIds.has(e.target),
+  );
+  for (const e of exposesEdges) {
+    lines.push(`  ${e.target} -.->|exposed by| ${e.source}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats the graph as a human/LLM-readable markdown guide.
+ */
+export function generateGraphMarkdownContent(graph: WorkspaceGraph): string {
+  const repoNodes = graph.nodes.filter((n) => n.type === 'repo');
+  const mermaid = buildMermaidDiagram(graph);
+
+  const lines: string[] = [
+    `# Workspace Architecture Graph — ${graph.workspaceId}`,
+    '',
+    '> **Token-Efficient Architecture Guide**: This file defines the entities, dependencies,',
+    '> and API call relationships of your multi-repository workspace. Use this map to navigate',
+    '> relationships without having to read through all repository directories.',
+    '',
+    '## Workspace Relations Diagram',
+    '',
+    '```mermaid',
+    mermaid,
+    '```',
+    '',
+    '## 📦 Repositories',
+    '',
+  ];
+
+  for (const repo of repoNodes) {
+    lines.push(`### ${repo.name}`);
+    lines.push(`- **Path**: \`${repo.metadata.path}\``);
+    if (repo.metadata.techStack) {
+      const ts = repo.metadata.techStack;
+      lines.push(`- **Languages**: ${ts.languages.join(', ')}`);
+      if (ts.frameworks.length > 0) {
+        lines.push(`- **Frameworks**: ${ts.frameworks.join(', ')}`);
+      }
+    }
+    
+    // Dependencies
+    const deps = graph.edges
+      .filter((e) => e.source === repo.id && e.target.startsWith('package:'))
+      .map((e) => {
+        const pkgNode = graph.nodes.find((n) => n.id === e.target);
+        return pkgNode ? `\`${pkgNode.name}\` (${pkgNode.metadata.manager})` : '';
+      })
+      .filter(Boolean);
+
+    if (deps.length > 0) {
+      lines.push(`- **Dependencies**: ${deps.slice(0, 10).join(', ')}${deps.length > 10 ? ` (+${deps.length - 10} more)` : ''}`);
+    }
+
+    // Exposed APIs
+    const exposed = graph.edges
+      .filter((e) => e.source === repo.id && e.target.startsWith('endpoint:'))
+      .map((e) => {
+        const ep = graph.nodes.find((n) => n.id === e.target);
+        return ep ? `\`${ep.name}\`` : '';
+      })
+      .filter(Boolean);
+
+    if (exposed.length > 0) {
+      lines.push(`- **Exposed APIs**: ${exposed.slice(0, 5).join(', ')}${exposed.length > 5 ? ` (+${exposed.length - 5} more)` : ''}`);
+    }
+
+    // API calls made
+    const calls = graph.edges
+      .filter((e) => e.source === repo.id && e.type === 'CALLS')
+      .map((e) => {
+        const ep = graph.nodes.find((n) => n.id === e.target);
+        return ep ? `\`${ep.name}\` (exposed by \`${ep.id.split(':')[1]}\`)` : '';
+      })
+      .filter(Boolean);
+
+    if (calls.length > 0) {
+      lines.push(`- **Calls Endpoints**: ${calls.join(', ')}`);
+    }
+    
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds the graph, writes `nexusflow-graph.json` and `nexusflow-graph.md` to workspace root.
+ */
+export async function generateWorkspaceGraphFiles(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  try {
+    const graph = await buildWorkspaceGraph(ctx, workspacePath);
+    
+    // Write JSON file
+    const jsonPath = path.join(workspacePath, 'nexusflow-graph.json');
+    await fs.writeFile(jsonPath, JSON.stringify(graph, null, 2), 'utf-8');
+
+    // Write MD file
+    const mdPath = path.join(workspacePath, 'nexusflow-graph.md');
+    const mdContent = generateGraphMarkdownContent(graph);
+    await fs.writeFile(mdPath, mdContent, 'utf-8');
+
+    console.log('  ✔ Generated Workspace Architecture Graph (nexusflow-graph.json / nexusflow-graph.md)');
+  } catch (error: any) {
+    console.error('  ✖ Failed to generate workspace architecture graph:', error.message);
+  }
+}

package/src/core/packer.ts

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import * as path from 'node:path';
+import { runCli } from 'repomix';
+import { loadFeatureConfig } from './workspace.js';
+
+export interface PackResult {
+  outputPath: string;
+  totalFiles: number;
+  totalCharacters: number;
+  fileSize: number;
+}
+
+/**
+ * Packs all repositories in a workspace into a single, compressed XML file using Repomix.
+ */
+export async function packWorkspace(
+  workspacePath: string,
+  options: { compress?: boolean } = {}
+): Promise<PackResult> {
+  const feature = await loadFeatureConfig(workspacePath);
+  if (!feature) {
+    throw new Error(`Workspace not found at ${workspacePath}`);
+  }
+
+  const compress = options.compress !== false; // default true
+  const outputPath = path.join(workspacePath, 'nexusflow-context.xml');
+  
+  // Use a write stream to avoid buffering huge workspaces in memory
+  const outStream = createWriteStream(outputPath, { encoding: 'utf-8' });
+  
+  outStream.write('<?xml version="1.0" encoding="UTF-8"?>\n');
+  outStream.write(`<workspace id="${feature.id}">\n`);
+  outStream.write(`  <description><![CDATA[${feature.description}]]></description>\n`);
+  outStream.write('  <repositories>\n');
+  
+  let totalFilesCount = 0;
+  let totalCharsCount = 0;
+
+  for (const repoPath of feature.repos) {
+    const repoName = path.basename(repoPath);
+    const worktreePath = path.join(workspacePath, repoName);
+
+    try {
+      await fs.access(worktreePath);
+    } catch {
+      continue;
+    }
+
+    const tempXmlPath = path.join(workspacePath, `temp-repomix-${repoName}.xml`);
+
+    try {
+      // Run repomix programmatically inside the worktree directory
+      const result = await runCli(['.'], worktreePath, {
+        style: 'xml',
+        output: tempXmlPath,
+        compress,
+        quiet: true,
+      });
+
+      if (result && result.packResult) {
+        totalFilesCount += result.packResult.totalFiles;
+        totalCharsCount += result.packResult.totalCharacters;
+      }
+
+      outStream.write(`    <repository name="${repoName}">\n`);
+      
+      // Stream output XML directly to avoid memory limits
+      await pipeline(
+        createReadStream(tempXmlPath, { encoding: 'utf-8' }),
+        outStream,
+        { end: false }
+      );
+      
+      outStream.write('\n    </repository>\n');
+    } catch (error: any) {
+      console.error(`Error packing repository ${repoName}:`, error.message);
+    } finally {
+      // Clean up temporary XML file
+      try {
+        await fs.unlink(tempXmlPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  outStream.write('  </repositories>\n');
+  outStream.write('</workspace>\n');
+  outStream.end();
+
+  // Wait for stream to finish writing
+  await new Promise<void>((resolve, reject) => {
+    outStream.on('finish', resolve);
+    outStream.on('error', reject);
+  });
+
+  const stats = await fs.stat(outputPath);
+
+  return {
+    outputPath,
+    totalFiles: totalFilesCount,
+    totalCharacters: totalCharsCount,
+    fileSize: stats.size,
+  };
+}
+

package/src/generators/index.ts

@@ -8,6 +8,7 @@ import { generateCopilotConfig } from './copilot.js';
 import { generateCursorConfig } from './cursor.js';
 import { buildContextContent } from './base.js';
 import { generateImplementationPlan } from './plan-generator.js';
+import { generateWorkspaceGraphFiles } from '../core/graph.js';
 
 /** Maps each assistant to its generator function and the file it produces. */
 const GENERATORS: Record<
@@ -156,6 +157,17 @@ export async function generateContextFiles(
     }
   }
 
+  // Generate Workspace Architecture Graph
+  try {
+    await generateWorkspaceGraphFiles(ctx, workspacePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      chalk.red('  ✖'),
+      `Failed to generate workspace architecture graph: ${message}`,
+    );
+  }
+
   // Generate implementation plan from dependency analysis (if analysis data available)
   try {
     await generateImplementationPlan(ctx, workspacePath);

package/src/index.ts

@@ -23,6 +23,7 @@ import { uiCommand } from './commands/ui.js';
 import { syncCommand } from './commands/sync.js';
 import { commitCommand } from './commands/commit.js';
 import { diffCommand } from './commands/diff.js';
+import { packCommand } from './commands/pack.js';
 import { mcpRunCommand, mcpSetupCommand } from './commands/mcp.js';
 import { getCurrentVersion, checkForUpdates, printUpdateBanner } from './utils/update-check.js';
 
@@ -234,6 +235,24 @@ program
     }
   });
 
+program
+  .command('pack')
+  .description('Pack the workspace codebase into a single token-efficient XML file for AI consumption')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .option('--no-compress', 'Do not compress files (strip comments, empty lines)')
+  .action(async (workspace: string | undefined, options: { compress?: boolean }) => {
+    try {
+      await packCommand(workspace, options);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('User force closed')) {
+        console.log('\nCancelled.');
+        process.exit(0);
+      }
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
 const mcp = program.command('mcp').description('Manage the NexusFlow MCP Server for AI assistants');
 
 mcp

package/src/mcp/server.ts

@@ -66,6 +66,42 @@ export async function startMcpServer(workspacePath?: string) {
             required: ['serviceName'],
           },
         },
+        {
+          name: 'get_workspace_graph',
+          description: 'Retrieve the structural architecture graph of the NexusFlow workspace. Contains nodes for repos, packages, API endpoints, and exposed ports, plus relation edges (CONTAINS, DEPENDS_ON, EXPOSES, CALLS). Highly token-efficient for global workspace context.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              workspaceId: {
+                type: 'string',
+                description: 'Optional ID/branchName of the workspace. If omitted, uses the currently active workspace.',
+              },
+            },
+          },
+        },
+        {
+          name: 'query_workspace_graph',
+          description: 'Query the workspace architecture graph by filtering nodes or edges (e.g., node types like "repo", "package", "endpoint", "port", or edge types like "DEPENDS_ON", "EXPOSES", "CALLS"). Reduces token payload by fetching specific architectural paths.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              nodeType: {
+                type: 'string',
+                enum: ['repo', 'package', 'endpoint', 'port'],
+                description: 'Optional node type to filter.',
+              },
+              edgeType: {
+                type: 'string',
+                enum: ['DEPENDS_ON', 'EXPOSES', 'CALLS'],
+                description: 'Optional edge/relation type to filter.',
+              },
+              workspaceId: {
+                type: 'string',
+                description: 'Optional ID/branchName of the workspace. If omitted, uses the currently active workspace.',
+              },
+            },
+          },
+        },
       ],
     };
   });
@@ -179,6 +215,101 @@ 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,
+        };
+      }
+    }
+
+    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,
+        };
+      }
+    }
+
     throw new Error(`Tool not found: ${name}`);
   });
 

package/src/server.ts

@@ -17,6 +17,7 @@ import { scanForRepos } from './core/scanner.js';
 import { createWorkspace, listWorkspaces, loadFeatureConfig } from './core/workspace.js';
 import { analyzeAllRepos } from './analyzers/index.js';
 import { generateContextFiles } from './generators/index.js';
+import { packWorkspace } from './core/packer.js';
 import { detectAIAssistants } from './utils/detect-ai.js';
 import { detectEditors } from './utils/detect-editors.js';
 import { findSessions, getSessionTranscript } from './utils/session-finder.js';
@@ -606,6 +607,30 @@ app.get('/api/update-status', async (c) => {
   }
 });
 
+// 18. Pack workspace codebase and download
+app.get('/api/workspace/:id/pack', async (c) => {
+  try {
+    const id = decodeURIComponent(c.req.param('id'));
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+
+    const feature = await loadFeatureConfig(workspacePath);
+    if (!feature) {
+      return c.json({ error: 'Workspace configuration not found.' }, 404);
+    }
+
+    const result = await packWorkspace(workspacePath);
+    const content = await fs.readFile(result.outputPath, 'utf-8');
+
+    c.header('Content-Disposition', `attachment; filename="nexusflow-context-${id.replace(/[\/\\ ]/g, '-')}.xml"`);
+    c.header('Content-Type', 'application/xml');
+    return c.text(content);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
 // Serve index.html explicitly on root endpoint
 app.get('/', async (c) => {
   try {