@supatype/cli 0.3.1 → 0.3.3

package/src/dev-compose.ts

@@ -2,6 +2,7 @@
  * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
+import { writeAstDerivedOutputs } from "./type-generation.js"
 import { withPublishing } from "./model-versioning.js"
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
@@ -29,6 +30,10 @@ import { handleComposeProjectRename } from "./compose-rename.js"
 import { recoverStaleDevSession, writeDevSessionLock } from "./dev-session-lock.js"
 import { endDevSession, startDevSession } from "./dev-session.js"
 import { ensureDevApiConfig } from "./ensure-dev-api-config.js"
+import { cacheSeedingNotes } from "./api-config-cache.js"
+import { refreshFunctionsContext } from "./functions-context-refresh.js"
+import { DB_PORT_ENV, syncDatabaseUrlPort } from "./db-port.js"
+import { degraded } from "./strict.js"
 import {
   COMPOSE_PINNED_IMAGE_ENV_KEYS,
   composeDockerImageEnv,
@@ -374,7 +379,16 @@ async function waitComposeHealthy(paths: SelfHostComposePaths, cwd: string, maxM
   while (Date.now() < deadline) {
     const ready = spawnSync(
       "docker",
-      [...baseArgs, "exec", "-T", "db", "pg_isready", "-U", "supatype_admin"],
+      // Over TCP, deliberately, not the Unix socket.
+      //
+      // On a first run the Postgres entrypoint starts a temporary server with `listen_addresses=''`
+      // to run the init scripts, then shuts it down and starts the real one. That temporary server
+      // answers on the socket, so a socket `pg_isready` reports ready during init and the very next
+      // thing to connect meets "the database system is shutting down". It is why the initial push
+      // failed three times in a row on a clean machine while a warm one was fine.
+      //
+      // TCP is the distinction the entrypoint itself draws: the init server does not listen on it.
+      [...baseArgs, "exec", "-T", "db", "pg_isready", "-h", "127.0.0.1", "-U", "supatype_admin"],
       { cwd: composeDir, encoding: "utf8" },
     )
     if (ready.status === 0) return
@@ -594,6 +608,12 @@ async function refreshSchemaArtifacts(
   // validator silently not firing means a write the schema says is checked is accepted with a 201.
   const hooksModule = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
   if (hooksModule !== null) console.log(`[supatype] Hook handler types written to ${hooksModule}`)
+  // And the context module, on the same terms. `init` and `functions new` wrote it and nothing
+  // else did, so a project that already had functions when the two-argument contract landed never
+  // received one: its handlers had no `FunctionContext` to import.
+  if (refreshFunctionsContext(cwd, config)) {
+    console.log("[supatype] Function context type written to functions/_shared/context.ts")
+  }
   if (syncManifestHooks(cwd, ast)) {
     console.log("[supatype] Hook and validator maps written to .supatype/manifest.json")
   }
@@ -604,6 +624,24 @@ async function refreshSchemaArtifacts(
     console.log(`[supatype] Row cache switched ${rowCache} in .env (pg_keyspace Mode B).`)
   }
 
+  // SUPATYPE_DB_PORT moves what compose binds; DATABASE_URL is what seeds and psql use. Nothing
+  // reconciled them, so a project moved off 5432 to avoid a clash came up perfectly and then
+  // failed on `npm run seed` with ECONNREFUSED against a port nothing was listening on.
+  const dbPort = syncDatabaseUrlPort(cwd)
+  if (dbPort !== null) {
+    console.log(
+      `[supatype] DATABASE_URL port ${dbPort.from} -> ${dbPort.to} in .env, ` +
+        `to match ${DB_PORT_ENV}.`,
+    )
+  }
+
+  // The declaration is a ceiling and the allowlist is what is actually on, and only `push` ever
+  // seeded the allowlist. So a stack brought up with `supatype dev` alone had every model's
+  // `cache` block declared and nothing switched on: `.cache({ server: true })` answered BYPASS,
+  // and the only way to find out why was to open Studio and tick a box the schema had already
+  // justified.
+  for (const note of cacheSeedingNotes(cwd, ast)) console.log(`[supatype] ${note}`)
+
   try {
     await ensureEngine()
   } catch (err) {
@@ -622,15 +660,19 @@ async function refreshSchemaArtifacts(
       adminConfigPath,
     ).catch(() => false)
     if (wrote) {
-      console.warn(
-        `[supatype] Host engine unavailable (${(err as Error).message}); used the in-compose ` +
-          "engine instead.",
+      // Reported through `degraded` rather than warned: the in-compose engine writes the admin
+      // config but never reaches the type generation below, so a run that takes this path has
+      // stale generated types and says so only in a line that scrolls past. In CI that is the
+      // difference between testing the host engine path and never touching it.
+      degraded(
+        "Host engine unavailable, used the in-compose engine instead",
+        (err as Error).message,
       )
       return
     }
-    console.warn(
-      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}
-` +
+    degraded(
+      "Host engine unavailable, admin config and types not refreshed",
+      `${(err as Error).message}\n` +
         "[supatype] Studio will report no schema until this succeeds, even though the schema is " +
         "applied. Retry with the stack up, or run `supatype push`.",
     )
@@ -660,6 +702,23 @@ async function refreshSchemaArtifacts(
     }
   }
 
+  // Needs no engine, so it is written whether or not the types step above ran or succeeded. This
+  // is what `dev` never did: a project developed entirely through `supatype dev` received neither
+  // `index.d.ts`, which is what makes `createClient` typed without a generic, nor the field kinds
+  // the client reads to keep bigInt, decimal and money columns exact.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message}`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
   try {
     const admin = withAdminRoles(await engineRequest<unknown>("/admin", { ast }), config)
     restoreSystemRelationTargets(admin, ast)
@@ -952,7 +1011,16 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     throw new Error(detail || `Engine schema diff failed (exit ${result.status})`)
   }
   if (!result.diff) {
-    throw new Error("Engine diff returned no result")
+    // The engine exited 0 and produced nothing this could parse, which is a different failure from
+    // the engine exiting non-zero and is the harder one to act on. "Engine diff returned no result"
+    // named only the symptom, and running the same compose command by hand gave a clear error in
+    // one go, so the message was the only thing standing between the reader and the answer.
+    const output = (filterComposeNoise(result.output) || result.output || "").trim()
+    throw new Error(
+      output === ""
+        ? "The schema engine exited 0 and printed nothing. Run `supatype self-host compose run --rm schema-engine diff` to see what it does."
+        : `The schema engine exited 0 but its output could not be parsed as a diff:\n${output}`,
+    )
   }
   return result.diff
 }
@@ -1159,19 +1227,26 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     }
   }
 
-  const pinnedRealtimeImage = readEnvValue(cwd, "SUPATYPE_REALTIME_IMAGE", "").trim()
-  if (pinnedRealtimeImage !== "") {
-    console.log("[supatype] Recreating realtime with pinned image...")
-    const rtStatus = runDockerCompose(
+  // A service whose image is pinned in `.env` is recreated once the stack is up, so a contributor
+  // can point at a build from this checkout rather than the published tag.
+  //
+  // Storage was missing from this list, which is why a storage bug survived: there was no way to
+  // run the suite against a local storage build, so every integration run tested the last release
+  // no matter what the working tree said.
+  for (const service of ["realtime", "storage"] as const) {
+    const variable = `SUPATYPE_${service.toUpperCase()}_IMAGE`
+    if (readEnvValue(cwd, variable, "").trim() === "") continue
+    console.log(`[supatype] Recreating ${service} with pinned image...`)
+    const status = runDockerCompose(
       paths.composePath,
-      ["up", "-d", "--force-recreate", "--no-deps", "realtime"],
+      ["up", "-d", "--force-recreate", "--no-deps", service],
       cwd,
       project,
       { quiet: true, brand: devBrand },
     )
-    if (rtStatus !== 0) {
+    if (status !== 0) {
       endDevSession()
-      exitComposeFailed(rtStatus, "Could not recreate the realtime container.", devBrand)
+      exitComposeFailed(status, `Could not recreate the ${service} container.`, devBrand)
     }
   }
 
@@ -1339,8 +1414,17 @@ function reconcileAuthenticatorPassword(
     },
   )
   if (result.status !== 0) {
+    // The cause, not just the consequence. This warned that REST "may answer 502" and said nothing
+    // about why, so when the supabucks e2e then failed its only API assertion with a 502, the
+    // warning twenty lines earlier read as unrelated noise. A message that predicts a failure and
+    // withholds its reason costs more than one that says nothing.
+    const detail = [result.stderr, result.error?.message]
+      .map((s) => (s ?? "").trim())
+      .filter((s) => s.length > 0)
+      .join("\n")
     console.warn(
-      "[supatype] Could not set the authenticator password; the REST API may answer 502.",
+      `[supatype] Could not set the authenticator password, so the REST API will answer 502.\n` +
+        (detail === "" ? "[supatype] docker gave no output." : detail),
     )
   }
 }
@@ -1447,6 +1531,22 @@ export async function generateViaComposeEngine(
     }
   }
 
+  // The same AST-derived files as the host path. This is the fallback used when the host engine
+  // could not be fetched, and these need no engine at all, so there is no reason for a project on
+  // this path to end up with fewer generated files than one on the other.
+  try {
+    for (const message of writeAstDerivedOutputs({
+      cwd,
+      ast,
+      ...(config.output?.types !== undefined && { typesPath: config.output.types }),
+      ...(config.output?.client !== undefined && { clientPath: config.output.client }),
+    })) {
+      console.log(`[supatype] ${message} (in-compose engine).`)
+    }
+  } catch (err) {
+    console.warn(`[supatype] Generated output failed: ${(err as Error).message}`)
+  }
+
   const adminOut = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["admin"])
   if (!adminOut) return false
   const parsed = parseEngineJsonOutput<unknown>(adminOut)

package/src/engine-client.ts

@@ -149,6 +149,7 @@ export async function engineHealth(): Promise<boolean> {
  *   /introspect  → engine introspect
  *   /validate    → engine validate
  *   /admin       → engine admin (admin-config JSON on stdout)
+ *   /seed        → engine seed (result document JSON on stdout)
  */
 export async function engineRequest<T = unknown>(
   endpoint: string,
@@ -171,6 +172,19 @@ export async function engineRequest<T = unknown>(
     writeFileSync(gzPath, Buffer.from(body["schema_sources_gz_base64"], "base64"))
     cleanup.push(gzPath)
   }
+  // One file per seed document. The engine takes `--ir` once per document rather than one
+  // combined blob, so a failure can name the file it was in.
+  const irPaths: string[] = []
+  const documents = body["ir_documents"]
+  if (Array.isArray(documents)) {
+    documents.forEach((document, index) => {
+      const irPath = join(tmpDir, `ir-${Date.now()}-${index}.json`)
+      writeFileSync(irPath, typeof document === "string" ? document : JSON.stringify(document))
+      cleanup.push(irPath)
+      irPaths.push(irPath)
+    })
+  }
+
   if (body["schema_sources_manifest"] !== undefined) {
     manifestPath = join(tmpDir, `manifest-${Date.now()}.json`)
     writeFileSync(manifestPath, JSON.stringify(body["schema_sources_manifest"]))
@@ -180,6 +194,7 @@ export async function engineRequest<T = unknown>(
   const args = endpointToArgs(endpoint, body, reqFile, {
     ...(gzPath !== undefined ? { gzPath } : {}),
     ...(manifestPath !== undefined ? { manifestPath } : {}),
+    ...(irPaths.length > 0 ? { irPaths } : {}),
   })
 
   const result = spawnSync(bin, args, {
@@ -191,7 +206,16 @@ export async function engineRequest<T = unknown>(
     try { unlinkSync(f) } catch { /* ignore */ }
   }
 
-  if (result.status !== 0) {
+  // A failed seed is an answer, not a crash.
+  //
+  // `engine seed` exits 1 when the seed itself failed and prints the result document on
+  // stdout: which file, what it wrote before it stopped, and the error in the schema's own
+  // terms. Treating a non-zero exit as "no output" threw all of that away and reported
+  // `Engine /seed failed (exit 1): (no output)`, which is worse than the raw Postgres error
+  // it replaced. Anything without a document to read still throws.
+  const reportsFailureAsData = endpoint === "/seed" && (result.stdout?.trim().length ?? 0) > 0
+
+  if (result.status !== 0 && !reportsFailureAsData) {
     const stderr = result.stderr?.trim() || "(no output)"
     throw new EngineError(
       `Engine ${endpoint} failed (exit ${result.status}): ${stderr}`,
@@ -221,7 +245,7 @@ function endpointToArgs(
   endpoint: string,
   body: Record<string, unknown>,
   reqFile: string,
-  sources?: { gzPath?: string; manifestPath?: string },
+  sources?: { gzPath?: string; manifestPath?: string; irPaths?: string[] },
 ): string[] {
   const dbUrl = (body["database_url"] as string | undefined) ?? ""
   const schema = (body["schema"] as string | undefined) ?? "public"
@@ -259,7 +283,32 @@ function endpointToArgs(
 
     case "/generate": {
       const lang = (body["lang"] as string | undefined) ?? "typescript"
-      return ["generate", "--input", reqFile, "--lang", lang]
+      const artifact = (body["artifact"] as string | undefined) ?? "types"
+      return ["generate", "--input", reqFile, "--lang", lang, "--artifact", artifact]
+    }
+
+    case "/seed": {
+      // `--status` reads the ledger and needs no schema, so it does not take `--input`:
+      // passing one would make the command fail on a project whose schema has moved on.
+      if (body["status"] === true) {
+        return ["seed", "--database-url", dbUrl, "--status"]
+      }
+      const documents = (sources?.irPaths ?? []).flatMap((path) => ["--ir", path])
+      const environment =
+        typeof body["environment"] === "string" ? ["--environment", body["environment"]] : []
+      return [
+        "seed",
+        "--input",
+        reqFile,
+        ...documents,
+        "--database-url",
+        dbUrl,
+        "--schema",
+        schema,
+        ...environment,
+        ...(body["atomic"] === true ? ["--atomic"] : []),
+        ...(body["run_once"] === true ? ["--run-once"] : []),
+      ]
     }
 
     case "/introspect":

package/src/engine-floor.ts

@@ -36,6 +36,27 @@ export const ENGINE_MIN_FOR_BOUNDS = "0.2.0"
  */
 export const ENGINE_MIN_FOR_VERSIONS = "0.3.0"
 
+/**
+ * First engine release that normalises a rich text column's contents (schema-engine v0.4.0).
+ *
+ * Silent in the same way `versions` is, and for a reason worth naming. The generated types accept
+ * a plain string on the way in and promise a Lexical document on the way out, and a trigger is
+ * what makes the second half true for every writer. An older engine emits no trigger and rejects
+ * nothing, so the string is stored exactly as it was written and every later read returns
+ * something the types say cannot happen.
+ */
+export const ENGINE_MIN_FOR_RICHTEXT_TRIGGER = "0.4.0"
+
+/**
+ * First engine release that has a `seed` subcommand (schema-engine v0.4.0).
+ *
+ * Unconditional, where everything else in this file is conditional on the schema. There is no way
+ * to write a seed that does not need the subcommand, so there is nothing to read the project for
+ * and nothing to point at. An older engine answers the request with a usage error about an
+ * unrecognised argument, which names no part of the project and reads like a broken install.
+ */
+export const ENGINE_MIN_FOR_SEED = "0.4.0"
+
 /**
  * Compare two dotted versions numerically. Returns <0, 0 or >0.
  *
@@ -89,6 +110,17 @@ export function boundsRequiringHelpers(ast: ExtractedSchemaAstV2): string[] {
   return [...fieldsWithBounds(ast.models), ...modelsWithConstraints(ast.models)]
 }
 
+/** Rich text fields, which need a trigger only a new enough engine emits. */
+export function fieldsNeedingRichTextTrigger(ast: ExtractedSchemaAstV2): string[] {
+  const found: string[] = []
+  for (const model of ast.models) {
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      if (field.kind === "richText") found.push(`${model.name}.${fieldName}`)
+    }
+  }
+  return found
+}
+
 /** Models declaring `versions`, which needs a whole layer only a new enough engine emits. */
 export function modelsRequiringVersions(ast: ExtractedSchemaAstV2): string[] {
   return ast.models
@@ -134,6 +166,17 @@ const ENGINE_REQUIREMENTS: EngineRequirement[] = [
       `push reports success and you get a model with no history, no drafts and an editor that ` +
       `saves into nothing. That silence is the reason this refuses.`,
   },
+  {
+    since: ENGINE_MIN_FOR_RICHTEXT_TRIGGER,
+    declaredBy: fieldsNeedingRichTextTrigger,
+    feature: "rich text columns",
+    consequence:
+      `Only engine ${ENGINE_MIN_FOR_RICHTEXT_TRIGGER}+ emits the trigger that turns a plain ` +
+      `string written into one of these columns into a Lexical document. The generated types ` +
+      `accept a string on the way in and promise a document on the way out, and the trigger is ` +
+      `the only thing that makes the second half true. Without it the string is stored as it ` +
+      `was written and a later read returns what the types say is impossible.`,
+  },
 ]
 
 /**
@@ -142,13 +185,37 @@ const ENGINE_REQUIREMENTS: EngineRequirement[] = [
  * Takes the pin from `versions.engine`, or undefined when unpinned. See the note above on why
  * that is the right source rather than the binary's own `--version`.
  */
+/**
+ * Whether a pin can be compared at all.
+ *
+ * Unpinned resolves to latest, and `local` points at a build whose version the config does not
+ * know. Neither can be compared, and neither is the case that breaks.
+ */
+function comparable(pin: string | undefined): pin is string {
+  return pin !== undefined && pin !== "local"
+}
+
+/**
+ * The parts every refusal here shares: what is needed, and what to do about it.
+ *
+ * One builder rather than one per check, because the remedy is the only part of this message
+ * anyone acts on, and a second copy is a second place for it to go stale.
+ */
+function refusal(parts: { needs: string; since: string; pinned: string; body: string }): string {
+  return (
+    `${parts.needs}, which needs schema-engine ${parts.since} or newer, and this project ` +
+    `pins ${parts.pinned}.\n\n` +
+    `${parts.body}\n\n` +
+    `Raise or remove the pin in supatype.config.ts:\n` +
+    `  versions: { engine: "${parts.since}" }   // or omit it to track latest`
+  )
+}
+
 export function assertEngineSupportsSchema(
   ast: ExtractedSchemaAstV2,
   pinnedEngineVersion: string | undefined,
 ): void {
-  // Unpinned resolves to latest, and `local` points at a build whose version the config does not
-  // know. Neither can be compared, and neither is the case that breaks.
-  if (pinnedEngineVersion === undefined || pinnedEngineVersion === "local") return
+  if (!comparable(pinnedEngineVersion)) return
 
   for (const requirement of ENGINE_REQUIREMENTS) {
     if (compareVersions(pinnedEngineVersion, requirement.since) >= 0) continue
@@ -159,12 +226,36 @@ export function assertEngineSupportsSchema(
     const shown = needed.slice(0, 3).join(", ")
     const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
     throw new Error(
-      `This schema declares ${requirement.feature}, which needs schema-engine ` +
-        `${requirement.since} or newer, and this project pins ${pinnedEngineVersion}.\n\n` +
-        `  Declared on: ${shown}${more}\n\n` +
-        `${requirement.consequence}\n\n` +
-        `Raise or remove the pin in supatype.config.ts:\n` +
-        `  versions: { engine: "${requirement.since}" }   // or omit it to track latest`,
+      refusal({
+        needs: `This schema declares ${requirement.feature}`,
+        since: requirement.since,
+        pinned: pinnedEngineVersion,
+        body: `  Declared on: ${shown}${more}\n\n${requirement.consequence}`,
+      }),
     )
   }
 }
+
+/**
+ * Why the pinned engine cannot run a seed, or undefined when it can.
+ *
+ * Returns rather than throws, because the seed command answers in exit codes and this is a `2`:
+ * the run could not start, alongside a missing builder or an unreachable database, rather than a
+ * `1` where the seed itself was wrong.
+ */
+export function seedUnsupportedByPinnedEngine(
+  pinnedEngineVersion: string | undefined,
+): string | undefined {
+  if (!comparable(pinnedEngineVersion)) return undefined
+  if (compareVersions(pinnedEngineVersion, ENGINE_MIN_FOR_SEED) >= 0) return undefined
+
+  return refusal({
+    needs: "Seeding is done by the engine",
+    since: ENGINE_MIN_FOR_SEED,
+    pinned: pinnedEngineVersion,
+    body:
+      `An engine older than ${ENGINE_MIN_FOR_SEED} has no \`seed\` subcommand. It would answer ` +
+      `this run with a usage error about an unrecognised argument, which names nothing about ` +
+      `your project and reads like a broken install.`,
+  })
+}

package/src/functions-context-refresh.ts

@@ -0,0 +1,25 @@
+/**
+ * Keep `functions/_shared/context.ts` current on a project that already exists.
+ *
+ * The module is generated by `ensureFunctionsDenoTypes`, which `init` and `supatype functions new`
+ * call and nothing else did. So it reached new projects and new functions, and never reached a
+ * project that already had functions when the two-argument handler contract landed: those keep
+ * `(req)` handlers with no `FunctionContext` to import, while the generated file asserts
+ * "Regenerated by the CLI. Edits are overwritten."
+ *
+ * A claim about a file nothing maintains is worse than no claim, because it tells people not to
+ * edit it and not to expect it to change.
+ *
+ * Only when the project has a functions directory: writing `_shared/` into a project that has no
+ * functions would create the thing it describes out of nothing.
+ */
+import { existsSync } from "node:fs"
+import { ensureFunctionsDenoTypes } from "./functions-deno-types.js"
+import { preferredFunctionsPathFromProject, type SupatypeProjectConfig } from "./project-config.js"
+
+/** Rewrite the context module. True when this project has functions and one was written. */
+export function refreshFunctionsContext(cwd: string, config: SupatypeProjectConfig): boolean {
+  const functionsDir = preferredFunctionsPathFromProject(config, cwd)
+  if (!existsSync(functionsDir)) return false
+  return ensureFunctionsDenoTypes(cwd, functionsDir).wroteContextModule
+}

package/src/functions-deno-types.ts

@@ -83,6 +83,23 @@ declare namespace Deno {
  * directory, but `deno check` builds its own type graph and does not look at either, so a function
  * naming an ambient type fails the check the runtime itself would run. An import works in both.
  */
+/**
+ * The `_shared/README.md` both scaffolds write.
+ *
+ * One definition because there were two, identical, as string literals in `init.ts` and
+ * `functions.ts`. It lives here rather than in either because this module already owns what goes
+ * into `_shared/`, and because the next edit to this text would otherwise change it in one scaffold
+ * and not the other.
+ */
+export function sharedFunctionsReadmeSource(): string {
+  return (
+    "# Shared Code\n\n" +
+    "Files in `_shared/` are available to all functions via relative imports.\n" +
+    "This directory is not deployed as a function.\n\n" +
+    "Example: `import { sendEmail } from '../_shared/email.ts'`\n"
+  )
+}
+
 export function functionsContextModuleSource(): string {
   return `/**
  * What a function is told about the call it is serving.
@@ -94,7 +111,13 @@ export function functionsContextModuleSource(): string {
  *
  * Passing them in removes the global, so functions run concurrently.
  *
- * Regenerated by the CLI. Edits are overwritten.
+ * Rewritten by supatype init, supatype functions new, supatype push and supatype dev.
+ * Edits are overwritten.
+ *
+ * Named explicitly because "regenerated by the CLI" was true of only the first two: a project that
+ * already had functions when this contract arrived never received the module at all, so its
+ * handlers had no type to import while this line told its author the file was maintained. Say
+ * which commands, so the claim can be checked rather than believed.
  */
 export interface FunctionContext {
   /** Unique to this invocation. Every log line it writes carries the same value. */

package/src/gitignore.ts

@@ -2,12 +2,42 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve } from "node:path"
 
 export const SUPATYPE_GITIGNORE_MARKER = "# Supatype, local runtime (contains secrets in link.json)"
+
+/**
+ * Every path Supatype writes that holds a secret, in one place.
+ *
+ * One list because there were two emitters, this one and `init`'s own template, and they had
+ * already drifted apart on content. Two lists of the same thing drift again, and the half that
+ * drifts is discovered by a key reaching a public repository.
+ *
+ * `.env.local` and `.env.*.local` are here because `.env` does not cover them. That pattern matches
+ * a file named exactly `.env`, while `supatype functions new` writes `functions/.env.local` with
+ * "These are NOT committed to git" at the top of it, and the worker reads
+ * `.env.<function>.local` beside that. Verified with `git check-ignore`: under `.env` alone both
+ * were tracked; with these two they are ignored at any depth, and no source file is caught.
+ */
+const SUPATYPE_IGNORED_PATHS = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  ".supatype/",
+  "supatype.local.config.ts",
+  "supatype.local.config.js",
+  "supatype.local.config.mjs",
+  // Generated from schema/index.ts by `supatype generate`, which needs no database and no
+  // running stack, so a clone can always rebuild it. Listed here rather than only in the
+  // `init` template so projects that already exist pick it up too.
+  //
+  // The default path. A project that moves `output.client` moves this with it, and would
+  // need its own line: there is no pattern that follows a value from the config file.
+  "supatype/generated/seed.ts",
+] as const
+
+/** The paths above, for a scaffold that composes its own `.gitignore` around them. */
+export const SUPATYPE_GITIGNORE_PATHS: readonly string[] = SUPATYPE_IGNORED_PATHS
+
 export const SUPATYPE_GITIGNORE_BLOCK = `${SUPATYPE_GITIGNORE_MARKER}
-.env
-.supatype/
-supatype.local.config.ts
-supatype.local.config.js
-supatype.local.config.mjs
+${SUPATYPE_IGNORED_PATHS.join("\n")}
 `
 
 export function isSupatypeGitignored(cwd: string): boolean {
@@ -26,11 +56,9 @@ export function ensureSupatypeGitignore(cwd: string, opts?: { silent?: boolean }
     const next = content.endsWith("\n") ? content : `${content}\n`
     writeFileSync(gitignorePath, `${next}\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   } else {
-    writeFileSync(
-      gitignorePath,
-      `.env\nnode_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`,
-      "utf8",
-    )
+    // `.env` is not repeated here: the block below already carries it, along with the
+    // `.env.local` patterns it does not cover.
+    writeFileSync(gitignorePath, `node_modules/\ndist/\n${SUPATYPE_GITIGNORE_BLOCK}`, "utf8")
   }
 
   if (!opts?.silent) {

package/src/hooks-generator.ts

@@ -83,12 +83,18 @@ export function generateHooksModule(ast: unknown): string | null {
 //   })
 
 /**
- * Lexical editor state as JSON, or the plain string accepted for seeds and defaults.
+ * Lexical editor state as JSON.
  *
  * Structural rather than imported: the precise \`SerializedEditorState\` lives in
  * \`@supatype/types/lexical\`, which a Deno function has no way to resolve.
+ *
+ * A hook writing to a rich text column may hand back a plain string instead; a trigger
+ * normalises it into one of these, so what a later read returns is always the document.
  */
-export type RichTextValue = { readonly root: { readonly children: readonly unknown[] } } | string
+export type RichTextValue = { readonly root: { readonly children: readonly unknown[] } }
+
+/** A stored file, and the bucket it went to. */
+export type StorageReference = { readonly bucket: string; readonly path: string }
 
 export interface HookTables {
 ${tableEntries}
@@ -412,11 +418,20 @@ function json(body: unknown, status: number): Response {
  * column emitted a module that failed to compile in the user's editor. Caught by compiling the
  * generated file in a test rather than by a reader reporting it.
  */
+/**
+ * The shared type names, as a Deno module can spell them.
+ *
+ * `RichText` resolves through `@supatype/types/lexical`, which a Deno function has no way to
+ * reach, so the module declares a structural stand-in and the generated rows point at that.
+ * `StorageReference` needs no import and is declared here as itself.
+ */
 function denoSafe(source: string): string {
-  return source.replaceAll(
-    'import("@supatype/types/lexical").SerializedEditorState',
-    "RichTextValue",
-  )
+  return source
+    .replaceAll("RichText", "RichTextValue")
+    .replaceAll(
+      'import("@supatype/types/lexical").SerializedEditorState',
+      "RichTextValue",
+    )
 }
 
 /** Re-indent a generated type literal so the emitted file reads as if it were written by hand. */