@supatype/cli 0.2.1 → 0.3.0

package/src/cache-identity-scope.ts

@@ -0,0 +1,92 @@
+/**
+ * Whether an access rule's outcome varies by *who* is asking.
+ *
+ * This decides whether a model may declare `cache: { public: true }`. A public cache entry is
+ * global — one response served to every caller — so on a table whose read rule varies by caller it
+ * serves one user's rows to another.
+ *
+ * **Row-dependence is not the same question, and getting that wrong in either direction is a bug.**
+ * `Lte<"published_at", Now>` varies by row and by time but not by caller, so a shared entry is
+ * exactly right for it: that is the case public caching exists to serve. Refusing it would make the
+ * feature useless. Allowing `Owner<"user_id">` would make it a data leak.
+ *
+ * ## This is the second implementation of one rule
+ *
+ * supatype-server already answers this at runtime, in
+ * `internal/studiobootstrap.IsIdentityDependent`, to decide whether a response may be cached under
+ * a shared scope. This one answers it at *push* time, where the error can name the model and the
+ * rule instead of a request quietly not being cached.
+ *
+ * Two implementations of one rule drift, and the drift is silent: the push says "shareable" and the
+ * runtime says "not", or worse the other way round. `tests/fixtures/identity-scope-corpus.json` is
+ * the defence — a shared corpus of rules and expected answers that both sides run against. Change
+ * this file and you change that corpus; the Go side reads the same cases.
+ */
+
+/** A rule node, in the shape the extractor emits and the server parses. */
+export interface AccessRuleNode {
+  type?: string
+  left?: AccessOperand
+  right?: AccessOperand
+  operand?: AccessOperand
+  rules?: AccessRuleNode[]
+  rule?: AccessRuleNode
+}
+
+export interface AccessOperand {
+  kind?: string
+}
+
+/**
+ * The operands whose value differs per caller. Columns, literals and the temporal operands
+ * (`Now` and friends) are the same for everyone, so they are not here.
+ */
+const IDENTITY_OPERANDS = new Set(["authUid", "authRole", "claim"])
+
+function operandIsIdentityDependent(o: AccessOperand | undefined): boolean {
+  if (!o) return false
+  return IDENTITY_OPERANDS.has(o.kind ?? "")
+}
+
+export function isIdentityDependent(rule: AccessRuleNode | undefined | null): boolean {
+  // No rule at all is not a caller-varying rule. An absent `access.read` means the table's
+  // readability is decided elsewhere, and treating that as identity-dependent would refuse public
+  // caching on every model that never wrote one.
+  if (!rule) return false
+
+  switch (rule.type) {
+    case "public":
+    case "private":
+      return false
+
+    // "Any authenticated user" still distinguishes signed-in from anonymous, so a shared entry
+    // could serve a member's view to a stranger.
+    case "authenticated":
+    case "role":
+    case "owner":
+      return true
+
+    // Membership is per caller by construction.
+    case "in":
+    case "exists":
+      return true
+
+    case "compare":
+      return operandIsIdentityDependent(rule.left) || operandIsIdentityDependent(rule.right)
+
+    case "nullCheck":
+      return operandIsIdentityDependent(rule.operand)
+
+    case "any":
+    case "all":
+      return (rule.rules ?? []).some(isIdentityDependent)
+
+    case "not":
+      return rule.rule ? isIdentityDependent(rule.rule) : false
+
+    default:
+      // An unrecognised rule is assumed to depend on identity. Guessing the other way would share
+      // a cache entry across callers on the strength of not recognising something.
+      return true
+  }
+}

package/src/cache-provider.ts

