@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/query/template.ts

@@ -0,0 +1,242 @@
+/**
+ * Template handlers — template selection and fill operations.
+ *
+ * Ported from get-shit-done/bin/lib/template.cjs.
+ * Provides templateSelect (heuristic template type selection) and
+ * templateFill (create file from template with auto-generated frontmatter).
+ *
+ * @example
+ * ```typescript
+ * import { templateSelect, templateFill } from './template.js';
+ *
+ * const selectResult = await templateSelect(['9'], projectDir);
+ * // { data: { template: 'summary' } }
+ *
+ * const fillResult = await templateFill(['summary', '/path/out.md', 'phase=09'], projectDir);
+ * // { data: { created: true, path: '/path/out.md', template: 'summary' } }
+ * ```
+ */
+
+import { readdir, writeFile } from 'node:fs/promises';
+import { join, resolve, relative } from 'node:path';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { reconstructFrontmatter, spliceFrontmatter } from './frontmatter-mutation.js';
+import { normalizeMd, planningPaths, normalizePhaseName, phaseTokenMatches } from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+// ─── templateSelect ─────────────────────────────────────────────────────────
+
+/**
+ * Select the appropriate template type based on phase directory contents.
+ *
+ * Heuristic:
+ * - Has all PLAN+SUMMARY pairs -> "verification"
+ * - Has PLAN but missing SUMMARY for latest plan -> "summary"
+ * - Else -> "plan" (default)
+ *
+ * @param args - [phaseNumber?] Optional phase number to check
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { template: 'plan' | 'summary' | 'verification' }
+ */
+export const templateSelect: QueryHandler = async (args, projectDir, workstream) => {
+  const phaseNum = args[0];
+  if (!phaseNum) {
+    return { data: { template: 'plan' } };
+  }
+
+  const paths = planningPaths(projectDir, workstream);
+  const normalized = normalizePhaseName(phaseNum);
+
+  // Find the phase directory
+  let phaseDir: string | null = null;
+  try {
+    const entries = await readdir(paths.phases);
+    for (const entry of entries) {
+      if (phaseTokenMatches(entry, normalized)) {
+        phaseDir = join(paths.phases, entry);
+        break;
+      }
+    }
+  } catch {
+    return { data: { template: 'plan' } };
+  }
+
+  if (!phaseDir) {
+    return { data: { template: 'plan' } };
+  }
+
+  // Read directory contents and check for plans/summaries
+  try {
+    const files = await readdir(phaseDir);
+    const plans = files.filter(f => f.match(/-PLAN\.md$/i));
+    const summaries = files.filter(f => f.match(/-SUMMARY\.md$/i));
+
+    if (plans.length === 0) {
+      return { data: { template: 'plan' } };
+    }
+
+    // Check if all plans have corresponding summaries
+    const allHaveSummaries = plans.every(plan => {
+      // Extract plan number: e.g., 09-01-PLAN.md -> 09-01
+      const prefix = plan.replace(/-PLAN\.md$/i, '');
+      return summaries.some(s => s.startsWith(prefix));
+    });
+
+    if (allHaveSummaries) {
+      return { data: { template: 'verification' } };
+    }
+
+    return { data: { template: 'summary' } };
+  } catch {
+    return { data: { template: 'plan' } };
+  }
+};
+
+// ─── templateFill ───────────────────────────────────────────────────────────
+
+/**
+ * Create a file from a template type with auto-generated frontmatter.
+ *
+ * Port of cmdTemplateFill from template.cjs.
+ *
+ * @param args - [templateType, outputPath, ...key=value overrides]
+ *   templateType: "summary" | "plan" | "verification"
+ *   outputPath: Absolute or relative path for output file
+ *   key=value: Optional frontmatter field overrides
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { created: true, path, template }
+ */
+export const templateFill: QueryHandler = async (args, projectDir) => {
+  const templateType = args[0];
+  const outputPath = args[1];
+
+  if (!templateType) {
+    throw new GSDError(
+      'template type required: summary, plan, or verification',
+      ErrorClassification.Validation,
+    );
+  }
+  if (!outputPath) {
+    throw new GSDError(
+      'output path required',
+      ErrorClassification.Validation,
+    );
+  }
+
+  // T-11-10: Reject path traversal attempts
+  const resolvedOut = resolve(projectDir, outputPath);
+  const rel = relative(projectDir, resolvedOut);
+  if (rel.startsWith('..') || rel.includes('..')) {
+    throw new GSDError(
+      `Output path escapes project directory: ${outputPath}`,
+      ErrorClassification.Validation,
+    );
+  }
+
+  // Parse key=value overrides from remaining args
+  const overrides: Record<string, unknown> = {};
+  for (let i = 2; i < args.length; i++) {
+    const eqIdx = args[i].indexOf('=');
+    if (eqIdx > 0) {
+      overrides[args[i].slice(0, eqIdx)] = args[i].slice(eqIdx + 1);
+    }
+  }
+
+  let fm: Record<string, unknown>;
+  let body: string;
+
+  switch (templateType) {
+    case 'summary': {
+      fm = {
+        phase: '', plan: '', subsystem: '', tags: [],
+        requires: [], provides: [], affects: [],
+        'tech-stack': { added: [], patterns: [] },
+        'key-files': { created: [], modified: [] },
+        'key-decisions': [], 'patterns-established': [],
+        'requirements-completed': [],
+        duration: '', completed: '',
+      };
+      body = [
+        '# Phase {phase} Plan {plan}: Summary',
+        '',
+        '## Performance',
+        '',
+        '## Accomplishments',
+        '',
+        '## Task Commits',
+        '',
+        '## Files Created/Modified',
+        '',
+        '## Decisions Made',
+        '',
+        '## Deviations from Plan',
+        '',
+        '## Issues Encountered',
+        '',
+        '## User Setup Required',
+        '',
+        '## Next Phase Readiness',
+        '',
+        '## Self-Check',
+      ].join('\n');
+      break;
+    }
+    case 'plan': {
+      fm = {
+        phase: '', plan: '', type: 'execute', wave: 1,
+        depends_on: [], files_modified: [], autonomous: true,
+        requirements: [], must_haves: { truths: [], artifacts: [], key_links: [] },
+      };
+      body = [
+        '<objective>',
+        '</objective>',
+        '',
+        '<context>',
+        '</context>',
+        '',
+        '<tasks>',
+        '</tasks>',
+        '',
+        '<verification>',
+        '</verification>',
+        '',
+        '<success_criteria>',
+        '</success_criteria>',
+      ].join('\n');
+      break;
+    }
+    case 'verification': {
+      fm = {
+        phase: '', status: 'pending', verified_at: '',
+      };
+      body = [
+        '# Phase {phase} Verification',
+        '',
+        '## Must-Have Checks',
+        '',
+        '## Artifact Verification',
+        '',
+        '## Key-Link Verification',
+        '',
+        '## Result',
+      ].join('\n');
+      break;
+    }
+    default:
+      throw new GSDError(
+        `Unknown template type: ${templateType}. Available: summary, plan, verification`,
+        ErrorClassification.Validation,
+      );
+  }
+
+  // Apply overrides
+  Object.assign(fm, overrides);
+
+  // Generate content
+  const content = spliceFrontmatter('', fm) + '\n' + body + '\n';
+  const normalized = normalizeMd(content);
+
+  await writeFile(resolvedOut, normalized, 'utf-8');
+
+  return { data: { created: true, path: outputPath, template: templateType } };
+};

