@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/project-state.js

@@ -0,0 +1,694 @@
+/**
+ * Bootspring Project State
+ * Manages PROJECT_STATE.json in the planning folder
+ * Single source of truth for project checkpoints and state
+ *
+ * @package bootspring
+ * @module core/project-state
+ */
+
+const fs = require('fs');
+const path = require('path');
+const utils = require('./utils');
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const VERSION = '1.0.0';
+const STATE_FILE = 'PROJECT_STATE.json';
+const HISTORY_FILE = 'CHECKPOINT_HISTORY.json';
+const GITHUB_SYNC_FILE = 'GITHUB_SYNC.json';
+const PLANNING_DIR = 'planning';
+
+// Project types
+const PROJECT_TYPES = {
+  DEVELOPMENT: 'development',
+  CONTENT: 'content',
+  BUSINESS: 'business'
+};
+
+// Checkpoints by project type
+const CHECKPOINTS = {
+  development: [
+    { id: 'initialized', label: 'Project Initialized', sourceFile: 'PROJECT_STATE.json', criteria: 'config_exists' },
+    { id: 'prd', label: 'PRD Created', sourceFile: 'PRD.md', criteria: 'file_exists_min_500' },
+    { id: 'technical_spec', label: 'Technical Spec', sourceFile: 'TECHNICAL_SPEC.md', criteria: 'file_exists' },
+    { id: 'architecture', label: 'Architecture Defined', sourceFile: 'ARCHITECTURE.md', criteria: 'file_exists' },
+    { id: 'database_schema', label: 'Database Schema', sourceFile: 'DATABASE_SCHEMA.md', criteria: 'file_exists' },
+    { id: 'api_contracts', label: 'API Contracts', sourceFile: 'API_CONTRACTS.md', criteria: 'file_exists' },
+    { id: 'tests_planned', label: 'Tests Planned', sourceFile: 'TEST_PLAN.md', criteria: 'file_exists' },
+    { id: 'deployed', label: 'Deployed', sourceFile: 'DEPLOYMENT.md', criteria: 'contains_url' },
+    { id: 'github_connected', label: 'GitHub Connected', sourceFile: 'PROJECT_STATE.json', criteria: 'github_connected' }
+  ],
+  content: [
+    { id: 'initialized', label: 'Project Initialized', sourceFile: 'PROJECT_STATE.json', criteria: 'config_exists' },
+    { id: 'content_strategy', label: 'Content Strategy', sourceFile: 'CONTENT_STRATEGY.md', criteria: 'file_exists' },
+    { id: 'editorial_calendar', label: 'Editorial Calendar', sourceFile: 'EDITORIAL_CALENDAR.md', criteria: 'file_exists' },
+    { id: 'style_guide', label: 'Style Guide', sourceFile: 'STYLE_GUIDE.md', criteria: 'file_exists' },
+    { id: 'seo_plan', label: 'SEO Plan', sourceFile: 'SEO_PLAN.md', criteria: 'file_exists' },
+    { id: 'published', label: 'Published', sourceFile: 'PROJECT_STATE.json', criteria: 'content_published' },
+    { id: 'github_connected', label: 'GitHub Connected', sourceFile: 'PROJECT_STATE.json', criteria: 'github_connected' }
+  ],
+  business: [
+    { id: 'initialized', label: 'Project Initialized', sourceFile: 'PROJECT_STATE.json', criteria: 'config_exists' },
+    { id: 'business_plan', label: 'Business Plan', sourceFile: 'BUSINESS_PLAN.md', criteria: 'file_exists' },
+    { id: 'market_analysis', label: 'Market Analysis', sourceFile: 'MARKET_ANALYSIS.md', criteria: 'file_exists' },
+    { id: 'competitor_analysis', label: 'Competitor Analysis', sourceFile: 'COMPETITOR_ANALYSIS.md', criteria: 'file_exists' },
+    { id: 'financial_model', label: 'Financial Model', sourceFile: 'FINANCIAL_MODEL.md', criteria: 'file_exists' },
+    { id: 'pitch_deck', label: 'Pitch Deck', sourceFile: 'PITCH_DECK.md', criteria: 'file_exists' },
+    { id: 'investor_list', label: 'Investor List', sourceFile: 'INVESTOR_LIST.md', criteria: 'file_exists' },
+    { id: 'github_connected', label: 'GitHub Connected', sourceFile: 'PROJECT_STATE.json', criteria: 'github_connected' }
+  ]
+};
+
+// ============================================================================
+// State Management
+// ============================================================================
+
+/**
+ * Get the planning directory path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Planning directory path
+ */
+function getPlanningDir(projectRoot) {
+  return path.join(projectRoot, PLANNING_DIR);
+}
+
+/**
+ * Get the state file path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} State file path
+ */
+function getStateFilePath(projectRoot) {
+  return path.join(getPlanningDir(projectRoot), STATE_FILE);
+}
+
+/**
+ * Get the history file path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} History file path
+ */
+function getHistoryFilePath(projectRoot) {
+  return path.join(getPlanningDir(projectRoot), HISTORY_FILE);
+}
+
+/**
+ * Get the GitHub sync file path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} GitHub sync file path
+ */
+function getGitHubSyncFilePath(projectRoot) {
+  return path.join(getPlanningDir(projectRoot), GITHUB_SYNC_FILE);
+}
+
+/**
+ * Create default state
+ * @param {string} projectType - Project type
+ * @returns {object} Default state object
+ */
+function createDefaultState(projectType = PROJECT_TYPES.DEVELOPMENT) {
+  const now = new Date().toISOString();
+  const checkpoints = {};
+
+  // Initialize all checkpoints as not completed
+  const checkpointDefs = CHECKPOINTS[projectType] || CHECKPOINTS.development;
+  for (const checkpoint of checkpointDefs) {
+    checkpoints[checkpoint.id] = {
+      completed: false,
+      completedAt: null,
+      completedBy: null
+    };
+  }
+
+  // Mark initialized as completed by default
+  checkpoints.initialized = {
+    completed: true,
+    completedAt: now,
+    completedBy: 'system'
+  };
+
+  return {
+    version: VERSION,
+    projectType,
+    autoTagged: false,
+    taggedBy: null,
+    createdAt: now,
+    updatedAt: now,
+    checkpoints,
+    github: {
+      connected: false,
+      repositoryUrl: null,
+      owner: null,
+      repo: null,
+      defaultBranch: null,
+      lastSync: null,
+      stats: {
+        totalCommits: 0,
+        openPRs: 0,
+        closedPRs: 0,
+        contributors: 0,
+        lastCommit: null,
+        lastCommitMessage: null
+      }
+    },
+    health: {
+      score: 0,
+      lastCalculated: null,
+      breakdown: {
+        checkpoints: 0,
+        github: 0,
+        docs: 0,
+        quality: 0
+      }
+    },
+    usage: {
+      currentPeriod: new Date().toISOString().slice(0, 7),
+      contextGenerations: 0,
+      agentInvocations: 0,
+      skillSearches: 0,
+      mcpCalls: 0
+    }
+  };
+}
+
+/**
+ * Load project state
+ * @param {string} projectRoot - Project root directory
+ * @returns {object|null} State object or null if not found
+ */
+function loadState(projectRoot) {
+  const stateFile = getStateFilePath(projectRoot);
+
+  if (!fs.existsSync(stateFile)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(stateFile, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    utils.print.debug(`Error loading state: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save project state
+ * @param {string} projectRoot - Project root directory
+ * @param {object} state - State object to save
+ * @returns {boolean} Success status
+ */
+function saveState(projectRoot, state) {
+  const planningDir = getPlanningDir(projectRoot);
+  const stateFile = getStateFilePath(projectRoot);
+
+  try {
+    // Ensure planning directory exists
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    // Update timestamp
+    state.updatedAt = new Date().toISOString();
+
+    // Write state
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+    return true;
+  } catch (error) {
+    utils.print.debug(`Error saving state: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Initialize project state
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ * @param {string} options.projectType - Project type
+ * @param {boolean} options.autoTagged - Whether auto-tagged
+ * @param {string} options.taggedBy - What triggered the tag
+ * @returns {object} Created state
+ */
+function initState(projectRoot, options = {}) {
+  const projectType = options.projectType || PROJECT_TYPES.DEVELOPMENT;
+  const state = createDefaultState(projectType);
+
+  if (options.autoTagged) {
+    state.autoTagged = true;
+    state.taggedBy = options.taggedBy || null;
+  }
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+/**
+ * Get or create project state
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options for creation if state doesn't exist
+ * @returns {object} State object
+ */
+function getOrCreateState(projectRoot, options = {}) {
+  let state = loadState(projectRoot);
+
+  if (!state) {
+    state = initState(projectRoot, options);
+  }
+
+  return state;
+}
+
+// ============================================================================
+// Checkpoint Management
+// ============================================================================
+
+/**
+ * Get checkpoint definitions for a project type
+ * @param {string} projectType - Project type
+ * @returns {Array} Checkpoint definitions
+ */
+function getCheckpointDefinitions(projectType) {
+  return CHECKPOINTS[projectType] || CHECKPOINTS.development;
+}
+
+/**
+ * Mark a checkpoint as complete
+ * @param {string} projectRoot - Project root directory
+ * @param {string} checkpointId - Checkpoint ID
+ * @param {object} options - Options
+ * @param {string} options.completedBy - Who completed it
+ * @param {string} options.notes - Optional notes
+ * @returns {object|null} Updated state or null on error
+ */
+function completeCheckpoint(projectRoot, checkpointId, options = {}) {
+  const state = loadState(projectRoot);
+
+  if (!state) {
+    return null;
+  }
+
+  const now = new Date().toISOString();
+
+  // Update checkpoint
+  if (!state.checkpoints[checkpointId]) {
+    state.checkpoints[checkpointId] = {};
+  }
+
+  state.checkpoints[checkpointId] = {
+    completed: true,
+    completedAt: now,
+    completedBy: options.completedBy || 'manual'
+  };
+
+  // Save state
+  saveState(projectRoot, state);
+
+  // Record to history
+  recordCheckpointHistory(projectRoot, {
+    checkpointId,
+    completedAt: now,
+    completedBy: options.completedBy || 'manual',
+    notes: options.notes || null
+  });
+
+  return state;
+}
+
+/**
+ * Record checkpoint completion to history
+ * @param {string} projectRoot - Project root directory
+ * @param {object} record - History record
+ */
+function recordCheckpointHistory(projectRoot, record) {
+  const historyFile = getHistoryFilePath(projectRoot);
+  let history = [];
+
+  if (fs.existsSync(historyFile)) {
+    try {
+      history = JSON.parse(fs.readFileSync(historyFile, 'utf-8'));
+    } catch {
+      history = [];
+    }
+  }
+
+  history.push({
+    ...record,
+    timestamp: new Date().toISOString()
+  });
+
+  try {
+    fs.writeFileSync(historyFile, JSON.stringify(history, null, 2), 'utf-8');
+  } catch (error) {
+    utils.print.debug(`Error saving history: ${error.message}`);
+  }
+}
+
+/**
+ * Get checkpoint history
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} History records
+ */
+function getCheckpointHistory(projectRoot) {
+  const historyFile = getHistoryFilePath(projectRoot);
+
+  if (!fs.existsSync(historyFile)) {
+    return [];
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(historyFile, 'utf-8'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get checkpoint progress summary
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Progress summary
+ */
+function getCheckpointProgress(projectRoot) {
+  const state = loadState(projectRoot);
+
+  if (!state) {
+    return {
+      total: 0,
+      completed: 0,
+      percentage: 0,
+      checkpoints: []
+    };
+  }
+
+  const definitions = getCheckpointDefinitions(state.projectType);
+  const checkpoints = definitions.map(def => ({
+    ...def,
+    completed: state.checkpoints[def.id]?.completed || false,
+    completedAt: state.checkpoints[def.id]?.completedAt || null
+  }));
+
+  const completed = checkpoints.filter(c => c.completed).length;
+  const total = checkpoints.length;
+
+  return {
+    total,
+    completed,
+    percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+    checkpoints
+  };
+}
+
+// ============================================================================
+// Project Type Management
+// ============================================================================
+
+/**
+ * Set project type
+ * @param {string} projectRoot - Project root directory
+ * @param {string} projectType - Project type
+ * @param {object} options - Options
+ * @returns {object|null} Updated state
+ */
+function setProjectType(projectRoot, projectType, options = {}) {
+  if (!Object.values(PROJECT_TYPES).includes(projectType)) {
+    return null;
+  }
+
+  let state = loadState(projectRoot);
+
+  if (!state) {
+    state = initState(projectRoot, { projectType, ...options });
+    return state;
+  }
+
+  // If changing type, reset checkpoints
+  if (state.projectType !== projectType) {
+    const definitions = getCheckpointDefinitions(projectType);
+    const oldCheckpoints = state.checkpoints;
+    state.checkpoints = {};
+
+    // Initialize new checkpoints
+    for (const checkpoint of definitions) {
+      // Preserve initialized and github_connected if they exist
+      if ((checkpoint.id === 'initialized' || checkpoint.id === 'github_connected') && oldCheckpoints[checkpoint.id]) {
+        state.checkpoints[checkpoint.id] = oldCheckpoints[checkpoint.id];
+      } else {
+        state.checkpoints[checkpoint.id] = {
+          completed: false,
+          completedAt: null,
+          completedBy: null
+        };
+      }
+    }
+  }
+
+  state.projectType = projectType;
+
+  if (options.autoTagged) {
+    state.autoTagged = true;
+    state.taggedBy = options.taggedBy || null;
+  }
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+/**
+ * Detect project type from files
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Detected project type
+ */
+function detectProjectType(projectRoot) {
+  const planningDir = getPlanningDir(projectRoot);
+
+  // Check for development indicators
+  const devIndicators = [
+    'TECHNICAL_SPEC.md', 'ARCHITECTURE.md', 'DATABASE_SCHEMA.md',
+    'API_CONTRACTS.md', 'TEST_PLAN.md'
+  ];
+  const devCount = devIndicators.filter(f => fs.existsSync(path.join(planningDir, f))).length;
+
+  // Check for content indicators
+  const contentIndicators = [
+    'CONTENT_STRATEGY.md', 'EDITORIAL_CALENDAR.md', 'STYLE_GUIDE.md', 'SEO_PLAN.md'
+  ];
+  const contentCount = contentIndicators.filter(f => fs.existsSync(path.join(planningDir, f))).length;
+
+  // Check for business indicators
+  const businessIndicators = [
+    'BUSINESS_PLAN.md', 'MARKET_ANALYSIS.md', 'COMPETITOR_ANALYSIS.md',
+    'FINANCIAL_MODEL.md', 'PITCH_DECK.md', 'INVESTOR_LIST.md'
+  ];
+  const businessCount = businessIndicators.filter(f => fs.existsSync(path.join(planningDir, f))).length;
+
+  // Return type with most indicators
+  if (contentCount > devCount && contentCount > businessCount) {
+    return PROJECT_TYPES.CONTENT;
+  }
+
+  if (businessCount > devCount && businessCount > contentCount) {
+    return PROJECT_TYPES.BUSINESS;
+  }
+
+  return PROJECT_TYPES.DEVELOPMENT;
+}
+
+// ============================================================================
+// GitHub State Management
+// ============================================================================
+
+/**
+ * Update GitHub state
+ * @param {string} projectRoot - Project root directory
+ * @param {object} githubData - GitHub data
+ * @returns {object|null} Updated state
+ */
+function updateGitHubState(projectRoot, githubData) {
+  const state = getOrCreateState(projectRoot);
+
+  state.github = {
+    ...state.github,
+    ...githubData,
+    lastSync: new Date().toISOString()
+  };
+
+  // Mark github_connected checkpoint if connected
+  if (githubData.connected) {
+    if (!state.checkpoints.github_connected?.completed) {
+      state.checkpoints.github_connected = {
+        completed: true,
+        completedAt: new Date().toISOString(),
+        completedBy: 'github-sync'
+      };
+
+      recordCheckpointHistory(projectRoot, {
+        checkpointId: 'github_connected',
+        completedAt: state.checkpoints.github_connected.completedAt,
+        completedBy: 'github-sync',
+        notes: `Connected to ${githubData.repositoryUrl}`
+      });
+    }
+  }
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+/**
+ * Clear GitHub connection
+ * @param {string} projectRoot - Project root directory
+ * @returns {object|null} Updated state
+ */
+function clearGitHubState(projectRoot) {
+  const state = loadState(projectRoot);
+
+  if (!state) {
+    return null;
+  }
+
+  state.github = {
+    connected: false,
+    repositoryUrl: null,
+    owner: null,
+    repo: null,
+    defaultBranch: null,
+    lastSync: null,
+    stats: {
+      totalCommits: 0,
+      openPRs: 0,
+      closedPRs: 0,
+      contributors: 0,
+      lastCommit: null,
+      lastCommitMessage: null
+    }
+  };
+
+  // Reset github_connected checkpoint
+  if (state.checkpoints.github_connected) {
+    state.checkpoints.github_connected = {
+      completed: false,
+      completedAt: null,
+      completedBy: null
+    };
+  }
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+// ============================================================================
+// Health Score Management
+// ============================================================================
+
+/**
+ * Update health score
+ * @param {string} projectRoot - Project root directory
+ * @param {object} healthData - Health data
+ * @returns {object|null} Updated state
+ */
+function updateHealthScore(projectRoot, healthData) {
+  const state = getOrCreateState(projectRoot);
+
+  state.health = {
+    ...healthData,
+    lastCalculated: new Date().toISOString()
+  };
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+/**
+ * Calculate checkpoint health score
+ * @param {string} projectRoot - Project root directory
+ * @returns {number} Checkpoint score (0-100)
+ */
+function calculateCheckpointScore(projectRoot) {
+  const progress = getCheckpointProgress(projectRoot);
+  return progress.percentage;
+}
+
+// ============================================================================
+// Usage Tracking
+// ============================================================================
+
+/**
+ * Increment usage counter
+ * @param {string} projectRoot - Project root directory
+ * @param {string} metric - Metric to increment
+ * @param {number} count - Amount to increment (default 1)
+ * @returns {object|null} Updated state
+ */
+function incrementUsage(projectRoot, metric, count = 1) {
+  const state = getOrCreateState(projectRoot);
+
+  const currentPeriod = new Date().toISOString().slice(0, 7);
+
+  // Reset counters if new period
+  if (state.usage.currentPeriod !== currentPeriod) {
+    state.usage = {
+      currentPeriod,
+      contextGenerations: 0,
+      agentInvocations: 0,
+      skillSearches: 0,
+      mcpCalls: 0
+    };
+  }
+
+  // Increment counter
+  if (state.usage[metric] !== undefined) {
+    state.usage[metric] += count;
+  }
+
+  saveState(projectRoot, state);
+  return state;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  // Constants
+  VERSION,
+  PROJECT_TYPES,
+  CHECKPOINTS,
+  PLANNING_DIR,
+  STATE_FILE,
+  HISTORY_FILE,
+
+  // Paths
+  getPlanningDir,
+  getStateFilePath,
+  getHistoryFilePath,
+  getGitHubSyncFilePath,
+
+  // State management
+  createDefaultState,
+  loadState,
+  saveState,
+  initState,
+  getOrCreateState,
+
+  // Checkpoint management
+  getCheckpointDefinitions,
+  completeCheckpoint,
+  recordCheckpointHistory,
+  getCheckpointHistory,
+  getCheckpointProgress,
+
+  // Project type
+  setProjectType,
+  detectProjectType,
+
+  // GitHub
+  updateGitHubState,
+  clearGitHubState,
+
+  // Health
+  updateHealthScore,
+  calculateCheckpointScore,
+
+  // Usage
+  incrementUsage
+};