contextforge-cli-harshil 1.0.0

package/src/commands/init.js

@@ -0,0 +1,275 @@
+/**
+ * src/commands/init.js
+ * Orchestrates the full contextforge init flow:
+ *   1. Scan repository
+ *   2. Analyze architecture
+ *   3. Detect AI provider (Groq / OpenAI / none)
+ *   4. Generate context (AI or structural fallback)
+ *   5. Write context.md
+ */
+
+import ora from 'ora';
+import chalk from 'chalk';
+import { scanRepository, buildFolderTree } from '../scan.js';
+import { analyzeRepository } from '../analyze.js';
+import { generateStructuralContext } from '../generate.js';
+import { writeContextFile, addTimestamp, isContextUpToDate } from '../context.js';
+import { logger, formatDuration, sanitizeErrorMessage } from '../utils.js';
+
+/**
+ * Main init command handler.
+ * @param {{ output: string, model?: string, ai: boolean, provider: string }} options
+ */
+export async function runInit(options) {
+  const { output, model: modelFlag, ai, provider: providerHint, force } = options;
+  const cwd = process.cwd();
+  const startTime = Date.now();
+
+  // ── Banner ─────────────────────────────────────────────────────────────────
+  console.log('');
+  console.log(
+    chalk.bold.cyan('  ⚡ ContextForge') +
+    chalk.dim(' — AI memory generation for repositories')
+  );
+  console.log(chalk.dim(`  Scanning: ${chalk.white(cwd)}`));
+  console.log('');
+
+  // ── Resolve AI provider ────────────────────────────────────────────────────
+  let provider = null;
+  let resolvedModel = modelFlag;
+
+  if (ai) {
+    // Fix #8: validate --provider value early with a clear error message
+    const VALID_PROVIDER_HINTS = ['openai', 'groq', 'auto'];
+    if (providerHint && !VALID_PROVIDER_HINTS.includes(providerHint)) {
+      logger.error(
+        `Invalid provider "${providerHint}". Valid options: groq | openai | auto`
+      );
+      process.exit(1);
+    }
+
+    const {
+      detectProvider,
+      validateProviderKey,
+      resolveModel,
+    } = await import('../ai.js');
+
+    provider = detectProvider(providerHint ?? 'auto');
+
+    if (!provider) {
+      logger.warn('No API key found — falling back to structural context.');
+      logger.dim(
+        'Add GROQ_API_KEY (free at console.groq.com) or OPENAI_API_KEY to your .env file.'
+      );
+      console.log('');
+    } else {
+      const { valid, message } = validateProviderKey(provider);
+      if (!valid) {
+        logger.warn(message);
+        logger.dim('Falling back to structural context generation.');
+        console.log('');
+        provider = null;
+      } else {
+        resolvedModel = resolveModel(modelFlag, provider);
+      }
+    }
+  }
+
+  // ── Step 1: Scan repository ────────────────────────────────────────────────
+  const spinnerScan = ora({
+    text: chalk.white('Scanning repository...'),
+    prefixText: ' ',
+    color: 'cyan',
+    stream: process.stdout,
+  }).start();
+
+  let files;
+  try {
+    files = await scanRepository(cwd);
+    spinnerScan.succeed(
+      chalk.green('Scanning repository') +
+      chalk.dim(` — ${files.length} files found`)
+    );
+  } catch (err) {
+    spinnerScan.fail(chalk.red('Failed to scan repository'));
+    logger.error(err.message);
+    process.exit(1);
+  }
+
+  if (files.length === 0) {
+    logger.warn('No relevant files found. Run contextforge from your project root.');
+    process.exit(0);
+  }
+
+  // ── Up-to-date check ──────────────────────────────────────────────────────
+  // Skip regeneration if context.md exists and no source files have changed.
+  // Use --force to bypass this check and always regenerate.
+  if (!force) {
+    const { upToDate, changedFile } = isContextUpToDate(output, files, cwd);
+    if (upToDate) {
+      console.log('');
+      console.log(chalk.dim('  ' + '─'.repeat(50)));
+      console.log('');
+      console.log(
+        chalk.bold.green('  ✅ Already up to date!') +
+        chalk.dim(' No files changed since last run.')
+      );
+      console.log('');
+      console.log(
+        chalk.dim('  ') + chalk.bold.cyan(output) +
+        chalk.dim(' is current — nothing to regenerate.')
+      );
+      console.log(chalk.dim('  Run with ') + chalk.white('--force') + chalk.dim(' to regenerate anyway.'));
+      console.log('');
+      process.exit(0);
+    }
+    if (changedFile) {
+      logger.dim(`Change detected in: ${changedFile}`);
+    }
+  }
+
+  // ── Step 2: Analyze architecture ──────────────────────────────────────────
+  const spinnerAnalyze = ora({
+    text: chalk.white('Detecting architecture...'),
+    prefixText: ' ',
+    color: 'cyan',
+    stream: process.stdout,
+  }).start();
+
+  let analysis, folderTree;
+  try {
+    analysis = analyzeRepository(files, cwd);
+    folderTree = buildFolderTree(files);
+    spinnerAnalyze.succeed(
+      chalk.green('Detecting architecture') +
+      chalk.dim(
+        ` — ${analysis.stack.length > 0 ? analysis.stack.slice(0, 3).join(', ') : analysis.language}`
+      )
+    );
+  } catch (err) {
+    spinnerAnalyze.fail(chalk.red('Failed to analyze repository'));
+    logger.error(err.message);
+    process.exit(1);
+  }
+
+  // ── Step 3: Identify important files ──────────────────────────────────────
+  const spinnerFiles = ora({
+    text: chalk.white('Finding important files...'),
+    prefixText: ' ',
+    color: 'cyan',
+    stream: process.stdout,
+  }).start();
+
+  await new Promise((r) => setTimeout(r, 80));
+
+  spinnerFiles.succeed(
+    chalk.green('Finding important files') +
+    chalk.dim(` — ${analysis.importantFiles.length} key files identified`)
+  );
+
+  // ── Step 4: Generate context ───────────────────────────────────────────────
+  const providerLabel = provider
+    ? chalk.cyan(`${provider === 'groq' ? 'Groq' : 'OpenAI'} / ${resolvedModel}`)
+    : null;
+
+  const spinnerGenerate = ora({
+    text: chalk.white(
+      provider
+        ? `Generating AI context with ${providerLabel}...`
+        : 'Generating structural context...'
+    ),
+    prefixText: ' ',
+    color: 'cyan',
+    stream: process.stdout,
+  }).start();
+
+  let contextContent;
+
+  if (provider) {
+    try {
+      const { createClient, buildPrompt, generateContextWithAI } = await import('../ai.js');
+      const client = createClient(provider);
+      const prompt = buildPrompt(analysis, folderTree);
+
+      contextContent = await generateContextWithAI(client, prompt, resolvedModel, provider);
+
+      // Strip wrapping markdown fence if model added one
+      if (contextContent.startsWith('```markdown')) {
+        contextContent = contextContent.replace(/^```markdown\n/, '').replace(/\n```$/, '');
+      } else if (contextContent.startsWith('```')) {
+        contextContent = contextContent.replace(/^```\n/, '').replace(/\n```$/, '');
+      }
+
+      spinnerGenerate.succeed(
+        chalk.green('Generating AI context') +
+        chalk.dim(` — via ${provider === 'groq' ? 'Groq' : 'OpenAI'} (${resolvedModel})`)
+      );
+    } catch (err) {
+      spinnerGenerate.warn(
+        chalk.yellow('AI generation failed') +
+        chalk.dim(' — falling back to structural context')
+      );
+      logger.dim(`Reason: ${sanitizeErrorMessage(err.message)}`);
+      contextContent = generateStructuralContext(analysis, folderTree);
+    }
+  } else {
+    contextContent = generateStructuralContext(analysis, folderTree);
+    spinnerGenerate.succeed(chalk.green('Generating structural context'));
+  }
+
+  // ── Step 5: Write context.md ───────────────────────────────────────────────
+  const spinnerWrite = ora({
+    text: chalk.white(`Writing ${output}...`),
+    prefixText: ' ',
+    color: 'cyan',
+    stream: process.stdout,
+  }).start();
+
+  let absoluteOutputPath;
+  try {
+    const finalContent = addTimestamp(contextContent);
+    absoluteOutputPath = writeContextFile(finalContent, output, cwd);
+    spinnerWrite.succeed(chalk.green(`${output} created successfully`));
+  } catch (err) {
+    spinnerWrite.fail(chalk.red(`Failed to write ${output}`));
+    logger.error(err.message);
+    process.exit(1);
+  }
+
+  // ── Summary ────────────────────────────────────────────────────────────────
+  const elapsed = formatDuration(Date.now() - startTime);
+
+  console.log('');
+  console.log(chalk.dim('  ' + '─'.repeat(50)));
+  console.log('');
+  console.log(chalk.bold.green('  ✅ Done!') + chalk.dim(` in ${elapsed}`));
+  console.log('');
+
+  if (analysis.stack.length > 0) {
+    console.log(chalk.dim('  Detected stack:'));
+    analysis.stack.slice(0, 8).forEach((s) => {
+      console.log(chalk.dim('    · ') + chalk.white(s));
+    });
+    if (analysis.stack.length > 8) {
+      console.log(chalk.dim(`    · ...and ${analysis.stack.length - 8} more`));
+    }
+    console.log('');
+  }
+
+  if (analysis.architecturePatterns.length > 0) {
+    console.log(chalk.dim('  Detected patterns:'));
+    analysis.architecturePatterns.slice(0, 5).forEach((p) => {
+      console.log(chalk.dim('    · ') + chalk.white(p));
+    });
+    console.log('');
+  }
+
+  console.log(chalk.dim('  Output: ') + chalk.bold.cyan(absoluteOutputPath));
+  console.log('');
+  console.log(
+    chalk.dim('  Paste ') +
+    chalk.bold.white(output) +
+    chalk.dim(' into your AI assistant to give it full project context.')
+  );
+  console.log('');
+}

