gencow 0.1.267 → 0.1.269

package/lib/cli-command-runner.mjs

@@ -1,5 +1,10 @@
 import { formatProcedureRpcDiagnostic } from "./procedure-rpc-diagnostic.mjs";
 import { describeMigrationFolderFormatFailure } from "./migration-folder-format.mjs";
+import {
+  buildHintsRequiredCommand,
+  HINTS_DATA_LOSS_NOTICE,
+  SAFE_COLUMN_REFERENCE,
+} from "./migration-hints.mjs";
 
 const SAFE_CORRELATION_ID = /^[A-Za-z0-9_-]{8,128}$/u;
 const SAFE_APP_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
@@ -166,8 +171,61 @@ const SAFE_LOCAL_ERROR_CODES = new Map([
       },
     },
   ],
+  [
+    "MIGRATION_HINTS_REQUIRED",
+    {
+      message: (caught) => {
+        const count = safeHintCount(caught);
+        const columns = safeHintColumns(caught);
+        if (columns.length === 0) {
+          return `Migration generation stopped: ${count} schema change(s) need your decision.`;
+        }
+        return `Migration generation stopped: ${count} column change(s) need your decision (${columns.join(", ")}).`;
+      },
+      stage: "migration",
+      action: (caught) => {
+        const example = `\`${buildHintsRequiredCommand(safeHintColumns(caught))}\``;
+        const createExample = `{"type":"create",...} to add a new column instead`;
+        const tail = `${HINTS_DATA_LOSS_NOTICE} Do not edit applied migration files.`;
+        if (caught.migrationHints?.hintsProvided) {
+          return `Retryable: yes, after your --hints array decides every listed column change — rerun with one rename or create decision per column, for example ${example}, or use ${createExample}. ${tail}`;
+        }
+        return `Retryable: yes, after you declare the decision — rerun ${example} (or use ${createExample}). ${tail}`;
+      },
+    },
+  ],
+  [
+    "MIGRATION_HINTS_INVALID",
+    {
+      message: (caught) => {
+        const source = caught.hintsSource === "file" ? "--hints-file" : "--hints";
+        const reasons = {
+          conflicting_options: "use only one of --hints or --hints-file.",
+          value_missing: `${source} needs a value.`,
+          json_invalid: `${source} value is not valid JSON.`,
+          not_array: `${source} must be a JSON array of decisions.`,
+          too_large: `${source} value is too large.`,
+          file_unreadable: "the --hints-file could not be read.",
+        };
+        return `Migration generation not started: ${reasons[caught.hintsReason] ?? "the hints value is not accepted."}`;
+      },
+      stage: "input",
+      action:
+        "Retryable: yes, after the hints value is fixed — pass a JSON array with `--hints '<json-array>'` or a JSON file with `--hints-file <path>`, then rerun `npx gencow@latest db:generate`.",
+    },
+  ],
 ]);
 
