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

package/dist/core/rate-limit/narrator.js

@@ -1,146 +0,0 @@
-/**
- * Rate-limit narrator — branded copy + actionable next step.
- *
- * Upstream providers (Anthropic, OpenAI, DeepSeek, Cerebras) emit
- * shaped error payloads when a tenant hits a quota / RPM / TPM gate.
- * Default error text is generic ("Rate limit exceeded") и hostile к
- * customers who don't know what to do next. This module normalises
- * those signals into a Pugi-flavoured narration that says:
- *
- *  1. What hit the wall (token quota / request rate / concurrent jobs)
- *  2. When to retry
- *  3. What the operator can do RIGHT NOW (switch tier, wait, cancel)
- *
- * Pure mapping function — no I/O, no globals. Caller (engine / TUI)
- * decides where the narration lands.
- */
-export function narrateRateLimit(signal) {
-    const retryAfterSec = signal.retryAfterSec ?? -1;
-    const provider = signal.provider ?? 'upstream provider';
-    switch (signal.kind) {
-        case 'token-budget':
-            return {
-                headline: `Token budget exhausted на ${provider}`,
-                body: formatTokenBudgetBody(signal),
-                nextStep: retryAfterSec > 0
-                    ? `Wait ${formatDuration(retryAfterSec)} or upgrade tier с pugi tier upgrade.`
-                    : 'Upgrade tier с pugi tier upgrade or wait for window reset.',
-                retryAfterSec,
-            };
-        case 'request-rate':
-            return {
-                headline: `Too many requests к ${provider}`,
-                body: formatRateBody(signal),
-                nextStep: retryAfterSec > 0
-                    ? `Pugi retries automatically in ${formatDuration(retryAfterSec)}.`
-                    : 'Pugi retries automatically. Press Ctrl+C to cancel.',
-                retryAfterSec,
-            };
-        case 'concurrent-jobs':
-            return {
-                headline: `Concurrent job limit reached (${provider})`,
-                body: `Your tier permits up к ${signal.limit ?? 'N'} parallel jobs. Pugi queues the rest.`,
-                nextStep: 'Wait for a job to finish or upgrade tier для more parallelism.',
-                retryAfterSec,
-            };
-        case 'provider-quota':
-            return {
-                headline: `${provider} monthly quota exhausted`,
-                body: formatProviderQuotaBody(signal),
-                nextStep: 'Switch model tier или wait until next billing window.',
-                retryAfterSec,
-            };
-        case 'unknown':
-        default:
-            return {
-                headline: `Rate limit hit на ${provider}`,
-                body: signal.message?.trim().slice(0, 240) ?? 'Upstream returned a rate-limit signal без structured details.',
-                nextStep: retryAfterSec > 0
-                    ? `Pugi retries в ${formatDuration(retryAfterSec)}.`
-                    : 'Pugi will retry shortly. Press Ctrl+C to cancel.',
-                retryAfterSec,
-            };
-    }
-}
-function formatTokenBudgetBody(signal) {
-    if (signal.used !== undefined && signal.limit !== undefined && signal.window) {
-        const pct = Math.min(100, Math.round((signal.used / signal.limit) * 100));
-        return `Used ${signal.used.toLocaleString('en-US')} of ${signal.limit.toLocaleString('en-US')} tokens this ${signal.window} (${pct}%).`;
-    }
-    return signal.message?.trim().slice(0, 240) ?? 'Token budget for this window has been exhausted.';
-}
-function formatRateBody(signal) {
-    if (signal.limit !== undefined && signal.window) {
-        return `Provider cap is ${signal.limit} requests per ${signal.window}.`;
-    }
-    return signal.message?.trim().slice(0, 240) ?? 'Upstream is throttling the request burst.';
-}
-function formatProviderQuotaBody(signal) {
-    if (signal.message)
-        return signal.message.trim().slice(0, 240);
-    return 'Provider monthly billing window is exhausted. Pugi cannot route к this model until reset.';
-}
-function formatDuration(seconds) {
-    if (seconds < 60)
-        return `${seconds}s`;
-    if (seconds < 3600) {
-        const m = Math.floor(seconds / 60);
-        const s = seconds % 60;
-        return s > 0 ? `${m}m ${s}s` : `${m}m`;
-    }
-    const h = Math.floor(seconds / 3600);
-    const m = Math.floor((seconds % 3600) / 60);
-    return m > 0 ? `${h}h ${m}m` : `${h}h`;
-}
-/**
- * Classify a raw error payload to one of the known kinds. Conservative —
- * defaults к 'unknown' rather than misclassifying. Caller feeds the
- * result back через narrateRateLimit().
- */
-export function classifyRateLimit(raw) {
-    const message = (raw.message ?? '').toLowerCase();
-    const retryAfterSec = parseRetryAfter(raw.retryAfter ?? raw.headers?.['retry-after']);
-    let kind = 'unknown';
-    if (raw.status === 429) {
-        if (/token|tpm|budget|quota/.test(message))
-            kind = 'token-budget';
-        else if (/rpm|requests? per|too many requests?/.test(message))
-            kind = 'request-rate';
-        else if (/concurrent|parallel/.test(message))
-            kind = 'concurrent-jobs';
-        else
-            kind = 'request-rate';
-    }
-    else if (raw.status === 402) {
-        kind = 'provider-quota';
-    }
-    else if (/rate.?limit/.test(message)) {
-        kind = 'request-rate';
-    }
-    else if (/quota/.test(message)) {
-        kind = 'provider-quota';
-    }
-    const signal = { kind };
-    if (raw.message !== undefined)
-        signal.message = raw.message;
-    if (retryAfterSec >= 0)
-        signal.retryAfterSec = retryAfterSec;
-    return signal;
-}
-function parseRetryAfter(value) {
-    if (value === undefined)
-        return -1;
-    if (typeof value === 'number')
-        return Math.max(0, Math.floor(value));
-    const trimmed = value.trim();
-    if (/^\d+$/.test(trimmed))
-        return Math.max(0, parseInt(trimmed, 10));
-    // HTTP-date form: Retry-After: Wed, 21 Oct 2026 07:28:00 GMT
-    const t = Date.parse(trimmed);
-    if (Number.isFinite(t)) {
-        const delta = Math.floor((t - Date.now()) / 1000);
-        return Math.max(0, delta);
-    }
-    return -1;
-}
-//# sourceMappingURL=narrator.js.map

