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

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

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