gsd-unsupervised 1.0.0

package/dist/session-log.test.js

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appendSessionLog, readSessionLog, inspectForCrashedSessions, getLastRunningSession, computeResumePoint, } from './session-log.js';
+describe('session-log', () => {
+    let logPath;
+    let tmpDir;
+    let workspaceRoot;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), 'session-log-test-'));
+        logPath = join(tmpDir, 'session-log.jsonl');
+        workspaceRoot = join(tmpDir, 'workspace');
+        mkdirSync(join(workspaceRoot, '.planning', 'phases'), { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(tmpDir, { recursive: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    const entry = (status, overrides) => ({
+        timestamp: new Date().toISOString(),
+        goalTitle: 'Test goal',
+        phase: '/gsd/execute-plan',
+        phaseNumber: 1,
+        planNumber: 1,
+        sessionId: null,
+        command: '/gsd/execute-plan .planning/phases/01-x/01-01-PLAN.md',
+        status,
+        ...overrides,
+    });
+    describe('appendSessionLog and readSessionLog', () => {
+        it('appends one line and readSessionLog returns entries', async () => {
+            await appendSessionLog(logPath, entry('running'));
+            const entries = await readSessionLog(logPath);
+            expect(entries).toHaveLength(1);
+            expect(entries[0].status).toBe('running');
+            expect(entries[0].goalTitle).toBe('Test goal');
+        });
+        it('appends multiple lines', async () => {
+            await appendSessionLog(logPath, entry('running'));
+            await appendSessionLog(logPath, entry('done', { durationMs: 100 }));
+            const entries = await readSessionLog(logPath);
+            expect(entries).toHaveLength(2);
+            expect(entries[0].status).toBe('running');
+            expect(entries[1].status).toBe('done');
+            expect(entries[1].durationMs).toBe(100);
+        });
+        it('skips malformed lines', async () => {
+            writeFileSync(logPath, '{"status":"running"}\nnot json\n{"timestamp":"x","goalTitle":"","phase":"","sessionId":null,"command":"","status":"done"}\n', 'utf-8');
+            const entries = await readSessionLog(logPath);
+            expect(entries).toHaveLength(2);
+        });
+        it('returns empty array for missing file', async () => {
+            const entries = await readSessionLog(join(tmpDir, 'nonexistent.jsonl'));
+            expect(entries).toEqual([]);
+        });
+    });
+    describe('inspectForCrashedSessions', () => {
+        it('returns null for empty log', async () => {
+            writeFileSync(logPath, '', 'utf-8');
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).toBeNull();
+        });
+        it('returns null when last entry is done', async () => {
+            await appendSessionLog(logPath, entry('running'));
+            await appendSessionLog(logPath, entry('done'));
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).toBeNull();
+        });
+        it('returns null when last entry is timeout', async () => {
+            await appendSessionLog(logPath, entry('timeout'));
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).toBeNull();
+        });
+        it('returns last entry when last is running', async () => {
+            await appendSessionLog(logPath, entry('done'));
+            await appendSessionLog(logPath, entry('running', { goalTitle: 'Current' }));
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).not.toBeNull();
+            expect(got.status).toBe('running');
+            expect(got.goalTitle).toBe('Current');
+        });
+        it('returns last entry when last is crashed', async () => {
+            await appendSessionLog(logPath, entry('running'));
+            await appendSessionLog(logPath, entry('crashed', { error: 'exit 1' }));
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).not.toBeNull();
+            expect(got.status).toBe('crashed');
+            expect(got.error).toBe('exit 1');
+        });
+        it('skips malformed lines and returns last valid running/crashed', async () => {
+            writeFileSync(logPath, 'garbage\n', 'utf-8');
+            await appendSessionLog(logPath, entry('crashed'));
+            const got = await inspectForCrashedSessions(logPath);
+            expect(got).not.toBeNull();
+            expect(got.status).toBe('crashed');
+        });
+    });
+    describe('getLastRunningSession', () => {
+        it('returns last running entry', async () => {
+            await appendSessionLog(logPath, entry('done'));
+            await appendSessionLog(logPath, entry('running', { goalTitle: 'A' }));
+            const got = await getLastRunningSession(logPath);
+            expect(got).not.toBeNull();
+            expect(got.goalTitle).toBe('A');
+        });
+        it('returns null when no running', async () => {
+            await appendSessionLog(logPath, entry('done'));
+            const got = await getLastRunningSession(logPath);
+            expect(got).toBeNull();
+        });
+    });
+    describe('computeResumePoint', () => {
+        it('returns null for empty log', async () => {
+            const got = await computeResumePoint(logPath, workspaceRoot, 'My Goal');
+            expect(got).toBeNull();
+        });
+        it('returns null when goal title mismatch', async () => {
+            await appendSessionLog(logPath, entry('crashed', { goalTitle: 'Other Goal' }));
+            const got = await computeResumePoint(logPath, workspaceRoot, 'My Goal');
+            expect(got).toBeNull();
+        });
+        it('returns ResumeFrom based on first missing SUMMARY file', async () => {
+            // ROADMAP: one phase, incomplete
+            writeFileSync(join(workspaceRoot, '.planning', 'ROADMAP.md'), '- [ ] **Phase 1: Alpha** — Test phase\n', 'utf-8');
+            const phaseDir = join(workspaceRoot, '.planning', 'phases', '01-alpha');
+            mkdirSync(phaseDir, { recursive: true });
+            // Plan 1 executed, plan 2 not executed
+            writeFileSync(join(phaseDir, '01-01-PLAN.md'), '# Plan 1\n', 'utf-8');
+            writeFileSync(join(phaseDir, '01-01-SUMMARY.md'), '# Summary 1\n', 'utf-8');
+            writeFileSync(join(phaseDir, '01-02-PLAN.md'), '# Plan 2\n', 'utf-8');
+            await appendSessionLog(logPath, entry('crashed', { goalTitle: 'My Goal' }));
+            const got = await computeResumePoint(logPath, workspaceRoot, 'My Goal');
+            expect(got).toEqual({ phaseNumber: 1, planNumber: 2 });
+        });
+        it('returns null when firstPendingGoalTitle is empty', async () => {
+            await appendSessionLog(logPath, entry('crashed', { goalTitle: 'My Goal' }));
+            const got = await computeResumePoint(logPath, workspaceRoot, '');
+            expect(got).toBeNull();
+        });
+    });
+});

