gswd 0.1.0

package/lib/render.ts

@@ -0,0 +1,200 @@
+/**
+ * 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
+ */
+
+// ─── Status Symbols ──────────────────────────────────────────────────────────
+
+export const SYMBOLS = {
+  complete: '\u2713',       // ✓
+  failed: '\u2717',         // ✗
+  inProgress: '\u25C6',     // ◆
+  pending: '\u25CB',        // ○
+  autoApproved: '\u26A1',   // ⚡
+  warning: '\u26A0',        // ⚠
+} as const;
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Pad or truncate a string to exact width.
+ * If str exceeds width, truncate and append '...' (total = width).
+ */
+export function padRight(str: string, width: number): string {
+  if (str.length > width) {
+    return str.slice(0, width - 3) + '...';
+  }
+  return str + ' '.repeat(width - str.length);
+}
+
+// ─── Banner ──────────────────────────────────────────────────────────────────
+
+/**
+ * Render a stage banner matching GSWD_SPEC Section 7.1.
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► {STAGE NAME}
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * Banner width = 55 characters. Stage name is uppercased.
+ */
+export function renderBanner(stageName: string): string {
+  const BANNER_WIDTH = 55;
+  const border = '\u2501'.repeat(BANNER_WIDTH);
+  const title = ` GSWD \u25B6 ${stageName.toUpperCase()}`;
+  return `${border}\n${title}\n${border}`;
+}
+
+// ─── Checkpoint Box ──────────────────────────────────────────────────────────
+
+/**
+ * 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 function renderCheckpoint(
+  type: string,
+  context: string,
+  options: string[],
+  actionPrompt: string,
+): string {
+  const BOX_WIDTH = 56;
+  const INNER_WIDTH = BOX_WIDTH - 4; // 52 (accounting for "│ " and " │")
+
+  const topBorder    = `\u250C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2510`;
+  const midBorder    = `\u251C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2524`;
+  const bottomBorder = `\u2514${'\u2500'.repeat(BOX_WIDTH - 2)}\u2518`;
+
+  const line = (text: string): string => {
+    const padded = padRight(text, INNER_WIDTH);
+    return `\u2502 ${padded} \u2502`;
+  };
+
+  const blankLine = line('');
+
+  const lines: string[] = [];
+  lines.push(topBorder);
+  lines.push(line(type));
+  lines.push(midBorder);
+  lines.push(line(context));
+  lines.push(blankLine);
+
+  for (let i = 0; i < options.length; i++) {
+    lines.push(line(`${i + 1}) ${options[i]}`));
+  }
+
+  lines.push(blankLine);
+  lines.push(line(`\u2192 ${actionPrompt}`));
+  lines.push(bottomBorder);
+
+  return lines.join('\n');
+}
+
+// ─── Next Up ─────────────────────────────────────────────────────────────────
+
+/**
+ * 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 function renderNextUp(
+  files: string[],
+  nextCommand: string,
+  alsoAvailable?: string[],
+): string {
+  const parts: string[] = [];
+
+  parts.push(`${SYMBOLS.complete} Wrote: ${files.join(', ')}`);
+  parts.push('');
+  parts.push('Next up:');
+  parts.push(`  ${nextCommand}`);
+  parts.push('');
+  parts.push('Tip:');
+  parts.push('  If context is getting crowded, run /clear.');
+
+  if (alsoAvailable && alsoAvailable.length > 0) {
+    parts.push('');
+    parts.push('Also available:');
+    for (const item of alsoAvailable) {
+      parts.push(`  - ${item}`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Status Line ─────────────────────────────────────────────────────────────
+
+/**
+ * Render a single status line with the appropriate symbol.
+ *
+ * Maps: done/pass -> ✓, fail -> ✗, in_progress -> ◆, not_started -> ○
+ */
+export function renderStatusLine(stage: string, status: string): string {
+  let symbol: string;
+  switch (status) {
+    case 'done':
+    case 'pass':
+      symbol = SYMBOLS.complete;
+      break;
+    case 'fail':
+      symbol = SYMBOLS.failed;
+      break;
+    case 'in_progress':
+      symbol = SYMBOLS.inProgress;
+      break;
+    case 'not_started':
+      symbol = SYMBOLS.pending;
+      break;
+    default:
+      symbol = SYMBOLS.pending;
+  }
+  return `${symbol}  ${stage}: ${status}`;
+}
+
+// ─── Progress Bar ────────────────────────────────────────────────────────────
+
+/**
+ * Render an ASCII progress bar.
+ *
+ * ```
+ * Progress: ████████░░ 80%
+ * ```
+ *
+ * @param current - Current value
+ * @param total - Total value
+ * @param width - Bar width in characters (default 10)
+ */
+export function renderProgressBar(
+  current: number,
+  total: number,
+  width: number = 10,
+): string {
+  const ratio = total === 0 ? 0 : Math.min(current / total, 1);
+  const filled = Math.round(ratio * width);
+  const empty = width - filled;
+  const percent = Math.round(ratio * 100);
+
+  const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+  return `Progress: ${bar} ${percent}%`;
+}

