@supatype/cli 0.3.1 → 0.3.3

package/src/commands/init.ts

@@ -14,7 +14,10 @@ import {
   ensureComponentBinaries,
   reportComponentBinaryFailures,
 } from "../ensure-component-binaries.js"
-import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
+import {
+  ensureFunctionsDenoTypes,
+  sharedFunctionsReadmeSource,
+} from "../functions-deno-types.js"
 import { mergeSupatypePackageJson } from "../init-package-json.js"
 import { cliPackageVersion } from "../cli-package-version.js"
 import {
@@ -23,6 +26,7 @@ import {
   type InitDependencyVersions,
 } from "../init-dependency-versions.js"
 import { detectProjectSetup, type DetectedProjectSetup } from "../init-project-detect.js"
+import { SUPATYPE_GITIGNORE_PATHS } from "../gitignore.js"
 
 // ─── Options model ─────────────────────────────────────────────────────────--
 
@@ -789,7 +793,7 @@ function scaffoldHelloFunction(
 ): void {
   write("functions/hello/index.ts", helloFunctionTemplate())
   if (!existsSync(join(dir, "functions/_shared/README.md"))) {
-    write("functions/_shared/README.md", sharedFunctionsReadme())
+    write("functions/_shared/README.md", sharedFunctionsReadmeSource())
   }
   if (!existsSync(join(dir, "functions/.env.local"))) {
     write("functions/.env.local", functionsEnvLocalTemplate())
@@ -808,7 +812,12 @@ function packageJsonTemplate(opts: ScaffoldOptions, deps: InitDependencyVersions
   const scripts: string[] = [
     `    "dev": "supatype dev"`,
     `    "push": "supatype push"`,
-    `    "seed": "tsx seed.ts"`,
+    `    "seed": "supatype seed"`,
+    // The generated seed builder is gitignored, so a fresh clone has to produce it before
+    // anything can import it. `generate` is fully offline, which is the condition that makes
+    // gitignoring generated code reasonable rather than a trap; without this hook it would be
+    // one, and the failure would be a missing module rather than anything naming the remedy.
+    `    "prepare": "supatype generate"`,
   ]
   if (opts.app.viteDevUrl) {
     scripts.push(`    "vite": "vite"`)
@@ -1343,28 +1352,33 @@ S3_SECRET_KEY=`
 }
 
 function seedTemplate(projectName: string): string {
-  return `import { sql } from "@supatype/cli/seed"
-
-// Connect using DATABASE_URL from environment
-const db = sql(
-  process.env["DATABASE_URL"] ??
-    "postgresql://supatype_admin:postgres@localhost:5432/${projectName}",
-)
-
-async function seed() {
-  console.log("Seeding ${projectName}...")
-
-  // TODO: insert seed data
-  // await db\`INSERT INTO profile (id, display_name) VALUES ('...', 'Admin')\`
+  return `import type { SeedContext } from "@supatype/cli/seed"
+
+/**
+ * Seed data for ${projectName}. Run it with \`supatype seed\`.
+ *
+ * The calls below are collected rather than executed. They are ordered by their foreign keys,
+ * batched into as few statements as they allow, and applied in one transaction: so there is no
+ * connection to open, no ordering to work out by hand, and a failure leaves nothing behind.
+ *
+ * Usually written as \`{ db, expr, log }\`; taken whole here so the example can stay commented.
+ */
+export default async function seed(ctx: SeedContext) {
+  ctx.log("seeding ${projectName}")
+
+  // \`upsert\` is the one to reach for. Seeds get re-run, and naming the row by a key it already
+  // has is what makes that safe, without an id pasted in from somewhere.
+  //
+  // ctx.db.profile.upsert({
+  //   where: { id: "00000000-0000-4000-8000-000000000001" },
+  //   data: { display_name: "Admin" },
+  // })
 
-  await db.end()
-  console.log("Done.")
+  // Times the database works out, so a fixture calendar is still ahead of whenever an
+  // environment is seeded rather than fixed to whenever this file was written:
+  //
+  //   starts_at: ctx.expr.startOf("day", { days: 30, hours: 9 })
 }
-
-seed().catch((e) => {
-  console.error(e)
-  process.exit(1)
-})
 `
 }
 
@@ -1396,22 +1410,18 @@ export default async function handler(req: Request, ctx: FunctionContext): Promi
 `
 }
 
-function sharedFunctionsReadme(): string {
-  return "# Shared Code\n\nFiles in `_shared/` are available to all functions via relative imports.\nThis directory is not deployed as a function.\n\nExample: `import { sendEmail } from '../_shared/email.ts'`\n"
-}
 
 function functionsEnvLocalTemplate(): string {
   return "# Local environment variables for edge functions\n# These are NOT committed to git\n# Set production env vars via: npx supatype functions env set KEY=value\n"
 }
 
 function gitignoreTemplate(): string {
-  return `.env
+  // Supatype's own paths come from `SUPATYPE_GITIGNORE_PATHS` rather than being written out again
+  // here. This template and that list were two copies of the same thing and had already diverged;
+  // the copy that drifts is found when a key reaches a public repository.
+  return `${SUPATYPE_GITIGNORE_PATHS.join("\n")}
 node_modules/
 dist/
-.supatype/
-supatype.local.config.ts
-supatype.local.config.js
-supatype.local.config.mjs
 # Generated by supatype push (legacy paths, prefer output.types in config)
 src/types/supatype.d.ts
 src/lib/supatype.ts

package/src/commands/push.ts

@@ -33,7 +33,8 @@ import type { ExtractedSchemaAstV2 } from "../schema-ast-v2.js"
 import { ensureFirstAdminUser } from "./admin.js"
 import { withAdminRoles } from "../studio-admin-roles.js"
 import { restoreSystemRelationTargets } from "../restore-system-relation-targets.js"
-import { freeTierCacheNote, seedApiConfigCache } from "../api-config-cache.js"
+import { cacheSeedingNotes, freeTierCacheNote } from "../api-config-cache.js"
+import { refreshFunctionsContext } from "../functions-context-refresh.js"
 import type { SupatypeProjectConfig } from "../project-config.js"
 import {
   resolveTarget,
@@ -265,20 +266,7 @@ async function deployHooksToTarget(
  * Never an error, and never a rewrite of an entry that already exists. See `seedApiConfigCache`.
  */
 function reportCacheSeeding(cwd: string, ast: unknown): void {
-  const result = seedApiConfigCache(cwd, ast)
-  if (result === null) return
-
-  if (result.seeded.length > 0) {
-    info(`Server cache enabled for ${result.seeded.join(", ")} in .supatype/api-config.json`)
-  }
-  if (result.ttlIsOff) {
-    // A note rather than a fix. Zero is an off switch someone may have chosen, and a push that
-    // turned caching on project-wide would be overriding a decision rather than filling in a blank.
-    info(
-      `${result.declared.length} table(s) declare a cache, but cache_max_ttl is 0 — nothing is ` +
-        `cached until it is set, under API → REST → Settings or in .supatype/api-config.json.`,
-    )
-  }
+  for (const note of cacheSeedingNotes(cwd, ast)) info(note)
 }
 
 /** The generated adapter, flattened to the name handlers were rewritten to import. */
@@ -294,6 +282,17 @@ async function generateTypesLocal(ast: unknown, config: SupatypeProjectConfig):
   const cwd = process.cwd()
   const hooksPath = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
   if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
+
+  // `_shared/context.ts` too, for the same reason the hook module is here.
+  //
+  // It was written by `init` and `functions new` and by nothing else, so a project that predates
+  // the two-argument handler contract never received it: its functions had no `FunctionContext` to
+  // import, while the file itself claims "Regenerated by the CLI. Edits are overwritten." That
+  // claim was only true if you scaffolded again. `tests/integration` had four functions and no
+  // context module at all.
+  if (refreshFunctionsContext(cwd, config)) {
+    info("Function context type written to functions/_shared/context.ts")
+  }
   // 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

package/src/commands/seed.ts

@@ -1,15 +1,33 @@
+/**
+ * `supatype seed`: find the seed files, collect what they describe, hand it to the engine.
+ *
+ * Discovery and the Cloud guard are what this command already did. The rest is new only in
+ * that it collects rather than executes: no connection handling, no SQL, no transaction, no
+ * error mapping, because those are the engine's now and six more language runners should not
+ * each reimplement them and disagree.
+ *
+ * Both module shapes are supported. A default-exported function is the new contract and is
+ * handed a context; a module with no default export is the old one, which does its work on
+ * import and is told so by name. Nothing here removes the old shape.
+ */
+
 import type { Command } from "commander"
 import { existsSync, readdirSync } from "node:fs"
-import { join, resolve } from "node:path"
-import { isLinkedToCloudProject } from "../binary-cache.js"
-import { loadConfig } from "../config.js"
-import { projectRootFromConfig } from "../project-config.js"
-import { runTsFile } from "../tsx-runner.js"
-import { error, info } from "../ui/messages.js"
+import { join, relative, resolve, sep } from "node:path"
+import { isLinkedToCloudProject, pinnedVersion } from "../binary-cache.js"
+import { loadConfig, loadSchemaAst, type SupatypeConfig } from "../config.js"
+import { engineRequest, ensureEngine } from "../engine-client.js"
+import { seedUnsupportedByPinnedEngine } from "../engine-floor.js"
+import { pgSchema, projectRootFromConfig, schemaPathFromProject } from "../project-config.js"
+import { DsnNotFound, redact, resolveSeedDsn } from "../seed-connection.js"
+import { collectSeed, SeedCollectionFailed } from "../seed-runner.js"
+import { seedBuilderPathWithDefaults } from "../type-generation.js"
+import type { SeedConfig, SeedIr } from "../seed.js"
+import { error, info, success, warn } from "../ui/messages.js"
 
 const SEED_EXT = /\.(ts|mts|tsx)$/
 
-/** Seed entries under `seeds/`, sorted by filename (Phase 10.6 C19). */
+/** Seed entries under `seeds/`, sorted by filename. */
 export function discoverSeedsDir(cwd: string, seedsDir: string): string[] {
   if (!existsSync(seedsDir)) return []
   const names = readdirSync(seedsDir).filter((n) => SEED_EXT.test(n))
@@ -17,6 +35,21 @@ export function discoverSeedsDir(cwd: string, seedsDir: string): string[] {
   return names.map((n) => join(seedsDir, n))
 }
 
+/** One file's worth of collected IR, with what that file asked for. */
+interface Prepared {
+  file: string
+  document: SeedIr
+  config: SeedConfig
+}
+
+export interface SeedFlags {
+  force: boolean
+  atomic: boolean
+  status: boolean
+  connection?: string
+  environment?: string
+}
+
 export function registerSeed(program: Command): void {
   program
     .command("seed [file]")
@@ -28,42 +61,259 @@ export function registerSeed(program: Command): void {
       "Allow running when the project is linked to Supatype Cloud (dangerous)",
       false,
     )
-    .action(async (file: string | undefined, opts: { force: boolean }) => {
-      const cwd = process.cwd()
-      const config = loadConfig(cwd)
-      if (isLinkedToCloudProject(cwd, config) && !opts.force) {
-        error(
-          "This project is linked to Supatype Cloud. Refusing to run seeds locally.\n" +
-            "  Pass --force only if you intend to target this linked project (advanced).",
-        )
-        process.exit(1)
-      }
-
-      const root = projectRootFromConfig(config, cwd)
-      const seedsDir = join(root, "seeds")
-
-      let paths: string[]
-      if (file !== undefined && file.trim() !== "") {
-        paths = [resolve(cwd, file)]
-      } else {
-        paths = discoverSeedsDir(cwd, seedsDir)
-        if (paths.length === 0) {
-          paths = [resolve(root, "seed.ts")]
-        }
-      }
-
-      const missing = paths.filter((p) => !existsSync(p))
-      if (missing.length > 0) {
-        error(`Seed file(s) not found:\n  ${missing.join("\n  ")}`)
-        process.exit(1)
-      }
-
-      for (const seedFile of paths) {
-        info(`Running ${seedFile}...`)
-        const result = runTsFile(seedFile, { cwd, stdio: "inherit" })
-        if (result.exitCode !== 0) {
-          process.exit(result.exitCode)
-        }
-      }
+    .option("--atomic", "Run every seed file in one transaction", false)
+    .option("--status", "Show what has been applied, and what has changed since", false)
+    .option("--connection <dsn>", "Database to seed, instead of the resolved one")
+    .option("--environment <name>", "Environment name, for an `environment` condition")
+    .action(async (file: string | undefined, opts: SeedFlags) => {
+      const code = await runSeed(file, opts)
+      if (code !== 0) process.exit(code)
+    })
+}
+
+/**
+ * Separated from the action so the exit code is a value rather than a side effect.
+ *
+ * `0` applied, `1` a seed failed, `2` the run could not start. The split is what lets CI
+ * retry one and not the other.
+ */
+export async function runSeed(file: string | undefined, opts: SeedFlags): Promise<number> {
+  const cwd = process.cwd()
+  const config = loadConfig(cwd)
+
+  if (isLinkedToCloudProject(cwd, config) && !opts.force) {
+    error(
+      "This project is linked to Supatype Cloud. Refusing to run seeds locally.\n" +
+        "  Pass --force only if you intend to target this linked project (advanced).",
+    )
+    return 2
+  }
+
+  // Before the connection is resolved and before a builder is looked for: an engine that cannot
+  // seed makes both of those pointless, and the pin is the cheapest thing here to read.
+  const tooOld = seedUnsupportedByPinnedEngine(pinnedVersion("engine", config))
+  if (tooOld !== undefined) {
+    error(tooOld)
+    return 2
+  }
+
+  let dsn: string
+  try {
+    dsn = resolveSeedDsn(cwd, config, {
+      connection: opts.connection,
+      allowDerived: true,
+    }).dsn
+  } catch (e) {
+    error(e instanceof DsnNotFound ? e.message : String(e))
+    return 2
+  }
+
+  await ensureEngine()
+  if (opts.status) return await reportStatus(dsn)
+
+  const paths = seedPaths(file, cwd, config)
+  const missing = paths.filter((p) => !existsSync(p))
+  if (missing.length > 0) {
+    error(`Seed file(s) not found:\n  ${missing.join("\n  ")}`)
+    return 2
+  }
+
+  const builderPath = locateBuilder(cwd, config)
+  if (builderPath === undefined) return 2
+
+  const prepared: Prepared[] = []
+  for (const path of paths) {
+    const label = toPosix(relative(cwd, path))
+    let collected
+    try {
+      collected = collectSeed(path, {
+        cwd,
+        builderPath,
+        environment: opts.environment,
+      })
+    } catch (e) {
+      error(e instanceof SeedCollectionFailed ? e.message : String(e))
+      return 1
+    }
+
+    if (collected.stdout.trim().length > 0) {
+      for (const line of collected.stdout.trimEnd().split(/\r?\n/)) info(`  ${label}: ${line}`)
+    }
+    if (collected.result.shape === "legacy") {
+      warn(
+        `${label} has no default export, so it ran on import.\n` +
+          "  Export a default function to have its writes collected, ordered and applied in one transaction.",
+      )
+      continue
+    }
+    prepared.push({
+      file: label,
+      document: collected.result.ir,
+      config: collected.result.config,
     })
+  }
+
+  if (prepared.length === 0) {
+    info("No seed operations to apply.")
+    return 0
+  }
+
+  return await apply(prepared, { cwd, config, dsn, opts })
+}
+
+// --- Discovery ---
+
+function seedPaths(file: string | undefined, cwd: string, config: SupatypeConfig): string[] {
+  if (file !== undefined && file.trim() !== "") return [resolve(cwd, file)]
+  const root = projectRootFromConfig(config, cwd)
+  const fromDir = discoverSeedsDir(cwd, join(root, "seeds"))
+  return fromDir.length > 0 ? fromDir : [resolve(root, "seed.ts")]
+}
+
+/**
+ * The generated builder, which the runtime needs for the manifest and the fingerprint.
+ *
+ * Absent is a setup problem with a one-line remedy rather than a crash: the builder is
+ * gitignored by design, so a fresh clone that has not run `generate` is the ordinary case.
+ */
+function locateBuilder(cwd: string, config: SupatypeConfig): string | undefined {
+  const relativePath = seedBuilderPathWithDefaults(config.output)
+  const path = resolve(cwd, relativePath)
+  if (!existsSync(path)) {
+    error(
+      `The generated seed builder is missing: ${toPosix(relativePath)}\n` +
+        "  Run `supatype generate`. It needs no database and no running stack.",
+    )
+    return undefined
+  }
+  return path
+}
+
+// --- Applying ---
+
+interface ApplyOptions {
+  cwd: string
+  config: SupatypeConfig
+  dsn: string
+  opts: SeedFlags
+}
+
+async function apply(prepared: Prepared[], options: ApplyOptions): Promise<number> {
+  const { cwd, config, dsn, opts } = options
+  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+
+  // The engine takes one `--run-once` for the run, so a file asking for it decides for all
+  // of them. Said out loud rather than generalised silently, because the difference is
+  // whether work someone expected to happen happens.
+  const askedRunOnce = prepared.filter((one) => one.config.runOnce === true)
+  if (askedRunOnce.length > 0 && askedRunOnce.length !== prepared.length) {
+    warn(
+      "Some seed files declare `runOnce` and others do not, and the run takes one setting.\n" +
+        `  Applying it to all of them, because ${askedRunOnce
+          .map((one) => one.file)
+          .join(", ")} asked for it.`,
+    )
+  }
+
+  const result = await engineRequest<SeedResult>("/seed", {
+    ast,
+    ir_documents: prepared.map((one) => JSON.stringify({ ...one.document, file: one.file })),
+    database_url: dsn,
+    schema: pgSchema(config),
+    atomic: opts.atomic,
+    run_once: askedRunOnce.length > 0,
+    ...(opts.environment !== undefined ? { environment: opts.environment } : {}),
+  })
+
+  return report(result, prepared.length, dsn)
+}
+
+interface SeedResult {
+  ok: boolean
+  atomic?: boolean
+  files?: Array<{
+    file: string
+    status: string
+    written?: Record<string, number>
+    skippedGroups?: string[]
+  }>
+  error?: {
+    kind: string
+    message?: string
+    remedy?: string | null
+    file?: string
+    path?: string
+  }
+}
+
+/**
+ * Print what happened to every file, then the outcome.
+ *
+ * Every file, not just the one that failed: without `--atomic` a failure in the third of
+ * five leaves the first two committed, and a report that mentioned only the failure would
+ * leave the reader to guess at the rest.
+ */
+function report(result: SeedResult, count: number, dsn: string): number {
+  for (const file of result.files ?? []) {
+    const rows = Object.entries(file.written ?? {})
+      .map(([model, written]) => `${model} ${written}`)
+      .join(", ")
+    info(`  ${file.file.padEnd(32)} ${file.status}${rows.length > 0 ? `  (${rows})` : ""}`)
+    for (const skipped of file.skippedGroups ?? []) {
+      info(`    condition was false, skipped: ${skipped}`)
+    }
+  }
+
+  if (result.ok) {
+    success(`Seeded ${count} file(s) into ${redact(dsn)}.`)
+    return 0
+  }
+
+  const failure = result.error
+  if (failure === undefined) {
+    error("The seed failed, and the engine said nothing about why.")
+    return 1
+  }
+
+  const where = [failure.file, failure.path].filter((part) => part !== undefined && part !== "")
+  error(
+    (failure.message ?? failure.kind) +
+      (where.length > 0 ? `\n  at ${where.join(" ")}` : "") +
+      (failure.remedy !== undefined && failure.remedy !== null ? `\n  ${failure.remedy}` : ""),
+  )
+  // Nothing ran because nothing could: the environment, not the seed.
+  return failure.kind === "connection" || failure.kind === "document" ? 2 : 1
+}
+
+async function reportStatus(dsn: string): Promise<number> {
+  interface StatusEntry {
+    file: string
+    appliedAt: string
+    status: string
+    durationMs: number
+    drifted: boolean
+  }
+  const result = await engineRequest<{ files?: StatusEntry[] }>("/seed", {
+    database_url: dsn,
+    status: true,
+  })
+
+  const files = result.files ?? []
+  if (files.length === 0) {
+    info(`No seeds have been applied to ${redact(dsn)}.`)
+    return 0
+  }
+
+  for (const entry of files) {
+    info(
+      `  ${entry.file.padEnd(32)} ${entry.status.padEnd(12)} ${entry.appliedAt}  ` +
+        `${entry.durationMs}ms${entry.drifted ? "  changed since it was applied" : ""}`,
+    )
+  }
+  return 0
+}
+
+/** Reported with forward slashes, so the message reads the same on every platform. */
+function toPosix(path: string): string {
+  return path.split(sep).join("/")
 }

package/src/commands/update.ts

@@ -23,6 +23,21 @@ function resolveConfigFile(cwd: string): string | null {
   return null
 }
 
+/**
+ * New images alone are not a finished upgrade.
+ *
+ * Components carry schema with them: grants, policies and the rest are generated by the engine and
+ * applied by `push`, not baked into an image. Pulling a newer storage service onto a database that
+ * predates its grants leaves every private bucket read refused, and the only clue is in the
+ * service's log. The remedy is one command, so it is named here rather than left to be discovered.
+ */
+function pushReminder(): void {
+  plain("")
+  info("Run `supatype push` to apply schema changes the new components expect.")
+  plain("  Components ship code; grants, policies and functions come from your schema.")
+  plain("  Skipping it can leave storage reads and other rules refused until it runs.")
+}
+
 export function registerUpdate(program: Command): void {
   program
     .command("update")
@@ -37,7 +52,9 @@ export function registerUpdate(program: Command): void {
 
       if (provider === "docker") {
         if (opts.check) {
-          info("Docker provider: run without --check to pull compose images (supatype self-host compose pull).")
+          // There is no `self-host compose pull` subcommand; the earlier text named one and a reader
+          // following it got "unknown command". `update` is what pulls.
+          info("Docker provider: run `supatype update` without --check to pull the compose images.")
           return
         }
         const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
@@ -54,6 +71,7 @@ export function registerUpdate(program: Command): void {
           exitComposeFailed(status, "Could not pull Compose images.", brand)
         }
         info("Compose images updated.")
+        pushReminder()
         return
       }
 
@@ -149,5 +167,6 @@ export function registerUpdate(program: Command): void {
 
       writeFileSync(configPath, text, "utf8")
       info(`${basename(configPath)} updated.`)
+      pushReminder()
     })
 }

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 }
+}