package/dist/state-index.d.ts

@@ -0,0 +1,5 @@
+import type { Logger } from './logger.js';
+import type { StateSnapshot } from './state-types.js';
+export type { StateSnapshot } from './state-types.js';
+export declare function parseStateFile(contents: string, logger?: Logger): StateSnapshot | null;
+export declare function readStateFile(filePath: string, logger?: Logger): Promise<StateSnapshot | null>;

package/dist/state-index.js

@@ -0,0 +1,31 @@
+import { parseStateMd, readStateMd } from './state-parser.js';
+export function parseStateFile(contents, logger) {
+    try {
+        const snapshot = parseStateMd(contents);
+        if (!snapshot && logger) {
+            logger.warn({ reason: 'unparseable_state_md' }, 'Failed to parse STATE.md contents');
+        }
+        return snapshot;
+    }
+    catch (err) {
+        if (logger) {
+            logger.warn({ err }, 'Exception while parsing STATE.md contents');
+        }
+        return null;
+    }
+}
+export async function readStateFile(filePath, logger) {
+    try {
+        const snapshot = await readStateMd(filePath);
+        if (!snapshot && logger) {
+            logger.warn({ path: filePath, reason: 'unparseable_or_missing' }, 'Failed to read STATE.md');
+        }
+        return snapshot;
+    }
+    catch (err) {
+        if (logger) {
+            logger.warn({ err, path: filePath }, 'Exception while reading STATE.md');
+        }
+        return null;
+    }
+}

package/dist/state-parser.d.ts

@@ -0,0 +1,13 @@
+import type { StateSnapshot } from './state-types.js';
+/**
+ * Parses the "## Current Position" section of STATE.md into a StateSnapshot.
+ * Returns null if the section is missing, content is empty/whitespace, or any
+ * required field (phase line with "of", plan line, status) is missing or malformed.
+ * progressPercent is null when the progress line is absent or has no percentage.
+ */
+export declare function parseStateMd(content: string): StateSnapshot | null;
+/**
+ * Reads STATE.md from the given file path and returns a StateSnapshot.
+ * Returns null if the file is missing, unreadable, or content fails to parse.
+ */
+export declare function readStateMd(filePath: string): Promise<StateSnapshot | null>;

