tlc-claude-code 2.4.10 → 2.5.0

package/server/lib/github/plan-sync.js

@@ -0,0 +1,456 @@
+/**
+ * Plan-to-Issues Sync — Phase 97, Task 3
+ *
+ * Parses PLAN.md task headings, creates GitHub issues + project board items,
+ * writes issue markers back into the plan. Idempotent — safe to re-run.
+ *
+ * All external dependencies (ghClient, ghProjects, fs) are injected.
+ * No silent failures: every catch logs with context or rethrows.
+ *
+ * @module plan-sync
+ */
+
+const nodeFs = require('fs');
+
+// ---------------------------------------------------------------------------
+// Status mapping
+// ---------------------------------------------------------------------------
+
+/** Map plan marker → project board Status option name */
+const STATUS_MAP = {
+  todo: 'Backlog',
+  in_progress: 'In progress',
+  done: 'Done',
+};
+
+// ---------------------------------------------------------------------------
+// Sprint name helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the sprint name from config prefix + phase number.
+ * - prefix "S" + phase 97 → "S97"
+ * - prefix "Phase" + phase 97 → "Phase-97"
+ *
+ * @param {string} prefix - e.g. "S" or "Phase"
+ * @param {number} phaseNumber
+ * @returns {string}
+ */
+function buildSprintName(prefix, phaseNumber) {
+  if (prefix.length <= 1) return `${prefix}${phaseNumber}`;
+  return `${prefix}-${phaseNumber}`;
+}
+
+// ---------------------------------------------------------------------------
+// parsePlanTasks
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a PLAN.md file and extract phase info + tasks.
+ *
+ * Recognises headings like:
+ *   ### Task 1: Title [ ]
+ *   ### Task 2: Title [>@user]
+ *   ### Task 3: Title [x]
+ *   ### Task 4: Title [x@user]
+ *   ### Task 5: Title [ ] <!-- #123 -->
+ *
+ * @param {string} planContent - Raw PLAN.md content
+ * @returns {{ phaseNumber: number, phaseTitle: string, tasks: Array<{ number: number, title: string, status: string, assignee: string|null, issueNumber: number|null }> }}
+ */
+function parsePlanTasks(planContent) {
+  // Extract phase heading: # Phase N: Title ...
+  const phaseMatch = planContent.match(/^#\s+Phase\s+(\d+):\s*(.+?)(?:\s*-\s*Plan)?\s*$/m);
+  const phaseNumber = phaseMatch ? parseInt(phaseMatch[1], 10) : 0;
+  const phaseTitle = phaseMatch ? phaseMatch[2].trim() : 'Unknown';
+
+  // Extract tasks from ### Task N: Title [marker] <!-- #issueNum -->
+  const taskRegex = /^###\s+Task\s+(\d+):\s*(.+?)\s+\[([^\]]*)\](?:\s*<!--\s*#(\d+)\s*-->)?/gm;
+  const tasks = [];
+
+  let match;
+  while ((match = taskRegex.exec(planContent)) !== null) {
+    const number = parseInt(match[1], 10);
+    const title = match[2].trim();
+    const marker = match[3].trim();
+    const issueNumber = match[4] ? parseInt(match[4], 10) : null;
+
+    let status = 'todo';
+    let assignee = null;
+
+    if (marker.startsWith('>@')) {
+      status = 'in_progress';
+      assignee = marker.slice(2);
+    } else if (marker.startsWith('x@')) {
+      status = 'done';
+      assignee = marker.slice(2);
+    } else if (marker === 'x') {
+      status = 'done';
+    }
+    // marker === '' or ' ' → todo (default)
+
+    tasks.push({ number, title, status, assignee, issueNumber });
+  }
+
+  return { phaseNumber, phaseTitle, tasks };
+}
+
+// ---------------------------------------------------------------------------
+// injectIssueMarkers
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject `<!-- #N -->` markers after task headings. Idempotent.
+ *
+ * @param {string} planContent - Raw PLAN.md content
+ * @param {Object<number, number>} taskIssueMap - { taskNumber: issueNumber }
+ * @returns {string} Modified plan content
+ */
+function injectIssueMarkers(planContent, taskIssueMap) {
+  if (!taskIssueMap || Object.keys(taskIssueMap).length === 0) return planContent;
+
+  let result = planContent;
+
+  for (const [taskNum, issueNum] of Object.entries(taskIssueMap)) {
+    // Match the task heading line — with or without an existing marker
+    const regex = new RegExp(
+      `(^###\\s+Task\\s+${taskNum}:\\s*.+?\\s+\\[[^\\]]*\\])(?:\\s*<!--\\s*#\\d+\\s*-->)?\\s*$`,
+      'gm'
+    );
+    result = result.replace(regex, `$1 <!-- #${issueNum} -->`);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// syncPlan
+// ---------------------------------------------------------------------------
+
+/**
+ * Sync a PLAN.md to GitHub issues and project board.
+ *
+ * 1. Read + parse plan
+ * 2. Create parent phase issue if not exists
+ * 3. Create sub-issues for tasks without markers
+ * 4. Add to project board, set Sprint + Status
+ * 5. Write markers back
+ *
+ * @param {Object} params
+ * @param {string} params.planPath - Absolute path to PLAN.md
+ * @param {Object} params.config - Config with github section + owner/repo
+ * @param {Object} params.ghClient - GitHub client (createIssue, closeIssue, listIssues, etc.)
+ * @param {Object} params.ghProjects - Projects client (addItem, setField, findField, etc.)
+ * @param {Object} [params.fs] - fs module (readFileSync, writeFileSync)
+ * @returns {{ created: number, updated: number, skipped: number, errors: string[] }}
+ */
+function syncPlan({ planPath, config, ghClient, ghProjects, fs = nodeFs }) {
+  const result = { created: 0, updated: 0, skipped: 0, errors: [] };
+  const { owner, repo } = config;
+  const ghConfig = config.github;
+
+  // 1. Read + parse
+  let planContent;
+  try {
+    planContent = fs.readFileSync(planPath, 'utf-8');
+  } catch (err) {
+    const msg = `[plan-sync] Failed to read plan at ${planPath}: ${err.message}`;
+    console.error(msg);
+    result.errors.push(msg);
+    return result;
+  }
+
+  const plan = parsePlanTasks(planContent);
+  if (plan.tasks.length === 0) {
+    console.log(`[plan-sync] No tasks found in ${planPath}, nothing to sync`);
+    return result;
+  }
+
+  // 2. Find or create parent phase issue
+  let parentIssueNumber = null;
+  try {
+    const existingIssues = ghClient.listIssues({
+      owner,
+      repo,
+      labels: [`tlc:phase-${plan.phaseNumber}`],
+      state: 'all',
+    });
+
+    if (Array.isArray(existingIssues)) {
+      const existing = existingIssues.find(i =>
+        i.title && i.title.startsWith(`Phase ${plan.phaseNumber}:`)
+      );
+      if (existing) {
+        parentIssueNumber = existing.number;
+      }
+    } else {
+      console.warn(`[plan-sync] listIssues returned non-array: ${existingIssues?.error || 'unknown'}`);
+    }
+  } catch (err) {
+    console.error(`[plan-sync] Failed to check for existing phase issue: ${err.message}`);
+  }
+
+  if (!parentIssueNumber) {
+    const parentResult = ghClient.createIssue({
+      owner,
+      repo,
+      title: `Phase ${plan.phaseNumber}: ${plan.phaseTitle}`,
+      body: `Phase ${plan.phaseNumber} tracking issue.\n\nTasks: ${plan.tasks.length}`,
+      labels: [`tlc:phase-${plan.phaseNumber}`],
+    });
+
+    if (parentResult.error) {
+      const msg = `[plan-sync] Failed to create parent phase issue: ${parentResult.error}`;
+      console.error(msg);
+      result.errors.push(msg);
+    } else {
+      parentIssueNumber = parentResult.number;
+    }
+  }
+
+  // 3. Resolve Sprint field + option
+  const sprintField = ghProjects.findField(ghConfig.sprintField || 'Sprint');
+  const statusField = ghProjects.findField(ghConfig.statusField || 'Status');
+  const sprintName = buildSprintName(ghConfig.phasePrefix || 'Phase', plan.phaseNumber);
+
+  let sprintOptionId = null;
+  if (sprintField) {
+    const existingOption = ghProjects.findOption(sprintField, sprintName);
+    if (existingOption) {
+      sprintOptionId = existingOption.id;
+    } else {
+      // Auto-create sprint option
+      const createResult = ghProjects.createOption({
+        fieldId: sprintField.id,
+        name: sprintName,
+      });
+      if (createResult.error) {
+        const msg = `[plan-sync] Failed to create sprint option "${sprintName}": ${createResult.error}`;
+        console.error(msg);
+        result.errors.push(msg);
+      } else {
+        sprintOptionId = createResult.optionId;
+      }
+    }
+  }
+
+  // 4. Create issues for tasks without markers
+  const taskIssueMap = {};
+
+  for (const task of plan.tasks) {
+    if (task.issueNumber) {
+      result.skipped++;
+      continue;
+    }
+
+    // Create issue for this task
+    const body = parentIssueNumber
+      ? `Part of #${parentIssueNumber}\n\n**[Phase ${plan.phaseNumber}] Task ${task.number}: ${task.title}**`
+      : `**[Phase ${plan.phaseNumber}] Task ${task.number}: ${task.title}**`;
+
+    const issueResult = ghClient.createIssue({
+      owner,
+      repo,
+      title: `[Phase ${plan.phaseNumber}] Task ${task.number}: ${task.title}`,
+      body,
+      labels: [`tlc:phase-${plan.phaseNumber}`, 'tlc:task'],
+    });
+
+    if (issueResult.error) {
+      const msg = `[plan-sync] Failed to create issue for Task ${task.number} "${task.title}": ${issueResult.error}`;
+      console.error(msg);
+      result.errors.push(msg);
+      continue;
+    }
+
+    taskIssueMap[task.number] = issueResult.number;
+    result.created++;
+
+    // Add to project board
+    const contentId = issueResult.id || `I_${issueResult.number}`;
+    const addResult = ghProjects.addItem({ contentId });
+
+    if (addResult.error) {
+      const msg = `[plan-sync] Failed to add issue #${issueResult.number} to project: ${addResult.error}`;
+      console.error(msg);
+      result.errors.push(msg);
+      continue;
+    }
+
+    const itemId = addResult.itemId;
+
+    // Set Sprint field
+    if (sprintField && sprintOptionId && itemId) {
+      const sprintResult = ghProjects.setField({
+        itemId,
+        fieldId: sprintField.id,
+        optionId: sprintOptionId,
+      });
+      if (sprintResult.error) {
+        const msg = `[plan-sync] Failed to set Sprint for issue #${issueResult.number}: ${sprintResult.error}`;
+        console.error(msg);
+        result.errors.push(msg);
+      }
+    }
+
+    // Set Status field
+    if (statusField && itemId) {
+      const statusName = STATUS_MAP[task.status] || 'Backlog';
+      const statusOption = ghProjects.findOption(statusField, statusName);
+      if (statusOption) {
+        const statusResult = ghProjects.setField({
+          itemId,
+          fieldId: statusField.id,
+          optionId: statusOption.id,
+        });
+        if (statusResult.error) {
+          const msg = `[plan-sync] Failed to set Status for issue #${issueResult.number}: ${statusResult.error}`;
+          console.error(msg);
+          result.errors.push(msg);
+        }
+      }
+    }
+
+    // Assign if claimed
+    if (task.assignee) {
+      const assignResult = ghClient.assignIssue({
+        owner,
+        repo,
+        number: issueResult.number,
+        assignees: [task.assignee],
+      });
+      if (assignResult && assignResult.error) {
+        const msg = `[plan-sync] Failed to assign ${task.assignee} to issue #${issueResult.number}: ${assignResult.error}`;
+        console.error(msg);
+        result.errors.push(msg);
+      }
+    }
+  }
+
+  // 5. Write markers back to PLAN.md
+  if (Object.keys(taskIssueMap).length > 0) {
+    try {
+      const updatedContent = injectIssueMarkers(planContent, taskIssueMap);
+      fs.writeFileSync(planPath, updatedContent);
+    } catch (err) {
+      const msg = `[plan-sync] Failed to write markers back to ${planPath}: ${err.message}`;
+      console.error(msg);
+      result.errors.push(msg);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// updateTaskStatuses
+// ---------------------------------------------------------------------------
+
+/**
+ * Lighter sync: only update statuses for tasks with existing issue markers.
+ * No issue creation. For use after /tlc:build marks tasks [x].
+ *
+ * @param {Object} params
+ * @param {string} params.planPath - Absolute path to PLAN.md
+ * @param {Object} params.config - Config with github section + owner/repo
+ * @param {Object} params.ghClient - GitHub client
+ * @param {Object} params.ghProjects - Projects client
+ * @param {Object} [params.fs] - fs module
+ * @returns {{ updated: number, closed: number }}
+ */
+function updateTaskStatuses({ planPath, config, ghClient, ghProjects, fs = nodeFs }) {
+  const result = { updated: 0, closed: 0 };
+  const { owner, repo } = config;
+  const ghConfig = config.github;
+
+  // Read + parse
+  let planContent;
+  try {
+    planContent = fs.readFileSync(planPath, 'utf-8');
+  } catch (err) {
+    console.error(`[plan-sync] Failed to read plan at ${planPath}: ${err.message}`);
+    return { updated: 0, closed: 0, error: 'Failed to read plan file' };
+  }
+
+  const plan = parsePlanTasks(planContent);
+  const tasksWithMarkers = plan.tasks.filter(t => t.issueNumber !== null);
+
+  if (tasksWithMarkers.length === 0) {
+    console.log(`[plan-sync] No tasks with issue markers in ${planPath}, nothing to update`);
+    return result;
+  }
+
+  // Get project items for matching
+  const statusField = ghProjects.findField(ghConfig.statusField || 'Status');
+  const projectItems = ghProjects.getItems() || [];
+
+  for (const task of tasksWithMarkers) {
+    // Find the matching project item by issue number in title
+    const matchingItem = Array.isArray(projectItems)
+      ? projectItems.find(item =>
+        item.title && item.title.includes(`Task ${task.number}:`)
+      )
+      : null;
+
+    // Close issue if done
+    if (task.status === 'done') {
+      const closeResult = ghClient.closeIssue({ owner, repo, number: task.issueNumber });
+      if (closeResult.error) {
+        console.error(`[plan-sync] Failed to close #${task.issueNumber}: ${closeResult.error}`);
+      } else {
+        result.closed++;
+      }
+    }
+
+    // Assign if claimed
+    if (task.assignee) {
+      const assignResult = ghClient.assignIssue({
+        owner,
+        repo,
+        number: task.issueNumber,
+        assignees: [task.assignee],
+      });
+      if (assignResult.error) {
+        console.error(`[plan-sync] Failed to assign #${task.issueNumber}: ${assignResult.error}`);
+      }
+    }
+
+    // Set project Status field
+    if (statusField && matchingItem) {
+      const statusName = STATUS_MAP[task.status] || 'Backlog';
+      const currentStatus = matchingItem.fieldValues && matchingItem.fieldValues.Status;
+
+      if (currentStatus !== statusName) {
+        const statusOption = ghProjects.findOption(statusField, statusName);
+        if (statusOption) {
+          const setResult = ghProjects.setField({
+            itemId: matchingItem.itemId,
+            fieldId: statusField.id,
+            optionId: statusOption.id,
+          });
+          if (setResult.error) {
+            console.error(`[plan-sync] Failed to set Status for issue #${task.issueNumber}: ${setResult.error}`);
+          } else {
+            result.updated++;
+          }
+        }
+      }
+    } else if (task.status !== 'todo') {
+      // Still count as updated if we did something (close/assign) even without project item
+      result.updated++;
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  parsePlanTasks,
+  injectIssueMarkers,
+  syncPlan,
+  updateTaskStatuses,
+};