@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/skills/bundled/stuck.js

@@ -0,0 +1,558 @@
+/**
+ * `pugi stuck` — non-invasive self-diagnosis for a Pugi process that
+ * appears wedged. Bundled skill, batch 1 (backlog, inspired by
+ * the upstream tool's bundled-skills pattern surfaced in leak intel).
+ *
+ * # What this does (and does not)
+ *
+ * The operator runs `pugi stuck` when the foreground Pugi seems frozen
+ * (engine spinner, REPL silent, edit hangs). The skill walks the
+ * process tree once, gathers vitals on every peer Pugi process, flags
+ * the ones that match a fault heuristic, optionally dumps a kernel
+ * stack via `sample(1)` on macOS, and posts the redacted snapshot to a
+ * feedback webhook if one is configured.
+ *
+ * **It NEVER signals, kills, or otherwise mutates a process.** The
+ * exit code is purely informational: a non-zero return means "at least
+ * one peer looked suspicious, here is what we saw". The operator
+ * decides what to do — kill, attach a debugger, file a bug, wait.
+ *
+ * # Fault heuristic (peer is suspect when ANY holds)
+ *
+ *  - sustained CPU >= CPU_THRESHOLD across the snapshot window
+ *  - resident set size (RSS) >= RSS_THRESHOLD_MB
+ *  - process state is `D` (uninterruptible I/O wait)
+ *  - process state is `T` (stopped, e.g. Ctrl+Z)
+ *  - process state is `Z` (zombie / exited but unreaped)
+ *
+ * # Output
+ *
+ * Human-readable table by default; machine-readable JSON envelope when
+ * `--json` is set. Both surfaces describe the same payload. The JSON
+ * envelope is the source of truth for the feedback webhook.
+ *
+ * # Provenance
+ *
+ * Inspired by the the upstream tool bundled-skills pattern (intel from
+ * leak-research memos, clean-room TS). No upstream code reused.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * CPU usage (percent) at which a peer Pugi is flagged. Single-core
+ * tight loops sit at ~100%; the threshold trips well before that to
+ * surface near-pegged processes. Operator-overridable via flag.
+ */
+const DEFAULT_CPU_THRESHOLD = 85;
+/**
+ * Resident set size (MB) at which a peer Pugi is flagged. Engine + REPL
+ * + Ink should stay well under 1 GB in normal operation. 4 GB indicates
+ * a runaway model context or a leaking subagent.
+ */
+const DEFAULT_RSS_THRESHOLD_MB = 4096;
+/**
+ * Process states that are inherently suspicious regardless of CPU / RSS.
+ *  D — uninterruptible sleep (often disk / network hang)
+ *  T — stopped (Ctrl+Z, debugger detached without continue)
+ *  Z — zombie (exit not reaped, parent leaking)
+ */
+const STUCK_STATES = new Set(['D', 'T', 'Z']);
+function parseFlags(args) {
+    const flags = {
+        json: false,
+        cpuThreshold: DEFAULT_CPU_THRESHOLD,
+        rssThresholdMb: DEFAULT_RSS_THRESHOLD_MB,
+        sampleStack: true,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (arg === '--no-sample') {
+            flags.sampleStack = false;
+            continue;
+        }
+        if (arg === '--cpu') {
+            const next = args[i + 1];
+            if (next === undefined)
+                return { flags, error: '--cpu requires a value' };
+            const parsed = Number.parseFloat(next);
+            if (!Number.isFinite(parsed) || parsed < 0 || parsed > 100) {
+                return { flags, error: '--cpu must be a number 0..100' };
+            }
+            flags.cpuThreshold = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg === '--rss') {
+            const next = args[i + 1];
+            if (next === undefined)
+                return { flags, error: '--rss requires a value' };
+            const parsed = Number.parseInt(next, 10);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                return { flags, error: '--rss must be a positive integer (MB)' };
+            }
+            flags.rssThresholdMb = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            return { flags, error: 'help' };
+        }
+        return { flags, error: `unknown argument: ${arg}` };
+    }
+    return { flags, error: null };
+}
+/**
+ * One row out of `ps -axo pid=,ppid=,%cpu=,rss=,state=,command=`. Parsed
+ * defensively because BSD ps and GNU ps disagree on whitespace + the
+ * trailing command can contain spaces (we slurp the remainder into the
+ * `command` field rather than splitting on spaces blindly).
+ */
+function parsePsLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    const head = trimmed.split(/\s+/, 5);
+    if (head.length < 5)
+        return null;
+    const [pidStr, ppidStr, cpuStr, rssStr, stateRaw] = head;
+    if (pidStr === undefined ||
+        ppidStr === undefined ||
+        cpuStr === undefined ||
+        rssStr === undefined ||
+        stateRaw === undefined) {
+        return null;
+    }
+    const pid = Number.parseInt(pidStr, 10);
+    const parentPid = Number.parseInt(ppidStr, 10);
+    const cpuPercent = Number.parseFloat(cpuStr);
+    const rssKb = Number.parseInt(rssStr, 10);
+    if (!Number.isFinite(pid) ||
+        !Number.isFinite(parentPid) ||
+        !Number.isFinite(cpuPercent) ||
+        !Number.isFinite(rssKb)) {
+        return null;
+    }
+    // Re-walk the line to recover the command tail without losing
+    // embedded spaces. We skip the 5 leading whitespace-delimited fields.
+    let cursor = 0;
+    for (let field = 0; field < 5; field += 1) {
+        // skip any leading whitespace
+        while (cursor < trimmed.length && /\s/.test(trimmed.charAt(cursor)))
+            cursor += 1;
+        // skip the field itself
+        while (cursor < trimmed.length && !/\s/.test(trimmed.charAt(cursor)))
+            cursor += 1;
+    }
+    const command = trimmed.slice(cursor).trim();
+    // First character of the BSD `state` field is the canonical state
+    // (e.g. `S+`, `R<`, `D+`). Normalise to single letter.
+    const state = stateRaw.charAt(0) || '?';
+    return { pid, parentPid, cpuPercent, rssKb, state, command };
+}
+/**
+ * Snapshot the whole process table once via `ps -axo`. Pure read, no
+ * mutation. Returns an empty list if `ps` is unavailable (extremely
+ * locked-down container) — the caller surfaces an empty snapshot
+ * rather than crashing.
+ */
+export function readProcessTable() {
+    try {
+        const stdout = execFileSync('ps', ['-axo', 'pid=,ppid=,%cpu=,rss=,state=,command='], {
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+            // 5 s is plenty even on a loaded host; we never want `pugi
+            // stuck` itself to wedge waiting for ps.
+            timeout: 5000,
+        });
+        const rows = [];
+        for (const line of stdout.split('\n')) {
+            const parsed = parsePsLine(line);
+            if (parsed !== null)
+                rows.push(parsed);
+        }
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Identify peer Pugi processes. A row is a "peer" when its command
+ * line looks like a `pugi` invocation — node + pugi entrypoint, or the
+ * bin shim, or a tsx-driven dev run. The current process is excluded
+ * so `pugi stuck` does not diagnose itself.
+ */
+function isPugiPeer(row, selfPid) {
+    if (row.pid === selfPid)
+        return false;
+    const cmd = row.command.toLowerCase();
+    // The bin shim path: `…/.npm/_npx/…/bin/pugi` or `node …/bin/pugi`.
+    if (/\bpugi\b/.test(cmd) && /(\bnode\b|\bbin\/pugi\b|\.npm\/|\.pnpm\/|tsx\b)/.test(cmd)) {
+        return true;
+    }
+    // Direct invocation of the compiled bundle inside dist/.
+    if (/pugi-cli\/(dist|bin)\//.test(cmd))
+        return true;
+    return false;
+}
+/**
+ * Walk the ps table and collect every Pugi peer with the heuristic
+ * verdict attached. We deliberately keep the verdict logic outside of
+ * any side-effects so tests can exercise the boundary by feeding a
+ * synthetic ps table.
+ */
+export function classifyPeers(rows, selfPid, thresholds) {
+    const peers = [];
+    for (const row of rows) {
+        if (!isPugiPeer(row, selfPid))
+            continue;
+        const rssMb = Math.round(row.rssKb / 1024);
+        const reasons = [];
+        if (row.cpuPercent >= thresholds.cpuPercent) {
+            reasons.push(`cpu ${row.cpuPercent.toFixed(1)}% >= ${thresholds.cpuPercent}%`);
+        }
+        if (rssMb >= thresholds.rssMb) {
+            reasons.push(`rss ${rssMb} MB >= ${thresholds.rssMb} MB`);
+        }
+        if (STUCK_STATES.has(row.state)) {
+            reasons.push(`state ${row.state} (${describeState(row.state)})`);
+        }
+        peers.push({
+            pid: row.pid,
+            parentPid: row.parentPid,
+            cpuPercent: row.cpuPercent,
+            rssMb,
+            state: row.state,
+            command: row.command,
+            suspect: reasons.length > 0,
+            reasons,
+        });
+    }
+    return peers;
+}
+function describeState(letter) {
+    switch (letter) {
+        case 'D':
+            return 'uninterruptible I/O wait';
+        case 'T':
+            return 'stopped';
+        case 'Z':
+            return 'zombie';
+        case 'R':
+            return 'runnable';
+        case 'S':
+            return 'sleeping';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Walk the ps table for child processes of a peer Pugi (git, node,
+ * shell helpers). A child is flagged when it is in a suspicious state
+ * OR pegged on CPU. Children are not subject to the RSS threshold
+ * because git/sh legitimately stay tiny.
+ */
+export function classifyChildren(rows, peerPids, thresholds) {
+    const peerSet = new Set(peerPids);
+    const out = [];
+    for (const row of rows) {
+        if (!peerSet.has(row.parentPid))
+            continue;
+        const suspicious = STUCK_STATES.has(row.state) || row.cpuPercent >= thresholds.cpuPercent;
+        if (!suspicious)
+            continue;
+        out.push({
+            pid: row.pid,
+            parentPid: row.parentPid,
+            state: row.state,
+            command: row.command,
+            cpuPercent: row.cpuPercent,
+        });
+    }
+    return out;
+}
+/**
+ * Read the tail of `~/.pugi/debug/` log files, if any. The directory
+ * is optional — most operators do not have debug logging enabled.
+ * We sort newest-first by mtime and slurp the last few lines of the
+ * top file so the snapshot carries enough context without dragging in
+ * megabytes of history.
+ */
+export function readDebugTail(home, maxLines = 25) {
+    const dir = join(home, '.pugi', 'debug');
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir)
+            .map((name) => ({ path: join(dir, name), mtimeMs: 0 }))
+            .map((entry) => {
+            try {
+                const st = statSync(entry.path);
+                return { path: entry.path, mtimeMs: st.mtimeMs };
+            }
+            catch {
+                return entry;
+            }
+        })
+            .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    }
+    catch {
+        return [];
+    }
+    const top = entries[0];
+    if (top === undefined)
+        return [];
+    try {
+        const raw = readFileSync(top.path, 'utf8');
+        const lines = raw.split('\n').filter((l) => l !== '');
+        return lines.slice(Math.max(0, lines.length - maxLines));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Capture a 1-second `sample <pid>` stack dump on macOS. Returns the
+ * raw textual output (already truncated by sample itself to a
+ * reasonable size). Returns null on any failure — sample is best-effort
+ * diagnostic, never blocking.
+ */
+export function captureSampleStack(pid) {
+    if (platform() !== 'darwin')
+        return null;
+    try {
+        const result = spawnSync('sample', [String(pid), '1'], {
+            encoding: 'utf8',
+            timeout: 5000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        if (result.status !== 0)
+            return null;
+        return result.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Post the snapshot JSON to a feedback webhook. The webhook is
+ * configured via `PUGI_FEEDBACK_WEBHOOK` env var; if absent we record
+ * `not-configured` and skip. We deliberately use a short fetch timeout
+ * because `pugi stuck` is run when the operator already suspects
+ * something is wrong — blocking on a slow webhook defeats the purpose.
+ */
+/**
+ * Webhook URL validation guard — P1 fix from triple-review PR.
+ *
+ * `PUGI_FEEDBACK_WEBHOOK` is operator-set, but a malicious shell-rc
+ * injection could redirect snapshot payloads to an attacker URL —
+ * SSRF + exfiltration of process telemetry (peer command-lines,
+ * debug-log tail, sample stack with symbols/paths). Enforce:
+ *  1. HTTPS only — reject http/file/data/javascript/etc.
+ *  2. No private/loopback hostnames — reject localhost, 127.x,
+ *     10.x, 172.16-31.x, 192.168.x, *.local, link-local.
+ * Returns null when URL is invalid OR safe-to-use otherwise.
+ */
+function validateWebhookUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'https:')
+        return null;
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'localhost' ||
+        host === '0.0.0.0' ||
+        host.endsWith('.local') ||
+        host.startsWith('127.') ||
+        host.startsWith('10.') ||
+        host.startsWith('192.168.') ||
+        /^172\.(1[6-9]|2[0-9]|3[01])\./.test(host) ||
+        /^169\.254\./.test(host) // link-local
+    ) {
+        return null;
+    }
+    return parsed;
+}
+export async function postSnapshotToWebhook(snapshot, url) {
+    if (!url || url.trim() === '')
+        return 'not-configured';
+    const safe = validateWebhookUrl(url.trim());
+    if (!safe)
+        return 'invalid-url';
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        try {
+            const response = await fetch(safe.toString(), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ kind: 'pugi-stuck', snapshot }),
+                signal: controller.signal,
+            });
+            return response.ok ? 'ok' : 'failed';
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        return 'failed';
+    }
+}
+function renderHumanReport(snapshot) {
+    const lines = [];
+    lines.push(`pugi stuck — diagnostic snapshot @ ${snapshot.capturedAt}`);
+    lines.push(`platform: ${snapshot.platform} selfPid: ${snapshot.selfPid}`);
+    lines.push(`thresholds: cpu>=${snapshot.thresholds.cpuPercent}% rss>=${snapshot.thresholds.rssMb} MB`);
+    lines.push('');
+    if (snapshot.peers.length === 0) {
+        lines.push('No peer Pugi processes detected.');
+    }
+    else {
+        lines.push(`Peer Pugi processes (${snapshot.peers.length}):`);
+        for (const peer of snapshot.peers) {
+            const tag = peer.suspect ? '[SUSPECT]' : '[ok]';
+            lines.push(` ${tag} pid=${peer.pid} ppid=${peer.parentPid} cpu=${peer.cpuPercent.toFixed(1)}% rss=${peer.rssMb}MB state=${peer.state}`);
+            lines.push(`          ${peer.command}`);
+            for (const reason of peer.reasons) {
+                lines.push(`          reason: ${reason}`);
+            }
+        }
+    }
+    if (snapshot.suspectChildren.length > 0) {
+        lines.push('');
+        lines.push(`Suspect child processes (${snapshot.suspectChildren.length}):`);
+        for (const child of snapshot.suspectChildren) {
+            lines.push(` pid=${child.pid} ppid=${child.parentPid} cpu=${child.cpuPercent.toFixed(1)}% state=${child.state}`);
+            lines.push(`          ${child.command}`);
+        }
+    }
+    if (snapshot.debugLogTail.length > 0) {
+        lines.push('');
+        lines.push(`Tail of ~/.pugi/debug/ (${snapshot.debugLogTail.length} lines):`);
+        for (const line of snapshot.debugLogTail)
+            lines.push(` ${line}`);
+    }
+    if (snapshot.sampleDump !== null) {
+        lines.push('');
+        lines.push('sample(1) stack (truncated):');
+        const dumpLines = snapshot.sampleDump.split('\n').slice(0, 40);
+        for (const line of dumpLines)
+            lines.push(` ${line}`);
+    }
+    lines.push('');
+    lines.push(`webhook: ${snapshot.webhookPosted}`);
+    lines.push('');
+    lines.push('Diagnostic only — no process was signalled or killed.');
+    return lines.join('\n');
+}
+/**
+ * Public entrypoint. The CLI dispatcher wraps this. Pure async function
+ * + injected `writeOutput` so tests can capture both surfaces without
+ * touching stdout.
+ */
+export async function runStuckCommand(args, ctx) {
+    const { flags, error } = parseFlags(args);
+    if (error === 'help') {
+        ctx.writeOutput({ ok: true, command: 'stuck', usage: STUCK_USAGE }, STUCK_USAGE);
+        return { snapshot: emptySnapshot(ctx), exitCode: 0 };
+    }
+    if (error !== null) {
+        ctx.writeOutput({ ok: false, command: 'stuck', error }, `pugi stuck: ${error}`);
+        return { exitCode: 2 };
+    }
+    const home = ctx.env.PUGI_HOME ?? homedir();
+    const rows = readProcessTable();
+    const peers = classifyPeers(rows, process.pid, {
+        cpuPercent: flags.cpuThreshold,
+        rssMb: flags.rssThresholdMb,
+    });
+    const peerPids = peers.map((p) => p.pid);
+    const suspectChildren = classifyChildren(rows, peerPids, {
+        cpuPercent: flags.cpuThreshold,
+    });
+    const debugLogTail = readDebugTail(home);
+    const mostSuspect = peers
+        .filter((p) => p.suspect)
+        .sort((a, b) => b.cpuPercent - a.cpuPercent)[0];
+    const sampleDump = flags.sampleStack && mostSuspect !== undefined
+        ? captureSampleStack(mostSuspect.pid)
+        : null;
+    const draftSnapshot = {
+        capturedAt: ctx.now().toISOString(),
+        platform: platform(),
+        selfPid: process.pid,
+        thresholds: {
+            cpuPercent: flags.cpuThreshold,
+            rssMb: flags.rssThresholdMb,
+        },
+        peers,
+        suspectChildren,
+        debugLogTail,
+        sampleDump,
+        webhookPosted: 'skipped',
+    };
+    const webhookUrl = ctx.env.PUGI_FEEDBACK_WEBHOOK;
+    const webhookPosted = await postSnapshotToWebhook(draftSnapshot, webhookUrl);
+    const snapshot = { ...draftSnapshot, webhookPosted };
+    const human = renderHumanReport(snapshot);
+    ctx.writeOutput({ ok: true, command: 'stuck', snapshot }, human);
+    const anySuspect = snapshot.peers.some((p) => p.suspect) || snapshot.suspectChildren.length > 0;
+    return { snapshot, exitCode: anySuspect ? 1 : 0 };
+}
+function emptySnapshot(ctx) {
+    return {
+        capturedAt: ctx.now().toISOString(),
+        platform: platform(),
+        selfPid: process.pid,
+        thresholds: {
+            cpuPercent: DEFAULT_CPU_THRESHOLD,
+            rssMb: DEFAULT_RSS_THRESHOLD_MB,
+        },
+        peers: [],
+        suspectChildren: [],
+        debugLogTail: [],
+        sampleDump: null,
+        webhookPosted: 'skipped',
+    };
+}
+const STUCK_USAGE = [
+    'pugi stuck — non-invasive self-diagnosis for a wedged Pugi process.',
+    '',
+    'Usage:',
+    ' pugi stuck [--json] [--cpu <pct>] [--rss <mb>] [--no-sample]',
+    '',
+    'Flags:',
+    ' --json            Emit a JSON envelope instead of human text.',
+    ' --cpu <pct>       CPU % at which a peer is flagged (default 85).',
+    ' --rss <mb>        RSS MB at which a peer is flagged (default 4096).',
+    ' --no-sample       Skip the macOS sample(1) stack dump.',
+    '',
+    'Env:',
+    ' PUGI_FEEDBACK_WEBHOOK POST snapshot JSON to this URL (best-effort).',
+    ' PUGI_HOME             Override the ~/.pugi/debug log root.',
+    '',
+    'Diagnostic only — NEVER signals or kills any process.',
+].join('\n');
+/**
+ * Public helper for tests + the dispatcher: assert the textual `resolve`
+ * import is still in the module graph so node resolution does not strip
+ * the side-effect-free path import. Some bundlers tree-shake otherwise.
+ */
+export function __debugResolveSelfPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi', 'debug');
+}
+//# sourceMappingURL=stuck.js.map