@mrpatronz/nexusflow 0.2.4 → 0.2.6

package/src/commands/doctor.ts

@@ -0,0 +1,301 @@
+import chalk from 'chalk';
+import { select } from '@inquirer/prompts';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { execa } from 'execa';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces, loadFeatureConfig } from '../core/workspace.js';
+import { getRepoStatus } from '../utils/multi-git.js';
+import { analyzeAllRepos } from '../analyzers/index.js';
+import { globby } from 'globby';
+
+/**
+ * Runs the doctor command to diagnose workspace state.
+ *
+ * @param workspaceArg - Optional workspace path.
+ */
+export async function doctorCommand(workspaceArg?: string): Promise<void> {
+  console.log(chalk.bold.cyan('\n🩺 NexusFlow — Workspace Doctor\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;
+  }
+
+  const allRepos = await Promise.all(
+    feature.repos.map(async (r) => {
+      const repoName = path.basename(r);
+      return {
+        name: repoName,
+        path: r,
+        defaultBranch: 'main',
+      };
+    })
+  );
+
+  console.log(chalk.cyan('Running diagnostics...\n'));
+
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  // ── 1. Worktree Paths Check ──────────────────────────────────────────
+  console.log(chalk.bold('📁 Worktree Paths:'));
+  let worktreeErrors = false;
+  for (const repo of allRepos) {
+    try {
+      const stat = await fs.stat(repo.path);
+      if (!stat.isDirectory()) {
+        errors.push(`Worktree path for "${repo.name}" is not a directory.`);
+        console.log(`  ${chalk.red('✖')} ${repo.name}: Path is not a directory`);
+        worktreeErrors = true;
+      } else {
+        console.log(`  ${chalk.green('✔')} ${repo.name}: Directory exists`);
+      }
+    } catch {
+      errors.push(`Worktree path for "${repo.name}" does not exist: ${repo.path}`);
+      console.log(`  ${chalk.red('✖')} ${repo.name}: Path does not exist`);
+      worktreeErrors = true;
+    }
+  }
+  console.log();
+
+  if (worktreeErrors) {
+    console.error(chalk.red('✖ Worktree errors detected. Cannot complete diagnostics.\n'));
+    return;
+  }
+
+  // ── 2. Run Analysis for detailed checks ────────────────────────────────
+  const analysis = await analyzeAllRepos(allRepos);
+  console.log();
+
+  // ── 3. Branch & Git Status Checks ──────────────────────────────────────
+  console.log(chalk.bold('🌿 Branch Alignment & Git Status:'));
+  for (const repo of allRepos) {
+    let branch = 'unknown';
+    try {
+      const { stdout } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repo.path });
+      branch = stdout.trim();
+    } catch {}
+
+    if (branch !== feature.branchName) {
+      warnings.push(`Repository "${repo.name}" is checked out on branch "${branch}", but workspace branch is "${feature.branchName}".`);
+      console.log(`  ${chalk.yellow('⚠')} ${repo.name}: Branch mismatch (${chalk.bold(branch)} vs expected ${chalk.bold(feature.branchName)})`);
+    } else {
+      console.log(`  ${chalk.green('✔')} ${repo.name}: Aligned on branch "${branch}"`);
+    }
+
+    const status = await getRepoStatus(repo.path);
+    if (status.hasChanges) {
+      warnings.push(`Repository "${repo.name}" has uncommitted changes.`);
+      console.log(`    ${chalk.dim(`↳ Has uncommitted changes (${status.summary})`)}`);
+    }
+  }
+  console.log();
+
+  // ── 4. Package Registry, Local Feeds, and Temporary Local Versions ─────
+  console.log(chalk.bold('📦 Local Package Setup & Reference Versioning:'));
+  let hasCsharp = false;
+  let hasNode = false;
+
+  for (const repo of allRepos) {
+    const a = analysis.get(repo.path);
+    if (!a) continue;
+
+    if (a.techStack.languages.includes('csharp')) hasCsharp = true;
+    if (a.techStack.languages.includes('typescript') || a.techStack.languages.includes('javascript')) hasNode = true;
+
+    // Check for temporary/uncommitted versions in C# csproj
+    if (a.techStack.languages.includes('csharp')) {
+      try {
+        const csprojs = await globby('**/*.csproj', {
+          cwd: repo.path,
+          absolute: true,
+          ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+        });
+
+        for (const csproj of csprojs) {
+          const content = await fs.readFile(csproj, 'utf-8');
+          if (content.toLowerCase().includes('-local') || content.toLowerCase().includes('-dev')) {
+            warnings.push(`Temporary package version (e.g. ending in "-local" or "-dev") found in "${path.basename(csproj)}".`);
+            console.log(`  ${chalk.yellow('⚠')} ${repo.name}: Temporary local package version found in "${path.basename(csproj)}"`);
+          }
+        }
+      } catch {}
+
+      // NuGet local feed checks: check if any local NuGet source is defined in local NuGet.configs
+      if (a.nugetFeeds && a.nugetFeeds.length === 0) {
+        // Find if there are NuGet.config files
+        try {
+          const nugetConfigs = await globby('**/NuGet.config', {
+            cwd: repo.path,
+            ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+          });
+          if (nugetConfigs.length === 0) {
+            warnings.push(`Repository "${repo.name}" does not have a NuGet.config. It might not resolve local package dependencies.`);
+            console.log(`  ${chalk.yellow('⚠')} ${repo.name}: No NuGet.config found (needed to configure local package feeds)`);
+          }
+        } catch {}
+      }
+    }
+
+    // Check for relative path/file: dependencies in Node package.json
+    if (a.techStack.languages.includes('typescript') || a.techStack.languages.includes('javascript')) {
+      try {
+        const pjs = await globby('**/package.json', {
+          cwd: repo.path,
+          absolute: true,
+          ignore: ['**/node_modules/**', '**/bin/**', '**/obj/**', '**/dist/**', '**/out/**', '**/.git/**'],
+        });
+
+        for (const pj of pjs) {
+          const content = await fs.readFile(pj, 'utf-8');
+          if (content.includes('"file:') || content.includes('"link:')) {
+            warnings.push(`Temporary package link/file reference (e.g., "file:../") found in "${path.basename(pj)}".`);
+            console.log(`  ${chalk.yellow('⚠')} ${repo.name}: Temporary local dependency reference ("file:" or "link:") found in "${path.basename(pj)}"`);
+          }
+        }
+      } catch {}
+    }
+  }
+
+  if (hasCsharp || hasNode) {
+    console.log(`  ${chalk.green('✔')} Local registry feeds/link validation completed.`);
+  } else {
+    console.log(`  ${chalk.dim('No C# or Node.js repositories to validate.')}`);
+  }
+  console.log();
+
+  // ── 5. Test Commands & Fallbacks ───────────────────────────────────────
+  console.log(chalk.bold('🧪 Test Commands:'));
+  for (const repo of allRepos) {
+    const a = analysis.get(repo.path);
+    if (!a) continue;
+
+    const testCommand = getTestCommand(a);
+    if (testCommand === 'npm test' && !a.techStack.languages.includes('typescript') && !a.techStack.languages.includes('javascript')) {
+      warnings.push(`Repository "${repo.name}" fell back to default test command "npm test".`);
+      console.log(`  ${chalk.yellow('⚠')} ${repo.name}: Using default fallback test command "npm test"`);
+    } else {
+      console.log(`  ${chalk.green('✔')} ${repo.name}: Test command is "${testCommand}"`);
+    }
+  }
+  console.log();
+
+  // ── 6. Missing Core Files ──────────────────────────────────────────────
+  console.log(chalk.bold('📄 Core Artifacts:'));
+  const coreFiles = [
+    { name: 'WORKSPACE.md', required: true },
+    { name: 'nexusflow-knowledge.md', required: true },
+    { name: 'nexusflow-plan.md', required: true },
+  ];
+
+  // Add expected maps
+  for (const repo of allRepos) {
+    coreFiles.push({ name: `nexusflow-map-${repo.name}.md`, required: true });
+  }
+
+  for (const file of coreFiles) {
+    const filePath = path.join(workspacePath, file.name);
+    try {
+      await fs.access(filePath);
+      console.log(`  ${chalk.green('✔')} ${file.name} exists`);
+    } catch {
+      warnings.push(`Missing core workspace artifact: "${file.name}".`);
+      console.log(`  ${chalk.yellow('⚠')} ${file.name} is missing`);
+    }
+  }
+
+  // Check VS Code Settings for search.useIgnoreFiles: false
+  const vscodeSettingsPath = path.join(workspacePath, '.vscode', 'settings.json');
+  try {
+    const content = await fs.readFile(vscodeSettingsPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (parsed['search.useIgnoreFiles'] === false) {
+      console.log(`  ${chalk.green('✔')} .vscode/settings.json is configured correctly (search.useIgnoreFiles: false)`);
+    } else {
+      warnings.push('.vscode/settings.json search.useIgnoreFiles is not set to false. VS Code global search may ignore repository files.');
+      console.log(`  ${chalk.yellow('⚠')} .vscode/settings.json: search.useIgnoreFiles is not set to false`);
+    }
+  } catch {
+    warnings.push('Missing .vscode/settings.json. VS Code search might not work properly inside sub-repos.');
+    console.log(`  ${chalk.yellow('⚠')} .vscode/settings.json is missing or invalid`);
+  }
+  console.log();
+
+  // ── Summary Report ────────────────────────────────────────────────────
+  console.log(chalk.bold('📊 Diagnostic Summary:'));
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log(chalk.bold.green('  ✔ All checks passed! Workspace is healthy.\n'));
+  } else {
+    if (errors.length > 0) {
+      console.log(chalk.bold.red(`  ✖ ${errors.length} error(s) found. Fix them before proceeding.`));
+      for (const err of errors) console.log(`    - ${err}`);
+    }
+    if (warnings.length > 0) {
+      console.log(chalk.bold.yellow(`  ⚠ ${warnings.length} warning(s) found.`));
+      for (const warn of warnings) console.log(`    - ${warn}`);
+    }
+    console.log();
+  }
+}
+
+/**
+ * Resolves correct test command candidate.
+ */
+function getTestCommand(analysis: any): string {
+  if (analysis.techStack.languages.includes('csharp')) {
+    return 'dotnet test';
+  }
+  if (analysis.techStack.languages.includes('typescript') || analysis.techStack.languages.includes('javascript')) {
+    return 'npm test';
+  }
+  if (analysis.techStack.languages.includes('python')) {
+    return 'pytest';
+  }
+  if (analysis.techStack.languages.includes('go')) {
+    return 'go test ./...';
+  }
+  return 'npm test'; // fallback
+}
+
+/**
+ * Resolves a 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 diagnose:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}

package/src/commands/handoff.ts

@@ -0,0 +1,266 @@
+import chalk from 'chalk';
+import { select } from '@inquirer/prompts';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { execa } from 'execa';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces, loadFeatureConfig } from '../core/workspace.js';
+import { getWorkspaceRepos, getRepoStatus } from '../utils/multi-git.js';
+import { analyzeAllRepos } from '../analyzers/index.js';
+import { buildDependencyGraph } from '../generators/plan-generator.js';
+
+/**
+ * Runs the handoff command.
+ * Auto-detects workspace from CWD or prompts user to select one.
+ *
+ * @param workspaceArg - Optional workspace path from CLI.
+ */
+export async function handoffCommand(workspaceArg?: string): Promise<void> {
+  console.log(chalk.bold.cyan('\n🤝 NexusFlow — Handoff Bundle\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;
+  }
+
+  const allRepos = await Promise.all(
+    feature.repos.map(async (r) => {
+      const repoName = path.basename(r);
+      return {
+        name: repoName,
+        path: r,
+        defaultBranch: 'main',
+      };
+    })
+  );
+
+  console.log(chalk.cyan('Retrieving repository statuses and running analysis...'));
+  const analysis = await analyzeAllRepos(allRepos);
+
+  const reposStatusInfo = await Promise.all(
+    allRepos.map(async (repo) => {
+      const status = await getRepoStatus(repo.path);
+      const branch = await getRepoBranch(repo.path);
+      const repoAnalysis = analysis.get(repo.path);
+      
+      const suggestedFiles = getSuggestedFiles(repo.path, status.changedFiles, repoAnalysis);
+      const testCommand = getTestCommand(repo.path, repoAnalysis);
+
+      return {
+        name: repo.name,
+        path: repo.path,
+        branch,
+        dirtySummary: status.summary,
+        isDirty: status.hasChanges,
+        changedFiles: status.changedFiles,
+        suggestedFiles,
+        testCommand,
+      };
+    })
+  );
+
+  // Parse knowledge from nexusflow-knowledge.md if it exists
+  const knowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md');
+  let extractedGotchas = '_None recorded yet._';
+  let extractedDecisions = '_None recorded yet._';
+  let extractedQuestions = '_None recorded yet._';
+
+  try {
+    const knowledgeContent = await fs.readFile(knowledgePath, 'utf-8');
+    extractedGotchas = extractSection(knowledgeContent, 'Known Gotchas');
+    extractedDecisions = extractSection(knowledgeContent, 'Architecture Decisions');
+    extractedQuestions = extractSection(knowledgeContent, 'Clarifying Questions for the User');
+  } catch {}
+
+  // Build dependency description
+  let depGraphDescription = '';
+  try {
+    const graph = buildDependencyGraph(analysis, allRepos);
+    const relations: string[] = [];
+    for (const [name, node] of graph) {
+      if (node.dependsOn.length > 0) {
+        relations.push(`- **${name}** depends on: ${node.dependsOn.map(d => `\`${d}\``).join(', ')}`);
+      }
+    }
+    depGraphDescription = relations.length > 0 ? relations.join('\n') : '_No inter-repo package dependencies detected._';
+  } catch {
+    depGraphDescription = '_Error generating dependency graph._';
+  }
+
+  const timestamp = new Date().toISOString();
+  
+  // Format handoff bundle
+  const md: string[] = [];
+  md.push(`# NexusFlow Handoff Bundle — ${feature.branchName}`);
+  md.push('');
+  md.push(`> **Workspace Path:** \`${workspacePath}\``);
+  md.push(`> **Current Branch:** \`${feature.branchName}\``);
+  md.push(`> **Generated:** ${timestamp} (UTC)`);
+  md.push('> **Instruction:** Read this handoff bundle first to resume context immediately.');
+  md.push('');
+  md.push('## 📋 Repository Statuses');
+  md.push('');
+  md.push('| Repository | Branch | Git Status | Suggested Files to Read |');
+  md.push('|---|---|---|---|');
+
+  for (const r of reposStatusInfo) {
+    const filesList = r.suggestedFiles.map(f => `\`${f}\``).join(', ') || '—';
+    const statusText = r.isDirty ? `⚠️ ${r.dirtySummary}` : '✅ Clean';
+    md.push(`| **${r.name}** | \`${r.branch}\` | ${statusText} | ${filesList} |`);
+  }
+  md.push('');
+
+  md.push('## 🧪 Verification & Run Commands');
+  md.push('');
+  for (const r of reposStatusInfo) {
+    md.push(`- **${r.name}**: \`${r.testCommand}\``);
+  }
+  md.push('');
+
+  md.push('## 🏗️ Inter-Repo Package Graph');
+  md.push('');
+  md.push(depGraphDescription);
+  md.push('');
+
+  md.push('## 📝 Active Session Context (from nexusflow-knowledge.md)');
+  md.push('');
+  md.push('### Open Gotchas & Blockers');
+  md.push(extractedGotchas);
+  md.push('');
+  md.push('### Recent Architecture Decisions');
+  md.push(extractedDecisions);
+  md.push('');
+  md.push('### Outstanding Clarifying Questions');
+  md.push(extractedQuestions);
+  md.push('');
+
+  const handoffFilePath = path.join(workspacePath, 'nexusflow-handoff.md');
+  await fs.writeFile(handoffFilePath, md.join('\n'), 'utf-8');
+
+  console.log(chalk.green(`\n✅ Generated handoff bundle: ${chalk.bold('nexusflow-handoff.md')}`));
+  console.log(chalk.dim(`  Path: ${handoffFilePath}\n`));
+}
+
+/**
+ * Gets the current branch name of a repository.
+ */
+async function getRepoBranch(repoPath: string): Promise<string> {
+  try {
+    const { stdout } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoPath });
+    return stdout.trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Determines a candidate list of files to read first.
+ */
+function getSuggestedFiles(repoPath: string, dirtyFiles: string[], analysis?: any): string[] {
+  if (dirtyFiles.length > 0) {
+    return dirtyFiles.slice(0, 3).map(f => f.replace(/\\/g, '/'));
+  }
+  
+  const suggestions: string[] = [];
+  if (analysis && analysis.runConfig && analysis.runConfig.entryPoints) {
+    for (const ep of analysis.runConfig.entryPoints) {
+      if (ep.projectPath && !suggestions.includes(ep.projectPath)) {
+        suggestions.push(ep.projectPath);
+      }
+    }
+  }
+
+  suggestions.push('README.md');
+  return suggestions.slice(0, 3);
+}
+
+/**
+ * Resolves correct test command.
+ */
+function getTestCommand(repoPath: string, analysis?: any): string {
+  if (analysis) {
+    if (analysis.techStack.languages.includes('csharp')) {
+      return 'dotnet test';
+    }
+    if (analysis.techStack.languages.includes('typescript') || analysis.techStack.languages.includes('javascript')) {
+      return 'npm test';
+    }
+    if (analysis.techStack.languages.includes('python')) {
+      return 'pytest';
+    }
+    if (analysis.techStack.languages.includes('go')) {
+      return 'go test ./...';
+    }
+  }
+  return 'npm test'; // fallback
+}
+
+/**
+ * Extracts a specific section from the knowledge file.
+ */
+function extractSection(content: string, header: string): string {
+  const lines = content.split('\n');
+  const index = lines.findIndex(l => l.trim().startsWith(`## ${header}`));
+  if (index === -1) return '_None recorded yet._';
+  
+  const resultLines: string[] = [];
+  for (let i = index + 1; i < lines.length; i++) {
+    if (lines[i]!.trim().startsWith('##')) break;
+    resultLines.push(lines[i]!);
+  }
+  
+  const sectionContent = resultLines.join('\n').trim();
+  if (
+    !sectionContent ||
+    sectionContent.includes('No assumptions recorded yet') ||
+    sectionContent.includes('No open questions recorded yet') ||
+    sectionContent.includes('No decisions recorded yet') ||
+    sectionContent.includes('No gotchas recorded yet') ||
+    sectionContent.includes('AI assistant to populate')
+  ) {
+    return '_None recorded yet._';
+  }
+  return sectionContent;
+}
+
+/**
+ * Resolves a 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:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}