@supatype/cli 0.3.0 → 0.3.2

package/src/db-port.ts

@@ -0,0 +1,99 @@
+/**
+ * Keep `DATABASE_URL` pointing at the port Postgres is actually published on.
+ *
+ * `SUPATYPE_DB_PORT` moves the host side of the compose port mapping, so a second project on one
+ * machine can avoid a clash. `DATABASE_URL` is what every host-side script uses: seeds, one-off
+ * psql, `supatype admin create-user --connection`. `init` writes the URL with 5432 in it and
+ * nothing has ever reconciled the two.
+ *
+ * The result is a project that starts cleanly, serves every request, and fails the first time
+ * someone runs `npm run seed`:
+ *
+ *   AggregateError [ECONNREFUSED]: connect ECONNREFUSED 127.0.0.1:5432
+ *
+ * with the database listening on 5433 and nothing connecting the error to the port variable the
+ * person set half an hour earlier. The generated `.env` even carries a comment conceding the
+ * assumption: "Self-host compose uses the same DATABASE_URL when Postgres is published on
+ * localhost:5432."
+ *
+ * `SUPATYPE_DB_PORT` is the source of truth, because it is what compose binds. The URL follows it.
+ */
+import { readEnvFile, upsertEnvFile } from "./env-file.js"
+
+/** The `.env` key that moves the published Postgres port for a self-host stack. */
+export const DB_PORT_ENV = "SUPATYPE_DB_PORT"
+
+/**
+ * The `.env` key that moves it for a dev-local stack, and which takes precedence.
+ *
+ * Two variables, two deployment shapes: an ordinary self-host stack publishes Postgres at
+ * `SUPATYPE_DB_PORT`, and a project with `overrides.engine` publishes it at
+ * `SUPATYPE_DEV_DB_PORT` so the host-side engine binary can reach it. Its presence is what marks
+ * the second shape, so it wins where both are set.
+ *
+ * Learned the hard way. The first cut of this file read only `SUPATYPE_DB_PORT`, so on a project
+ * with `SUPATYPE_DEV_DB_PORT=54330` it rewrote a correct `DATABASE_URL` to 5432, where nothing was
+ * listening. It fixed the bug it was written for and reintroduced it through the other door, which
+ * is the exact failure this file exists to prevent.
+ */
+export const DEV_DB_PORT_ENV = "SUPATYPE_DEV_DB_PORT"
+
+/** What compose binds when neither variable is set, and what `init` writes into the URL. */
+export const DEFAULT_DB_PORT = 5432
+
+/** Hosts whose port is ours to correct. Anything else is somebody else's database. */
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"])
+
+/** The port Postgres is published on for this project, from `.env`. */
+export function publishedDbPort(env: Record<string, string>): number {
+  // Dev-local first: its presence is what says this project publishes for a host-side engine.
+  for (const key of [DEV_DB_PORT_ENV, DB_PORT_ENV]) {
+    const raw = (env[key] ?? "").trim()
+    if (raw === "") continue
+    const port = Number(raw)
+    // A non-numeric or out-of-range value is the operator's to fix, and compose reports it far
+    // better than we can. Falling through keeps this from inventing a port nothing listens on.
+    if (Number.isInteger(port) && port > 0 && port < 65536) return port
+  }
+  return DEFAULT_DB_PORT
+}
+
+/** What changed, for the caller to report. */
+export interface DbPortSync {
+  from: string
+  to: string
+}
+
+/**
+ * Rewrite `DATABASE_URL`'s port to match `SUPATYPE_DB_PORT`, and report it.
+ *
+ * Returns null when there is nothing to do, which is the common case.
+ *
+ * Only touches a URL pointing at this machine. A project whose `DATABASE_URL` names a managed
+ * Postgres elsewhere has a port that is nothing to do with our compose mapping, and rewriting it
+ * would repoint the whole project at a database that does not exist.
+ */
+export function syncDatabaseUrlPort(cwd: string): DbPortSync | null {
+  const env = readEnvFile(cwd)
+  const raw = (env["DATABASE_URL"] ?? "").trim()
+  if (raw === "") return null
+
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    // Malformed, so not ours to rewrite: a partial edit here would turn a typo into a URL that
+    // parses and points somewhere wrong, which is harder to spot than the typo.
+    return null
+  }
+
+  if (!LOCAL_HOSTS.has(url.hostname)) return null
+
+  const wanted = String(publishedDbPort(env))
+  const current = url.port === "" ? String(DEFAULT_DB_PORT) : url.port
+  if (current === wanted) return null
+
+  url.port = wanted
+  upsertEnvFile(cwd, { DATABASE_URL: url.toString() })
+  return { from: current, to: wanted }
+}

