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

package/dist/core/agent-progress/schema.js

@@ -0,0 +1,144 @@
+/**
+ * Agent progress JSON schema — α7 live-progress sprint (2026-05-27).
+ *
+ * Long-running agents (spawned externally OR via `pugi /agent`) emit a
+ * single JSON document per agent to `~/.pugi/agent-progress/<id>.json`.
+ * `pugi jobs --watch` tails the directory via chokidar and re-renders
+ * an Ink TUI that mirrors the Claude Code `/compact` visual pattern
+ * (header with elapsed + token counter, unicode progress bar, milestone
+ * list with done/active/pending status icons).
+ *
+ * Schema is intentionally optimistic — every numeric field is clamped
+ * by the writer/reader so a malformed document degrades to a partial
+ * card instead of crashing the watcher. The `pendingCount` /
+ * `completedCount` fields are pre-computed by the agent for the
+ * "… +N pending, M completed" footer; the renderer never re-counts
+ * (the agent may have collapsed milestone history to save bytes).
+ */
+/**
+ * Validate an unknown payload as an `AgentProgress` document. Returns
+ * the typed value on success and a string error otherwise. We deliberately
+ * keep this hand-rolled (no zod) — every field is checked exactly once,
+ * the error message is human-readable, and zero runtime deps.
+ */
+export function validateAgentProgress(value) {
+    if (typeof value !== 'object' || value === null) {
+        return { ok: false, error: 'progress payload must be a JSON object' };
+    }
+    const raw = value;
+    const requiredString = (field) => {
+        const v = raw[field];
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    };
+    const agentId = requiredString('agentId');
+    if (!agentId)
+        return { ok: false, error: 'agentId required (non-empty string)' };
+    if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) {
+        return { ok: false, error: 'agentId must match [a-zA-Z0-9_-]+ (filename-safe)' };
+    }
+    const agentType = requiredString('agentType');
+    if (!agentType)
+        return { ok: false, error: 'agentType required (non-empty string)' };
+    const task = requiredString('task');
+    if (!task)
+        return { ok: false, error: 'task required (non-empty string)' };
+    const startedAt = requiredString('startedAt');
+    if (!startedAt)
+        return { ok: false, error: 'startedAt required (ISO string)' };
+    if (Number.isNaN(Date.parse(startedAt))) {
+        return { ok: false, error: 'startedAt must be a parseable ISO timestamp' };
+    }
+    const lastUpdate = requiredString('lastUpdate');
+    if (!lastUpdate)
+        return { ok: false, error: 'lastUpdate required (ISO string)' };
+    if (Number.isNaN(Date.parse(lastUpdate))) {
+        return { ok: false, error: 'lastUpdate must be a parseable ISO timestamp' };
+    }
+    const elapsedMs = raw.elapsedMs;
+    if (typeof elapsedMs !== 'number' || !Number.isFinite(elapsedMs) || elapsedMs < 0) {
+        return { ok: false, error: 'elapsedMs required (non-negative number)' };
+    }
+    const percentComplete = raw.percentComplete;
+    if (typeof percentComplete !== 'number' ||
+        !Number.isFinite(percentComplete)) {
+        return { ok: false, error: 'percentComplete required (number 0..100)' };
+    }
+    const clampedPercent = Math.max(0, Math.min(100, percentComplete));
+    const status = raw.status;
+    if (status !== 'running' && status !== 'completed' && status !== 'failed') {
+        return { ok: false, error: 'status must be running | completed | failed' };
+    }
+    const currentStep = raw.currentStep;
+    if (typeof currentStep !== 'number' || currentStep < 0) {
+        return { ok: false, error: 'currentStep required (non-negative number)' };
+    }
+    const totalSteps = raw.totalSteps;
+    if (typeof totalSteps !== 'number' || totalSteps < 0) {
+        return { ok: false, error: 'totalSteps required (non-negative number)' };
+    }
+    const stepDescription = typeof raw.stepDescription === 'string'
+        ? raw.stepDescription
+        : '';
+    const milestonesRaw = raw.milestones;
+    if (!Array.isArray(milestonesRaw)) {
+        return { ok: false, error: 'milestones required (array, may be empty)' };
+    }
+    const milestones = [];
+    for (let i = 0; i < milestonesRaw.length; i += 1) {
+        const m = milestonesRaw[i];
+        if (typeof m !== 'object' || m === null) {
+            return { ok: false, error: `milestones[${i}] must be an object` };
+        }
+        const mr = m;
+        const label = typeof mr.label === 'string' ? mr.label : '';
+        if (!label) {
+            return { ok: false, error: `milestones[${i}].label required` };
+        }
+        const mStatus = mr.status;
+        if (mStatus !== 'done' && mStatus !== 'active' && mStatus !== 'pending') {
+            return {
+                ok: false,
+                error: `milestones[${i}].status must be done | active | pending`,
+            };
+        }
+        const ts = typeof mr.ts === 'string' ? mr.ts : undefined;
+        milestones.push({ label, status: mStatus, ts });
+    }
+    const tokensUsed = typeof raw.tokensUsed === 'number' && Number.isFinite(raw.tokensUsed)
+        ? Math.max(0, raw.tokensUsed)
+        : undefined;
+    const pendingCount = typeof raw.pendingCount === 'number' && Number.isFinite(raw.pendingCount)
+        ? Math.max(0, Math.floor(raw.pendingCount))
+        : undefined;
+    const completedCount = typeof raw.completedCount === 'number' && Number.isFinite(raw.completedCount)
+        ? Math.max(0, Math.floor(raw.completedCount))
+        : undefined;
+    return {
+        ok: true,
+        value: {
+            agentId,
+            agentType,
+            task,
+            startedAt,
+            lastUpdate,
+            elapsedMs,
+            tokensUsed,
+            percentComplete: clampedPercent,
+            status,
+            currentStep,
+            totalSteps,
+            stepDescription,
+            milestones,
+            pendingCount,
+            completedCount,
+        },
+    };
+}
+/**
+ * Default directory the writer and watcher share. Lives under the
+ * project workspace by convention so worktree-isolated agents can emit
+ * progress without crossing tenant boundaries. Operators can override
+ * via `PUGI_AGENT_PROGRESS_DIR` env var.
+ */
+export const DEFAULT_AGENT_PROGRESS_DIRNAME = '.pugi/agent-progress';
+//# sourceMappingURL=schema.js.map

