contextforge-cli-ai-prompt-pirates 0.4.0

package/src/core/pipeline.js

@@ -0,0 +1,256 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { loadConfig, ensureContextForgeDirs } from './config.js';
+import { getLogsDir } from './paths.js';
+import { scanRepository } from '../scanner/repo-scanner.js';
+import { loadFileIndex, saveFileIndex, updateFileIndex } from '../scanner/file-index.js';
+import { findConfigFiles } from '../scanner/config-files.js';
+import { mergePackageDependencies } from '../scanner/package-deps.js';
+import { detectTechStack } from '../detectors/tech-stack.js';
+import { analyzeArchitecture } from '../detectors/architecture.js';
+import { extractDatabaseInfo } from '../detectors/database.js';
+import { detectAuthAndDeploy } from '../detectors/auth-deploy.js';
+import { buildFolderTree } from '../analyzers/folder-tree.js';
+import { collectGitInsights } from '../analyzers/git-insights.js';
+import { analyzeDependencies } from '../analyzers/dependencies.js';
+import { analyzeCodeInsights } from '../analyzers/code-insights.js';
+import { runBugsLite } from '../analyzers/bugs-lite.js';
+import { parseSourceFilesAst } from '../analyzers/ast-parser.js';
+import { runEslintIfAvailable } from '../analyzers/eslint-runner.js';
+import { computeChangelog, computeFileDiff, loadChangesHistory } from '../analyzers/changelog.js';
+import { writeChangesMarkdown } from '../generators/changes-markdown.js';
+import { buildContextSnapshot } from '../generators/context-json.js';
+import { writeArtifacts } from '../generators/artifacts.js';
+import { renderContextMarkdown } from '../generators/context-markdown.js';
+import { loadProjectEnv } from './env.js';
+import {
+  enrichWithAI,
+  isAiAvailable,
+  scheduleBackgroundEnrichment,
+  loadCachedEnrichment,
+} from '../services/ai/index.js';
+import { computeConfidenceScores } from './confidence.js';
+import { analyzeProjectMeta } from '../analyzers/project-meta.js';
+import { assessDetectionQuality } from '../analyzers/detection-quality.js';
+import {
+  computeScanHash,
+  computeFilesSignature,
+  saveScanHash,
+  shouldSkipAi,
+} from './snapshot-hash.js';
+import { installCursorRules } from './cursor-rules.js';
+
+function log(projectRoot, message, verbose) {
+  if (verbose) {
+    console.log(`[contextforge] ${message}`);
+  }
+  const logFile = path.join(getLogsDir(projectRoot), 'contextforge.log');
+  const line = `${new Date().toISOString()} ${message}\n`;
+  fs.appendFile(logFile, line).catch(() => {});
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ verbose?: boolean, skipAi?: boolean, forceAi?: boolean }} options
+ */
+export async function runPipeline(projectRoot, options = {}) {
+  const { verbose = false, skipAi = false, forceAi = false } = options;
+  const projectRootResolved = path.resolve(projectRoot);
+
+  await loadProjectEnv(projectRootResolved);
+  await ensureContextForgeDirs(projectRootResolved);
+  const config = await loadConfig(projectRootResolved);
+
+  if (forceAi) config.ai = { ...config.ai, enabled: true };
+  if (skipAi) config.ai = { ...config.ai, enabled: false };
+
+  log(projectRootResolved, 'Scanning repository...', verbose);
+
+  const scanResult = await scanRepository(projectRootResolved, config);
+  const configFiles = await findConfigFiles(projectRootResolved, scanResult.relativePaths);
+  configFiles.mergedDependencies = await mergePackageDependencies(
+    projectRootResolved,
+    scanResult.relativePaths,
+    configFiles.packageJson
+  );
+
+  const previousIndex = await loadFileIndex(projectRootResolved);
+  const fileDiff = config.trackChanges !== false
+    ? computeFileDiff(previousIndex, scanResult.files)
+    : null;
+  const fileIndex = updateFileIndex(previousIndex, scanResult.files);
+  await saveFileIndex(projectRootResolved, fileIndex);
+
+  const techStack = detectTechStack(configFiles, scanResult.relativePaths);
+  const architecture = analyzeArchitecture(scanResult.relativePaths);
+  const database = await extractDatabaseInfo(projectRootResolved, scanResult.relativePaths);
+  const authDeploy = detectAuthAndDeploy(techStack, configFiles, scanResult.relativePaths);
+  const folderTree = buildFolderTree(scanResult.relativePaths, config.maxTreeDepth);
+
+  const ast = await parseSourceFilesAst(projectRootResolved, scanResult.relativePaths);
+
+  let git = { available: false, commits: [], insights: [] };
+  if (config.includeGitHistory) {
+    git = await collectGitInsights(projectRootResolved, config.gitCommitLimit);
+  }
+
+  const codeInsights = await analyzeCodeInsights(
+    projectRootResolved,
+    scanResult,
+    configFiles,
+    ast
+  );
+  const projectMeta = await analyzeProjectMeta(
+    projectRootResolved,
+    configFiles,
+    scanResult.relativePaths
+  );
+  const dependencies = analyzeDependencies(
+    projectRootResolved,
+    scanResult,
+    config,
+    codeInsights
+  );
+  if (!architecture.dependencyFlow && dependencies.chains?.length) {
+    architecture.dependencyFlow = dependencies.chains[0];
+  }
+  if (!architecture.apiFlow && codeInsights.pipelineFlow) {
+    architecture.apiFlow = codeInsights.pipelineFlow;
+  }
+
+  let bugs = { issues: [], summary: 'Bug detection disabled' };
+  if (config.detectBugs) {
+    bugs = await runBugsLite(projectRootResolved, scanResult, config);
+    const eslint = await runEslintIfAvailable(projectRootResolved, scanResult.relativePaths);
+    if (eslint.ran && eslint.issues.length) {
+      bugs.issues = [...eslint.issues, ...bugs.issues].slice(0, 35);
+      bugs.summary = `${bugs.summary}; ${eslint.summary}`;
+    } else if (eslint.ran) {
+      bugs.summary = eslint.summary;
+    }
+  }
+
+  let aiEnrichment = null;
+
+  const filesSignature = computeFilesSignature(scanResult.files);
+
+  const snapshot = buildContextSnapshot({
+    projectRoot: projectRootResolved,
+    config,
+    scanResult,
+    filesSignature,
+    configFiles,
+    techStack,
+    architecture,
+    database,
+    authDeploy,
+    folderTree,
+    git,
+    dependencies,
+    codeInsights,
+    bugs,
+    aiEnrichment,
+    ast,
+    changelog: null,
+    confidence: null,
+    detectionQuality: null,
+    projectMeta,
+    astFull: ast,
+  });
+
+  snapshot.changelog = await computeChangelog(
+    projectRootResolved,
+    snapshot,
+    fileDiff
+  );
+  snapshot.confidence = computeConfidenceScores(snapshot);
+  snapshot.detectionQuality = assessDetectionQuality(snapshot);
+
+  snapshot.filesSignature = filesSignature;
+
+  const scanHash = computeScanHash(snapshot, fileDiff);
+  const skipAiRun = await shouldSkipAi(
+    projectRootResolved,
+    snapshot,
+    forceAi,
+    fileDiff
+  );
+
+  const cachedAi = await loadCachedEnrichment(projectRootResolved);
+  if (cachedAi && !forceAi && skipAiRun) {
+    aiEnrichment = cachedAi;
+    snapshot.aiEnrichment = cachedAi;
+    log(projectRootResolved, 'Using cached AI enrichment (scan unchanged)', verbose);
+  }
+
+  const aiReady = config.ai?.enabled && isAiAvailable(config);
+
+  if (aiReady && config.ai.enrichContext && !config.ai.background && !skipAi && !skipAiRun) {
+    log(projectRootResolved, `AI enrichment (${config.ai.provider})...`, verbose);
+    try {
+      aiEnrichment = await enrichWithAI(snapshot, config);
+      snapshot.aiEnrichment = aiEnrichment;
+      await saveScanHash(projectRootResolved, scanHash);
+      console.log(`  AI enriched via ${aiEnrichment.provider} (${aiEnrichment.model})`);
+    } catch (err) {
+      console.warn(`  AI enrichment skipped: ${err.message}`);
+    }
+  } else if (skipAiRun && aiReady) {
+    console.log('  AI skipped — repository scan unchanged since last run');
+  }
+
+  await writeArtifacts(projectRootResolved, snapshot);
+  await renderContextMarkdown(projectRootResolved, snapshot);
+
+  if (config.installCursorRules !== false) {
+    const { rulePaths } = await installCursorRules(projectRootResolved, snapshot);
+    log(
+      projectRootResolved,
+      `Synced ${rulePaths.length} Cursor rule(s) in .cursor/rules/`,
+      verbose
+    );
+  }
+
+  if (config.trackChanges !== false) {
+    const history = await loadChangesHistory(projectRootResolved, 15);
+    await writeChangesMarkdown(projectRootResolved, snapshot.changelog, history);
+  }
+
+  await saveScanHash(projectRootResolved, scanHash);
+
+  log(projectRootResolved, `Generated ${path.join('.contextforge', 'context.md')}`, true);
+  console.log('Context generated successfully.');
+  console.log(`  → .contextforge/context.md`);
+  if (fileDiff?.hasFileChanges) {
+    const parts = [];
+    if (fileDiff.added.length) parts.push(`+${fileDiff.added.length} new`);
+    if (fileDiff.modified.length) parts.push(`~${fileDiff.modified.length} modified`);
+    if (fileDiff.removed.length) parts.push(`-${fileDiff.removed.length} removed`);
+    console.log(`  File/code changes detected — context updated (${parts.join(', ')})`);
+    if (fileDiff.modified.length && verbose) {
+      console.log(`  Modified: ${fileDiff.modified.slice(0, 5).join(', ')}${fileDiff.modified.length > 5 ? '...' : ''}`);
+    }
+  } else if (config.trackChanges !== false && snapshot.changelog?.hasPrevious) {
+    console.log('  No file/code changes — context refreshed (metadata only).');
+  }
+  if (config.trackChanges !== false) {
+    console.log(`  → .contextforge/CHANGES.md`);
+    if (snapshot.changelog?.hasChanges) {
+      console.log(`  Changes: ${snapshot.changelog.summary}`);
+    } else if (snapshot.changelog?.hasPrevious) {
+      console.log('  Summary: no structural changes since last run.');
+    }
+  }
+  console.log(`  Overall confidence: ${snapshot.confidence?.overall || 'medium'}`);
+
+  if (aiReady && config.ai.enrichContext && config.ai.background && !skipAi && !skipAiRun) {
+    scheduleBackgroundEnrichment(projectRootResolved, { ...snapshot }, config, scanHash);
+    console.log('  AI enrichment queued in background (context.md will update when ready)');
+  } else if (aiReady && skipAiRun && config.ai.background && !fileDiff?.hasFileChanges) {
+    console.log('  Background AI skipped — no file/code changes since last run');
+  } else if (config.ai?.enabled && !isAiAvailable(config)) {
+    console.log('  Tip: Set OPENAI_API_KEY or GROQ_API_KEY in .env to enable AI enrichment');
+  }
+
+  return snapshot;
+}

