contextforge-cli-ai-prompt-pirates 0.4.0

package/src/cli/commands/doctor.js

@@ -0,0 +1,152 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { loadConfig, isInitialized } from '../../core/config.js';
+import {
+  loadProjectEnv,
+  hasAnyAiKey,
+  isAutoStartEnabledViaEnv,
+  isPostinstallWatchEnabledViaEnv,
+} from '../../core/env.js';
+import { getPidPath } from '../../core/paths.js';
+import { validateEnvSetup } from '../../core/setup-env.js';
+import { isAiAvailable } from '../../services/ai/index.js';
+import { getContextForgeRoot, getOutputPath, OUTPUT_FILES } from '../../core/paths.js';
+
+export async function doctorCommand(projectRoot) {
+  const root = path.resolve(projectRoot);
+  await loadProjectEnv(root);
+
+  const checks = [];
+  let ok = true;
+
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+  if (nodeMajor >= 18) {
+    checks.push({ name: 'Node.js', status: 'ok', detail: nodeVersion });
+  } else {
+    checks.push({ name: 'Node.js', status: 'fail', detail: `${nodeVersion} — need >= 18` });
+    ok = false;
+  }
+
+  if (await isInitialized(root)) {
+    checks.push({ name: 'ContextForge init', status: 'ok', detail: getContextForgeRoot(root) });
+  } else {
+    checks.push({ name: 'ContextForge init', status: 'fail', detail: 'Run: npx contextforge init' });
+    ok = false;
+  }
+
+  const contextMd = getOutputPath(root, OUTPUT_FILES.contextMd);
+  if (await fs.pathExists(contextMd)) {
+    const stat = await fs.stat(contextMd);
+    checks.push({
+      name: 'context.md',
+      status: 'ok',
+      detail: `Exists (${Math.round(stat.size / 1024)} KB, ${stat.mtime.toISOString().slice(0, 10)})`,
+    });
+  } else {
+    checks.push({ name: 'context.md', status: 'warn', detail: 'Run: npx contextforge generate' });
+  }
+
+  try {
+    await fs.access(root, fs.constants.W_OK);
+    checks.push({ name: 'Write permission', status: 'ok', detail: root });
+  } catch {
+    checks.push({ name: 'Write permission', status: 'fail', detail: 'Cannot write to project root' });
+    ok = false;
+  }
+
+  const envCheck = await validateEnvSetup(root);
+  if (await fs.pathExists(path.join(root, '.env'))) {
+    checks.push({
+      name: '.env file',
+      status: 'ok',
+      detail: hasAnyAiKey() ? 'API key(s) present' : 'No API keys set (AI disabled)',
+    });
+  } else {
+    checks.push({
+      name: '.env file',
+      status: 'warn',
+      detail: 'Copy .env.example to .env for AI enrichment',
+    });
+  }
+
+  if (envCheck.hasOpenAI) checks.push({ name: 'OpenAI key', status: 'ok', detail: 'Configured' });
+  if (envCheck.hasGroq) checks.push({ name: 'Groq key', status: 'ok', detail: 'Configured' });
+
+  try {
+    const { default: simpleGit } = await import('simple-git');
+    const git = simpleGit(root);
+    if (await git.checkIsRepo()) {
+      checks.push({ name: 'Git', status: 'ok', detail: `Branch: ${(await git.branch()).current}` });
+    } else {
+      checks.push({ name: 'Git', status: 'warn', detail: 'Not a git repo — history skipped' });
+    }
+  } catch {
+    checks.push({
+      name: 'Git',
+      status: 'warn',
+      detail: 'Git not in PATH — install Git for commit insights',
+    });
+  }
+
+  const config = await loadConfig(root);
+  if (config.ai?.enabled) {
+    if (isAiAvailable(config)) {
+      checks.push({
+        name: 'AI enrichment',
+        status: 'ok',
+        detail: `Provider: ${config.ai.provider}, model: ${config.ai.openai?.model || config.ai.groq?.model}`,
+      });
+    } else {
+      checks.push({
+        name: 'AI enrichment',
+        status: 'fail',
+        detail: 'Enabled in config but no valid API keys',
+      });
+      ok = false;
+    }
+  } else {
+    checks.push({ name: 'AI enrichment', status: 'ok', detail: 'Disabled (enable in config + .env)' });
+  }
+
+  if (isAutoStartEnabledViaEnv()) {
+    const pidPath = getPidPath(root);
+    const watcherRunning = await fs.pathExists(pidPath);
+    checks.push({
+      name: 'npm install auto-start',
+      status: 'ok',
+      detail: watcherRunning
+        ? 'Enabled — background watch is running'
+        : 'Enabled — runs on next npm install (or npm run watch)',
+    });
+  } else {
+    checks.push({
+      name: 'npm install auto-start',
+      status: 'ok',
+      detail: 'Disabled (CONTEXTFORGE_AUTO_START=false or SKIP_POSTINSTALL=1)',
+    });
+  }
+
+  const intervalMin = config.refreshIntervalMinutes ?? 0;
+  if (intervalMin > 0 && isPostinstallWatchEnabledViaEnv()) {
+    checks.push({
+      name: 'Watch auto-refresh',
+      status: 'ok',
+      detail: `Every ${intervalMin} minute(s) (from .env or config)`,
+    });
+  } else {
+    checks.push({
+      name: 'Watch auto-refresh',
+      status: 'ok',
+      detail: 'Off — set CONTEXTFORGE_REFRESH_INTERVAL_MINUTES in .env or watch --interval',
+    });
+  }
+
+  console.log('\nContextForge Doctor\n');
+  for (const c of checks) {
+    const icon = c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗';
+    console.log(`  ${icon} ${c.name}: ${c.detail}`);
+  }
+  console.log(ok ? '\nAll critical checks passed.\n' : '\nSome checks failed — fix above issues.\n');
+  if (!ok) process.exit(1);
+}