package/src/context.js

@@ -0,0 +1,107 @@
+/**
+ * context.js
+ * Handles writing (and reading) the context.md file.
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync, statSync } from 'fs';
+import { resolve, relative, dirname, isAbsolute } from 'path';
+
+/**
+ * Check whether context.md is already up to date.
+ *
+ * Strategy: compare the last-modified time (mtime) of the output file
+ * against every scanned source file. If context.md is newer than ALL of
+ * them, nothing has changed and we can safely skip regeneration.
+ *
+ * @param {string} outputPath - relative path to context.md
+ * @param {Array<{ absolutePath: string }>} files - scanned files
+ * @param {string} cwd
+ * @returns {{ upToDate: boolean, changedFile: string|null }}
+ */
+export function isContextUpToDate(outputPath, files, cwd) {
+  const absolutePath = resolve(cwd, outputPath);
+
+  if (!existsSync(absolutePath)) {
+    return { upToDate: false, changedFile: null };
+  }
+
+  let contextMtime;
+  try {
+    contextMtime = statSync(absolutePath).mtimeMs;
+  } catch {
+    return { upToDate: false, changedFile: null };
+  }
+
+  // Find the first source file that is newer than context.md
+  for (const file of files) {
+    try {
+      const mtime = statSync(file.absolutePath).mtimeMs;
+      if (mtime > contextMtime) {
+        return { upToDate: false, changedFile: file.path };
+      }
+    } catch {
+      // Unreadable file — treat as changed to be safe
+      return { upToDate: false, changedFile: file.path };
+    }
+  }
+
+  return { upToDate: true, changedFile: null };
+}
+
+
+/**
+ * Write the generated context markdown to a file.
+ *
+ * Security: validates that the resolved output path stays inside cwd
+ * to prevent path traversal via a malicious --output flag.
+ *
+ * @param {string} content     - Markdown content
+ * @param {string} outputPath  - Relative path for the output file (e.g. "context.md")
+ * @param {string} cwd         - Working directory (project root)
+ * @returns {string} Absolute path of the written file
+ */
+export function writeContextFile(content, outputPath, cwd) {
+  const absolutePath = resolve(cwd, outputPath);
+
+  // ── Fix #4: Path traversal guard ─────────────────────────────────────────
+  // Ensure the resolved path is inside cwd, not a parent or sibling directory.
+  const rel = relative(cwd, absolutePath);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(
+      `Output path "${outputPath}" resolves outside the project directory.\n` +
+      `Use a relative path inside your project (e.g., context.md or docs/context.md).`
+    );
+  }
+
+  // Create parent directories if needed (e.g., --output docs/ai/context.md)
+  const dir = dirname(absolutePath);
+  mkdirSync(dir, { recursive: true });
+
+  writeFileSync(absolutePath, content, 'utf-8');
+  return absolutePath;
+}
+
+/**
+ * Check if a context.md already exists and return its content.
+ * @param {string} outputPath
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function readExistingContext(outputPath, cwd) {
+  const absolutePath = resolve(cwd, outputPath);
+  if (existsSync(absolutePath)) {
+    return readFileSync(absolutePath, 'utf-8');
+  }
+  return null;
+}
+
+/**
+ * Add a timestamp header to the context markdown.
+ * @param {string} content
+ * @returns {string}
+ */
+export function addTimestamp(content) {
+  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+  const header = `<!-- Generated by ContextForge on ${timestamp} -->\n\n`;
+  return header + content;
+}

