@supatype/cli 0.1.6 → 0.1.7

package/src/dev-compose.ts

@@ -15,6 +15,7 @@ import {
   projectRootFromConfig,
   resolveRuntimeProvider,
   schemaPathFromProject,
+  usesExternalDatabase,
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { signJwt } from "./jwt.js"
@@ -40,6 +41,12 @@ import { ensureLocalServerDockerImage } from "./compose-local-server-image.js"
 import { ensureEngine, engineRequest, type DiffResult } from "./engine-client.js"
 import { writeSchemaSourcePushArtifacts, type SchemaSourcePushArtifacts } from "./schema-sources.js"
 import { readEnvValue, upsertEnvFile } from "./env-file.js"
+import {
+  devJwtSecret,
+  devPostgresPassword,
+  seedMissingDatabaseIdentity,
+  seedMissingLocalSecrets,
+} from "./local-secrets.js"
 import { writeLocalEnvironment } from "./link.js"
 import { registerDevShutdown } from "./dev-shutdown.js"
 import {
@@ -55,16 +62,19 @@ import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
 import { ensureFirstAdminUserForProject } from "./commands/admin.js"
 import { publishDevReady } from "./dev-ready-panel.js"
 
-const LOCAL_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long"
-
 /** Default host port for compose Postgres when `overrides.engine` is set (devLocal). */
 const COMPOSE_DEV_DB_PORT = 54329
 
 /** Sync optional Docker image pins from config into `.env` (no JWT rotation). */
 export function syncComposeImagePins(cwd: string, config: SupatypeProjectConfig): void {
   const imagePins = composeDockerImageEnv(config)
+  // Clean up only what a previous run wrote from config. A hand-written image tag in `.env` is the
+  // documented way to run a local build, and this used to delete it on every compose run.
   const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
-  upsertEnvFile(cwd, imagePins, removeImageKeys)
+  upsertEnvFile(cwd, imagePins, {
+    removeManaged: removeImageKeys,
+    managed: COMPOSE_PINNED_IMAGE_ENV_KEYS,
+  })
 }
 
 export interface DevComposeOptions {
@@ -72,8 +82,10 @@ export interface DevComposeOptions {
 }
 
 /** In-compose Postgres URL (SCRAM; not published to the host). */
-export function composeDbUrl(): string {
-  return "postgresql://supatype_admin:postgres@db:5432/supatype?sslmode=disable"
+export function composeDbUrl(cwd: string): string {
+  const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+  const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
+  return `postgresql://${user}:${devPostgresPassword(cwd)}@db:5432/${db}?sslmode=disable`
 }
 
 /**
@@ -84,10 +96,23 @@ async function resolveDevDbPort(cwd: string): Promise<number> {
   return ensureDevDbPort(cwd)
 }
 
+/**
+ * The database URL to hand a tool, from wherever it happens to run.
+ *
+ * The compose helpers below describe the `db` *container* — on the host at
+ * `SUPATYPE_DEV_DB_PORT`, or in-network at `db:5432`. Neither exists for a project pointed at an
+ * external database, and passing one produced "pool timed out while waiting for an open connection"
+ * — a message with nothing in it about the URL being wrong.
+ */
+function projectDatabaseUrl(cwd: string, config: SupatypeProjectConfig, inNetwork = false): string {
+  if (usesExternalDatabase(config)) return connectionString(config)
+  return inNetwork ? composeDbUrl(cwd) : hostComposeDbUrl(cwd)
+}
+
 function hostComposeDbUrl(cwd: string): string {
   const port = readEnvValue(cwd, "SUPATYPE_DEV_DB_PORT", String(COMPOSE_DEV_DB_PORT))
   const user = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
-  const pass = readEnvValue(cwd, "POSTGRES_PASSWORD", "postgres")
+  const pass = devPostgresPassword(cwd)
   const db = readEnvValue(cwd, "POSTGRES_DB", "supatype")
   return `postgresql://${user}:${pass}@127.0.0.1:${port}/${db}?sslmode=disable`
 }
@@ -117,19 +142,12 @@ export async function ensureDockerDbPublishedForHostEngine(
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    ...(brand !== undefined && { brand }),
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", brand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  await startComposeDatabase(config, paths, cwd, project, brand)
 }
 
 /**
@@ -142,6 +160,9 @@ export function usesLocalDockerEngineDb(
 ): boolean {
   if (explicitConnection?.trim()) return false
   if (config.connection?.trim()) return false
+  // An external database is already reachable and is not ours to publish. Without this the engine
+  // path tried `compose up -d db` against a compose file that deliberately has no `db` service.
+  if (usesExternalDatabase(config)) return false
   return resolveRuntimeProvider(config) === "docker" && hasEngineOverride(config)
 }
 
@@ -168,6 +189,36 @@ async function resolveKongPort(cwd: string): Promise<number> {
   return ensureKongPort(cwd, { context: "dev" })
 }
 
+/**
+ * Bring up the compose `db` service and wait for it to answer.
+ *
+ * A no-op when the project uses an external database: there is no such service, the database is
+ * already running, and its readiness is the operator's — `supatype db check` is what reports on it.
+ * Four call sites did this inline, so an external project hit `compose up -d db` against a compose
+ * file that deliberately has no `db`.
+ */
+async function startComposeDatabase(
+  config: SupatypeProjectConfig,
+  paths: SelfHostComposePaths,
+  cwd: string,
+  project: string,
+  brand: DockerBrandOptions | undefined,
+  timeoutMs = 120_000,
+  onFailure?: () => void,
+): Promise<void> {
+  if (usesExternalDatabase(config)) return
+
+  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
+    quiet: true,
+    ...(brand !== undefined && { brand }),
+  })
+  if (up !== 0) {
+    onFailure?.()
+    exitComposeFailed(up, "Could not start Postgres (compose db service).", brand)
+  }
+  await waitComposeHealthy(paths, cwd, timeoutMs, project)
+}
+
 function upsertDevComposeEnv(
   cwd: string,
   config: SupatypeProjectConfig,
@@ -179,11 +230,25 @@ function upsertDevComposeEnv(
 ): void {
   const apiUrl = `http://localhost:${kongPort}`
   const imagePins = composeDockerImageEnv(config)
+  // `POSTGRES_PASSWORD` and `JWT_SECRET` are deliberately absent.
+  //
+  // They used to be pinned here to published constants on every `dev` run, against the same
+  // `.env` a self-host deployment reads — so a project could not hold its own secrets, and one
+  // `dev` after generating them put the published values back with nothing to show it. They are
+  // now resolved from `.env` (see `local-secrets.ts`) and written by `init` alone.
+  //
+  // The keys below still have to be written, because they are *derived*: the anon and
+  // service-role tokens are signed with the effective secret, so leaving a stale pair in place
+  // would desync them from the secret that validates them.
   const updates: Record<string, string> = {
-    POSTGRES_USER: "supatype_admin",
-    POSTGRES_PASSWORD: "postgres",
-    POSTGRES_DB: "supatype",
-    JWT_SECRET: LOCAL_JWT_SECRET,
+    // The docker dev path renders the *self-host* compose file, where the secrets have no
+    // defaults — an unset value is a hard compose error rather than a service quietly starting
+    // with a published constant. This guarantees presence without overwriting: only keys
+    // genuinely absent from `.env` are filled, and with the value the project has been running
+    // with rather than a fresh one.
+    ...seedMissingLocalSecrets(cwd),
+    // Project configuration, seeded not overwritten — see seedMissingDatabaseIdentity.
+    ...seedMissingDatabaseIdentity(cwd),
     ANON_KEY: anonKey,
     SERVICE_ROLE_KEY: serviceRoleKey,
     PUBLIC_SUPATYPE_ANON_KEY: anonKey,
@@ -198,13 +263,26 @@ function upsertDevComposeEnv(
     ...imagePins,
     ...(localServerImage !== undefined && { SUPATYPE_SERVER_IMAGE: localServerImage }),
   }
-  if (devDbPort !== undefined) {
+  // Never for an external database: this URL describes the `db` container, which that project does
+  // not have. Writing it overwrote the operator's own DATABASE_URL — the value the whole stack and
+  // every CLI command reads — with a DSN pointing at a database that does not exist. Found by
+  // rehearsing a push against a real external Postgres, where the compose guard then refused to
+  // proceed because .env and the config disagreed. They disagreed because of this line.
+  if (devDbPort !== undefined && !usesExternalDatabase(config)) {
     updates.SUPATYPE_DEV_DB_PORT = String(devDbPort)
+    // User and database from the project, not hardcoded — same reason as
+    // `seedMissingDatabaseIdentity`: a project not named "supatype" had this URL pointing at a
+    // database that does not exist.
+    const dbUser = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
+    const dbName = readEnvValue(cwd, "POSTGRES_DB", "supatype")
     updates.DATABASE_URL =
-      `postgresql://supatype_admin:postgres@localhost:${devDbPort}/supatype?sslmode=disable`
+      `postgresql://${dbUser}:${devPostgresPassword(cwd)}@localhost:${devDbPort}/${dbName}?sslmode=disable`
   }
   const removeImageKeys = COMPOSE_PINNED_IMAGE_ENV_KEYS.filter((key) => !(key in imagePins))
-  upsertEnvFile(cwd, updates, removeImageKeys)
+  upsertEnvFile(cwd, updates, {
+    removeManaged: removeImageKeys,
+    managed: COMPOSE_PINNED_IMAGE_ENV_KEYS,
+  })
 }
 
 /** Keep compose + Studio on the same freshly signed dev JWTs; sync optional image pins from config. */
@@ -440,7 +518,7 @@ async function runComposeSchemaPush(
     try {
       await engineRequest("/push", {
         ast,
-        database_url: hostComposeDbUrl(cwd),
+        database_url: projectDatabaseUrl(cwd, config),
         schema: pgSchema,
         force: true,
         ...(sources
@@ -540,7 +618,7 @@ async function runComposeEnginePush(
     "-i",
     "/project/.supatype/schema.ast.json",
     "--database-url",
-    composeDbUrl(),
+    projectDatabaseUrl(cwd, config, true),
     "--force",
     "--non-interactive",
   )
@@ -606,7 +684,7 @@ async function runComposeEngineDiff(
     "-i",
     "/project/.supatype/schema.ast.json",
     "--database-url",
-    composeDbUrl(),
+    projectDatabaseUrl(cwd, config, true),
     "--schema",
     pgSchema,
   )
@@ -651,7 +729,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     await ensureEngine()
     return engineRequest<DiffResult>("/diff", {
       ast,
-      database_url: hostComposeDbUrl(cwd),
+      database_url: projectDatabaseUrl(cwd, config),
       schema: pgSchema,
     })
   }
@@ -659,21 +737,14 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
   const kongPort = await resolveKongPort(cwd)
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, undefined)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   const diffBrand = { intro: "Schema diff" }
 
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: diffBrand,
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", diffBrand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  await startComposeDatabase(config, paths, cwd, project, diffBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
   const ast = loadSchemaAst(schemaPath, cwd)
@@ -710,26 +781,25 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   }
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
-  const devDbPort = hasEngineOverride(config) ? await resolveDevDbPort(cwd) : undefined
+  // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
+  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL — the
+  // one the whole stack and every CLI command reads.
+  const devDbPort =
+    hasEngineOverride(config) && !usesExternalDatabase(config)
+      ? await resolveDevDbPort(cwd)
+      : undefined
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort)
 
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   const pushBrand = { intro: "Push schema" }
 
   console.log(`[supatype] provider: docker — applying schema via compose (project ${project})...`)
-  const up = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: pushBrand,
-  })
-  if (up !== 0) {
-    exitComposeFailed(up, "Could not start Postgres (compose db service).", pushBrand)
-  }
-  await waitComposeHealthy(paths, cwd, 120_000, project)
+  await startComposeDatabase(config, paths, cwd, project, pushBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
   const ast = loadSchemaAst(schemaPath, cwd)
@@ -762,12 +832,18 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   // stack on the machine (own containers, volumes, network, and gateway port).
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
-  const devDbPort = hasEngineOverride(config) ? await resolveDevDbPort(cwd) : undefined
+  // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
+  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL — the
+  // one the whole stack and every CLI command reads.
+  const devDbPort =
+    hasEngineOverride(config) && !usesExternalDatabase(config)
+      ? await resolveDevDbPort(cwd)
+      : undefined
 
   const now = Math.floor(Date.now() / 1000)
   const jwtBase = { iss: "supatype", iat: now, exp: now + 315_360_000 }
-  const anonKey = signJwt({ ...jwtBase, role: "anon" }, LOCAL_JWT_SECRET)
-  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, LOCAL_JWT_SECRET)
+  const anonKey = signJwt({ ...jwtBase, role: "anon" }, devJwtSecret(cwd))
+  const serviceRoleKey = signJwt({ ...jwtBase, role: "service_role" }, devJwtSecret(cwd))
 
   const devBrand = { intro: "Local development" }
   const localServerImage = await ensureLocalServerDockerImage(cwd, config, devBrand)
@@ -818,18 +894,10 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   await recoverStaleDevSession(cwd)
   await handleComposeProjectRename(cwd, config.project.name, paths)
 
-  console.log("[supatype] Bringing up Postgres (compose db)...")
-  const upDbStatus = runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-    quiet: true,
-    brand: devBrand,
-  })
-  if (upDbStatus !== 0) {
-    endDevSession()
-    exitComposeFailed(upDbStatus, "Could not start Postgres (compose db service).", devBrand)
+  if (!usesExternalDatabase(config)) {
+    console.log("[supatype] Bringing up Postgres (compose db)...")
   }
-
-  console.log("[supatype] Waiting for Postgres (compose)...")
-  await waitComposeHealthy(paths, cwd, 180_000, project)
+  await startComposeDatabase(config, paths, cwd, project, devBrand, 180_000, endDevSession)
   // Settle before DDL — pg_isready can pass slightly before the instance is stable.
   await new Promise((r) => setTimeout(r, 3000))
 
@@ -851,16 +919,17 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
         )
         dumpComposeDbLogs(paths, cwd, project, `schema push attempt ${attempt}/${maxAttempts}`)
         if (attempt < maxAttempts) {
-          console.log("[supatype] Resetting Postgres after failed schema push...")
-          runDockerCompose(paths.composePath, ["down", "-v"], cwd, project, {
-            quiet: true,
-            brand: devBrand,
-          })
-          runDockerCompose(paths.composePath, ["up", "-d", "db"], cwd, project, {
-            quiet: true,
-            brand: devBrand,
-          })
-          await waitComposeHealthy(paths, cwd, 120_000, project)
+          // Only for a database Supatype created. Tearing down an external one is not ours to do,
+          // and `down -v` would destroy the stack's other volumes for a failure that was never
+          // about Postgres.
+          if (!usesExternalDatabase(config)) {
+            console.log("[supatype] Resetting Postgres after failed schema push...")
+            runDockerCompose(paths.composePath, ["down", "-v"], cwd, project, {
+              quiet: true,
+              brand: devBrand,
+            })
+            await startComposeDatabase(config, paths, cwd, project, devBrand)
+          }
           await new Promise((r) => setTimeout(r, 3000 * attempt))
         }
       }
@@ -927,7 +996,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   writeLocalEnvironment(cwd, {
     target: "local",
     apiUrl: `http://localhost:${kongPort}`,
-    databaseUrl: hasEngineOverride(config) ? hostComposeDbUrl(cwd) : composeDbUrl(),
+    databaseUrl: projectDatabaseUrl(cwd, config, !hasEngineOverride(config)),
     projectRef: config.project.name,
     kongPort,
     provider: "docker",

package/src/env-file.ts

@@ -1,23 +1,162 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
-/** Merge key/value updates into a project `.env` without dropping unrelated lines. */
+/**
+ * Marks a value the CLI wrote from `versions` in `supatype.config.ts`.
+ *
+ * Provenance, so that removing a pin from config can clean up the stale image reference it left
+ * behind *without* deleting a value the operator wrote by hand. Before this, the image keys derived
+ * from config were removed unconditionally on every compose run: an operator could override
+ * `SUPATYPE_REALTIME_IMAGE` from `.env` and could not override `SUPATYPE_SERVER_IMAGE`, because the
+ * latter is derivable from a pin and the former is not. Same file, same shape, different rules.
+ */
+export const MANAGED_MARKER = "# supatype:managed — value from versions in supatype.config.ts"
+
+interface EnvLine {
+  /** `KEY` for an assignment, undefined for comments and blanks. */
+  key?: string
+  text: string
+  /** True when the preceding line is the managed marker. */
+  managed: boolean
+}
+
+function parseLines(text: string): EnvLine[] {
+  const out: EnvLine[] = []
+  if (text === "") return out
+  let markerPending = false
+  // A file ending in a newline yields a final empty element; keeping it would put a blank line
+  // between the existing content and anything appended.
+  const raws = text.split(/\r?\n/)
+  while (raws.length > 0 && raws[raws.length - 1] === "") raws.pop()
+  for (const raw of raws) {
+    const trimmed = raw.trim()
+    if (trimmed === MANAGED_MARKER) {
+      markerPending = true
+      out.push({ text: raw, managed: false })
+      continue
+    }
+    const eq = raw.indexOf("=")
+    const key = eq > 0 ? raw.slice(0, eq).trim() : undefined
+    const isAssignment = key !== undefined && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
+    out.push({ ...(isAssignment && { key }), text: raw, managed: isAssignment && markerPending })
+    if (!isAssignment && trimmed !== "") markerPending = false
+    else if (isAssignment) markerPending = false
+  }
+  return out
+}
+
+export interface UpsertOptions {
+  /**
+   * Keys to delete — but only where the CLI wrote them (see [`MANAGED_MARKER`]). A hand-written value
+   * is left alone, because the operator putting an image tag in `.env` is the documented way to run a
+   * local build and deleting it silently sent them back to `:latest`.
+   */
+  removeManaged?: readonly string[]
+  /** Keys in `updates` that come from config and may later be cleaned up. Written with the marker. */
+  managed?: readonly string[]
+  /** Keys to delete outright, whoever wrote them. For secrets being rotated out. */
+  remove?: readonly string[]
+}
+
+/**
+ * Merge key/value updates into a project `.env`.
+ *
+ * Comments, blank lines and ordering are preserved: this file is edited by hand, and the previous
+ * implementation rebuilt it from the assignments alone, so every comment an operator had written
+ * disappeared the first time they ran anything that touched `.env`.
+ */
 export function upsertEnvFile(
   cwd: string,
   updates: Record<string, string>,
-  removeKeys: readonly string[] = [],
+  options: UpsertOptions | readonly string[] = {},
 ): void {
+  // Historically the third argument was a plain list of keys to remove unconditionally.
+  const opts: UpsertOptions = Array.isArray(options)
+    ? { remove: options as readonly string[] }
+    : (options as UpsertOptions)
+  const removeManaged = new Set(opts.removeManaged ?? [])
+  const removeAlways = new Set(opts.remove ?? [])
+  const managed = new Set(opts.managed ?? [])
+
   const envPath = join(cwd, ".env")
   const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
-  const keys = new Set([...Object.keys(updates), ...removeKeys])
-  const kept = existing
-    .split("\n")
-    .filter((line) => {
-      const key = line.split("=")[0]?.trim()
-      return key && line.includes("=") && !keys.has(key)
-    })
-  const merged = [...kept, ...Object.entries(updates).map(([key, value]) => `${key}=${value}`)]
-  writeFileSync(envPath, `${merged.join("\n").trimEnd()}\n`, "utf8")
+  const lines = parseLines(existing)
+
+  const written = new Set<string>()
+  const kept: EnvLine[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const key = line.key
+
+    if (key === undefined) {
+      kept.push(line)
+      continue
+    }
+
+    if (removeAlways.has(key) || (removeManaged.has(key) && line.managed)) {
+      // Drop the marker that introduced it, so no orphan comment is left behind.
+      if (line.managed && kept[kept.length - 1]?.text.trim() === MANAGED_MARKER) kept.pop()
+      continue
+    }
+
+    if (key in updates) {
+      const wantsMarker = managed.has(key)
+      if (wantsMarker && kept[kept.length - 1]?.text.trim() !== MANAGED_MARKER) {
+        kept.push({ text: MANAGED_MARKER, managed: false })
+      }
+      if (!wantsMarker && line.managed && kept[kept.length - 1]?.text.trim() === MANAGED_MARKER) {
+        kept.pop()
+      }
+      kept.push({ key, text: `${key}=${updates[key]}`, managed: wantsMarker })
+      written.add(key)
+      continue
+    }
+
+    kept.push(line)
+  }
+
+  const appended: string[] = []
+  for (const [key, value] of Object.entries(updates)) {
+    if (written.has(key)) continue
+    if (managed.has(key)) appended.push(MANAGED_MARKER)
+    appended.push(`${key}=${value}`)
+  }
+
+  const body = [...kept.map((l) => l.text), ...appended].join("\n")
+  writeFileSync(envPath, `${body.replace(/\n+$/, "")}\n`, "utf8")
+}
+
+/**
+ * Parse a project `.env` into key/value pairs.
+ *
+ * Deliberately small: `KEY=value`, `#` comments, one optional layer of surrounding quotes. No
+ * interpolation and no `export` handling, because Compose's own parser does not do those either and
+ * a `.env` that means two different things depending on who reads it is worse than a limited one.
+ */
+export function readEnvFile(cwd: string): Record<string, string> {
+  const envPath = join(cwd, ".env")
+  if (!existsSync(envPath)) return {}
+
+  const out: Record<string, string> = {}
+  for (const line of readFileSync(envPath, "utf8").split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue
+    const eq = trimmed.indexOf("=")
+    if (eq <= 0) continue
+    const key = trimmed.slice(0, eq).trim()
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
+    let value = trimmed.slice(eq + 1).trim()
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1)
+    }
+    out[key] = value
+  }
+  return out
 }
 
 export function readEnvValue(cwd: string, key: string, fallback: string): string {
@@ -29,6 +168,13 @@ export function readEnvValue(cwd: string, key: string, fallback: string): string
   return fallback
 }
 
+/** Whether `.env` carries a non-empty value for `key`. Distinguishes absent from defaulted. */
+export function hasEnvValue(cwd: string, key: string): boolean {
+  const envPath = join(cwd, ".env")
+  if (!existsSync(envPath)) return false
+  return new RegExp(`^${key}=(.+)$`, "m").test(readFileSync(envPath, "utf8"))
+}
+
 export function readEnvInt(cwd: string, key: string): number | null {
   const raw = readEnvValue(cwd, key, "")
   if (!raw) return null