@supatype/cli 0.1.6 → 0.1.9

package/src/docker-postgres.ts

@@ -1,5 +1,5 @@
 /**
- * docker-postgres — manage a supatype/postgres Docker container for local dev.
+ * docker-postgres: manage a supatype/postgres Docker container for local dev.
  *
  * Used by `supatype dev` when database.provider = "docker".
  * The container is named supatype-{projectName} and persists data in a
@@ -11,7 +11,7 @@ import { spawnSync } from "node:child_process"
 export interface DockerPgOptions {
   /** Docker image to run. Defaults to supatype/postgres:latest. */
   image: string
-  /** Project name — used to derive the container and volume names. */
+  /** Project name: used to derive the container and volume names. */
   projectName: string
   /** Host port to bind to container's 5432. */
   port: number
@@ -85,7 +85,7 @@ export function dockerPgStart(opts: DockerPgOptions): void {
 }
 
 /**
- * Stop the container (fast — does not remove it or the data volume).
+ * Stop the container (fast, does not remove it or the data volume).
  * Safe to call even if the container is not running.
  */
 export function dockerPgStop(projectName: string): void {
@@ -120,7 +120,7 @@ export function dockerPgPostInitServing(logs: string): boolean {
 
   const initDone = logs.lastIndexOf("PostgreSQL init process complete")
   if (initDone === -1) {
-    // Reused data volume — this run did not re-run entrypoint init.
+    // Reused data volume: this run did not re-run entrypoint init.
     return true
   }
   return initDone < lastReady
@@ -240,7 +240,7 @@ export function dockerDbUrl(projectName: string, port: number, password = DEFAUL
 /**
  * DB URL for processes sharing the Postgres container network namespace
  * (supatype-server migrate in a one-shot container). Uses loopback inside the
- * container where pg_hba grants trust — avoids host-published-port SCRAM/SSL issues.
+ * container where pg_hba grants trust, avoids host-published-port SCRAM/SSL issues.
  */
 export function dockerPgLoopbackDbUrl(projectName: string, password = DEFAULT_DEV_PASSWORD): string {
   return `postgres://${PG_USER}:${password}@127.0.0.1:5432/${projectName}?sslmode=disable`
@@ -254,7 +254,7 @@ export const DEFAULT_SERVER_DOCKER_IMAGE = "supatype/server:latest"
 
 /**
  * Run `supatype-server migrate` on the Postgres container network (loopback trust).
- * Used on Windows + database.provider docker — host-published :5432 breaks libpq TLS there.
+ * Used on Windows + database.provider docker, host-published :5432 breaks libpq TLS there.
  */
 export function runGotrueMigrationsViaDocker(
   pgContainerName: string,

package/src/docker-runtime.ts

@@ -1,5 +1,5 @@
 /**
- * Docker daemon availability — used before `docker compose` and other docker CLI calls.
+ * Docker daemon availability: used before `docker compose` and other docker CLI calls.
  */
 
 import { spawnSync } from "node:child_process"
@@ -41,7 +41,7 @@ export function probeDockerDaemon(): DockerDaemonProbe {
   const versionStderr = (version.stderr ?? "").trim()
   const versionDetail = `${versionStderr}${version.stdout ?? ""}`.trim()
 
-  // No client version — CLI missing or broken.
+  // No client version: CLI missing or broken.
   if (!clientVersion) {
     return {
       ok: false,
@@ -51,7 +51,7 @@ export function probeDockerDaemon(): DockerDaemonProbe {
   }
 
   // Client is present but daemon refused (paused/stopped). `docker info` can hang
-  // while paused on Docker Desktop — use the version stderr and skip info.
+  // while paused on Docker Desktop, use the version stderr and skip info.
   if (version.status !== 0 && versionStderr) {
     return { ok: false, reason: "daemon_unavailable", detail: versionStderr }
   }
@@ -104,7 +104,7 @@ function dockerUnavailableHints(probe: Extract<DockerDaemonProbe, { ok: false }>
   return hints
 }
 
-/** @deprecated Tests only — use `reportDockerUnavailable`. */
+/** @deprecated Tests only: use `reportDockerUnavailable`. */
 export function formatDockerUnavailableMessage(
   probe: Extract<DockerDaemonProbe, { ok: false }>,
 ): string {
@@ -142,7 +142,7 @@ export function reportDockerUnavailable(
 export function requireDockerDaemon(opts?: DockerReportOptions): void {
   const probe = probeDockerDaemon()
   if (probe.ok) return
-  // Dev TUI patches console — restore stderr before printing a fatal message.
+  // Dev TUI patches console, restore stderr before printing a fatal message.
   if (getActiveDevSession()) {
     endDevSession()
   }

package/src/engine-client.ts

@@ -1,5 +1,5 @@
 /**
- * engine-client.ts — subprocess-based engine invocation.
+ * engine-client.ts: subprocess-based engine invocation.
  *
  * Replaces the former HTTP-based engine client (Docker container API).
  * All callers use the same interface; only the transport changed.
@@ -99,7 +99,7 @@ async function getEngineBin(): Promise<string> {
     // Otherwise (no valid project config) fall through to default cache scan.
   }
 
-  // No config found — scan the cache for any available engine binary.
+  // No config found: scan the cache for any available engine binary.
   const platform = currentPlatform()
   const engineCacheDir = join(homedir(), ".supatype", "cache", "engine")
   try {
@@ -208,7 +208,7 @@ export async function engineRequest<T = unknown>(
   try {
     return JSON.parse(result.stdout) as T
   } catch {
-    // Non-JSON stdout — return as message.
+    // Non-JSON stdout: return as message.
     return { message: result.stdout.trim() } as T
   }
 }

package/src/engine-push-output.ts

@@ -43,7 +43,7 @@ export function parseEnginePushOutput(output: string): EnginePushResult | null {
 export function formatEnginePushMessage(result: EnginePushResult): string {
   if (result.status === "up_to_date") {
     if (result.admin_refreshed) {
-      return "Schema up to date — Studio metadata synced."
+      return "Schema up to date, Studio metadata synced."
     }
     return "Schema up to date."
   }

package/src/ensure-binary.ts

@@ -11,8 +11,26 @@ import {
   type Component,
 } from "./binary-cache.js"
 import { isDownloadInProgress, waitForComponentDownload } from "./binary-download-lock.js"
+import { currentLibc } from "./cli-artifacts.js"
 import type { SupatypeProjectConfig } from "./project-config.js"
 
+/**
+ * Components are published for glibc only, so on Alpine the CLI itself runs (it has a musl
+ * build) while everything it downloads cannot start. Said once, before the first download,
+ * because the alternative is a dynamic loader error naming a file the user never asked for.
+ */
+let warnedAboutMusl = false
+function warnIfMusl(component: Component): void {
+  if (warnedAboutMusl || currentLibc() !== "musl") return
+  warnedAboutMusl = true
+  console.warn(
+    `[supatype] This is a musl system (Alpine). Component binaries such as ${component} are ` +
+      "published for glibc only, so they may fail to start here.\n" +
+      "[supatype] Use a glibc image (for example node:22-bookworm) for local stacks, or run " +
+      "against a remote target with `supatype link`.",
+  )
+}
+
 export async function ensureBinary(
   component: Component,
   config: SupatypeProjectConfig,
@@ -26,6 +44,8 @@ export async function ensureBinary(
     }
   }
 
+  warnIfMusl(component)
+
   const version = await resolveVersionFor(component, config)
   const platform = currentPlatform()
 

package/src/ensure-component-binaries.ts

@@ -37,7 +37,7 @@ export async function ensureComponentBinaries(
   const list = describeRequiredHostComponents(components)
   if (provider === "docker") {
     info(
-      `Preparing host CLI tools (${list}) — Compose still runs Postgres and the API stack.`,
+      `Preparing host CLI tools (${list}), Compose still runs Postgres and the API stack.`,
     )
   } else {
     info(`Preparing local runtime components (${list})…`)

package/src/env-file.ts

@@ -1,23 +1,162 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 
-/** Merge key/value updates into a project `.env` without dropping unrelated lines. */
+/**
+ * Marks a value the CLI wrote from `versions` in `supatype.config.ts`.
+ *
+ * Provenance, so that removing a pin from config can clean up the stale image reference it left
+ * behind *without* deleting a value the operator wrote by hand. Before this, the image keys derived
+ * from config were removed unconditionally on every compose run: an operator could override
+ * `SUPATYPE_REALTIME_IMAGE` from `.env` and could not override `SUPATYPE_SERVER_IMAGE`, because the
+ * latter is derivable from a pin and the former is not. Same file, same shape, different rules.
+ */
+export const MANAGED_MARKER = "# supatype:managed, value from versions in supatype.config.ts"
+
+interface EnvLine {
+  /** `KEY` for an assignment, undefined for comments and blanks. */
+  key?: string
+  text: string
+  /** True when the preceding line is the managed marker. */
+  managed: boolean
+}
+
+function parseLines(text: string): EnvLine[] {
+  const out: EnvLine[] = []
+  if (text === "") return out
+  let markerPending = false
+  // A file ending in a newline yields a final empty element; keeping it would put a blank line
+  // between the existing content and anything appended.
+  const raws = text.split(/\r?\n/)
+  while (raws.length > 0 && raws[raws.length - 1] === "") raws.pop()
+  for (const raw of raws) {
+    const trimmed = raw.trim()
+    if (trimmed === MANAGED_MARKER) {
+      markerPending = true
+      out.push({ text: raw, managed: false })
+      continue
+    }
+    const eq = raw.indexOf("=")
+    const key = eq > 0 ? raw.slice(0, eq).trim() : undefined
+    const isAssignment = key !== undefined && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
+    out.push({ ...(isAssignment && { key }), text: raw, managed: isAssignment && markerPending })
+    if (!isAssignment && trimmed !== "") markerPending = false
+    else if (isAssignment) markerPending = false
+  }
+  return out
+}
+
+export interface UpsertOptions {
+  /**
+   * Keys to delete: but only where the CLI wrote them (see [`MANAGED_MARKER`]). A hand-written value
+   * is left alone, because the operator putting an image tag in `.env` is the documented way to run a
+   * local build and deleting it silently sent them back to `:latest`.
+   */
+  removeManaged?: readonly string[]
+  /** Keys in `updates` that come from config and may later be cleaned up. Written with the marker. */
+  managed?: readonly string[]
+  /** Keys to delete outright, whoever wrote them. For secrets being rotated out. */
+  remove?: readonly string[]
+}
+
+/**
+ * Merge key/value updates into a project `.env`.
+ *
+ * Comments, blank lines and ordering are preserved: this file is edited by hand, and the previous
+ * implementation rebuilt it from the assignments alone, so every comment an operator had written
+ * disappeared the first time they ran anything that touched `.env`.
+ */
 export function upsertEnvFile(
   cwd: string,
   updates: Record<string, string>,
-  removeKeys: readonly string[] = [],
+  options: UpsertOptions | readonly string[] = {},
 ): void {
+  // Historically the third argument was a plain list of keys to remove unconditionally.
+  const opts: UpsertOptions = Array.isArray(options)
+    ? { remove: options as readonly string[] }
+    : (options as UpsertOptions)
+  const removeManaged = new Set(opts.removeManaged ?? [])
+  const removeAlways = new Set(opts.remove ?? [])
+  const managed = new Set(opts.managed ?? [])
+
   const envPath = join(cwd, ".env")
   const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
-  const keys = new Set([...Object.keys(updates), ...removeKeys])
-  const kept = existing
-    .split("\n")
-    .filter((line) => {
-      const key = line.split("=")[0]?.trim()
-      return key && line.includes("=") && !keys.has(key)
-    })
-  const merged = [...kept, ...Object.entries(updates).map(([key, value]) => `${key}=${value}`)]
-  writeFileSync(envPath, `${merged.join("\n").trimEnd()}\n`, "utf8")
+  const lines = parseLines(existing)
+
+  const written = new Set<string>()
+  const kept: EnvLine[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const key = line.key
+
+    if (key === undefined) {
+      kept.push(line)
+      continue
+    }
+
+    if (removeAlways.has(key) || (removeManaged.has(key) && line.managed)) {
+      // Drop the marker that introduced it, so no orphan comment is left behind.
+      if (line.managed && kept[kept.length - 1]?.text.trim() === MANAGED_MARKER) kept.pop()
+      continue
+    }
+
+    if (key in updates) {
+      const wantsMarker = managed.has(key)
+      if (wantsMarker && kept[kept.length - 1]?.text.trim() !== MANAGED_MARKER) {
+        kept.push({ text: MANAGED_MARKER, managed: false })
+      }
+      if (!wantsMarker && line.managed && kept[kept.length - 1]?.text.trim() === MANAGED_MARKER) {
+        kept.pop()
+      }
+      kept.push({ key, text: `${key}=${updates[key]}`, managed: wantsMarker })
+      written.add(key)
+      continue
+    }
+
+    kept.push(line)
+  }
+
+  const appended: string[] = []
+  for (const [key, value] of Object.entries(updates)) {
+    if (written.has(key)) continue
+    if (managed.has(key)) appended.push(MANAGED_MARKER)
+    appended.push(`${key}=${value}`)
+  }
+
+  const body = [...kept.map((l) => l.text), ...appended].join("\n")
+  writeFileSync(envPath, `${body.replace(/\n+$/, "")}\n`, "utf8")
+}
+
+/**
+ * Parse a project `.env` into key/value pairs.
+ *
+ * Deliberately small: `KEY=value`, `#` comments, one optional layer of surrounding quotes. No
+ * interpolation and no `export` handling, because Compose's own parser does not do those either and
+ * a `.env` that means two different things depending on who reads it is worse than a limited one.
+ */
+export function readEnvFile(cwd: string): Record<string, string> {
+  const envPath = join(cwd, ".env")
+  if (!existsSync(envPath)) return {}
+
+  const out: Record<string, string> = {}
+  for (const line of readFileSync(envPath, "utf8").split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue
+    const eq = trimmed.indexOf("=")
+    if (eq <= 0) continue
+    const key = trimmed.slice(0, eq).trim()
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue
+    let value = trimmed.slice(eq + 1).trim()
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1)
+    }
+    out[key] = value
+  }
+  return out
 }
 
 export function readEnvValue(cwd: string, key: string, fallback: string): string {
@@ -29,6 +168,13 @@ export function readEnvValue(cwd: string, key: string, fallback: string): string
   return fallback
 }
 
+/** Whether `.env` carries a non-empty value for `key`. Distinguishes absent from defaulted. */
+export function hasEnvValue(cwd: string, key: string): boolean {
+  const envPath = join(cwd, ".env")
+  if (!existsSync(envPath)) return false
+  return new RegExp(`^${key}=(.+)$`, "m").test(readFileSync(envPath, "utf8"))
+}
+
 export function readEnvInt(cwd: string, key: string): number | null {
   const raw = readEnvValue(cwd, key, "")
   if (!raw) return null

package/src/field-masking-tier.ts

@@ -0,0 +1,107 @@
+/**
+ * Which mechanism will enforce this project's per-column rules, decided offline.
+ *
+ * The engine makes the same decision at push time by asking the database whether `supatype_mask` is
+ * installed. The CLI has to answer earlier: it writes `PGRST_DB_SCHEMA` when it generates compose,
+ * before any database necessarily exists. It can, because the extension needs
+ * `shared_preload_libraries` and a compiled library on the host, so exactly one path ships it,
+ * `supatype/postgres`. Everything else gets the view tier:
+ *
+ * | Config                                       | Ships the extension | Tier      |
+ * | -------------------------------------------- | ------------------- | --------- |
+ * | `database.provider: "docker"`                | yes                 | extension |
+ * | `provider: native`                           | no                  | views     |
+ * | `database.external`                          | no                  | views     |
+ * | `provider: docker` + `database.image` override | no                | views     |
+ *
+ * Deliberately **not** "is the database external": a native `supatype dev` has no extension either,
+ * and treating it as tier 1 would point PostgREST at a schema whose tables the API roles no longer
+ * hold privileges on: every request denied.
+ *
+ * The one case this cannot call is a self-managed Postgres where the operator compiled and installed
+ * the extension themselves and points at it with `database.external`. They set `schema.api_schemas`
+ * explicitly; `supatype db check` reports the mismatch either way.
+ */
+
+import { existsSync } from "node:fs"
+// Statically imported: these packages are ESM, where `require` does not exist. The first attempt used
+// it for a lazy import and every command that generates compose would have thrown at runtime, caught
+// by the tests that run the built binary rather than the source.
+import { loadSchemaAst } from "./config.js"
+export { nativeMaskLibraryPresent } from "./postgres-ctl.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+import {
+  resolveRuntimeProvider,
+  schemaPathFromProject,
+  usesExternalDatabase,
+} from "./project-config.js"
+
+export type FieldMaskingTier = "none" | "extension" | "views"
+
+
+/** Postgres image this project would run, when it runs one at all. */
+function postgresImage(config: SupatypeProjectConfig): string | undefined {
+  if (usesExternalDatabase(config)) return undefined
+  if (config.database.provider !== "docker" && resolveRuntimeProvider(config) !== "docker") {
+    return undefined
+  }
+  return config.database.image?.trim() || "supatype/postgres:latest"
+}
+
+/** True when the Postgres this project runs is one that carries `supatype_mask`. */
+export function imageShipsMaskExtension(config: SupatypeProjectConfig): boolean {
+  const image = postgresImage(config)
+  return image !== undefined && /^supatype\/postgres(:|$)/.test(image)
+}
+
+/**
+ * Whether any model masks a column.
+ *
+ * Read from the extracted AST rather than the config, because that is where field rules live. Shaped
+ * loosely on purpose: the CLI's AST type carries `platform.access` as an opaque record, and this only
+ * needs to know whether a `fields` map is present and non-empty.
+ */
+export function schemaHasFieldRules(ast: unknown): boolean {
+  const models = (ast as { models?: unknown[] } | null)?.models
+  if (!Array.isArray(models)) return false
+  return models.some((model) => {
+    const access = (
+      model as { annotations?: { platform?: { access?: Record<string, unknown> } } } | null
+    )?.annotations?.platform?.access
+    const fields = access?.["fields"]
+    return typeof fields === "object" && fields !== null && Object.keys(fields).length > 0
+  })
+}
+
+/** The tier this project's next push will use. */
+export function fieldMaskingTier(
+  config: SupatypeProjectConfig,
+  ast: unknown,
+  /** Set on the native path once the Postgres install is known, see [`nativeMaskLibraryPresent`]. */
+  maskLibraryPresent?: boolean,
+): FieldMaskingTier {
+  if (!schemaHasFieldRules(ast)) return "none"
+  if (maskLibraryPresent === true) return "extension"
+  return imageShipsMaskExtension(config) ? "extension" : "views"
+}
+
+/**
+ * The tier for a project on disk, loading its schema to see whether any column is masked.
+ *
+ * A schema that fails to load falls back to `"none"`, the default exposed-schema list. Deciding the
+ * tier is the wrong moment to report a syntax error, and `push`/`dev` do it properly moments later
+ * with the file and line.
+ */
+export function fieldMaskingTierFromProject(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  maskLibraryPresent?: boolean,
+): FieldMaskingTier {
+  try {
+    const schemaPath = schemaPathFromProject(config, cwd)
+    if (!existsSync(schemaPath)) return "none"
+    return fieldMaskingTier(config, loadSchemaAst(schemaPath, cwd), maskLibraryPresent)
+  } catch {
+    return "none"
+  }
+}

package/src/functions-deno-types.ts

@@ -0,0 +1,188 @@
+/**
+ * Scaffold Deno IDE types for edge functions so tsserver / Cursor stop
+ * reporting "Cannot find name 'Deno'" under the project root tsconfig.
+ *
+ * We ship a curated ambient declaration (not `@types/deno` at the app root):
+ * installing `@types/deno` as a project dependency auto-includes it in the
+ * whole app when root `tsconfig` omits `"types"`, which pollutes React/Next.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs"
+import { join, relative } from "node:path"
+import ts from "typescript"
+
+const MARKER = "Supatype edge functions (IDE / tsserver)"
+
+/** Ambient Deno types written into `functions/deno.d.ts`. */
+export function functionsDenoAmbientSource(): string {
+  return `/**
+ * ${MARKER}.
+ * Runtime is Deno; this file covers APIs edge functions commonly use.
+ * Do not add \`@types/deno\` to the app package.json, it leaks into the
+ * whole project when root tsconfig has no \`"types"\` field.
+ *
+ * Optional: for the full Deno API, install the Deno VS Code/Cursor extension
+ * and open \`functions/\` as a Deno-enabled workspace folder.
+ */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+interface DenoEnv {
+  /** Returns the value of the environment variable, or \`undefined\` if unset. */
+  get(key: string): string | undefined
+  set(key: string, value: string): void
+  delete(key: string): void
+  has(key: string): boolean
+  toObject(): { [key: string]: string }
+}
+
+declare namespace Deno {
+  const env: DenoEnv
+
+  namespace errors {
+    class NotFound extends Error {}
+    class PermissionDenied extends Error {}
+  }
+
+  interface DirEntry {
+    name: string
+    isFile: boolean
+    isDirectory: boolean
+    isSymlink: boolean
+  }
+
+  interface FileInfo {
+    isFile: boolean
+    isDirectory: boolean
+    isSymlink: boolean
+    size: number
+    mtime: Date | null
+  }
+
+  function readDir(path: string): AsyncIterable<DirEntry>
+  function readTextFile(path: string): Promise<string>
+  function stat(path: string): Promise<FileInfo>
+
+  function serve(
+    options: { port: number; hostname?: string; onListen?: (params: { hostname: string; port: number }) => void },
+    handler: (req: Request) => Response | Promise<Response>,
+  ): void
+}
+`
+}
+
+/** `functions/tsconfig.json`: owns function files so the app config can exclude them. */
+export function functionsTsConfigSource(): string {
+  return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "types": []
+  },
+  "include": ["./**/*.ts", "./deno.d.ts"]
+}
+`
+}
+
+export type FunctionsDenoTypesResult = {
+  wroteDenoDts: boolean
+  wroteTsconfig: boolean
+  rootExclude: "updated" | "already" | "missing" | "manual"
+  hints: string[]
+}
+
+/**
+ * Ensure `functions/deno.d.ts` + `functions/tsconfig.json` exist, and try to
+ * exclude `functions` from the project-root `tsconfig.json`.
+ */
+export function ensureFunctionsDenoTypes(
+  projectRoot: string,
+  functionsDir: string,
+): FunctionsDenoTypesResult {
+  mkdirSync(functionsDir, { recursive: true })
+
+  const denoDtsPath = join(functionsDir, "deno.d.ts")
+  const tsconfigPath = join(functionsDir, "tsconfig.json")
+
+  let wroteDenoDts = false
+  if (!existsSync(denoDtsPath)) {
+    writeFileSync(denoDtsPath, functionsDenoAmbientSource(), "utf8")
+    wroteDenoDts = true
+  }
+
+  let wroteTsconfig = false
+  if (!existsSync(tsconfigPath)) {
+    writeFileSync(tsconfigPath, functionsTsConfigSource(), "utf8")
+    wroteTsconfig = true
+  }
+
+  const rootExclude = ensureRootTsconfigExcludesFunctions(projectRoot)
+  const hints: string[] = []
+  const fnRel = toPosix(relative(projectRoot, functionsDir)) || "functions"
+
+  if (rootExclude === "manual") {
+    hints.push(
+      `Add "functions" to the root tsconfig.json "exclude" array so the app checker skips ${fnRel}/.`,
+    )
+  } else if (rootExclude === "missing") {
+    hints.push(
+      `If you add a root tsconfig.json, exclude "${fnRel}" (or "functions") so app typecheck stays separate.`,
+    )
+  }
+
+  return { wroteDenoDts, wroteTsconfig, rootExclude, hints }
+}
+
+function ensureRootTsconfigExcludesFunctions(
+  projectRoot: string,
+): FunctionsDenoTypesResult["rootExclude"] {
+  const path = join(projectRoot, "tsconfig.json")
+  if (!existsSync(path)) return "missing"
+
+  const raw = readFileSync(path, "utf8")
+  const parsed = ts.parseConfigFileTextToJson(path, raw)
+  if (parsed.error || parsed.config === undefined || typeof parsed.config !== "object") {
+    return "manual"
+  }
+
+  const cfg = parsed.config as { exclude?: unknown }
+  const exclude = Array.isArray(cfg.exclude) ? cfg.exclude.map(String) : []
+  if (exclude.some(isFunctionsExcludeEntry)) return "already"
+
+  try {
+    const asJson = JSON.parse(raw) as { exclude?: string[] }
+    asJson.exclude = [...(Array.isArray(asJson.exclude) ? asJson.exclude : []), "functions"]
+    writeFileSync(path, `${JSON.stringify(asJson, null, 2)}\n`, "utf8")
+    return "updated"
+  } catch {
+    // JSONC / trailing commas, try a conservative string splice into an existing exclude array.
+    if (/"exclude"\s*:\s*\[/.test(raw)) {
+      const next = raw.replace(/("exclude"\s*:\s*\[)/, `$1\n    "functions",`)
+      if (next !== raw) {
+        writeFileSync(path, next, "utf8")
+        return "updated"
+      }
+    }
+    return "manual"
+  }
+}
+
+function isFunctionsExcludeEntry(entry: string): boolean {
+  const n = entry.replace(/\\/g, "/").replace(/^\.\//, "")
+  return n === "functions" || n === "functions/**" || n.startsWith("functions/")
+}
+
+function toPosix(path: string): string {
+  return path.replace(/\\/g, "/")
+}

package/src/functions-router-gen.ts

@@ -58,7 +58,7 @@ export function generateFunctionsRouterSource(
   )
   const routes = fns.map((fn, i) => `  "${fn.name}": handler_${i},`)
 
-  return `// Auto-generated — do not edit (regenerated by supatype dev / functions serve)
+  return `// Auto-generated: do not edit (regenerated by supatype dev / functions serve)
 ${imports.join("\n")}
 
 const handlers: Record<string, (req: Request) => Response | Promise<Response>> = {