contextforge-cli-harshil 1.0.0

package/.env.example

@@ -0,0 +1,37 @@
+# ============================================================
+# ContextForge Configuration
+# Copy this file to .env and fill in your values.
+# Change ONLY this file — no code changes needed.
+# ============================================================
+
+
+# ── Provider (groq | openai) ─────────────────────────────────
+# Which AI provider to use.
+# Leave blank to auto-detect from whichever API key is present.
+# If both keys are set, Groq is preferred (faster + free tier).
+AI_PROVIDER=groq
+
+
+# ── Model ────────────────────────────────────────────────────
+# Which model to use. Leave blank to use each provider's default.
+#
+# Groq models:
+#   llama-3.3-70b-versatile   ← default (best quality)
+#   llama-3.1-8b-instant      ← fastest
+#   mixtral-8x7b-32768
+#   gemma2-9b-it
+#
+# OpenAI models:
+#   gpt-4o-mini               ← default (cheap + fast)
+#   gpt-4o
+#   gpt-4-turbo
+#
+AI_MODEL=llama-3.3-70b-versatile
+
+
+# ── API Keys ─────────────────────────────────────────────────
+# Get a free Groq key at: https://console.groq.com
+GROQ_API_KEY=gsk_your-groq-key-here
+
+# Get an OpenAI key at: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=sk-your-openai-key-here

package/README.md

