contextforge-cli-ai-prompt-pirates 0.4.0

package/src/core/config.js

@@ -0,0 +1,183 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { getConfigPath, getContextForgeRoot } from './paths.js';
+import { DEFAULT_AI_CONFIG } from '../services/ai/config.js';
+import {
+  loadProjectEnv,
+  getRefreshIntervalMinutesFromEnv,
+  getDebounceMsFromEnv,
+  isAiEnabledViaEnv,
+  hasAnyAiKey,
+} from './env.js';
+import { resolveAiConfig } from '../services/ai/config.js';
+
+export const DEFAULT_CONFIG = {
+  ignore: [
+    'node_modules',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    '.git',
+    'test/fixtures',
+    'test/tmp-mini-express',
+    '.contextforge/cache',
+    '.contextforge/logs',
+    '.contextforge/embeddings',
+  ],
+  watch: true,
+  autoGenerate: true,
+  includeGitHistory: true,
+  detectBugs: true,
+  debounceMs: 2000,
+  /** Auto-refresh context.md every N minutes during `watch` (0 = file changes only) */
+  refreshIntervalMinutes: 0,
+  /** Track and log file/stack changes between runs */
+  trackChanges: true,
+  maxTreeDepth: 4,
+  gitCommitLimit: 20,
+  maxFileSizeBytes: 524288,
+  installCursorRules: true,
+  /** Run generate after npm install (postinstall hook) */
+  postinstallGenerate: true,
+  /** Start `watch --daemon` in background after npm install */
+  postinstallWatch: true,
+  ai: { ...DEFAULT_AI_CONFIG },
+};
+
+/** Paths never read for content analysis */
+export const SENSITIVE_PATTERNS = [
+  /^\.env(\.|$)/,
+  /\.pem$/i,
+  /credentials/i,
+  /id_rsa/i,
+  /\.key$/i,
+  /secrets?\./i,
+];
+
+export function isSensitivePath(relativePath) {
+  const base = path.basename(relativePath);
+  return SENSITIVE_PATTERNS.some((re) => re.test(base) || re.test(relativePath));
+}
+
+/** Merge saved config with package defaults (adds new fields on upgrade). */
+export function mergeConfigWithDefaults(userConfig = {}) {
+  const merged = { ...DEFAULT_CONFIG, ...userConfig };
+  if (userConfig.ignore) {
+    merged.ignore = [...new Set([...DEFAULT_CONFIG.ignore, ...userConfig.ignore])];
+  }
+  merged.ai = {
+    ...DEFAULT_AI_CONFIG,
+    ...(userConfig.ai || {}),
+    openai: { ...DEFAULT_AI_CONFIG.openai, ...(userConfig.ai?.openai || {}) },
+    groq: { ...DEFAULT_AI_CONFIG.groq, ...(userConfig.ai?.groq || {}) },
+  };
+  return merged;
+}
+
+/** Apply .env overrides (timer, debounce, AI provider) on top of config. */
+export function applyEnvOverrides(config) {
+  const envInterval = getRefreshIntervalMinutesFromEnv();
+  if (envInterval !== null) {
+    config.refreshIntervalMinutes = envInterval;
+  }
+  const envDebounce = getDebounceMsFromEnv();
+  if (envDebounce !== null) {
+    config.debounceMs = envDebounce;
+  }
+  const resolvedAi = resolveAiConfig(config);
+  config.ai = { ...config.ai, ...resolvedAi };
+  return config;
+}
+
+/**
+ * Write/update config.json from defaults + .env (proper init/upgrade path).
+ * @param {string} projectRoot
+ * @param {{ enableAi?: boolean, upgrade?: boolean }} options
+ */
+export async function syncConfigFile(projectRoot, options = {}) {
+  await loadProjectEnv(projectRoot);
+  const configPath = getConfigPath(projectRoot);
+  let userConfig = {};
+  if (await fs.pathExists(configPath)) {
+    userConfig = await fs.readJson(configPath);
+  }
+
+  const merged = mergeConfigWithDefaults(userConfig);
+
+  if (options.enableAi) {
+    merged.ai.enabled = true;
+    merged.ai.enrichContext = true;
+    merged.ai.background = true;
+  } else {
+    const envAi = isAiEnabledViaEnv();
+    if (envAi === true) {
+      merged.ai.enabled = true;
+    } else if (envAi === false) {
+      merged.ai.enabled = false;
+    } else if (options.upgrade && hasAnyAiKey() && userConfig.ai?.enabled === undefined) {
+      merged.ai.enabled = true;
+    }
+  }
+
+  applyEnvOverrides(merged);
+
+  await ensureContextForgeDirs(projectRoot);
+  await fs.writeJson(configPath, merged, { spaces: 2 });
+  return merged;
+}
+
+export async function loadConfig(projectRoot) {
+  await loadProjectEnv(projectRoot);
+
+  const configPath = getConfigPath(projectRoot);
+  let userConfig = {};
+
+  if (await fs.pathExists(configPath)) {
+    userConfig = await fs.readJson(configPath);
+  }
+
+  const merged = mergeConfigWithDefaults(userConfig);
+  applyEnvOverrides(merged);
+  return merged;
+}
+
+export async function ensureContextForgeDirs(projectRoot) {
+  const root = getContextForgeRoot(projectRoot);
+  await fs.ensureDir(root);
+  await fs.ensureDir(path.join(root, 'cache'));
+  await fs.ensureDir(path.join(root, 'logs'));
+}
+
+export async function writeDefaultConfig(projectRoot, options = {}) {
+  await ensureContextForgeDirs(projectRoot);
+  const configPath = getConfigPath(projectRoot);
+
+  if (!(await fs.pathExists(configPath))) {
+    const config = mergeConfigWithDefaults(options);
+    if (options.ai) {
+      config.ai = { ...config.ai, ...options.ai };
+    }
+    applyEnvOverrides(config);
+    if (options.enableAi) {
+      config.ai.enabled = true;
+    }
+    await fs.writeJson(configPath, config, { spaces: 2 });
+    return config;
+  }
+
+  if (options.ai) {
+    const existing = await fs.readJson(configPath);
+    await fs.writeJson(
+      configPath,
+      mergeConfigWithDefaults({ ...existing, ai: { ...existing.ai, ...options.ai } }),
+      { spaces: 2 }
+    );
+  }
+
+  return mergeConfigWithDefaults(await fs.readJson(configPath));
+}
+
+export async function isInitialized(projectRoot) {
+  return fs.pathExists(getConfigPath(projectRoot));
+}

