@supatype/cli 0.2.1 → 0.3.1

package/tests/cache-provider-config.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest"
+import { validateProjectConfig } from "../src/project-config.js"
+import { cacheProvider } from "../src/cache-provider.js"
+
+/**
+ * `cache.provider` picks the RESP server the response cache and Kong's ACME
+ * certificates share. Every rejection here is a case where accepting the
+ * config would produce a stack that runs, and runs something other than what
+ * was asked for.
+ */
+const validate = (cache: unknown, database: unknown = { provider: "docker" }) =>
+  validateProjectConfig(
+    {
+      project: { name: "acme" },
+      database,
+      server: { mode: "dev" },
+      app: { mode: "none" },
+      ...(cache === undefined ? {} : { cache }),
+    },
+    "supatype.config.ts",
+  )
+
+describe("cache.provider", () => {
+  it("accepts both providers, and no cache section at all", () => {
+    expect(() => validate(undefined)).not.toThrow()
+    expect(() => validate({})).not.toThrow()
+    expect(() => validate({ provider: "valkey" })).not.toThrow()
+    expect(() => validate({ provider: "pg_keyspace" })).not.toThrow()
+  })
+
+  it("refuses a provider it does not have", () => {
+    expect(() => validate({ provider: "redis" })).toThrow(/cache\.provider must be/)
+  })
+
+  // Rejected rather than silently downgraded to Valkey: a stack that quietly
+  // runs the thing you switched away from is worse than one that will not start.
+  it("refuses pg_keyspace against a database this stack does not start", () => {
+    expect(() =>
+      validate({ provider: "pg_keyspace" }, { external: { url: "postgres://u:p@h:5432/d" } }),
+    ).toThrow(/needs the Postgres this stack starts/)
+  })
+
+  it("leaves valkey alone with an external database", () => {
+    expect(() =>
+      validate({ provider: "valkey" }, { external: { url: "postgres://u:p@h:5432/d" } }),
+    ).not.toThrow()
+  })
+})
+
+describe("cache.durablePrefixes", () => {
+  it("accepts a list of prefixes", () => {
+    expect(() => validate({ provider: "pg_keyspace", durablePrefixes: ["session:"] })).not.toThrow()
+  })
+
+  it("refuses anything that is not a list of non-empty strings", () => {
+    for (const bad of ["session:", [""], [3], [null]]) {
+      expect(() => validate({ provider: "pg_keyspace", durablePrefixes: bad })).toThrow(
+        /must be an array of non-empty strings/,
+      )
+    }
+  })
+
+  // `,` separates entries and `=` separates a prefix from its tier in
+  // pg_keyspace.durability_overrides. A prefix containing either would be read
+  // as two settings, and the first sign of it would be a database that will
+  // not start — long after the config was written.
+  it("refuses a prefix carrying one of the separators", () => {
+    for (const bad of ["a,b", "a=b"]) {
+      expect(() => validate({ provider: "pg_keyspace", durablePrefixes: [bad] })).toThrow(
+        /cannot contain "," or "="/,
+      )
+    }
+  })
+})
+
+describe("which provider a project actually runs", () => {
+  /*
+   * P9 flipped the default. The resolver is one function because the answer depends on two fields:
+   * an absent `cache.provider` means pg_keyspace beside a database this stack starts and Valkey
+   * beside an external one. A default written into the parser would have to be wrong for one of
+   * them, or applied twice — and applied twice is how the compose file and the native path end up
+   * disagreeing about which server is running, which is a cache that silently never hits and, with
+   * TLS on, a Kong that cannot store its certificate.
+   */
+  const project = (over: Record<string, unknown>) =>
+    ({
+      project: { name: "acme" },
+      database: { provider: "docker" },
+      server: { mode: "dev" },
+      app: { mode: "none" },
+      ...over,
+    }) as unknown as Parameters<typeof cacheProvider>[0]
+
+  it("runs the keyspace in Postgres when nothing says otherwise", () => {
+    expect(cacheProvider(project({}))).toBe("pg_keyspace")
+    expect(cacheProvider(project({ cache: {} }))).toBe("pg_keyspace")
+    expect(cacheProvider(project({ cache: { durablePrefixes: ["session:"] } }))).toBe("pg_keyspace")
+  })
+
+  it("keeps Valkey for a project that pins its Postgres image", () => {
+    // The image honours SUPATYPE_KEYSPACE_ENABLED from the release that introduced it, and an
+    // older one ignores it and starts with no RESP listener — no error anywhere, just a cache that
+    // never hits. A pin says this project's image is fixed; a default cannot assume something
+    // about a fixed image it has no way to check. Saying `pg_keyspace` explicitly still works, and
+    // is the whole instruction for a project whose pin does carry the toggle.
+    expect(cacheProvider(project({ versions: { postgres: "17.2" } }))).toBe("valkey")
+    expect(
+      cacheProvider(project({ versions: { postgres: "17.2" }, cache: { provider: "pg_keyspace" } })),
+    ).toBe("pg_keyspace")
+  })
+
+  it("is unaffected by a pin on anything else", () => {
+    // Only the Postgres image decides whether a keyspace can be served.
+    expect(cacheProvider(project({ versions: { engine: "0.4.2", server: "0.1.0" } }))).toBe("pg_keyspace")
+  })
+
+  it("honours an explicit choice, including the one that is no longer the default", () => {
+    // Selectable, not deprecated. A project that wrote `valkey` down keeps the sidecar.
+    expect(cacheProvider(project({ cache: { provider: "valkey" } }))).toBe("valkey")
+    expect(cacheProvider(project({ cache: { provider: "pg_keyspace" } }))).toBe("pg_keyspace")
+  })
+
+  it("resolves to Valkey for a database this stack does not start", () => {
+    // Not a preference: pg_keyspace is loaded through shared_preload_libraries, so against an
+    // unmanaged Postgres there is nothing to configure and Valkey is the only thing that can run.
+    // Asking for pg_keyspace explicitly there is refused by validation rather than resolved here.
+    expect(cacheProvider(project({ database: { external: { url: "postgres://u:p@h:5432/d" } } }))).toBe("valkey")
+    expect(
+      cacheProvider(project({ database: { external: { url: "postgres://u:p@h:5432/d" } }, cache: {} })),
+    ).toBe("valkey")
+  })
+})

