@supatype/cli 0.3.1 → 0.3.2

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")
+  })
+})

package/tests/client-generator.test.ts

@@ -0,0 +1,103 @@
+/**
+ * The client a project imports, generated into its own source tree.
+ *
+ * An app writes one import and nothing else:
+ *
+ *     import { createClient } from "./supatype/client"
+ *
+ * That single file carries three things that previously arrived by three different routes, two of
+ * which could silently fail:
+ *
+ *   the module augmentation  was a `.d.ts` found only through tsconfig `include`, so a stale or
+ *                            missing entry left every table name accepted and every column
+ *                            `unknown`, with the build passing
+ *   the field kinds          were read off disk and, failing that, reconstructed from PostgREST's
+ *                            OpenAPI document, which always succeeds and so could never report a
+ *                            project that had not generated
+ *   `createClient`           came from the package, which knows nothing about the project
+ *
+ * Arriving by import means the bundler carries them, tsconfig cannot lose them, nothing is
+ * fetched, and a project that has not generated has no file to import, so the build fails.
+ */
+import { describe, expect, it } from "vitest"
+import { generateProjectClient } from "../src/client-generator.js"
+
+const ast = {
+  models: [
+    {
+      name: "JobPost",
+      annotations: { db: { tableName: "job_post" } },
+      fields: {
+        id: { kind: "uuid", required: true },
+        title: { kind: "text", required: true },
+        views: { kind: "bigInt", required: true },
+        equityPct: { kind: "decimal", required: false },
+      },
+    },
+  ],
+}
+
+const plainAst = {
+  models: [
+    {
+      name: "LandingPage",
+      annotations: { db: { tableName: "landing_page" } },
+      fields: { id: { kind: "uuid", required: true } },
+    },
+  ],
+}
+
+describe("generateProjectClient", () => {
+  it("re-exports the client package, so one import is enough", () => {
+    expect(generateProjectClient(ast)).toContain('export * from "@supatype/client"')
+  })
+
+  it("carries the module augmentation, rather than relying on tsconfig to find it", () => {
+    const out = generateProjectClient(ast)
+    expect(out).toContain('declare module "@supatype/client"')
+    expect(out).toContain("interface SupatypeModels")
+    expect(out).toContain("job_post")
+  })
+
+  it("registers the columns a JSON parser would destroy", () => {
+    const out = generateProjectClient(ast)
+    expect(out).toContain("registerFieldKinds(")
+    expect(out).toContain('"views": "bigint"')
+    expect(out).toContain('"equityPct": "numeric"')
+  })
+
+  it("leaves ordinary columns out of the registration", () => {
+    // Listing a column that survives a parse would invite the client to convert one that was
+    // already correct.
+    const out = generateProjectClient(ast)
+    expect(out).not.toContain('"title"')
+    expect(out).not.toContain('"id": "')
+  })
+
+  it("still registers for a schema with nothing exact", () => {
+    // Registered-and-empty is how the client tells "this project generated and has no exact
+    // columns" from "this project never generated". Both must not look the same.
+    const out = generateProjectClient(plainAst)
+    expect(out).toContain("registerFieldKinds(")
+    expect(out).toContain('"tables": {}')
+  })
+
+  it("imports the registration function from the package", () => {
+    expect(generateProjectClient(ast)).toContain(
+      'import { registerFieldKinds } from "@supatype/client"',
+    )
+  })
+
+  it("says it is generated, on the first line", () => {
+    expect(generateProjectClient(ast).split("\n")[0]).toContain("Generated by supatype")
+  })
+
+  it("is stable across runs, so it does not churn the diff", () => {
+    expect(generateProjectClient(ast)).toBe(generateProjectClient(ast))
+  })
+
+  it("survives an ast it does not recognise", () => {
+    expect(() => generateProjectClient({})).not.toThrow()
+    expect(() => generateProjectClient(null)).not.toThrow()
+  })
+})

package/tests/db-port.test.ts

