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

package/dist/commands/flatten.js

@@ -0,0 +1,191 @@
+/**
+ * `pugi flatten` — CLI surface for the rendergit-port flatten engine.
+ *
+ * The runner lives here (not in `runtime/cli.ts`) so the dispatch
+ * surface stays focused on argv routing. This module owns:
+ *
+ *  - Parsing the command-local flags (`--mode`, `--max-file-size`,
+ *    `--include`, `--exclude`, `--stdout`, `--open`, `--out`).
+ *  - Routing to `flattenRepo` with a resolved option bag.
+ *  - Forwarding the rendered text + summary through the unified
+ *    `writeOutput` writer so `--json` mode works without a second
+ *    code path.
+ *
+ * Ported from karpathy/rendergit (BSD-0). License compatible with
+ * Pugi's open-source posture.
+ */
+import { resolve } from 'node:path';
+import { DEFAULT_MAX_FILE_SIZE, flattenRepo, } from '../core/flatten/flatten-repo.js';
+/**
+ * Entry point invoked by `runtime/cli.ts::dispatchFlatten`. Returns
+ * the desired process exit code so the dispatcher can set
+ * `process.exitCode` without a second round-trip.
+ */
+export async function runFlattenCommand(ctx) {
+    const parsed = parseArgs(ctx.args);
+    if ('error' in parsed) {
+        ctx.writeOutput({ ok: false, error: parsed.error }, `pugi flatten: ${parsed.error}`);
+        return 2;
+    }
+    const options = {
+        cwd: parsed.cwd,
+        mode: parsed.mode,
+        stdout: parsed.stdout,
+        maxFileSize: parsed.maxFileSize,
+        include: parsed.include,
+        exclude: parsed.exclude,
+        open: parsed.open,
+    };
+    try {
+        const result = await flattenRepo(options);
+        if (parsed.stdout) {
+            // Always emit the rendered text to stdout. JSON mode wraps it
+            // in an envelope so scripted callers can demux the result from
+            // the summary line.
+            if (ctx.json) {
+                ctx.writeOutput({
+                    ok: true,
+                    mode: parsed.mode,
+                    files: result.files.length,
+                    skipped: result.skipped.length,
+                    html: result.html,
+                }, result.html);
+            }
+            else {
+                process.stdout.write(result.html);
+            }
+            return 0;
+        }
+        const summary = `pugi flatten: wrote ${result.files.length} files (${result.skipped.length} skipped) to ${result.path ?? '<unknown>'}`;
+        ctx.writeOutput({
+            ok: true,
+            mode: parsed.mode,
+            path: result.path,
+            files: result.files.length,
+            skipped: result.skipped.length,
+        }, summary);
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ ok: false, error: msg }, `pugi flatten: ${msg}`);
+        return 1;
+    }
+}
+function parseArgs(args) {
+    let cwd = process.cwd();
+    let mode = 'human';
+    let stdout = false;
+    let open = false;
+    let maxFileSize = DEFAULT_MAX_FILE_SIZE;
+    const include = [];
+    const exclude = [];
+    let positionalConsumed = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--stdout') {
+            stdout = true;
+            continue;
+        }
+        if (arg === '--open') {
+            open = true;
+            continue;
+        }
+        if (arg === '--mode') {
+            const next = args[i + 1];
+            if (!next)
+                return { error: '--mode requires a value (human | llm)' };
+            const m = parseMode(next);
+            if (!m)
+                return { error: `--mode: unknown value "${next}" (expected human | llm)` };
+            mode = m;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--mode=')) {
+            const m = parseMode(arg.slice('--mode='.length));
+            if (!m)
+                return { error: `--mode: unknown value "${arg.slice('--mode='.length)}" (expected human | llm)` };
+            mode = m;
+            continue;
+        }
+        if (arg === '--max-file-size') {
+            const next = args[i + 1];
+            if (!next)
+                return { error: '--max-file-size requires a value (e.g. 200kb)' };
+            const n = parseSize(next);
+            if (n === undefined)
+                return { error: `--max-file-size: cannot parse "${next}"` };
+            maxFileSize = n;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--max-file-size=')) {
+            const v = arg.slice('--max-file-size='.length);
+            const n = parseSize(v);
+            if (n === undefined)
+                return { error: `--max-file-size: cannot parse "${v}"` };
+            maxFileSize = n;
+            continue;
+        }
+        if (arg === '--include') {
+            const next = args[i + 1];
+            if (!next)
+                return { error: '--include requires a pattern' };
+            include.push(next);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--include=')) {
+            include.push(arg.slice('--include='.length));
+            continue;
+        }
+        if (arg === '--exclude') {
+            const next = args[i + 1];
+            if (!next)
+                return { error: '--exclude requires a pattern' };
+            exclude.push(next);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--exclude=')) {
+            exclude.push(arg.slice('--exclude='.length));
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            return { error: `unknown flag "${arg}"` };
+        }
+        // Positional: workspace path. Only the first non-flag wins; extras
+        // are an error so a typo (`pugi flatten . foo`) surfaces.
+        if (positionalConsumed) {
+            return { error: `unexpected positional argument "${arg}"` };
+        }
+        cwd = resolve(arg);
+        positionalConsumed = true;
+    }
+    return { cwd, mode, stdout, open, maxFileSize, include, exclude };
+}
+function parseMode(v) {
+    if (v === 'human' || v === 'llm')
+        return v;
+    return undefined;
+}
+/**
+ * Parse a size literal: bare number = bytes; `200kb` / `1mb` / `2gb`
+ * (case-insensitive, binary units — 1KB = 1024 bytes).
+ */
+export function parseSize(raw) {
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return undefined;
+    const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/.exec(trimmed);
+    if (!match)
+        return undefined;
+    const n = Number(match[1]);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    const unit = match[2] ?? 'b';
+    const multiplier = unit === 'b' ? 1 : unit === 'kb' ? 1024 : unit === 'mb' ? 1024 * 1024 : 1024 * 1024 * 1024;
+    return Math.floor(n * multiplier);
+}
+//# sourceMappingURL=flatten.js.map