package/src/core/postinstall.js

@@ -0,0 +1,168 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'node:url';
+import { ensureInitialized } from './ensure-setup.js';
+import { loadConfig, syncConfigFile } from './config.js';
+import { runPipeline } from './pipeline.js';
+import { getPidPath, getLogsDir } from './paths.js';
+import {
+  loadProjectEnv,
+  isAutoStartEnabledViaEnv,
+  isPostinstallGenerateEnabledViaEnv,
+  isPostinstallWatchEnabledViaEnv,
+  isAiEnabledViaEnv,
+  hasAnyAiKey,
+} from './env.js';
+import { ensureEnvFromExample } from './setup-env.js';
+import { isAiAvailable } from '../services/ai/index.js';
+import { startWatcher } from '../watcher/watcher.js';
+import { getOwnPackageName, hasContextForgeDependency } from './package-meta.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKER_SCRIPT = path.join(__dirname, '../../bin/postinstall-worker.js');
+
+/**
+ * Project root where the user ran `npm install` (not node_modules/contextforge).
+ */
+export function resolveInstallProjectRoot() {
+  return path.resolve(process.env.INIT_CWD || process.cwd());
+}
+
+/**
+ * @param {string} projectRoot
+ */
+export async function shouldRunPostinstall(projectRoot) {
+  await loadProjectEnv(projectRoot);
+
+  if (!isAutoStartEnabledViaEnv()) {
+    return false;
+  }
+  if (process.env.CONTEXTFORGE_POSTINSTALL_WORKER === '1') {
+    return false;
+  }
+  if (process.env.npm_command === 'publish' || process.env.npm_command === 'pack') {
+    return false;
+  }
+  if (isCi() && process.env.CONTEXTFORGE_RUN_IN_CI !== '1') {
+    return false;
+  }
+
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!(await fs.pathExists(pkgPath))) {
+    return false;
+  }
+
+  const pkg = await fs.readJson(pkgPath);
+  if (pkg.contextforge?.postinstall === false) {
+    return false;
+  }
+
+  const ownName = await getOwnPackageName();
+
+  // npm lifecycle: npm_package_name matches this package when postinstall runs
+  if (process.env.npm_package_name === ownName) {
+    return true;
+  }
+
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.optionalDependencies,
+  };
+
+  return hasContextForgeDependency(deps, pkg.name, ownName);
+}
+
+function isCi() {
+  return (
+    process.env.CI === 'true' ||
+    process.env.CI === '1' ||
+    process.env.GITHUB_ACTIONS === 'true'
+  );
+}
+
+/**
+ * Fire-and-forget worker so `npm install` is not blocked.
+ * @param {string} projectRoot
+ */
+export function spawnPostinstallWorker(projectRoot) {
+  const child = spawn(process.execPath, [WORKER_SCRIPT, projectRoot], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      CONTEXTFORGE_POSTINSTALL_WORKER: '1',
+    },
+    windowsHide: true,
+  });
+  child.unref();
+}
+
+async function logPostinstall(projectRoot, message) {
+  const logDir = getLogsDir(projectRoot);
+  await fs.ensureDir(logDir);
+  const line = `${new Date().toISOString()} ${message}\n`;
+  await fs.appendFile(path.join(logDir, 'postinstall.log'), line).catch(() => {});
+}
+
+/**
+ * Setup + generate + optional background watch (runs in detached worker).
+ * @param {string} projectRoot
+ */
+export async function runPostinstall(projectRoot) {
+  const root = path.resolve(projectRoot);
+  await loadProjectEnv(root);
+  await logPostinstall(root, 'postinstall worker started');
+
+  try {
+    const createdEnv = await ensureEnvFromExample(root);
+    if (createdEnv) {
+      await logPostinstall(root, 'created .env from .env.example — add API keys for AI');
+      await loadProjectEnv(root);
+    }
+
+    await ensureInitialized(root, { quiet: true });
+    await syncConfigFile(root, { upgrade: true });
+    const config = await loadConfig(root);
+
+    const runGenerate =
+      config.postinstallGenerate !== false &&
+      config.autoGenerate !== false &&
+      isPostinstallGenerateEnabledViaEnv();
+
+    if (runGenerate) {
+      const envAi = isAiEnabledViaEnv();
+      const useAi =
+        envAi !== false &&
+        config.ai?.enabled !== false &&
+        config.ai?.enrichContext !== false &&
+        hasAnyAiKey() &&
+        isAiAvailable(config);
+      await logPostinstall(root, `running generate (ai=${useAi})`);
+      await runPipeline(root, { verbose: false, skipAi: !useAi });
+      await logPostinstall(root, 'generate complete');
+    }
+
+    const startWatch =
+      config.postinstallWatch !== false &&
+      config.watch !== false &&
+      config.autoGenerate !== false &&
+      isPostinstallWatchEnabledViaEnv();
+
+    if (startWatch) {
+      const pidPath = getPidPath(root);
+      if (await fs.pathExists(pidPath)) {
+        await logPostinstall(root, 'watch already running (pid file exists)');
+        return;
+      }
+      await logPostinstall(root, 'starting watch --daemon');
+      await startWatcher(root, { daemon: true, verbose: false });
+    }
+  } catch (err) {
+    await logPostinstall(root, `failed: ${err.message}`);
+    console.error('[contextforge] postinstall:', err.message);
+    process.exitCode = 1;
+  }
+}

