@percher/core 0.2.6 → 0.4.0

package/dist/publish-retry.js

@@ -0,0 +1,224 @@
+/**
+ * Publish-retry classifier and runner (Phase 7.2).
+ *
+ * The 2026-05-07 incident batch surfaced a class of agent-perceived
+ * failure where the platform's `WORKER_UNAVAILABLE` (transient — the
+ * worker was restarting) bubbled through the CLI as a hard error.
+ * Humans/agents recovered by typing `percher publish` again. The CLI
+ * should do that itself.
+ *
+ * Rules table (mirrored in `docs/plans/IMPLEMENTING_publish-resilience-and-clarity-plan.md`):
+ *
+ *   WORKER_UNAVAILABLE        retry 3× — 5s / 15s / 45s
+ *   WORKER_UNAVAILABLE_PERSISTENT  no retry — surface as platform incident
+ *   DEPLOY_RATE_LIMITED       retry 2× — honour retryAfterSec from response
+ *   network error / TCP reset retry 3× — 2s / 8s / 24s
+ *   HTTP 5xx                  retry 2× — 5s / 20s
+ *   HTTP 4xx (incl. 429 quota, 422 config)  no retry
+ *   BUILD_FAILED / BUILD_TIMEOUT / DEPLOY_STALLED  no retry — these are
+ *      observed during the *poll* phase, not the upload, but listed here
+ *      defensively so any future code path that encounters them while
+ *      retrying still classifies them correctly.
+ *
+ * Every retry reuses the same `Idempotency-Key` header so the API treats
+ * a re-attempt as "are you still working on this one?" rather than
+ * minting a new deploy row. The caller is responsible for generating the
+ * key (via `crypto.randomUUID()`) and threading it into the request.
+ */
+import { PercherApiError } from "@percher/client";
+const NON_RETRYABLE_CODES = new Set([
+    "WORKER_UNAVAILABLE_PERSISTENT",
+    "BUILD_FAILED",
+    "BUILD_TIMEOUT",
+    "DEPLOY_STALLED",
+    "REQUIRED_ENV_MISSING",
+    "ENV_KEY_UNDECLARED",
+    "DAILY_QUOTA_EXCEEDED",
+    "RETRY_LIMIT_REACHED",
+    "ACCOUNT_SUSPENDED",
+    "APP_SUSPENDED",
+    "EMAIL_NOT_VERIFIED",
+    "PREVIEW_LIMIT_REACHED",
+    "VALIDATION_ERROR",
+    // Phase 8.1 — past hardCap the queue is so deep that retry-after
+    // would lie about wait time. Treat as a platform incident: surface
+    // immediately so the user sees the status-page link instead of
+    // a CLI that loops every minute claiming "should be back in 5s".
+    "PLATFORM_DOWN",
+]);
+const WORKER_UNAVAILABLE_BACKOFF_MS = [5_000, 15_000, 45_000];
+const NETWORK_BACKOFF_MS = [2_000, 8_000, 24_000];
+const HTTP_5XX_BACKOFF_MS = [5_000, 20_000];
+export function classifyDeployRetry(err, attempt) {
+    // attempt is 1-indexed — `attempt = 1` means "first failure, decide
+    // delay before attempt 2"; the schedule arrays are 0-indexed.
+    const idx = attempt - 1;
+    if (err instanceof PercherApiError) {
+        if (err.code === "WORKER_UNAVAILABLE_PERSISTENT") {
+            return {
+                retryable: false,
+                delayMs: 0,
+                reason: "platform circuit breaker open — surfacing as incident",
+                category: "persistent",
+            };
+        }
+        if (err.code === "WORKER_UNAVAILABLE") {
+            const delay = WORKER_UNAVAILABLE_BACKOFF_MS[idx];
+            if (delay === undefined) {
+                return {
+                    retryable: false,
+                    delayMs: 0,
+                    reason: "worker unavailable after 3 attempts",
+                    category: "worker_unavailable",
+                };
+            }
+            return {
+                retryable: true,
+                delayMs: delay,
+                reason: "worker was restarting",
+                category: "worker_unavailable",
+            };
+        }
+        if (err.code === "DEPLOY_RATE_LIMITED") {
+            if (idx >= 2) {
+                return {
+                    retryable: false,
+                    delayMs: 0,
+                    reason: "rate-limited after 2 attempts",
+                    category: "rate_limited",
+                };
+            }
+            const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 5;
+            return {
+                retryable: true,
+                delayMs: Math.min(60_000, Math.max(1_000, retryAfterSec * 1000)),
+                reason: "per-app rate limit",
+                category: "rate_limited",
+            };
+        }
+        if (err.code === "USER_CONCURRENT_LIMIT") {
+            // Phase 8.2 — the user has the most parallel deploys their plan
+            // allows. Retrying after the suggested window often clears one
+            // of the in-flight builds. Single retry is enough; past that the
+            // user almost certainly needs to take action (upgrade or stop
+            // looping), so surface the error.
+            if (idx >= 1) {
+                return {
+                    retryable: false,
+                    delayMs: 0,
+                    reason: "concurrent-deploy cap still saturated after one wait",
+                    category: "rate_limited",
+                };
+            }
+            const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 60;
+            return {
+                retryable: true,
+                delayMs: Math.min(2 * 60_000, Math.max(5_000, retryAfterSec * 1000)),
+                reason: "per-user concurrent-deploy cap",
+                category: "rate_limited",
+            };
+        }
+        if (err.code === "PLATFORM_OVERLOADED") {
+            // Phase 8.1 — global backpressure. The API supplies a
+            // Retry-After header computed from the realistic drain estimate;
+            // honor it (capped at 5 min so a misbehaving server can't hold
+            // the CLI hostage). Up to 3 retries — past that the queue isn't
+            // draining for this caller and surfacing the incident is fairer.
+            if (idx >= 3) {
+                return {
+                    retryable: false,
+                    delayMs: 0,
+                    reason: "platform overloaded after 3 attempts",
+                    category: "rate_limited",
+                };
+            }
+            const retryAfterSec = typeof err.extra?.retryAfterSec === "number" ? err.extra.retryAfterSec : 30;
+            return {
+                retryable: true,
+                delayMs: Math.min(5 * 60_000, Math.max(5_000, retryAfterSec * 1000)),
+                reason: "platform overloaded — queue-depth backpressure",
+                category: "rate_limited",
+            };
+        }
+        if (NON_RETRYABLE_CODES.has(err.code)) {
+            return {
+                retryable: false,
+                delayMs: 0,
+                reason: `non-retryable: ${err.code}`,
+                category: "non_retryable",
+            };
+        }
+        if (err.status >= 500 && err.status < 600) {
+            const delay = HTTP_5XX_BACKOFF_MS[idx];
+            if (delay === undefined) {
+                return {
+                    retryable: false,
+                    delayMs: 0,
+                    reason: `HTTP ${err.status} after 2 attempts`,
+                    category: "http_5xx",
+                };
+            }
+            return {
+                retryable: true,
+                delayMs: delay,
+                reason: `HTTP ${err.status}`,
+                category: "http_5xx",
+            };
+        }
+        return {
+            retryable: false,
+            delayMs: 0,
+            reason: `HTTP ${err.status} ${err.code}`,
+            category: "non_retryable",
+        };
+    }
+    if (err instanceof Error &&
+        /network error|fetch failed|ECONNRESET|ENOTFOUND|ETIMEDOUT/i.test(err.message)) {
+        const delay = NETWORK_BACKOFF_MS[idx];
+        if (delay === undefined) {
+            return {
+                retryable: false,
+                delayMs: 0,
+                reason: "network error after 3 attempts",
+                category: "network",
+            };
+        }
+        return {
+            retryable: true,
+            delayMs: delay,
+            reason: "network blip",
+            category: "network",
+        };
+    }
+    return {
+        retryable: false,
+        delayMs: 0,
+        reason: "unknown error",
+        category: "non_retryable",
+    };
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function runDeployWithRetry(opts) {
+    const max = opts.maxAttempts ?? 4;
+    const sleep = opts.sleep ?? defaultSleep;
+    let attempt = 0;
+    let lastErr;
+    while (attempt < max) {
+        attempt += 1;
+        try {
+            const result = await opts.call(attempt);
+            return { result, attempts: attempt };
+        }
+        catch (err) {
+            lastErr = err;
+            const decision = classifyDeployRetry(err, attempt);
+            if (!decision.retryable || attempt >= max) {
+                throw err;
+            }
+            opts.onRetry?.({ attempt, decision, err });
+            await sleep(decision.delayMs);
+        }
+    }
+    throw lastErr;
+}
+//# sourceMappingURL=publish-retry.js.map

package/dist/publish-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-retry.js","sourceRoot":"","sources":["../src/publish-retry.ts"],"names":[],"mappings":"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"}

package/dist/recovery.d.ts

@@ -0,0 +1,356 @@
+import type { BuildProblem } from "@percher/client";
+import type { ErrorClass } from "./error-classifier";
+/**
+ * Action an AI agent should take after a deploy result.
+ *
+ * Stable, machine-readable enum. Treat values as a public API: agents will
+ * hardcode `===` comparisons against these strings, so removing or renaming
+ * a value is a breaking change.
+ */
+export type RecoveryAction = 
+/** User is unauthenticated; agent should call `percher_login`. */
+"open_login"
+/** Build/runtime is missing env vars; call `percher_env_set`. */
+ | "set_env_vars"
+/**
+ * FUTURE11 Phase 2 — deploy is in flight (queued/building/deploying);
+ * agent should call `percher_wait_for_deploy` to keep checking in
+ * short intervals instead of starting a new deploy.
+ */
+ | "wait_deploy"
+/** Transient infra failure; safe to call `percher_publish` again. */
+ | "retry"
+/**
+ * FUTURE12 Phase 1a — additive enum value. Reserved for ambiguous
+ * failures (generic `build_failed`, stalled deploys, runtime crashes,
+ * unclear state) where the right path is to ask `percher_doctor`
+ * for a primary recommendation rather than hopping straight to a
+ * specific low-level inspector. Phase 4 of FUTURE12 migrates the
+ * existing `inspect_build_log` primary cases over to this action.
+ */
+ | "run_doctor"
+/** Build failed for a code reason; agent should call `percher_deploys_inspect`. */
+ | "inspect_build_log"
+/**
+ * FUTURE1 Phase 2.3 — build failed and the API extracted at least one
+ * structured BuildProblem (file + line + actionable hint). Agent
+ * should patch the offending file directly using `problems` rather
+ * than fetching/parsing the build log.
+ */
+ | "fix_problems"
+/**
+ * FUTURE1 Phase 4.2 — explicit opt-in path for reproducing a build
+ * failure locally. Never auto-suggested as `nextAction`: cloud-side
+ * `inspect_build_log` always works while local reproduction needs
+ * nixpacks installed AND only ships env *keys* (no values), so it
+ * makes recovery WORSE for runtime-secret failures and dockerfile-
+ * only flows. Surfaces via `alternativeActions` instead so an agent
+ * can opt in after `inspect_build_log` didn't yield a fix.
+ */
+ | "reproduce_locally"
+/** `percher.toml` is invalid; agent should ask the user or repair the file. */
+ | "fix_config"
+/** Plan limits exceeded or otherwise needs human input; agent should ask the user. */
+ | "ask_user"
+/** Success path — no further action required. */
+ | "none";
+/** MCP tool the agent should invoke for `nextAction`, when applicable. */
+export type SuggestedTool = "percher_login" | "percher_env_set" | "percher_deploys_inspect" | "percher_publish"
+/** FUTURE11 Phase 2 — short-poll a specific deploy without starting a new one. */
+ | "percher_wait_for_deploy"
+/**
+ * FUTURE12 Phase 1a — pairs with `run_doctor` action. Phase 4 of
+ * FUTURE12 migrates publish/wait's generic-failure paths to emit
+ * `percher_doctor` instead of `percher_deploys_inspect`.
+ */
+ | "percher_doctor"
+/** FUTURE1 Phase 3.2 — percher_redeploy tool, used by burst-rate-
+ *  limit recovery so agents retry the rerun after retryAfterSec
+ *  instead of hopping to a fresh percher_publish. */
+ | "percher_redeploy"
+/** FUTURE1 Phase 4.2 — percher_reproduce tool, surfaced via
+ *  alternativeActions on build-failure recovery. */
+ | "percher_reproduce";
+/**
+ * FUTURE12 Phase 1a — stable, enumerated reason an agent or human can
+ * branch on. Intentionally orthogonal to `RecoveryAction`: action says
+ * *what to do next*, reasonCode says *why we're here*. Two recoveries
+ * can share `nextAction` (e.g. both `ask_user`) but emit different
+ * reasonCodes (`quota_exceeded` vs `retry_limit_reached`) so the agent
+ * can produce a different prompt to the user.
+ *
+ * **Treat values as a public API.** Agents will hardcode `===` checks.
+ */
+export type ReasonCode = 
+/** Success or otherwise no specific reason to surface. */
+"none"
+/** User is unauthenticated; needs to log in before any deploy can run. */
+ | "auth_required"
+/** App referenced in config doesn't exist (or was deleted). */
+ | "app_not_found"
+/** No `percher.toml` in cwd; can't determine app config. */
+ | "config_missing"
+/** `percher.toml` parsed but failed schema validation. */
+ | "config_invalid"
+/** `[env].required`/`optional`/`ignore` rules conflict (e.g. duplicate key). */
+ | "env_contract_invalid"
+/** Source code references env keys that the contract doesn't declare. */
+ | "env_key_undeclared"
+/** Reserved alias for `env_contract_invalid` — used when the missing
+ *  contract block itself is the problem. */
+ | "env_contract_missing"
+/** App exists but no deploys have ever run (or all were pruned). */
+ | "no_deploys"
+/** Deploy is sitting in the queue, not yet picked up by a worker. */
+ | "deploy_queued"
+/** Deploy worker is actively building. */
+ | "deploy_building"
+/** Build done; deploy is being swapped in / health-checked. */
+ | "deploy_deploying"
+/** Deploy hasn't progressed for longer than the watchdog window. */
+ | "deploy_stalled"
+/** Wait window elapsed without terminal status; no stall judgement made. */
+ | "deploy_timeout"
+/** Caller tried to publish while another deploy is already in flight. */
+ | "deploy_already_in_progress"
+/** This deploy row was superseded by a newer one. */
+ | "replaced_by_newer"
+/** Build/runtime needs env keys that aren't set. */
+ | "missing_env"
+/** Build itself failed (compile error, missing dep, bad command, etc). */
+ | "build_failed"
+/** Container booted but the app crashed at runtime. */
+ | "runtime_crashed"
+/** Daily/burst quota hit; not retryable until reset. */
+ | "quota_exceeded"
+/** Already retried once after transient infra failure; stop auto-retrying. */
+ | "retry_limit_reached"
+/** Likely-transient infra issue (network, image registry, etc). */
+ | "infra_transient"
+/** Hard infra outage — Percher can't deploy at all right now. */
+ | "infra_unavailable"
+/** Build log isn't in storage yet (deploy too fresh). */
+ | "log_unavailable_yet"
+/** Build log fetch errored (transport / encoding / size cap). */
+ | "log_fetch_failed"
+/** Deploy died before the build phase started (e.g. tarball validation). */
+ | "failed_before_build"
+/** Catch-all for unclassified state — agents should route to doctor. */
+ | "unknown";
+/**
+ * FUTURE12 Phase 1a — `percher_doctor` mode hint. Public MCP path
+ * defaults to `auto`. Other modes exist for CLI `--mode` and for
+ * cases where publish/wait can give doctor an exact starting point
+ * (e.g. `mode: "deploy"` with a known `deployId`).
+ */
+export type DoctorMode = "auto" | "deploy" | "runtime" | "config" | "env" | "account";
+/**
+ * FUTURE12 Phase 1a — single source of truth for `PublishResult.status`.
+ *
+ * `already_in_progress` is reserved for Phase 6's server-side guardrail
+ * that short-circuits publish when the app already has an active
+ * deploy. Pinning the value here so the CLI/MCP can declare exhaustive
+ * switches before the server path lands.
+ */
+export type PublishStatus = "live" | "failed" | "needs_login" | "dry_run" | "queued" | "replaced" | "already_in_progress";
+/**
+ * Structured problem entry used by `fix_config` and `fix_problems`
+ * recoveries. Agents apply file edits directly using these.
+ */
+export interface RecoveryProblem {
+    file: string;
+    line?: number;
+    column?: number;
+    message: string;
+}
+/** Secondary affordance — see `BaseRecovery.alternativeActions`. */
+export interface RecoveryAlternative {
+    action: RecoveryAction;
+    suggestedTool?: SuggestedTool;
+    args?: Record<string, unknown>;
+    /** When this alternative is preferable to `nextAction`. */
+    when: string;
+}
+/** Fields shared by every recovery branch. */
+interface BaseRecovery {
+    /** True if calling the same tool again with no changes might succeed. */
+    retryable: boolean;
+    /**
+     * FUTURE12 Phase 1b — required, machine-readable reason. Branches
+     * orthogonally to `nextAction`: two recoveries can share `nextAction`
+     * but emit different `reasonCode`s so an agent can produce a
+     * different prompt or telemetry tag.
+     */
+    reasonCode: ReasonCode;
+    /**
+     * FUTURE1 Phase 4.2 — optional secondary affordances the agent MAY
+     * use after `nextAction` if the primary path didn't yield a fix.
+     * Always populated on build-failure paths so the reproduce-locally
+     * option is discoverable, but `nextAction` stays at the always-
+     * works cloud path so a passive follow-the-arrow agent doesn't get
+     * steered into a flow that needs nixpacks installed locally.
+     */
+    alternativeActions?: RecoveryAlternative[];
+}
+/**
+ * Tool-action recovery — `nextAction` maps to a concrete MCP tool and
+ * `args` carries everything the agent needs to invoke it. The
+ * `inspect_build_log` value is kept here for legacy callers; FUTURE12
+ * Phase 4 migrates it to `run_doctor`.
+ */
+export interface ToolRecovery extends BaseRecovery {
+    nextAction: "open_login" | "wait_deploy" | "run_doctor" | "set_env_vars" | "retry" | "inspect_build_log";
+    suggestedTool: SuggestedTool;
+    args: Record<string, unknown>;
+}
+/**
+ * File-edit recovery — `problems` describes what to fix. The agent
+ * applies file edits in its own surface, not via an MCP tool.
+ */
+export interface UserRecovery extends BaseRecovery {
+    nextAction: "fix_config" | "fix_problems";
+    problems: RecoveryProblem[];
+}
+/** Success / no-action recovery. `url` is set when a current live URL is known. */
+export interface NoneRecovery extends BaseRecovery {
+    nextAction: "none";
+    url?: string;
+}
+/** Human-input recovery — `prompt` is the question the agent should ask the user. */
+export interface AskUserRecovery extends BaseRecovery {
+    nextAction: "ask_user";
+    prompt: string;
+    options?: string[];
+}
+/**
+ * Discriminated union over `nextAction`. Agents narrow by checking
+ * `nextAction` first, then read the branch-specific fields:
+ *
+ * - `ask_user` → `prompt`, optional `options`
+ * - `none` → optional `url`
+ * - `fix_config` / `fix_problems` → `problems`
+ * - everything else → `suggestedTool` + `args`
+ */
+export type PublishRecovery = ToolRecovery | UserRecovery | NoneRecovery | AskUserRecovery;
+/** Success / no-op recovery. `url` is the current live URL when known. */
+export declare function recoveryNone(opts?: {
+    reasonCode?: ReasonCode;
+    url?: string;
+}): NoneRecovery;
+/** Authentication required — agent should call `percher_login`. */
+export declare function recoveryLogin(opts?: {
+    reasonCode?: ReasonCode;
+}): ToolRecovery;
+/** Wait on an in-flight deploy — agent should call `percher_wait_for_deploy`. */
+export declare function recoveryWait(opts: {
+    app: string;
+    deployId: string;
+    timeoutSeconds?: number;
+    reasonCode: ReasonCode;
+}): ToolRecovery;
+/** Route to `percher_doctor` for an ambiguous failure that needs diagnosis. */
+export declare function recoveryDoctor(opts: {
+    app?: string;
+    deployId?: string;
+    mode?: DoctorMode;
+    reasonCode: ReasonCode;
+    alternativeActions?: RecoveryAlternative[];
+}): ToolRecovery;
+/** Build/runtime needs env keys — agent should call `percher_env_set`. */
+export declare function recoveryEnv(opts: {
+    app?: string;
+    keys: string[];
+    reasonCode?: ReasonCode;
+}): ToolRecovery;
+/**
+ * `percher.toml` is invalid or missing — agent should fix the file
+ * directly. `problems` carries the structured issue list (file,
+ * line/column, message) so the agent can apply edits without parsing
+ * a free-text error.
+ */
+export declare function recoveryFixConfig(opts: {
+    problems: RecoveryProblem[];
+    reasonCode?: ReasonCode;
+}): UserRecovery;
+/**
+ * Build failed and the API extracted at least one structured problem
+ * with file/line data — agent should patch the offending file(s).
+ */
+export declare function recoveryFixProblems(opts: {
+    problems: RecoveryProblem[];
+    reasonCode?: ReasonCode;
+    alternativeActions?: RecoveryAlternative[];
+}): UserRecovery;
+/** Transient infra failure — agent can re-issue the same call. */
+export declare function recoveryRetry(opts: {
+    suggestedTool: SuggestedTool;
+    args: Record<string, unknown>;
+    reasonCode: ReasonCode;
+}): ToolRecovery;
+/**
+ * Human-input required. `prompt` MUST be a concrete question — agents
+ * surface it verbatim, so empty/placeholder strings violate the
+ * contract.
+ */
+export declare function recoveryAsk(opts: {
+    prompt: string;
+    options?: string[];
+    reasonCode: ReasonCode;
+    retryable?: boolean;
+}): AskUserRecovery;
+/**
+ * Legacy `inspect_build_log` recovery — kept for the build-failure
+ * paths that haven't migrated to `run_doctor` yet. FUTURE12 Phase 4
+ * will replace these emit sites with `recoveryDoctor`.
+ */
+export declare function recoveryInspectBuildLog(opts: {
+    app?: string;
+    deployId?: string;
+    reasonCode?: ReasonCode;
+    alternativeActions?: RecoveryAlternative[];
+}): ToolRecovery;
+/** Recovery on the success path. */
+export declare const RECOVERY_NONE: NoneRecovery;
+/** Recovery for the unauthenticated path. */
+export declare const RECOVERY_NEEDS_LOGIN: ToolRecovery;
+interface FailureContext {
+    /** Concrete env var names the classifier extracted, if any. */
+    missingEnvVars?: string[];
+    /** Deploy id, used to point `percher_deploys_inspect` at the right build. */
+    deployId?: string;
+    /** App name, optional — `percher_deploys_inspect` defaults to the toml app. */
+    appName?: string;
+    /**
+     * Original publish input, echoed back as `args` for `retry`. Lets an agent
+     * re-issue the same call (preview/dryRun/message/force) without re-deriving.
+     */
+    publishInput?: Record<string, unknown>;
+    /**
+     * FUTURE1 Phase 2.3 — structured build problems from the API parser.
+     * When at least one carries a `file` field, the recovery action
+     * upgrades to `fix_problems` with the problems echoed in `args` so
+     * agents can issue file edits directly without log archaeology.
+     */
+    problems?: BuildProblem[];
+}
+/**
+ * Convert a `BuildProblem` into the lossless `RecoveryProblem` shape.
+ * Drops fields that aren't part of the recovery contract (severity,
+ * code) — those still ride on `error.problems` for the CLI's pretty
+ * printer. `hint` is folded into the message because it carries the
+ * actionable next step (especially for problems without a line, like
+ * malformed package.json) and the recovery contract has no separate
+ * hint slot.
+ *
+ * Exported so doctor (Phase 2c fix_problems path) can reuse the
+ * same hint-preserving mapping rather than re-implementing it.
+ */
+export declare function buildProblemToRecoveryProblem(p: BuildProblem): RecoveryProblem;
+/**
+ * Map an `ErrorClass` to a recovery action. Conservative by default —
+ * unknown classes resolve to `ask_user` so an agent never blindly retries
+ * something we haven't classified.
+ */
+export declare function recoveryFromErrorClass(errorClass: ErrorClass, failure?: FailureContext): PublishRecovery;
+export {};
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc;AACxB,kEAAkE;AAChE,YAAY;AACd,iEAAiE;GAC/D,cAAc;AAChB;;;;GAIG;GACD,aAAa;AACf,qEAAqE;GACnE,OAAO;AACT;;;;;;;GAOG;GACD,YAAY;AACd,mFAAmF;GACjF,mBAAmB;AACrB;;;;;GAKG;GACD,cAAc;AAChB;;;;;;;;GAQG;GACD,mBAAmB;AACrB,+EAA+E;GAC7E,YAAY;AACd,sFAAsF;GACpF,UAAU;AACZ,iDAAiD;GAC/C,MAAM,CAAC;AAEX,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,iBAAiB,GACjB,yBAAyB,GACzB,iBAAiB;AACnB,kFAAkF;GAChF,yBAAyB;AAC3B;;;;GAIG;GACD,gBAAgB;AAClB;;qDAEqD;GACnD,kBAAkB;AACpB;oDACoD;GAClD,mBAAmB,CAAC;AAExB;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU;AACpB,0DAA0D;AACxD,MAAM;AACR,0EAA0E;GACxE,eAAe;AACjB,+DAA+D;GAC7D,eAAe;AACjB,4DAA4D;GAC1D,gBAAgB;AAClB,0DAA0D;GACxD,gBAAgB;AAClB,gFAAgF;GAC9E,sBAAsB;AACxB,yEAAyE;GACvE,oBAAoB;AACtB;4CAC4C;GAC1C,sBAAsB;AACxB,oEAAoE;GAClE,YAAY;AACd,qEAAqE;GACnE,eAAe;AACjB,0CAA0C;GACxC,iBAAiB;AACnB,+DAA+D;GAC7D,kBAAkB;AACpB,oEAAoE;GAClE,gBAAgB;AAClB,4EAA4E;GAC1E,gBAAgB;AAClB,yEAAyE;GACvE,4BAA4B;AAC9B,qDAAqD;GACnD,mBAAmB;AACrB,oDAAoD;GAClD,aAAa;AACf,0EAA0E;GACxE,cAAc;AAChB,uDAAuD;GACrD,iBAAiB;AACnB,wDAAwD;GACtD,gBAAgB;AAClB,8EAA8E;GAC5E,qBAAqB;AACvB,mEAAmE;GACjE,iBAAiB;AACnB,iEAAiE;GAC/D,mBAAmB;AACrB,yDAAyD;GACvD,qBAAqB;AACvB,iEAAiE;GAC/D,kBAAkB;AACpB,4EAA4E;GAC1E,qBAAqB;AACvB,wEAAwE;GACtE,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAEtF;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,QAAQ,GACR,aAAa,GACb,SAAS,GACT,QAAQ,GACR,UAAU,GACV,qBAAqB,CAAC;AAE1B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8CAA8C;AAC9C,UAAU,YAAY;IACpB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,UAAU,EACN,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,cAAc,GACd,OAAO,GACP,mBAAmB,CAAC;IACxB,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,UAAU,EAAE,YAAY,GAAG,cAAc,CAAC;IAC1C,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,eAAe,CAAC;AAS3F,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,UAAU,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAO/F;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAO,GAAG,YAAY,CAQlF;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;CACxB,GAAG,YAAY,CAYf;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,kBAAkB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C,GAAG,YAAY,CAef;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,YAAY,CAWf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,YAAY,CAOf;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C,GAAG,YAAY,CAUf;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,EAAE,UAAU,CAAC;CACxB,GAAG,YAAY,CAQf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,eAAe,CAWlB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C,GAAG,YAAY,CAcf;AAQD,oCAAoC;AACpC,eAAO,MAAM,aAAa,EAAE,YAA6B,CAAC;AAE1D,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB,EAAE,YAA8B,CAAC;AAElE,UAAU,cAAc;IACtB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,YAAY,GAAG,eAAe,CAW9E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAoHjB"}