@@ -0,0 +1,170 @@
+# ⚡ ContextForge
+
+> **Automatic AI memory generation for repositories.**
+
+Run one command → automatically generate reusable AI-ready project context.
+
+---
+
+## What It Does
+
+ContextForge scans your repository, analyzes its architecture and stack, and generates a `context.md` file that you can paste into any AI assistant (ChatGPT, Claude, Gemini, Cursor, etc.) to give it deep, accurate knowledge of your codebase — instantly.
+
+**No backend. No cloud. No magic. Just fast, local analysis.**
+
+---
+
+## Installation
+
+```bash
+npm install -g contextforge
+```
+
+---
+
+## Usage
+
+### 1. Add your OpenAI API key
+
+Create a `.env` file in your **project root** (the repo you want to analyze):
+
+```env
+OPENAI_API_KEY=sk-your-api-key-here
+```
+
+### 2. Run ContextForge
+
+```bash
+contextforge init
+```
+
+That's it. ContextForge will:
+
+1. 🔍 **Scan** your repository (using fast-glob + .gitignore rules)
+2. 🧠 **Analyze** your architecture, stack, patterns, and auth
+3. 📁 **Identify** important files with heuristic scoring
+4. ✨ **Generate** AI-ready context using GPT-4o-mini
+5. 📝 **Write** `context.md` to your project root
+
+---
+
+## CLI Options
+
+```
+contextforge init [options]
+
+Options:
+  -o, --output <path>   Output file path (default: "context.md")
+  --model <model>       OpenAI model to use (default: "gpt-4o-mini")
+  --no-ai               Skip OpenAI, generate structural context only
+  -v, --version         Output the current version
+  -h, --help            Display help
+```
+
+### Examples
+
+```bash
+# Standard usage
+contextforge init
+
+# Use a more powerful model
+contextforge init --model gpt-4o
+
+# Offline / no API key — structural context only
+contextforge init --no-ai
+
+# Custom output path
+contextforge init --output docs/ai-context.md
+```
+
+---
+
+## Output Format
+
+```markdown
+# Project Context
+
+> Express.js REST API with Prisma ORM and JWT authentication.
+
+## Stack
+- Express.js
+- Node.js
+- Prisma ORM
+- JWT (jsonwebtoken)
+- Zod
+
+## Architecture
+- Route-based API structure
+- MVC / Controller pattern
+- Service layer pattern
+- Middleware-based request handling
+
+## Important Modules
+### `src/`
+- `src/app.js`
+- `src/routes/`
+- `src/controllers/`
+- `src/services/`
+- `src/middleware/auth.js`
+
+## Coding Patterns
+- async/await pattern
+- ES Modules (import/export)
+- try/catch error handling
+- Schema validation (Zod)
+
+## AI Instructions
+- This is a JavaScript project using ES Modules
+- Backend: Express.js — follow route/controller/service layering
+- Database: Prisma ORM — use existing query patterns
+- Auth: JWT — never bypass the auth middleware
+- Validate all inputs with Zod schemas
+- Use async/await for all async operations
+```
+
+---
+
+## How File Importance Is Scored
+
+ContextForge uses **lightweight heuristic scoring** — no embeddings, no vectors:
+
+| Signal | Score |
+|---|---|
+| Filename matches known important files | +10 |
+| Directory matches (auth, routes, services, etc.) | +7 |
+| Filename contains keywords (auth, route, controller...) | +5 |
+| Content patterns (router.get, prisma., jwt.sign...) | +2 each |
+| File extension (JS/TS > JSON/YAML > MD) | +1–3 |
+
+---
+
+## Architecture Detection
+
+ContextForge detects:
+
+- **Frameworks**: Express, Fastify, NestJS, Next.js, React, Vue, Svelte, Astro, Remix...
+- **Databases**: Prisma, Mongoose, TypeORM, Drizzle, Sequelize, PostgreSQL, MySQL, Redis...
+- **Auth**: JWT, Passport.js, NextAuth, Clerk, Supabase, Firebase, bcrypt...
+- **State**: Zustand, Jotai, Redux Toolkit, TanStack Query, SWR...
+- **Validation**: Zod, Joi, Yup, class-validator...
+- **Testing**: Jest, Vitest, Playwright, Cypress...
+- **Patterns**: Service layer, Repository, MVC, Middleware, RBAC, File-system routing...
+
+---
+
+## Privacy
+
+Everything runs **locally** on your machine. Your code is only sent to OpenAI when AI generation is enabled (the default). Use `--no-ai` to keep everything fully local.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- OpenAI API key (optional with `--no-ai`)
+
+---
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import dotenv from 'dotenv';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+
+// Load .env from the directory where contextforge is being run
+const envPath = resolve(process.cwd(), '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+// Read package.json for version
+const __dirname = new URL('.', import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1');
+const pkgPath = resolve(__dirname, '..', 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+program
+  .name('contextforge')
+  .description(
+    chalk.bold.cyan('⚡ ContextForge') +
+    ' — Automatic AI memory generation for repositories.'
+  )
+  .version(pkg.version, '-v, --version', 'Output the current version');
+
+// ── contextforge init ──────────────────────────────────────────────────────
+program
+  .command('init')
+  .description('Scan repository and generate AI-ready context.md')
+  .option('-o, --output <path>', 'Output file path', 'context.md')
+  .option(
+    '-p, --provider <provider>',
+    'AI provider to use: groq | openai | auto (default: auto — prefers Groq)',
+    'auto'
+  )
+  .option(
+    '--model <model>',
+    'Model override (e.g. llama-3.3-70b-versatile, gpt-4o). Defaults to provider\'s recommended model.'
+  )
+  .option('--no-ai', 'Skip AI and generate a structural context only')
+  .option('--force', 'Regenerate even if context.md is already up to date')
+  .action(async (options) => {
+    const { runInit } = await import('../src/commands/init.js');
+    await runInit(options);
+  });
+
+// Show help with clean exit if no command given
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+  process.exit(0); // explicit 0 — not a failure
+}
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "contextforge-cli-harshil",
+  "version": "1.0.0",
+  "description": "Automatically scan a repository and generate AI-ready project context in context.md",
+  "main": "src/index.js",
+  "bin": {
+    "contextforge": "./bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node bin/index.js",
+    "dev": "node bin/index.js"
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "cli",
+    "openai",
+    "repository",
+    "codegen",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "fast-glob": "^3.3.2",
+    "groq-sdk": "^1.2.0",
+    "ignore": "^5.3.1",
+    "openai": "^4.52.7",
+    "ora": "^8.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module"
+}

package/src/ai.js

@@ -0,0 +1,399 @@
+/**
+ * ai.js
+ * Unified AI provider — supports OpenAI and Groq.
+ *
+ * Configuration priority (highest → lowest):
+ *   1. CLI flags      --provider groq   --model llama-3.3-70b-versatile
+ *   2. .env vars      AI_PROVIDER=groq  AI_MODEL=llama-3.3-70b-versatile
+ *   3. Auto-detect    reads GROQ_API_KEY / OPENAI_API_KEY from .env
+ *   4. Defaults       Groq → llama-3.3-70b-versatile | OpenAI → gpt-4o-mini
+ *
+ * Changing ONLY your .env file is enough to switch provider and model.
+ */
+
+import OpenAI from 'openai';
+import Groq from 'groq-sdk';
+import { readFileSafe } from './scan.js';
+
+// ── Provider registry ─────────────────────────────────────────────────────────
+
+export const PROVIDERS = {
+  openai: {
+    name: 'OpenAI',
+    envKey: 'OPENAI_API_KEY',
+    defaultModel: 'gpt-4o-mini',
+    models: ['gpt-4o-mini', 'gpt-4o', 'gpt-4-turbo', 'gpt-3.5-turbo'],
+  },
+  groq: {
+    name: 'Groq',
+    envKey: 'GROQ_API_KEY',
+    defaultModel: 'llama-3.3-70b-versatile',
+    models: [
+      'llama-3.3-70b-versatile',
+      'llama-3.1-70b-versatile',
+      'llama-3.1-8b-instant',
+      'llama3-70b-8192',
+      'llama3-8b-8192',
+      'mixtral-8x7b-32768',
+      'gemma2-9b-it',
+    ],
+  },
+};
+
+// ── Provider detection ────────────────────────────────────────────────────────
+
+/**
+ * Detect which AI provider to use.
+ *
+ * Resolution order:
+ *   1. Explicit CLI --provider flag  (hint !== 'auto')
+ *   2. AI_PROVIDER env var           (set in .env)
+ *   3. Auto-detect from API keys     (GROQ preferred over OpenAI)
+ *
+ * @param {'openai'|'groq'|'auto'} hint - value from --provider flag
+ * @returns {'openai'|'groq'|null}
+ */
+export function detectProvider(hint = 'auto') {
+  // 1. Explicit CLI flag overrides everything
+  if (hint === 'openai') return process.env.OPENAI_API_KEY ? 'openai' : null;
+  if (hint === 'groq')   return process.env.GROQ_API_KEY   ? 'groq'   : null;
+
+  // 2. AI_PROVIDER set in .env
+  const envProvider = (process.env.AI_PROVIDER || '').toLowerCase().trim();
+  if (envProvider === 'openai') return process.env.OPENAI_API_KEY ? 'openai' : null;
+  if (envProvider === 'groq')   return process.env.GROQ_API_KEY   ? 'groq'   : null;
+
+  // 3. Auto-detect: prefer Groq (faster, generous free tier)
+  if (process.env.GROQ_API_KEY)   return 'groq';
+  if (process.env.OPENAI_API_KEY) return 'openai';
+
+  return null;
+}
+
+/**
+ * Validate that the API key for the selected provider is present and looks valid.
+ *
+ * @param {'openai'|'groq'} provider
+ * @returns {{ valid: boolean, message: string }}
+ */
+export function validateProviderKey(provider) {
+  const cfg = PROVIDERS[provider];
+  if (!cfg) {
+    return { valid: false, message: `Unknown provider: "${provider}"` };
+  }
+
+  const key = process.env[cfg.envKey];
+  if (!key) {
+    return {
+      valid: false,
+      message:
+        `${cfg.envKey} is not set.\n` +
+        `    Add it to a .env file in your project root:\n\n` +
+        `      ${cfg.envKey}=your-key-here\n`,
+    };
+  }
+
+  // Basic format checks
+  if (provider === 'openai' && !key.startsWith('sk-')) {
+    return {
+      valid: false,
+      message: 'OPENAI_API_KEY looks invalid (should start with "sk-"). Check your .env file.',
+    };
+  }
+  if (provider === 'groq' && !key.startsWith('gsk_')) {
+    return {
+      valid: false,
+      message: 'GROQ_API_KEY looks invalid (should start with "gsk_"). Check your .env file.',
+    };
+  }
+
+  return { valid: true, message: '' };
+}
+
+// ── Client creation ───────────────────────────────────────────────────────────
+
+/**
+ * Create and return the AI client for the given provider.
+ *
+ * @param {'openai'|'groq'} provider
+ * @returns {OpenAI|Groq}
+ */
+export function createClient(provider) {
+  if (provider === 'groq') {
+    return new Groq({ apiKey: process.env.GROQ_API_KEY });
+  }
+  return new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+}
+
+/**
+ * Resolve which model to use.
+ *
+ * Resolution order:
+ *   1. --model CLI flag
+ *   2. AI_MODEL env var  (set in .env)
+ *   3. Provider's built-in default
+ *
+ * @param {string|undefined} modelFlag - value from --model CLI flag
+ * @param {'openai'|'groq'} provider
+ * @returns {string}
+ */
+export function resolveModel(modelFlag, provider) {
+  // 1. Explicit CLI --model flag
+  if (modelFlag) return modelFlag;
+
+  // 2. AI_MODEL in .env
+  const envModel = (process.env.AI_MODEL || '').trim();
+  if (envModel) return envModel;
+
+  // 3. Provider default
+  return PROVIDERS[provider].defaultModel;
+}
+
+// ── Prompt builder ────────────────────────────────────────────────────────────
+
+/**
+ * Build the analysis prompt to send to the AI model.
+ *
+ * @param {Object} analysis  - Result from analyzeRepository()
+ * @param {string} folderTree
+ * @returns {string}
+ */
+export function buildPrompt(analysis, folderTree) {
+  const {
+    projectName,
+    projectVersion,
+    projectDescription,
+    language,
+    moduleSystem,
+    stack,
+    byCategory,
+    architecturePatterns,
+    authApproach,
+    codingConventions,
+    scripts,
+    importantFiles,
+  } = analysis;
+
+  // Collect snippets from important files (budget-capped for free-tier models)
+  const snippetParts = [];
+  let totalSnippetLength = 0;
+  const MAX_TOTAL = 18_000;   // ~4500 tokens — leaves room for prompt + response
+  const MAX_PER_FILE = 1_200; // ~300 tokens per file
+
+  for (const file of importantFiles) {
+    if (totalSnippetLength >= MAX_TOTAL) break;
+    const content = readFileSafe(file.absolutePath, MAX_PER_FILE);
+    if (!content) continue;
+    const snippet = `### ${file.path}\n\`\`\`\n${content}\n\`\`\``;
+    snippetParts.push(snippet);
+    totalSnippetLength += snippet.length;
+  }
+
+  // package.json summary (capped)
+  const pkgSummary = analysis.pkgJson
+    ? JSON.stringify(
+        {
+          name: analysis.pkgJson.name,
+          version: analysis.pkgJson.version,
+          description: analysis.pkgJson.description,
+          scripts: analysis.pkgJson.scripts,
+          dependencies: analysis.pkgJson.dependencies,
+          devDependencies: analysis.pkgJson.devDependencies,
+        },
+        null,
+        2
+      ).slice(0, 4_000)
+    : 'Not available';
+
+  const stackBlock =
+    stack.length > 0
+      ? stack.map((s) => `- ${s}`).join('\n')
+      : '- No external dependencies detected';
+
+  const categoryBlock =
+    Object.entries(byCategory)
+      .map(([cat, items]) => `**${capitalize(cat)}:** ${items.join(', ')}`)
+      .join('\n') || 'N/A';
+
+  const archBlock =
+    architecturePatterns.length > 0
+      ? architecturePatterns.map((p) => `- ${p}`).join('\n')
+      : '- Unable to determine';
+
+  const authBlock =
+    authApproach.length > 0
+      ? authApproach.map((a) => `- ${a}`).join('\n')
+      : '- None detected';
+
+  const conventionBlock =
+    codingConventions.length > 0
+      ? codingConventions.map((c) => `- ${c}`).join('\n')
+      : '- None detected';
+
+  const scriptBlock =
+    scripts.length > 0
+      ? scripts.map((s) => `- \`${s}\``).join('\n')
+      : '- None';
+
+  return `You are an expert software architect. Analyze the following repository and generate a comprehensive, AI-ready project context document.
+
+## Repository Overview
+
+**Project Name:** ${projectName}
+**Version:** ${projectVersion || 'N/A'}
+**Description:** ${projectDescription || 'N/A'}
+**Language:** ${language}
+**Module System:** ${moduleSystem}
+
+## Detected Technology Stack
+
+${stackBlock}
+
+### By Category
+${categoryBlock}
+
+## Detected Architecture Patterns
+
+${archBlock}
+
+## Detected Auth Approach
+
+${authBlock}
+
+## Detected Coding Conventions
+
+${conventionBlock}
+
+## Available Scripts
+
+${scriptBlock}
+
+## Folder Structure
+
+\`\`\`
+${folderTree}
+\`\`\`
+
+## package.json
+
+\`\`\`json
+${pkgSummary}
+\`\`\`
+
+## Important File Snippets
+
+${snippetParts.join('\n\n')}
+
+---
+
+## Your Task
+
+Based on all of the above, generate a well-structured **context.md** document in the following exact format:
+
+\`\`\`markdown
+# Project Context
+
+> [One-sentence summary of what this project does]
+
+## Stack
+
+[List every confirmed technology: language, runtime, frameworks, databases, auth, styling, testing, build tools]
+
+## Architecture
+
+[Explain the high-level design: patterns used, folder layout rationale, component interaction, data flow]
+
+## Important Modules
+
+[For each major area — auth, database, routing, services, etc. — list relevant paths and explain their role]
+
+## Coding Patterns
+
+[List observed conventions: async style, error handling, module system, typing, etc.]
+
+## API Structure
+
+[If applicable: REST/GraphQL/tRPC style, endpoint organization, auth middleware flow]
+
+## Database & Data Layer
+
+[If applicable: ORM/query approach, schema structure, migration strategy]
+
+## Environment & Configuration
+
+[List important environment variables and how config is managed]
+
+## Development Workflow
+
+[List npm scripts and what they do]
+
+## AI Instructions
+
+[Specific, actionable rules for an AI assistant working in this codebase. Be concrete and prescriptive.]
+\`\`\`
+
+Rules:
+1. Omit any section that is not relevant to this project.
+2. Be specific and concrete — avoid generic advice.
+3. The **AI Instructions** section is the most important: write precise rules an AI must follow when editing this repo.
+4. Return ONLY the markdown content — no preamble, no commentary, no wrapping fences.
+5. Use actual file paths, module names, and library names from the data above.
+`;
+}
+
+// ── AI call ───────────────────────────────────────────────────────────────────
+
+/**
+ * Call the selected provider and return the generated markdown context.
+ * Both OpenAI and Groq implement the same chat completions interface.
+ *
+ * @param {OpenAI|Groq} client
+ * @param {string} prompt
+ * @param {string} model
+ * @param {'openai'|'groq'} provider
+ * @returns {Promise<string>}
+ */
+export async function generateContextWithAI(client, prompt, model, provider) {
+  const TIMEOUT_MS = 60_000; // 60 seconds
+
+  const apiCall = client.chat.completions.create({
+    model,
+    messages: [
+      {
+        role: 'system',
+        content:
+          'You are a senior software architect who specializes in analyzing codebases ' +
+          'and producing precise, AI-ready documentation. Write concise, actionable ' +
+          'context documents that help AI assistants understand and contribute to projects.',
+      },
+      {
+        role: 'user',
+        content: prompt,
+      },
+    ],
+    temperature: 0.3,
+    max_tokens: 3000,
+  });
+
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(
+      () => reject(new Error(`AI request timed out after ${TIMEOUT_MS / 1000}s. Try again or use --no-ai.`)),
+      TIMEOUT_MS
+    )
+  );
+
+  const response = await Promise.race([apiCall, timeoutPromise]);
+
+  const content = response.choices?.[0]?.message?.content;
+  if (!content) {
+    const name = PROVIDERS[provider]?.name ?? provider;
+    throw new Error(`${name} returned an empty response.`);
+  }
+  return content.trim();
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}