gencow 0.1.261 → 0.1.262

package/lib/app-response-error.mjs

@@ -24,6 +24,7 @@ import {
 
 export { APP_DELETE_OPERATION_PATTERN } from "./app-delete-diagnostic.mjs";
 
+const APP_DELETE_DIAGNOSTIC_STAGES = new Set(["admission", "runtime-stop", "tenant-database", "catalog-finalize"]);
 const RETRY_CLASSES = new Set(["operator-action", "platform-action", "retryable-infra", "terminal-client"]);
 const USER_ACTIONS = new Set([
   "CONTACT_SUPPORT",
@@ -102,8 +103,13 @@ export function appResponseError(body, fallback, response = null, options = {})
   if (/^[A-Za-z0-9_-]{8,128}$/u.test(body.correlationId ?? "")) {
     lines.push(`Correlation ID: ${body.correlationId}`);
   }
-  if (body.stage === "admission") lines.push("Stage: admission");
-  if (body.stateImpact === "This deletion request made no ownership or resource change.") {
+  // Delete-stage diagnoses from the Platform name the failed stage and its state impact.
+  if (APP_DELETE_DIAGNOSTIC_STAGES.has(body.stage)) lines.push(`Stage: ${body.stage}`);
+  if (
+    APP_DELETE_DIAGNOSTIC_STAGES.has(body.stage) &&
+    typeof body.stateImpact === "string" &&
+    /^[A-Za-z0-9 ,.;:-]{1,200}$/u.test(body.stateImpact)
+  ) {
     lines.push(`State impact: ${body.stateImpact}`);
   }
   if (typeof body.retryPrecondition === "string" &&

package/lib/env-command.mjs

@@ -10,6 +10,56 @@ import { resolveCloudAppTarget } from "./cloud-targets.mjs";
 import { BOLD, CYAN, DIM, GREEN, RESET, error, info, log, success, warn } from "./output.mjs";
 import { platformFetch, requireCreds } from "./platform-client.mjs";
 
+const ENV_RESPONSE_UNREADABLE_CODE = "ENV_RESPONSE_UNREADABLE";
+
+// Reads a failed platform response. A JSON `null`, an empty body, or a non-object body
+// normalizes to `message: null`, so callers never dereference the parsed value.
+async function readEnvErrorResponse(response) {
+  const parsed = await response.json().catch(() => null);
+  const body = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  const message = typeof body?.error === "string" && body.error.trim() ? body.error.trim() : null;
+  return { ...envResponseFacts(response), message };
+}
+
+function envResponseFacts(response) {
+  const correlationId = response.headers?.get?.("x-correlation-id") ?? null;
+  return {
+    status: response.status,
+    correlationId: /^[A-Za-z0-9_-]{8,128}$/u.test(correlationId ?? "") ? correlationId : null,
+  };
+}
+
+// A typed `{error}` text is kept verbatim. Without one, the CLI uses the same labels as
+// renderProjectionResult, with state reported as unknown because the CLI cannot observe it.
+function formatEnvErrorMessage(failure, { stage, checkCommand, retryable = isRetryableEnvStatus(failure.status) }) {
+  if (failure.message) return failure.message;
+  return [
+    "Platform returned an empty or unreadable error response",
+    `Code: ${ENV_RESPONSE_UNREADABLE_CODE}`,
+    `Stage: ${stage}`,
+    `HTTP ${failure.status}`,
+    failure.correlationId ? `Correlation ID: ${failure.correlationId}` : null,
+    "Catalog changed: unknown",
+    "Serving process changed: unknown",
+    `Retryable: ${retryable ? "yes" : "no"}`,
+    `Next action: run ${checkCommand}, then retry only if the change is not applied.`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function isRetryableEnvStatus(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+
+function envTargetFlags(appId, envTarget) {
+  return envTarget === "prod" ? "--prod" : `--app ${appId}`;
+}
+
+function envListCommand(appId, envTarget) {
+  return `gencow env list ${envTargetFlags(appId, envTarget)}`;
+}
+
 export function sanitizeCloudEnvKey(rawKey) {
   return rawKey
     .trim()
@@ -86,29 +136,36 @@ export function createEnvCommand(deps = {}) {
   const sleepImpl = deps.sleep ?? ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms)));
   const projectionPollAttempts = deps.projectionPollAttempts ?? 40;
 
-  async function loadProjectionStatus(creds, appId, operationId) {
+  async function loadProjectionStatus(creds, appId, operationId, envTarget) {
     const response = await platformFetchImpl(
       creds,
       `/platform/apps/${appId}/env/operations/${encodeURIComponent(operationId)}`,
       { method: "GET" },
     );
-    const body = await response.json().catch(() => ({}));
-    if (!response.ok) throw new Error(body.error || `HTTP ${response.status}`);
-    return body;
+    if (!response.ok) {
+      throw new Error(
+        formatEnvErrorMessage(await readEnvErrorResponse(response), {
+          stage: "env_status",
+          checkCommand: `gencow env status --operation ${operationId} ${envTargetFlags(appId, envTarget)}`,
+        }),
+      );
+    }
+    const body = await response.json().catch(() => null);
+    return body && typeof body === "object" ? body : {};
   }
 
-  async function waitForProjection(creds, appId, initial) {
+  async function waitForProjection(creds, appId, initial, envTarget) {
     if (!initial?.operationId || initial.runtimeState !== "pending") return initial ?? {};
     let current = initial;
     for (let attempt = 0; attempt < projectionPollAttempts; attempt += 1) {
       await sleepImpl(Number(current.retryAfterMs) || 500);
       try {
-        current = await loadProjectionStatus(creds, appId, initial.operationId);
+        current = await loadProjectionStatus(creds, appId, initial.operationId, envTarget);
       } catch {
         return {
           ...current,
           statusQueryFailed: true,
-          nextAction: `Run gencow env status --operation ${initial.operationId}`,
+          nextAction: `Run gencow env status --operation ${initial.operationId} ${envTargetFlags(appId, envTarget)}`,
         };
       }
       if (current.runtimeState !== "pending") return current;
@@ -205,7 +262,7 @@ export function createEnvCommand(deps = {}) {
         return;
       }
       try {
-        return renderProjectionResult(await loadProjectionStatus(creds, appId, operationId));
+        return renderProjectionResult(await loadProjectionStatus(creds, appId, operationId, envTarget));
       } catch (e) {
         error(`Failed to fetch env operation: ${e.message}`);
         return 1;
@@ -223,7 +280,20 @@ export function createEnvCommand(deps = {}) {
           const reason = typeof body?.error === "string" && body.error ? body.error : null;
           throw new Error(reason ?? `HTTP ${res.status}`);
         }
-        const vars = await res.json();
+        const vars = await res.json().catch(() => null);
+        if (!Array.isArray(vars)) {
+          throw new Error(
+            formatEnvErrorMessage(
+              { ...envResponseFacts(res), message: null },
+              {
+                stage: "env_list",
+                checkCommand: envListCommand(appId, envTarget),
+                // A successful list read is side-effect free, so retrying it is safe.
+                retryable: true,
+              },
+            ),
+          );
+        }
 
         log(
           `\n${BOLD}Environment Variables${RESET}  ${DIM}(cloud: ${appId}, ${envTarget}, ${vars.length} total)${RESET}\n`,
@@ -297,11 +367,15 @@ export function createEnvCommand(deps = {}) {
             body: JSON.stringify({ key: name, value, env: envTarget }),
           });
           if (!res.ok) {
-            const body = await res.json().catch(() => ({}));
-            throw new Error(body.error || `HTTP ${res.status}`);
+            throw new Error(
+              formatEnvErrorMessage(await readEnvErrorResponse(res), {
+                stage: "env_set",
+                checkCommand: envListCommand(appId, envTarget),
+              }),
+            );
           }
           const mutation = await res.json().catch(() => ({}));
-          const projection = await waitForProjection(creds, appId, mutation);
+          const projection = await waitForProjection(creds, appId, mutation, envTarget);
           const projectionExitCode = renderProjectionResult(projection);
           if (projectionExitCode === 0) {
             success(`Stored ${BOLD}${name}${RESET} ${DIM}(cloud: ${appId}, ${envTarget})${RESET}`);
@@ -346,11 +420,15 @@ export function createEnvCommand(deps = {}) {
             },
           );
           if (!res.ok) {
-            const body = await res.json().catch(() => ({}));
-            throw new Error(body.error || `HTTP ${res.status}`);
+            throw new Error(
+              formatEnvErrorMessage(await readEnvErrorResponse(res), {
+                stage: "env_unset",
+                checkCommand: envListCommand(appId, envTarget),
+              }),
+            );
           }
           const mutation = await res.json().catch(() => ({}));
-          const projection = await waitForProjection(creds, appId, mutation);
+          const projection = await waitForProjection(creds, appId, mutation, envTarget);
           const projectionExitCode = renderProjectionResult(projection);
           if (projectionExitCode === 0) {
             success(`Removed ${BOLD}${key}${RESET} ${DIM}(cloud: ${appId}, ${envTarget})${RESET}`);
@@ -435,15 +513,19 @@ export function createEnvCommand(deps = {}) {
           body: JSON.stringify({ vars, env: envTarget }),
         });
         if (!res.ok) {
-          const body = await res.json().catch(() => ({}));
-          throw new Error(body.error || `HTTP ${res.status}`);
+          throw new Error(
+            formatEnvErrorMessage(await readEnvErrorResponse(res), {
+              stage: "env_push",
+              checkCommand: envListCommand(appId, envTarget),
+            }),
+          );
         }
-        const data = await res.json();
+        const data = (await res.json().catch(() => null)) ?? {};
         for (const key of Object.keys(vars)) {
           success(`${key}`);
         }
         log(`\n  ${GREEN}${data.count || count} set${RESET} ${DIM}(cloud: ${appId}, ${envTarget})${RESET}`);
-        commandFailed = renderProjectionResult(await waitForProjection(creds, appId, data)) !== 0;
+        commandFailed = renderProjectionResult(await waitForProjection(creds, appId, data, envTarget)) !== 0;
       } catch (e) {
         error(`Failed to push env vars: ${e.message}`);
         commandFailed = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gencow",
-  "version": "0.1.261",
+  "version": "0.1.262",
   "description": "Gencow — AI Backend Engine",
   "type": "module",
   "bin": {
@@ -40,11 +40,11 @@
     "ai": "^6.0.314",
     "better-auth": "1.7.11",
     "postgres": "^3.4.9",
-    "@gencow/react": "0.2.8",
     "@gencow/client": "0.2.8",
-    "@gencow/server": "0.1.3",
     "@gencow/core": "0.1.47",
-    "@gencow/shared": "0.0.0"
+    "@gencow/shared": "0.0.0",
+    "@gencow/react": "0.2.8",
+    "@gencow/server": "0.1.3"
   },
   "scripts": {
     "build": "node scripts/bundle-core.mjs && node scripts/bundle-shared.mjs && node scripts/bundle-server.mjs",