package/src/cli/commands/generate.js

@@ -0,0 +1,7 @@
+import { ensureInitialized } from '../../core/ensure-setup.js';
+import { runPipeline } from '../../core/pipeline.js';
+
+export async function generateCommand(projectRoot, options = {}) {
+  await ensureInitialized(projectRoot, { enableAi: options.forceAi });
+  await runPipeline(projectRoot, options);
+}

package/src/cli/commands/init.js

@@ -0,0 +1,98 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import {
+  writeDefaultConfig,
+  isInitialized,
+  loadConfig,
+  syncConfigFile,
+} from '../../core/config.js';
+import { runPipeline } from '../../core/pipeline.js';
+import { getContextForgeRoot } from '../../core/paths.js';
+import { ensureEnvExample, ensureEnvFromExample, validateEnvSetup } from '../../core/setup-env.js';
+import { isAiAvailable } from '../../services/ai/index.js';
+import { loadProjectEnv } from '../../core/env.js';
+import { ensureProjectPrompts } from '../../core/setup-prompts.js';
+
+export async function initCommand(projectRoot, options = {}) {
+  const initialized = await isInitialized(projectRoot);
+
+  if (initialized && !options.force) {
+    console.log('ContextForge already initialized.');
+    console.log(`  → ${getContextForgeRoot(projectRoot)}`);
+    console.log('Run: npx contextforge generate');
+    return;
+  }
+
+  const initOptions = {};
+  if (options.enableAi) {
+    initOptions.ai = { enabled: true, enrichContext: true, background: true };
+  }
+
+  await writeDefaultConfig(projectRoot, initOptions);
+  const cfgWritten = await syncConfigFile(projectRoot, {
+    enableAi: options.enableAi,
+    upgrade: options.force || !initialized,
+  });
+  const { targetDir: promptsDir, copied: promptsCopied } =
+    await ensureProjectPrompts(projectRoot);
+  await ensureEnvExample(projectRoot);
+  const createdEnv = await ensureEnvFromExample(projectRoot);
+
+  console.log('Initialized ContextForge.');
+  console.log(`  → ${getContextForgeRoot(projectRoot)}/config.json`);
+  console.log(`  → ${promptsDir}/ (${promptsCopied} prompt file(s) copied — edit to customize AI)`);
+  if (createdEnv) {
+    console.log('  → .env created from .env.example — add your API keys');
+  } else {
+    console.log('  → Copy .env.example to .env and set OPENAI_API_KEY / GROQ_API_KEY');
+  }
+
+  await loadProjectEnv(projectRoot);
+  await runPipeline(projectRoot, {
+    verbose: options.verbose,
+    forceAi: options.enableAi,
+  });
+
+  const cfg = await loadConfig(projectRoot);
+
+  if (cfg.installCursorRules !== false) {
+    console.log('  → Cursor rule: .cursor/rules/contextforge.mdc');
+  }
+  if (cfg.watch && cfg.autoGenerate) {
+    console.log('\nWatch mode: `npx contextforge watch`');
+    console.log('  • Updates when you save files (content hash detection)');
+    if (cfg.refreshIntervalMinutes > 0) {
+      console.log(
+        `  • Auto-refresh every ${cfg.refreshIntervalMinutes} min (from .env or config)`
+      );
+    } else {
+      console.log('  • Timer: set CONTEXTFORGE_REFRESH_INTERVAL_MINUTES in .env (e.g. 15)');
+    }
+    console.log('  • Change log: `npx contextforge changes` → .contextforge/CHANGES.md');
+    console.log('  • Daemon: `watch --daemon` then `npx contextforge stop`');
+  }
+
+  const envCheck = await validateEnvSetup(projectRoot);
+  if (cfg.ai?.enabled) {
+    if (isAiAvailable(cfg)) {
+      console.log('\nAI: enabled — OpenAI/Groq will enrich context.md (background if configured)');
+      if (envCheck.hasOpenAI) console.log('  → OpenAI key loaded');
+      if (envCheck.hasGroq) console.log('  → Groq key loaded');
+    } else {
+      console.log('\nAI: enabled in config but API keys missing in .env');
+      envCheck.issues.forEach((i) => console.log(`  → ${i}`));
+    }
+  } else if (options.enableAi) {
+    envCheck.issues.forEach((i) => console.log(`  → ${i}`));
+  }
+
+  const gitignore = projectRoot + '/.gitignore';
+  if (await fs.pathExists(gitignore)) {
+    const content = await fs.readFile(gitignore, 'utf8');
+    if (!content.includes('.contextforge/cache')) {
+      console.log('\nTip: Add to .gitignore:');
+      console.log('  .contextforge/cache/');
+      console.log('  .contextforge/logs/');
+    }
+  }
+}

