gswd 1.0.0 → 1.1.0

package/dist/lib/parse.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * GSWD Parse Module — ID extraction, heading validation, normalization
+ *
+ * Parses GSWD artifact files for IDs (J-NNN, FR-NNN, NFR-NNN, I-NNN, C-NNN),
+ * validates required heading structure, and normalizes malformed IDs.
+ *
+ * Schema: GSWD_SPEC.md Section 6.1-6.3
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_HEADINGS = void 0;
+exports.normalizeId = normalizeId;
+exports.extractIds = extractIds;
+exports.validateHeadings = validateHeadings;
+exports.extractHeadingContent = extractHeadingContent;
+// ─── Required Headings ──────────────────────────────────────────────────────
+/**
+ * Required headings per artifact file type, from GSWD_SPEC Section 6.3.
+ * These are the stable anchors used by audit/compile parsers.
+ */
+exports.REQUIRED_HEADINGS = {
+    'JOURNEYS.md': ['## Journeys'],
+    'SPEC.md': ['## Roles & Permissions', '## Functional Requirements', '## Acceptance Criteria'],
+    'NFR.md': ['## Non-Functional Requirements'],
+    'INTEGRATIONS.md': ['## Integrations'],
+    'ARCHITECTURE.md': ['## Architecture', '### Components', '### Data Model'],
+    'DECISIONS.md': [
+        '## Vision',
+        '## Frozen Decisions',
+        '## Success Metrics',
+        '## Out of Scope',
+        '## Risks & Mitigations',
+        '## Open Questions',
+    ],
+    'AUDIT.md': ['## Coverage Matrix', '## Check Results'],
+    'PROJECT.md': ['## What This Is', '## Target User', '## Problem Statement', '## Wedge / MVP Boundary', '## Success Metrics', '## Out of Scope', '## Context'],
+    'REQUIREMENTS.md': ['## Functional Requirements', '## Non-Functional Requirements', '## Traceability'],
+    'ROADMAP.md': ['## Overview', '## Phases'],
+    'STATE.md': ['## Frozen Decisions', '## Approvals', '## Open Questions', '## Risks'],
+};
+// ─── ID Normalization ────────────────────────────────────────────────────────
+/** Valid ID prefixes */
+const ID_PREFIXES = ['J', 'FR', 'NFR', 'I', 'C'];
+/**
+ * Normalize an ID to canonical format: PREFIX-NNN (3-digit minimum, zero-padded).
+ *
+ * - FR-1    -> FR-001
+ * - FR-01   -> FR-001
+ * - FR-001  -> FR-001 (no change)
+ * - FR-1000 -> FR-1000 (4+ digits kept as-is)
+ * - INVALID -> INVALID (unrecognized format returned as-is)
+ */
+function normalizeId(rawId) {
+    if (!rawId)
+        return rawId;
+    const match = rawId.match(/^(J|FR|NFR|I|C)-(\d+)$/);
+    if (!match)
+        return rawId;
+    const prefix = match[1];
+    const num = parseInt(match[2], 10);
+    const padded = num.toString().padStart(3, '0');
+    return `${prefix}-${padded}`;
+}
+/**
+ * Extract IDs from content using regex.
+ *
+ * Regex: /\b(J|FR|NFR|I|C)-(\d{1,4})\b/g
+ * - Word boundary prevents partial matches (e.g., INFRASTRUCTURE-001)
+ * - Returns deduplicated array sorted by normalized ID ascending
+ * - Optional filter by idType (e.g., 'FR')
+ */
+function extractIds(content, idType) {
+    const regex = /\b(J|FR|NFR|I|C)-(\d{1,4})\b/g;
+    const seen = new Map();
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const raw = match[0];
+        const prefix = match[1];
+        // Filter by ID type if specified
+        if (idType && prefix !== idType)
+            continue;
+        const normalized = normalizeId(raw);
+        if (!seen.has(normalized)) {
+            seen.set(normalized, {
+                id: normalized,
+                raw,
+                normalized: raw !== normalized,
+            });
+        }
+    }
+    // Sort by normalized ID ascending
+    return Array.from(seen.values()).sort((a, b) => {
+        // Split into prefix and number for proper sorting
+        const aParts = a.id.match(/^(.+)-(\d+)$/);
+        const bParts = b.id.match(/^(.+)-(\d+)$/);
+        if (!aParts || !bParts)
+            return a.id.localeCompare(b.id);
+        // Sort by prefix first, then by number
+        if (aParts[1] !== bParts[1])
+            return aParts[1].localeCompare(bParts[1]);
+        return parseInt(aParts[2], 10) - parseInt(bParts[2], 10);
+    });
+}
+/**
+ * Validate that a file contains all required headings for its type.
+ *
+ * - Looks up required headings from REQUIRED_HEADINGS[fileType]
+ * - Case-insensitive search as safety layer
+ * - Returns which headings are present and which are missing
+ * - Unknown file types are always valid (no required headings)
+ */
+function validateHeadings(content, fileType) {
+    const required = exports.REQUIRED_HEADINGS[fileType];
+    // Unknown file type — no required headings, always valid
+    if (!required) {
+        return { valid: true, missing: [], present: [] };
+    }
+    const contentLower = content.toLowerCase();
+    const missing = [];
+    const present = [];
+    for (const heading of required) {
+        if (contentLower.includes(heading.toLowerCase())) {
+            present.push(heading);
+        }
+        else {
+            missing.push(heading);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+        present,
+    };
+}
+// ─── Heading Content Extraction ──────────────────────────────────────────────
+/**
+ * Extract content between a heading and the next heading of same or higher level.
+ *
+ * @param content - Full file content
+ * @param heading - The heading to extract content from (e.g., "## Section A")
+ * @returns Content string (trimmed) or null if heading not found
+ */
+function extractHeadingContent(content, heading) {
+    const lines = content.split('\n');
+    const headingLevel = (heading.match(/^#+/) || [''])[0].length;
+    let capturing = false;
+    let startIdx = -1;
+    let endIdx = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!capturing) {
+            // Look for the target heading
+            if (line.trim().toLowerCase() === heading.toLowerCase()) {
+                capturing = true;
+                startIdx = i + 1;
+            }
+        }
+        else {
+            // Check if we hit another heading of same or higher level
+            const lineHeadingMatch = line.match(/^(#+)\s/);
+            if (lineHeadingMatch && lineHeadingMatch[1].length <= headingLevel) {
+                endIdx = i;
+                break;
+            }
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    const extracted = lines.slice(startIdx, endIdx).join('\n').trim();
+    return extracted;
+}

package/dist/lib/render.d.ts

@@ -0,0 +1,309 @@
+/**
+ * GSWD Render Module — Terminal UI rendering functions
+ *
+ * All functions return strings (not print to stdout).
+ * Zero external dependencies. Uses only string operations.
+ *
+ * Schema: GSWD_SPEC.md Section 7.1-7.3
+ */
+export declare const SYMBOLS: {
+    readonly complete: "✓";
+    readonly failed: "✗";
+    readonly inProgress: "◆";
+    readonly pending: "○";
+    readonly autoApproved: "⚡";
+    readonly warning: "⚠";
+};
+/**
+ * ANSI color codes for GSWD branding.
+ * Electric orange/amber is the brand color (per CONTEXT.md locked decision).
+ * 256-color code \x1b[38;5;208m; dim uses \x1b[2m.
+ */
+export declare const COLORS: {
+    readonly orange: "\u001B[38;5;208m";
+    readonly dim: "\u001B[2m";
+    readonly reset: "\u001B[0m";
+};
+/**
+ * Wrap text in ANSI color. No-op when stdout is not a TTY (CI/Docker/pipe safety).
+ * Respects FORCE_COLOR env var to override TTY detection.
+ */
+export declare function colorize(text: string, color: keyof typeof COLORS): string;
+/**
+ * Render the GSWD ASCII logo with catchphrase.
+ * Logo shape matches GSD's block-letter style from install.js.
+ * Static string — no figlet (STATE.md architectural decision).
+ *
+ * @param version - Optional version string (e.g., "1.0.1")
+ */
+export declare function renderLogo(version?: string): string;
+/**
+ * Render the condensed first-run command guide.
+ * Per CONTEXT.md: primary commands only, no descriptions.
+ * Followed by automatic /gswd:start proposal for zero-friction onboarding.
+ */
+export declare function renderFirstRunGuide(): string;
+/**
+ * Pad or truncate a string to exact width.
+ * If str exceeds width, truncate and append '...' (total = width).
+ */
+export declare function padRight(str: string, width: number): string;
+/**
+ * Render a stage banner matching GSWD_SPEC Section 7.1.
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► {STAGE NAME}
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * Banner width = 55 characters. Stage name is uppercased.
+ */
+export declare function renderBanner(stageName: string): string;
+/**
+ * Render a checkpoint box matching GSWD_SPEC Section 7.2.
+ *
+ * Box total width: 56 characters (54 inner + 2 border characters).
+ * Uses single-line box-drawing characters.
+ *
+ * @param type - Header text (e.g., "Decision Required")
+ * @param context - Context paragraph
+ * @param options - Numbered options list
+ * @param actionPrompt - Action prompt (appears after → )
+ */
+export declare function renderCheckpoint(type: string, context: string, options: string[], actionPrompt: string): string;
+/**
+ * Render a Next Up block matching GSWD_SPEC Section 7.3.
+ *
+ * ```
+ * ✓ Wrote: file1, file2, ...
+ *
+ * Next up:
+ *   {nextCommand}
+ *
+ * Tip:
+ *   If context is getting crowded, run /clear.
+ * ```
+ */
+export declare function renderNextUp(files: string[], nextCommand: string, alsoAvailable?: string[]): string;
+/**
+ * Render a single status line with the appropriate symbol.
+ *
+ * Maps: done/pass -> ✓, fail -> ✗, in_progress -> ◆, not_started -> ○
+ */
+export declare function renderStatusLine(stage: string, status: string): string;
+/**
+ * Render an ASCII progress bar.
+ *
+ * ```
+ * Progress: ████████░░ 80%
+ * ```
+ *
+ * @param current - Current value
+ * @param total - Total value
+ * @param width - Bar width in characters (default 10)
+ */
+export declare function renderProgressBar(current: number, total: number, width?: number): string;
+/**
+ * Input for stage summary rendering.
+ * Used at manual-mode checkpoints to show what a stage produced.
+ */
+export interface StageSummarySection {
+    name: string;
+    summary: string;
+}
+export interface StageSummaryInput {
+    stageName: string;
+    headline: string;
+    sections: StageSummarySection[];
+    filesCreated: string[];
+}
+/**
+ * Render a structured stage summary for manual-mode checkpoints.
+ * Consistent template per CONTEXT.md locked decision:
+ *   Headline -> section paragraphs -> file list
+ *
+ * ```
+ * ## Imagine Complete
+ *
+ * Imagine produced 3 product directions with ICP, GTM, and competition analysis.
+ *
+ * **Key outputs:**
+ * - ICP Analysis: Identified 2 primary personas with distinct pain points...
+ * - GTM Strategy: Recommended freemium launch with enterprise upgrade path...
+ *
+ * **Created:** IMAGINE.md, ICP.md, GTM.md, COMPETITION.md, DECISIONS.md
+ * ```
+ */
+/**
+ * Research summary section for post-agent display.
+ * Mirrors ResearchSummarySection from imagine-synthesis.ts.
+ */
+export interface RenderResearchSection {
+    displayName: string;
+    takeaways: string[];
+    bridge: string;
+}
+/**
+ * Render structured research summary after agent completion.
+ * Product-contextualized: section intros reference user's product.
+ * Per CONTEXT.md: 3-5 takeaway bullets per section, bridging paragraph per section.
+ *
+ * @param sections - Research summary sections from buildResearchSummary
+ * @param productContext - Brief description of the product (from brief.vision)
+ * @param targetUser - Who the product is for (from brief.target_user)
+ */
+export declare function renderResearchSummary(sections: RenderResearchSection[], productContext: string, targetUser: string): string;
+/**
+ * Direction card input for rendering.
+ */
+export interface RenderDirectionInput {
+    label: string;
+    rationale: string[];
+    icp_summary: string;
+    problem_framing: string;
+    wedge: string;
+    differentiator: string;
+    risks: string[];
+}
+/**
+ * Render a direction card with "Why this makes sense" rationale section.
+ * Per CONTEXT.md: rationale section comes FIRST, before existing fields.
+ * Recommended direction gets a visual marker.
+ *
+ * @param direction - Direction data
+ * @param index - 0-based index for display numbering
+ * @param isRecommended - Whether this is the proposed/recommended direction
+ */
+export declare function renderDirectionCard(direction: RenderDirectionInput, index: number, isRecommended: boolean): string;
+export declare function renderStageSummary(input: StageSummaryInput): string;
+/**
+ * Minimal product context for contextual messaging throughout the pipeline.
+ * Extracted from INTAKE.json and DECISIONS.md with graceful fallbacks.
+ */
+export interface ProductContext {
+    /** Product domain (e.g., "spec-writing tool") */
+    domain: string;
+    /** Target user (e.g., "solo founders") */
+    targetUser: string;
+    /** Stage-specific context string */
+    stageContext: string;
+    /** Whether this is a re-run (changes banner messaging) */
+    isRerun: boolean;
+    /** Re-run feedback context (if re-run) */
+    rerunContext?: string;
+}
+/**
+ * Extract product context from DECISIONS.md and INTAKE.json.
+ * DECISIONS.md is preferred (more precise, available after Imagine).
+ * INTAKE.json is fallback (available from pipeline start).
+ * Returns safe defaults if neither file exists.
+ *
+ * @param planningDir - Path to .planning/ directory
+ * @param isRerun - Whether this is a re-run
+ */
+export declare function extractProductContext(planningDir: string, isRerun?: boolean): ProductContext;
+/**
+ * Stage-specific context line generators for contextual banners.
+ * Each returns a product-contextualized one-liner for the banner.
+ * Compile is deliberately excluded (per CONTEXT.md: deterministic, no banner needed).
+ */
+export declare const STAGE_CONTEXT_TEMPLATES: Record<string, (ctx: ProductContext) => string>;
+/**
+ * Product-contextualized one-liner descriptions for Imagine research agents.
+ * Each function receives ProductContext and returns a purpose string.
+ */
+export declare const IMAGINE_AGENT_BRIEFINGS: Record<string, (ctx: ProductContext) => string>;
+/**
+ * Product-contextualized one-liner descriptions for Specify agents.
+ */
+export declare const SPECIFY_AGENT_BRIEFINGS: Record<string, (ctx: ProductContext) => string>;
+/**
+ * Render a stage banner with a product-contextualized line below the title.
+ * Extension of renderBanner() for consultant-style messaging (Phase 16).
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► IMAGINE
+ *  Validating product direction for a spec-writing tool targeting founders
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * @param stageName - Stage name (will be uppercased)
+ * @param contextLine - Product-contextualized one-liner
+ */
+export declare function renderContextBanner(stageName: string, contextLine: string): string;
+/**
+ * Input for agent pre-briefing display.
+ */
+export interface AgentBriefingEntry {
+    name: string;
+    productPurpose: string;
+}
+/**
+ * Render agent pre-briefing block before spawning.
+ * Technical transparency: name each agent explicitly with product-specific purpose.
+ *
+ * ```
+ * ◆ Spawning 5 research agents:
+ *   → market-researcher: mapping the spec-tooling landscape to find gaps
+ *   → icp-persona: profiling founders who struggle with product specification
+ * ```
+ *
+ * @param agents - Array of agent names with product-contextualized purposes
+ * @param stageContext - Optional stage context description
+ */
+export declare function renderAgentBriefing(agents: AgentBriefingEntry[], stageContext?: string): string;
+/**
+ * Render a single agent completion line with its key finding headline.
+ *
+ * ✓ market-researcher: 3 direct competitors in the spec-tooling space
+ * ✗ icp-persona: Agent failed — timeout
+ *
+ * @param agentName - Agent name
+ * @param headline - Key finding or error message
+ * @param status - Agent completion status
+ */
+export declare function renderAgentCompletion(agentName: string, headline: string, status: 'complete' | 'failed'): string;
+/**
+ * Render full agent progress block showing pending and completed agents.
+ * Pending agents show ○, completed show ✓ with headline, failed show ✗.
+ *
+ * ✓ market-researcher: 3 direct competitors found
+ * ✓ icp-persona: primary persona is technical founder
+ * ○ positioning (pending)
+ * ○ brainstorm-alternatives (pending)
+ * ○ devils-advocate (pending)
+ */
+export declare function renderAgentProgress(agents: Array<{
+    name: string;
+    status: 'pending' | 'complete' | 'failed';
+    headline?: string;
+}>): string;
+/**
+ * Render a file inventory table listing all generated files with descriptions.
+ * Used at pipeline end to give users a deliverable checklist.
+ *
+ * @param files - Array of { path, description } objects
+ * @returns Markdown table string
+ */
+export declare function renderFileInventory(files: Array<{
+    path: string;
+    description: string;
+}>): string;
+/**
+ * Extract a one-line headline from agent output for completion display.
+ * Multi-strategy extraction with robust fallback.
+ *
+ * Strategy priority:
+ * 1. First sentence after "## Summary" heading
+ * 2. Text after "Key finding:" prefix
+ * 3. First non-heading, non-empty line
+ * 4. Fallback: "{agentName} analysis complete"
+ *
+ * Truncates to 80 chars. Never returns empty string.
+ *
+ * @param agentOutput - Raw agent output content
+ * @param agentName - Agent name (for fallback)
+ */
+export declare function extractHeadline(agentOutput: string, agentName: string): string;