@mrpatronz/nexusflow 0.2.4 → 0.2.6

package/src/commands/refresh.ts

@@ -0,0 +1,139 @@
+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 } from '../utils/multi-git.js';
+import { analyzeAllRepos } from '../analyzers/index.js';
+import { generateContextFiles } from '../generators/index.js';
+import type { WorkspaceContext } from '../types.js';
+
+/**
+ * Runs the refresh command.
+ * Updates context files, maps, and plans.
+ *
+ * @param options - CLI options, e.g. { repo: 'API_CoworkerFacade' }.
+ * @param workspaceArg - Optional workspace path.
+ */
+export async function refreshCommand(
+  options: { repo?: string },
+  workspaceArg?: string,
+): Promise<void> {
+  console.log(chalk.bold.cyan('\n🔄 NexusFlow — Refresh Workspace Context\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 onlyRepo = options.repo;
+  if (onlyRepo) {
+    const hasRepo = feature.repos.some(r => path.basename(r) === onlyRepo);
+    if (!hasRepo) {
+      console.error(chalk.red(`✖ Repository "${onlyRepo}" is not part of this workspace.`));
+      console.log(chalk.dim(`  Available repos: ${feature.repos.map(r => path.basename(r)).join(', ')}`));
+      return;
+    }
+    console.log(`Refreshing context for repository: ${chalk.bold(onlyRepo)}`);
+  } else {
+    console.log('Refreshing context for all repositories...');
+  }
+
+  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 project analysis...'));
+  const analysis = await analyzeAllRepos(allRepos);
+
+  const ctx: WorkspaceContext = {
+    feature,
+    repos: allRepos,
+    analysis,
+  };
+
+  console.log(chalk.cyan('Regenerating context files and maps...'));
+  await generateContextFiles(ctx, feature.assistants, workspacePath, onlyRepo);
+
+  // If repopack context packing is enabled
+  const config = await loadConfig();
+  if (config.packContextXml) {
+    const { packWorkspace } = await import('../core/packer.js');
+    console.log(chalk.cyan('Re-packing workspace context...'));
+    try {
+      await packWorkspace(workspacePath);
+    } catch (error) {
+      console.warn(chalk.yellow(`  ⚠ Failed to repack context: ${error}`));
+    }
+  }
+
+  // If handoff file exists, refresh it automatically too!
+  const handoffPath = path.join(workspacePath, 'nexusflow-handoff.md');
+  let hasHandoff = false;
+  try {
+    await fs.access(handoffPath);
+    hasHandoff = true;
+  } catch {}
+
+  if (hasHandoff) {
+    console.log(chalk.cyan('Refreshing handoff bundle...'));
+    try {
+      const { handoffCommand } = await import('./handoff.js');
+      await handoffCommand(workspacePath);
+    } catch (error) {
+      console.warn(chalk.yellow(`  ⚠ Failed to refresh handoff bundle: ${error}`));
+    }
+  }
+
+  console.log(chalk.bold.green('\n✅ Workspace context successfully refreshed!\n'));
+}
+
+/**
+ * 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 refresh:',
+    choices: workspaces.map((ws) => ({
+      name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+      value: ws.workspacePath,
+    })),
+  });
+
+  return selected;
+}

package/src/core/workspace.ts

@@ -66,6 +66,22 @@ export async function createWorkspace(
     console.warn('Warning: Failed to initialize git repository at workspace root:', error);
   }
 
+  // Create .vscode/settings.json to allow VS Code search to query inside ignored sub-repos
+  try {
+    const vscodeDir = path.join(workspacePath, '.vscode');
+    await fs.mkdir(vscodeDir, { recursive: true });
+    const settings = {
+      "search.useIgnoreFiles": false
+    };
+    await fs.writeFile(
+      path.join(vscodeDir, 'settings.json'),
+      JSON.stringify(settings, null, 2) + '\n',
+      'utf-8'
+    );
+  } catch (error) {
+    console.warn('Warning: Failed to create .vscode/settings.json:', error);
+  }
+
   // Create a worktree for each repo inside the workspace.
   for (const repo of repos) {
     const worktreeTarget = path.join(workspacePath, repo.name);

package/src/core/worktree.ts

@@ -78,10 +78,10 @@ export async function createWorktree(
       { cwd: repoPath },
     );
   } else {
-    // If the branch does not exist, create a new branch based on the start point
+    // If the branch does not exist, create a new branch based on the start point without tracking it
     await execa(
       'git',
-      ['worktree', 'add', targetPath, '-b', branchName, startPoint],
+      ['worktree', 'add', '--no-track', targetPath, '-b', branchName, startPoint],
       { cwd: repoPath },
     );
   }

package/src/generators/base.ts

@@ -151,14 +151,20 @@ ${parts.join('\n')}
 
   const knowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md').replace(/\\/g, '/');
 
-  const taskSection = `## First Steps
-
-Your very first task upon entering this workspace is to explore the codebase and align with the user:
+  let setupDone = false;
+  try {
+    const realKnowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md');
+    if (fs.existsSync(realKnowledgePath)) {
+      const content = fs.readFileSync(realKnowledgePath, 'utf-8');
+      if (!content.includes('No assumptions recorded yet') && !content.includes('AI assistant to populate')) {
+        setupDone = true;
+      }
+    }
+  } catch {}
 
-1. **Verify Assumptions**: Open [nexusflow-knowledge.md](file:///${knowledgePath}) and fill in the **Project Assumptions** section with a brief description of what each project does, its tech stack, and responsibilities.
-2. **Raise Questions**: Document any outstanding uncertainties or architectural questions in the **Clarifying Questions for the User** section.
-3. **Obtain Approval**: Ask the user to confirm your assumptions and answer your questions before writing any code.
-`;
+  const taskSection = setupDone
+    ? `## Setup Status\n\n✅ **Setup Completed**: Project assumptions and initial questions have been addressed. Refer to [nexusflow-knowledge.md](file:///${knowledgePath}) for persistent session details.`
+    : `## First Steps\n\nYour very first task upon entering this workspace is to explore the codebase and align with the user:\n\n1. **Verify Assumptions**: Open [nexusflow-knowledge.md](file:///${knowledgePath}) and fill in the **Project Assumptions** section with a brief description of what each project does, its tech stack, and responsibilities.\n2. **Raise Questions**: Document any outstanding uncertainties or architectural questions in the **Clarifying Questions for the User** section.\n3. **Obtain Approval**: Ask the user to confirm your assumptions and answer your questions before writing any code.`;
 
   return `# Multi-Repo Workspace Context
 
@@ -194,6 +200,8 @@ ${taskSection}
     - \`nexusflow diff\` — view changes across all sub-repositories.
     - \`nexusflow commit\` — commit and push changes across modified repositories.
     - \`nexusflow sync\` — rebase all repositories with their default base branches.
+    - \`nexusflow refresh\` — regenerate maps, context files and plans without rebasing.
+    - \`nexusflow doctor\` — run diagnostics to verify workspace health.
 - **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.

package/src/generators/index.ts

@@ -117,6 +117,7 @@ export async function generateContextFiles(
   ctx: WorkspaceContext,
   assistants: AIAssistant[],
   workspacePath: string,
+  onlyRepo?: string,
 ): Promise<void> {
   // Always generate a universal WORKSPACE.md at the workspace root
   try {
@@ -159,6 +160,9 @@ export async function generateContextFiles(
     }
 
     for (const repo of ctx.repos) {
+      if (onlyRepo && repo.name !== onlyRepo) {
+        continue;
+      }
       const a = ctx.analysis.get(repo.path);
       if (a) {
         try {

package/src/generators/map-generator.ts

@@ -129,7 +129,7 @@ export async function generateRepoMap(
   md.push('');
   md.push(`> **Repository Path**: \`${worktreePath}\``);
   md.push(`> **Generated At**: ${new Date().toISOString()} (UTC)`);
-  md.push(`> **Regeneration Command**: Run \`nexusflow sync\` to update this map and workspace planning files.`);
+  md.push(`> **Regeneration Command**: Run \`nexusflow refresh\` to update this map.`);
   md.push(`> **Note**: Maps are advisory snapshots of the codebase. Always verify route parameters, patterns, and filenames before relying on them.`);
   md.push('');
 
@@ -495,18 +495,44 @@ export async function generateRepoMap(
   
   const conventionsFile = path.join(workspacePath, `nexusflow-conventions-${repoName}.md`);
   let customConventions = '';
+  
+  let conventionsExist = false;
   try {
-    customConventions = await fs.readFile(conventionsFile, 'utf-8');
-    // Strip the title from the old conventions file if present
-    customConventions = customConventions.replace(/^#\s+.+\n?/, '').trim();
+    await fs.access(conventionsFile);
+    conventionsExist = true;
   } catch {}
 
+  if (!conventionsExist) {
+    const starterContent = `# Repository Conventions — ${repoName}
+
+Use this file to record project-specific coding conventions, patterns, gotchas, and constraints learned during development.
+Future AI assistant sessions will read these conventions from the repository map.
+
+## Coding Patterns
+<!-- E.g., Use ErrorContent structure for errors instead of plain strings -->
+
+- None recorded yet.
+
+## Gotchas & Watch-outs
+<!-- E.g., Non-nullable enum required attributes gotchas -->
+
+- None recorded yet.
+`;
+    try {
+      await fs.writeFile(conventionsFile, starterContent, 'utf-8');
+      customConventions = starterContent.replace(/^#\s+.+\n?/, '').trim();
+    } catch {}
+  } else {
+    try {
+      customConventions = await fs.readFile(conventionsFile, 'utf-8');
+      customConventions = customConventions.replace(/^#\s+.+\n?/, '').trim();
+    } catch {}
+  }
+
   if (customConventions) {
     md.push(customConventions);
     md.push('');
   } else {
-    md.push('<!-- AI assistants: Document any project-specific conventions, gotchas, or coding rules discovered here. -->');
-    md.push('');
     md.push('- None recorded yet.');
     md.push('');
   }

package/src/generators/plan-generator.ts

@@ -204,6 +204,9 @@ export async function generateImplementationPlan(
 
     md.push(`# Implementation Plan — ${feature.id}`);
     md.push('');
+    md.push(`> **Generated At**: ${new Date().toISOString()} (UTC)`);
+    md.push(`> **Regeneration Command**: Run \`nexusflow refresh\` to update this plan.`);
+    md.push('');
     md.push(
       '> Auto-generated by NexusFlow based on dependency analysis between repos.',
     );

package/src/index.ts

@@ -27,6 +27,9 @@ import { packCommand } from './commands/pack.js';
 import { removeCommand } from './commands/remove.js';
 import { addRepoCommand } from './commands/add-repo.js';
 import { mcpRunCommand, mcpSetupCommand } from './commands/mcp.js';
+import { handoffCommand } from './commands/handoff.js';
+import { refreshCommand } from './commands/refresh.js';
+import { doctorCommand } from './commands/doctor.js';
 import { getCurrentVersion, checkForUpdates, printUpdateBanner } from './utils/update-check.js';
 
 const program = new Command();
@@ -292,6 +295,46 @@ program
     }
   });
 
+program
+  .command('handoff')
+  .description('Generate a compact handoff bundle (nexusflow-handoff.md) for session resumption')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .action(async (workspace?: string) => {
+    try {
+      await handoffCommand(workspace);
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('refresh')
+  .description('Refresh workspace context, maps, plans and handoff files')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .option('-r, --repo <repo>', 'Only refresh the map for a specific repository')
+  .action(async (workspace: string | undefined, options: { repo?: string }) => {
+    try {
+      await refreshCommand(options, workspace);
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('doctor')
+  .description('Run diagnostics to verify workspace health and check for local loop issues')
+  .argument('[workspace]', 'Path to workspace (auto-detects from CWD)')
+  .action(async (workspace?: string) => {
+    try {
+      await doctorCommand(workspace);
+    } catch (error) {
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
 const mcp = program.command('mcp').description('Manage the NexusFlow MCP Server for AI assistants');
 
 mcp