@mrpatronz/nexusflow 0.1.0

package/src/analyzers/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @module analyzers/index
+ * Orchestrates all project analyzers and produces a full ProjectAnalysis
+ * for each repository.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+
+import type { ProjectAnalysis, RepoInfo } from '../types.js';
+import { detectTechStack } from './tech-stack.js';
+import { detectApis } from './detect-apis.js';
+import { detectDependencies } from './detect-deps.js';
+import { detectPorts } from './detect-ports.js';
+import { detectExistingAIConfigs } from './detect-existing.js';
+import { extractReadmeSummary } from './readme-summarizer.js';
+
+/**
+ * Runs all analyzers against a single repository and returns
+ * a complete {@link ProjectAnalysis}.
+ *
+ * @param repo - The repo metadata.
+ * @returns Full analysis result.
+ */
+export async function analyzeRepo(repo: RepoInfo): Promise<ProjectAnalysis> {
+  const [techStack, endpoints, dependencies, ports, existingAIConfigs, readmeSummary] =
+    await Promise.all([
+      detectTechStack(repo.path),
+      detectApis(repo.path),
+      detectDependencies(repo.path),
+      detectPorts(repo.path),
+      detectExistingAIConfigs(repo.path),
+      extractReadmeSummary(repo.path),
+    ]);
+
+  return {
+    name: repo.name,
+    path: repo.path,
+    techStack,
+    endpoints,
+    dependencies,
+    ports,
+    existingAIConfigs,
+    readmeSummary,
+  };
+}
+
+/**
+ * Analyzes all repos in a list and returns a Map of path → analysis.
+ * Shows a progress spinner while running.
+ *
+ * @param repos - Array of repos to analyze.
+ * @returns Map of repo path to {@link ProjectAnalysis}.
+ */
+export async function analyzeAllRepos(
+  repos: RepoInfo[],
+): Promise<Map<string, ProjectAnalysis>> {
+  const spinner = ora('Analyzing projects...').start();
+  const results = new Map<string, ProjectAnalysis>();
+
+  for (let i = 0; i < repos.length; i++) {
+    const repo = repos[i]!;
+    spinner.text = `Analyzing ${chalk.bold(repo.name)} (${i + 1}/${repos.length})...`;
+
+    try {
+      const analysis = await analyzeRepo(repo);
+      results.set(repo.path, analysis);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      spinner.warn(`Failed to analyze ${repo.name}: ${msg}`);
+      spinner.start();
+    }
+  }
+
+  spinner.succeed(`Analyzed ${chalk.bold(results.size)} projects`);
+  return results;
+}
+
+// Re-export individual analyzers
+export { detectTechStack } from './tech-stack.js';
+export { detectApis } from './detect-apis.js';
+export { detectDependencies, findInterRepoDependencies } from './detect-deps.js';
+export { detectPorts } from './detect-ports.js';
+export { detectExistingAIConfigs } from './detect-existing.js';
+export { extractReadmeSummary } from './readme-summarizer.js';

package/src/analyzers/readme-summarizer.ts