package/dist/core/recipes/cli-types.js

@@ -1,20 +0,0 @@
-/**
- * Recipe — saved parameterized multi-step workflows (Pugi backlog #62).
- *
- * Recipes are DIFFERENT from Skills (markdown LLM hints). Recipes are a
- * deterministic parameterized command sequence the operator runs
- * verbatim — Goose pattern. Each step's command is run through
- * `/bin/sh -c` (POSIX), with parameter substitution done at the
- * argv-quoting layer (NOT shell-eval) so a value like
- * `foo;rm -rf /` is passed as a literal single string and NOT split
- * into shell tokens.
- *
- * On-disk layout:
- *  .pugi/recipes/<id>.yml      repo-local (committed to project)
- *  ~/.pugi/recipes/<id>.yml    global (per-operator)
- *
- * Repo wins on id conflict — operators can shadow a global recipe by
- * dropping a same-id file in `.pugi/recipes/`.
- */
-export {};
-//# sourceMappingURL=cli-types.js.map

package/dist/core/recipes/loader.js

@@ -1,103 +0,0 @@
-/**
- * Recipe loader — walks both global (~/.pugi/recipes/) and repo-local
- * (.pugi/recipes/) directories, parses each `.yml`/`.yaml` file, dedups
- * on recipe id with repo-wins semantics. Parse errors are collected
- * and returned alongside the success map so `recipe list` can surface
- * them as soft warnings without aborting.
- */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { parseRecipeFile } from './schema.js';
-export function globalRecipesDir(home) {
-    return join(home ?? homedir(), '.pugi', 'recipes');
-}
-export function repoRecipesDir(workspaceRoot) {
-    return join(workspaceRoot, '.pugi', 'recipes');
-}
-export function loadRecipes(opts) {
-    const globalDir = globalRecipesDir(opts.home);
-    const repoDir = repoRecipesDir(opts.workspaceRoot);
-    const errors = [];
-    const recipes = new Map();
-    // Load global first. Repo overlays on top, so repo wins on conflict.
-    for (const entry of safeScan(globalDir)) {
-        const result = loadFile(entry, 'global');
-        if (result.ok) {
-            recipes.set(result.recipe.id, result.recipe);
-        }
-        else {
-            errors.push(result.error);
-        }
-    }
-    for (const entry of safeScan(repoDir)) {
-        const result = loadFile(entry, 'repo');
-        if (result.ok) {
-            recipes.set(result.recipe.id, result.recipe);
-        }
-        else {
-            errors.push(result.error);
-        }
-    }
-    return { recipes, errors, globalDir, repoDir };
-}
-function safeScan(dir) {
-    if (!existsSync(dir))
-        return [];
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return [];
-    }
-    const files = [];
-    for (const entry of entries) {
-        const full = resolve(dir, entry);
-        let info;
-        try {
-            info = statSync(full);
-        }
-        catch {
-            continue;
-        }
-        if (!info.isFile())
-            continue;
-        if (!/\.(yml|yaml)$/.test(entry))
-            continue;
-        files.push(full);
-    }
-    // Stable order so list output is deterministic across machines.
-    files.sort();
-    return files;
-}
-function loadFile(path, origin) {
-    const filename = path.split('/').pop() ?? path;
-    const id = filename.replace(/\.(yml|yaml)$/, '');
-    let body;
-    try {
-        body = readFileSync(path, 'utf8');
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { ok: false, error: { source: path, id, error: `read failed: ${message}` } };
-    }
-    const parsed = parseRecipeFile(body, { id, source: path, origin });
-    if (!parsed.ok) {
-        return { ok: false, error: { source: path, id, error: parsed.error } };
-    }
-    return { ok: true, recipe: parsed.recipe };
-}
-export function resolveRecipe(id, loaded) {
-    const direct = loaded.get(id);
-    if (direct)
-        return { ok: true, recipe: direct };
-    const ids = Array.from(loaded.keys());
-    const near = ids.find((known) => known.startsWith(id) || id.startsWith(known));
-    const suggestion = near ? ` Did you mean '${near}'?` : '';
-    return {
-        ok: false,
-        error: `recipe '${id}' not found.${suggestion}`,
-    };
-}
-//# sourceMappingURL=loader.js.map

