gencow 0.1.186 → 0.1.188

package/bin/gencow.mjs

@@ -55,6 +55,8 @@ import { createInitCommand } from "../lib/init-command.mjs";
 import { createJobsCommand } from "../lib/jobs-command.mjs";
 import { createLogsCommand } from "../lib/logs-command.mjs";
 import { createOriginsCommand } from "../lib/origins-command.mjs";
+import { parseProjectSelectionArgs, setCliInvocationSelection } from "../lib/project-context.mjs";
+import { createRuntimeCommand } from "../lib/runtime-command.mjs";
 import { createStaticDeployRuntime } from "../lib/static-deploy-command.mjs";
 import { createStaticCommand } from "../lib/static-command.mjs";
 import { createTemplateMarketplaceCommand } from "../lib/template-marketplace-command.mjs";
@@ -103,7 +105,10 @@ const runAddCommand = createAddCommand({
   RESET,
   YELLOW,
 });
-const runAppCommand = createAppCommand({ loadConfig });
+const runAppCommand = createAppCommand({
+  loadConfig,
+  errorImpl: (message) => console.error(`${RED}  ✗${RESET} ${message}`),
+});
 const runBackupCommand = createBackupCommand();
 const { login: runLoginCommand, logout: runLogoutCommand, whoami: runWhoamiCommand } = createAuthCommands();
 const runCodegenCommand = createCodegenCommand({
@@ -130,14 +135,17 @@ const runDoctorCommand = createDoctorCommand({
   loadConfig,
   logImpl: log,
   infoImpl: info,
+  warnImpl: warn,
   errorImpl: error,
   successImpl: success,
   exitImpl: (code) => process.exit(code),
   cwdImpl: () => process.cwd(),
   BOLD,
   CYAN,
+  DIM,
   RESET,
 });
+const runRuntimeCommand = createRuntimeCommand();
 const {
   dbReset: runDbResetCommand,
   dbSeed: runDbSeedCommand,
@@ -227,6 +235,7 @@ const runStaticDeployRuntime = createStaticDeployRuntime({
   cliVersion: CLI_VERSION,
   cwdImpl: () => process.cwd(),
   drizzleKitCmdImpl: _drizzleKitCmd,
+  loadConfigImpl: loadConfig,
   verifyAppReadyImpl: verifyAppReady,
   updateEnvLocalUrlImpl: updateEnvLocalUrl,
   prepareReleaseAttemptImpl: prepareReleaseAttempt,
@@ -298,6 +307,7 @@ const runLogsCommand = createLogsCommand({ loadConfig });
 const runOriginsCommand = createOriginsCommand();
 const runStaticCommand = createStaticCommand({
   cwdImpl: () => process.cwd(),
+  loadConfigImpl: loadConfig,
   requireCredsImpl: requireCreds,
   runStaticDeployRuntimeImpl: runStaticDeployRuntime,
 });
@@ -356,18 +366,25 @@ ${BOLD}Usage:${RESET}
 
 ${BOLD}Quick Start:${RESET}
   ${GREEN}init <name>${RESET}       Create a new Gencow project
-                     ${DIM}--template, -t  Select template (default, task-app, fullstack, ai-chat)${RESET}
+                     ${DIM}--template, -t  Select template (default, task-app, admin-tool, fullstack, ai-chat)${RESET}
                      ${DIM}--force, -f     Initialize in non-empty directory (preserves existing files)${RESET}
   ${GREEN}add <comp...>${RESET}   Add components ${DIM}(AI Agent RAG Tools Memory ...)${RESET}
-  ${GREEN}codegen${RESET}          Generate frontend api.ts from schema
+  ${GREEN}codegen${RESET}          Generate client codegen artifacts from schema
                      ${DIM}--outdir, -o  Output directory (default: src/gencow/)${RESET}
+                     ${DIM}--target NAME Select declared codegen client${RESET}
   ${GREEN}doctor${RESET}           Run pre-run source diagnostics
+                     ${DIM}--plan/--diff/--fix  backend autofix; --no-sync skips BOM rewrite${RESET}
+  ${GREEN}runtime list${RESET}     List runtime releases ${DIM}(marks current tip)${RESET}
+  ${GREEN}runtime show${RESET}     Show managed BOM package versions
+  ${GREEN}runtime check${RESET}    Compare package.json against runtime BOM
+  ${GREEN}runtime sync${RESET}     Align managed dependency versions to BOM
 
 ${BOLD}Commands (login required):${RESET}
   ${GREEN}login${RESET}            Login to Gencow Platform ${DIM}(browser → token)${RESET}
   ${GREEN}logout${RESET}           Clear credentials
   ${GREEN}whoami${RESET}           Show current user info
   ${GREEN}dev${RESET}              Watch + auto-deploy to cloud + live logs
+                     ${DIM}--local     Run local Bun + Hono + PGlite development${RESET}
                      ${DIM}--verbose   Show all HTTP logs (including admin/ws)${RESET}
   ${GREEN}db:push${RESET}          Apply versioned migrations to cloud DB
                      ${DIM}--prod      Push to production DB (confirmation required)${RESET}
@@ -378,6 +395,8 @@ ${BOLD}Commands (login required):${RESET}
                      ${DIM}--prod      Seed production app (confirmation required)${RESET}
   ${GREEN}static [dir]${RESET}     Deploy static files only ${DIM}(dist/, out/, build/)${RESET}
                      ${DIM}--prod          Deploy to production app${RESET}
+                     ${DIM}--client NAME   Select declared client workspace${RESET}
+                     ${DIM}--frontend NAME Compatibility alias for --client${RESET}
                      ${DIM}--force, -f     Skip optional dependency scan${RESET}
   ${GREEN}templates publish${RESET} Publish current project as a marketplace template
                      ${DIM}--title, --slug, --price, --private, --unlisted${RESET}
@@ -385,7 +404,7 @@ ${BOLD}Commands (login required):${RESET}
   ${GREEN}templates clone <slug>${RESET} Clone a template into a local directory
   ${GREEN}deploy${RESET}           Deploy backend to cloud ${DIM}(dev by default)${RESET}
                      ${DIM}--static [dir]  Deploy backend, then static files${RESET}
-                     ${DIM}--prod          Deploy to production (Pro+ only)${RESET}
+                     ${DIM}--prod          Deploy to production (Startup/Enterprise)${RESET}
                      ${DIM}--rollback      Rollback to previous deployment${RESET}
                      ${DIM}--force, -f     Skip optional dependency scan${RESET}
                      ${DIM}logs [-n N]     Show cloud app server logs${RESET}
@@ -393,7 +412,7 @@ ${BOLD}Commands (login required):${RESET}
   ${GREEN}env list${RESET}         List cloud env vars ${DIM}(--prod for production)${RESET}
   ${GREEN}env set K=V${RESET}      Set cloud env var ${DIM}(hot-reload, no restart)${RESET}
   ${GREEN}env unset KEY${RESET}    Remove cloud env var
-  ${GREEN}env push${RESET}         Push .env to cloud ${DIM}(--prod reads .env.production)${RESET}
+  ${GREEN}env push${RESET}         Push backend env file ${DIM}(gencow/.env by default)${RESET}
   ${GREEN}cors list${RESET}        Show legacy CORS overrides
   ${GREEN}cors add URL${RESET}     Add legacy CORS override ${DIM}(compat only)${RESET}
   ${GREEN}cors remove URL${RESET}  Remove legacy CORS override
@@ -446,7 +465,7 @@ ${BOLD}Examples:${RESET}
   ${DIM}# Deploy built frontend files only:${RESET}
   gencow static dist/
 
-  ${DIM}# Deploy to production (Pro+ only):${RESET}
+  ${DIM}# Deploy to production (Startup/Enterprise):${RESET}
   gencow deploy --prod
 
   ${DIM}# Inspect stale workflows:${RESET}
@@ -497,6 +516,9 @@ ${BOLD}Examples:${RESET}
   // ── doctor — 실행 전 소스 진단 ────────────────────
   doctor: runDoctorCommand,
 
+  // ── runtime — BOM list/show/check/sync ─────────────
+  runtime: runRuntimeCommand,
+
   // ── app (subcommands: create, list, delete) ────────
   app: runAppCommand,
 
@@ -539,7 +561,10 @@ ${BOLD}Examples:${RESET}
 
 // ─── updateReadme: gencow/ 폴더 스캔 → README에 컴포넌트 문서 자동 추가 ────
 
-const [, , rawCmd = "help", ...args] = process.argv;
+const [, , rawCmd = "help", ...rawArgs] = process.argv;
+const globalProjectSelection = parseProjectSelectionArgs(rawArgs);
+setCliInvocationSelection(globalProjectSelection);
+const args = [...globalProjectSelection.remainingArgs];
 const cmd =
   rawCmd === "--help" || rawCmd === "-h"
     ? "help"

package/core/index.js

@@ -2979,6 +2979,7 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "GENCOW_PLATFORM_URL",
   "GENCOW_PLATFORM_INTERNAL_URL",
   "GENCOW_PLATFORM_INTERNAL_URL_ALT",
+  "GENCOW_REALTIME_GATEWAY_INTERNAL_URL",
   "GENCOW_PLATFORM_DB",
   "GENCOW_MANAGED_PUBLIC_ORIGINS",
   "PLATFORM_OPENAI_KEY",
@@ -2986,6 +2987,18 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "PLATFORM_GOOGLE_CLIENT_ID",
   "PLATFORM_GOOGLE_CLIENT_SECRET",
   "PLATFORM_INTERNAL_SECRET",
+  "STRIPE_SECRET_KEY",
+  "STRIPE_WEBHOOK_SECRET",
+  "TOSS_BILLING_CLIENT_KEY",
+  "TOSS_BILLING_SECRET_KEY",
+  "TOSS_BILLING_WEBHOOK_SECRET",
+  "GENCOW_BILLING_STRIPE_MODE",
+  "GENCOW_BILLING_STRIPE_ENVIRONMENT",
+  "GENCOW_BILLING_STRIPE_EXPECTED_ACCOUNT_ID",
+  "GENCOW_BILLING_STRIPE_API_VERSION",
+  "GENCOW_BILLING_NEW_CHECKOUT_PROVIDER",
+  "GENCOW_BILLING_STRIPE_ANNUAL_ENABLED",
+  "GENCOW_BILLING_STRIPE_CANARY_USER_IDS",
   "INVITE_ONLY",
   "RUNNER_TYPE",
   "COWBOX_PROFILE",
@@ -2993,6 +3006,8 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "PGBOUNCER_PORT",
   "DIRECT_PG_PORT",
   "GENCOW_DIRECT_DATABASE_URL",
+  "GENCOW_CATALOG_READ_DATABASE_URL",
+  "GENCOW_DIRECT_DDL_DATABASE_URL",
   "DIRECT_DATABASE_URL",
   "GENCOW_APP_USER_PASS",
   "GENCOW_DDL_USER_PASS",
@@ -3016,10 +3031,15 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "GENCOW_BACKUP_RETENTION_V2_EFFECTIVE_AT",
   "GENCOW_MIGRATIONS",
   "GENCOW_APP_NAME",
+  "GENCOW_MANAGED_RUNTIME",
   "GENCOW_APP_DATA_DIR",
   "GENCOW_RUNTIME_COMPATIBILITY",
   "GENCOW_RUNTIME_RELEASE_ID",
   "GENCOW_RUNTIME_RELEASE_DIR",
+  "GENCOW_RUNTIME_GENERATION_DIR",
+  "GENCOW_APP_RUNTIME_DIR",
+  "GENCOW_APP_OWNED_DEPS_DIR",
+  "GENCOW_RUNTIME_RUNTIME_DIR",
   "GENCOW_RUNTIME_NODE_MODULES",
   "GENCOW_INTERNAL_TOKEN",
   "GENCOW_CRON_TOKEN",
@@ -3035,8 +3055,10 @@ var RESERVED_TENANT_RUNTIME_ENV_KEYS = [
   "GENCOW_SHUTDOWN_MARKER_PATH",
   "GENCOW_SKIP_MIGRATION",
   "GENCOW_DB_MAX_CONNECTIONS",
+  "GENCOW_DB_POOL_POLICY_VERSION",
   "GENCOW_DB_IDLE_TIMEOUT_SECONDS",
   "GENCOW_DB_CONNECTION_TIMEOUT_SECONDS",
+  "GENCOW_DB_OPERATION_TIMEOUT_MS",
   "GENCOW_MEMORY_MB",
   "BUN_JSC_forceRAMSize",
   "MIMALLOC_PURGE_DELAY",
@@ -3046,6 +3068,7 @@ var RESERVED_TENANT_RUNTIME_ENV_KEY_SET = new Set(RESERVED_TENANT_RUNTIME_ENV_KE
 var RESERVED_TENANT_RUNTIME_ENV_PREFIXES = [
   "__GENCOW_",
   "GENCOW_CONTROL_PLANE_",
+  "GENCOW_BUILDER_",
   "GENCOW_PLATFORM_STORAGE_",
   "GENCOW_RELEASE_",
   "GENCOW_DOCUMENT_",
@@ -3053,6 +3076,7 @@ var RESERVED_TENANT_RUNTIME_ENV_PREFIXES = [
   "GENCOW_WARM_",
   "GENCOW_DIRECT_RUNNER_",
   "GENCOW_RUNTIME_PINNING_",
+  "GENCOW_FUNCTION_TIMEOUT_RESTART_",
   "GENCOW_COWBOX_"
 ];
 function isReservedTenantRuntimeEnvKey(key) {

package/lib/app-command.mjs

@@ -7,8 +7,30 @@ import {
   selectAppDiagnosticLogLines,
 } from "./app-diagnostics.mjs";
 import { resolveCreatedAppId, resolveCreatedAppResponse } from "./app-create-response.mjs";
+import {
+  isExactAppDeleteResponse,
+  parseAppListResponse,
+  parseAppStatusResponse,
+} from "./app-response-contract.mjs";
+import { pollAppDeleteOperation } from "./app-delete-operation.mjs";
+import { appResponseError } from "./app-response-error.mjs";
+import { readJsonObjectResponse } from "./http-response-json.mjs";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, error, info, log, success, warn } from "./output.mjs";
 import { loadCreds, rpcMutation, rpcQuery, saveCreds, requireCreds } from "./platform-client.mjs";
+import { resolveProjectMetadataPath, resolveProjectSelection } from "./project-context.mjs";
+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;
+
+function appResponseStatus(response) {
+  return Number.isSafeInteger(response?.status) ? `HTTP ${response.status}` : "unknown HTTP status";
+}
+
+function invalidAppResponse(operation, response, kind) {
+  return `CLI_APP_RESPONSE_INVALID: ${operation} returned an invalid ${kind} response (${appResponseStatus(response)})`;
+}
 
 export function formatAppDeployedAgo(dateStr, now = Date.now()) {
   if (!dateStr) return `${DIM}never${RESET}`;
@@ -89,7 +111,10 @@ export function createAppCommand({
   rpcMutationImpl = rpcMutation,
   rpcQueryImpl = rpcQuery,
   saveCredsImpl = saveCreds,
+  sleepImpl = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
+  deletePollAttempts = DEFAULT_DELETE_POLL_ATTEMPTS,
   successImpl = success,
+  updateEnvLocalUrlImpl = updateEnvLocalUrl,
   warnImpl = warn,
 }) {
   return async function app(subcmd, ...rest) {
@@ -109,11 +134,18 @@ export function createAppCommand({
     if (!subcmd || subcmd === "list") {
       logImpl(`\n${BOLD}${CYAN}Your Apps${RESET}\n`);
       const res = await rpcQueryImpl(creds, "apps.list");
+      const body = await res.json().catch(() => null);
       if (!res.ok) {
-        errorImpl((await res.json().catch(() => ({}))).error || "Failed to list apps");
+        errorImpl(appResponseError(body, invalidAppResponse("app list", res, "error")));
+        processRef.exit(1);
+        return;
+      }
+      const apps = parseAppListResponse(body);
+      if (!apps) {
+        errorImpl(invalidAppResponse("app list", res, "success"));
+        processRef.exit(1);
         return;
       }
-      const apps = await res.json();
       if (!apps.length) {
         infoImpl("No apps yet. Run: gencow app create <name>");
         return;
@@ -143,10 +175,16 @@ export function createAppCommand({
       logImpl(`\n${BOLD}${CYAN}Gencow App Create${RESET}\n`);
       infoImpl(`Creating app "${name}"...`);
       const res = await rpcMutationImpl(creds, "apps.create", { name });
-      const data = await res.json();
+      const data = await readJsonObjectResponse(res);
       if (!res.ok) {
-        errorImpl(data.error || "Failed to create app");
+        errorImpl(appResponseError(data, invalidAppResponse("app create", res, "error")));
+        processRef.exit(1);
+        return;
+      }
+      if (!data) {
+        errorImpl(invalidAppResponse("app create", res, "success"));
         processRef.exit(1);
+        return;
       }
 
       let createdApp;
@@ -162,9 +200,14 @@ export function createAppCommand({
       saveCredsImpl({ ...creds, currentApp: appId });
 
       const cwd = cwdImpl();
-      const config = await loadConfig();
+      const projectSelection = resolveProjectSelection({
+        allowMissingConfig: true,
+        cwd,
+      });
+      const projectDir = projectSelection.projectDir;
+      const config = await loadConfig({ cwd: projectDir });
       writeFileSync(
-        resolve(cwd, "gencow.json"),
+        resolveProjectMetadataPath(projectDir, resolve),
         `${JSON.stringify(
           buildCreatedAppProjectMetadata({ appId, displayName: name, platformUrl: creds.platformUrl }),
           null,
@@ -172,20 +215,15 @@ export function createAppCommand({
         )}\n`,
       );
       successImpl(`gencow.json — saved appId = "${appId}"`);
-      const envFilePath = resolve(cwd, ".env");
-      const envLine = `VITE_API_URL=${appUrl}`;
-      if (existsSync(envFilePath)) {
-        const envContent = readFileSync(envFilePath, "utf8");
-        if (!envContent.includes("VITE_API_URL")) {
-          writeFileSync(envFilePath, envContent.trimEnd() + "\n" + envLine + "\n");
-          successImpl(`.env — added VITE_API_URL`);
-        }
-      } else {
-        writeFileSync(envFilePath, `# Gencow app backend URL\n${envLine}\n`);
-        successImpl(`.env — created`);
-      }
+      await Promise.resolve(
+        updateEnvLocalUrlImpl(appUrl, {
+          config,
+          cwd,
+          projectDir,
+        }),
+      );
 
-      const functionsDir = resolve(cwd, config.rootDir);
+      const functionsDir = resolve(projectDir, config.rootDir);
       const indexPath = resolve(functionsDir, "index.ts");
       if (!existsSync(indexPath)) {
         mkdirSync(functionsDir, { recursive: true });
@@ -196,7 +234,7 @@ export function createAppCommand({
         successImpl(`${config.rootDir}/index.ts — created (starter)`);
       }
 
-      const configPath = resolve(cwd, "gencow.config.ts");
+      const configPath = projectSelection.configPath ?? resolve(projectDir, "gencow.config.ts");
       if (existsSync(configPath)) {
         const src = readFileSync(configPath, "utf8");
         const nextSrc = addDeployAppToConfigSource(src, appId);
@@ -241,10 +279,28 @@ ${dashboardLine}
 
       infoImpl(`Deleting app "${name}"...`);
       const delRes = await rpcMutationImpl(creds, "apps.delete", { name });
-      const delData = await delRes.json();
-      if (!delRes.ok) {
-        errorImpl(delData.error || "Failed to delete app");
+      let delData = await readJsonObjectResponse(delRes);
+      if (!isExactAppDeleteResponse(delData, name)) {
+        const operationResult = await pollAppDeleteOperation({
+          creds,
+          initialBody: delData,
+          name,
+          pollAttempts: deletePollAttempts,
+          pollIntervalMs: DELETE_POLL_INTERVAL_MS,
+          rpcQueryImpl,
+          sleepImpl,
+        });
+        if (operationResult) delData = operationResult;
+      }
+      if (!isExactAppDeleteResponse(delData, name)) {
+        errorImpl(
+          appResponseError(
+            delData,
+            invalidAppResponse("app delete", delRes, delRes.ok ? "success" : "error"),
+          ),
+        );
         processRef.exit(1);
+        return;
       }
 
       const currentCreds = loadCredsImpl();
@@ -261,17 +317,20 @@ ${dashboardLine}
       if (!name) {
         errorImpl("Usage: gencow app status <name>");
         processRef.exit(1);
+        return;
       }
       const res = await rpcQueryImpl(creds, "apps.get", { name });
-      const body = await res.json();
-      const data = body?.result || body;
+      const body = await readJsonObjectResponse(res);
       if (!res.ok) {
-        errorImpl(data?.error || "App not found");
+        errorImpl(appResponseError(body, invalidAppResponse("app status", res, "error")));
         processRef.exit(1);
+        return;
       }
+      const data = parseAppStatusResponse(body, name);
       if (!data) {
-        errorImpl("App not found");
+        errorImpl(invalidAppResponse("app status", res, "success"));
         processRef.exit(1);
+        return;
       }
       logImpl(`\n  ${BOLD}${data.name}${RESET}`);
       const status = formatAppStatusForCli(data);

package/lib/app-delete-operation.mjs

@@ -0,0 +1,129 @@
+import { isExactAppDeleteResponse } from "./app-response-contract.mjs";
+import { APP_DELETE_OPERATION_PATTERN } from "./app-response-error.mjs";
+import { readJsonObjectResponse } from "./http-response-json.mjs";
+
+const APP_DELETE_ACTIVE_STATES = new Set([
+  "accepted",
+  "stopping_children",
+  "draining_runtime",
+  "stop_dispatched",
+  "runtime_absent",
+  "tenant_db_drop_pending",
+  "catalog_delete_pending",
+  "blocked_ownership_ambiguous",
+  "blocked_active_work",
+  "blocked_runtime_outcome_unknown",
+  "failed_tenant_db_cleanup",
+  "failed_catalog_cleanup",
+]);
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/u;
+const DIAGNOSTIC_CODE_PATTERN = /^[A-Za-z][A-Za-z0-9_]{2,127}$/u;
+const APP_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+){2}$/u;
+
+function isAllowedStatusPath(value, operationId, expectedAppId) {
+  if (value === undefined) return true;
+  if (typeof value !== "string" || value.length > 256 || value.includes("?") || value.includes("#")) {
+    return false;
+  }
+  const match = /^\/api\/apps\/([^/]+)\/delete\/([^/]+)$/u.exec(value);
+  if (!match) return false;
+  try {
+    const appId = decodeURIComponent(match[1]);
+    return (
+      APP_ID_PATTERN.test(appId) &&
+      (!expectedAppId || appId === expectedAppId) &&
+      decodeURIComponent(match[2]) === operationId
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function parseAppDeleteOperationEnvelope(value, expectedAppId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.success !== undefined && value.success !== false) return null;
+  if (!APP_DELETE_OPERATION_PATTERN.test(value.operationId ?? "")) return null;
+  if (!APP_DELETE_ACTIVE_STATES.has(value.state)) return null;
+  if (
+    !CORRELATION_ID_PATTERN.test(value.correlationId ?? "") ||
+    (value.deleted !== undefined && value.deleted !== expectedAppId) ||
+    (value.code !== undefined && !DIAGNOSTIC_CODE_PATTERN.test(value.code)) ||
+    !isAllowedStatusPath(value.statusPath, value.operationId, expectedAppId)
+  ) {
+    return null;
+  }
+  return value;
+}
+
+function invalidPollResponse(accepted) {
+  return {
+    error: "CLI_APP_RESPONSE_INVALID: app delete status returned an invalid response",
+    code: "CLI_APP_RESPONSE_INVALID",
+    operationId: accepted.operationId,
+    correlationId: accepted.correlationId,
+    state: accepted.state,
+  };
+}
+
+function isMatchingTerminalResponse(value, accepted, expectedAppId) {
+  return (
+    isExactAppDeleteResponse(value, expectedAppId) &&
+    value.operationId === accepted.operationId &&
+    value.correlationId === accepted.correlationId &&
+    value.state === "completed"
+  );
+}
+
+export async function pollAppDeleteOperation({
+  creds,
+  initialBody,
+  name,
+  pollAttempts,
+  pollIntervalMs,
+  rpcQueryImpl,
+  sleepImpl,
+}) {
+  const accepted = parseAppDeleteOperationEnvelope(initialBody, name);
+  if (!accepted) return null;
+
+  let latest = accepted;
+  let successfulPollResponses = 0;
+  let transportFailures = 0;
+  for (let attempt = 0; attempt < pollAttempts; attempt += 1) {
+    try {
+      const statusRes = await rpcQueryImpl(creds, "apps.deleteStatus", {
+        name,
+        operationId: accepted.operationId,
+      });
+      const statusData = await readJsonObjectResponse(statusRes);
+      if (!statusRes?.ok || !statusData) return invalidPollResponse(accepted);
+      successfulPollResponses += 1;
+      if (isMatchingTerminalResponse(statusData, accepted, name)) return statusData;
+      const operation = parseAppDeleteOperationEnvelope(statusData, name);
+      if (
+        !operation ||
+        operation.operationId !== accepted.operationId ||
+        operation.correlationId !== accepted.correlationId
+      ) {
+        return invalidPollResponse(accepted);
+      }
+      latest = operation;
+    } catch {
+      transportFailures += 1;
+      // The durable receipt remains authoritative across transient polling failures.
+    }
+    if (attempt + 1 < pollAttempts) await sleepImpl(pollIntervalMs);
+  }
+
+  const pollingUnavailable = successfulPollResponses === 0 && transportFailures > 0;
+  return {
+    error: pollingUnavailable
+      ? "App deletion status is temporarily unavailable. Retry the command with the same app."
+      : "App deletion is still pending. Retry the command to resume this operation.",
+    code: pollingUnavailable ? "APP_DELETE_STATUS_POLL_UNAVAILABLE" : "APP_DELETE_OPERATION_PENDING",
+    operationCode: latest.code ?? accepted.code,
+    operationId: accepted.operationId,
+    correlationId: latest.correlationId ?? accepted.correlationId,
+    state: latest.state,
+  };
+}

package/lib/app-response-contract.mjs

@@ -0,0 +1,49 @@
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function optionalString(value) {
+  return value == null || typeof value === "string";
+}
+
+export function parseAppListResponse(value) {
+  if (!Array.isArray(value)) return null;
+  return value.every((row) => {
+    const app = record(row);
+    return (
+      nonEmptyString(app?.name) &&
+      nonEmptyString(app?.status) &&
+      optionalString(app?.url) &&
+      optionalString(app?.lastDeployedAt)
+    );
+  })
+    ? value
+    : null;
+}
+
+export function parseAppStatusResponse(value, expectedAppId) {
+  const body = record(value);
+  if (!body) return null;
+  const hasEnvelope = Object.prototype.hasOwnProperty.call(body, "result");
+  const app = record(hasEnvelope ? body.result : body);
+  if (
+    !app ||
+    app.name !== expectedAppId ||
+    !nonEmptyString(app.status) ||
+    !Number.isSafeInteger(app.port) ||
+    app.port <= 0 ||
+    app.port > 65535
+  ) {
+    return null;
+  }
+  return app;
+}
+
+export function isExactAppDeleteResponse(value, expectedAppId) {
+  const body = record(value);
+  return body?.success === true && body.deleted === expectedAppId;
+}

package/lib/app-response-error.mjs

@@ -0,0 +1,24 @@
+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;
+
+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;
+  const lines = [message];
+  if (/^[A-Za-z][A-Za-z0-9_]{2,127}$/u.test(body.code ?? "")) {
+    lines.push(`Code: ${body.code}`);
+  }
+  if (/^[A-Za-z][A-Za-z0-9_]{2,127}$/u.test(body.operationCode ?? "")) {
+    lines.push(`Operation code: ${body.operationCode}`);
+  }
+  if (/^[A-Za-z0-9_-]{8,128}$/u.test(body.correlationId ?? "")) {
+    lines.push(`Correlation ID: ${body.correlationId}`);
+  }
+  if (APP_DELETE_OPERATION_PATTERN.test(body.operationId ?? "")) {
+    lines.push(`Operation ID: ${body.operationId}`);
+  }
+  if (/^[a-z][a-z0-9_]{2,63}$/u.test(body.state ?? "")) {
+    lines.push(`State: ${body.state}`);
+  }
+  return lines.join("\n");
+}

package/lib/backup-command.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import { resolve } from "path";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, YELLOW, error, info, log, success } from "./output.mjs";
 import { platformFetch, requireCreds, rpcMutation, rpcQuery } from "./platform-client.mjs";
+import { readProjectMetadata } from "./project-context.mjs";
 
 export function resolveBackupAppId(restArgs, gencowJson = null) {
   let appId = null;
@@ -94,7 +95,7 @@ function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   logImpl(`    gencow backup restore <id>        Restore from backup`);
   logImpl(`    gencow backup restore-file <path> Restore from a downloaded dump file`);
   logImpl(`    gencow backup delete <id>         Delete a backup`);
-  logImpl(`    gencow backup download <id>       Download backup file (Pro+)\n`);
+  logImpl(`    gencow backup download <id>       Download backup file (plan-dependent)\n`);
 }
 
 export function buildRestoreConfirmPrompt(sourceLabel, { includeStorageRisk = false } = {}) {
@@ -139,11 +140,12 @@ export function createBackupCommand({
     const subCmd = backupArgs[0] || "list";
     const restArgs = backupArgs.slice(1);
 
-    let gencowJson = null;
-    const gencowJsonPath = resolvePathImpl(cwdImpl(), "gencow.json");
-    if (existsSyncImpl(gencowJsonPath)) {
-      gencowJson = JSON.parse(readFileSyncImpl(gencowJsonPath, "utf8"));
-    }
+    const { gencowJson } = readProjectMetadata({
+      cwd: cwdImpl(),
+      existsSyncImpl,
+      readFileSyncImpl,
+      resolvePathImpl,
+    });
 
     const appId = resolveBackupAppId(restArgs, gencowJson);
     if (!appId) {