@girardmedia/bootspring 1.2.0 → 2.0.3

package/generators/templates/build-planning.template.js

@@ -0,0 +1,596 @@
+/**
+ * Bootspring Build Planning Templates
+ *
+ * Generates planning artifacts for the autonomous build loop:
+ * - MASTER_PLAN.md - Vision + phases + progress tracker
+ * - TODO.md - Checkbox list by phase
+ * - IMPLEMENTATION_QUEUE.md - Ordered tasks with acceptance criteria
+ * - CONTEXT.md - Condensed context for AI iterations
+ *
+ * @package bootspring
+ * @module generators/templates/build-planning
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate all planning artifacts
+ * @param {string} projectRoot - Project root path
+ * @param {object} docs - Source documents
+ * @param {array} tasks - Extracted tasks
+ * @param {object} options - Generation options
+ * @returns {object} Generated file paths
+ */
+function generateAll(projectRoot, docs, tasks, options = {}) {
+  const planningDir = path.join(projectRoot, 'planning');
+
+  // Ensure planning directory exists
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  const files = {};
+
+  // Generate MASTER_PLAN.md
+  const masterPlan = generateMasterPlan(docs, tasks, options);
+  const masterPlanPath = path.join(planningDir, 'MASTER_PLAN.md');
+  fs.writeFileSync(masterPlanPath, masterPlan);
+  files.masterPlan = masterPlanPath;
+
+  // Generate TODO.md
+  const todo = generateTodo(tasks, options);
+  const todoPath = path.join(planningDir, 'TODO.md');
+  fs.writeFileSync(todoPath, todo);
+  files.todo = todoPath;
+
+  // Generate IMPLEMENTATION_QUEUE.md
+  const queue = generateImplementationQueue(tasks, options);
+  const queuePath = path.join(planningDir, 'IMPLEMENTATION_QUEUE.md');
+  fs.writeFileSync(queuePath, queue);
+  files.implementationQueue = queuePath;
+
+  // Generate CONTEXT.md
+  const context = generateContext(docs, tasks, options);
+  const contextPath = path.join(planningDir, 'CONTEXT.md');
+  fs.writeFileSync(contextPath, context);
+  files.context = contextPath;
+
+  return files;
+}
+
+/**
+ * Generate MASTER_PLAN.md
+ * @param {object} docs - Source documents
+ * @param {array} tasks - Extracted tasks
+ * @param {object} options - Options
+ * @returns {string} MASTER_PLAN.md content
+ */
+function generateMasterPlan(docs, tasks, options = {}) {
+  const projectName = options.projectName || 'Project';
+  const phases = groupByPhase(tasks);
+
+  let content = `# ${projectName} - Master Build Plan
+
+> Generated by Bootspring Autonomous Build System
+> Last Updated: ${new Date().toISOString().split('T')[0]}
+
+---
+
+## Overview
+
+This master plan guides the autonomous build process from foundation to MVP completion.
+Each phase contains specific tasks that will be executed sequentially by the build loop.
+
+---
+
+## Progress Tracker
+
+| Phase | Status | Progress | Tasks |
+|-------|--------|----------|-------|
+`;
+
+  // Add phase progress rows
+  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
+    const completed = phaseTasks.filter(t => t.status === 'completed').length;
+    const total = phaseTasks.length;
+    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+    const status = completed === 0 ? 'Pending' :
+      completed === total ? 'Complete' : 'In Progress';
+
+    content += `| ${formatPhaseName(phaseName)} | ${status} | ${percent}% | ${completed}/${total} |\n`;
+  }
+
+  content += `
+---
+
+## Phases
+
+`;
+
+  // Add phase details
+  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
+    const icon = phaseName === 'foundation' ? '1' :
+      phaseName === 'mvp' ? '2' :
+        phaseName === 'launch' ? '3' : '4';
+
+    content += `### Phase ${icon}: ${formatPhaseName(phaseName)}
+
+`;
+
+    // Group tasks by source
+    const bySource = {};
+    for (const task of phaseTasks) {
+      const source = task.source || 'Manual';
+      if (!bySource[source]) bySource[source] = [];
+      bySource[source].push(task);
+    }
+
+    for (const [source, sourceTasks] of Object.entries(bySource)) {
+      content += `**From ${source}:**\n`;
+      for (const task of sourceTasks) {
+        const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
+        content += `- ${checkbox} ${task.title}\n`;
+      }
+      content += '\n';
+    }
+
+    content += '---\n\n';
+  }
+
+  // Add exit criteria
+  content += `## MVP Exit Criteria
+
+The build loop will exit when:
+
+1. All MVP phase tasks are completed
+2. Quality gates pass (tests, lint, typecheck)
+3. Core user journeys are functional
+4. No critical bugs remain
+
+---
+
+## Build Commands
+
+\`\`\`bash
+# Start the build loop
+bootspring seed build --loop
+
+# Check progress
+bootspring build status
+
+# Pause the build
+bootspring build pause
+
+# Resume building
+bootspring build resume
+
+# View current task
+bootspring build task
+\`\`\`
+
+---
+
+*Generated by [Bootspring](https://bootspring.com) Autonomous Build System*
+`;
+
+  return content;
+}
+
+/**
+ * Generate TODO.md
+ * @param {array} tasks - Extracted tasks
+ * @param {object} options - Options
+ * @returns {string} TODO.md content
+ */
+function generateTodo(tasks, options = {}) {
+  const phases = groupByPhase(tasks);
+  const projectName = options.projectName || 'Project';
+
+  let content = `# ${projectName} - Build Todo
+
+> Checklist for autonomous build completion
+
+---
+
+`;
+
+  for (const [phaseName, phaseTasks] of Object.entries(phases)) {
+    const completed = phaseTasks.filter(t => t.status === 'completed').length;
+    const total = phaseTasks.length;
+    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+    content += `## ${formatPhaseName(phaseName)} (${percent}%)
+
+`;
+
+    for (const task of phaseTasks) {
+      const checkbox = task.status === 'completed' ? '[x]' : '[ ]';
+      content += `- ${checkbox} ${task.title}\n`;
+
+      // Add acceptance criteria as sub-items
+      if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+        for (const criteria of task.acceptanceCriteria.slice(0, 3)) {
+          const subCheckbox = task.status === 'completed' ? '[x]' : '[ ]';
+          content += `  - ${subCheckbox} ${criteria}\n`;
+        }
+      }
+    }
+
+    content += '\n---\n\n';
+  }
+
+  content += `## Progress Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Tasks | ${tasks.length} |
+| Completed | ${tasks.filter(t => t.status === 'completed').length} |
+| Remaining | ${tasks.filter(t => t.status === 'pending').length} |
+| In Progress | ${tasks.filter(t => t.status === 'in_progress').length} |
+
+---
+
+*Updated: ${new Date().toISOString()}*
+`;
+
+  return content;
+}
+
+/**
+ * Generate IMPLEMENTATION_QUEUE.md
+ * @param {array} tasks - Extracted tasks
+ * @param {object} options - Options
+ * @returns {string} IMPLEMENTATION_QUEUE.md content
+ */
+function generateImplementationQueue(tasks, options = {}) {
+  const projectName = options.projectName || 'Project';
+
+  let content = `# ${projectName} - Implementation Queue
+
+> Ordered task queue for autonomous execution
+
+---
+
+## Queue Status
+
+| Position | ID | Task | Phase | Complexity | Status |
+|----------|----|----- |-------|------------|--------|
+`;
+
+  tasks.forEach((task, index) => {
+    const statusIcon = task.status === 'completed' ? 'Done' :
+      task.status === 'in_progress' ? 'Active' :
+        task.status === 'blocked' ? 'Blocked' : 'Pending';
+
+    content += `| ${index + 1} | ${task.id} | ${truncate(task.title, 40)} | ${formatPhaseName(task.phase)} | ${task.estimatedComplexity || 'medium'} | ${statusIcon} |\n`;
+  });
+
+  content += `
+---
+
+## Task Details
+
+`;
+
+  for (const task of tasks) {
+    content += `### ${task.id}: ${task.title}
+
+**Phase:** ${formatPhaseName(task.phase)}
+**Source:** ${task.source || 'Manual'} ${task.sourceSection ? `(${task.sourceSection})` : ''}
+**Complexity:** ${task.estimatedComplexity || 'medium'}
+**Status:** ${task.status || 'pending'}
+
+`;
+
+    if (task.description) {
+      content += `**Description:**
+${task.description}
+
+`;
+    }
+
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      content += `**Acceptance Criteria:**
+${task.acceptanceCriteria.map(c => `- [ ] ${c}`).join('\n')}
+
+`;
+    }
+
+    if (task.dependencies && task.dependencies.length > 0) {
+      content += `**Dependencies:** ${task.dependencies.join(', ')}
+
+`;
+    }
+
+    content += '---\n\n';
+  }
+
+  content += `## Execution Guidelines
+
+1. **One Task at a Time** - Complete each task fully before moving on
+2. **Quality Gates** - Run tests, lint, and typecheck before marking complete
+3. **Commit Per Task** - Create meaningful commits for each completed task
+4. **Update Status** - Mark tasks complete in BUILD_STATE.json
+5. **Document Changes** - Update CLAUDE.md with new patterns/decisions
+
+---
+
+*Generated by Bootspring*
+`;
+
+  return content;
+}
+
+/**
+ * Generate CONTEXT.md
+ * @param {object} docs - Source documents
+ * @param {array} tasks - Extracted tasks
+ * @param {object} options - Options
+ * @returns {string} CONTEXT.md content
+ */
+function generateContext(docs, tasks, options = {}) {
+  const projectName = options.projectName || 'Project';
+  const techStack = options.techStack || extractTechStack(docs);
+
+  let content = `# ${projectName} - Build Context
+
+> Condensed context for AI build iterations
+> Read this file at the start of each build task
+
+---
+
+## Project Identity
+
+**Name:** ${projectName}
+${options.tagline ? `**Tagline:** ${options.tagline}` : ''}
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Framework | ${techStack.framework || 'Next.js'} |
+| Language | ${techStack.language || 'TypeScript'} |
+| Database | ${techStack.database || 'PostgreSQL'} |
+| ORM | ${techStack.orm || 'Prisma'} |
+| UI | ${techStack.uiLibrary || 'shadcn/ui'} |
+| Styling | ${techStack.styling || 'Tailwind CSS'} |
+| Auth | ${techStack.auth || 'Clerk'} |
+| Hosting | ${techStack.hosting || 'Vercel'} |
+
+---
+
+## Current Build Status
+
+**Phase:** ${options.currentPhase || 'MVP'}
+**Tasks Remaining:** ${tasks.filter(t => t.status !== 'completed').length}
+**Tasks Completed:** ${tasks.filter(t => t.status === 'completed').length}
+
+---
+
+## Key Decisions
+
+`;
+
+  // Add any decisions from docs
+  if (docs.TECHNICAL_SPEC || docs.technical_spec) {
+    content += `### Architecture
+- Use Server Components by default
+- Prefer Server Actions over API routes for mutations
+- Use Zod for input validation
+- Never expose API keys to client
+
+`;
+  }
+
+  content += `### Code Style
+- TypeScript strict mode enabled
+- ESLint + Prettier for formatting
+- Conventional commits (feat:, fix:, docs:, refactor:)
+- Keep files under 300 lines
+
+---
+
+## MVP Features
+
+`;
+
+  // Extract unique MVP features
+  const mvpTasks = tasks.filter(t => t.phase === 'mvp');
+  const uniqueFeatures = [...new Set(mvpTasks.map(t => t.title))].slice(0, 10);
+
+  uniqueFeatures.forEach((feature, i) => {
+    content += `${i + 1}. ${feature}\n`;
+  });
+
+  content += `
+---
+
+## File Structure
+
+\`\`\`
+${projectName.toLowerCase().replace(/\s+/g, '-')}/
+├── app/                    # Next.js App Router
+│   ├── (auth)/             # Auth pages
+│   ├── (dashboard)/        # Main dashboard
+│   ├── (marketing)/        # Landing pages
+│   └── api/                # API routes
+├── components/
+│   ├── ui/                 # UI components
+│   └── [feature]/          # Feature components
+├── lib/
+│   ├── db.ts               # Database client
+│   ├── auth.ts             # Auth utilities
+│   └── utils.ts            # Helpers
+├── prisma/
+│   └── schema.prisma       # Database schema
+├── planning/               # Build planning (this folder)
+└── public/                 # Static assets
+\`\`\`
+
+---
+
+## Build Loop Rules
+
+When executing a task:
+
+1. **Read CLAUDE.md** - Understand project patterns
+2. **Check BUILD_STATE.json** - Know current task and status
+3. **Implement ONE task** - Focus on the current task only
+4. **Run quality checks** - \`npm run lint && npm run test\`
+5. **Commit changes** - Use conventional commits
+6. **Update status** - Mark task complete in BUILD_STATE.json
+
+---
+
+## Exit Signals
+
+Output these signals for loop control:
+
+\`\`\`
+<loop-status>TASK_COMPLETE</loop-status>    # Task done successfully
+<loop-status>TASK_BLOCKED</loop-status>     # Cannot complete, needs help
+<loop-status>ALL_COMPLETE</loop-status>     # All MVP tasks done
+EXIT_SIGNAL                                  # Stop the loop
+\`\`\`
+
+---
+
+*This context is refreshed at the start of each build iteration*
+`;
+
+  return content;
+}
+
+/**
+ * Group tasks by phase
+ * @param {array} tasks - Tasks to group
+ * @returns {object} Tasks grouped by phase
+ */
+function groupByPhase(tasks) {
+  const phases = {
+    foundation: [],
+    mvp: [],
+    launch: [],
+    other: []
+  };
+
+  for (const task of tasks) {
+    const phase = task.phase || 'other';
+    if (phases[phase]) {
+      phases[phase].push(task);
+    } else {
+      phases.other.push(task);
+    }
+  }
+
+  // Remove empty phases
+  for (const [key, value] of Object.entries(phases)) {
+    if (value.length === 0) {
+      delete phases[key];
+    }
+  }
+
+  return phases;
+}
+
+/**
+ * Format phase name for display
+ * @param {string} phase - Phase name
+ * @returns {string} Formatted name
+ */
+function formatPhaseName(phase) {
+  if (!phase) return 'Other';
+
+  const names = {
+    foundation: 'Foundation',
+    mvp: 'MVP',
+    launch: 'Launch',
+    other: 'Other'
+  };
+
+  return names[phase] || phase.charAt(0).toUpperCase() + phase.slice(1);
+}
+
+/**
+ * Truncate string to max length
+ * @param {string} str - String to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated string
+ */
+function truncate(str, maxLength) {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Extract tech stack from docs
+ * @param {object} docs - Source documents
+ * @returns {object} Tech stack
+ */
+function extractTechStack(docs) {
+  const techDoc = docs.TECHNICAL_SPEC || docs.technical_spec || '';
+  const seedDoc = docs.SEED || docs.seed || '';
+  const allDocs = techDoc + seedDoc;
+
+  const stack = {
+    framework: 'nextjs',
+    language: 'typescript',
+    database: 'postgresql',
+    orm: 'prisma',
+    uiLibrary: 'shadcn',
+    styling: 'tailwind',
+    auth: 'clerk',
+    hosting: 'vercel'
+  };
+
+  // Framework detection
+  if (allDocs.match(/Next\.?js/i)) stack.framework = 'Next.js';
+  else if (allDocs.match(/Remix/i)) stack.framework = 'Remix';
+  else if (allDocs.match(/Nuxt/i)) stack.framework = 'Nuxt';
+
+  // Database
+  if (allDocs.match(/Postgres|PostgreSQL/i)) stack.database = 'PostgreSQL';
+  else if (allDocs.match(/MongoDB/i)) stack.database = 'MongoDB';
+  else if (allDocs.match(/Supabase/i)) stack.database = 'Supabase';
+
+  // Auth
+  if (allDocs.match(/\bClerk\b/i)) stack.auth = 'Clerk';
+  else if (allDocs.match(/NextAuth|Auth\.js/i)) stack.auth = 'NextAuth';
+
+  return stack;
+}
+
+/**
+ * Update planning files with current state
+ * @param {string} projectRoot - Project root path
+ * @param {object} state - Current build state
+ */
+function updateFromState(projectRoot, state) {
+  if (!state || !state.implementationQueue) return;
+
+  const tasks = state.implementationQueue;
+  const planningDir = path.join(projectRoot, 'planning');
+
+  // Regenerate TODO.md with current status
+  const todo = generateTodo(tasks, { projectName: state.projectName });
+  fs.writeFileSync(path.join(planningDir, 'TODO.md'), todo);
+
+  // Regenerate IMPLEMENTATION_QUEUE.md
+  const queue = generateImplementationQueue(tasks, { projectName: state.projectName });
+  fs.writeFileSync(path.join(planningDir, 'IMPLEMENTATION_QUEUE.md'), queue);
+}
+
+module.exports = {
+  generateAll,
+  generateMasterPlan,
+  generateTodo,
+  generateImplementationQueue,
+  generateContext,
+  groupByPhase,
+  formatPhaseName,
+  updateFromState
+};