gsdd-cli 0.1.0

package/bin/lib/phase.mjs

@@ -0,0 +1,237 @@
+// phase.mjs — Phase discovery, verification, and scaffolding
+//
+// IMPORTANT: No module-scope process.cwd() — ESM caching means sub-modules
+// evaluate once, so CWD must be computed inside function bodies.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import { output } from './cli-utils.mjs';
+
+function findFiles(dir, prefix) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
+}
+
+function padPhase(n) {
+  return String(n).padStart(2, '0');
+}
+
+function parsePhaseStatuses(roadmap) {
+  const phases = [];
+  const lines = roadmap.split('\n');
+  for (const line of lines) {
+    // Supports:
+    // - checkbox statuses: [ ] / [x]
+    // - legacy emoji markers in ROADMAP templates: not started / in progress / done
+    // - mojibake-encoded variants that exist in some files
+    const match = line.match(
+      /^[-*]\s*(\[[ x]\]|\[-\]|⬜|ðŸ"„|✅|⬜|🔄|✅)\s*\*\*Phase\s+(\d+):\s*(.+?)\*\*/i
+    );
+    if (match) {
+      const rawStatus = match[1].toLowerCase();
+      let status = 'not_started';
+      if (rawStatus === '[x]' || rawStatus === '✅' || rawStatus === '✅') status = 'done';
+      else if (rawStatus === '[-]') status = 'in_progress';
+      else if (rawStatus === 'ðÿ"„' || rawStatus === '🔄') status = 'in_progress';
+      phases.push({
+        number: parseInt(match[2], 10),
+        name: match[3].replace(/\*\*/g, '').split('-')[0].trim(),
+        status,
+      });
+    }
+  }
+  return phases;
+}
+
+export function cmdFindPhase(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const phaseNum = args[0];
+
+  if (!existsSync(planningDir)) {
+    output({ error: 'No .planning/ directory found. Run `gsdd init` then the new-project workflow first.' });
+    return;
+  }
+
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  if (!existsSync(roadmapPath)) {
+    output({ error: 'No ROADMAP.md found. Run the new-project workflow first.' });
+    return;
+  }
+
+  const phasesDir = join(planningDir, 'phases');
+  const researchDir = join(planningDir, 'research');
+
+  if (phaseNum) {
+    const plans = findFiles(phasesDir, `${padPhase(phaseNum)}-PLAN`);
+    const summaries = findFiles(phasesDir, `${padPhase(phaseNum)}-SUMMARY`);
+
+    output({
+      phase: parseInt(phaseNum, 10),
+      directory: phasesDir,
+      plans,
+      summaries,
+      hasResearch: existsSync(researchDir) && readdirSync(researchDir).length > 0,
+      incomplete: plans.filter((p) => !summaries.some((s) => s.replace('SUMMARY', '') === p.replace('PLAN', ''))),
+    });
+    return;
+  }
+
+  const allFiles = existsSync(phasesDir) ? readdirSync(phasesDir) : [];
+  const plans = allFiles.filter((f) => f.includes('PLAN'));
+  const summaries = allFiles.filter((f) => f.includes('SUMMARY'));
+
+  const roadmap = readFileSync(roadmapPath, 'utf-8');
+  const phases = parsePhaseStatuses(roadmap);
+
+  output({
+    phases,
+    planCount: plans.length,
+    summaryCount: summaries.length,
+    currentPhase: phases.find((p) => p.status === 'in_progress') || phases.find((p) => p.status === 'not_started') || null,
+    hasResearch: existsSync(researchDir) && readdirSync(researchDir).length > 0,
+  });
+}
+
+export function cmdVerify(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const phaseNum = args[0];
+  if (!phaseNum) {
+    console.error('Usage: gsdd verify <phase-number>');
+    process.exit(1);
+  }
+
+  if (!existsSync(planningDir)) {
+    console.error('No .planning/ directory found.');
+    process.exit(1);
+  }
+
+  const planFile = findFiles(join(planningDir, 'phases'), `${padPhase(phaseNum)}-PLAN`)[0];
+  if (!planFile) {
+    console.error(`No plan found for phase ${phaseNum}`);
+    process.exit(1);
+  }
+
+  const planPath = join(planningDir, 'phases', planFile);
+  const plan = readFileSync(planPath, 'utf-8');
+
+  const fileMatches = plan.matchAll(/<files>([\s\S]*?)<\/files>/g);
+  const expectedFiles = [];
+  for (const match of fileMatches) {
+    const lines = match[1]
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.startsWith('-'));
+    for (const line of lines) {
+      const fileMatch = line.match(/(?:CREATE|MODIFY):\s*(.+)/);
+      if (fileMatch) expectedFiles.push(fileMatch[1].trim());
+    }
+  }
+
+  const results = expectedFiles.map((f) => {
+    const fullPath = join(cwd, f);
+    const exists = existsSync(fullPath);
+    let substantive = false;
+    if (exists) {
+      try {
+        const content = readFileSync(fullPath, 'utf-8');
+        const meaningfulLines = content.split('\n').filter(
+          (l) => l.trim() && !/^\s*(\/\/|\/\*|\*|#)/.test(l)
+        );
+        substantive = meaningfulLines.length >= 3 && !content.includes('// TODO: implement');
+      } catch {
+        substantive = false;
+      }
+    }
+    return { file: f, exists, substantive };
+  });
+
+  const antiPatterns = [];
+  for (const r of results) {
+    if (!r.exists) continue;
+    try {
+      const content = readFileSync(join(cwd, r.file), 'utf-8');
+      const lines = content.split('\n');
+      lines.forEach((line, i) => {
+        if (/TODO|FIXME|HACK|XXX/.test(line)) {
+          antiPatterns.push({ file: r.file, line: i + 1, pattern: 'TODO/FIXME', content: line.trim() });
+        }
+        if (/catch\s*\([^)]*\)\s*\{[\s]*\}/.test(line) || /catch\s*\([^)]*\)\s*\{\s*$/.test(line)) {
+          antiPatterns.push({ file: r.file, line: i + 1, pattern: 'Empty catch', content: line.trim() });
+        }
+      });
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  output({
+    phase: parseInt(phaseNum, 10),
+    artifacts: results,
+    allExist: results.every((r) => r.exists),
+    allSubstantive: results.filter((r) => r.exists).every((r) => r.substantive),
+    antiPatterns,
+    antiPatternCount: antiPatterns.length,
+  });
+}
+
+export function cmdScaffold(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const [type, ...rest] = args;
+
+  if (type !== 'phase') {
+    console.error('Usage: gsdd scaffold phase <number> [name]');
+    process.exit(1);
+  }
+
+  const phaseNum = rest[0];
+  const phaseName = rest.slice(1).join(' ');
+  if (!phaseNum) {
+    console.error('Usage: gsdd scaffold phase <number> [name]');
+    process.exit(1);
+  }
+
+  const phasesDir = join(planningDir, 'phases');
+  mkdirSync(phasesDir, { recursive: true });
+
+  const planFile = join(phasesDir, `${padPhase(phaseNum)}-PLAN.md`);
+  if (existsSync(planFile)) {
+    console.log(`  - ${basename(planFile)} already exists`);
+    return;
+  }
+
+  const content = `# Phase ${phaseNum}: ${phaseName || '[Name]'} - Plan
+
+## Phase Goal
+[From ROADMAP.md]
+
+## Requirements Covered
+[REQ-IDs from SPEC.md]
+
+## Approach
+[2-3 sentences]
+
+## Must-Haves (from success criteria)
+1. [Success criterion]
+
+## Tasks
+
+<!-- Add tasks using XML format:
+<task id="${phaseNum}-01">
+  <files>
+    - CREATE: path/to/file
+  </files>
+  <action>Description of what to implement</action>
+  <verify>How to verify it works</verify>
+  <done>When is this task done</done>
+</task>
+-->
+
+## Notes
+`;
+
+  writeFileSync(planFile, content);
+  console.log(`  - created ${basename(planFile)}`);
+}

package/bin/lib/rendering.mjs

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
+
+function getWorkflowContent(workflowFile) {
+  const filePath = join(DISTILLED_DIR, 'workflows', workflowFile);
+  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
+  return `<!-- Workflow file not found: ${workflowFile} -->\n`;
+}
+
+function getDelegateContent(delegateFile) {
+  const filePath = join(DISTILLED_DIR, 'templates', 'delegates', delegateFile);
+  if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
+  return `<!-- Delegate file not found: ${delegateFile} -->\n`;
+}
+
+function renderSkillContent(workflow) {
+  const workflowContent = getWorkflowContent(workflow.workflow);
+  return `---
+name: ${workflow.name}
+description: ${workflow.description}
+context: fork
+agent: ${workflow.agent}
+---
+
+${workflowContent}`;
+}
+
+function renderOpenCodeCommandContent(workflow) {
+  const workflowContent = getWorkflowContent(workflow.workflow);
+  return `---
+description: ${workflow.description}
+---
+
+${workflowContent}`;
+}
+
+function renderAgentsBoundedBlock() {
+  const blockPath = join(DISTILLED_DIR, 'templates', 'agents.block.md');
+  if (existsSync(blockPath)) return readFileSync(blockPath, 'utf-8').trim();
+  return '## GSDD Governance (Generated)\n\n- Framework: GSDD\n- Planning: .planning/\n- Workflows: .agents/skills/gsdd-*/SKILL.md';
+}
+
+function renderAgentsFileContent() {
+  const templatePath = join(DISTILLED_DIR, 'templates', 'agents.md');
+  if (existsSync(templatePath)) {
+    const template = readFileSync(templatePath, 'utf-8');
+    return template.replace('{{GSDD_BLOCK}}', renderAgentsBoundedBlock()).trimEnd() + '\n';
+  }
+  const block = renderAgentsBoundedBlock();
+  return `# AGENTS.md - GSDD Governance\n\n<!-- BEGIN GSDD -->\n${block}\n<!-- END GSDD -->\n`;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function upsertBoundedBlock(existing, blockContent) {
+  const begin = '<!-- BEGIN GSDD -->';
+  const end = '<!-- END GSDD -->';
+  const bounded = `${begin}\n${blockContent.trimEnd()}\n${end}`;
+
+  const re = new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}`, 'm');
+  if (re.test(existing)) return existing.replace(re, bounded);
+
+  const lines = existing.split(/\r?\n/);
+  const h1Idx = lines.findIndex((line) => /^#\s+/.test(line));
+  if (h1Idx !== -1) {
+    const insertAt = h1Idx + 1;
+    const out = [
+      ...lines.slice(0, insertAt),
+      '',
+      bounded,
+      '',
+      ...lines.slice(insertAt),
+    ];
+    return out.join('\n').replace(/\n{3,}/g, '\n\n');
+  }
+
+  return `${bounded}\n\n${existing}`.replace(/\n{3,}/g, '\n\n');
+}
+
+export {
+  getDelegateContent,
+  getWorkflowContent,
+  renderAgentsBoundedBlock,
+  renderAgentsFileContent,
+  renderOpenCodeCommandContent,
+  renderSkillContent,
+  upsertBoundedBlock,
+};

package/bin/lib/templates.mjs

@@ -0,0 +1,207 @@
+// templates.mjs - Project template and role installation/refresh helpers
+
+import { existsSync, mkdirSync, readdirSync, cpSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { fileHash, readManifest } from './manifest.mjs';
+
+export function installProjectTemplates({ planningDir, distilledDir, agentsDir }) {
+  const localTemplatesDir = join(planningDir, 'templates');
+  const globalTemplatesDir = join(distilledDir, 'templates');
+
+  if (!existsSync(localTemplatesDir)) {
+    if (existsSync(globalTemplatesDir)) {
+      cpSync(globalTemplatesDir, localTemplatesDir, { recursive: true });
+      console.log('  - copied templates to .planning/templates/');
+    } else {
+      console.log('  - WARN: missing distilled/templates/; cannot copy templates');
+    }
+  } else {
+    console.log('  - .planning/templates/ already exists');
+  }
+
+  const localRolesDir = join(localTemplatesDir, 'roles');
+  if (!existsSync(localRolesDir)) {
+    if (existsSync(agentsDir)) {
+      mkdirSync(localRolesDir, { recursive: true });
+      for (const file of listRoleFiles(agentsDir)) {
+        cpSync(join(agentsDir, file), join(localRolesDir, file));
+      }
+      console.log('  - copied role contracts to .planning/templates/roles/');
+    } else {
+      console.log('  - WARN: missing agents/; cannot copy role contracts');
+    }
+  } else {
+    console.log('  - .planning/templates/roles/ already exists');
+  }
+}
+
+export function refreshTemplates({ planningDir, distilledDir, agentsDir, isDry = false }) {
+  const existingManifest = readManifest(planningDir);
+  const globalTemplatesDir = join(distilledDir, 'templates');
+  const localTemplatesDir = join(planningDir, 'templates');
+
+  const categories = [
+    { name: 'delegates', src: join(globalTemplatesDir, 'delegates'), dest: join(localTemplatesDir, 'delegates'), manifestKey: 'delegates' },
+    { name: 'research', src: join(globalTemplatesDir, 'research'), dest: join(localTemplatesDir, 'research'), manifestKey: 'research' },
+    { name: 'codebase', src: join(globalTemplatesDir, 'codebase'), dest: join(localTemplatesDir, 'codebase'), manifestKey: 'codebase' },
+  ];
+
+  for (const category of categories) {
+    refreshCategory(category, existingManifest, isDry);
+  }
+
+  refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry);
+  refreshRoles(agentsDir, join(localTemplatesDir, 'roles'), existingManifest, isDry);
+}
+
+function listRoleFiles(agentsDir) {
+  return readdirSync(agentsDir).filter(
+    (file) => file.endsWith('.md') && file !== 'README.md' && !file.startsWith('_')
+  );
+}
+
+function refreshCategory({ name, src, dest, manifestKey }, existingManifest, isDry) {
+  if (!existsSync(src)) return;
+  if (!existsSync(dest) && !isDry) {
+    mkdirSync(dest, { recursive: true });
+  }
+
+  const manifestHashes = existingManifest?.templates?.[manifestKey] || null;
+  const sourceFiles = readdirSync(src).filter((file) => file.endsWith('.md'));
+  const installedFiles = existsSync(dest) ? readdirSync(dest).filter((file) => file.endsWith('.md')) : [];
+
+  for (const file of sourceFiles) {
+    const srcPath = join(src, file);
+    const destPath = join(dest, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: ${name}/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh ${name}/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed ${name}/${file}`);
+    }
+  }
+
+  for (const file of installedFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan ${name}/${file}`);
+      } else {
+        const orphanPath = join(dest, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan ${name}/${file}`);
+      }
+    }
+  }
+}
+
+function refreshRootTemplates(globalTemplatesDir, localTemplatesDir, existingManifest, isDry) {
+  if (!existsSync(globalTemplatesDir)) return;
+
+  const manifestHashes = existingManifest?.templates?.root || null;
+  const sourceFiles = readdirSync(globalTemplatesDir).filter((file) => file.endsWith('.md'));
+
+  for (const file of sourceFiles) {
+    const srcPath = join(globalTemplatesDir, file);
+    const destPath = join(localTemplatesDir, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: templates/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh templates/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed templates/${file}`);
+    }
+  }
+
+  const installedRootFiles = existsSync(localTemplatesDir)
+    ? readdirSync(localTemplatesDir).filter((file) => file.endsWith('.md'))
+    : [];
+
+  for (const file of installedRootFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan templates/${file}`);
+      } else {
+        const orphanPath = join(localTemplatesDir, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan templates/${file}`);
+      }
+    }
+  }
+}
+
+function refreshRoles(agentsDir, localRolesDir, existingManifest, isDry) {
+  if (!existsSync(agentsDir)) return;
+  if (!existsSync(localRolesDir) && !isDry) {
+    mkdirSync(localRolesDir, { recursive: true });
+  }
+
+  const manifestHashes = existingManifest?.roles || null;
+  const sourceFiles = listRoleFiles(agentsDir);
+  const installedFiles = existsSync(localRolesDir)
+    ? readdirSync(localRolesDir).filter((file) => file.endsWith('.md'))
+    : [];
+
+  for (const file of sourceFiles) {
+    const srcPath = join(agentsDir, file);
+    const destPath = join(localRolesDir, file);
+    const srcHash = fileHash(srcPath);
+
+    if (existsSync(destPath)) {
+      const destHash = fileHash(destPath);
+      if (destHash === srcHash) continue;
+
+      const manifestHash = manifestHashes?.[file];
+      if (manifestHash && destHash !== manifestHash) {
+        console.log(`  - WARN: roles/${file} was modified locally; overwriting with framework source`);
+      }
+    }
+
+    if (isDry) {
+      console.log(`  - would refresh roles/${file}`);
+    } else {
+      cpSync(srcPath, destPath);
+      console.log(`  - refreshed roles/${file}`);
+    }
+  }
+
+  for (const file of installedFiles) {
+    if (!sourceFiles.includes(file)) {
+      if (isDry) {
+        console.log(`  - would remove orphan roles/${file}`);
+      } else {
+        const orphanPath = join(localRolesDir, file);
+        if (existsSync(orphanPath)) {
+          unlinkSync(orphanPath);
+        }
+        console.log(`  - removed orphan roles/${file}`);
+      }
+    }
+  }
+}