context-planning 0.7.0

package/lib/detect.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * Harness × provider detection engine (v0.5).
+ *
+ * Scans harness plugin_roots for provider plugin_shape matches, with
+ * fallback to legacy detect.any_of literal sentinels. All filesystem
+ * reads happen at call time — no caching.
+ *
+ * Trailing-* glob: `~/.copilot/installed-plugins/⁕/` expands to the
+ * immediate child directories of the parent. No full minimatch — the
+ * "zero deps in lib/" constraint from PROJECT.md stays honoured.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { repoRoot } = require('./paths');
+
+// ───────────────────────── tilde + trailing-* expansion ─────────────────
+
+/**
+ * Expand a root spec with tilde and trailing-* support.
+ *
+ * Rules:
+ *  - Leading `~/` replaced with os.homedir().
+ *  - If no `*` in the string → literal: return [abs] if exists, else [].
+ *  - First path segment containing `*` is expanded via readdirSync of
+ *    its parent, keeping only directories. Remaining segments are
+ *    appended verbatim.
+ *
+ * Returns string[] (may be empty).
+ */
+function expandRoot(rootSpec) {
+  let spec = rootSpec;
+
+  // Tilde expansion
+  if (spec.startsWith('~/') || spec.startsWith('~\\')) {
+    spec = path.join(os.homedir(), spec.slice(2));
+  }
+  spec = path.normalize(spec);
+
+  // Find first segment with a wildcard
+  const segments = spec.split(path.sep);
+  const wildIdx = segments.findIndex((s) => s.includes('*'));
+
+  if (wildIdx < 0) {
+    // Literal path — no glob
+    return fs.existsSync(spec) ? [spec] : [];
+  }
+
+  // Build parent from segments before the wildcard
+  const parentSegments = segments.slice(0, wildIdx);
+  const parent = parentSegments.join(path.sep) || path.sep;
+
+  if (!fs.existsSync(parent)) return [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(parent, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const pattern = segments[wildIdx]; // e.g. '*' or 'sp-*'
+  const dirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => matchSegment(name, pattern));
+
+  // Remaining segments after the wildcard
+  const rest = segments.slice(wildIdx + 1);
+
+  const results = [];
+  for (const d of dirs) {
+    const candidate = path.join(parent, d, ...rest);
+    // Only include if the full expanded path exists
+    if (fs.existsSync(candidate)) {
+      results.push(candidate);
+    }
+  }
+  return results;
+}
+
+/**
+ * Match a directory name against a simple wildcard pattern.
+ * Only supports `*` as "match anything" (not `?`, `[...]`, etc.).
+ * Examples: `*` matches all, `sp-*` matches `sp-foo`, `*-mkt` matches `abc-mkt`.
+ */
+function matchSegment(name, pattern) {
+  if (pattern === '*') return true;
+  // Convert to a regex: escape everything except *, replace * with .*
+  const re = new RegExp(
+    '^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$'
+  );
+  return re.test(name);
+}
+
+// ───────────────────────── legacy literal sentinel search ───────────────
+
+/**
+ * Search the 5 standard base directories for a literal sentinel path.
+ * Preserved for back-compat with detect.any_of entries.
+ */
+function existsAnywhere(candidate) {
+  const home = os.homedir();
+  const root = repoRoot();
+  const tries = [
+    path.join(root, candidate),
+    path.join(home, candidate),
+    path.join(home, '.claude', candidate),
+    path.join(home, '.github', candidate),
+    path.join(home, '.copilot', candidate),
+  ];
+  return tries.find((t) => fs.existsSync(t)) || null;
+}
+
+// ───────────────────────── per-provider detection ──────────────────────
+
+/**
+ * Detect whether a single provider is installed across any harness.
+ *
+ * Lookup order (first hit wins):
+ *  1. plugin_shape match: for each harness, expand plugin_roots, look for
+ *     a child dir matching plugin_shape.dir_name, verify required_subdirs.
+ *  2. Legacy detect.any_of literal sentinels via existsAnywhere().
+ *  3. detect.always === true (manual provider).
+ *
+ * Returns { name, installed, via?, source?, evidence?, reason? }
+ */
+function detectProviderAtAnyHarness(cfg, providerName) {
+  const providers = (cfg.cp && cfg.cp.providers) || {};
+  const provider = providers[providerName];
+  if (!provider) return { name: providerName, installed: false, reason: 'unknown provider' };
+
+  const det = provider.detect || {};
+
+  // always:true shortcut (manual provider)
+  if (det.always === true) {
+    return { name: providerName, installed: true, via: '_builtin', source: 'always' };
+  }
+
+  // 1. plugin_shape detection via harnesses
+  const shape = provider.plugin_shape;
+  if (shape && shape.dir_name) {
+    const harnesses = (cfg.cp && cfg.cp.harnesses) || {};
+    for (const [harnessName, harness] of Object.entries(harnesses)) {
+      const roots = harness.plugin_roots || [];
+      for (const rootSpec of roots) {
+        const expanded = expandRoot(rootSpec);
+        for (const expandedRoot of expanded) {
+          const pluginDir = path.join(expandedRoot, shape.dir_name);
+          if (fs.existsSync(pluginDir)) {
+            // Verify required_subdirs
+            const subdirs = Array.isArray(shape.required_subdirs) ? shape.required_subdirs : [];
+            const allPresent = subdirs.every((sub) =>
+              fs.existsSync(path.join(pluginDir, sub))
+            );
+            if (allPresent) {
+              return {
+                name: providerName,
+                installed: true,
+                via: harnessName,
+                source: 'plugin_shape',
+                evidence: pluginDir,
+              };
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // 2. Legacy literal sentinel fallback
+  const candidates = det.any_of || [];
+  for (const c of candidates) {
+    const hit = existsAnywhere(c);
+    if (hit) {
+      return {
+        name: providerName,
+        installed: true,
+        via: '_anywhere',
+        source: 'literal',
+        evidence: hit,
+      };
+    }
+  }
+
+  return { name: providerName, installed: false, reason: 'no sentinel matched' };
+}
+
+// ───────────────────────── full scan ───────────────────────────────────
+
+/**
+ * Scan all harnesses × all providers and return a full detection report.
+ *
+ * Returns {
+ *   harnesses: [{ name, scannedRoots: [{ root, expanded }], pluginCount }],
+ *   providers: [{ name, installed, hits: [{ via, source, evidence }] }]
+ * }
+ */
+function detectAllInstalled(cfg) {
+  const harnesses = (cfg.cp && cfg.cp.harnesses) || {};
+  const providers = (cfg.cp && cfg.cp.providers) || {};
+
+  // Harness scan
+  const harnessReports = [];
+  for (const [name, harness] of Object.entries(harnesses)) {
+    const roots = harness.plugin_roots || [];
+    const scannedRoots = [];
+    let pluginCount = 0;
+    for (const rootSpec of roots) {
+      const expanded = expandRoot(rootSpec);
+      scannedRoots.push({ root: rootSpec, expanded });
+      pluginCount += expanded.length;
+    }
+    harnessReports.push({ name, scannedRoots, pluginCount });
+  }
+
+  // Provider scan — collect ALL hits (not just first)
+  const providerReports = [];
+  for (const providerName of Object.keys(providers)) {
+    const provider = providers[providerName];
+    const det = provider.detect || {};
+    const hits = [];
+
+    // always:true
+    if (det.always === true) {
+      hits.push({ via: '_builtin', source: 'always', evidence: null });
+    } else {
+      // plugin_shape across harnesses
+      const shape = provider.plugin_shape;
+      if (shape && shape.dir_name) {
+        for (const [harnessName, harness] of Object.entries(harnesses)) {
+          const roots = harness.plugin_roots || [];
+          for (const rootSpec of roots) {
+            const expanded = expandRoot(rootSpec);
+            for (const expandedRoot of expanded) {
+              const pluginDir = path.join(expandedRoot, shape.dir_name);
+              if (fs.existsSync(pluginDir)) {
+                const subdirs = Array.isArray(shape.required_subdirs) ? shape.required_subdirs : [];
+                const allPresent = subdirs.every((sub) =>
+                  fs.existsSync(path.join(pluginDir, sub))
+                );
+                if (allPresent) {
+                  hits.push({ via: harnessName, source: 'plugin_shape', evidence: pluginDir });
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Legacy literal sentinels
+      const candidates = det.any_of || [];
+      for (const c of candidates) {
+        const hit = existsAnywhere(c);
+        if (hit) {
+          hits.push({ via: '_anywhere', source: 'literal', evidence: hit });
+        }
+      }
+    }
+
+    providerReports.push({
+      name: providerName,
+      installed: hits.length > 0,
+      hits,
+    });
+  }
+
+  return { harnesses: harnessReports, providers: providerReports };
+}
+
+module.exports = {
+  expandRoot,
+  matchSegment,
+  existsAnywhere,
+  detectProviderAtAnyHarness,
+  detectAllInstalled,
+};

package/lib/frontmatter.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * YAML frontmatter reader/writer. Backed by the `yaml` package so it handles
+ * the full GSD frontmatter shape (nested maps, lists, list-of-maps, inline
+ * flow `[]` / `{}`, quoted strings, multiline literals, etc.).
+ *
+ * Returns `{ frontmatter, body }` for compatibility with earlier callers.
+ */
+
+const yaml = require('yaml');
+
+const FENCE = '---';
+
+function split(content) {
+  if (!content.startsWith(FENCE)) {
+    return { fmText: '', body: content };
+  }
+  // First fence line, then locate the closing fence on its own line.
+  const after = content.slice(FENCE.length);
+  // Allow optional leading newline / whitespace after opening fence.
+  const m = after.match(/^[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
+  if (!m) return { fmText: '', body: content };
+  const fmText = m[1];
+  const body = after.slice(m[0].length);
+  return { fmText, body };
+}
+
+function parse(content) {
+  const { fmText, body } = split(content);
+  let frontmatter = {};
+  let parseError = null;
+  if (fmText.trim()) {
+    try {
+      const parsed = yaml.parse(fmText);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        frontmatter = parsed;
+      }
+    } catch (e) {
+      // Preserve body for lenient callers but surface the error so strict
+      // callers (e.g. `cp gsd-import`'s auditor) can report it.
+      frontmatter = {};
+      parseError = e.message || String(e);
+    }
+  }
+  return { frontmatter, body, parseError };
+}
+
+function stringify(frontmatter, body) {
+  const dumped = yaml
+    .stringify(frontmatter || {}, {
+      lineWidth: 0, // never wrap
+      defaultStringType: 'PLAIN',
+      defaultKeyType: 'PLAIN',
+    })
+    .replace(/\n$/, ''); // yaml.stringify always ends in a newline
+  return `${FENCE}\n${dumped}\n${FENCE}\n${body || ''}`;
+}
+
+/** Get a single top-level frontmatter key. */
+function get(content, key) {
+  return parse(content).frontmatter[key];
+}
+
+/** Set a single top-level frontmatter key, returning the updated content. */
+function set(content, key, value) {
+  const { frontmatter, body } = parse(content);
+  frontmatter[key] = value;
+  return stringify(frontmatter, body);
+}
+
+module.exports = { parse, stringify, get, set };

package/lib/gsd-compat.js

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * GSD compatibility helpers.
+ *
+ * cp's state-document format is a SUPERSET of GSD's: same filenames, same
+ * frontmatter keys, plus cp-specific behavior driven by a `cp` block inside
+ * `.planning/config.json` (which GSD ignores as an unknown top-level key).
+ *
+ * This module:
+ *   - Detects whether a project was created/managed by GSD.
+ *   - Detects whether a project's .planning/ is already cp-aware.
+ *   - Reports interop diagnostics for `cp doctor`.
+ *
+ * No mutating helpers — repairs are user-initiated via `cp config set` or
+ * dedicated commands (eventually `cp gsd-import`).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { planningDir, repoRoot } = require('./paths');
+
+/** Sentinel files/dirs that strongly indicate "this is a GSD project".
+ *  These are things GSD creates but cp does NOT. Items removed over time:
+ *  - MILESTONES.md — cp also writes it (via `cp init` + `cp complete-milestone`).
+ *  - .planning/codebase — cp also writes it (via `cp scaffold-codebase` /
+ *    /cp-map-codebase, v0.3.2+).
+ *  - Short-form PLAN.md / SUMMARY.md — cp emits these by design (v0.3+). */
+const GSD_SENTINELS = [
+  '.planning/research',
+  '.planning/todos',
+  '.planning/seeds',
+  '.planning/REQUIREMENTS.md',
+  '.planning/DEBUG.md',
+  '.planning/SECURITY.md',
+];
+
+const SHARED_FILES = [
+  '.planning/PROJECT.md',
+  '.planning/ROADMAP.md',
+  '.planning/STATE.md',
+  '.planning/config.json',
+];
+
+function fileExists(rel, root) {
+  return fs.existsSync(path.join(root, rel));
+}
+
+/** True if .planning/ exists at all. */
+function hasPlanning(root = repoRoot()) {
+  return fs.existsSync(planningDir(root));
+}
+
+/** True if any of the GSD-only sentinels exist. */
+function isGsdProject(root = repoRoot()) {
+  return GSD_SENTINELS.some((s) => fileExists(s, root));
+}
+
+/** True if the merged config has a `cp` block (i.e., cp-initialised). */
+function isCpAware(root = repoRoot()) {
+  const cfg = path.join(planningDir(root), 'config.json');
+  if (!fs.existsSync(cfg)) return false;
+  try {
+    const c = JSON.parse(fs.readFileSync(cfg, 'utf8'));
+    return !!(c && typeof c === 'object' && c.cp && typeof c.cp === 'object');
+  } catch {
+    return false;
+  }
+}
+
+/** Find shared files that are present. */
+function presentSharedFiles(root = repoRoot()) {
+  return SHARED_FILES.filter((s) => fileExists(s, root));
+}
+
+/** Find phase dirs scanned from .planning/phases/. */
+function scanPhases(root = repoRoot()) {
+  const phasesDir = path.join(planningDir(root), 'phases');
+  if (!fs.existsSync(phasesDir)) return [];
+  return fs
+    .readdirSync(phasesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const dir = path.join(phasesDir, e.name);
+      const files = fs.readdirSync(dir);
+      // Count GSD-style {phase}-{plan}-PLAN.md vs short PLAN.md
+      const planFiles = files.filter((f) => /-PLAN\.md$/.test(f));
+      const summaryFiles = files.filter((f) => /-SUMMARY\.md$/.test(f));
+      const hasShortPlan = files.includes('PLAN.md');
+      const hasShortSummary = files.includes('SUMMARY.md');
+      return {
+        name: e.name,
+        path: dir,
+        planFiles,
+        summaryFiles,
+        hasShortPlan,
+        hasShortSummary,
+      };
+    });
+}
+
+/**
+ * Compute a status report suitable for `cp doctor`.
+ */
+function report(root = repoRoot()) {
+  const r = {
+    planning: hasPlanning(root),
+    cpAware: isCpAware(root),
+    gsdProject: isGsdProject(root),
+    sharedFiles: presentSharedFiles(root),
+    phases: scanPhases(root),
+    warnings: [],
+  };
+
+  if (r.planning && !r.cpAware) {
+    r.warnings.push(
+      '.planning/ exists but has no `cp` block in config.json. Run `cp init` ' +
+        'to add cp settings without touching existing files.'
+    );
+  }
+  if (r.gsdProject && r.cpAware) {
+    r.warnings.push(
+      'GSD sentinels detected (research/ / todos/ / seeds/ / REQUIREMENTS.md). ' +
+        'cp will read GSD-shaped state and write GSD-compatible filenames. ' +
+        'Switch back to GSD any time — `cp` only ADDS to .planning/, never ' +
+        'rewrites GSD files.'
+    );
+  }
+  for (const p of r.phases) {
+    // Short-form `PLAN.md` / `SUMMARY.md` are cp-canonical (cp emits them by
+    // design — see `lib/lifecycle.js scaffoldPhase`). They round-trip through
+    // `cp gsd-import` cleanly. Only warn on the genuinely-broken case where
+    // BOTH a short-form AND long-form `{NN-MM}-PLAN.md` coexist in the same
+    // phase dir (the parser would have to pick one, and that's ambiguous).
+    //
+    // v0.3.3 — closes CONCERNS High: "cp scaffolds short-form PLAN.md, then
+    // cp doctor warns the same shape is GSD-incompatible."
+    if (p.hasShortPlan && p.planFiles.length > 0) {
+      r.warnings.push(
+        `Phase ${p.name} has BOTH short-form PLAN.md AND long-form ` +
+          `${p.planFiles.join(', ')}. Pick one — cp's canonical shape is ` +
+          `short-form PLAN.md; the long-form files exist for GSD round-trip only.`
+      );
+    }
+    if (p.hasShortSummary && p.summaryFiles.length > 0) {
+      r.warnings.push(
+        `Phase ${p.name} has BOTH short-form SUMMARY.md AND long-form ` +
+          `${p.summaryFiles.join(', ')}. Pick one — cp writes per-plan ` +
+          `{NN-MM}-SUMMARY.md files via \`cp write-summary\`.`
+      );
+    }
+  }
+  return r;
+}
+
+module.exports = {
+  GSD_SENTINELS,
+  SHARED_FILES,
+  hasPlanning,
+  isGsdProject,
+  isCpAware,
+  presentSharedFiles,
+  scanPhases,
+  report,
+};