package/src/cli/commands/prompt.js

@@ -0,0 +1,53 @@
+import fs from 'fs-extra';
+import { getOutputPath, OUTPUT_FILES } from '../../core/paths.js';
+
+export async function promptCommand(projectRoot, options = {}) {
+  const mdPath = getOutputPath(projectRoot, OUTPUT_FILES.contextMd);
+  const jsonPath = getOutputPath(projectRoot, OUTPUT_FILES.contextJson);
+
+  if (!(await fs.pathExists(mdPath))) {
+    console.error('No context found. Run: npx contextforge init');
+    process.exit(1);
+  }
+
+  const sections = (options.sections || 'all').split(',').map((s) => s.trim().toLowerCase());
+  const useAll = sections.includes('all');
+
+  if (useAll) {
+    const md = await fs.readFile(mdPath, 'utf8');
+    console.log('--- ContextForge AI Context ---\n');
+    console.log(md);
+    console.log('\n--- End Context ---');
+    return;
+  }
+
+  const snapshot = await fs.readJson(jsonPath);
+  const parts = [];
+
+  if (sections.includes('stack')) {
+    const ts = snapshot.techStack;
+    parts.push(
+      `Tech: Frontend[${ts.frontend.join(', ')}] Backend[${ts.backend.join(', ')}] DB[${ts.database.join(', ')}]`
+    );
+  }
+  if (sections.includes('arch')) {
+    parts.push(`Architecture: ${snapshot.architecture?.primary?.displayLabel}`);
+    if (snapshot.architecture?.apiFlow) parts.push(`API Flow: ${snapshot.architecture.apiFlow}`);
+  }
+  if (sections.includes('git') && snapshot.git?.commits?.length) {
+    parts.push('Recent commits:');
+    snapshot.git.commits.slice(0, 5).forEach((c) => {
+      parts.push(`  ${c.hash} ${c.message.slice(0, 50)}`);
+    });
+  }
+  if (sections.includes('bugs') && snapshot.bugs?.issues?.length) {
+    parts.push('Issues:');
+    snapshot.bugs.issues.slice(0, 5).forEach((i) => {
+      parts.push(`  [${i.severity}] ${i.message}`);
+    });
+  }
+
+  console.log('--- ContextForge AI Context ---\n');
+  console.log(parts.join('\n'));
+  console.log('\n--- End Context ---');
+}