package/tests/engine-floor.test.ts

@@ -4,6 +4,8 @@ import {
   boundsRequiringHelpers,
   compareVersions,
   ENGINE_MIN_FOR_BOUNDS,
+  ENGINE_MIN_FOR_VERSIONS,
+  modelsRequiringVersions,
 } from "../src/engine-floor.js"
 import type { ExtractedSchemaAstV2, FieldAstV2, ModelAstV2 } from "../src/schema-ast-v2.js"
 
@@ -100,3 +102,44 @@ describe("assertEngineSupportsSchema", () => {
     expect(() => assertEngineSupportsSchema(WITH_BOUND, "1.0.0")).not.toThrow()
   })
 })
+
+describe("the versions floor", () => {
+  const versionedModel = (): ModelAstV2 => ({
+    ...model("Post", { title: field() }),
+    options: { versions: { drafts: true, keep: 20 } },
+  })
+  const VERSIONED = schema([versionedModel()])
+  const PLAIN = schema([model("Post", { title: field() })])
+
+  it("names the models that declare it", () => {
+    expect(modelsRequiringVersions(VERSIONED)).toEqual(["Post"])
+    expect(modelsRequiringVersions(PLAIN)).toEqual([])
+  })
+
+  it("refuses a pin older than the release that emits the layer", () => {
+    // The failure this guards is *silent*: an older engine does not reject `versions`, it ignores
+    // the key, so the push reports success and the model has no snapshot table and no drafts.
+    expect(() => { assertEngineSupportsSchema(VERSIONED, "0.2.0") }).toThrow(
+      /`versions`[\s\S]*0\.3\.0[\s\S]*saves into nothing/,
+    )
+  })
+
+  it("allows the release itself and anything newer", () => {
+    expect(() => { assertEngineSupportsSchema(VERSIONED, ENGINE_MIN_FOR_VERSIONS) }).not.toThrow()
+    expect(() => { assertEngineSupportsSchema(VERSIONED, "1.0.0") }).not.toThrow()
+  })
+
+  it("says nothing about a schema that declares no versions", () => {
+    // The floor must not spread to projects that never asked for the feature.
+    expect(() => { assertEngineSupportsSchema(PLAIN, "0.1.0") }).not.toThrow()
+  })
+
+  it("leaves an unpinned or local project alone", () => {
+    expect(() => { assertEngineSupportsSchema(VERSIONED, undefined) }).not.toThrow()
+    expect(() => { assertEngineSupportsSchema(VERSIONED, "local") }).not.toThrow()
+  })
+
+  it("still refuses bounds on an older pin, so the second rule did not shadow the first", () => {
+    expect(() => { assertEngineSupportsSchema(WITH_BOUND, "0.1.9") }).toThrow(/bounds/)
+  })
+})

