@supatype/cli 0.3.0 → 0.3.2

package/src/schema-ast-v2.ts

@@ -227,6 +227,15 @@ export interface ExtractedSchemaAstV2 {
   }
 }
 
+/**
+ * The Postgres type each field kind maps to, as published in the AST.
+ *
+ * A contract, not a hint: consumers generate parsers and casts from it. `money` and `decimal` said
+ * `TEXT` here while the engine creates `NUMERIC(19,4)` and `NUMERIC`, so anyone reading this wrote
+ * code that rejected every value the column returns. The engine's own `default_pg_type` agreed
+ * with the mistake for `money`, and was already right for `decimal`, which is what made it look
+ * considered.
+ */
 const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>> = {
   text: { pgType: "TEXT" },
   richText: { pgType: "JSONB" },
@@ -244,17 +253,17 @@ const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>
   slug: { pgType: "TEXT" },
   enum: { pgType: "TEXT" },
   json: { pgType: "JSONB" },
-  decimal: { pgType: "TEXT" },
+  decimal: { pgType: "NUMERIC" },
   bytes: { pgType: "BYTEA" },
   serial: { pgType: "SERIAL" },
   bigSerial: { pgType: "BIGSERIAL" },
-  money: { pgType: "TEXT" },
-  ip: { pgType: "TEXT" },
-  cidr: { pgType: "TEXT" },
-  macaddr: { pgType: "TEXT" },
-  xml: { pgType: "TEXT" },
-  tsQuery: { pgType: "TEXT" },
-  tsVector: { pgType: "TEXT" },
+  money: { pgType: "NUMERIC(19,4)" },
+  ip: { pgType: "INET" },
+  cidr: { pgType: "CIDR" },
+  macaddr: { pgType: "MACADDR" },
+  xml: { pgType: "XML" },
+  tsQuery: { pgType: "TSQUERY" },
+  tsVector: { pgType: "TSVECTOR" },
   color: { pgType: "TEXT" },
   array: { pgType: "ARRAY" },
   image: { pgType: "JSONB" },

package/src/self-host-compose.ts

@@ -17,7 +17,8 @@ import {
 import { hasEngineOverride, hasStudioOverride, pinnedVersion, fetchLatestVersion, VERSION_PIN_LOCAL } from "./binary-cache.js"
 import { buildKongDeclarative } from "./kong-config.js"
 import { keyspaceInPostgres } from "./cache-provider.js"
-import { readEnvFile } from "./env-file.js"
+import { STUDIO_DEV_PORT } from "./studio-dev-server.js"
+import { hasEnvValue, readEnvFile } from "./env-file.js"
 import { fieldMaskingTierFromProject, type FieldMaskingTier } from "./field-masking-tier.js"
 import { projectHasVersionedModels } from "./model-versioning.js"
 
@@ -285,8 +286,16 @@ function postgrestDatabaseUrl(config: SupatypeProjectConfig): string {
   return `postgresql://authenticator:${password}@${parsed.hostname}${port}${parsed.pathname}${parsed.search}`
 }
 
-/** Host Vite dev server as seen from Kong inside Docker Compose. */
-export const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002"
+/**
+ * Host Vite dev server as seen from Kong inside Docker Compose.
+ *
+ * Derived from STUDIO_DEV_PORT rather than repeating the number, because the two are one decision.
+ * Held separately they drift, and the drift is invisible: Vite binds the new port, Kong keeps
+ * proxying to the old one, and `/studio/` serves whatever else happens to be listening there. On
+ * the machine this was found, that was an unrelated Next.js app, and every Studio view failed with
+ * a missing sign-in form rather than anything naming a port.
+ */
+export const COMPOSE_STUDIO_HOST_URL = `http://host.docker.internal:${STUDIO_DEV_PORT}`
 
 /** Studio container: always Docker Hub unless SUPATYPE_STUDIO_IMAGE is set in .env. */
 function studioServiceBlock(): string {
@@ -395,25 +404,41 @@ ${studioService}
     : `      - server
       - studio
       - control-plane`
-  const publishDbToHost = !devLocal || hasEngineOverride(config)
+  // In dev the database is published only when something on the host needs to reach it, which is
+  // normally a host engine build. A project that names a port is asking for one too: without this,
+  // `SUPATYPE_DEV_DB_PORT` was honoured for the number and ignored for whether the port existed,
+  // so a seed connecting over TCP got ECONNREFUSED and nothing said why.
+  const dbPortRequested = hasEnvValue(cwd, "SUPATYPE_DEV_DB_PORT")
+  const publishDbToHost = !devLocal || hasEngineOverride(config) || dbPortRequested
   const dbPorts = publishDbToHost
     ? devLocal
       ? `    ports:
       - "127.0.0.1:\${SUPATYPE_DEV_DB_PORT:-54329}:5432"
 `
       : `    ports:
-      - "5432:5432"
+      - "\${SUPATYPE_DB_PORT:-5432}:5432"
 `
     : ""
+  // Host ports, every one of them overridable.
+  //
+  // Kong's has been `${SUPATYPE_KONG_PORT:-18473}` for as long as `supatype dev` has picked a free
+  // one per project and written it back to .env. These three were fixed literals, so the second
+  // project on a machine could not start: Docker refuses the bind and compose reports only that
+  // the stack would not come up, naming no port. Two projects side by side is the normal case
+  // here (this repository ships eight examples), so a literal is the wrong default.
+  //
+  // Defaults are the previous literals, so a project with none of these set behaves exactly as
+  // before. Allocating them per project the way the Kong port is allocated is the follow-up; this
+  // makes a second stack possible rather than automatic.
   const serverPorts = devLocal
     ? ""
     : `    ports:
-      - "9999:9999"
+      - "\${SUPATYPE_SERVER_PORT:-9999}:9999"
 `
   const seaweedPorts = devLocal
     ? ""
     : `    ports:
-      - "8333:8333"
+      - "\${SUPATYPE_SEAWEEDFS_PORT:-8333}:8333"
 `
   // One source for the credentials: the server is configured with them and the storage service is
   // handed them, and a mismatch does not fail at start, it fails at the first upload.
@@ -426,6 +451,15 @@ ${studioService}
     volumes:
       - storage-data:/data
       - ${SEAWEED_CONFIG_MOUNT}:/etc/seaweedfs/s3.json:ro
+    healthcheck:
+      # Any HTTP status line means the S3 endpoint is listening, which is the whole question.
+      # Success cannot be "HTTP 200": an unauthenticated GET on the root answers 403 by design,
+      # because the anonymous identity is deliberately absent from s3.json.
+      test: ["CMD-SHELL", "wget -q -S -O /dev/null http://127.0.0.1:8333 2>&1 | grep -q 'HTTP/'"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+      start_period: 5s
 ${seaweedPorts}`
   const kongTlsEnv = tlsEnabled
     ? `      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
@@ -480,6 +514,21 @@ ${keyspaceInPg ? "" : "  valkey-data:\n"}`
 `
   const dbDependency = external ? "" : `    depends_on:\n${dbDependencyClause}`
 
+  // Storage waits for the object store, not only the database.
+  //
+  // seaweedfs had no healthcheck and nothing depended on it, so compose started it alongside
+  // storage rather than before it. Storage would then accept a bucket creation before seaweedfs
+  // was listening, and every bucket in the schema failed with `connect ECONNREFUSED <ip>:8333`
+  // while the metadata row was written anyway. Measured on a live stack: seaweedfs started twelve
+  // minutes after storage with RestartCount 0, so it was ordered late rather than crashing.
+  //
+  // A later push succeeds, which is exactly what made it read as an intermittent mystery. It
+  // lands on the first push after a stack comes up, which is the first push a new user ever runs.
+  const storageDependency = `    depends_on:
+${dbDependencyClause}      seaweedfs:
+        condition: service_healthy
+`
+
   // Realtime, omitted entirely when the project has turned it off.
   //
   // Not started-and-disabled: the service degrades gracefully on its own (it reports the reason on
@@ -560,6 +609,29 @@ ${dbDependency}`
       SUPATYPE_KEYSPACE_KEYS: "200000"
       SUPATYPE_KEYSPACE_RING_MB: "16"
       SUPATYPE_KEYSPACE_ROWCACHE_MB: "64"
+      # Mode B, the row cache itself. The segment above is reserved either way; these two decide
+      # whether anything decodes into it or serves from it, and the image refuses readthrough
+      # without decode because that pair serves stale rows forever rather than merely wasting
+      # memory.
+      #
+      # From .env rather than a literal, because only a push can answer this: the switches follow
+      # whether any model declares \`cache: { rows: true }\`, and \`self-host compose render\` runs
+      # with no schema in hand. Default off, so a project that declares no row cache does not pin
+      # WAL behind a replication slot it never reads.
+      SUPATYPE_KEYSPACE_ROWCACHE_DECODE: "\${SUPATYPE_KEYSPACE_ROWCACHE_DECODE:-0}"
+      SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH: "\${SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH:-0}"
+      # Both decoders this stack runs, because the image's setting REPLACES the allowlist.
+      #
+      # Turning the row cache on makes the entrypoint write
+      # \`output_plugin_libraries = 'supacache_keys'\`, and PostgreSQL then refuses every other
+      # plugin. Realtime decodes with wal2json, so a project that declared \`cache: { rows: true }\`
+      # silently lost realtime: the service stayed up, answered /health/ready with 200, and logged
+      # \`library "wal2json" may not be used as an output plugin\` once a second while every
+      # subscription reported SUBSCRIBED and delivered nothing.
+      #
+      # Named here rather than left to the image because only this file knows both features are in
+      # the same stack.
+      SUPATYPE_KEYSPACE_OUTPUT_PLUGIN_LIBRARIES: "supacache_keys, wal2json"
 `
     : ""
 
@@ -642,7 +714,7 @@ ${dbDependency}
       S3_ACCESS_KEY: ${OBJECT_STORE_ACCESS_KEY}
       S3_SECRET_KEY: ${OBJECT_STORE_SECRET_KEY}
       S3_FORCE_PATH_STYLE: "true"
-${dbDependency}
+${storageDependency}
   functions-worker:
     image: \${SUPATYPE_FUNCTIONS_WORKER_IMAGE:-supatype/functions-worker:latest}
     expose:
@@ -671,6 +743,18 @@ ${dbDependency}
       # each one able to read past every access rule in the schema.
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
       SUPATYPE_SERVICE_ROLE_ROUTES: "${serviceRoleRoutes(config).join(",")}"
+      # A direct database connection for functions, off unless asked for.
+      #
+      # The worker reads SUPATYPE_DB_URL and exposes it as \`ctx.dbUrl\`, and nothing here ever set
+      # it, so the field was permanently undefined on self-host and a function reaching for it got
+      # no value and no explanation.
+      #
+      # Deliberately its own variable rather than the project's DATABASE_URL. That one is the owner
+      # DSN every service already uses, and wiring it through by default would hand every function
+      # a connection that bypasses access rules, field masking and model hooks, none of which live
+      # in the database. Naming a separate variable makes it a decision: set it to the owner URL
+      # and accept that, or to a role you restricted yourself.
+      SUPATYPE_DB_URL: \${SUPATYPE_FUNCTIONS_DB_URL:-}
       STRIPE_SECRET_KEY: \${STRIPE_SECRET_KEY:-}
       STRIPE_WEBHOOK_SECRET: \${STRIPE_WEBHOOK_SECRET:-}
       SITE_URL: \${SITE_URL:-\${API_EXTERNAL_URL:-${externalUrlFallback}}}
@@ -696,6 +780,12 @@ ${realtimeBlock}
 ${dbDependency}
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     # The server runs its migrations at boot on a connection of their own,
     # and that path does not wait out a database that is still in recovery:
     # it exits. Waiting for db to report healthy is not enough, because
@@ -705,7 +795,17 @@ ${dbDependency}
     # stays visible instead of hiding in a crash loop.
     restart: on-failure:5
 ${serverPorts}    volumes:
+      # The project is read-only: the server reads the schema, the manifest and the functions, and
+      # has no business editing any of them.
       - ${projectMount}:/project:ro
+      # .supatype is the exception, and only because one file in it is not project source.
+      # api-config.json is the operator's runtime state: which tables have caching switched on,
+      # the project TTL, max_rows. PATCH /admin/v1/config/rest writes it, which is what Studio's
+      # cache panel and the CLI's cache commands call. Under the read-only mount alone that PATCH
+      # fails with "read-only file system", so a cache a model declares can be read back as
+      # declared and never actually switched on. A narrower bind than making the whole project
+      # writable, because the rest of the tree keeps the guarantee.
+      - ${projectMount}/.supatype:/project/.supatype
     working_dir: /project
     environment:
       SUPATYPE_MODE: ${devLocal ? "dev" : "standalone"}
@@ -754,7 +854,7 @@ ${appEnv}
       SUPATYPE_SMTP_ADMIN_EMAIL: \${SUPATYPE_SMTP_ADMIN_EMAIL:-}
       SUPATYPE_SMTP_SENDER_NAME: \${SUPATYPE_SMTP_SENDER_NAME:-}
       SUPATYPE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
-${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
+${devLocal ? "      STUDIO_OPEN_DEV: \"${STUDIO_OPEN_DEV:-1}\"\n" : ""}
     depends_on:
 ${dbDependencyClause}${keyspaceInPg ? "" : "      valkey:\n        condition: service_started\n"}      postgrest:
         condition: service_started
@@ -775,6 +875,12 @@ ${objectStoreBlock}
     working_dir: /project
 ${dbDependency}${studioBlock}${valkeyBlock}${tlsHintComment}  kong:
     image: kong:3.6
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       KONG_DATABASE: "off"
       KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml

package/src/strict.ts

@@ -0,0 +1,40 @@
+/**
+ * Strict mode: a degraded path is a failure rather than a warning.
+ *
+ * Every fallback in this CLI exists because giving up would serve a person at a terminal worse
+ * than carrying on: the in-compose engine when the CDN cannot be reached, SHA256-only verification
+ * when no key is embedded, a bucket that could not be reached from the host but works from inside
+ * the network. Each is the right default interactively.
+ *
+ * In CI the trade runs the other way. A run that limps reports success, and the thing it quietly
+ * skipped is precisely the thing nobody tests again.
+ *
+ * This is not hypothetical. On 2026-09-24 three integration jobs failed on assertions about
+ * validators and served SPAs, and the cause in all three was an engine download refused twenty
+ * lines earlier and warned about. The same fallback made a local from-zero run look like a clean
+ * pass while the host engine path was never exercised at all.
+ */
+
+/** True when the caller has asked for degraded paths to fail. */
+export function strict(): boolean {
+  return process.env["SUPATYPE_STRICT"] === "1"
+}
+
+/**
+ * Report a path that worked less well than intended.
+ *
+ * Throws under `SUPATYPE_STRICT=1`, so a CI job cannot pass over it. Warns otherwise, because
+ * interactively a working stack and a note beats an abort.
+ *
+ * `what` names the capability that degraded, not the error: the reader needs to know which feature
+ * they are now without. `detail` carries the cause.
+ */
+export function degraded(what: string, detail: string): void {
+  const message = `${what}: ${detail}`
+  if (strict()) {
+    throw new Error(
+      `${message}\nSUPATYPE_STRICT=1 is set, so a degraded path fails rather than warns.`,
+    )
+  }
+  console.warn(`[supatype] ${message}`)
+}

package/src/studio-dev-server.ts

@@ -2,8 +2,18 @@ import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { ProcessManager } from "./process-manager.js"
 
-/** Vite dev server port when `overrides.studio` is set. */
-export const STUDIO_DEV_PORT = 3002
+/**
+ * Vite dev server port when `overrides.studio` is set.
+ *
+ * Overridable because it is bound with `--strictPort`, so anything else already on 3002 does not
+ * make Vite pick another port, it makes Studio fail to start and be restarted every thirty seconds
+ * for the life of the session. 3002 is an ordinary port for a local app to be sitting on, and the
+ * only signal is a Vite stack trace in among the compose output.
+ *
+ * Only the `overrides.studio` path is affected, so this is a contributor's papercut rather than a
+ * user's: an ordinary `supatype dev` serves Studio from its container.
+ */
+export const STUDIO_DEV_PORT = Number(process.env["SUPATYPE_STUDIO_DEV_PORT"]) || 3002
 
 export interface StudioDevServerOptions {
   cwd: string

package/src/type-extractor.ts

@@ -1055,7 +1055,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("file", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,
@@ -1067,7 +1070,10 @@ function parseScalarType(
         const assetOpts = parseAssetFieldOptions(typeNode.typeArguments?.[1], sourceFile)
         return attachStorageFieldMeta(
           scalar("image", {
-            db: { pgType: "TEXT" },
+            // JSONB, not TEXT. The column holds { bucket, path }, this package's own
+            // DEFAULT_DB_BY_KIND says JSONB, and the engine honours an explicit annotation, so
+            // TEXT here was one code path from a text column with a JSON object written into it.
+            db: { pgType: "JSONB" },
             kernel: { bucket, ...(assetOpts.localized && { localized: true }) },
           }),
           bucket,

package/src/type-generation.ts

@@ -13,9 +13,13 @@
  */
 
 import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname, resolve } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 import { generateClientAugmentation } from "./augmentation-generator.js"
 import { ensureEngine, engineRequest } from "./engine-client.js"
+import { generateProjectClient } from "./client-generator.js"
+
+/** The client a project imports, beside the generated types. */
+const PROJECT_CLIENT_FILENAME = "client.ts"
 
 export interface GenerateTypesRequest {
   cwd: string
@@ -48,7 +52,27 @@ export async function writeGeneratedTypes(req: GenerateTypesRequest): Promise<st
     written.push(`Types written to ${req.typesPath}`)
   }
 
-  // Generated locally from the AST, so it needs no engine round trip.
+  written.push(...writeAstDerivedOutputs(req))
+
+  return written
+}
+
+/**
+ * The generated files that come from the AST alone, with no engine round trip.
+ *
+ * Shared because three commands need them and only one was writing them. `push` and `generate`
+ * call {@link writeGeneratedTypes}; `dev` has its own type generation, for good reasons it should
+ * keep, and so never wrote these at all. The result was a project developed entirely through
+ * `supatype dev` that never received `index.d.ts`, so the module augmentation that makes
+ * `createClient` typed without a generic never happened, and never received the generated client,
+ * so every exact-value column fell back to asking the API.
+ *
+ * Kept separate from the types branch above rather than folding `dev` into it: that branch slices
+ * the engine's output from a marker and treats a failure as fatal, and `dev` must do neither.
+ */
+export function writeAstDerivedOutputs(req: GenerateTypesRequest): string[] {
+  const written: string[] = []
+
   if (req.clientPath !== undefined && req.clientPath !== "") {
     const outPath = resolve(req.cwd, req.clientPath)
     mkdirSync(dirname(outPath), { recursive: true })
@@ -56,5 +80,26 @@ export async function writeGeneratedTypes(req: GenerateTypesRequest): Promise<st
     written.push(`Client augmentation written to ${req.clientPath}`)
   }
 
+  // The client the project imports. One file carrying the augmentation, the exact-value columns
+  // and a re-export of `createClient`, so an app writes a single import and tsconfig cannot lose
+  // any of it. See `client-generator.ts` for what each part replaced.
+  // Beside `output.client` when set, otherwise beside `output.types`. A project that configured
+  // only types still gets a usable client: this one file carries the augmentation and the exact
+  // columns as well as `createClient`, so without it the project has types and no way to use them
+  // that knows anything about its schema.
+  const clientDir = req.clientPath ?? req.typesPath
+  if (clientDir !== undefined && clientDir !== "") {
+    const relative = join(dirname(clientDir), PROJECT_CLIENT_FILENAME)
+    const outPath = resolve(req.cwd, relative)
+    mkdirSync(dirname(outPath), { recursive: true })
+    writeFileSync(outPath, generateProjectClient(req.ast), "utf8")
+    written.push(`Client written to ${toPosix(relative)}`)
+  }
+
   return written
 }
+
+/** Reported with forward slashes, so the message reads the same on every platform. */
+function toPosix(path: string): string {
+  return path.split(sep).join("/")
+}

package/tests/ast-derived-outputs.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The generated files that need no engine, and which `dev` never wrote.
+ *
+ * `push` and `generate` go through `writeGeneratedTypes`. `dev` has its own type generation, which
+ * it should keep: it slices the engine's output from a marker and treats a failure as a warning
+ * rather than killing the session. What it should not have had is its own idea of which files
+ * exist, and the result was that a project developed entirely through `supatype dev` never
+ * received the module augmentation that types `createClient` without a generic.
+ *
+ * Both files come from the AST alone, so they are shared and all three commands write them.
+ */
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { writeAstDerivedOutputs } from "../src/type-generation.js"
+
+const ast = {
+  models: [
+    {
+      name: "JobPost",
+      annotations: { db: { tableName: "job_post" } },
+      fields: {
+        id: { kind: "uuid", required: true },
+        views: { kind: "bigInt", required: true },
+      },
+    },
+  ],
+}
+
+let cwd: string
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), "supatype-outputs-"))
+})
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+describe("writeAstDerivedOutputs", () => {
+  it("writes the augmentation and the project client together", () => {
+    const written = writeAstDerivedOutputs({
+      cwd,
+      ast,
+      typesPath: "supatype/generated/database.ts",
+      clientPath: "supatype/generated/index.d.ts",
+    })
+
+    expect(existsSync(join(cwd, "supatype/generated/index.d.ts"))).toBe(true)
+    expect(existsSync(join(cwd, "supatype/generated/client.ts"))).toBe(true)
+    expect(written).toHaveLength(2)
+  })
+
+  it("puts the client beside the generated types", () => {
+    // An app imports it by a relative path, so it has to land next to the rest of the generated
+    // output rather than at the project root.
+    writeAstDerivedOutputs({ cwd, ast, clientPath: "supatype/generated/index.d.ts" })
+    const body = readFileSync(join(cwd, "supatype/generated/client.ts"), "utf8")
+
+    expect(body).toContain('export * from "@supatype/client"')
+    expect(body).toContain('declare module "@supatype/client"')
+    expect(body).toContain('"views": "bigint"')
+  })
+
+  it("writes nothing when a project configured no output at all", () => {
+    // `push` must not start creating files in projects that never asked for any.
+    expect(writeAstDerivedOutputs({ cwd, ast })).toEqual([])
+    expect(existsSync(join(cwd, "supatype"))).toBe(false)
+  })
+
+  it("needs no engine, so it can run when type generation could not", () => {
+    // This is why it is separate: in `dev` the engine may be unavailable, and the augmentation and
+    // the client should still reach the project.
+    const written = writeAstDerivedOutputs({ cwd, ast, clientPath: "supatype/generated/index.d.ts" })
+    expect(written.some((line) => line.includes("Client written"))).toBe(true)
+  })
+})
+
+describe("a project that configured only types", () => {
+  it("still gets a client, beside the types", () => {
+    // Otherwise it has generated types and no way to use them that knows its schema: the
+    // augmentation and the exact-value columns both travel in this file.
+    const dir = mkdtempSync(join(tmpdir(), "supatype-types-only-"))
+    try {
+      writeAstDerivedOutputs({ cwd: dir, ast, typesPath: "supatype/generated/database.ts" })
+      expect(existsSync(join(dir, "supatype/generated/client.ts"))).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/tests/augmentation-generator.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { generateClientAugmentation } from "../src/augmentation-generator.js"
+import { generateClientAugmentation, generateRowType } from "../src/augmentation-generator.js"
 
 describe("generateClientAugmentation", () => {
   it("emits deterministic output independent of model order", () => {
@@ -125,3 +125,129 @@ describe("generateClientAugmentation", () => {
     expect(out).toContain("notes: Record<string, unknown> | null")
   })
 })
+
+describe("exact-value numeric kinds", () => {
+  /**
+   * A column whose value does not survive an IEEE-754 double must not be typed as one.
+   *
+   * `decimal` used to emit `number` here while `@supatype/types` declared `Decimal<P, S>` as
+   * `string` and the engine emitted `string`, so the ambient client type contradicted both and
+   * told a caller a rounded value was exact.
+   */
+  it("types money, decimal and bigInt so the exact value survives", () => {
+    const out = generateClientAugmentation({
+      models: [
+        {
+          name: "Invoice",
+          annotations: { db: { tableName: "invoice", indexes: [] } },
+          fields: {
+            total: { kind: "money", required: true },
+            rate: { kind: "decimal", required: true },
+            ref: { kind: "bigInt", required: true },
+            qty: { kind: "integer", required: true },
+          },
+        },
+      ],
+    })
+
+    expect(out).toContain("total: string")
+    expect(out).toContain("rate: string")
+    expect(out).toContain("ref: bigint")
+    // The kinds that genuinely fit a double are untouched.
+    expect(out).toContain("qty: number")
+  })
+})
+
+describe("relation fields", () => {
+  const talk = {
+    models: [
+      {
+        name: "Talk",
+        annotations: { db: { tableName: "talk", indexes: [] } },
+        fields: {
+          title: { kind: "text", required: true },
+          speaker: {
+            kind: "relation",
+            cardinality: "belongsTo",
+            target: "Speaker",
+            annotations: { db: { foreignKey: "speaker_id" } },
+          },
+          venue: {
+            kind: "relation",
+            cardinality: "belongsTo",
+            target: "Room",
+            required: true,
+            annotations: { db: { foreignKey: "room_id" } },
+          },
+          authUser: { kind: "relation", cardinality: "belongsTo", target: "User" },
+          slots: { kind: "relation", cardinality: "hasMany", target: "Slot" },
+        },
+      },
+    ],
+  }
+
+  /**
+   * A `belongsTo` is a foreign key column, not an embedded object.
+   *
+   * The generator used to group `relation` with geo/vector/image and emit
+   * `Record<string, unknown>` under the *declared* name, so the augmentation claimed a column
+   * named `speaker` holding an object while Postgres and the engine both had `speaker_id`
+   * holding text. Wrong name and wrong type on the same column.
+   */
+  it("emits the foreign key column, not the declared relation name", () => {
+    const out = generateClientAugmentation(talk)
+    expect(out).toContain("speaker_id: string | null")
+    expect(out).not.toContain("speaker: Record<string, unknown>")
+  })
+
+  it("keeps a required relation non-nullable, matching the engine", () => {
+    expect(generateClientAugmentation(talk)).toContain("room_id: string\n")
+  })
+
+  /** No `foreignKey` annotation, so the column name falls back to the same convention. */
+  it("derives the column name when the AST carries no foreignKey", () => {
+    expect(generateClientAugmentation(talk)).toContain("auth_user_id: string | null")
+  })
+
+  /** The key lives on the other table, so this side has no column to describe. */
+  it("omits hasMany, which is not a column on this table", () => {
+    const out = generateClientAugmentation(talk)
+    expect(out).not.toContain("slots")
+  })
+})
+
+describe("column shapes that disagreed with the database", () => {
+  it("types a localized column as a locale map", () => {
+    // `page.title` is jsonb holding {"en": "...", "fr": "..."} and this said `string`, so
+    // `page.title.toUpperCase()` compiled and then failed in the browser.
+    const row = generateRowType({
+      title: { kind: "text", required: true, localized: true },
+    })
+    expect(row).toContain("title: { [locale: string]: string }")
+  })
+
+  it("leaves a non-localized column of the same kind alone", () => {
+    // The control: a fix that wrapped every text column would pass the assertion above.
+    const row = generateRowType({ slug: { kind: "text", required: true } })
+    expect(row).toContain("slug: string")
+    expect(row).not.toContain("locale")
+  })
+
+  it("types an image as what storage.upload actually produces", () => {
+    // Was `Record<string, unknown>`, which is why the examples cast on the good path.
+    const row = generateRowType({
+      headshot: { kind: "image", required: false, bucket: "speaker-headshots" },
+    })
+    expect(row).toContain("headshot: { bucket: string; path: string } | null")
+  })
+
+  it("types a file the same way", () => {
+    const row = generateRowType({ attachment: { kind: "file", required: true } })
+    expect(row).toContain("attachment: { bucket: string; path: string }")
+  })
+
+  it("does not store a url, because a stored one goes stale", () => {
+    const row = generateRowType({ headshot: { kind: "image", required: true } })
+    expect(row).not.toContain("url")
+  })
+})