@mrpatronz/nexusflow 0.1.0 → 0.1.2

package/src/generators/plan-generator.ts

@@ -0,0 +1,390 @@
+/**
+ * @module plan-generator
+ * Analyzes inter-repo dependencies within a workspace and generates a
+ * `nexusflow-plan.md` implementation plan with build-order phases.
+ */
+
+import path from 'node:path';
+import fse from 'fs-extra';
+import chalk from 'chalk';
+import type {
+  WorkspaceContext,
+  ProjectAnalysis,
+  RepoInfo,
+  DependencyNode,
+  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.
+ *
+ * @param analysis  Per-repo analysis results, keyed by repo path.
+ * @param repos     Metadata for every repo in the workspace.
+ * @returns A map of repo name → {@link DependencyNode}.
+ */
+export function buildDependencyGraph(
+  analysis: Map<string, ProjectAnalysis>,
+  repos: RepoInfo[],
+): DependencyGraph {
+  const graph: DependencyGraph = new Map();
+
+  // ── Initialise a node for each repo ──────────────────────────────────
+  for (const repo of repos) {
+    graph.set(repo.name, {
+      repoName: repo.name,
+      repoPath: repo.path,
+      dependsOn: [],
+      dependedOnBy: [],
+    });
+  }
+
+  // Build a quick lookup: repo name → ProjectAnalysis
+  const analysisByName = new Map<string, ProjectAnalysis>();
+  for (const repo of repos) {
+    const a = analysis.get(repo.path);
+    if (a) analysisByName.set(repo.name, a);
+  }
+
+  const repoNames = new Set(repos.map((r) => r.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);
+        }
+      }
+    }
+  }
+
+  // ── 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;
+}
+
+// ─── Topological Sort ─────────────────────────────────────────────────────
+
+/**
+ * Topologically sort the dependency graph into build phases.
+ * Each phase is a group of repos that can be built in parallel
+ * because all of their dependencies appear in earlier phases.
+ *
+ * If a cycle is detected, the remaining nodes are placed in a final phase
+ * with a warning logged to the console.
+ *
+ * @param graph  The workspace dependency graph.
+ * @returns An array of phases, where each phase is an array of repo names.
+ */
+export function topologicalSort(graph: DependencyGraph): string[][] {
+  // Calculate in-degrees
+  const inDegree = new Map<string, number>();
+  for (const [name, node] of graph) {
+    inDegree.set(name, node.dependsOn.length);
+  }
+
+  const phases: string[][] = [];
+  const placed = new Set<string>();
+
+  while (placed.size < graph.size) {
+    // Collect nodes whose in-degree is 0 and haven't been placed yet
+    const phase: string[] = [];
+    for (const [name, degree] of inDegree) {
+      if (degree === 0 && !placed.has(name)) {
+        phase.push(name);
+      }
+    }
+
+    // Cycle detection — no zero-in-degree nodes remain
+    if (phase.length === 0) {
+      const remaining = [...graph.keys()].filter((n) => !placed.has(n));
+      console.log(
+        chalk.yellow('  ⚠'),
+        `Dependency cycle detected among: ${remaining.join(', ')}`,
+      );
+      phases.push(remaining);
+      break;
+    }
+
+    phase.sort(); // Deterministic ordering within a phase
+    phases.push(phase);
+
+    // "Remove" placed nodes and decrement dependents' in-degrees
+    for (const name of phase) {
+      placed.add(name);
+      const node = graph.get(name)!;
+      for (const dependent of node.dependedOnBy) {
+        inDegree.set(dependent, (inDegree.get(dependent) ?? 1) - 1);
+      }
+    }
+  }
+
+  return phases;
+}
+
+// ─── Plan Generator ───────────────────────────────────────────────────────
+
+/**
+ * Generate a `nexusflow-plan.md` implementation plan for the workspace.
+ *
+ * The plan includes:
+ * - A Mermaid dependency diagram
+ * - Phased implementation order derived from topological sort
+ * - A dependency cross-reference table
+ *
+ * @param ctx            The current workspace context (feature + repos + analysis).
+ * @param workspacePath  Absolute path to the workspace root directory.
+ */
+export async function generateImplementationPlan(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  try {
+    const { feature, repos, analysis } = ctx;
+
+    // ── Fallback: no analysis available ─────────────────────────────────
+    if (!analysis || analysis.size === 0) {
+      const lines = [
+        `# Implementation Plan — ${feature.id}`,
+        '',
+        '> Auto-generated by NexusFlow.',
+        '> No project analysis data was available, so repos are listed alphabetically.',
+        '',
+        '## Repos',
+        '',
+        ...repos
+          .map((r) => r.name)
+          .sort()
+          .map((n) => `- ${n}`),
+        '',
+      ];
+      await fse.outputFile(
+        path.join(workspacePath, 'nexusflow-plan.md'),
+        lines.join('\n'),
+      );
+      console.log(chalk.green('  ✔'), 'Generated nexusflow-plan.md');
+      return;
+    }
+
+    // ── Build graph & sort ──────────────────────────────────────────────
+    const graph = buildDependencyGraph(analysis, repos);
+    const phases = topologicalSort(graph);
+
+    // ── Render markdown ─────────────────────────────────────────────────
+    const md: string[] = [];
+
+    md.push(`# Implementation Plan — ${feature.id}`);
+    md.push('');
+    md.push(
+      '> Auto-generated by NexusFlow based on dependency analysis between repos.',
+    );
+    md.push(
+      '> Follow the phase order to avoid blocking yourself on cross-repo dependencies.',
+    );
+    md.push('');
+
+    // ── Mermaid diagram ─────────────────────────────────────────────────
+    md.push('## Dependency Diagram');
+    md.push('');
+    md.push('```mermaid');
+    md.push('graph TD');
+
+    const alias = buildAliasMap(graph);
+
+    for (const [name, node] of graph) {
+      if (node.dependsOn.length === 0 && node.dependedOnBy.length === 0) {
+        // Isolated node — still show it
+        md.push(`    ${alias.get(name)}["${name}"]`);
+      }
+      for (const dep of node.dependsOn) {
+        // Arrow: dependency → dependent (dep is built first)
+        md.push(
+          `    ${alias.get(dep)}["${dep}"] --> ${alias.get(name)}["${name}"]`,
+        );
+      }
+    }
+
+    md.push('```');
+    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('');
+      md.push(`**Repos:** ${phase.join(', ')}`);
+      md.push('');
+
+      if (i === 0) {
+        md.push(
+          `**Why first:** These repos have no dependencies on other workspace repos. Other repos depend on them.`,
+        );
+      } else if (i === phases.length - 1) {
+        md.push(
+          `**Why ${ordinal}:** Depends on APIs and types from earlier phases.`,
+        );
+      } else {
+        const prevPhases = phases
+          .slice(0, i)
+          .flat()
+          .join(', ');
+        md.push(
+          `**Why ${ordinal}:** Depends on Phase ${i === 1 ? '1' : `1–${i}`} repos (${prevPhases}). Build these before the consumers.`,
+        );
+      }
+
+      md.push('');
+    }
+
+    // ── Dependency table ────────────────────────────────────────────────
+    md.push('## Dependency Table');
+    md.push('');
+    md.push('| Repo | Depends On | Depended On By |');
+    md.push('|:---|:---|:---|');
+
+    // Sort repos by phase order for a natural reading experience
+    const orderedNames = phases.flat();
+    for (const name of orderedNames) {
+      const node = graph.get(name)!;
+      const deps = node.dependsOn.length > 0 ? node.dependsOn.join(', ') : '—';
+      const rdeps =
+        node.dependedOnBy.length > 0 ? node.dependedOnBy.join(', ') : '—';
+      md.push(`| ${name} | ${deps} | ${rdeps} |`);
+    }
+
+    md.push('');
+
+    // ── Write file ──────────────────────────────────────────────────────
+    const outPath = path.join(workspacePath, 'nexusflow-plan.md');
+    await fse.outputFile(outPath, md.join('\n'));
+    console.log(chalk.green('  ✔'), 'Generated nexusflow-plan.md');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      chalk.red('  ✖'),
+      `Failed to generate implementation plan: ${message}`,
+    );
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Add a directed edge: `from` depends on `to`.
+ * Idempotent — duplicate edges are ignored.
+ */
+function addEdge(graph: DependencyGraph, from: string, to: string): void {
+  const fromNode = graph.get(from);
+  const toNode = graph.get(to);
+  if (!fromNode || !toNode) return;
+
+  if (!fromNode.dependsOn.includes(to)) {
+    fromNode.dependsOn.push(to);
+  }
+  if (!toNode.dependedOnBy.includes(from)) {
+    toNode.dependedOnBy.push(from);
+  }
+}
+
+/**
+ * Build a short single-letter alias map for Mermaid node IDs.
+ * Falls back to sanitised names when there are more than 26 repos.
+ */
+function buildAliasMap(graph: DependencyGraph): Map<string, string> {
+  const map = new Map<string, string>();
+  const names = [...graph.keys()].sort();
+
+  if (names.length <= 26) {
+    let code = 65; // 'A'
+    for (const name of names) {
+      map.set(name, String.fromCharCode(code++));
+    }
+  } else {
+    for (const name of names) {
+      map.set(name, name.replace(/[^a-zA-Z0-9]/g, '_'));
+    }
+  }
+
+  return map;
+}
+
+/** Return an ordinal word for small numbers, or "nth" for larger ones. */
+function ordinalWord(n: number): string {
+  const words = ['first', 'second', 'third', 'fourth', 'fifth'];
+  if (n >= 1 && n <= words.length) return words[n - 1];
+  return `${n}th`;
+}

