gencow 0.1.260 → 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/cli-command-runner.mjs

@@ -86,6 +86,11 @@ const SAFE_LOCAL_ERROR_CODES = new Map([
       message: "Deploy stopped before upload: a backend source file could not be loaded.",
       stage: "codegen",
       action: (caught) => {
+        if (safeMissingExportName(caught)) {
+          const name = safeMissingExportName(caught);
+          const where = safeSourceLocation(caught) ? "at the location above " : "";
+          return `Retryable: yes, after the import of "${name}" ${where}names an export its module does not have — use an exported name, or export it from that module, then run \`npx gencow@latest codegen\` to confirm it passes, then rerun your deploy command.`;
+        }
         const cause =
           "the top-level code that throws during module load, or an import path that does not resolve (check the path and that the imported package is installed)";
         if (safeSourceLocation(caught)) {
@@ -169,6 +174,13 @@ function safeDisplayDir(caught) {
 }
 const SAFE_SOURCE_LOCATION_PATH = /^(?![/\\])(?!.*(?:^|\/)\.\.(?:\/|$))[^\u0000-\u001f\u007f]{1,240}$/u;
 
+const SAFE_IMPORT_NAME = /^[A-Za-z_$][\w$]{0,127}$/u;
+
+function safeMissingExportName(caught) {
+  const { missingExport } = caught;
+  return typeof missingExport === "string" && SAFE_IMPORT_NAME.test(missingExport) ? missingExport : null;
+}
+
 function safeSourceLocation(caught) {
   const { sourceFile, line, column } = caught;
   if (typeof sourceFile !== "string" || !SAFE_SOURCE_LOCATION_PATH.test(sourceFile)) return null;

package/lib/deploy-codegen-failure.mjs

@@ -36,13 +36,24 @@ function toProjectRelativePath(rawPath, cwd, processCwd) {
 // esbuild prints one diagnostic per line (`<file>:<line>:<col>: ERROR: <text>`) and the
 // Bun loader prints `Could not resolve`/`Cannot find module` for an import path that does
 // not exist. Those are load failures: the source is well-formed, its import is not.
+// `No matching export` is an import of a name its module does not export (esbuild, or the
+// named-import check in codegen-named-import-check.ts); the module itself is well-formed.
 const DIAGNOSTIC_LINE_PATTERN = /ERROR: |Could not resolve "|Cannot find (?:module|package)\b/u;
-const UNRESOLVED_MODULE_PATTERN = /Could not resolve "|Cannot find (?:module|package)\b/u;
+const UNRESOLVED_MODULE_PATTERN = /Could not resolve "|Cannot find (?:module|package)\b|No matching export in "/u;
+const MISSING_EXPORT_PATTERN = /No matching export in "[^"\n]*" for import "([A-Za-z_$][\w$]{0,127})"/u;
 
 // The first diagnostic decides the class, matching how the first location is reported.
+function firstDiagnosticLine(message) {
+  return message.split("\n").find((line) => DIAGNOSTIC_LINE_PATTERN.test(line)) ?? message;
+}
+
 function isUnresolvedModuleFailure(message) {
-  const firstDiagnostic = message.split("\n").find((line) => DIAGNOSTIC_LINE_PATTERN.test(line)) ?? message;
-  return UNRESOLVED_MODULE_PATTERN.test(firstDiagnostic);
+  return UNRESOLVED_MODULE_PATTERN.test(firstDiagnosticLine(message));
+}
+
+// Returns the imported name of a missing-export diagnostic (identifier only), or null.
+function findMissingExportName(message) {
+  return MISSING_EXPORT_PATTERN.exec(firstDiagnosticLine(message))?.[1] ?? null;
 }
 
 // Returns the first project-relative source location found in a raw message, or null.
@@ -67,7 +78,12 @@ export function classifyDeployCodegenFailure(error, { cwd, backendRoot = "gencow
     const location = findProjectSourceLocation(message, { cwd, processCwd });
     const backendLocation = location && location.sourceFile.startsWith(`${backendRoot}/`) ? location : null;
     if (isUnresolvedModuleFailure(message)) {
-      return { code: CODEGEN_FAILURE_CODES.SOURCE_LOAD_FAILED, ...(backendLocation ?? {}) };
+      const missingExport = findMissingExportName(message);
+      return {
+        code: CODEGEN_FAILURE_CODES.SOURCE_LOAD_FAILED,
+        ...(backendLocation ?? {}),
+        ...(missingExport ? { missingExport } : {}),
+      };
     }
     if (location) {
       return {
@@ -140,6 +156,7 @@ export function createDeployCodegenFailure(classification, { correlationId } = {
     error.line = classification.line;
     if (classification.column !== undefined) error.column = classification.column;
   }
+  if (classification.missingExport !== undefined) error.missingExport = classification.missingExport;
   // Local reference only (no Platform request exists for a codegen failure).
   if (correlationId !== undefined) error.correlationId = correlationId;
   return error;

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.260",
+  "version": "0.1.262",
   "description": "Gencow — AI Backend Engine",
   "type": "module",
   "bin": {
@@ -41,9 +41,9 @@
     "better-auth": "1.7.11",
     "postgres": "^3.4.9",
     "@gencow/client": "0.2.8",
-    "@gencow/react": "0.2.8",
     "@gencow/core": "0.1.47",
     "@gencow/shared": "0.0.0",
+    "@gencow/react": "0.2.8",
     "@gencow/server": "0.1.3"
   },
   "scripts": {