package/src/cli/commands/stop.js

@@ -0,0 +1,10 @@
+import { stopWatcher } from '../../watcher/watcher.js';
+
+export async function stopCommand(projectRoot) {
+  try {
+    await stopWatcher(projectRoot);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/src/cli/commands/summary.js

@@ -0,0 +1,22 @@
+import fs from 'fs-extra';
+import { getOutputPath, OUTPUT_FILES } from '../../core/paths.js';
+
+export async function summaryCommand(projectRoot) {
+  const jsonPath = getOutputPath(projectRoot, OUTPUT_FILES.contextJson);
+
+  if (!(await fs.pathExists(jsonPath))) {
+    console.error('No context found. Run: npx contextforge init');
+    process.exit(1);
+  }
+
+  const snapshot = await fs.readJson(jsonPath);
+  const ts = snapshot.techStack;
+
+  console.log(`\n${snapshot.projectName || 'Project'} — ContextForge Summary\n`);
+  console.log(`Generated: ${snapshot.generatedAt}`);
+  console.log(`Files scanned: ${snapshot.filesScanned}`);
+  console.log(`\nStack: ${[...ts.frontend, ...ts.backend].join(', ') || 'unknown'}`);
+  console.log(`Architecture: ${snapshot.architecture?.primary?.displayLabel || 'unknown'}`);
+  console.log(`Database: ${[...ts.database, ...ts.orm].join(', ') || 'none detected'}`);
+  console.log(`\nFull context: .contextforge/context.md\n`);
+}

package/src/cli/commands/watch.js

@@ -0,0 +1,9 @@
+import { ensureInitialized } from '../../core/ensure-setup.js';
+import { runPipeline } from '../../core/pipeline.js';
+import { startWatcher } from '../../watcher/watcher.js';
+
+export async function watchCommand(projectRoot, options = {}) {
+  await ensureInitialized(projectRoot);
+  await runPipeline(projectRoot, { verbose: options.verbose });
+  await startWatcher(projectRoot, options);
+}

package/src/cli/index.js

@@ -0,0 +1,120 @@
+import { Command } from 'commander';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { initCommand } from './commands/init.js';
+import { generateCommand } from './commands/generate.js';
+import { watchCommand } from './commands/watch.js';
+import { summaryCommand } from './commands/summary.js';
+import { promptCommand } from './commands/prompt.js';
+import { stopCommand } from './commands/stop.js';
+import { doctorCommand } from './commands/doctor.js';
+import { changesCommand } from './commands/changes.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function resolveCwd(cwd) {
+  return path.resolve(cwd || process.cwd());
+}
+
+export async function runCli(argv) {
+  const program = new Command();
+
+  program
+    .name('contextforge-cli-ai-prompt-pirates')
+    .description('AI-ready repository context generator')
+    .version('0.4.0')
+    .option('-c, --cwd <path>', 'Project root directory', process.cwd())
+    .option('-v, --verbose', 'Verbose logging');
+
+  program
+    .command('init')
+    .description('Initialize .contextforge and generate initial context')
+    .option('-f, --force', 'Re-run setup even if already initialized')
+    .option('--ai', 'Enable AI enrichment in config')
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await initCommand(resolveCwd(globalOpts.cwd), {
+        force: opts.force,
+        verbose: globalOpts.verbose,
+        enableAi: opts.ai,
+      });
+    });
+
+  program
+    .command('generate')
+    .description('Scan repository and regenerate context')
+    .option('--ai', 'Force enable AI enrichment (OpenAI/Groq)')
+    .option('--no-ai', 'Skip AI enrichment for this run')
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await generateCommand(resolveCwd(globalOpts.cwd), {
+        verbose: globalOpts.verbose,
+        forceAi: opts.ai,
+        skipAi: opts.noAi,
+      });
+    });
+
+  program
+    .command('watch')
+    .description('Watch files + optional timed refresh of context.md')
+    .option('--daemon', 'Write PID file for contextforge stop')
+    .option(
+      '-i, --interval <minutes>',
+      'Also regenerate every N minutes (e.g. 5, 15, 30)'
+    )
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      const interval = opts.interval ? parseFloat(opts.interval) : undefined;
+      await watchCommand(resolveCwd(globalOpts.cwd), {
+        verbose: globalOpts.verbose,
+        daemon: opts.daemon,
+        intervalMinutes: interval,
+      });
+    });
+
+  program
+    .command('changes')
+    .description('Show history of what changed between runs')
+    .option('-n, --limit <number>', 'Number of runs to show', '10')
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await changesCommand(resolveCwd(globalOpts.cwd), {
+        limit: parseInt(opts.limit, 10),
+      });
+    });
+
+  program
+    .command('stop')
+    .description('Stop background watcher started with watch --daemon')
+    .action(async (_opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await stopCommand(resolveCwd(globalOpts.cwd));
+    });
+
+  program
+    .command('doctor')
+    .description('Health check: Node, Git, .env, AI keys, context.md')
+    .action(async (_opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await doctorCommand(resolveCwd(globalOpts.cwd));
+    });
+
+  program
+    .command('summary')
+    .description('Print short project summary to stdout')
+    .action(async (_opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await summaryCommand(resolveCwd(globalOpts.cwd));
+    });
+
+  program
+    .command('prompt')
+    .description('Export AI-ready context block to stdout')
+    .option('-s, --sections <list>', 'Comma-separated sections: stack,arch,git,bugs,all', 'all')
+    .action(async (opts, cmd) => {
+      const globalOpts = cmd.parent?.opts?.() || {};
+      await promptCommand(resolveCwd(globalOpts.cwd), { sections: opts.sections });
+    });
+
+  await program.parseAsync(argv);
+}

