@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,228 @@
+/**
+ * Template — Template selection and fill operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = require('./core.cjs');
+const { reconstructFrontmatter } = require('./frontmatter.cjs');
+
+function cmdTemplateSelect(cwd, planPath, raw) {
+  if (!planPath) {
+    error('plan-path required');
+  }
+
+  try {
+    const fullPath = path.join(cwd, planPath);
+    const content = fs.readFileSync(fullPath, 'utf-8');
+
+    // Simple heuristics
+    const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
+    const taskCount = taskMatch.length;
+
+    const decisionMatch = content.match(/decision/gi) || [];
+    const hasDecisions = decisionMatch.length > 0;
+
+    // Count file mentions
+    const fileMentions = new Set();
+    const filePattern = /`([^`]+\.[a-zA-Z]+)`/g;
+    let m;
+    while ((m = filePattern.exec(content)) !== null) {
+      if (m[1].includes('/') && !m[1].startsWith('http')) {
+        fileMentions.add(m[1]);
+      }
+    }
+    const fileCount = fileMentions.size;
+
+    let template = 'templates/summary-standard.md';
+    let type = 'standard';
+
+    if (taskCount <= 2 && fileCount <= 3 && !hasDecisions) {
+      template = 'templates/summary-minimal.md';
+      type = 'minimal';
+    } else if (hasDecisions || fileCount > 6 || taskCount > 5) {
+      template = 'templates/summary-complex.md';
+      type = 'complex';
+    }
+
+    const result = { template, type, taskCount, fileCount, hasDecisions };
+    output(result, raw, template);
+  } catch (e) {
+    // Fallback to standard
+    output({ template: 'templates/summary-standard.md', type: 'standard', error: e.message }, raw, 'templates/summary-standard.md');
+  }
+}
+
+function cmdTemplateFill(cwd, templateType, options, raw) {
+  if (!templateType) { error('template type required: summary, plan, or verification'); }
+  if (!options.phase) { error('--phase required'); }
+
+  const phaseInfo = findPhaseInternal(cwd, options.phase);
+  if (!phaseInfo || !phaseInfo.found) { output({ error: 'Phase not found', phase: options.phase }, raw); return; }
+
+  const padded = normalizePhaseName(options.phase);
+  const today = new Date().toISOString().split('T')[0];
+  const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
+  const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
+  const phaseId = `${padded}-${phaseSlug}`;
+  const planNum = (options.plan || '01').padStart(2, '0');
+  const fields = options.fields || {};
+
+  // Build DGS metadata comment for plan and summary templates
+  const author = options.author || 'Unknown';
+  const metadataComment = `<!-- DGS metadata\nAuthor: ${author}\nCreated: ${today}\n-->\n`;
+
+  let frontmatter, body, fileName;
+
+  switch (templateType) {
+    case 'summary': {
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        subsystem: '[primary category]',
+        tags: [],
+        provides: [],
+        affects: [],
+        'tech-stack': { added: [], patterns: [] },
+        'key-files': { created: [], modified: [] },
+        'key-decisions': [],
+        'patterns-established': [],
+        duration: '[X]min',
+        completed: today,
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} Summary`,
+        '',
+        '**[Substantive one-liner describing outcome]**',
+        '',
+        '## Performance',
+        '- **Duration:** [time]',
+        '- **Tasks:** [count completed]',
+        '- **Files modified:** [count]',
+        '',
+        '## Accomplishments',
+        '- [Key outcome 1]',
+        '- [Key outcome 2]',
+        '',
+        '## Task Commits',
+        '1. **Task 1: [task name]** - `hash`',
+        '',
+        '## Files Created/Modified',
+        '- `path/to/file.ts` - What it does',
+        '',
+        '## Decisions & Deviations',
+        '[Key decisions or "None - followed plan as specified"]',
+        '',
+        '## Next Phase Readiness',
+        '[What\'s ready for next phase]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-SUMMARY.md`;
+      break;
+    }
+    case 'plan': {
+      const planType = options.type || 'execute';
+      const wave = parseInt(options.wave) || 1;
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        type: planType,
+        wave,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        user_setup: [],
+        must_haves: { truths: [], artifacts: [], key_links: [] },
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase} Plan ${planNum}: [Title]`,
+        '',
+        '## Objective',
+        '- **What:** [What this plan builds]',
+        '- **Why:** [Why it matters for the phase goal]',
+        '- **Output:** [Concrete deliverable]',
+        '',
+        '## Context',
+        '@.planning/PROJECT.md',
+        '@.planning/ROADMAP.md',
+        '@.planning/STATE.md',
+        '',
+        '## Tasks',
+        '',
+        '<task type="code">',
+        '  <name>[Task name]</name>',
+        '  <files>[file paths]</files>',
+        '  <action>[What to do]</action>',
+        '  <verify>[How to verify]</verify>',
+        '  <done>[Definition of done]</done>',
+        '</task>',
+        '',
+        '## Verification',
+        '[How to verify this plan achieved its objective]',
+        '',
+        '## Success Criteria',
+        '- [ ] [Criterion 1]',
+        '- [ ] [Criterion 2]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-PLAN.md`;
+      break;
+    }
+    case 'verification': {
+      frontmatter = {
+        phase: phaseId,
+        verified: new Date().toISOString(),
+        status: 'pending',
+        score: '0/0 must-haves verified',
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} — Verification`,
+        '',
+        '## Observable Truths',
+        '| # | Truth | Status | Evidence |',
+        '|---|-------|--------|----------|',
+        '| 1 | [Truth] | pending | |',
+        '',
+        '## Required Artifacts',
+        '| Artifact | Expected | Status | Details |',
+        '|----------|----------|--------|---------|',
+        '| [path] | [what] | pending | |',
+        '',
+        '## Key Link Verification',
+        '| From | To | Via | Status | Details |',
+        '|------|----|----|--------|---------|',
+        '| [source] | [target] | [connection] | pending | |',
+        '',
+        '## Requirements Coverage',
+        '| Requirement | Status | Blocking Issue |',
+        '|-------------|--------|----------------|',
+        '| [req] | pending | |',
+        '',
+        '## Result',
+        '[Pending verification]',
+      ].join('\n');
+      fileName = `${padded}-VERIFICATION.md`;
+      break;
+    }
+    default:
+      error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
+      return;
+  }
+
+  const needsMetadata = (templateType === 'plan' || templateType === 'summary');
+  const prefix = needsMetadata ? metadataComment : '';
+  const fullContent = `${prefix}---\n${reconstructFrontmatter(frontmatter)}\n---\n\n${body}\n`;
+  const outPath = path.join(cwd, phaseInfo.directory, fileName);
+
+  if (fs.existsSync(outPath)) {
+    output({ error: 'File already exists', path: toPosixPath(path.relative(cwd, outPath)) }, raw);
+    return;
+  }
+
+  fs.writeFileSync(outPath, fullContent, 'utf-8');
+  const relPath = toPosixPath(path.relative(cwd, outPath));
+  output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

package/deliver-great-systems/bin/lib/test-helpers.cjs

@@ -0,0 +1,291 @@
+/**
+ * Shared test helper module for DGS test suite.
+ *
+ * Provides dual-mode fixture creation (v1 and v2 directory structures),
+ * temp directory management, file writing, and git repo initialization.
+ *
+ * All functions are synchronous, matching existing test patterns.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const { initPaths, resetPaths, PROJECTS_DIR } = require('./paths.cjs');
+
+// ─── Utility Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Creates a temp directory with optional prefix.
+ * @param {string} [prefix='dgs-test-'] - Prefix for the temp directory name.
+ * @returns {string} Absolute path to the created temp directory.
+ */
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix || 'dgs-test-'));
+}
+
+/**
+ * Recursively removes a directory.
+ * @param {string} dir - Absolute path to the directory to remove.
+ */
+function cleanupDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Creates parent directories and writes a file.
+ * @param {string} base - Base directory (absolute path).
+ * @param {string} relPath - Relative path from base.
+ * @param {string} content - File content to write.
+ */
+function writeFile(base, relPath, content) {
+  const fullPath = path.join(base, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+}
+
+/**
+ * Initializes a git repo with an initial commit.
+ * @param {string} dir - Directory to initialize as a git repo.
+ */
+function initGitRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  execSync('git init', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(dir, '.gitkeep'), '');
+  execSync('git add .', { cwd: dir, stdio: 'pipe' });
+  execSync('git commit -m "initial"', { cwd: dir, stdio: 'pipe' });
+}
+
+// ─── Fixture Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Creates a temporary directory with an arbitrary file/folder structure.
+ *
+ * @param {Object} structure - Keys are relative paths, values are file content
+ *   (string) or null (directory). Paths ending with '/' are also treated as directories.
+ * @returns {{ cwd: string, cleanup: () => void }}
+ *
+ * Example:
+ *   createFixture({
+ *     '.planning/config.json': '{}',
+ *     '.planning/STATE.md': '# State',
+ *     '.planning/phases/': null,  // directory
+ *   })
+ */
+function createFixture(structure) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-test-'));
+
+  for (const [relPath, content] of Object.entries(structure)) {
+    const fullPath = path.join(cwd, relPath);
+    if (content === null || relPath.endsWith('/')) {
+      fs.mkdirSync(fullPath, { recursive: true });
+    } else {
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, content, 'utf-8');
+    }
+  }
+
+  // Prime the paths cache for this fixture
+  initPaths(cwd);
+
+  return {
+    cwd,
+    cleanup: function cleanup() {
+      resetPaths();
+      fs.rmSync(cwd, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Creates a temporary project fixture with either v1 or v2 directory structure.
+ *
+ * @param {Object} [options={}]
+ * @param {number} [options.version=1] - 1 for v1 flat structure, 2 for v2 multi-project.
+ * @param {string} [options.project] - Project slug (required when version=2).
+ * @param {string} [options.projectName] - Display name (defaults to title-casing the slug).
+ * @param {boolean} [options.withGit=false] - Initialize as git repo and commit the structure.
+ * @param {Object} [options.withConfig] - Additional config.json fields to merge.
+ * @param {boolean} [options.withPhases=true] - Create phases/ directory with sample plan.
+ * @param {boolean} [options.withTodos=false] - Create todos/pending/ and todos/completed/.
+ * @param {boolean} [options.withResearch=false] - Create research/ directory.
+ * @returns {{ cwd: string, cleanup: () => void, planningDir: string, projectRoot: string }}
+ */
+function createTempProject(options) {
+  const opts = options || {};
+  const version = opts.version || 1;
+  const layout = opts.layout || 'dotplanning';
+  const project = opts.project || null;
+  const projectName = opts.projectName || titleCase(project || 'Test Project');
+  const withGit = opts.withGit || false;
+  const withConfig = opts.withConfig || {};
+  const withPhases = opts.withPhases !== undefined ? opts.withPhases : true;
+  const withTodos = opts.withTodos || false;
+  const withResearch = opts.withResearch || false;
+
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-test-'));
+
+  // If withGit, initialize repo first
+  if (withGit) {
+    initGitRepo(cwd);
+  }
+
+  var planningDir;
+  var projectRoot;
+
+  if (layout === 'root') {
+    // Root layout: planning files live at repo root, dgs.config.json at root
+    planningDir = cwd;
+    projectRoot = '.';
+
+    // Write dgs.config.json at repo root with planningRoot: '.'
+    var rootConfigData = Object.assign({ planningRoot: '.' }, withConfig);
+    writeFile(cwd, 'dgs.config.json', JSON.stringify(rootConfigData));
+
+    // Project files at root
+    writeFile(cwd, 'PROJECT.md', '# Project: ' + projectName + '\n');
+    writeFile(cwd, 'REQUIREMENTS.md', '# Requirements\n');
+    writeFile(cwd, 'ROADMAP.md', '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n');
+    writeFile(cwd, 'STATE.md', '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [░░░░░░░░░░] 0%\n');
+
+    // v2 markers at root (for completeness if root-layout + v2 ever used)
+    writeFile(cwd, 'PROJECTS.md', '# Projects\n');
+    writeFile(cwd, 'REPOS.md', '# Repos\n');
+
+    if (withPhases) {
+      writeFile(cwd, 'phases/01-test-phase/01-01-PLAN.md',
+        '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan\n');
+    }
+
+    if (withTodos) {
+      fs.mkdirSync(path.join(cwd, 'todos', 'pending'), { recursive: true });
+      fs.mkdirSync(path.join(cwd, 'todos', 'completed'), { recursive: true });
+    }
+
+    if (withResearch) {
+      fs.mkdirSync(path.join(cwd, 'research'), { recursive: true });
+    }
+
+  } else if (version === 2) {
+    if (!project) {
+      throw new Error('createTempProject: version 2 requires a project slug');
+    }
+    planningDir = path.join(cwd, '.planning');
+    projectRoot = path.join('.planning', PROJECTS_DIR, project);
+    var absProjectRoot = path.join(cwd, '.planning', PROJECTS_DIR, project);
+
+    // Product-level config
+    var configData = Object.assign({ current_project: project }, withConfig);
+    writeFile(cwd, '.planning/config.json', JSON.stringify(configData));
+
+    // v2 markers
+    var projectsMd = '# Projects\n\n## Active\n\n';
+    projectsMd += '| Project | Status | Repos Touched | Current Phase |\n';
+    projectsMd += '|---------|--------|---------------|---------------|\n';
+    projectsMd += '| ' + project + ' | Active |  | Phase 1 |\n';
+    projectsMd += '\n## Completed\n\n';
+    projectsMd += '| Project | Completed | Duration |\n';
+    projectsMd += '|---------|-----------|----------|\n';
+    writeFile(cwd, '.planning/PROJECTS.md', projectsMd);
+
+    var reposMd = '# Repos\n\n';
+    reposMd += 'Registered repositories for this product. Managed by DGS — manual edits may be overwritten.\n\n';
+    reposMd += '| Name | Path | GitHub URL | Description |\n';
+    reposMd += '|------|------|------------|-------------|\n';
+    writeFile(cwd, '.planning/REPOS.md', reposMd);
+
+    // Project-level files under .planning/projects/<slug>/
+    writeFile(cwd, path.join('.planning', PROJECTS_DIR, project, 'PROJECT.md'), '# Project: ' + projectName + '\n');
+    writeFile(cwd, path.join('.planning', PROJECTS_DIR, project, 'REQUIREMENTS.md'), '# Requirements\n');
+    writeFile(cwd, path.join('.planning', PROJECTS_DIR, project, 'ROADMAP.md'), '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n');
+    writeFile(cwd, path.join('.planning', PROJECTS_DIR, project, 'STATE.md'), '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [░░░░░░░░░░] 0%\n');
+
+    if (withPhases) {
+      writeFile(cwd, path.join('.planning', PROJECTS_DIR, project, 'phases', '01-test-phase', '01-01-PLAN.md'),
+        '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan\n');
+    }
+
+    if (withTodos) {
+      fs.mkdirSync(path.join(cwd, '.planning', PROJECTS_DIR, project, 'todos', 'pending'), { recursive: true });
+      fs.mkdirSync(path.join(cwd, '.planning', PROJECTS_DIR, project, 'todos', 'completed'), { recursive: true });
+    }
+
+    if (withResearch) {
+      fs.mkdirSync(path.join(cwd, '.planning', PROJECTS_DIR, project, 'research'), { recursive: true });
+    }
+
+  } else {
+    // v1 mode (dotplanning layout)
+    planningDir = path.join(cwd, '.planning');
+    projectRoot = '.planning';
+
+    // config.json
+    var v1ConfigData = Object.assign({}, withConfig);
+    writeFile(cwd, '.planning/config.json', JSON.stringify(v1ConfigData));
+
+    // Project files
+    writeFile(cwd, '.planning/PROJECT.md', '# Project: ' + projectName + '\n');
+    writeFile(cwd, '.planning/REQUIREMENTS.md', '# Requirements\n');
+    writeFile(cwd, '.planning/ROADMAP.md', '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n');
+    writeFile(cwd, '.planning/STATE.md', '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [░░░░░░░░░░] 0%\n');
+
+    if (withPhases) {
+      writeFile(cwd, '.planning/phases/01-test-phase/01-01-PLAN.md',
+        '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan\n');
+    }
+
+    if (withTodos) {
+      fs.mkdirSync(path.join(cwd, '.planning', 'todos', 'pending'), { recursive: true });
+      fs.mkdirSync(path.join(cwd, '.planning', 'todos', 'completed'), { recursive: true });
+    }
+
+    if (withResearch) {
+      fs.mkdirSync(path.join(cwd, '.planning', 'research'), { recursive: true });
+    }
+  }
+
+  // If withGit, commit the fixture structure
+  if (withGit) {
+    execSync('git add .', { cwd: cwd, stdio: 'pipe' });
+    execSync('git commit -m "test fixture"', { cwd: cwd, stdio: 'pipe' });
+  }
+
+  // Prime the paths cache for this fixture
+  initPaths(cwd);
+
+  return {
+    cwd: cwd,
+    cleanup: function cleanup() {
+      resetPaths();
+      fs.rmSync(cwd, { recursive: true, force: true });
+    },
+    planningDir: planningDir,
+    projectRoot: projectRoot,
+  };
+}
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Converts a slug or plain string to title case.
+ * @param {string} str
+ * @returns {string}
+ */
+function titleCase(str) {
+  return str
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, function (c) { return c.toUpperCase(); });
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  createTempDir,
+  cleanupDir,
+  writeFile,
+  initGitRepo,
+  createFixture,
+  createTempProject,
+};