@velt-js/mcp-installer 0.1.0

package/src/utils/cli.js

@@ -0,0 +1,380 @@
+/**
+ * Velt CLI Execution Utilities
+ *
+ * Handles running the Velt CLI via npx @velt-js/add-velt.
+ * This module spawns npx to execute the published npm package.
+ */
+
+import { spawn } from 'child_process';
+
+/**
+ * Maps MCP feature selections to CLI flags
+ *
+ * CLI Flags supported by @velt-js/add-velt:
+ *   --presence          Add presence (VeltPresence - shows online users)
+ *   --cursors           Add cursors (VeltCursor - shows live cursor positions)
+ *   --comments          Add comments (VeltComments, VeltCommentsSidebar)
+ *   --notifications     Add notifications (VeltNotificationsTool)
+ *   --reactflow-crdt    Add ReactFlow CRDT
+ *   --tiptap-crdt       Add Tiptap CRDT
+ *   --codemirror-crdt   Add CodeMirror CRDT
+ *   --all               Enable presence + cursors + comments + notifications + CRDT (REQUIRES a CRDT flag!)
+ *   --force, -f         Force overwrite existing files
+ *   --legacy-peer-deps  Use legacy peer deps (npm only)
+ *
+ * @param {Object} params
+ * @param {string[]} [params.features=[]] - Features to install: 'presence', 'cursors', 'comments', 'notifications', 'crdt'
+ * @param {string} [params.crdtType=null] - CRDT type: 'tiptap', 'codemirror', 'reactflow'
+ * @param {boolean} [params.force=false] - Force overwrite files
+ * @param {boolean} [params.legacyPeerDeps=false] - Use legacy peer deps
+ * @returns {string[]} Array of CLI flags
+ */
+export function mapFeaturesToCliFlags({
+  features = [],
+  crdtType = null,
+  force = false,
+  legacyPeerDeps = false,
+}) {
+  const flags = [];
+
+  // Normalize features to lowercase
+  const normalizedFeatures = features.map(f => f.toLowerCase());
+
+  const hasPresence = normalizedFeatures.includes('presence');
+  const hasCursors = normalizedFeatures.includes('cursors');
+  const hasComments = normalizedFeatures.includes('comments');
+  const hasNotifications = normalizedFeatures.includes('notifications');
+  const hasCrdt = normalizedFeatures.includes('crdt') && crdtType;
+
+  // Validate CRDT type if provided
+  // Recognized types (accepted by MCP): includes blocknote which is handled via docs, not CLI flag
+  const recognizedCrdtTypes = ['tiptap', 'codemirror', 'reactflow', 'blocknote'];
+  // CLI-supported types (have a corresponding --X-crdt flag)
+  const cliFlagCrdtTypes = ['tiptap', 'codemirror', 'reactflow'];
+  const isCrdtRecognized = hasCrdt && recognizedCrdtTypes.includes(crdtType.toLowerCase());
+  const isCrdtCliSupported = hasCrdt && cliFlagCrdtTypes.includes(crdtType.toLowerCase());
+  if (hasCrdt && !isCrdtRecognized) {
+    console.error(`   ⚠️  Unknown CRDT type "${crdtType}", skipping CRDT flag`);
+  } else if (hasCrdt && !isCrdtCliSupported) {
+    console.error(`   ℹ️  CRDT type "${crdtType}" is handled via docs/plan, no CLI flag generated`);
+  }
+
+  // Determine flag strategy
+  // --all requires a CLI-supported CRDT flag, so only use it when we have all features with a supported CRDT type
+  const useAllFlag = hasPresence && hasCursors && hasComments && hasNotifications && isCrdtCliSupported;
+
+  if (useAllFlag) {
+    // Use --all with CRDT type
+    flags.push('--all');
+    flags.push(`--${crdtType.toLowerCase()}-crdt`);
+  } else {
+    // Build individual flags
+    if (hasPresence) {
+      flags.push('--presence');
+    }
+    if (hasCursors) {
+      flags.push('--cursors');
+    }
+    if (hasComments) {
+      flags.push('--comments');
+    }
+    if (hasNotifications) {
+      flags.push('--notifications');
+    }
+    if (isCrdtCliSupported) {
+      flags.push(`--${crdtType.toLowerCase()}-crdt`);
+    }
+  }
+
+  // Add installation flags
+  if (force) {
+    flags.push('--force');
+  }
+  if (legacyPeerDeps) {
+    flags.push('--legacy-peer-deps');
+  }
+
+  return flags;
+}
+
+/**
+ * Runs the Velt CLI via npx @velt-js/add-velt
+ *
+ * @param {Object} params
+ * @param {string} params.installDir - Directory to install Velt in
+ * @param {string} params.apiKey - Velt API key
+ * @param {string} [params.authToken] - Optional auth token
+ * @param {string[]} [params.features=[]] - Features to install (for guided mode)
+ * @param {string} [params.crdtType=null] - CRDT editor type if 'crdt' feature selected
+ * @param {boolean} [params.force=false] - Force overwrite existing files
+ * @param {boolean} [params.legacyPeerDeps=false] - Use legacy peer deps (npm only)
+ * @returns {Promise<Object>} CLI execution result
+ */
+export async function runVeltCli({
+  installDir,
+  apiKey,
+  authToken = null,
+  features = [],
+  crdtType = null,
+  force = false,
+  legacyPeerDeps = false,
+}) {
+  try {
+    // Log what we're about to do
+    console.error('\n📦 Velt CLI Execution');
+    console.error(`   Directory: ${installDir}`);
+    console.error(`   API Key: ${apiKey ? `${apiKey.substring(0, 8)}...` : '(not provided)'}`);
+
+    // Map features to CLI flags
+    const flags = mapFeaturesToCliFlags({
+      features,
+      crdtType,
+      force,
+      legacyPeerDeps,
+    });
+
+    console.error(`   🏷️  Features: ${features.length > 0 ? features.join(', ') : '(core only)'}`);
+    console.error(`   🚩 Flags: ${flags.length > 0 ? flags.join(' ') : '(none)'}`);
+
+    // Build environment with API credentials
+    const env = {
+      ...process.env,
+      VELT_API_KEY: apiKey,
+      NEXT_PUBLIC_VELT_API_KEY: apiKey,
+    };
+
+    if (authToken) {
+      env.VELT_AUTH_TOKEN = authToken;
+    }
+
+    // Build npx command
+    const npxArgs = ['@velt-js/add-velt', ...flags];
+    const fullCommand = `npx ${npxArgs.join(' ')}`;
+
+    console.error('\n   ═══════════════════════════════════════════════════════════');
+    console.error(`   📋 EXACT CLI COMMAND: ${fullCommand}`);
+    console.error('   ═══════════════════════════════════════════════════════════\n');
+
+    // Execute via npx
+    const result = await new Promise((resolve) => {
+      let stdout = '';
+      let stderr = '';
+      const timeout = 120000;
+
+      const proc = spawn('npx', npxArgs, {
+        cwd: installDir,
+        env,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        shell: process.platform === 'win32',
+      });
+
+      const timeoutId = setTimeout(() => {
+        proc.kill('SIGTERM');
+        resolve({
+          success: false,
+          error: `CLI execution timed out after ${timeout}ms`,
+          method: 'npx',
+          command: fullCommand,
+          exitCode: -1,
+          stdout,
+          stderr,
+        });
+      }, timeout);
+
+      proc.stdout?.on('data', (data) => {
+        stdout += data.toString();
+        process.stderr.write(data);
+      });
+
+      proc.stderr?.on('data', (data) => {
+        stderr += data.toString();
+        process.stderr.write(data);
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timeoutId);
+        resolve({
+          success: false,
+          error: err.message,
+          method: 'npx',
+          command: fullCommand,
+          exitCode: 1,
+          stdout,
+          stderr,
+        });
+      });
+
+      proc.on('close', (code) => {
+        clearTimeout(timeoutId);
+        resolve({
+          success: code === 0,
+          exitCode: code,
+          method: 'npx',
+          command: fullCommand,
+          stdout,
+          stderr,
+          output: stdout + stderr,
+        });
+      });
+    });
+
+    // Log result summary
+    if (result.success) {
+      console.error(`\n   ✅ CLI completed successfully (method: ${result.method})`);
+    } else {
+      console.error(`\n   ⚠️  CLI exited with code ${result.exitCode} (method: ${result.method})`);
+      if (result.error) {
+        console.error(`   Error: ${result.error}`);
+      }
+    }
+
+    return {
+      success: result.success,
+      exitCode: result.exitCode,
+      output: result.output,
+      command: result.command,
+      method: result.method,
+      error: result.error,
+    };
+  } catch (error) {
+    console.error(`   ❌ CLI execution error: ${error.message}`);
+    return {
+      success: false,
+      error: error.message,
+      exitCode: 1,
+      method: 'error',
+    };
+  }
+}
+
+/**
+ * Runs CLI with feature-specific flags (for guided mode)
+ *
+ * This is the recommended function for the guided installation path
+ * where users have selected specific features.
+ *
+ * @param {Object} params
+ * @param {string} params.projectPath - Target project directory
+ * @param {string} params.apiKey - Velt API key
+ * @param {string} [params.authToken] - Auth token
+ * @param {string[]} params.features - Features: 'comments', 'notifications', 'crdt', 'presence', 'cursors', 'recorder'
+ * @param {string} [params.commentType] - Comment type (not used by CLI, for plan only)
+ * @param {string} [params.crdtEditorType] - CRDT editor: 'tiptap', 'codemirror', 'reactflow'
+ * @param {boolean} [params.force=false] - Force overwrite
+ * @returns {Promise<Object>} CLI execution result
+ */
+export async function runVeltCliWithFeatures({
+  projectPath,
+  apiKey,
+  authToken = null,
+  features = [],
+  commentType = null,
+  crdtEditorType = null,
+  force = false,
+}) {
+  console.error('\n🎯 Running Velt CLI with feature flags');
+
+  // Map MCP features to CLI-compatible features
+  // The CLI supports: comments, notifications, presence, cursors, and CRDT types
+  // Only 'recorder' is handled by the MCP guided plan (not supported by CLI)
+  const cliFeatures = [];
+
+  if (features.includes('comments')) {
+    cliFeatures.push('comments');
+  }
+  if (features.includes('notifications')) {
+    cliFeatures.push('notifications');
+  }
+  if (features.includes('presence')) {
+    cliFeatures.push('presence');
+  }
+  if (features.includes('cursors')) {
+    cliFeatures.push('cursors');
+  }
+  if (features.includes('crdt')) {
+    if (crdtEditorType) {
+      cliFeatures.push('crdt');
+    } else {
+      console.error('   ⚠️  CRDT feature selected but no crdtEditorType provided — CRDT will be skipped');
+    }
+  }
+
+  console.error(`   Requested features: ${features.join(', ')}`);
+  console.error(`   CLI features to forward: ${cliFeatures.length > 0 ? cliFeatures.join(', ') : '(core only)'}`);
+
+  if (crdtEditorType) {
+    console.error(`   CRDT Editor: ${crdtEditorType}`);
+  }
+
+  return runVeltCli({
+    installDir: projectPath,
+    apiKey,
+    authToken,
+    features: cliFeatures,
+    crdtType: crdtEditorType,
+    force,
+  });
+}
+
+/**
+ * Runs CLI in core-only mode (for SKIP/CLI-only path)
+ *
+ * This runs the CLI without any feature flags, generating only
+ * the core scaffold files (VeltInitializeDocument, VeltInitializeUser, VeltCollaboration).
+ *
+ * @param {Object} params
+ * @param {string} params.projectPath - Target project directory
+ * @param {string} params.apiKey - Velt API key
+ * @param {string} [params.authToken] - Auth token
+ * @param {boolean} [params.force=false] - Force overwrite
+ * @returns {Promise<Object>} CLI execution result
+ */
+export async function runVeltCliCoreOnly({
+  projectPath,
+  apiKey,
+  authToken = null,
+  force = false,
+}) {
+  console.error('\n📦 Running Velt CLI (core only, no feature flags)');
+
+  return runVeltCli({
+    installDir: projectPath,
+    apiKey,
+    authToken,
+    features: [], // No features = core scaffold only
+    crdtType: null,
+    force,
+  });
+}
+
+/**
+ * Gets CLI resolution info (for diagnostics/validation)
+ *
+ * @returns {Object} CLI resolution result
+ */
+export function getCliResolutionInfo() {
+  return {
+    method: 'npx',
+    command: 'npx @velt-js/add-velt',
+    path: null,
+  };
+}
+
+/**
+ * Gets the CLI flags that would be used for given features
+ *
+ * @param {Object} params - Same as mapFeaturesToCliFlags
+ * @returns {string[]} Array of CLI flags
+ */
+export function previewCliFlags(params) {
+  return mapFeaturesToCliFlags(params);
+}
+
+export default {
+  runVeltCli,
+  runVeltCliWithFeatures,
+  runVeltCliCoreOnly,
+  getCliResolutionInfo,
+  previewCliFlags,
+  mapFeaturesToCliFlags,
+};

