@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.6

package/dist/core/jobs/registry.js

@@ -0,0 +1,462 @@
+/**
+ * JobRegistry — Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J).
+ *
+ * First-class persistent registry for background bash jobs. Lifts the
+ * inline `~/.pugi/jobs.json` management from `src/tools/bash.ts` and
+ * extends it with:
+ *
+ *   - Atomic write (tempfile + rename) so concurrent CLI invocations
+ *     cannot corrupt the ledger (Code Reviewer P2 retro on PR #306).
+ *   - Stale-job reaping on every `list()` call: entries whose pid no
+ *     longer corresponds to a live process are marked `abandoned`.
+ *   - 24h retention for finished / killed / abandoned entries; older
+ *     records are dropped silently.
+ *   - Lifecycle status field (`running` / `finished` / `killed` /
+ *     `failed` / `abandoned`) so the `pugi jobs` CLI can render an
+ *     accurate snapshot regardless of which CLI invocation observed
+ *     the exit.
+ *
+ * Storage stays at `~/.pugi/jobs.json` as a JSON array (not JSONL) so
+ * α5.2 readers continue to work. The schema is additive: legacy
+ * entries lacking `id` / `status` / etc. are upgraded on read.
+ */
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Retention window for non-`running` entries. 24 hours mirrors the
+ * default session window in `core/session.ts`; older jobs are dropped
+ * to keep the ledger bounded.
+ */
+export const JOB_RETENTION_MS = 24 * 60 * 60 * 1000;
+/**
+ * Default grace period between SIGTERM and SIGKILL. Matches the bash
+ * tool's BASH_SIGKILL_GRACE_MS so foreground / background paths share
+ * the same shutdown contract.
+ */
+export const JOB_DEFAULT_GRACEFUL_MS = 5_000;
+const DEFAULT_JOBS_PATH = join(homedir(), '.pugi', 'jobs.json');
+/**
+ * Indirection point so tests can isolate the registry to a tmpdir
+ * without touching the user's real `~/.pugi/jobs.json`. The override
+ * lives at the module scope (single global) because the registry
+ * itself is a singleton — tests reset between cases with
+ * `resetJobRegistryForTesting`.
+ */
+let jobsPathOverride;
+let singleton;
+export function getJobRegistry() {
+    if (!singleton) {
+        singleton = new FileJobRegistry(resolveJobsPath());
+    }
+    return singleton;
+}
+/**
+ * Test-only hook. Resets the singleton so the next `getJobRegistry()`
+ * call binds to the (possibly overridden) jobs path again.
+ */
+export function resetJobRegistryForTesting(jobsPath) {
+    jobsPathOverride = jobsPath;
+    singleton = undefined;
+}
+function resolveJobsPath() {
+    return jobsPathOverride ?? DEFAULT_JOBS_PATH;
+}
+class FileJobRegistry {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async list() {
+        return this.listSync();
+    }
+    listSync() {
+        const entries = this.readAll();
+        const reaped = this.reapInMemory(entries);
+        const pruned = this.pruneOld(reaped);
+        if (mutated(entries, pruned)) {
+            this.writeAll(pruned);
+        }
+        return pruned;
+    }
+    async get(id) {
+        const entries = await this.list();
+        return entries.find((entry) => entry.id === id);
+    }
+    async add(input) {
+        const entry = {
+            ...input,
+            startedAt: new Date().toISOString(),
+            status: 'running',
+        };
+        const entries = this.readAll();
+        entries.push(entry);
+        this.writeAll(entries);
+        return entry;
+    }
+    async kill(id, opts = {}) {
+        const entries = this.readAll();
+        const target = entries.find((entry) => entry.id === id);
+        if (!target) {
+            return { killed: false, method: 'noop' };
+        }
+        if (target.status !== 'running') {
+            return { killed: false, method: 'noop' };
+        }
+        const grace = opts.gracefulMs ?? JOB_DEFAULT_GRACEFUL_MS;
+        if (!processAlive(target.pid)) {
+            this.markStatus(id, 'abandoned');
+            return { killed: false, method: 'noop' };
+        }
+        try {
+            process.kill(target.pid, 'SIGTERM');
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ESRCH') {
+                this.markStatus(id, 'abandoned');
+                return { killed: false, method: 'noop' };
+            }
+            return { killed: false, method: 'noop' };
+        }
+        const sigtermSettled = await waitForExit(target.pid, Math.min(grace, 1_500));
+        if (sigtermSettled) {
+            this.markStatus(id, 'killed');
+            return { killed: true, method: 'SIGTERM' };
+        }
+        try {
+            process.kill(target.pid, 'SIGKILL');
+        }
+        catch {
+            // already gone between the check and the signal
+        }
+        await waitForExit(target.pid, 500);
+        this.markStatus(id, 'killed');
+        return { killed: true, method: 'SIGKILL' };
+    }
+    async markFinished(id, exitCode) {
+        const entries = this.readAll();
+        const next = entries.map((entry) => entry.id === id
+            ? {
+                ...entry,
+                status: (exitCode === 0 ? 'finished' : 'failed'),
+                exitCode,
+                finishedAt: new Date().toISOString(),
+            }
+            : entry);
+        this.writeAll(next);
+    }
+    async reapStale() {
+        const entries = this.readAll();
+        const abandoned = [];
+        const next = entries.map((entry) => {
+            if (entry.status !== 'running')
+                return entry;
+            if (processAlive(entry.pid))
+                return entry;
+            abandoned.push(entry.id);
+            return {
+                ...entry,
+                status: 'abandoned',
+                finishedAt: new Date().toISOString(),
+            };
+        });
+        if (abandoned.length > 0) {
+            this.writeAll(next);
+        }
+        return { abandoned };
+    }
+    markStatus(id, status) {
+        const entries = this.readAll();
+        const next = entries.map((entry) => entry.id === id
+            ? {
+                ...entry,
+                status,
+                finishedAt: entry.finishedAt ?? new Date().toISOString(),
+            }
+            : entry);
+        this.writeAll(next);
+    }
+    readAll() {
+        if (!existsSync(this.path))
+            return [];
+        try {
+            const raw = readFileSync(this.path, 'utf8');
+            if (raw.trim() === '')
+                return [];
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed
+                .map(normalizeEntry)
+                .filter((entry) => entry !== undefined);
+        }
+        catch {
+            return [];
+        }
+    }
+    writeAll(entries) {
+        const dir = dirname(this.path);
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            // ignore — the open() below surfaces the failure
+        }
+        // Atomic write: write to a sibling temp file, fsync, then rename
+        // onto the target. Rename is atomic on POSIX so concurrent
+        // readers either see the previous file or the new file, never a
+        // half-written buffer.
+        const tempPath = `${this.path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+        const body = `${JSON.stringify(entries, null, 2)}\n`;
+        let fd;
+        try {
+            fd = openSync(tempPath, 'w', 0o600);
+            writeSync(fd, body);
+            fsyncSync(fd);
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        }
+        try {
+            renameSync(tempPath, this.path);
+        }
+        catch (error) {
+            // Cleanup the temp file if rename failed for any reason.
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // best-effort
+            }
+            throw error;
+        }
+    }
+    reapInMemory(entries) {
+        return entries.map((entry) => {
+            if (entry.status !== 'running')
+                return entry;
+            if (processAlive(entry.pid))
+                return entry;
+            return {
+                ...entry,
+                status: 'abandoned',
+                finishedAt: entry.finishedAt ?? new Date().toISOString(),
+            };
+        });
+    }
+    pruneOld(entries) {
+        const cutoff = Date.now() - JOB_RETENTION_MS;
+        return entries.filter((entry) => {
+            if (entry.status === 'running')
+                return true;
+            const stamp = entry.finishedAt ?? entry.startedAt;
+            const parsed = Date.parse(stamp);
+            if (Number.isNaN(parsed))
+                return true;
+            return parsed >= cutoff;
+        });
+    }
+}
+/**
+ * Normalize legacy `~/.pugi/jobs.json` entries (Sprint α5.2 shape with
+ * `jobId` / `class` / no status) into the JobEntry shape used here.
+ * Returns undefined for entries that cannot be migrated so the loop
+ * silently skips garbage.
+ */
+function normalizeEntry(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return undefined;
+    const c = candidate;
+    const id = typeof c['id'] === 'string'
+        ? c['id']
+        : typeof c['jobId'] === 'string'
+            ? c['jobId']
+            : undefined;
+    if (!id)
+        return undefined;
+    const pid = typeof c['pid'] === 'number' ? c['pid'] : undefined;
+    if (pid === undefined)
+        return undefined;
+    const command = typeof c['command'] === 'string'
+        ? c['command']
+        : typeof c['cmd'] === 'string'
+            ? c['cmd']
+            : undefined;
+    if (command === undefined)
+        return undefined;
+    const bashClassRaw = typeof c['bashClass'] === 'string'
+        ? c['bashClass']
+        : typeof c['class'] === 'string'
+            ? c['class']
+            : 'unknown';
+    const bashClass = bashClassRaw;
+    const cwd = typeof c['cwd'] === 'string' ? c['cwd'] : '';
+    const startedAt = typeof c['startedAt'] === 'string'
+        ? c['startedAt']
+        : new Date().toISOString();
+    const sessionId = typeof c['sessionId'] === 'string' ? c['sessionId'] : 'unknown';
+    const status = c['status'] === 'finished' ||
+        c['status'] === 'killed' ||
+        c['status'] === 'failed' ||
+        c['status'] === 'abandoned'
+        ? c['status']
+        : 'running';
+    const exitCode = typeof c['exitCode'] === 'number' ? c['exitCode'] : undefined;
+    const finishedAt = typeof c['finishedAt'] === 'string' ? c['finishedAt'] : undefined;
+    const outputArtifactRef = typeof c['outputArtifactRef'] === 'string'
+        ? c['outputArtifactRef']
+        : undefined;
+    return {
+        id,
+        pid,
+        command,
+        bashClass,
+        cwd,
+        startedAt,
+        finishedAt,
+        status,
+        exitCode,
+        sessionId,
+        outputArtifactRef,
+    };
+}
+function processAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        // EPERM means the process exists but we cannot signal it — still alive.
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return !processAlive(pid);
+}
+function mutated(before, after) {
+    if (before.length !== after.length)
+        return true;
+    for (let i = 0; i < before.length; i++) {
+        const a = before[i];
+        const b = after[i];
+        if (!a || !b)
+            return true;
+        if (a.id !== b.id)
+            return true;
+        if (a.status !== b.status)
+            return true;
+        if (a.exitCode !== b.exitCode)
+            return true;
+        if (a.finishedAt !== b.finishedAt)
+            return true;
+    }
+    return false;
+}
+/**
+ * Format a compact one-line summary for the engine prompt snapshot.
+ * Public so the prompts module can pre-format without re-implementing
+ * the rendering rules.
+ */
+export function summarizeJobsForPrompt(entries) {
+    if (entries.length === 0) {
+        return 'BACKGROUND JOBS: none on watch.';
+    }
+    const running = entries.filter((entry) => entry.status === 'running');
+    const finished = entries
+        .filter((entry) => entry.status !== 'running')
+        .slice(-5);
+    const lines = ['BACKGROUND JOBS:'];
+    if (running.length === 0) {
+        lines.push('  - Running: 0');
+    }
+    else {
+        const oldest = running.reduce((min, entry) => {
+            return Date.parse(entry.startedAt) < Date.parse(min.startedAt)
+                ? entry
+                : min;
+        }, running[0]);
+        lines.push(`  - Running: ${running.length} (oldest started ${relativeAge(oldest.startedAt)} ago)`);
+        const counts = new Map();
+        for (const entry of running) {
+            counts.set(entry.bashClass, (counts.get(entry.bashClass) ?? 0) + 1);
+        }
+        const classSummary = [...counts.entries()]
+            .map(([cls, count]) => `${cls} (${count})`)
+            .join(', ');
+        lines.push(`  - Classes in flight: ${classSummary}`);
+    }
+    if (finished.length > 0) {
+        const compact = finished
+            .map((entry) => `${entry.id.slice(0, 8)} ${entry.status}${entry.exitCode !== undefined ? ` exit=${entry.exitCode}` : ''}`)
+            .join('; ');
+        lines.push(`  - Recent finished (last ${finished.length}): ${compact}`);
+    }
+    lines.push('  Use `pugi jobs tail <id>` to inspect output. Do not spawn another long-running background job while 3+ are already on watch.');
+    return lines.join('\n');
+}
+/**
+ * Renders an ISO timestamp as a compact relative age (`2m`, `1h 14m`,
+ * `3d`). Used by the engine prompt snapshot and the `pugi jobs list`
+ * table rendering.
+ */
+export function relativeAge(iso) {
+    const ms = Math.max(0, Date.now() - Date.parse(iso));
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const remMinutes = minutes - hours * 60;
+    if (hours < 24) {
+        return remMinutes === 0 ? `${hours}h` : `${hours}h ${remMinutes}m`;
+    }
+    const days = Math.floor(hours / 24);
+    const remHours = hours - days * 24;
+    return remHours === 0 ? `${days}d` : `${days}d ${remHours}h`;
+}
+/**
+ * Renders a finished-duration in the same units as `relativeAge` but
+ * computed from a startedAt + finishedAt pair. Falls back to `?` when
+ * the timestamps cannot be parsed.
+ */
+export function formatDuration(startedAt, finishedAt) {
+    const start = Date.parse(startedAt);
+    const end = finishedAt ? Date.parse(finishedAt) : Date.now();
+    if (Number.isNaN(start) || Number.isNaN(end) || end < start)
+        return '?';
+    const ms = end - start;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remSeconds = seconds - minutes * 60;
+    if (minutes < 60) {
+        return remSeconds === 0 ? `${minutes}m` : `${minutes}m ${remSeconds}s`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remMinutes = minutes - hours * 60;
+    return remMinutes === 0 ? `${hours}h` : `${hours}h ${remMinutes}m`;
+}
+//# sourceMappingURL=registry.js.map