gswd 0.1.0

package/lib/state.ts

@@ -0,0 +1,305 @@
+/**
+ * GSWD State Module — STATE.json CRUD with atomic writes
+ *
+ * All file writes use the atomic pattern: write to .tmp -> verify -> rename.
+ * STATE.json is updated only AFTER artifact writes complete.
+ *
+ * Schema: GSWD_SPEC.md Section 5.1
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface StageStatus {
+  imagine: 'not_started' | 'in_progress' | 'done';
+  specify: 'not_started' | 'in_progress' | 'done';
+  audit: 'not_started' | 'in_progress' | 'pass' | 'fail';
+  compile: 'not_started' | 'in_progress' | 'done';
+}
+
+export interface Checkpoint {
+  workflow: string;
+  checkpoint_id: string;
+  timestamp: string;
+}
+
+export interface PaidIntegration {
+  integration_id: string;
+  name: string;
+  monthly_cost_usd: number;
+  status: 'approved' | 'rejected';
+  approved_at: string;
+}
+
+export interface IdRange {
+  agent: string;
+  start: number;
+  end: number;
+}
+
+export interface IdRegistry {
+  allocated_ranges: Record<string, IdRange[]>;
+}
+
+export interface GswdState {
+  version: number;
+  project_slug: string;
+  created_at: string;
+  updated_at: string;
+  stage: 'init' | 'imagine' | 'specify' | 'audit' | 'compile' | 'done';
+  stage_status: StageStatus;
+  last_checkpoint: Checkpoint | null;
+  auto: {
+    enabled: boolean;
+    policy: 'strict' | 'balanced' | 'aggressive';
+    interrupt_reasons: string[];
+    decisions?: Array<{ type: string; chosen: string; rationale: string; score?: number; recorded_at: string }>;
+  };
+  approvals: {
+    auth_model: string;
+    data_store: string;
+    paid_integrations: PaidIntegration[];
+  };
+  id_registry?: IdRegistry;
+}
+
+// ─── Atomic File I/O ─────────────────────────────────────────────────────────
+
+/**
+ * Atomically write a file: write to .tmp, verify, rename.
+ * Cleans up .tmp on any failure.
+ */
+export function safeWriteFile(filePath: string, content: string): void {
+  const tmpPath = filePath + '.tmp';
+  const dir = path.dirname(filePath);
+
+  // Ensure parent directory exists
+  fs.mkdirSync(dir, { recursive: true });
+
+  try {
+    // Write to temp file
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+
+    // Verify temp file was written correctly
+    const written = fs.readFileSync(tmpPath, 'utf-8');
+    if (written !== content) {
+      throw new Error(`Write verification failed for ${filePath}: content mismatch`);
+    }
+
+    // Atomic rename (atomic on Unix/macOS)
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    // Clean up .tmp on any failure
+    try {
+      if (fs.existsSync(tmpPath)) {
+        fs.unlinkSync(tmpPath);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+/**
+ * Atomically write JSON: pretty-print, atomic write, then verify round-trip.
+ */
+export function safeWriteJson(filePath: string, data: unknown): void {
+  const content = JSON.stringify(data, null, 2) + '\n';
+  safeWriteFile(filePath, content);
+
+  // Post-rename verification: re-read and parse
+  const verify = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  if (JSON.stringify(verify) !== JSON.stringify(data)) {
+    throw new Error(`JSON round-trip verification failed for ${filePath}`);
+  }
+}
+
+// ─── State CRUD ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a default STATE.json object matching GSWD_SPEC Section 5.1.
+ */
+export function createDefaultState(projectSlug: string): GswdState {
+  const now = new Date().toISOString();
+  return {
+    version: 1,
+    project_slug: projectSlug,
+    created_at: now,
+    updated_at: now,
+    stage: 'init',
+    stage_status: {
+      imagine: 'not_started',
+      specify: 'not_started',
+      audit: 'not_started',
+      compile: 'not_started',
+    },
+    last_checkpoint: null,
+    auto: {
+      enabled: false,
+      policy: 'balanced',
+      interrupt_reasons: [],
+      decisions: [],
+    },
+    approvals: {
+      auth_model: 'unapproved',
+      data_store: 'unapproved',
+      paid_integrations: [],
+    },
+  };
+}
+
+/**
+ * Read STATE.json. Returns null if file doesn't exist or is invalid JSON.
+ */
+export function readState(statePath: string): GswdState | null {
+  try {
+    const content = fs.readFileSync(statePath, 'utf-8');
+    const parsed = JSON.parse(content);
+    // Basic validation: check required top-level fields
+    if (typeof parsed.version !== 'number' || typeof parsed.project_slug !== 'string') {
+      return null;
+    }
+    return parsed as GswdState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write STATE.json atomically. Updates updated_at timestamp.
+ */
+export function writeState(statePath: string, state: GswdState): void {
+  state.updated_at = new Date().toISOString();
+  safeWriteJson(statePath, state);
+}
+
+/**
+ * Idempotent init: create STATE.json only if missing or corrupt.
+ * If valid state exists, returns it unchanged (no timestamp update).
+ */
+export function initState(stateDir: string, projectSlug: string): GswdState {
+  const statePath = path.join(stateDir, 'STATE.json');
+
+  // Try reading existing state
+  const existing = readState(statePath);
+  if (existing !== null) {
+    return existing;
+  }
+
+  // Create new state
+  const state = createDefaultState(projectSlug);
+  safeWriteJson(statePath, state);
+  return state;
+}
+
+/**
+ * Update a specific stage status. Read-modify-write pattern.
+ */
+export function updateStageStatus(
+  statePath: string,
+  stage: keyof StageStatus,
+  status: string
+): void {
+  const state = readState(statePath);
+  if (!state) {
+    throw new Error(`Cannot read STATE.json at ${statePath}`);
+  }
+  (state.stage_status as Record<string, string>)[stage] = status;
+  writeState(statePath, state);
+}
+
+/**
+ * Write a checkpoint to STATE.json.
+ */
+export function writeCheckpoint(
+  statePath: string,
+  workflow: string,
+  checkpointId: string
+): void {
+  const state = readState(statePath);
+  if (!state) {
+    throw new Error(`Cannot read STATE.json at ${statePath}`);
+  }
+  state.last_checkpoint = {
+    workflow,
+    checkpoint_id: checkpointId,
+    timestamp: new Date().toISOString(),
+  };
+  writeState(statePath, state);
+}
+
+// ─── ID Registry ─────────────────────────────────────────────────────────────
+
+/**
+ * Allocate an ID range for an agent. Ranges are non-overlapping per ID type.
+ */
+export function allocateIdRange(
+  statePath: string,
+  idType: string,
+  agentName: string,
+  rangeSize: number = 50
+): { start: number; end: number } {
+  const state = readState(statePath);
+  if (!state) {
+    throw new Error(`Cannot read STATE.json at ${statePath}`);
+  }
+
+  if (!state.id_registry) {
+    state.id_registry = { allocated_ranges: {} };
+  }
+  if (!state.id_registry.allocated_ranges[idType]) {
+    state.id_registry.allocated_ranges[idType] = [];
+  }
+
+  const ranges = state.id_registry.allocated_ranges[idType];
+  const lastEnd = ranges.length > 0
+    ? Math.max(...ranges.map(r => r.end))
+    : 0;
+
+  const newRange: IdRange = {
+    agent: agentName,
+    start: lastEnd + 1,
+    end: lastEnd + rangeSize,
+  };
+
+  ranges.push(newRange);
+  writeState(statePath, state);
+
+  return { start: newRange.start, end: newRange.end };
+}
+
+/**
+ * Get allocated ID ranges, optionally filtered by type.
+ */
+export function getIdRanges(
+  statePath: string,
+  idType?: string
+): Record<string, IdRange[]> {
+  const state = readState(statePath);
+  if (!state || !state.id_registry) {
+    return {};
+  }
+
+  if (idType) {
+    const ranges = state.id_registry.allocated_ranges[idType];
+    return ranges ? { [idType]: ranges } : {};
+  }
+
+  return state.id_registry.allocated_ranges;
+}
+
+/**
+ * Reset all allocated ID ranges.
+ */
+export function resetIdRegistry(statePath: string): void {
+  const state = readState(statePath);
+  if (!state) {
+    throw new Error(`Cannot read STATE.json at ${statePath}`);
+  }
+
+  state.id_registry = { allocated_ranges: {} };
+  writeState(statePath, state);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "gswd",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "description": "Get Shit Well Done — CLI meta-prompting and spec-generation system",
+  "bin": {
+    "gswd": "./bin/gswd-tools.cjs",
+    "gswd-tools": "./bin/gswd-tools.cjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "agents/"
+  ],
+  "scripts": {
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:cjs": "node --test tests/*.test.cjs",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0"
+  }
+}

package/templates/gswd/ARCHITECTURE.template.md

@@ -0,0 +1,17 @@
+# Architecture
+
+## Architecture
+
+### Components
+
+<!-- GSWD:CONTENT:COMPONENTS -->
+
+### Data Model
+
+<!-- GSWD:CONTENT:DATA_MODEL -->
+
+### Ownership Boundaries
+
+<!-- GSWD:CONTENT:OWNERSHIP -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/AUDIT.template.md

@@ -0,0 +1,31 @@
+# Audit Report
+
+**Date:** {date}
+**Result:** {PASS|FAIL}
+**Summary:** {passed}/{total} checks passed, {findings} issue(s) found
+
+## Coverage Matrix
+
+| Journey | Linked FRs | Linked NFRs | Acceptance Tests | Integrations | Status |
+|---------|------------|-------------|------------------|--------------|--------|
+
+## Coverage Statistics
+
+| Metric | Count |
+|--------|-------|
+| Journeys | {N} |
+| Functional Requirements | {N} |
+| Non-Functional Requirements | {N} |
+| Integrations | {N} |
+
+## Check Results
+
+### Journey FR Coverage
+### Journey Test Coverage
+### Orphan v1 FRs
+### Integration Approval
+### Required Headings
+
+## Actionable Checklist
+
+{Only present on FAIL}

package/templates/gswd/COMPETITION.template.md

@@ -0,0 +1,18 @@
+# Competition
+
+## Market Overview
+<!-- GSWD:CONTENT market_overview -->
+
+## Competitors
+<!-- GSWD:CONTENT competitors -->
+
+## Market Gaps
+<!-- GSWD:CONTENT gaps -->
+
+## Opportunities
+<!-- GSWD:CONTENT opportunities -->
+
+## Competitive Positioning
+<!-- GSWD:CONTENT competitive_positioning -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/DECISIONS.template.md

@@ -0,0 +1,18 @@
+# Decisions
+
+## Frozen Decisions
+<!-- GSWD:CONTENT - Minimum 8 frozen decisions required -->
+
+## Success Metrics
+<!-- GSWD:CONTENT - 1-3 measurable success metrics -->
+
+## Out of Scope
+<!-- GSWD:CONTENT - Explicit exclusions -->
+
+## Risks & Mitigations
+<!-- GSWD:CONTENT - Minimum 5 risks with mitigations -->
+
+## Open Questions
+<!-- GSWD:CONTENT - Unresolved questions for future resolution -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/GTM.template.md

@@ -0,0 +1,18 @@
+# Go-to-Market
+
+## Value Proposition
+<!-- GSWD:CONTENT value_prop -->
+
+## Positioning Statement
+<!-- GSWD:CONTENT positioning -->
+
+## Key Differentiators
+<!-- GSWD:CONTENT differentiators -->
+
+## Go-to-Market Angle
+<!-- GSWD:CONTENT gtm_angle -->
+
+## Early Traction Strategy
+<!-- GSWD:CONTENT traction -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/ICP.template.md

@@ -0,0 +1,18 @@
+# Ideal Customer Profile
+
+## ICP Profile
+<!-- GSWD:CONTENT icp_profile -->
+
+## Pain Points
+<!-- GSWD:CONTENT pain_points -->
+
+## Willingness to Pay
+<!-- GSWD:CONTENT wtp -->
+
+## Reachability
+<!-- GSWD:CONTENT reachability -->
+
+## Behavioral Traits
+<!-- GSWD:CONTENT traits -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/IMAGINE.template.md

@@ -0,0 +1,24 @@
+# Imagine
+
+## Vision
+<!-- GSWD:CONTENT vision -->
+
+## Target User
+<!-- GSWD:CONTENT target_user -->
+
+## Problem Statement
+<!-- GSWD:CONTENT problem -->
+
+## Product Direction
+<!-- GSWD:CONTENT direction -->
+
+## Alternatives
+<!-- GSWD:CONTENT alternatives -->
+
+## Wedge / MVP Boundary
+<!-- GSWD:CONTENT wedge -->
+
+## Success Metrics
+<!-- GSWD:CONTENT metrics -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/INTEGRATIONS.template.md

@@ -0,0 +1,7 @@
+# External Integrations
+
+## Integrations
+
+<!-- GSWD:CONTENT:INTEGRATIONS -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/JOURNEYS.template.md

@@ -0,0 +1,7 @@
+# User Journeys
+
+## Journeys
+
+<!-- GSWD:CONTENT:JOURNEYS -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/NFR.template.md

@@ -0,0 +1,7 @@
+# Non-Functional Requirements
+
+## Non-Functional Requirements
+
+<!-- GSWD:CONTENT:NFRS -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/PROJECT.template.md

@@ -0,0 +1,21 @@
+# {project_slug}
+
+## What This Is
+<!-- Compiled from IMAGINE.md vision -->
+
+## Target User
+<!-- Compiled from IMAGINE.md target user / ICP -->
+
+## Problem Statement
+<!-- Compiled from IMAGINE.md product direction -->
+
+## Wedge / MVP Boundary
+<!-- Compiled from IMAGINE.md wedge -->
+
+## Success Metrics
+<!-- Compiled from DECISIONS.md success metrics -->
+
+## Out of Scope
+<!-- Compiled from DECISIONS.md out of scope -->
+
+<!-- GSWD:COMPILED -->

package/templates/gswd/REQUIREMENTS.template.md

@@ -0,0 +1,31 @@
+# Requirements
+
+## Functional Requirements
+
+### v1 (In Scope)
+<!-- FRs with Scope: v1, sorted by Priority then ID -->
+
+### v2 (Future)
+<!-- FRs with Scope: v2, sorted by Priority then ID -->
+
+## Non-Functional Requirements
+
+### Security
+<!-- NFRs in security category -->
+
+### Privacy
+<!-- NFRs in privacy category -->
+
+### Performance
+<!-- NFRs in performance category -->
+
+### Observability
+<!-- NFRs in observability category -->
+
+## Traceability
+
+<!-- FR-to-Journey mapping table for v1 FRs -->
+| FR | Description | Journeys |
+|----|-------------|----------|
+
+<!-- GSWD:COMPILED -->

package/templates/gswd/ROADMAP.template.md

@@ -0,0 +1,21 @@
+# Roadmap
+
+## Overview
+
+v1 journeys assigned to 4 phases following deterministic rules.
+
+## Phases
+
+### Phase 1: Skeleton & Core Loop
+<!-- onboarding + core_action journeys -->
+
+### Phase 2: Persistence & History
+<!-- view_results journeys -->
+
+### Phase 3: Polish: errors, empty states, settings
+<!-- error_states + empty_states + settings journeys -->
+
+### Phase 4: Observability & Hardening
+<!-- Observability + security NFRs (no journeys) -->
+
+<!-- GSWD:COMPILED -->

package/templates/gswd/SPEC.template.md

@@ -0,0 +1,19 @@
+# Specification
+
+## Roles & Permissions
+
+<!-- GSWD:CONTENT:ROLES -->
+
+## Functional Requirements
+
+<!-- GSWD:CONTENT:FRS -->
+
+## Acceptance Criteria
+
+<!-- GSWD:CONTENT:ACCEPTANCE -->
+
+## Traceability
+
+<!-- GSWD:CONTENT:TRACEABILITY -->
+
+<!-- GSWD:COMPLETE -->

package/templates/gswd/STATE.template.md

@@ -0,0 +1,15 @@
+# Project State
+
+## Frozen Decisions
+<!-- Numbered list from DECISIONS.md -->
+
+## Approvals
+<!-- Auth model, data store, paid integrations from STATE.json -->
+
+## Open Questions
+<!-- Bulleted list from DECISIONS.md -->
+
+## Risks
+<!-- Bulleted list from DECISIONS.md risks & mitigations -->
+
+<!-- GSWD:COMPILED -->