@supatype/cli 0.1.11 → 0.1.13

package/tests/field-bounds-matrix.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest"
+import { compileBounds } from "../src/field-bounds.js"
+import type { FieldKind } from "../src/schema-ast-v2.js"
+
+/**
+ * Every field kind, against every bound family, asserted to do exactly one of two things.
+ *
+ * This is the test whose absence caused the whole defect. Nine of twelve field kinds accepted a
+ * declared bound and enforced nothing, and no test noticed, because no test enumerated the kinds:
+ * each was handled wherever someone happened to look.
+ *
+ * `MATRIX` is typed `Record<FieldKind, KindRow>`, so **completeness is the compiler's job**: adding
+ * a kind to `FIELD_KINDS` fails the build in three places at once, here, in `BOUNDS_BY_KIND`, and
+ * at any `scalar()` call using a name the registry does not know. No assertion can rot into
+ * vacuous, because there is nothing to keep in sync by hand.
+ *
+ * Every cell is either an expression or a refusal. **A cell that is silently empty is the bug**, so
+ * there is no way to express one.
+ */
+
+type Cell = { sql: string } | { refused: RegExp }
+
+interface KindRow {
+  /** `MaxLength<T, 5>` */
+  length: Cell
+  /** `MaxItems<T, 5>` */
+  items: Cell
+  /** `Between<T, ...>`, using whichever bound shape the kind accepts. */
+  range: Cell
+  /** The literal to bound with, when the kind takes a string rather than a number. */
+  rangeBound?: string
+}
+
+const COL = '"{name}"'
+const refusedAs = (alternative: string): Cell => ({ refused: new RegExp(alternative) })
+
+const textual = (): KindRow => ({
+  length: { sql: `char_length(${COL}) <= 5` },
+  items: refusedAs("MaxItems is not supported"),
+  range: refusedAs("Between is not supported"),
+})
+
+const numeric = (): KindRow => ({
+  length: refusedAs("MaxLength is not supported"),
+  items: refusedAs("MaxItems is not supported"),
+  range: { sql: `${COL} <= 5` },
+})
+
+// An interval is bounded by a duration, not by a date. The matrix keeps them distinct because the
+// extractor validates the literal shape per cast and would otherwise reject one of them at push time.
+const temporal = (cast: string, bound = "2026-12-31"): KindRow => ({
+  length: refusedAs("MaxLength is not supported"),
+  items: refusedAs("MaxItems is not supported"),
+  range: { sql: `${COL} <= '${bound}'::${cast}` },
+  rangeBound: bound,
+})
+
+const unbounded = (why: string): KindRow => ({
+  length: refusedAs(why),
+  items: refusedAs(why),
+  range: refusedAs(why),
+})
+
+const collection = (measure: string): KindRow => ({
+  length: refusedAs("MaxItems"),
+  items: { sql: measure },
+  range: refusedAs("Between is not supported"),
+})
+
+const MATRIX: Record<FieldKind, KindRow> = {
+  text: textual(),
+  email: textual(),
+  url: textual(),
+  slug: textual(),
+  color: textual(),
+  xml: textual(),
+  ip: textual(),
+  cidr: textual(),
+  macaddr: textual(),
+  tsQuery: textual(),
+  tsVector: textual(),
+
+  richText: {
+    length: { sql: `char_length(_supatype.richtext_text(${COL})) <= 5` },
+    items: refusedAs("MaxItems is not supported"),
+    range: refusedAs("Between is not supported"),
+  },
+  bytes: {
+    length: { sql: `octet_length(${COL}) <= 5` },
+    items: refusedAs("MaxItems is not supported"),
+    range: refusedAs("Between is not supported"),
+  },
+
+  integer: numeric(),
+  smallInt: numeric(),
+  bigInt: numeric(),
+  float: numeric(),
+  serial: numeric(),
+  bigSerial: numeric(),
+  decimal: numeric(),
+  money: numeric(),
+
+  datetime: temporal("timestamptz"),
+  timestamp: temporal("timestamp"),
+  date: temporal("date"),
+  interval: temporal("interval", "30 days"),
+
+  array: collection(`cardinality(${COL}) <= 5`),
+  blocks: collection(`jsonb_typeof(${COL}) = 'array' AND jsonb_array_length(${COL}) <= 5`),
+  json: unbounded("JSON object has no single measure"),
+  button: unbounded("composite value"),
+
+  enum: unbounded("union already constrains"),
+  boolean: unbounded("boolean has two values"),
+  uuid: unbounded("fixed width"),
+  image: unbounded("fileSizeLimit"),
+  file: unbounded("fileSizeLimit"),
+  geo: unbounded("not measured this way"),
+  vector: unbounded("dimension is already fixed"),
+  relation: unbounded("bound the column on the model"),
+  custom: unbounded("plugin field declares its own storage"),
+  timestamps: unbounded("composite expands into columns"),
+  publishable: unbounded("composite expands into columns"),
+  softDelete: unbounded("composite expands into columns"),
+}
+
+function assertCell(kind: FieldKind, family: string, cell: Cell, run: () => { check?: string }): void {
+  if ("refused" in cell) {
+    expect(
+      run,
+      `${kind}.${family} must refuse rather than silently accept a bound it cannot honour`,
+    ).toThrow(cell.refused)
+    return
+  }
+  const { check } = run()
+  expect(check, `${kind}.${family} must compile to its own expression`).toBe(cell.sql)
+}
+
+describe("bounds matrix", () => {
+  for (const [kind, row] of Object.entries(MATRIX) as Array<[FieldKind, KindRow]>) {
+    describe(kind, () => {
+      it("length", () => {
+        assertCell(kind, "length", row.length, () => compileBounds("f", kind, { maxLength: 5 }))
+      })
+
+      it("items", () => {
+        assertCell(kind, "items", row.items, () => compileBounds("f", kind, { maxItems: 5 }))
+      })
+
+      it("range", () => {
+        const max = row.rangeBound ?? 5
+        assertCell(kind, "range", row.range, () => compileBounds("f", kind, { max }))
+      })
+    })
+  }
+
+  it("treats JSON as a collection only when its type argument is an array", () => {
+    // The one cell the kind alone cannot decide: the CLI reads it from the declared type.
+    expect(compileBounds("f", "json", { maxItems: 5 }, { jsonIsArray: true }).check).toBe(
+      `jsonb_typeof(${COL}) = 'array' AND jsonb_array_length(${COL}) <= 5`,
+    )
+  })
+})

