@mrpatronz/nexusflow 0.2.17 → 0.2.18

package/src/commands/adapter.ts

@@ -0,0 +1,348 @@
+/**
+ * @module commands/adapter
+ * CLI commands for managing storage adapters.
+ *
+ * Usage:
+ *   nexusflow adapter list               # List all available adapters
+ *   nexusflow adapter use <name>          # Switch active adapter (prompts for config)
+ *   nexusflow adapter info <name>         # Show adapter details and current settings
+ *   nexusflow adapter init <name>         # Scaffold a new adapter plugin project
+ */
+
+import chalk from 'chalk';
+import { input, confirm } from '@inquirer/prompts';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { listStorageProviders, getStorageProvider } from '../core/adapters/registry.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import type { StorageAdapterMeta, AdapterConfigField } from '../core/ports/storage.js';
+
+/**
+ * Lists all registered storage adapters in a formatted table.
+ */
+export async function adapterListCommand(): Promise<void> {
+  const config = await loadConfig();
+  const activeName = config.storageProvider || 'local';
+  const adapters = listStorageProviders();
+
+  console.log(chalk.bold.cyan('\n📦 Available Storage Adapters\n'));
+
+  // Table header
+  const nameW = 18;
+  const dispW = 22;
+  const actW = 8;
+  console.log(
+    chalk.dim('  ') +
+    chalk.bold('Name'.padEnd(nameW)) +
+    chalk.bold('Display Name'.padEnd(dispW)) +
+    chalk.bold('Active'.padEnd(actW)) +
+    chalk.bold('Description')
+  );
+  console.log(chalk.dim('  ' + '─'.repeat(nameW + dispW + actW + 40)));
+
+  for (const adapter of adapters) {
+    const isActive = adapter.name === activeName;
+    const activeMarker = isActive ? chalk.green('  ✔') : '   ';
+    const configCount = adapter.configFields.length;
+    const configHint = configCount > 0 ? chalk.dim(` (${configCount} settings)`) : '';
+
+    console.log(
+      '  ' +
+      chalk.white(adapter.name.padEnd(nameW)) +
+      chalk.cyan(adapter.displayName.padEnd(dispW)) +
+      activeMarker.padEnd(actW) +
+      chalk.gray(adapter.description) +
+      configHint
+    );
+  }
+  console.log();
+}
+
+/**
+ * Shows detailed information about a specific adapter.
+ */
+export async function adapterInfoCommand(adapterName: string): Promise<void> {
+  const config = await loadConfig();
+  const activeName = config.storageProvider || 'local';
+
+  let meta: StorageAdapterMeta;
+  try {
+    meta = getStorageProvider(adapterName).meta;
+  } catch {
+    console.error(chalk.red(`\n✖ Adapter "${adapterName}" is not registered.\n`));
+    const adapters = listStorageProviders();
+    console.log(chalk.dim(`  Available: ${adapters.map(a => a.name).join(', ')}`));
+    return;
+  }
+
+  console.log(chalk.bold.cyan(`\n📦 Adapter: ${meta.displayName}\n`));
+  console.log(`  ${chalk.bold('Name:')}        ${meta.name}`);
+  console.log(`  ${chalk.bold('Active:')}      ${meta.name === activeName ? chalk.green('Yes') : 'No'}`);
+  console.log(`  ${chalk.bold('Description:')} ${meta.description}`);
+
+  if (meta.configFields.length > 0) {
+    console.log(`\n  ${chalk.bold('Configuration Fields:')}`);
+    const currentSettings = config.adapterConfig?.[meta.name] ?? {};
+
+    for (const field of meta.configFields) {
+      const currentValue = currentSettings[field.key];
+      const defaultStr = field.default !== undefined ? chalk.dim(` (default: ${String(field.default)})`) : '';
+      const requiredStr = field.required ? chalk.yellow(' *required') : '';
+      const valueStr = currentValue !== undefined ? chalk.green(String(currentValue)) : chalk.dim('not set');
+
+      console.log(`    ${chalk.white(field.label)} [${field.key}]${requiredStr}${defaultStr}`);
+      console.log(`      ${chalk.dim(field.description || '')}`);
+      console.log(`      Current: ${valueStr}`);
+    }
+  } else {
+    console.log(chalk.dim('\n  No configuration needed.'));
+  }
+  console.log();
+}
+
+/**
+ * Switches the active adapter and prompts for any required configuration.
+ */
+export async function adapterUseCommand(adapterName: string): Promise<void> {
+  let provider;
+  try {
+    provider = getStorageProvider(adapterName);
+  } catch {
+    console.error(chalk.red(`\n✖ Adapter "${adapterName}" is not registered.\n`));
+    const adapters = listStorageProviders();
+    console.log(chalk.dim(`  Available: ${adapters.map(a => a.name).join(', ')}`));
+    return;
+  }
+
+  const config = await loadConfig();
+  const meta = provider.meta;
+  const existingSettings = config.adapterConfig?.[meta.name] ?? {};
+  const newSettings: Record<string, unknown> = { ...existingSettings };
+
+  // Prompt for each config field
+  if (meta.configFields.length > 0) {
+    console.log(chalk.bold.cyan(`\n⚙️  Configure ${meta.displayName}\n`));
+
+    for (const field of meta.configFields) {
+      const currentValue = existingSettings[field.key];
+      const defaultValue = currentValue !== undefined ? String(currentValue) : (field.default !== undefined ? String(field.default) : undefined);
+
+      if (field.type === 'boolean') {
+        const result = await confirm({
+          message: field.label + (field.description ? chalk.dim(` — ${field.description}`) : ''),
+          default: defaultValue === 'true' || field.default === true,
+        });
+        newSettings[field.key] = result;
+      } else {
+        const result = await input({
+          message: field.label + (field.description ? chalk.dim(` — ${field.description}`) : ''),
+          default: defaultValue,
+          validate: (val) => {
+            if (field.required && !val.trim()) return `${field.label} is required`;
+            return true;
+          },
+        });
+
+        if (field.type === 'number') {
+          newSettings[field.key] = Number(result);
+        } else {
+          newSettings[field.key] = result;
+        }
+      }
+    }
+  }
+
+  // Save config
+  if (!config.adapterConfig) {
+    config.adapterConfig = {};
+  }
+  config.adapterConfig[meta.name] = newSettings;
+  config.storageProvider = meta.name;
+  await saveConfig(config);
+
+  // Apply configuration
+  if (provider.configure) {
+    provider.configure(newSettings);
+  }
+
+  console.log(chalk.green(`\n✔ Activated '${meta.displayName}' adapter.\n`));
+}
+
+/**
+ * Scaffolds a new adapter plugin project.
+ */
+export async function adapterInitCommand(adapterName: string): Promise<void> {
+  const targetDir = path.resolve(adapterName);
+
+  try {
+    await fs.access(targetDir);
+    console.error(chalk.red(`\n✖ Directory "${adapterName}" already exists.\n`));
+    return;
+  } catch {}
+
+  console.log(chalk.bold.cyan(`\n🔧 Scaffolding adapter: ${adapterName}\n`));
+
+  await fs.mkdir(path.join(targetDir, 'src'), { recursive: true });
+
+  // package.json
+  const pkg = {
+    name: `nexusflow-${adapterName}`,
+    version: '1.0.0',
+    type: 'module',
+    main: 'dist/index.js',
+    scripts: {
+      build: 'tsc',
+      dev: 'tsc --watch',
+    },
+    peerDependencies: {
+      '@mrpatronz/nexusflow': '>=0.2.0',
+    },
+    devDependencies: {
+      typescript: '^5.0.0',
+    },
+  };
+  await fs.writeFile(path.join(targetDir, 'package.json'), JSON.stringify(pkg, null, 2), 'utf8');
+
+  // tsconfig.json
+  const tsconfig = {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'Node16',
+      moduleResolution: 'Node16',
+      outDir: 'dist',
+      rootDir: 'src',
+      strict: true,
+      esModuleInterop: true,
+      declaration: true,
+    },
+    include: ['src/**/*'],
+  };
+  await fs.writeFile(path.join(targetDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2), 'utf8');
+
+  // src/index.ts — starter adapter
+  const indexContent = `/**
+ * NexusFlow Storage Adapter: ${adapterName}
+ *
+ * Implement the StoragePort interface to create a custom storage backend.
+ * See: https://github.com/antan87/NexusFlow#adapters
+ */
+
+import type { StoragePort, StorageAdapterMeta, NexusFlowPlugin } from '@mrpatronz/nexusflow';
+// If the above import fails, use relative path to nexusflow's type definitions.
+
+class ${toPascalCase(adapterName)}Adapter implements StoragePort {
+  readonly meta: StorageAdapterMeta = {
+    name: '${adapterName}',
+    displayName: '${toTitleCase(adapterName)}',
+    description: 'A custom NexusFlow storage adapter.',
+    configFields: [
+      // Add your configuration fields here, e.g.:
+      // { key: 'endpoint', label: 'API Endpoint', type: 'string', required: true, description: 'URL of the storage API' },
+    ],
+  };
+
+  configure(settings: Record<string, unknown>): void {
+    // Read your adapter-specific settings here
+  }
+
+  // ── Workspace (feature) layer ────────────────────────────
+
+  async writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void> {
+    throw new Error('Not implemented yet');
+  }
+
+  async readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string> {
+    throw new Error('Not implemented yet');
+  }
+
+  async workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean> {
+    return false;
+  }
+
+  resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string {
+    return '';
+  }
+
+  // ── Base (repo) layer ────────────────────────────────────
+
+  async writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void> {
+    throw new Error('Not implemented yet');
+  }
+
+  async readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string> {
+    throw new Error('Not implemented yet');
+  }
+
+  async baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean> {
+    return false;
+  }
+
+  resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string {
+    return '';
+  }
+}
+
+const plugin: NexusFlowPlugin = {
+  name: 'nexusflow-${adapterName}',
+  version: '1.0.0',
+  register(context) {
+    context.registerStorageProvider('${adapterName}', new ${toPascalCase(adapterName)}Adapter());
+  },
+};
+
+export default plugin;
+`;
+  await fs.writeFile(path.join(targetDir, 'src', 'index.ts'), indexContent, 'utf8');
+
+  // README.md
+  const readme = `# nexusflow-${adapterName}
+
+A custom storage adapter for [NexusFlow](https://github.com/antan87/NexusFlow).
+
+## Development
+
+\`\`\`bash
+npm install
+npm run build
+\`\`\`
+
+## Usage
+
+Add to your NexusFlow config (\`~/.nexusflow/config.json\`):
+
+\`\`\`json
+{
+  "plugins": ["./path/to/nexusflow-${adapterName}/dist/index.js"],
+  "storageProvider": "${adapterName}"
+}
+\`\`\`
+
+Or activate via CLI:
+
+\`\`\`bash
+nexusflow adapter use ${adapterName}
+\`\`\`
+`;
+  await fs.writeFile(path.join(targetDir, 'README.md'), readme, 'utf8');
+
+  console.log(chalk.green('  ✔ Created package.json'));
+  console.log(chalk.green('  ✔ Created tsconfig.json'));
+  console.log(chalk.green('  ✔ Created src/index.ts (starter adapter)'));
+  console.log(chalk.green('  ✔ Created README.md'));
+  console.log(chalk.bold.green(`\n✅ Adapter scaffolded at ${targetDir}\n`));
+  console.log(chalk.dim('  Next steps:'));
+  console.log(chalk.dim(`    cd ${adapterName}`));
+  console.log(chalk.dim('    npm install'));
+  console.log(chalk.dim('    # Implement the StoragePort methods in src/index.ts'));
+  console.log(chalk.dim('    npm run build'));
+  console.log();
+}
+
+function toPascalCase(str: string): string {
+  return str.split(/[-_]/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+
+function toTitleCase(str: string): string {
+  return str.split(/[-_]/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+}

package/src/commands/add-repo.ts

@@ -1,157 +1,156 @@
-/**
- * @module commands/add-repo
- * Adds a repository to an existing NexusFlow workspace.
- */
-
-import chalk from 'chalk';
-import ora from 'ora';
-import { select, search } from '@inquirer/prompts';
-import * as path from 'node:path';
-
-import { loadConfig } from '../core/config.js';
-import { scanForRepos } from '../core/scanner.js';
-import { listWorkspaces, loadFeatureConfig, addRepoToWorkspace } from '../core/workspace.js';
-
-/**
- * Executes the add-repo command.
- *
- * @param repoPathArg - Optional repository path to add.
- * @param workspaceArg - Optional workspace path or name.
- */
-export async function addRepoCommand(
-  repoPathArg?: string,
-  workspaceArg?: string,
-): Promise<void> {
-  console.log(chalk.bold.cyan('\n➕ NexusFlow — Adding Repository to Workspace\n'));
-
-  const config = await loadConfig();
-
-  // 1. Resolve workspace
-  let workspacePath: string | null = null;
-  let workspaceName = '';
-
-  if (workspaceArg) {
-    const resolvedPath = path.isAbsolute(workspaceArg)
-      ? workspaceArg
-      : path.resolve(config.workspacesDir, workspaceArg);
-
-    try {
-      const manifest = await loadFeatureConfig(resolvedPath);
-      if (manifest) {
-        workspacePath = resolvedPath;
-        workspaceName = manifest.branchName;
-      }
-    } catch {}
-
-    if (!workspacePath) {
-      const directPath = path.join(config.workspacesDir, workspaceArg);
-      const manifest = await loadFeatureConfig(directPath);
-      if (manifest) {
-        workspacePath = directPath;
-        workspaceName = manifest.branchName;
-      } else {
-        console.error(chalk.red(`✖ Invalid workspace: No nexusflow.json found at ${workspaceArg}`));
-        return;
-      }
-    }
-  } else {
-    const cwdFeature = await loadFeatureConfig(process.cwd());
-    if (cwdFeature) {
-      workspacePath = cwdFeature.workspacePath;
-      workspaceName = cwdFeature.branchName;
-    } else {
-      const workspaces = await listWorkspaces(config.workspacesDir);
-      if (workspaces.length === 0) {
-        console.log(chalk.yellow('No workspaces found.\n'));
-        return;
-      }
-
-      const selected = await search({
-        message: 'Search and select a workspace to add a repository to:',
-        source: async (input) => {
-          const query = (input || '').toLowerCase();
-          const filtered = workspaces.filter(
-            (ws) =>
-              ws.branchName.toLowerCase().includes(query) ||
-              ws.workspacePath.toLowerCase().includes(query)
-          );
-          return filtered.map((ws) => ({
-            name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
-            value: ws,
-          }));
-        },
-      });
-
-      workspacePath = selected.workspacePath;
-      workspaceName = selected.branchName;
-    }
-  }
-
-  if (!workspacePath) return;
-
-  const feature = await loadFeatureConfig(workspacePath);
-  if (!feature) {
-    console.error(chalk.red('✖ Failed to load workspace configuration.'));
-    return;
-  }
-
-  // 2. Resolve repository to add
-  let repoPathToAdd = '';
-
-  if (repoPathArg) {
-    repoPathToAdd = path.resolve(repoPathArg);
-  } else {
-    const scanSpinner = ora('Scanning for projects...').start();
-    let repos = [];
-    try {
-      repos = await scanForRepos(config.devDir, config.scanDepth);
-      scanSpinner.succeed(`Found ${chalk.bold(repos.length)} projects in ${config.devDir}`);
-    } catch (error) {
-      scanSpinner.fail('Failed to scan for projects');
-      console.error(error);
-      return;
-    }
-
-    const availableRepos = repos.filter(
-      (r) => !feature.repos.includes(r.path)
-    );
-
-    if (availableRepos.length === 0) {
-      console.log(chalk.yellow('All scanned repositories are already in the workspace.\n'));
-      return;
-    }
-
-    repoPathToAdd = await search({
-      message: 'Search and select a repository to add:',
-      source: async (input) => {
-        const query = (input || '').toLowerCase();
-        const filtered = availableRepos.filter(
-          (r) =>
-            r.name.toLowerCase().includes(query) ||
-            r.path.toLowerCase().includes(query)
-        );
-        return filtered.map((r) => ({
-          name: `${r.name} ${chalk.dim(`(${r.path})`)}`,
-          value: r.path,
-        }));
-      },
-    });
-  }
-
-  const repoName = path.basename(repoPathToAdd);
-  const spinner = ora(`Adding ${repoName} to workspace ${workspaceName}...`).start();
-
-  try {
-    await addRepoToWorkspace(workspacePath, repoPathToAdd);
-    spinner.succeed(`Successfully added ${chalk.bold(repoName)} to workspace ${chalk.bold(workspaceName)}`);
-    console.log(chalk.dim('  - Checked out git worktree'));
-    console.log(chalk.dim('  - Updated nexusflow.json and .gitignore'));
-    console.log(chalk.dim('  - Re-analyzed workspace codebases'));
-    console.log(chalk.dim('  - Regenerated LLM instruction context files'));
-    console.log(chalk.dim('  - Repacked codebase context using Repomix'));
-    console.log();
-  } catch (error) {
-    spinner.fail(`Failed to add repository: ${error instanceof Error ? error.message : String(error)}`);
-    console.log();
-  }
-}
+/**
+ * @module commands/add-repo
+ * Adds a repository to an existing NexusFlow workspace.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { select, search } from '@inquirer/prompts';
+import * as path from 'node:path';
+
+import { loadConfig } from '../core/config.js';
+import { scanForRepos } from '../core/scanner.js';
+import { listWorkspaces, loadFeatureConfig, addRepoToWorkspace } from '../core/workspace.js';
+
+/**
+ * Executes the add-repo command.
+ *
+ * @param repoPathArg - Optional repository path to add.
+ * @param workspaceArg - Optional workspace path or name.
+ */
+export async function addRepoCommand(
+  repoPathArg?: string,
+  workspaceArg?: string,
+): Promise<void> {
+  console.log(chalk.bold.cyan('\n➕ NexusFlow — Adding Repository to Workspace\n'));
+
+  const config = await loadConfig();
+
+  // 1. Resolve workspace
+  let workspacePath: string | null = null;
+  let workspaceName = '';
+
+  if (workspaceArg) {
+    const resolvedPath = path.isAbsolute(workspaceArg)
+      ? workspaceArg
+      : path.resolve(config.workspacesDir, workspaceArg);
+
+    try {
+      const manifest = await loadFeatureConfig(resolvedPath);
+      if (manifest) {
+        workspacePath = resolvedPath;
+        workspaceName = manifest.branchName;
+      }
+    } catch {}
+
+    if (!workspacePath) {
+      const directPath = path.join(config.workspacesDir, workspaceArg);
+      const manifest = await loadFeatureConfig(directPath);
+      if (manifest) {
+        workspacePath = directPath;
+        workspaceName = manifest.branchName;
+      } else {
+        console.error(chalk.red(`✖ Invalid workspace: No nexusflow.json found at ${workspaceArg}`));
+        return;
+      }
+    }
+  } else {
+    const cwdFeature = await loadFeatureConfig(process.cwd());
+    if (cwdFeature) {
+      workspacePath = cwdFeature.workspacePath;
+      workspaceName = cwdFeature.branchName;
+    } else {
+      const workspaces = await listWorkspaces(config.workspacesDir);
+      if (workspaces.length === 0) {
+        console.log(chalk.yellow('No workspaces found.\n'));
+        return;
+      }
+
+      const selected = await search({
+        message: 'Search and select a workspace to add a repository to:',
+        source: async (input) => {
+          const query = (input || '').toLowerCase();
+          const filtered = workspaces.filter(
+            (ws) =>
+              ws.branchName.toLowerCase().includes(query) ||
+              ws.workspacePath.toLowerCase().includes(query)
+          );
+          return filtered.map((ws) => ({
+            name: `${ws.branchName} ${chalk.dim(`(${ws.repos.length} repos)`)}`,
+            value: ws,
+          }));
+        },
+      });
+
+      workspacePath = selected.workspacePath;
+      workspaceName = selected.branchName;
+    }
+  }
+
+  if (!workspacePath) return;
+
+  const feature = await loadFeatureConfig(workspacePath);
+  if (!feature) {
+    console.error(chalk.red('✖ Failed to load workspace configuration.'));
+    return;
+  }
+
+  // 2. Resolve repository to add
+  let repoPathToAdd = '';
+
+  if (repoPathArg) {
+    repoPathToAdd = path.resolve(repoPathArg);
+  } else {
+    const scanSpinner = ora('Scanning for projects...').start();
+    let repos = [];
+    try {
+      repos = await scanForRepos(config.devDir, config.scanDepth);
+      scanSpinner.succeed(`Found ${chalk.bold(repos.length)} projects in ${config.devDir}`);
+    } catch (error) {
+      scanSpinner.fail('Failed to scan for projects');
+      console.error(error);
+      return;
+    }
+
+    const availableRepos = repos.filter(
+      (r) => !feature.repos.includes(r.path)
+    );
+
+    if (availableRepos.length === 0) {
+      console.log(chalk.yellow('All scanned repositories are already in the workspace.\n'));
+      return;
+    }
+
+    repoPathToAdd = await search({
+      message: 'Search and select a repository to add:',
+      source: async (input) => {
+        const query = (input || '').toLowerCase();
+        const filtered = availableRepos.filter(
+          (r) =>
+            r.name.toLowerCase().includes(query) ||
+            r.path.toLowerCase().includes(query)
+        );
+        return filtered.map((r) => ({
+          name: `${r.name} ${chalk.dim(`(${r.path})`)}`,
+          value: r.path,
+        }));
+      },
+    });
+  }
+
+  const repoName = path.basename(repoPathToAdd);
+  const spinner = ora(`Adding ${repoName} to workspace ${workspaceName}...`).start();
+
+  try {
+    await addRepoToWorkspace(workspacePath, repoPathToAdd);
+    spinner.succeed(`Successfully added ${chalk.bold(repoName)} to workspace ${chalk.bold(workspaceName)}`);
+    console.log(chalk.dim('  - Checked out git worktree'));
+    console.log(chalk.dim('  - Updated nexusflow.json and .gitignore'));
+    console.log(chalk.dim('  - Re-analyzed workspace codebases'));
+    console.log(chalk.dim('  - Regenerated LLM instruction context files'));
+    console.log();
+  } catch (error) {
+    spinner.fail(`Failed to add repository: ${error instanceof Error ? error.message : String(error)}`);
+    console.log();
+  }
+}