@mrpatronz/nexusflow 0.1.0

package/src/types.ts

@@ -0,0 +1,294 @@
+/**
+ * @module types
+ * Shared interfaces and types for NexusFlow.
+ */
+
+/** Supported AI assistant identifiers. */
+export type AIAssistant = 'claude' | 'antigravity' | 'codex' | 'copilot' | 'cursor';
+
+/** Top-level NexusFlow configuration stored in ~/.nexusflow/config.json. */
+export interface NexusFlowConfig {
+  /** Semantic version of the NexusFlow config schema. */
+  version: string;
+
+  /** Root development directory. Default: ~/dev */
+  devDir: string;
+
+  /** Directory where workspaces are created. Default: ~/dev/workspaces */
+  workspacesDir: string;
+
+  /** The user's preferred AI assistant, or null if none chosen yet. */
+  defaultAssistant: AIAssistant | null;
+
+  /** How many directory levels deep to scan for git repos. Default: 2 */
+  scanDepth: number;
+}
+
+/** Result of probing for an AI assistant on the system. */
+export interface DetectedAI {
+  /** Canonical assistant identifier. */
+  name: AIAssistant;
+
+  /** Human-readable label shown in prompts. */
+  displayName: string;
+
+  /** Whether the assistant's CLI was found. */
+  detected: boolean;
+
+  /** The CLI command that was detected (e.g. 'claude', 'antigravity'). */
+  command?: string;
+}
+
+/** Result of probing for a code editor on the system. */
+export interface DetectedEditor {
+  /** Human-readable editor name. */
+  name: string;
+
+  /** CLI command used to launch the editor. */
+  command: string;
+
+  /** Whether the editor's CLI was found in PATH. */
+  detected: boolean;
+}
+
+/** Metadata about a discovered git repository. */
+export interface RepoInfo {
+  /** Directory name of the repo. */
+  name: string;
+
+  /** Absolute path to the repo root. */
+  path: string;
+
+  /** Default branch — typically 'main' or 'master'. */
+  defaultBranch: string;
+}
+
+/** Metadata about a past AI session. */
+export interface AISession {
+  id: string;
+  assistant: AIAssistant;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  messageCount: number;
+  workspacePath: string;
+}
+
+/** A single chat message in a session transcript. */
+export interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp?: string;
+}
+
+
+/** Configuration for resuming the active session. */
+export interface ResumptionConfig {
+  /** The command to run verification tests. */
+  testCommand?: string;
+  /** The command to spin up dev databases/mocks/caches. */
+  mockCommand?: string;
+  /** The command to start workspace services manually if needed. */
+  startCommand?: string;
+}
+
+/** A feature workspace that spans one or more repos. */
+export interface Feature {
+  /** Unique identifier — the git branch name. */
+  id: string;
+
+  /** Git branch name created for this feature. */
+  branchName: string;
+
+  /** Short human-readable description of the feature. */
+  description: string;
+
+  /** Absolute paths to the repos included in this feature. */
+  repos: string[];
+
+  /** AI assistants enabled for this feature workspace. */
+  assistants: AIAssistant[];
+
+  /** Absolute path to the workspace directory on disk. */
+  workspacePath: string;
+
+  /** ISO-8601 timestamp of when the feature was created. */
+  createdAt: string;
+
+  /** Resumption configuration. */
+  resumption?: ResumptionConfig;
+}
+
+/** Runtime context for an active workspace — now includes analysis data. */
+export interface WorkspaceContext {
+  /** The feature definition. */
+  feature: Feature;
+
+  /** Full repo metadata for every repo in the feature. */
+  repos: RepoInfo[];
+
+  /** Analysis results for each repo (keyed by repo path). */
+  analysis?: Map<string, ProjectAnalysis>;
+}
+
+// ─── Phase 2: Project Analysis Types ──────────────────────────────────────
+
+/** Recognized language/runtime. */
+export type Language =
+  | 'typescript'
+  | 'javascript'
+  | 'csharp'
+  | 'python'
+  | 'go'
+  | 'java'
+  | 'rust'
+  | 'ruby'
+  | 'php'
+  | 'other';
+
+/** Recognized framework. */
+export type Framework =
+  | 'react'
+  | 'nextjs'
+  | 'angular'
+  | 'vue'
+  | 'svelte'
+  | 'express'
+  | 'nestjs'
+  | 'fastify'
+  | 'hono'
+  | 'aspnet'
+  | 'blazor'
+  | 'django'
+  | 'flask'
+  | 'fastapi'
+  | 'gin'
+  | 'spring'
+  | 'rails'
+  | 'laravel'
+  | 'other';
+
+/** Recognized project type. */
+export type ProjectType =
+  | 'frontend'
+  | 'backend'
+  | 'fullstack'
+  | 'library'
+  | 'api'
+  | 'cli'
+  | 'worker'
+  | 'other';
+
+/** Detected tech stack for a repo. */
+export interface TechStack {
+  languages: Language[];
+  frameworks: Framework[];
+  buildTools: string[];
+  projectType: ProjectType;
+}
+
+/** A detected API endpoint or route. */
+export interface ApiEndpoint {
+  method: string;
+  path: string;
+  source?: string;
+}
+
+/** An inter-repo dependency reference. */
+export interface RepoDependency {
+  /** Name of the dependency (npm package, NuGet package, etc.). */
+  name: string;
+  /** Type of dependency. */
+  type: 'npm' | 'nuget' | 'pip' | 'go' | 'other';
+  /** Version constraint if known. */
+  version?: string;
+}
+
+/** Port/service configuration detected in a repo. */
+export interface ServicePort {
+  port: number;
+  protocol: 'http' | 'https' | 'grpc' | 'other';
+  source: string;
+}
+
+/** Full analysis result for a single project/repo. */
+export interface ProjectAnalysis {
+  /** Repo name. */
+  name: string;
+  /** Repo path. */
+  path: string;
+  /** Detected tech stack. */
+  techStack: TechStack;
+  /** Detected API endpoints. */
+  endpoints: ApiEndpoint[];
+  /** Detected dependencies. */
+  dependencies: RepoDependency[];
+  /** Detected ports/services. */
+  ports: ServicePort[];
+  /** Summary from README.md if found. */
+  readmeSummary: string | null;
+  /** Existing AI config files found in the repo. */
+  existingAIConfigs: ExistingAIConfig[];
+}
+
+/** An existing AI configuration file found in a repo. */
+export interface ExistingAIConfig {
+  /** Which assistant this config is for. */
+  assistant: AIAssistant | 'agents';
+  /** File path relative to repo root. */
+  relativePath: string;
+  /** First 500 chars of the content for context. */
+  contentPreview: string;
+}
+
+// ─── Phase 3: Service Orchestration Types ─────────────────────────────────
+
+/** How to start a single service/project. */
+export interface ServiceConfig {
+  /** Display name for the service. */
+  name: string;
+  /** Absolute path to the project directory. */
+  cwd: string;
+  /** The command to run (e.g., 'npm', 'dotnet', 'python'). */
+  command: string;
+  /** Arguments for the command. */
+  args: string[];
+  /** Optional port the service listens on. */
+  port?: number;
+  /** How the start command was detected. */
+  source: 'package.json' | 'dotnet' | 'docker-compose' | 'aspire' | 'python' | 'go' | 'makefile' | 'manual';
+}
+
+/** Detected orchestration tool in a workspace. */
+export interface OrchestrationDetection {
+  /** Which tool was found. */
+  tool: 'docker-compose' | 'aspire' | 'tilt' | 'procfile' | 'makefile';
+  /** Path to the config file. */
+  configPath: string;
+  /** Start command for this tool. */
+  startCommand: string;
+  /** Stop command for this tool. */
+  stopCommand: string;
+}
+
+/** A currently running service process. */
+export interface RunningService {
+  /** Service name. */
+  name: string;
+  /** Process ID. */
+  pid: number;
+  /** Service config used to start it. */
+  config: ServiceConfig;
+  /** Timestamp when started. */
+  startedAt: string;
+}
+
+/** State file saved to track running services. */
+export interface RunningState {
+  /** Workspace path this state belongs to. */
+  workspacePath: string;
+  /** List of running services. */
+  services: RunningService[];
+  /** Timestamp when the state was last updated. */
+  updatedAt: string;
+}

