@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/skills/bundled/stuck.js

@@ -1,558 +0,0 @@
-/**
- * `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, independent implementation 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