+function safeHintCount(caught) {
+  const count = caught.migrationHints?.count;
+  return Number.isInteger(count) && count > 0 && count <= 9999 ? count : 1;
+}
+
+function safeHintColumns(caught) {
+  const columns = caught.migrationHints?.columns;
+  return Array.isArray(columns) ? columns.filter((value) => typeof value === "string" && SAFE_COLUMN_REFERENCE.test(value)) : [];
+}
+
 function safeDisplayDir(caught) {
   const { displayDir } = caught;
   return typeof displayDir === "string" && SAFE_DISPLAY_DIR.test(displayDir) ? displayDir : null;

package/lib/db-command.mjs

@@ -14,8 +14,10 @@ import {
 import { dirname, resolve } from "path";
 import { tmpdir } from "os";
 import { createDbCheckCommand, createDbPushCommand } from "./db-push-command.mjs";
+import { renderMaintenanceFailure } from "./db-seed-failure-render.mjs";
 import { logEnvFileOperationWithType } from "./backend-env-resolver.mjs";
 import { runDrizzleGenerateWithFallback } from "./drizzle-generate.mjs";
+import { HINTS_DATA_LOSS_NOTICE, parseMigrationHintsArgs } from "./migration-hints.mjs";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, error, info, log, success, warn } from "./output.mjs";
 import {
   describeProdTargetFailure,
@@ -150,8 +152,17 @@ function renderDbCheckHelp(logImpl = log) {
 
 function renderDbGenerateHelp(logImpl = log) {
   logImpl(`\n${BOLD}${CYAN}gencow db:generate${RESET} — Generate SQL migration files\n`);
-  logImpl(`  ${BOLD}Usage:${RESET}  gencow db:generate\n`);
+  logImpl(`  ${BOLD}Usage:${RESET}  gencow db:generate [--hints '<json-array>' | --hints-file <path>]\n`);
   logImpl(`  Generates migration files from schema.ts using drizzle-kit.\n`);
+  logImpl(`  ${BOLD}Options:${RESET}`);
+  logImpl(`    --hints '<json-array>'  Decide each changed column: rename or create.`);
+  logImpl(`    --hints-file <path>     Same decisions, read from a JSON array file.\n`);
+  logImpl(`  Example (rename column label to tag in table files):`);
+  logImpl(
+    `    gencow db:generate --hints '[{"type":"rename","kind":"column","from":["public","files","label"],"to":["public","files","tag"]}]'\n`,
+  );
+  logImpl(`  Use only one of --hints or --hints-file. Hints are never inferred automatically.`);
+  logImpl(`  ${HINTS_DATA_LOSS_NOTICE}\n`);
 }
 
 function renderLocalSeedMissingFile({ infoImpl = info, logImpl = log, warnImpl = warn } = {}) {
@@ -200,6 +211,7 @@ export function createDbCommands({
   resolvePathImpl = resolve,
   rmSyncImpl = rmSync,
   runInServer,
+  spawnSyncImpl,
   statSyncImpl = statSync,
   successImpl = success,
   tarCreateImpl,
@@ -296,12 +308,23 @@ export function createDbCommands({
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ confirm: "delete all data" }),
           });
-          const data = await res.json();
+          const data = await res.json().catch(() => null);
+          if (data === null) {
+            errorImpl("Server connection failed: the server response could not be read.");
+            logImpl("");
+            return 1;
+          }
 
           if (!res.ok) {
-            errorImpl(`Reset failed: ${data.error || "Unknown error"}`);
+            renderMaintenanceFailure(data, res.status, {
+              errorImpl,
+              infoImpl,
+              label: "Reset failed",
+              retryCommand: "gencow db:reset",
+              impactNote: "verify which tables still contain data before rerunning",
+            });
             logImpl("");
-            return;
+            return 1;
           }
 
           successImpl(`TRUNCATE done: ${data.truncated?.length || 0} tables`);
@@ -315,6 +338,8 @@ export function createDbCommands({
           }
         } catch (e) {
           errorImpl(`Server connection failed: ${e.message}`);
+          logImpl("");
+          return 1;
         }
       } else {
         const dbPath = resolvePathImpl(cwd, config.db.url);
@@ -442,13 +467,18 @@ export function createDbCommands({
           headers: { "Content-Type": "application/json" },
           signal: AbortSignal.timeout(30000),
         });
-        const data = await res.json();
+        const data = await res.json().catch(() => null);
+        if (data === null) {
+          errorImpl("Cloud app connection failed: the platform response could not be read.");
+          infoImpl(`${DIM}Check if the platform is reachable: ${targetCreds.platformUrl}${RESET}`);
+          return 1;
+        }
 
         if (res.status === 404 && String(data.error || "").includes("seed.ts")) {
           renderCloudSeedMissingFile({ infoImpl, logImpl, warnImpl });
           return 1;
         } else if (!res.ok) {
-          errorImpl(`Cloud seed failed: ${data.error || "Unknown error"}`);
+          renderMaintenanceFailure(data, res.status, { errorImpl, infoImpl });
           return 1;
         } else {
           successImpl("Cloud seed completed ✓");
@@ -531,6 +561,12 @@ export function createDbCommands({
         return;
       }
 
+      // Hints are validated before the config is read or the generator starts.
+      const hints = parseMigrationHintsArgs(args, {
+        cwd: cwdImpl(),
+        readFileSyncImpl,
+        resolvePathImpl,
+      });
       const config = await loadConfig();
       logImpl(`\n${BOLD}${CYAN}Gencow DB Generate${RESET}\n`);
       infoImpl("Generating migration files from schema.ts...");
@@ -540,6 +576,8 @@ export function createDbCommands({
         drizzleKitCmdImpl,
         env: buildEnv(config),
         execSyncImpl,
+        generatorArgs: hints.args,
+        spawnSyncImpl,
         stdio: "inherit",
         warnImpl,
       });

package/lib/db-push-command.mjs

@@ -28,7 +28,9 @@ import {
   buildClientPreflightFailureDiagnostic,
   buildClientUserFixableDiagnostic,
   buildMigrationFolderFormatDiagnostic,
+  buildMigrationHintsRequiredDiagnostic,
 } from "./migration-client-diagnostic.mjs";
+import { MIGRATION_HINTS_REQUIRED } from "./migration-hints.mjs";
 import { detectConflictingAuthSchemaFiles, formatAuthSchemaConflictMessage } from "./codegen-command.mjs";
 import { BOLD, CYAN, DIM, RESET } from "./output.mjs";
 import { stageMigrationBundleArchive } from "./migration-bundle-staging.mjs";
@@ -468,7 +470,9 @@ function createDbMigrationCommand(deps, command) {
             emitFailure(
               folderFormat
                 ? buildMigrationFolderFormatDiagnostic(folderFormat, clientCorrelationId())
-                : buildClientUserFixableDiagnostic("MIGRATION_GENERATION_FAILED", clientCorrelationId()),
+                : error?.code === MIGRATION_HINTS_REQUIRED
+                  ? buildMigrationHintsRequiredDiagnostic(error.migrationHints, clientCorrelationId())
+                  : buildClientUserFixableDiagnostic("MIGRATION_GENERATION_FAILED", clientCorrelationId()),
             );
             return;
           }

package/lib/db-seed-failure-render.mjs

@@ -0,0 +1,84 @@
+import { DIM, RESET } from "./output.mjs";
+
+const TYPED_CODE_PATTERN = /^(SEED|RESET)_[A-Z_]+$/;
+const UNAUTHORIZED_TEXT = "Seed request was not authorized for this app.";
+const UNEXPECTED_TEXT = "the platform returned an unexpected response.";
+const GENERIC_NEXT_ACTION = "Verify the app state, then rerun";
+const PLAIN_TEXT_LIMIT = 400;
+
+// Exact platform messages from packages/platform/gencow/apps-seed-handler.ts and apps-account-hold.ts.
+// Any other untyped text is never printed, even when it looks harmless.
+const KNOWN_PLATFORM_MESSAGES = new Set([
+  "App not found or not owned by you",
+  "Static-only app has no backend to seed",
+  "App is frozen — thaw before seed",
+  "App is locked because the owner account is suspended.",
+  "App is locked because the owner account is pending deletion.",
+  "App is locked because the owner account is deleted.",
+]);
+const KNOWN_NOT_RUNNING_PATTERN = /^Cloud app "[^"\n]{1,128}" is not running$/;
+
+// Typed text is rebuilt from the server catalog by the platform. This screen only blocks SQL-shaped text
+// that a tampered or future body could carry, because the CLI does not import the catalog.
+const SQL_SHAPED_PATTERN =
+  /Failed query|params:|\b(select|insert|update|delete|truncate|from|into|values|where)\b|\$\d/i;
+
+export function isTypedMaintenanceFailure(data) {
+  return (
+    data !== null &&
+    typeof data === "object" &&
+    typeof data.code === "string" &&
+    TYPED_CODE_PATTERN.test(data.code)
+  );
+}
+
+function typedText(value, fallback) {
+  if (typeof value !== "string" || value.trim() === "" || value.length > PLAIN_TEXT_LIMIT) return fallback;
+  return SQL_SHAPED_PATTERN.test(value) ? fallback : value;
+}
+
+function isKnownPlatformMessage(text) {
+  return KNOWN_PLATFORM_MESSAGES.has(text) || KNOWN_NOT_RUNNING_PATTERN.test(text);
+}
+
+/**
+ * Renders a failed db:seed or db:reset response. The label and retry command name the operation.
+ * - Typed platform failures show the code, stage, data impact, retry condition, next action and correlation ID.
+ * - Untyped responses print only a fixed sentence per status, or an exact known platform message.
+ *   Everything else, including raw database text, is replaced by the generic sentence.
+ */
+export function renderMaintenanceFailure(
+  data,
+  status,
+  { errorImpl, infoImpl, label = "Cloud seed failed", retryCommand = "gencow db:seed --prod", impactNote },
+) {
+  if (!isTypedMaintenanceFailure(data)) {
+    const text = typeof data?.error === "string" ? data.error : "";
+    if (status === 401 || status === 403) {
+      errorImpl(`${label}: ${UNAUTHORIZED_TEXT}`);
+      return;
+    }
+    if (isKnownPlatformMessage(text)) {
+      errorImpl(`${label}: ${text}`);
+      return;
+    }
+    errorImpl(`${label}: ${UNEXPECTED_TEXT}`);
+    infoImpl(`${DIM}Next action: ${GENERIC_NEXT_ACTION} \`${retryCommand}\`.${RESET}`);
+    return;
+  }
+
+  errorImpl(`${label}: ${typedText(data.error, "the platform reported a failure.")}`);
+  infoImpl(`${DIM}Code: ${data.code}${RESET}`);
+  infoImpl(`${DIM}Stage: ${typedText(data.stage, "unknown")}${RESET}`);
+  infoImpl(
+    `${DIM}Data impact: unknown — ${impactNote ?? "verify what was inserted before rerunning"}${RESET}`,
+  );
+  infoImpl(`${DIM}Retryable: ${data.retryable === true ? "yes" : "no"}${RESET}`);
+  infoImpl(
+    `${DIM}Retry condition: ${typedText(data.retryPrecondition, "Verify the current data before retrying.")}${RESET}`,
+  );
+  infoImpl(
+    `${DIM}Next action: ${typedText(data.nextAction, `${GENERIC_NEXT_ACTION} \`${retryCommand}\`.`)}${RESET}`,
+  );
+  infoImpl(`${DIM}Correlation: ${typedText(data.correlationId, "unavailable")}${RESET}`);
+}

package/lib/deploy-package-runtime.mjs

@@ -7,6 +7,7 @@ import { fetchAppDiagnosticLogsViaRest, normalizeDiagnosticLogLines } from "./ap
 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 { loadPackageJson } from "./deploy-project-package-json.mjs";
 import { resolveConfiguredAuditorImplementation } from "./auditor-mode.mjs";
 import {
   loadDeployMigrationGenerationContext,
@@ -398,12 +399,13 @@ export function createDeployPackageRuntime({
     warnRuntimePathsOutsideBackendRoot({ entryPoint, projectRoot: cwd, backendRoot, warnImpl });
     let dependencyAuditManifest = null;
     let dependencyVersionMessage = "";
-    let projectPkg;
+    const packageJson = loadPackageJson({ cwd, readFileSyncImpl, resolvePathImpl, errorImpl, exitImpl });
+    if (!packageJson) return null;
+    const projectPkg = packageJson.pkg;
     try {
       const { auditDependencyVersions, formatDependencyVersionAuditError } = await (
         loadDeployAuditorImpl ?? loadDeployAuditorDefault
       )();
-      projectPkg = JSON.parse(readFileSyncImpl(resolvePathImpl(cwd, "package.json"), "utf8"));
       const auditOptions = { cwd, existsSyncImpl, readFileSyncImpl };
       const dependencyVersionResult = auditDependencyVersions(projectPkg, auditOptions);
       dependencyVersionMessage = formatDependencyVersionAuditError(dependencyVersionResult);
@@ -447,9 +449,6 @@ export function createDeployPackageRuntime({
       }
     }
 
-    // Keep the manifest byte-compatible with the canonical pnpm lock importer.
-    const stagedPackageJson = readFileSyncImpl(resolvePathImpl(cwd, "package.json"), "utf8");
-
     let bundleBackendRoot;
     let bundleFileRows = [];
     try {
@@ -472,7 +471,7 @@ export function createDeployPackageRuntime({
         readFileSyncImpl,
         resolvePathImpl,
         rmSyncImpl,
-        stagedPackageJson,
+        stagedPackageJson: packageJson.text,
         tarCreateImpl,
         tmpBundle,
         writeCronManifestForProjectImpl,

package/lib/deploy-project-package-json.mjs

@@ -0,0 +1,79 @@
+// Reads the project package.json for deploy packaging. A missing, unreadable or non-JSON file is reported
+// as a typed, secret-free diagnosis (no raw fs/parser text, no absolute workspace path) and returns null.
+
+export const DEPLOY_PACKAGE_JSON_CODES = Object.freeze({
+  MISSING: "DEPLOY_PACKAGE_JSON_MISSING",
+  UNREADABLE: "DEPLOY_PACKAGE_JSON_UNREADABLE",
+  INVALID: "DEPLOY_PACKAGE_JSON_INVALID",
+});
+
+const NEXT_ACTION_FOR_MISSING =
+  "Next action: for a static-only site, run `gencow static --prod <build-output-dir>` (for example `gencow static --prod dist/`); for a backend app, run `npx gencow@latest init` to create a project with a package.json, then rerun deploy.";
+
+const DIAGNOSES = Object.freeze({
+  [DEPLOY_PACKAGE_JSON_CODES.MISSING]: {
+    message: "DEPLOY BLOCKED — package.json was not found in the project root.",
+    retryable:
+      "Retryable: yes, after package.json exists in the project root — run `ls package.json` to confirm, then rerun the same deploy command.",
+    nextAction: NEXT_ACTION_FOR_MISSING,
+  },
+  [DEPLOY_PACKAGE_JSON_CODES.UNREADABLE]: {
+    message: "DEPLOY BLOCKED — package.json exists but could not be read.",
+    retryable:
+      "Retryable: yes, after package.json is readable by the current user — check its file permissions, then rerun the same deploy command.",
+    nextAction:
+      "Next action: make package.json a readable regular file in the project root, then rerun deploy.",
+  },
+  [DEPLOY_PACKAGE_JSON_CODES.INVALID]: {
+    message: "DEPLOY BLOCKED — package.json is not a valid JSON object.",
+    retryable:
+      "Retryable: yes, after package.json is fixed — run `node -p \"require('./package.json').name\"` to see the syntax error, correct the file, then rerun the same deploy command.",
+    nextAction:
+      "Next action: correct the JSON syntax of package.json in the project root, then rerun deploy.",
+  },
+});
+
+export function formatDeployPackageJsonDiagnostic(code) {
+  const diagnosis = DIAGNOSES[code];
+  return [
+    diagnosis.message,
+    `Code: ${code}`,
+    "Stage: packaging",
+    "Database mutation: NONE",
+    "Incumbent serving: PRESERVED",
+    diagnosis.retryable,
+    diagnosis.nextAction,
+  ].join("\n");
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Returns { pkg, text } (text is the exact file content, so the staged manifest stays byte-identical to what
+// was validated), or null after printing the typed diagnosis and exiting with code 1.
+export function loadPackageJson({ cwd, readFileSyncImpl, resolvePathImpl, errorImpl, exitImpl }) {
+  let text;
+  let code = null;
+  try {
+    text = readFileSyncImpl(resolvePathImpl(cwd, "package.json"), "utf8");
+  } catch (caught) {
+    code =
+      caught?.code === "ENOENT" ? DEPLOY_PACKAGE_JSON_CODES.MISSING : DEPLOY_PACKAGE_JSON_CODES.UNREADABLE;
+  }
+  let pkg;
+  if (code === null) {
+    try {
+      pkg = JSON.parse(text);
+    } catch {
+      pkg = undefined;
+    }
+    if (!isPlainObject(pkg)) code = DEPLOY_PACKAGE_JSON_CODES.INVALID;
+  }
+  if (code !== null) {
+    errorImpl(formatDeployPackageJsonDiagnostic(code));
+    exitImpl(1);
+    return null;
+  }
+  return { pkg, text };
+}

package/lib/drizzle-generate.mjs

@@ -4,6 +4,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
 import { classifyMigrationFolderFormatFailure } from "./migration-folder-format.mjs";
+import {
+  classifyMissingHintsOutput,
+  createMigrationHintsRequiredError,
+  MIGRATION_HINTS_REQUIRED,
+} from "./migration-hints.mjs";
 
 export const SUPPORTED_DRIZZLE_KIT_GENERATOR_VERSION = SUPPORTED_MIGRATION_GENERATOR_VERSION;
 export const UNKNOWN_DRIZZLE_KIT_GENERATOR_VERSION = "unknown";
@@ -119,7 +124,22 @@ export function getMigrationFolderFormatFailure(error) {
   );
 }
 
+// Every raw stream the generator wrote; drizzle-kit reports hint requests on stdout.
+function rawGeneratorOutput(error) {
+  return (
+    error?.gencowRawGeneratorOutput ??
+    [error?.stdout, error?.stderr, error?.message].map((value) => String(value ?? "")).join("\n")
+  );
+}
+
+function getMissingHintsFailure(error) {
+  return classifyMissingHintsOutput(rawGeneratorOutput(error));
+}
+
 export function buildMigrationGenerationError(error) {
+  if (error?.code === MIGRATION_HINTS_REQUIRED && error.migrationHints) {
+    return createMigrationHintsRequiredError(error.migrationHints);
+  }
   const firstLine = getCommandErrorMessage(error).split("\n")[0] || "unknown generator error";
   const failure = new Error(`Migration generation failed: ${firstLine}`);
   const folderFormat = getMigrationFolderFormatFailure(error);
@@ -135,11 +155,17 @@ export function shouldRetryLegacyGenerate(error) {
   return message.includes("unknown command 'generate'") && message.includes("generate:pg");
 }
 
+// Quotes one argv element for the legacy string-command path (never used for spawn).
+function shellQuote(value) {
+  return `'${String(value).replace(/'/gu, `'\\''`)}'`;
+}
+
 export function runDrizzleGenerateWithFallback({
   cwd,
   drizzleKitCmdImpl,
   env = {},
   execSyncImpl,
+  generatorArgs = [],
   spawnSyncImpl = spawnSync,
   stderrWriteImpl = (value) => process.stderr.write(value),
   stdio = "inherit",
@@ -151,7 +177,7 @@ export function runDrizzleGenerateWithFallback({
     try {
       const generatorEnv = selectDrizzleGeneratorEnvironment(env, dk.env);
       if (typeof dk.command === "string" && Array.isArray(dk.args)) {
-        const result = spawnSyncImpl(dk.command, dk.args, {
+        const result = spawnSyncImpl(dk.command, [...dk.args, ...generatorArgs], {
           cwd,
           encoding: "utf8",
           env: generatorEnv,
@@ -169,6 +195,7 @@ export function runDrizzleGenerateWithFallback({
           Object.defineProperties(failure, {
             gencowGeneratorCwd: { value: cwd },
             gencowRawGeneratorMessage: { value: rawMessage },
+            gencowRawGeneratorOutput: { value: `${rawStdout}\n${rawStderr}\n${result.error?.message ?? ""}` },
           });
           throw failure;
         }
@@ -179,7 +206,10 @@ export function runDrizzleGenerateWithFallback({
           if (stderr) stderrWriteImpl(stderr);
         }
       } else {
-        execSyncImpl(dk.cmd, { cwd, env: generatorEnv, stdio });
+        const command = generatorArgs.length
+          ? [dk.cmd, ...generatorArgs.map(shellQuote)].join(" ")
+          : dk.cmd;
+        execSyncImpl(command, { cwd, env: generatorEnv, stdio });
       }
     } catch (error) {
       if (error && typeof error === "object") {
@@ -188,6 +218,16 @@ export function runDrizzleGenerateWithFallback({
         } catch {
           /* preserve the original generator error when the thrown value is immutable */
         }
+        const missingHints = getMissingHintsFailure(error);
+        if (missingHints) {
+          try {
+            error.code = MIGRATION_HINTS_REQUIRED;
+            error.migrationHints = { ...missingHints, hintsProvided: generatorArgs.length > 0 };
+          } catch {
+            /* keep the raw generator error; the hints code is then unavailable */
+          }
+          throw error;
+        }
         const folderFormat = getMigrationFolderFormatFailure(error);
         if (folderFormat) {
           try {

package/lib/migration-client-diagnostic.mjs

@@ -6,6 +6,7 @@ import {
 } from "@gencow/migration-contract";
 
 import { describeMigrationFolderFormatFailure } from "./migration-folder-format.mjs";
+import { buildHintsRequiredCommand, HINTS_DATA_LOSS_NOTICE, SAFE_COLUMN_REFERENCE } from "./migration-hints.mjs";
 
 const FORBIDDEN_ACTIONS = [
   "Do not use --force to bypass migration safety checks.",
@@ -50,6 +51,13 @@ const USER_FIXABLE_FAILURES = {
     detail:
       "Fix schema imports, types, or Drizzle configuration before uploading any existing migration bundle.",
   },
+  MIGRATION_HINTS_REQUIRED: {
+    phase: "GENERATE",
+    target: "SCHEMA_SOURCE",
+    summary: "Drizzle needs a rename or create decision for changed columns before it can generate migrations.",
+    detail:
+      "Run `npx gencow@latest db:generate --hints '<json-array>'` with one rename or create decision per changed column, then rerun this command. Do not edit applied migration files.",
+  },
   MIGRATION_BUNDLE_SCHEMA_CHANGE_WITHOUT_FORWARD_MIGRATION: {
     phase: "PREFLIGHT",
     target: "PENDING_MIGRATION",
@@ -93,6 +101,30 @@ export function buildClientUserFixableDiagnostic(code, correlationId) {
   };
 }
 
+// Same stable code and state as MIGRATION_HINTS_REQUIRED from db:generate, with the exact
+// retry command for the named column in text fields (USER_FIXABLE diagnostics cannot carry one).
+export function buildMigrationHintsRequiredDiagnostic(hints, correlationId) {
+  const columns = Array.isArray(hints?.columns)
+    ? hints.columns.filter((value) => typeof value === "string" && SAFE_COLUMN_REFERENCE.test(value))
+    : [];
+  const command = buildHintsRequiredCommand(columns);
+  const detail = `Declare each changed column with \`${command}\` (use {"type":"create",...} to add a new column instead), then rerun this command. ${HINTS_DATA_LOSS_NOTICE} Do not edit applied migration files.`;
+  const base = buildClientUserFixableDiagnostic("MIGRATION_HINTS_REQUIRED", correlationId);
+  return {
+    ...base,
+    retryCondition: "Run db:generate with --hints for each changed column, then rerun this command.",
+    reason: { code: "migration_hints_required", summary: base.reason.summary, detail },
+    suggestedFixes: [
+      {
+        ...base.suggestedFixes[0],
+        id: "migration_hints_required-fix",
+        title: "Declare the column decisions with db:generate --hints",
+        detail,
+      },
+    ],
+  };
+}
+
 // Same stable code and state as MIGRATION_GENERATION_FAILED, with the folder-format reason and the
 // pinned conversion command in text fields (USER_FIXABLE diagnostics cannot carry a command).
 export function buildMigrationFolderFormatDiagnostic(folderFormat, correlationId) {