@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/prd-check/session-review.js

@@ -0,0 +1,557 @@
+/**
+ * PRD ↔ session review — Pugi  final (`/prd-check --session`,
+ *).
+ *
+ * The shipped `/prd-check` surface verifies a PRD's acceptance criteria
+ * against committed artifacts on disk (file / test / doc / command /
+ * route verifiers — see `core/prd-check/verifiers.ts`). That mode is
+ * the canonical CI gate; it inspects a snapshot of the workspace and
+ * decides healthy / failing / unparsed.
+ *
+ * `--session` adds a complementary mode: ask "does the work I just
+ * did in this REPL session actually cover the PRD?" without requiring
+ * the acceptance criteria to be written in the structured shape the
+ * verifier expects. The mode:
+ *
+ *  1. Walks up from the current working directory looking for
+ *     `PRD.md`, then `PRODUCT.md`, then `apps/<any>/PRODUCT.md`
+ *     under the workspace root. The first hit wins; the rest are
+ *     ignored. We stop at the filesystem root.
+ *
+ *  2. Reads the last N (default 20) events from `.pugi/events.jsonl`
+ *     that represent operator-visible turns: user prompts, model
+ *     responses, and tool calls with their results. Other event
+ *     types (`session`, `hook`, …) are filtered so the prompt the
+ *     subagent receives is dominated by intent + work-actually-done
+ *     rather than infrastructure noise.
+ *
+ *  3. Builds a structured prompt for a cross-review subagent. The
+ *     subagent is dispatched via the standard `dispatch()` surface
+ *     (see `core/subagents/dispatcher.ts`) using the `pm` persona —
+ *     the closest match to a PRD reviewer in today's roster. The
+ *     subagent is instructed to return two newline-separated lists:
+ *     `Satisfied:` and `Outstanding:`.
+ *
+ *  4. Parses the subagent's response into a structured envelope so
+ *     the slash + the top-level CLI render the same output shape
+ *     (Markdown sections in the TUI, JSON for scripts).
+ *
+ * The module is pure with respect to dependencies — every IO surface
+ * (`readPrdSearch`, `readSessionEvents`, `dispatchReview`) is
+ * accepted as an injected dep so the spec can drive every branch
+ * without a real filesystem or a network call. The default
+ * implementations live in `defaultSessionReviewDeps`.
+ *
+ * The subagent return contract is intentionally loose: any line
+ * starting with `Satisfied:` (case-insensitive) opens the satisfied
+ * section; any line starting with `Outstanding:` opens the
+ * outstanding section. Bulleted lines (`-`, `*`, `•`) inside each
+ * section land as list items. Free prose between sections is
+ * captured as the `note` field on the envelope so the reviewer can
+ * still attach a sentence of context.
+ *
+ * Cross-review subagent: this module routes to whatever persona
+ * resolves the "PRD reviewer" role at dispatch time. In
+ * that is the `pm` persona via `dispatch({ role: 'pm', … })`. Once
+ * a dedicated reviewer persona lands (project tracking ID:
+ * cross-review subagent track), swapping it requires only changing
+ * `DEFAULT_REVIEW_ROLE` below.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+/**
+ * Names of PRD-style files we will try to locate. Order matters —
+ * `PRD.md` wins over `PRODUCT.md` so a project that has both an
+ * authored PRD and a legacy PRODUCT brief points at the PRD.
+ */
+const PRD_CANDIDATE_NAMES = ['PRD.md', 'PRODUCT.md'];
+/**
+ * Per-app product brief glob. We scan `apps/*` under the workspace
+ * root for a top-level `PRODUCT.md` — this matches the layout the
+ * Pugi monorepo uses (`apps/admin-api/PRODUCT.md`, etc.). Walk is
+ * shallow on purpose to keep the search bounded.
+ */
+const APPS_DIR = 'apps';
+/** Default number of NDJSON turns to surface to the reviewer. */
+export const DEFAULT_TURN_COUNT = 20;
+/**
+ * Subagent role we ask to play the PRD reviewer. `reviewer` is the
+ * canonical slot in the dispatcher's role enum (see
+ * `packages/pugi-sdk/src/subagent-contracts.ts`) — every dispatch
+ * resolves a role to a persona at runtime via the isolation matrix.
+ * The constant is exported so callers can override (e.g. route to
+ * `verifier` for a stricter pass).
+ */
+export const DEFAULT_REVIEW_ROLE = 'reviewer';
+/**
+ * Run the `--session` mode end-to-end. The function emits status
+ * lines through `deps.onStatus` (the slash dispatcher wires this to
+ * `appendSystemLine`) and returns the structured envelope.
+ */
+export async function runSessionReview(workspaceRoot, deps, options = {}) {
+    const turnCount = options.turnCount ?? DEFAULT_TURN_COUNT;
+    const status = deps.onStatus ?? (() => undefined);
+    status('Locating PRD...');
+    const prdPath = deps.resolvePrd(workspaceRoot);
+    if (prdPath === null) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'no_prd',
+            prdPath: null,
+            prdTitle: null,
+            turnsRead: 0,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: `No PRD.md or PRODUCT.md found walking up from ${workspaceRoot}.`,
+        };
+    }
+    const prdSource = safeRead(prdPath);
+    if (prdSource === null) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'no_prd',
+            prdPath: relative(workspaceRoot, prdPath) || prdPath,
+            prdTitle: null,
+            turnsRead: 0,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: `PRD file at ${prdPath} is unreadable.`,
+        };
+    }
+    const prdTitle = extractTitle(prdSource);
+    status(`Reading last ${turnCount} session turns...`);
+    const rawEvents = deps.readEventsLog(workspaceRoot);
+    const turns = rawEvents === null ? [] : parseTurns(rawEvents, turnCount);
+    status('Reviewing against PRD...');
+    const prompt = buildReviewPrompt({
+        prdPath,
+        prdTitle,
+        prdSource,
+        turns,
+        workspaceRoot,
+    });
+    const outcome = await deps.dispatchReview({
+        role: DEFAULT_REVIEW_ROLE,
+        prompt,
+        workspaceRoot,
+    });
+    if (!outcome.ok) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'dispatch_failed',
+            prdPath: relative(workspaceRoot, prdPath) || prdPath,
+            prdTitle,
+            turnsRead: turns.length,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: outcome.reason,
+        };
+    }
+    const parsed = parseReviewResponse(outcome.text);
+    return {
+        command: 'prd-check',
+        mode: 'session',
+        status: 'ok',
+        prdPath: relative(workspaceRoot, prdPath) || prdPath,
+        prdTitle,
+        turnsRead: turns.length,
+        satisfied: parsed.satisfied,
+        outstanding: parsed.outstanding,
+        note: parsed.note,
+        rawReview: outcome.text,
+    };
+}
+/**
+ * Render the envelope as plain-text lines for the TUI / shell. The
+ * slash + the top-level CLI both use this so the surface stays
+ * single-sourced; the structured envelope (above) feeds `--json`.
+ */
+export function renderSessionReview(result) {
+    if (result.status === 'no_prd') {
+        return result.reason ?? 'No PRD found.';
+    }
+    if (result.status === 'dispatch_failed') {
+        return `PRD review dispatch failed: ${result.reason ?? 'unknown'}`;
+    }
+    const lines = [];
+    lines.push(`PRD review (${result.turnsRead} turn(s) read from .pugi/events.jsonl)`);
+    if (result.prdPath !== null) {
+        const titlePart = result.prdTitle === null ? '' : ` — ${result.prdTitle}`;
+        lines.push(`Source: ${result.prdPath}${titlePart}`);
+    }
+    lines.push('');
+    if (result.satisfied.length === 0) {
+        lines.push('Satisfied: (none reported)');
+    }
+    else {
+        lines.push('Satisfied:');
+        for (const item of result.satisfied)
+            lines.push(` - ${item}`);
+    }
+    lines.push('');
+    if (result.outstanding.length === 0) {
+        lines.push('Outstanding: (none reported)');
+    }
+    else {
+        lines.push('Outstanding:');
+        for (const item of result.outstanding)
+            lines.push(` - ${item}`);
+    }
+    if (result.note.length > 0) {
+        lines.push('');
+        lines.push(`Note: ${result.note}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compose the prompt handed to the reviewer subagent. The prompt is
+ * deterministic — input order matters for prompt cache hits so we
+ * keep the layout stable: PRD source first, session turns second,
+ * forcing-question schema last.
+ */
+export function buildReviewPrompt(input) {
+    const parts = [];
+    parts.push('You are a PRD reviewer. Read the PRD below, then read the recent session turns, then decide which requirements are SATISFIED by the work-so-far and which remain OUTSTANDING.');
+    parts.push('');
+    parts.push('Reply in EXACTLY this shape:');
+    parts.push('');
+    parts.push('Satisfied:');
+    parts.push('- <requirement>');
+    parts.push('- <requirement>');
+    parts.push('');
+    parts.push('Outstanding:');
+    parts.push('- <requirement>');
+    parts.push('- <requirement>');
+    parts.push('');
+    parts.push('Each list item is one PRD requirement, paraphrased to fit a single line. Do not invent requirements that are not in the PRD. If the session shows no work toward a requirement, list it Outstanding.');
+    parts.push('');
+    parts.push('--- PRD start ---');
+    parts.push(`Path: ${relative(input.workspaceRoot, input.prdPath) || input.prdPath}`);
+    if (input.prdTitle !== null)
+        parts.push(`Title: ${input.prdTitle}`);
+    parts.push('');
+    parts.push(input.prdSource);
+    parts.push('--- PRD end ---');
+    parts.push('');
+    parts.push(`--- Last ${input.turns.length} session turn(s) start ---`);
+    for (const turn of input.turns) {
+        parts.push(formatTurn(turn));
+    }
+    parts.push('--- session turns end ---');
+    return parts.join('\n');
+}
+/**
+ * Walk up from cwd looking for the first PRD / PRODUCT file. Also
+ * scans `apps/*` under the workspace root once we find a directory
+ * that contains an `apps` folder. Returns absolute path or null.
+ */
+export function defaultResolvePrd(cwd) {
+    let current = resolve(cwd);
+    for (let i = 0; i < 32; i += 1) {
+        for (const name of PRD_CANDIDATE_NAMES) {
+            const candidate = join(current, name);
+            if (existsSync(candidate) && safeIsFile(candidate)) {
+                return candidate;
+            }
+        }
+        // If this directory holds an apps/ folder, scan one level deep
+        // for app-scoped PRODUCT.md. We do NOT keep walking up past this
+        // point — the apps/ folder marks the workspace root in our
+        // monorepo layout.
+        const appsDir = join(current, APPS_DIR);
+        if (existsSync(appsDir) && safeIsDirectory(appsDir)) {
+            const appHit = scanAppsForProduct(appsDir);
+            if (appHit !== null)
+                return appHit;
+            return null;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Default events log reader. Returns the raw file contents or null
+ * when the log is absent — `.pugi/events.jsonl` only exists when
+ * the workspace has had at least one session.
+ */
+export function defaultReadEventsLog(workspaceRoot) {
+    const path = join(workspaceRoot, '.pugi', 'events.jsonl');
+    return safeRead(path);
+}
+/**
+ * Default cross-review dispatcher. Routes through the standard
+ * subagents `dispatch()` surface in stub-mode (no engine client) so
+ * the slash + the CLI top-level have a working default that does not
+ * require a live admin-api connection. When an engine client is in
+ * scope (callers supply one via injection from the runtime cli.ts
+ * layer once auth is resolved), `dispatch()` will route to the real
+ * cross-review subagent.
+ *
+ * Imported dynamically so test paths that inject a stub never pull
+ * the dispatcher graph into the spec.
+ */
+export const defaultDispatchReview = async (input) => {
+    try {
+        const { dispatch, inMemoryDispatcherContext } = await import('../subagents/dispatcher.js');
+        // The dispatcher's role enum is the canonical schema; `as` keeps
+        // the caller's role string flowing through without re-importing
+        // the schema here (the schema parse inside `dispatch()` will
+        // reject if it does not match — that is the contract gate).
+        const task = {
+            id: `prd-review-${Date.now()}`,
+            role: input.role,
+            prompt: input.prompt,
+            permissionMode: 'plan',
+        };
+        const ctx = inMemoryDispatcherContext({
+            sessionId: `prd-review-session-${Date.now()}`,
+            workspaceRoot: input.workspaceRoot,
+            sink: [],
+        });
+        const outcome = await dispatch(task, ctx);
+        if (!outcome || typeof outcome !== 'object') {
+            return { ok: false, reason: 'dispatcher returned an unexpected shape' };
+        }
+        if (typeof outcome.summary === 'string' && outcome.summary.length > 0) {
+            return { ok: true, text: outcome.summary };
+        }
+        return { ok: false, reason: 'dispatcher response carried no reviewable summary' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: message };
+    }
+};
+/** Convenience bundle for callers that want the real-IO defaults. */
+export function defaultSessionReviewDeps(overrides = {}) {
+    return {
+        resolvePrd: overrides.resolvePrd ?? defaultResolvePrd,
+        readEventsLog: overrides.readEventsLog ?? defaultReadEventsLog,
+        dispatchReview: overrides.dispatchReview ?? defaultDispatchReview,
+        ...(overrides.onStatus !== undefined ? { onStatus: overrides.onStatus } : {}),
+    };
+}
+/**
+ * Parse NDJSON, filter to operator-visible turns, and return the
+ * last N in chronological order. Malformed lines are silently
+ * dropped — the events log is appended to from multiple processes
+ * and partial writes during shutdown can leave a trailing line.
+ */
+export function parseTurns(raw, max) {
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const events = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // Drop malformed lines.
+        }
+    }
+    const visible = [];
+    for (const event of events) {
+        const role = classifyEvent(event);
+        if (role === null)
+            continue;
+        visible.push({
+            index: visible.length,
+            role,
+            summary: summariseEvent(event, role),
+            raw: event,
+        });
+    }
+    if (visible.length <= max) {
+        return visible.map((t, idx) => ({ ...t, index: idx }));
+    }
+    return visible.slice(visible.length - max).map((t, idx) => ({ ...t, index: idx }));
+}
+/**
+ * Pull a "Satisfied:" / "Outstanding:" pair out of the subagent text.
+ * Both labels are matched case-insensitively at line start. Bulleted
+ * items use any of `- `, `* `, or `• `. Free prose before / between
+ * sections lands in `note` (concatenated with a single space so the
+ * renderer can decide on wrapping).
+ */
+export function parseReviewResponse(text) {
+    const lines = text.split('\n');
+    const satisfied = [];
+    const outstanding = [];
+    const noteParts = [];
+    let section = 'none';
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const header = matchSectionHeader(line);
+        if (header !== null) {
+            section = header;
+            // Capture any inline item after the colon, e.g. "Satisfied: foo".
+            const inline = stripHeaderPrefix(line);
+            if (inline.length > 0) {
+                pushItem(inline, section, satisfied, outstanding);
+            }
+            continue;
+        }
+        const bulleted = matchBulleted(line);
+        if (bulleted !== null) {
+            pushItem(bulleted, section, satisfied, outstanding);
+            continue;
+        }
+        if (section === 'none') {
+            noteParts.push(line);
+        }
+        else {
+            // Continuation of the previous bulleted item — append.
+            const target = section === 'satisfied' ? satisfied : outstanding;
+            if (target.length > 0) {
+                target[target.length - 1] = `${target[target.length - 1]} ${line}`;
+            }
+            else {
+                noteParts.push(line);
+            }
+        }
+    }
+    return { satisfied, outstanding, note: noteParts.join(' ') };
+}
+/* ------------------------------ helpers ------------------------------ */
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function safeIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function safeIsDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function scanAppsForProduct(appsDir) {
+    let entries;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        entries = require('node:fs').readdirSync(appsDir);
+    }
+    catch {
+        return null;
+    }
+    entries.sort();
+    for (const entry of entries) {
+        const candidate = join(appsDir, entry, 'PRODUCT.md');
+        if (existsSync(candidate) && safeIsFile(candidate))
+            return candidate;
+        const prdCandidate = join(appsDir, entry, 'PRD.md');
+        if (existsSync(prdCandidate) && safeIsFile(prdCandidate))
+            return prdCandidate;
+    }
+    return null;
+}
+function extractTitle(source) {
+    for (const raw of source.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('# '))
+            return line.slice(2).trim();
+        if (line.startsWith('#'))
+            return line.replace(/^#+/, '').trim();
+        return null;
+    }
+    return null;
+}
+function classifyEvent(event) {
+    const type = typeof event.type === 'string' ? event.type : '';
+    if (type === 'user' || type === 'user_message' || type === 'prompt')
+        return 'user';
+    if (type === 'assistant' || type === 'model' || type === 'response' || type === 'completion') {
+        return 'model';
+    }
+    if (type === 'tool_call' || type === 'tool_result' || type === 'file_mutation')
+        return 'tool';
+    return null;
+}
+function summariseEvent(event, role) {
+    const text = typeof event.text === 'string' ? event.text : '';
+    const tool = typeof event.tool === 'string' ? event.tool : '';
+    const status = typeof event.status === 'string' ? event.status : '';
+    const path = typeof event.path === 'string' ? event.path : '';
+    const op = typeof event.operation === 'string' ? event.operation : '';
+    switch (role) {
+        case 'user':
+            return clip(text, 480);
+        case 'model':
+            return clip(text, 800);
+        case 'tool': {
+            if (event.type === 'tool_call')
+                return `tool_call ${tool || '?'}`;
+            if (event.type === 'tool_result')
+                return `tool_result ${tool || '?'} ${status}`.trim();
+            if (event.type === 'file_mutation')
+                return `file_mutation ${op} ${path}`.trim();
+            return `tool ${tool}`;
+        }
+    }
+}
+function clip(text, max) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, max - 1)}…`;
+}
+function formatTurn(turn) {
+    return `[${turn.index + 1}] ${turn.role}: ${turn.summary}`;
+}
+function matchSectionHeader(line) {
+    const lower = line.toLowerCase();
+    if (/^satisfied\b/.test(lower))
+        return 'satisfied';
+    if (/^outstanding\b/.test(lower))
+        return 'outstanding';
+    return null;
+}
+function stripHeaderPrefix(line) {
+    const colon = line.indexOf(':');
+    if (colon === -1)
+        return '';
+    return line.slice(colon + 1).trim();
+}
+function matchBulleted(line) {
+    const match = /^(?:[-*•]|\d+\.)\s+(.*)$/u.exec(line);
+    return match === null ? null : (match[1] ?? '').trim();
+}
+function pushItem(item, section, satisfied, outstanding) {
+    if (item.length === 0)
+        return;
+    if (section === 'satisfied')
+        satisfied.push(item);
+    else if (section === 'outstanding')
+        outstanding.push(item);
+}
+//# sourceMappingURL=session-review.js.map