package/src/core/setup-env.js

@@ -0,0 +1,86 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+
+const ENV_EXAMPLE_CONTENT = `# ContextForge — auto-created on npm install
+
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4o-mini
+
+GROQ_API_KEY=
+GROQ_MODEL=llama-3.3-70b-versatile
+
+CONTEXTFORGE_AI_PROVIDER=openai
+CONTEXTFORGE_AI_ENABLED=true
+
+CONTEXTFORGE_AUTO_START=true
+CONTEXTFORGE_POSTINSTALL_GENERATE=true
+CONTEXTFORGE_POSTINSTALL_WATCH=true
+
+CONTEXTFORGE_REFRESH_INTERVAL_MINUTES=15
+`;
+
+/**
+ * Ensure .env.example exists in the target project.
+ * @param {string} projectRoot
+ */
+export async function ensureEnvExample(projectRoot) {
+  const target = path.join(projectRoot, '.env.example');
+  const packageExample = path.join(PACKAGE_ROOT, '.env.example');
+
+  if (await fs.pathExists(target)) return;
+
+  if (await fs.pathExists(packageExample)) {
+    await fs.copy(packageExample, target);
+  } else {
+    await fs.writeFile(target, ENV_EXAMPLE_CONTENT, 'utf8');
+  }
+}
+
+/**
+ * Create .env from .env.example if .env does not exist.
+ * @param {string} projectRoot
+ * @returns {Promise<boolean>} true if .env was created
+ */
+export async function ensureEnvFromExample(projectRoot) {
+  const envPath = path.join(projectRoot, '.env');
+  const examplePath = path.join(projectRoot, '.env.example');
+
+  if (await fs.pathExists(envPath)) return false;
+
+  await ensureEnvExample(projectRoot);
+
+  if (await fs.pathExists(examplePath)) {
+    await fs.copy(examplePath, envPath);
+    return true;
+  }
+
+  await fs.writeFile(envPath, ENV_EXAMPLE_CONTENT, 'utf8');
+  return true;
+}
+
+/**
+ * Validate .env has at least placeholder structure (warn if keys empty when AI on).
+ * @param {string} projectRoot
+ */
+export async function validateEnvSetup(projectRoot) {
+  const envPath = path.join(projectRoot, '.env');
+  const issues = [];
+
+  if (!(await fs.pathExists(envPath))) {
+    return { ok: false, issues: ['.env file missing — run: copy .env.example .env'] };
+  }
+
+  const content = await fs.readFile(envPath, 'utf8');
+  const hasOpenAI = /^OPENAI_API_KEY=.+/m.test(content) && !/your-|sk-your/i.test(content);
+  const hasGroq = /^GROQ_API_KEY=.+/m.test(content) && !/your-|gsk_your/i.test(content);
+
+  if (!hasOpenAI && !hasGroq) {
+    issues.push('Add OPENAI_API_KEY and/or GROQ_API_KEY to .env for AI enrichment');
+  }
+
+  return { ok: issues.length === 0, issues, hasOpenAI, hasGroq };
+}

