@mrpatronz/nexusflow 0.2.17 → 0.2.18

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);
+}