context-planning 0.7.0

package/lib/paths.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * Tiny path resolver for the cp plugin. No external deps.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+function repoRoot() {
+  // walk up from cwd until we find .git or a package.json
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (
+      fs.existsSync(path.join(dir, '.git')) ||
+      fs.existsSync(path.join(dir, '.planning'))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+function planningDir(root = repoRoot()) {
+  return path.join(root, '.planning');
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+  return p;
+}
+
+function pluginRoot() {
+  // bin/cp.js -> ../
+  return path.resolve(__dirname, '..');
+}
+
+function templatePath(name) {
+  return path.join(pluginRoot(), 'templates', name);
+}
+
+function readTemplate(name) {
+  return fs.readFileSync(templatePath(name), 'utf8');
+}
+
+/**
+ * Format a phase number for use in directory names and filename prefixes.
+ * Integer phases get zero-padded to width 2 ("1" -> "01"). Decimal phases
+ * keep their natural form ("2.1" stays "2.1"). Matches GSD conventions.
+ */
+function padPhaseNum(num) {
+  const s = String(num);
+  if (/^\d+$/.test(s)) return s.padStart(2, '0');
+  return s; // decimal like "2.1"
+}
+
+function padPlanNum(num) {
+  return String(num).padStart(2, '0');
+}
+
+/** Slugify a phase name for the directory portion of phases/XX-name. */
+function slugifyPhase(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'phase';
+}
+
+/** "01-foundation" given phase 1, name "Foundation". */
+function phaseDirName(phaseNum, phaseName) {
+  return `${padPhaseNum(phaseNum)}-${slugifyPhase(phaseName)}`;
+}
+
+/** Full path to a phase directory. */
+function phaseDir(phaseNum, phaseName, root = repoRoot()) {
+  return path.join(planningDir(root), 'phases', phaseDirName(phaseNum, phaseName));
+}
+
+/** Filename prefix "01-02" for phase 1, plan 2. */
+function phasePlanPrefix(phaseNum, planNum) {
+  return `${padPhaseNum(phaseNum)}-${padPlanNum(planNum)}`;
+}
+
+/** Full path to a phase plan file: .planning/phases/01-foundation/01-02-PLAN.md */
+function planFile(phaseNum, phaseName, planNum, root = repoRoot()) {
+  return path.join(
+    phaseDir(phaseNum, phaseName, root),
+    `${phasePlanPrefix(phaseNum, planNum)}-PLAN.md`
+  );
+}
+
+/** Full path to a phase summary file. */
+function summaryFile(phaseNum, phaseName, planNum, root = repoRoot()) {
+  return path.join(
+    phaseDir(phaseNum, phaseName, root),
+    `${phasePlanPrefix(phaseNum, planNum)}-SUMMARY.md`
+  );
+}
+
+/** Full path to a phase DESIGN.md file. Resolves the phase dir on disk first
+ *  so callers can pass just the phase number. Returns null if no phase dir. */
+function designFile(phaseNumOrSlug, root = repoRoot()) {
+  const dir = findPhaseDir(phaseNumOrSlug, root);
+  if (!dir) return null;
+  return path.join(dir, 'DESIGN.md');
+}
+
+/** Full path to a phase REVIEW-LOG.md file. Returns null if no phase dir. */
+function reviewLogFile(phaseNumOrSlug, root = repoRoot()) {
+  const dir = findPhaseDir(phaseNumOrSlug, root);
+  if (!dir) return null;
+  return path.join(dir, 'REVIEW-LOG.md');
+}
+
+/** Slugify a milestone name (e.g. "v0.7 Design Capture" -> "v0-7-design-capture"). */
+function milestoneSlug(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'milestone';
+}
+
+/** Full path to a milestone directory: .planning/milestones/<slug>/ */
+function milestoneDir(milestoneName, root = repoRoot()) {
+  return path.join(planningDir(root), 'milestones', milestoneSlug(milestoneName));
+}
+
+/** Full path to a milestone DESIGN.md file. */
+function milestoneDesignFile(milestoneName, root = repoRoot()) {
+  return path.join(milestoneDir(milestoneName, root), 'DESIGN.md');
+}
+
+/** Locate the existing phase dir for a number, scanning the filesystem.
+ *  Accepts either a phase number (e.g. `'3'`, `3`, `'3.1'`) or a full slug
+ *  (e.g. `'03-sharing'`). Returns the absolute path, or null if not found. */
+function findPhaseDir(phaseNumOrSlug, root = repoRoot()) {
+  const phasesRoot = path.join(planningDir(root), 'phases');
+  if (!fs.existsSync(phasesRoot)) return null;
+  const input = String(phaseNumOrSlug);
+  const entries = fs.readdirSync(phasesRoot);
+
+  // Exact dir-name match first (slug case).
+  if (entries.includes(input)) return path.join(phasesRoot, input);
+
+  // Otherwise treat input as a phase number and match by "NN-" prefix.
+  const prefix = padPhaseNum(input) + '-';
+  const hit = entries.find((n) => n.startsWith(prefix));
+  return hit ? path.join(phasesRoot, hit) : null;
+}
+
+/** Quick task dir: .planning/quick/YYYYMMDD-slug/ */
+function quickDirName(slug, date = new Date()) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}${m}${d}-${slug}`;
+}
+
+function quickDir(slug, root = repoRoot(), date = new Date()) {
+  return path.join(planningDir(root), 'quick', quickDirName(slug, date));
+}
+
+module.exports = {
+  repoRoot,
+  planningDir,
+  ensureDir,
+  pluginRoot,
+  templatePath,
+  readTemplate,
+  padPhaseNum,
+  padPlanNum,
+  slugifyPhase,
+  phaseDirName,
+  phaseDir,
+  phasePlanPrefix,
+  planFile,
+  summaryFile,
+  designFile,
+  reviewLogFile,
+  milestoneSlug,
+  milestoneDir,
+  milestoneDesignFile,
+  findPhaseDir,
+  quickDirName,
+  quickDir,
+};

package/lib/provider.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * Workflow provider abstraction (GSD-compatible).
+ *
+ * Reads from `.planning/config.json` (the same file GSD uses) and looks for
+ * cp-specific settings under the top-level `cp` key. GSD ignores unknown
+ * top-level keys, so both tools share the same config file safely.
+ *
+ * If `config.json` doesn't exist, we materialise it from the template (which
+ * includes both GSD's defaults AND the `cp` block).
+ *
+ * If `config.json` exists but lacks the `cp` block (i.e., pure-GSD project),
+ * we merge in the default `cp` block on first read and save it back —
+ * preserving every existing GSD key untouched.
+ *
+ * Detection logic lives in lib/detect.js (v0.5). This module re-exports
+ * the detection functions for back-compat.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { planningDir, repoRoot, readTemplate } = require('./paths');
+const detect = require('./detect');
+const { mergeCpDefaults } = require('./merge');
+
+const CONFIG_NAME = 'config.json';
+
+function configPath(root = repoRoot()) {
+  return path.join(planningDir(root), CONFIG_NAME);
+}
+
+function loadDefaults() {
+  return JSON.parse(readTemplate('config.json'));
+}
+
+/** Return the parsed config, ensuring a `cp` block exists. Writes back if merged. */
+function loadConfig(root = repoRoot()) {
+  const p = configPath(root);
+  const defaults = loadDefaults();
+
+  if (!fs.existsSync(p)) {
+    // No config at all — caller hasn't run `cp init`. Return defaults in-memory;
+    // do NOT write the file from here (init owns that).
+    return defaults;
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to parse ${p}: ${e.message}`);
+  }
+
+  if (!raw.cp) {
+    // Pure-GSD config (or hand-rolled). Merge in the cp defaults non-destructively.
+    raw.cp = defaults.cp;
+    fs.writeFileSync(p, JSON.stringify(raw, null, 2) + '\n');
+    return raw;
+  }
+
+  // v0.5 auto-heal: additive merge of new upstream defaults into existing cp block
+  try {
+    const merged = mergeCpDefaults(raw, defaults);
+    if (merged.changed) {
+      fs.writeFileSync(p, JSON.stringify(merged.cfg, null, 2) + '\n');
+      process.stderr.write(`cp: refreshed .planning/config.json with ${merged.summary}\n`);
+    }
+    return merged.cfg;
+  } catch (e) {
+    // Merge failure — return unmerged config, don't block the command
+    process.stderr.write(`cp: config merge warning: ${e.message}\n`);
+    return raw;
+  }
+}
+
+function saveConfig(cfg, root = repoRoot()) {
+  const p = configPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + '\n');
+  return p;
+}
+
+/** Convenience: read a value from cfg.cp.<path> with safe defaulting. */
+function cpGet(cfg, dotted, fallback) {
+  const v = dotted.split('.').reduce((o, k) => (o == null ? o : o[k]), cfg.cp || {});
+  return v === undefined ? fallback : v;
+}
+
+/** Set cfg.cp.<path> = value. Creates nested objects as needed. */
+function cpSet(cfg, dotted, value) {
+  cfg.cp = cfg.cp || {};
+  const keys = dotted.split('.');
+  let cur = cfg.cp;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') cur[keys[i]] = {};
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Back-compat wrapper: adapts detectProviderAtAnyHarness to the old
+ * detectProvider return shape { name, installed, evidence?, reason? }.
+ * New callers should use detect.detectProviderAtAnyHarness directly.
+ */
+function detectProvider(cfg, name) {
+  const result = detect.detectProviderAtAnyHarness(cfg, name);
+  // Old shape didn't have via/source — strip them for strict back-compat
+  // but the superset is harmless since callers only read known keys.
+  return result;
+}
+
+/**
+ * Resolve a role -> { name, installed, skill, fallback?, primaryMissing? }.
+ */
+function resolveSkill(role, root = repoRoot()) {
+  const cfg = loadConfig(root);
+  const configured = cpGet(cfg, 'workflow_provider', 'superpowers');
+  const fallback = cpGet(cfg, 'behavior.fall_back_to_manual_if_provider_missing', true);
+  const providers = (cfg.cp && cfg.cp.providers) || {};
+
+  const tryProvider = (name) => {
+    const det = detect.detectProviderAtAnyHarness(cfg, name);
+    const skills = (providers[name] && providers[name].skills) || {};
+    return { name, installed: det.installed, skill: skills[role] || null };
+  };
+
+  const primary = tryProvider(configured);
+  if (primary.installed) {
+    return { ...primary, fallback: false };
+  }
+  if (fallback) {
+    const manual = tryProvider('manual');
+    return { ...manual, fallback: true, primaryMissing: configured };
+  }
+  return { ...primary, fallback: false };
+}
+
+/**
+ * Resolve the inline manual prompt for a role. Returns the prompt string, or
+ * null if the manual provider has no prompt for this role.
+ */
+function resolvePrompt(role, root = repoRoot()) {
+  const cfg = loadConfig(root);
+  const manual = (cfg.cp && cfg.cp.providers && cfg.cp.providers.manual) || {};
+  const prompts = manual.prompts || {};
+  return typeof prompts[role] === 'string' ? prompts[role] : null;
+}
+
+module.exports = {
+  CONFIG_NAME,
+  configPath,
+  loadDefaults,
+  loadConfig,
+  saveConfig,
+  cpGet,
+  cpSet,
+  // Back-compat re-exports from detect.js
+  existsAnywhere: detect.existsAnywhere,
+  detectProvider,
+  resolveSkill,
+  resolvePrompt,
+  // New v0.5 detection (re-exported for convenience)
+  detectProviderAtAnyHarness: detect.detectProviderAtAnyHarness,
+  detectAllInstalled: detect.detectAllInstalled,
+};

package/lib/roadmap.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * ROADMAP.md helpers — minimal regex-based operations. Avoids a full markdown
+ * parser; just enough to:
+ *   - List phases ({ num, name, status, plans: [{ id, desc, done }] })
+ *   - Toggle a plan checkbox
+ *   - Recompute the Progress table row for a phase
+ *   - Add a new milestone block
+ *   - Add a new phase block
+ */
+
+const fs = require('fs');
+
+function read(roadmapPath) {
+  return fs.readFileSync(roadmapPath, 'utf8');
+}
+
+function write(roadmapPath, content) {
+  fs.writeFileSync(roadmapPath, content);
+}
+
+/**
+ * Find phase sections. Phase headings look like:
+ *   ### Phase 1: Foundation
+ *   ### Phase 2.1: Hotfix (INSERTED)
+ */
+function listPhases(content) {
+  const phases = [];
+  const headingRe = /^###\s+Phase\s+([\d.]+):\s+(.+?)\s*(?:\(INSERTED\))?\s*$/gm;
+  let match;
+  const matches = [];
+  while ((match = headingRe.exec(content)) !== null) {
+    matches.push({ num: match[1], name: match[2].trim(), index: match.index });
+  }
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : content.length;
+    const block = content.slice(start, end);
+    const plans = [];
+    const planRe = /^\s*-\s+\[([ xX])\]\s+([\d.]+-\d+):\s*(.*)$/gm;
+    let p;
+    while ((p = planRe.exec(block)) !== null) {
+      plans.push({
+        id: p[2],
+        desc: p[3].trim(),
+        done: p[1].toLowerCase() === 'x',
+      });
+    }
+    phases.push({
+      num: matches[i].num,
+      name: matches[i].name,
+      plans,
+      blockStart: start,
+      blockEnd: end,
+    });
+  }
+  return phases;
+}
+
+/**
+ * Toggle a plan checkbox by ID (e.g., "01-02"). Returns updated content.
+ */
+function setPlanDone(content, planId, done = true) {
+  const re = new RegExp(
+    `(^\\s*-\\s+\\[)([ xX])(\\]\\s+${escapeRegex(planId)}:)`,
+    'm'
+  );
+  return content.replace(re, (_m, a, _b, c) => `${a}${done ? 'x' : ' '}${c}`);
+}
+
+/**
+ * Append a new phase block. Caller supplies the full markdown for the section
+ * (starting with `### Phase N: ...`).
+ */
+function appendPhaseBlock(content, phaseBlock) {
+  // Insert before the "## Progress" section if present, else at end.
+  const progressIdx = content.indexOf('\n## Progress');
+  if (progressIdx === -1) {
+    return content.trimEnd() + '\n\n' + phaseBlock.trim() + '\n';
+  }
+  const before = content.slice(0, progressIdx).trimEnd();
+  const after = content.slice(progressIdx);
+  return before + '\n\n' + phaseBlock.trim() + '\n' + after;
+}
+
+/**
+ * Recompute the Progress table. Replaces every existing row with fresh ones
+ * derived from `listPhases`. Idempotent.
+ */
+function rebuildProgressTable(content, milestoneByPhase = {}) {
+  const phases = listPhases(content);
+  const header =
+    '| Phase | Milestone | Plans Complete | Status | Completed |\n' +
+    '|-------|-----------|----------------|--------|-----------|\n';
+  const rows = phases
+    .map((p) => {
+      const total = p.plans.length;
+      const done = p.plans.filter((x) => x.done).length;
+      const status =
+        total === 0
+          ? 'Planned'
+          : done === 0
+          ? 'Not started'
+          : done < total
+          ? 'In progress'
+          : 'Complete';
+      const completed = status === 'Complete' ? new Date().toISOString().slice(0, 10) : '-';
+      const ms = milestoneByPhase[p.num] || '-';
+      return `| ${p.num}. ${p.name} | ${ms} | ${done}/${total} | ${status} | ${completed} |`;
+    })
+    .join('\n');
+
+  const table = header + rows + '\n';
+
+  const sectionRe = /(## Progress[\s\S]*?)(\n(?=## )|$)/;
+  if (sectionRe.test(content)) {
+    return content.replace(sectionRe, `## Progress\n\n${table}$2`);
+  }
+  return content.trimEnd() + '\n\n## Progress\n\n' + table;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  read,
+  write,
+  listPhases,
+  setPlanDone,
+  appendPhaseBlock,
+  rebuildProgressTable,
+};

package/lib/state.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * STATE.md helpers. STATE.md is intentionally tiny (<100 lines). We only need:
+ *   - read / write
+ *   - update "Current Position" block
+ *   - update "Session Continuity" block
+ *   - update progress bar
+ *   - append to "Recent Decisions"
+ */
+
+const fs = require('fs');
+
+function read(p) {
+  return fs.readFileSync(p, 'utf8');
+}
+
+function write(p, content) {
+  fs.writeFileSync(p, content);
+}
+
+function progressBar(percent) {
+  const pct = Math.max(0, Math.min(100, Math.round(percent)));
+  const filled = Math.round(pct / 10);
+  return '[' + '█'.repeat(filled) + '░'.repeat(10 - filled) + '] ' + pct + '%';
+}
+
+/**
+ * Replace a labeled line inside a section. Lines have the shape:
+ *   `Label: value`
+ */
+function replaceLineInSection(content, sectionHeading, label, newValue) {
+  const sectionRe = new RegExp(
+    `(^${escapeRegex(sectionHeading)}\\s*\\n[\\s\\S]*?)(^${escapeRegex(
+      label
+    )}:[^\\n]*$)`,
+    'm'
+  );
+  const replaced = content.replace(
+    sectionRe,
+    (_m, pre) => `${pre}${label}: ${newValue}`
+  );
+  return replaced;
+}
+
+function updatePosition(content, { phase, plan, status, lastActivity, date }) {
+  let next = content;
+  if (phase !== undefined)
+    next = replaceLineInSection(next, '## Current Position', 'Phase', phase);
+  if (plan !== undefined)
+    next = replaceLineInSection(next, '## Current Position', 'Plan', plan);
+  if (status !== undefined)
+    next = replaceLineInSection(next, '## Current Position', 'Status', status);
+  if (lastActivity !== undefined)
+    next = replaceLineInSection(
+      next,
+      '## Current Position',
+      'Last activity',
+      `${date || new Date().toISOString().slice(0, 10)} — ${lastActivity}`
+    );
+  return next;
+}
+
+function updateProgressBar(content, percent) {
+  const bar = progressBar(percent);
+  return content.replace(/^Progress:\s+.*$/m, `Progress: ${bar}`);
+}
+
+function updateSessionContinuity(content, { date, stoppedAt, resumeFile }) {
+  let next = content;
+  if (date !== undefined)
+    next = replaceLineInSection(next, '## Session Continuity', 'Last session', date);
+  if (stoppedAt !== undefined)
+    next = replaceLineInSection(next, '## Session Continuity', 'Stopped at', stoppedAt);
+  if (resumeFile !== undefined)
+    next = replaceLineInSection(next, '## Session Continuity', 'Resume file', resumeFile);
+  return next;
+}
+
+function appendRecentDecision(content, decision) {
+  // Insert as the FIRST bullet under "### Recent Decisions"
+  const re = /(### Recent Decisions\s*\n+(?:<!--[^>]*?-->\s*\n*)?)/;
+  if (!re.test(content)) return content;
+  return content.replace(re, (m) => `${m}- ${decision}\n`);
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  read,
+  write,
+  progressBar,
+  updatePosition,
+  updateProgressBar,
+  updateSessionContinuity,
+  appendRecentDecision,
+};