@percher/core 0.2.6 → 0.3.0

package/dist/commands/unsuspend.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod/v3";
+import type { Context } from "../context";
+export declare const unsuspendInputSchema: z.ZodObject<{
+    app: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    app: string;
+}, {
+    app: string;
+}>;
+export type UnsuspendInput = z.infer<typeof unsuspendInputSchema>;
+export interface UnsuspendResult {
+    ok: true;
+    app: {
+        id: string;
+        name: string;
+        status: string;
+    };
+    /** True if this call flipped the app from suspended to active.
+     *  False if the app was already active (idempotent). */
+    flipped: boolean;
+    summary: string;
+}
+/**
+ * Unsuspend an app. Used from CLI ("Lock removed") and from the
+ * agent surface (`percher_unsuspend` MCP tool) when an auto-suspend
+ * is the recovery action the agent should take after the user has
+ * fixed the underlying failure.
+ *
+ * Server-side this triggers the cooldown threshold in
+ * FailureLoopGuard: if the app fails N=3 more times within an hour,
+ * it auto-suspends again (faster than the standard N=8) — discourages
+ * the "unsuspend → resume the loop → re-burn the budget" antipattern.
+ */
+export declare function unsuspend(ctx: Context, input: UnsuspendInput): Promise<UnsuspendResult>;
+//# sourceMappingURL=unsuspend.d.ts.map

package/dist/commands/unsuspend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsuspend.d.ts","sourceRoot":"","sources":["../../src/commands/unsuspend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,oBAAoB;;;;;;EAE/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD;4DACwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAU7F"}

package/dist/commands/unsuspend.js

@@ -0,0 +1,27 @@
+import { z } from "zod/v3";
+export const unsuspendInputSchema = z.object({
+    app: z.string().min(1).describe("App name or id to unsuspend"),
+});
+/**
+ * Unsuspend an app. Used from CLI ("Lock removed") and from the
+ * agent surface (`percher_unsuspend` MCP tool) when an auto-suspend
+ * is the recovery action the agent should take after the user has
+ * fixed the underlying failure.
+ *
+ * Server-side this triggers the cooldown threshold in
+ * FailureLoopGuard: if the app fails N=3 more times within an hour,
+ * it auto-suspends again (faster than the standard N=8) — discourages
+ * the "unsuspend → resume the loop → re-burn the budget" antipattern.
+ */
+export async function unsuspend(ctx, input) {
+    const result = await ctx.client.apps.unsuspend(input.app);
+    return {
+        ok: true,
+        app: result.app,
+        flipped: result.flipped,
+        summary: result.flipped
+            ? `Unsuspended ${result.app.name}. If it fails 3 more times in the next hour, the cooldown threshold will auto-suspend it again — fix the cause before retrying.`
+            : `${result.app.name} was already active (no change).`,
+    };
+}
+//# sourceMappingURL=unsuspend.js.map

package/dist/commands/unsuspend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsuspend.js","sourceRoot":"","sources":["../../src/commands/unsuspend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAG3B,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;CAC/D,CAAC,CAAC;AAYH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAY,EAAE,KAAqB;IACjE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1D,OAAO;QACL,EAAE,EAAE,IAAI;QACR,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACrB,CAAC,CAAC,eAAe,MAAM,CAAC,GAAG,CAAC,IAAI,iIAAiI;YACjK,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,kCAAkC;KACzD,CAAC;AACJ,CAAC"}

