@mrpatronz/nexusflow 0.1.0 → 0.1.2

package/src/commands/diff.ts

@@ -0,0 +1,125 @@
+/**
+ * @module commands/diff
+ * Displays diff summaries across all repositories in a workspace.
+ */
+
+import chalk from 'chalk';
+import { select } from '@inquirer/prompts';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces, loadFeatureConfig } from '../core/workspace.js';
+import { getWorkspaceRepos, getRepoStatus, getDiffSummary } from '../utils/multi-git.js';
+
+/**
+ * Executes the diff command.
+ *
+ * @param workspaceArg - Optional workspace path.
+ */
+export async function diffCommand(workspaceArg?: string): Promise<void> {
+  console.log(chalk.bold.cyan('\n🔍 NexusFlow — Workspace Diff Summary\n'));
+
+  const workspacePath = await resolveWorkspace(workspaceArg);
+  if (!workspacePath) return;
+
+  const feature = await loadFeatureConfig(workspacePath);
+  if (!feature) {
+    console.error(chalk.red('✖ Failed to load workspace configuration.'));
+    return;
+  }
+
+  const repos = await getWorkspaceRepos(workspacePath);
+  let cleanCount = 0;
+
+  const results: Array<{
+    name: string;
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+    summary: string;
+  }> = [];
+
+  for (const repo of repos) {
+    const status = await getRepoStatus(repo.path);
+    if (!status.hasChanges) {
+      cleanCount++;
+      continue;
+    }
+
+    const diff = await getDiffSummary(repo.path);
+    results.push({
+      name: repo.name,
+      filesChanged: status.changedFiles.length,
+      additions: diff.additions,
+      deletions: diff.deletions,
+      summary: diff.summary,
+    });
+  }
+
+  if (results.length === 0) {
+    console.log(chalk.green('✅ All repositories are clean.\n'));
+    return;
+  }
+
+  // Print unified table
+  console.log(chalk.bold('Repository'.padEnd(25) + ' | ' + 'Files'.padEnd(6) + ' | ' + 'Additions'.padEnd(10) + ' | ' + 'Deletions'.padEnd(10)));
+  console.log(chalk.dim('─'.repeat(61)));
+
+  for (const res of results) {
+    const fileStr = res.filesChanged.toString().padEnd(6);
+    const addStr = `+${res.additions}`.padEnd(10);
+    const delStr = `-${res.deletions}`.padEnd(10);
+    console.log(
+      chalk.bold(res.name.padEnd(25)) + ' | ' +
+      fileStr + ' | ' +
+      chalk.green(addStr) + ' | ' +
+      chalk.red(delStr)
+    );
+  }
+
+  console.log('\n' + chalk.bold('Detailed Diff Stats:'));
+  for (const res of results) {
+    console.log(`\n📂 ${chalk.bold.cyan(res.name)}:`);
+    console.log(chalk.dim(res.summary.split('\n').map(l => `  ${l}`).join('\n')));
+  }
+
+  console.log();
+}
+
+/**
+ * Resolves workspace path.
+ */
+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 view diff:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}

package/src/commands/sync.ts

