@supatype/cli 0.3.1 → 0.3.3

package/dist/type-generation.js

@@ -12,9 +12,47 @@
  * asked for and must not start creating files in projects that never configured any.
  */
 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";
+/**
+ * Where generated output goes when a project has not said otherwise.
+ *
+ * Exported because two commands need the same answer: `generate` writes these files and
+ * `seed` reads one of them, and when they disagreed the builder was written to a path the
+ * seed run then reported as missing.
+ */
+export const DEFAULT_TYPES_PATH = "types/database.ts";
+export const DEFAULT_CLIENT_PATH = "supatype/generated/index.d.ts";
+/** The seed builder, beside the client, because both are generated from the same schema. */
+const SEED_BUILDER_FILENAME = "seed.ts";
+/**
+ * Where the generated seed builder lives for this project.
+ *
+ * One rule, exported, because two things need the answer and a seed run that looked
+ * somewhere else would report a missing builder for a file that had just been written.
+ */
+export function seedBuilderPath(req) {
+    const directory = req.clientPath ?? req.typesPath;
+    if (directory === undefined || directory === "")
+        return undefined;
+    return join(dirname(directory), SEED_BUILDER_FILENAME);
+}
+/**
+ * The same answer for a project that has configured nothing.
+ *
+ * `generate` writes with the defaults applied, so a reader must resolve them the same way or
+ * it looks for a file beside a path the project never set.
+ */
+export function seedBuilderPathWithDefaults(output) {
+    return (seedBuilderPath({
+        typesPath: output?.types ?? DEFAULT_TYPES_PATH,
+        clientPath: output?.client ?? DEFAULT_CLIENT_PATH,
+    }) ?? join(dirname(DEFAULT_CLIENT_PATH), SEED_BUILDER_FILENAME));
+}
 /** Writes what was asked for and returns one message per file, for the caller to report. */
 export async function writeGeneratedTypes(req) {
     const written = [];
@@ -32,13 +70,66 @@ export async function writeGeneratedTypes(req) {
         writeFileSync(outPath, code, "utf8");
         written.push(`Types written to ${req.typesPath}`);
     }
-    // Generated locally from the AST, so it needs no engine round trip.
+    const seedPath = seedBuilderPath(req);
+    if (seedPath !== undefined) {
+        await ensureEngine();
+        const result = await engineRequest("/generate", {
+            ast: req.ast,
+            lang: "typescript",
+            artifact: "seed",
+        });
+        const code = result.code ?? result.message;
+        if (code === undefined) {
+            throw new Error("Engine returned no output for the seed builder.");
+        }
+        const outPath = resolve(req.cwd, seedPath);
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, code, "utf8");
+        written.push(`Seed builder written to ${toPosix(seedPath)}`);
+    }
+    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) {
+    const written = [];
     if (req.clientPath !== undefined && req.clientPath !== "") {
         const outPath = resolve(req.cwd, req.clientPath);
         mkdirSync(dirname(outPath), { recursive: true });
         writeFileSync(outPath, generateClientAugmentation(req.ast), "utf8");
         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) {
+    return path.split(sep).join("/");
+}
 //# sourceMappingURL=type-generation.js.map

package/dist/type-generation.js.map

@@ -1 +1 @@
-{"version":3,"file":"type-generation.js","sourceRoot":"","sources":["../src/type-generation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAWhE,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAyB;IACjE,MAAM,OAAO,GAAa,EAAE,CAAA;IAE5B,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,KAAK,EAAE,EAAE,CAAC;QACxD,MAAM,YAAY,EAAE,CAAA;QACpB,MAAM,MAAM,GAAG,MAAM,aAAa,CAChC,WAAW,EACX,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,CACrC,CAAA;QACD,6FAA6F;QAC7F,sEAAsE;QACtE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,CAAA;QAC1C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QACnE,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;QAC/C,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAChD,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;QACpC,OAAO,CAAC,IAAI,CAAC,oBAAoB,GAAG,CAAC,SAAS,EAAE,CAAC,CAAA;IACnD,CAAC;IAED,oEAAoE;IACpE,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,CAAA;QAChD,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAChD,aAAa,CAAC,OAAO,EAAE,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAA;QACnE,OAAO,CAAC,IAAI,CAAC,kCAAkC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC"}
+{"version":3,"file":"type-generation.js","sourceRoot":"","sources":["../src/type-generation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supatype/cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "Apache-2.0",
   "description": "Supatype CLI: schema push, introspect, generate",
   "type": "module",
@@ -41,7 +41,7 @@
     "@types/pg": "^8",
     "@types/react": "^18.3.18",
     "vitest": "^4.0.18",
-    "@supatype/types": "0.3.1"
+    "@supatype/types": "0.3.3"
   },
   "scripts": {
     "build": "tsc --project tsconfig.json && node --input-type=module -e \"import{cpSync,mkdirSync}from'node:fs';const a='dist/assets';mkdirSync(a,{recursive:true});cpSync('assets/supatype-logo-wordmark.ascii.txt',a+'/supatype-logo-wordmark.ascii.txt')\"",

package/src/api-config-cache.ts

@@ -100,6 +100,36 @@ export function seedApiConfigCache(cwd: string, ast: unknown): CacheSeedResult |
  * refused it where the read rule varies by caller. Defaulting it off would make the declaration
  * mean nothing until someone ticked a box that the schema had already justified.
  */
+/**
+ * What a push or a dev boot should say about cache seeding, as lines to print.
+ *
+ * Returns the text rather than printing it, because the two callers write to the console
+ * differently and the thing worth sharing is the decision about what to say, not the formatting.
+ * Extracted from `push` when `dev` grew the same need: `seedApiConfigCache` had exactly one caller
+ * for a long time, which is why a stack brought up with `supatype dev` alone had no cache
+ * allowlist at all and nothing anywhere said so.
+ *
+ * Never an error, and never a rewrite of an entry that already exists. See `seedApiConfigCache`.
+ */
+export function cacheSeedingNotes(cwd: string, ast: unknown): string[] {
+  const result = seedApiConfigCache(cwd, ast)
+  if (result === null) return []
+
+  const notes: string[] = []
+  if (result.seeded.length > 0) {
+    notes.push(`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.
+    notes.push(
+      `${result.declared.length} table(s) declare a cache, but cache_max_ttl is 0, so nothing ` +
+        `is cached until it is set, under API > REST > Settings or in .supatype/api-config.json.`,
+    )
+  }
+  return notes
+}
+
 function seedEntry(entry: ManifestCacheEntry): TableCacheConfig {
   return { enabled: true, allow_public: entry.public === true }
 }

package/src/augmentation-generator.ts

@@ -38,21 +38,44 @@ function fieldServerGenerated(meta: Record<string, unknown>): boolean {
 
 export function generateClientAugmentation(ast: unknown): string {
   const parsed = ast as AstShape
-  const models = [...(parsed.models ?? [])]
-    .map((model) => ({ model, tableName: resolveTableName(model) }))
-    .sort((a, b) => a.tableName.localeCompare(b.tableName))
+  // In the order the schema declares them. The AST preserves that order, and it is the order
+  // the author reads their own schema in.
+  const models = [...(parsed.models ?? [])].map((model) => ({
+    model,
+    tableName: resolveTableName(model),
+  }))
+
+  const kinds = new Set<string>()
+  for (const { model } of models) {
+    for (const meta of Object.values(model.fields ?? {})) {
+      if (typeof meta["kind"] === "string") kinds.add(meta["kind"])
+    }
+  }
 
   const lines: string[] = []
   lines.push("// Generated by supatype CLI, do not edit manually.")
   lines.push("")
+  if (kinds.has("richText")) {
+    lines.push("import type { SerializedEditorState } from \"@supatype/types/lexical\"")
+    lines.push("")
+    lines.push("export type RichText = SerializedEditorState")
+    lines.push("")
+  }
+  if (kinds.has("image") || kinds.has("file")) {
+    lines.push("export type StorageReference = {")
+    lines.push("  bucket: string")
+    lines.push("  path: string")
+    lines.push("}")
+    lines.push("")
+  }
   lines.push("declare module \"@supatype/client\" {")
   lines.push("  interface SupatypeModels {")
 
   for (const { model, tableName } of models) {
     lines.push(`    ${quoteKey(tableName)}: {`)
-    lines.push(`      Row: ${generateRowType(model.fields)}`)
-    lines.push(`      Insert: ${generateInsertType(model.fields)}`)
-    lines.push(`      Update: ${generateUpdateType(model.fields)}`)
+    lines.push(`      Row: ${indent(generateRowType(model.fields), 6)}`)
+    lines.push(`      Insert: ${indent(generateInsertType(model.fields), 6)}`)
+    lines.push(`      Update: ${indent(generateUpdateType(model.fields), 6)}`)
     lines.push("    }")
   }
 
@@ -65,41 +88,117 @@ export function generateClientAugmentation(ast: unknown): string {
   return lines.join("\n")
 }
 
-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)}`)
+/** Place a generated object body inside the block that holds it. */
+function indent(source: string, spaces: number): string {
+  const pad = " ".repeat(spaces)
+  return source
+    .split("\n")
+    .map((line, i) => (i === 0 ? line : `${pad}${line}`))
     .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,
+    )
+}
+
+export function generateRowType(fields: Record<string, Record<string, unknown>>): string {
+  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}`
 }
 
+/**
+ * What a column accepts on the way in, where that is wider than what it returns.
+ *
+ * A rich text column holds a Lexical document, and the engine emits a trigger that normalises a
+ * plain string into one on insert and update. So writing prose is a string and reading it is
+ * always a document, and this is the only place the three shapes differ by more than
+ * optionality. Flattening them back would either demand hand-built Lexical JSON from every
+ * caller, or claim a read might return a string, which after the trigger it cannot.
+ */
+function widenForWrites(ts: string, meta: Record<string, unknown>): string {
+  // Rebuilt rather than edited. The widening has to land on the value the trigger normalises,
+  // and for a localized column that is each locale's value, not the map holding them. Splicing
+  // ` | string` into the finished string put it outside the locale wrapper, which said a bare
+  // string was a valid write to the column; the trigger would then store it as a single document
+  // where a locale map belongs, and the Row type says that cannot happen.
+  return meta["kind"] === "richText" ? toTsType(meta, true) : ts
+}
+
 function insertColumnOptionalOnInsert(meta: Record<string, unknown>): boolean {
-  return meta["default"] !== undefined || fieldServerGenerated(meta)
+  // `slug` has neither a declared default nor a `serverGenerated` flag, but the engine emits
+  // a trigger that fills it, which is the same thing from an insert's point of view.
+  return (
+    meta["default"] !== undefined || fieldServerGenerated(meta) || meta["kind"] === "slug"
+  )
 }
 
 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 ? "" : "?"}: ${widenForWrites(ts, meta)}`
     })
     .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)}`)
+  const columns = columnsOf(fields)
+  if (columns.length === 0) return "Record<string, unknown>"
+  const body = columns
+    .map(({ column, ts, meta }) => `  ${quoteKey(column)}?: ${widenForWrites(ts, meta)}`)
     .join("\n")
   return `{\n${body}\n}`
 }
 
-function toTsType(meta: Record<string, unknown>): string {
+function toTsType(meta: Record<string, unknown>, prose = false): string {
   const kind = typeof meta["kind"] === "string" ? meta["kind"] : "json"
   const required = meta["required"] === true
   const base = (() => {
@@ -119,6 +218,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 +230,6 @@ function toTsType(meta: Record<string, unknown>): string {
       case "smallInt":
       case "serial":
       case "float":
-      case "decimal":
         return "number"
       case "bigSerial":
       case "bigInt":
@@ -139,11 +242,16 @@ 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 "StorageReference"
       case "richText":
-        return "(import(\"@supatype/types/lexical\").SerializedEditorState | string)"
+        return "RichText"
       case "enum": {
         const values = Array.isArray(meta["values"]) ? meta["values"] as unknown[] : []
         const quoted = values
@@ -155,7 +263,15 @@ 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.
+  // Prose, which a trigger normalises into a document on the way in. Applied to the element,
+  // before the locale wrapper goes on, so a localized column reads `{ [locale: string]: RichText
+  // | string }` rather than claiming the whole map could be a string.
+  const written = prose && meta["kind"] === "richText" ? `${base} | string` : base
+  const shaped = meta["localized"] === true ? `{ [locale: string]: ${written} }` : written
+  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.1"
+export const EMBEDDED_CLI_VERSION: string = "0.3.3"

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/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/generate.ts

@@ -2,7 +2,11 @@ import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
 import { writeHooksModule } from "../model-hooks.js"
-import { writeGeneratedTypes } from "../type-generation.js"
+import {
+  DEFAULT_CLIENT_PATH,
+  DEFAULT_TYPES_PATH,
+  writeGeneratedTypes,
+} from "../type-generation.js"
 import { error, info } from "../ui/messages.js"
 
 export function registerGenerate(program: Command): void {
@@ -14,8 +18,8 @@ export function registerGenerate(program: Command): void {
       const cwd = process.cwd()
       const config = loadConfig(cwd)
       const schemaPath = schemaPathFromProject(config, cwd)
-      const outputTypesPath = config.output?.types ?? "types/database.ts"
-      const outputClientPath = config.output?.client ?? "supatype/generated/index.d.ts"
+      const outputTypesPath = config.output?.types ?? DEFAULT_TYPES_PATH
+      const outputClientPath = config.output?.client ?? DEFAULT_CLIENT_PATH
 
       info("Loading schema...")
       const ast = loadSchemaAst(schemaPath, cwd)