package/src/core/cursor-rules.js

@@ -0,0 +1,293 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { getOutputPath, OUTPUT_FILES } from './paths.js';
+
+const RULE_FILENAME = 'contextforge.mdc';
+
+/**
+ * @param {{ description?: string, alwaysApply?: boolean }} meta
+ * @param {string} body
+ */
+function formatMdc(meta, body) {
+  const lines = ['---'];
+  if (meta.description) lines.push(`description: ${meta.description}`);
+  lines.push(`alwaysApply: ${meta.alwaysApply === true}`);
+  lines.push('---', '', body.trim(), '');
+  return lines.join('\n');
+}
+
+function bullets(items, empty = '_None_') {
+  if (!items?.length) return empty;
+  return items.map((i) => `- ${i}`).join('\n');
+}
+
+function renderAtAGlanceTable(snapshot) {
+  const ts = snapshot.techStack || {};
+  const arch = snapshot.architecture || {};
+  const auth = snapshot.authDeploy || {};
+
+  const rows = [
+    ['Frontend', [...(ts.frontend || []), ...(ts.styling || [])].join(', ') || '—'],
+    ['Backend', (ts.backend || []).join(', ') || '—'],
+    ['Database / ORM', [...(ts.database || []), ...(ts.orm || [])].join(', ') || '—'],
+    ['State', (ts.state || []).join(', ') || '—'],
+    [
+      'Auth',
+      [...new Set([...(auth.authentication || []), ...(ts.auth || [])])].join(', ') || '—',
+    ],
+    ['Deploy', [...(auth.deployment || []), ...(ts.deploy || [])].join(', ') || '—'],
+    ['Architecture', arch?.primary?.label || '—'],
+    ['API style', arch?.apiFlow || snapshot.codeInsights?.pipelineFlow || '—'],
+  ];
+
+  return [
+    '| Area | Detected |',
+    '|------|----------|',
+    ...rows.map(([a, b]) => `| **${a}** | ${b} |`),
+  ].join('\n');
+}
+
+function collectImportantRules(snapshot) {
+  const code = snapshot.codeInsights || {};
+  const ai = snapshot.aiEnrichment?.structured || snapshot.aiEnrichment || {};
+  const fromCode = code.importantRules || [];
+  const fromAi = Array.isArray(ai.importantRules)
+    ? ai.importantRules
+    : ai.importantRules
+      ? [String(ai.importantRules)]
+      : [];
+  return [...new Set([...fromCode, ...fromAi])].slice(0, 12);
+}
+
+function collectConventions(snapshot) {
+  const ai = snapshot.aiEnrichment?.structured || snapshot.aiEnrichment || {};
+  const fromAi = Array.isArray(ai.codingConventions)
+    ? ai.codingConventions
+    : ai.codingConventions
+      ? [String(ai.codingConventions)]
+      : [];
+  const patterns = snapshot.codeInsights?.patterns || [];
+  return [...new Set([...fromAi, ...patterns])].slice(0, 10);
+}
+
+function renderRoutesBrief(endpoints = []) {
+  if (!endpoints.length) return null;
+  const lines = [
+    '| Method | Path | File |',
+    '|--------|------|------|',
+    ...endpoints.slice(0, 20).map((e) => `| ${e.method} | ${e.path} | \`${e.file}\` |`),
+  ];
+  if (endpoints.length > 20) {
+    lines.push('', `_+ ${endpoints.length - 20} more in \`.contextforge/context.md\`_`);
+  }
+  return lines.join('\n');
+}
+
+function renderServicesBrief(businessLogic = []) {
+  if (!businessLogic.length) return null;
+  return businessLogic
+    .slice(0, 15)
+    .map((b) => `- \`${b.name}\` (${b.type}) — \`${b.file}\``)
+    .join('\n');
+}
+
+/**
+ * Build a single Cursor rule file from the pipeline snapshot (same source as context.md).
+ * @param {object} snapshot
+ * @returns {{ filename: string, content: string }[]}
+ */
+export function buildCursorRuleFiles(snapshot) {
+  const projectName = snapshot.projectName || 'project';
+  const generatedAt = snapshot.generatedAt || new Date().toISOString();
+  const ts = snapshot.techStack || {};
+  const sections = [];
+
+  sections.push(
+    `# ContextForge — ${projectName}`,
+    '',
+    `_Synced from \`.contextforge/context.md\` (${generatedAt})_`,
+    '',
+    'Before answering questions about this codebase, **read [`.contextforge/context.md`](.contextforge/context.md)** for full detail.',
+    '',
+    '## At a Glance',
+    '',
+    renderAtAGlanceTable(snapshot),
+    '',
+    '## Commands',
+    '',
+    '- Regenerate: `npx contextforge generate`',
+    '- Watch: `npx contextforge watch`',
+    '- Changes: `npx contextforge changes` or `.contextforge/CHANGES.md`',
+    '- Timer: `CONTEXTFORGE_REFRESH_INTERVAL_MINUTES` in `.env` (e.g. 15)'
+  );
+
+  const importantRules = collectImportantRules(snapshot);
+  if (importantRules.length) {
+    sections.push('', '## Important rules', '', bullets(importantRules));
+  }
+
+  const conventions = collectConventions(snapshot);
+  if (conventions.length) {
+    sections.push('', '## Patterns & conventions', '', bullets(conventions));
+  }
+
+  const topIssues = (snapshot.bugs?.issues || []).slice(0, 5);
+  if (topIssues.length) {
+    sections.push(
+      '',
+      '## Watch for (static analysis)',
+      '',
+      ...topIssues.map(
+        (i) => `- **[${i.severity}]** ${i.message}${i.file ? ` — \`${i.file}\`` : ''}`
+      )
+    );
+  }
+
+  const endpoints = snapshot.codeInsights?.apiEndpoints || [];
+  const routeTable = renderRoutesBrief(endpoints);
+  if (routeTable) {
+    sections.push(
+      '',
+      '## API routes',
+      '',
+      snapshot.architecture?.apiFlow ? `**Flow:** ${snapshot.architecture.apiFlow}` : '',
+      '',
+      routeTable
+    );
+  }
+
+  const businessLogic = snapshot.codeInsights?.businessLogic || [];
+  const serviceList = renderServicesBrief(businessLogic);
+  if (serviceList || snapshot.codeInsights?.summary) {
+    sections.push('', '## Business logic');
+    if (snapshot.codeInsights?.summary) {
+      sections.push('', snapshot.codeInsights.summary);
+    }
+    if (serviceList) {
+      sections.push('', serviceList);
+    }
+  }
+
+  if (ts.frontend?.length || ts.styling?.length) {
+    sections.push(
+      '',
+      '## Frontend',
+      '',
+      `**Stack:** ${[...(ts.frontend || []), ...(ts.styling || []), ...(ts.state || [])].join(', ') || '—'}`
+    );
+  }
+
+  sections.push(
+    '_More detail in `.contextforge/context.md` (architecture, git, database, full issue list)._'
+  );
+
+  return [
+    {
+      filename: RULE_FILENAME,
+      content: formatMdc(
+        {
+          description: 'ContextForge project memory — read before coding',
+          alwaysApply: true,
+        },
+        sections.join('\n\n')
+      ),
+    },
+  ];
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} [snapshot]
+ */
+export async function installCursorRules(projectRoot, snapshot = null) {
+  const cursorDir = path.join(projectRoot, '.cursor', 'rules');
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+
+  if (!snapshot) {
+    const jsonPath = getOutputPath(projectRoot, OUTPUT_FILES.contextJson);
+    if (await fs.pathExists(jsonPath)) {
+      snapshot = await fs.readJson(jsonPath);
+    }
+  }
+
+  await fs.ensureDir(cursorDir);
+
+  const ruleFiles = snapshot ? buildCursorRuleFiles(snapshot) : [buildFallbackRule()];
+
+  const written = [];
+  for (const { filename, content } of ruleFiles) {
+    const rulePath = path.join(cursorDir, filename);
+    await fs.writeFile(rulePath, content, 'utf8');
+    written.push(rulePath);
+  }
+
+  await pruneStaleRules(cursorDir, ruleFiles.map((r) => r.filename));
+
+  await syncAgentsMd(agentsPath);
+
+  return { rulePaths: written, agentsPath };
+}
+
+function buildFallbackRule() {
+  return {
+    filename: RULE_FILENAME,
+    content: formatMdc(
+      {
+        description: 'ContextForge project context — read before coding',
+        alwaysApply: true,
+      },
+      `# ContextForge — Project Memory
+
+Before answering questions about this codebase, **read \`.contextforge/context.md\`** in full.
+
+Regenerate context: \`npx contextforge generate\`
+Watch mode: \`npx contextforge watch\`
+Change history: \`npx contextforge changes\` or \`.contextforge/CHANGES.md\``
+    ),
+  };
+}
+
+/** Remove old split contextforge-*.mdc files from previous versions. */
+async function pruneStaleRules(cursorDir, keepFilenames) {
+  const keep = new Set(keepFilenames);
+  let entries = [];
+  try {
+    entries = await fs.readdir(cursorDir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith('contextforge') || !name.endsWith('.mdc')) continue;
+    if (!keep.has(name)) {
+      await fs.remove(path.join(cursorDir, name));
+    }
+  }
+}
+
+async function syncAgentsMd(agentsPath) {
+  const agentsSnippet = `## ContextForge
+
+Read [\`.contextforge/context.md\`](.contextforge/context.md) before working on this repository.
+Cursor rule [\`.cursor/rules/contextforge.mdc\`](.cursor/rules/contextforge.mdc) is synced from the latest generate run.
+
+`;
+
+  if (await fs.pathExists(agentsPath)) {
+    const content = await fs.readFile(agentsPath, 'utf8');
+    if (!content.includes('contextforge/context.md')) {
+      await fs.writeFile(agentsPath, agentsSnippet + content, 'utf8');
+    } else if (!content.includes('contextforge.mdc')) {
+      const updated = content.replace(
+        /Cursor rules in \[`\.cursor\/rules\/`\]\(\.cursor\/rules\/\) are synced from the latest generate run\./,
+        'Cursor rule [`.cursor/rules/contextforge.mdc`](.cursor/rules/contextforge.mdc) is synced from the latest generate run.'
+      );
+      if (updated !== content) await fs.writeFile(agentsPath, updated, 'utf8');
+    }
+  } else {
+    await fs.writeFile(
+      agentsPath,
+      `# Agent Instructions\n\n${agentsSnippet}`,
+      'utf8'
+    );
+  }
+}

