@ktpartners/dgs-platform 2.8.0 → 3.0.4

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

@@ -0,0 +1,584 @@
+/**
+ * Quick -- Quick workflow lifecycle management
+ *
+ * Two flavors:
+ *   - Product-level quick: ephemeral worktree off main with quick/{slug} branch.
+ *     Full lifecycle: start, complete (rebase+merge+cleanup), abandon (discard).
+ *   - Milestone-context quick: work in existing milestone worktree, no new worktree.
+ *     No complete/abandon -- changes merge with the milestone.
+ *
+ * One active product-level quick at a time per product (planning root).
+ * Stale entries (directory missing) are auto-cleared.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execGit, output, error, loadConfig } = require('./core.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { cmdWorktreesCreate, cmdWorktreesRemove, rebaseAndMerge } = require('./worktrees.cjs');
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Read config.local.json safely.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function _readLocalConfig(cwd) {
+  const localPath = getLocalConfigPath(cwd);
+  try {
+    if (fs.existsSync(localPath)) {
+      return JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+  return {};
+}
+
+/**
+ * Write config.local.json atomically.
+ * @param {string} cwd
+ * @param {object} data
+ */
+function _writeLocalConfig(cwd, data) {
+  const localPath = getLocalConfigPath(cwd);
+  const dir = path.dirname(localPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = localPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmpPath, localPath);
+}
+
+/**
+ * Sanitize a title into a valid slug for branch/worktree naming.
+ * @param {string} title
+ * @returns {string}
+ */
+function _sanitizeSlug(title) {
+  if (!title) return '';
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/, '');
+}
+
+/**
+ * Clear a stale quick entry from config.local.json.
+ * Called when getActiveQuick detects a quick whose worktree directory is missing.
+ * @param {string} cwd
+ * @param {string} project
+ * @param {string} slug
+ * @param {object} localConfig - Already loaded config.local.json object
+ */
+function _clearStaleQuick(cwd, project, slug, localConfig) {
+  if (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  // Clear active_context if it points to this stale quick
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  _writeLocalConfig(cwd, localConfig);
+  process.stderr.write('Warning: Stale quick \'' + slug + '\' auto-cleared (worktree directory missing)\n');
+}
+
+// ─── Exported functions ───────────────────────────────────────────────────────
+
+/**
+ * Detect whether a quick should be product-level or milestone-context.
+ *
+ * @param {string} cwd - Planning root
+ * @param {boolean} forceMain - True if --main flag was passed
+ * @returns {{ mode: 'product'|'milestone-context', activeSlug?: string, activeMilestone?: string }}
+ */
+function detectQuickMode(cwd, forceMain) {
+  if (forceMain) return { mode: 'product' };
+
+  const config = loadConfig(cwd);
+  const localConfig = _readLocalConfig(cwd);
+  const activeContext = localConfig.execution && localConfig.execution.active_context;
+
+  if (!activeContext) return { mode: 'product' };
+
+  // Check if active context is a milestone worktree
+  const project = config.current_project;
+  if (!project) return { mode: 'product' };
+
+  const worktrees = (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) || {};
+  const entry = worktrees[activeContext];
+
+  if (entry && entry.type === 'milestone') {
+    return { mode: 'milestone-context', activeSlug: activeContext, activeMilestone: activeContext };
+  }
+
+  // If active context is a quick or unknown, treat as product-level
+  return { mode: 'product' };
+}
+
+/**
+ * Get the currently active product-level quick, if any.
+ *
+ * @param {string} cwd - Planning root
+ * @returns {{ slug: string, entry: object }|null}
+ */
+function getActiveQuick(cwd) {
+  const config = loadConfig(cwd);
+  const localConfig = _readLocalConfig(cwd);
+  const project = config.current_project;
+  if (!project) return null;
+
+  const worktrees = (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) || {};
+
+  for (const [slug, entry] of Object.entries(worktrees)) {
+    if (entry.type === 'quick') {
+      // Verify directory still exists (stale detection)
+      const repos = entry.repos || {};
+      const paths = Object.values(repos);
+      const anyExists = paths.some(function(p) { return fs.existsSync(p); });
+      if (anyExists) {
+        return { slug: slug, entry: entry };
+      }
+      // Directory missing -- stale entry, auto-clear
+      _clearStaleQuick(cwd, project, slug, localConfig);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Start a product-level quick: guard check, create worktree, set context.
+ *
+ * @param {string} cwd - Planning root
+ * @param {string} title - Quick task title (used for slug and branch)
+ * @param {string|null} mode - 'full', 'debug', or null (plain)
+ * @returns {{ success: boolean, slug?: string, error?: string, activeSlug?: string }}
+ */
+function startProductQuick(cwd, title, mode) {
+  // Guard: one active product-level quick at a time
+  const active = getActiveQuick(cwd);
+  if (active) {
+    return {
+      success: false,
+      error: 'Quick worktree already active: \'' + active.slug + '\'. Complete it (`dgs:complete-quick`), abandon it (`dgs:abandon-quick`), or use `dgs:fast` for trivial fixes.',
+      activeSlug: active.slug,
+    };
+  }
+
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) return { success: false, error: 'No current project set' };
+
+  // Sanitize title to slug
+  const slug = _sanitizeSlug(title);
+  if (!slug) return { success: false, error: 'Cannot create slug from title: ' + title };
+
+  // Create worktree via existing cmdWorktreesCreate
+  // Note: cmdWorktreesCreate calls output() which exits the process.
+  // We need to handle this differently -- call the underlying logic directly.
+  // Since cmdWorktreesCreate calls process.exit via output(), we invoke it
+  // through a subprocess to capture the result.
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    const modeArgs = mode ? ' --mode ' + mode : '';
+    const result = execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees create ' + JSON.stringify(slug) + ' --type quick' + modeArgs,
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+    // Parse output to verify creation
+    const parsed = JSON.parse(result.trim());
+    if (!parsed.created) {
+      return { success: false, error: 'Worktree creation returned unexpected result' };
+    }
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    return { success: false, error: 'Failed to create quick worktree: ' + (stderr || err.message || String(err)) };
+  }
+
+  // Set mode in worktree config entry and set active_context
+  const localConfig = _readLocalConfig(cwd);
+  if (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees
+    && localConfig.projects[project].worktrees[slug]) {
+    localConfig.projects[project].worktrees[slug].mode = mode || null;
+  }
+
+  // Set active_context
+  if (!localConfig.execution) localConfig.execution = {};
+  localConfig.execution.active_context = slug;
+
+  _writeLocalConfig(cwd, localConfig);
+
+  const finalConfig = _readLocalConfig(cwd);
+  const repos =
+    (finalConfig.projects &&
+      finalConfig.projects[project] &&
+      finalConfig.projects[project].worktrees &&
+      finalConfig.projects[project].worktrees[slug] &&
+      finalConfig.projects[project].worktrees[slug].repos) || {};
+  return { success: true, slug: slug, repos: repos };
+}
+
+/**
+ * Complete the active product-level quick: rebase, merge, push, cleanup.
+ *
+ * @param {string} cwd - Planning root
+ * @returns {{ success: boolean, commitCount?: number, slug?: string, error?: string, manualInstructions?: string }}
+ */
+function quickComplete(cwd) {
+  const active = getActiveQuick(cwd);
+  if (!active) {
+    return { success: false, error: 'No active product-level quick to complete. If working in a milestone context, changes are part of the milestone.' };
+  }
+
+  const { slug, entry } = active;
+  const repos = entry.repos || {};
+  const repoNames = Object.keys(repos);
+
+  if (repoNames.length === 0) {
+    return { success: false, error: 'Quick \'' + slug + '\' has no repos tracked' };
+  }
+
+  // Count commits on quick branch vs base_branch for summary
+  let totalCommits = 0;
+  const config = loadConfig(cwd);
+  const baseBranch = config.base_branch || 'main';
+
+  // Rebase and merge each repo
+  for (const repoName of repoNames) {
+    const worktreePath = repos[repoName];
+    const branchName = 'quick/' + slug;
+
+    // Count commits before merge
+    const countResult = execGit(worktreePath, ['rev-list', '--count', baseBranch + '..' + branchName]);
+    if (countResult.exitCode === 0) {
+      totalCommits += parseInt(countResult.stdout.trim(), 10) || 0;
+    }
+
+    const result = rebaseAndMerge(cwd, repoName, slug, { push: true });
+    if (!result.success) {
+      return {
+        success: false,
+        slug: slug,
+        error: result.error,
+        manualInstructions: result.manualInstructions,
+      };
+    }
+  }
+
+  // Cleanup: remove worktree and branch via subprocess
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees remove ' + JSON.stringify(slug),
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+  } catch (err) {
+    process.stderr.write('Warning: Worktree cleanup failed: ' + ((err.stderr || '').toString().trim() || err.message || String(err)) + '\n');
+  }
+
+  // Clear active_context and worktree entry (belt-and-suspenders -- remove should handle this)
+  const localConfig = _readLocalConfig(cwd);
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  const project = config.current_project;
+  if (project && localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  _writeLocalConfig(cwd, localConfig);
+
+  return {
+    success: true,
+    slug: slug,
+    commitCount: totalCommits,
+  };
+}
+
+/**
+ * Abandon the active product-level quick: remove worktree without merging.
+ *
+ * @param {string} cwd - Planning root
+ * @param {boolean} confirmed - Must be true to proceed (workflows handle confirmation UI)
+ * @returns {{ success: boolean, slug?: string, error?: string }}
+ */
+function quickAbandon(cwd, confirmed) {
+  if (!confirmed) {
+    return { success: false, error: 'Abandon not confirmed. Pass confirmed=true to proceed.' };
+  }
+
+  const active = getActiveQuick(cwd);
+  if (!active) {
+    return { success: false, error: 'No active product-level quick to abandon. If working in a milestone context, use complete-milestone instead.' };
+  }
+
+  const { slug } = active;
+
+  // Remove worktree and branch (without merging) via subprocess
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees remove ' + JSON.stringify(slug),
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+  } catch (err) {
+    process.stderr.write('Warning: Worktree removal failed: ' + ((err.stderr || '').toString().trim() || err.message || String(err)) + '\n');
+  }
+
+  // Clear active_context and worktree entry
+  const localConfig = _readLocalConfig(cwd);
+  const config = loadConfig(cwd);
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  const project = config.current_project;
+  if (project && localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  _writeLocalConfig(cwd, localConfig);
+
+  return { success: true, slug: slug };
+}
+
+// ─── CLI command wrappers ─────────────────────────────────────────────────────
+
+/**
+ * CLI handler for `dgs-tools complete-quick` (also `quick-complete` for backward compat).
+ * @param {string} cwd
+ */
+function cmdQuickComplete(cwd) {
+  const result = quickComplete(cwd);
+  if (!result.success) {
+    if (result.manualInstructions) {
+      process.stderr.write(result.manualInstructions + '\n');
+    }
+    error(result.error);
+    return;
+  }
+  output({
+    completed: true,
+    slug: result.slug,
+    commits: result.commitCount,
+    message: 'Quick \'' + result.slug + '\' merged to main (' + result.commitCount + ' commits). Worktree cleaned up. Pushed to origin.',
+  });
+}
+
+/**
+ * CLI handler for `dgs-tools abandon-quick` (also `quick-abandon` for backward compat).
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function cmdQuickAbandon(cwd, args) {
+  const confirmed = args && args.includes('--confirmed');
+  const result = quickAbandon(cwd, confirmed);
+  if (!result.success) {
+    error(result.error);
+    return;
+  }
+  output({
+    abandoned: true,
+    slug: result.slug,
+    message: 'Quick \'' + result.slug + '\' abandoned. Worktree removed.',
+  });
+}
+
+/**
+ * CLI: `dgs-tools quick finalize <quick_id> [flags]`.
+ *
+ * Stages and commits all quick-task artifacts atomically in a single git commit:
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-PLAN.md         (required in non-fast mode)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-SUMMARY.md      (required in non-fast mode)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-CONTEXT.md      (optional)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-VERIFICATION.md (optional)
+ *   - {quickDir}/HISTORY.md                                 (optional)
+ *   - {statePath}                                           (optional)
+ *
+ * In --fast mode the task directory does NOT exist; only STATE.md and optional
+ * HISTORY.md are committed. Commit message: `docs(quick-${quickId}): track fast task`.
+ *
+ * Respects config.commit_docs (skip commit if false). Does NOT call cmdCommit
+ * (which process.exits via output()); uses execGit directly, mirroring the
+ * inline pattern used by cmdPhaseFinalize (phase.cjs ~line 947).
+ *
+ * @param {string} cwd - Planning root (used for config + git cwd unless options.repoCwd)
+ * @param {string} quickId - Quick task id (e.g., '260405-u6b')
+ * @param {object} options - { description, quickDir, statePath, push, repoCwd, fast }
+ * @param {boolean} raw - true to emit raw JSON, false for pretty output
+ */
+function cmdQuickFinalize(cwd, quickId, options, raw) {
+  options = options || {};
+
+  if (!quickId) {
+    error('quick_id required for quick finalize');
+    return;
+  }
+  if (!options.quickDir) {
+    error('--quick-dir required');
+    return;
+  }
+  if (!options.fast && !options.description) {
+    error('--description required (unless --fast)');
+    return;
+  }
+
+  const result = {
+    committed: false,
+    hash: null,
+    files_committed: [],
+    commit_reason: 'unknown',
+  };
+
+  const gitCwd = options.repoCwd || cwd;
+  // Resolve to real path so path.relative works when gitCwd and file paths
+  // cross symlink boundaries (e.g., /tmp vs /private/tmp on macOS).
+  let gitCwdReal = gitCwd;
+  try { gitCwdReal = fs.realpathSync(gitCwd); } catch { /* fallback to gitCwd */ }
+  const toRel = (absPath) => {
+    let p = absPath;
+    try { p = fs.realpathSync(absPath); } catch { /* use original */ }
+    return path.relative(gitCwdReal, p);
+  };
+  const filesToStage = [];
+
+  // In non-fast mode, locate the task directory and enumerate artifacts
+  if (!options.fast) {
+    if (!fs.existsSync(options.quickDir)) {
+      error('task directory not found for quick_id: ' + quickId + ' (quick-dir missing: ' + options.quickDir + ')');
+      return;
+    }
+    let taskDirName = null;
+    try {
+      const entries = fs.readdirSync(options.quickDir);
+      const prefix = quickId + '-';
+      for (const e of entries) {
+        if (e === prefix.replace(/-$/, '')) { continue; }
+        if (e.indexOf(prefix) === 0) {
+          const full = path.join(options.quickDir, e);
+          try {
+            if (fs.statSync(full).isDirectory()) {
+              taskDirName = e;
+              break;
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    } catch { /* ignore */ }
+
+    if (!taskDirName) {
+      error('task directory not found for quick_id: ' + quickId);
+      return;
+    }
+
+    const taskDir = path.join(options.quickDir, taskDirName);
+    const candidates = [
+      path.join(taskDir, quickId + '-PLAN.md'),
+      path.join(taskDir, quickId + '-SUMMARY.md'),
+      path.join(taskDir, quickId + '-CONTEXT.md'),
+      path.join(taskDir, quickId + '-VERIFICATION.md'),
+    ];
+    for (const abs of candidates) {
+      if (fs.existsSync(abs)) {
+        filesToStage.push(toRel(abs));
+      }
+    }
+  }
+
+  // STATE.md (optional — may not exist in some flows)
+  if (options.statePath && fs.existsSync(options.statePath)) {
+    filesToStage.push(toRel(options.statePath));
+  }
+
+  // HISTORY.md at quickDir root (optional — created by archival)
+  const historyPath = path.join(options.quickDir, 'HISTORY.md');
+  if (fs.existsSync(historyPath)) {
+    filesToStage.push(toRel(historyPath));
+  }
+
+  // Honor config.commit_docs — file writes already happened, just skip commit.
+  const config = loadConfig(cwd);
+  if (!config.commit_docs) {
+    result.committed = false;
+    result.commit_reason = 'skipped_commit_docs_false';
+    result.files_committed = [];
+    output(result, raw);
+    return;
+  }
+
+  // Stage + commit atomically (inline execGit — cmdCommit calls output/exit).
+  for (const f of filesToStage) {
+    execGit(gitCwdReal, ['add', f]);
+  }
+  const message = options.fast
+    ? 'docs(quick-' + quickId + '): track fast task'
+    : 'docs(quick-' + quickId + '): ' + options.description;
+  const commitResult = execGit(gitCwdReal, ['commit', '-m', message]);
+  if (commitResult.exitCode !== 0) {
+    const nothing =
+      (commitResult.stdout || '').includes('nothing to commit') ||
+      (commitResult.stderr || '').includes('nothing to commit') ||
+      (commitResult.stdout || '').includes('no changes added') ||
+      (commitResult.stderr || '').includes('no changes added');
+    result.committed = false;
+    result.commit_reason = nothing ? 'nothing_to_commit' : 'commit_failed';
+    if (!nothing) result.commit_error = commitResult.stderr;
+    result.files_committed = [];
+    output(result, raw);
+    return;
+  }
+  const hashResult = execGit(gitCwdReal, ['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 cmdPhaseFinalize)
+  if (options.push) {
+    const syncPush = config.sync_push || 'off';
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushRes = pushAll(gitCwdReal, { 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);
+}
+
+module.exports = {
+  detectQuickMode,
+  getActiveQuick,
+  startProductQuick,
+  quickComplete,
+  quickAbandon,
+  cmdQuickComplete,
+  cmdQuickAbandon,
+  cmdQuickFinalize,
+};