package/dist/commands/jobs-watch.js

@@ -0,0 +1,201 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `pugi jobs --watch` Ink TUI — live progress .
+ *
+ * Tails `~/.pugi/agent-progress/*.json` via chokidar and re-renders a
+ * grid of <AgentProgressCard> components. Mirrors the the upstream tool
+ * `/compact` layout pattern — one card per agent, sorted by status
+ * (running → completed → failed) then by lastUpdate descending so the
+ * freshest activity floats к the top.
+ *
+ * Lifecycle:
+ *  1. Resolve dir via resolveProgressDir() (env-aware).
+ *  2. Initial scan with readdirSync — populate the map.
+ *  3. chokidar.watch(dir, { ignoreInitial: true }) for add/change/unlink.
+ *  4. setInterval(1000) tick re-renders to keep elapsed labels live
+ *     WITHOUT re-reading files.
+ *  5. SIGINT (Ctrl+C) triggers `app.unmount()` + process.exit(0).
+ *
+ * Layout: single column under 100 cols, two columns at 100+ cols
+ * (Ink's flexbox computes the responsive split automatically — we just
+ * set `flexDirection="row" flexWrap="wrap"` and bound each card к 50%
+ * width when stdout is wide enough).
+ *
+ * The TUI is opt-in (operator runs `pugi jobs --watch`); the bare
+ * `pugi jobs` continues to print the legacy job-registry table.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import chokidar from 'chokidar';
+import { useEffect, useMemo, useState } from 'react';
+import { Box, Text, render, useApp, useInput, useStdout } from 'ink';
+import { resolveProgressDir } from '../core/agent-progress/writer.js';
+import { runCleanup } from '../core/agent-progress/cleanup.js';
+import { validateAgentProgress, } from '../core/agent-progress/schema.js';
+import { AgentProgressCard } from '../tui/agent-progress-card.js';
+/** Cleanup pass cadence inside the watcher. Cheap (readdir on a small
+ * dir); 60s is the operator-tested sweet spot — fast enough to feel
+ * live, slow enough к never burn CPU. */
+const CLEANUP_INTERVAL_MS = 60_000;
+const STATUS_RANK = {
+    running: 0,
+    completed: 1,
+    failed: 2,
+};
+/**
+ * Read + validate one progress file. Returns undefined on any failure
+ * — the watcher prefers к skip a malformed entry rather than crash.
+ * Exported for the spec.
+ */
+export function readProgressFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const body = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(body);
+        const result = validateAgentProgress(parsed);
+        return result.ok ? result.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sort progress entries for stable, operator-friendly display:
+ *  1. Running first.
+ *  2. Then by lastUpdate (most recent first).
+ *  3. Tiebreak on agentId for snapshot stability.
+ */
+export function sortProgressEntries(entries) {
+    return [...entries].sort((a, b) => {
+        const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+        if (rank !== 0)
+            return rank;
+        const tsDiff = Date.parse(b.lastUpdate) - Date.parse(a.lastUpdate);
+        if (tsDiff !== 0)
+            return tsDiff;
+        return a.agentId.localeCompare(b.agentId);
+    });
+}
+export function JobsWatch(props) {
+    const { dir, nowEpochMs, staticMode = false } = props;
+    const resolvedDir = useMemo(() => resolveProgressDir(dir), [dir]);
+    const [agents, setAgents] = useState(() => initialScan(resolvedDir));
+    const [tick, setTick] = useState(0);
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const cols = stdout?.columns ?? 80;
+    const twoColumns = cols >= 100;
+    useInput((_input, key) => {
+        if (key.escape || key.ctrl) {
+            // Ink's useInput passes ctrl=true for Ctrl+<x>; we exit on Ctrl+C
+            // (key.ctrl alone is too broad — actual key char arrives in `input`).
+            // Practically, raw mode passes Ctrl+C as SIGINT to the process so
+            // this is a belt-and-suspenders catch.
+            if (key.escape)
+                exit();
+        }
+    });
+    useEffect(() => {
+        if (staticMode)
+            return;
+        let watcher;
+        try {
+            watcher = chokidar.watch(resolvedDir, {
+                ignoreInitial: true,
+                depth: 0,
+                // The agent writer uses atomic rename — chokidar reports `add`
+                // when the final filename appears, never the *.tmp-* intermediate.
+                ignored: /\.tmp-/,
+            });
+            const onChange = (path) => {
+                if (!/\.json$/.test(path))
+                    return;
+                const progress = readProgressFile(path);
+                if (!progress)
+                    return;
+                setAgents((prev) => ({ ...prev, [progress.agentId]: progress }));
+            };
+            const onRemove = (path) => {
+                const match = /([^/\\]+)\.json$/.exec(path);
+                if (!match)
+                    return;
+                const id = match[1];
+                if (!id)
+                    return;
+                setAgents((prev) => {
+                    if (!(id in prev))
+                        return prev;
+                    const next = { ...prev };
+                    delete next[id];
+                    return next;
+                });
+            };
+            watcher.on('add', onChange);
+            watcher.on('change', onChange);
+            watcher.on('unlink', onRemove);
+        }
+        catch {
+            // Watcher failures degrade gracefully — initial scan still rendered.
+        }
+        const interval = setInterval(() => setTick((t) => t + 1), 1000);
+        // Auto-cleanup completed/failed entries older than the TTL. The
+        // sweep moves them к `<dir>/archive/` so operators can still
+        // forensic; the watcher's chokidar `unlink` handler drops them
+        // from the live grid as the rename fires.
+        const cleanupInterval = setInterval(() => {
+            try {
+                runCleanup({ dir: resolvedDir });
+            }
+            catch {
+                // best-effort housekeeping; never crash the TUI
+            }
+        }, CLEANUP_INTERVAL_MS);
+        return () => {
+            clearInterval(interval);
+            clearInterval(cleanupInterval);
+            if (watcher) {
+                void watcher.close();
+            }
+        };
+    }, [resolvedDir, staticMode]);
+    const sorted = useMemo(() => sortProgressEntries(Object.values(agents)), [agents]);
+    const effectiveNow = nowEpochMs ?? Date.now() + tick * 0; // tick triggers re-render only
+    if (sorted.length === 0) {
+        return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Text, { dimColor: true, children: ["No agents broadcasting progress yet. Watching", ' ', _jsx(Text, { bold: true, children: resolvedDir }), " for `<id>.json` files\u2026"] }), _jsx(Text, { dimColor: true, children: "(Press Esc / Ctrl+C \u043A exit.)" })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, children: "pugi jobs --watch" }), _jsxs(Text, { dimColor: true, children: [' ', "\u00B7 ", sorted.length, " ", sorted.length === 1 ? 'agent' : 'agents', " \u00B7", ' ', resolvedDir] })] }), _jsx(Box, { flexDirection: "row", flexWrap: "wrap", children: sorted.map((progress) => (_jsx(Box, { width: twoColumns ? '50%' : '100%', flexDirection: "column", children: _jsx(AgentProgressCard, { progress: progress, nowEpochMs: effectiveNow }) }, progress.agentId))) }), _jsx(Text, { dimColor: true, children: "(Esc / Ctrl+C \u043A exit.)" })] }));
+}
+function initialScan(dir) {
+    const map = {};
+    if (!existsSync(dir))
+        return map;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return map;
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.json'))
+            continue;
+        if (/\.tmp-/.test(name))
+            continue;
+        const progress = readProgressFile(join(dir, name));
+        if (progress)
+            map[progress.agentId] = progress;
+    }
+    return map;
+}
+/**
+ * Entry-point for `pugi jobs --watch`. Mounts the Ink app and returns
+ * a Promise that resolves when the user exits (Ctrl+C / Esc).
+ */
+export async function runJobsWatch(options = {}) {
+    return new Promise((resolve) => {
+        const app = render(_jsx(JobsWatch, { dir: options.dir }), { exitOnCtrlC: true });
+        void app.waitUntilExit().then(() => resolve(0));
+    });
+}
+//# sourceMappingURL=jobs-watch.js.map

