@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

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

@@ -1,557 +0,0 @@
-/**
- * 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