package/src/core/ensure-setup.js

@@ -0,0 +1,45 @@
+import {
+  writeDefaultConfig,
+  isInitialized,
+  syncConfigFile,
+  ensureContextForgeDirs,
+} from './config.js';
+import { ensureEnvExample, ensureEnvFromExample } from './setup-env.js';
+import { ensureProjectPrompts } from './setup-prompts.js';
+import { getContextForgeRoot } from './paths.js';
+
+/**
+ * Create `.contextforge/` and config when missing (used by generate/watch).
+ * @param {string} projectRoot
+ * @param {{ enableAi?: boolean, quiet?: boolean }} [options]
+ * @returns {Promise<boolean>} true if setup was created now
+ */
+export async function ensureInitialized(projectRoot, options = {}) {
+  if (await isInitialized(projectRoot)) {
+    await ensureContextForgeDirs(projectRoot);
+    return false;
+  }
+
+  if (!options.quiet) {
+    console.log('ContextForge not set up — creating `.contextforge/` automatically...');
+  }
+
+  const initOptions = {};
+  if (options.enableAi) {
+    initOptions.ai = { enabled: true, enrichContext: true, background: true };
+  }
+
+  await writeDefaultConfig(projectRoot, initOptions);
+  await syncConfigFile(projectRoot, { enableAi: options.enableAi, upgrade: true });
+  await ensureProjectPrompts(projectRoot);
+  await ensureEnvExample(projectRoot);
+  await ensureEnvFromExample(projectRoot);
+  await ensureContextForgeDirs(projectRoot);
+
+  if (!options.quiet) {
+    console.log(`  → ${getContextForgeRoot(projectRoot)}/`);
+    console.log('  Tip: run `npx contextforge watch` to keep context.md updated while you code');
+  }
+
+  return true;
+}