package/dist/commands/versions.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import type { Context } from "../context";
 export declare const versionsInputSchema: z.ZodObject<{
     app: z.ZodOptional<z.ZodString>;

package/dist/commands/versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/commands/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,eAAO,MAAM,mBAAmB;;;;;;EAA2C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAS7F"}
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/commands/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,eAAO,MAAM,mBAAmB;;;;;;EAA2C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAS7F"}

package/dist/commands/versions.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { readPercherTomlAppName } from "../app-name";
 import { PercherCoreError } from "../errors";
 export const versionsInputSchema = z.object({ app: z.string().optional() });

package/dist/commands/versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/commands/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAS5E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAY,EAAE,QAAuB,EAAE;IACpE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,gBAAgB,CAAC,4CAA4C,EAAE;YACvE,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,6DAA6D;SACpE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/commands/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAS5E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAY,EAAE,QAAuB,EAAE;IACpE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,gBAAgB,CAAC,4CAA4C,EAAE;YACvE,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,6DAA6D;SACpE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/commands/wait-deploy.d.ts

@@ -0,0 +1,92 @@
+import type { App, Deployment } from "@percher/client";
+import { z } from "zod/v3";
+import type { Context } from "../context";
+import { type PublishRecovery } from "../recovery";
+import type { PublishError } from "./publish";
+export declare const waitForDeployInputSchema: z.ZodObject<{
+    app: z.ZodString;
+    deployId: z.ZodString;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    pollIntervalSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    app: string;
+    deployId: string;
+    timeoutSeconds?: number | undefined;
+    pollIntervalSeconds?: number | undefined;
+}, {
+    app: string;
+    deployId: string;
+    timeoutSeconds?: number | undefined;
+    pollIntervalSeconds?: number | undefined;
+}>;
+export type WaitForDeployInput = z.infer<typeof waitForDeployInputSchema>;
+export interface WaitForDeployResult {
+    /**
+     * - `live` — deployment reached terminal success.
+     * - `failed` — deployment reached terminal failure (`error` populated).
+     * - `replaced` — deployment was superseded. Resolver looks at the
+     *    latest deploy on the app and routes accordingly:
+     *      • newer live exists → `nextAction: "none"`, `url` is the
+     *        current live URL, `summary` includes the resolved deployId.
+     *      • newer deploy still in flight → `nextAction: "wait_deploy"`
+     *        pointing at the newer deployId.
+     *      • no newer / latest also failed → `nextAction: "ask_user"`.
+     *    Never `retry` — replaced isn't a transient failure of this row.
+     * - `still_running` — timeout hit before terminal status; agent should
+     *    call this tool again with the same deployId.
+     */
+    status: "live" | "failed" | "replaced" | "still_running";
+    app: {
+        id: string;
+        name: string;
+        url: string;
+    };
+    deployment: Deployment;
+    /** Live or preview URL on success. */
+    url?: string;
+    /** Wall-clock seconds spent in this single wait call. */
+    elapsedSeconds: number;
+    /**
+     * Total seconds since the deployment was first created (server-side
+     * `createdAt`). Helps the agent answer "is this stuck?" — combined
+     * with status, an `elapsedSeconds`-since-create > 600 in `building`
+     * is a strong signal of a real stall, not just a slow build.
+     */
+    totalElapsedSeconds: number;
+    error?: PublishError;
+    recovery: PublishRecovery;
+    summary: string;
+}
+/**
+ * FUTURE11 Phase 2 — short-poll a specific deploy without starting a new
+ * one. Returns terminal results when the deploy reaches live/failed
+ * within the timeout, otherwise returns `still_running` with a
+ * `wait_deploy` recovery so the agent loops without growing the call
+ * stack. Never starts a new deploy.
+ */
+export declare function waitForDeploy(ctx: Context, input: WaitForDeployInput): Promise<WaitForDeployResult>;
+/**
+ * FUTURE11 review round 5 — resolve what `replaced` actually means by
+ * looking at the latest deploy. Two API code-paths produce `replaced`:
+ *
+ *   1. `markPreviousLiveAsReplaced` — a NEWER live deploy succeeded
+ *      and pushed this row aside. App is live; route to nextAction='none'.
+ *   2. `markLiveDeployReplaced` — reconcile saw the container is gone
+ *      (CONTAINER_NOT_FOUND). No newer live exists; app is effectively
+ *      down. Route to ask_user.
+ *
+ * Resolver also handles the in-flight case where the newer deploy is
+ * still building — point at it via wait_deploy. Matches FUTURE12 Phase
+ * 4's locked behavior for `replaced_by_newer`.
+ */
+export declare function resolveReplaced(opts: {
+    ctx: Context;
+    app: App;
+    replacedDeployment: Deployment;
+}): Promise<{
+    recovery: PublishRecovery;
+    url?: string;
+    summary: string;
+    resolvedDeployment?: Deployment;
+}>;
+//# sourceMappingURL=wait-deploy.d.ts.map

package/dist/commands/wait-deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-deploy.d.ts","sourceRoot":"","sources":["../../src/commands/wait-deploy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACL,KAAK,eAAe,EAKrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;EAmBnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,eAAe,CAAC;IACzD,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,EAAE,UAAU,CAAC;IACvB,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAoE9B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,kBAAkB,EAAE,UAAU,CAAC;CAChC,GAAG,OAAO,CAAC;IACV,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC,CAAC,CA4ED"}

package/dist/commands/wait-deploy.js

@@ -0,0 +1,225 @@
+import { z } from "zod/v3";
+import { RECOVERY_NONE, recoveryAsk, recoveryNone, recoveryWait, } from "../recovery";
+import { classifyDeploymentFailure } from "./publish-failure";
+export const waitForDeployInputSchema = z.object({
+    app: z.string().describe("App name (the value of [app].name in percher.toml)"),
+    deployId: z.string().describe("Deploy id returned by percher_publish (e.g. dep_abc123)"),
+    timeoutSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe("Maximum wall-clock seconds to wait before returning still_running (default 30, max 120). Keeping this short is the point — the agent can resume in another short call without holding a long-lived connection."),
+    pollIntervalSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .describe("Seconds between polls (default 2)."),
+});
+/**
+ * FUTURE11 Phase 2 — short-poll a specific deploy without starting a new
+ * one. Returns terminal results when the deploy reaches live/failed
+ * within the timeout, otherwise returns `still_running` with a
+ * `wait_deploy` recovery so the agent loops without growing the call
+ * stack. Never starts a new deploy.
+ */
+export async function waitForDeploy(ctx, input) {
+    const timeoutSeconds = input.timeoutSeconds ?? 30;
+    const pollIntervalSeconds = input.pollIntervalSeconds ?? 2;
+    // Fetch app + initial deployment in parallel; the app row is needed for
+    // the URL on success and for failure-classification context.
+    const [app, initial] = await Promise.all([
+        ctx.client.apps.get(input.app),
+        ctx.client.apps.getDeployment(input.app, input.deployId),
+    ]);
+    const startedAt = Date.now();
+    const deadlineMs = startedAt + timeoutSeconds * 1000;
+    let deployment = initial;
+    while (!isTerminal(deployment.status)) {
+        if (Date.now() >= deadlineMs) {
+            return buildStillRunningResult(app, deployment, startedAt);
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalSeconds * 1000));
+        try {
+            deployment = await ctx.client.apps.getDeployment(input.app, input.deployId);
+        }
+        catch (err) {
+            // Transient fetch errors during a short wait don't justify
+            // throwing — return still_running so the agent retries. The
+            // deploy may already be live server-side; the agent's next call
+            // will pick that up.
+            const msg = err.message ?? String(err);
+            if (msg.startsWith("network error:")) {
+                return buildStillRunningResult(app, deployment, startedAt, msg);
+            }
+            throw err;
+        }
+    }
+    if (deployment.status === "failed") {
+        const { error, recovery, summary } = await classifyDeploymentFailure({
+            ctx,
+            app,
+            deployment,
+        });
+        return {
+            status: "failed",
+            app: { id: app.id, name: app.name, url: app.url },
+            deployment,
+            elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+            totalElapsedSeconds: secondsSinceCreated(deployment),
+            error,
+            recovery,
+            summary,
+        };
+    }
+    if (deployment.status === "replaced") {
+        return await buildReplacedResult({ ctx, app, deployment, startedAt });
+    }
+    const url = deployment.previewUrl ?? deployment.url ?? app.url;
+    return {
+        status: "live",
+        app: { id: app.id, name: app.name, url: app.url },
+        deployment,
+        url,
+        elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+        totalElapsedSeconds: secondsSinceCreated(deployment),
+        recovery: RECOVERY_NONE,
+        summary: `${app.name} deploy ${deployment.id} is live → ${url}`,
+    };
+}
+function isTerminal(status) {
+    return status === "live" || status === "failed" || status === "replaced";
+}
+/**
+ * FUTURE11 review round 5 — resolve what `replaced` actually means by
+ * looking at the latest deploy. Two API code-paths produce `replaced`:
+ *
+ *   1. `markPreviousLiveAsReplaced` — a NEWER live deploy succeeded
+ *      and pushed this row aside. App is live; route to nextAction='none'.
+ *   2. `markLiveDeployReplaced` — reconcile saw the container is gone
+ *      (CONTAINER_NOT_FOUND). No newer live exists; app is effectively
+ *      down. Route to ask_user.
+ *
+ * Resolver also handles the in-flight case where the newer deploy is
+ * still building — point at it via wait_deploy. Matches FUTURE12 Phase
+ * 4's locked behavior for `replaced_by_newer`.
+ */
+export async function resolveReplaced(opts) {
+    const { ctx, app, replacedDeployment } = opts;
+    // Filter the lookup to the same deploy kind. A `replaced` row is
+    // always a live deploy in the API (both markPreviousLiveAsReplaced
+    // and markLiveDeployReplaced enforce eq(deployments.type, "live")),
+    // so without `type` filtering a newer preview deploy could hijack
+    // recovery — the resolver might wait on the preview, surface a
+    // preview URL as if it were the canonical live, or fall back to
+    // ask_user when previews push the real successor past the limit.
+    // Default to "live" when the row's type is missing for any reason.
+    const deployType = replacedDeployment.type ?? "live";
+    let latest;
+    try {
+        const deploys = await ctx.client.apps.listDeploys(app.name, {
+            limit: 5,
+            type: deployType,
+        });
+        // Skip the row we already know is replaced; pick the most recent
+        // deploy that's not this one. The list is ordered desc by createdAt.
+        latest = deploys.find((d) => d.id !== replacedDeployment.id);
+    }
+    catch {
+        return {
+            recovery: recoveryAsk({
+                prompt: `${app.name} deploy ${replacedDeployment.id} was replaced, but listing recent deploys failed. Check the dashboard or run \`percher doctor --app ${app.name}\` to inspect current state.`,
+                reasonCode: "replaced_by_newer",
+            }),
+            summary: `${app.name} deploy ${replacedDeployment.id} was replaced, but listing recent deploys failed. Surface to user — they can check the dashboard.`,
+        };
+    }
+    if (!latest) {
+        return {
+            recovery: recoveryAsk({
+                prompt: `${app.name} deploy ${replacedDeployment.id} was replaced and there are no other deploys to resolve to. Surface this to the user — they may need to redeploy.`,
+                reasonCode: "replaced_by_newer",
+            }),
+            summary: `${app.name} deploy ${replacedDeployment.id} was replaced and there are no other deploys to resolve to. Surface to user.`,
+        };
+    }
+    if (latest.status === "live") {
+        const url = latest.previewUrl ?? latest.url ?? app.url;
+        return {
+            recovery: recoveryNone({ reasonCode: "replaced_by_newer", url }),
+            url,
+            resolvedDeployment: latest,
+            summary: `${app.name} deploy ${replacedDeployment.id} was replaced — the app is live at ${url} via deploy ${latest.id}.`,
+        };
+    }
+    if (latest.status === "queued" || latest.status === "building" || latest.status === "deploying") {
+        const reasonCode = latest.status === "queued"
+            ? "deploy_queued"
+            : latest.status === "building"
+                ? "deploy_building"
+                : "deploy_deploying";
+        return {
+            recovery: recoveryWait({ app: app.name, deployId: latest.id, reasonCode }),
+            resolvedDeployment: latest,
+            summary: `${app.name} deploy ${replacedDeployment.id} was replaced; the newer deploy ${latest.id} is ${latest.status} — call percher_wait_for_deploy.`,
+        };
+    }
+    // latest is failed or another replaced — there's no clear current
+    // live state. Surface to user; FUTURE12's expanded doctor will own
+    // deeper diagnostics.
+    return {
+        recovery: recoveryAsk({
+            prompt: `${app.name} deploy ${replacedDeployment.id} was replaced, and the latest deploy ${latest.id} is also ${latest.status}. Run \`percher doctor --app ${app.name}\` to diagnose, or surface this to the user.`,
+            reasonCode: "replaced_by_newer",
+        }),
+        resolvedDeployment: latest,
+        summary: `${app.name} deploy ${replacedDeployment.id} was replaced; the latest deploy ${latest.id} is ${latest.status}. Surface to user.`,
+    };
+}
+async function buildReplacedResult(opts) {
+    const { ctx, app, deployment, startedAt } = opts;
+    const resolved = await resolveReplaced({ ctx, app, replacedDeployment: deployment });
+    return {
+        status: "replaced",
+        app: { id: app.id, name: app.name, url: app.url },
+        deployment,
+        url: resolved.url,
+        elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+        totalElapsedSeconds: secondsSinceCreated(deployment),
+        recovery: resolved.recovery,
+        summary: resolved.summary,
+    };
+}
+function buildStillRunningResult(app, deployment, startedAt, networkHint) {
+    return {
+        status: "still_running",
+        app: { id: app.id, name: app.name, url: app.url },
+        deployment,
+        elapsedSeconds: Math.round((Date.now() - startedAt) / 1000),
+        totalElapsedSeconds: secondsSinceCreated(deployment),
+        recovery: recoveryWait({
+            app: app.name,
+            deployId: deployment.id,
+            reasonCode: deployment.status === "queued"
+                ? "deploy_queued"
+                : deployment.status === "building"
+                    ? "deploy_building"
+                    : deployment.status === "deploying"
+                        ? "deploy_deploying"
+                        : "deploy_timeout",
+        }),
+        summary: networkHint
+            ? `${app.name} deploy ${deployment.id} still ${deployment.status} (transient: ${networkHint}) — call percher_wait_for_deploy again.`
+            : `${app.name} deploy ${deployment.id} still ${deployment.status} — call percher_wait_for_deploy again.`,
+    };
+}
+function secondsSinceCreated(deployment) {
+    const t = Date.parse(deployment.createdAt);
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, Math.round((Date.now() - t) / 1000));
+}
+//# sourceMappingURL=wait-deploy.js.map