package/sdk/src/query/uat.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests for UAT query handlers.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { uatRenderCheckpoint, auditUat } from './uat.js';
+
+const SAMPLE_UAT = `---
+status: draft
+---
+# UAT
+
+## Current Test
+
+number: 1
+name: Login flow
+expected: |
+  User can sign in
+
+## Other
+`;
+
+describe('uatRenderCheckpoint', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-uat-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns error when --file is missing', async () => {
+    const r = await uatRenderCheckpoint([], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.error).toBeDefined();
+  });
+
+  it('renders checkpoint for valid UAT file', async () => {
+    const f = join(tmpDir, '01-UAT.md');
+    await writeFile(f, SAMPLE_UAT, 'utf-8');
+    const r = await uatRenderCheckpoint(['--file', '01-UAT.md'], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(data.checkpoint).toBeDefined();
+    expect(String(data.checkpoint)).toContain('CHECKPOINT');
+    expect(data.test_number).toBe(1);
+  });
+});
+
+describe('auditUat', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-uat-audit-'));
+    await mkdir(join(tmpDir, '.planning', 'phases', '01-x'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns empty results when no UAT files', async () => {
+    const r = await auditUat([], tmpDir);
+    const data = r.data as Record<string, unknown>;
+    expect(Array.isArray(data.results)).toBe(true);
+    const summary = data.summary as Record<string, unknown>;
+    expect(summary.total_files).toBe(0);
+    expect(summary.total_items).toBe(0);
+    expect(summary.by_category).toEqual({});
+    expect(summary.by_phase).toEqual({});
+  });
+});

package/sdk/src/query/uat.ts