package/src/utils/detect-ai.ts

@@ -0,0 +1,81 @@
+/**
+ * @module utils/detect-ai
+ * Detects which AI coding assistants are available on the system.
+ */
+
+import { execa } from 'execa';
+
+import type { AIAssistant, DetectedAI } from '../types.js';
+
+/**
+ * Attempts to run `<command> --version` and returns `true` if the process
+ * exits successfully (exit code 0).
+ */
+async function commandExists(command: string): Promise<boolean> {
+  try {
+    const result = await execa(command, ['--version'], { reject: false });
+    return result.exitCode === 0;
+  } catch {
+    // The command could not be spawned at all (not in PATH).
+    return false;
+  }
+}
+
+/**
+ * Probes the system for known AI coding assistants and returns their status.
+ *
+ * Detection rules:
+ * - **Claude**: detected if `claude` *or* `antigravity` is on PATH.
+ *   When Antigravity is found it is labelled as `'claude'` because it
+ *   generates `CLAUDE.md` context files.
+ * - **Codex**: detected if `codex` is on PATH.
+ * - **Copilot**: always shown as an option (convention-based via
+ *   `.github/copilot-instructions.md`).
+ * - **Cursor**: detected if `cursor` is on PATH.
+ *
+ * @returns An array of {@link DetectedAI} results, one per assistant.
+ */
+export async function detectAIAssistants(): Promise<DetectedAI[]> {
+  // Run all probes concurrently.
+  const [hasClaude, hasAntigravity, hasCodex, hasCursor] = await Promise.all([
+    commandExists('claude'),
+    commandExists('agy'),
+    commandExists('codex'),
+    commandExists('cursor'),
+  ]);
+
+  const results: DetectedAI[] = [
+    {
+      name: 'claude' as AIAssistant,
+      displayName: 'Claude Code',
+      detected: hasClaude,
+      ...(hasClaude ? { command: 'claude' } : {}),
+    },
+    {
+      name: 'antigravity' as AIAssistant,
+      displayName: 'Antigravity',
+      detected: hasAntigravity,
+      ...(hasAntigravity ? { command: 'agy' } : {}),
+    },
+    {
+      name: 'codex' as AIAssistant,
+      displayName: 'OpenAI Codex',
+      detected: hasCodex,
+      ...(hasCodex ? { command: 'codex' } : {}),
+    },
+    {
+      name: 'copilot' as AIAssistant,
+      displayName: 'GitHub Copilot',
+      // Copilot is convention-based; always available as an option.
+      detected: true,
+    },
+    {
+      name: 'cursor' as AIAssistant,
+      displayName: 'Cursor',
+      detected: hasCursor,
+      ...(hasCursor ? { command: 'cursor' } : {}),
+    },
+  ];
+
+  return results;
+}