package/src/dev-compose.ts

@@ -2,6 +2,7 @@
  * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
+import { writeAstDerivedOutputs } from "./type-generation.js"
 import { withPublishing } from "./model-versioning.js"
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
@@ -21,12 +22,18 @@ import {
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { syncManifestHooks, writeHooksModule } from "./model-hooks.js"
+import { syncRowCacheEnv } from "./model-cache.js"
+import { anonKeyEnvUpdates } from "./commands/keys.js"
 import { signJwt } from "./jwt.js"
 import { ensureDevDbPort, ensureKongPort } from "./dev-ports.js"
 import { handleComposeProjectRename } from "./compose-rename.js"
 import { recoverStaleDevSession, writeDevSessionLock } from "./dev-session-lock.js"
 import { endDevSession, startDevSession } from "./dev-session.js"
 import { ensureDevApiConfig } from "./ensure-dev-api-config.js"
+import { cacheSeedingNotes } from "./api-config-cache.js"
+import { refreshFunctionsContext } from "./functions-context-refresh.js"
+import { DB_PORT_ENV, syncDatabaseUrlPort } from "./db-port.js"
+import { degraded } from "./strict.js"
 import {
   COMPOSE_PINNED_IMAGE_ENV_KEYS,
   composeDockerImageEnv,
@@ -35,6 +42,7 @@ import {
   runDockerCompose,
   schemaEngineImageForPush,
   writeSelfHostCompose,
+  selfHostComposePaths,
   type SelfHostComposePaths,
 } from "./self-host-compose.js"
 import type { DockerBrandOptions } from "./docker-runtime.js"
@@ -288,13 +296,13 @@ export function upsertDevComposeEnv(
     ...seedMissingLocalSecrets(cwd),
     // Project configuration, seeded not overwritten, see seedMissingDatabaseIdentity.
     ...seedMissingDatabaseIdentity(cwd),
-    ANON_KEY: anonKey,
-    SERVICE_ROLE_KEY: serviceRoleKey,
-    PUBLIC_SUPATYPE_ANON_KEY: anonKey,
-    VITE_SUPATYPE_ANON_KEY: anonKey,
-    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
-    PUBLIC_SUPATYPE_URL: apiUrl,
-    EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
+    // Shared with `supatype keys --write`, so a front end's prefix cannot be written by one and
+    // forgotten by the other. See `anonKeyEnvUpdates`.
+    //
+    // This list used to live here as well, and the two had already drifted: `dev` wrote
+    // PUBLIC_ and EXPO_PUBLIC_ URLs and no VITE_SUPATYPE_URL, so a Vite app whose `.env` had only
+    // ever been touched by `supatype dev` built against an empty string.
+    ...anonKeyEnvUpdates(anonKey, serviceRoleKey, apiUrl),
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
     SITE_URL: apiUrl,
@@ -371,7 +379,16 @@ async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxM
   while (Date.now() < deadline) {
     const ready = spawnSync(
       "docker",
-      [...baseArgs, "exec", "-T", "db", "pg_isready", "-U", "supatype_admin"],
+      // Over TCP, deliberately, not the Unix socket.
+      //
+      // On a first run the Postgres entrypoint starts a temporary server with `listen_addresses=''`
+      // to run the init scripts, then shuts it down and starts the real one. That temporary server
+      // answers on the socket, so a socket `pg_isready` reports ready during init and the very next
+      // thing to connect meets "the database system is shutting down". It is why the initial push
+      // failed three times in a row on a clean machine while a warm one was fine.
+      //
+      // TCP is the distinction the entrypoint itself draws: the init server does not listen on it.
+      [...baseArgs, "exec", "-T", "db", "pg_isready", "-h", "127.0.0.1", "-U", "supatype_admin"],
       { cwd: composeDir, encoding: "utf8" },
     )
     if (ready.status === 0) return
@@ -591,15 +608,73 @@ async function refreshSchemaArtifacts(
   // validator silently not firing means a write the schema says is checked is accepted with a 201.
   const hooksModule = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
   if (hooksModule !== null) console.log(`[supatype] Hook handler types written to ${hooksModule}`)
+  // And the context module, on the same terms. `init` and `functions new` wrote it and nothing
+  // else did, so a project that already had functions when the two-argument contract landed never
+  // received one: its handlers had no `FunctionContext` to import.
+  if (refreshFunctionsContext(cwd, config)) {
+    console.log("[supatype] Function context type written to functions/_shared/context.ts")
+  }
   if (syncManifestHooks(cwd, ast)) {
     console.log("[supatype] Hook and validator maps written to .supatype/manifest.json")
   }
+  // Written before the stack comes up, so a first run with a row cache declared starts with it on
+  // rather than needing a second `supatype dev`.
+  const rowCache = syncRowCacheEnv(cwd, ast)
+  if (rowCache !== null) {
+    console.log(`[supatype] Row cache switched ${rowCache} in .env (pg_keyspace Mode B).`)
+  }
+
+  // SUPATYPE_DB_PORT moves what compose binds; DATABASE_URL is what seeds and psql use. Nothing
+  // reconciled them, so a project moved off 5432 to avoid a clash came up perfectly and then
+  // failed on `npm run seed` with ECONNREFUSED against a port nothing was listening on.
+  const dbPort = syncDatabaseUrlPort(cwd)
+  if (dbPort !== null) {
+    console.log(
+      `[supatype] DATABASE_URL port ${dbPort.from} -> ${dbPort.to} in .env, ` +
+        `to match ${DB_PORT_ENV}.`,
+    )
+  }
+
+  // The declaration is a ceiling and the allowlist is what is actually on, and only `push` ever
+  // seeded the allowlist. So a stack brought up with `supatype dev` alone had every model's
+  // `cache` block declared and nothing switched on: `.cache({ server: true })` answered BYPASS,
+  // and the only way to find out why was to open Studio and tick a box the schema had already
+  // justified.
+  for (const note of cacheSeedingNotes(cwd, ast)) console.log(`[supatype] ${note}`)
 
   try {
     await ensureEngine()
   } catch (err) {
-    console.warn(
-      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}`,
+    // The host engine is a CDN download and this machine could not complete it. The schema is
+    // already applied, so fall back to the engine in compose rather than giving up: without
+    // admin-config.json Studio reports "No schema has been pushed yet" on a stack whose schema is
+    // entirely live, which reads as a failed push rather than a missing binary.
+    const paths = selfHostComposePaths(cwd)
+    const composeProject = composeProjectName(config.project.name)
+    const wrote = await generateViaComposeEngine(
+      paths,
+      cwd,
+      composeProject,
+      config,
+      ast,
+      adminConfigPath,
+    ).catch(() => false)
+    if (wrote) {
+      // Reported through `degraded` rather than warned: the in-compose engine writes the admin
+      // config but never reaches the type generation below, so a run that takes this path has
+      // stale generated types and says so only in a line that scrolls past. In CI that is the
+      // difference between testing the host engine path and never touching it.
+      degraded(
+        "Host engine unavailable, used the in-compose engine instead",
+        (err as Error).message,
+      )
+      return
+    }
+    degraded(
+      "Host engine unavailable, admin config and types not refreshed",
+      `${(err as Error).message}\n` +
+        "[supatype] Studio will report no schema until this succeeds, even though the schema is " +
+        "applied. Retry with the stack up, or run `supatype push`.",
     )
     return
   }
@@ -627,6 +702,23 @@ async function refreshSchemaArtifacts(
     }
   }
 
+  // Needs no engine, so it is written whether or not the types step above ran or succeeded. This
+  // is what `dev` never did: a project developed entirely through `supatype dev` received neither
+  // `index.d.ts`, which is what makes `createClient` typed without a generic, nor the field kinds
+  // the client reads to keep bigInt, decimal and money columns exact.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message}`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
   try {
     const admin = withAdminRoles(await engineRequest<unknown>("/admin", { ast }), config)
     restoreSystemRelationTargets(admin, ast)
@@ -919,7 +1011,16 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     throw new Error(detail || `Engine schema diff failed (exit ${result.status})`)
   }
   if (!result.diff) {
-    throw new Error("Engine diff returned no result")
+    // The engine exited 0 and produced nothing this could parse, which is a different failure from
+    // the engine exiting non-zero and is the harder one to act on. "Engine diff returned no result"
+    // named only the symptom, and running the same compose command by hand gave a clear error in
+    // one go, so the message was the only thing standing between the reader and the answer.
+    const output = (filterComposeNoise(result.output) || result.output || "").trim()
+    throw new Error(
+      output === ""
+        ? "The schema engine exited 0 and printed nothing. Run `supatype self-host compose run --rm schema-engine diff` to see what it does."
+        : `The schema engine exited 0 but its output could not be parsed as a diff:\n${output}`,
+    )
   }
   return result.diff
 }
@@ -1126,19 +1227,26 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     }
   }
 
-  const pinnedRealtimeImage = readEnvValue(cwd, "SUPATYPE_REALTIME_IMAGE", "").trim()
-  if (pinnedRealtimeImage !== "") {
-    console.log("[supatype] Recreating realtime with pinned image...")
-    const rtStatus = runDockerCompose(
+  // A service whose image is pinned in `.env` is recreated once the stack is up, so a contributor
+  // can point at a build from this checkout rather than the published tag.
+  //
+  // Storage was missing from this list, which is why a storage bug survived: there was no way to
+  // run the suite against a local storage build, so every integration run tested the last release
+  // no matter what the working tree said.
+  for (const service of ["realtime", "storage"] as const) {
+    const variable = `SUPATYPE_${service.toUpperCase()}_IMAGE`
+    if (readEnvValue(cwd, variable, "").trim() === "") continue
+    console.log(`[supatype] Recreating ${service} with pinned image...`)
+    const status = runDockerCompose(
       paths.composePath,
-      ["up", "-d", "--force-recreate", "--no-deps", "realtime"],
+      ["up", "-d", "--force-recreate", "--no-deps", service],
       cwd,
       project,
       { quiet: true, brand: devBrand },
     )
-    if (rtStatus !== 0) {
+    if (status !== 0) {
       endDevSession()
-      exitComposeFailed(rtStatus, "Could not recreate the realtime container.", devBrand)
+      exitComposeFailed(status, `Could not recreate the ${service} container.`, devBrand)
     }
   }
 
@@ -1306,8 +1414,17 @@ function reconcileAuthenticatorPassword(
     },
   )
   if (result.status !== 0) {
+    // The cause, not just the consequence. This warned that REST "may answer 502" and said nothing
+    // about why, so when the supabucks e2e then failed its only API assertion with a 502, the
+    // warning twenty lines earlier read as unrelated noise. A message that predicts a failure and
+    // withholds its reason costs more than one that says nothing.
+    const detail = [result.stderr, result.error?.message]
+      .map((s) => (s ?? "").trim())
+      .filter((s) => s.length > 0)
+      .join("\n")
     console.warn(
-      "[supatype] Could not set the authenticator password; the REST API may answer 502.",
+      `[supatype] Could not set the authenticator password, so the REST API will answer 502.\n` +
+        (detail === "" ? "[supatype] docker gave no output." : detail),
     )
   }
 }
@@ -1333,3 +1450,111 @@ function grantAuthSchemaAccess(
     console.warn("[supatype] Could not grant service_role access to auth.users, Studio relation preview may fail.")
   }
 }
+
+/**
+ * Run one read-only generator in the in-compose schema-engine and return its stdout.
+ *
+ * The same image and the same bind mount the push just used, so if the schema could be applied
+ * this can run. It exists because the host engine is a separate binary fetched from a CDN, and a
+ * machine that cannot fetch it is not a machine that cannot generate: the schema is already
+ * applied, the AST is already on disk, and the container that did it is one `docker compose run`
+ * away.
+ */
+async function runComposeEngineGenerator(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  config: SupatypeProjectConfig,
+  args: readonly string[],
+): Promise<string | null> {
+  const envFile = resolve(cwd, ".env")
+  const composeArgs = ["compose", "--progress", "quiet"]
+  if (composeProject) composeArgs.push("-p", composeProject)
+  composeArgs.push("--project-directory", cwd)
+  composeArgs.push("-f", paths.composePath)
+  if (existsSync(envFile)) composeArgs.push("--env-file", envFile)
+  composeArgs.push(
+    "--profile",
+    "tools",
+    "run",
+    "--rm",
+    "-T",
+    "schema-engine",
+    ...args,
+    "-i",
+    "/project/.supatype/schema.ast.json",
+  )
+
+  const env: NodeJS.ProcessEnv = { ...process.env, COMPOSE_PROGRESS: "quiet" }
+  const engineImage = await schemaEngineImageForPush(config)
+  if (engineImage) env.SUPATYPE_ENGINE_IMAGE = engineImage
+
+  const result = spawnSync("docker", composeArgs, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    env,
+  })
+  if ((result.status ?? 1) !== 0) return null
+  return String(result.stdout ?? "")
+}
+
+/**
+ * Write `admin-config.json` and the generated types using the in-compose engine.
+ *
+ * The fallback for a host engine that could not be fetched. Without it, a `supatype dev` that
+ * applied the schema perfectly well still left no `admin-config.json`, and Studio reads that file
+ * to decide whether a schema exists: the stack came up, every table was live, the API served them,
+ * and Studio said **"No schema has been pushed yet."** The warning that preceded it named the
+ * download, not the consequence, so nothing connected the two.
+ *
+ * Returns true when the admin config was written, which is the file Studio actually needs.
+ */
+export async function generateViaComposeEngine(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  config: SupatypeProjectConfig,
+  ast: unknown,
+  adminConfigPath: string,
+): Promise<boolean> {
+  const typesPath = config.output?.types
+  if (typeof typesPath === "string" && typesPath.trim().length > 0) {
+    const out = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["generate"])
+    const marker = out?.indexOf("// Generated by supatype-engine") ?? -1
+    if (out && out.includes("export type")) {
+      const ts = (marker >= 0 ? out.slice(marker) : out).trimStart()
+      const hostPath = join(cwd, typesPath)
+      mkdirSync(dirname(hostPath), { recursive: true })
+      writeFileSync(hostPath, ts)
+      console.log(`[supatype] Types written to ${typesPath} (in-compose engine).`)
+    }
+  }
+
+  // The same AST-derived files as the host path. This is the fallback used when the host engine
+  // could not be fetched, and these need no engine at all, so there is no reason for a project on
+  // this path to end up with fewer generated files than one on the other.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message} (in-compose engine).`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
+  const adminOut = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["admin"])
+  if (!adminOut) return false
+  const parsed = parseEngineJsonOutput<unknown>(adminOut)
+  if (parsed === null) return false
+
+  const admin = withAdminRoles(parsed, config)
+  restoreSystemRelationTargets(admin, ast)
+  writeFileSync(adminConfigPath, `${JSON.stringify(admin, null, 2)}\n`)
+  console.log("[supatype] Admin config written to .supatype/admin-config.json (in-compose engine).")
+  return true
+}