package/tests/field-bounds.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest"
+import { compileBounds } from "../src/field-bounds.js"
+import type { FieldKind } from "../src/schema-ast-v2.js"
+
+// The bug this module exists to prevent: a declared bound that reaches neither Postgres nor Studio
+// and raises nothing. Every assertion here is therefore either "this exact SQL" or "this throws".
+// A kind that silently returns no check is the failure mode, so there is no test that permits one.
+
+describe("compileBounds: length", () => {
+  it("counts characters for text-like kinds", () => {
+    expect(compileBounds("title", "text", { maxLength: 120 })).toEqual({
+      check: 'char_length("{name}") <= 120',
+      validation: { maxLength: 120 },
+    })
+    expect(compileBounds("email", "email", { minLength: 5 }).check).toBe(
+      'char_length("{name}") >= 5',
+    )
+  })
+
+  it("counts octets for a binary column, not characters", () => {
+    expect(compileBounds("blob", "bytes", { maxLength: 1024 }).check).toBe(
+      'octet_length("{name}") <= 1024',
+    )
+  })
+
+  it("counts plain-text characters for rich text, through the managed helper", () => {
+    expect(compileBounds("body", "richText", { maxLength: 320 }).check).toBe(
+      'char_length(_supatype.richtext_text("{name}")) <= 320',
+    )
+  })
+
+  it("merges both ends into one constraint", () => {
+    expect(compileBounds("body", "text", { maxLength: 4000, minLength: 20 })).toEqual({
+      check: '(char_length("{name}") <= 4000) AND (char_length("{name}") >= 20)',
+      validation: { maxLength: 4000, minLength: 20 },
+    })
+  })
+})
+
+describe("compileBounds: items", () => {
+  it("uses cardinality for a real array, never char_length", () => {
+    // char_length(text[]) does not exist: the old generator's output failed CREATE TABLE.
+    expect(compileBounds("tags", "array", { maxItems: 10 }).check).toBe(
+      'cardinality("{name}") <= 10',
+    )
+  })
+
+  it("guards jsonb_array_length with a type check", () => {
+    // Unguarded, an object value raises "cannot get array length of a non-array" at insert.
+    expect(compileBounds("sections", "blocks", { minItems: 1 }).check).toBe(
+      'jsonb_typeof("{name}") = \'array\' AND jsonb_array_length("{name}") >= 1',
+    )
+  })
+
+  it("accepts item bounds on JSON only when the declared type argument is an array", () => {
+    expect(compileBounds("items", "json", { minItems: 1 }, { jsonIsArray: true }).check).toBe(
+      'jsonb_typeof("{name}") = \'array\' AND jsonb_array_length("{name}") >= 1',
+    )
+    expect(() => compileBounds("meta", "json", { minItems: 1 })).toThrow(
+      /MinItems is not supported on a json field.*JSON<T\[\]>/s,
+    )
+  })
+})
+
+describe("compileBounds: range", () => {
+  it("compares a numeric column directly, with no cast", () => {
+    expect(compileBounds("score", "integer", { min: 1, max: 5 })).toEqual({
+      check: '("{name}" >= 1) AND ("{name}" <= 5)',
+      validation: { min: 1, max: 5 },
+    })
+  })
+
+  it("money and decimal are NUMERIC columns, so they need no cast either", () => {
+    expect(compileBounds("price", "money", { min: 0 }).check).toBe('"{name}" >= 0')
+    expect(compileBounds("rate", "decimal", { max: 100 }).check).toBe('"{name}" <= 100')
+  })
+
+  it("casts a temporal bound to the column's own type", () => {
+    expect(compileBounds("startsAt", "datetime", { min: "2026-01-01T00:00:00Z" }).check).toBe(
+      `"{name}" >= '2026-01-01T00:00:00Z'::timestamptz`,
+    )
+    expect(compileBounds("day", "date", { max: "2026-12-31" }).check).toBe(
+      `"{name}" <= '2026-12-31'::date`,
+    )
+    expect(compileBounds("window", "interval", { max: "30 days" }).check).toBe(
+      `"{name}" <= '30 days'::interval`,
+    )
+  })
+
+  it("refuses a string bound on a number and a number bound on a date", () => {
+    expect(() => compileBounds("score", "integer", { min: "1" })).toThrow(
+      /takes numbers, but "1" is a string/,
+    )
+    expect(() => compileBounds("day", "date", { min: 20260101 })).toThrow(
+      /takes ISO-8601 string bounds, but 20260101 is a number/,
+    )
+  })
+
+  it("refuses a temporal bound that is not a date, before it reaches a migration", () => {
+    expect(() => compileBounds("day", "date", { max: "next tuesday" })).toThrow(
+      /is not a valid ISO-8601 date/,
+    )
+  })
+})
+
+describe("compileBounds: refusals name the alternative", () => {
+  const cases: Array<[string, FieldKind, Parameters<typeof compileBounds>[2], RegExp]> = [
+    ["tags", "array", { maxLength: 10 }, /MaxLength is not supported on a array field.*MaxItems/s],
+    ["body", "richText", { maxItems: 3 }, /MaxItems is not supported on a richText field/],
+    ["score", "integer", { maxLength: 3 }, /MaxLength is not supported on a integer field/],
+    ["title", "text", { min: 1 }, /Between is not supported on a text field/],
+    ["status", "enum", { maxLength: 5 }, /union already constrains the permitted values/],
+    ["cover", "image", { maxLength: 5 }, /fileSizeLimit and allowedMimeTypes/],
+    ["embedding", "vector", { max: 1 }, /dimension is already fixed by the type/],
+    ["author", "relation", { maxLength: 5 }, /bound the column on the model this relation points at/],
+    ["flag", "boolean", { min: 0 }, /a boolean has two values/],
+  ]
+
+  for (const [field, kind, bounds, expected] of cases) {
+    it(`${kind} refuses and says where to go instead`, () => {
+      expect(() => compileBounds(field, kind, bounds)).toThrow(expected)
+    })
+  }
+
+  it("names the field, so the error is actionable in a large schema", () => {
+    expect(() => compileBounds("setupItems", "json", { maxLength: 3 })).toThrow(/Field "setupItems"/)
+  })
+})
+
+describe("compileBounds: coverage is enforced, not assumed", () => {
+  // Completeness moved from a runtime throw to the type system: `BOUNDS_BY_KIND` is
+  // `Record<FieldKind, ...>` and `scalar()` takes a `FieldKind`, so an unclassified kind cannot be
+  // written down, let alone reach here. Asserting the old throw would mean calling `compileBounds`
+  // with a kind that no longer typechecks, which is the point.
+
+  it("returns nothing when nothing was declared", () => {
+    expect(compileBounds("x", "text", {})).toEqual({})
+  })
+})