@@ -0,0 +1,110 @@
+/**
+ * @module commands/sync
+ * Syncs the active workspace by fetching and rebasing all repos onto their base branch.
+ */
+
+import chalk from 'chalk';
+import { select } from '@inquirer/prompts';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces, loadFeatureConfig } from '../core/workspace.js';
+import { getWorkspaceRepos, rebaseRepo } from '../utils/multi-git.js';
+
+/**
+ * Executes the sync command.
+ *
+ * @param workspaceArg - Optional workspace path from CLI.
+ */
+export async function syncCommand(workspaceArg?: string): Promise<void> {
+  console.log(chalk.bold.cyan('\n🔄 NexusFlow — Syncing Workspace\n'));
+
+  const workspacePath = await resolveWorkspace(workspaceArg);
+  if (!workspacePath) return;
+
+  const feature = await loadFeatureConfig(workspacePath);
+  if (!feature) {
+    console.error(chalk.red('✖ Failed to load workspace configuration. Ensure nexusflow.json exists.'));
+    return;
+  }
+
+  console.log(chalk.bold(`Syncing workspace: ${chalk.cyan(feature.branchName)}`));
+  console.log(chalk.dim(`Path: ${workspacePath}\n`));
+
+  let repos;
+  try {
+    repos = await getWorkspaceRepos(workspacePath);
+  } catch (error) {
+    console.error(chalk.red(`✖ Failed to retrieve repos: ${error instanceof Error ? error.message : String(error)}`));
+    return;
+  }
+
+  let syncedCount = 0;
+  let conflictCount = 0;
+
+  for (const repo of repos) {
+    console.log(`Repository: ${chalk.bold(repo.name)}`);
+    // Ideally we rebase on the repo's default branch, which is often 'main' or 'master'
+    // Let's assume 'main' as default unless we fetch/read it.
+    const defaultBranch = 'main'; // We can default to 'main' as specified in requirements
+
+    const spinner = chalk.dim('  Rebasing...');
+    process.stdout.write(spinner);
+
+    const result = await rebaseRepo(repo.path, defaultBranch);
+
+    // Clear rebase message line
+    process.stdout.write('\r' + ' '.repeat(spinner.length) + '\r');
+
+    if (result.success) {
+      console.log(`  ${chalk.green('✅')} Synced (${result.message})`);
+      syncedCount++;
+    } else {
+      console.log(`  ${chalk.red('⚠️')} Conflict: ${result.message}`);
+      if (result.conflict) {
+        console.log(chalk.dim(result.conflict.split('\n').map(l => `    ${l}`).slice(0, 5).join('\n')));
+      }
+      conflictCount++;
+    }
+  }
+
+  console.log(`\n📊 ${chalk.bold('Summary:')} ${syncedCount} synced, ${conflictCount} conflict(s)\n`);
+}
+
+/**
+ * Resolves a workspace path from argument, cwd, or user prompt.
+ */
+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 sync:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}

package/src/generators/base.ts

@@ -176,6 +176,8 @@ Once you have created \`nexusflow-overview.md\` and compiled your questions, ask
 
 ## Guidelines
 
+- **Workspace Knowledge**: Read \`nexusflow-knowledge.md\` at the start of every session. It serves as the persistent memory for this feature. Before ending your session, append significant architecture decisions, discovered gotchas, and checklist progress to \`nexusflow-knowledge.md\`. Never delete or overwrite existing knowledge/decisions — only append.
+- **Implementation Plan**: Refer to \`nexusflow-plan.md\` for the suggested implementation order based on dependency analysis. Follow the phased implementation order to avoid blocking yourself on cross-repo dependencies.
 - Read each project's existing \`README.md\` and any doc files before proposing changes.
 - When modifying a shared library, check every downstream consumer for breakage.
 - Prefer small, focused commits that touch one repo at a time when possible.
@@ -183,5 +185,6 @@ Once you have created \`nexusflow-overview.md\` and compiled your questions, ask
 
 
 
+
 `;
 }

package/src/generators/index.ts

@@ -7,6 +7,7 @@ import { generateCodexConfig } from './codex.js';
 import { generateCopilotConfig } from './copilot.js';
 import { generateCursorConfig } from './cursor.js';
 import { buildContextContent } from './base.js';
+import { generateImplementationPlan } from './plan-generator.js';
 
 /** Maps each assistant to its generator function and the file it produces. */
 const GENERATORS: Record<
@@ -23,11 +24,83 @@ const GENERATORS: Record<
   cursor: { generate: generateCursorConfig, outputFile: '.cursor/rules/nexusflow.mdc' },
 };
 
