gencow 0.1.261 → 0.1.263

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/deploy-app-creation.mjs

@@ -21,6 +21,7 @@ export function createCloudAppIfNeeded({
     envTarget = "dev",
     gencowJsonPath,
     allowMissingAppReplacement = true,
+    explicitApp = false,
   }) {
     const resolvedAppId = await resolveDeployAppId({
       creds,
@@ -29,6 +30,7 @@ export function createCloudAppIfNeeded({
       environment: envTarget,
       platformFetchImpl,
       allowMissingAppReplacement,
+      explicitApp,
       infoImpl,
       errorImpl,
       exitImpl,

package/lib/deploy-app-target.mjs

@@ -1,3 +1,4 @@
+import { appNotFoundDiagnostic } from "./app-response-contract.mjs";
 import { readJsonObjectResponse } from "./http-response-json.mjs";
 
 const PUBLIC_LOOKUP_ERROR_CODES = new Set([
@@ -48,6 +49,30 @@ function formatLookupFailure(failure, target) {
   return lines.join("\n");
 }
 
+// Rejection for an app ID the user named explicitly with --app. Such an ID is never replaced:
+// a replacement would create a different app and rewrite gencow.json without the user asking.
+function explicitAppNotFoundMessage({ appId, target = "dev", correlationId = null }) {
+  const lines = [
+    ...appNotFoundDiagnostic().split("\n"),
+    "Stage: deploy target lookup",
+    `App ID: ${appId}${target === "prod" ? " (requested with --prod)" : ""}`,
+    "Changed: nothing. No replacement app was created, gencow.json was not modified, and app data and the serving state were not changed.",
+    "Retry: only after --app names an app you own. Retrying the same ID fails the same way.",
+    "Next: gencow app list   (find the app ID you own)",
+    "      gencow app create <name>   (create a new app, then deploy to its ID)",
+  ];
+  if (typeof correlationId === "string" && SAFE_CORRELATION_ID.test(correlationId)) {
+    lines.push(`Correlation ID: ${correlationId}`);
+  }
+  return lines.join("\n");
+}
+
+export function rejectExplicitAppNotFound({ appId, target, correlationId, errorImpl, exitImpl }) {
+  errorImpl(explicitAppNotFoundMessage({ appId, target, correlationId }));
+  exitImpl(1);
+  return false;
+}
+
 export async function lookupOwnedApp({ creds, appId, environment, platformFetchImpl }) {
   try {
     const response = await platformFetchImpl(
@@ -79,6 +104,7 @@ export async function resolveDeployAppId({
   environment = "dev",
   platformFetchImpl,
   allowMissingAppReplacement,
+  explicitApp = false,
   infoImpl,
   errorImpl,
   exitImpl,
@@ -91,6 +117,9 @@ export async function resolveDeployAppId({
     exitImpl(1);
     return false;
   }
+  if (explicitApp) {
+    return rejectExplicitAppNotFound({ appId, target: environment, errorImpl, exitImpl });
+  }
   if (!allowMissingAppReplacement) {
     errorImpl(
       `APP_NOT_FOUND: The existing app ID "${appId}" is unavailable. This deployment requires the original app; restore access before retrying. No replacement app was created.`,
@@ -110,6 +139,7 @@ export async function reconcileProductionAppTarget({
   gencowJsonPath,
   platformFetchImpl,
   createCloudAppIfNeeded,
+  explicitApp = false,
   infoImpl,
   errorImpl,
   exitImpl,
@@ -156,6 +186,9 @@ export async function reconcileProductionAppTarget({
   }
 
   if (productionParentAppId && parentState === "missing") {
+    if (explicitApp) {
+      return rejectExplicitAppNotFound({ appId: productionParentAppId, target: "prod", errorImpl, exitImpl });
+    }
     infoImpl(`Configured app ID is no longer available. Creating a new app named "${displayName}"...`);
     productionParentAppId = await createCloudAppIfNeeded({
       creds,

package/lib/deploy-package-runtime.mjs

@@ -5,6 +5,8 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFil
 import { dirname, resolve } from "path";
 import { fetchAppDiagnosticLogsViaRest, normalizeDiagnosticLogLines } from "./app-diagnostics.mjs";
 import { createCloudAppIfNeeded as createCloudAppIfNeededImpl } from "./deploy-app-creation.mjs";
+import { rejectExplicitAppNotFound } from "./deploy-app-target.mjs";
+import { loadProjectConfigForDeploy } from "./deploy-project-config-load.mjs";
 import { resolveConfiguredAuditorImplementation } from "./auditor-mode.mjs";
 import {
   loadDeployMigrationGenerationContext,
@@ -52,41 +54,9 @@ import { buildClientUserFixableDiagnostic } from "./migration-client-diagnostic.
 import { assertRuntimeAssetsWithinBackendRoot } from "./deploy-runtime-asset-audit.mjs";
 import { formatBundleSummaryLines } from "./deploy-bundle-summary.mjs";
 import { warnRuntimePathsOutsideBackendRoot } from "./deploy-runtime-path-audit.mjs";
-async function loadProjectConfigDefault(options) {
-  const { loadConfig } = await import("./cli-project-runtime.mjs");
-  return loadConfig(options);
-}
 export function isExplicitEmptyBackendApi(source) {
   return /\bdefineApi\s*\(\s*\{\s*procedures\s*:\s*\{\s*\}\s*,?\s*\}\s*\)\s*;?\s*$/u.test(source);
 }
-async function loadProjectConfigForDeploy({
-  cwd,
-  existsSyncImpl,
-  readFileSyncImpl,
-  resolvePathImpl,
-  statSyncImpl,
-  warnImpl,
-  errorImpl,
-  loadConfigImpl,
-  throwOnInvalid = false,
-}) {
-  const loadConfig = loadConfigImpl ?? loadProjectConfigDefault;
-  try {
-    return await loadConfig({
-      cwd,
-      existsSyncImpl,
-      readFileSyncImpl,
-      resolvePathImpl,
-      statSyncImpl,
-      warnImpl,
-      errorImpl,
-      throwOnInvalid,
-    });
-  } catch (caught) {
-    if (throwOnInvalid) throw caught;
-    return null;
-  }
-}
 async function loadInternalToolingDefault() {
   return loadToolingRuntime({
     required: ["analyzerAudit"],
@@ -604,6 +574,7 @@ export function createDeployPackageRuntime({
     resumeExistingReceipt = false,
     releaseAttemptId = null,
     clientName = null,
+    explicitApp = false,
   }) {
     lastDeployOutcome = "pending";
     const cwd = cwdImpl();
@@ -707,6 +678,19 @@ export function createDeployPackageRuntime({
     if (!deployRes.ok && deployRes.status === 404) {
       if (preserveSavedReceiptAfterMissingApp(receipt, targetAppId, envTarget)) return null;
       if (receipt) deployReceiptStore.releaseDeployReceipt(receipt);
+      if (explicitApp) {
+        // The user named this app with --app: report it instead of creating a replacement.
+        const notFoundBody = await readJsonObjectResponse(deployRes);
+        lastDeployOutcome = "failed";
+        rejectExplicitAppNotFound({
+          appId: targetAppId,
+          target: envTarget,
+          correlationId: notFoundBody?.correlationId,
+          errorImpl,
+          exitImpl,
+        });
+        return null;
+      }
       warnImpl(`App "${targetAppId}" not found. Creating new one...`);
       targetAppId = await createCloudAppIfNeeded({
         creds,

package/lib/deploy-prod-target.mjs

@@ -27,6 +27,7 @@ export async function ensureProductionDeployTarget({
   exitImpl = (code) => process.exit(code),
   prodAppId = null,
   region = null,
+  explicitApp = false,
   prepareLocalSource = null,
 }) {
   const confirmMode = resolveConfirmationMode({
@@ -50,6 +51,7 @@ export async function ensureProductionDeployTarget({
     gencowJsonPath,
     platformFetchImpl,
     createCloudAppIfNeeded,
+    explicitApp,
     infoImpl,
     errorImpl,
     exitImpl,

package/lib/deploy-project-config-load.mjs

@@ -0,0 +1,32 @@
+async function loadProjectConfigDefault(options) {
+  const { loadConfig } = await import("./cli-project-runtime.mjs");
+  return loadConfig(options);
+}
+export async function loadProjectConfigForDeploy({
+  cwd,
+  existsSyncImpl,
+  readFileSyncImpl,
+  resolvePathImpl,
+  statSyncImpl,
+  warnImpl,
+  errorImpl,
+  loadConfigImpl,
+  throwOnInvalid = false,
+}) {
+  const loadConfig = loadConfigImpl ?? loadProjectConfigDefault;
+  try {
+    return await loadConfig({
+      cwd,
+      existsSyncImpl,
+      readFileSyncImpl,
+      resolvePathImpl,
+      statSyncImpl,
+      warnImpl,
+      errorImpl,
+      throwOnInvalid,
+    });
+  } catch (caught) {
+    if (throwOnInvalid) throw caught;
+    return null;
+  }
+}

package/lib/deploy-runtime.mjs

@@ -527,6 +527,7 @@ export function createDeployCommand({
           exitImpl,
           prodAppId,
           region: parsed.region,
+          explicitApp: Boolean(parsed.appId),
           prepareLocalSource: preparesBackendSource
             ? async () => {
                 preparedSource = await prepareBackendSourceForProdCreate(backendDeployRuntime, {
@@ -565,6 +566,7 @@ export function createDeployCommand({
           envTarget: parsed.envTarget,
           forceDeploy: parsed.forceDeploy,
           requestId: parsed.requestId,
+          explicitApp: Boolean(parsed.appId),
           resumeStaticOnly: parsed.resumeRequested,
           gencowJsonPath,
           hasDetectedBackend,
@@ -657,6 +659,7 @@ export function createDeployCommand({
         envTarget: parsed.envTarget,
         forceDeploy: parsed.forceDeploy,
         existingBundleMode: parsed.existingBundleMode,
+        explicitApp: Boolean(parsed.appId),
         requestId: parsed.requestId,
         resumeExistingReceipt: parsed.resumeRequested,
         gencowJsonPath: activeGencowJsonPath,

package/lib/deploy-static-fullstack-runtime.mjs

@@ -93,6 +93,8 @@ export async function deployBackendPackage({
   failReleaseAttempt,
   sourceRoot = null,
   clientName = null,
+  // True when the user named the app with --app. Such an ID is never replaced.
+  explicitApp = false,
   successImpl = success,
 }) {
   let packageResult = null;
@@ -122,6 +124,7 @@ export async function deployBackendPackage({
         envTarget,
         gencowJsonPath,
         allowMissingAppReplacement: false,
+        explicitApp,
       });
       if (!activeAppId) return null;
     } else {
@@ -152,7 +155,8 @@ export async function deployBackendPackage({
         displayName,
         envTarget,
         gencowJsonPath,
-        allowMissingAppReplacement: !existingBundleMode,
+        allowMissingAppReplacement: !existingBundleMode && !explicitApp,
+        explicitApp,
       });
       if (!activeAppId) return null;
 
@@ -201,6 +205,7 @@ export async function deployBackendPackage({
       resumeExistingReceipt,
       releaseAttemptId: releaseAttempt?.attemptId ?? null,
       clientName,
+      explicitApp,
     });
     if (deployed && Object.hasOwn(deployed, "releaseAttemptId")) {
       releaseAttempt = deployed.releaseAttemptId ? { attemptId: deployed.releaseAttemptId } : null;
@@ -298,6 +303,7 @@ export async function runStaticDeployFlow({
   prepareReleaseAttempt,
   failReleaseAttempt,
   selectedClient = null,
+  explicitApp = false,
   successImpl = success,
 }) {
   if (!runStaticDeployRuntimeImpl) {
@@ -363,6 +369,7 @@ export async function runStaticDeployFlow({
       failReleaseAttempt,
       sourceRoot: backendRoot,
       clientName: selectedClient?.name ?? null,
+      explicitApp,
       successImpl,
     });
     if (!deployed) return;

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.263",
   "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/react": "0.2.8",
     "@gencow/core": "0.1.47",
-    "@gencow/shared": "0.0.0"
+    "@gencow/shared": "0.0.0",
+    "@gencow/server": "0.1.3"
   },
   "scripts": {
     "build": "node scripts/bundle-core.mjs && node scripts/bundle-shared.mjs && node scripts/bundle-server.mjs",