@supatype/cli 0.3.0 → 0.3.2

package/src/augmentation-generator.ts

@@ -65,12 +65,58 @@ export function generateClientAugmentation(ast: unknown): string {
   return lines.join("\n")
 }
 
+function toSnakeCase(name: string): string {
+  return name.replace(/([A-Z])/g, "_$1").replace(/^_/, "").toLowerCase()
+}
+
+/**
+ * The column a declared field actually occupies, which is not always the name it was declared under.
+ *
+ * Only `belongsTo` puts a column on this table, and that column is the foreign key: `speaker_id`
+ * holding text, not `speaker` holding the target row. This used to group `relation` with the JSONB
+ * kinds, so the augmentation described a column that does not exist while the engine described the
+ * one that does, and the two generated files disagreed about the same field. `hasMany`, `hasOne` and
+ * `manyToMany` keep their key on the other table, so there is nothing here to describe.
+ */
+function resolveColumn(
+  name: string,
+  meta: Record<string, unknown>,
+): { column: string; ts: string } | null {
+  if (meta["kind"] !== "relation") return { column: name, ts: toTsType(meta) }
+  if (meta["cardinality"] !== "belongsTo") return null
+
+  const annotations = meta["annotations"]
+  const declared =
+    typeof annotations === "object" && annotations !== null
+      ? (annotations as { db?: { foreignKey?: unknown } }).db?.foreignKey
+      : undefined
+  const column =
+    typeof declared === "string" && declared.length > 0 ? declared : `${toSnakeCase(name)}_id`
+
+  // Nullable unless the relation asked for `NOT NULL`, which is the engine's rule. A fix that made
+  // every foreign key non-nullable would be wrong in the other direction just as often.
+  return { column, ts: meta["required"] === true ? "string" : "string | null" }
+}
+
+/** Declared fields as the columns they become, dropping the ones that are not columns here. */
+function columnsOf(
+  fields: Record<string, Record<string, unknown>>,
+): Array<{ column: string; ts: string; meta: Record<string, unknown> }> {
+  return Object.entries(fields)
+    .map(([name, meta]) => {
+      const resolved = resolveColumn(name, meta)
+      return resolved === null ? null : { ...resolved, meta }
+    })
+    .filter((entry): entry is { column: string; ts: string; meta: Record<string, unknown> } =>
+      entry !== null,
+    )
+    .sort((a, b) => a.column.localeCompare(b.column))
+}
+
 export function generateRowType(fields: Record<string, Record<string, unknown>>): string {
-  const entries = Object.entries(fields).sort(([a], [b]) => a.localeCompare(b))
-  if (entries.length === 0) return "Record<string, unknown>"
-  const body = entries
-    .map(([name, meta]) => `  ${quoteKey(name)}: ${toTsType(meta)}`)
-    .join("\n")
+  const columns = columnsOf(fields)
+  if (columns.length === 0) return "Record<string, unknown>"
+  const body = columns.map(({ column, ts }) => `  ${quoteKey(column)}: ${ts}`).join("\n")
   return `{\n${body}\n}`
 }
 
