@supatype/cli 0.3.0 → 0.3.1

package/src/commands/keys.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander"
-import { readFileSync, existsSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
+import { readEnvFile, upsertEnvFile } from "../env-file.js"
 import { signJwt } from "../jwt.js"
 import { error, plain } from "../ui/messages.js"
 
@@ -10,7 +11,9 @@ export function registerKeys(program: Command): void {
     .description("Generate ANON_KEY and SERVICE_ROLE_KEY JWTs from your JWT_SECRET")
     .option("--secret <secret>", "JWT secret (defaults to JWT_SECRET env var or value in .env)")
     .option("--exp-years <years>", "Token expiry in years (default: 10)", "10")
-    .action((opts: { secret?: string; expYears: string }) => {
+    .option("--write", "Write the keys into .env in the current directory instead of printing them")
+    .option("--force", "With --write, replace every key already in .env rather than filling blanks")
+    .action((opts: { secret?: string; expYears: string; write?: boolean; force?: boolean }) => {
       const secret = opts.secret ?? resolveSecret()
       if (!secret) {
         error("JWT_SECRET not found. Set it in .env or pass --secret <value>")
@@ -23,19 +26,116 @@ export function registerKeys(program: Command): void {
         process.exit(1)
       }
 
-      const now = Math.floor(Date.now() / 1000)
-      const exp = now + expYears * 365 * 24 * 60 * 60
+      const { anonKey, serviceKey } = signKeyPair(secret, expYears)
 
-      const anonKey = signJwt({ iss: "supatype", role: "anon", iat: now, exp }, secret)
-      const serviceKey = signJwt({ iss: "supatype", role: "service_role", iat: now, exp }, secret)
+      if (opts.write) {
+        const written = writeKeysToEnv(
+          process.cwd(),
+          { anonKey, serviceKey },
+          opts.force === true,
+        )
+        if (written.path === null) {
+          error("No .env here to write to. Create one, or drop --write to print the keys.")
+          process.exit(1)
+        }
+        plain(`\nKeys valid for ${expYears} years, written to ${written.path}:\n`)
+        // The names come back from the writer rather than being restated here, which is the whole
+        // point of there being one list.
+        for (const key of written.written) plain(`  ${key}`)
+        if (written.kept.length > 0) {
+          plain(`\nLeft alone, because they already hold a value:\n`)
+          for (const key of written.kept) plain(`  ${key}`)
+          plain("\nRe-run with --force to replace them.")
+        }
+        plain("\nDo not commit .env to source control.")
+        return
+      }
 
       plain(`\nGenerated keys (valid for ${expYears} years):\n`)
       plain("ANON_KEY=" + anonKey)
       plain("SERVICE_ROLE_KEY=" + serviceKey)
-      plain("\nAdd these to your .env file. Do not commit .env to source control.")
+      plain("\nAdd these to your .env file, or re-run with --write. Do not commit .env to source control.")
     })
 }
 
+/**
+ * Every env name a minted key pair is written to, in one place.
+ *
+ * Shared with `supatype dev`, which writes the same pair when it starts a stack. They used to hold
+ * separate lists, so a front end's prefix could be written by one and forgotten by the other, and
+ * which names your `.env` ended up with depended on whichever command you happened to run last.
+ *
+ * The URL names are only included when there is a URL to write, because an empty
+ * `VITE_SUPATYPE_URL` is worse than an absent one: the client reads it, finds a blank string, and
+ * requests against the page origin without saying why.
+ */
+export function anonKeyEnvUpdates(
+  anonKey: string,
+  serviceKey: string,
+  apiUrl?: string | undefined,
+): Record<string, string> {
+  return {
+    ANON_KEY: anonKey,
+    SERVICE_ROLE_KEY: serviceKey,
+    VITE_SUPATYPE_ANON_KEY: anonKey,
+    PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    ...(apiUrl !== undefined && {
+      VITE_SUPATYPE_URL: apiUrl,
+      PUBLIC_SUPATYPE_URL: apiUrl,
+      EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
+    }),
+  }
+}
+
+export interface WriteKeysResult {
+  /** The .env written, or null when there is none here. */
+  path: string | null
+  written: string[]
+  kept: string[]
+}
+
+/**
+ * Write a minted pair into `dir`'s .env.
+ *
+ * Blanks only by default. An anon key already in `.env` is held by clients this command cannot
+ * reach, and reissuing it locks them out, so filling what is empty is the useful half and
+ * replacing what is not is a decision someone has to make out loud. `--force` is how they make it,
+ * and it rewrites every name this owns rather than only the empty ones.
+ *
+ * `--force` does not rewrite the file. `.env` also holds `JWT_SECRET`, which these keys are
+ * derived from, along with the database password and whatever else the project keeps there;
+ * replacing the file would leave a project whose keys cannot be regenerated and whose stack cannot
+ * start. Every line this command does not own is left exactly as it was, comments included.
+ */
+export function writeKeysToEnv(
+  dir: string,
+  keys: { anonKey: string; serviceKey: string },
+  force: boolean,
+): WriteKeysResult {
+  const envPath = resolve(dir, ".env")
+  if (!existsSync(envPath)) return { path: null, written: [], kept: [] }
+
+  const existing = readEnvFile(dir)
+  const apiUrl = existing["PUBLIC_SUPATYPE_URL"] || existing["API_EXTERNAL_URL"] || undefined
+  const candidates = anonKeyEnvUpdates(keys.anonKey, keys.serviceKey, apiUrl)
+
+  const updates: Record<string, string> = {}
+  const kept: string[] = []
+  for (const [name, value] of Object.entries(candidates)) {
+    // Blank counts as absent: a template ships `ANON_KEY=` and that is exactly the line to fill.
+    const current = existing[name]?.trim() ?? ""
+    if (!force && current !== "") {
+      kept.push(name)
+      continue
+    }
+    updates[name] = value
+  }
+
+  if (Object.keys(updates).length > 0) upsertEnvFile(dir, updates)
+  return { path: envPath, written: Object.keys(updates), kept }
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /** Mint a long-lived anon + service_role JWT pair from a secret. */
@@ -91,6 +191,11 @@ function upsertEnvVar(content: string, key: string, value: string): string {
   return `${content}${sep}${key}=${value}\n`
 }
 
+/** Whether `.env` declares `key` at all, with or without a value. */
+function hasEnvLine(content: string, key: string): boolean {
+  return new RegExp(`^${key}=`, "m").test(content)
+}
+
 function readEnvVar(content: string, key: string): string | undefined {
   const re = new RegExp(`^${key}=(.*)$`, "m")
   const match = re.exec(content)

package/src/commands/push.ts

@@ -9,6 +9,7 @@ import {
   validateModelValidators,
   writeHooksModule,
 } from "../model-hooks.js"
+import { syncRowCacheEnv } from "../model-cache.js"
 import { adapterEntry, readHookUpload } from "../hook-upload.js"
 import { checkServiceRoleRoutes, serviceRoleProblemLines } from "../service-role-check.js"
 import { fatalError } from "../ui/fatal.js"
@@ -295,6 +296,16 @@ async function generateTypesLocal(ast: unknown, config: SupatypeProjectConfig):
   if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
   // The server watches this file, so a changed hook takes effect without a restart.
   if (syncManifestHooks(cwd, ast)) info("Hook map written to .supatype/manifest.json")
+  // The row cache is configured at postmaster start, so this is the one cache setting a push
+  // cannot make take effect on its own.
+  const rowCache = syncRowCacheEnv(cwd, ast)
+  if (rowCache !== null) {
+    info(
+      `Row cache switched ${rowCache} in .env. Recreate the database container for it to take ` +
+        "effect: the image writes pg_keyspace.conf at start, so a running Postgres keeps the " +
+        "setting it booted with.",
+    )
+  }
 
   if (!config.output?.types && !config.output?.client) return
   // The CLI writes these, it does not ask the engine to. Passing types_path and client_path and

package/src/dev-compose.ts

@@ -21,6 +21,8 @@ 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"
@@ -35,6 +37,7 @@ import {
   runDockerCompose,
   schemaEngineImageForPush,
   writeSelfHostCompose,
+  selfHostComposePaths,
   type SelfHostComposePaths,
 } from "./self-host-compose.js"
 import type { DockerBrandOptions } from "./docker-runtime.js"
@@ -288,13 +291,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,
@@ -594,12 +597,42 @@ async function refreshSchemaArtifacts(
   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).`)
+  }
 
   try {
     await ensureEngine()
   } catch (err) {
+    // 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) {
+      console.warn(
+        `[supatype] Host engine unavailable (${(err as Error).message}); used the in-compose ` +
+          "engine instead.",
+      )
+      return
+    }
     console.warn(
-      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}`,
+      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}
+` +
+        "[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
   }
@@ -1333,3 +1366,95 @@ 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).`)
+    }
+  }
+
+  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/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"
+}

package/src/self-host-compose.ts

@@ -402,18 +402,29 @@ ${studioService}
       - "127.0.0.1:\${SUPATYPE_DEV_DB_PORT:-54329}:5432"
 `
       : `    ports:
-      - "5432:5432"
+      - "\${SUPATYPE_DB_PORT:-5432}:5432"
 `
     : ""
+  // Host ports, every one of them overridable.
+  //
+  // Kong's has been `${SUPATYPE_KONG_PORT:-18473}` for as long as `supatype dev` has picked a free
+  // one per project and written it back to .env. These three were fixed literals, so the second
+  // project on a machine could not start: Docker refuses the bind and compose reports only that
+  // the stack would not come up, naming no port. Two projects side by side is the normal case
+  // here (this repository ships eight examples), so a literal is the wrong default.
+  //
+  // Defaults are the previous literals, so a project with none of these set behaves exactly as
+  // before. Allocating them per project the way the Kong port is allocated is the follow-up; this
+  // makes a second stack possible rather than automatic.
   const serverPorts = devLocal
     ? ""
     : `    ports:
-      - "9999:9999"
+      - "\${SUPATYPE_SERVER_PORT:-9999}:9999"
 `
   const seaweedPorts = devLocal
     ? ""
     : `    ports:
-      - "8333:8333"
+      - "\${SUPATYPE_SEAWEEDFS_PORT:-8333}:8333"
 `
   // One source for the credentials: the server is configured with them and the storage service is
   // handed them, and a mismatch does not fail at start, it fails at the first upload.
@@ -560,6 +571,29 @@ ${dbDependency}`
       SUPATYPE_KEYSPACE_KEYS: "200000"
       SUPATYPE_KEYSPACE_RING_MB: "16"
       SUPATYPE_KEYSPACE_ROWCACHE_MB: "64"
+      # Mode B, the row cache itself. The segment above is reserved either way; these two decide
+      # whether anything decodes into it or serves from it, and the image refuses readthrough
+      # without decode because that pair serves stale rows forever rather than merely wasting
+      # memory.
+      #
+      # From .env rather than a literal, because only a push can answer this: the switches follow
+      # whether any model declares \`cache: { rows: true }\`, and \`self-host compose render\` runs
+      # with no schema in hand. Default off, so a project that declares no row cache does not pin
+      # WAL behind a replication slot it never reads.
+      SUPATYPE_KEYSPACE_ROWCACHE_DECODE: "\${SUPATYPE_KEYSPACE_ROWCACHE_DECODE:-0}"
+      SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH: "\${SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH:-0}"
+      # Both decoders this stack runs, because the image's setting REPLACES the allowlist.
+      #
+      # Turning the row cache on makes the entrypoint write
+      # \`output_plugin_libraries = 'supacache_keys'\`, and PostgreSQL then refuses every other
+      # plugin. Realtime decodes with wal2json, so a project that declared \`cache: { rows: true }\`
+      # silently lost realtime: the service stayed up, answered /health/ready with 200, and logged
+      # \`library "wal2json" may not be used as an output plugin\` once a second while every
+      # subscription reported SUBSCRIBED and delivered nothing.
+      #
+      # Named here rather than left to the image because only this file knows both features are in
+      # the same stack.
+      SUPATYPE_KEYSPACE_OUTPUT_PLUGIN_LIBRARIES: "supacache_keys, wal2json"
 `
     : ""
 
@@ -705,7 +739,17 @@ ${dbDependency}
     # stays visible instead of hiding in a crash loop.
     restart: on-failure:5
 ${serverPorts}    volumes:
+      # The project is read-only: the server reads the schema, the manifest and the functions, and
+      # has no business editing any of them.
       - ${projectMount}:/project:ro
+      # .supatype is the exception, and only because one file in it is not project source.
+      # api-config.json is the operator's runtime state: which tables have caching switched on,
+      # the project TTL, max_rows. PATCH /admin/v1/config/rest writes it, which is what Studio's
+      # cache panel and the CLI's cache commands call. Under the read-only mount alone that PATCH
+      # fails with "read-only file system", so a cache a model declares can be read back as
+      # declared and never actually switched on. A narrower bind than making the whole project
+      # writable, because the rest of the tree keeps the guarantee.
+      - ${projectMount}/.supatype:/project/.supatype
     working_dir: /project
     environment:
       SUPATYPE_MODE: ${devLocal ? "dev" : "standalone"}

package/tests/keys-write.test.ts

@@ -0,0 +1,148 @@
+/**
+ * `supatype keys --write` writes the pair it mints.
+ *
+ * The command printed the keys and wrote nothing, while every README in this repository says it
+ * mints them into `.env`. Following the docs therefore produced a front end built with
+ * `anonKey: undefined` and a gateway refusing its every request, with nothing in the output saying
+ * so.
+ *
+ * Writing is opt-in rather than the default: a command that reads a secret and edits a file on
+ * sight is worse than one that has to be asked. What it writes is blanks only, because an anon key
+ * already in `.env` is held by clients this command cannot reach and reissuing it locks them out.
+ * `--force` is how someone says they meant to rotate.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { anonKeyEnvUpdates, writeKeysToEnv } from "../src/commands/keys.js"
+
+const PAIR = { anonKey: "anon.jwt.value", serviceKey: "service.jwt.value" }
+
+function envValue(dir: string, key: string): string | undefined {
+  const line = readFileSync(join(dir, ".env"), "utf8")
+    .split("\n")
+    .find((l) => l.startsWith(`${key}=`))
+  return line?.slice(key.length + 1).trim()
+}
+
+describe("writeKeysToEnv", () => {
+  let dir: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "supatype-keys-"))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it("fills blank keys", () => {
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\nANON_KEY=\nSERVICE_ROLE_KEY=\n")
+    const result = writeKeysToEnv(dir, PAIR, false)
+
+    expect(result.written).toContain("ANON_KEY")
+    expect(result.written).toContain("SERVICE_ROLE_KEY")
+    expect(envValue(dir, "ANON_KEY")).toBe(PAIR.anonKey)
+    expect(envValue(dir, "SERVICE_ROLE_KEY")).toBe(PAIR.serviceKey)
+  })
+
+  it("adds keys that are absent entirely", () => {
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\n")
+    writeKeysToEnv(dir, PAIR, false)
+
+    expect(envValue(dir, "ANON_KEY")).toBe(PAIR.anonKey)
+    expect(envValue(dir, "VITE_SUPATYPE_ANON_KEY")).toBe(PAIR.anonKey)
+  })
+
+  it("treats a declared-but-blank line as a blank to fill", () => {
+    // The templates ship `ANON_KEY=` with nothing after it, which is exactly the line to write.
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\nVITE_SUPATYPE_ANON_KEY=\n")
+    const result = writeKeysToEnv(dir, PAIR, false)
+
+    expect(result.written).toContain("VITE_SUPATYPE_ANON_KEY")
+    expect(envValue(dir, "VITE_SUPATYPE_ANON_KEY")).toBe(PAIR.anonKey)
+  })
+
+  it("leaves a key that already holds a value, and says which", () => {
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\nANON_KEY=in-use-by-clients\nSERVICE_ROLE_KEY=\n")
+    const result = writeKeysToEnv(dir, PAIR, false)
+
+    expect(result.kept).toContain("ANON_KEY")
+    expect(result.written).not.toContain("ANON_KEY")
+    expect(envValue(dir, "ANON_KEY")).toBe("in-use-by-clients")
+    expect(envValue(dir, "SERVICE_ROLE_KEY")).toBe(PAIR.serviceKey)
+  })
+
+  it("replaces every key it owns under --force, not only the blank ones", () => {
+    writeFileSync(
+      join(dir, ".env"),
+      "JWT_SECRET=s\nANON_KEY=old-anon\nSERVICE_ROLE_KEY=old-service\nVITE_SUPATYPE_ANON_KEY=old-vite\n",
+    )
+    const result = writeKeysToEnv(dir, PAIR, true)
+
+    expect(result.kept).toEqual([])
+    expect(envValue(dir, "ANON_KEY")).toBe(PAIR.anonKey)
+    expect(envValue(dir, "SERVICE_ROLE_KEY")).toBe(PAIR.serviceKey)
+    expect(envValue(dir, "VITE_SUPATYPE_ANON_KEY")).toBe(PAIR.anonKey)
+  })
+
+  it("does not rewrite the file, even under --force", () => {
+    // `.env` holds JWT_SECRET, which these keys are derived from, plus the database password and
+    // whatever else the project keeps there. Replacing the file would leave a project whose keys
+    // cannot be regenerated and whose stack cannot start.
+    writeFileSync(
+      join(dir, ".env"),
+      "# a comment someone wrote\nJWT_SECRET=s\nPOSTGRES_PASSWORD=pw\nANON_KEY=old\nCUSTOM_THING=mine\n",
+    )
+    writeKeysToEnv(dir, PAIR, true)
+
+    const content = readFileSync(join(dir, ".env"), "utf8")
+    expect(content).toContain("# a comment someone wrote")
+    expect(envValue(dir, "JWT_SECRET")).toBe("s")
+    expect(envValue(dir, "POSTGRES_PASSWORD")).toBe("pw")
+    expect(envValue(dir, "CUSTOM_THING")).toBe("mine")
+  })
+
+  it("carries the API URL through when the project records one", () => {
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\nPUBLIC_SUPATYPE_URL=http://localhost:18475\n")
+    writeKeysToEnv(dir, PAIR, true)
+
+    expect(envValue(dir, "VITE_SUPATYPE_URL")).toBe("http://localhost:18475")
+  })
+
+  it("writes no URL names when the project records no URL", () => {
+    // An empty `VITE_SUPATYPE_URL` is worse than an absent one: the client reads it, finds a blank
+    // string, and requests against the page origin without saying why.
+    writeFileSync(join(dir, ".env"), "JWT_SECRET=s\n")
+    writeKeysToEnv(dir, PAIR, false)
+
+    expect(readFileSync(join(dir, ".env"), "utf8")).not.toContain("VITE_SUPATYPE_URL")
+  })
+
+  it("reports no .env rather than creating one", () => {
+    const result = writeKeysToEnv(dir, PAIR, false)
+
+    expect(result.path).toBeNull()
+    expect(result.written).toEqual([])
+  })
+})
+
+describe("anonKeyEnvUpdates", () => {
+  it("is the one list both `keys` and `dev` write from", () => {
+    // They held separate lists, so a front end's prefix could be written by one and forgotten by
+    // the other, and which names a project's .env ended up with depended on which command ran last.
+    const names = Object.keys(anonKeyEnvUpdates("a", "s"))
+    expect(names).toEqual([
+      "ANON_KEY",
+      "SERVICE_ROLE_KEY",
+      "VITE_SUPATYPE_ANON_KEY",
+      "PUBLIC_SUPATYPE_ANON_KEY",
+      "EXPO_PUBLIC_SUPATYPE_ANON_KEY",
+    ])
+  })
+
+  it("adds the URL names only when given a URL", () => {
+    expect(Object.keys(anonKeyEnvUpdates("a", "s", "http://x"))).toContain("VITE_SUPATYPE_URL")
+    expect(Object.keys(anonKeyEnvUpdates("a", "s"))).not.toContain("VITE_SUPATYPE_URL")
+  })
+})