gswd 1.0.0 → 1.1.0

package/dist/lib/state.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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
+ */
+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 ManualModeState {
+    enabled: boolean;
+    reruns: {
+        imagine: number;
+        specify: number;
+        audit: number;
+        compile: number;
+    };
+    last_checkpoint_stage: string | null;
+    interrupt_type: 'mid_stage' | 'between_stages' | null;
+}
+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;
+    first_run_complete?: boolean;
+    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;
+    manual_mode?: ManualModeState;
+}
+export declare const STAGE_ORDER: readonly ["imagine", "specify", "audit", "compile"];
+export type StageName = typeof STAGE_ORDER[number];
+/**
+ * Atomically write a file: write to .tmp, verify, rename.
+ * Cleans up .tmp on any failure.
+ */
+export declare function safeWriteFile(filePath: string, content: string): void;
+/**
+ * Atomically write JSON: pretty-print, atomic write, then verify round-trip.
+ */
+export declare function safeWriteJson(filePath: string, data: unknown): void;
+/**
+ * Create a default STATE.json object matching GSWD_SPEC Section 5.1.
+ */
+export declare function createDefaultState(projectSlug: string): GswdState;
+/**
+ * Read STATE.json. Returns null if file doesn't exist or is invalid JSON.
+ */
+export declare function readState(statePath: string): GswdState | null;
+/**
+ * Write STATE.json atomically. Updates updated_at timestamp.
+ */
+export declare function writeState(statePath: string, state: GswdState): void;
+/**
+ * Idempotent init: create STATE.json only if missing or corrupt.
+ * If valid state exists, returns it unchanged (no timestamp update).
+ */
+export declare function initState(stateDir: string, projectSlug: string): GswdState;
+/**
+ * Update a specific stage status. Read-modify-write pattern.
+ */
+export declare function updateStageStatus(statePath: string, stage: keyof StageStatus, status: string): void;
+/**
+ * Write a checkpoint to STATE.json.
+ */
+export declare function writeCheckpoint(statePath: string, workflow: string, checkpointId: string): void;
+/**
+ * Allocate an ID range for an agent. Ranges are non-overlapping per ID type.
+ */
+export declare function allocateIdRange(statePath: string, idType: string, agentName: string, rangeSize?: number): {
+    start: number;
+    end: number;
+};
+/**
+ * Get allocated ID ranges, optionally filtered by type.
+ */
+export declare function getIdRanges(statePath: string, idType?: string): Record<string, IdRange[]>;
+/**
+ * Reset all allocated ID ranges.
+ */
+export declare function resetIdRegistry(statePath: string): void;
+/**
+ * Mark all stages downstream of the re-run stage as 'not_started'.
+ * Also increments the re-run counter for the given stage.
+ * Performs a single atomic STATE.json write.
+ */
+export declare function cascadeInvalidate(statePath: string, fromStage: StageName): void;
+/**
+ * Update the manual mode checkpoint tracking in STATE.json.
+ * Called when entering or completing a stage boundary checkpoint.
+ */
+export declare function updateManualCheckpoint(statePath: string, stage: StageName | null, interruptType: 'mid_stage' | 'between_stages' | null): void;
+/**
+ * Set manual mode enabled/disabled in STATE.json.
+ */
+export declare function setManualMode(statePath: string, enabled: boolean): void;

