@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/commands/retro.js

@@ -0,0 +1,210 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text, render } from 'ink';
+import { collectGitContext, countCommitsAheadOfBase, } from '../core/retro/git-collector.js';
+import { ensurePugiGitIgnore } from '../core/pugi-gitignore.js';
+import { computeMetrics } from '../core/retro/metrics.js';
+import { persistRetro } from '../core/retro/narrative.js';
+import { collectPlaneSlice, postRetroToPlane, resolvePlaneConfig, } from '../core/retro/plane-collector.js';
+import { enrichLinks } from '../core/retro/pr-issue-link.js';
+import { computeHealthCard } from '../core/retro/health-card.js';
+/** Parse `7d` | `14d` | `30d` | `24h` into a duration in days
+ * (fractional for sub-day windows). Defaults to 7 days when omitted.
+ */
+function parseDurationToken(token) {
+    if (!token)
+        return undefined;
+    const match = /^(\d+)(h|d)$/.exec(token);
+    if (!match)
+        return undefined;
+    const value = Number.parseInt(match[1] ?? '0', 10);
+    const unit = match[2];
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    const days = unit === 'h' ? value / 24 : value;
+    return { days, label: token };
+}
+function buildWindow(durationDays, label, now) {
+    const until = now;
+    const sinceMs = until.getTime() - durationDays * 24 * 60 * 60 * 1000;
+    const since = new Date(sinceMs);
+    // Midnight-align the lower bound to keep `--since` deterministic per day.
+    since.setHours(0, 0, 0, 0);
+    return { since, until, label, days: Math.max(1, Math.round(durationDays)) };
+}
+function buildPriorWindow(current) {
+    const until = new Date(current.since.getTime());
+    const sinceMs = until.getTime() - current.days * 24 * 60 * 60 * 1000;
+    const since = new Date(sinceMs);
+    since.setHours(0, 0, 0, 0);
+    return { since, until, label: `prior ${current.label}`, days: current.days };
+}
+function parseRetroArgs(rawArgs, now) {
+    const args = [...rawArgs];
+    const postPlane = args.includes('--post-plane');
+    const enrichPlane = args.includes('--plane') || postPlane;
+    const positional = args.filter((a) => !a.startsWith('-'));
+    let compare = false;
+    let durationToken;
+    if (positional[0] === 'compare') {
+        compare = true;
+        durationToken = positional[1];
+    }
+    else {
+        durationToken = positional[0];
+    }
+    const parsed = parseDurationToken(durationToken) ?? { days: 7, label: '7d' };
+    return {
+        window: buildWindow(parsed.days, parsed.label, now),
+        compare,
+        enrichPlane,
+        postPlane,
+    };
+}
+function SummaryCard(props) {
+    const { persisted, metrics, plane, planePostUrl } = props;
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderRight: false, borderTop: false, borderBottom: false, paddingLeft: 1, children: [_jsxs(Text, { bold: true, children: ["pugi retro \u00B7 ", metrics.window.label] }), _jsxs(Text, { dimColor: true, children: ["Branch ", metrics.branch.current, " over ", metrics.branch.base] }), _jsxs(Text, { children: [metrics.commits.total, " commits \u00B7 +", metrics.loc.insertions, " / -", metrics.loc.deletions, " LOC \u00B7 ", metrics.activeDays, " active days"] }), _jsxs(Text, { children: ["Focus ", metrics.focus.score, "% on ", metrics.focus.topDir ?? 'n/a', " \u00B7 Streak ", metrics.streak.personalDays, "d personal / ", metrics.streak.teamDays, "d team"] }), metrics.shipOfTheWeek ? (_jsxs(Text, { children: ["Ship of the week: ", metrics.shipOfTheWeek.subject.slice(0, 60)] })) : null, plane ? (_jsxs(Text, { children: ["Plane: closed ", plane.closedIssues.length, " \u00B7 created ", plane.createdIssues.length, " \u00B7 oversized modules ", plane.oversizedModules.length] })) : null, _jsxs(Text, { dimColor: true, children: ["Markdown: ", persisted.markdownPath] }), _jsxs(Text, { dimColor: true, children: ["JSON:     ", persisted.jsonPath] }), planePostUrl ? _jsxs(Text, { children: ["Posted to Plane: ", planePostUrl] }) : null] }));
+}
+function renderSummary(props) {
+    const app = render(_jsx(SummaryCard, { ...props }));
+    app.unmount();
+}
+export async function runRetroCommand(ctx) {
+    const now = ctx.now ?? new Date();
+    const parsed = parseRetroArgs(ctx.args, now);
+    const gitCtx = await collectGitContext({ cwd: ctx.cwd, window: parsed.window });
+    if (!gitCtx.hasGit) {
+        const msg = 'pugi retro: not a git workspace - initialise git or cd into one.';
+        if (ctx.flags.json) {
+            ctx.io.write(`${JSON.stringify({ ok: false, error: 'no_git_workspace' })}\n`);
+        }
+        else {
+            ctx.io.writeError(msg);
+        }
+        return 2;
+    }
+    // Triple-review P1.2 (): before we write anything
+    // under `.pugi/retros/`, guarantee `.gitignore` covers `.pugi/`. Without
+    // this, the first customer run of `pugi retro` in a fresh repo would
+    // leave retros (and any future `.pugi/settings.json` secret store)
+    // tracked by git on the next `git add -A`. Idempotent.
+    //
+    // Round 2 P1 (2026-06-04): surface failure к stderr — silent catch
+    // defeats the gate's purpose. If `.gitignore` is read-only or perms
+    // refuse, the operator must know retros may be tracked by git.
+    const gitIgnoreCreated = [];
+    const gitIgnoreSkipped = [];
+    try {
+        ensurePugiGitIgnore(ctx.cwd, gitIgnoreCreated, gitIgnoreSkipped);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        ctx.io.writeError(`pugi retro: could not update .gitignore (${reason}). ` +
+            `Manually add ".pugi/" to .gitignore so retros are not tracked.`);
+    }
+    const toBaseHeadCount = await countCommitsAheadOfBase(ctx.cwd, gitCtx.baseBranch, parsed.window.since);
+    const metrics = computeMetrics({
+        window: parsed.window,
+        currentBranch: gitCtx.currentBranch,
+        baseBranch: gitCtx.baseBranch,
+        toBaseHeadCount,
+        currentUserName: gitCtx.userName,
+        currentUserEmail: gitCtx.userEmail,
+        commits: gitCtx.commits,
+    });
+    let compare;
+    if (parsed.compare) {
+        const priorWindow = buildPriorWindow(parsed.window);
+        const priorCtx = await collectGitContext({ cwd: ctx.cwd, window: priorWindow });
+        const priorAhead = await countCommitsAheadOfBase(ctx.cwd, gitCtx.baseBranch, priorWindow.since);
+        const priorMetrics = computeMetrics({
+            window: priorWindow,
+            currentBranch: gitCtx.currentBranch,
+            baseBranch: gitCtx.baseBranch,
+            toBaseHeadCount: priorAhead,
+            currentUserName: gitCtx.userName,
+            currentUserEmail: gitCtx.userEmail,
+            commits: priorCtx.commits,
+        });
+        compare = { current: metrics, prior: priorMetrics };
+    }
+    let plane;
+    let planeUnavailableReason;
+    if (parsed.enrichPlane) {
+        const cfgResult = resolvePlaneConfig(ctx.cwd);
+        if (!cfgResult.ok) {
+            planeUnavailableReason = cfgResult.reason;
+        }
+        else {
+            try {
+                const slice = await collectPlaneSlice({
+                    config: cfgResult.config,
+                    since: parsed.window.since,
+                });
+                const links = enrichLinks(gitCtx.commits, slice.closedIssues.concat(slice.createdIssues));
+                const health = computeHealthCard(slice.modules);
+                plane = {
+                    ...slice,
+                    prToIssueLinks: links,
+                    oversizedModules: health.oversized,
+                };
+            }
+            catch (err) {
+                planeUnavailableReason = err instanceof Error ? err.message : String(err);
+            }
+        }
+    }
+    const persisted = persistRetro({
+        root: ctx.cwd,
+        metrics,
+        plane,
+        compare,
+        now,
+    });
+    let planePostUrl;
+    if (parsed.postPlane) {
+        if (!plane) {
+            ctx.io.writeError(`pugi retro --post-plane: Plane unavailable (${planeUnavailableReason ?? 'unknown'}).`);
+        }
+        else {
+            const cfgResult = resolvePlaneConfig(ctx.cwd);
+            if (cfgResult.ok) {
+                try {
+                    const result = await postRetroToPlane({
+                        config: cfgResult.config,
+                        markdown: persisted.markdown,
+                        sequence: persisted.sequence,
+                        dateLabel: persisted.dateLabel,
+                    });
+                    planePostUrl = result.url;
+                    if (result.alreadyExists) {
+                        ctx.io.write(`pugi retro: already exists at ${result.url}\n`);
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.io.writeError(`pugi retro --post-plane failed: ${msg}`);
+                }
+            }
+        }
+    }
+    if (ctx.flags.json) {
+        ctx.io.write(`${JSON.stringify({
+            ok: true,
+            markdownPath: persisted.markdownPath,
+            jsonPath: persisted.jsonPath,
+            sequence: persisted.sequence,
+            metrics,
+            plane: plane ?? null,
+            planePostUrl: planePostUrl ?? null,
+            planeUnavailableReason: planeUnavailableReason ?? null,
+        }, null, 2)}\n`);
+    }
+    else {
+        renderSummary({ persisted, metrics, plane, planePostUrl });
+        if (planeUnavailableReason && !plane) {
+            ctx.io.writeError(`pugi retro: Plane integration unavailable (${planeUnavailableReason}).`);
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=retro.js.map

package/dist/commands/smoke.js

@@ -0,0 +1,133 @@
+/**
+ * `pugi smoke` — runs the bundled scenario corpus through the headless
+ * harness and reports pass/fail per scenario (
+ *).
+ *
+ * The CLI surface lives here rather than in `runtime/cli.ts` so the
+ * dispatch surface stays focused on argv routing. This module owns:
+ *
+ *  - Resolving the scenarios directory (default
+ *    `<cli-root>/test/scenarios/` when bundled, configurable via
+ *    `--scenarios-dir`).
+ *  - Selecting the `pugi` binary the headless driver should spawn.
+ *    Local development: `node <cli-root>/bin/run.js`. CI / published
+ *    usage: the `pugi` on PATH.
+ *  - Forwarding the orchestrator output to the unified
+ *    `writeOutput` writer so `--json` mode works without a second
+ *    code path.
+ *
+ * Phase 1 deliberately ships ONE flag (`--filter`) and one option
+ * (`--scenarios-dir`); the rest of the surface comes in Phase 2 once
+ * the engine path is wired and we know which scenarios actually need
+ * per-run plumbing (timeouts, fixture credentials, hermetic stubs).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runSmoke, renderReportText, } from '../core/smoke/orchestrator.js';
+import { runHeadlessScenario } from '../core/smoke/headless-driver.js';
+/**
+ * Entry point invoked by `runtime/cli.ts::dispatchSmoke`. Returns the
+ * desired process exit code so the dispatcher can set
+ * `process.exitCode` without a second round-trip.
+ */
+export async function runSmokeCommand(ctx) {
+    // Parse the (small) command-local argv. We only honor flags this
+    // command actually consumes; unknown args produce a usage error so
+    // typos surface immediately.
+    let scenariosDirOverride = ctx.scenariosDir ?? undefined;
+    let filter = ctx.filter ?? '';
+    for (let i = 0; i < ctx.args.length; i += 1) {
+        const arg = ctx.args[i] ?? '';
+        if (arg === '--filter') {
+            const next = ctx.args[i + 1];
+            if (!next || next.startsWith('--')) {
+                ctx.writeOutput({ ok: false, error: '--filter requires a pattern' }, 'pugi smoke: --filter requires a pattern (substring or *-glob)');
+                return 2;
+            }
+            filter = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--filter=')) {
+            filter = arg.slice('--filter='.length);
+        }
+        else if (arg === '--scenarios-dir') {
+            const next = ctx.args[i + 1];
+            if (!next || next.startsWith('--')) {
+                ctx.writeOutput({ ok: false, error: '--scenarios-dir requires a path' }, 'pugi smoke: --scenarios-dir requires a path');
+                return 2;
+            }
+            scenariosDirOverride = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--scenarios-dir=')) {
+            scenariosDirOverride = arg.slice('--scenarios-dir='.length);
+        }
+        else if (arg === '--help' || arg === '-h') {
+            ctx.writeOutput({
+                ok: true,
+                usage: 'pugi smoke [--filter <pattern>] [--scenarios-dir <path>]',
+            }, [
+                'pugi smoke — run the bundled scenario corpus headlessly.',
+                '',
+                'Flags:',
+                ' --filter <pattern>    Run a subset (substring or *-glob match on scenario id).',
+                ' --scenarios-dir <path> Override the scenarios directory (default: bundled corpus).',
+            ].join('\n'));
+            return 0;
+        }
+        else {
+            ctx.writeOutput({ ok: false, error: `unknown arg: ${arg}` }, `pugi smoke: unknown arg ${arg}`);
+            return 2;
+        }
+    }
+    const scenariosDir = scenariosDirOverride ?? resolveBundledScenariosDir();
+    if (!existsSync(scenariosDir)) {
+        ctx.writeOutput({ ok: false, error: `scenarios dir not found: ${scenariosDir}` }, `pugi smoke: scenarios dir not found: ${scenariosDir}`);
+        return 2;
+    }
+    const pugiBin = ctx.pugiBin ?? process.env.PUGI_SMOKE_BIN ?? 'pugi';
+    const log = ctx.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const report = await runSmoke({
+        scenariosDir,
+        filter,
+        executor: (scenario) => runHeadlessScenario(scenario, { pugiBin }),
+        log,
+    });
+    if (ctx.json) {
+        ctx.writeOutput(report, renderReportText(report));
+    }
+    else {
+        process.stdout.write(`${renderReportText(report)}\n`);
+    }
+    return report.exitCode;
+}
+/**
+ * Resolve the scenarios directory that ships alongside the CLI.
+ *
+ * Both the dev source layout (`<cli-root>/src/commands/smoke.ts`) and
+ * the built output layout (`<cli-root>/dist/commands/smoke.js`) land
+ * on the same `../../test/scenarios` path relative to this file.
+ * The bundled `npm i -g @pugi/cli` install replicates that structure
+ * by shipping `test/scenarios` (glob `**\/*.scenario.txt`) via the
+ * `package.json` `files` field — so the single resolved path works in
+ * dev, in `tsx` runs, and in published installs without a config knob.
+ *
+ * If a future restructure ever bundles scenarios at
+ * `<cli-root>/dist/scenarios/` instead, add that to the fallback chain
+ * here AND mirror the path in `package.json` `files`. Until then we
+ * keep the resolver intentionally one-line.
+ */
+export function resolveBundledScenariosDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Works for both src/commands/smoke.ts and dist/commands/smoke.js —
+    // both live two directories below the cli root.
+    const bundled = resolve(here, '..', '..', 'test', 'scenarios');
+    if (existsSync(bundled))
+        return bundled;
+    // Last resort: return the expected path so the orchestrator surfaces
+    // a clean "scenarios dir not found" diagnostic at the call site
+    // rather than the resolver swallowing it silently.
+    return bundled;
+}
+//# sourceMappingURL=smoke.js.map

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

@@ -0,0 +1,134 @@
+/**
+ * Agent-progress auto-cleanup — live progress .
+ *
+ * Rule: a progress file whose status === 'completed' OR 'failed' AND
+ * whose `lastUpdate` is older than COMPLETION_TTL_MS (default 5 min)
+ * gets MOVED into `<dir>/archive/<id>-<ts>.json` rather than deleted.
+ * Operators sometimes want to inspect a finished agent's last state;
+ * the archive keeps that affordance while preventing the live watcher
+ * from cluttering up with stale rows.
+ *
+ * The function is pure-ish:
+ *  - All clock reads go through the injected `now` (defaults Date.now).
+ *  - Returns a structured report so the caller (the watcher or a CLI
+ *    cron) can log what got swept.
+ *  - File-system errors degrade silently — the cleanup is best-effort
+ *    housekeeping, never a hot path.
+ *
+ * Hook-in point: `pugi jobs --watch` calls `runCleanup()` once per
+ * 60-second tick (cheap — readdir on a small directory). A separate
+ * cron entry can call it standalone via the (future) `pugi jobs
+ * gc` subcommand if the operator never runs --watch.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, } from 'node:fs';
+import { join } from 'node:path';
+import { validateAgentProgress, } from './schema.js';
+import { resolveProgressDir } from './writer.js';
+/** Default time a completed/failed entry sits before getting swept. */
+export const COMPLETION_TTL_MS = 5 * 60 * 1000;
+/** Archive subdirectory under the resolved progress dir. */
+export const ARCHIVE_SUBDIR = 'archive';
+/**
+ * Run a single cleanup pass. Returns the report for telemetry / tests.
+ */
+export function runCleanup(options = {}) {
+    const dir = resolveProgressDir(options.dir);
+    const ttl = options.ttlMs ?? COMPLETION_TTL_MS;
+    const now = options.now ?? Date.now;
+    const report = { dir, archived: [], skipped: [] };
+    if (!existsSync(dir))
+        return report;
+    const archiveDir = join(dir, ARCHIVE_SUBDIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        report.skipped.push({ path: dir, reason: `readdir failed: ${err.message}` });
+        return report;
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        if (/\.tmp-/.test(name))
+            continue;
+        const path = join(dir, name);
+        let body;
+        try {
+            body = readFileSync(path, 'utf8');
+        }
+        catch {
+            report.skipped.push({ path, reason: 'read failed' });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            report.skipped.push({ path, reason: 'malformed JSON' });
+            continue;
+        }
+        const validation = validateAgentProgress(parsed);
+        if (!validation.ok) {
+            report.skipped.push({ path, reason: `invalid: ${validation.error}` });
+            continue;
+        }
+        const progress = validation.value;
+        if (!isExpired(progress, now(), ttl)) {
+            continue;
+        }
+        if (!existsSync(archiveDir)) {
+            try {
+                mkdirSync(archiveDir, { recursive: true });
+            }
+            catch (err) {
+                report.skipped.push({
+                    path,
+                    reason: `archive mkdir failed: ${err.message}`,
+                });
+                continue;
+            }
+        }
+        const target = join(archiveDir, `${progress.agentId}-${safeStamp(progress.lastUpdate)}.json`);
+        try {
+            renameSync(path, target);
+            report.archived.push({ agentId: progress.agentId, from: path, to: target });
+        }
+        catch (err) {
+            report.skipped.push({ path, reason: `rename failed: ${err.message}` });
+        }
+    }
+    return report;
+}
+/**
+ * Decide whether a single progress doc has aged out. Exported for the
+ * spec — kept pure so tests can probe edges (running entries never
+ * expire, completed entries before TTL stay, etc).
+ */
+export function isExpired(progress, nowEpochMs, ttlMs = COMPLETION_TTL_MS) {
+    if (progress.status === 'running')
+        return false;
+    const lastTs = Date.parse(progress.lastUpdate);
+    if (Number.isNaN(lastTs))
+        return false;
+    return nowEpochMs - lastTs >= ttlMs;
+}
+// Claude review followup: `pruneArchive` was removed.
+// Rationale (P1 in the Claude review batch on PR):
+//  - hardcoded `/tmp` path was POSIX-only (Windows would break),
+//  - `renameSync` across volumes throws EXDEV,
+//  - collision risk between concurrent hosts/sessions sharing `/tmp`,
+//  - and crucially, the function had ZERO call-sites in the codebase.
+// Deleting it is strictly safer than leaving a broken-on-Windows
+// dead helper that future refactors might accidentally wire up.
+// If/when an archive GC is needed, the right shape is:
+//  - `os.tmpdir()` (not '/tmp'),
+//  - `rmSync(path, {force: true})` for cross-volume safe delete,
+//  - exposed as `pugi jobs gc` so we have an explicit caller.
+function safeStamp(iso) {
+    // Build a filename-safe slug — strip colons/dots which are friendly
+    // в ISO timestamps but hostile к some filesystems.
+    return iso.replace(/[:.]/g, '-');
+}
+//# sourceMappingURL=cleanup.js.map

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

@@ -0,0 +1,144 @@
+/**
+ * Agent progress JSON schema — live-progress sprint .
+ *
+ * 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 the upstream tool `/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