gencow 0.1.193 → 0.1.195

package/bin/gencow.mjs

@@ -38,6 +38,7 @@ import {
   updateEnvLocalUrl,
 } from "../lib/cli-project-runtime.mjs";
 import { createCodegenCommand } from "../lib/codegen-command.mjs";
+import { runCliCommand } from "../lib/cli-command-runner.mjs";
 import { createDoctorCommand } from "../lib/doctor-command.mjs";
 import { maybeCheckCliVersion } from "../lib/cli-version-check.mjs";
 import { updateComponentReadme } from "../lib/component-readme.mjs";
@@ -579,13 +580,10 @@ maybeCheckCliVersion({
   warnImpl: warn,
 });
 
-if (commands[cmd]) {
-  Promise.resolve(commands[cmd](...args)).catch((e) => {
-    error(e.message || String(e));
-    process.exit(1);
-  });
-} else {
-  error(`Unknown command: ${cmd}`);
-  commands.help();
-  process.exit(1);
-}
+process.exitCode = await runCliCommand({
+  args,
+  command: cmd,
+  commands,
+  errorImpl: error,
+  helpImpl: commands.help,
+});

package/lib/app-command.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 import {
@@ -24,6 +25,14 @@ import { updateEnvLocalUrl } from "./cli-project-runtime.mjs";
 // Covers the 60s runtime-observer restart grace plus multiple 5s reconciliation scans.
 const DEFAULT_DELETE_POLL_ATTEMPTS = 75;
 const DELETE_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_APP_CREATE_TIMEOUT_MS = 60_000;
+
+function resolveAppCreateTimeoutMs(value) {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 100 && parsed <= 600_000
+    ? parsed
+    : DEFAULT_APP_CREATE_TIMEOUT_MS;
+}
 
 function appResponseStatus(response) {
   return Number.isSafeInteger(response?.status) ? `HTTP ${response.status}` : "unknown HTTP status";
@@ -105,23 +114,53 @@ async function confirmDelete(name) {
 }
 
 export function createAppCommand({
+  appCreateTimeoutMs = resolveAppCreateTimeoutMs(process.env.GENCOW_APP_CREATE_TIMEOUT_MS),
+  clearTimeoutImpl = clearTimeout,
+  confirmDeleteImpl = confirmDelete,
+  createAbortControllerImpl = () => new AbortController(),
+  createDeleteRequestIdImpl = () => `app_delete_request_${randomUUID()}`,
   cwdImpl = () => process.cwd(),
   loadConfig,
   errorImpl = error,
   infoImpl = info,
   loadCredsImpl = loadCreds,
   logImpl = log,
-  processRef = process,
   requireCredsImpl = requireCreds,
   rpcMutationImpl = rpcMutation,
   rpcQueryImpl = rpcQuery,
   saveCredsImpl = saveCreds,
+  setTimeoutImpl = setTimeout,
   sleepImpl = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
   deletePollAttempts = DEFAULT_DELETE_POLL_ATTEMPTS,
   successImpl = success,
   updateEnvLocalUrlImpl = updateEnvLocalUrl,
   warnImpl = warn,
 }) {
+  const boundedAppCreateTimeoutMs = resolveAppCreateTimeoutMs(appCreateTimeoutMs);
+
+  async function requestAppCreate(creds, name) {
+    const controller = createAbortControllerImpl();
+    const timeoutError = new Error(
+      `App creation request timed out after ${boundedAppCreateTimeoutMs}ms. Please try again.`,
+    );
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+      timeoutHandle = setTimeoutImpl(() => {
+        controller.abort(timeoutError);
+        reject(timeoutError);
+      }, boundedAppCreateTimeoutMs);
+    });
+    try {
+      const request = (async () => {
+        const response = await rpcMutationImpl(creds, "apps.create", { name }, { signal: controller.signal });
+        return { response, data: await readJsonObjectResponse(response) };
+      })();
+      return await Promise.race([request, timeoutPromise]);
+    } finally {
+      clearTimeoutImpl(timeoutHandle);
+    }
+  }
+
   return async function app(subcmd, ...rest) {
     if (subcmd === "--help" || subcmd === "-h" || rest.includes("--help") || rest.includes("-h")) {
       logImpl(`\n${BOLD}${CYAN}gencow app${RESET} — App management\n`);
@@ -131,10 +170,10 @@ export function createAppCommand({
       logImpl(`    ${CYAN}create${RESET}    Create a new app`);
       logImpl(`    ${CYAN}delete${RESET}    Delete an app (confirmation required)`);
       logImpl(`    ${CYAN}status${RESET}    Show app status\n`);
-      return;
+      return 0;
     }
 
-    const creds = requireCredsImpl();
+    const creds = requireCredsImpl({ throwOnMissing: true });
 
     if (!subcmd || subcmd === "list") {
       logImpl(`\n${BOLD}${CYAN}Your Apps${RESET}\n`);
@@ -142,18 +181,16 @@ export function createAppCommand({
       const body = await res.json().catch(() => null);
       if (!res.ok) {
         errorImpl(appResponseError(body, invalidAppResponse("app list", res, "error")));
-        processRef.exit(1);
-        return;
+        return 1;
       }
       const apps = parseAppListResponse(body);
       if (!apps) {
         errorImpl(invalidAppResponse("app list", res, "success"));
-        processRef.exit(1);
-        return;
+        return 1;
       }
       if (!apps.length) {
         infoImpl("No apps yet. Run: gencow app create <name>");
-        return;
+        return 0;
       }
 
       logImpl(`  ${"NAME".padEnd(22)} ${"STATUS".padEnd(12)} ${"URL".padEnd(38)} DEPLOYED`);
@@ -167,29 +204,26 @@ export function createAppCommand({
         );
       }
       logImpl("");
-      return;
+      return 0;
     }
 
     if (subcmd === "create") {
       const name = rest[0];
       if (!name) {
         errorImpl("Usage: gencow app create <name>");
-        processRef.exit(1);
+        return 1;
       }
 
       logImpl(`\n${BOLD}${CYAN}Gencow App Create${RESET}\n`);
       infoImpl(`Creating app "${name}"...`);
-      const res = await rpcMutationImpl(creds, "apps.create", { name });
-      const data = await readJsonObjectResponse(res);
+      const { response: res, data } = await requestAppCreate(creds, name);
       if (!res.ok) {
         errorImpl(appResponseError(data, invalidAppResponse("app create", res, "error")));
-        processRef.exit(1);
-        return;
+        return 1;
       }
       if (!data) {
         errorImpl(invalidAppResponse("app create", res, "success"));
-        processRef.exit(1);
-        return;
+        return 1;
       }
 
       let createdApp;
@@ -197,8 +231,7 @@ export function createAppCommand({
         createdApp = resolveCreatedAppResponse(data, { platformUrl: creds.platformUrl });
       } catch (caught) {
         errorImpl(caught.message);
-        processRef.exit(1);
-        return;
+        return 1;
       }
       const { appId, appUrl } = createdApp;
 
@@ -259,7 +292,7 @@ ${dashboardLine}
 
   ${DIM}pnpm gencow dev   — watch & auto-deploy to cloud + live logs${RESET}
 `);
-      return;
+      return 0;
     }
 
     if (subcmd === "delete") {
@@ -270,20 +303,20 @@ ${dashboardLine}
       const name = rest.find((value) => !value.startsWith("-")) || loadCredsImpl()?.currentApp;
       if (!name || unsupportedOption) {
         errorImpl("Usage: gencow app delete <name> [--force]");
-        processRef.exit(1);
-        return;
+        return 1;
       }
 
       if (!force) {
-        const confirmed = await confirmDelete(name);
+        const confirmed = await confirmDeleteImpl(name);
         if (!confirmed) {
           warnImpl("Cancelled — name did not match.");
-          processRef.exit(0);
+          return 0;
         }
       }
 
       infoImpl(`Deleting app "${name}"...`);
-      const delRes = await rpcMutationImpl(creds, "apps.delete", { name });
+      const requestId = createDeleteRequestIdImpl();
+      const delRes = await rpcMutationImpl(creds, "apps.delete", { name, requestId });
       let delData = await readJsonObjectResponse(delRes);
       if (!isExactAppDeleteResponse(delData, name)) {
         const operationResult = await pollAppDeleteOperation({
@@ -304,8 +337,7 @@ ${dashboardLine}
             invalidAppResponse("app delete", delRes, delRes.ok ? "success" : "error"),
           ),
         );
-        processRef.exit(1);
-        return;
+        return 1;
       }
 
       const currentCreds = loadCredsImpl();
@@ -314,15 +346,14 @@ ${dashboardLine}
       }
 
       successImpl(`App "${name}" deleted`);
-      return;
+      return 0;
     }
 
     if (subcmd === "status") {
       const name = rest[0] || loadCredsImpl()?.currentApp;
       if (!name) {
         errorImpl("Usage: gencow app status <name>");
-        processRef.exit(1);
-        return;
+        return 1;
       }
       const res = await rpcQueryImpl(creds, "apps.get", { name });
       const decoded = await readJsonValueResponse(res);
@@ -333,24 +364,20 @@ ${dashboardLine}
             ? appNotFoundDiagnostic()
             : appResponseError(body, invalidAppResponse("app status", res, "error")),
         );
-        processRef.exit(1);
-        return;
+        return 1;
       }
       if (!decoded.parsed) {
         errorImpl(invalidAppResponse("app status", res, "success"));
-        processRef.exit(1);
-        return;
+        return 1;
       }
       const lookup = parseAppLookupResponse(body, name);
       if (lookup.kind === "not_found") {
         errorImpl(appNotFoundDiagnostic());
-        processRef.exit(1);
-        return;
+        return 1;
       }
       if (lookup.kind === "invalid_response") {
         errorImpl(invalidAppResponse("app status", res, "success"));
-        processRef.exit(1);
-        return;
+        return 1;
       }
       const data = lookup.app;
       logImpl(`\n  ${BOLD}${data.name}${RESET}`);
@@ -377,10 +404,11 @@ ${dashboardLine}
         );
       }
       logImpl("");
-      return;
+      return 0;
     }
 
     errorImpl(`Unknown app subcommand: ${subcmd}`);
     logImpl(`  Usage: gencow app [list|create|delete|status]`);
+    return 1;
   };
 }

package/lib/app-response-error.mjs

@@ -1,6 +1,19 @@
 export const APP_DELETE_OPERATION_PATTERN =
   /^app_delete_(?:[a-f0-9]{32}|[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12})$/u;
 
+const RETRY_CLASSES = new Set(["operator-action", "platform-action", "retryable-infra", "terminal-client"]);
+const USER_ACTIONS = new Set([
+  "CONTACT_SUPPORT",
+  "EDIT_AND_CHECK",
+  "INSPECT_STATE",
+  "OPERATOR_ACTION",
+  "RETRY",
+  "UPGRADE_CLI",
+  "VIEW_DELETE_STATUS",
+  "VIEW_STATUS",
+  "WAIT",
+]);
+
 export function appResponseError(body, fallback) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return fallback;
   const message = typeof body.error === "string" && body.error.trim() ? body.error.trim() : fallback;
@@ -20,5 +33,16 @@ export function appResponseError(body, fallback) {
   if (/^[a-z][a-z0-9_]{2,63}$/u.test(body.state ?? "")) {
     lines.push(`State: ${body.state}`);
   }
+  if (RETRY_CLASSES.has(body.retryClass) && USER_ACTIONS.has(body.userAction)) {
+    lines.push(`Retry class: ${body.retryClass}`);
+    lines.push(`Next action: ${body.userAction}`);
+    if (
+      Number.isSafeInteger(body.retryAfterMs) &&
+      body.retryAfterMs >= 0 &&
+      body.retryAfterMs <= 600_000
+    ) {
+      lines.push(`Retry after: ${body.retryAfterMs}ms`);
+    }
+  }
   return lines.join("\n");
 }

package/lib/cli-command-runner.mjs

@@ -0,0 +1,82 @@
+const SAFE_CORRELATION_ID = /^[A-Za-z0-9_-]{8,128}$/u;
+const SAFE_PLATFORM_ERROR_DETAILS = new Map([
+  ["ACCOUNT_DELETED", "This account has been deleted."],
+  ["ACCOUNT_DELETION_PENDING", "This account is pending deletion."],
+  ["ACCOUNT_SUSPENDED", "This account is suspended."],
+  ["APP_RELEASE_CAPABILITY_UNAVAILABLE", "Release capability is temporarily unavailable."],
+  ["APP_RELEASE_POLICY_READ_UNAVAILABLE", "Release policy is temporarily unavailable."],
+]);
+
+function safePlatformOrigin(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function commandErrorMessage(caught) {
+  if (caught instanceof Error && (caught.message === "APP_RELEASE_AUTH_REQUIRED" || caught.status === 401)) {
+    const lines = ["Login expired or invalid for this Platform."];
+    const platformOrigin = safePlatformOrigin(caught.platformUrl);
+    if (platformOrigin) lines.push(`Platform: ${platformOrigin}`);
+    const credentialEnvName =
+      caught.credentialSource === "environment" &&
+      (caught.credentialEnvName === "GENCOW_TOKEN" || caught.credentialEnvName === "GENCOW_DEPLOY_TOKEN")
+        ? caught.credentialEnvName
+        : null;
+    if (credentialEnvName) {
+      lines.push(`Credential source: ${credentialEnvName}`);
+      lines.push(
+        `Action: replace or unset ${credentialEnvName}; environment credentials override interactive login.`,
+      );
+    } else {
+      lines.push("Run: npx gencow@latest login");
+    }
+    if (typeof caught.correlationId === "string" && SAFE_CORRELATION_ID.test(caught.correlationId)) {
+      lines.push(`Correlation ID: ${caught.correlationId}`);
+    }
+    return lines.join("\n");
+  }
+  if (caught instanceof Error && caught.message) {
+    const platformOrigin = safePlatformOrigin(caught.platformUrl);
+    const correlationId =
+      typeof caught.correlationId === "string" && SAFE_CORRELATION_ID.test(caught.correlationId)
+        ? caught.correlationId
+        : null;
+    if (platformOrigin || correlationId || typeof caught.retryable === "boolean") {
+      const safeDetail = SAFE_PLATFORM_ERROR_DETAILS.get(caught.message);
+      const lines = [safeDetail ? `${caught.message}: ${safeDetail}` : caught.message];
+      if (platformOrigin) lines.push(`Platform: ${platformOrigin}`);
+      if (typeof caught.retryable === "boolean") lines.push(`Retryable: ${caught.retryable ? "yes" : "no"}`);
+      if (correlationId) lines.push(`Correlation ID: ${correlationId}`);
+      return lines.join("\n");
+    }
+  }
+  if (caught instanceof Error && caught.message) return caught.message;
+  return String(caught);
+}
+
+function normalizeCommandExitCode(exitCode) {
+  if (exitCode === undefined || exitCode === 0) return 0;
+  if (exitCode === 1) return 1;
+  throw new Error("CLI command returned an invalid exit code");
+}
+
+export async function runCliCommand({ args, command, commands, errorImpl, helpImpl }) {
+  const handler = Object.hasOwn(commands, command) ? commands[command] : undefined;
+  if (typeof handler !== "function") {
+    errorImpl(`Unknown command: ${command}`);
+    helpImpl();
+    return 1;
+  }
+
+  try {
+    const exitCode = await Reflect.apply(handler, commands, args);
+    return normalizeCommandExitCode(exitCode);
+  } catch (caught) {
+    errorImpl(commandErrorMessage(caught));
+    return 1;
+  }
+}

package/lib/deploy-runtime.mjs

@@ -468,10 +468,7 @@ export function createDeployCommand({
       const declaredStaticClients = Array.isArray(workspaceConfig?.clients)
         ? workspaceConfig.clients.filter((client) => client?.static?.dir)
         : [];
-      const clientSelection = selectClient(
-        declaredStaticClients,
-        cliSelection?.client ?? null,
-      );
+      const clientSelection = selectClient(declaredStaticClients, cliSelection?.client ?? null);
       if (clientSelection.error) {
         errorImpl(clientSelection.error);
         exitImpl(1);
@@ -541,7 +538,9 @@ export function createDeployCommand({
         resolvePathImpl,
       }) || displayName;
     const backendDeployRuntime =
-      backendProjectRoot === cwd ? deployPackageRuntime : createDeployPackageRuntimeForCwd(() => backendProjectRoot);
+      backendProjectRoot === cwd
+        ? deployPackageRuntime
+        : createDeployPackageRuntimeForCwd(() => backendProjectRoot);
 
     if (parsed.existingBundleMode && !appId) {
       errorImpl("--existing-bundle requires an existing app target.");
@@ -607,7 +606,7 @@ export function createDeployCommand({
     }
 
     if (parsed.staticDeploy) {
-      return runStaticDeployFlow({
+      await runStaticDeployFlow({
         appId,
         backendRoot: backendProjectRoot,
         creds,
@@ -659,6 +658,7 @@ export function createDeployCommand({
               })
           : undefined,
       });
+      return 0;
     }
 
     logImpl(`\n${BOLD}${CYAN}Gencow Deploy${RESET}\n`);

package/lib/platform-client.mjs

@@ -27,24 +27,40 @@ export function clearCreds() {
 }
 
 export function resolveCredsFromSources({ env = process.env, loadCredsImpl = loadCreds } = {}) {
-  const envToken = env.GENCOW_TOKEN || env.GENCOW_DEPLOY_TOKEN;
+  const credentialEnvName = env.GENCOW_TOKEN
+    ? "GENCOW_TOKEN"
+    : env.GENCOW_DEPLOY_TOKEN
+      ? "GENCOW_DEPLOY_TOKEN"
+      : null;
+  const envToken = credentialEnvName ? env[credentialEnvName] : null;
   if (envToken) {
     const platformUrl = env.GENCOW_PLATFORM_URL || "https://gencow.app";
-    return { apiKey: envToken, platformUrl: validatePlatformUrl(platformUrl) };
+    return {
+      apiKey: envToken,
+      platformUrl: validatePlatformUrl(platformUrl),
+      credentialSource: "environment",
+      credentialEnvName,
+    };
   }
 
   const creds = loadCredsImpl();
   if (!creds?.apiKey) return null;
   const platformUrl = env.GENCOW_PLATFORM_URL || creds.platformUrl;
   if (platformUrl) {
-    return { ...creds, platformUrl: validatePlatformUrl(platformUrl) };
+    return { ...creds, platformUrl: validatePlatformUrl(platformUrl), credentialSource: "stored" };
   }
-  return creds;
+  return { ...creds, credentialSource: "stored" };
+}
+
+export function formatPlatformCredentialsRequiredMessage({ isCi = Boolean(process.env.CI) } = {}) {
+  return isCi
+    ? "CI environment detected but no credentials found. Set GENCOW_TOKEN in your CI/CD settings."
+    : "Not logged in. Run: gencow login";
 }
 
 export class PlatformCredentialsRequiredError extends Error {
-  constructor() {
-    super("Platform credentials are required");
+  constructor(message = "Platform credentials are required") {
+    super(message);
     this.name = "PlatformCredentialsRequiredError";
   }
 }
@@ -52,7 +68,9 @@ export class PlatformCredentialsRequiredError extends Error {
 export function requireCreds({ throwOnMissing = false } = {}) {
   const creds = resolveCredsFromSources();
   if (!creds?.apiKey) {
-    if (throwOnMissing) throw new PlatformCredentialsRequiredError();
+    if (throwOnMissing) {
+      throw new PlatformCredentialsRequiredError(formatPlatformCredentialsRequiredMessage());
+    }
     if (process.env.CI) {
       error("CI environment detected but no credentials found.");
       info(`Set ${CYAN}GENCOW_TOKEN${RESET} secret in your CI/CD settings.`);
@@ -86,10 +104,11 @@ export async function rpcQuery(creds, queryName, args = {}) {
   });
 }
 
-export async function rpcMutation(creds, mutationName, args = {}) {
+export async function rpcMutation(creds, mutationName, args = {}, requestOptions = {}) {
   return platformFetch(creds, "/api/mutation", {
+    ...requestOptions,
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { ...requestOptions.headers, "Content-Type": "application/json" },
     body: JSON.stringify({ name: mutationName, args }),
   });
 }

package/lib/release-client.mjs

@@ -8,22 +8,87 @@ function releaseRequestId(explicit) {
   return explicit || `release_${randomUUID()}`;
 }
 
-async function responseError(response, fallback) {
-  const body = await response.json().catch(() => ({}));
-  const error = new Error(body.code || fallback);
-  error.detail = body.error || response.statusText;
+const SAFE_CORRELATION_ID = /^[A-Za-z0-9_-]{8,128}$/u;
+const PUBLIC_RELEASE_ERROR_CODES = new Set([
+  "ACCOUNT_DELETED",
+  "ACCOUNT_DELETION_PENDING",
+  "ACCOUNT_SUSPENDED",
+  "APP_RELEASE_APP_NOT_FOUND",
+  "APP_RELEASE_ATTEMPT_NOT_FOUND",
+  "APP_RELEASE_ATTEMPT_TERMINAL",
+  "APP_RELEASE_AUTH_REQUIRED",
+  "APP_RELEASE_CAPABILITY_UNAVAILABLE",
+  "APP_RELEASE_COMPONENT_CONFLICT",
+  "APP_RELEASE_COMPONENT_INCOMPLETE",
+  "APP_RELEASE_COMPONENT_UNEXPECTED",
+  "APP_RELEASE_ENVIRONMENT_INVALID",
+  "APP_RELEASE_ENVIRONMENT_MISMATCH",
+  "APP_RELEASE_ENV_KEYS_MISSING",
+  "APP_RELEASE_IDEMPOTENCY_CONFLICT",
+  "APP_RELEASE_METADATA_INVALID",
+  "APP_RELEASE_POLICY_READ_UNAVAILABLE",
+  "APP_RELEASE_SOURCE_CONFLICT",
+  "APP_RELEASE_SOURCE_INVALID",
+  "APP_RELEASE_STATE_CONFLICT",
+  "APP_RELEASE_STORAGE_QUOTA_EXCEEDED",
+  "APP_RELEASE_VERSIONS_DISABLED",
+  "APP_SERVING_ROUTE_COMMIT_BLOCKED",
+  "APP_SERVING_ROUTE_COMMIT_PENDING",
+  "RELEASE_SOURCE_COMPONENT_MISMATCH",
+]);
+
+function safePlatformOrigin(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function throwResponseError(response, fallback, body, creds = {}) {
+  const authRequired = response.status === 401;
+  const responseCode = PUBLIC_RELEASE_ERROR_CODES.has(body?.code) ? body.code : fallback;
+  const error = new Error(authRequired ? "APP_RELEASE_AUTH_REQUIRED" : responseCode);
   error.status = response.status;
+  const platformOrigin = safePlatformOrigin(creds.platformUrl);
+  if (platformOrigin) error.platformUrl = platformOrigin;
+  if (creds.credentialSource === "environment" || creds.credentialSource === "stored") {
+    error.credentialSource = creds.credentialSource;
+  }
+  if (creds.credentialEnvName === "GENCOW_TOKEN" || creds.credentialEnvName === "GENCOW_DEPLOY_TOKEN") {
+    error.credentialEnvName = creds.credentialEnvName;
+  }
+  if (typeof body.correlationId === "string" && SAFE_CORRELATION_ID.test(body.correlationId)) {
+    error.correlationId = body.correlationId;
+  }
+  error.retryable = authRequired
+    ? false
+    : typeof body.retryable === "boolean"
+      ? body.retryable
+      : response.status >= 500;
   throw error;
 }
 
+async function responseError(response, fallback, creds, parsedBody) {
+  const body = parsedBody ?? ((await response.json().catch(() => ({}))) || {});
+  throwResponseError(response, fallback, body, creds);
+}
+
 async function releaseCapability({ creds, appId, environment, platformFetchImpl }) {
   const response = await platformFetchImpl(
     creds,
     `/platform/apps/${appId}/release-capability?environment=${environment}`,
     { method: "GET" },
   );
-  if (response.status === 404 || response.status === 405) return null;
-  if (!response.ok) await responseError(response, "APP_RELEASE_CAPABILITY_FAILED");
+  if (response.status === 404 || response.status === 405) {
+    const body = (await response.json().catch(() => ({}))) || {};
+    if (typeof body?.code !== "string" || body.code.length === 0) return null;
+    await responseError(response, "APP_RELEASE_CAPABILITY_FAILED", creds, body);
+  }
+  if (!response.ok) {
+    await responseError(response, "APP_RELEASE_CAPABILITY_FAILED", creds);
+  }
   const body = await response.json().catch(() => ({}));
   if (body?.protocol !== "app-release-v1" || typeof body?.enabled !== "boolean") {
     throw new Error("APP_RELEASE_CAPABILITY_RESPONSE_INVALID");
@@ -66,7 +131,9 @@ export async function prepareReleaseAttempt({
       },
       body: sourcePackage.bundleBuffer,
     });
-    if (!response.ok) await responseError(response, "APP_RELEASE_SOURCE_UPLOAD_FAILED");
+    if (!response.ok) {
+      await responseError(response, "APP_RELEASE_SOURCE_UPLOAD_FAILED", creds);
+    }
     const data = await response.json();
     if (!data.attemptId || data.state !== "source_stored") {
       throw new Error("APP_RELEASE_SOURCE_RESPONSE_INVALID");
@@ -97,14 +164,19 @@ export async function finalizeReleaseAttempt({
           body: JSON.stringify({ environment }),
         },
       );
-      if (!response.ok) await responseError(response, "APP_RELEASE_FINALIZE_FAILED");
+      if (!response.ok) {
+        await responseError(response, "APP_RELEASE_FINALIZE_FAILED", creds);
+      }
       const data = await response.json();
       if (!data.release?.id || !Number.isSafeInteger(data.release.version)) {
         throw new Error("APP_RELEASE_FINALIZE_RESPONSE_INVALID");
       }
       return data.release;
     } catch (error) {
-      const retryable = typeof error?.status !== "number" || error.status >= 500;
+      const retryable =
+        typeof error?.retryable === "boolean"
+          ? error.retryable
+          : typeof error?.status !== "number" || error.status >= 500;
       if (!retryable || attempt >= retryDelaysMs.length) throw error;
       await delayImpl(retryDelaysMs[attempt]);
     }
@@ -129,6 +201,8 @@ export async function failReleaseAttempt({
       body: JSON.stringify({ environment, failureStage, failureCode }),
     },
   );
-  if (!response.ok) await responseError(response, "APP_RELEASE_FAIL_RECORD_FAILED");
+  if (!response.ok) {
+    await responseError(response, "APP_RELEASE_FAIL_RECORD_FAILED", creds);
+  }
   return await response.json();
 }