package/src/generate.js

@@ -0,0 +1,211 @@
+/**
+ * generate.js
+ * Generates the fallback structural context.md when AI is skipped or unavailable.
+ */
+
+/**
+ * Generate a purely structural context.md from analysis data (no AI).
+ * @param {Object} analysis - Result from analyzeRepository()
+ * @param {string} folderTree
+ * @returns {string} Markdown content
+ */
+export function generateStructuralContext(analysis, folderTree) {
+  const {
+    projectName,
+    projectVersion,
+    projectDescription,
+    language,
+    moduleSystem,
+    stack,
+    byCategory,
+    architecturePatterns,
+    authApproach,
+    codingConventions,
+    scripts,
+    importantFiles,
+    totalFiles,
+  } = analysis;
+
+  const now = new Date().toISOString().split('T')[0];
+
+  const sections = [];
+
+  // Header
+  sections.push(`# Project Context`);
+  sections.push(
+    `> **${projectName}**${projectDescription ? ` — ${projectDescription}` : ''}\n` +
+    `> Generated by [ContextForge](https://github.com/contextforge) on ${now}`
+  );
+
+  // Stack
+  sections.push(`## Stack`);
+  if (stack.length > 0) {
+    sections.push(stack.map((s) => `- ${s}`).join('\n'));
+  } else {
+    sections.push(`- Language: ${language}\n- Module system: ${moduleSystem}`);
+  }
+
+  // Metadata
+  sections.push(`## Project Metadata`);
+  const meta = [
+    `| Field | Value |`,
+    `|-------|-------|`,
+    `| Name | \`${projectName}\` |`,
+    `| Version | \`${projectVersion || 'N/A'}\` |`,
+    `| Language | ${language} |`,
+    `| Module System | ${moduleSystem} |`,
+    `| Total Files Scanned | ${totalFiles} |`,
+  ];
+  sections.push(meta.join('\n'));
+
+  // Architecture
+  if (architecturePatterns.length > 0) {
+    sections.push(`## Architecture`);
+    sections.push(architecturePatterns.map((p) => `- ${p}`).join('\n'));
+  }
+
+  // Auth
+  if (authApproach.length > 0) {
+    sections.push(`## Authentication`);
+    sections.push(authApproach.map((a) => `- ${a}`).join('\n'));
+  }
+
+  // Tech by category
+  const categoryOrder = ['backend', 'frontend', 'database', 'auth', 'state', 'validation', 'testing', 'styling', 'api', 'build', 'http', 'realtime'];
+  const hasCategories = Object.keys(byCategory).length > 0;
+  if (hasCategories) {
+    sections.push(`## Technology by Category`);
+    categoryOrder.forEach((cat) => {
+      if (byCategory[cat]) {
+        sections.push(`### ${capitalize(cat)}\n${byCategory[cat].map((t) => `- ${t}`).join('\n')}`);
+      }
+    });
+    // Any remaining categories not in order
+    Object.keys(byCategory).forEach((cat) => {
+      if (!categoryOrder.includes(cat)) {
+        sections.push(`### ${capitalize(cat)}\n${byCategory[cat].map((t) => `- ${t}`).join('\n')}`);
+      }
+    });
+  }
+
+  // Coding Patterns
+  if (codingConventions.length > 0) {
+    sections.push(`## Coding Patterns`);
+    sections.push(codingConventions.map((c) => `- ${c}`).join('\n'));
+  }
+
+  // Important Files
+  if (importantFiles.length > 0) {
+    sections.push(`## Important Modules`);
+    const grouped = groupFilesByTopDir(importantFiles);
+    Object.entries(grouped).forEach(([dir, files]) => {
+      sections.push(`### ${dir === '_root' ? 'Root' : `\`${dir}/\``}`);
+      sections.push(files.map((f) => `- \`${f.path}\``).join('\n'));
+    });
+  }
+
+  // Folder structure
+  sections.push(`## Folder Structure`);
+  sections.push('```\n' + folderTree + '```');
+
+  // Scripts
+  if (scripts.length > 0) {
+    sections.push(`## Development Workflow`);
+    const pkgScripts = analysis.pkgJson?.scripts || {};
+    const scriptLines = scripts.map((s) => {
+      const cmd = pkgScripts[s] || '';
+      return `- \`npm run ${s}\`${cmd ? ` — \`${cmd}\`` : ''}`;
+    });
+    sections.push(scriptLines.join('\n'));
+  }
+
+  // AI Instructions (structural version)
+  sections.push(`## AI Instructions`);
+  const instructions = buildAIInstructions(analysis);
+  sections.push(instructions.map((i) => `- ${i}`).join('\n'));
+
+  return sections.join('\n\n') + '\n';
+}
+
+/**
+ * Build AI instructions from the analysis.
+ * @param {Object} analysis
+ * @returns {string[]}
+ */
+function buildAIInstructions(analysis) {
+  const instructions = [];
+  const { byCategory, architecturePatterns, codingConventions, authApproach, language, moduleSystem } = analysis;
+
+  instructions.push(`This is a **${language}** project using **${moduleSystem}**`);
+
+  if (byCategory.backend?.length) {
+    instructions.push(`Backend framework: ${byCategory.backend.join(', ')} — follow its conventions for routing and middleware`);
+  }
+  if (byCategory.frontend?.length) {
+    instructions.push(`Frontend: ${byCategory.frontend.join(', ')} — follow component and hook patterns already established`);
+  }
+  if (byCategory.database?.length) {
+    instructions.push(`Database layer: ${byCategory.database.join(', ')} — use existing query patterns, do not introduce new ORM`);
+  }
+  if (byCategory.auth?.length) {
+    instructions.push(`Auth: ${byCategory.auth.join(', ')} — do not change the auth mechanism without explicit instruction`);
+  }
+  if (byCategory.validation?.length) {
+    instructions.push(`Validation: ${byCategory.validation.join(', ')} — validate all inputs using existing schema patterns`);
+  }
+
+  architecturePatterns.forEach((p) => {
+    instructions.push(`Respect the existing pattern: ${p}`);
+  });
+
+  if (codingConventions.includes('async/await pattern')) {
+    instructions.push('Use async/await for all asynchronous operations — avoid .then() chains');
+  }
+  if (codingConventions.includes('ES Modules (import/export)')) {
+    instructions.push('Use ES module import/export syntax — never use require()');
+  }
+  if (codingConventions.includes('CommonJS (require/exports)')) {
+    instructions.push('Use CommonJS require/exports — avoid ES module import/export');
+  }
+  if (codingConventions.includes('TypeScript with strict typing')) {
+    instructions.push('Maintain strict TypeScript types — no implicit any, define interfaces for all data structures');
+  }
+  if (codingConventions.includes('try/catch error handling')) {
+    instructions.push('Wrap all async operations in try/catch and propagate errors appropriately');
+  }
+  if (codingConventions.includes('Schema validation')) {
+    instructions.push('Validate all external inputs with the existing validation library (Zod/Joi/Yup)');
+  }
+
+  if (authApproach.includes('JWT token authentication')) {
+    instructions.push('Authentication uses JWT — always verify tokens through the existing middleware, never bypass it');
+  }
+  if (authApproach.includes('Role-based access control (RBAC)')) {
+    instructions.push('RBAC is implemented — check user roles before authorizing sensitive operations');
+  }
+
+  instructions.push('Match the existing code style, naming conventions, and file organization');
+  instructions.push('Do not introduce new dependencies without explicit user approval');
+  instructions.push('Write tests for any new feature following the existing test structure');
+
+  return instructions;
+}
+
+/**
+ * Group files by their top-level directory.
+ * Files at root are grouped under '_root'.
+ */
+function groupFilesByTopDir(files) {
+  const groups = {};
+  files.forEach((file) => {
+    const parts = file.path.split('/');
+    const dir = parts.length > 1 ? parts[0] : '_root';
+    if (!groups[dir]) groups[dir] = [];
+    groups[dir].push(file);
+  });
+  return groups;
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}