@mrpatronz/nexusflow 0.1.0

package/src/core/workspace.ts

@@ -0,0 +1,149 @@
+/**
+ * @module core/workspace
+ * Creates and manages NexusFlow workspaces — directories that group
+ * worktrees for a multi-repo feature together with a `nexusflow.json`
+ * manifest.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type { Feature, RepoInfo } from '../types.js';
+import { createWorktree } from './worktree.js';
+
+/** Name of the per-workspace manifest file. */
+const MANIFEST_FILE = 'nexusflow.json';
+
+/**
+ * Derives the workspace directory path for a given branch name.
+ *
+ * @param workspacesDir - The root workspaces directory (e.g. ~/dev/workspaces).
+ * @param branchName    - The feature branch name used as the workspace folder.
+ * @returns Absolute path to the workspace directory.
+ */
+export function getWorkspacePath(
+  workspacesDir: string,
+  branchName: string,
+): string {
+  return path.join(workspacesDir, branchName);
+}
+
+/**
+ * Creates a full workspace for a feature:
+ * 1. Creates the workspace directory.
+ * 2. Creates a git worktree for every repo in the feature.
+ * 3. Saves the feature manifest (`nexusflow.json`).
+ *
+ * @param feature - The feature definition.
+ * @param repos   - Resolved repo metadata for every repo in the feature.
+ * @returns The absolute path to the newly created workspace.
+ */
+export async function createWorkspace(
+  feature: Feature,
+  repos: RepoInfo[],
+): Promise<string> {
+  const workspacePath = feature.workspacePath;
+
+  // Ensure the workspace directory exists.
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  // Create a worktree for each repo inside the workspace.
+  for (const repo of repos) {
+    const worktreeTarget = path.join(workspacePath, repo.name);
+    await createWorktree(
+      repo.path,
+      worktreeTarget,
+      feature.branchName,
+      repo.defaultBranch,
+    );
+  }
+
+  // Persist the feature manifest.
+  await saveFeatureConfig(workspacePath, feature);
+
+  return workspacePath;
+}
+
+/**
+ * Lists all existing workspaces by reading `nexusflow.json` manifests from
+ * each subdirectory of {@link workspacesDir}.
+ *
+ * Directories that do not contain a valid manifest are silently skipped.
+ *
+ * @param workspacesDir - The root workspaces directory.
+ * @returns An array of {@link Feature} objects for each discovered workspace.
+ */
+export async function listWorkspaces(
+  workspacesDir: string,
+): Promise<Feature[]> {
+  const features: Feature[] = [];
+
+  async function scan(dir: string, depth: number) {
+    if (depth > 3) return;
+
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    // Check if current directory contains a nexusflow.json manifest
+    const hasManifest = entries.some(
+      (e) => e.isFile() && e.name === MANIFEST_FILE,
+    );
+    if (hasManifest) {
+      const loaded = await loadFeatureConfig(dir);
+      if (loaded) {
+        features.push(loaded);
+        return; // Workspaces do not nest.
+      }
+    }
+
+    // Otherwise, recursively scan subdirectories
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await scan(path.join(dir, entry.name), depth + 1);
+      }
+    }
+  }
+
+  await scan(workspacesDir, 1);
+  return features;
+}
+
+/**
+ * Saves a {@link Feature} as `nexusflow.json` inside the given workspace.
+ *
+ * @param workspacePath - Absolute path to the workspace directory.
+ * @param feature       - The feature definition to persist.
+ */
+export async function saveFeatureConfig(
+  workspacePath: string,
+  feature: Feature,
+): Promise<void> {
+  const manifestPath = path.join(workspacePath, MANIFEST_FILE);
+  const data = JSON.stringify(feature, null, 2) + '\n';
+  await fs.writeFile(manifestPath, data, 'utf-8');
+}
+
+/**
+ * Loads a {@link Feature} from the `nexusflow.json` manifest inside a
+ * workspace directory.
+ *
+ * @param workspacePath - Absolute path to the workspace directory.
+ * @returns The loaded feature, or `null` if the manifest doesn't exist or is
+ *          invalid.
+ */
+export async function loadFeatureConfig(
+  workspacePath: string,
+): Promise<Feature | null> {
+  const manifestPath = path.join(workspacePath, MANIFEST_FILE);
+
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf-8');
+    return JSON.parse(raw) as Feature;
+  } catch {
+    return null;
+  }
+}