@@ -0,0 +1,61 @@
+/**
+ * Which RESP server this stack runs: one decision, in one place.
+ *
+ * The response cache and Kong's ACME certificates share a RESP server. Since P1 that can be
+ * pg_keyspace inside the Postgres container — one stateful service instead of two, no second
+ * image to keep patched, and a cache whose memory is accounted for in the database's own
+ * reservation. That is now the default rather than the option.
+ *
+ * **Valkey stays selectable**, and stays the answer for `database.external`: pg_keyspace is loaded
+ * through `shared_preload_libraries`, which is a property of a Postgres this stack starts. Against
+ * a database Supatype does not manage there is nothing to configure, so the fallback is not a
+ * preference — it is the only thing that can run.
+ *
+ * A resolver rather than a default written into the config type, because the answer depends on
+ * more than one field: the same absent `cache.provider` means pg_keyspace beside a managed
+ * database and Valkey beside an external one. A default baked into the parser would have to be
+ * either 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 — a cache that silently never hits
+ * and, with TLS on, a Kong that cannot store its certificate.
+ */
+import { pinnedVersion } from "./binary-cache.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export type CacheProvider = "valkey" | "pg_keyspace"
+
+/**
+ * The provider this project runs, explicit or resolved.
+ *
+ * An explicit `cache.provider` is honoured exactly — including `"valkey"`, which is how a project
+ * keeps the sidecar it has. `validateProjectConfig` has already refused the one explicit
+ * combination that cannot run (pg_keyspace against `database.external`), so this never overrides
+ * what someone wrote.
+ *
+ * The two things that resolve an absent one to Valkey are both cases where this cannot know that a
+ * keyspace would work:
+ *
+ *  - **`database.external`**: pg_keyspace is loaded through `shared_preload_libraries`, and there
+ *    is no container here to set that on.
+ *  - **A pinned `versions.postgres`**: the keyspace is served by the image, and the entrypoint
+ *    honours `SUPATYPE_KEYSPACE_ENABLED` only from the release that introduced it. An older image
+ *    ignores the variable and starts with no RESP listener, which is not an error anywhere — the
+ *    stack comes up and the cache never hits. A pin says this project's image is fixed, and a
+ *    default must not assume something about a fixed image it cannot check. Unpinned tracks
+ *    latest, which carries the toggle by definition.
+ *
+ * A project on a pin that *does* carry the toggle says `cache: { provider: "pg_keyspace" }` and
+ * gets it — which is also the only instruction anyone needs, and is better than a version floor
+ * here that would have to be right about a release number in another repository.
+ */
+export function cacheProvider(config: SupatypeProjectConfig): CacheProvider {
+  const declared = config.cache?.provider
+  if (declared === "valkey" || declared === "pg_keyspace") return declared
+  if (config.database?.external) return "valkey"
+  if (pinnedVersion("postgres", config) !== undefined) return "valkey"
+  return "pg_keyspace"
+}
+
+/** Whether the RESP keyspace is served by the Postgres this stack starts. */
+export function keyspaceInPostgres(config: SupatypeProjectConfig): boolean {
+  return cacheProvider(config) === "pg_keyspace"
+}

package/src/cli-version-embedded.ts

@@ -9,4 +9,4 @@
 // Annotated `string`, not left to inference: once a release stamps a value here, the
 // inferred literal type makes the `!== ""` test in cliPackageVersion() a compile error
 // (TS2367, no overlap), so the build would only fail during a release.
-export const EMBEDDED_CLI_VERSION: string = "0.2.1"
+export const EMBEDDED_CLI_VERSION: string = "0.3.0"

package/src/commands/add.ts

@@ -101,5 +101,5 @@ function printDomainNextSteps(cwd: string, domain: string): void {
     `Platform URL: https://${domain}`,
   ])
   plain("  App, REST, Auth, Storage, Realtime, Functions, and Studio, one HTTPS domain.")
-  plain("  Certificates persist in the valkey-data volume.\n")
+  plain("  Certificates outlive restarts — in the keyspace's durable store, or the valkey-data volume.\n")
 }

package/src/commands/cache.ts

@@ -1,5 +1,5 @@
 /**
- * supatype cache: list and clean cached component binaries + REST Valkey cache.
+ * supatype cache: list and clean cached component binaries + the REST response cache.
  */
 
 import type { Command } from "commander"
