@mrpatronz/nexusflow 0.1.4 → 0.1.6

package/src/commands/pack.ts

@@ -0,0 +1,73 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { select } from '@inquirer/prompts';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces, loadFeatureConfig } from '../core/workspace.js';
+import { packWorkspace } from '../core/packer.js';
+
+/**
+ * Packs the workspace codebase into a single token-efficient XML file.
+ */
+export async function packCommand(
+  workspaceArg?: string,
+  options: { compress?: boolean } = {}
+): Promise<void> {
+  console.log(chalk.bold.cyan('\n📦 NexusFlow — Codebase Context Packing\n'));
+
+  const workspacePath = await resolveWorkspace(workspaceArg);
+  if (!workspacePath) return;
+
+  const spinner = ora('Packing workspace repositories using Repomix...').start();
+  try {
+    const result = await packWorkspace(workspacePath, { compress: options.compress });
+    spinner.succeed('Workspace packed successfully!');
+
+    console.log(`\n📄 ${chalk.bold('Packed Output File:')} ${chalk.green(result.outputPath)}`);
+    console.log(`📊 ${chalk.bold('Total Files:')}       ${result.totalFiles}`);
+    console.log(`🔠 ${chalk.bold('Total Characters:')}  ${result.totalCharacters}`);
+    console.log(`💾 ${chalk.bold('File Size:')}        ${(result.fileSize / 1024).toFixed(2)} KB\n`);
+  } catch (error: any) {
+    spinner.fail('Failed to pack workspace');
+    console.error(chalk.red(`  Error: ${error.message}`));
+  }
+}
+
+/**
+ * Resolves the workspace path from argument, cwd, or list.
+ */
+async function resolveWorkspace(workspaceArg?: string): Promise<string | null> {
+  if (workspaceArg) {
+    const absolutePath = path.resolve(workspaceArg);
+    try {
+      await fs.access(path.join(absolutePath, 'nexusflow.json'));
+      return absolutePath;
+    } catch {
+      console.error(chalk.red(`✖ Invalid workspace: No nexusflow.json found at ${absolutePath}`));
+      return null;
+    }
+  }
+
+  const cwdFeature = await loadFeatureConfig(process.cwd());
+  if (cwdFeature) return process.cwd();
+
+  const config = await loadConfig();
+  const workspaces = await listWorkspaces(config.workspacesDir);
+
+  if (workspaces.length === 0) {
+    console.log(chalk.yellow('No workspaces found.\n'));
+    return null;
+  }
+
+  const selected = await select({
+    message: 'Select a workspace to pack:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}

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,107 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execa } from 'execa';
+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 reposXmlData: { repoName: string; xmlContent: string }[] = [];
+  
+  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`);
+
+    // Build repomix arguments
+    const args = ['repomix', '--style', 'xml', '--output', tempXmlPath];
+    if (compress) {
+      args.push('--compress');
+    }
+
+    try {
+      // Run repomix inside the worktree directory
+      await execa('npx', args, { cwd: worktreePath });
+
+      // Read output XML
+      const xmlContent = await fs.readFile(tempXmlPath, 'utf8');
+
+      // Estimate file and character counts
+      const fileMatches = xmlContent.match(/<file\s+path=/gi) || [];
+      totalFilesCount += fileMatches.length;
+      totalCharsCount += xmlContent.length;
+
+      reposXmlData.push({
+        repoName,
+        xmlContent,
+      });
+    } catch (error: any) {
+      console.error(`Error packing repository ${repoName}:`, error.message);
+    } finally {
+      // Clean up temporary XML file
+      try {
+        await fs.unlink(tempXmlPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // Combine reposXmlData into a single XML structure
+  const xmlLines: string[] = [];
+  xmlLines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  xmlLines.push(`<workspace id="${feature.id}">`);
+  xmlLines.push(`  <description><![CDATA[${feature.description}]]></description>`);
+  xmlLines.push('  <repositories>');
+
+  for (const repo of reposXmlData) {
+    xmlLines.push(`    <repository name="${repo.repoName}">`);
+    xmlLines.push(repo.xmlContent);
+    xmlLines.push('    </repository>');
+  }
+
+  xmlLines.push('  </repositories>');
+  xmlLines.push('</workspace>');
+  xmlLines.push('');
+
+  const outputXmlContent = xmlLines.join('\n');
+  const outputPath = path.join(workspacePath, 'nexusflow-context.xml');
+  await fs.writeFile(outputPath, outputXmlContent, 'utf-8');
+
+  const stats = await fs.stat(outputPath);
+
+  return {
+    outputPath,
+    totalFiles: totalFilesCount,
+    totalCharacters: totalCharsCount,
+    fileSize: stats.size,
+  };
+}

package/src/core/worktree.ts

@@ -32,6 +32,23 @@ export async function createWorktree(
     // Silently ignore fetch failures (e.g., offline or no remote origin)
   }
 
+  // Update local baseBranch to keep it in sync with remote before branching
+  if (fetched) {
+    try {
+      // Find out if the main repo currently has baseBranch checked out
+      const { stdout: currentBranch } = await execa('git', ['branch', '--show-current'], { cwd: repoPath });
+      if (currentBranch.trim() === baseBranch) {
+        // Safe fast-forward pull
+        await execa('git', ['pull', '--ff-only'], { cwd: repoPath });
+      } else {
+        // Fast-forward local ref from remote ref without checkout
+        await execa('git', ['fetch', 'origin', `${baseBranch}:${baseBranch}`], { cwd: repoPath });
+      }
+    } catch {
+      // Ignore failures (e.g. non-fast-forward, uncommitted changes, or no upstream tracking branch)
+    }
+  }
+
   // Determine starting point: remote branch if fetched successfully and exists, else local branch.
   let startPoint = baseBranch;
   if (fetched) {
@@ -43,12 +60,31 @@ export async function createWorktree(
     }
   }
 
-  // Create the worktree with a new branch based on the start point.
-  await execa(
-    'git',
-    ['worktree', 'add', targetPath, '-b', branchName, startPoint],
-    { cwd: repoPath },
-  );
+  // Check if the target branch already exists locally
+  let branchExists = false;
+  try {
+    await execa('git', ['rev-parse', '--verify', branchName], { cwd: repoPath });
+    branchExists = true;
+  } catch {
+    // Branch does not exist locally
+  }
+
+  // Create the worktree
+  if (branchExists) {
+    // If the branch already exists, checkout the existing branch
+    await execa(
+      'git',
+      ['worktree', 'add', targetPath, branchName],
+      { cwd: repoPath },
+    );
+  } else {
+    // If the branch does not exist, create a new branch based on the start point
+    await execa(
+      'git',
+      ['worktree', 'add', targetPath, '-b', branchName, startPoint],
+      { cwd: repoPath },
+    );
+  }
 }
 
 /**

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