@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/deliver-great-systems/bin/lib/commands.cjs

@@ -4,10 +4,12 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
-const { extractFrontmatter } = require('./frontmatter.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getProjectRoot, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
+const { extractFrontmatter, spliceFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
+const TODO_STATUSES = ['pending', 'done'];
+
 function cmdGenerateSlug(text, raw) {
   if (!text) {
     error('text required for slug generation');
@@ -43,15 +45,62 @@ function cmdCurrentTimestamp(format, raw) {
 }
 
 function cmdListTodos(cwd, area, raw) {
-  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
-
   let count = 0;
   const todos = [];
+  const seenFiles = new Set();
 
+  // Flat-first scan: check todos/ root directory
+  const flatDir = path.join(getPlanningRoot(cwd), 'todos');
   try {
-    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    const flatFiles = fs.readdirSync(flatDir).filter(f => f.endsWith('.md') && !fs.statSync(path.join(flatDir, f)).isDirectory());
+    for (const file of flatFiles) {
+      try {
+        const content = fs.readFileSync(path.join(flatDir, file), 'utf-8');
+
+        // Parse frontmatter status (if present)
+        let status = null;
+        const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+        if (fmMatch) {
+          const statusMatch = fmMatch[1].match(/^status:\s*(.+)$/m);
+          if (statusMatch) status = statusMatch[1].trim();
+        }
+
+        // Only list pending todos (default behavior)
+        if (status && status !== 'pending') continue;
+
+        const createdMatch = content.match(/^created:\s*(.+)$/m);
+        const titleMatch = content.match(/^title:\s*(.+)$/m);
+        const areaMatch = content.match(/^area:\s*(.+)$/m);
+
+        const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
+        if (area && todoArea !== area) continue;
 
+        count++;
+        seenFiles.add(file);
+        todos.push({
+          file,
+          created: createdMatch ? createdMatch[1].trim() : 'unknown',
+          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
+          area: todoArea,
+          status: status || 'pending',
+          path: toPosixPath(path.join(path.relative(cwd, getPlanningRoot(cwd)) || '.', 'todos', file)),
+        });
+      } catch {}
+    }
+  } catch {
+    // Flat directory may not exist
+  }
+
+  // Legacy fallback: check todos/pending/
+  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
+  try {
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
     for (const file of files) {
+      if (seenFiles.has(file)) continue; // Skip if already found in flat directory
+
+      // Legacy fallback warning
+      process.stderr.write(`[DGS] Warning: todo '${file}' found in legacy pending/ directory. Run migration to flatten.\n`);
+
       try {
         const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
         const createdMatch = content.match(/^created:\s*(.+)$/m);
@@ -59,8 +108,6 @@ function cmdListTodos(cwd, area, raw) {
         const areaMatch = content.match(/^area:\s*(.+)$/m);
 
         const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
-
-        // Apply area filter if specified
         if (area && todoArea !== area) continue;
 
         count++;
@@ -69,6 +116,7 @@ function cmdListTodos(cwd, area, raw) {
           created: createdMatch ? createdMatch[1].trim() : 'unknown',
           title: titleMatch ? titleMatch[1].trim() : 'Untitled',
           area: todoArea,
+          status: 'pending',
           path: toPosixPath(path.join(path.relative(cwd, getPlanningRoot(cwd)) || '.', 'todos', 'pending', file)),
         });
       } catch {}
@@ -98,7 +146,13 @@ function cmdVerifyPathExists(cwd, targetPath, raw) {
 }
 
 function cmdHistoryDigest(cwd, raw) {
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+  let phasesDir;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    phasesDir = path.join(cwd, projectRoot, 'phases');
+  } catch {
+    phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+  }
   const digest = { phases: {}, decisions: [], tech_stack: new Set() };
 
   // Collect all phase directories: archived + current
@@ -214,7 +268,22 @@ function cmdResolveModel(cwd, agentType, raw) {
   output(result, raw, model);
 }
 
-function cmdCommit(cwd, message, files, raw, amend, push) {
+/**
+ * Commit staged/unstaged files with an optional push orchestration.
+ *
+ * @param {string} cwd - Planning-root cwd. Config (commit_docs, sync_push,
+ *   current_project, worktree map) is always loaded from this directory.
+ * @param {string} message - Commit message (required unless amend=true).
+ * @param {string[]} files - Paths to stage. Resolved relative to repoCwd
+ *   (or cwd if repoCwd is not set). Defaults to ['.'].
+ * @param {boolean} raw - Emit raw (non-JSON) output.
+ * @param {boolean} amend - Run `git commit --amend --no-edit` instead.
+ * @param {boolean} push - Orchestrate push via pushAll() when sync_push=auto.
+ * @param {string} [repoCwd] - Optional absolute path where git operations run.
+ *   Config loading still uses cwd. Used by fast-path in milestone-context to
+ *   commit in a worktree while loading config from the planning root.
+ */
+function cmdCommit(cwd, message, files, raw, amend, push, repoCwd) {
   if (!message && !amend) {
     error('commit message required');
   }
@@ -228,15 +297,20 @@ function cmdCommit(cwd, message, files, raw, amend, push) {
     return;
   }
 
+  // Resolve git-operation cwd: use repoCwd when provided, otherwise cwd.
+  // Config is always loaded from cwd (planning root); only git exec targets
+  // the worktree filesystem.
+  const gitCwd = repoCwd || cwd;
+
   // Stage files
   const filesToStage = files && files.length > 0 ? files : ['.'];
   for (const file of filesToStage) {
-    execGit(cwd, ['add', file]);
+    execGit(gitCwd, ['add', file]);
   }
 
   // Commit
   const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
-  const commitResult = execGit(cwd, commitArgs);
+  const commitResult = execGit(gitCwd, commitArgs);
   if (commitResult.exitCode !== 0) {
     if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
       const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
@@ -249,7 +323,7 @@ function cmdCommit(cwd, message, files, raw, amend, push) {
   }
 
   // Get short hash
-  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  const hashResult = execGit(gitCwd, ['rev-parse', '--short', 'HEAD']);
   const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
   const result = { committed: true, hash, reason: 'committed' };
 
@@ -276,6 +350,148 @@ function cmdCommit(cwd, message, files, raw, amend, push) {
   output(result, raw, hash || 'committed');
 }
 
+/**
+ * CLI: `plan finalize <phase> <plan> [--plan-name <name>] [--push]`.
+ *
+ * Runs state update-progress + roadmap update-plan-progress + requirements
+ * mark-complete AND commits PLAN.md + SUMMARY.md + tracking files in a single
+ * atomic call. Requirement IDs are auto-extracted from PLAN.md frontmatter.
+ * Plan name resolution order: --plan-name flag > PLAN.md frontmatter plan_name
+ * > "execution" fallback.
+ *
+ * Does NOT call cmdCommit or the existing cmdStateUpdateProgress /
+ * cmdRoadmapUpdatePlanProgress / cmdRequirementsMarkComplete CLIs (all call
+ * output()/exit). Uses their *Internal helpers + execGit directly.
+ */
+function cmdPlanFinalize(cwd, phaseNum, planNum, options, raw) {
+  if (!phaseNum) error('phase number required for plan finalize');
+  if (!planNum) error('plan number required for plan finalize');
+
+  const { stateUpdateProgressInternal } = require('./state.cjs');
+  const { roadmapUpdatePlanProgressInternal } = require('./roadmap.cjs');
+  const { requirementsMarkCompleteInternal } = require('./milestone.cjs');
+
+  // Resolve phase dir via findPhaseInternal (returns phases/NN-name relative path)
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo) error(`Phase ${phaseNum} not found`);
+  const phaseDir = path.join(cwd, phaseInfo.directory);
+
+  // Locate PLAN.md + SUMMARY.md within the phase dir using `${phaseNum}-${planNum}` prefix
+  // phaseInfo.phase_number is the canonical (padded) number e.g. "01".
+  const prefix = `${phaseInfo.phase_number || phaseNum}-${planNum}`;
+  let planPath = null;
+  let summaryPath = null;
+  try {
+    const entries = fs.readdirSync(phaseDir);
+    const planFile = entries.find(f =>
+      f.toLowerCase().startsWith(prefix.toLowerCase()) && /-PLAN\.md$/i.test(f)
+    );
+    const summaryFile = entries.find(f =>
+      f.toLowerCase().startsWith(prefix.toLowerCase()) && /-SUMMARY\.md$/i.test(f)
+    );
+    if (planFile) planPath = path.join(phaseDir, planFile);
+    if (summaryFile) summaryPath = path.join(phaseDir, summaryFile);
+  } catch { /* ignore */ }
+
+  // Extract plan_name + requirements from PLAN.md frontmatter
+  let planName = (options && options.planName) || null;
+  let reqIds = [];
+  if (planPath && fs.existsSync(planPath)) {
+    try {
+      const content = fs.readFileSync(planPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      if (fm) {
+        if (!planName && fm.plan_name) planName = String(fm.plan_name);
+        if (fm.requirements) {
+          reqIds = Array.isArray(fm.requirements)
+            ? fm.requirements.map(String).map(s => s.trim()).filter(Boolean)
+            : String(fm.requirements).replace(/[\[\]]/g, '').split(/[,\s]+/).map(s => s.trim()).filter(Boolean);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  if (!planName) planName = 'execution';
+
+  // Resolve tracking file paths (uses same project-root logic as phase finalize)
+  let projRoot;
+  try { projRoot = require('./core.cjs').getProjectRoot(cwd); } catch { projRoot = '.'; }
+  const roadmapPath = path.join(cwd, projRoot, 'ROADMAP.md');
+  const statePath = path.join(cwd, projRoot, 'STATE.md');
+  const requirementsPath = path.join(cwd, projRoot, 'REQUIREMENTS.md');
+
+  // Run internal updates (each returns { result, ... } without exit)
+  const stateUpdate = stateUpdateProgressInternal(cwd);
+  const roadmapUpdate = roadmapUpdatePlanProgressInternal(cwd, phaseNum);
+  const reqUpdate = reqIds.length > 0
+    ? requirementsMarkCompleteInternal(cwd, reqIds)
+    : { result: { updated: false, marked_complete: [], not_found: [], total: 0 }, reqPath: requirementsPath };
+
+  // Stage all files that exist on disk
+  const candidates = [planPath, summaryPath, statePath, roadmapPath, requirementsPath];
+  const filesToStage = candidates
+    .filter(p => p && fs.existsSync(p))
+    .map(p => path.relative(cwd, p));
+
+  const config = loadConfig(cwd);
+  const result = {
+    phase: phaseNum,
+    plan: planNum,
+    plan_name: planName,
+    state: stateUpdate.result,
+    roadmap: roadmapUpdate.result,
+    requirements: reqUpdate.result,
+    files_committed: [],
+  };
+
+  if (!config.commit_docs) {
+    result.committed = false;
+    result.commit_reason = 'skipped_commit_docs_false';
+    output(result, raw);
+    return;
+  }
+
+  const message = `docs(${phaseNum}-${planNum}): complete ${planName} plan`;
+  for (const f of filesToStage) {
+    execGit(cwd, ['add', f]);
+  }
+  const commitResult = execGit(cwd, ['commit', '-m', message]);
+  if (commitResult.exitCode !== 0) {
+    const nothing =
+      commitResult.stdout.includes('nothing to commit') ||
+      commitResult.stderr.includes('nothing to commit');
+    result.committed = false;
+    result.commit_reason = nothing ? 'nothing_to_commit' : 'commit_failed';
+    if (!nothing) result.commit_error = commitResult.stderr;
+    output(result, raw);
+    return;
+  }
+  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  result.committed = true;
+  result.hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  result.commit_reason = 'committed';
+  result.files_committed = filesToStage;
+
+  // Optional push (same semantics as cmdCommit / cmdPhaseFinalize)
+  if (options && options.push) {
+    const syncPush = config.sync_push || 'off';
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushRes = pushAll(cwd, { force: true });
+        result.pushed = pushRes.ok;
+        result.push_result = pushRes;
+      } catch (err) {
+        result.pushed = false;
+        result.push_result = { ok: false, error: err.message };
+      }
+    } else if (syncPush === 'prompt') {
+      result.needs_push = true;
+    }
+  }
+
+  output(result, raw);
+}
+
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
   if (!summaryPath) {
     error('summary-path required for summary-extract');
@@ -395,8 +611,17 @@ async function cmdWebsearch(query, options, raw) {
 }
 
 function cmdProgressRender(cwd, format, raw) {
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
-  const roadmapPath = path.join(getPlanningRoot(cwd), 'ROADMAP.md');
+  let phasesDir, roadmapPath;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    const projectAbs = path.join(cwd, projectRoot);
+    phasesDir = path.join(projectAbs, 'phases');
+    roadmapPath = path.join(projectAbs, 'ROADMAP.md');
+  } catch {
+    const planRoot = getPlanningRoot(cwd);
+    phasesDir = path.join(planRoot, 'phases');
+    roadmapPath = path.join(planRoot, 'ROADMAP.md');
+  }
   const milestone = getMilestoneInfo(cwd);
 
   const phases = [];
@@ -462,31 +687,88 @@ function cmdProgressRender(cwd, format, raw) {
   }
 }
 
-function cmdTodoComplete(cwd, filename, raw) {
-  if (!filename) {
-    error('filename required for todo complete');
+/**
+ * Set a todo's frontmatter status field (internal helper — throws on error).
+ *
+ * If the todo file has no YAML frontmatter, wraps existing content with a
+ * frontmatter block containing status (and completed_date if status is 'done').
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} filename - Todo filename
+ * @param {string} status - Target status (must be in TODO_STATUSES)
+ * @returns {{ filename: string, previous_status: string, status: string, completed_date?: string }}
+ * @throws {Error} If status is invalid or todo not found
+ */
+function setTodoStatus(cwd, filename, status) {
+  if (!TODO_STATUSES.includes(status)) {
+    throw new Error(`Invalid status: ${status}. Allowed: ${TODO_STATUSES.join(', ')}`);
   }
 
-  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
-  const completedDir = path.join(getPlanningRoot(cwd), 'todos', 'completed');
-  const sourcePath = path.join(pendingDir, filename);
+  // Search in both pending and completed directories
+  const planningRoot = getPlanningRoot(cwd);
+  let todoPath = null;
+  let previousStatus = 'pending';
 
-  if (!fs.existsSync(sourcePath)) {
-    error(`Todo not found: ${filename}`);
+  for (const dir of ['pending', 'completed']) {
+    const candidate = path.join(planningRoot, 'todos', dir, filename);
+    if (fs.existsSync(candidate)) {
+      todoPath = candidate;
+      previousStatus = dir === 'completed' ? 'done' : 'pending';
+      break;
+    }
+  }
+  // Also check flat todos/ directory (future layout)
+  if (!todoPath) {
+    const flat = path.join(planningRoot, 'todos', filename);
+    if (fs.existsSync(flat)) {
+      todoPath = flat;
+      const content = fs.readFileSync(flat, 'utf-8');
+      const fm = extractFrontmatter(content);
+      previousStatus = fm.status || 'pending';
+    }
   }
 
-  // Ensure completed directory exists
-  fs.mkdirSync(completedDir, { recursive: true });
+  if (!todoPath) {
+    throw new Error(`Todo not found: ${filename}`);
+  }
 
-  // Read, add completion timestamp, move
-  let content = fs.readFileSync(sourcePath, 'utf-8');
-  const today = new Date().toISOString().split('T')[0];
-  content = `completed: ${today}\n` + content;
+  let content = fs.readFileSync(todoPath, 'utf-8');
+  const fm = extractFrontmatter(content);
+
+  // Build frontmatter fields
+  fm.status = status;
+  if (status === 'done') {
+    fm.completed_date = new Date().toISOString().split('T')[0];
+  }
+
+  // If file has frontmatter block, splice it; otherwise add one
+  if (content.match(/^---\n/)) {
+    content = spliceFrontmatter(content, fm);
+  } else {
+    // Strip bare "completed: YYYY-MM-DD" line if present (legacy format)
+    content = content.replace(/^completed:\s*\d{4}-\d{2}-\d{2}\n/, '');
+    const yamlStr = reconstructFrontmatter(fm);
+    content = `---\n${yamlStr}\n---\n${content}`;
+  }
+
+  fs.writeFileSync(todoPath, content, 'utf-8');
+
+  const result = { filename, previous_status: previousStatus, status };
+  if (fm.completed_date) result.completed_date = fm.completed_date;
+  return result;
+}
+
+function cmdTodoComplete(cwd, filename, raw) {
+  if (!filename) {
+    error('filename required for todo complete');
+  }
 
-  fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');
-  fs.unlinkSync(sourcePath);
+  // Use setTodoStatus to edit frontmatter status to 'done'
+  // setTodoStatus handles finding the file in flat or legacy directories
+  // and automatically sets completed_date when status is 'done'
+  const result = setTodoStatus(cwd, filename, 'done');
 
-  output({ completed: true, file: filename, date: today }, raw, 'completed');
+  output({ completed: true, file: filename, date: result.completed_date || new Date().toISOString().split('T')[0] }, raw, 'completed');
 }
 
 function cmdScaffold(cwd, type, options, raw) {
@@ -568,6 +850,8 @@ function cmdContextHelp(raw) {
 }
 
 module.exports = {
+  TODO_STATUSES,
+  setTodoStatus,
   cmdGenerateSlug,
   cmdCurrentTimestamp,
   cmdListTodos,
@@ -575,6 +859,7 @@ module.exports = {
   cmdHistoryDigest,
   cmdResolveModel,
   cmdCommit,
+  cmdPlanFinalize,
   cmdSummaryExtract,
   cmdWebsearch,
   cmdProgressRender,