package/src/index.ts

@@ -20,6 +20,10 @@ import { stopCommand } from './commands/stop.js';
 import { logsCommand } from './commands/logs.js';
 import { statusCommand } from './commands/status.js';
 import { uiCommand } from './commands/ui.js';
+import { syncCommand } from './commands/sync.js';
+import { commitCommand } from './commands/commit.js';
+import { diffCommand } from './commands/diff.js';
+
 
 const program = new Command();
 
@@ -175,4 +179,59 @@ program
     }
   });
 
+program
+  .command('sync')
+  .description('Sync all repositories in a workspace')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .action(async (workspace?: string) => {
+    try {
+      await syncCommand(workspace);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('User force closed')) {
+        console.log('\nCancelled.');
+        process.exit(0);
+      }
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('commit')
+  .description('Commit changes across all repositories in a workspace')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .requiredOption('-m, --message <msg>', 'Commit message')
+  .option('--no-push', 'Stage and commit changes without pushing to remote')
+  .option('--dry-run', 'Preview changes without committing')
+  .action(async (workspace: string | undefined, options: { message: string; noPush?: boolean; dryRun?: boolean }) => {
+    try {
+      await commitCommand(options.message, 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);
+    }
+  });
+
+program
+  .command('diff')
+  .description('Display a unified summary of changes across all repositories')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .action(async (workspace?: string) => {
+    try {
+      await diffCommand(workspace);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('User force closed')) {
+        console.log('\nCancelled.');
+        process.exit(0);
+      }
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
 program.parse();
+

package/src/server.ts

@@ -20,6 +20,7 @@ import { generateContextFiles } from './generators/index.js';
 import { detectAIAssistants } from './utils/detect-ai.js';
 import { detectEditors } from './utils/detect-editors.js';
 import { findSessions, getSessionTranscript } from './utils/session-finder.js';
+import { getWorkspaceRepos, rebaseRepo, commitAndPush, getRepoStatus } from './utils/multi-git.js';
 import {
   detectAllServices,
   detectOrchestrationTools,
@@ -301,6 +302,27 @@ app.get('/api/workspace/:id/changes', async (c) => {
         const { stdout } = await execa('git', ['status', '--porcelain'], { cwd: worktreePath });
         const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
 
+        // Get numstat to determine additions and deletions per file
+        const numstatMap = new Map<string, { additions: number; deletions: number }>();
+        try {
+          const { stdout: numstatRaw } = await execa('git', ['diff', 'HEAD', '--numstat'], {
+            cwd: worktreePath,
+          });
+          const numstatLines = numstatRaw.split('\n').filter(Boolean);
+          for (const numLine of numstatLines) {
+            const parts = numLine.trim().split(/\s+/);
+            if (parts.length >= 3) {
+              const [add, del, file] = parts;
+              numstatMap.set(file, {
+                additions: add === '-' ? 0 : parseInt(add, 10) || 0,
+                deletions: del === '-' ? 0 : parseInt(del, 10) || 0,
+              });
+            }
+          }
+        } catch (e) {
+          // Ignore diff errors
+        }
+
         const files = lines.map((line) => {
           const status = line.slice(0, 2).trim();
           const file = line.slice(2).trim();
@@ -309,7 +331,15 @@ app.get('/api/workspace/:id/changes', async (c) => {
           if (status === 'A' || status === '??') type = 'added';
           else if (status === 'D') type = 'deleted';
 
-          return { file, type, rawStatus: status };
+          const stats = numstatMap.get(file) || { additions: 0, deletions: 0 };
+
+          return {
+            file,
+            type,
+            rawStatus: status,
+            additions: stats.additions,
+            deletions: stats.deletions,
+          };
         });
 
         results.push({
@@ -334,6 +364,127 @@ app.get('/api/workspace/:id/changes', async (c) => {
   }
 });
 
+// 13a. Get workspace knowledge (nexusflow-knowledge.md)
+app.get('/api/workspace/:id/knowledge', async (c) => {
+  try {
+    const id = c.req.param('id');
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+    const knowledgeFile = path.join(workspacePath, 'nexusflow-knowledge.md');
+
+    let content = '';
+    try {
+      content = await fs.readFile(knowledgeFile, 'utf-8');
+    } catch {
+      content = '# Workspace Knowledge\n\nNo knowledge file yet.';
+    }
+
+    return c.json({ content });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+// 13b. Update workspace knowledge (nexusflow-knowledge.md)
+app.put('/api/workspace/:id/knowledge', async (c) => {
+  try {
+    const id = c.req.param('id');
+    const { content } = await c.req.json() as { content: string };
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+    const knowledgeFile = path.join(workspacePath, 'nexusflow-knowledge.md');
+
+    await fs.writeFile(knowledgeFile, content, 'utf-8');
+    return c.json({ success: true });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+// 13c. Get workspace plan (nexusflow-plan.md)
+app.get('/api/workspace/:id/plan', async (c) => {
+  try {
+    const id = c.req.param('id');
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+    const planFile = path.join(workspacePath, 'nexusflow-plan.md');
+
+    let content = '';
+    try {
+      content = await fs.readFile(planFile, 'utf-8');
+    } catch {
+      content = '# Workspace Plan\n\nNo implementation plan file yet.';
+    }
+
+    return c.json({ content });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+// 13d. Sync all repositories in workspace
+app.post('/api/workspace/:id/sync', async (c) => {
+  try {
+    const id = c.req.param('id');
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+
+    const repos = await getWorkspaceRepos(workspacePath);
+    const results = [];
+
+    for (const repo of repos) {
+      const result = await rebaseRepo(repo.path, 'main');
+      results.push({
+        repoName: repo.name,
+        success: result.success,
+        message: result.message,
+        conflict: result.conflict,
+      });
+    }
+
+    return c.json({ results });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+// 13e. Commit changes in all repositories in workspace
+app.post('/api/workspace/:id/commit', async (c) => {
+  try {
+    const id = c.req.param('id');
+    const { message } = await c.req.json() as { message: string };
+    const config = await loadConfig();
+    const workspacePath = path.join(config.workspacesDir, id);
+
+    const repos = await getWorkspaceRepos(workspacePath);
+    const results = [];
+
+    for (const repo of repos) {
+      const status = await getRepoStatus(repo.path);
+      if (status.hasChanges) {
+        const result = await commitAndPush(repo.path, message, repo.branchName);
+        results.push({
+          repoName: repo.name,
+          success: result.success,
+          commitHash: result.commitHash,
+          filesChanged: result.filesChanged,
+          message: result.message,
+        });
+      }
+    }
+
+    return c.json({ results });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+
 // 14. Resume session in workspace (copies CLI resume command and opens editor)
 app.post('/api/workspace/:id/resume', async (c) => {
   try {

package/src/types.ts

@@ -292,3 +292,20 @@ export interface RunningState {
   /** Timestamp when the state was last updated. */
   updatedAt: string;
 }
+
+// ─── Phase 3: Dependency Graph Types ──────────────────────────────────────
+
+/** A node in the workspace dependency graph. */
+export interface DependencyNode {
+  /** Repository name. */
+  repoName: string;
+  /** Absolute path to the repository. */
+  repoPath: string;
+  /** Names of repos this one depends on. */
+  dependsOn: string[];
+  /** Names of repos that depend on this one. */
+  dependedOnBy: string[];
+}
+
+/** The full dependency graph for a workspace. */
+export type DependencyGraph = Map<string, DependencyNode>;