package/src/functions-context-refresh.ts

@@ -0,0 +1,25 @@
+/**
+ * Keep `functions/_shared/context.ts` current on a project that already exists.
+ *
+ * The module is generated by `ensureFunctionsDenoTypes`, which `init` and `supatype functions new`
+ * call and nothing else did. So it reached new projects and new functions, and never reached a
+ * project that already had functions when the two-argument handler contract landed: those keep
+ * `(req)` handlers with no `FunctionContext` to import, while the generated file asserts
+ * "Regenerated by the CLI. Edits are overwritten."
+ *
+ * A claim about a file nothing maintains is worse than no claim, because it tells people not to
+ * edit it and not to expect it to change.
+ *
+ * Only when the project has a functions directory: writing `_shared/` into a project that has no
+ * functions would create the thing it describes out of nothing.
+ */
+import { existsSync } from "node:fs"
+import { ensureFunctionsDenoTypes } from "./functions-deno-types.js"
+import { preferredFunctionsPathFromProject, type SupatypeProjectConfig } from "./project-config.js"
+
+/** Rewrite the context module. True when this project has functions and one was written. */
+export function refreshFunctionsContext(cwd: string, config: SupatypeProjectConfig): boolean {
+  const functionsDir = preferredFunctionsPathFromProject(config, cwd)
+  if (!existsSync(functionsDir)) return false
+  return ensureFunctionsDenoTypes(cwd, functionsDir).wroteContextModule
+}