package/src/core/worktree.ts

@@ -0,0 +1,50 @@
+/**
+ * @module core/worktree
+ * Git worktree operations — create and remove worktrees for feature branches.
+ */
+
+import { execa } from 'execa';
+
+/**
+ * Creates a new git worktree for a feature branch.
+ *
+ * Runs:
+ * 1. `git fetch origin` — ensure we have the latest remote refs.
+ * 2. `git worktree add <targetPath> -b <branchName> origin/<baseBranch>`
+ *
+ * @param repoPath   - Absolute path to the main repo checkout.
+ * @param targetPath - Absolute path where the worktree should be created.
+ * @param branchName - Name of the new local branch to create.
+ * @param baseBranch - Remote branch to base the new branch on (e.g. 'main').
+ */
+export async function createWorktree(
+  repoPath: string,
+  targetPath: string,
+  branchName: string,
+  baseBranch: string,
+): Promise<void> {
+  // Fetch latest remote state.
+  await execa('git', ['fetch', 'origin'], { cwd: repoPath });
+
+  // Create the worktree with a new branch based on the remote base branch.
+  await execa(
+    'git',
+    ['worktree', 'add', targetPath, '-b', branchName, `origin/${baseBranch}`],
+    { cwd: repoPath },
+  );
+}
+
+/**
+ * Removes an existing git worktree.
+ *
+ * Runs `git worktree remove <worktreePath>` from the main repo.
+ *
+ * @param repoPath     - Absolute path to the main repo checkout.
+ * @param worktreePath - Absolute path to the worktree to remove.
+ */
+export async function removeWorktree(
+  repoPath: string,
+  worktreePath: string,
+): Promise<void> {
+  await execa('git', ['worktree', 'remove', worktreePath], { cwd: repoPath });
+}

package/src/generators/base.ts

