@mrpatronz/nexusflow 0.2.17 → 0.2.19

package/src/commands/ui.ts

@@ -1,111 +1,111 @@
-/**
- * @module commands/ui
- * Starts the Hono web server and opens the browser to the NexusFlow GUI.
- */
-
-import chalk from 'chalk';
-import { exec, spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import * as path from 'node:path';
-import * as net from 'node:net';
-import { startServer } from '../server.js';
-
-function isPortActive(port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = net.connect(port, 'localhost');
-    socket.on('connect', () => {
-      socket.destroy();
-      resolve(true);
-    });
-    socket.on('error', () => {
-      resolve(false);
-    });
-  });
-}
-
-function openBrowser(url: string): void {
-  let openCmd = '';
-  if (process.platform === 'win32') {
-    openCmd = `start ${url}`;
-  } else if (process.platform === 'darwin') {
-    openCmd = `open ${url}`;
-  } else {
-    openCmd = `xdg-open ${url}`;
-  }
-
-  exec(openCmd, (err) => {
-    if (err) {
-      console.log(chalk.dim(`  Could not auto-open browser. Please visit ${url} manually.`));
-    }
-  });
-}
-
-/**
- * Starts the local GUI server and opens the dashboard in the default browser.
- *
- * @param options - CLI options, including optional port, daemon, and server-only.
- */
-export async function uiCommand(options: { port?: string; daemon?: boolean; serverOnly?: boolean }): Promise<void> {
-  const port = options.port ? parseInt(options.port, 10) : 3000;
-  const url = `http://localhost:${port}`;
-
-  console.log(chalk.bold.cyan('\n🖥️  NexusFlow — Web Dashboard\n'));
-
-  // Check if port is already active
-  const active = await isPortActive(port);
-  if (active) {
-    console.log(chalk.green(`  ✔ Dashboard is already active at: ${chalk.bold(url)}`));
-    if (!options.serverOnly) {
-      console.log(chalk.dim('  Opening browser...'));
-      openBrowser(url);
-    }
-    return;
-  }
-
-  // Handle Daemon mode (runs detached in the background)
-  if (options.daemon) {
-    console.log(chalk.dim('  Starting server in the background...'));
-    try {
-      const serverScript = fileURLToPath(new URL('../index.js', import.meta.url));
-      const child = spawn(process.execPath, [serverScript, 'ui', '--port', String(port), '--server-only'], {
-        detached: true,
-        stdio: 'ignore'
-      });
-      child.unref();
-
-      console.log(chalk.green(`  ✔ Dashboard daemon successfully spawned.`));
-      if (!options.serverOnly) {
-        console.log(chalk.dim('  Opening browser...'));
-        // Give the background process a brief moment to start listening
-        await new Promise((resolve) => setTimeout(resolve, 600));
-        openBrowser(url);
-      }
-      return;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(chalk.red(`  ✖ Failed to start background daemon: ${msg}`));
-      return;
-    }
-  }
-
-  // Standard foreground blocking mode
-  console.log(chalk.dim('  Starting local server...'));
-  try {
-    const { port: actualPort } = await startServer(port);
-    const actualUrl = `http://localhost:${actualPort}`;
-
-    console.log(chalk.green(`  ✔ Dashboard running at: ${chalk.bold(actualUrl)}`));
-    console.log(chalk.dim('  Press Ctrl+C to stop.\n'));
-
-    if (!options.serverOnly) {
-      openBrowser(actualUrl);
-    }
-
-    // Keep process alive
-    await new Promise(() => {});
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    console.error(chalk.red(`  ✖ Failed to start dashboard: ${msg}`));
-  }
-}
-
+/**
+ * @module commands/ui
+ * Starts the Hono web server and opens the browser to the NexusFlow GUI.
+ */
+
+import chalk from 'chalk';
+import { exec, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import * as net from 'node:net';
+import { startServer } from '../server.js';
+
+function isPortActive(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect(port, 'localhost');
+    socket.on('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on('error', () => {
+      resolve(false);
+    });
+  });
+}
+
+function openBrowser(url: string): void {
+  let openCmd = '';
+  if (process.platform === 'win32') {
+    openCmd = `start ${url}`;
+  } else if (process.platform === 'darwin') {
+    openCmd = `open ${url}`;
+  } else {
+    openCmd = `xdg-open ${url}`;
+  }
+
+  exec(openCmd, (err) => {
+    if (err) {
+      console.log(chalk.dim(`  Could not auto-open browser. Please visit ${url} manually.`));
+    }
+  });
+}
+
+/**
+ * Starts the local GUI server and opens the dashboard in the default browser.
+ *
+ * @param options - CLI options, including optional port, daemon, and server-only.
+ */
+export async function uiCommand(options: { port?: string; daemon?: boolean; serverOnly?: boolean }): Promise<void> {
+  const port = options.port ? parseInt(options.port, 10) : 3000;
+  const url = `http://localhost:${port}`;
+
+  console.log(chalk.bold.cyan('\n🖥️  NexusFlow — Web Dashboard\n'));
+
+  // Check if port is already active
+  const active = await isPortActive(port);
+  if (active) {
+    console.log(chalk.green(`  ✔ Dashboard is already active at: ${chalk.bold(url)}`));
+    if (!options.serverOnly) {
+      console.log(chalk.dim('  Opening browser...'));
+      openBrowser(url);
+    }
+    return;
+  }
+
+  // Handle Daemon mode (runs detached in the background)
+  if (options.daemon) {
+    console.log(chalk.dim('  Starting server in the background...'));
+    try {
+      const serverScript = fileURLToPath(new URL('../index.js', import.meta.url));
+      const child = spawn(process.execPath, [serverScript, 'ui', '--port', String(port), '--server-only'], {
+        detached: true,
+        stdio: 'ignore'
+      });
+      child.unref();
+
+      console.log(chalk.green(`  ✔ Dashboard daemon successfully spawned.`));
+      if (!options.serverOnly) {
+        console.log(chalk.dim('  Opening browser...'));
+        // Give the background process a brief moment to start listening
+        await new Promise((resolve) => setTimeout(resolve, 600));
+        openBrowser(url);
+      }
+      return;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(chalk.red(`  ✖ Failed to start background daemon: ${msg}`));
+      return;
+    }
+  }
+
+  // Standard foreground blocking mode
+  console.log(chalk.dim('  Starting local server...'));
+  try {
+    const { port: actualPort } = await startServer(port);
+    const actualUrl = `http://localhost:${actualPort}`;
+
+    console.log(chalk.green(`  ✔ Dashboard running at: ${chalk.bold(actualUrl)}`));
+    console.log(chalk.dim('  Press Ctrl+C to stop.\n'));
+
+    if (!options.serverOnly) {
+      openBrowser(actualUrl);
+    }
+
+    // Keep process alive
+    await new Promise(() => {});
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`  ✖ Failed to start dashboard: ${msg}`));
+  }
+}
+

