gsdd-cli 0.2.0 → 0.16.1

package/bin/lib/cli-utils.mjs

@@ -15,7 +15,7 @@ export function parseFlagValue(flagArgs, flagName) {
 export function parseToolsFlag(flagArgs) {
   const { value } = parseFlagValue(flagArgs, '--tools');
   if (!value) return [];
-  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents'];
+  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents', 'cursor', 'copilot', 'gemini'];
   return value.split(',').map((v) => v.trim()).filter(Boolean);
 }
 

package/bin/lib/file-ops.mjs

@@ -0,0 +1,161 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, relative, resolve } from 'path';
+import { output, parseFlagValue } from './cli-utils.mjs';
+
+class FileOpError extends Error {}
+
+function fail(message) {
+  console.error(message);
+  throw new FileOpError(message);
+}
+
+function resolveWorkspacePath(cwd, target) {
+  const workspaceRoot = resolve(cwd);
+  const resolved = resolve(workspaceRoot, target);
+  const rel = relative(workspaceRoot, resolved);
+
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+    return resolved;
+  }
+
+  fail(`Path must stay inside the workspace: ${target}`);
+}
+
+function getMissingBehavior(args) {
+  const parsed = parseFlagValue(args, '--missing');
+  if (!parsed.present) return 'error';
+  if (parsed.invalid) fail('Usage: --missing <error|ok>');
+  if (!['error', 'ok'].includes(parsed.value)) fail('Usage: --missing <error|ok>');
+  return parsed.value;
+}
+
+function cmdCopy(cwd, args) {
+  const [sourceArg, destinationArg, ...flags] = args;
+  if (!sourceArg || !destinationArg) {
+    fail('Usage: gsdd file-op copy <source> <destination> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const source = resolveWorkspacePath(cwd, sourceArg);
+  const destination = resolveWorkspacePath(cwd, destinationArg);
+
+  if (!existsSync(source)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: false, reason: 'missing_source' });
+      return;
+    }
+    fail(`Source file does not exist: ${sourceArg}`);
+  }
+
+  if (statSync(source).isDirectory()) {
+    fail(`Copy only supports files in this phase: ${sourceArg}`);
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { force: true });
+  output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: true });
+}
+
+function cmdDelete(cwd, args) {
+  const [targetArg, ...flags] = args;
+  if (!targetArg) {
+    fail('Usage: gsdd file-op delete <target> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'delete', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`Delete only supports files in this phase: ${targetArg}`);
+  }
+
+  unlinkSync(target);
+  output({ operation: 'delete', target: targetArg, changed: true });
+}
+
+function cmdRegexSub(cwd, args) {
+  const [targetArg, pattern, replacement, ...flags] = args;
+  if (!targetArg || pattern === undefined || replacement === undefined) {
+    fail('Usage: gsdd file-op regex-sub <target> <pattern> <replacement> [--flags <flags>] [--missing <error|ok>]');
+  }
+
+  const regexFlags = parseFlagValue(flags, '--flags');
+  if (regexFlags.present && regexFlags.invalid) {
+    fail('Usage: --flags <regex-flags>');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'regex-sub', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`regex-sub only supports files in this phase: ${targetArg}`);
+  }
+
+  let regex;
+  try {
+    regex = new RegExp(pattern, regexFlags.value || 'g');
+  } catch (error) {
+    fail(`Invalid regex pattern: ${error.message}`);
+  }
+
+  const source = readFileSync(target, 'utf-8');
+  let replacementCount = 0;
+  if (regex.global) {
+    const matches = source.match(regex);
+    replacementCount = matches ? matches.length : 0;
+  } else {
+    replacementCount = regex.test(source) ? 1 : 0;
+  }
+
+  if (replacementCount === 0) {
+    fail(`Pattern did not match any text in ${targetArg}`);
+  }
+
+  const updated = source.replace(regex, replacement);
+  const changed = updated !== source;
+  writeFileSync(target, updated);
+  output({ operation: 'regex-sub', target: targetArg, changed, replacements: replacementCount });
+}
+
+export function cmdFileOp(...args) {
+  const cwd = process.cwd();
+  const [operation, ...rest] = args;
+
+  try {
+    switch (operation) {
+      case 'copy':
+        cmdCopy(cwd, rest);
+        return;
+      case 'delete':
+        cmdDelete(cwd, rest);
+        return;
+      case 'regex-sub':
+        cmdRegexSub(cwd, rest);
+        return;
+      default:
+        fail('Usage: gsdd file-op <copy|delete|regex-sub> ...');
+    }
+  } catch (error) {
+    if (error instanceof FileOpError) {
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}

package/bin/lib/health-truth.mjs

@@ -0,0 +1,188 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10'];
+
+export function runTruthChecks(planningDir, frameworkDir, actualCheckIds) {
+  const warnings = [];
+  const designPath = join(frameworkDir, 'distilled', 'DESIGN.md');
+  const readmePath = join(frameworkDir, 'distilled', 'README.md');
+  const workflowsDir = join(frameworkDir, 'distilled', 'workflows');
+  const gapsPath = join(frameworkDir, '.internal-research', 'gaps.md');
+  const specPath = join(planningDir, 'SPEC.md');
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+
+  if (existsSync(designPath)) {
+    const documentedIds = extractHealthTableIds(readFileSync(designPath, 'utf-8'));
+    const missingFromDesign = actualCheckIds.filter((id) => !documentedIds.includes(id));
+    const extraInDesign = documentedIds.filter((id) => !actualCheckIds.includes(id));
+    if (missingFromDesign.length > 0 || extraInDesign.length > 0) {
+      const parts = [];
+      if (missingFromDesign.length > 0) parts.push(`missing in DESIGN.md: ${missingFromDesign.join(', ')}`);
+      if (extraInDesign.length > 0) parts.push(`extra in DESIGN.md: ${extraInDesign.join(', ')}`);
+      warnings.push({
+        id: 'W7',
+        severity: 'WARN',
+        message: `DESIGN.md health check table is out of sync (${parts.join('; ')})`,
+        fix: 'Update distilled/DESIGN.md section 20 to match the implemented health checks',
+      });
+    }
+  }
+
+  if (existsSync(readmePath) && existsSync(workflowsDir)) {
+    const readme = readFileSync(readmePath, 'utf-8');
+    const workflowFiles = readdirSync(workflowsDir).filter((entry) => entry.endsWith('.md')).sort();
+    const statusEntries = extractReadmeStatusEntries(readme);
+    const treeEntries = extractReadmeWorkflowTreeEntries(readme);
+    const issues = [];
+    if (statusEntries.length !== workflowFiles.length) {
+      issues.push(`status table ${statusEntries.length} != workflows dir ${workflowFiles.length}`);
+    }
+    if (treeEntries.length !== workflowFiles.length) {
+      issues.push(`framework tree ${treeEntries.length} != workflows dir ${workflowFiles.length}`);
+    }
+    const missingStatus = workflowFiles.filter((name) => !statusEntries.includes(name));
+    const missingTree = workflowFiles.filter((name) => !treeEntries.includes(name));
+    if (missingStatus.length > 0) issues.push(`missing from status table: ${missingStatus.join(', ')}`);
+    if (missingTree.length > 0) issues.push(`missing from framework tree: ${missingTree.join(', ')}`);
+    if (issues.length > 0) {
+      warnings.push({
+        id: 'W8',
+        severity: 'WARN',
+        message: `distilled/README.md workflow inventory is out of sync (${issues.join('; ')})`,
+        fix: 'Update distilled/README.md workflow status table and framework file tree to match distilled/workflows/',
+      });
+    }
+  }
+
+  if (existsSync(gapsPath)) {
+    const gapRefs = extractRepoLocalPaths(readFileSync(gapsPath, 'utf-8'));
+    const missingRefs = gapRefs.filter((ref) => !existsSync(join(frameworkDir, ref)));
+    if (missingRefs.length > 0) {
+      warnings.push({
+        id: 'W9',
+        severity: 'WARN',
+        message: `gaps.md references missing repo-local paths (${missingRefs.join(', ')})`,
+        fix: 'Annotate stale gap references as resolved or update them to current repo truth',
+      });
+    }
+  }
+
+  if (existsSync(specPath) && existsSync(roadmapPath)) {
+    const spec = readFileSync(specPath, 'utf-8');
+    const roadmap = readFileSync(roadmapPath, 'utf-8');
+    const checkedRequirements = extractCheckedRequirements(spec);
+    const roadmapRequirements = extractRoadmapRequirements(roadmap);
+    const mismatches = [];
+    for (const [requirementId, roadmapStatus] of roadmapRequirements.entries()) {
+      const specChecked = checkedRequirements.has(requirementId);
+      if (roadmapStatus && !specChecked) mismatches.push(`${requirementId} phase complete but SPEC unchecked`);
+      if (!roadmapStatus && specChecked) mismatches.push(`${requirementId} SPEC checked but phase incomplete`);
+    }
+    if (mismatches.length > 0) {
+      warnings.push({
+        id: 'W10',
+        severity: 'WARN',
+        message: `ROADMAP/SPEC requirement status drift (${mismatches.join('; ')})`,
+        fix: 'Reconcile .planning/ROADMAP.md phase completion markers with .planning/SPEC.md requirement checkboxes',
+      });
+    }
+  }
+
+  return warnings;
+}
+
+function extractHealthTableIds(content) {
+  const section = extractSection(content, '## 20. Workspace Health Diagnostics', '## 21.');
+  if (!section) return [];
+  return [...normalizeContent(section).matchAll(/^\|\s*([EWI]\d+)\s*\|/gm)].map((result) => result[1]);
+}
+
+function extractReadmeStatusEntries(content) {
+  const section = extractSection(content, '## Current Status', 'Architecture notes:');
+  if (!section) return [];
+  return [...normalizeContent(section).matchAll(/\|\s*`([^`]+\.md)`\s*\|/g)].map((result) => result[1]);
+}
+
+function extractReadmeWorkflowTreeEntries(content) {
+  const section = extractSection(content, '## Files In This Framework', '## ');
+  const match = normalizeContent(section || '').match(/```[\s\S]*?workflows\/\n([\s\S]*?)\n\s*templates\//);
+  if (!match) return [];
+  return match[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.endsWith('.md'));
+}
+
+function extractRepoLocalPaths(content) {
+  const allowedRoots = [
+    'AGENTS.md',
+    'README.md',
+    'CHANGELOG.md',
+    'SPEC.md',
+    'package.json',
+    '.planning/',
+    '.internal-research/',
+    '.agents/',
+    '.claude/',
+    '.opencode/',
+    '.codex/',
+    '.worktrees/',
+    'bin/',
+    'distilled/',
+    'tests/',
+    'fixtures/',
+    'agents/',
+  ];
+  const refs = new Set();
+  for (const result of content.matchAll(/`([^`]+)`/g)) {
+    const value = result[1].trim();
+    if (!looksLikeRepoLocalPath(value, allowedRoots)) continue;
+    refs.add(value.replace(/\\/g, '/').replace(/\/$/, ''));
+  }
+  return [...refs];
+}
+
+function looksLikeRepoLocalPath(value, allowedRoots) {
+  if (value.includes(' ')) return false;
+  if (value.startsWith('/')) return false;
+  if (value.startsWith('$')) return false;
+  if (value.startsWith('..')) return false;
+  if (value.includes('://')) return false;
+  if (value.startsWith('feat/') || value.startsWith('fix/') || value.startsWith('pr') || value.startsWith('origin/')) return false;
+  if (allowedRoots.some((root) => value === root || value.startsWith(root))) return true;
+  return false;
+}
+
+function extractSection(content, startMarker, endMarker) {
+  const normalized = normalizeContent(content);
+  const start = normalized.indexOf(startMarker);
+  if (start === -1) return '';
+  const rest = normalized.slice(start);
+  if (!endMarker) return rest;
+  const end = rest.indexOf(endMarker, startMarker.length);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+function normalizeContent(content) {
+  return content.replace(/\r\n/g, '\n');
+}
+
+function extractCheckedRequirements(content) {
+  const checked = new Set();
+  for (const result of content.matchAll(/- \[x\] \*\*\[([A-Z0-9-]+)]\*\*/g)) {
+    checked.add(result[1]);
+  }
+  return checked;
+}
+
+function extractRoadmapRequirements(content) {
+  const mapped = new Map();
+  for (const result of content.matchAll(/- \[([ x-])] \*\*Phase\s+\d+[a-z]?:.*?\*\*\s+—\s+\[([^\]]+)]/g)) {
+    const requirementIds = result[2].split(',').map((id) => id.trim());
+    for (const requirementId of requirementIds) {
+      mapped.set(requirementId, result[1].toLowerCase() === 'x');
+    }
+  }
+  return mapped;
+}

package/bin/lib/health.mjs

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { readManifest, detectModifications } from './manifest.mjs';
 import { output } from './cli-utils.mjs';
+import { runTruthChecks, TRUTH_CHECK_IDS } from './health-truth.mjs';
 
 /**
  * Factory function returning the health command.
@@ -17,6 +18,8 @@ export function createCmdHealth(ctx) {
     const jsonMode = healthArgs.includes('--json');
     const cwd = process.cwd();
     const planningDir = join(cwd, '.planning');
+    const frameworkSourceMode = isFrameworkSourceRepo(cwd);
+    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
@@ -56,10 +59,11 @@ export function createCmdHealth(ctx) {
     const delegatesDir = join(templatesDir, 'delegates');
     const hasRolesDir = hasTemplatesDir && existsSync(rolesDir);
     const hasDelegatesDir = hasTemplatesDir && existsSync(delegatesDir);
+    const skipInstalledTemplateChecks = !hasTemplatesDir && frameworkSourceMode;
 
-    if (!hasTemplatesDir) {
+    if (!hasTemplatesDir && !skipInstalledTemplateChecks) {
       errors.push({ id: 'E3', severity: 'ERROR', message: '.planning/templates/ missing', fix: 'Run `gsdd update --templates`' });
-    } else {
+    } else if (hasTemplatesDir) {
       // E4: roles/ missing or empty
       if (!hasRolesDir) {
         errors.push({ id: 'E4', severity: 'ERROR', message: '.planning/templates/roles/ missing', fix: 'Run `gsdd update --templates`' });
@@ -79,13 +83,42 @@ export function createCmdHealth(ctx) {
           errors.push({ id: 'E5', severity: 'ERROR', message: '.planning/templates/delegates/ has 0 delegate files', fix: 'Run `gsdd update --templates`' });
         }
       }
+
+      // E6: research/ missing or empty
+      const researchDir = join(templatesDir, 'research');
+      if (!existsSync(researchDir)) {
+        errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ missing', fix: 'Run `gsdd update --templates`' });
+      } else {
+        const researchFiles = readdirSync(researchDir).filter((f) => f.endsWith('.md'));
+        if (researchFiles.length === 0) {
+          errors.push({ id: 'E6', severity: 'ERROR', message: '.planning/templates/research/ has 0 template files', fix: 'Run `gsdd update --templates`' });
+        }
+      }
+
+      // E7: codebase/ missing or empty
+      const codebaseDir = join(templatesDir, 'codebase');
+      if (!existsSync(codebaseDir)) {
+        errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ missing', fix: 'Run `gsdd update --templates`' });
+      } else {
+        const codebaseFiles = readdirSync(codebaseDir).filter((f) => f.endsWith('.md'));
+        if (codebaseFiles.length === 0) {
+          errors.push({ id: 'E7', severity: 'ERROR', message: '.planning/templates/codebase/ has 0 template files', fix: 'Run `gsdd update --templates`' });
+        }
+      }
+
+      // E8: critical root template files missing
+      const requiredRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
+      const missingRoot = requiredRootFiles.filter((f) => !existsSync(join(templatesDir, f)));
+      if (missingRoot.length > 0) {
+        errors.push({ id: 'E8', severity: 'ERROR', message: `.planning/templates/ missing critical root files: ${missingRoot.join(', ')}`, fix: 'Run `gsdd update --templates`' });
+      }
     }
 
     // --- WARNING checks ---
 
     // W1: generation-manifest.json missing
-    const manifest = readManifest(planningDir);
-    if (!manifest) {
+    const manifest = skipInstalledTemplateChecks ? null : readManifest(planningDir);
+    if (!manifest && !skipInstalledTemplateChecks) {
       warnings.push({ id: 'W1', severity: 'WARN', message: 'generation-manifest.json missing', fix: 'Run `gsdd update --templates` to create' });
     }
 
@@ -118,16 +151,25 @@ export function createCmdHealth(ctx) {
     const phaseArtifacts = existsSync(phasesDir) ? listPhaseArtifacts(phasesDir) : [];
 
     if (roadmap && existsSync(phasesDir)) {
-      const phaseNums = [];
+      const phaseLabels = [];
+      let inDetails = false;
       for (const line of roadmap.split('\n')) {
-        const match = line.match(/^\s*[-*]\s*\[[ x-]\]\s*\*\*Phase\s+(\d+)/i);
-        if (match) phaseNums.push(parseInt(match[1], 10));
+        if (line.includes('<details>') && !line.includes('</details>')) {
+          inDetails = true;
+          continue;
+        }
+        if (line.includes('</details>')) {
+          inDetails = false;
+          continue;
+        }
+        if (inDetails) continue;
+        const match = line.match(/^\s*[-*]\s*\[([x-])\]\s*\*\*Phase\s+(\d+[a-z]?)/i);
+        if (match) phaseLabels.push(normalizePhaseLabel(match[2]));
       }
-      for (const num of phaseNums) {
-        const padded = String(num).padStart(2, '0');
-        const hasFile = phaseArtifacts.some((artifact) => artifact.phasePrefix === padded || artifact.phasePrefix === String(num));
+      for (const label of phaseLabels) {
+        const hasFile = phaseArtifacts.some((artifact) => normalizePhaseLabel(artifact.phasePrefix) === label);
         if (!hasFile) {
-          warnings.push({ id: 'W4', severity: 'WARN', message: `ROADMAP.md references Phase ${num} but no files found in .planning/phases/`, fix: 'Create missing phase dirs or update ROADMAP' });
+          warnings.push({ id: 'W4', severity: 'WARN', message: `ROADMAP.md references active Phase ${label} but no files found in .planning/phases/`, fix: 'Create missing phase dirs or update ROADMAP' });
         }
       }
     }
@@ -160,6 +202,8 @@ export function createCmdHealth(ctx) {
       warnings.push({ id: 'W6', severity: 'WARN', message: 'No adapter surfaces detected', fix: 'Run `gsdd init --tools <platform>`' });
     }
 
+    warnings.push(...runTruthChecks(planningDir, cwd, healthCheckIds));
+
     // --- INFO checks ---
 
     // I1: generation manifest was produced by a different framework version
@@ -220,6 +264,15 @@ export function createCmdHealth(ctx) {
   };
 }
 
+function isFrameworkSourceRepo(cwd) {
+  return existsSync(join(cwd, 'distilled', 'templates')) && existsSync(join(cwd, 'distilled', 'workflows'));
+}
+
+function normalizePhaseLabel(value) {
+  if (!value) return null;
+  return value.toLowerCase().replace(/^0+(\d)/, '$1');
+}
+
 function listPhaseArtifacts(phasesDir) {
   const artifacts = [];
   for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
@@ -243,6 +296,6 @@ function createPhaseArtifact(dir, name) {
     dir,
     name,
     displayPath: dir ? `${dir}/${name}` : name,
-    phasePrefix: name.match(/^(\d+(?:\.\d+)?)-/)?.[1] || dir.match(/^(\d+(?:\.\d+)?)-/)?.[1] || null,
+    phasePrefix: name.match(/^(\d+[a-z]?(?:\.\d+)?)-/i)?.[1] || dir.match(/^(\d+[a-z]?(?:\.\d+)?)-/i)?.[1] || null,
   };
 }