package/dist/core/recipes/runner.js

@@ -1,345 +0,0 @@
-/**
- * Recipe runner — execute a parameterized recipe step-by-step.
- *
- * # Security model — parameter substitution
- *
- * `${params.X}` markers in `run:` templates are substituted with
- * shell-quoted values BEFORE the command is handed to `/bin/sh -c`.
- * The substitution wraps every value in single quotes, doubling any
- * embedded single quotes per POSIX:
- *
- *  value `foo;rm -rf /`
- *    -> `'foo;rm -rf /'`
- *  value `it's`
- *    -> `'it'\''s'`
- *
- * The result is ONE shell token. Metacharacters (`;`, `&&`, `|`,
- * `$()`, backticks, redirects, newlines) are literal inside the
- * quoted segment — the shell never re-parses them. This is the same
- * pattern `printf %q` produces and the one Goose / `shell-quote`
- * recommend.
- *
- * # Permission gate
- *
- * Each step's command is routed through `evaluateBashPermission` with
- * the operator's current settings.permissions.mode. A `deny` decision
- * halts the run. `allow` / `ask` both proceed — this is an operator-
- * initiated context (no interactive prompt is possible from a recipe
- * run), so an "ask" result is treated as "allow" for the duration of
- * the recipe.
- *
- * # Halt vs continueOnError
- *
- * A non-zero exit halts the run unless the step declares
- * `continueOnError: true`, in which case the next step runs anyway
- * and the failing step is recorded with status `failed`.
- */
-import { spawn } from 'node:child_process';
-import { compileWhenExpression } from './schema.js';
-import { evaluateBashPermission, } from '../permission.js';
-const PARAM_REF_RE = /\$\{params\.([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
-export function resolveParams(recipe, supplied) {
-    const out = {};
-    for (const spec of recipe.params) {
-        const raw = supplied[spec.name];
-        if (raw === undefined) {
-            if (spec.default !== undefined) {
-                out[spec.name] = spec.default;
-                continue;
-            }
-            if (spec.required) {
-                return {
-                    ok: false,
-                    error: `missing required param '${spec.name}' (--${spec.name}=<value>)`,
-                };
-            }
-            // Unspecified optional param without a default: skip — when a
-            // step references it, the substitution layer will report a
-            // clean error so the operator knows which step needs it.
-            continue;
-        }
-        const coerced = coerceParam(raw, spec.type);
-        if (!coerced.ok) {
-            return {
-                ok: false,
-                error: `param '${spec.name}': ${coerced.error}`,
-            };
-        }
-        out[spec.name] = coerced.value;
-    }
-    // Reject unknown params so a `--typo=foo` doesn't silently disappear.
-    for (const key of Object.keys(supplied)) {
-        if (!recipe.params.some((p) => p.name === key)) {
-            return {
-                ok: false,
-                error: `unknown param '${key}' (recipe declares: ${recipe.params.map((p) => p.name).join(', ') || 'none'})`,
-            };
-        }
-    }
-    return { ok: true, params: out };
-}
-function coerceParam(raw, type) {
-    switch (type) {
-        case 'string':
-            if (typeof raw === 'string')
-                return { ok: true, value: raw };
-            if (typeof raw === 'number' || typeof raw === 'boolean') {
-                return { ok: true, value: String(raw) };
-            }
-            return { ok: false, error: `expected string, got ${typeof raw}` };
-        case 'boolean':
-            if (typeof raw === 'boolean')
-                return { ok: true, value: raw };
-            if (raw === 'true')
-                return { ok: true, value: true };
-            if (raw === 'false')
-                return { ok: true, value: false };
-            return {
-                ok: false,
-                error: `expected boolean ('true' | 'false'), got '${String(raw)}'`,
-            };
-        case 'number': {
-            if (typeof raw === 'number')
-                return { ok: true, value: raw };
-            if (typeof raw === 'string') {
-                const parsed = Number(raw);
-                if (Number.isFinite(parsed))
-                    return { ok: true, value: parsed };
-            }
-            return { ok: false, error: `expected number, got '${String(raw)}'` };
-        }
-    }
-}
-/**
- * Quote a value into a single POSIX-shell-safe token.
- *
- *  foo           -> 'foo'
- *  foo;rm -rf /  -> 'foo;rm -rf /'
- *  it's          -> 'it'\''s'
- *
- * The wrapping single quotes mean nothing inside them is interpreted
- * by the shell — that is the entire point of this layer. Public so
- * test code can assert the contract directly.
- */
-export function shellQuote(value) {
-    const str = String(value);
-    // Empty string still needs visible quotes so the shell sees a token.
-    if (str === '')
-        return "''";
-    // Pure safe ASCII can pass through unquoted as a micro-optimization;
-    // we deliberately DO NOT take that shortcut. Always quote so the
-    // contract holds regardless of value content.
-    const escaped = str.replace(/'/g, "'\\''");
-    return `'${escaped}'`;
-}
-/**
- * Substitute `${params.X}` markers in a template. Each value is
- * shell-quoted. Returns a clean error when a referenced param is
- * absent from the resolved map (optional param without a default and
- * the operator did not pass it).
- *
- * Public for direct injection-test coverage.
- */
-export function substituteCommand(template, params) {
-    let missing = null;
-    const out = template.replace(PARAM_REF_RE, (_match, rawName) => {
-        if (!(rawName in params)) {
-            missing = rawName;
-            return '';
-        }
-        const value = params[rawName];
-        if (value === undefined) {
-            missing = rawName;
-            return '';
-        }
-        return shellQuote(value);
-    });
-    if (missing !== null) {
-        return {
-            ok: false,
-            error: `step references '\${params.${missing}}' but it is unset (declare a default or pass --${missing})`,
-        };
-    }
-    return { ok: true, command: out };
-}
-const defaultExec = (command, cwd) => new Promise((resolveExec) => {
-    const child = spawn('/bin/sh', ['-c', command], {
-        cwd,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        env: process.env,
-    });
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
-    child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
-    child.on('error', (error) => {
-        resolveExec({
-            stdout: Buffer.concat(stdoutChunks).toString('utf8'),
-            stderr: Buffer.concat(stderrChunks).toString('utf8') +
-                `\nspawn error: ${error.message}`,
-            exitCode: 126,
-        });
-    });
-    child.on('exit', (code, signal) => {
-        const exit = typeof code === 'number'
-            ? code
-            : signal !== null
-                ? 128 + (signalNumber(signal) ?? 0)
-                : 0;
-        resolveExec({
-            stdout: Buffer.concat(stdoutChunks).toString('utf8'),
-            stderr: Buffer.concat(stderrChunks).toString('utf8'),
-            exitCode: exit,
-        });
-    });
-});
-function signalNumber(signal) {
-    switch (signal) {
-        case 'SIGTERM':
-            return 15;
-        case 'SIGKILL':
-            return 9;
-        case 'SIGINT':
-            return 2;
-        default:
-            return null;
-    }
-}
-/**
- * Execute a recipe step-by-step. Returns the aggregated `RecipeRunResult`
- * with one `StepResult` per declared step (skipped steps still produce
- * an entry so the operator can see why each step did or didn't run).
- */
-export async function runRecipe(opts) {
-    const exec = opts.exec ?? defaultExec;
-    const now = opts.now ?? Date.now;
-    const source = opts.source ?? 'human';
-    const additionalDirs = opts.additionalDirectories ?? [];
-    const steps = [];
-    let aggregate = 'success';
-    let haltAfter = false;
-    let totalDuration = 0;
-    for (const step of opts.recipe.steps) {
-        if (haltAfter) {
-            steps.push({
-                name: step.name,
-                command: null,
-                status: 'aborted',
-                exitCode: null,
-                stdout: '',
-                stderr: '',
-                durationMs: 0,
-                denyReason: '',
-            });
-            continue;
-        }
-        // when: gate — skip pre-substitution so a templated command never
-        // hits the shell when its `when` says no.
-        if (step.when !== undefined) {
-            const compiled = compileWhenExpression(step.when, opts.recipe.params);
-            if (!compiled.ok) {
-                steps.push({
-                    name: step.name,
-                    command: null,
-                    status: 'failed',
-                    exitCode: null,
-                    stdout: '',
-                    stderr: `when-clause invalid: ${compiled.error}`,
-                    durationMs: 0,
-                    denyReason: '',
-                });
-                aggregate = 'halted';
-                haltAfter = true;
-                continue;
-            }
-            const allowed = compiled.evaluate(opts.params);
-            if (!allowed) {
-                steps.push({
-                    name: step.name,
-                    command: null,
-                    status: 'skipped',
-                    exitCode: null,
-                    stdout: '',
-                    stderr: '',
-                    durationMs: 0,
-                    denyReason: '',
-                });
-                continue;
-            }
-        }
-        const substituted = substituteCommand(step.run, opts.params);
-        if (!substituted.ok) {
-            steps.push({
-                name: step.name,
-                command: null,
-                status: 'failed',
-                exitCode: null,
-                stdout: '',
-                stderr: substituted.error,
-                durationMs: 0,
-                denyReason: '',
-            });
-            if (!step.continueOnError) {
-                aggregate = 'halted';
-                haltAfter = true;
-            }
-            else {
-                aggregate = aggregate === 'success' ? 'failed' : aggregate;
-            }
-            continue;
-        }
-        const command = substituted.command;
-        const decision = evaluateBashPermission(command, opts.permissionMode, {
-            workspaceRoot: opts.workspaceRoot,
-            additionalDirectories: [...additionalDirs],
-            source,
-        });
-        if (decision.decision === 'deny') {
-            steps.push({
-                name: step.name,
-                command,
-                status: 'denied',
-                exitCode: null,
-                stdout: '',
-                stderr: decision.reason,
-                durationMs: 0,
-                denyReason: decision.reason,
-            });
-            aggregate = 'denied';
-            haltAfter = true;
-            continue;
-        }
-        const startedAt = now();
-        const result = await exec(command, opts.workspaceRoot);
-        const durationMs = Math.max(0, now() - startedAt);
-        totalDuration += durationMs;
-        const status = result.exitCode === 0 ? 'success' : 'failed';
-        steps.push({
-            name: step.name,
-            command,
-            status,
-            exitCode: result.exitCode,
-            stdout: result.stdout,
-            stderr: result.stderr,
-            durationMs,
-            denyReason: '',
-        });
-        if (status === 'failed') {
-            if (step.continueOnError) {
-                aggregate = aggregate === 'success' ? 'failed' : aggregate;
-            }
-            else {
-                aggregate = 'halted';
-                haltAfter = true;
-            }
-        }
-    }
-    return {
-        id: opts.recipe.id,
-        params: opts.params,
-        steps,
-        status: aggregate,
-        durationMs: totalDuration,
-    };
-}
-//# sourceMappingURL=runner.js.map