package/dist/lib/state.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * 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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGE_ORDER = void 0;
+exports.safeWriteFile = safeWriteFile;
+exports.safeWriteJson = safeWriteJson;
+exports.createDefaultState = createDefaultState;
+exports.readState = readState;
+exports.writeState = writeState;
+exports.initState = initState;
+exports.updateStageStatus = updateStageStatus;
+exports.writeCheckpoint = writeCheckpoint;
+exports.allocateIdRange = allocateIdRange;
+exports.getIdRanges = getIdRanges;
+exports.resetIdRegistry = resetIdRegistry;
+exports.cascadeInvalidate = cascadeInvalidate;
+exports.updateManualCheckpoint = updateManualCheckpoint;
+exports.setManualMode = setManualMode;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// ─── Stage Order ─────────────────────────────────────────────────────────────
+exports.STAGE_ORDER = ['imagine', 'specify', 'audit', 'compile'];
+// ─── Atomic File I/O ─────────────────────────────────────────────────────────
+/**
+ * Atomically write a file: write to .tmp, verify, rename.
+ * Cleans up .tmp on any failure.
+ */
+function safeWriteFile(filePath, content) {
+    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.
+ */
+function safeWriteJson(filePath, data) {
+    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.
+ */
+function createDefaultState(projectSlug) {
+    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,
+        first_run_complete: false,
+        auto: {
+            enabled: false,
+            policy: 'balanced',
+            interrupt_reasons: [],
+            decisions: [],
+        },
+        approvals: {
+            auth_model: 'unapproved',
+            data_store: 'unapproved',
+            paid_integrations: [],
+        },
+        manual_mode: {
+            enabled: false,
+            reruns: { imagine: 0, specify: 0, audit: 0, compile: 0 },
+            last_checkpoint_stage: null,
+            interrupt_type: null,
+        },
+    };
+}
+/**
+ * Read STATE.json. Returns null if file doesn't exist or is invalid JSON.
+ */
+function readState(statePath) {
+    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;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write STATE.json atomically. Updates updated_at timestamp.
+ */
+function writeState(statePath, state) {
+    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).
+ */
+function initState(stateDir, projectSlug) {
+    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.
+ */
+function updateStageStatus(statePath, stage, status) {
+    const state = readState(statePath);
+    if (!state) {
+        throw new Error(`Cannot read STATE.json at ${statePath}`);
+    }
+    state.stage_status[stage] = status;
+    writeState(statePath, state);
+}
+/**
+ * Write a checkpoint to STATE.json.
+ */
+function writeCheckpoint(statePath, workflow, checkpointId) {
+    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.
+ */
+function allocateIdRange(statePath, idType, agentName, rangeSize = 50) {
+    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 = {
+        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.
+ */
+function getIdRanges(statePath, idType) {
+    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.
+ */
+function resetIdRegistry(statePath) {
+    const state = readState(statePath);
+    if (!state) {
+        throw new Error(`Cannot read STATE.json at ${statePath}`);
+    }
+    state.id_registry = { allocated_ranges: {} };
+    writeState(statePath, state);
+}
+// ─── Manual Mode ──────────────────────────────────────────────────────────────
+/**
+ * Mark all stages downstream of the re-run stage as 'not_started'.
+ * Also increments the re-run counter for the given stage.
+ * Performs a single atomic STATE.json write.
+ */
+function cascadeInvalidate(statePath, fromStage) {
+    const state = readState(statePath);
+    if (!state) {
+        throw new Error(`Cannot read STATE.json at ${statePath}`);
+    }
+    const idx = exports.STAGE_ORDER.indexOf(fromStage);
+    if (idx === -1)
+        return;
+    // Invalidate all downstream stages
+    for (let i = idx + 1; i < exports.STAGE_ORDER.length; i++) {
+        state.stage_status[exports.STAGE_ORDER[i]] = 'not_started';
+    }
+    // Ensure manual_mode exists
+    if (!state.manual_mode) {
+        state.manual_mode = {
+            enabled: false,
+            reruns: { imagine: 0, specify: 0, audit: 0, compile: 0 },
+            last_checkpoint_stage: null,
+            interrupt_type: null,
+        };
+    }
+    // Increment re-run counter for this stage
+    state.manual_mode.reruns[fromStage] = (state.manual_mode.reruns[fromStage] || 0) + 1;
+    // Single atomic write (re-run count + cascade in one operation)
+    writeState(statePath, state);
+}
+/**
+ * Update the manual mode checkpoint tracking in STATE.json.
+ * Called when entering or completing a stage boundary checkpoint.
+ */
+function updateManualCheckpoint(statePath, stage, interruptType) {
+    const state = readState(statePath);
+    if (!state) {
+        throw new Error(`Cannot read STATE.json at ${statePath}`);
+    }
+    if (!state.manual_mode) {
+        state.manual_mode = {
+            enabled: false,
+            reruns: { imagine: 0, specify: 0, audit: 0, compile: 0 },
+            last_checkpoint_stage: null,
+            interrupt_type: null,
+        };
+    }
+    state.manual_mode.last_checkpoint_stage = stage;
+    state.manual_mode.interrupt_type = interruptType;
+    writeState(statePath, state);
+}
+/**
+ * Set manual mode enabled/disabled in STATE.json.
+ */
+function setManualMode(statePath, enabled) {
+    const state = readState(statePath);
+    if (!state) {
+        throw new Error(`Cannot read STATE.json at ${statePath}`);
+    }
+    if (!state.manual_mode) {
+        state.manual_mode = {
+            enabled,
+            reruns: { imagine: 0, specify: 0, audit: 0, compile: 0 },
+            last_checkpoint_stage: null,
+            interrupt_type: null,
+        };
+    }
+    else {
+        state.manual_mode.enabled = enabled;
+    }
+    writeState(statePath, state);
+}

package/dist/tests/audit.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Audit module tests — coverage matrix, checks, report generation, auto-fix, gate
+ */
+export {};