package/src/functions-deno-types.ts

@@ -83,6 +83,23 @@ declare namespace Deno {
  * directory, but `deno check` builds its own type graph and does not look at either, so a function
  * naming an ambient type fails the check the runtime itself would run. An import works in both.
  */
+/**
+ * The `_shared/README.md` both scaffolds write.
+ *
+ * One definition because there were two, identical, as string literals in `init.ts` and
+ * `functions.ts`. It lives here rather than in either because this module already owns what goes
+ * into `_shared/`, and because the next edit to this text would otherwise change it in one scaffold
+ * and not the other.
+ */
+export function sharedFunctionsReadmeSource(): string {
+  return (
+    "# Shared Code\n\n" +
+    "Files in `_shared/` are available to all functions via relative imports.\n" +
+    "This directory is not deployed as a function.\n\n" +
+    "Example: `import { sendEmail } from '../_shared/email.ts'`\n"
+  )
+}
+
 export function functionsContextModuleSource(): string {
   return `/**
  * What a function is told about the call it is serving.
@@ -94,7 +111,13 @@ export function functionsContextModuleSource(): string {
  *
  * Passing them in removes the global, so functions run concurrently.
  *
- * Regenerated by the CLI. Edits are overwritten.
+ * Rewritten by supatype init, supatype functions new, supatype push and supatype dev.
+ * Edits are overwritten.
+ *
+ * Named explicitly because "regenerated by the CLI" was true of only the first two: a project that
+ * already had functions when this contract arrived never received the module at all, so its
+ * handlers had no type to import while this line told its author the file was maintained. Say
+ * which commands, so the claim can be checked rather than believed.
  */
 export interface FunctionContext {
   /** Unique to this invocation. Every log line it writes carries the same value. */

package/src/gitignore.ts

@@ -2,12 +2,35 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
 
 export const SUPATYPE_GITIGNORE_MARKER = "# Supatype, local runtime (contains secrets in link.json)"
+
+/**
+ * Every path Supatype writes that holds a secret, in one place.
+ *
+ * One list because there were two emitters, this one and `init`'s own template, and they had
+ * already drifted apart on content. Two lists of the same thing drift again, and the half that
+ * drifts is discovered by a key reaching a public repository.
+ *
+ * `.env.local` and `.env.*.local` are here because `.env` does not cover them. That pattern matches
+ * a file named exactly `.env`, while `supatype functions new` writes `functions/.env.local` with
+ * "These are NOT committed to git" at the top of it, and the worker reads
+ * `.env.<function>.local` beside that. Verified with `git check-ignore`: under `.env` alone both
+ * were tracked; with these two they are ignored at any depth, and no source file is caught.
+ */
+const SUPATYPE_IGNORED_PATHS = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  ".supatype/",
+  "supatype.local.config.ts",
+  "supatype.local.config.js",
+  "supatype.local.config.mjs",
+] as const
+
+/** The paths above, for a scaffold that composes its own `.gitignore` around them. */
+export const SUPATYPE_GITIGNORE_PATHS: readonly string[] = SUPATYPE_IGNORED_PATHS
+
 export const SUPATYPE_GITIGNORE_BLOCK = `${SUPATYPE_GITIGNORE_MARKER}
-.env
-.supatype/
-supatype.local.config.ts
-supatype.local.config.js
-supatype.local.config.mjs
+${SUPATYPE_IGNORED_PATHS.join("\n")}
 `
 
 export function isSupatypeGitignored(cwd: string): boolean {
@@ -26,11 +49,9 @@ export function ensureSupatypeGitignore(cwd: string, opts?: { silent?: boolean }
     const next = content.endsWith("\n") ? content : `${content}\n`
     writeFileSync(gitignorePath, `${next}\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   } else {
-    writeFileSync(
-      gitignorePath,
-      `.env\nnode_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`,
-      "utf8",
-    )
+    // `.env` is not repeated here: the block below already carries it, along with the
+    // `.env.local` patterns it does not cover.
+    writeFileSync(gitignorePath, `node_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   }
 
   if (!opts?.silent) {

package/src/model-cache.ts

@@ -16,6 +16,7 @@
  * `hooks` has always taken this route for the same reason. Plan §13.1 said otherwise and said to
  * verify before relying on it; this is the verified path.
  */
+import { readEnvValue, upsertEnvFile } from "./env-file.js"
 import type { ModelCacheAst } from "./schema-ast-v2.js"
 
 /** One table's cache declaration, as the manifest carries it. */
@@ -72,3 +73,50 @@ export function manifestCache(ast: unknown): Record<string, ManifestCacheEntry>
   }
   return out
 }
+
+// ─── Row cache enablement ────────────────────────────────────────────────────
+
+/** The two env names the Postgres image reads to turn Mode B on. */
+export const ROWCACHE_DECODE_ENV = "SUPATYPE_KEYSPACE_ROWCACHE_DECODE"
+export const ROWCACHE_READTHROUGH_ENV = "SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH"
+
+/** Whether any model declares `cache: { rows: true }`. */
+export function declaresRowCache(ast: unknown): boolean {
+  return Object.values(manifestCache(ast)).some((entry) => entry.rows === true)
+}
+
+/**
+ * Keep the row cache's two switches in `.env` matching what the schema declares.
+ *
+ * `cache: { rows: true }` registers a table with the row cache, and registration alone serves
+ * nothing: Mode B needs `pg_keyspace.rowcache_decode` for the invalidation worker and
+ * `rowcache_readthrough` to fill on a primary-key miss. Both are written by the image's entrypoint
+ * from these variables, before any server starts, so they cannot be switched at runtime and cannot
+ * be decided by the compose file alone: only a push knows whether any model declares `rows`.
+ *
+ * Without this the stack came up with the row-cache segment reserved, the tables registered, both
+ * switches off and nothing anywhere saying so. Studio's panel was the only thing that reported it,
+ * and it reported it as an operator's missing configuration rather than as a push that had not
+ * finished the job.
+ *
+ * Written to `.env` rather than baked into the compose file for the same reason `SUPATYPE_KONG_PORT`
+ * is: `self-host compose render` runs with no AST in hand, so a value the compose file hardcoded
+ * would be whatever the last render guessed.
+ *
+ * Returns the new state when it changed, and null when it did not. A change needs the database
+ * container recreated, which the caller is the one that can say.
+ */
+export function syncRowCacheEnv(cwd: string, ast: unknown): "on" | "off" | null {
+  const want = declaresRowCache(ast)
+  const value = want ? "1" : "0"
+
+  const current = readEnvValue(cwd, ROWCACHE_DECODE_ENV, "")
+  const currentThrough = readEnvValue(cwd, ROWCACHE_READTHROUGH_ENV, "")
+  if (current === value && currentThrough === value) return null
+
+  upsertEnvFile(cwd, {
+    [ROWCACHE_DECODE_ENV]: value,
+    [ROWCACHE_READTHROUGH_ENV]: value,
+  })
+  return want ? "on" : "off"
+}