@@ -0,0 +1,187 @@
+/**
+ * @module generators/base
+ * Builds the shared markdown context content that all AI assistant generators
+ * use as their foundation. Now includes rich project analysis data when available.
+ */
+
+import type { WorkspaceContext, ProjectAnalysis } from '../types.js';
+
+/**
+ * Formats a ProjectAnalysis into a readable markdown section.
+ */
+function formatProjectSection(analysis: ProjectAnalysis): string {
+  const lines: string[] = [];
+
+  lines.push(`### ${analysis.name}`);
+
+  // Tech stack
+  const { techStack } = analysis;
+  if (techStack.languages.length > 0 && techStack.languages[0] !== 'other') {
+    const langStr = techStack.languages.join(', ');
+    const fwStr = techStack.frameworks.length > 0 ? techStack.frameworks.join(', ') : 'none detected';
+    const buildStr = techStack.buildTools.length > 0 ? techStack.buildTools.join(', ') : 'none detected';
+
+    lines.push(`- **Type**: ${techStack.projectType}`);
+    lines.push(`- **Languages**: ${langStr}`);
+    lines.push(`- **Frameworks**: ${fwStr}`);
+    lines.push(`- **Build tools**: ${buildStr}`);
+  }
+
+  // README summary
+  if (analysis.readmeSummary) {
+    // Take first 200 chars of README summary as purpose
+    const purpose = analysis.readmeSummary
+      .replace(/^#\s+.+\n?/, '') // Remove h1 title
+      .trim()
+      .slice(0, 200)
+      .trim();
+    if (purpose) {
+      lines.push(`- **Purpose**: ${purpose}`);
+    }
+  }
+
+  // API endpoints
+  if (analysis.endpoints.length > 0) {
+    lines.push(`- **API endpoints** (${analysis.endpoints.length} detected):`);
+    // Show up to 10 endpoints
+    const shown = analysis.endpoints.slice(0, 10);
+    for (const ep of shown) {
+      lines.push(`  - \`${ep.method} ${ep.path}\``);
+    }
+    if (analysis.endpoints.length > 10) {
+      lines.push(`  - _...and ${analysis.endpoints.length - 10} more_`);
+    }
+  }
+
+  // Ports
+  if (analysis.ports.length > 0) {
+    const portStr = analysis.ports.map((p) => `${p.port} (${p.protocol}, from ${p.source})`).join(', ');
+    lines.push(`- **Ports**: ${portStr}`);
+  }
+
+  // Path
+  lines.push(`- **Path**: \`${analysis.path}\``);
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds the shared markdown context content that all AI assistant generators
+ * use as their foundation. Includes analysis data if available.
+ *
+ * @param ctx - The workspace context containing feature metadata, repo list, and optional analysis.
+ * @returns A markdown string with feature details, repo listing, and task instructions.
+ */
+export function buildContextContent(ctx: WorkspaceContext): string {
+  const { feature, repos, analysis } = ctx;
+
+  // Build project sections — rich if analysis is available, simple if not
+  let projectSections: string;
+
+  if (analysis && analysis.size > 0) {
+    const sections = repos.map((r) => {
+      const a = analysis.get(r.path);
+      if (a) return formatProjectSection(a);
+      return `### ${r.name}\n- **Path**: \`${r.path}\``;
+    });
+    projectSections = sections.join('\n\n');
+  } else {
+    projectSections = repos
+      .map((r) => `- **${r.name}** — \`${r.path}\` (default branch: \`${r.defaultBranch}\`)`)
+      .join('\n');
+  }
+
+  // Build existing AI configs section
+  let existingConfigsSection = '';
+  if (analysis && analysis.size > 0) {
+    const allConfigs: string[] = [];
+    for (const [, a] of analysis) {
+      for (const config of a.existingAIConfigs) {
+        allConfigs.push(`- **${a.name}** has \`${config.relativePath}\` (${config.assistant})`);
+      }
+    }
+    if (allConfigs.length > 0) {
+      existingConfigsSection = `
+---
+
+## Existing AI Configurations
+
+The following repos already have AI assistant configuration files.
+Incorporate their instructions when working in those repos:
+
+${allConfigs.join('\n')}
+`;
+    }
+  }
+
+  // Resumption commands section
+  let resumptionSection = '';
+  if (feature.resumption) {
+    const { testCommand, mockCommand, startCommand } = feature.resumption;
+    const parts: string[] = [];
+    if (mockCommand) parts.push(`- **Setup/Mock Command**: \`${mockCommand}\``);
+    if (startCommand) parts.push(`- **Start/Run Command**: \`${startCommand}\``);
+    if (testCommand) parts.push(`- **Verification/Test Command**: \`${testCommand}\``);
+
+    if (parts.length > 0) {
+      resumptionSection = `
+---
+
+## Workspace Resumption & Verification Commands
+
+Use these pre-configured commands to spin up mocks, run background services, and verify your changes:
+
+${parts.join('\n')}
+`;
+    }
+  }
+
+  return `# Multi-Repo Workspace Context
+
+## Feature: ${feature.id}
+
+**Description:** ${feature.description}
+
+**Branch:** \`${feature.branchName}\`
+**Created:** ${feature.createdAt}
+
+---
+
+## Projects
+
+This workspace contains the following projects, each checked out as a
+git worktree on the feature branch:
+
+${projectSections}
+${existingConfigsSection}
+${resumptionSection}
+---
+
+## Task & Step-by-Step Initialization
+
+Your very first task upon entering this workspace is to analyze the codebase and document it in a universal reference file:
+
+1. **Create \`nexusflow-overview.md\`** at the workspace root.
+2. **Project Assumptions**: For each project, write down a clear assumption of what it does, its primary tech stack, and its core responsibilities.
+3. **Inter-Repo Relationships**: Document how the repos relate:
+   - Shared libraries/packages (producers and consumers).
+   - API boundaries (which repos expose APIs, which ones consume them).
+   - Data flows and dependencies.
+4. **Clarifying Questions**: If any feature requirements, architectural patterns, or API contracts are unclear, list them explicitly under a section called **"Clarifying Questions for the User"**.
+5. **Universal Reference**: Keep this file updated. This acts as a universal reference so that any LLM assistant (Claude, Antigravity, Codex, Cursor, Copilot) joining this workspace instantly understands the project landscape.
+
+Once you have created \`nexusflow-overview.md\` and compiled your questions, ask the user to verify your assumptions and answer your questions before proceeding to write code.
+
+---
+
+## Guidelines
+
+- 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.
+- If a change must span repos, describe the ordering and any migration steps.
+
+
+
+`;
+}

package/src/generators/claude.ts

@@ -0,0 +1,34 @@
+/**
+ * @module generators/claude
+ * Generates a CLAUDE.md file for Claude Code / Antigravity.
+ * Now uses the shared base content builder which includes analysis data.
+ */
+
+import path from 'node:path';
+import fse from 'fs-extra';
+import type { WorkspaceContext } from '../types.js';
+import { buildContextContent } from './base.js';
+
+/**
+ * Generates a `CLAUDE.md` file at the workspace root.
+ *
+ * Claude Code reads this file automatically when opened in a directory,
+ * so it is the primary way to give Claude long-lived project context.
+ *
+ * @param ctx           - The workspace context (feature + repos + analysis).
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateClaudeConfig(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  const content = buildContextContent(ctx);
+  const filePath = path.join(workspacePath, 'CLAUDE.md');
+
+  try {
+    await fse.writeFile(filePath, content, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write CLAUDE.md: ${message}`);
+  }
+}

package/src/generators/codex.ts

@@ -0,0 +1,48 @@
+/**
+ * @module generators/codex
+ * Generates an AGENTS.md file for OpenAI Codex.
+ * Uses the shared base content and adds Codex-specific sections.
+ */
+
+import path from 'node:path';
+import fse from 'fs-extra';
+import type { WorkspaceContext } from '../types.js';
+import { buildContextContent } from './base.js';
+
+/**
+ * Generates an `AGENTS.md` file at the workspace root.
+ *
+ * Codex reads AGENTS.md for persistent context about the workspace.
+ *
+ * @param ctx           - The workspace context (feature + repos + analysis).
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateCodexConfig(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  const baseContent = buildContextContent(ctx);
+
+  const codexExtra = `
+---
+
+## Codex-Specific Notes
+
+- Each project subdirectory may contain its own \`AGENTS.md\` or
+  \`AGENTS.override.md\` with module-specific context.
+- When working in a subdirectory, check for local overrides before
+  applying workspace-level guidance.
+- Use \`codex --approval-mode suggest\` for cross-repo changes to
+  review each change before applying.
+`;
+
+  const content = baseContent + codexExtra;
+  const filePath = path.join(workspacePath, 'AGENTS.md');
+
+  try {
+    await fse.writeFile(filePath, content, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write AGENTS.md: ${message}`);
+  }
+}

package/src/generators/copilot.ts

@@ -0,0 +1,56 @@
+/**
+ * @module generators/copilot
+ * Generates a .github/copilot-instructions.md file for GitHub Copilot.
+ * Uses the shared base content and adds Copilot-specific sections.
+ */
+
+import path from 'node:path';
+import fse from 'fs-extra';
+import type { WorkspaceContext } from '../types.js';
+import { buildContextContent } from './base.js';
+
+/**
+ * Generates a `.github/copilot-instructions.md` file at the workspace root.
+ *
+ * Copilot reads this file for repository-level guidance in Chat and Agent modes.
+ *
+ * @param ctx           - The workspace context (feature + repos + analysis).
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateCopilotConfig(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  const baseContent = buildContextContent(ctx);
+
+  const copilotExtra = `
+---
+
+## Copilot-Specific Notes
+
+- Path-scoped instructions can be added in \`.github/instructions/\`
+  using \`*.instructions.md\` files with YAML frontmatter to target
+  specific file patterns.
+- Example path-scoped file:
+  \`\`\`markdown
+  ---
+  applyTo:
+    - src/frontend/**
+  ---
+  # Frontend Guidelines
+  - Use TypeScript strict mode.
+  \`\`\`
+`;
+
+  const content = baseContent + copilotExtra;
+  const githubDir = path.join(workspacePath, '.github');
+  const filePath = path.join(githubDir, 'copilot-instructions.md');
+
+  try {
+    await fse.ensureDir(githubDir);
+    await fse.writeFile(filePath, content, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write copilot-instructions.md: ${message}`);
+  }
+}

package/src/generators/cursor.ts

@@ -0,0 +1,44 @@
+/**
+ * @module generators/cursor
+ * Generates a .cursor/rules/nexusflow.mdc file for Cursor.
+ * Uses the shared base content with Cursor-specific YAML frontmatter.
+ */
+
+import path from 'node:path';
+import fse from 'fs-extra';
+import type { WorkspaceContext } from '../types.js';
+import { buildContextContent } from './base.js';
+
+/**
+ * Generates a `.cursor/rules/nexusflow.mdc` file at the workspace root.
+ *
+ * Cursor reads `.mdc` rule files from `.cursor/rules/` for project-wide
+ * instructions. The YAML frontmatter controls when the rule is applied.
+ *
+ * @param ctx           - The workspace context (feature + repos + analysis).
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateCursorConfig(
+  ctx: WorkspaceContext,
+  workspacePath: string,
+): Promise<void> {
+  const baseContent = buildContextContent(ctx);
+
+  const content = `---
+description: "NexusFlow workspace context for multi-repo feature development"
+alwaysApply: true
+---
+
+${baseContent}`;
+
+  const rulesDir = path.join(workspacePath, '.cursor', 'rules');
+  const filePath = path.join(rulesDir, 'nexusflow.mdc');
+
+  try {
+    await fse.ensureDir(rulesDir);
+    await fse.writeFile(filePath, content, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to write nexusflow.mdc: ${message}`);
+  }
+}

package/src/generators/index.ts

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+import path from 'node:path';
+import fse from 'fs-extra';
+import type { AIAssistant, WorkspaceContext } from '../types.js';
+import { generateClaudeConfig } from './claude.js';
+import { generateCodexConfig } from './codex.js';
+import { generateCopilotConfig } from './copilot.js';
+import { generateCursorConfig } from './cursor.js';
+import { buildContextContent } from './base.js';
+
+/** Maps each assistant to its generator function and the file it produces. */
+const GENERATORS: Record<
+  AIAssistant,
+  {
+    generate: (ctx: WorkspaceContext, workspacePath: string) => Promise<void>;
+    outputFile: string;
+  }
+> = {
+  claude: { generate: generateClaudeConfig, outputFile: 'CLAUDE.md' },
+  antigravity: { generate: generateClaudeConfig, outputFile: 'CLAUDE.md' },
+  codex: { generate: generateCodexConfig, outputFile: 'AGENTS.md' },
+  copilot: { generate: generateCopilotConfig, outputFile: '.github/copilot-instructions.md' },
+  cursor: { generate: generateCursorConfig, outputFile: '.cursor/rules/nexusflow.mdc' },
+};
+
+/**
+ * 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.
+ *
+ * @param ctx           - The workspace context (feature + repos).
+ * @param assistants    - Which AI assistants to generate context files for.
+ * @param workspacePath - Absolute path to the workspace root directory.
+ */
+export async function generateContextFiles(
+  ctx: WorkspaceContext,
+  assistants: AIAssistant[],
+  workspacePath: string,
+): Promise<void> {
+  // Always generate a universal WORKSPACE.md at the workspace root
+  try {
+    const content = buildContextContent(ctx);
+    const filePath = path.join(workspacePath, 'WORKSPACE.md');
+    await fse.writeFile(filePath, content, 'utf-8');
+    console.log(
+      chalk.green('  ✔'),
+      `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`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      chalk.red('  ✖'),
+      `Failed to generate universal context files: ${message}`,
+    );
+  }
+
+  for (const assistant of assistants) {
+    const entry = GENERATORS[assistant];
+
+    try {
+      await entry.generate(ctx, workspacePath);
+      console.log(
+        chalk.green('  ✔'),
+        `Generated ${chalk.bold(entry.outputFile)} for ${assistant}`,
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        chalk.red('  ✖'),
+        `Failed to generate ${entry.outputFile} for ${assistant}: ${message}`,
+      );
+    }
+  }
+}
+
+// Re-export individual generators for direct use
+export { generateClaudeConfig } from './claude.js';
+export { generateCodexConfig } from './codex.js';
+export { generateCopilotConfig } from './copilot.js';
+export { generateCursorConfig } from './cursor.js';
+export { buildContextContent } from './base.js';