@percher/core 0.2.6 → 0.4.0

package/dist/recovery.js

@@ -0,0 +1,300 @@
+import { TIMEOUTS } from "@percher/shared/timeouts";
+// ── Builders ─────────────────────────────────────────────────────────
+//
+// All recovery construction goes through these. Each builder enforces
+// the required fields for its branch, so a typo or missing field is
+// caught at compile time rather than producing an inline literal that
+// silently violates the contract (e.g. ask_user without prompt).
+/** Success / no-op recovery. `url` is the current live URL when known. */
+export function recoveryNone(opts = {}) {
+    return {
+        retryable: false,
+        nextAction: "none",
+        reasonCode: opts.reasonCode ?? "none",
+        ...(opts.url !== undefined ? { url: opts.url } : {}),
+    };
+}
+/** Authentication required — agent should call `percher_login`. */
+export function recoveryLogin(opts = {}) {
+    return {
+        retryable: false,
+        nextAction: "open_login",
+        suggestedTool: "percher_login",
+        args: {},
+        reasonCode: opts.reasonCode ?? "auth_required",
+    };
+}
+/** Wait on an in-flight deploy — agent should call `percher_wait_for_deploy`. */
+export function recoveryWait(opts) {
+    return {
+        retryable: false,
+        nextAction: "wait_deploy",
+        suggestedTool: "percher_wait_for_deploy",
+        args: {
+            app: opts.app,
+            deployId: opts.deployId,
+            timeoutSeconds: opts.timeoutSeconds ?? TIMEOUTS.mcpWaitDeployDefault / 1000,
+        },
+        reasonCode: opts.reasonCode,
+    };
+}
+/** Route to `percher_doctor` for an ambiguous failure that needs diagnosis. */
+export function recoveryDoctor(opts) {
+    const args = {};
+    if (opts.app !== undefined)
+        args.app = opts.app;
+    if (opts.deployId !== undefined)
+        args.deployId = opts.deployId;
+    if (opts.mode !== undefined)
+        args.mode = opts.mode;
+    return {
+        retryable: false,
+        nextAction: "run_doctor",
+        suggestedTool: "percher_doctor",
+        args,
+        reasonCode: opts.reasonCode,
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+/** Build/runtime needs env keys — agent should call `percher_env_set`. */
+export function recoveryEnv(opts) {
+    const args = {};
+    if (opts.app !== undefined)
+        args.app = opts.app;
+    if (opts.keys.length > 0)
+        args.keys = opts.keys;
+    return {
+        retryable: false,
+        nextAction: "set_env_vars",
+        suggestedTool: "percher_env_set",
+        args,
+        reasonCode: opts.reasonCode ?? "missing_env",
+    };
+}
+/**
+ * `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 function recoveryFixConfig(opts) {
+    return {
+        retryable: false,
+        nextAction: "fix_config",
+        problems: opts.problems,
+        reasonCode: opts.reasonCode ?? "config_invalid",
+    };
+}
+/**
+ * Build failed and the API extracted at least one structured problem
+ * with file/line data — agent should patch the offending file(s).
+ */
+export function recoveryFixProblems(opts) {
+    return {
+        retryable: false,
+        nextAction: "fix_problems",
+        problems: opts.problems,
+        reasonCode: opts.reasonCode ?? "build_failed",
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+/** Transient infra failure — agent can re-issue the same call. */
+export function recoveryRetry(opts) {
+    return {
+        retryable: true,
+        nextAction: "retry",
+        suggestedTool: opts.suggestedTool,
+        args: opts.args,
+        reasonCode: opts.reasonCode,
+    };
+}
+/**
+ * Human-input required. `prompt` MUST be a concrete question — agents
+ * surface it verbatim, so empty/placeholder strings violate the
+ * contract.
+ */
+export function recoveryAsk(opts) {
+    if (!opts.prompt || opts.prompt.trim().length === 0) {
+        throw new Error("recoveryAsk requires a non-empty prompt");
+    }
+    return {
+        retryable: opts.retryable ?? false,
+        nextAction: "ask_user",
+        prompt: opts.prompt,
+        ...(opts.options !== undefined ? { options: opts.options } : {}),
+        reasonCode: opts.reasonCode,
+    };
+}
+/**
+ * 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 function recoveryInspectBuildLog(opts) {
+    const args = opts.deployId
+        ? { id: opts.deployId, app: opts.app }
+        : { latestFailed: true, app: opts.app };
+    return {
+        retryable: false,
+        nextAction: "inspect_build_log",
+        suggestedTool: "percher_deploys_inspect",
+        args,
+        reasonCode: opts.reasonCode ?? "build_failed",
+        ...(opts.alternativeActions !== undefined
+            ? { alternativeActions: opts.alternativeActions }
+            : {}),
+    };
+}
+// ── Legacy const exports ─────────────────────────────────────────────
+//
+// Kept as concrete values so existing call-sites compile until they
+// migrate to the builders directly. Each is just the corresponding
+// builder evaluated with default reasonCode.
+/** Recovery on the success path. */
+export const RECOVERY_NONE = recoveryNone();
+/** Recovery for the unauthenticated path. */
+export const RECOVERY_NEEDS_LOGIN = recoveryLogin();
+/**
+ * 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 function buildProblemToRecoveryProblem(p) {
+    // p.file is optional on BuildProblem but the caller filters to
+    // file-bearing problems before reaching here.
+    const file = p.file ?? "";
+    const message = p.hint && p.hint.length > 0 ? `${p.message}\nHint: ${p.hint}` : p.message;
+    return {
+        file,
+        ...(typeof p.line === "number" ? { line: p.line } : {}),
+        ...(typeof p.column === "number" ? { column: p.column } : {}),
+        message,
+    };
+}
+/**
+ * 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 function recoveryFromErrorClass(errorClass, failure = {}) {
+    switch (errorClass) {
+        case "missing_env":
+            return recoveryEnv({
+                keys: failure.missingEnvVars ?? [],
+                reasonCode: "missing_env",
+            });
+        case "infra_unavailable":
+            return recoveryRetry({
+                suggestedTool: "percher_publish",
+                args: failure.publishInput ?? {},
+                reasonCode: "infra_unavailable",
+            });
+        case "config_invalid":
+            return recoveryFixConfig({
+                problems: [
+                    {
+                        file: "percher.toml",
+                        message: "percher.toml failed validation — fix the file and re-run.",
+                    },
+                ],
+                reasonCode: "config_invalid",
+            });
+        case "build_failed":
+        case "missing_dependency":
+        case "health_check_timeout":
+        case "port_mismatch":
+        case "permission_denied":
+        case "runtime_crash":
+        case "oom_killed": {
+            // FUTURE1 Phase 2.3: when the API parser extracted at least one
+            // problem WITH a file location, give the agent a structured
+            // `fix_problems` recovery instead of routing through doctor.
+            // Problems without a file (missing-module by bare name,
+            // missing-build-env) are still actionable by hint but the agent
+            // has nothing to open — let doctor classify those so it can pull
+            // the build log and decide between set_env_vars / ask_user / etc.
+            const fileProblems = (failure.problems ?? []).filter((p) => p.file);
+            const reproduceAlt = failure.deployId
+                ? {
+                    action: "reproduce_locally",
+                    suggestedTool: "percher_reproduce",
+                    args: { deployId: failure.deployId, app: failure.appName },
+                    when: "after the primary path didn't surface a clear fix and the user has nixpacks installed locally",
+                }
+                : undefined;
+            if (fileProblems.length > 0) {
+                return recoveryFixProblems({
+                    problems: fileProblems.map(buildProblemToRecoveryProblem),
+                    reasonCode: "build_failed",
+                    ...(reproduceAlt
+                        ? {
+                            alternativeActions: [
+                                {
+                                    ...reproduceAlt,
+                                    when: "after fixing the file-located problems didn't make the build pass and the user has nixpacks installed locally",
+                                },
+                            ],
+                        }
+                        : {}),
+                });
+            }
+            // FUTURE12 Phase 4: route ambiguous build failures through
+            // `percher_doctor` instead of straight to `inspect_build_log`.
+            // Doctor's deploy-mode dispatch (Phase 2c) fetches the build
+            // log, runs `classifyError`, and returns a more specific
+            // recovery (`set_env_vars` when missing env keys are extracted,
+            // `fix_problems` when structured BuildProblems with file
+            // locations are extracted, falling back to `inspect_build_log`
+            // only when classification yields nothing). Publish/wait don't
+            // always have the build log when they hit this path, so handing
+            // off to doctor closes the loop with one consistent contract for
+            // agents.
+            //
+            // `inspect_build_log` is preserved as an `alternativeAction` so
+            // agents that want the raw log can still opt in after doctor's
+            // primary recovery doesn't help. Reproduce-locally chains after
+            // that for users with nixpacks installed.
+            const inspectAlt = {
+                action: "inspect_build_log",
+                suggestedTool: "percher_deploys_inspect",
+                args: failure.deployId
+                    ? { id: failure.deployId, app: failure.appName }
+                    : { latestFailed: true, app: failure.appName },
+                when: "after percher_doctor's recovery didn't yield a fix and you want to read the raw build log directly",
+            };
+            const alternativeActions = [inspectAlt];
+            if (reproduceAlt) {
+                alternativeActions.push({
+                    ...reproduceAlt,
+                    when: "after percher_doctor + percher_deploys_inspect didn't surface a clear fix and the user has nixpacks installed locally",
+                });
+            }
+            return recoveryDoctor({
+                app: failure.appName,
+                deployId: failure.deployId,
+                mode: "deploy",
+                reasonCode: "build_failed",
+                alternativeActions,
+            });
+        }
+        default:
+            // Exhaustiveness fallback. New `ErrorClass` values land here until a
+            // mapping is added — better than misclassifying as `retry`.
+            return recoveryAsk({
+                prompt: "Unexpected failure — Percher couldn't classify this error. Try `percher doctor` for diagnostics, or surface the error to the user.",
+                reasonCode: "unknown",
+            });
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

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

package/dist/stream-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cross-runtime streaming file write.
+ *
+ * Both the CLI and MCP server advertise Node.js compatibility
+ * (`npx percher`, `npx -y @percher/mcp`). The core package must not
+ * call Bun globals directly.
+ *
+ * In Bun: Bun.write(path, Response) streams to disk natively and
+ * returns the byte count — zero intermediate allocation.
+ *
+ * In Node.js 18+: we use Readable.fromWeb() + pipeline() to pipe the
+ * Web ReadableStream from the fetch Response to a fs.createWriteStream.
+ * The byte count is read back from fs.stat after the pipeline finishes.
+ */
+/**
+ * Node.js fallback — exported for direct testing so we don't need to
+ * mask the read-only Bun global in tests.
+ */
+export declare function writeResponseToFileNode(res: Response, filePath: string): Promise<number>;
+export declare function writeResponseToFile(res: Response, filePath: string): Promise<number>;
+//# sourceMappingURL=stream-utils.d.ts.map

package/dist/stream-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../src/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB9F;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1F"}

package/dist/stream-utils.js

@@ -0,0 +1,41 @@
+/**
+ * Cross-runtime streaming file write.
+ *
+ * Both the CLI and MCP server advertise Node.js compatibility
+ * (`npx percher`, `npx -y @percher/mcp`). The core package must not
+ * call Bun globals directly.
+ *
+ * In Bun: Bun.write(path, Response) streams to disk natively and
+ * returns the byte count — zero intermediate allocation.
+ *
+ * In Node.js 18+: we use Readable.fromWeb() + pipeline() to pipe the
+ * Web ReadableStream from the fetch Response to a fs.createWriteStream.
+ * The byte count is read back from fs.stat after the pipeline finishes.
+ */
+/**
+ * Node.js fallback — exported for direct testing so we don't need to
+ * mask the read-only Bun global in tests.
+ */
+export async function writeResponseToFileNode(res, filePath) {
+    if (!res.body)
+        throw new Error("Server returned empty response body");
+    const { createWriteStream } = await import("node:fs");
+    const { stat } = await import("node:fs/promises");
+    const { Readable } = await import("node:stream");
+    const { pipeline } = await import("node:stream/promises");
+    const fileStream = createWriteStream(filePath);
+    // fromWeb converts a WHATWG ReadableStream to a Node.js Readable.
+    // The cast is needed because TypeScript's Node typedefs require
+    // stream.web.ReadableStream but fetch returns the global ReadableStream.
+    const nodeReadable = Readable.fromWeb(res.body);
+    await pipeline(nodeReadable, fileStream);
+    const { size } = await stat(filePath);
+    return size;
+}
+export async function writeResponseToFile(res, filePath) {
+    if (typeof Bun !== "undefined") {
+        return Bun.write(filePath, res);
+    }
+    return writeResponseToFileNode(res, filePath);
+}
+//# sourceMappingURL=stream-utils.js.map

package/dist/stream-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.js","sourceRoot":"","sources":["../src/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,GAAa,EAAE,QAAgB;IAC3E,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAEtE,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAClD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACjD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAE1D,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,kEAAkE;IAClE,gEAAgE;IAChE,yEAAyE;IACzE,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CACnC,GAAG,CAAC,IAAyD,CAC9D,CAAC;IACF,MAAM,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAEzC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAa,EAAE,QAAgB;IACvE,IAAI,OAAO,GAAG,KAAK,WAAW,EAAE,CAAC;QAC/B,OAAQ,GAAyE,CAAC,KAAK,CACrF,QAAQ,EACR,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO,uBAAuB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC"}

package/dist/structured-error-codes.d.ts

@@ -0,0 +1,30 @@
+import type { ClassifiedError } from "./error-classifier";
+/**
+ * Phase 4 of the publish-resilience plan — CLI-side mapping from
+ * the canonical `DeployErrorCode` strings (defined server-side in
+ * `@percher/api/src/worker/error-codes.ts`) to the
+ * `ClassifiedError` shape the CLI's publish-failure renderer
+ * already consumes.
+ *
+ * Why this lives in @percher/core instead of @percher/client: the
+ * client surfaces the raw `errorCode` string on `Deployment` and
+ * stays unopinionated; the core package owns the rendering of
+ * publish failures and is the right place to decide "given this
+ * canonical code, what title/explanation/suggestion does the user
+ * see". The CLI's `publish-failure.ts` calls into this module
+ * BEFORE the regex-based `classifyError` so the structured code
+ * always wins when present.
+ *
+ * Set parity: the strings here MUST match the ones in the API's
+ * `DEPLOY_ERROR_CODES` const. Adding a new code requires updating
+ * both files. Forward-compat: an unknown code returns null, the
+ * CLI falls back to the regex classifier, no breakage.
+ */
+export type DeployErrorCode = "WORKER_UNAVAILABLE" | "WORKER_UNAVAILABLE_PERSISTENT" | "BUILD_TIMEOUT" | "BUILD_FAILED" | "WORKER_ERROR" | "DEPLOY_STALLED";
+/**
+ * Map a canonical Phase 4 error code to a {@link ClassifiedError}.
+ * Returns null for NULL / unknown codes so the caller can fall back
+ * to the regex-based `classifyError`.
+ */
+export declare function classifyByErrorCode(code: string | null | undefined, rawMessage: string): ClassifiedError | null;
+//# sourceMappingURL=structured-error-codes.d.ts.map

package/dist/structured-error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-error-codes.d.ts","sourceRoot":"","sources":["../src/structured-error-codes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,oBAAoB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,+BAA+B,GAC/B,eAAe,GACf,cAAc,GACd,cAAc,GACd,gBAAgB,CAAC;AAoFrB;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GACjB,eAAe,GAAG,IAAI,CAcxB"}

package/dist/structured-error-codes.js

@@ -0,0 +1,86 @@
+const MAPPINGS = {
+    WORKER_UNAVAILABLE: {
+        errorClass: "infra_unavailable",
+        phase: "infra",
+        cause: "worker_fetch_failed",
+        title: "Build worker is unreachable",
+        explanation: (raw) => raw
+            ? `The Percher build worker did not respond in time: ${trimMessage(raw)}. This is a platform-side issue, not your code.`
+            : "The Percher build worker did not respond in time. This is a platform-side issue, not your code.",
+        suggestion: "Wait 30 seconds and run `percher publish` again. If retry #2 also fails, pause 5 minutes before the next attempt — back-to-back retries during a partial outage just waste your time. After 3 spaced-out retries, check status.percher.app or contact support. Your build never started.",
+    },
+    WORKER_UNAVAILABLE_PERSISTENT: {
+        errorClass: "infra_unavailable",
+        phase: "infra",
+        cause: "worker_circuit_breaker_open",
+        title: "Build worker is in a crash loop",
+        explanation: () => "The Percher build worker has failed repeatedly in the last minute and the platform's circuit breaker has flipped open. Retrying immediately would just queue more failures.",
+        suggestion: "Wait 2-3 minutes for the platform to recover, then retry. If it persists past 5 minutes check status.percher.app or contact support — this is a platform incident, not your code.",
+    },
+    BUILD_TIMEOUT: {
+        errorClass: "build_failed",
+        phase: "build",
+        cause: "build_timeout",
+        title: "Build timed out",
+        explanation: () => "The build ran longer than the 10-minute platform limit and was aborted.",
+        suggestion: "Common causes: a slow `postinstall` hook, very large dependency tree, or a Dockerfile that pulls a huge base image. Try `bun install` locally and check what's slow. If it's legitimately a heavy build, contact support to discuss raising the limit for your account.",
+    },
+    BUILD_FAILED: {
+        errorClass: "build_failed",
+        phase: "build",
+        cause: "build_nonzero_exit",
+        title: "Build failed",
+        explanation: (raw) => raw
+            ? `The build process returned a non-zero exit code: ${trimMessage(raw)}. Read the build log below for the exact error.`
+            : "The build process returned a non-zero exit code. Read the build log below for the exact error.",
+        suggestion: "Run your build locally to reproduce: `bun install && bun run build`. The error in the build log usually points to a missing dependency, a TypeScript/syntax error, or a misconfigured framework setting.",
+    },
+    WORKER_ERROR: {
+        errorClass: "infra_unavailable",
+        phase: "infra",
+        cause: "worker_internal_error",
+        title: "Platform error inside the build worker",
+        explanation: (raw) => raw
+            ? `The build worker hit an internal error: ${trimMessage(raw)}. This is a Percher bug, not your code.`
+            : "The build worker hit an internal error. This is a Percher bug, not your code.",
+        suggestion: "Retry once — transient platform errors usually clear within a minute. If it repeats, please report it: include the deploy ID and we'll investigate. Your account is not at fault.",
+    },
+    DEPLOY_STALLED: {
+        errorClass: "infra_unavailable",
+        phase: "infra",
+        cause: "deploy_stalled",
+        title: "Deploy stalled",
+        explanation: () => "The platform abandoned this deploy — likely because the API or build worker restarted mid-build. Your code is fine; the build never finished.",
+        suggestion: "Run `percher publish` again. The new deploy will start fresh. If you see this repeatedly across multiple publishes, check status.percher.app — it implies a recurring platform issue.",
+    },
+};
+/**
+ * Map a canonical Phase 4 error code to a {@link ClassifiedError}.
+ * Returns null for NULL / unknown codes so the caller can fall back
+ * to the regex-based `classifyError`.
+ */
+export function classifyByErrorCode(code, rawMessage) {
+    if (!code)
+        return null;
+    const mapping = MAPPINGS[code];
+    if (!mapping)
+        return null;
+    return {
+        title: mapping.title,
+        explanation: mapping.explanation(rawMessage),
+        suggestion: mapping.suggestion,
+        errorClass: mapping.errorClass,
+        phase: mapping.phase,
+        cause: mapping.cause,
+        relevantFiles: [],
+        missingEnvVars: [],
+    };
+}
+function trimMessage(raw) {
+    // Keep the first line + truncate. The CLI already shows the
+    // full build-log tail below; this is just enough context to
+    // explain WHY the platform-side classifier picked this code.
+    const firstLine = raw.split("\n")[0] ?? "";
+    return firstLine.length > 200 ? `${firstLine.slice(0, 200)}…` : firstLine;
+}
+//# sourceMappingURL=structured-error-codes.js.map

package/dist/structured-error-codes.js.map

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

package/dist/tarball.d.ts

@@ -12,6 +12,17 @@ export interface TarballResult {
         path: string;
         size: number;
     }>;
+    /**
+     * Phase 7.8 follow-up — deterministic content-hash of the bundle.
+     * Used by the CLI's cache-probe call so identical sources hash to
+     * the same value across runs. Distinct from the gzipped-bytes hash
+     * the API computes on upload (which carries embedded mtimes from
+     * tar/gzip headers and therefore *cannot* be deterministic). The
+     * CLI sends this value as the `X-Tarball-Hash` header on the
+     * upload; the API stores it on `deployments.tarball_hash` so a
+     * subsequent probe matches.
+     */
+    contentHash: string;
 }
 export declare function createTarball(options: TarballOptions): Promise<TarballResult>;
 //# sourceMappingURL=tarball.d.ts.map

package/dist/tarball.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../src/tarball.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAiCD,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA2CnF"}
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../src/tarball.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD;;;;;;;;;OASG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAiCD,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAgEnF"}

package/dist/tarball.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -45,18 +46,34 @@ export async function createTarball(options) {
     }
     if (options.extraIgnore)
         ig.add(options.extraIgnore);
-    const files = [];
+    // Sorted entries — required for the deterministic content-hash
+    // below. Without this, readdirSync's platform-dependent order
+    // produces a different hash on every run even for unchanged
+    // sources, and cache-probe never matches. Codex P2, 2026-05-08.
+    const fileBuffers = [];
     for (const rel of walk(options.cwd, options.cwd, ig)) {
-        const stats = statSync(join(options.cwd, rel));
-        files.push({ path: rel, size: stats.size });
+        const data = readFileSync(join(options.cwd, rel));
+        fileBuffers.push({ path: rel, size: data.length, data });
     }
-    const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+    fileBuffers.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const totalBytes = fileBuffers.reduce((sum, f) => sum + f.size, 0);
+    // Deterministic content-hash: SHA-256 over a canonical encoding of
+    // every file's path + bytes, in sorted order. The encoding uses
+    // length-prefixed sections so a path containing a delimiter can't
+    // collide with a longer/shorter path of the same prefix.
+    const contentHasher = createHash("sha256");
+    for (const f of fileBuffers) {
+        contentHasher.update(`PATH:${f.path.length}:${f.path}\n`);
+        contentHasher.update(`SIZE:${f.size}\n`);
+        contentHasher.update(f.data);
+        contentHasher.update("\n");
+    }
+    const contentHash = contentHasher.digest("hex");
     const pack = tarPack();
     (async () => {
-        for (const file of files) {
-            const data = readFileSync(join(options.cwd, file.path));
+        for (const file of fileBuffers) {
             await new Promise((resolve, reject) => {
-                pack.entry({ name: file.path, size: data.length }, data, (err) => err ? reject(err) : resolve());
+                pack.entry({ name: file.path, size: file.data.length }, file.data, (err) => err ? reject(err) : resolve());
             });
         }
         pack.finalize();
@@ -64,12 +81,16 @@ export async function createTarball(options) {
     const gzip = createGzip();
     const nodeStream = pack.pipe(gzip);
     const webStream = Readable.toWeb(nodeStream);
-    const topFiles = [...files].sort((a, b) => b.size - a.size).slice(0, 5);
+    const topFiles = [...fileBuffers]
+        .sort((a, b) => b.size - a.size)
+        .slice(0, 5)
+        .map((f) => ({ path: f.path, size: f.size }));
     return {
         stream: webStream,
         bytes: totalBytes,
-        fileCount: files.length,
+        fileCount: fileBuffers.length,
         topFiles,
+        contentHash,
     };
 }
 //# sourceMappingURL=tarball.js.map

package/dist/tarball.js.map

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

package/dist/templates/ai-files/claude-md.d.ts

@@ -0,0 +1,7 @@
+export declare const CLAUDE_MD: {
+    id: "claude-md";
+    path: string;
+    version: string;
+    content: string;
+};
+//# sourceMappingURL=claude-md.d.ts.map

package/dist/templates/ai-files/claude-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../../../src/templates/ai-files/claude-md.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;CA4ErB,CAAC"}