package/dist/state-parser.js

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+const SECTION_RE = /## Current Position\n([\s\S]*?)(?=\n## |$)/;
+const PHASE_RE = /^Phase:\s*(\d+)\s+of\s+(\d+)\s*\(([^)]+)\)\s*$/m;
+const PLAN_RE = /^Plan:\s*(\d+)\s+of\s+(\d+)\s+in current phase\s*$/m;
+const STATUS_RE = /^Status:\s*(.+)$/m;
+const LAST_ACTIVITY_RE = /^Last activity:\s*(.+)$/m;
+const PROGRESS_RE = /^Progress:\s*[^\n]*?(\d+)%\s*$/m;
+const GIT_SHA_RE = /^Git SHA:\s*(.+)$/m;
+/**
+ * Parses the "## Current Position" section of STATE.md into a StateSnapshot.
+ * Returns null if the section is missing, content is empty/whitespace, or any
+ * required field (phase line with "of", plan line, status) is missing or malformed.
+ * progressPercent is null when the progress line is absent or has no percentage.
+ */
+export function parseStateMd(content) {
+    if (typeof content !== 'string' || content.trim().length === 0) {
+        return null;
+    }
+    const sectionMatch = content.match(SECTION_RE);
+    if (!sectionMatch) {
+        return null;
+    }
+    const block = sectionMatch[1];
+    const phaseMatch = block.match(PHASE_RE);
+    if (!phaseMatch) {
+        return null;
+    }
+    const phaseNumber = parseInt(phaseMatch[1], 10);
+    const totalPhases = parseInt(phaseMatch[2], 10);
+    const phaseName = phaseMatch[3].trim();
+    const planMatch = block.match(PLAN_RE);
+    if (!planMatch) {
+        return null;
+    }
+    const planNumber = parseInt(planMatch[1], 10);
+    const totalPlans = parseInt(planMatch[2], 10);
+    const statusMatch = block.match(STATUS_RE);
+    if (!statusMatch) {
+        return null;
+    }
+    const status = statusMatch[1].trim();
+    let lastActivity = '';
+    const lastActivityMatch = block.match(LAST_ACTIVITY_RE);
+    if (lastActivityMatch) {
+        lastActivity = lastActivityMatch[1].trim();
+    }
+    let progressPercent = null;
+    const progressMatch = block.match(PROGRESS_RE);
+    if (progressMatch) {
+        progressPercent = parseInt(progressMatch[1], 10);
+    }
+    let gitSha = null;
+    const gitMatch = content.match(GIT_SHA_RE);
+    if (gitMatch && gitMatch[1].trim().length > 0) {
+        gitSha = gitMatch[1].trim();
+    }
+    return {
+        phaseNumber,
+        totalPhases,
+        phaseName,
+        planNumber,
+        totalPlans,
+        status,
+        lastActivity,
+        progressPercent,
+        gitSha,
+    };
+}
+/**
+ * Reads STATE.md from the given file path and returns a StateSnapshot.
+ * Returns null if the file is missing, unreadable, or content fails to parse.
+ */
+export async function readStateMd(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    return parseStateMd(content);
+}

