gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/gsd/db-writer.js

@@ -0,0 +1,298 @@
+// GSD DB Writer — Markdown generators + DB-first write helpers
+//
+// The missing DB→markdown direction. S03 established markdown→DB (md-importer.ts).
+// This module generates DECISIONS.md and REQUIREMENTS.md from DB state,
+// computes next decision IDs, and provides write helpers that upsert to DB
+// then regenerate the corresponding markdown file.
+//
+// Critical invariant: generated markdown must round-trip through
+// parseDecisionsTable() and parseRequirementsSections() with field fidelity.
+import { resolve } from 'node:path';
+import { resolveGsdRootFile } from './paths.js';
+import { saveFile } from './files.js';
+import { GSDError, GSD_STALE_STATE, GSD_IO_ERROR } from './errors.js';
+import { invalidateStateCache } from './state.js';
+import { clearPathCache } from './paths.js';
+import { clearParseCache } from './files.js';
+// ─── Markdown Generators ──────────────────────────────────────────────────
+/**
+ * Generate full DECISIONS.md content from an array of Decision objects.
+ * Produces the canonical format: H1 header, HTML comment block, table header,
+ * separator, and one data row per decision.
+ *
+ * Column order: #, When, Scope, Decision, Choice, Rationale, Revisable?
+ */
+export function generateDecisionsMd(decisions) {
+    const lines = [];
+    lines.push('# Decisions Register');
+    lines.push('');
+    lines.push('<!-- Append-only. Never edit or remove existing rows.');
+    lines.push('     To reverse a decision, add a new row that supersedes it.');
+    lines.push('     Read this file at the start of any planning or research phase. -->');
+    lines.push('');
+    lines.push('| # | When | Scope | Decision | Choice | Rationale | Revisable? |');
+    lines.push('|---|------|-------|----------|--------|-----------|------------|');
+    for (const d of decisions) {
+        // Escape pipe characters within cell values to preserve table structure
+        const cells = [
+            d.id,
+            d.when_context,
+            d.scope,
+            d.decision,
+            d.choice,
+            d.rationale,
+            d.revisable,
+        ].map(cell => (cell ?? '').replace(/\|/g, '\\|'));
+        lines.push(`| ${cells.join(' | ')} |`);
+    }
+    return lines.join('\n') + '\n';
+}
+// ─── Requirements Markdown Generator ──────────────────────────────────────
+/** Status values that map to specific sections, in display order. */
+const STATUS_SECTION_MAP = [
+    { status: 'active', heading: 'Active' },
+    { status: 'validated', heading: 'Validated' },
+    { status: 'deferred', heading: 'Deferred' },
+    { status: 'out-of-scope', heading: 'Out of Scope' },
+];
+/**
+ * Generate full REQUIREMENTS.md content from an array of Requirement objects.
+ * Groups requirements by status into sections (## Active, ## Validated, etc.),
+ * each containing ### RXXX — Description headings with bullet fields.
+ * Only emits sections that have content. Appends Traceability table and
+ * Coverage Summary at the bottom.
+ */
+export function generateRequirementsMd(requirements) {
+    const lines = [];
+    lines.push('# Requirements');
+    lines.push('');
+    lines.push('This file is the explicit capability and coverage contract for the project.');
+    lines.push('');
+    // Group by status
+    const byStatus = new Map();
+    for (const r of requirements) {
+        const status = (r.status || 'active').toLowerCase();
+        if (!byStatus.has(status))
+            byStatus.set(status, []);
+        byStatus.get(status).push(r);
+    }
+    // Emit sections in canonical order
+    for (const { status, heading } of STATUS_SECTION_MAP) {
+        const reqs = byStatus.get(status);
+        if (!reqs || reqs.length === 0)
+            continue;
+        lines.push(`## ${heading}`);
+        lines.push('');
+        for (const r of reqs) {
+            lines.push(`### ${r.id} — ${r.description || 'Untitled'}`);
+            // Emit bullet fields — only those with content
+            if (r.class)
+                lines.push(`- Class: ${r.class}`);
+            if (r.status)
+                lines.push(`- Status: ${r.status}`);
+            if (r.description)
+                lines.push(`- Description: ${r.description}`);
+            if (r.why)
+                lines.push(`- Why it matters: ${r.why}`);
+            if (r.source)
+                lines.push(`- Source: ${r.source}`);
+            if (r.primary_owner)
+                lines.push(`- Primary owning slice: ${r.primary_owner}`);
+            if (r.supporting_slices)
+                lines.push(`- Supporting slices: ${r.supporting_slices}`);
+            if (r.validation)
+                lines.push(`- Validation: ${r.validation}`);
+            if (r.notes)
+                lines.push(`- Notes: ${r.notes}`);
+            lines.push('');
+        }
+    }
+    // Traceability table
+    lines.push('## Traceability');
+    lines.push('');
+    lines.push('| ID | Class | Status | Primary owner | Supporting | Proof |');
+    lines.push('|---|---|---|---|---|---|');
+    for (const r of requirements) {
+        const proof = r.validation || 'unmapped';
+        lines.push(`| ${r.id} | ${r.class || ''} | ${r.status || ''} | ${r.primary_owner || 'none'} | ${r.supporting_slices || 'none'} | ${proof} |`);
+    }
+    lines.push('');
+    // Coverage Summary
+    const activeCount = byStatus.get('active')?.length ?? 0;
+    const validatedReqs = byStatus.get('validated') ?? [];
+    const validatedIds = validatedReqs.map(r => r.id).join(', ');
+    lines.push('## Coverage Summary');
+    lines.push('');
+    lines.push(`- Active requirements: ${activeCount}`);
+    lines.push(`- Mapped to slices: ${activeCount}`);
+    lines.push(`- Validated: ${validatedReqs.length}${validatedIds ? ` (${validatedIds})` : ''}`);
+    lines.push(`- Unmapped active requirements: 0`);
+    return lines.join('\n') + '\n';
+}
+// ─── Next Decision ID ─────────────────────────────────────────────────────
+/**
+ * Compute the next decision ID from the current DB state.
+ * Queries MAX(CAST(SUBSTR(id, 2) AS INTEGER)) from decisions table.
+ * Returns D001 if no decisions exist. Zero-pads to 3 digits.
+ */
+export async function nextDecisionId() {
+    try {
+        const db = await import('./gsd-db.js');
+        const adapter = db._getAdapter();
+        if (!adapter)
+            return 'D001';
+        const row = adapter
+            .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
+            .get();
+        const maxNum = row ? row['max_num'] : null;
+        if (maxNum == null || isNaN(maxNum))
+            return 'D001';
+        const next = maxNum + 1;
+        return `D${String(next).padStart(3, '0')}`;
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: nextDecisionId failed: ${err.message}\n`);
+        return 'D001';
+    }
+}
+/**
+ * Save a new decision to DB and regenerate DECISIONS.md.
+ * Auto-assigns the next ID via nextDecisionId().
+ * Returns the assigned ID.
+ */
+export async function saveDecisionToDb(fields, basePath) {
+    try {
+        const db = await import('./gsd-db.js');
+        const id = await nextDecisionId();
+        db.upsertDecision({
+            id,
+            when_context: fields.when_context ?? '',
+            scope: fields.scope,
+            decision: fields.decision,
+            choice: fields.choice,
+            rationale: fields.rationale,
+            revisable: fields.revisable ?? 'Yes',
+            superseded_by: null,
+        });
+        // Fetch all decisions (including superseded for the full register)
+        const adapter = db._getAdapter();
+        let allDecisions = [];
+        if (adapter) {
+            const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
+            allDecisions = rows.map(row => ({
+                seq: row['seq'],
+                id: row['id'],
+                when_context: row['when_context'],
+                scope: row['scope'],
+                decision: row['decision'],
+                choice: row['choice'],
+                rationale: row['rationale'],
+                revisable: row['revisable'],
+                superseded_by: row['superseded_by'] ?? null,
+            }));
+        }
+        const md = generateDecisionsMd(allDecisions);
+        const filePath = resolveGsdRootFile(basePath, 'DECISIONS');
+        await saveFile(filePath, md);
+        // Invalidate file-read caches so deriveState() sees the updated markdown.
+        // Do NOT clear the artifacts table — we just wrote to it intentionally.
+        invalidateStateCache();
+        clearPathCache();
+        clearParseCache();
+        return { id };
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: saveDecisionToDb failed: ${err.message}\n`);
+        throw err;
+    }
+}
+// ─── Update Requirement in DB + Regenerate Markdown ───────────────────────
+/**
+ * Update a requirement in DB and regenerate REQUIREMENTS.md.
+ * Fetches existing requirement, merges updates, upserts, then regenerates.
+ */
+export async function updateRequirementInDb(id, updates, basePath) {
+    try {
+        const db = await import('./gsd-db.js');
+        const existing = db.getRequirementById(id);
+        if (!existing) {
+            throw new GSDError(GSD_STALE_STATE, `Requirement ${id} not found`);
+        }
+        // Merge updates into existing
+        const merged = {
+            ...existing,
+            ...updates,
+            id: existing.id, // ID cannot be changed
+        };
+        db.upsertRequirement(merged);
+        // Fetch ALL requirements (including superseded) for full file regeneration
+        const adapter = db._getAdapter();
+        let allRequirements = [];
+        if (adapter) {
+            const rows = adapter.prepare('SELECT * FROM requirements ORDER BY id').all();
+            allRequirements = rows.map(row => ({
+                id: row['id'],
+                class: row['class'],
+                status: row['status'],
+                description: row['description'],
+                why: row['why'],
+                source: row['source'],
+                primary_owner: row['primary_owner'],
+                supporting_slices: row['supporting_slices'],
+                validation: row['validation'],
+                notes: row['notes'],
+                full_content: row['full_content'],
+                superseded_by: row['superseded_by'] ?? null,
+            }));
+        }
+        // Filter to non-superseded for the markdown file
+        // (superseded requirements don't appear in section headings)
+        const nonSuperseded = allRequirements.filter(r => r.superseded_by == null);
+        const md = generateRequirementsMd(nonSuperseded);
+        const filePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
+        await saveFile(filePath, md);
+        // Invalidate file-read caches so deriveState() sees the updated markdown.
+        // Do NOT clear the artifacts table — we just wrote to it intentionally.
+        invalidateStateCache();
+        clearPathCache();
+        clearParseCache();
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: updateRequirementInDb failed: ${err.message}\n`);
+        throw err;
+    }
+}
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk.
+ * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
+ * The full file path is computed as basePath + '.gsd/' + path.
+ */
+export async function saveArtifactToDb(opts, basePath) {
+    try {
+        const db = await import('./gsd-db.js');
+        db.insertArtifact({
+            path: opts.path,
+            artifact_type: opts.artifact_type,
+            milestone_id: opts.milestone_id ?? null,
+            slice_id: opts.slice_id ?? null,
+            task_id: opts.task_id ?? null,
+            full_content: opts.content,
+        });
+        // Write the file to disk (guard against path traversal)
+        const gsdDir = resolve(basePath, '.gsd');
+        const fullPath = resolve(basePath, '.gsd', opts.path);
+        if (!fullPath.startsWith(gsdDir)) {
+            throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+        }
+        await saveFile(fullPath, opts.content);
+        // Invalidate file-read caches so deriveState() sees the updated markdown.
+        // Do NOT clear the artifacts table — we just wrote to it intentionally.
+        invalidateStateCache();
+        clearPathCache();
+        clearParseCache();
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: saveArtifactToDb failed: ${err.message}\n`);
+        throw err;
+    }
+}

