@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/runtime/commands/chain.js

@@ -0,0 +1,489 @@
+/**
+ * `pugi chain` — Pugi α7 Wave 6 artifact chain command (2026-05-27).
+ *
+ * The chain encodes Pugi's moat: an operator drops one high-level
+ * intent and the CLI walks a deterministic 7-step pipeline (PRD →
+ * ADR → mindmap → ER → sequence → tests → code), each step
+ * dispatched to a specialist persona. The CLI surface mirrors `pugi
+ * doctor` / `pugi prd-check`: thin wiring layer that resolves cwd +
+ * flags + writeOutput, with the heavy lifting in
+ * `core/artifact-chain/{state,steps,dispatcher,exporter}.ts`.
+ *
+ * Subcommand grammar:
+ *
+ *   pugi chain new "<intent>"         — start new chain
+ *   pugi chain status [<chain-id>]    — show current cursor + step table
+ *   pugi chain next [<chain-id>]      — advance to next step (operator approves prior)
+ *   pugi chain show <step> [<chain-id>] — render one artifact
+ *   pugi chain export [<chain-id>] [--json] — bundle as markdown/JSON
+ *   pugi chain list                   — list every chain in the workspace
+ *
+ * When `<chain-id>` is omitted the handler resolves the most-recent
+ * chain on disk (operator workflow optimization — the common case is
+ * iterating on the chain you just created).
+ *
+ * Module contract:
+ *
+ *   - `runChainCommand` is the single entry point. Both the top-level
+ *     `pugi chain` handler in `runtime/cli.ts` AND the in-REPL
+ *     `/chain` slash command call it. Subcommand parsing is inline so
+ *     a typo surfaces with a usage hint instead of silently dropping.
+ *
+ *   - The dispatcher dep is injected so the spec can drive every
+ *     branch without standing up Anvil. Real wire-up binds to the
+ *     existing `submitDelegate` SDK helper via the SSE waiter.
+ *
+ *   - Exit codes:
+ *       0 — happy path
+ *       1 — runtime failure (no chain found / no credentials / dispatch failed)
+ *       2 — usage error (unknown subcommand / missing required arg)
+ */
+import { submitDelegate } from '@pugi/sdk';
+import { chainDir, createChain, listChainIds, markComplete, readChain, } from '../../core/artifact-chain/state.js';
+import { CHAIN_STEPS, findStep, } from '../../core/artifact-chain/steps.js';
+import { dispatchStep, } from '../../core/artifact-chain/dispatcher.js';
+import { exportChain, } from '../../core/artifact-chain/exporter.js';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { waitForDelegateTerminal, } from './delegate.js';
+/**
+ * Parse + run the chain command. Non-throwing — every failure mode
+ * surfaces a structured envelope. Sets `process.exitCode` so the
+ * cli.ts handler does not need a try/catch wrapper.
+ */
+export async function runChainCommand(args, ctx) {
+    const [rawSub, ...rest] = args;
+    if (!rawSub) {
+        emitUsage(ctx, 'missing subcommand');
+        return;
+    }
+    const sub = rawSub.toLowerCase();
+    switch (sub) {
+        case 'new':
+            return handleNew(rest, ctx);
+        case 'status':
+            return handleStatus(rest, ctx);
+        case 'next':
+            return handleNext(rest, ctx);
+        case 'show':
+            return handleShow(rest, ctx);
+        case 'export':
+            return handleExport(rest, ctx);
+        case 'list':
+            return handleList(rest, ctx);
+        default:
+            emitUsage(ctx, `unknown subcommand '${rawSub}'`);
+            return;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Subcommand handlers                                                */
+/* ------------------------------------------------------------------ */
+async function handleNew(args, ctx) {
+    const intent = args.join(' ').trim();
+    if (intent.length === 0) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'new',
+            error: 'intent must be non-empty',
+            hint: 'Usage: pugi chain new "<one-sentence intent>"',
+        }, 'pugi chain new: intent must be non-empty.\nUsage: pugi chain new "<one-sentence intent>"');
+        process.exitCode = 2;
+        return;
+    }
+    let state;
+    try {
+        state = createChain(ctx.cwd, intent, ctx.now ? { now: ctx.now } : {});
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ ok: false, command: 'chain', subcommand: 'new', error: message }, `pugi chain new: ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const firstStep = state.nextStep ? findStep(state.nextStep) : null;
+    ctx.writeOutput({
+        ok: true,
+        command: 'chain',
+        subcommand: 'new',
+        chainId: state.id,
+        data: { intent: state.intent, nextStep: state.nextStep, dir: chainDir(ctx.cwd, state.id) },
+    }, [
+        `chain ${state.id} created.`,
+        `intent: ${state.intent}`,
+        firstStep
+            ? `next: ${firstStep.id} — ${firstStep.gloss} (persona: ${firstStep.personaLabel})`
+            : 'next: (none — chain already finalised)',
+        `dir: ${chainDir(ctx.cwd, state.id)}`,
+        'Run `pugi chain next` to dispatch the first step.',
+    ].join('\n'));
+}
+async function handleStatus(args, ctx) {
+    const chainId = await resolveChainId(args[0], ctx, 'status');
+    if (!chainId)
+        return;
+    const state = readChain(ctx.cwd, chainId);
+    if (!state) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'status',
+            error: `chain ${chainId} not found`,
+        }, `pugi chain status: chain ${chainId} not found.`);
+        process.exitCode = 1;
+        return;
+    }
+    const next = state.nextStep ? findStep(state.nextStep) : null;
+    const lines = [];
+    lines.push(`chain ${state.id} — ${state.intent}`);
+    lines.push(`created ${state.createdAt}; updated ${state.updatedAt}`);
+    lines.push('');
+    lines.push('  #  step      status      persona         dispatch');
+    for (const step of CHAIN_STEPS) {
+        const record = state.steps.find((s) => s.id === step.id);
+        if (!record)
+            continue;
+        lines.push(`  ${step.ordinal}  ${step.id.padEnd(8)}  ${record.status.padEnd(10)}  ${step.personaLabel.padEnd(15)} ${record.dispatchId ?? '-'}`);
+    }
+    lines.push('');
+    lines.push(next
+        ? `next: ${next.id} — ${next.gloss}`
+        : 'next: (none — chain finalised)');
+    ctx.writeOutput({
+        ok: true,
+        command: 'chain',
+        subcommand: 'status',
+        chainId: state.id,
+        data: {
+            intent: state.intent,
+            nextStep: state.nextStep,
+            steps: state.steps,
+        },
+    }, lines.join('\n'));
+}
+async function handleNext(args, ctx) {
+    const chainId = await resolveChainId(args[0], ctx, 'next');
+    if (!chainId)
+        return;
+    const state = readChain(ctx.cwd, chainId);
+    if (!state) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'next',
+            error: `chain ${chainId} not found`,
+        }, `pugi chain next: chain ${chainId} not found.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Operator approval gate: if the most-recent step is in `dispatched`
+    // and its artifact file is on disk, flip it to complete before
+    // advancing. This is the "operator reviewed the artifact, ship the
+    // next step" semantic — running `pugi chain next` twice in a row
+    // walks the chain forward by one step each time.
+    const pendingApproval = state.steps.find((s) => s.status === 'dispatched');
+    let workingState = state;
+    if (pendingApproval) {
+        const step = findStep(pendingApproval.id);
+        const artifactPath = step
+            ? join(chainDir(ctx.cwd, state.id), step.artifactFilename)
+            : null;
+        if (artifactPath && existsSync(artifactPath)) {
+            workingState = markComplete(ctx.cwd, state.id, pendingApproval.id, ctx.now ? { now: ctx.now } : {});
+        }
+    }
+    if (!workingState.nextStep) {
+        ctx.writeOutput({
+            ok: true,
+            command: 'chain',
+            subcommand: 'next',
+            chainId: workingState.id,
+            data: { finalised: true },
+        }, `chain ${workingState.id} is finalised — every step is complete.`);
+        return;
+    }
+    const dispatcher = ctx.dispatch ?? buildLiveDispatcher(ctx);
+    const result = await dispatchStep({
+        workspaceCwd: ctx.cwd,
+        chainId: workingState.id,
+        dispatch: dispatcher,
+        ...(ctx.now ? { now: ctx.now } : {}),
+    });
+    if (!result.ok) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'next',
+            error: result.error,
+            hint: `step ${result.stepId} did not complete; re-run after fixing the issue.`,
+        }, `pugi chain next: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    const step = findStep(result.stepId);
+    ctx.writeOutput({
+        ok: true,
+        command: 'chain',
+        subcommand: 'next',
+        chainId: workingState.id,
+        data: {
+            stepId: result.stepId,
+            dispatchId: result.dispatchId,
+            artifactPath: result.artifactPath,
+            nextStep: result.state.nextStep,
+        },
+    }, [
+        `dispatched ${result.stepId} (${step?.personaLabel ?? 'unknown persona'}); dispatchId=${result.dispatchId}.`,
+        `artifact: ${result.artifactPath}`,
+        'Review the artifact, then run `pugi chain next` again to advance.',
+    ].join('\n'));
+}
+async function handleShow(args, ctx) {
+    const [stepArg, idArg] = args;
+    if (!stepArg) {
+        emitUsage(ctx, 'usage: pugi chain show <step> [<chain-id>]');
+        return;
+    }
+    const step = findStep(stepArg.toLowerCase());
+    if (!step) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'show',
+            error: `unknown step '${stepArg}'`,
+            hint: `valid: ${CHAIN_STEPS.map((s) => s.id).join(', ')}`,
+        }, `pugi chain show: unknown step '${stepArg}'. Valid: ${CHAIN_STEPS.map((s) => s.id).join(', ')}.`);
+        process.exitCode = 2;
+        return;
+    }
+    const chainId = await resolveChainId(idArg, ctx, 'show');
+    if (!chainId)
+        return;
+    const path = join(chainDir(ctx.cwd, chainId), step.artifactFilename);
+    if (!existsSync(path)) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand: 'show',
+            error: `artifact not found: ${path}`,
+            hint: `step '${step.id}' may not have been dispatched yet.`,
+        }, `pugi chain show: artifact not found at ${path}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const contents = readFileSync(path, 'utf8');
+    ctx.writeOutput({
+        ok: true,
+        command: 'chain',
+        subcommand: 'show',
+        chainId,
+        data: { stepId: step.id, path, contents },
+    }, contents);
+}
+async function handleExport(args, ctx) {
+    const jsonFlag = args.includes('--json');
+    const positional = args.filter((a) => !a.startsWith('--'));
+    const chainId = await resolveChainId(positional[0], ctx, 'export');
+    if (!chainId)
+        return;
+    const format = jsonFlag || ctx.json ? 'json' : 'markdown';
+    // exportChain is non-throwing per the artifact-chain module contract;
+    // we branch on the structured discriminator instead of a try/catch.
+    // Gemini P1 fix (PR #608, 2026-05-27): the historical impl threw on
+    // missing chain, which broke the contract documented in
+    // `core/artifact-chain/exporter.ts`.
+    const result = exportChain({ workspaceCwd: ctx.cwd, chainId, format });
+    if (!result.ok) {
+        ctx.writeOutput({ ok: false, command: 'chain', subcommand: 'export', error: result.error }, `pugi chain export: ${result.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    ctx.writeOutput({
+        ok: true,
+        command: 'chain',
+        subcommand: 'export',
+        chainId,
+        data: {
+            format,
+            missingSteps: result.envelope.missingSteps,
+            bytes: result.rendered.length,
+        },
+    }, result.rendered);
+}
+async function handleList(_args, ctx) {
+    const ids = listChainIds(ctx.cwd);
+    if (ids.length === 0) {
+        ctx.writeOutput({ ok: true, command: 'chain', subcommand: 'list', data: { chains: [] } }, 'no chains in this workspace. Run `pugi chain new "<intent>"` to start one.');
+        return;
+    }
+    const rows = [];
+    const lines = ['chain id        next step    intent'];
+    for (const id of ids) {
+        const state = readChain(ctx.cwd, id);
+        if (!state)
+            continue;
+        rows.push({ id, intent: state.intent, nextStep: state.nextStep });
+        lines.push(`${id.padEnd(15)} ${(state.nextStep ?? 'done').padEnd(12)} ${state.intent}`);
+    }
+    ctx.writeOutput({ ok: true, command: 'chain', subcommand: 'list', data: { chains: rows } }, lines.join('\n'));
+}
+/* ------------------------------------------------------------------ */
+/* Helpers                                                            */
+/* ------------------------------------------------------------------ */
+function emitUsage(ctx, error) {
+    ctx.writeOutput({
+        ok: false,
+        command: 'chain',
+        subcommand: 'usage',
+        error,
+        hint: 'Usage:\n' +
+            '  pugi chain new "<intent>"\n' +
+            '  pugi chain status [<chain-id>]\n' +
+            '  pugi chain next [<chain-id>]\n' +
+            '  pugi chain show <step> [<chain-id>]\n' +
+            '  pugi chain export [<chain-id>] [--json]\n' +
+            '  pugi chain list',
+    }, `pugi chain: ${error}\n` +
+        'Usage:\n' +
+        '  pugi chain new "<intent>"\n' +
+        '  pugi chain status [<chain-id>]\n' +
+        '  pugi chain next [<chain-id>]\n' +
+        '  pugi chain show <step> [<chain-id>]\n' +
+        '  pugi chain export [<chain-id>] [--json]\n' +
+        '  pugi chain list');
+    process.exitCode = 2;
+}
+async function resolveChainId(explicit, ctx, subcommand) {
+    if (explicit && explicit.length > 0 && !explicit.startsWith('--')) {
+        return explicit;
+    }
+    const ids = listChainIds(ctx.cwd);
+    if (ids.length === 0) {
+        ctx.writeOutput({
+            ok: false,
+            command: 'chain',
+            subcommand,
+            error: 'no chains in this workspace',
+            hint: 'Run `pugi chain new "<intent>"` first.',
+        }, `pugi chain ${subcommand}: no chains in this workspace. Run \`pugi chain new "<intent>"\` first.`);
+        process.exitCode = 1;
+        return null;
+    }
+    // Pick the most-recently-modified chain (last write wins). The
+    // `listChainIds` sort is alphabetic, so we re-stat each candidate
+    // and pick the freshest. Cheap — operator workspaces hold tens of
+    // chains at the absolute outside.
+    let best = ids[0];
+    let bestMtime = 0;
+    for (const id of ids) {
+        const statePath = join(chainDir(ctx.cwd, id), 'chain.json');
+        try {
+            const mtime = statSync(statePath).mtimeMs;
+            if (mtime > bestMtime) {
+                best = id;
+                bestMtime = mtime;
+            }
+        }
+        catch {
+            // skip directories without a chain.json
+        }
+    }
+    return best;
+}
+/**
+ * Build the live dispatcher that binds to the existing delegate SDK
+ * surface. The dispatcher opens a fresh session per step (matching
+ * `pugi delegate` semantics), POSTs the brief, and waits for the SSE
+ * terminal event. The waiter aggregates every matching
+ * `agent.message` frame for the persona's taskId and returns the
+ * concatenated text as the `transcript` field on the `completed`
+ * outcome; the dispatcher writes that transcript verbatim as the
+ * artifact, fulfilling the artifact-chain module contract that the
+ * persona's response lands on disk.
+ *
+ * When credentials are missing the dispatcher returns a `failed`
+ * outcome on every call so the chain surfaces a clean error instead
+ * of crashing. The CLI handler caller surfaces this to the operator.
+ *
+ * Gemini P1 fix (PR #608, 2026-05-27): the previous implementation
+ * wrote a comment-only stub pointing the operator at the SSE log
+ * because the waiter did not surface persona text. Pairing the new
+ * `transcript` field on `DelegateTerminalOutcome` with this caller
+ * closes the loop end-to-end.
+ *
+ * Test surface: `ctx.waitForTerminal` is injected so the spec can
+ * exercise the success / failure / empty-transcript / blocked paths
+ * without standing up a real fetch + EventSource pipeline. The default
+ * is the live `waitForDelegateTerminal` impl.
+ */
+export function buildLiveDispatcher(ctx) {
+    return async ({ chainId, step, brief }) => {
+        const config = ctx.resolveConfig ? ctx.resolveConfig() : null;
+        if (!config) {
+            return {
+                kind: 'failed',
+                dispatchId: null,
+                error: 'no Pugi credential configured; run `pugi login` first. Set ctx.resolveConfig OR `pugi login`.',
+            };
+        }
+        if (!ctx.openSession) {
+            return {
+                kind: 'failed',
+                dispatchId: null,
+                error: 'session opener not wired; this code path requires a runtime context',
+            };
+        }
+        const opened = await ctx.openSession(config, ctx.cwd);
+        if ('error' in opened) {
+            return {
+                kind: 'failed',
+                dispatchId: null,
+                error: `session open failed: ${opened.error}`,
+            };
+        }
+        const submit = ctx.submitDelegate ?? submitDelegate;
+        const result = await submit(config, opened.sessionId, {
+            persona: step.persona,
+            brief,
+        });
+        if (result.status !== 'ok') {
+            return {
+                kind: 'failed',
+                dispatchId: null,
+                error: `delegate failed: ${result.status}${'message' in result ? ` — ${result.message}` : ''}`,
+            };
+        }
+        const waiter = ctx.waitForTerminal ?? waitForDelegateTerminal;
+        const outcome = await waiter(config, opened.sessionId, result.response.personaSlug);
+        if (outcome.kind === 'completed') {
+            // Persona text captured verbatim from `agent.message` frames on
+            // the SSE stream. The `transcript` field is empty when the
+            // persona reached `agent.completed` without emitting any
+            // assistant text (e.g. a tool-only turn) — we still surface a
+            // structured artifact so `pugi chain show` does not 404 and the
+            // operator has dispatch provenance even on a silent completion.
+            const artifact = outcome.transcript.length > 0
+                ? outcome.transcript
+                : `<!-- chain ${chainId} step ${step.id} completed with no assistant text -->\n` +
+                    `<!-- dispatchId: ${result.response.dispatchId}, session: ${opened.sessionId} -->\n` +
+                    `<!-- persona '${step.personaLabel}' reached terminal without emitting agent.message frames -->\n`;
+            return {
+                kind: 'completed',
+                dispatchId: result.response.dispatchId,
+                artifact,
+            };
+        }
+        const error = outcome.kind === 'blocked'
+            ? outcome.detail
+            : outcome.kind === 'failed'
+                ? outcome.error
+                : outcome.error;
+        return {
+            kind: 'failed',
+            dispatchId: result.response.dispatchId,
+            error,
+        };
+    };
+}
+//# sourceMappingURL=chain.js.map