package/dist/commands/jobs.js

@@ -1,21 +1,22 @@
 /**
- * `pugi jobs` command surface — Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J).
+ * `pugi jobs` command surface — Sprint .
  *
  * Subcommands:
- *   pugi jobs list                 — table of all tracked jobs (or JSON envelope)
- *   pugi jobs status <id>          — full record + tail of overflow artifact
- *   pugi jobs tail <id>            — stream the overflow artifact
- *   pugi jobs kill <id>            — SIGTERM then SIGKILL after a grace
- *   pugi jobs kill --all           — kill every running job in this session
+ *  pugi jobs list                — table of all tracked jobs (or JSON envelope)
+ *  pugi jobs status <id>         — full record + tail of overflow artifact
+ *  pugi jobs tail <id>           — stream the overflow artifact
+ *  pugi jobs kill <id>           — SIGTERM then SIGKILL after a grace
+ *  pugi jobs kill --all          — kill every running job in this session
  *
  * Power-word voice rules (per Pugi brand guide):
- *   - status names render as "on watch" (running), "shipped" (finished),
- *     "stood down" (killed), "blocked" (failed), "lost" (abandoned).
- *   - JSON envelopes keep the machine-friendly enum so consumers do
- *     not have to map back.
+ *  - status names render as "on watch" (running), "shipped" (finished),
+ *    "stood down" (killed), "blocked" (failed), "lost" (abandoned).
+ *  - JSON envelopes keep the machine-friendly enum so consumers do
+ *    not have to map back.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { formatDuration, getJobRegistry, relativeAge, } from '../core/jobs/registry.js';
+import { runJobsWatch } from './jobs-watch.js';
 const HUMAN_STATUS = {
     running: 'on watch',
     finished: 'shipped',
@@ -24,6 +25,19 @@ const HUMAN_STATUS = {
     abandoned: 'lost',
 };
 export async function runJobsCommand(args, flags, io, sessionId) {
+    // live progress : `pugi jobs --watch` mounts the live
+    // agent-progress TUI. The flag may sit anywhere in the arg list
+    // (`pugi jobs --watch` or `pugi jobs watch`) — both forms route к
+    // the watcher. JSON mode is incompatible (it would never return); we
+    // bail with a helpful error instead of silently swallowing the flag.
+    const wantsWatch = args.includes('--watch') || args[0] === 'watch';
+    if (wantsWatch) {
+        if (flags.json) {
+            io.writeError('pugi jobs --watch is interactive; --json is not supported.');
+            return 2;
+        }
+        return runJobsWatch();
+    }
     const sub = args[0] ?? 'list';
     switch (sub) {
         case 'list':
@@ -43,11 +57,12 @@ export async function runJobsCommand(args, flags, io, sessionId) {
 function usage() {
     return [
         'Usage:',
-        '  pugi jobs list [--json]                  Table of background jobs.',
-        '  pugi jobs status <id> [--json]           Full record + tail of artifact.',
-        '  pugi jobs tail <id>                      Stream the captured artifact.',
-        '  pugi jobs kill <id> [--json]             SIGTERM, escalate to SIGKILL.',
-        '  pugi jobs kill --all [--json]            Stand down every running job.',
+        ' pugi jobs list [--json]                 Table of background jobs.',
+        ' pugi jobs status <id> [--json]          Full record + tail of artifact.',
+        ' pugi jobs tail <id>                     Stream the captured artifact.',
+        ' pugi jobs kill <id> [--json]            SIGTERM, escalate to SIGKILL.',
+        ' pugi jobs kill --all [--json]           Stand down every running job.',
+        ' pugi jobs --watch                       Live Ink TUI of agent progress.',
     ].join('\n');
 }
 async function runList(flags, io) {
@@ -91,20 +106,20 @@ async function runStatus(id, flags, io) {
     }
     const lines = [
         `Job ${entry.id}`,
-        `  PID:        ${entry.pid}`,
-        `  Command:    ${entry.command}`,
-        `  Class:      ${entry.bashClass}`,
-        `  Status:     ${HUMAN_STATUS[entry.status]} (${entry.status})`,
-        `  CWD:        ${entry.cwd}`,
-        `  Started:    ${entry.startedAt} (${relativeAge(entry.startedAt)} ago)`,
-        `  Duration:   ${formatDuration(entry.startedAt, entry.finishedAt)}`,
+        ` PID:       ${entry.pid}`,
+        ` Command:   ${entry.command}`,
+        ` Class:     ${entry.bashClass}`,
+        ` Status:    ${HUMAN_STATUS[entry.status]} (${entry.status})`,
+        ` CWD:       ${entry.cwd}`,
+        ` Started:   ${entry.startedAt} (${relativeAge(entry.startedAt)} ago)`,
+        ` Duration:  ${formatDuration(entry.startedAt, entry.finishedAt)}`,
     ];
     if (entry.finishedAt)
-        lines.push(`  Finished:   ${entry.finishedAt}`);
+        lines.push(` Finished:  ${entry.finishedAt}`);
     if (entry.exitCode !== undefined)
-        lines.push(`  Exit code:  ${entry.exitCode}`);
+        lines.push(` Exit code: ${entry.exitCode}`);
     if (entry.outputArtifactRef)
-        lines.push(`  Artifact:   ${entry.outputArtifactRef}`);
+        lines.push(` Artifact:  ${entry.outputArtifactRef}`);
     if (tail) {
         lines.push('', '--- output tail ---', tail);
     }
@@ -159,7 +174,7 @@ async function runKill(args, flags, io, sessionId) {
         }
         else {
             for (const result of results) {
-                io.write(`  ${result.id}  ${result.killed ? 'stood down' : 'noop'} (${result.method})\n`);
+                io.write(` ${result.id} ${result.killed ? 'stood down' : 'noop'} (${result.method})\n`);
             }
         }
         return 0;
@@ -233,7 +248,7 @@ function renderTable(entries) {
     return rows
         .map((row) => row
         .map((cell, i) => cell.padEnd(widths[i] ?? cell.length))
-        .join('  ')
+        .join(' ')
         .trimEnd())
         .join('\n');
 }