@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/context-loader.ts

@@ -0,0 +1,694 @@
+/**
+ * Bootspring Context Loader
+ * Loads and indexes project context files for AI agent access
+ *
+ * Context Types:
+ * - seed: SEED.md project configuration
+ * - claude: CLAUDE.md AI context
+ * - plan: Planning documents (MASTER_PLAN, PRD, etc.)
+ * - business: Business documents (plans, competitive analysis)
+ * - legal: Legal documents (terms, privacy)
+ * - mvp: MVP source code
+ * - logs: Action logs and history
+ *
+ * @package bootspring
+ * @module core/context-loader
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Module interfaces
+interface ConfigModule {
+  load: () => Config | null;
+}
+
+interface Config {
+  _projectRoot: string;
+}
+
+interface Utils {
+  fileExists: (path: string) => boolean;
+  readFile: (path: string) => string | null;
+  ensureDir: (dir: string) => void;
+  truncate: (text: string, maxLength: number) => string;
+  writeFile: (path: string, content: string) => boolean;
+  formatRelativeTime: (date: Date) => string;
+}
+
+// Lazy-loaded modules
+let _config: ConfigModule | null = null;
+let _utils: Utils | null = null;
+
+function getConfig(): ConfigModule {
+  if (!_config) {
+    _config = require('./config') as ConfigModule;
+  }
+  return _config;
+}
+
+function getUtils(): Utils {
+  if (!_utils) {
+    _utils = require('./utils') as Utils;
+  }
+  return _utils;
+}
+
+// Type definitions
+export interface ContextFileMetadata {
+  size: number;
+  modified: Date;
+  modifiedRelative: string;
+  extension?: string | undefined;
+}
+
+export interface SingleFileContext {
+  exists: boolean;
+  type: string;
+  path: string;
+  fullPath?: string | undefined;
+  content: string | null;
+  metadata?: ContextFileMetadata | undefined;
+  error?: string | undefined;
+}
+
+export interface DirectoryFile {
+  name: string;
+  path: string;
+  fullPath: string;
+  size: number;
+  modified: Date;
+  extension: string;
+}
+
+export interface DirectoryContext {
+  exists: boolean;
+  type: string;
+  path: string;
+  files: DirectoryFile[];
+  fileCount?: number | undefined;
+}
+
+export interface AgentContextFile {
+  type: string;
+  isDirectory: boolean;
+  path?: string | undefined;
+  content?: string | undefined;
+  metadata?: ContextFileMetadata | undefined;
+  fileCount?: number | undefined;
+  files?: DirectoryFile[] | undefined;
+}
+
+export interface AgentContext {
+  agent: string;
+  files: AgentContextFile[];
+  summary: string[];
+}
+
+export interface ContextStatus {
+  type: string;
+  path: string;
+  exists: boolean;
+  isDirectory?: boolean | undefined;
+  fileCount?: number | undefined;
+  size?: number | undefined;
+  modified?: Date | undefined;
+  modifiedRelative?: string | undefined;
+}
+
+export interface SearchMatch {
+  line: number;
+  preview: string;
+}
+
+export interface SearchResult {
+  type: string;
+  file: string;
+  matchType: 'filename' | 'content';
+  preview?: string | undefined;
+  matches?: SearchMatch[] | undefined;
+}
+
+export interface IndexFile {
+  type: string;
+  path: string;
+  isDirectory: boolean;
+  fileCount?: number | undefined;
+  size?: number | undefined;
+  modified?: Date | undefined;
+}
+
+export interface ContextIndex {
+  version: string;
+  lastUpdated: string;
+  projectRoot: string;
+  files: IndexFile[];
+  agents: Record<string, string[]>;
+}
+
+export interface LoadOptions {
+  config?: Config | undefined;
+}
+
+export interface SearchOptions {
+  config?: Config | undefined;
+  types?: string[] | undefined;
+  limit?: number | undefined;
+}
+
+/**
+ * Default context file locations
+ */
+export const CONTEXT_LOCATIONS: Record<string, string> = {
+  // Root level files
+  seed: 'SEED.md',
+  claude: 'CLAUDE.md',
+  todo: 'todo.md',
+  readme: 'README.md',
+  changelog: 'CHANGELOG.md',
+
+  // Planning folder
+  plan: 'planning/MASTER_PLAN.md',
+  prd: 'planning/PRD.md',
+  architecture: 'planning/ARCHITECTURE.md',
+  decisions: 'planning/DECISION_LOG.md',
+  roadmap: 'planning/ROADMAP.md',
+
+  // Business documents
+  business_plan: 'planning/BUSINESS_PLAN.md',
+  pitch_deck: 'planning/PITCH_DECK.md',
+  competitive: 'planning/COMPETITIVE_ANALYSIS.md',
+  market: 'planning/MARKET_RESEARCH.md',
+  financial: 'planning/FINANCIAL_MODEL.md',
+
+  // Legal documents
+  terms: 'legal/TERMS_OF_SERVICE.md',
+  privacy: 'legal/PRIVACY_POLICY.md',
+  legal_checklist: 'legal/LEGAL_CHECKLIST.md',
+
+  // MVP and code context
+  mvp_source: '.bootspring/mvp/source/',
+  mvp_references: '.bootspring/mvp/references/',
+
+  // Logs
+  logs: '.bootspring/logs/',
+  context_index: '.bootspring/context-index.json'
+};
+
+/**
+ * Agent to context mapping
+ */
+export const AGENT_CONTEXT_MAP: Record<string, string[]> = {
+  // Technical agents
+  'frontend-expert': ['seed', 'architecture', 'prd', 'mvp_source'],
+  'backend-expert': ['seed', 'architecture', 'prd', 'mvp_source'],
+  'database-expert': ['seed', 'architecture', 'mvp_source'],
+  'api-expert': ['seed', 'architecture', 'prd'],
+  'security-expert': ['architecture', 'legal_checklist', 'prd'],
+  'testing-expert': ['architecture', 'prd'],
+  'performance-expert': ['architecture', 'mvp_source'],
+  'devops-expert': ['architecture', 'plan'],
+  'ui-ux-expert': ['seed', 'prd', 'mvp_source'],
+  'code-review-expert': ['architecture', 'mvp_source'],
+
+  // Business agents
+  'business-strategy-expert': ['seed', 'business_plan', 'competitive', 'plan'],
+  'financial-expert': ['seed', 'business_plan', 'financial'],
+  'fundraising-expert': ['pitch_deck', 'financial', 'business_plan'],
+  'legal-expert': ['terms', 'privacy', 'legal_checklist'],
+  'marketing-expert': ['business_plan', 'competitive', 'plan'],
+  'sales-expert': ['business_plan', 'competitive', 'prd'],
+  'growth-expert': ['plan', 'competitive', 'market'],
+  'operations-expert': ['plan', 'architecture'],
+  'competitive-analysis-expert': ['competitive', 'market', 'business_plan'],
+  'market-research-expert': ['market', 'competitive', 'business_plan'],
+  'investor-relations-expert': ['pitch_deck', 'financial', 'plan'],
+
+  // Research agents
+  'research-expert': ['plan', 'architecture', 'prd'],
+  'data-modeling-expert': ['architecture', 'prd', 'mvp_source'],
+
+  // Technical specialists
+  'vercel-expert': ['architecture', 'prd', 'plan'],
+  'architecture-expert': ['architecture', 'prd', 'plan', 'mvp_source'],
+  'ai-integration-expert': ['seed', 'architecture', 'prd', 'mvp_source'],
+  'auth-expert': ['seed', 'architecture', 'prd', 'mvp_source'],
+  'email-expert': ['seed', 'prd', 'mvp_source'],
+  'monitoring-expert': ['architecture', 'plan'],
+  'payment-expert': ['seed', 'business_plan', 'prd', 'mvp_source'],
+  'railway-expert': ['architecture', 'plan'],
+
+  // Product and content
+  'content-expert': ['seed', 'prd', 'plan'],
+  'product-expert': ['seed', 'prd', 'plan', 'roadmap'],
+  'mobile-expert': ['seed', 'architecture', 'prd', 'mvp_source'],
+  'infrastructure-expert': ['architecture', 'plan'],
+
+  // Business specialists
+  'partnerships-expert': ['business_plan', 'competitive', 'plan'],
+  'private-equity-expert': ['pitch_deck', 'financial', 'business_plan']
+};
+
+/**
+ * Get the bootspring directory path
+ */
+export function getBootspringDir(projectRoot: string): string {
+  return path.join(projectRoot, '.bootspring');
+}
+
+/**
+ * Ensure bootspring directories exist
+ */
+export function ensureDirectories(projectRoot: string): void {
+  const utils = getUtils();
+  const bootspringDir = getBootspringDir(projectRoot);
+  const dirs = [
+    bootspringDir,
+    path.join(bootspringDir, 'logs'),
+    path.join(bootspringDir, 'logs', 'agents'),
+    path.join(bootspringDir, 'logs', 'code'),
+    path.join(bootspringDir, 'logs', 'decisions'),
+    path.join(bootspringDir, 'logs', 'fixes'),
+    path.join(bootspringDir, 'logs', 'business'),
+    path.join(bootspringDir, 'logs', 'meetings'),
+    path.join(bootspringDir, 'mvp'),
+    path.join(bootspringDir, 'mvp', 'source'),
+    path.join(bootspringDir, 'mvp', 'references')
+  ];
+
+  for (const dir of dirs) {
+    utils.ensureDir(dir);
+  }
+}
+
+/**
+ * Load a specific context file
+ */
+export function load(contextType: string, options: LoadOptions = {}): SingleFileContext | DirectoryContext {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const projectRoot = cfg?._projectRoot || process.cwd();
+
+  const relativePath = CONTEXT_LOCATIONS[contextType];
+  if (!relativePath) {
+    return { exists: false, type: contextType, path: '', content: null, error: `Unknown context type: ${contextType}` };
+  }
+
+  const fullPath = path.join(projectRoot, relativePath);
+
+  // Check if it's a directory (like mvp_source)
+  if (relativePath.endsWith('/')) {
+    return loadDirectory(fullPath, contextType);
+  }
+
+  // Load single file
+  if (!utils.fileExists(fullPath)) {
+    return {
+      exists: false,
+      type: contextType,
+      path: relativePath,
+      content: null
+    };
+  }
+
+  const content = utils.readFile(fullPath);
+  const stats = fs.statSync(fullPath);
+
+  return {
+    exists: true,
+    type: contextType,
+    path: relativePath,
+    fullPath: fullPath,
+    content: content,
+    metadata: {
+      size: stats.size,
+      modified: stats.mtime,
+      modifiedRelative: utils.formatRelativeTime(stats.mtime)
+    }
+  };
+}
+
+/**
+ * Load all files from a directory
+ */
+export function loadDirectory(dirPath: string, contextType: string): DirectoryContext {
+  const utils = getUtils();
+
+  if (!utils.fileExists(dirPath)) {
+    return {
+      exists: false,
+      type: contextType,
+      path: dirPath,
+      files: []
+    };
+  }
+
+  const files: DirectoryFile[] = [];
+
+  function walkDir(dir: string, relativeTo: string): void {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(relativeTo, fullPath);
+
+        // Skip hidden files and common excludes
+        if (entry.name.startsWith('.') ||
+            entry.name === 'node_modules' ||
+            entry.name === 'dist' ||
+            entry.name === 'build') {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          walkDir(fullPath, relativeTo);
+        } else if (entry.isFile()) {
+          const stats = fs.statSync(fullPath);
+          files.push({
+            name: entry.name,
+            path: relativePath,
+            fullPath: fullPath,
+            size: stats.size,
+            modified: stats.mtime,
+            extension: path.extname(entry.name)
+          });
+        }
+      }
+    } catch {
+      // Directory read error, skip
+    }
+  }
+
+  walkDir(dirPath, dirPath);
+
+  return {
+    exists: true,
+    type: contextType,
+    path: dirPath,
+    files: files,
+    fileCount: files.length
+  };
+}
+
+/**
+ * Load a specific file from a directory context
+ */
+export function loadFile(contextType: string, filePath: string, options: LoadOptions = {}): SingleFileContext {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const projectRoot = cfg?._projectRoot || process.cwd();
+
+  const basePath = CONTEXT_LOCATIONS[contextType];
+  if (!basePath) {
+    return { exists: false, type: contextType, path: filePath, content: null, error: `Unknown context type: ${contextType}` };
+  }
+
+  const fullPath = path.join(projectRoot, basePath, filePath);
+
+  if (!utils.fileExists(fullPath)) {
+    return {
+      exists: false,
+      type: contextType,
+      path: filePath,
+      content: null
+    };
+  }
+
+  const content = utils.readFile(fullPath);
+  const stats = fs.statSync(fullPath);
+
+  return {
+    exists: true,
+    type: contextType,
+    path: filePath,
+    fullPath: fullPath,
+    content: content,
+    metadata: {
+      size: stats.size,
+      modified: stats.mtime,
+      modifiedRelative: utils.formatRelativeTime(stats.mtime),
+      extension: path.extname(fullPath)
+    }
+  };
+}
+
+/**
+ * Get all context for a specific agent
+ */
+export function getAgentContext(agentName: string, options: LoadOptions = {}): AgentContext {
+  const contextTypes = AGENT_CONTEXT_MAP[agentName] || [];
+  const context: AgentContext = {
+    agent: agentName,
+    files: [],
+    summary: []
+  };
+
+  for (const contextType of contextTypes) {
+    const loaded = load(contextType, options);
+    if (loaded.exists) {
+      if ('files' in loaded && loaded.files) {
+        // Directory context
+        context.files.push({
+          type: contextType,
+          isDirectory: true,
+          fileCount: loaded.fileCount,
+          files: loaded.files.slice(0, 10) // Limit to first 10 files
+        });
+        context.summary.push(`${contextType}: ${loaded.fileCount} files`);
+      } else if ('content' in loaded) {
+        // Single file context
+        context.files.push({
+          type: contextType,
+          isDirectory: false,
+          path: loaded.path,
+          content: loaded.content || undefined,
+          metadata: loaded.metadata
+        });
+        context.summary.push(`${contextType}: ${loaded.path}`);
+      }
+    }
+  }
+
+  return context;
+}
+
+/**
+ * List all available context types and their status
+ */
+export function list(options: LoadOptions = {}): ContextStatus[] {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const projectRoot = cfg?._projectRoot || process.cwd();
+  const results: ContextStatus[] = [];
+
+  for (const [type, relativePath] of Object.entries(CONTEXT_LOCATIONS)) {
+    const fullPath = path.join(projectRoot, relativePath);
+    const exists = utils.fileExists(fullPath);
+
+    const result: ContextStatus = {
+      type,
+      path: relativePath,
+      exists
+    };
+
+    if (exists) {
+      if (relativePath.endsWith('/')) {
+        // Directory
+        const dirContext = loadDirectory(fullPath, type);
+        result.isDirectory = true;
+        result.fileCount = dirContext.fileCount;
+      } else {
+        // File
+        const stats = fs.statSync(fullPath);
+        result.isDirectory = false;
+        result.size = stats.size;
+        result.modified = stats.mtime;
+        result.modifiedRelative = utils.formatRelativeTime(stats.mtime);
+      }
+    }
+
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Search across all context files
+ */
+export function search(query: string, options: SearchOptions = {}): SearchResult[] {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const types = options.types || Object.keys(CONTEXT_LOCATIONS);
+  const limit = options.limit || 20;
+  const results: SearchResult[] = [];
+  const queryLower = query.toLowerCase();
+
+  for (const type of types) {
+    if (!CONTEXT_LOCATIONS[type]) continue;
+
+    const loaded = load(type, { config: cfg || undefined });
+    if (!loaded.exists) continue;
+
+    if ('files' in loaded && loaded.files) {
+      // Directory - search file names and contents
+      for (const file of loaded.files) {
+        // Search in filename
+        if (file.name.toLowerCase().includes(queryLower)) {
+          results.push({
+            type,
+            file: file.path,
+            matchType: 'filename',
+            preview: file.name
+          });
+        }
+
+        // Search in content for text files
+        if (['.md', '.txt', '.js', '.ts', '.json', '.yaml', '.yml'].includes(file.extension)) {
+          const content = utils.readFile(file.fullPath);
+          if (content && content.toLowerCase().includes(queryLower)) {
+            const lines = content.split('\n');
+            const matchingLines = lines
+              .map((line, i) => ({ line, num: i + 1 }))
+              .filter(l => l.line.toLowerCase().includes(queryLower))
+              .slice(0, 3);
+
+            results.push({
+              type,
+              file: file.path,
+              matchType: 'content',
+              matches: matchingLines.map(m => ({
+                line: m.num,
+                preview: utils.truncate(m.line.trim(), 100)
+              }))
+            });
+          }
+        }
+
+        if (results.length >= limit) break;
+      }
+    } else if ('content' in loaded && loaded.content) {
+      // Single file - search content
+      const content = loaded.content;
+      if (content.toLowerCase().includes(queryLower)) {
+        const lines = content.split('\n');
+        const matchingLines = lines
+          .map((line, i) => ({ line, num: i + 1 }))
+          .filter(l => l.line.toLowerCase().includes(queryLower))
+          .slice(0, 5);
+
+        results.push({
+          type,
+          file: loaded.path,
+          matchType: 'content',
+          matches: matchingLines.map(m => ({
+            line: m.num,
+            preview: utils.truncate(m.line.trim(), 100)
+          }))
+        });
+      }
+    }
+
+    if (results.length >= limit) break;
+  }
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Build or update the context index
+ */
+export function buildIndex(options: LoadOptions = {}): ContextIndex {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const projectRoot = cfg?._projectRoot || process.cwd();
+
+  ensureDirectories(projectRoot);
+
+  const index: ContextIndex = {
+    version: '1.0',
+    lastUpdated: new Date().toISOString(),
+    projectRoot: projectRoot,
+    files: [],
+    agents: {}
+  };
+
+  // Index all context files
+  const contextList = list({ config: cfg || undefined });
+  for (const ctx of contextList) {
+    if (ctx.exists) {
+      index.files.push({
+        type: ctx.type,
+        path: ctx.path,
+        isDirectory: ctx.isDirectory || false,
+        fileCount: ctx.fileCount,
+        size: ctx.size,
+        modified: ctx.modified
+      });
+    }
+  }
+
+  // Build agent context mappings
+  for (const [agent, types] of Object.entries(AGENT_CONTEXT_MAP)) {
+    const availableTypes = types.filter(t => {
+      const ctx = contextList.find(c => c.type === t);
+      return ctx && ctx.exists;
+    });
+    index.agents[agent] = availableTypes;
+  }
+
+  // Save index
+  const indexPath = path.join(projectRoot, CONTEXT_LOCATIONS.context_index || '.bootspring/context-index.json');
+  utils.writeFile(indexPath, JSON.stringify(index, null, 2));
+
+  return index;
+}
+
+/**
+ * Load the context index
+ */
+export function loadIndex(options: LoadOptions = {}): ContextIndex | null {
+  const config = getConfig();
+  const utils = getUtils();
+
+  const cfg = options.config || config.load();
+  const projectRoot = cfg?._projectRoot || process.cwd();
+  const indexPath = path.join(projectRoot, CONTEXT_LOCATIONS.context_index || '.bootspring/context-index.json');
+
+  if (!utils.fileExists(indexPath)) {
+    return null;
+  }
+
+  try {
+    const content = utils.readFile(indexPath);
+    if (!content) return null;
+    return JSON.parse(content) as ContextIndex;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get context locations configuration
+ */
+export function getLocations(): Record<string, string> {
+  return { ...CONTEXT_LOCATIONS };
+}
+
+/**
+ * Get agent context mapping
+ */
+export function getAgentMap(): Record<string, string[]> {
+  return { ...AGENT_CONTEXT_MAP };
+}