package/tests/field-validators.test.ts

@@ -0,0 +1,139 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  declaredValidators,
+  hooksReport,
+  manifestValidators,
+  validateModelValidators,
+} from "../src/model-hooks.js"
+import { extractSchemaAstFromTypes } from "../src/type-extractor.js"
+
+// A per-field validator that silently never fires is the failure this feature cannot have: the
+// schema would say the field is checked and nothing would be checking it. So the tests here are
+// mostly about the ways that could happen, and each one fails the push instead.
+
+const dirs: string[] = []
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function extract(meta: string, fields = "  id: UUID\n  sku: string\n  setupItems: JSON<{ label: string }[]>"): unknown {
+  const dir = mkdtempSync(join(tmpdir(), "supatype-validators-"))
+  dirs.push(dir)
+  const schemaPath = join(dir, "schema.ts")
+  writeFileSync(
+    schemaPath,
+    `
+import type { JSON, Model, Public, UUID } from "@supatype/types"
+
+export type Product = Model<{
+${fields}
+}, {
+  access: { read: Public }
+${meta}
+}>
+`,
+    "utf8",
+  )
+  return extractSchemaAstFromTypes(schemaPath, dir)
+}
+
+/** A functions directory containing the named handlers. */
+function functionsDir(...names: string[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "supatype-fns-"))
+  dirs.push(dir)
+  for (const name of names) {
+    mkdirSync(join(dir, name), { recursive: true })
+    writeFileSync(join(dir, name, "index.ts"), "export default () => new Response()", "utf8")
+  }
+  return dir
+}
+
+describe("declaring a field validator", () => {
+  it("extracts the field and its function", () => {
+    const ast = extract('  validate: { setupItems: "check-items" }')
+    expect(declaredValidators(ast)).toEqual([
+      { model: "Product", field: "setupItems", function: "check-items" },
+    ])
+  })
+
+  it("accepts per-validator options, as hooks do", () => {
+    const ast = extract('  validate: { sku: { function: "check-sku", timeout: 3000 } }')
+    const manifest = manifestValidators(ast)
+    expect(manifest["product"]?.["sku"]).toEqual({
+      function: "check-sku",
+      timeout: 3000,
+      onUnavailable: "reject",
+    })
+  })
+
+  it("writes onUnavailable explicitly rather than relying on the server's default", () => {
+    // The server does default to refusing, but its policy matches exact event names, and a value
+    // missing from that switch is how an unreachable validator came to accept writes once already.
+    const ast = extract('  validate: { setupItems: "check-items" }')
+    expect(manifestValidators(ast)["product"]?.["setupItems"]?.onUnavailable).toBe("reject")
+  })
+
+  it("refuses a validator naming a field the model does not have", () => {
+    // Caught here, where the message can list the real fields, rather than becoming a manifest entry
+    // for a column that will never appear in a write.
+    expect(() => extract('  validate: { noSuchField: "check-it" }')).toThrow(
+      /names "noSuchField", which is not a field on this model.*id, sku, setupItems/s,
+    )
+  })
+
+  it("refuses a validate block that is not an object", () => {
+    expect(() => extract("  validate: string")).toThrow(/`validate` must be an object/)
+  })
+
+  it("emits nothing when a model declares none", () => {
+    const ast = extract("")
+    expect(declaredValidators(ast)).toEqual([])
+    expect(manifestValidators(ast)).toEqual({})
+  })
+})
+
+describe("push refuses a validator whose function is missing", () => {
+  it("names the field and where the function should be", () => {
+    const ast = extract('  validate: { setupItems: "check-items" }')
+    const problems = validateModelValidators(ast, functionsDir("something-else"), process.cwd())
+
+    expect(problems.join("\n")).toMatch(/Product\.setupItems → "check-items"/)
+    expect(problems.join("\n")).toMatch(/something-else/)
+  })
+
+  it("says nothing when every function exists", () => {
+    const ast = extract('  validate: { setupItems: "check-items" }')
+    expect(validateModelValidators(ast, functionsDir("check-items"), process.cwd())).toEqual([])
+  })
+})
+
+describe("doctor reports what will and will not run", () => {
+  it("separates a missing validator from a missing hook", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "supatype-doctor-"))
+    dirs.push(cwd)
+    const ast = extract('  validate: { setupItems: "check-items", sku: "check-sku" }')
+
+    const report = hooksReport(cwd, functionsDir("check-sku"), ast)
+
+    expect(report.validators).toHaveLength(2)
+    expect(report.validatorsMissing.map((v) => v.field)).toEqual(["setupItems"])
+    // A validator problem is not a hook problem: the fix and the consequence differ.
+    expect(report.missing).toEqual([])
+  })
+
+  it("notices a manifest with no validator map, which means nothing is being checked", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "supatype-doctor-"))
+    dirs.push(cwd)
+    mkdirSync(join(cwd, ".supatype"), { recursive: true })
+    writeFileSync(join(cwd, ".supatype", "manifest.json"), JSON.stringify({ hooks: {} }), "utf8")
+
+    const ast = extract('  validate: { setupItems: "check-items" }')
+    const report = hooksReport(cwd, functionsDir("check-items"), ast)
+
+    expect(report.validatorMapMissing).toBe(true)
+  })
+})

