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

package/dist/skills/bundled/loop.js

@@ -1,358 +0,0 @@
-/**
- * `pugi loop` — drives a repeating prompt against the engine until a
- * stop-condition matches.
- *
- * Bundled skill, batch 2 (backlog). Useful for autonomous "fix
- * until green" or "scaffold until verified" inner loops where the
- * operator does not want to hand-paste the same prompt repeatedly.
- *
- * # Flow
- *
- *  1. Build the prompt + optional `--until <regex>` stop condition.
- *  2. Iterate up to `--max-iterations` (default 10, hard cap 100).
- *  3. Each iteration calls the injected `engineInvoker` once and
- *     captures the assistant text + tool-call summaries.
- *  4. Concatenate the captured text and test the stop regex against
- *     it; if it matches, exit early with `status='matched'`.
- *  5. Enforce a USD ceiling via `--max-cost-usd` (default 2.0); when
- *     crossed, exit early with `status='cost-cap'`.
- *  6. Persist per-iteration progress to
- *     `.pugi/loops/<loop-id>.jsonl` (atomic tmp + rename per write).
- *
- * # Why a hard iteration cap
- *
- * The operator can set `--max-iterations` up to 100; beyond that the
- * skill refuses at CLI parse time. The ceiling protects against a
- * misconfigured stop regex that never matches — at $0.02/turn typical
- * cost, 100 iterations is still under the default USD cap, so the
- * tighter of the two limits always wins.
- *
- * # Provenance
- *
- * Inspired by the external bundled-skills pattern (intel from
- * leak-research memos, independent implementation TS). No upstream code reused.
- * Multi-provider council mode inside loop is backlog; today the
- * skill is single-engine.
- */
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
-const DEFAULT_MAX_ITERATIONS = 10;
-const HARD_MAX_ITERATIONS = 100;
-const DEFAULT_MAX_COST_USD = 2.0;
-function parseFlags(args) {
-    const flags = {
-        json: false,
-        prompt: null,
-        until: null,
-        maxIterations: DEFAULT_MAX_ITERATIONS,
-        maxCostUsd: DEFAULT_MAX_COST_USD,
-    };
-    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 === '--prompt') {
-            const next = args[i + 1];
-            if (next === undefined)
-                return { flags, error: '--prompt requires a value' };
-            flags.prompt = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--until') {
-            const next = args[i + 1];
-            if (next === undefined)
-                return { flags, error: '--until requires a regex' };
-            flags.until = next;
-            i += 1;
-            continue;
-        }
-        if (arg === '--max-iterations') {
-            const next = args[i + 1];
-            if (next === undefined) {
-                return { flags, error: '--max-iterations requires a value' };
-            }
-            const parsed = Number.parseInt(next, 10);
-            if (!Number.isFinite(parsed) || parsed <= 0) {
-                return { flags, error: '--max-iterations must be a positive integer' };
-            }
-            if (parsed > HARD_MAX_ITERATIONS) {
-                return {
-                    flags,
-                    error: `--max-iterations must be <= ${HARD_MAX_ITERATIONS}`,
-                };
-            }
-            flags.maxIterations = parsed;
-            i += 1;
-            continue;
-        }
-        if (arg === '--max-cost-usd') {
-            const next = args[i + 1];
-            if (next === undefined) {
-                return { flags, error: '--max-cost-usd requires a value' };
-            }
-            const parsed = Number.parseFloat(next);
-            if (!Number.isFinite(parsed) || parsed <= 0) {
-                return {
-                    flags,
-                    error: '--max-cost-usd must be a positive number (USD)',
-                };
-            }
-            flags.maxCostUsd = parsed;
-            i += 1;
-            continue;
-        }
-        if (arg === '--help' || arg === '-h') {
-            return { flags, error: 'help' };
-        }
-        return { flags, error: `unknown argument: ${arg}` };
-    }
-    return { flags, error: null };
-}
-/** Hard cap on `--until` source length — defends against ReDoS via long input. */
-const MAX_STOP_REGEX_LEN = 256;
-/**
- * Reject patterns that contain nested unbounded quantifiers — the classic
- * catastrophic-backtracking shape `(a+)+`, `(.+)*`, `(x*)*`, etc. Cheap
- * heuristic: look for any `+`/`*` immediately following a `)` that itself
- * closes a group whose body ends in another unbounded quantifier. Anything
- * that matches is rejected outright rather than handed to the V8 regex
- * engine where a malicious operator could pin a CPU core through the
- * loop's iteration budget.
- *
- * NOT a full regex AST parser — it just blocks the two known shapes that
- * matter. Operators with a legitimate need can pass an explicit
- * `/pattern/flags` form after the check (the rejection still fires).
- */
-function hasNestedUnboundedQuantifier(source) {
-    // Strip character classes so `[+*]` does not trip the heuristic.
-    const stripped = source.replace(/\[(?:\\.|[^\]\\])*\]/g, '');
-    // `(...+)+` / `(...+)*` / `(...*)*` / `(...*)+` shapes after class strip.
-    return /\([^)]*[+*][^)]*\)\s*[+*]/.test(stripped);
-}
-/**
- * Parse the `--until` argument into a RegExp. Accepts either a raw
- * pattern (used with the `s` flag so `.` spans newlines, friendly to
- * multi-line assistant output) or `/pattern/flags` for explicit control.
- *
- * Returns `null` on length overflow (> 256 chars), nested unbounded
- * quantifier (ReDoS shield), or any RegExp construction error. The
- * caller surfaces "invalid_stop_regex" so the operator can fix it
- * rather than discover a hang at iteration N.
- *
- * Public for test coverage.
- */
-export function parseStopRegex(input) {
-    if (input.length === 0)
-        return null;
-    if (input.length > MAX_STOP_REGEX_LEN)
-        return null;
-    if (input.startsWith('/') && /\/[gimsuy]*$/.test(input.slice(1))) {
-        const lastSlash = input.lastIndexOf('/');
-        const source = input.slice(1, lastSlash);
-        if (hasNestedUnboundedQuantifier(source))
-            return null;
-        try {
-            return new RegExp(source, input.slice(lastSlash + 1));
-        }
-        catch {
-            return null;
-        }
-    }
-    if (hasNestedUnboundedQuantifier(input))
-        return null;
-    try {
-        return new RegExp(input, 's');
-    }
-    catch {
-        return null;
-    }
-}
-function makeLoopId(now) {
-    const iso = now.toISOString().replace(/[:.]/g, '-');
-    const suffix = Math.floor(Math.random() * 0xfffff)
-        .toString(16)
-        .padStart(5, '0');
-    return `loop-${iso}-${suffix}`;
-}
-/**
- * Atomic JSONL append — keeps the file consistent for chokidar / tail
- * watchers by rewriting the whole document via tmp + rename on every
- * iteration. The watcher never sees a partial line.
- *
- * Public so the test suite can drive the helper directly.
- */
-export function atomicWriteFile(targetPath, body) {
-    const parent = dirname(targetPath);
-    if (!existsSync(parent)) {
-        mkdirSync(parent, { recursive: true });
-    }
-    const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
-    try {
-        writeFileSync(tmpPath, body, 'utf8');
-        renameSync(tmpPath, targetPath);
-    }
-    catch (err) {
-        try {
-            rmSync(tmpPath, { force: true });
-        }
-        catch {
-            // ignore cleanup
-        }
-        throw err;
-    }
-}
-function renderHumanReport(result) {
-    const lines = [];
-    lines.push(`pugi loop — id=${result.loopId} status=${result.status}`);
-    lines.push(`iterations: ${result.iterations.length} totalCostUsd: ${result.totalCostUsd.toFixed(4)}`);
-    lines.push(`progress: ${result.progressPath}`);
-    lines.push('');
-    for (const iter of result.iterations) {
-        lines.push(` [${String(iter.iteration).padStart(3, '0')}] cost=$${iter.costUsd.toFixed(4)} (cum=$${iter.cumulativeCostUsd.toFixed(4)})${iter.stopMatched ? ' <- stop matched' : ''}`);
-    }
-    return lines.join('\n');
-}
-export async function runLoopCommand(args, ctx) {
-    const { flags, error } = parseFlags(args);
-    if (error === 'help') {
-        ctx.writeOutput({ ok: true, command: 'loop', usage: LOOP_USAGE }, LOOP_USAGE);
-        return emptyResult('help', '', 'aborted', 0);
-    }
-    if (error !== null) {
-        ctx.writeOutput({ ok: false, command: 'loop', error }, `pugi loop: ${error}`);
-        return emptyResult('args-error', '', 'aborted', 2);
-    }
-    if (flags.prompt === null || flags.prompt.trim() === '') {
-        const msg = '--prompt is required';
-        ctx.writeOutput({ ok: false, command: 'loop', error: msg }, `pugi loop: ${msg}\n\n${LOOP_USAGE}`);
-        return emptyResult('args-error', '', 'no-prompt', 2);
-    }
-    const stopRegex = flags.until !== null ? parseStopRegex(flags.until) : null;
-    if (flags.until !== null && stopRegex === null) {
-        const msg = `--until is not a valid regex: ${flags.until}`;
-        ctx.writeOutput({ ok: false, command: 'loop', error: msg }, `pugi loop: ${msg}`);
-        return emptyResult('args-error', '', 'aborted', 2);
-    }
-    const loopId = ctx.newLoopId ? ctx.newLoopId() : makeLoopId(ctx.now());
-    const progressPath = join(ctx.cwd, '.pugi', 'loops', `${loopId}.jsonl`);
-    const iterations = [];
-    let cumulative = 0;
-    let status = 'max-iterations';
-    for (let i = 1; i <= flags.maxIterations; i += 1) {
-        const startedAt = ctx.now().toISOString();
-        let engineOut;
-        try {
-            engineOut = await ctx.engineInvoker({
-                iteration: i,
-                prompt: flags.prompt,
-                transcript: iterations,
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            status = 'aborted';
-            const completedAt = ctx.now().toISOString();
-            iterations.push({
-                iteration: i,
-                startedAt,
-                completedAt,
-                assistantText: `engine error: ${message}`,
-                toolCallSummary: [],
-                costUsd: 0,
-                cumulativeCostUsd: cumulative,
-                stopMatched: false,
-            });
-            persistProgress(progressPath, iterations);
-            break;
-        }
-        const completedAt = ctx.now().toISOString();
-        const stopMatched = stopRegex !== null
-            ? stopRegex.test([engineOut.assistantText, ...engineOut.toolCallSummary].join('\n'))
-            : false;
-        cumulative += engineOut.costUsd;
-        iterations.push({
-            iteration: i,
-            startedAt,
-            completedAt,
-            assistantText: engineOut.assistantText,
-            toolCallSummary: engineOut.toolCallSummary,
-            costUsd: engineOut.costUsd,
-            cumulativeCostUsd: cumulative,
-            stopMatched,
-        });
-        persistProgress(progressPath, iterations);
-        if (stopMatched) {
-            status = 'matched';
-            break;
-        }
-        if (cumulative >= flags.maxCostUsd) {
-            status = 'cost-cap';
-            break;
-        }
-    }
-    const exitCode = status === 'matched' || status === 'max-iterations'
-        ? 0
-        : 1;
-    const result = {
-        loopId,
-        status,
-        iterations,
-        totalCostUsd: cumulative,
-        progressPath,
-        exitCode,
-    };
-    ctx.writeOutput({ ok: true, command: 'loop', result }, renderHumanReport(result));
-    return result;
-}
-function persistProgress(progressPath, iterations) {
-    const body = iterations
-        .map((iter) => JSON.stringify(iter))
-        .join('\n');
-    try {
-        atomicWriteFile(progressPath, body === '' ? '' : `${body}\n`);
-    }
-    catch {
-        // The persistence path is informational; a fs failure must not
-        // bring the loop down. The operator still sees the in-memory
-        // summary on stdout / via the returned result.
-    }
-}
-function emptyResult(loopId, progressPath, status, exitCode) {
-    return {
-        loopId,
-        status,
-        iterations: [],
-        totalCostUsd: 0,
-        progressPath,
-        exitCode,
-    };
-}
-const LOOP_USAGE = [
-    'pugi loop — repeat a prompt against the engine until a stop condition.',
-    '',
-    'Usage:',
-    ' pugi loop --prompt "<text>" [--until "<regex>"]',
-    '           [--max-iterations <N>] [--max-cost-usd <USD>] [--json]',
-    '',
-    'Flags:',
-    ' --prompt <text>         The prompt sent to the engine each iteration.',
-    ' --until <regex>         Stop regex; matched against assistant + tool',
-    '                          output. Bare patterns get the `s` flag (`.`',
-    '                          spans newlines); `/pattern/flags` is explicit.',
-    ' --max-iterations <N>    Iteration ceiling (default 10, hard cap 100).',
-    ' --max-cost-usd <USD>    USD ceiling (default 2.0). EXPERIMENTAL — only',
-    '                          enforced when the engine invoker emits a',
-    '                          non-zero costUsd. The shipped stub returns 0,',
-    '                          so this cap is a no-op until the real engine',
-    '                          variant lands (backlog follow-up).',
-    ' --json                  JSON envelope instead of human text.',
-    '',
-    'Progress lands at .pugi/loops/<loop-id>.jsonl (one line per iteration,',
-    'rewritten atomically every iteration).',
-].join('\n');
-//# sourceMappingURL=loop.js.map