package/dist/commands/wait-deploy.js.map

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

package/dist/env-scan-source.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A single env reference discovered by the source scanner.
+ *
+ * The scanner inspects an extracted upload tarball before queueing a deploy.
+ * Phase 6c uses these references to enforce the `[env]` contract in
+ * `percher.toml`: any static key not declared in `required`, `optional`, or
+ * `ignore` blocks the deploy with a `fix_config` problem.
+ */
+export interface EnvReference {
+    /** The env key referenced. Empty string when `shape` is `"dynamic"`. */
+    key: string;
+    /** File path relative to the source root (forward slashes). */
+    file: string;
+    /** 1-based line number where the reference appears. */
+    line: number;
+    /** Verbatim source line (trimmed) for diagnostics. */
+    context: string;
+    /** Static (literal key) vs dynamic (e.g. `process.env[varName]`). */
+    shape: "static" | "dynamic";
+}
+export interface ScanOptions {
+    /** Optional list of relative paths to skip on top of the built-in defaults. */
+    exclude?: string[];
+    /**
+     * Files larger than this in bytes are skipped silently (default 1 MiB).
+     * Prevents pathological inputs (minified bundles, huge JSON blobs) from
+     * dominating scan time.
+     */
+    maxFileBytes?: number;
+}
+/**
+ * Recursively scans `rootDir` for env references in supported source files.
+ *
+ * Read-only: never modifies the source tree. Tolerant of unreadable files and
+ * directories — they are skipped silently. Files exceeding `maxFileBytes` are
+ * skipped to bound runtime on pathological inputs (minified bundles, etc.).
+ */
+export declare function scanSourceForEnvRefs(rootDir: string, opts?: ScanOptions): Promise<EnvReference[]>;
+//# sourceMappingURL=env-scan-source.d.ts.map

package/dist/env-scan-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-scan-source.d.ts","sourceRoot":"","sources":["../src/env-scan-source.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6QD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CA+CzB"}