package/tests/hooks-generator.test.ts

@@ -210,3 +210,89 @@ export default nope
     expect(output).toContain("comments")
   })
 })
+
+describe("field validators", () => {
+  const VALIDATED_SCHEMA = `
+import type { JSON, Model, Public, UUID } from "@supatype/types"
+
+export type Product = Model<{
+  id: UUID
+  sku: string
+  setupItems: JSON<{ label: string }[]>
+}, {
+  access: { read: Public }
+  validate: { setupItems: "check-setup-items", sku: { function: "check-sku", timeout: 3000 } }
+}>
+`
+
+  it("generates the module for a model that declares only validators", () => {
+    // Validators need the same row types hooks do. A model declaring only validators used to produce
+    // no module at all, which would make `FieldValidator<"product", ...>` fail to resolve.
+    const module = generateHooksModule(astFor(VALIDATED_SCHEMA))
+    expect(module).not.toBeNull()
+    expect(module).toContain("FieldValidator")
+    expect(module).toContain("export function fieldValidator(")
+  })
+
+  it("typechecks with a validator written the way the docs will show it", () => {
+    const dir = mkdtempSync(join(tmpdir(), "supatype-validatorcompile-"))
+    dirs.push(dir)
+
+    const module = generateHooksModule(astFor(VALIDATED_SCHEMA))
+    writeFileSync(join(dir, "hooks.ts"), module ?? "", "utf8")
+    writeFileSync(
+      join(dir, "deno.d.ts"),
+      `declare namespace Deno {
+  const env: { get(key: string): string | undefined }
+}
+`,
+      "utf8",
+    )
+    writeFileSync(
+      join(dir, "handler.ts"),
+      `import { fieldValidator, type FieldValidator } from "./hooks.ts"
+
+// The value is the column's real type, so this narrows without a cast.
+const checkItems: FieldValidator<"product", "setupItems"> = (ctx) => {
+  if (!Array.isArray(ctx.value) || ctx.value.length === 0) {
+    return "At least one setup item is required."
+  }
+  return true
+}
+
+export default fieldValidator(checkItems)
+`,
+      "utf8",
+    )
+    writeFileSync(
+      join(dir, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: {
+          strict: true,
+          exactOptionalPropertyTypes: true,
+          noEmit: true,
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          allowImportingTsExtensions: true,
+          lib: ["ES2022", "DOM"],
+        },
+        include: ["*.ts"],
+      }),
+      "utf8",
+    )
+
+    const tsc = join(__dirname, "..", "..", "..", "node_modules", "typescript", "bin", "tsc")
+    let output = ""
+    try {
+      execFileSync(process.execPath, [tsc, "-p", join(dir, "tsconfig.json")], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      })
+    } catch (err) {
+      const failure = err as { stdout?: string; stderr?: string }
+      output = `${failure.stdout ?? ""}${failure.stderr ?? ""}`
+    }
+    expect(output, "the generated validator surface must compile").toBe("")
+  })
+})

