@mrpatronz/nexusflow 0.2.17 → 0.2.19

package/src/core/plugins/index.ts

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,71 @@
+/**
+ * @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 +1,61 @@
-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' }
-    ]);
-  });
-});
+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 +1,91 @@
-/**
- * @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);
-}
+/**
+ * @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

@@ -0,0 +1,37 @@
+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);
+}

package/src/core/sync.ts

@@ -0,0 +1,121 @@
+/**
+ * @module core/sync
+ * Headless workspace sync — rebases every repo in a workspace onto its base
+ * branch, records the per-repo outcome to workspace state, and regenerates
+ * context files. Produces no console output, so it can back the CLI, the HTTP
+ * API, and the MCP tool alike.
+ */
+
+import * as path from 'node:path';
+
+import { loadFeatureConfig } from './workspace.js';
+import { recordRepoSync } from './workspace-state.js';
+import { getWorkspaceRepos, rebaseRepo } from '../utils/multi-git.js';
+import { analyzeAllRepos } from '../analyzers/index.js';
+import { generateContextFiles } from '../generators/index.js';
+import type { SyncStatus, WorkspaceContext } from '../types.js';
+
+/** Sync outcome for a single repo. */
+export interface RepoSyncReport {
+  /** Directory name of the repo. */
+  name: string;
+  /** Classified outcome. */
+  status: SyncStatus;
+  /** Human-readable message. */
+  message: string;
+  /** Conflict stderr — populated only for `status === 'conflict'`. */
+  conflict?: string;
+}
+
+/** Aggregated result of syncing an entire workspace. */
+export interface SyncReport {
+  /** Absolute path to the workspace. */
+  workspacePath: string;
+  /** Feature branch name being synced. */
+  branchName: string;
+  /** Per-repo outcomes, in workspace order. */
+  repos: RepoSyncReport[];
+  /** Count of repos that landed cleanly (up-to-date, rebased, or stash-conflict). */
+  syncedCount: number;
+  /** Count of repos with a genuine merge conflict. */
+  conflictCount: number;
+  /** Count of repos that failed for infrastructure reasons (fetch/auth, etc.). */
+  errorCount: number;
+}
+
+/** A sync status counts as "synced" when the rebase itself landed. */
+function isSynced(status: SyncStatus): boolean {
+  return status === 'up-to-date' || status === 'rebased' || status === 'stash-conflict';
+}
+
+/**
+ * Syncs all repos in a workspace. Throws if the workspace configuration cannot
+ * be loaded; individual repo failures are captured in the returned report
+ * rather than thrown.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ * @returns A structured report of every repo's outcome.
+ */
+export async function syncWorkspace(workspacePath: string): Promise<SyncReport> {
+  const feature = await loadFeatureConfig(workspacePath);
+  if (!feature) {
+    throw new Error(
+      `Failed to load workspace configuration. Ensure nexusflow.json exists at ${workspacePath}.`,
+    );
+  }
+
+  const repos = await getWorkspaceRepos(workspacePath);
+
+  const repoReports: RepoSyncReport[] = [];
+  let syncedCount = 0;
+  let conflictCount = 0;
+  let errorCount = 0;
+
+  for (const repo of repos) {
+    const defaultBranch = repo.defaultBranch || 'main';
+    const result = await rebaseRepo(repo.path, defaultBranch);
+
+    await recordRepoSync(workspacePath, repo.name, {
+      status: result.status,
+      message: result.message,
+    });
+
+    repoReports.push({
+      name: repo.name,
+      status: result.status,
+      message: result.message,
+      conflict: result.conflict,
+    });
+
+    if (isSynced(result.status)) syncedCount++;
+    else if (result.status === 'conflict') conflictCount++;
+    else errorCount++;
+  }
+
+  // Regenerate maps/context when anything synced. A regen failure must never
+  // fail the sync itself — the rebases already happened.
+  if (syncedCount > 0) {
+    try {
+      const allRepos = feature.repos.map((r) => ({
+        name: path.basename(r),
+        path: r,
+        defaultBranch: 'main',
+      }));
+
+      const analysis = await analyzeAllRepos(allRepos);
+      const ctx: WorkspaceContext = { feature, repos: allRepos, analysis };
+      await generateContextFiles(ctx, feature.assistants, workspacePath);
+    } catch {
+      // Best-effort regeneration; ignore failures.
+    }
+  }
+
+  return {
+    workspacePath,
+    branchName: feature.branchName,
+    repos: repoReports,
+    syncedCount,
+    conflictCount,
+    errorCount,
+  };
+}