package/src/core/setup-prompts.js

@@ -0,0 +1,31 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { getContextForgeRoot } from './paths.js';
+import { PACKAGE_PROMPTS, PROMPT_FILES } from '../services/ai/prompt-loader.js';
+
+/**
+ * Copy default prompts to .contextforge/prompts/ (skip existing files).
+ * @param {string} projectRoot
+ */
+export async function ensureProjectPrompts(projectRoot) {
+  const targetDir = path.join(getContextForgeRoot(projectRoot), 'prompts');
+  await fs.ensureDir(targetDir);
+
+  let copied = 0;
+  for (const file of Object.values(PROMPT_FILES)) {
+    const dest = path.join(targetDir, file);
+    const src = path.join(PACKAGE_PROMPTS, file);
+    if (!(await fs.pathExists(dest)) && (await fs.pathExists(src))) {
+      await fs.copy(src, dest);
+      copied++;
+    }
+  }
+
+  const readmeSrc = path.join(PACKAGE_PROMPTS, 'README.md');
+  const readmeDest = path.join(targetDir, 'README.md');
+  if (!(await fs.pathExists(readmeDest)) && (await fs.pathExists(readmeSrc))) {
+    await fs.copy(readmeSrc, readmeDest);
+  }
+
+  return { targetDir, copied };
+}