package/tests/external-database-compose.test.ts

@@ -61,7 +61,7 @@ describe("external database: compose", () => {
   it("interpolates the URL rather than baking the password into the file", () => {
     // The compose file is generated into .supatype/, which operators do commit.
     const compose = renderSelfHostCompose(external())
-    // "secret" alone would match minio's own S3 credentials, so match the userinfo form.
+    // "secret" alone would match the object store's own S3 credentials, so match the userinfo form.
     expect(compose).not.toContain("owner:secret@")
     expect(compose).not.toContain("://owner")
     expect(compose).toContain("${DATABASE_URL:?DATABASE_URL is missing from .env")
@@ -122,7 +122,7 @@ describe("external database: compose", () => {
 
   it("still declares the volumes it does own", () => {
     const compose = renderSelfHostCompose(external())
-    expect(compose).toContain("  minio-data:")
+    expect(compose).toContain("  storage-data:")
     expect(compose).toContain("  valkey-data:")
   })
 
@@ -137,7 +137,7 @@ describe("external database: compose", () => {
       "realtime:",
       "control-plane:",
       "server:",
-      "minio:",
+      "seaweedfs:",
       "schema-engine:",
       "studio:",
       "valkey:",
@@ -182,3 +182,74 @@ describe("a loopback external URL", () => {
     expect(loopbackExternalHost(managed())).toBeUndefined()
   })
 })
+
+describe("the draft schema in generated compose", () => {
+  it("reaches PGRST_DB_SCHEMA when a model is versioned", () => {
+    // The wiring, not the list: a correct `apiSchemaList` behind a placeholder that never gets the
+    // flag is exactly the failure shape this project has hit before, and it reads as "there is no
+    // draft" rather than as an error.
+    const compose = renderSelfHostCompose(managed(), process.cwd(), { drafts: true })
+    expect(compose).toMatch(/PGRST_DB_SCHEMA: "public, draft, /)
+  })
+
+  it("leaves it off when nothing is versioned", () => {
+    const compose = renderSelfHostCompose(managed(), process.cwd(), { drafts: false })
+    expect(compose).toContain('PGRST_DB_SCHEMA: "public, supatype, graphql_public, auth"')
+    expect(compose).not.toContain("draft")
+  })
+})
+
+describe("the server's own configuration keys", () => {
+  // `renderSelfHostCompose` is pure over its config, so one render serves every
+  // assertion here and the fixture lives in one place.
+  const compose = renderSelfHostCompose(managed())
+
+  it("uses the SUPATYPE_ prefix the server actually reads", () => {
+    // The server's config prefix is "supatype", so a GOTRUE_ key is read by nothing. It does not
+    // warn about the ones it ignores: it dies on the first *required* key it cannot find, so
+    // self-host failed to start with a message naming a variable that was present in .env under
+    // another spelling, and no test noticed because none asserted these.
+    for (const key of [
+      "SUPATYPE_API_EXTERNAL_URL",
+      "SUPATYPE_API_HOST",
+      "SUPATYPE_API_PORT",
+      "SUPATYPE_DB_DRIVER",
+      "SUPATYPE_DB_DATABASE_URL",
+      "SUPATYPE_SITE_URL",
+      "SUPATYPE_JWT_SECRET",
+      "SUPATYPE_DISABLE_SIGNUP",
+      "SUPATYPE_MAILER_AUTOCONFIRM",
+    ]) {
+      expect(compose).toContain(`${key}:`)
+    }
+  })
+
+  it("sets no GOTRUE_ key on the server, since none of them are read", () => {
+    const serverBlock = compose.split("\n  server:")[1]?.split("\n  kong:")[0] ?? ""
+    const stale = serverBlock
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => /^GOTRUE_[A-Z_]+:/.test(line))
+    expect(stale).toEqual([])
+  })
+
+  it("reads its override from the current name too, not the retired one", () => {
+    // Interpolating from GOTRUE_MAILER_AUTOCONFIRM would require the operator to keep that key in
+    // `.env` — and the server reads config files into its environment before checking for retired
+    // names, so its presence there is fatal. The old spelling cannot be the escape hatch when
+    // having it set at all is the failure.
+    expect(compose).toContain("SUPATYPE_MAILER_AUTOCONFIRM: ${SUPATYPE_MAILER_AUTOCONFIRM:-true}")
+    expect(compose).not.toContain("${GOTRUE_MAILER_AUTOCONFIRM")
+  })
+
+  it("raises the header buffer, because localhost cookies are not port-scoped", () => {
+    // Every project a developer runs on localhost shares one cookie jar, so this gateway is sent
+    // cookies belonging to entirely unrelated stacks, and nginx's default buffers are not sized for
+    // that. The answer is "Request header or cookie too large" from a component nobody configured.
+    //
+    // The value is pinned rather than merely present, because Studio's own nginx must carry the
+    // same one: a request that clears the gateway and fails at the page is worse to diagnose than
+    // one that fails outright. packages/studio/nginx.conf holds the reasoning and its own test.
+    expect(compose).toContain('KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS: "4 32k"')
+  })
+})

package/tests/field-masking-tier.test.ts

@@ -118,7 +118,7 @@ describe("the exposed schema list", () => {
   it("serves from api under tier 2, and drops the managed schema", () => {
     // Both halves matter. A client picks its schema per request with `Accept-Profile`, so leaving the
     // managed schema exposed would let any caller read the unmasked table.
-    const list = apiSchemaList(project({ provider: "native" }), "views")
+    const list = apiSchemaList(project({ provider: "native" }), { tier: "views" })
     expect(list).toBe("api, supatype, graphql_public, auth")
     // Entries, not substrings: `graphql_public` legitimately contains "public".
     expect(list.split(", ")).not.toContain("public")
@@ -126,7 +126,7 @@ describe("the exposed schema list", () => {
 
   it("is unchanged for tier 1 and for a schema with no field rules", () => {
     for (const tier of ["extension", "none", undefined] as const) {
-      expect(apiSchemaList(project({ provider: "docker" }), tier)).toBe(
+      expect(apiSchemaList(project({ provider: "docker" }), { tier })).toBe(
         "public, supatype, graphql_public, auth",
       )
     }
@@ -138,7 +138,7 @@ describe("the exposed schema list", () => {
     const cfg = project({ external: { url: "postgres://u@h:5432/d" } }, {
       schema: { api_schemas: ["public", "supatype"] },
     })
-    expect(apiSchemaList(cfg, "views")).toBe("public, supatype")
+    expect(apiSchemaList(cfg, { tier: "views" })).toBe("public, supatype")
   })
 })
 

package/tests/fixtures/identity-scope-corpus.json

@@ -0,0 +1,42 @@
+{
+  "_comment": "Shared corpus for the identity-dependence rule, which exists twice: here, for supatype push (packages/cli/src/cache-identity-scope.ts), and in supatype-server (internal/studiobootstrap.IsIdentityDependent) for the runtime cache-scope decision. Two implementations of one rule drift silently — a push that says 'shareable' against a runtime that says 'not', or the reverse, which is a data leak. Both sides run these cases. Add a case here when you change either.",
+  "cases": [
+    { "name": "no rule at all",              "rule": null,                                                         "identityDependent": false },
+    { "name": "Public",                      "rule": { "type": "public" },                                          "identityDependent": false },
+    { "name": "Private",                     "rule": { "type": "private" },                                         "identityDependent": false },
+
+    { "name": "LoggedIn",                    "rule": { "type": "authenticated" },                                   "identityDependent": true },
+    { "name": "Role<admin>",                 "rule": { "type": "role" },                                            "identityDependent": true },
+    { "name": "Owner<user_id>",              "rule": { "type": "owner", "field": "user_id" },                       "identityDependent": true },
+    { "name": "In<...>",                     "rule": { "type": "in" },                                              "identityDependent": true },
+    { "name": "Exists<...>",                 "rule": { "type": "exists" },                                          "identityDependent": true },
+
+    { "name": "Eq<user_id, CurrentUser>",    "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "authUid" } },   "identityDependent": true },
+    { "name": "CurrentUser on the left",     "rule": { "type": "compare", "left": { "kind": "authUid" }, "right": { "kind": "column" } },   "identityDependent": true },
+    { "name": "compare against a claim",     "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "claim" } },     "identityDependent": true },
+    { "name": "compare against authRole",    "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "authRole" } },  "identityDependent": true },
+
+    { "name": "Lte<published_at, Now> — row-dependent but shareable", "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "now" } }, "identityDependent": false },
+    { "name": "column vs literal",           "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "literal" } },   "identityDependent": false },
+    { "name": "column vs column",            "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "column" } },    "identityDependent": false },
+
+    { "name": "IsNull on a column",          "rule": { "type": "nullCheck", "operand": { "kind": "column" } },       "identityDependent": false },
+    { "name": "IsNull on a claim",           "rule": { "type": "nullCheck", "operand": { "kind": "claim" } },        "identityDependent": true },
+
+    { "name": "Any of two shareable",        "rule": { "type": "any", "rules": [ { "type": "public" }, { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "now" } } ] }, "identityDependent": false },
+    { "name": "Any with one caller-varying", "rule": { "type": "any", "rules": [ { "type": "public" }, { "type": "owner" } ] },             "identityDependent": true },
+    { "name": "All of two shareable",        "rule": { "type": "all", "rules": [ { "type": "public" }, { "type": "private" } ] },           "identityDependent": false },
+    { "name": "All with one caller-varying", "rule": { "type": "all", "rules": [ { "type": "public" }, { "type": "authenticated" } ] },     "identityDependent": true },
+    { "name": "Any with no rules",           "rule": { "type": "any", "rules": [] },                                 "identityDependent": false },
+
+    { "name": "Not over shareable",          "rule": { "type": "not", "rule": { "type": "public" } },                "identityDependent": false },
+    { "name": "Not over caller-varying",     "rule": { "type": "not", "rule": { "type": "owner" } },                 "identityDependent": true },
+    { "name": "Not over nothing",            "rule": { "type": "not" },                                              "identityDependent": false },
+
+    { "name": "nested any/all/not, shareable throughout", "rule": { "type": "all", "rules": [ { "type": "any", "rules": [ { "type": "public" } ] }, { "type": "not", "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "now" } } } ] }, "identityDependent": false },
+    { "name": "caller-varying buried three deep",         "rule": { "type": "all", "rules": [ { "type": "any", "rules": [ { "type": "not", "rule": { "type": "compare", "left": { "kind": "column" }, "right": { "kind": "authUid" } } } ] } ] }, "identityDependent": true },
+
+    { "name": "unrecognised rule type",      "rule": { "type": "somethingNew" },                                     "identityDependent": true },
+    { "name": "rule with no type",           "rule": {},                                                             "identityDependent": true }
+  ]
+}

package/tests/functions-concurrency.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest"
+import { generateFunctionsRouterSource } from "../src/functions-router-gen.js"
+
+// The router the CLI generates for `supatype dev` used to serialise every invocation.
+//
+// Per-invocation configuration was delivered by mutating `Deno.env`, which is process-global, so
+// two concurrent calls would read each other's values — including a service-role key granted to one
+// route and not the other. The defence was a lock held across the whole handler, which meant one
+// invocation at a time: a function waiting two seconds on a third-party API blocked every other
+// function for two seconds.
+//
+// It was invisible because the deployed worker had the same lock, so local behaved exactly like
+// production and there was nothing to compare against. Measured after the fix: four 300ms
+// invocations complete in about 430ms through the worker and 655ms through this router, against
+// ~1200ms serial.
+//
+// These assert the shape rather than the timing. A timing test here would need a Deno runtime and
+// would be the slowest test in the suite; what actually regresses is somebody reintroducing the
+// global mutation, and that is visible in the source.
+
+const ROUTER = generateFunctionsRouterSource("/project/.supatype/functions-router.ts", [
+  { name: "hello", entrypoint: "/project/functions/hello/index.ts" },
+])
+
+describe("the generated functions router", () => {
+  it("holds no lock across a handler", () => {
+    // Any of these names coming back means the serialisation is back.
+    for (const banned of ["envLock", "withEnvLock", "runWithScopedEnv"]) {
+      expect(ROUTER).not.toContain(banned)
+    }
+  })
+
+  it("does not write per-invocation values into the process environment", () => {
+    // `Deno.env.set` is the mechanism, and there is no safe amount of it: the environment is shared
+    // by every invocation in the isolate, so one write is enough to need the lock back.
+    expect(ROUTER).not.toContain("Deno.env.set")
+    expect(ROUTER).not.toContain("Deno.env.delete")
+  })
+
+  it("passes the call's configuration to the handler instead", () => {
+    expect(ROUTER).toContain("ctx: FunctionContext")
+    expect(ROUTER).toContain("handlers[fnName]!(req, context)")
+    // The service-role key reaches a route through the context or not at all.
+    expect(ROUTER).toContain("serviceRoleKey")
+  })
+
+  it("keeps each invocation's identity in async context, not in a module variable", () => {
+    // `console` is global and calls now genuinely interleave, so a captured line has to be
+    // attributed to the invocation that wrote it. A module-level "current request" would
+    // mis-attribute every interleaved line.
+    expect(ROUTER).toContain("AsyncLocalStorage")
+    expect(ROUTER).toContain("invocationStore.run(")
+  })
+
+  it("logs one JSON object per line, with the fields the cloud pipeline indexes on", () => {
+    // Promtail parses each line as JSON and labels on these, taking the timestamp from a `timestamp`
+    // field. A plain-text line is collected, matches no expression, and is indexed under no project.
+    for (const field of ["timestamp", "level", "service", "project_ref", "request_id", "duration_ms"]) {
+      expect(ROUTER).toContain(field)
+    }
+    expect(ROUTER).toContain("JSON.stringify(line)")
+  })
+
+  it("emits source that is valid to embed, with no stray template escapes", () => {
+    // The generator builds this with a template literal, so an unescaped backtick or `${` silently
+    // ends the literal and emits broken code. Cheap to assert, and it has bitten twice.
+    expect(ROUTER).not.toContain("\\`")
+    expect(ROUTER).not.toContain("\\${")
+    expect(ROUTER).toContain('import handler_0 from "')
+  })
+})

package/tests/init.test.ts

@@ -291,7 +291,11 @@ describe("scaffold()", () => {
     expect(existsSync(join(tmpRoot, "functions/.env.local"))).toBe(true)
     expect(existsSync(join(tmpRoot, "functions/deno.d.ts"))).toBe(true)
     expect(existsSync(join(tmpRoot, "functions/tsconfig.json"))).toBe(true)
-    expect(readFileSync(join(tmpRoot, "functions/hello/index.ts"), "utf8")).toContain("Deno.env.get")
+    // The scaffold teaches the context, not the environment. It used to read Deno.env.get, which is
+    // the process-global delivery that forced the worker to run one invocation at a time.
+    const hello = readFileSync(join(tmpRoot, "functions/hello/index.ts"), "utf8")
+    expect(hello).toContain("ctx: FunctionContext")
+    expect(hello).not.toContain("Deno.env.get")
     const pkg = readFileSync(join(tmpRoot, "package.json"), "utf8")
     expect(pkg).toContain("supatype functions serve")
   })
@@ -329,7 +333,37 @@ describe("scaffold()", () => {
     expect(config).toContain('provider: "local"')
     expect(config).toContain("Production storage: external S3")
     const env = readFileSync(join(tmpRoot, ".env"), "utf8")
-    expect(env).toContain("local development, MinIO")
+    expect(env).toContain("local development, SeaweedFS")
     expect(env).toContain("production, external bucket")
   })
+
+  // The compose generator has had this guard since SeaweedFS replaced MinIO; the .env generator
+  // did not, which is the whole reason it kept naming a withdrawn image and a port nothing serves.
+  // A scaffolded .env is the first thing a new project reads, so it gets the same guard.
+  it("a scaffolded .env never names MinIO or its port", () => {
+    for (const storage of ["local", "s3"] as const) {
+      scaffold(tmpRoot, {
+        ...defaultScaffoldOptions("my-app"),
+        storageLocal: storage,
+        storageProduction: storage,
+      })
+      const env = readFileSync(join(tmpRoot, ".env"), "utf8")
+      expect(env.toLowerCase()).not.toContain("minio")
+      expect(env).not.toContain("9000")
+      rmSync(tmpRoot, { recursive: true, force: true })
+      mkdirSync(tmpRoot, { recursive: true })
+    }
+  })
+
+  // The object store publishes 8333, and the storage service reads S3_ENDPOINT from this file.
+  // A local .env pointing anywhere else is a stack that starts and then fails on first upload.
+  it("local storage points at the port the object store actually publishes", () => {
+    scaffold(tmpRoot, {
+      ...defaultScaffoldOptions("my-app"),
+      storageLocal: "local",
+      storageProduction: "local",
+    })
+    const env = readFileSync(join(tmpRoot, ".env"), "utf8")
+    expect(env).toContain("S3_ENDPOINT=http://localhost:8333")
+  })
 })

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