@@ -79,23 +125,21 @@ function insertColumnOptionalOnInsert(meta: Record<string, unknown>): boolean {
 }
 
 export function generateInsertType(fields: Record<string, Record<string, unknown>>): string {
-  const entries = Object.entries(fields).sort(([a], [b]) => a.localeCompare(b))
-  if (entries.length === 0) return "Record<string, unknown>"
-  const body = entries
-    .map(([name, meta]) => {
+  const columns = columnsOf(fields)
+  if (columns.length === 0) return "Record<string, unknown>"
+  const body = columns
+    .map(({ column, ts, meta }) => {
       const required = meta["required"] === true && !insertColumnOptionalOnInsert(meta)
-      return `  ${quoteKey(name)}${required ? "" : "?"}: ${toTsType(meta)}`
+      return `  ${quoteKey(column)}${required ? "" : "?"}: ${ts}`
     })
     .join("\n")
   return `{\n${body}\n}`
 }
 
 export function generateUpdateType(fields: Record<string, Record<string, unknown>>): string {
-  const entries = Object.entries(fields).sort(([a], [b]) => a.localeCompare(b))
-  if (entries.length === 0) return "Record<string, unknown>"
-  const body = entries
-    .map(([name, meta]) => `  ${quoteKey(name)}?: ${toTsType(meta)}`)
-    .join("\n")
+  const columns = columnsOf(fields)
+  if (columns.length === 0) return "Record<string, unknown>"
+  const body = columns.map(({ column, ts }) => `  ${quoteKey(column)}?: ${ts}`).join("\n")
   return `{\n${body}\n}`
 }
 
@@ -119,6 +163,11 @@ function toTsType(meta: Record<string, unknown>): string {
       case "timestamp":
       case "datetime":
       case "money":
+      // NUMERIC, and the exact value is the point. A `number` here is the same defect as parsing
+      // the wire with `JSON.parse`: `12345678901234567890.1234` has no float representation, so a
+      // column declared to hold it would arrive rounded and typed as though it had not been.
+      // `@supatype/types` already says so: `Decimal<P, S>` carries `string`.
+      case "decimal":
       case "xml":
       case "interval":
         return "string"
@@ -126,7 +175,6 @@ function toTsType(meta: Record<string, unknown>): string {
       case "smallInt":
       case "serial":
       case "float":
-      case "decimal":
         return "number"
       case "bigSerial":
       case "bigInt":
@@ -139,9 +187,14 @@ function toTsType(meta: Record<string, unknown>): string {
       case "vector":
       case "relation":
       case "array":
+        return "Record<string, unknown>"
+      // What `storage.upload()` actually produces, plus the bucket it went to. Emitting
+      // `Record<string, unknown>` here is why two example screens cast on the good path. A `url`
+      // is deliberately absent: a stored one goes stale and hard-codes the storage host, so it is
+      // derived at read time instead.
       case "image":
       case "file":
-        return "Record<string, unknown>"
+        return "{ bucket: string; path: string }"
       case "richText":
         return "(import(\"@supatype/types/lexical\").SerializedEditorState | string)"
       case "enum": {
@@ -155,7 +208,11 @@ function toTsType(meta: Record<string, unknown>): string {
         return "unknown"
     }
   })()
-  return required ? base : `${base} | null`
+  // A localized column is JSONB holding a locale map, `{"en": ..., "fr": ...}`, not the bare
+  // value. `page.title` is exactly this and was typed `string`, so calling a string method on it
+  // compiled and then failed against real data.
+  const shaped = meta["localized"] === true ? `{ [locale: string]: ${base} }` : base
+  return required ? shaped : `${shaped} | null`
 }
 
 function quoteKey(key: string): string {

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.3.0"
+export const EMBEDDED_CLI_VERSION: string = "0.3.2"

package/src/client-generator.ts

@@ -0,0 +1,122 @@
+/**
+ * The client a project imports, generated into its own source tree.
+ *
+ * One file, written by `supatype push`, that an app imports once:
+ *
+ *     import { createClient } from "./supatype/client"
+ *
+ * It carries three things that used to arrive by three routes, two of which could fail without
+ * saying so.
+ *
+ * The **module augmentation** was a `.d.ts` that TypeScript found only because the project's
+ * tsconfig `include` happened to name the generated directory. Thirteen tsconfig files across the
+ * examples named it, one project never named it at all, and in that state `AugmentedTables` falls
+ * back to `Record<string, TableDef>`: every table name is accepted, every column is `unknown`, and
+ * the build passes. Reaching it by import instead means tsconfig cannot lose it.
+ *
+ * The **field kinds** were read from `field-kinds.json` on disk, falling back to fetching
+ * PostgREST's OpenAPI document. That fallback reconstructs the answer from the live database, so it
+ * always succeeds, which made a project that had never generated indistinguishable from one that
+ * had. Compiling them in removes both the read and the fallback, and makes absence detectable.
+ *
+ * And **`createClient`** itself, so the one import is the whole setup. A project that has not
+ * generated has no file here to import, so the build fails rather than the app running with a
+ * client that knows nothing about its schema.
+ */
+import { generateClientAugmentation } from "./augmentation-generator.js"
+
+/** The kinds whose values no binary float holds, keyed by the schema kind that produces them. */
+const EXACT_KIND_BY_FIELD_KIND: Readonly<Record<string, "bigint" | "numeric">> = {
+  bigInt: "bigint",
+  bigSerial: "bigint",
+  decimal: "numeric",
+  money: "numeric",
+}
+
+const FORMAT_VERSION = 1
+
+type AstShape = {
+  models?: Array<{
+    name?: string
+    annotations?: Record<string, unknown>
+    fields?: Record<string, Record<string, unknown>>
+  }>
+}
+
+/** The full contents of `supatype/client.ts`. */
+export function generateProjectClient(ast: unknown): string {
+  // Normalised first: `push` should not die on a malformed AST while writing a file, and the
+  // augmentation generator indexes `.models` without checking.
+  const safe = ast !== null && typeof ast === "object" ? ast : { models: [] }
+  const augmentation = generateClientAugmentation(safe)
+
+  return [
+    "// Generated by supatype CLI, do not edit manually.",
+    "//",
+    "// Import the client from here rather than from `@supatype/client`:",
+    "//",
+    '//     import { createClient } from "./supatype/client"',
+    "//",
+    "// This file carries your schema's types and the columns that need exact handling, so one",
+    "// import is the whole setup. Importing `@supatype/client` directly gets a client that knows",
+    "// nothing about this project.",
+    "",
+    'import { registerFieldKinds } from "@supatype/client"',
+    "",
+    augmentationBody(augmentation),
+    "",
+    "// Columns holding values a JSON parser would round: bigInt, decimal and money. Registered at",
+    "// import time, so reading one returns what the database holds rather than the nearest double.",
+    `registerFieldKinds(${JSON.stringify(fieldKindsDocument(safe), null, 2)})`,
+    "",
+    'export * from "@supatype/client"',
+    "",
+  ].join("\n")
+}
+
+/**
+ * The augmentation, without the pieces that only made sense in a file of its own.
+ *
+ * Its header said "generated", which this file says once already, and it ended in `export {}` to
+ * make itself a module. This file has imports and exports of its own, so it is one regardless.
+ */
+function augmentationBody(augmentation: string): string {
+  return augmentation
+    .replace(/^\/\/ Generated by supatype CLI[^\n]*\n+/, "")
+    .replace(/\n*export \{\}\s*$/, "")
+    .trimEnd()
+}
+
+/** The exact-value columns of every table, as the registry expects them. */
+function fieldKindsDocument(ast: unknown): { version: number; tables: Record<string, unknown> } {
+  const tables: Record<string, Record<string, string>> = {}
+
+  for (const model of readModels(ast)) {
+    const exact: Record<string, string> = {}
+    for (const [column, meta] of Object.entries(model.fields ?? {})) {
+      const kind = typeof meta["kind"] === "string" ? meta["kind"] : ""
+      const exactKind = EXACT_KIND_BY_FIELD_KIND[kind]
+      if (exactKind !== undefined) exact[column] = exactKind
+    }
+    if (Object.keys(exact).length > 0) {
+      tables[resolveTableName(model)] = exact
+    }
+  }
+
+  return { version: FORMAT_VERSION, tables }
+}
+
+function resolveTableName(model: { name?: string; annotations?: Record<string, unknown> }): string {
+  const db = model.annotations?.["db"]
+  if (db !== null && typeof db === "object") {
+    const named = (db as { tableName?: unknown }).tableName
+    if (typeof named === "string" && named !== "") return named
+  }
+  return model.name ?? ""
+}
+
+function readModels(ast: unknown): NonNullable<AstShape["models"]> {
+  if (ast === null || typeof ast !== "object") return []
+  const models = (ast as AstShape).models
+  return Array.isArray(models) ? models : []
+}

package/src/commands/admin.ts

@@ -363,12 +363,7 @@ export async function ensureFirstAdminWithQuery(
 
   const credentials = await resolveAdminCredentials(options, cwd)
   if (!credentials) {
-    if (!isInteractive()) {
-      info(
-        "No admin users found. Set SUPATYPE_ADMIN_EMAIL / SUPATYPE_ADMIN_PASSWORD in .env, " +
-          "or run: supatype admin create-user",
-      )
-    }
+    if (!isInteractive()) info(missingAdminCredentialsHint(cwd, options))
     return
   }
 
@@ -397,6 +392,28 @@ function logFirstAdminCreated(email: string, role: string): void {
   info("Log in at /admin after starting the dev server.")
 }
 
+/**
+ * What to say when there is no admin and no credentials to make one with.
+ *
+ * Naming both variables is wrong in the common case. `clearAdminSeedPassword` retires the seed
+ * password once it has been used, so a project that has ever created an admin keeps the email and
+ * has no password, and a later run against a reset database then reports both as missing. That
+ * reads as "you never set these" when in fact this tool consumed one of them, which is a dead end
+ * for anyone who knows they set it.
+ */
+function missingAdminCredentialsHint(cwd: string, options: EnsureFirstAdminOptions): string {
+  const email = options.email ?? readEnvValue(cwd, ADMIN_EMAIL_ENV, "").trim()
+  const create = "or run: supatype admin create-user"
+  if (!email) {
+    return `No admin users found. Set ${ADMIN_EMAIL_ENV} / ${ADMIN_PASSWORD_ENV} in .env, ${create}`
+  }
+  return (
+    `No admin users found. .env has ${ADMIN_EMAIL_ENV}="${email}" but no ${ADMIN_PASSWORD_ENV}: ` +
+    `it is a one-time seed and is removed once an admin has been created. ` +
+    `Set ${ADMIN_PASSWORD_ENV} again to seed one, ${create}`
+  )
+}
+
 async function resolveAdminCredentials(
   options: EnsureFirstAdminOptions,
   cwd: string,

package/src/commands/functions.ts

@@ -25,7 +25,10 @@ import {
 import { loadProjectLink } from "../link.js"
 import { resolveTarget } from "../resolve-target.js"
 import { targetFetch } from "../target-client.js"
-import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
+import {
+  ensureFunctionsDenoTypes,
+  sharedFunctionsReadmeSource,
+} from "../functions-deno-types.js"
 import { error, info, plain } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 
@@ -173,7 +176,7 @@ export default async function handler(req: Request, ctx: FunctionContext): Promi
     mkdirSync(sharedDir, { recursive: true })
     writeFileSync(
       join(sharedDir, "README.md"),
-      "# Shared Code\n\nFiles in `_shared/` are available to all functions via relative imports.\nThis directory is not deployed as a function.\n\nExample: `import { sendEmail } from '../_shared/email.ts'`\n",
+      sharedFunctionsReadmeSource(),
       "utf8",
     )
   }

package/src/commands/init.ts

@@ -14,7 +14,10 @@ import {
   ensureComponentBinaries,
   reportComponentBinaryFailures,
 } from "../ensure-component-binaries.js"
-import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
+import {
+  ensureFunctionsDenoTypes,
+  sharedFunctionsReadmeSource,
+} from "../functions-deno-types.js"
 import { mergeSupatypePackageJson } from "../init-package-json.js"
 import { cliPackageVersion } from "../cli-package-version.js"
 import {
@@ -23,6 +26,7 @@ import {
   type InitDependencyVersions,
 } from "../init-dependency-versions.js"
 import { detectProjectSetup, type DetectedProjectSetup } from "../init-project-detect.js"
+import { SUPATYPE_GITIGNORE_PATHS } from "../gitignore.js"
 
 // ─── Options model ─────────────────────────────────────────────────────────--
 
@@ -789,7 +793,7 @@ function scaffoldHelloFunction(
 ): void {
   write("functions/hello/index.ts", helloFunctionTemplate())
   if (!existsSync(join(dir, "functions/_shared/README.md"))) {
-    write("functions/_shared/README.md", sharedFunctionsReadme())
+    write("functions/_shared/README.md", sharedFunctionsReadmeSource())
   }
   if (!existsSync(join(dir, "functions/.env.local"))) {
     write("functions/.env.local", functionsEnvLocalTemplate())
@@ -1396,22 +1400,18 @@ export default async function handler(req: Request, ctx: FunctionContext): Promi
 `
 }
 
-function sharedFunctionsReadme(): string {
-  return "# Shared Code\n\nFiles in `_shared/` are available to all functions via relative imports.\nThis directory is not deployed as a function.\n\nExample: `import { sendEmail } from '../_shared/email.ts'`\n"
-}
 
 function functionsEnvLocalTemplate(): string {
   return "# Local environment variables for edge functions\n# These are NOT committed to git\n# Set production env vars via: npx supatype functions env set KEY=value\n"
 }
 
 function gitignoreTemplate(): string {
-  return `.env
+  // Supatype's own paths come from `SUPATYPE_GITIGNORE_PATHS` rather than being written out again
+  // here. This template and that list were two copies of the same thing and had already diverged;
+  // the copy that drifts is found when a key reaches a public repository.
+  return `${SUPATYPE_GITIGNORE_PATHS.join("\n")}
 node_modules/
 dist/
-.supatype/
-supatype.local.config.ts
-supatype.local.config.js
-supatype.local.config.mjs
 # Generated by supatype push (legacy paths, prefer output.types in config)
 src/types/supatype.d.ts
 src/lib/supatype.ts

package/src/commands/keys.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander"
-import { readFileSync, existsSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
+import { readEnvFile, upsertEnvFile } from "../env-file.js"
 import { signJwt } from "../jwt.js"
 import { error, plain } from "../ui/messages.js"
 
@@ -10,7 +11,9 @@ export function registerKeys(program: Command): void {
     .description("Generate ANON_KEY and SERVICE_ROLE_KEY JWTs from your JWT_SECRET")
     .option("--secret <secret>", "JWT secret (defaults to JWT_SECRET env var or value in .env)")
     .option("--exp-years <years>", "Token expiry in years (default: 10)", "10")
-    .action((opts: { secret?: string; expYears: string }) => {
+    .option("--write", "Write the keys into .env in the current directory instead of printing them")
+    .option("--force", "With --write, replace every key already in .env rather than filling blanks")
+    .action((opts: { secret?: string; expYears: string; write?: boolean; force?: boolean }) => {
       const secret = opts.secret ?? resolveSecret()
       if (!secret) {
         error("JWT_SECRET not found. Set it in .env or pass --secret <value>")
@@ -23,19 +26,116 @@ export function registerKeys(program: Command): void {
         process.exit(1)
       }
 
-      const now = Math.floor(Date.now() / 1000)
-      const exp = now + expYears * 365 * 24 * 60 * 60
+      const { anonKey, serviceKey } = signKeyPair(secret, expYears)
 
-      const anonKey = signJwt({ iss: "supatype", role: "anon", iat: now, exp }, secret)
-      const serviceKey = signJwt({ iss: "supatype", role: "service_role", iat: now, exp }, secret)
+      if (opts.write) {
+        const written = writeKeysToEnv(
+          process.cwd(),
+          { anonKey, serviceKey },
+          opts.force === true,
+        )
+        if (written.path === null) {
+          error("No .env here to write to. Create one, or drop --write to print the keys.")
+          process.exit(1)
+        }
+        plain(`\nKeys valid for ${expYears} years, written to ${written.path}:\n`)
+        // The names come back from the writer rather than being restated here, which is the whole
+        // point of there being one list.
+        for (const key of written.written) plain(`  ${key}`)
+        if (written.kept.length > 0) {
+          plain(`\nLeft alone, because they already hold a value:\n`)
+          for (const key of written.kept) plain(`  ${key}`)
+          plain("\nRe-run with --force to replace them.")
+        }
+        plain("\nDo not commit .env to source control.")
+        return
+      }
 
       plain(`\nGenerated keys (valid for ${expYears} years):\n`)
       plain("ANON_KEY=" + anonKey)
       plain("SERVICE_ROLE_KEY=" + serviceKey)
-      plain("\nAdd these to your .env file. Do not commit .env to source control.")
+      plain("\nAdd these to your .env file, or re-run with --write. Do not commit .env to source control.")
     })
 }
 
+/**
+ * Every env name a minted key pair is written to, in one place.
+ *
+ * Shared with `supatype dev`, which writes the same pair when it starts a stack. They used to hold
+ * separate lists, so a front end's prefix could be written by one and forgotten by the other, and
+ * which names your `.env` ended up with depended on whichever command you happened to run last.
+ *
+ * The URL names are only included when there is a URL to write, because 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.
+ */
+export function anonKeyEnvUpdates(
+  anonKey: string,
+  serviceKey: string,
+  apiUrl?: string | undefined,
+): Record<string, string> {
+  return {
+    ANON_KEY: anonKey,
+    SERVICE_ROLE_KEY: serviceKey,
+    VITE_SUPATYPE_ANON_KEY: anonKey,
+    PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
+    ...(apiUrl !== undefined && {
+      VITE_SUPATYPE_URL: apiUrl,
+      PUBLIC_SUPATYPE_URL: apiUrl,
+      EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
+    }),
+  }
+}
+
+export interface WriteKeysResult {
+  /** The .env written, or null when there is none here. */
+  path: string | null
+  written: string[]
+  kept: string[]
+}
+
+/**
+ * Write a minted pair into `dir`'s .env.
+ *
+ * Blanks only by default. An anon key already in `.env` is held by clients this command cannot
+ * reach, and reissuing it locks them out, so filling what is empty is the useful half and
+ * replacing what is not is a decision someone has to make out loud. `--force` is how they make it,
+ * and it rewrites every name this owns rather than only the empty ones.
+ *
+ * `--force` does not rewrite the file. `.env` also holds `JWT_SECRET`, which these keys are
+ * derived from, along with 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. Every line this command does not own is left exactly as it was, comments included.
+ */
+export function writeKeysToEnv(
+  dir: string,
+  keys: { anonKey: string; serviceKey: string },
+  force: boolean,
+): WriteKeysResult {
+  const envPath = resolve(dir, ".env")
+  if (!existsSync(envPath)) return { path: null, written: [], kept: [] }
+
+  const existing = readEnvFile(dir)
+  const apiUrl = existing["PUBLIC_SUPATYPE_URL"] || existing["API_EXTERNAL_URL"] || undefined
+  const candidates = anonKeyEnvUpdates(keys.anonKey, keys.serviceKey, apiUrl)
+
+  const updates: Record<string, string> = {}
+  const kept: string[] = []
+  for (const [name, value] of Object.entries(candidates)) {
+    // Blank counts as absent: a template ships `ANON_KEY=` and that is exactly the line to fill.
+    const current = existing[name]?.trim() ?? ""
+    if (!force && current !== "") {
+      kept.push(name)
+      continue
+    }
+    updates[name] = value
+  }
+
+  if (Object.keys(updates).length > 0) upsertEnvFile(dir, updates)
+  return { path: envPath, written: Object.keys(updates), kept }
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /** Mint a long-lived anon + service_role JWT pair from a secret. */
@@ -91,6 +191,11 @@ function upsertEnvVar(content: string, key: string, value: string): string {
   return `${content}${sep}${key}=${value}\n`
 }
 
+/** Whether `.env` declares `key` at all, with or without a value. */
+function hasEnvLine(content: string, key: string): boolean {
+  return new RegExp(`^${key}=`, "m").test(content)
+}
+
 function readEnvVar(content: string, key: string): string | undefined {
   const re = new RegExp(`^${key}=(.*)$`, "m")
   const match = re.exec(content)

package/src/commands/push.ts

@@ -9,6 +9,7 @@ import {
   validateModelValidators,
   writeHooksModule,
 } from "../model-hooks.js"
+import { syncRowCacheEnv } from "../model-cache.js"
 import { adapterEntry, readHookUpload } from "../hook-upload.js"
 import { checkServiceRoleRoutes, serviceRoleProblemLines } from "../service-role-check.js"
 import { fatalError } from "../ui/fatal.js"
@@ -32,7 +33,8 @@ import type { ExtractedSchemaAstV2 } from "../schema-ast-v2.js"
 import { ensureFirstAdminUser } from "./admin.js"
 import { withAdminRoles } from "../studio-admin-roles.js"
 import { restoreSystemRelationTargets } from "../restore-system-relation-targets.js"
-import { freeTierCacheNote, seedApiConfigCache } from "../api-config-cache.js"
+import { cacheSeedingNotes, freeTierCacheNote } from "../api-config-cache.js"
+import { refreshFunctionsContext } from "../functions-context-refresh.js"
 import type { SupatypeProjectConfig } from "../project-config.js"
 import {
   resolveTarget,
@@ -264,20 +266,7 @@ async function deployHooksToTarget(
  * Never an error, and never a rewrite of an entry that already exists. See `seedApiConfigCache`.
  */
 function reportCacheSeeding(cwd: string, ast: unknown): void {
-  const result = seedApiConfigCache(cwd, ast)
-  if (result === null) return
-
-  if (result.seeded.length > 0) {
-    info(`Server cache enabled for ${result.seeded.join(", ")} in .supatype/api-config.json`)
-  }
-  if (result.ttlIsOff) {
-    // A note rather than a fix. Zero is an off switch someone may have chosen, and a push that
-    // turned caching on project-wide would be overriding a decision rather than filling in a blank.
-    info(
-      `${result.declared.length} table(s) declare a cache, but cache_max_ttl is 0 — nothing is ` +
-        `cached until it is set, under API → REST → Settings or in .supatype/api-config.json.`,
-    )
-  }
+  for (const note of cacheSeedingNotes(cwd, ast)) info(note)
 }
 
 /** The generated adapter, flattened to the name handlers were rewritten to import. */
@@ -293,8 +282,29 @@ async function generateTypesLocal(ast: unknown, config: SupatypeProjectConfig):
   const cwd = process.cwd()
   const hooksPath = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
   if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
+
+  // `_shared/context.ts` too, for the same reason the hook module is here.
+  //
+  // It was written by `init` and `functions new` and by nothing else, so a project that predates
+  // the two-argument handler contract never received it: its functions had no `FunctionContext` to
+  // import, while the file itself claims "Regenerated by the CLI. Edits are overwritten." That
+  // claim was only true if you scaffolded again. `tests/integration` had four functions and no
+  // context module at all.
+  if (refreshFunctionsContext(cwd, config)) {
+    info("Function context type written to functions/_shared/context.ts")
+  }
   // The server watches this file, so a changed hook takes effect without a restart.
   if (syncManifestHooks(cwd, ast)) info("Hook map written to .supatype/manifest.json")
+  // The row cache is configured at postmaster start, so this is the one cache setting a push
+  // cannot make take effect on its own.
+  const rowCache = syncRowCacheEnv(cwd, ast)
+  if (rowCache !== null) {
+    info(
+      `Row cache switched ${rowCache} in .env. Recreate the database container for it to take ` +
+        "effect: the image writes pg_keyspace.conf at start, so a running Postgres keeps the " +
+        "setting it booted with.",
+    )
+  }
 
   if (!config.output?.types && !config.output?.client) return
   // The CLI writes these, it does not ask the engine to. Passing types_path and client_path and

package/src/commands/update.ts

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