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

package/dist/commands/smoke.js

@@ -1,133 +0,0 @@
-/**
- * `pugi smoke` — runs the bundled scenario corpus through the headless
- * harness and reports pass/fail per scenario (
- *).
- *
- * The CLI surface lives here rather than in `runtime/cli.ts` so the
- * dispatch surface stays focused on argv routing. This module owns:
- *
- *  - Resolving the scenarios directory (default
- *    `<cli-root>/test/scenarios/` when bundled, configurable via
- *    `--scenarios-dir`).
- *  - Selecting the `pugi` binary the headless driver should spawn.
- *    Local development: `node <cli-root>/bin/run.js`. CI / published
- *    usage: the `pugi` on PATH.
- *  - Forwarding the orchestrator output to the unified
- *    `writeOutput` writer so `--json` mode works without a second
- *    code path.
- *
- * Phase 1 deliberately ships ONE flag (`--filter`) and one option
- * (`--scenarios-dir`); the rest of the surface comes in Phase 2 once
- * the engine path is wired and we know which scenarios actually need
- * per-run plumbing (timeouts, fixture credentials, hermetic stubs).
- */
-import { existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runSmoke, renderReportText, } from '../core/smoke/orchestrator.js';
-import { runHeadlessScenario } from '../core/smoke/headless-driver.js';
-/**
- * Entry point invoked by `runtime/cli.ts::dispatchSmoke`. Returns the
- * desired process exit code so the dispatcher can set
- * `process.exitCode` without a second round-trip.
- */
-export async function runSmokeCommand(ctx) {
-    // Parse the (small) command-local argv. We only honor flags this
-    // command actually consumes; unknown args produce a usage error so
-    // typos surface immediately.
-    let scenariosDirOverride = ctx.scenariosDir ?? undefined;
-    let filter = ctx.filter ?? '';
-    for (let i = 0; i < ctx.args.length; i += 1) {
-        const arg = ctx.args[i] ?? '';
-        if (arg === '--filter') {
-            const next = ctx.args[i + 1];
-            if (!next || next.startsWith('--')) {
-                ctx.writeOutput({ ok: false, error: '--filter requires a pattern' }, 'pugi smoke: --filter requires a pattern (substring or *-glob)');
-                return 2;
-            }
-            filter = next;
-            i += 1;
-        }
-        else if (arg.startsWith('--filter=')) {
-            filter = arg.slice('--filter='.length);
-        }
-        else if (arg === '--scenarios-dir') {
-            const next = ctx.args[i + 1];
-            if (!next || next.startsWith('--')) {
-                ctx.writeOutput({ ok: false, error: '--scenarios-dir requires a path' }, 'pugi smoke: --scenarios-dir requires a path');
-                return 2;
-            }
-            scenariosDirOverride = next;
-            i += 1;
-        }
-        else if (arg.startsWith('--scenarios-dir=')) {
-            scenariosDirOverride = arg.slice('--scenarios-dir='.length);
-        }
-        else if (arg === '--help' || arg === '-h') {
-            ctx.writeOutput({
-                ok: true,
-                usage: 'pugi smoke [--filter <pattern>] [--scenarios-dir <path>]',
-            }, [
-                'pugi smoke — run the bundled scenario corpus headlessly.',
-                '',
-                'Flags:',
-                ' --filter <pattern>    Run a subset (substring or *-glob match on scenario id).',
-                ' --scenarios-dir <path> Override the scenarios directory (default: bundled corpus).',
-            ].join('\n'));
-            return 0;
-        }
-        else {
-            ctx.writeOutput({ ok: false, error: `unknown arg: ${arg}` }, `pugi smoke: unknown arg ${arg}`);
-            return 2;
-        }
-    }
-    const scenariosDir = scenariosDirOverride ?? resolveBundledScenariosDir();
-    if (!existsSync(scenariosDir)) {
-        ctx.writeOutput({ ok: false, error: `scenarios dir not found: ${scenariosDir}` }, `pugi smoke: scenarios dir not found: ${scenariosDir}`);
-        return 2;
-    }
-    const pugiBin = ctx.pugiBin ?? process.env.PUGI_SMOKE_BIN ?? 'pugi';
-    const log = ctx.log ?? ((line) => process.stderr.write(`${line}\n`));
-    const report = await runSmoke({
-        scenariosDir,
-        filter,
-        executor: (scenario) => runHeadlessScenario(scenario, { pugiBin }),
-        log,
-    });
-    if (ctx.json) {
-        ctx.writeOutput(report, renderReportText(report));
-    }
-    else {
-        process.stdout.write(`${renderReportText(report)}\n`);
-    }
-    return report.exitCode;
-}
-/**
- * Resolve the scenarios directory that ships alongside the CLI.
- *
- * Both the dev source layout (`<cli-root>/src/commands/smoke.ts`) and
- * the built output layout (`<cli-root>/dist/commands/smoke.js`) land
- * on the same `../../test/scenarios` path relative to this file.
- * The bundled `npm i -g @pugi/cli` install replicates that structure
- * by shipping `test/scenarios` (glob `**\/*.scenario.txt`) via the
- * `package.json` `files` field — so the single resolved path works in
- * dev, in `tsx` runs, and in published installs without a config knob.
- *
- * If a future restructure ever bundles scenarios at
- * `<cli-root>/dist/scenarios/` instead, add that to the fallback chain
- * here AND mirror the path in `package.json` `files`. Until then we
- * keep the resolver intentionally one-line.
- */
-export function resolveBundledScenariosDir() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    // Works for both src/commands/smoke.ts and dist/commands/smoke.js —
-    // both live two directories below the cli root.
-    const bundled = resolve(here, '..', '..', 'test', 'scenarios');
-    if (existsSync(bundled))
-        return bundled;
-    // Last resort: return the expected path so the orchestrator surfaces
-    // a clean "scenarios dir not found" diagnostic at the call site
-    // rather than the resolver swallowing it silently.
-    return bundled;
-}
-//# sourceMappingURL=smoke.js.map

package/dist/core/agent-progress/cleanup.js

@@ -1,134 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,101 +0,0 @@
-/**
- * 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