package/lib/specify-agents.ts

@@ -0,0 +1,332 @@
+/**
+ * GSWD Specify Agents Module — Agent definitions, sequential-then-parallel orchestration
+ *
+ * Provides the 3 specify agents: journey-mapper (sequential), then
+ * architecture-drafter + integrations-checker (parallel).
+ *
+ * Follows the imagine-agents.ts pattern but with phased orchestration.
+ *
+ * Schema: GSWD_SPEC.md Section 8.3, Section 11.1
+ */
+
+import * as fs from 'node:fs';
+import type { Journey, FunctionalRequirement } from './specify-journeys.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface SpecifyAgentDefinition {
+  /** Agent name matching file name (without .md) */
+  name: string;
+  /** Path to agent definition file */
+  definitionPath: string;
+  /** Phase: 'sequential' runs first, 'parallel' runs after sequential completes */
+  phase: 'sequential' | 'parallel';
+  /** Minimum headings expected in agent output */
+  requiredHeadings: string[];
+}
+
+export interface Integration {
+  /** Integration ID in I-001 format */
+  id: string;
+  /** Integration name */
+  name: string;
+  /** Steps to set up the integration */
+  setupSteps: string[];
+  /** Authentication method */
+  authMethod: string;
+  /** Monthly cost or quota description */
+  costQuota: string;
+  /** Fallback if integration unavailable */
+  fallback: string;
+  /** Approval status — MANDATORY field */
+  status: 'approved' | 'deferred with fallback' | 'rejected';
+}
+
+export interface ArchitectureComponent {
+  /** Component ID in C-001 format */
+  id: string;
+  /** Component name */
+  name: string;
+  /** What this component does */
+  responsibility: string;
+  /** Other C-XXX IDs this depends on */
+  dependencies: string[];
+  /** FR-XXX IDs this component implements */
+  linkedFRs: string[];
+}
+
+export interface AgentResult {
+  /** Agent name */
+  agent: string;
+  /** Agent output content */
+  content: string;
+  /** Completion status */
+  status: 'complete' | 'failed';
+  /** Error message if failed */
+  error?: string;
+  /** Execution time in milliseconds */
+  duration_ms?: number;
+}
+
+export type SpawnFn = (prompt: string) => Promise<string>;
+
+// ─── Agent Definitions ───────────────────────────────────────────────────────
+
+/**
+ * The 3 specify agents from GSWD_SPEC Section 11.1.
+ * journey-mapper runs first (sequential); others run after (parallel).
+ */
+export const SPECIFY_AGENTS: SpecifyAgentDefinition[] = [
+  {
+    name: 'journey-mapper',
+    definitionPath: 'agents/gswd/journey-mapper.md',
+    phase: 'sequential',
+    requiredHeadings: ['### J-'],
+  },
+  {
+    name: 'architecture-drafter',
+    definitionPath: 'agents/gswd/architecture-drafter.md',
+    phase: 'parallel',
+    requiredHeadings: ['### Components', '### Data Model'],
+  },
+  {
+    name: 'integrations-checker',
+    definitionPath: 'agents/gswd/integrations-checker.md',
+    phase: 'parallel',
+    requiredHeadings: ['## Integrations'],
+  },
+];
+
+// ─── Prompt Building ─────────────────────────────────────────────────────────
+
+export interface SpecifyAgentContext {
+  /** DECISIONS.md content */
+  decisionsContent: string;
+  /** IMAGINE.md content (optional) */
+  imagineContent?: string;
+  /** Extracted journeys (available after journey-mapper) */
+  journeys?: Journey[];
+  /** Extracted FRs (available after FR extraction) */
+  frs?: FunctionalRequirement[];
+  /** Auto policy config content */
+  autoPolicy?: string;
+}
+
+/**
+ * Build the prompt for a specify agent.
+ *
+ * - journey-mapper: gets DECISIONS.md + IMAGINE.md
+ * - architecture-drafter: gets journeys + FRs + DECISIONS.md
+ * - integrations-checker: gets journeys + FRs + DECISIONS.md + auto policy
+ */
+export function buildSpecifyAgentPrompt(
+  agent: SpecifyAgentDefinition,
+  context: SpecifyAgentContext,
+): string {
+  let definition: string;
+  try {
+    definition = fs.readFileSync(agent.definitionPath, 'utf-8');
+  } catch {
+    definition = `Agent: ${agent.name}\nRole: Specify agent`;
+  }
+
+  const sections: string[] = [definition];
+
+  // Always include decisions
+  if (context.decisionsContent) {
+    sections.push(`<decisions>\n${context.decisionsContent}\n</decisions>`);
+  }
+
+  switch (agent.name) {
+    case 'journey-mapper':
+      if (context.imagineContent) {
+        sections.push(`<imagine>\n${context.imagineContent}\n</imagine>`);
+      }
+      break;
+
+    case 'architecture-drafter':
+      if (context.frs && context.frs.length > 0) {
+        const frSummary = context.frs
+          .map((fr) => `- ${fr.id}: ${fr.description} [${fr.scope}/${fr.priority}]`)
+          .join('\n');
+        sections.push(`<functional_requirements>\n${frSummary}\n</functional_requirements>`);
+      }
+      if (context.journeys && context.journeys.length > 0) {
+        const journeySummary = context.journeys
+          .map((j) => `- ${j.id}: ${j.name} (${j.type}, ${j.steps.length} steps)`)
+          .join('\n');
+        sections.push(`<journeys>\n${journeySummary}\n</journeys>`);
+      }
+      break;
+
+    case 'integrations-checker':
+      if (context.frs && context.frs.length > 0) {
+        const frSummary = context.frs
+          .map((fr) => `- ${fr.id}: ${fr.description} [${fr.scope}/${fr.priority}]`)
+          .join('\n');
+        sections.push(`<functional_requirements>\n${frSummary}\n</functional_requirements>`);
+      }
+      if (context.journeys && context.journeys.length > 0) {
+        const journeySummary = context.journeys
+          .map((j) => `- ${j.id}: ${j.name} (${j.type}, ${j.steps.length} steps)`)
+          .join('\n');
+        sections.push(`<journeys>\n${journeySummary}\n</journeys>`);
+      }
+      if (context.autoPolicy) {
+        sections.push(`<auto_policy>\n${context.autoPolicy}\n</auto_policy>`);
+      }
+      break;
+  }
+
+  sections.push(
+    `Produce your output now. Include all required headings: ${agent.requiredHeadings.join(', ')}.`
+  );
+
+  return sections.join('\n\n');
+}
+
+// ─── Orchestration ───────────────────────────────────────────────────────────
+
+/**
+ * Orchestrate specify agents with sequential-then-parallel pattern.
+ *
+ * Phase 1 (sequential): Run journey-mapper, wait for completion.
+ * Phase 2 (parallel): Run architecture-drafter + integrations-checker concurrently.
+ *
+ * Failed agents are marked with status: 'failed' but do not crash orchestration.
+ *
+ * @param agents - Agent definitions (defaults to SPECIFY_AGENTS)
+ * @param context - Shared context for prompt building
+ * @param spawnFn - Function that spawns an agent (Task() wrapper)
+ * @returns All agent results including failures
+ */
+export async function orchestrateSpecifyAgents(
+  agents: SpecifyAgentDefinition[],
+  context: SpecifyAgentContext,
+  spawnFn: SpawnFn,
+): Promise<AgentResult[]> {
+  const results: AgentResult[] = [];
+
+  // Phase 1: Sequential agents
+  const sequentialAgents = agents.filter((a) => a.phase === 'sequential');
+  for (const agent of sequentialAgents) {
+    const result = await runSingleAgent(agent, context, spawnFn);
+    results.push(result);
+  }
+
+  // Phase 2: Parallel agents
+  const parallelAgents = agents.filter((a) => a.phase === 'parallel');
+  if (parallelAgents.length > 0) {
+    const parallelPromises = parallelAgents.map((agent) =>
+      runSingleAgent(agent, context, spawnFn)
+    );
+    const parallelResults = await Promise.all(parallelPromises);
+    results.push(...parallelResults);
+  }
+
+  return results;
+}
+
+/**
+ * Run a single agent and return its result.
+ */
+async function runSingleAgent(
+  agent: SpecifyAgentDefinition,
+  context: SpecifyAgentContext,
+  spawnFn: SpawnFn,
+): Promise<AgentResult> {
+  const start = Date.now();
+  try {
+    const prompt = buildSpecifyAgentPrompt(agent, context);
+    const content = await spawnFn(prompt);
+    return {
+      agent: agent.name,
+      content,
+      status: 'complete',
+      duration_ms: Date.now() - start,
+    };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      agent: agent.name,
+      content: '',
+      status: 'failed',
+      error: message,
+      duration_ms: Date.now() - start,
+    };
+  }
+}
+
+// ─── Integration Validation ──────────────────────────────────────────────────
+
+/**
+ * Valid integration status values.
+ */
+export const VALID_INTEGRATION_STATUSES = [
+  'approved',
+  'deferred with fallback',
+  'rejected',
+] as const;
+
+/**
+ * Validate that an integration has all required fields including mandatory Status.
+ */
+export function validateIntegration(
+  integration: Integration,
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // ID format
+  if (!/^I-\d{3,}$/.test(integration.id)) {
+    errors.push(`Invalid integration ID format: ${integration.id} (expected I-XXX)`);
+  }
+
+  // Name non-empty
+  if (!integration.name || integration.name.trim() === '') {
+    errors.push(`Integration ${integration.id} has empty name`);
+  }
+
+  // Status is mandatory and must be a valid value
+  if (!VALID_INTEGRATION_STATUSES.includes(integration.status)) {
+    errors.push(
+      `Integration ${integration.id} has invalid status: "${integration.status}" (expected: ${VALID_INTEGRATION_STATUSES.join(', ')})`
+    );
+  }
+
+  // Deferred integrations must have a fallback
+  if (integration.status === 'deferred with fallback') {
+    if (!integration.fallback || integration.fallback.trim() === '') {
+      errors.push(
+        `Integration ${integration.id} is deferred but has no fallback`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate that a component has correct ID format and required fields.
+ */
+export function validateComponent(
+  component: ArchitectureComponent,
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // ID format
+  if (!/^C-\d{3,}$/.test(component.id)) {
+    errors.push(`Invalid component ID format: ${component.id} (expected C-XXX)`);
+  }
+
+  // Name non-empty
+  if (!component.name || component.name.trim() === '') {
+    errors.push(`Component ${component.id} has empty name`);
+  }
+
+  // Responsibility non-empty
+  if (!component.responsibility || component.responsibility.trim() === '') {
+    errors.push(`Component ${component.id} has empty responsibility`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}