package/src/core/confidence.js

@@ -0,0 +1,51 @@
+/**
+ * Per-section confidence for context.md accuracy labels.
+ * @param {object} snapshot
+ */
+export function computeConfidenceScores(snapshot) {
+  const ts = snapshot.techStack || {};
+  const scores = {};
+
+  scores.techStack =
+    ts.signals?.length >= 3 ? 'high' : ts.signals?.length >= 1 ? 'medium' : 'low';
+
+  scores.architecture = snapshot.architecture?.primary?.confidence || 'low';
+
+  scores.database =
+    snapshot.database?.models?.length > 0
+      ? 'high'
+      : snapshot.database?.orm
+        ? 'medium'
+        : 'low';
+
+  scores.git = snapshot.git?.available && snapshot.git?.commits?.length ? 'high' : 'low';
+
+  scores.apiRoutes =
+    snapshot.codeInsights?.apiEndpoints?.length > 0 ||
+    snapshot.ast?.routes?.length > 0
+      ? 'high'
+      : 'low';
+
+  scores.bugs =
+    snapshot.bugs?.issues?.some((i) => i.type === 'eslint')
+      ? 'high'
+      : snapshot.bugs?.issues?.length
+        ? 'medium'
+        : 'low';
+
+  scores.overall = aggregateOverall(scores);
+
+  return scores;
+}
+
+function aggregateOverall(scores) {
+  const vals = Object.values(scores).filter((v) => v !== scores.overall);
+  if (vals.every((v) => v === 'high')) return 'high';
+  if (vals.some((v) => v === 'low') && !vals.some((v) => v === 'high')) return 'low';
+  return 'medium';
+}
+
+export function confidenceBadge(level) {
+  const map = { high: '🟢 High', medium: '🟡 Medium', low: '🔴 Low' };
+  return map[level] || level;
+}