@supatype/cli 0.3.1 → 0.3.3

package/src/seed.ts

@@ -1,3 +1,22 @@
+/**
+ * What a project's seed file imports.
+ *
+ * Two contracts live here. `sql()` is the old one: the author opens a connection, writes
+ * statements and closes it. It is unchanged and still supported, because every existing
+ * project uses it.
+ *
+ * The rest is the new one. A seed exports a function, the runner hands it a `db` typed from
+ * the project's schema, and the calls it makes are **collected, not executed**: they become
+ * a seed IR document that the engine validates, orders, batches and runs in one
+ * transaction.
+ *
+ * **Nothing here connects to a database, and nothing here builds SQL.** That is the point of
+ * the split: the hard parts, ordering a foreign-key graph, batching, mapping a Postgres
+ * error back to the schema, are written once in the engine rather than once per language.
+ * This file is the part that has to exist per language, and it is deliberately small enough
+ * to be worth writing seven times.
+ */
+
 import pg from "pg"
 
 export interface SeedSql {
@@ -41,3 +60,392 @@ export function sql(connectionString: string): SeedSql {
     },
   })
 }
+
+// --- The expression language ---
+
+/**
+ * A value the database computes, rather than one the seed hardcodes.
+ *
+ * The same operand set the schema's access rules use, serialised the same way. Not a second
+ * vocabulary: forking one for seeds would need a second validator and a second SQL
+ * renderer, and would re-litigate decisions the engine has already made and documented.
+ */
+export type Operand<C extends string = string> =
+  | { kind: "literal"; value: LiteralValue }
+  | { kind: "column"; name: C }
+  | { kind: "now" }
+  | { kind: "startOf"; unit: TruncUnit }
+  | { kind: "ago"; amount: number; unit: TimeUnit }
+  | { kind: "fromNow"; amount: number; unit: TimeUnit }
+  | { kind: "after"; base: Operand<C>; interval: IntervalSpec }
+  | { kind: "before"; base: Operand<C>; interval: IntervalSpec }
+
+export type LiteralValue = string | number | boolean
+
+export type TruncUnit = "day" | "week" | "month" | "year"
+
+export type TimeUnit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years"
+
+/**
+ * A span of time, in any combination of units.
+ *
+ * Multi-unit because a fixture calendar wants "thirty days from now at 09:00", which a
+ * single `{ amount, unit }` cannot say. Components are non-negative: the direction lives in
+ * the operand's name, so that `ago` reads as itself rather than as a double negative.
+ */
+export interface IntervalSpec {
+  years?: number
+  months?: number
+  weeks?: number
+  days?: number
+  hours?: number
+  minutes?: number
+  seconds?: number
+}
+
+/**
+ * A time the database evaluates.
+ *
+ * Its own type so a generated builder can accept it on date-like columns and nowhere else:
+ * `expr.now()` assigned to a title does not compile.
+ */
+export type TimeExpr = Extract<
+  Operand,
+  { kind: "now" | "startOf" | "ago" | "fromNow" | "after" | "before" }
+>
+
+/**
+ * The column's own default.
+ *
+ * Distinct from leaving the field out. Omission means "do not write this column", which on
+ * the update half of an upsert keeps the existing value; this means "put it back to the
+ * default". Both are wanted and only one can be spelled by absence.
+ */
+export interface DefaultExpr {
+  readonly $default: true
+}
+
+const DEFAULT_EXPR: DefaultExpr = { $default: true }
+
+const INTERVAL_UNITS = [
+  "years",
+  "months",
+  "weeks",
+  "days",
+  "hours",
+  "minutes",
+  "seconds",
+] as const
+
+/**
+ * Drop the units nobody asked for, so two equal intervals serialise the same way.
+ *
+ * A negative or fractional component is refused rather than carried. The engine's interval
+ * components are whole and unsigned, so one that is not fails to read as an operand, falls
+ * through to being a plain value, and reaches the database as JSON text in a date column.
+ * That surfaced as `invalid input syntax for type timestamp with time zone`, naming neither
+ * the field nor the real mistake. Here it names both, at the call that made it.
+ */
+function interval(spec: IntervalSpec): IntervalSpec {
+  const out: IntervalSpec = {}
+  for (const unit of INTERVAL_UNITS) {
+    const value = spec[unit]
+    if (value === undefined || value === 0) continue
+    if (!Number.isInteger(value) || value < 0) {
+      throw new TypeError(
+        `An interval's \`${unit}\` must be a whole number and not negative, and this is ${value}. ` +
+          "The direction is in the name: use `ago` or `before` to go backwards.",
+      )
+    }
+    out[unit] = value
+  }
+  return out
+}
+
+function shifted(base: Operand, spec: IntervalSpec | undefined, ahead: boolean): TimeExpr {
+  if (spec === undefined) return base as TimeExpr
+  const amount = interval(spec)
+  if (Object.keys(amount).length === 0) return base as TimeExpr
+  return ahead
+    ? { kind: "after", base, interval: amount }
+    : { kind: "before", base, interval: amount }
+}
+
+/**
+ * Values the database computes.
+ *
+ * Deliberately database-side rather than computed here. A client-computed `daysFromNow(30)`
+ * produces a different instant on every run, so a builder emitting it could never reproduce
+ * a checked-in fixture; and one IR applied to several environments at different times would
+ * give every one of them the same hardcoded instant, which for a fixture calendar is never
+ * what people mean.
+ */
+export const expr = {
+  /** `now()`, optionally shifted forward. */
+  now(after?: IntervalSpec): TimeExpr {
+    return shifted({ kind: "now" }, after, true)
+  },
+  /** `now()` shifted back. */
+  ago(before: IntervalSpec): TimeExpr {
+    return shifted({ kind: "now" }, before, false)
+  },
+  /** The start of the current day, week, month or year, optionally shifted forward. */
+  startOf(unit: TruncUnit, after?: IntervalSpec): TimeExpr {
+    return shifted({ kind: "startOf", unit }, after, true)
+  },
+  /** The start of a period, shifted back. */
+  startOfBefore(unit: TruncUnit, amount: IntervalSpec): TimeExpr {
+    return shifted({ kind: "startOf", unit }, amount, false)
+  },
+  /** The column's own default. */
+  default(): DefaultExpr {
+    return DEFAULT_EXPR
+  },
+} as const
+
+// --- Predicates ---
+
+export type CompareOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like"
+
+/**
+ * A condition on rows, in the schema's own rule language.
+ *
+ * The engine already parses, validates and compiles this tree for every RLS policy it
+ * writes, so a seed condition is that tree scoped to a model rather than anything new. A
+ * person who has written `Eq<"status", Literal<"published">>` in their schema already knows
+ * this language.
+ */
+export type Predicate<C extends string = string> =
+  | { type: "compare"; left: Operand<C>; op: CompareOp; right: Operand<C> }
+  | { type: "any"; rules: Predicate<C>[] }
+  | { type: "all"; rules: Predicate<C>[] }
+  | { type: "not"; rule: Predicate<C> }
+  | { type: "nullCheck"; operand: Operand<C>; isNull: boolean }
+  | { type: "in"; column: C; source: { kind: "literal"; values: LiteralValue[] } }
+
+function compare<C extends string>(column: C, op: CompareOp, value: LiteralValue): Predicate<C> {
+  return {
+    type: "compare",
+    left: { kind: "column", name: column },
+    op,
+    right: { kind: "literal", value },
+  }
+}
+
+export const eq = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "eq", value)
+export const neq = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "neq", value)
+export const gt = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "gt", value)
+export const gte = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "gte", value)
+export const lt = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "lt", value)
+export const lte = <C extends string>(column: C, value: LiteralValue): Predicate<C> =>
+  compare(column, "lte", value)
+export const like = <C extends string>(column: C, pattern: string): Predicate<C> =>
+  compare(column, "like", pattern)
+
+export const isNull = <C extends string>(column: C): Predicate<C> => ({
+  type: "nullCheck",
+  operand: { kind: "column", name: column },
+  isNull: true,
+})
+export const notNull = <C extends string>(column: C): Predicate<C> => ({
+  type: "nullCheck",
+  operand: { kind: "column", name: column },
+  isNull: false,
+})
+
+/** Every rule must hold. */
+export const and = <C extends string>(...rules: Predicate<C>[]): Predicate<C> => ({
+  type: "all",
+  rules,
+})
+
+/** Any one rule holding is enough. */
+export const or = <C extends string>(...rules: Predicate<C>[]): Predicate<C> => ({
+  type: "any",
+  rules,
+})
+
+export const not = <C extends string>(rule: Predicate<C>): Predicate<C> => ({ type: "not", rule })
+
+/**
+ * The column's value is one of these.
+ *
+ * `oneOf` rather than `in`, which is a reserved word and cannot be an identifier.
+ */
+export const oneOf = <C extends string>(
+  column: C,
+  values: readonly LiteralValue[],
+): Predicate<C> => ({
+  type: "in",
+  column,
+  source: { kind: "literal", values: [...values] },
+})
+
+// --- The document a builder produces ---
+
+/** A value produced by an earlier operation in the same document. */
+export interface RefValue {
+  readonly $ref: string
+}
+
+/** An exact decimal, kept as text because JSON has no decimal type. */
+export interface NumericValue {
+  readonly $numeric: string
+}
+
+export type SeedValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly SeedValue[]
+  | RefValue
+  | NumericValue
+  | DefaultExpr
+  | Operand
+  | { readonly [key: string]: SeedValue | undefined }
+
+export type SeedData = Record<string, SeedValue>
+
+export type SeedOperation =
+  | { op: "create"; model: string; id?: string; data: SeedData }
+  | { op: "createMany"; model: string; rows: SeedData[] }
+  | { op: "upsert"; model: string; id?: string; where: SeedData; data: SeedData }
+  | { op: "sql"; text: string; params?: SeedValue[] }
+  | { op: "group"; if?: SeedCondition; operations: SeedOperation[] }
+
+export type SeedCondition =
+  | { kind: "exists"; model: string; where?: Predicate }
+  | { kind: "notExists"; model: string; where?: Predicate }
+  | { kind: "environment"; name: string }
+
+/** One seed document, as the engine reads it. */
+export interface SeedIr {
+  irVersion: 1
+  schemaFingerprint: string
+  operations: SeedOperation[]
+}
+
+// --- What a generated builder plugs into ---
+
+/**
+ * What the runtime needs to know about a model and cannot tell from a value.
+ *
+ * Written by the generator, read by the collector. Three facts, each of which changes how a
+ * value is encoded and none of which is visible at runtime: which columns are exact
+ * decimals, which hold a time, and which fields are relations to what.
+ */
+export interface ModelManifest {
+  model: string
+  table: string
+  /** Columns where a number would lose precision, so the value travels as an exact decimal. */
+  numeric: readonly string[]
+  /** Columns that hold an instant, so a `Date` is rendered as one. */
+  temporal: readonly string[]
+  relations: Readonly<Record<string, { kind: RelationKind; target: string }>>
+}
+
+export type RelationKind = "belongsTo" | "hasOne" | "hasMany" | "manyToMany"
+
+/** What a model exposes on `db`. */
+export interface ModelApi<TCreate, TWhere, TRef> {
+  /** Insert one row, and hand back something later operations can point at. */
+  create(data: TCreate, options?: { id?: string }): TRef
+  /**
+   * Insert many rows of one model in one statement.
+   *
+   * Not sugar for repeated `create`: a per-row API is how a seed of a few thousand rows
+   * becomes a few thousand round trips.
+   */
+  createMany(rows: readonly TCreate[]): void
+  /**
+   * Insert, or update the row the `where` columns already identify.
+   *
+   * The primary operation for a seed, because seeds get re-run and idempotency is the thing
+   * every hand-written one gets wrong.
+   */
+  upsert(args: { where: TWhere; data: TCreate; id?: string }): TRef
+}
+
+/**
+ * Filled in by the generated builder, through declaration merging.
+ *
+ * Empty here so the runtime compiles on its own, and so a project that has not run
+ * `supatype generate` yet gets a loosely typed `db` rather than a module that does not
+ * resolve.
+ */
+export interface SupatypeSeedRegistry {
+  /** Never set. Present so the interface is not empty, which some lint rules refuse. */
+  readonly __generated?: never
+}
+
+type FallbackModel = ModelApi<SeedData, SeedData, Record<string, RefValue>>
+
+type RegisteredModels = SupatypeSeedRegistry extends { models: infer M }
+  ? M
+  : Record<string, FallbackModel>
+
+type RegisteredCondition = SupatypeSeedRegistry extends { condition: infer C }
+  ? C
+  : SeedConditionInput
+
+/** The condition surface, before a generated builder narrows it to this schema's models. */
+export type SeedConditionInput =
+  | { exists: { model: string; where?: Predicate } }
+  | { notExists: { model: string; where?: Predicate } }
+  | { environment: string }
+
+export type SeedDb = RegisteredModels & {
+  /**
+   * Run a block only when the database says so.
+   *
+   * Plain `if` already works for anything decided from the program's own inputs, and should
+   * be preferred. This is for the one thing plain `if` cannot do: branch on database state,
+   * which the builder cannot read because it never connects. The condition travels in the
+   * IR and the engine evaluates it at this position, inside the transaction.
+   */
+  $if(condition: RegisteredCondition, body: () => void): void
+  /**
+   * A raw statement, in the same transaction and the same order as everything else.
+   *
+   * Inside the IR rather than offered as a side channel, so a seed that mixes typed
+   * operations and raw SQL still runs as one thing instead of the author opening a second
+   * connection the engine knows nothing about.
+   */
+  $sql(text: string, params?: readonly SeedValue[]): void
+}
+
+/** What the runner hands a seed's default export. */
+export interface SeedContext {
+  db: SeedDb
+  expr: typeof expr
+  /** Print a line, through the runner's own output rather than straight to stdout. */
+  log: (message: string) => void
+  /** The environment this run targets, when the runner was told one. */
+  environment?: string | undefined
+}
+
+/** What a seed file may ask of the runner. */
+export interface SeedConfig {
+  /** Run this document in a transaction. Default true, and rarely worth changing. */
+  transaction?: boolean
+  /**
+   * Apply this document at most once per environment.
+   *
+   * For a genuine one-time backfill rather than a fixture. Off by default, because seeds
+   * are idempotent upserts by design and skipping one because it ran before would turn
+   * every seed file into a one-shot migration.
+   */
+  runOnce?: boolean
+}
+
+/** The shape a seed module exports. */
+export interface SeedModule {
+  default?: (context: SeedContext) => void | Promise<void>
+  config?: SeedConfig
+}