package/src/core/adapters/local-storage.ts

@@ -0,0 +1,66 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { StoragePort, StorageAdapterMeta } from '../ports/storage.js';
+
+export class LocalStorageAdapter implements StoragePort {
+  readonly meta: StorageAdapterMeta = {
+    name: 'local',
+    displayName: 'Local Workspace',
+    description: 'Write context files directly into the workspace directory.',
+    configFields: [],
+  };
+
+  async writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void> {
+    const filePath = path.join(workspacePath, filename);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf8');
+  }
+
+  async readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string> {
+    const filePath = path.join(workspacePath, filename);
+    return await fs.readFile(filePath, 'utf8');
+  }
+
+  async workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean> {
+    const filePath = path.join(workspacePath, filename);
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string {
+    return path.join(workspacePath, filename).replace(/\\/g, '/');
+  }
+
+  async writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void> {
+    const filePath = path.join(workspacePath, filename);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf8');
+  }
+
+  async readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string> {
+    const filePath = path.join(workspacePath, filename);
+    return await fs.readFile(filePath, 'utf8');
+  }
+
+  async baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean> {
+    const filePath = path.join(workspacePath, filename);
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string {
+    return path.join(workspacePath, filename).replace(/\\/g, '/');
+  }
+
+  async deleteWorkspace(workspacePath: string, featureId: string): Promise<void> {
+    // NOP - local files are inside workspacePath, which is deleted directly on workspace removal.
+  }
+}

package/src/core/adapters/obsidian-storage.ts

@@ -0,0 +1,151 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { StoragePort, StorageAdapterMeta } from '../ports/storage.js';
+
+/**
+ * Obsidian-native storage adapter.
+ *
+ * Writes markdown files to a configurable Obsidian vault path with optional
+ * YAML frontmatter (tags, dates, type). Uses the same two-layer structure
+ * as CentralVaultAdapter (_base/<repo>/ + <workspace>/).
+ */
+export class ObsidianStorageAdapter implements StoragePort {
+  readonly meta: StorageAdapterMeta = {
+    name: 'obsidian',
+    displayName: 'Obsidian Vault',
+    description: 'Store context in an Obsidian vault with YAML frontmatter and wikilinks.',
+    configFields: [
+      {
+        key: 'vaultPath',
+        label: 'Obsidian Vault Path',
+        type: 'path',
+        required: true,
+        description: 'Absolute path to your Obsidian vault folder (e.g. ~/Obsidian/Dev)',
+      },
+      {
+        key: 'addFrontmatter',
+        label: 'Add YAML Frontmatter',
+        type: 'boolean',
+        default: true,
+        description: 'Add tags, created date, and type metadata to each file',
+      },
+    ],
+  };
+
+  private vaultPath: string = '';
+  private addFrontmatter: boolean = true;
+
+  constructor() {
+    try {
+      const home = os.homedir();
+      if (home) {
+        this.vaultPath = path.join(home, 'Obsidian', 'NexusFlow');
+      }
+    } catch {}
+  }
+
+  configure(settings: Record<string, unknown>): void {
+    if (settings.vaultPath && typeof settings.vaultPath === 'string') {
+      this.vaultPath = settings.vaultPath.startsWith('~')
+        ? path.join(os.homedir(), settings.vaultPath.slice(1))
+        : settings.vaultPath;
+    }
+    if (typeof settings.addFrontmatter === 'boolean') {
+      this.addFrontmatter = settings.addFrontmatter;
+    }
+  }
+
+  // ── Frontmatter helpers ──────────────────────────────────
+
+  private wrapWithFrontmatter(content: string, tags: string[], type: string): string {
+    if (!this.addFrontmatter) return content;
+
+    const now = new Date().toISOString();
+    const fm = [
+      '---',
+      `tags: [${tags.map(t => `"${t}"`).join(', ')}]`,
+      `type: ${type}`,
+      `created: ${now}`,
+      `modified: ${now}`,
+      `generator: nexusflow`,
+      '---',
+      '',
+    ].join('\n');
+
+    // Strip existing frontmatter if present
+    const stripped = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+    return fm + stripped;
+  }
+
+  // ── Workspace (feature) layer ────────────────────────────
+
+  private getFeaturePath(featureId: string): string {
+    return path.join(this.vaultPath, 'nexusflow', 'workspaces', featureId);
+  }
+
+  async writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void> {
+    const dir = this.getFeaturePath(featureId);
+    const filePath = path.join(dir, filename);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const wrapped = this.wrapWithFrontmatter(content, [featureId, 'workspace'], 'workspace-context');
+    await fs.writeFile(filePath, wrapped, 'utf8');
+  }
+
+  async readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string> {
+    const dir = this.getFeaturePath(featureId);
+    return await fs.readFile(path.join(dir, filename), 'utf8');
+  }
+
+  async workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean> {
+    try {
+      await fs.access(path.join(this.getFeaturePath(featureId), filename));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string {
+    return path.join(this.getFeaturePath(featureId), filename).replace(/\\/g, '/');
+  }
+
+  // ── Base (repo) layer ────────────────────────────────────
+
+  private getBasePath(repoName: string): string {
+    return path.join(this.vaultPath, 'nexusflow', '_base', repoName);
+  }
+
+  async writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void> {
+    const dir = this.getBasePath(repoName);
+    const filePath = path.join(dir, filename);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const wrapped = this.wrapWithFrontmatter(content, [repoName, 'base'], 'base-knowledge');
+    await fs.writeFile(filePath, wrapped, 'utf8');
+  }
+
+  async readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string> {
+    const dir = this.getBasePath(repoName);
+    return await fs.readFile(path.join(dir, filename), 'utf8');
+  }
+
+  async baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean> {
+    try {
+      await fs.access(path.join(this.getBasePath(repoName), filename));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string {
+    return path.join(this.getBasePath(repoName), filename).replace(/\\/g, '/');
+  }
+
+  async deleteWorkspace(workspacePath: string, featureId: string): Promise<void> {
+    const dir = this.getFeaturePath(featureId);
+    try {
+      await fs.rm(dir, { recursive: true, force: true });
+    } catch {}
+  }
+}

package/src/core/adapters/registry.ts

@@ -0,0 +1,44 @@
+import type { StoragePort, StorageAdapterMeta } from '../ports/storage.js';
+import { LocalStorageAdapter } from './local-storage.js';
+import { CentralVaultAdapter } from './vault-storage.js';
+import { ObsidianStorageAdapter } from './obsidian-storage.js';
+
+const storageProviders = new Map<string, StoragePort>();
+let activeProvider: StoragePort | null = null;
+
+export function registerStorageProvider(name: string, provider: StoragePort) {
+  storageProviders.set(name, provider);
+}
+
+// Auto-register built-in adapters
+registerStorageProvider('local', new LocalStorageAdapter());
+registerStorageProvider('central-vault', new CentralVaultAdapter());
+registerStorageProvider('obsidian', new ObsidianStorageAdapter());
+
+/** Returns metadata for all registered storage providers. */
+export function listStorageProviders(): StorageAdapterMeta[] {
+  return Array.from(storageProviders.values()).map(p => p.meta);
+}
+
+export function getStorageProvider(name: string): StoragePort {
+  const provider = storageProviders.get(name);
+  if (!provider) {
+    throw new Error(`Storage provider "${name}" is not registered.`);
+  }
+  return provider;
+}
+
+export function setActiveStorageProvider(provider: StoragePort) {
+  activeProvider = provider;
+}
+
+export function getActiveStorageProvider(): StoragePort {
+  if (!activeProvider) {
+    const local = storageProviders.get('local');
+    if (!local) {
+      throw new Error('No storage providers registered.');
+    }
+    return local;
+  }
+  return activeProvider;
+}

package/src/core/adapters/storage.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { LocalStorageAdapter } from './local-storage.js';
+import { CentralVaultAdapter } from './vault-storage.js';
+import { ObsidianStorageAdapter } from './obsidian-storage.js';
+
+vi.mock('node:fs/promises');
+vi.mock('node:os', async () => {
+  const actual = await vi.importActual<typeof import('node:os')>('node:os');
+  return {
+    ...actual,
+    homedir: vi.fn().mockReturnValue('/mock/home'),
+  };
+});
+
+describe('Storage Adapters', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(os.homedir).mockReturnValue('/mock/home');
+  });
+
+  describe('LocalStorageAdapter', () => {
+    const adapter = new LocalStorageAdapter();
+
+    it('should declare correct meta', () => {
+      expect(adapter.meta.name).toBe('local');
+      expect(adapter.meta.configFields.length).toBe(0);
+    });
+
+    it('should write workspace files directly to the workspace path', async () => {
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeWorkspaceFile('/ws/path', 'feature-1', 'test.txt', 'hello');
+
+      expect(fs.mkdir).toHaveBeenCalledWith(expect.stringContaining(path.normalize('/ws/path')), { recursive: true });
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        path.normalize('/ws/path/test.txt'),
+        'hello',
+        'utf8'
+      );
+    });
+
+    it('should resolve local workspace paths', () => {
+      const resolved = adapter.resolveWorkspaceFileUrl('/ws/path', 'feature-1', 'test.txt');
+      expect(resolved).toContain('/ws/path/test.txt');
+    });
+
+    it('should delete workspace as NOP', async () => {
+      await adapter.deleteWorkspace('/ws/path', 'feature-1');
+      expect(fs.rm).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('CentralVaultAdapter', () => {
+    const adapter = new CentralVaultAdapter();
+
+    it('should declare correct meta', () => {
+      expect(adapter.meta.name).toBe('central-vault');
+    });
+
+    it('should write workspace files to ~/.nexusflow/vault/<featureId>', async () => {
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeWorkspaceFile('/ws/path', 'feature-1', 'test.txt', 'hello');
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining(path.normalize('.nexusflow/vault/feature-1/test.txt')),
+        'hello',
+        'utf8'
+      );
+    });
+
+    it('should write base files to ~/.nexusflow/vault/_base/<repoName>', async () => {
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeBaseFile('/ws/path', 'RepoName', 'map.md', 'content');
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining(path.normalize('.nexusflow/vault/_base/RepoName/map.md')),
+        'content',
+        'utf8'
+      );
+    });
+
+    it('should delete workspace folder from ~/.nexusflow/vault', async () => {
+      vi.mocked(fs.rm).mockResolvedValue(undefined);
+      await adapter.deleteWorkspace('/ws/path', 'feature-1');
+      expect(fs.rm).toHaveBeenCalledWith(
+        expect.stringContaining(path.normalize('.nexusflow/vault/feature-1')),
+        { recursive: true, force: true }
+      );
+    });
+  });
+
+  describe('ObsidianStorageAdapter', () => {
+    it('should declare correct meta and configuration settings', () => {
+      const adapter = new ObsidianStorageAdapter();
+      expect(adapter.meta.name).toBe('obsidian');
+      expect(adapter.meta.configFields.some(f => f.key === 'vaultPath')).toBe(true);
+    });
+
+    it('should respect custom vaultPath configuration', async () => {
+      const adapter = new ObsidianStorageAdapter();
+      adapter.configure({ vaultPath: '/custom/obsidian/vault' });
+
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeWorkspaceFile('/ws/path', 'feature-1', 'test.txt', 'hello');
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        path.normalize('/custom/obsidian/vault/nexusflow/workspaces/feature-1/test.txt'),
+        expect.any(String),
+        'utf8'
+      );
+    });
+
+    it('should wrap content with YAML frontmatter by default', async () => {
+      const adapter = new ObsidianStorageAdapter();
+      adapter.configure({ vaultPath: '/custom/obsidian/vault', addFrontmatter: true });
+
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeWorkspaceFile('/ws/path', 'feature-1', 'test.txt', 'hello');
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('tags: ["feature-1", "workspace"]'),
+        'utf8'
+      );
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('generator: nexusflow'),
+        'utf8'
+      );
+    });
+
+    it('should not wrap content with frontmatter if addFrontmatter is disabled', async () => {
+      const adapter = new ObsidianStorageAdapter();
+      adapter.configure({ vaultPath: '/custom/obsidian/vault', addFrontmatter: false });
+
+      vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+      vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+
+      await adapter.writeWorkspaceFile('/ws/path', 'feature-1', 'test.txt', 'hello');
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        expect.any(String),
+        'hello',
+        'utf8'
+      );
+    });
+
+    it('should delete workspace folder from custom vault path under nexusflow', async () => {
+      const adapter = new ObsidianStorageAdapter();
+      adapter.configure({ vaultPath: '/custom/obsidian/vault' });
+      vi.mocked(fs.rm).mockResolvedValue(undefined);
+
+      await adapter.deleteWorkspace('/ws/path', 'feature-1');
+
+      expect(fs.rm).toHaveBeenCalledWith(
+        path.normalize('/custom/obsidian/vault/nexusflow/workspaces/feature-1'),
+        { recursive: true, force: true }
+      );
+    });
+  });
+});