@@ -0,0 +1,68 @@
+/**
+ * @module analyzers/readme-summarizer
+ * Extracts a summary from a repository's README.md file.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+/** Maximum chars to extract from README for summary. */
+const MAX_SUMMARY_LENGTH = 800;
+
+/**
+ * Reads a repository's README.md and extracts the first meaningful
+ * section as a summary. Looks for README.md (case-insensitive).
+ *
+ * @param repoPath - Absolute path to the repository root.
+ * @returns The extracted summary text, or null if no README is found.
+ */
+export async function extractReadmeSummary(
+  repoPath: string,
+): Promise<string | null> {
+  // Try common README filenames
+  const candidates = ['README.md', 'readme.md', 'Readme.md', 'README.MD', 'README'];
+
+  let content: string | null = null;
+
+  for (const filename of candidates) {
+    try {
+      content = await fs.readFile(path.join(repoPath, filename), 'utf-8');
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  if (!content) return null;
+
+  // Strip badges, images, and HTML at the top
+  const lines = content.split('\n');
+  const meaningfulLines: string[] = [];
+  let foundContent = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines before content starts
+    if (!foundContent && !trimmed) continue;
+
+    // Skip badge lines ([![...](...)]) and image lines (![...](...)
+    if (trimmed.startsWith('[![') || (trimmed.startsWith('![') && trimmed.includes('http'))) continue;
+
+    // Skip HTML tags
+    if (trimmed.startsWith('<') && trimmed.endsWith('>')) continue;
+
+    // Skip horizontal rules
+    if (/^(-{3,}|={3,}|\*{3,})$/.test(trimmed)) continue;
+
+    foundContent = true;
+    meaningfulLines.push(line);
+
+    // Stop after we have enough content
+    const currentLength = meaningfulLines.join('\n').length;
+    if (currentLength >= MAX_SUMMARY_LENGTH) break;
+  }
+
+  const summary = meaningfulLines.join('\n').slice(0, MAX_SUMMARY_LENGTH).trim();
+  return summary || null;
+}

package/src/analyzers/tech-stack.ts

@@ -0,0 +1,255 @@
+/**
+ * @module analyzers/tech-stack
+ * Detects the language, framework, build tools, and project type
+ * of a repository by inspecting manifest files.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type { TechStack, Language, Framework, ProjectType } from '../types.js';
+
+/** Check if a file exists in a directory. */
+async function fileExists(dir: string, filename: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(dir, filename));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Safely read and parse a JSON file. Returns null on failure. */
+async function readJson(filePath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Check if any file matching a glob-like pattern exists. */
+async function hasFileWithExtension(dir: string, ext: string): Promise<boolean> {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.some((e) => e.endsWith(ext));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detects the tech stack of a repository by inspecting its root directory
+ * for manifest files, config files, and project structures.
+ *
+ * @param repoPath - Absolute path to the repository root.
+ * @returns A {@link TechStack} object describing the detected stack.
+ */
+export async function detectTechStack(repoPath: string): Promise<TechStack> {
+  const languages: Language[] = [];
+  const frameworks: Framework[] = [];
+  const buildTools: string[] = [];
+  let projectType: ProjectType = 'other';
+
+  // ── Node.js / JavaScript / TypeScript ──────────────────────────────
+  const hasPackageJson = await fileExists(repoPath, 'package.json');
+  if (hasPackageJson) {
+    const pkg = await readJson(path.join(repoPath, 'package.json'));
+
+    // Detect TypeScript vs JavaScript
+    const hasTsConfig = await fileExists(repoPath, 'tsconfig.json');
+    if (hasTsConfig) {
+      languages.push('typescript');
+    } else {
+      languages.push('javascript');
+    }
+
+    if (pkg) {
+      const allDeps = {
+        ...(pkg.dependencies as Record<string, string> | undefined),
+        ...(pkg.devDependencies as Record<string, string> | undefined),
+      };
+
+      // Frameworks
+      if (allDeps['next']) { frameworks.push('nextjs'); projectType = 'fullstack'; }
+      if (allDeps['react'] && !allDeps['next']) { frameworks.push('react'); projectType = 'frontend'; }
+      if (allDeps['@angular/core']) { frameworks.push('angular'); projectType = 'frontend'; }
+      if (allDeps['vue']) { frameworks.push('vue'); projectType = 'frontend'; }
+      if (allDeps['svelte']) { frameworks.push('svelte'); projectType = 'frontend'; }
+      if (allDeps['express']) { frameworks.push('express'); projectType = 'backend'; }
+      if (allDeps['@nestjs/core']) { frameworks.push('nestjs'); projectType = 'backend'; }
+      if (allDeps['fastify']) { frameworks.push('fastify'); projectType = 'backend'; }
+      if (allDeps['hono']) { frameworks.push('hono'); projectType = 'backend'; }
+
+      // Build tools
+      if (allDeps['vite'] || allDeps['@vitejs/plugin-react']) buildTools.push('vite');
+      if (allDeps['webpack']) buildTools.push('webpack');
+      if (allDeps['esbuild']) buildTools.push('esbuild');
+      if (allDeps['rollup']) buildTools.push('rollup');
+      if (allDeps['turbo']) buildTools.push('turborepo');
+      if (allDeps['nx']) buildTools.push('nx');
+
+      // Project type heuristics
+      if (pkg.bin) projectType = 'cli';
+      if (pkg.main && !pkg.bin && frameworks.length === 0) projectType = 'library';
+    }
+  }
+
+  // ── .NET / C# ─────────────────────────────────────────────────────
+  const hasCsproj = await hasFileWithExtension(repoPath, '.csproj');
+  const hasSln = await hasFileWithExtension(repoPath, '.sln');
+  if (hasCsproj || hasSln) {
+    languages.push('csharp');
+
+    // Try to detect ASP.NET or Blazor from csproj content
+    try {
+      const entries = await fs.readdir(repoPath);
+      const csprojFile = entries.find((e) => e.endsWith('.csproj'));
+      if (csprojFile) {
+        const content = await fs.readFile(path.join(repoPath, csprojFile), 'utf-8');
+        if (content.includes('Microsoft.NET.Sdk.Web')) {
+          frameworks.push('aspnet');
+          projectType = 'backend';
+        }
+        if (content.includes('Microsoft.NET.Sdk.BlazorWebAssembly') || content.includes('Blazor')) {
+          frameworks.push('blazor');
+          projectType = 'frontend';
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+
+    buildTools.push('dotnet');
+  }
+
+  // ── Python ────────────────────────────────────────────────────────
+  const hasPyproject = await fileExists(repoPath, 'pyproject.toml');
+  const hasRequirements = await fileExists(repoPath, 'requirements.txt');
+  const hasSetupPy = await fileExists(repoPath, 'setup.py');
+  if (hasPyproject || hasRequirements || hasSetupPy) {
+    languages.push('python');
+
+    // Try to detect frameworks from requirements
+    try {
+      let content = '';
+      if (hasRequirements) {
+        content = await fs.readFile(path.join(repoPath, 'requirements.txt'), 'utf-8');
+      } else if (hasPyproject) {
+        content = await fs.readFile(path.join(repoPath, 'pyproject.toml'), 'utf-8');
+      }
+      const lower = content.toLowerCase();
+      if (lower.includes('django')) { frameworks.push('django'); projectType = 'backend'; }
+      if (lower.includes('flask')) { frameworks.push('flask'); projectType = 'backend'; }
+      if (lower.includes('fastapi')) { frameworks.push('fastapi'); projectType = 'backend'; }
+    } catch {
+      // Ignore
+    }
+
+    if (hasPyproject) buildTools.push('pyproject');
+    if (hasSetupPy) buildTools.push('setuptools');
+  }
+
+  // ── Go ────────────────────────────────────────────────────────────
+  const hasGoMod = await fileExists(repoPath, 'go.mod');
+  if (hasGoMod) {
+    languages.push('go');
+    buildTools.push('go');
+
+    try {
+      const content = await fs.readFile(path.join(repoPath, 'go.mod'), 'utf-8');
+      if (content.includes('github.com/gin-gonic/gin')) {
+        frameworks.push('gin');
+        projectType = 'backend';
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // ── Java ──────────────────────────────────────────────────────────
+  const hasPom = await fileExists(repoPath, 'pom.xml');
+  const hasGradle = await fileExists(repoPath, 'build.gradle');
+  const hasGradleKts = await fileExists(repoPath, 'build.gradle.kts');
+  if (hasPom || hasGradle || hasGradleKts) {
+    languages.push('java');
+    if (hasPom) buildTools.push('maven');
+    if (hasGradle || hasGradleKts) buildTools.push('gradle');
+
+    try {
+      let content = '';
+      if (hasPom) {
+        content = await fs.readFile(path.join(repoPath, 'pom.xml'), 'utf-8');
+      } else if (hasGradle) {
+        content = await fs.readFile(path.join(repoPath, 'build.gradle'), 'utf-8');
+      }
+      if (content.includes('spring')) {
+        frameworks.push('spring');
+        projectType = 'backend';
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // ── Rust ──────────────────────────────────────────────────────────
+  const hasCargo = await fileExists(repoPath, 'Cargo.toml');
+  if (hasCargo) {
+    languages.push('rust');
+    buildTools.push('cargo');
+  }
+
+  // ── Ruby ──────────────────────────────────────────────────────────
+  const hasGemfile = await fileExists(repoPath, 'Gemfile');
+  if (hasGemfile) {
+    languages.push('ruby');
+    buildTools.push('bundler');
+
+    try {
+      const content = await fs.readFile(path.join(repoPath, 'Gemfile'), 'utf-8');
+      if (content.includes('rails')) {
+        frameworks.push('rails');
+        projectType = 'backend';
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // ── PHP ───────────────────────────────────────────────────────────
+  const hasComposer = await fileExists(repoPath, 'composer.json');
+  if (hasComposer) {
+    languages.push('php');
+    buildTools.push('composer');
+
+    const composer = await readJson(path.join(repoPath, 'composer.json'));
+    if (composer) {
+      const req = composer.require as Record<string, string> | undefined;
+      if (req?.['laravel/framework']) {
+        frameworks.push('laravel');
+        projectType = 'backend';
+      }
+    }
+  }
+
+  // ── Docker ────────────────────────────────────────────────────────
+  if (await fileExists(repoPath, 'Dockerfile')) {
+    buildTools.push('docker');
+  }
+  if (await fileExists(repoPath, 'docker-compose.yml') || await fileExists(repoPath, 'compose.yaml')) {
+    buildTools.push('docker-compose');
+  }
+
+  // Fallback
+  if (languages.length === 0) {
+    languages.push('other');
+  }
+
+  return {
+    languages,
+    frameworks,
+    buildTools,
+    projectType,
+  };
+}

package/src/commands/create.ts

@@ -0,0 +1,142 @@
+/**
+ * @module commands/create
+ * The main "create workspace" command — the core NexusFlow workflow.
+ * Mirrors and enhances the user's existing Create-Workspace.ps1 script.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import path from 'node:path';
+import { execa } from 'execa';
+
+import { loadConfig } from '../core/config.js';
+import { scanForRepos } from '../core/scanner.js';
+import { createWorkspace } from '../core/workspace.js';
+import { generateContextFiles } from '../generators/index.js';
+import { analyzeAllRepos } from '../analyzers/index.js';
+import { detectAIAssistants } from '../utils/detect-ai.js';
+import { detectEditors } from '../utils/detect-editors.js';
+import {
+  promptBranchName,
+  promptDescription,
+  promptSelectRepos,
+  promptSelectAI,
+  promptSelectEditor,
+} from '../utils/prompts.js';
+import type { Feature, WorkspaceContext } from '../types.js';
+
+/**
+ * Executes the full "create workspace" flow:
+ * 1. Prompt for branch name
+ * 2. Prompt for feature description
+ * 3. Scan for repos and let user pick
+ * 4. Detect AI assistants and let user pick
+ * 5. Create workspace with git worktrees
+ * 6. Generate AI context files
+ * 7. Optionally open in editor
+ */
+export async function createCommand(): Promise<void> {
+  console.log(
+    chalk.bold.cyan('\n🚀 NexusFlow — Create Feature Workspace\n'),
+  );
+
+  // ── 1. Branch name ──────────────────────────────────────────────────
+  const branchName = await promptBranchName();
+
+  // ── 2. Feature description ──────────────────────────────────────────
+  const description = await promptDescription();
+
+  // ── 3. Scan for repos ───────────────────────────────────────────────
+  const config = await loadConfig();
+  const spinner = ora('Scanning for projects...').start();
+
+  let repos;
+  try {
+    repos = await scanForRepos(config.devDir, config.scanDepth);
+    spinner.succeed(`Found ${chalk.bold(repos.length)} projects in ${config.devDir}`);
+  } catch (error) {
+    spinner.fail('Failed to scan for projects');
+    throw error;
+  }
+
+  if (repos.length === 0) {
+    console.log(chalk.yellow('No git projects found. Check your devDir setting.'));
+    return;
+  }
+
+  // ── 4. Select repos ────────────────────────────────────────────────
+  const selectedRepos = await promptSelectRepos(repos);
+  if (selectedRepos.length === 0) {
+    console.log(chalk.yellow('No projects selected. Exiting.'));
+    return;
+  }
+
+  console.log(
+    chalk.dim(`  Selected: ${selectedRepos.map((r) => r.name).join(', ')}`),
+  );
+
+  // ── 5. Detect and select AI assistants ──────────────────────────────
+  const detectedAI = await detectAIAssistants();
+  const selectedAI = await promptSelectAI(detectedAI);
+
+  // ── 6. Create workspace ─────────────────────────────────────────────
+  const workspacePath = path.join(config.workspacesDir, branchName);
+  const feature: Feature = {
+    id: branchName,
+    branchName,
+    description,
+    repos: selectedRepos.map((r) => r.path),
+    assistants: selectedAI,
+    workspacePath,
+    createdAt: new Date().toISOString(),
+  };
+
+  const wsSpinner = ora('Creating workspace with git worktrees...').start();
+  try {
+    await createWorkspace(feature, selectedRepos);
+    wsSpinner.succeed(`Workspace created at ${chalk.bold(workspacePath)}`);
+  } catch (error) {
+    wsSpinner.fail('Failed to create workspace');
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`  ${message}`));
+    return;
+  }
+
+  // ── 7. Analyze projects ─────────────────────────────────────────────
+  console.log(chalk.cyan('\nAnalyzing projects...'));
+  const analysis = await analyzeAllRepos(selectedRepos);
+
+  // ── 8. Generate AI context files ────────────────────────────────────
+  const ctx: WorkspaceContext = { feature, repos: selectedRepos, analysis };
+  console.log(chalk.cyan('\nGenerating AI context files...'));
+  await generateContextFiles(ctx, selectedAI, workspacePath);
+
+  // ── 8. Open in editor ───────────────────────────────────────────────
+  const detectedEditors = await detectEditors();
+  const editor = await promptSelectEditor(detectedEditors);
+
+  if (editor) {
+    const editorSpinner = ora(`Opening in ${editor.name}...`).start();
+    try {
+      await execa(editor.command, [workspacePath], { stdio: 'ignore' });
+      editorSpinner.succeed(`Opened in ${editor.name}`);
+    } catch {
+      editorSpinner.warn(
+        `Could not open ${editor.name}. Open manually:\n  ${chalk.dim(`cd "${workspacePath}"`)}`,
+      );
+    }
+  }
+
+  // ── Done ────────────────────────────────────────────────────────────
+  console.log(
+    chalk.bold.green('\n✅ Workspace ready!\n'),
+  );
+  console.log(`  ${chalk.dim('Path:')}  ${workspacePath}`);
+  console.log(`  ${chalk.dim('Branch:')} ${branchName}`);
+  console.log(`  ${chalk.dim('Repos:')}  ${selectedRepos.map((r) => r.name).join(', ')}`);
+  console.log(`  ${chalk.dim('AI:')}     ${selectedAI.join(', ')}`);
+  console.log(
+    `\n  ${chalk.dim('To navigate:')} cd "${workspacePath}"`,
+  );
+  console.log();
+}

package/src/commands/init.ts

@@ -0,0 +1,58 @@
+/**
+ * @module commands/init
+ * Initializes the NexusFlow configuration.
+ */
+
+import chalk from 'chalk';
+import { input } from '@inquirer/prompts';
+import path from 'node:path';
+import os from 'node:os';
+
+import { loadConfig, saveConfig, ensureConfigDir } from '../core/config.js';
+
+/**
+ * Initializes NexusFlow configuration interactively.
+ * Creates ~/.nexusflow/config.json with user preferences.
+ */
+export async function initCommand(): Promise<void> {
+  console.log(chalk.bold.cyan('\n⚙️  NexusFlow — Initialize\n'));
+
+  await ensureConfigDir();
+  const existing = await loadConfig();
+
+  const devDir = await input({
+    message: 'Development directory (where your repos live):',
+    default: existing.devDir || path.join(os.homedir(), 'dev'),
+  });
+
+  const workspacesDir = await input({
+    message: 'Workspaces directory (where feature workspaces are created):',
+    default: existing.workspacesDir || path.join(devDir, 'workspaces'),
+  });
+
+  const scanDepth = await input({
+    message: 'How deep to scan for repos (directory levels):',
+    default: String(existing.scanDepth || 2),
+    validate: (value: string) => {
+      const num = parseInt(value, 10);
+      if (isNaN(num) || num < 1 || num > 10) return 'Enter a number between 1 and 10';
+      return true;
+    },
+  });
+
+  const config = {
+    ...existing,
+    devDir: devDir.trim(),
+    workspacesDir: workspacesDir.trim(),
+    scanDepth: parseInt(scanDepth, 10),
+  };
+
+  await saveConfig(config);
+
+  console.log(chalk.green('\n✅ Configuration saved!\n'));
+  console.log(chalk.dim('  Config file: ~/.nexusflow/config.json'));
+  console.log(chalk.dim(`  Dev dir:     ${config.devDir}`));
+  console.log(chalk.dim(`  Workspaces:  ${config.workspacesDir}`));
+  console.log(chalk.dim(`  Scan depth:  ${config.scanDepth}`));
+  console.log(chalk.dim('\n  Run "nexusflow create" to create your first workspace.\n'));
+}

package/src/commands/list.ts

@@ -0,0 +1,46 @@
+/**
+ * @module commands/list
+ * Lists all existing NexusFlow workspaces.
+ */
+
+import chalk from 'chalk';
+
+import { loadConfig } from '../core/config.js';
+import { listWorkspaces } from '../core/workspace.js';
+
+/**
+ * Lists all existing workspaces, showing feature name, repos, and status.
+ */
+export async function listCommand(): Promise<void> {
+  const config = await loadConfig();
+  const workspaces = await listWorkspaces(config.workspacesDir);
+
+  if (workspaces.length === 0) {
+    console.log(chalk.yellow('\nNo workspaces found.'));
+    console.log(chalk.dim(`  Workspaces directory: ${config.workspacesDir}`));
+    console.log(chalk.dim('  Run "nexusflow create" to create your first workspace.\n'));
+    return;
+  }
+
+  console.log(chalk.bold.cyan(`\n📂 NexusFlow Workspaces (${workspaces.length})\n`));
+
+  for (const ws of workspaces) {
+    const repoCount = ws.repos.length;
+    const aiList = ws.assistants.join(', ');
+    const date = new Date(ws.createdAt).toLocaleDateString();
+
+    console.log(
+      `  ${chalk.bold(ws.branchName)} ${chalk.dim(`(${date})`)}`,
+    );
+    console.log(
+      `    ${chalk.dim('Repos:')}  ${repoCount} project${repoCount !== 1 ? 's' : ''}`,
+    );
+    console.log(
+      `    ${chalk.dim('AI:')}     ${aiList || 'none'}`,
+    );
+    console.log(
+      `    ${chalk.dim('Path:')}   ${ws.workspacePath}`,
+    );
+    console.log();
+  }
+}