package/src/core/env.js

@@ -0,0 +1,113 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+/**
+ * Load environment variables from project .env (never committed).
+ * @param {string} projectRoot
+ */
+export async function loadProjectEnv(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const envPath = path.join(root, '.env');
+  const examplePath = path.join(root, '.env.example');
+
+  if (await fs.pathExists(envPath)) {
+    const result = dotenv.config({ path: envPath, override: true });
+    if (result.error) {
+      console.warn(`[contextforge] Warning: could not parse .env — ${result.error.message}`);
+    }
+  } else if (await fs.pathExists(examplePath)) {
+    dotenv.config({ path: examplePath, override: true });
+  }
+}
+
+export function getApiKey(provider) {
+  if (provider === 'groq') {
+    return (
+      process.env.GROQ_API_KEY ||
+      process.env.CONTEXTFORGE_GROQ_API_KEY ||
+      ''
+    ).trim();
+  }
+  return (
+    process.env.OPENAI_API_KEY ||
+    process.env.CONTEXTFORGE_OPENAI_API_KEY ||
+    ''
+  ).trim();
+}
+
+export function getEnvModel(provider, defaultModel) {
+  if (provider === 'groq') {
+    return (process.env.GROQ_MODEL || defaultModel).trim();
+  }
+  return (process.env.OPENAI_MODEL || defaultModel).trim();
+}
+
+function parseEnvBool(value) {
+  if (value === 'true' || value === '1') return true;
+  if (value === 'false' || value === '0') return false;
+  return null;
+}
+
+export function isAiEnabledViaEnv() {
+  return parseEnvBool(process.env.CONTEXTFORGE_AI_ENABLED);
+}
+
+/** Master switch: auto setup + background watch on `npm install` (default: on). */
+export function isAutoStartEnabledViaEnv() {
+  if (process.env.CONTEXTFORGE_SKIP_POSTINSTALL === '1') return false;
+  const v = parseEnvBool(process.env.CONTEXTFORGE_AUTO_START);
+  if (v !== null) return v;
+  return true;
+}
+
+export function isPostinstallGenerateEnabledViaEnv() {
+  const v = parseEnvBool(process.env.CONTEXTFORGE_POSTINSTALL_GENERATE);
+  if (v !== null) return v;
+  return true;
+}
+
+export function isPostinstallWatchEnabledViaEnv() {
+  const v = parseEnvBool(process.env.CONTEXTFORGE_POSTINSTALL_WATCH);
+  if (v !== null) return v;
+  return true;
+}
+
+export function hasAnyAiKey() {
+  return !!(getApiKey('openai') || getApiKey('groq'));
+}
+
+function parseNonNegativeNumber(value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return null;
+  }
+  const n = parseFloat(String(value).trim());
+  if (Number.isNaN(n) || n < 0) return null;
+  return n;
+}
+
+/**
+ * Auto-refresh interval for `watch` (minutes). 0 = only on file changes.
+ * Env: CONTEXTFORGE_REFRESH_INTERVAL_MINUTES, CONTEXTFORGE_WATCH_INTERVAL_MINUTES
+ * Or seconds: CONTEXTFORGE_REFRESH_INTERVAL_SECONDS
+ */
+export function getRefreshIntervalMinutesFromEnv() {
+  const minutes = parseNonNegativeNumber(
+    process.env.CONTEXTFORGE_REFRESH_INTERVAL_MINUTES ??
+      process.env.CONTEXTFORGE_WATCH_INTERVAL_MINUTES
+  );
+  if (minutes !== null) return minutes;
+
+  const seconds = parseNonNegativeNumber(
+    process.env.CONTEXTFORGE_REFRESH_INTERVAL_SECONDS
+  );
+  if (seconds !== null) return seconds / 60;
+
+  return null;
+}
+
+/** File-change debounce for watch (milliseconds). Env: CONTEXTFORGE_DEBOUNCE_MS */
+export function getDebounceMsFromEnv() {
+  const ms = parseNonNegativeNumber(process.env.CONTEXTFORGE_DEBOUNCE_MS);
+  return ms !== null ? Math.round(ms) : null;
+}