package/dist/core/agent-progress/writer.js

@@ -0,0 +1,101 @@
+/**
+ * Agent progress writer — atomic file ops so the chokidar watcher
+ * never reads a half-written JSON document.
+ *
+ * Pattern (POSIX-portable):
+ *   1. Build the canonical JSON body.
+ *   2. Write to `<dir>/<agentId>.json.tmp-<pid>-<seq>`.
+ *   3. Rename (atomic on the same filesystem) to `<dir>/<agentId>.json`.
+ *   4. Cleanup is a no-op on success; on failure the caller bubbles the
+ *      error and the .tmp file is removed best-effort.
+ *
+ * The auto-cleanup of completed entries lives in `cleanup.ts` (commit 4);
+ * the writer here is the minimal surface the agent prompt boilerplate
+ * needs to copy + paste.
+ */
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { DEFAULT_AGENT_PROGRESS_DIRNAME, validateAgentProgress, } from './schema.js';
+let writeSequence = 0;
+/**
+ * Resolve the effective progress directory. Public so the watcher can
+ * share the same resolution rules without duplicating env-var logic.
+ */
+export function resolveProgressDir(override) {
+    const candidate = override
+        ?? process.env.PUGI_AGENT_PROGRESS_DIR
+        ?? join(process.cwd(), DEFAULT_AGENT_PROGRESS_DIRNAME);
+    if (candidate.startsWith('~/')) {
+        return join(homedir(), candidate.slice(2));
+    }
+    return resolve(candidate);
+}
+/**
+ * Write a progress document atomically.
+ *
+ * Throws on validation failure so the caller is loud about a schema
+ * regression. File-system errors propagate untouched.
+ */
+export function writeProgress(progress, options = {}) {
+    const validation = validateAgentProgress(progress);
+    if (!validation.ok) {
+        throw new Error(`invalid agent-progress payload: ${validation.error}`);
+    }
+    const dir = resolveProgressDir(options.dir);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const finalPath = join(dir, `${progress.agentId}.json`);
+    writeSequence += 1;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${writeSequence}`;
+    const body = `${JSON.stringify(progress, null, 2)}\n`;
+    try {
+        // mkdirSync above may have created `dir`, but a parallel agent could
+        // delete it between the existsSync and writeFile — ensure the parent
+        // of the tmp file exists right before the write.
+        const parent = dirname(tmpPath);
+        if (!existsSync(parent)) {
+            mkdirSync(parent, { recursive: true });
+        }
+        writeFileSync(tmpPath, body, 'utf8');
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup; surface the original error
+        }
+        throw err;
+    }
+    return { path: finalPath };
+}
+/**
+ * Build a fresh progress document with sensible defaults. Mostly a
+ * convenience for tests + the agent prompt boilerplate — the writer
+ * does NOT call this implicitly because agents have richer context
+ * about their own milestone state.
+ */
+export function makeInitialProgress(input) {
+    const now = input.now ?? Date.now;
+    const iso = new Date(now()).toISOString();
+    return {
+        agentId: input.agentId,
+        agentType: input.agentType,
+        task: input.task,
+        startedAt: iso,
+        lastUpdate: iso,
+        elapsedMs: 0,
+        percentComplete: 0,
+        status: 'running',
+        currentStep: 0,
+        totalSteps: Math.max(0, Math.floor(input.totalSteps)),
+        stepDescription: '',
+        milestones: input.milestones ?? [],
+        pendingCount: input.milestones?.filter((m) => m.status === 'pending').length,
+        completedCount: input.milestones?.filter((m) => m.status === 'done').length,
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/core/artifact-chain/dispatcher.js

@@ -0,0 +1,148 @@
+/**
+ * Artifact chain dispatcher — Pugi α7 Wave 6 (2026-05-27).
+ *
+ * Bridges the chain state machine (`state.ts`) to the existing
+ * `pugi delegate` surface. Each step renders a brief from the
+ * step's template + chain context, dispatches the brief to the
+ * step's persona, and writes the persona's response verbatim to the
+ * artifact file on disk.
+ *
+ * Mock-friendly by contract — the dispatcher accepts an injected
+ * `dispatch` function so specs can drive every branch without
+ * standing up a real runtime + Anvil round-trip. The real wire-up
+ * binds `dispatch` to the existing `submitDelegate` SDK helper +
+ * the SSE waiter; that wiring lives in `runtime/commands/chain.ts`
+ * so this module stays pure with respect to the network.
+ *
+ * Module contract:
+ *
+ *   - `dispatchStep` is the ONLY entry point. It reads the chain,
+ *     renders the brief, calls the injected dispatcher, persists the
+ *     artifact, and flips the step state. Callers do not touch the
+ *     state machine directly — that surface is intentionally narrow.
+ *
+ *   - The dispatcher never auto-advances. After a step lands the
+ *     cursor stays on the same step until the operator runs
+ *     `pugi chain next` again (or until `markComplete` is invoked
+ *     by the CLI handler after operator approval).
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chainDir, markComplete, markDispatched, markError, readChain, } from './state.js';
+import { findStep, renderBrief, } from './steps.js';
+/**
+ * Dispatch one step in the chain. The function is non-throwing — every
+ * failure mode returns a structured result so the CLI handler can map
+ * to an exit code without a try/catch wrapper.
+ */
+export async function dispatchStep(options) {
+    const now = options.now ?? (() => new Date());
+    const state = readChain(options.workspaceCwd, options.chainId);
+    if (!state) {
+        // Gemini P1 fix (PR #608): the docblock above promises a non-
+        // throwing surface, but the historical implementation threw here.
+        // Return a structured result keyed on `reason: 'chain_not_found'`
+        // so callers can switch on the failure family deterministically.
+        return {
+            ok: false,
+            stepId: 'prd',
+            error: `chain ${options.chainId} not found`,
+            reason: 'chain_not_found',
+            state: null,
+        };
+    }
+    const targetStepId = options.stepId ?? state.nextStep;
+    if (!targetStepId) {
+        return {
+            ok: false,
+            stepId: 'code',
+            error: 'chain is finalised — every step is already complete',
+            state,
+        };
+    }
+    const step = findStep(targetStepId);
+    if (!step) {
+        return {
+            ok: false,
+            stepId: targetStepId,
+            error: `unknown step id '${targetStepId}'`,
+            state,
+        };
+    }
+    const stepRecord = state.steps.find((s) => s.id === targetStepId);
+    if (stepRecord?.status === 'complete') {
+        return {
+            ok: false,
+            stepId: targetStepId,
+            error: `step '${targetStepId}' is already complete`,
+            state,
+        };
+    }
+    const brief = renderBrief(step.briefTemplate, {
+        chainId: state.id,
+        intent: state.intent,
+    });
+    let outcome;
+    try {
+        outcome = await options.dispatch({ chainId: state.id, step, brief });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const errorState = markError(options.workspaceCwd, options.chainId, targetStepId, message, { now });
+        return {
+            ok: false,
+            stepId: targetStepId,
+            error: message,
+            state: errorState,
+        };
+    }
+    if (outcome.kind === 'failed') {
+        const errorState = markError(options.workspaceCwd, options.chainId, targetStepId, outcome.error, { now });
+        return {
+            ok: false,
+            stepId: targetStepId,
+            error: outcome.error,
+            state: errorState,
+        };
+    }
+    // Success path: persist the artifact, flip the step to dispatched
+    // (or complete when autoApprove is set).
+    const dir = chainDir(options.workspaceCwd, state.id);
+    mkdirSync(dir, { recursive: true });
+    const artifactPath = join(dir, step.artifactFilename);
+    writeFileSync(artifactPath, ensureTrailingNewline(outcome.artifact), 'utf8');
+    let finalState = markDispatched(options.workspaceCwd, options.chainId, targetStepId, outcome.dispatchId, { now });
+    if (options.autoApprove) {
+        finalState = markComplete(options.workspaceCwd, options.chainId, targetStepId, { now });
+    }
+    return {
+        ok: true,
+        stepId: targetStepId,
+        dispatchId: outcome.dispatchId,
+        artifactPath,
+        state: finalState,
+    };
+}
+/**
+ * Synthesize a dispatcher that captures every call for inspection.
+ * Test-only — the real wire-up never uses this.
+ */
+export function createRecordingDispatcher(outcomes) {
+    const calls = [];
+    let index = 0;
+    const fn = async ({ chainId, step, brief }) => {
+        calls.push({ chainId, stepId: step.id, brief });
+        const outcome = outcomes[index];
+        index += 1;
+        if (!outcome) {
+            throw new Error(`recording dispatcher exhausted at call #${calls.length}`);
+        }
+        return outcome;
+    };
+    fn.calls = calls;
+    return fn;
+}
+function ensureTrailingNewline(text) {
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/core/artifact-chain/exporter.js

@@ -0,0 +1,164 @@
+/**
+ * Artifact chain exporter — Pugi α7 Wave 6 (2026-05-27).
+ *
+ * Bundles the seven step artifacts under `.pugi/chains/<id>/` into a
+ * single markdown report (default) or a deterministic JSON envelope
+ * the operator can feed into a future zip bundler. The exporter is
+ * read-only — it never mutates state.
+ *
+ * Why markdown instead of an actual `.zip`: the CLI ships zero binary
+ * dependencies (HARD rule for `@pugi/cli` install footprint — the
+ * 4.4MB bundled-zip toolchains would land the install at ~20MB).
+ * Operators that want a true zip pipe `pugi chain export` through
+ * `zip -j chain.zip` or similar; the markdown form covers 95% of the
+ * "share with my CTO" workflow without the dep.
+ *
+ * Module contract:
+ *
+ *   - `renderMarkdownReport` is pure. Pass it a snapshot + a map of
+ *     filename → contents and it returns the rendered report. The
+ *     CLI handler does the disk read; the spec drives the renderer
+ *     with synthetic content so it never touches the filesystem.
+ *
+ *   - `exportChain` does the disk dance — reads every artifact that
+ *     exists, skips missing ones (a partially-finished chain still
+ *     exports cleanly), and returns the report + the list of
+ *     skipped steps so the renderer can warn the operator.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { chainDir, readChain } from './state.js';
+import { CHAIN_STEPS } from './steps.js';
+/**
+ * Render the markdown report. The format is intentionally stable so
+ * downstream tools can grep it; do NOT reformat without bumping the
+ * report version comment in the header.
+ *
+ * Report layout:
+ *
+ *   # Pugi artifact chain: <chain id>
+ *
+ *   - **Intent**: ...
+ *   - **Created**: ...
+ *   - **Finalised**: ... (or "in progress")
+ *
+ *   ## 1. PRD — Olivia (PM)
+ *   <contents>
+ *
+ *   ## 2. ADR — Marcus (CTO)
+ *   <contents>
+ *
+ *   ... (one section per step)
+ */
+export function renderMarkdownReport(envelope) {
+    const lines = [];
+    lines.push(`# Pugi artifact chain: ${envelope.chainId}`);
+    lines.push('');
+    lines.push(`- **Intent**: ${envelope.intent}`);
+    lines.push(`- **Created**: ${envelope.createdAt}`);
+    lines.push(`- **Finalised**: ${envelope.finalisedAt ?? 'in progress'}`);
+    if (envelope.missingSteps.length > 0) {
+        lines.push(`- **Missing steps**: ${envelope.missingSteps.join(', ')}`);
+    }
+    lines.push('');
+    for (const entry of envelope.artifacts) {
+        lines.push(`## ${entry.step.ordinal}. ${entry.step.id.toUpperCase()} — ${entry.step.personaLabel}`);
+        lines.push('');
+        if (entry.contents === null) {
+            lines.push(`_artifact not yet produced (${entry.step.artifactFilename})_`);
+        }
+        else {
+            const trimmed = entry.contents.trimEnd();
+            lines.push(trimmed.length === 0 ? '_empty artifact_' : trimmed);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Render a deterministic JSON envelope. Same shape as
+ * `ChainExportEnvelope` minus the descriptor object (we serialise the
+ * step id + ordinal + persona so the consumer does not need access to
+ * the in-process descriptor table).
+ */
+export function renderJsonReport(envelope) {
+    const serialisable = {
+        chainId: envelope.chainId,
+        intent: envelope.intent,
+        createdAt: envelope.createdAt,
+        finalisedAt: envelope.finalisedAt,
+        missingSteps: envelope.missingSteps,
+        artifacts: envelope.artifacts.map((entry) => ({
+            stepId: entry.step.id,
+            ordinal: entry.step.ordinal,
+            persona: entry.step.persona,
+            personaLabel: entry.step.personaLabel,
+            filename: entry.step.artifactFilename,
+            bytes: entry.bytes,
+            contents: entry.contents,
+        })),
+    };
+    return `${JSON.stringify(serialisable, null, 2)}\n`;
+}
+/**
+ * Read the chain + every artifact on disk, build the envelope, and
+ * render either markdown OR JSON. Returns BOTH the envelope and the
+ * rendered string so callers can route to stdout, a file, or both.
+ *
+ * Non-throwing per the artifact-chain module contract — every failure
+ * mode (chain not found, malformed state) returns a structured
+ * `ok: false` result so callers can map to an exit code without a
+ * try/catch wrapper.
+ */
+export function exportChain(options) {
+    const state = readChain(options.workspaceCwd, options.chainId);
+    if (!state) {
+        return {
+            ok: false,
+            error: `chain ${options.chainId} not found`,
+            reason: 'chain_not_found',
+        };
+    }
+    const envelope = buildEnvelope(state, options.workspaceCwd);
+    const format = options.format ?? 'markdown';
+    const rendered = format === 'json' ? renderJsonReport(envelope) : renderMarkdownReport(envelope);
+    return { ok: true, envelope, rendered };
+}
+/**
+ * Build the export envelope from a chain snapshot + the workspace
+ * directory. Exported so the spec can drive the renderer against a
+ * fixture state without an explicit disk read.
+ */
+export function buildEnvelope(state, workspaceCwd, options = {}) {
+    const dir = chainDir(workspaceCwd, state.id);
+    const readArtifact = options.readArtifact ?? defaultReadArtifact;
+    const artifacts = [];
+    const missing = [];
+    for (const step of CHAIN_STEPS) {
+        const path = join(dir, step.artifactFilename);
+        const contents = readArtifact(path);
+        if (contents === null) {
+            missing.push(step.id);
+        }
+        artifacts.push({
+            step,
+            contents,
+            bytes: contents === null ? 0 : Buffer.byteLength(contents, 'utf8'),
+        });
+    }
+    const finalisedAt = state.nextStep === null ? state.updatedAt : null;
+    return {
+        chainId: state.id,
+        intent: state.intent,
+        createdAt: state.createdAt,
+        finalisedAt,
+        artifacts,
+        missingSteps: missing,
+    };
+}
+function defaultReadArtifact(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf8');
+}
+//# sourceMappingURL=exporter.js.map