+/**
+ * Builds the nexusflow-knowledge.md content — a persistent AI memory file.
+ */
+function buildKnowledgeContent(ctx: WorkspaceContext): string {
+  const { feature, repos, analysis } = ctx;
+
+  // Build repo list with tech stack info if available
+  const repoList = repos.map((r) => {
+    if (analysis && analysis.has(r.path)) {
+      const a = analysis.get(r.path)!;
+      const tech = a.techStack.frameworks.length > 0
+        ? ` (${a.techStack.languages.join(', ')} — ${a.techStack.frameworks.join(', ')})`
+        : a.techStack.languages[0] !== 'other'
+          ? ` (${a.techStack.languages.join(', ')})`
+          : '';
+      return `- **${r.name}**${tech}`;
+    }
+    return `- **${r.name}**`;
+  }).join('\n');
+
+  // Build initial progress checklist
+  const progressItems = repos.map((r) => `- [ ] ${r.name} — changes implemented and tested`).join('\n');
+
+  return `# Workspace Knowledge — ${feature.id}
+
+> **This file is a living document.** AI assistants should read this at the
+> start of each session and append new learnings at the end.
+> It preserves context across sessions so decisions aren't lost or repeated.
+
+## Feature Goal
+
+${feature.description}
+
+**Branch:** \`${feature.branchName}\`
+**Created:** ${feature.createdAt}
+
+## Repos in This Workspace
+
+${repoList}
+
+## Architecture Decisions
+
+<!-- AI assistants: append decisions here as they are made during development.
+     Format: ### YYYY-MM-DD — Decision Title
+     **Decision:** What was decided
+     **Alternatives considered:** What else was evaluated
+     **Reasoning:** Why this choice was made -->
+
+_(No decisions recorded yet.)_
+
+## Implementation Progress
+
+${progressItems}
+
+## Known Gotchas
+
+<!-- AI assistants: append any gotchas, workarounds, or "watch out for" items
+     discovered during development. These help future sessions avoid repeating
+     the same debugging. -->
+
+_(No gotchas recorded yet.)_
+
+## Open Questions
+
+<!-- Add questions that need human input before the AI can proceed. -->
+
+_(No open questions.)_
+`;
+}
+
 /**
  * Generates AI context files for each of the selected assistants.
  *
- * Iterates over the provided assistant list, invokes the corresponding
- * generator, and logs success / failure for each one.
+ * Also generates:
+ * - WORKSPACE.md — universal context file
+ * - nexusflow-knowledge.md — persistent AI memory across sessions
+ * - nexusflow-plan.md — implementation order based on dependency analysis
  *
  * @param ctx           - The workspace context (feature + repos).
  * @param assistants    - Which AI assistants to generate context files for.
@@ -48,44 +121,14 @@ export async function generateContextFiles(
       `Generated universal ${chalk.bold('WORKSPACE.md')}`,
     );
 
-    // Generate session.md template if it does not exist
-    const sessionPath = path.join(workspacePath, 'session.md');
-    if (!(await fse.pathExists(sessionPath))) {
-      const sessionContent = `# AI Session Handover Memo
-
-- **Feature Branch**: \`${ctx.feature.branchName}\`
-- **Session Started**: ${new Date().toLocaleDateString()}
-- **Last Modified Files**: None (Start of session)
-
-## Summary of Accomplished Work
-- Setup workspace with ${ctx.repos.length} mapped repositories.
-
-## Active State & Blockers
-- No active blockers.
-
-## Next Steps
-1. Open this workspace in your selected editor.
-2. Ask the assistant to read \`WORKSPACE.md\` and \`session.md\` to get started.
-`;
-      await fse.writeFile(sessionPath, sessionContent, 'utf-8');
-      console.log(chalk.green('  ✔'), `Generated initial session.md`);
-    }
-
-    // Generate plan.md template if it does not exist
-    const planPath = path.join(workspacePath, 'plan.md');
-    if (!(await fse.pathExists(planPath))) {
-      const planContent = `# Feature Development Plan
-
-## Checklist
-- [ ] Read \`WORKSPACE.md\` and analyze the codebase structure.
-- [ ] Initialize context by creating \`nexusflow-overview.md\` outlining assumptions and raising clarifying questions.
-- [ ] Review user's responses to clarifying questions.
-- [ ] Implement feature logic.
-- [ ] Verify build and run tests.
-- [ ] Compile final changes in the session handover memo.
-`;
-      await fse.writeFile(planPath, planContent, 'utf-8');
-      console.log(chalk.green('  ✔'), `Generated initial plan.md`);
+    // Generate nexusflow-knowledge.md if it does not exist
+    const knowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md');
+    if (!(await fse.pathExists(knowledgePath))) {
+      const knowledgeContent = buildKnowledgeContent(ctx);
+      await fse.writeFile(knowledgePath, knowledgeContent, 'utf-8');
+      console.log(chalk.green('  ✔'), `Generated ${chalk.bold('nexusflow-knowledge.md')} (persistent AI memory)`);
+    } else {
+      console.log(chalk.gray('  ○'), `nexusflow-knowledge.md already exists — preserving existing content`);
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -112,6 +155,17 @@ export async function generateContextFiles(
       );
     }
   }
+
+  // Generate implementation plan from dependency analysis (if analysis data available)
+  try {
+    await generateImplementationPlan(ctx, workspacePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      chalk.red('  ✖'),
+      `Failed to generate implementation plan: ${message}`,
+    );
+  }
 }
 
 // Re-export individual generators for direct use
@@ -120,3 +174,4 @@ export { generateCodexConfig } from './codex.js';
 export { generateCopilotConfig } from './copilot.js';
 export { generateCursorConfig } from './cursor.js';
 export { buildContextContent } from './base.js';
+export { generateImplementationPlan } from './plan-generator.js';