package/src/core/package-meta.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+
+/** Published npm package name (must match package.json "name"). */
+export const NPM_PACKAGE_NAME = 'contextforge-cli-ai-prompt-pirates';
+
+/** Older / alternate names still recognized in consumer package.json. */
+export const LEGACY_NPM_NAMES = ['contextforge', '@contextforge/core'];
+
+let cachedOwnName = null;
+
+export async function getOwnPackageName() {
+  if (cachedOwnName) return cachedOwnName;
+  try {
+    const pkg = await fs.readJson(path.join(PACKAGE_ROOT, 'package.json'));
+    cachedOwnName = pkg.name || NPM_PACKAGE_NAME;
+  } catch {
+    cachedOwnName = NPM_PACKAGE_NAME;
+  }
+  return cachedOwnName;
+}
+
+/**
+ * @param {Record<string, string>} deps merged dependencies from consumer package.json
+ * @param {string} consumerPackageName
+ */
+export function hasContextForgeDependency(deps, consumerPackageName, ownName) {
+  const keys = [ownName, NPM_PACKAGE_NAME, ...LEGACY_NPM_NAMES];
+  if (keys.some((k) => deps[k])) return true;
+  return keys.includes(consumerPackageName);
+}

package/src/core/paths.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+export const CONTEXTFORGE_DIR = '.contextforge';
+
+export function getContextForgeRoot(projectRoot) {
+  return path.join(projectRoot, CONTEXTFORGE_DIR);
+}
+
+export function getConfigPath(projectRoot) {
+  return path.join(getContextForgeRoot(projectRoot), 'config.json');
+}
+
+export function getCacheDir(projectRoot) {
+  return path.join(getContextForgeRoot(projectRoot), 'cache');
+}
+
+export function getLogsDir(projectRoot) {
+  return path.join(getContextForgeRoot(projectRoot), 'logs');
+}
+
+export function getFileIndexPath(projectRoot) {
+  return path.join(getCacheDir(projectRoot), 'file-index.json');
+}
+
+export function getPidPath(projectRoot) {
+  return path.join(getContextForgeRoot(projectRoot), '.watch.pid');
+}
+
+export const OUTPUT_FILES = {
+  contextMd: 'context.md',
+  contextJson: 'context.json',
+  architectureJson: 'architecture.json',
+  gitInsightsJson: 'git-insights.json',
+  bugsReportJson: 'bugs-report.json',
+};
+
+export function getOutputPath(projectRoot, filename) {
+  return path.join(getContextForgeRoot(projectRoot), filename);
+}