@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

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

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

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

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

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