gencow 0.1.268 → 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/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) {

package/lib/migration-hints.mjs

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// drizzle-kit reports column rename-or-create decisions it cannot infer as
+// `missing_hints: N unresolved decisions` on stdout and exits non-zero. This module is the
+// single judgment for that output and for the user's --hints / --hints-file input.
+export const MIGRATION_HINTS_REQUIRED = "MIGRATION_HINTS_REQUIRED";
+export const MIGRATION_HINTS_INVALID = "MIGRATION_HINTS_INVALID";
+
+const MAX_HINTS_BYTES = 32 * 1024;
+const MAX_LISTED_COLUMNS = 8;
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/gu;
+const MISSING_HINTS_PATTERN = /^missing_hints:\s*(\d{1,4})\s+unresolved\b/mu;
+const DECISION_LINE_PATTERN = /^\s*\d+\.\s+Rename or create\b/u;
+const COLUMN_REF_PATTERN = /\bcolumn\s+(\S+)/u;
+// schema.table.column only; anything else is never echoed back to the user.
+export const SAFE_COLUMN_REFERENCE =
+  /^[A-Za-z_][A-Za-z0-9_]{0,62}\.[A-Za-z_][A-Za-z0-9_]{0,62}\.[A-Za-z_][A-Za-z0-9_]{0,62}$/u;
+
+// Returns { count, columns } when the generator output asks for hints, otherwise null.
+export function classifyMissingHintsOutput(rawOutput) {
+  const text = String(rawOutput ?? "").replace(ANSI_PATTERN, "");
+  const match = MISSING_HINTS_PATTERN.exec(text);
+  if (!match) return null;
+  const columns = [];
+  for (const line of text.split("\n")) {
+    if (!DECISION_LINE_PATTERN.test(line)) continue;
+    const ref = COLUMN_REF_PATTERN.exec(line)?.[1];
+    if (ref && SAFE_COLUMN_REFERENCE.test(ref) && !columns.includes(ref)) {
+      columns.push(ref);
+      if (columns.length === MAX_LISTED_COLUMNS) break;
+    }
+  }
+  return { count: Number(match[1]), columns };
+}
+
+// Shared by db:generate, db:push, and the db:generate help so the wording cannot drift.
+export const HINTS_DATA_LOSS_NOTICE =
+  "A rename keeps the existing column's data, while create adds a new column; an old column that is not renamed may be dropped and its data lost. Review the generated migration SQL before applying it.";
+
+// Exact retry command for the single decision we can name; placeholders otherwise.
+export function buildHintsRequiredCommand(columns) {
+  const [table, column] =
+    columns.length === 1 ? columns[0].split(".").slice(1) : ["<table>", "<new-column>"];
+  return `npx gencow@latest db:generate --hints '[{"type":"rename","kind":"column","from":["public","${table}","<old-column>"],"to":["public","${table}","${column}"]}]'`;
+}
+
+export function createMigrationHintsRequiredError({ count, columns, hintsProvided }) {
+  const error = new Error(`Migration generation needs ${count} decision(s) for changed columns.`);
+  error.code = MIGRATION_HINTS_REQUIRED;
+  error.migrationHints = { count, columns, hintsProvided: hintsProvided === true };
+  return error;
+}
+
+function invalidHints(reason, source) {
+  const error = new Error(`Migration hints rejected: ${reason}.`);
+  error.code = MIGRATION_HINTS_INVALID;
+  error.hintsReason = reason;
+  error.hintsSource = source;
+  return error;
+}
+
+function isHintsArray(value) {
+  return (
+    Array.isArray(value) && value.every((item) => item !== null && typeof item === "object" && !Array.isArray(item))
+  );
+}
+
+function validateHintsJson(text, source) {
+  if (Buffer.byteLength(text, "utf8") > MAX_HINTS_BYTES) throw invalidHints("too_large", source);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw invalidHints("json_invalid", source);
+  }
+  if (!isHintsArray(parsed)) throw invalidHints("not_array", source);
+}
+
+// Parses --hints / --hints-file (also in --flag=value form). Unknown arguments are ignored
+// as before. Returns the extra generator arguments; never invokes the generator itself.
+export function parseMigrationHintsArgs(args, { cwd, readFileSyncImpl = readFileSync, resolvePathImpl = resolve } = {}) {
+  const occurrences = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index]);
+    const flag = arg.startsWith("--hints-file") ? "--hints-file" : arg.startsWith("--hints") ? "--hints" : null;
+    if (!flag) continue;
+    const rest = arg.slice(flag.length);
+    if (rest !== "" && rest[0] !== "=") continue;
+    if (rest.startsWith("=")) {
+      occurrences.push({ flag, value: rest.slice(1) });
+    } else {
+      const next = args[index + 1];
+      occurrences.push({ flag, value: typeof next === "string" && !next.startsWith("--") ? next : undefined });
+      if (next !== undefined && !String(next).startsWith("--")) index += 1;
+    }
+  }
+  if (occurrences.length === 0) return { args: [] };
+  if (occurrences.length > 1) throw invalidHints("conflicting_options", "argument");
+  const [{ flag, value }] = occurrences;
+  const source = flag === "--hints" ? "inline" : "file";
+  if (typeof value !== "string" || value === "") throw invalidHints("value_missing", source);
+  if (flag === "--hints") {
+    validateHintsJson(value, source);
+    return { args: ["--hints", value] };
+  }
+  const absolutePath = resolvePathImpl(cwd ?? ".", value);
+  let text;
+  try {
+    text = readFileSyncImpl(absolutePath, "utf8");
+  } catch {
+    throw invalidHints("file_unreadable", source);
+  }
+  validateHintsJson(String(text), source);
+  return { args: ["--hints-file", absolutePath] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gencow",
-  "version": "0.1.268",
+  "version": "0.1.269",
   "description": "Gencow — AI Backend Engine",
   "type": "module",
   "bin": {
@@ -43,8 +43,8 @@
     "@gencow/client": "0.2.8",
     "@gencow/react": "0.2.8",
     "@gencow/core": "0.1.47",
-    "@gencow/server": "0.1.3",
-    "@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",