@@ -0,0 +1,128 @@
+/**
+ * `DATABASE_URL` has to name the port Postgres is published on.
+ *
+ * `SUPATYPE_DB_PORT` moves the host side of the compose mapping so two projects can coexist on one
+ * machine. `DATABASE_URL` is what every host-side script uses. Nothing reconciled them, so a
+ * project moved to 5433 started cleanly, served every request, and failed on its own seed script
+ * with `ECONNREFUSED 127.0.0.1:5432`, naming a port the person never chose.
+ *
+ * The cases that matter most here are the ones where it must NOT act: a remote database is not
+ * ours to repoint, and a malformed URL is not ours to half-fix.
+ */
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { DEFAULT_DB_PORT, publishedDbPort, syncDatabaseUrlPort } from "../src/db-port.js"
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "supatype-dbport-"))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+function writeEnv(lines: string): void {
+  writeFileSync(join(dir, ".env"), lines, "utf8")
+}
+
+function envText(): string {
+  return readFileSync(join(dir, ".env"), "utf8")
+}
+
+describe("publishedDbPort", () => {
+  it("defaults to the port compose binds when unset", () => {
+    expect(publishedDbPort({})).toBe(DEFAULT_DB_PORT)
+  })
+
+  it("reads the configured port", () => {
+    expect(publishedDbPort({ SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("prefers the dev-local port, because its presence marks the deployment shape", () => {
+    // Found by running the validation e2e: that project publishes on SUPATYPE_DEV_DB_PORT=54330
+    // for its host-side engine, and an earlier version of this file rewrote a correct URL to 5432.
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "54330" })).toBe(54330)
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "54330", SUPATYPE_DB_PORT: "5433" })).toBe(54330)
+  })
+
+  it("uses the self-host port when there is no dev-local one", () => {
+    expect(publishedDbPort({ SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("falls through a nonsense dev-local port to the self-host one", () => {
+    expect(publishedDbPort({ SUPATYPE_DEV_DB_PORT: "abc", SUPATYPE_DB_PORT: "5433" })).toBe(5433)
+  })
+
+  it("falls back rather than inventing a port from nonsense", () => {
+    // Compose reports a bad value far better than we can, and a made-up port would send the seed
+    // somewhere nothing is listening with no clue why.
+    for (const bad of ["", "   ", "abc", "-1", "0", "70000", "5433.5"]) {
+      expect(publishedDbPort({ SUPATYPE_DB_PORT: bad }), `value ${JSON.stringify(bad)}`).toBe(
+        DEFAULT_DB_PORT,
+      )
+    }
+  })
+})
+
+describe("syncDatabaseUrlPort", () => {
+  it("rewrites the port when the two disagree", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost:5432/acme\nSUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toEqual({ from: "5432", to: "5433" })
+    expect(envText()).toContain("localhost:5433/acme")
+  })
+
+  it("keeps the credentials, database and query string intact", () => {
+    // The whole point is one field. A rewrite that dropped the password would take the stack down
+    // in a way that looks nothing like a port problem.
+    writeEnv(
+      "DATABASE_URL=postgresql://supatype_admin:s3cr3t@127.0.0.1:5432/acme?sslmode=disable\nSUPATYPE_DB_PORT=5440\n",
+    )
+    syncDatabaseUrlPort(dir)
+    const url = new URL(readFileSync(join(dir, ".env"), "utf8").match(/^DATABASE_URL=(.+)$/m)![1]!)
+    expect(url.port).toBe("5440")
+    expect(url.username).toBe("supatype_admin")
+    expect(url.password).toBe("s3cr3t")
+    expect(url.pathname).toBe("/acme")
+    expect(url.searchParams.get("sslmode")).toBe("disable")
+  })
+
+  it("does nothing when they already agree", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost:5433/acme\nSUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("treats an absent port as the default rather than rewriting it every run", () => {
+    writeEnv("DATABASE_URL=postgresql://u:p@localhost/acme\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("leaves a remote database alone", () => {
+    // Somebody else's Postgres. Its port has nothing to do with our compose mapping, and
+    // rewriting it would repoint the project at a database that does not exist.
+    const remote = "postgresql://u:p@db.example.com:5432/acme"
+    writeEnv(`DATABASE_URL=${remote}\nSUPATYPE_DB_PORT=5433\n`)
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+    expect(envText()).toContain(remote)
+  })
+
+  it("leaves a malformed URL alone rather than half-fixing it", () => {
+    const broken = "postgres//u:p@localhost:5432/acme"
+    writeEnv(`DATABASE_URL=${broken}\nSUPATYPE_DB_PORT=5433\n`)
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+    expect(envText()).toContain(broken)
+  })
+
+  it("does nothing when there is no DATABASE_URL at all", () => {
+    writeEnv("SUPATYPE_DB_PORT=5433\n")
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+
+  it("does nothing when there is no .env", () => {
+    expect(syncDatabaseUrlPort(dir)).toBeNull()
+  })
+})

package/tests/external-database-compose.test.ts

@@ -42,13 +42,20 @@ describe("external database: compose", () => {
     const compose = renderSelfHostCompose(managed())
     expect(compose).toMatch(/^ {2}db:$/m)
     expect(compose).toContain("pg_isready")
+    // The positive half of "leaves no reference to the db host anywhere" below. Without this, that
+    // test's negative assertion could pass against a pattern that matches nothing at all.
+    expect(compose).toMatch(/^\s+db:\s*\n\s+condition:/m)
   })
 
   it("leaves no reference to the db host anywhere", () => {
     const compose = renderSelfHostCompose(external())
     expect(compose).not.toContain("@db:5432")
     expect(compose).not.toContain("db-data")
-    expect(compose).not.toContain("condition: service_healthy")
+    // Nothing may wait on a `db` service that is not there. Asserted as a dependency on `db`
+    // rather than as the absence of any health condition, which is what this used to say: storage
+    // waits for the object store to be healthy in every deployment, because that race is about
+    // seaweedfs and has nothing to do with where Postgres lives.
+    expect(compose).not.toMatch(/^\s+db:\s*\n\s+condition:/m)
   })
 
   it("points every database consumer at the one URL", () => {

package/tests/functions-context-refresh.test.ts

@@ -0,0 +1,86 @@
+/**
+ * `functions/_shared/context.ts` reaches a project that already exists.
+ *
+ * The module was written by `init` and `supatype functions new`, and by nothing else. So it arrived
+ * with new projects and new functions, and never arrived at 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 itself asserts
+ *
+ *   Regenerated by the CLI. Edits are overwritten.
+ *
+ * which was true only if you scaffolded again. `tests/integration` in this repo had four functions
+ * and no context module at all, which is how it was found.
+ */
+import { describe, expect, it, beforeEach, afterEach } from "vitest"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { refreshFunctionsContext } from "../src/functions-context-refresh.js"
+import type { SupatypeProjectConfig } from "../src/project-config.js"
+
+const config: SupatypeProjectConfig = {
+  project: { name: "ctx" },
+  database: { provider: "docker" },
+} as SupatypeProjectConfig
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "supatype-ctx-"))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+/** A project with functions but no `_shared`, which is what a pre-migration project looks like. */
+function projectWithFunctions(): string {
+  const functions = join(dir, "functions")
+  mkdirSync(functions, { recursive: true })
+  writeFileSync(
+    join(functions, "ping.ts"),
+    "export default function ping(_req: Request) { return new Response('ok') }\n",
+    "utf8",
+  )
+  return functions
+}
+
+describe("a project that already has functions", () => {
+  it("gets the context module written", () => {
+    const functions = projectWithFunctions()
+    expect(existsSync(join(functions, "_shared", "context.ts"))).toBe(false)
+
+    expect(refreshFunctionsContext(dir, config)).toBe(true)
+    expect(existsSync(join(functions, "_shared", "context.ts"))).toBe(true)
+  })
+
+  it("writes a module that actually declares the contract", () => {
+    // Not merely that a file appeared. The point is the type handlers import.
+    projectWithFunctions()
+    refreshFunctionsContext(dir, config)
+    const source = readFileSync(join(dir, "functions", "_shared", "context.ts"), "utf8")
+    expect(source).toContain("FunctionContext")
+    expect(source).toContain("executionId")
+  })
+
+  it("rewrites a stale copy rather than leaving it", () => {
+    // The file says edits are overwritten, so they have to be.
+    const functions = projectWithFunctions()
+    mkdirSync(join(functions, "_shared"), { recursive: true })
+    writeFileSync(join(functions, "_shared", "context.ts"), "// stale\n", "utf8")
+
+    refreshFunctionsContext(dir, config)
+    const source = readFileSync(join(functions, "_shared", "context.ts"), "utf8")
+    expect(source).not.toBe("// stale\n")
+    expect(source).toContain("FunctionContext")
+  })
+})
+
+describe("a project with no functions", () => {
+  it("is left alone", () => {
+    // Writing `_shared/` into a project with no functions would create the thing it describes out
+    // of nothing, and leave a directory nobody asked for in the diff.
+    expect(refreshFunctionsContext(dir, config)).toBe(false)
+    expect(existsSync(join(dir, "functions"))).toBe(false)
+  })
+})