package/src/utils/detect-editors.ts

@@ -0,0 +1,54 @@
+/**
+ * @module utils/detect-editors
+ * Detects which code editors are available on the system.
+ */
+
+import { execa } from 'execa';
+
+import type { DetectedEditor } from '../types.js';
+
+/** Editor definitions we probe for. */
+const EDITOR_CANDIDATES: ReadonlyArray<{ name: string; command: string }> = [
+  { name: 'VS Code', command: 'code' },
+  { name: 'VS Code Insiders', command: 'code-insiders' },
+  { name: 'Cursor', command: 'cursor' },
+  { name: 'Antigravity', command: 'agy' },
+];
+
+/**
+ * Attempts to run `<command> --version` and returns `true` if the process
+ * exits successfully (exit code 0).
+ */
+async function commandExists(command: string): Promise<boolean> {
+  try {
+    const result = await execa(command, ['--version'], { reject: false });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probes the system for known code editors by checking whether their CLI
+ * commands are available on PATH.
+ *
+ * Currently checks for:
+ * - **VS Code** (`code`)
+ * - **VS Code Insiders** (`code-insiders`)
+ * - **Cursor** (`cursor`)
+ * - **Antigravity** (`antigravity`)
+ *
+ * @returns An array of {@link DetectedEditor} results, one per editor.
+ */
+export async function detectEditors(): Promise<DetectedEditor[]> {
+  const probes = EDITOR_CANDIDATES.map(async (editor) => {
+    const detected = await commandExists(editor.command);
+    return {
+      name: editor.name,
+      command: editor.command,
+      detected,
+    } satisfies DetectedEditor;
+  });
+
+  return Promise.all(probes);
+}

package/src/utils/git.ts

@@ -0,0 +1,61 @@
+/**
+ * @module utils/git
+ * Low-level git helper functions used throughout NexusFlow.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execa } from 'execa';
+
+/**
+ * Checks whether the given directory is a git repository
+ * by testing for the presence of a `.git` entry.
+ *
+ * @param dirPath - Absolute path to the directory.
+ * @returns `true` if a `.git` file or directory exists.
+ */
+export async function isGitRepo(dirPath: string): Promise<boolean> {
+  try {
+    const gitPath = path.join(dirPath, '.git');
+    await fs.access(gitPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Runs `git fetch origin` inside the given repository.
+ *
+ * @param repoPath - Absolute path to the repo root.
+ */
+export async function gitFetch(repoPath: string): Promise<void> {
+  await execa('git', ['fetch', 'origin'], { cwd: repoPath });
+}
+
+/**
+ * Detects the default branch of a repository by inspecting remote branches.
+ * Prefers `main` over `master`. Falls back to `'main'` when neither is found.
+ *
+ * @param repoPath - Absolute path to the repo root.
+ * @returns The name of the default branch.
+ */
+export async function detectDefaultBranch(repoPath: string): Promise<string> {
+  try {
+    const { stdout } = await execa('git', ['branch', '-r'], { cwd: repoPath });
+    const branches = stdout.split('\n').map((b) => b.trim());
+
+    if (branches.some((b) => b === 'origin/main' || b.endsWith('/origin/main'))) {
+      return 'main';
+    }
+
+    if (branches.some((b) => b === 'origin/master' || b.endsWith('/origin/master'))) {
+      return 'master';
+    }
+
+    // Fallback — assume main.
+    return 'main';
+  } catch {
+    return 'main';
+  }
+}

package/src/utils/prompts.ts

@@ -0,0 +1,135 @@
+/**
+ * @module utils/prompts
+ * Interactive CLI prompts for NexusFlow using @inquirer/prompts.
+ */
+
+import { input, checkbox, confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+
+import type { AIAssistant, DetectedAI, DetectedEditor, RepoInfo } from '../types.js';
+
+/**
+ * Prompts the user for a feature branch name.
+ */
+export async function promptBranchName(): Promise<string> {
+  const branchName = await input({
+    message: 'Feature branch name:',
+    validate: (value: string) => {
+      if (!value.trim()) return 'Branch name cannot be empty';
+      if (/\s/.test(value)) return 'Branch name cannot contain spaces';
+      return true;
+    },
+  });
+  return branchName.trim();
+}
+
+/**
+ * Prompts the user for a feature description.
+ * Accepts plain text or a path to a file.
+ */
+export async function promptDescription(): Promise<string> {
+  const { readFile } = await import('node:fs/promises');
+  const { existsSync } = await import('node:fs');
+
+  const descInput = await input({
+    message: 'Describe the feature (or paste a path to a .md/.txt file):',
+    validate: (value: string) => {
+      if (!value.trim()) return 'Description cannot be empty';
+      return true;
+    },
+  });
+
+  const trimmed = descInput.trim();
+
+  // Check if it's a file path
+  if (existsSync(trimmed)) {
+    try {
+      const content = await readFile(trimmed, 'utf-8');
+      console.log(chalk.dim(`  Read description from ${trimmed}`));
+      return content;
+    } catch {
+      // Fall through to use as plain text
+    }
+  }
+
+  return trimmed;
+}
+
+/**
+ * Prompts the user to select repos from a list of discovered repos.
+ */
+export async function promptSelectRepos(repos: RepoInfo[]): Promise<RepoInfo[]> {
+  if (repos.length === 0) {
+    return [];
+  }
+
+  const selected = await checkbox({
+    message: 'Select projects to include:',
+    choices: repos.map((repo) => ({
+      name: `${repo.name} ${chalk.dim(`(${repo.path})`)}`,
+      value: repo.path,
+      checked: false,
+    })),
+    validate: (items) => {
+      if (items.length === 0) return 'Please select at least one project';
+      return true;
+    },
+  });
+
+  return repos.filter((r) => selected.includes(r.path));
+}
+
+/**
+ * Prompts the user to select AI assistants to generate context for.
+ */
+export async function promptSelectAI(
+  detected: DetectedAI[],
+): Promise<AIAssistant[]> {
+  const selected = await checkbox({
+    message: 'Select AI assistant(s) to generate context for:',
+    choices: detected.map((ai) => ({
+      name: `${ai.displayName} ${ai.detected ? chalk.green('✓ detected') : chalk.dim('not found')}`,
+      value: ai.name,
+      checked: ai.detected,
+    })),
+    validate: (items) => {
+      if (items.length === 0) return 'Please select at least one AI assistant';
+      return true;
+    },
+  });
+
+  return selected as AIAssistant[];
+}
+
+/**
+ * Prompts the user to select an editor to open the workspace in.
+ */
+export async function promptSelectEditor(
+  detected: DetectedEditor[],
+): Promise<DetectedEditor | null> {
+  const shouldOpen = await confirm({
+    message: 'Open workspace in an editor?',
+    default: true,
+  });
+
+  if (!shouldOpen) return null;
+
+  const available = detected.filter((e) => e.detected);
+
+  if (available.length === 0) {
+    console.log(chalk.yellow('  No editors detected in PATH.'));
+    return null;
+  }
+
+  const selected = await checkbox({
+    message: 'Select editor:',
+    choices: available.map((editor) => ({
+      name: editor.name,
+      value: editor.command,
+    })),
+  });
+
+  if (selected.length === 0) return null;
+
+  return available.find((e) => e.command === selected[0]) ?? null;
+}