package/src/self-host-compose.ts

@@ -14,9 +14,10 @@ import {
   usesExternalDatabase,
   type SupatypeProjectConfig,
 } from "./project-config.js"
-import { hasEngineOverride, hasStudioOverride, pinnedVersion, fetchLatestVersion, VERSION_PIN_LOCAL } from "./binary-cache.js"
+import { hasStudioOverride, pinnedVersion, fetchLatestVersion, VERSION_PIN_LOCAL } from "./binary-cache.js"
 import { buildKongDeclarative } from "./kong-config.js"
 import { keyspaceInPostgres } from "./cache-provider.js"
+import { STUDIO_DEV_PORT } from "./studio-dev-server.js"
 import { readEnvFile } from "./env-file.js"
 import { fieldMaskingTierFromProject, type FieldMaskingTier } from "./field-masking-tier.js"
 import { projectHasVersionedModels } from "./model-versioning.js"
@@ -285,8 +286,16 @@ function postgrestDatabaseUrl(config: SupatypeProjectConfig): string {
   return `postgresql://authenticator:${password}@${parsed.hostname}${port}${parsed.pathname}${parsed.search}`
 }
 
-/** Host Vite dev server as seen from Kong inside Docker Compose. */
-export const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002"
+/**
+ * Host Vite dev server as seen from Kong inside Docker Compose.
+ *
+ * Derived from STUDIO_DEV_PORT rather than repeating the number, because the two are one decision.
+ * Held separately they drift, and the drift is invisible: Vite binds the new port, Kong keeps
+ * proxying to the old one, and `/studio/` serves whatever else happens to be listening there. On
+ * the machine this was found, that was an unrelated Next.js app, and every Studio view failed with
+ * a missing sign-in form rather than anything naming a port.
+ */
+export const COMPOSE_STUDIO_HOST_URL = `http://host.docker.internal:${STUDIO_DEV_PORT}`
 
 /** Studio container: always Docker Hub unless SUPATYPE_STUDIO_IMAGE is set in .env. */
 function studioServiceBlock(): string {
@@ -395,7 +404,18 @@ ${studioService}
     : `      - server
       - studio
       - control-plane`
-  const publishDbToHost = !devLocal || hasEngineOverride(config)
+  // The database is always reachable from the host.
+  //
+  // It used to be published in dev only when something was known to need it, which was a host
+  // engine build or a project that had named `SUPATYPE_DEV_DB_PORT`. Seeding is now a host
+  // process: the CLI resolves a connection string and the engine connects over TCP. Under the old
+  // rule a fresh `supatype init` produced a stack whose database nothing on the host could reach,
+  // so the first `supatype seed` got ECONNREFUSED and the remedy was an environment variable
+  // nobody had reason to know about.
+  //
+  // This exposes nothing new: the dev port below is bound to `127.0.0.1`, so it is reachable from
+  // this machine and from nowhere else.
+  const publishDbToHost = true
   const dbPorts = publishDbToHost
     ? devLocal
       ? `    ports:
@@ -437,6 +457,15 @@ ${studioService}
     volumes:
       - storage-data:/data
       - ${SEAWEED_CONFIG_MOUNT}:/etc/seaweedfs/s3.json:ro
+    healthcheck:
+      # Any HTTP status line means the S3 endpoint is listening, which is the whole question.
+      # Success cannot be "HTTP 200": an unauthenticated GET on the root answers 403 by design,
+      # because the anonymous identity is deliberately absent from s3.json.
+      test: ["CMD-SHELL", "wget -q -S -O /dev/null http://127.0.0.1:8333 2>&1 | grep -q 'HTTP/'"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+      start_period: 5s
 ${seaweedPorts}`
   const kongTlsEnv = tlsEnabled
     ? `      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
@@ -491,6 +520,21 @@ ${keyspaceInPg ? "" : "  valkey-data:\n"}`
 `
   const dbDependency = external ? "" : `    depends_on:\n${dbDependencyClause}`
 
+  // Storage waits for the object store, not only the database.
+  //
+  // seaweedfs had no healthcheck and nothing depended on it, so compose started it alongside
+  // storage rather than before it. Storage would then accept a bucket creation before seaweedfs
+  // was listening, and every bucket in the schema failed with `connect ECONNREFUSED <ip>:8333`
+  // while the metadata row was written anyway. Measured on a live stack: seaweedfs started twelve
+  // minutes after storage with RestartCount 0, so it was ordered late rather than crashing.
+  //
+  // A later push succeeds, which is exactly what made it read as an intermittent mystery. It
+  // lands on the first push after a stack comes up, which is the first push a new user ever runs.
+  const storageDependency = `    depends_on:
+${dbDependencyClause}      seaweedfs:
+        condition: service_healthy
+`
+
   // Realtime, omitted entirely when the project has turned it off.
   //
   // Not started-and-disabled: the service degrades gracefully on its own (it reports the reason on
@@ -676,7 +720,7 @@ ${dbDependency}
       S3_ACCESS_KEY: ${OBJECT_STORE_ACCESS_KEY}
       S3_SECRET_KEY: ${OBJECT_STORE_SECRET_KEY}
       S3_FORCE_PATH_STYLE: "true"
-${dbDependency}
+${storageDependency}
   functions-worker:
     image: \${SUPATYPE_FUNCTIONS_WORKER_IMAGE:-supatype/functions-worker:latest}
     expose:
@@ -705,6 +749,18 @@ ${dbDependency}
       # each one able to read past every access rule in the schema.
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
       SUPATYPE_SERVICE_ROLE_ROUTES: "${serviceRoleRoutes(config).join(",")}"
+      # A direct database connection for functions, off unless asked for.
+      #
+      # The worker reads SUPATYPE_DB_URL and exposes it as \`ctx.dbUrl\`, and nothing here ever set
+      # it, so the field was permanently undefined on self-host and a function reaching for it got
+      # no value and no explanation.
+      #
+      # Deliberately its own variable rather than the project's DATABASE_URL. That one is the owner
+      # DSN every service already uses, and wiring it through by default would hand every function
+      # a connection that bypasses access rules, field masking and model hooks, none of which live
+      # in the database. Naming a separate variable makes it a decision: set it to the owner URL
+      # and accept that, or to a role you restricted yourself.
+      SUPATYPE_DB_URL: \${SUPATYPE_FUNCTIONS_DB_URL:-}
       STRIPE_SECRET_KEY: \${STRIPE_SECRET_KEY:-}
       STRIPE_WEBHOOK_SECRET: \${STRIPE_WEBHOOK_SECRET:-}
       SITE_URL: \${SITE_URL:-\${API_EXTERNAL_URL:-${externalUrlFallback}}}
@@ -730,6 +786,12 @@ ${realtimeBlock}
 ${dbDependency}
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     # The server runs its migrations at boot on a connection of their own,
     # and that path does not wait out a database that is still in recovery:
     # it exits. Waiting for db to report healthy is not enough, because
@@ -798,7 +860,7 @@ ${appEnv}
       SUPATYPE_SMTP_ADMIN_EMAIL: \${SUPATYPE_SMTP_ADMIN_EMAIL:-}
       SUPATYPE_SMTP_SENDER_NAME: \${SUPATYPE_SMTP_SENDER_NAME:-}
       SUPATYPE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
-${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
+${devLocal ? "      STUDIO_OPEN_DEV: \"${STUDIO_OPEN_DEV:-1}\"\n" : ""}
     depends_on:
 ${dbDependencyClause}${keyspaceInPg ? "" : "      valkey:\n        condition: service_started\n"}      postgrest:
         condition: service_started
@@ -819,6 +881,12 @@ ${objectStoreBlock}
     working_dir: /project
 ${dbDependency}${studioBlock}${valkeyBlock}${tlsHintComment}  kong:
     image: kong:3.6
+    # host.docker.internal is a Docker Desktop name. On Linux it does not resolve unless it is
+    # mapped, so a project proxying the site or Studio to something on the host worked on macOS
+    # and Windows and failed on Linux with nothing reaching the app. host-gateway is Docker's own
+    # alias for the host, and needs 20.10, which this stack already requires.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       KONG_DATABASE: "off"
       KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml

package/src/strict.ts

@@ -0,0 +1,40 @@
+/**
+ * Strict mode: a degraded path is a failure rather than a warning.
+ *
+ * Every fallback in this CLI exists because giving up would serve a person at a terminal worse
+ * than carrying on: the in-compose engine when the CDN cannot be reached, SHA256-only verification
+ * when no key is embedded, a bucket that could not be reached from the host but works from inside
+ * the network. Each is the right default interactively.
+ *
+ * In CI the trade runs the other way. A run that limps reports success, and the thing it quietly
+ * skipped is precisely the thing nobody tests again.
+ *
+ * This is not hypothetical. On 2026-09-24 three integration jobs failed on assertions about
+ * validators and served SPAs, and the cause in all three was an engine download refused twenty
+ * lines earlier and warned about. The same fallback made a local from-zero run look like a clean
+ * pass while the host engine path was never exercised at all.
+ */
+
+/** True when the caller has asked for degraded paths to fail. */
+export function strict(): boolean {
+  return process.env["SUPATYPE_STRICT"] === "1"
+}
+
+/**
+ * Report a path that worked less well than intended.
+ *
+ * Throws under `SUPATYPE_STRICT=1`, so a CI job cannot pass over it. Warns otherwise, because
+ * interactively a working stack and a note beats an abort.
+ *
+ * `what` names the capability that degraded, not the error: the reader needs to know which feature
+ * they are now without. `detail` carries the cause.
+ */
+export function degraded(what: string, detail: string): void {
+  const message = `${what}: ${detail}`
+  if (strict()) {
+    throw new Error(
+      `${message}\nSUPATYPE_STRICT=1 is set, so a degraded path fails rather than warns.`,
+    )
+  }
+  console.warn(`[supatype] ${message}`)
+}

package/src/studio-dev-server.ts

@@ -2,8 +2,18 @@ import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { ProcessManager } from "./process-manager.js"
 
-/** Vite dev server port when `overrides.studio` is set. */
-export const STUDIO_DEV_PORT = 3002
+/**
+ * Vite dev server port when `overrides.studio` is set.
+ *
+ * Overridable because it is bound with `--strictPort`, so anything else already on 3002 does not
+ * make Vite pick another port, it makes Studio fail to start and be restarted every thirty seconds
+ * for the life of the session. 3002 is an ordinary port for a local app to be sitting on, and the
+ * only signal is a Vite stack trace in among the compose output.
+ *
+ * Only the `overrides.studio` path is affected, so this is a contributor's papercut rather than a
+ * user's: an ordinary `supatype dev` serves Studio from its container.
+ */
+export const STUDIO_DEV_PORT = Number(process.env["SUPATYPE_STUDIO_DEV_PORT"]) || 3002
 
 export interface StudioDevServerOptions {
   cwd: string