package/src/utils/comment-detector.js

@@ -0,0 +1,305 @@
+/**
+ * Comment Placement Detector
+ *
+ * Analyzes project structure to determine the best files and locations
+ * for placing Velt comments (Freestyle or Popover).
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * @typedef {Object} CommentPlacement
+ * @property {string} file - File path where comment should be added
+ * @property {string} componentName - Name of the component/file
+ * @property {string} reason - Why this location was chosen
+ * @property {string} implementationGuide - How to implement the comment type
+ * @property {number} confidence - Confidence score (0-100)
+ */
+
+/**
+ * Detects where to place comments based on user's description and comment type
+ *
+ * @param {Object} options - Detection options
+ * @param {string} options.projectPath - Path to the Next.js project
+ * @param {string} options.commentType - 'freestyle' or 'popover'
+ * @param {string} [options.targetDescription] - User's description of where to place comments (e.g., "header", "sidebar")
+ * @param {string} [options.targetComponent] - Specific component name if known
+ * @returns {Promise<Object>} Detection results
+ */
+export async function detectCommentPlacement(options) {
+  const {
+    projectPath,
+    commentType,
+    targetDescription = '',
+    targetComponent = '',
+  } = options;
+
+  try {
+    console.error(`🔍 Analyzing project for ${commentType} comment placement...`);
+    if (targetDescription) {
+      console.error(`   🎯 Target: ${targetDescription}`);
+    }
+
+    // Step 1: Detect project structure
+    const structure = detectProjectStructure(projectPath);
+
+    // Step 2: Find candidate files
+    const candidates = await findCandidateFiles({
+      structure,
+      targetDescription,
+      targetComponent,
+      commentType,
+    });
+
+    // Step 3: Rank candidates by confidence
+    const rankedCandidates = rankCandidates(candidates, {
+      commentType,
+      targetDescription,
+      targetComponent,
+    });
+
+    console.error(`   ✅ Found ${rankedCandidates.length} potential placement(s)`);
+
+    return {
+      success: true,
+      data: {
+        commentType,
+        targetDescription,
+        placements: rankedCandidates,
+        recommendedPlacement: rankedCandidates[0] || null,
+      },
+    };
+  } catch (error) {
+    console.error(`   ❌ Error detecting comment placement: ${error.message}`);
+
+    return {
+      success: false,
+      error: error.message,
+      stack: error.stack,
+    };
+  }
+}
+
+/**
+ * Detects project structure
+ */
+function detectProjectStructure(projectPath) {
+  const srcAppPath = path.join(projectPath, 'src', 'app');
+  const hasSrcApp = fs.existsSync(srcAppPath);
+
+  const appRoot = hasSrcApp
+    ? path.join(projectPath, 'src', 'app')
+    : path.join(projectPath, 'app');
+
+  const componentsRoot = hasSrcApp
+    ? path.join(projectPath, 'src', 'components')
+    : path.join(projectPath, 'components');
+
+  return {
+    hasSrcApp,
+    appRoot,
+    componentsRoot,
+    projectPath,
+  };
+}
+
+/**
+ * Finds candidate files for comment placement
+ */
+async function findCandidateFiles(options) {
+  const { structure, targetDescription, targetComponent, commentType } = options;
+  const candidates = [];
+
+  // Helper to search directory recursively
+  function searchDirectory(dir, relativePath = '') {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.join(relativePath, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip node_modules and .next
+        if (entry.name === 'node_modules' || entry.name === '.next') continue;
+        searchDirectory(fullPath, relPath);
+      } else if (entry.isFile() && /\.(tsx|jsx)$/.test(entry.name)) {
+        // Analyze this file
+        const analysis = analyzeFile(fullPath, relPath, targetDescription, targetComponent, commentType);
+        if (analysis) {
+          candidates.push(analysis);
+        }
+      }
+    }
+  }
+
+  // Search app directory
+  searchDirectory(structure.appRoot, 'app');
+
+  // Search components directory
+  if (fs.existsSync(structure.componentsRoot)) {
+    searchDirectory(structure.componentsRoot, 'components');
+  }
+
+  return candidates;
+}
+
+/**
+ * Analyzes a file to determine if it's a good candidate
+ */
+function analyzeFile(filePath, relativePath, targetDescription, targetComponent, commentType) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const fileName = path.basename(filePath);
+    const componentName = fileName.replace(/\.(tsx|jsx)$/, '');
+
+    // Calculate match score
+    let matchScore = 0;
+    let matchReasons = [];
+
+    // Check if filename matches target description
+    const normalizedTarget = targetDescription.toLowerCase();
+    const normalizedFileName = fileName.toLowerCase();
+    const normalizedRelPath = relativePath.toLowerCase();
+
+    // Keyword matching
+    const keywords = {
+      header: ['header', 'navbar', 'nav', 'topbar', 'menu'],
+      sidebar: ['sidebar', 'drawer', 'aside', 'panel'],
+      footer: ['footer', 'bottom'],
+      main: ['main', 'content', 'body', 'page'],
+      card: ['card', 'item', 'post', 'article'],
+      list: ['list', 'grid', 'table'],
+      form: ['form', 'input', 'field'],
+      button: ['button', 'btn', 'action'],
+    };
+
+    // Match against keywords
+    for (const [category, words] of Object.entries(keywords)) {
+      if (normalizedTarget.includes(category)) {
+        for (const word of words) {
+          if (normalizedFileName.includes(word) || normalizedRelPath.includes(word)) {
+            matchScore += 30;
+            matchReasons.push(`Matches "${word}" in filename/path`);
+            break;
+          }
+        }
+      }
+    }
+
+    // Check if specific component name matches
+    if (targetComponent && normalizedFileName.includes(targetComponent.toLowerCase())) {
+      matchScore += 50;
+      matchReasons.push(`Matches specified component name "${targetComponent}"`);
+    }
+
+    // Check for React component patterns
+    if (content.includes('export default') || content.includes('export function') || content.includes('export const')) {
+      matchScore += 10;
+      matchReasons.push('Contains React component export');
+    }
+
+    // Freestyle comments work best on page-level components
+    if (commentType === 'freestyle') {
+      if (fileName === 'page.tsx' || fileName === 'page.jsx') {
+        matchScore += 20;
+        matchReasons.push('Page component is ideal for freestyle comments');
+      }
+      if (content.includes('VeltComments') || content.includes('VeltProvider')) {
+        matchScore += 15;
+        matchReasons.push('Already has Velt integration');
+      }
+    }
+
+    // Popover comments work best on interactive components
+    if (commentType === 'popover') {
+      if (content.includes('onClick') || content.includes('button') || content.includes('Button')) {
+        matchScore += 15;
+        matchReasons.push('Has interactive elements (good for popover)');
+      }
+      if (content.includes('card') || content.includes('Card') || content.includes('item')) {
+        matchScore += 15;
+        matchReasons.push('Has card/item components (good for popover)');
+      }
+    }
+
+    // If no matches, skip this file
+    if (matchScore === 0) {
+      return null;
+    }
+
+    // Build implementation guide
+    const implementationGuide = buildImplementationGuide(commentType, componentName, content);
+
+    return {
+      file: relativePath,
+      fullPath: filePath,
+      componentName,
+      reason: matchReasons.join('; '),
+      implementationGuide,
+      confidence: Math.min(matchScore, 100),
+      commentType,
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Builds implementation guide for the comment type
+ */
+function buildImplementationGuide(commentType, componentName, fileContent) {
+  if (commentType === 'freestyle') {
+    return `
+To add Freestyle Comments to ${componentName}:
+
+1. Import: import { VeltComments } from '@veltdev/react';
+2. Add component: <VeltComments />
+3. Freestyle comments allow users to click anywhere on the page to add comments
+4. No additional props required for basic setup
+
+Example:
+  <div>
+    <VeltComments />
+    {/* Your existing content */}
+  </div>
+
+Docs: https://docs.velt.dev/async-collaboration/comments/setup/freestyle
+`;
+  }
+
+  if (commentType === 'popover') {
+    return `
+To add Popover Comments to ${componentName}:
+
+1. Import: import { VeltCommentTool } from '@veltdev/react';
+2. Add data attribute to target elements: data-velt-comment-target="{uniqueId}"
+3. Add the comment tool component: <VeltCommentTool commentTargetId="{uniqueId}" />
+
+Example:
+  <div data-velt-comment-target="component-${componentName.toLowerCase()}">
+    <VeltCommentTool commentTargetId="component-${componentName.toLowerCase()}" />
+    {/* Your existing content */}
+  </div>
+
+Docs: https://docs.velt.dev/async-collaboration/comments/setup/popover
+`;
+  }
+
+  return `See Velt documentation for ${commentType} comments implementation.`;
+}
+
+/**
+ * Ranks candidates by confidence score
+ */
+function rankCandidates(candidates, options) {
+  return candidates
+    .sort((a, b) => b.confidence - a.confidence)
+    .slice(0, 5); // Return top 5 candidates
+}
+
+export default {
+  detectCommentPlacement,
+};