package/src/core/snapshot-hash.js

@@ -0,0 +1,70 @@
+import crypto from 'node:crypto';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { getCacheDir } from './paths.js';
+
+function hashPayload(obj) {
+  return crypto.createHash('sha256').update(JSON.stringify(obj)).digest('hex');
+}
+
+/**
+ * Fingerprint of all scanned file contents — detects code edits.
+ */
+export function computeFilesSignature(files = []) {
+  const parts = files
+    .filter((f) => f.hash && f.hash !== 'skipped-large' && f.hash !== 'unreadable')
+    .map((f) => `${f.relativePath}:${f.hash}`)
+    .sort();
+  return hashPayload(parts);
+}
+
+/**
+ * Stable hash of scan data — skip AI if unchanged.
+ * @param {object} snapshot
+ * @param {{ added?: string[], modified?: string[], removed?: string[] } | null} fileDiff
+ */
+export function computeScanHash(snapshot, fileDiff = null) {
+  const payload = {
+    projectName: snapshot.projectName,
+    techStack: snapshot.techStack,
+    architecture: {
+      primary: snapshot.architecture?.primary?.pattern,
+      apiFlow: snapshot.architecture?.apiFlow,
+    },
+    database: snapshot.database?.models?.map((m) => m.name),
+    filesScanned: snapshot.filesScanned,
+    filesSignature: snapshot.filesSignature,
+    codeSummary: snapshot.codeInsights?.summary,
+    astRouteCount: snapshot.ast?.routes?.length,
+    bugCount: snapshot.bugs?.issues?.length,
+    gitHead: snapshot.git?.commits?.[0]?.hash,
+    fileDiff: fileDiff
+      ? {
+          added: fileDiff.added?.length || 0,
+          modified: fileDiff.modified?.length || 0,
+          removed: fileDiff.removed?.length || 0,
+        }
+      : null,
+  };
+  return hashPayload(payload);
+}
+
+export async function loadScanHash(projectRoot) {
+  const p = path.join(getCacheDir(projectRoot), 'scan-hash.txt');
+  if (await fs.pathExists(p)) {
+    return (await fs.readFile(p, 'utf8')).trim();
+  }
+  return null;
+}
+
+export async function saveScanHash(projectRoot, hash) {
+  await fs.writeFile(path.join(getCacheDir(projectRoot), 'scan-hash.txt'), hash, 'utf8');
+}
+
+export async function shouldSkipAi(projectRoot, snapshot, forceAi, fileDiff = null) {
+  if (forceAi) return false;
+  if (fileDiff?.hasFileChanges) return false;
+  const current = computeScanHash(snapshot, fileDiff);
+  const previous = await loadScanHash(projectRoot);
+  return previous === current;
+}