@mrpatronz/nexusflow 0.2.19 → 1.3.0

package/src/core/graph.ts

@@ -1,344 +0,0 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { execa } from 'execa';
-import type { WorkspaceContext, RepoInfo } from '../types.js';
-
-export interface GraphNode {
-  id: string;
-  type: 'repo' | 'package' | 'endpoint' | 'port';
-  name: string;
-  metadata: Record<string, any>;
-}
-
-export interface GraphEdge {
-  source: string;
-  target: string;
-  type: 'CONTAINS' | 'DEPENDS_ON' | 'EXPOSES' | 'CALLS';
-  metadata?: Record<string, any>;
-}
-
-export interface WorkspaceGraph {
-  workspaceId: string;
-  nodes: GraphNode[];
-  edges: GraphEdge[];
-}
-
-/**
- * Builds a structural and API interaction graph across all repos in a workspace.
- */
-export async function buildWorkspaceGraph(
-  ctx: WorkspaceContext,
-  workspacePath: string,
-): Promise<WorkspaceGraph> {
-  const { feature, repos, analysis } = ctx;
-  const nodes: GraphNode[] = [];
-  const edges: GraphEdge[] = [];
-
-  // 1. Add Repository Nodes
-  for (const repo of repos) {
-    const a = analysis?.get(repo.path);
-    nodes.push({
-      id: `repo:${repo.name}`,
-      type: 'repo',
-      name: repo.name,
-      metadata: {
-        path: repo.path,
-        techStack: a?.techStack || null,
-        description: a?.readmeSummary || '',
-      },
-    });
-  }
-
-  // 2. Add API Endpoint and Port Nodes, and EXPOSES Edges
-  const allEndpoints: { endpointId: string; method: string; path: string; repoName: string }[] = [];
-  
-  if (analysis) {
-    for (const repo of repos) {
-      const a = analysis.get(repo.path);
-      if (!a) continue;
-
-      // Add Ports
-      for (const p of a.ports) {
-        const portId = `port:${repo.name}:${p.port}`;
-        nodes.push({
-          id: portId,
-          type: 'port',
-          name: `${p.port}`,
-          metadata: {
-            protocol: p.protocol,
-            source: p.source,
-          },
-        });
-        edges.push({
-          source: `repo:${repo.name}`,
-          target: portId,
-          type: 'EXPOSES',
-        });
-      }
-
-      // Add API Endpoints
-      for (const ep of a.endpoints) {
-        const endpointId = `endpoint:${repo.name}:${ep.method}:${ep.path}`;
-        nodes.push({
-          id: endpointId,
-          type: 'endpoint',
-          name: `${ep.method} ${ep.path}`,
-          metadata: {
-            method: ep.method,
-            path: ep.path,
-            source: ep.source,
-          },
-        });
-        edges.push({
-          source: `repo:${repo.name}`,
-          target: endpointId,
-          type: 'EXPOSES',
-        });
-
-        allEndpoints.push({
-          endpointId,
-          method: ep.method,
-          path: ep.path,
-          repoName: repo.name,
-        });
-      }
-
-      // Add package dependencies
-      for (const dep of a.dependencies) {
-        const packageId = `package:${dep.type}:${dep.name}`;
-        if (!nodes.some((n) => n.id === packageId)) {
-          nodes.push({
-            id: packageId,
-            type: 'package',
-            name: dep.name,
-            metadata: {
-              manager: dep.type,
-              version: dep.version || 'latest',
-            },
-          });
-        }
-        edges.push({
-          source: `repo:${repo.name}`,
-          target: packageId,
-          type: 'DEPENDS_ON',
-        });
-      }
-    }
-  }
-
-  // 3. Add inter-repo DEPENDS_ON edges
-  if (analysis) {
-    const repoNames = new Map(repos.map((r) => [r.path, r.name]));
-    const { findInterRepoDependencies } = await import('../analyzers/detect-deps.js');
-    const interDeps = findInterRepoDependencies(analysis, repoNames);
-
-    for (const [caller, callees] of interDeps) {
-      for (const callee of callees) {
-        edges.push({
-          source: `repo:${caller}`,
-          target: `repo:${callee}`,
-          type: 'DEPENDS_ON',
-          metadata: { relation: 'repo-to-repo' },
-        });
-      }
-    }
-  }
-
-  // 4. Detect CALLS Edges using git grep inside worktrees
-  for (const ep of allEndpoints) {
-    const pathQuery = ep.path;
-    // Skip very short or generic paths to avoid false positives and noise
-    if (!pathQuery || pathQuery.length < 4 || pathQuery === '/api' || pathQuery === '/dev') continue;
-
-    for (const repo of repos) {
-      if (repo.name === ep.repoName) continue; // Skip self
-
-      const worktreePath = path.join(workspacePath, repo.name);
-      try {
-        await fs.access(worktreePath);
-        // Use git grep to find references to this endpoint path in other worktrees
-        const { stdout } = await execa('git', ['grep', '-l', '-F', pathQuery], {
-          cwd: worktreePath,
-          reject: false,
-        });
-
-        if (stdout && stdout.trim()) {
-          const files = stdout.split('\n').filter(Boolean);
-          edges.push({
-            source: `repo:${repo.name}`,
-            target: ep.endpointId,
-            type: 'CALLS',
-            metadata: {
-              files,
-              reason: `References endpoint path '${pathQuery}'`,
-            },
-          });
-        }
-      } catch {
-        // Ignore git grep failures
-      }
-    }
-  }
-
-  return {
-    workspaceId: feature.id,
-    nodes,
-    edges,
-  };
-}
-
-/**
- * Builds a Mermaid Flowchart representation of the workspace architecture graph.
- */
-export function buildMermaidDiagram(graph: WorkspaceGraph): string {
-  const lines: string[] = ['flowchart TD'];
-
-  lines.push('  classDef repo fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#fff;');
-  lines.push('  classDef endpoint fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff;');
-  lines.push('  classDef port fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff;');
-  lines.push('  classDef package fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff;');
-
-  // Render Repo nodes
-  for (const n of graph.nodes) {
-    if (n.type === 'repo') {
-      lines.push(`  ${n.id}["📦 ${n.name}"]:::repo`);
-    }
-  }
-
-  // Render edges between repos
-  const repoEdges = graph.edges.filter(
-    (e) => e.source.startsWith('repo:') && e.target.startsWith('repo:'),
-  );
-  for (const e of repoEdges) {
-    lines.push(`  ${e.source} -->|depends on| ${e.target}`);
-  }
-
-  // Render API calls and endpoint interactions
-  const callsEdges = graph.edges.filter((e) => e.type === 'CALLS');
-  const referencedEndpointIds = new Set(callsEdges.map((e) => e.target));
-
-  for (const n of graph.nodes) {
-    if (n.type === 'endpoint' && referencedEndpointIds.has(n.id)) {
-      lines.push(`  ${n.id}["🔌 ${n.name}"]:::endpoint`);
-    }
-  }
-
-  for (const e of callsEdges) {
-    lines.push(`  ${e.source} -->|calls| ${e.target}`);
-  }
-
-  // Render exposures from endpoints to their parent repos
-  const exposesEdges = graph.edges.filter(
-    (e) => e.type === 'EXPOSES' && referencedEndpointIds.has(e.target),
-  );
-  for (const e of exposesEdges) {
-    lines.push(`  ${e.target} -.->|exposed by| ${e.source}`);
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Formats the graph as a human/LLM-readable markdown guide.
- */
-export function generateGraphMarkdownContent(graph: WorkspaceGraph): string {
-  const repoNodes = graph.nodes.filter((n) => n.type === 'repo');
-  const mermaid = buildMermaidDiagram(graph);
-
-  const lines: string[] = [
-    `# Workspace Architecture Graph — ${graph.workspaceId}`,
-    '',
-    '> **Token-Efficient Architecture Guide**: This file defines the entities, dependencies,',
-    '> and API call relationships of your multi-repository workspace. Use this map to navigate',
-    '> relationships without having to read through all repository directories.',
-    '',
-    '## Workspace Relations Diagram',
-    '',
-    '```mermaid',
-    mermaid,
-    '```',
-    '',
-    '## 📦 Repositories',
-    '',
-  ];
-
-  for (const repo of repoNodes) {
-    lines.push(`### ${repo.name}`);
-    lines.push(`- **Path**: \`${repo.metadata.path}\``);
-    if (repo.metadata.techStack) {
-      const ts = repo.metadata.techStack;
-      lines.push(`- **Languages**: ${ts.languages.join(', ')}`);
-      if (ts.frameworks.length > 0) {
-        lines.push(`- **Frameworks**: ${ts.frameworks.join(', ')}`);
-      }
-    }
-    
-    // Dependencies
-    const deps = graph.edges
-      .filter((e) => e.source === repo.id && e.target.startsWith('package:'))
-      .map((e) => {
-        const pkgNode = graph.nodes.find((n) => n.id === e.target);
-        return pkgNode ? `\`${pkgNode.name}\` (${pkgNode.metadata.manager})` : '';
-      })
-      .filter(Boolean);
-
-    if (deps.length > 0) {
-      lines.push(`- **Dependencies**: ${deps.slice(0, 10).join(', ')}${deps.length > 10 ? ` (+${deps.length - 10} more)` : ''}`);
-    }
-
-    // Exposed APIs
-    const exposed = graph.edges
-      .filter((e) => e.source === repo.id && e.target.startsWith('endpoint:'))
-      .map((e) => {
-        const ep = graph.nodes.find((n) => n.id === e.target);
-        return ep ? `\`${ep.name}\`` : '';
-      })
-      .filter(Boolean);
-
-    if (exposed.length > 0) {
-      lines.push(`- **Exposed APIs**: ${exposed.slice(0, 5).join(', ')}${exposed.length > 5 ? ` (+${exposed.length - 5} more)` : ''}`);
-    }
-
-    // API calls made
-    const calls = graph.edges
-      .filter((e) => e.source === repo.id && e.type === 'CALLS')
-      .map((e) => {
-        const ep = graph.nodes.find((n) => n.id === e.target);
-        return ep ? `\`${ep.name}\` (exposed by \`${ep.id.split(':')[1]}\`)` : '';
-      })
-      .filter(Boolean);
-
-    if (calls.length > 0) {
-      lines.push(`- **Calls Endpoints**: ${calls.join(', ')}`);
-    }
-    
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Builds the graph, writes `nexusflow-graph.json` and `nexusflow-graph.md` to workspace root.
- */
-export async function generateWorkspaceGraphFiles(
-  ctx: WorkspaceContext,
-  workspacePath: string,
-): Promise<void> {
-  try {
-    const graph = await buildWorkspaceGraph(ctx, workspacePath);
-    
-    // Write JSON file
-    const jsonPath = path.join(workspacePath, 'nexusflow-graph.json');
-    await fs.writeFile(jsonPath, JSON.stringify(graph, null, 2), 'utf-8');
-
-    // Write MD file
-    const mdPath = path.join(workspacePath, 'nexusflow-graph.md');
-    const mdContent = generateGraphMarkdownContent(graph);
-    await fs.writeFile(mdPath, mdContent, 'utf-8');
-
-    console.log('  ✔ Generated Workspace Architecture Graph (nexusflow-graph.json / nexusflow-graph.md)');
-  } catch (error: any) {
-    console.error('  ✖ Failed to generate workspace architecture graph:', error.message);
-  }
-}

package/src/core/plugins/index.ts

@@ -1,17 +0,0 @@
-import type { StoragePort } from '../ports/storage.js';
-
-export type { StoragePort, StorageAdapterMeta, AdapterConfigField } from '../ports/storage.js';
-
-export interface PluginRegistryContext {
-  /** Registers a custom storage provider/adapter. The provider must include a `meta` property. */
-  registerStorageProvider(name: string, provider: StoragePort): void;
-
-  /** Registers a custom commander CLI subcommand. */
-  registerCommand(commandBuilder: (program: any) => void): void;
-}
-
-export interface NexusFlowPlugin {
-  name: string;
-  version: string;
-  register(context: PluginRegistryContext): void | Promise<void>;
-}

package/src/core/plugins/loader.ts

@@ -1,36 +0,0 @@
-import * as path from 'node:path';
-import type { PluginRegistryContext, NexusFlowPlugin } from './index.js';
-import { registerStorageProvider } from '../adapters/registry.js';
-
-export async function loadPlugins(program: any, pluginsList: string[]): Promise<void> {
-  const context: PluginRegistryContext = {
-    registerStorageProvider(name, provider) {
-      registerStorageProvider(name, provider);
-    },
-    registerCommand(commandBuilder) {
-      commandBuilder(program);
-    }
-  };
-
-  for (const pluginPath of pluginsList) {
-    try {
-      let resolvedPath = pluginPath;
-      if (pluginPath.startsWith('.') || path.isAbsolute(pluginPath)) {
-        resolvedPath = path.resolve(pluginPath);
-      }
-      
-      // Dynamic import works with file:// URLs on Windows
-      const fileUrl = resolvedPath.startsWith('file://') ? resolvedPath : `file:///${resolvedPath.replace(/\\/g, '/')}`;
-      const module = await import(fileUrl);
-      const plugin: NexusFlowPlugin = module.default || module.plugin;
-      
-      if (plugin && typeof plugin.register === 'function') {
-        await plugin.register(context);
-      } else {
-        console.warn(`Warning: Plugin at "${pluginPath}" does not export a valid NexusFlowPlugin.`);
-      }
-    } catch (error: any) {
-      console.error(`Failed to load plugin "${pluginPath}":`, error.message);
-    }
-  }
-}

package/src/core/ports/storage.ts

@@ -1,71 +0,0 @@
-/**
- * @module core/ports/storage
- * Storage Port defining the interface for workspace document persistence.
- *
- * Adapters implement this interface to provide different storage backends.
- * Each adapter is self-describing via the `meta` property, which enables
- * automatic discovery in CLI, GUI, and plugin systems.
- */
-
-/** Describes a single configurable field for an adapter. */
-export interface AdapterConfigField {
-  /** Machine-readable key, stored in config.json. */
-  key: string;
-  /** Human-readable label for CLI prompts and GUI forms. */
-  label: string;
-  /** Value type — 'path' renders a file picker in the GUI. */
-  type: 'string' | 'boolean' | 'number' | 'path';
-  /** Whether the field must be set before the adapter can be used. */
-  required?: boolean;
-  /** Default value when not explicitly configured. */
-  default?: unknown;
-  /** Help text shown in CLI prompts and GUI tooltips. */
-  description?: string;
-}
-
-/** Metadata that makes an adapter self-describing and discoverable. */
-export interface StorageAdapterMeta {
-  /** Unique machine-readable identifier (e.g. 'obsidian'). */
-  name: string;
-  /** Human-readable name for CLI tables and GUI dropdowns (e.g. 'Obsidian Vault'). */
-  displayName: string;
-  /** One-line description of what this adapter does. */
-  description: string;
-  /** Configuration fields this adapter accepts. Empty array = no config needed. */
-  configFields: AdapterConfigField[];
-}
-
-export interface StoragePort {
-  /** Adapter metadata — who am I, what do I need? */
-  readonly meta: StorageAdapterMeta;
-
-  /** Called once after registration with the user's per-adapter settings. */
-  configure?(settings: Record<string, unknown>): void;
-
-  /** Writes a workspace context/metadata document. */
-  writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void>;
-
-  /** Reads a workspace context/metadata document. */
-  readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string>;
-
-  /** Checks if a workspace context/metadata document exists. */
-  workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean>;
-
-  /** Resolves the human-readable path or link to the workspace document for the AI assistant. */
-  resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string;
-
-  /** Writes a base-layer context document (stable maps/conventions across workspaces). */
-  writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void>;
-
-  /** Reads a base-layer context document. */
-  readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string>;
-
-  /** Checks if a base-layer context document exists. */
-  baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean>;
-
-  /** Resolves the human-readable path or link to the base document. */
-  resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string;
-
-  /** Cleanly deletes all workspace-specific documents from the storage backend. */
-  deleteWorkspace(workspacePath: string, featureId: string): Promise<void>;
-}

package/src/core/scanner.test.ts

@@ -1,61 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { scanForRepos } from './scanner.js';
-import * as gitUtils from '../utils/git.js';
-
-vi.mock('node:fs/promises');
-vi.mock('../utils/git.js');
-
-describe('scanner core module', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('should return repository info if the root dir is a git repo', async () => {
-    vi.mocked(gitUtils.isGitRepo).mockResolvedValue(true);
-    vi.mocked(gitUtils.detectDefaultBranch).mockResolvedValue('main');
-
-    const result = await scanForRepos('/mock/dev', 2);
-
-    expect(result).toEqual([
-      { name: 'dev', path: '/mock/dev', defaultBranch: 'main' }
-    ]);
-    expect(gitUtils.isGitRepo).toHaveBeenCalledWith('/mock/dev');
-  });
-
-  it('should recursively scan subdirectories up to limit and return repos found', async () => {
-    // Root is not a git repo
-    vi.mocked(gitUtils.isGitRepo).mockImplementation(async (dir) => {
-      const normalized = dir.replace(/\\/g, '/');
-      return normalized === '/mock/dev/repo1' || normalized === '/mock/dev/sub/repo2';
-    });
-    vi.mocked(gitUtils.detectDefaultBranch).mockResolvedValue('main');
-
-    // Root directory entries
-    vi.mocked(fs.readdir).mockImplementation(async (dir: any) => {
-      const normalized = dir.replace(/\\/g, '/');
-      if (normalized === '/mock/dev') {
-        return [
-          { name: 'repo1', isDirectory: () => true },
-          { name: 'sub', isDirectory: () => true },
-          { name: 'ignored_file.txt', isDirectory: () => false },
-          { name: 'node_modules', isDirectory: () => true },
-        ] as any[];
-      }
-      if (normalized === '/mock/dev/sub') {
-        return [
-          { name: 'repo2', isDirectory: () => true },
-        ] as any[];
-      }
-      return [];
-    });
-
-    const result = await scanForRepos('/mock/dev', 2);
-
-    expect(result).toEqual([
-      { name: 'repo1', path: path.join('/mock/dev', 'repo1'), defaultBranch: 'main' },
-      { name: 'repo2', path: path.join('/mock/dev', 'sub', 'repo2'), defaultBranch: 'main' }
-    ]);
-  });
-});

package/src/core/scanner.ts

@@ -1,91 +0,0 @@
-/**
- * @module core/scanner
- * Scans a development directory tree for git repositories.
- */
-
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-
-import type { RepoInfo } from '../types.js';
-import { detectDefaultBranch, isGitRepo } from '../utils/git.js';
-
-/** Directory names to skip while scanning. */
-const IGNORED_DIRS = new Set(['node_modules', 'workspaces', '.git']);
-
-/**
- * Recursively scans {@link devDir} for directories containing a `.git`
- * entry, up to the given {@link depth}.
- *
- * Skips `node_modules`, `workspaces`, and `.git` directories to keep
- * scans fast and relevant.
- *
- * @param devDir - Absolute path to the root directory to scan.
- * @param depth  - Maximum directory depth to descend (0 = only devDir itself).
- * @returns An array of discovered {@link RepoInfo} objects.
- */
-export async function scanForRepos(
-  devDir: string,
-  depth: number,
-): Promise<RepoInfo[]> {
-  const repos: RepoInfo[] = [];
-  await walk(devDir, depth, repos);
-  return repos;
-}
-
-/**
- * Internal recursive walker.
- *
- * When a directory is itself a git repo it is recorded and its children are
- * **not** descended into (a repo inside a repo is unusual and almost always
- * unintentional).
- */
-async function walk(
-  dir: string,
-  remainingDepth: number,
-  results: RepoInfo[],
-): Promise<void> {
-  // Check if the current directory is a git repo.
-  if (await isGitRepo(dir)) {
-    const defaultBranch = await detectDefaultBranch(dir);
-    results.push({
-      name: path.basename(dir),
-      path: dir,
-      defaultBranch,
-    });
-    // Don't recurse into a repo's subdirectories.
-    return;
-  }
-
-  if (remainingDepth <= 0) {
-    return;
-  }
-
-  // Read children and recurse.
-  let entries: import('node:fs').Dirent[];
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    // Permission denied or directory disappeared — skip silently.
-    return;
-  }
-
-  const tasks: Promise<void>[] = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-
-    if (IGNORED_DIRS.has(entry.name)) {
-      continue;
-    }
-
-    // Skip hidden directories (except we already handle .git above).
-    if (entry.name.startsWith('.')) {
-      continue;
-    }
-
-    tasks.push(walk(path.join(dir, entry.name), remainingDepth - 1, results));
-  }
-
-  await Promise.all(tasks);
-}

package/src/core/storage.ts

@@ -1,37 +0,0 @@
-import { getActiveStorageProvider } from './adapters/registry.js';
-
-export async function writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void> {
-  await getActiveStorageProvider().writeWorkspaceFile(workspacePath, featureId, filename, content);
-}
-
-export async function readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string> {
-  return await getActiveStorageProvider().readWorkspaceFile(workspacePath, featureId, filename);
-}
-
-export async function workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean> {
-  return await getActiveStorageProvider().workspaceFileExists(workspacePath, featureId, filename);
-}
-
-export function resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string {
-  return getActiveStorageProvider().resolveWorkspaceFileUrl(workspacePath, featureId, filename);
-}
-
-export async function writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void> {
-  await getActiveStorageProvider().writeBaseFile(workspacePath, repoName, filename, content);
-}
-
-export async function readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string> {
-  return await getActiveStorageProvider().readBaseFile(workspacePath, repoName, filename);
-}
-
-export async function baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean> {
-  return await getActiveStorageProvider().baseFileExists(workspacePath, repoName, filename);
-}
-
-export function resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string {
-  return getActiveStorageProvider().resolveBaseFileUrl(workspacePath, repoName, filename);
-}
-
-export async function deleteWorkspaceFiles(workspacePath: string, featureId: string): Promise<void> {
-  await getActiveStorageProvider().deleteWorkspace(workspacePath, featureId);
-}