package/tests/local-server-image-env.test.ts

@@ -0,0 +1,93 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { syncComposeImagePins, upsertDevComposeEnv } from "../src/dev-compose.js"
+import {
+  LOCAL_SERVER_DOCKER_IMAGE,
+  usesLocalServerImage,
+} from "../src/compose-local-server-image.js"
+import type { SupatypeProjectConfig } from "../src/project-config.js"
+
+/**
+ * `overrides.server` has to survive the next `.env` write, whichever command makes it.
+ *
+ * The local image reaches compose through one variable, and several code paths rewrite the file
+ * that holds it. When only one of them knew the local image existed, the others removed the key as
+ * an unpinned managed pin: `dev` started the local server, the next `push` deleted the variable,
+ * and compose recreated the container from the published image. Nothing failed, so the symptom was
+ * a contributor testing their own build and running someone else's.
+ */
+
+const dirs: string[] = []
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+/** A project whose `overrides.server` points at a binary beside a Dockerfile. */
+function project(versions?: SupatypeProjectConfig["versions"]): {
+  cwd: string
+  config: SupatypeProjectConfig
+} {
+  const cwd = mkdtempSync(join(tmpdir(), "supatype-local-image-"))
+  dirs.push(cwd)
+  const serverRoot = join(cwd, "server-src")
+  mkdirSync(serverRoot, { recursive: true })
+  writeFileSync(join(serverRoot, "Dockerfile"), "FROM scratch\n", "utf8")
+
+  return {
+    cwd,
+    config: {
+      project: { name: "demo" },
+      ...(versions !== undefined && { versions }),
+      overrides: { server: join(serverRoot, "supatype-server.exe") },
+    } as SupatypeProjectConfig,
+  }
+}
+
+const envOf = (cwd: string): string => readFileSync(join(cwd, ".env"), "utf8")
+
+describe("the locally built server image", () => {
+  it("is recognised from config alone, so no caller has to be told about it", () => {
+    const { cwd, config } = project({ server: "local" })
+    expect(usesLocalServerImage(cwd, config)).toBe(true)
+  })
+
+  it("is not claimed when the override points nowhere near a Dockerfile", () => {
+    const { cwd, config } = project({ server: "local" })
+    const stray = { ...config, overrides: { server: join(cwd, "nope", "server.exe") } }
+    expect(usesLocalServerImage(cwd, stray as SupatypeProjectConfig)).toBe(false)
+  })
+
+  it("is not claimed when versions.server names a release", () => {
+    const { cwd, config } = project({ server: "1.2.3" })
+    expect(usesLocalServerImage(cwd, config)).toBe(false)
+  })
+
+  it("survives an image-pin sync that knows nothing about it", () => {
+    // The exact sequence that broke: `dev` writes the local image, then another command rewrites
+    // `.env` to reconcile pins from `versions`. The second command has no local image of its own,
+    // so the first must not leave the key looking like a pin the second is entitled to remove.
+    const { cwd, config } = project({ server: "local" })
+    writeFileSync(join(cwd, ".env"), "JWT_SECRET=x\n", "utf8")
+
+    upsertDevComposeEnv(cwd, config, "anon-key", "service-key", 54321)
+    expect(envOf(cwd)).toContain(`SUPATYPE_SERVER_IMAGE=${LOCAL_SERVER_DOCKER_IMAGE}`)
+
+    syncComposeImagePins(cwd, { project: { name: "demo" } } as SupatypeProjectConfig)
+    expect(envOf(cwd)).toContain(`SUPATYPE_SERVER_IMAGE=${LOCAL_SERVER_DOCKER_IMAGE}`)
+  })
+
+  it("is cleared once the project stops asking for a local build", () => {
+    // Otherwise compose keeps starting a stale `local-dev` image that nothing rebuilds.
+    const { cwd, config } = project({ server: "local" })
+    writeFileSync(join(cwd, ".env"), "JWT_SECRET=x\n", "utf8")
+    upsertDevComposeEnv(cwd, config, "anon-key", "service-key", 54321)
+
+    const released = { ...config, versions: { server: "1.2.3" } } as SupatypeProjectConfig
+    upsertDevComposeEnv(cwd, released, "anon-key", "service-key", 54321)
+
+    expect(envOf(cwd)).not.toContain(LOCAL_SERVER_DOCKER_IMAGE)
+  })
+})