package/dist/state-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/state-parser.test.js

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'vitest';
+import { parseStateMd, readStateMd } from './state-parser.js';
+const STANDARD_BLOCK = `
+## Current Position
+
+Phase: 3 of 7 (Cursor Agent Integration)
+Plan: 3 of 3 in current phase
+Status: Phase complete
+Last activity: 2026-03-16 — Completed 03-03-PLAN.md — Phase 3 complete
+
+Progress: ██████░░░░ 43%
+`;
+describe('parseStateMd', () => {
+    it('parses standard content with all fields', () => {
+        const got = parseStateMd(STANDARD_BLOCK);
+        expect(got).not.toBeNull();
+        expect(got).toEqual({
+            phaseNumber: 3,
+            totalPhases: 7,
+            phaseName: 'Cursor Agent Integration',
+            planNumber: 3,
+            totalPlans: 3,
+            status: 'Phase complete',
+            lastActivity: '2026-03-16 — Completed 03-03-PLAN.md — Phase 3 complete',
+            progressPercent: 43,
+        });
+    });
+    it('parses phase in-progress (Executing plan)', () => {
+        const content = `
+## Current Position
+
+Phase: 2 of 7 (Core Orchestration Loop)
+Plan: 1 of 3 in current phase
+Status: Executing plan
+Last activity: 2026-03-16 — Running 02-01-PLAN.md
+
+Progress: ██░░░░░░░░ 14%
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got.status).toBe('Executing plan');
+        expect(got.phaseNumber).toBe(2);
+        expect(got.planNumber).toBe(1);
+    });
+    it('parses plan 1 of 1 in phase', () => {
+        const content = `
+## Current Position
+
+Phase: 1 of 7 (Foundation & CLI Scaffold)
+Plan: 1 of 1 in current phase
+Status: Planned
+Last activity: 2026-03-16 — Not started
+
+Progress: ░░░░░░░░░░ 0%
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got.planNumber).toBe(1);
+        expect(got.totalPlans).toBe(1);
+    });
+    it('returns null when "Current Position" section is missing', () => {
+        const content = `
+# Project State
+
+## Some Other Section
+
+Phase: 1 of 7 (Foundation)
+Plan: 1 of 1 in current phase
+Status: Planned
+`;
+        expect(parseStateMd(content)).toBeNull();
+    });
+    it('returns null for empty content', () => {
+        expect(parseStateMd('')).toBeNull();
+    });
+    it('returns null for whitespace-only content', () => {
+        expect(parseStateMd('   \n\n  \t  ')).toBeNull();
+    });
+    it('returns null when phase line has no "of" (malformed)', () => {
+        const content = `
+## Current Position
+
+Phase: 3 (Cursor Agent Integration)
+Plan: 3 of 3 in current phase
+Status: Phase complete
+Last activity: 2026-03-16
+`;
+        expect(parseStateMd(content)).toBeNull();
+    });
+    it('returns null when plan line is missing', () => {
+        const content = `
+## Current Position
+
+Phase: 3 of 7 (Cursor Agent Integration)
+Status: Phase complete
+Last activity: 2026-03-16
+`;
+        expect(parseStateMd(content)).toBeNull();
+    });
+    it('returns null when status line is missing', () => {
+        const content = `
+## Current Position
+
+Phase: 3 of 7 (Cursor Agent Integration)
+Plan: 3 of 3 in current phase
+Last activity: 2026-03-16
+`;
+        expect(parseStateMd(content)).toBeNull();
+    });
+    it('sets progressPercent to null when progress line has no percentage', () => {
+        const content = `
+## Current Position
+
+Phase: 3 of 7 (Cursor Agent Integration)
+Plan: 3 of 3 in current phase
+Status: Phase complete
+Last activity: 2026-03-16
+
+Progress: ██████░░░░
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got.progressPercent).toBeNull();
+    });
+    it('sets progressPercent to null when progress line is missing', () => {
+        const content = `
+## Current Position
+
+Phase: 3 of 7 (Cursor Agent Integration)
+Plan: 3 of 3 in current phase
+Status: Phase complete
+Last activity: 2026-03-16
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got.progressPercent).toBeNull();
+    });
+    it('parses real STATE.md Current Position block (phase 4)', () => {
+        const content = `
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md
+
+## Current Position
+
+Phase: 4 of 7 (State Monitoring & Phase Transitions)
+Plan: 0 of 3 in current phase
+Status: Planned
+Last activity: 2026-03-16 — Phase 4 planned with 3 plans (TDD parser, watcher + events, daemon/orchestrator wiring)
+
+Progress: ██████░░░░ 43%
+
+## Performance Metrics
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got).toEqual({
+            phaseNumber: 4,
+            totalPhases: 7,
+            phaseName: 'State Monitoring & Phase Transitions',
+            planNumber: 0,
+            totalPlans: 3,
+            status: 'Planned',
+            lastActivity: '2026-03-16 — Phase 4 planned with 3 plans (TDD parser, watcher + events, daemon/orchestrator wiring)',
+            progressPercent: 43,
+        });
+    });
+    it('trims status and lastActivity', () => {
+        const content = `
+## Current Position
+
+Phase: 1 of 7 (Foundation)
+Plan: 1 of 1 in current phase
+Status:   Planned  
+Last activity:   2026-03-16 — Started
+
+Progress: 10%
+`;
+        const got = parseStateMd(content);
+        expect(got).not.toBeNull();
+        expect(got.status).toBe('Planned');
+        expect(got.lastActivity).toBe('2026-03-16 — Started');
+        expect(got.progressPercent).toBe(10);
+    });
+});
+describe('readStateMd', () => {
+    it('reads and parses existing STATE.md', async () => {
+        const { mkdtemp, writeFile, rm, mkdir } = await import('node:fs/promises');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const dir = await mkdtemp(join(tmpdir(), 'state-parser-existing-'));
+        const planningDir = join(dir, '.planning');
+        const statePath = join(planningDir, 'STATE.md');
+        try {
+            await mkdir(planningDir, { recursive: true });
+            await writeFile(statePath, STANDARD_BLOCK, 'utf-8');
+            const got = await readStateMd(statePath);
+            expect(got).not.toBeNull();
+            expect(typeof got.phaseNumber).toBe('number');
+            expect(typeof got.totalPhases).toBe('number');
+            expect(typeof got.status).toBe('string');
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it('returns null when file is missing', async () => {
+        const got = await readStateMd('.planning/NONEXISTENT-STATE.md');
+        expect(got).toBeNull();
+    });
+    it('returns null when file content is unparseable', async () => {
+        const { mkdtemp, writeFile, rm } = await import('node:fs/promises');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const dir = await mkdtemp(join(tmpdir(), 'state-parser-'));
+        const badPath = join(dir, 'STATE.md');
+        try {
+            await writeFile(badPath, 'not a valid state file, no ## Current Position', 'utf-8');
+            const got = await readStateMd(badPath);
+            expect(got).toBeNull();
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/state-types.d.ts

@@ -0,0 +1,20 @@
+export interface StateSnapshot {
+    phaseNumber: number;
+    totalPhases: number;
+    phaseName: string;
+    planNumber: number;
+    totalPlans: number;
+    status: string;
+    lastActivity: string;
+    /**
+     * When present, represents the overall progress percentage parsed from the
+     * "Progress:" line in STATE.md. Null when the progress line is missing or
+     * has no percentage.
+     */
+    progressPercent: number | null;
+    /**
+     * Optional git SHA associated with the snapshot, parsed from a "Git SHA:"
+     * line when present. Older STATE.md files may not include this.
+     */
+    gitSha?: string | null;
+}

package/dist/state-types.js

@@ -0,0 +1 @@
+export {};

package/dist/state-watcher.d.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from 'node:events';
+import type { Logger } from './logger.js';
+import type { StateSnapshot } from './state-types.js';
+/** Progress event payloads emitted by StateWatcher */
+export type ProgressEvent = {
+    type: 'state_changed';
+    previous: StateSnapshot | null;
+    current: StateSnapshot;
+} | {
+    type: 'phase_advanced';
+    fromPhase: number;
+    toPhase: number;
+    phaseName: string;
+} | {
+    type: 'plan_advanced';
+    phaseNumber: number;
+    fromPlan: number;
+    toPlan: number;
+} | {
+    type: 'phase_completed';
+    phaseNumber: number;
+    phaseName: string;
+} | {
+    type: 'goal_completed';
+    progressPercent: number;
+};
+export interface StateWatcherOptions {
+    stateMdPath: string;
+    debounceMs?: number;
+    logger: Logger;
+}
+/**
+ * Watches STATE.md for changes, parses content, and emits typed progress events.
+ * Used by the daemon and dashboard for real-time progress visibility.
+ */
+export declare class StateWatcher extends EventEmitter {
+    private readonly stateMdPath;
+    private readonly debounceMs;
+    private readonly logger;
+    private watcher;
+    private debounceTimer;
+    private lastSnapshot;
+    private goalCompleteEmitted;
+    constructor(options: StateWatcherOptions);
+    start(): void;
+    private handleChange;
+    stop(): void;
+    getLastSnapshot(): StateSnapshot | null;
+}