package/dist/resources/extensions/gsd/debug-logger.js

@@ -0,0 +1,161 @@
+// GSD Extension — Debug Logger
+// Structured JSONL debug logging for diagnosing stuck/slow GSD sessions.
+// Zero overhead when disabled — all public functions are no-ops.
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { gsdRoot } from './paths.js';
+// ─── State ────────────────────────────────────────────────────────────────────
+let _enabled = false;
+let _logPath = null;
+let _startTime = 0;
+/** Rolling counters for the debug summary written on stop. */
+const _counters = {
+    deriveStateCalls: 0,
+    deriveStateTotalMs: 0,
+    ttsrChecks: 0,
+    ttsrTotalMs: 0,
+    ttsrPeakBuffer: 0,
+    parseRoadmapCalls: 0,
+    parseRoadmapTotalMs: 0,
+    parsePlanCalls: 0,
+    parsePlanTotalMs: 0,
+    dispatches: 0,
+    renders: 0,
+};
+/** Max debug log files to keep. Older ones are pruned on enable. */
+const MAX_DEBUG_LOGS = 5;
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Enable debug logging. Creates the log file and prunes old logs.
+ * Can be activated via `--debug` flag or `GSD_DEBUG=1` env var.
+ */
+export function enableDebug(basePath) {
+    const debugDir = join(gsdRoot(basePath), 'debug');
+    mkdirSync(debugDir, { recursive: true });
+    // Prune old debug logs
+    try {
+        const files = readdirSync(debugDir)
+            .filter(f => f.startsWith('debug-') && f.endsWith('.log'))
+            .sort();
+        while (files.length >= MAX_DEBUG_LOGS) {
+            const oldest = files.shift();
+            try {
+                unlinkSync(join(debugDir, oldest));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch { /* non-fatal */ }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    _logPath = join(debugDir, `debug-${timestamp}.log`);
+    _startTime = Date.now();
+    _enabled = true;
+    // Reset counters
+    for (const key of Object.keys(_counters)) {
+        _counters[key] = 0;
+    }
+}
+/** Disable debug logging and return the log file path (if any). */
+export function disableDebug() {
+    const path = _logPath;
+    _enabled = false;
+    _logPath = null;
+    _startTime = 0;
+    return path;
+}
+/** Check if debug mode is active. */
+export function isDebugEnabled() {
+    return _enabled;
+}
+/** Return the current log file path (or null). */
+export function getDebugLogPath() {
+    return _logPath;
+}
+/**
+ * Log a structured debug event. No-op when debug is disabled.
+ *
+ * Each event is one JSON line: `{ ts, event, ...data }`
+ */
+export function debugLog(event, data) {
+    if (!_enabled || !_logPath)
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        event,
+        ...data,
+    };
+    try {
+        appendFileSync(_logPath, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Silently ignore write failures — debug logging must never break GSD
+    }
+}
+/**
+ * Start a timer for a named operation. Returns a stop function that logs
+ * the elapsed time and optional result data.
+ *
+ * Usage:
+ * ```ts
+ * const stop = debugTime('derive-state');
+ * const result = await deriveState(base);
+ * stop({ phase: result.phase });
+ * ```
+ */
+export function debugTime(event) {
+    if (!_enabled)
+        return _noop;
+    const start = performance.now();
+    return (data) => {
+        const elapsed_ms = Math.round((performance.now() - start) * 100) / 100;
+        debugLog(event, { elapsed_ms, ...data });
+    };
+}
+// ─── Counter Helpers ──────────────────────────────────────────────────────────
+/** Increment a debug counter (used by instrumentation points). */
+export function debugCount(counter, value = 1) {
+    if (!_enabled)
+        return;
+    _counters[counter] += value;
+}
+/** Record a peak value (only updates if new value is higher). */
+export function debugPeak(counter, value) {
+    if (!_enabled)
+        return;
+    if (value > _counters[counter]) {
+        _counters[counter] = value;
+    }
+}
+/**
+ * Write the debug summary and disable logging. Call this when auto-mode stops.
+ * Returns the log file path for user notification.
+ */
+export function writeDebugSummary() {
+    if (!_enabled || !_logPath)
+        return null;
+    const totalElapsed_ms = Date.now() - _startTime;
+    const avgDeriveState_ms = _counters.deriveStateCalls > 0
+        ? Math.round((_counters.deriveStateTotalMs / _counters.deriveStateCalls) * 100) / 100
+        : 0;
+    const avgTtsrCheck_ms = _counters.ttsrChecks > 0
+        ? Math.round((_counters.ttsrTotalMs / _counters.ttsrChecks) * 100) / 100
+        : 0;
+    debugLog('debug-summary', {
+        totalElapsed_ms,
+        dispatches: _counters.dispatches,
+        deriveStateCalls: _counters.deriveStateCalls,
+        avgDeriveState_ms,
+        parseRoadmapCalls: _counters.parseRoadmapCalls,
+        avgParseRoadmap_ms: _counters.parseRoadmapCalls > 0
+            ? Math.round((_counters.parseRoadmapTotalMs / _counters.parseRoadmapCalls) * 100) / 100
+            : 0,
+        parsePlanCalls: _counters.parsePlanCalls,
+        ttsrChecks: _counters.ttsrChecks,
+        avgTtsrCheck_ms,
+        ttsrPeakBuffer: _counters.ttsrPeakBuffer,
+        renders: _counters.renders,
+    });
+    return disableDebug();
+}
+// ─── Internal ─────────────────────────────────────────────────────────────────
+function _noop(_data) { }