@@ -135,7 +135,7 @@ export function registerCache(program: Command): void {
 
   const rest = cache
     .command("rest")
-    .description("Manage REST API response cache in Valkey")
+    .description("Manage the server-side REST API response cache")
 
   rest
     .command("list")
@@ -170,7 +170,7 @@ export function registerCache(program: Command): void {
 
   rest
     .command("get <key>")
-    .description("Show one cache entry (full Valkey key)")
+    .description("Show one cache entry (full key)")
     .option("--json", "Output JSON")
     .action(async (key: string, opts: { json?: boolean }) => {
       const cwd = process.cwd()

package/src/commands/cloud.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { readFileSync, writeFileSync, existsSync } from "node:fs"
 import { resolve } from "node:path"
@@ -91,7 +92,7 @@ export async function pushSchemaToLinkedProject(
     process.exit(1)
   }
 
-  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
   info(`Pushing schema to ${target.mode} project ${target.projectRef} (${target.environment})...`)
 
   const result = await targetSchemaPush(target, ast, {

package/src/commands/deploy.ts

@@ -11,6 +11,7 @@
  *   supatype deploy logs <version>, show build logs
  */
 
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { existsSync, readdirSync, statSync, createReadStream, mkdirSync, cpSync } from "node:fs"
 import { join, relative } from "node:path"
@@ -74,7 +75,7 @@ export function registerDeploy(program: Command): void {
 
       // Step 1: Schema push (unless --app-only or --skip-build, or already done via cloud.json)
       if (!opts.appOnly && !opts.skipBuild && !schemaDone) {
-        const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+        const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
 
         if (opts.local) {
           step("Schema Push (local)")

package/src/commands/dev.ts

@@ -10,6 +10,7 @@
  * Deno is not provisioned by the CLI on those paths.
  */
 
+import { keyspaceInPostgres } from "../cache-provider.js"
 import type { Command } from "commander"
 import { spawnSync } from "node:child_process"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
@@ -26,6 +27,7 @@ import {
 } from "../project-config.js"
 import { discoverTsFunctionsInDir, writeDevFunctionsRouter } from "../functions-router-gen.js"
 import { fieldMaskingTierFromProject } from "../field-masking-tier.js"
+import { projectHasVersionedModels } from "../model-versioning.js"
 import { signJwt } from "../jwt.js"
 import {
   devAuthenticatorPassword,
@@ -55,9 +57,13 @@ import { registerDevShutdown } from "../dev-shutdown.js"
 import { patchRouteManifest } from "../route-manifest.js"
 import { resolveRealtimeLaunch } from "../realtime-launch.js"
 import { writeAppViteEnv } from "../app-vite-env.js"
-import { ensureValkeySidecar, stopValkeySidecar } from "../valkey-sidecar.js"
+import { ensureValkeySidecar, probeTcp, stopValkeySidecar } from "../valkey-sidecar.js"
 import {
+  firstFreePort,
   initdb,
+  KEYSPACE_PORT_BASE,
+  KEYSPACE_PORT_SPAN,
+  nativeKeyspaceLibraryPresent,
   nativeMaskLibraryPresent,
   start as pgStart,
   stop as pgStop,
@@ -193,13 +199,46 @@ export function registerDev(program: Command): void {
       // pgBinDir is set on the native path and used to add DLL search path for
       // PostgREST on Windows (PostgREST links against libpq + SSL from MinGW).
       let pgBinDir: string | null = null
+      // The port the native Postgres serves RESP on, or null when this archive
+      // has no pg_keyspace and the Valkey sidecar is what the cache talks to.
+      let keyspacePort: number | null = null
 
       {
         // native: resolve pg bin dir and manage with pg_ctl
         pgBinDir = await resolvePgBinDir(config)
         const dataDir = config.database.data_dir ?? join(stateRoot, "data")
         mkdirSync(dataDir, { recursive: true })
-        const pgOpts = { pgBinDir, dataDir, port: pgPort, logPath: join(logsDir, "postgres.log") }
+        // The RESP keyspace, when this archive carries it: one process instead
+        // of a Postgres and a Valkey container. The port is chosen rather than
+        // fixed because 6379 is the first thing a developer's own Redis or a
+        // leftover sidecar takes, and a keyspace that cannot bind its port
+        // fails inside the postmaster log where nobody is looking.
+        //
+        // `cache.provider: "valkey"` is honoured here too, and this is the only place it could
+        // be: the native path asks the archive what it carries rather than the config what it
+        // wants, so a project that deliberately kept the sidecar would otherwise find Postgres
+        // serving RESP anyway and the sidecar never started.
+        const wantsPgKeyspace = keyspaceInPostgres(config)
+        keyspacePort =
+          wantsPgKeyspace && nativeKeyspaceLibraryPresent(pgBinDir)
+            ? await firstFreePort(KEYSPACE_PORT_BASE, KEYSPACE_PORT_SPAN)
+            : null
+        if (wantsPgKeyspace && nativeKeyspaceLibraryPresent(pgBinDir) && keyspacePort === null) {
+          console.warn(
+            `[supatype] ⚠  No free port in ${KEYSPACE_PORT_BASE}-${KEYSPACE_PORT_BASE + KEYSPACE_PORT_SPAN - 1} ` +
+              "for the Postgres keyspace — starting without it.",
+          )
+        }
+
+        const pgOpts = {
+          pgBinDir,
+          dataDir,
+          port: pgPort,
+          logPath: join(logsDir, "postgres.log"),
+          ...(keyspacePort !== null
+            ? { keyspacePort, keyspaceDatabase: projectName }
+            : {}),
+        }
 
         console.log("[supatype] Initialising Postgres data directory...")
         initdb(pgOpts)
@@ -399,7 +438,27 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
               ? "ses"
               : "smtp"
 
-      const valkeySidecar = ensureValkeySidecar(projectName)
+      // Postgres serves RESP itself when the archive had pg_keyspace and the
+      // port came up. The probe is not ceremony: shared memory limits, a
+      // preload ordering mistake or a port taken between the check and the
+      // start all leave a Postgres that is running and a keyspace that is not,
+      // and the difference is a cache that silently never hits.
+      const nativeKeyspaceAddr =
+        keyspacePort !== null && (await probeTcp("127.0.0.1", keyspacePort))
+          ? `127.0.0.1:${keyspacePort}`
+          : null
+      if (keyspacePort !== null && nativeKeyspaceAddr === null) {
+        console.warn(
+          `[supatype] ⚠  Postgres has pg_keyspace but is not serving RESP on :${keyspacePort} — ` +
+            "see logs/postgres.log. Falling back to the Valkey sidecar.",
+        )
+      }
+      if (nativeKeyspaceAddr) {
+        console.log(`[supatype] Keyspace served by Postgres (${nativeKeyspaceAddr}).`)
+      }
+      const valkeySidecar = nativeKeyspaceAddr
+        ? { addr: nativeKeyspaceAddr, containerName: null, started: false }
+        : ensureValkeySidecar(projectName)
 
       const serverEnv: Record<string, string> = {
         // supatype-server outer layer
@@ -513,12 +572,14 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO authenticate
           // a non-default pg_schema pushed correctly and then answered PGRST106 on every request.
           // Native dev has no masking extension either, so a schema with field rules is served from
           // `api` here too: the case an "is the database external" rule would have got wrong.
-          PGRST_DB_SCHEMA: apiSchemaList(
-            config,
+          PGRST_DB_SCHEMA: apiSchemaList(config, {
             // The installed archive decides: one downloaded before the masking library was bundled
             // has no extension, so its field rules are enforced by views instead.
-            fieldMaskingTierFromProject(cwd, config, nativeMaskLibraryPresent(pgBinDir)),
-          ),
+            tier: fieldMaskingTierFromProject(cwd, config, nativeMaskLibraryPresent(pgBinDir)),
+            // A versioned model adds the generated `draft` schema, or `.draft()` would answer
+            // PGRST106 against a stack that had migrated the views into place.
+            drafts: projectHasVersionedModels(cwd, config),
+          }),
           // Parity with self-host, which has always set this. Unqualified names in column defaults
           // (`uuid_generate_v4()`) resolve here, and with a non-public pg_schema the request schema
           // alone does not reach them.

package/src/commands/diff.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { resolveRuntimeProvider, schemaPathFromProject } from "../project-config.js"
@@ -19,7 +20,7 @@ export function registerDiff(program: Command): void {
       const pgSchema = schemaPgSchema(cwd)
 
       const ast = await withSpinner("Loading schema", async () =>
-        loadSchemaAst(schemaPathFromProject(config, cwd), cwd),
+        withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config),
       )
 
       const linked = loadProjectLink(cwd)

package/src/commands/functions.ts

@@ -141,9 +141,13 @@ function scaffoldFunction(cwd: string, name: string): void {
   const indexContent = `// ${name}, Supatype Edge Function
 // Docs: https://supatype.com/docs/edge-functions
 
-export default async function handler(req: Request): Promise<Response> {
+import type { FunctionContext } from "../_shared/context.ts"
+
+export default async function handler(req: Request, ctx: FunctionContext): Promise<Response> {
   const { method } = req
-  const url = Deno.env.get("SUPATYPE_URL")
+  // From the context, not the environment. Per-invocation values are passed in, which is what lets
+  // the worker run your functions concurrently instead of one at a time.
+  const { url } = ctx
 
   // Example: read request body for POST requests
   if (method === "POST") {

package/src/commands/init.ts

@@ -70,7 +70,7 @@ const STORAGE_PROVIDER_OPTIONS: {
   label: string
   hint: string
 }[] = [
-  { value: "local", label: "Local", hint: "storage you host yourself (MinIO)" },
+  { value: "local", label: "Local", hint: "storage you host yourself (SeaweedFS)" },
   { value: "s3", label: "S3", hint: "external bucket (AWS S3 or compatible)" },
 ]
 
@@ -1164,7 +1164,7 @@ function storageConfigLines(
   if (storageProduction === "s3" && storageLocal !== "s3") {
     lines.push(`  // Production storage: external S3 bucket, set production S3_* in .env`)
   } else if (storageProduction === "local" && storageLocal === "s3") {
-    lines.push(`  // Production storage: MinIO on your server (included in self-host compose)`)
+    lines.push(`  // Production storage: SeaweedFS on your server (included in self-host compose)`)
   }
   return lines
 }
@@ -1305,7 +1305,7 @@ S3_SECRET_KEY=`
     }
     return `${localStorageEnvSection("local")}
 
-# Production storage (MinIO on your server)
+# Production storage (SeaweedFS on your server)
 # Included in the self-host compose stack, no extra configuration needed.`
   }
 
@@ -1323,8 +1323,8 @@ S3_BUCKET=
 S3_ACCESS_KEY=
 S3_SECRET_KEY=`
   }
-  return `# Storage (local development, MinIO)
-S3_ENDPOINT=http://localhost:9000
+  return `# Storage (local development, SeaweedFS)
+S3_ENDPOINT=http://localhost:8333
 S3_ACCESS_KEY=supatype
 S3_SECRET_KEY=supatype-secret`
 }
@@ -1338,7 +1338,7 @@ S3_BUCKET=
 S3_ACCESS_KEY=
 S3_SECRET_KEY=`
   }
-  return `# Storage (production, MinIO on your server)
+  return `# Storage (production, SeaweedFS on your server)
 # Included in the self-host compose stack, no extra configuration needed.`
 }
 
@@ -1372,9 +1372,13 @@ function helloFunctionTemplate(): string {
   return `// hello: Supatype Edge Function
 // Docs: https://supatype.com/docs/edge-functions
 
-export default async function handler(req: Request): Promise<Response> {
+import type { FunctionContext } from "../_shared/context.ts"
+
+export default async function handler(req: Request, ctx: FunctionContext): Promise<Response> {
   const { method } = req
-  const url = Deno.env.get("SUPATYPE_URL")
+  // From the context, not the environment. Per-invocation values are passed in, which is what lets
+  // the worker run your functions concurrently instead of one at a time.
+  const { url } = ctx
 
   if (method === "POST") {
     const body = await req.json()
@@ -1507,7 +1511,7 @@ function printNextSteps(args: {
       selfHostSteps.push("supatype self-host compose up -d   # Kong provisions HTTPS automatically")
       selfHostSteps.push(`Your Supatype platform goes live at https://${domain}`)
       selfHostSteps.push(
-        "Your app, REST, Auth, Storage, Realtime, Functions, and Studio, all behind one HTTPS domain (certs persist in valkey-data)",
+        "Your app, REST, Auth, Storage, Realtime, Functions, and Studio, all behind one HTTPS domain (certificates outlive restarts)",
       )
     } else {
       selfHostSteps.push(

package/src/commands/migrate.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { join } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
@@ -149,7 +150,7 @@ export function registerMigrate(program: Command): void {
       const cwd = process.cwd()
 
       await ensureEngine()
-      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
       const result = await engineRequest<{ message?: string }>("/push", {
         ast,
         database_url: connection,

package/src/commands/push.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
@@ -19,6 +20,10 @@ import {
 } from "../project-config.js"
 import { ensureEngine, engineRequest, type DiffResult } from "../engine-client.js"
 import { assertEngineSupportsSchema } from "../engine-floor.js"
+import {
+  modelsWithUnresolvablePreview,
+  unresolvablePreviewMessage,
+} from "../preview-config-check.js"
 import { pinnedVersion } from "../binary-cache.js"
 import { printDiffOperations, printDiffWarnings } from "../diff-output.js"
 import { signJwt } from "../jwt.js"
@@ -27,6 +32,7 @@ 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 type { SupatypeProjectConfig } from "../project-config.js"
 import {
   resolveTarget,
@@ -71,10 +77,11 @@ export function registerPush(program: Command): void {
       const cwd = process.cwd()
       const config = loadConfig(cwd)
       const pgSchema = schemaPgSchema(cwd)
-      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
       assertModelHooksResolve(cwd, config, ast)
       assertServiceRoleGrantsResolve(cwd, config)
       assertEngineSupportsSchema(ast, pinnedVersion("engine", config))
+      assertPreviewAddressesResolve(config)
 
       const linked = loadProjectLink(cwd)
       const useDirect = opts.direct || opts.local || Boolean(opts.connection)
@@ -175,6 +182,7 @@ async function pushViaTarget(
     }
     await generateTypesLocal(ast, config)
     await provisionLocalStorage(ast, config)
+    reportCacheSeeding(cwd, ast)
 
     // Local Studio only: a cloud/self-host push must not advertise the local
     // gateway URL from config, which may not even be running.
@@ -186,6 +194,12 @@ async function pushViaTarget(
   }
 
   info(`Pushed to ${target.mode} (${target.environment}).`)
+  // Cloud only. A self-host control plane has tiers too and they mean nothing there, so the same
+  // sentence would be telling a self-hosted project to upgrade something it already has.
+  if (target.mode === "cloud") {
+    const note = freeTierCacheNote((pushResult as { cache?: { tables?: string[]; honoured?: boolean } }).cache)
+    if (note) info(note)
+  }
   const envUrl = target.link?.environments?.[target.environment]?.apiUrl?.replace(/\/$/, "")
   if (envUrl) {
     plain(`\nProject API: ${envUrl}`)
@@ -239,6 +253,33 @@ async function deployHooksToTarget(
   ).then(() => info(`Deployed ${upload.handlers.length} hook(s)`))
 }
 
+/**
+ * Switch on what the schema newly declares, and say what is still in the way.
+ *
+ * Two things have to be true for a local `.cache({ server: true })` to be served: the schema
+ * declares the table, and the runtime allowlist has it on. A push writes the first, so without
+ * this the second is a trip to Studio that nothing in the output asks for — the symptom being a
+ * BYPASS header and a declaration that appears to do nothing.
+ *
+ * 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.`,
+    )
+  }
+}
+
 /** The generated adapter, flattened to the name handlers were rewritten to import. */
 function readGeneratedAdapter(hooksDir: string): { name: string; source: string } | null {
   const file = join(hooksDir, "_supatype", "hooks.ts")
@@ -295,6 +336,21 @@ async function writeLocalAdminConfig(ast: unknown, config: SupatypeProjectConfig
   writeFileSync(join(dir, "admin-config.json"), `${JSON.stringify(admin, null, 2)}\n`)
 }
 
+/**
+ * Stop the push when a preview address could never open.
+ *
+ * Refused here rather than left to fail later, because later means in front of whoever was sent the
+ * link, not in front of whoever configured it.
+ */
+function assertPreviewAddressesResolve(config: SupatypeProjectConfig): void {
+  const models = modelsWithUnresolvablePreview(config)
+  if (models.length === 0) return
+  fatalError(unresolvablePreviewMessage(models), [
+    'Give an absolute URL: urlPattern: "https://example.com/preview/{slug}"',
+    'Or set app.mode to "static" or "proxy", if this deployment should serve the app.',
+  ])
+}
+
 /**
  * Stop the push when a declared hook names a function that is not there.
  *

package/src/compose-services.ts

@@ -4,7 +4,8 @@
  * `status` and `logs` each used to carry a hardcoded list of container names.
  * Both lists were wrong: they named containers the compose file does not create
  * (`supatype-postgres`, `supatype-kong`), omitted every service it does create
- * (`server`, `storage`, `functions-worker`, `schema-engine`, `valkey`), and used
+ * (`server`, `storage`, `functions-worker`, `schema-engine`, and `valkey` when the
+ * stack runs one), and used
  * a naming scheme the compose file never applies, since it sets no
  * `container_name` and Docker therefore names containers
  * `<project>-<service>-<n>`.