@@ -0,0 +1,365 @@
+/**
+ * UAT query handlers — checkpoint rendering and audit scanning.
+ *
+ * Ported from get-shit-done/bin/lib/uat.cjs.
+ * Provides UAT checkpoint rendering for verify-work workflows and
+ * audit scanning for UAT/VERIFICATION files across phases.
+ *
+ * @example
+ * ```typescript
+ * import { uatRenderCheckpoint, auditUat } from './uat.js';
+ *
+ * await uatRenderCheckpoint(['--file', 'path/to/UAT.md'], '/project');
+ * // { data: { test_number: 1, test_name: 'Login', checkpoint: '...' } }
+ *
+ * await auditUat([], '/project');
+ * // { data: { results: [...], summary: { total_files: 2, total_items: 5 } } }
+ * ```
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { GSDError, ErrorClassification } from '../errors.js';
+import { extractFrontmatter } from './frontmatter.js';
+import { planningPaths, resolvePathUnderProject, sanitizeForDisplay, toPosixPath } from './helpers.js';
+import { getMilestonePhaseFilter } from './state.js';
+import type { QueryHandler } from './utils.js';
+
+/** Same string as `buildCheckpoint` in `get-shit-done/bin/lib/uat.cjs`. */
+function buildUatCheckpoint(currentTest: { number: number; name: string; expected: string }): string {
+  return [
+    '╔══════════════════════════════════════════════════════════════╗',
+    '║  CHECKPOINT: Verification Required                           ║',
+    '╚══════════════════════════════════════════════════════════════╝',
+    '',
+    `**Test ${currentTest.number}: ${currentTest.name}**`,
+    '',
+    currentTest.expected,
+    '',
+    '──────────────────────────────────────────────────────────────',
+    'Type `pass` or describe what\'s wrong.',
+    '──────────────────────────────────────────────────────────────',
+  ].join('\n');
+}
+
+// ─── uatRenderCheckpoint ─────────────────────────────────────────────────
+
+/**
+ * Render the current UAT checkpoint — reads a UAT file, parses the
+ * "Current Test" section, and returns a formatted checkpoint prompt.
+ *
+ * Port of `cmdRenderCheckpoint` from `uat.cjs` (paths via `requireSafePath`,
+ * checkpoint via `buildCheckpoint`, name/expected via `sanitizeForDisplay`).
+ *
+ * Args: --file <path>
+ */
+export const uatRenderCheckpoint: QueryHandler = async (args, projectDir) => {
+  const fileIdx = args.indexOf('--file');
+  const filePath = fileIdx !== -1 ? args[fileIdx + 1] : null;
+  if (!filePath) {
+    return { data: { error: 'UAT file required: use uat render-checkpoint --file <path>' } };
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = await resolvePathUnderProject(projectDir, filePath);
+  } catch {
+    return { data: { error: `UAT file not found: ${filePath}` } };
+  }
+
+  if (!existsSync(resolvedPath)) {
+    return { data: { error: `UAT file not found: ${filePath}` } };
+  }
+
+  const content = readFileSync(resolvedPath, 'utf-8');
+
+  const currentTestMatch = content.match(/##\s*Current Test\s*(?:\n<!--[\s\S]*?-->)?\n([\s\S]*?)(?=\n##\s|$)/i);
+  if (!currentTestMatch) {
+    return { data: { error: 'UAT file is missing a Current Test section' } };
+  }
+
+  const section = currentTestMatch[1].trimEnd();
+  if (!section.trim()) {
+    return { data: { error: 'Current Test section is empty' } };
+  }
+
+  if (/\[testing complete\]/i.test(section)) {
+    return { data: { error: 'UAT session is already complete; no pending checkpoint to render' } };
+  }
+
+  const numberMatch = section.match(/^number:\s*(\d+)\s*$/m);
+  const nameMatch = section.match(/^name:\s*(.+)\s*$/m);
+  const expectedBlockMatch = section.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
+    || section.match(/^expected:\s*\|\n([\s\S]+)/m);
+  const expectedInlineMatch = section.match(/^expected:\s*(.+)\s*$/m);
+
+  if (!numberMatch || !nameMatch || (!expectedBlockMatch && !expectedInlineMatch)) {
+    return { data: { error: 'Current Test section is malformed' } };
+  }
+
+  let expectedRaw: string;
+  if (expectedBlockMatch) {
+    expectedRaw = expectedBlockMatch[1]
+      .split('\n')
+      .map(line => line.replace(/^ {2}/, ''))
+      .join('\n')
+      .trim();
+  } else {
+    expectedRaw = expectedInlineMatch![1].trim();
+  }
+
+  const currentTest = {
+    complete: false as const,
+    number: parseInt(numberMatch[1], 10),
+    name: sanitizeForDisplay(nameMatch[1].trim()),
+    expected: sanitizeForDisplay(expectedRaw),
+  };
+
+  const checkpoint = buildUatCheckpoint(currentTest);
+
+  return {
+    data: {
+      file_path: toPosixPath(relative(projectDir, resolvedPath)),
+      test_number: currentTest.number,
+      test_name: currentTest.name,
+      checkpoint,
+    },
+  };
+};
+
+// ─── auditUat (cmdAuditUat) ────────────────────────────────────────────────
+
+/** Port of `categorizeItem` from `uat.cjs`. */
+function categorizeItem(
+  result: string,
+  reason: string | undefined,
+  blockedBy: string | undefined,
+): string {
+  if (result === 'blocked' || blockedBy) {
+    if (blockedBy) {
+      if (/server/i.test(blockedBy)) return 'server_blocked';
+      if (/device|physical/i.test(blockedBy)) return 'device_needed';
+      if (/build|release|preview/i.test(blockedBy)) return 'build_needed';
+      if (/third.party|twilio|stripe/i.test(blockedBy)) return 'third_party';
+    }
+    return 'blocked';
+  }
+  if (result === 'skipped') {
+    if (reason) {
+      if (/server|not running|not available/i.test(reason)) return 'server_blocked';
+      if (/simulator|physical|device/i.test(reason)) return 'device_needed';
+      if (/build|release|preview/i.test(reason)) return 'build_needed';
+    }
+    return 'skipped_unresolved';
+  }
+  if (result === 'pending') return 'pending';
+  if (result === 'human_needed') return 'human_uat';
+  return 'unknown';
+}
+
+/** Port of `parseUatItems` from `uat.cjs`. */
+function parseUatItems(content: string): Record<string, unknown>[] {
+  const items: Record<string, unknown>[] = [];
+  const testPattern =
+    /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*(\w+)(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
+  let match: RegExpExecArray | null;
+  while ((match = testPattern.exec(content)) !== null) {
+    const [, num, name, expected, result] = match;
+    if (result === 'pending' || result === 'skipped' || result === 'blocked') {
+      const afterMatch = content.slice(match.index);
+      const nextHeading = afterMatch.indexOf('\n###', 1);
+      const blockText = nextHeading > 0 ? afterMatch.slice(0, nextHeading) : afterMatch;
+      const reasonMatch = blockText.match(/reason:\s*(.+)/);
+      const blockedByMatch = blockText.match(/blocked_by:\s*(.+)/);
+
+      const item: Record<string, unknown> = {
+        test: parseInt(num, 10),
+        name: name.trim(),
+        expected: expected.trim(),
+        result,
+        category: categorizeItem(result, reasonMatch?.[1], blockedByMatch?.[1]),
+      };
+      if (reasonMatch) item.reason = reasonMatch[1].trim();
+      if (blockedByMatch) item.blocked_by = blockedByMatch[1].trim();
+      items.push(item);
+    }
+  }
+  return items;
+}
+
+/**
+ * Parse frontmatter human_verification: YAML array entries into audit items.
+ *
+ * Fixes #2788: when gsd-verifier encodes human items in YAML frontmatter
+ * rather than the body, parseVerificationItems was returning [] because it
+ * only searched the body for a "## Human Verification" heading.
+ */
+export function parseVerificationFrontmatterItems(fm: Record<string, unknown>): Record<string, unknown>[] {
+  const items: Record<string, unknown>[] = [];
+  const hvArray = fm.human_verification;
+  if (!Array.isArray(hvArray)) return items;
+
+  let i = 0;
+  for (const entry of hvArray) {
+    i++;
+    if (typeof entry === 'string') {
+      const name = entry.trim();
+      if (name.length > 0) {
+        items.push({ test: i, name, result: 'human_needed', category: 'human_uat' });
+      }
+    } else if (typeof entry === 'object' && entry !== null) {
+      const obj = entry as Record<string, unknown>;
+      // Accept any string property as the item name; prefer 'test' key.
+      const name = (obj.test as string | undefined) || (obj.name as string | undefined) || '';
+      if (name) {
+        const item: Record<string, unknown> = {
+          test: i,
+          name: String(name).trim(),
+          result: 'human_needed',
+          category: 'human_uat',
+        };
+        if (obj.expected) item.expected = String(obj.expected).trim();
+        if (obj.why_human) item.why_human = String(obj.why_human).trim();
+        items.push(item);
+      }
+    }
+  }
+  return items;
+}
+
+/** Port of `parseVerificationItems` from `uat.cjs`. */
+function parseVerificationItems(content: string, status: string, fm?: Record<string, unknown>): Record<string, unknown>[] {
+  const items: Record<string, unknown>[] = [];
+  if (status === 'human_needed') {
+    // Check frontmatter human_verification: array first (#2788).
+    // gsd-verifier writes items here; body-section fallback is secondary.
+    if (fm) {
+      const fmItems = parseVerificationFrontmatterItems(fm);
+      if (fmItems.length > 0) return fmItems;
+    }
+
+    // Body fallback: match ## human_verification or ## Human Verification
+    // (case-insensitive, underscore or space, with optional parenthetical).
+    const hvSection = content.match(
+      /##\s*human[_\s-]verification[^\n]*\n([\s\S]*?)(?=\n##\s|\n---\s|$)/i
+    );
+    if (hvSection) {
+      const lines = hvSection[1].split('\n');
+      for (const line of lines) {
+        const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);
+        const bulletMatch = line.match(/^[-*]\s+(.+)/);
+        const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
+
+        if (tableMatch) {
+          items.push({
+            test: parseInt(tableMatch[1], 10),
+            name: tableMatch[2].trim(),
+            result: 'human_needed',
+            category: 'human_uat',
+          });
+        } else if (numberedMatch) {
+          items.push({
+            test: parseInt(numberedMatch[1], 10),
+            name: numberedMatch[2].trim(),
+            result: 'human_needed',
+            category: 'human_uat',
+          });
+        } else if (bulletMatch && bulletMatch[1].length > 10) {
+          items.push({
+            name: bulletMatch[1].trim(),
+            result: 'human_needed',
+            category: 'human_uat',
+          });
+        }
+      }
+    }
+  }
+  return items;
+}
+
+/**
+ * Cross-phase UAT / VERIFICATION audit — port of `cmdAuditUat` (`uat.cjs`).
+ */
+export const auditUat: QueryHandler = async (_args, projectDir, workstream) => {
+  const paths = planningPaths(projectDir, workstream);
+  if (!existsSync(paths.phases)) {
+    throw new GSDError('No phases directory found in planning directory', ErrorClassification.Blocked);
+  }
+
+  const isDirInMilestone = await getMilestonePhaseFilter(projectDir, workstream);
+  const results: Record<string, unknown>[] = [];
+
+  const dirs = readdirSync(paths.phases, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .filter(isDirInMilestone)
+    .sort();
+
+  for (const dir of dirs) {
+    const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+    const phaseNum = phaseMatch ? phaseMatch[1] : dir;
+    const phaseDir = join(paths.phases, dir);
+    const files = readdirSync(phaseDir);
+
+    for (const file of files.filter(f => f.includes('-UAT') && f.endsWith('.md'))) {
+      const content = readFileSync(join(phaseDir, file), 'utf-8');
+      const items = parseUatItems(content);
+      if (items.length > 0) {
+        const fm = extractFrontmatter(content);
+        results.push({
+          phase: phaseNum,
+          phase_dir: dir,
+          file,
+          file_path: toPosixPath(relative(projectDir, join(phaseDir, file))),
+          type: 'uat',
+          status: (fm.status || 'unknown') as string,
+          items,
+        });
+      }
+    }
+
+    for (const file of files.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
+      const content = readFileSync(join(phaseDir, file), 'utf-8');
+      const fm = extractFrontmatter(content);
+      const status = (fm.status || 'unknown') as string;
+      if (status === 'human_needed' || status === 'gaps_found') {
+        const items = parseVerificationItems(content, status, fm);
+        if (items.length > 0) {
+          results.push({
+            phase: phaseNum,
+            phase_dir: dir,
+            file,
+            file_path: toPosixPath(relative(projectDir, join(phaseDir, file))),
+            type: 'verification',
+            status,
+            items,
+          });
+        }
+      }
+    }
+  }
+
+  const summary: {
+    total_files: number;
+    total_items: number;
+    by_category: Record<string, number>;
+    by_phase: Record<string, number>;
+  } = {
+    total_files: results.length,
+    total_items: results.reduce((sum, r) => sum + (r.items as unknown[]).length, 0),
+    by_category: {},
+    by_phase: {},
+  };
+
+  for (const r of results) {
+    if (!summary.by_phase[r.phase as string]) summary.by_phase[r.phase as string] = 0;
+    for (const item of r.items as Array<{ category?: string }>) {
+      summary.by_phase[r.phase as string]++;
+      const cat = item.category || 'unknown';
+      summary.by_category[cat] = (summary.by_category[cat] || 0) + 1;
+    }
+  }
+
+  return { data: { results, summary } };
+};