@supatype/cli 0.1.7 → 0.1.10

package/src/commands/push.ts

@@ -167,7 +167,7 @@ async function pushViaTarget(
     await generateTypesLocal(ast, config)
     await provisionLocalStorage(ast, config)
 
-    // Local Studio only — a cloud/self-host push must not advertise the local
+    // Local Studio only: a cloud/self-host push must not advertise the local
     // gateway URL from config, which may not even be running.
     const baseUrl = (serverBaseUrl(config) ?? "").replace(/\/$/, "")
     if (baseUrl) {
@@ -191,7 +191,7 @@ async function pushViaTarget(
  * into a 503.
  *
  * The handler types are written locally as well. A project pushing to cloud still edits its hooks on
- * this machine, and `hooks/_supatype/hooks.ts` is what makes them typed — it is generated, never
+ * this machine, and `hooks/_supatype/hooks.ts` is what makes them typed, it is generated, never
  * committed, so a fresh clone that has only ever pushed to cloud would otherwise have no types at all.
  */
 async function deployHooksToTarget(
@@ -285,7 +285,7 @@ async function writeLocalAdminConfig(ast: unknown, config: SupatypeProjectConfig
  * Stop the push when a declared hook names a function that is not there.
  *
  * A hook is only enforcement if it runs. A typo'd name would extract cleanly, reach the manifest, and
- * then never fire — so the write it was meant to validate would succeed and look fine. Cheaper to
+ * then never fire: so the write it was meant to validate would succeed and look fine. Cheaper to
  * fail here, naming the directory searched.
  */
 /**

package/src/commands/self-host.ts

@@ -1,5 +1,5 @@
 /**
- * self-host commands — manage self-hosted deployments.
+ * self-host commands: manage self-hosted deployments.
  *
  * Compose-based commands are the default path.
  * Native/systemd commands remain available for bare-metal deployments.

package/src/commands/self-update.ts

@@ -1,139 +1,89 @@
 /**
-
- * supatype self-update — Phase 10.6C8.
-
+ * supatype self-update
  *
-
  * npm-installed CLI: instruct to use `npm update -g`.
-
  * Homebrew: instruct to use `brew upgrade supatype`.
-
- * Standalone curl|sh installs: replace binary from releases.supatype.com/cli/.
-
+ * Standalone curl|sh installs: replace the binary from releases.supatype.com/cli/.
  */
 
-
-
 import type { Command } from "commander"
-
 import { copyFileSync, renameSync } from "node:fs"
-
-import { detectCliInstallMethod } from "../cli-install-method.js"
-
+import { cliPackageVersion } from "../cli-package-version.js"
+import { detectCliInstallMethod, runningBinaryPath } from "../cli-install-method.js"
 import { downloadStandaloneCli, fetchStandaloneCliLatestVersion } from "../cli-standalone.js"
-
 import { error, info, plain } from "../ui/messages.js"
 
-
-
 export function registerSelfUpdate(program: Command): void {
-
   program
-
     .command("self-update")
-
     .description("Update the supatype CLI (npm or standalone CDN binary)")
-
-    .action(async () => {
-
+    .option("--force", "Reinstall even if the latest version is already installed")
+    .action(async (opts: { force?: boolean }) => {
       const method = detectCliInstallMethod()
 
-
-
       if (method === "npm") {
-
         plain(
-
           "This CLI was installed via npm (or runs from the package workspace).\n" +
-
             "Update with:\n\n  npm update -g @supatype/cli\n\n" +
-
             "To bump engine/server/postgres/deno/realtime pinned in supatype.config.ts, use:\n\n  supatype update\n",
-
         )
-
         return
-
       }
 
-
-
       if (method === "homebrew") {
-
         plain(
-
           "This CLI was installed via Homebrew.\n" +
-
             "Update with:\n\n  brew update && brew upgrade supatype\n\n" +
-
             "To bump component binaries pinned in supatype.config.ts, use:\n\n  supatype update\n",
-
         )
-
         return
-
       }
 
-
-
-      const currentPath = process.argv[1]
-
+      // The binary on disk, not argv[1]: in a compiled binary argv[1] points into the embedded
+      // filesystem, so backing it up failed with ENOENT and no update could ever complete.
+      const currentPath = runningBinaryPath()
       if (!currentPath) {
-
         error("Could not determine current CLI path.")
-
         process.exit(1)
-
       }
 
-
-
       try {
-
         const latest = await fetchStandaloneCliLatestVersion()
+        const current = cliPackageVersion()
+
+        // Without this the command re-downloaded on every run: it compared nothing, so a
+        // machine already on the latest version fetched and rewrote the same binary.
+        if (latest === current && !opts.force) {
+          info(`Already on v${current}, the latest release.`)
+          plain("Reinstall anyway with `supatype self-update --force`.")
+          return
+        }
 
-        info(`Downloading supatype CLI v${latest}...`)
-
+        info(
+          latest === current
+            ? `Reinstalling v${latest}...`
+            : `Downloading supatype CLI v${latest} (current: v${current})...`,
+        )
         const downloaded = await downloadStandaloneCli(latest)
 
         const backup = `${currentPath}.bak`
-
         copyFileSync(currentPath, backup)
-
         try {
-
           renameSync(downloaded, currentPath)
-
         } catch {
-
           copyFileSync(downloaded, currentPath)
-
         }
 
         info(`Updated to v${latest}.`)
-
         plain("Run `supatype --version` to verify.")
-
       } catch (err) {
-
         error(
-
           `Standalone CLI self-update failed: ${(err as Error).message}\n\n` +
-
             "Install or upgrade via npm:\n  npm install -g @supatype/cli\n\n" +
-
             "Or Homebrew:\n  brew upgrade supatype\n\n" +
-
             "Component binaries (engine, server, postgres, deno, realtime):\n  supatype update\n",
-
         )
-
         process.exit(1)
-
       }
-
     })
-
 }
-
-

package/src/commands/status.ts

@@ -1,5 +1,5 @@
 /**
- * supatype status — show linked target or local dev stack state.
+ * supatype status: show linked target or local dev stack state.
  */
 import type { Command } from "commander"
 import { spawnSync } from "node:child_process"

package/src/commands/update.ts

@@ -1,5 +1,5 @@
 /**
- * supatype update — bump component versions in supatype.config.ts
+ * supatype update: bump component versions in supatype.config.ts
  * and download the new binaries.
  */
 

package/src/config.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs"
 import { resolve } from "node:path"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { evalTsSnippet } from "./tsx-runner.js"
+import { importModuleAsJson } from "./tsx-runner.js"
 import { readEnvFile } from "./env-file.js"
 import {
   mergeProjectConfig,
@@ -72,7 +72,7 @@ export interface AppConfig {
   headers?: Record<string, string>
 }
 
-/** Identity helper — provides type inference for config files. */
+/** Identity helper: provides type inference for config files. */
 export function defineConfig(config: SupatypeProjectConfig): SupatypeProjectConfig {
   return config
 }
@@ -137,7 +137,7 @@ export function loadConfig(cwd: string = process.cwd()): SupatypeProjectConfig {
 
   const localNorm = normalizeProjectJson(localRaw) as Partial<SupatypeProjectConfig>
   // Re-validated after merging: the local override can reintroduce a combination the base file was
-  // rejected for — `database.provider` beside an inherited `database.external`, say — and merging
+  // rejected for: `database.provider` beside an inherited `database.external`, say, and merging
   // has no opinion about that.
   return validateProjectConfig(
     mergeProjectConfig(base, localNorm),
@@ -149,7 +149,7 @@ export function loadConfig(cwd: string = process.cwd()): SupatypeProjectConfig {
  * Environment for the child process that imports the config module.
  *
  * `supatype.config.ts` is TypeScript, so the natural way to keep a database password out of version
- * control is `process.env.DATABASE_URL` — which only works if the project's `.env` is visible to the
+ * control is `process.env.DATABASE_URL`: which only works if the project's `.env` is visible to the
  * process doing the import. A real environment variable still wins over the file, matching how every
  * other dotenv reader behaves and how Compose itself resolves the same names.
  */
@@ -157,6 +157,37 @@ function configLoadEnv(cwd: string): NodeJS.ProcessEnv {
   return { ...readEnvFile(cwd), ...process.env }
 }
 
+/**
+ * A config file exists but could not be evaluated.
+ *
+ * Distinct from absence on purpose. Six call sites catch config loading so the CLI still works
+ * outside a project, and while they treated both cases the same, a config that failed to load
+ * looked exactly like no config at all. That is how a standalone binary that could not read any
+ * config shipped in v0.1.9 and still appeared to function: `status` printed a stack of stopped
+ * services, and `db check` fell back to DATABASE_URL from .env and reported a connection error.
+ * Those call sites should swallow absence and re-throw this.
+ */
+export class ConfigLoadError extends Error {
+  readonly configPath: string
+
+  constructor(configPath: string, detail: string) {
+    super(`Failed to load ${configPath}:\n${detail}`)
+    this.name = "ConfigLoadError"
+    this.configPath = configPath
+  }
+}
+
+/**
+ * Re-throw a config that exists but could not be read; swallow anything else.
+ *
+ * For the call sites that catch config loading so the CLI still works outside a project. They
+ * want to ignore absence, not breakage, and treating the two alike is what let a standalone
+ * binary that could read no config at all still look like it was working.
+ */
+export function rethrowIfConfigBroken(err: unknown): void {
+  if (err instanceof ConfigLoadError) throw err
+}
+
 function loadFirstTsConfig(
   cwd: string,
   candidates: string[],
@@ -166,24 +197,19 @@ function loadFirstTsConfig(
     if (!existsSync(configPath)) continue
 
     const urlPath = "file:///" + configPath.replace(/\\/g, "/")
-    const snippet = `
-const mod = await import(${JSON.stringify(urlPath)})
-const config = mod.default ?? mod
-process.stdout.write(JSON.stringify(config))
-`
-    const result = evalTsSnippet(snippet, { cwd, env: configLoadEnv(cwd) })
+    const result = importModuleAsJson(urlPath, { cwd, env: configLoadEnv(cwd) })
     if (result.exitCode === 0) {
       return JSON.parse(result.stdout) as Record<string, unknown>
     }
 
     const failure = result.stderr || result.stdout
     if (!shouldStripCliImportOnLoadFailure(failure)) {
-      throw new Error(`Failed to load ${candidate}:\n${failure}`)
+      throw new ConfigLoadError(candidate, failure)
     }
 
     const fallback = loadTsConfigWithoutCliImport(configPath, cwd)
     if (fallback !== null) return fallback
-    throw new Error(`Failed to load ${candidate}:\n${failure}`)
+    throw new ConfigLoadError(candidate, failure)
   }
   return null
 }
@@ -217,12 +243,7 @@ function loadTsConfigWithoutCliImport(
   writeFileSync(tmpPath, wrapper, "utf8")
   try {
     const urlPath = "file:///" + tmpPath.replace(/\\/g, "/")
-    const snippet = `
-const mod = await import(${JSON.stringify(urlPath)})
-const config = mod.default ?? mod
-process.stdout.write(JSON.stringify(config))
-`
-    const result = evalTsSnippet(snippet, { cwd, env: configLoadEnv(cwd) })
+    const result = importModuleAsJson(urlPath, { cwd, env: configLoadEnv(cwd) })
     if (result.exitCode !== 0) return null
     return JSON.parse(result.stdout) as Record<string, unknown>
   } finally {

package/src/db-preflight.ts

@@ -3,7 +3,7 @@
  *
  * Written for the bring-your-own-Postgres case: an external database will not look like
  * `supatype/postgres`, and the failures it produces are mostly indirect. The four API roles are
- * the sharpest example — every `GRANT` the engine emits is guarded with
+ * the sharpest example: every `GRANT` the engine emits is guarded with
  * `IF EXISTS (SELECT 1 FROM pg_roles …)`, so a missing role is skipped in silence and the symptom
  * is an API that cannot switch roles at all, days later.
  *
@@ -31,7 +31,7 @@ export interface CheckResult {
   /** SQL that resolves it, if SQL can. */
   remedy?: string
   /**
-   * True when the remedy cannot run inside a transaction — server settings, chiefly. `--fix`
+   * True when the remedy cannot run inside a transaction, server settings, chiefly. `--fix`
    * refuses these and reports them rather than half-applying.
    */
   remedyNeedsOperator?: boolean
@@ -117,7 +117,7 @@ const REQUIRED_ROLES = ["anon", "authenticated", "service_role", "authenticator"
  * Stands in for the `authenticator` password when the operator has not supplied one.
  *
  * Fine to print for a human to replace; never acceptable to execute. `--fix` refuses when a remedy
- * still contains it, because the decision was that this credential belongs to the operator —
+ * still contains it, because the decision was that this credential belongs to the operator,
  * Supatype does not invent one for a database it does not own, and creating a role with a
  * placeholder password would be worse than refusing.
  */
@@ -225,13 +225,13 @@ export async function runPreflight(
   })
 
   // `CREATE` on the database, which the check above only asked about when the target schema was
-  // missing — and `public` always exists, so on a database where the role cannot create schemas that
+  // missing: and `public` always exists, so on a database where the role cannot create schemas that
   // check passed while the stack could not start.
   //
   // Measured on a role with `CONNECT` and `USAGE ON SCHEMA public` but no `CREATE`: storage's
   // bootstrap fails `42501 permission denied for database`, and so does every one of the engine's own
   // schemas. Storage was the least examined service in this plan and this is the whole of what it
-  // needs — no extensions, no superuser, no replication, just somewhere to put `storage.buckets` and
+  // needs: no extensions, no superuser, no replication, just somewhere to put `storage.buckets` and
   // `storage.objects`.
   results.push({
     id: "create-schemas",
@@ -274,7 +274,7 @@ export async function runPreflight(
         // create role" because BYPASSRLS is superuser-only. Better to say so up front.
         (needsSuperuserForRoles(missing, privs.is_super)
           ? "\n         Note: service_role needs BYPASSRLS, which only a superuser can grant. " +
-            `This connection is not a superuser, so --fix cannot create it — have someone with ` +
+            `This connection is not a superuser, so --fix cannot create it, have someone with ` +
             `superuser apply the emitted SQL, or create service_role first.`
           : ""),
       remedy: roleRemedy(missing, opts.authenticatorPassword),
@@ -333,7 +333,7 @@ export async function runPreflight(
   results.push(
     extensionCheck("pgcrypto", installed, available, {
       title: "pgcrypto",
-      needs: "UUID primary keys — the engine emits gen_random_uuid() defaults.",
+      needs: "UUID primary keys, the engine emits gen_random_uuid() defaults.",
       whenMissing: "fail",
     }),
   )
@@ -359,14 +359,14 @@ export async function runPreflight(
     detail: installed.has("supatype_mask")
       ? "enforced by supatype_mask, the planner rewrite (tier 1)"
       : available.has("supatype_mask")
-        ? "supatype_mask is available but not installed — rules will be enforced by generated api views (tier 2)"
+        ? "supatype_mask is available but not installed, rules will be enforced by generated api views (tier 2)"
         : "enforced by generated api views (tier 2); supatype_mask is not available on this server",
     ...(!installed.has("supatype_mask") && {
       impact:
         "Tier 2 puts the masking expression in a view instead of the query planner. It is the same " +
         "behaviour with one exception: an aggregate over a masked column returns the sum of what the " +
-        "caller may read, where tier 1 raises. Unreachable through the API — PostgREST ships with " +
-        "aggregates disabled and Supatype never enables them — so this matters only for direct SQL " +
+        "caller may read, where tier 1 raises. Unreachable through the API, PostgREST ships with " +
+        "aggregates disabled and Supatype never enables them, so this matters only for direct SQL " +
         "against the api views. PostgREST is pointed at `api` instead of your managed schema, and the " +
         "API roles hold their privileges on the views rather than the tables.",
       ...(available.has("supatype_mask") && {
@@ -413,7 +413,7 @@ export async function runPreflight(
   // The definitive realtime check: create the slot realtime would create, then drop it.
   //
   // There is no catalog to consult. `wal2json` is a shared library, not an extension, so it never
-  // appears in `pg_available_extensions` — the only way to know whether this database can decode is
+  // appears in `pg_available_extensions`: the only way to know whether this database can decode is
   // to ask it to. Cloud SQL does not ship the plugin at all; plenty of managed Postgres will not
   // grant `REPLICATION`. Both produce a stack that looks healthy until the first subscription.
   //
@@ -448,7 +448,7 @@ export async function runPreflight(
           (names.length > 8 ? `, … and ${names.length - 8} more` : ""),
         impact:
           "These are not described by your schema. Model them, or keep them out of the managed " +
-          "schema — a push only manages what it created.",
+          "schema: a push only manages what it created.",
       })
     }
   }
@@ -488,7 +488,7 @@ function extensionCheck(
  * SQL to create the missing API roles.
  *
  * `authenticator` needs a password because PostgREST logs in as it; the others never do. The
- * password is the operator's to supply — Supatype does not invent a credential for a database it
+ * password is the operator's to supply, Supatype does not invent a credential for a database it
  * does not own.
  */
 function roleRemedy(missing: readonly string[], authenticatorPassword?: string): string {
@@ -518,7 +518,7 @@ function roleRemedy(missing: readonly string[], authenticatorPassword?: string):
  * Whether creating the missing roles needs superuser rather than merely CREATEROLE.
  *
  * `service_role` carries `BYPASSRLS`, and only a superuser may set that attribute. A CREATEROLE
- * operator — which is what managed Postgres typically gives you — gets "permission denied to
+ * operator: which is what managed Postgres typically gives you, gets "permission denied to
  * create role" with no indication that the attribute is the reason.
  */
 function needsSuperuserForRoles(missing: readonly string[], isSuperuser: boolean): boolean {
@@ -551,7 +551,7 @@ export function operatorRemedies(report: PreflightReport): CheckResult[] {
  * Postgres, so any failure rolls the whole thing back and the database is exactly as it was. That
  * is the guarantee worth having when the database belongs to someone else.
  *
- * Server settings are the exception and are never included — `ALTER SYSTEM` cannot run in a
+ * Server settings are the exception and are never included, `ALTER SYSTEM` cannot run in a
  * transaction, and needs a restart besides. Those are reported for the operator to do.
  */
 export async function applyRemedies(

package/src/dev-compose.ts

@@ -1,5 +1,5 @@
 /**
- * `supatype dev` when `provider: docker` — full self-host Compose stack (Kong gateway).
+ * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
@@ -99,10 +99,10 @@ async function resolveDevDbPort(cwd: string): Promise<number> {
 /**
  * The database URL to hand a tool, from wherever it happens to run.
  *
- * The compose helpers below describe the `db` *container* — on the host at
+ * The compose helpers below describe the `db` *container*, on the host at
  * `SUPATYPE_DEV_DB_PORT`, or in-network at `db:5432`. Neither exists for a project pointed at an
  * external database, and passing one produced "pool timed out while waiting for an open connection"
- * — a message with nothing in it about the URL being wrong.
+ *- a message with nothing in it about the URL being wrong.
  */
 function projectDatabaseUrl(cwd: string, config: SupatypeProjectConfig, inNetwork = false): string {
   if (usesExternalDatabase(config)) return connectionString(config)
@@ -193,7 +193,7 @@ async function resolveKongPort(cwd: string): Promise<number> {
  * Bring up the compose `db` service and wait for it to answer.
  *
  * A no-op when the project uses an external database: there is no such service, the database is
- * already running, and its readiness is the operator's — `supatype db check` is what reports on it.
+ * already running, and its readiness is the operator's, `supatype db check` is what reports on it.
  * Four call sites did this inline, so an external project hit `compose up -d db` against a compose
  * file that deliberately has no `db`.
  */
@@ -233,7 +233,7 @@ function upsertDevComposeEnv(
   // `POSTGRES_PASSWORD` and `JWT_SECRET` are deliberately absent.
   //
   // They used to be pinned here to published constants on every `dev` run, against the same
-  // `.env` a self-host deployment reads — so a project could not hold its own secrets, and one
+  // `.env` a self-host deployment reads, so a project could not hold its own secrets, and one
   // `dev` after generating them put the published values back with nothing to show it. They are
   // now resolved from `.env` (see `local-secrets.ts`) and written by `init` alone.
   //
@@ -242,12 +242,12 @@ function upsertDevComposeEnv(
   // would desync them from the secret that validates them.
   const updates: Record<string, string> = {
     // The docker dev path renders the *self-host* compose file, where the secrets have no
-    // defaults — an unset value is a hard compose error rather than a service quietly starting
+    // defaults: an unset value is a hard compose error rather than a service quietly starting
     // with a published constant. This guarantees presence without overwriting: only keys
     // genuinely absent from `.env` are filled, and with the value the project has been running
     // with rather than a fresh one.
     ...seedMissingLocalSecrets(cwd),
-    // Project configuration, seeded not overwritten — see seedMissingDatabaseIdentity.
+    // Project configuration, seeded not overwritten, see seedMissingDatabaseIdentity.
     ...seedMissingDatabaseIdentity(cwd),
     ANON_KEY: anonKey,
     SERVICE_ROLE_KEY: serviceRoleKey,
@@ -264,13 +264,13 @@ function upsertDevComposeEnv(
     ...(localServerImage !== undefined && { SUPATYPE_SERVER_IMAGE: localServerImage }),
   }
   // Never for an external database: this URL describes the `db` container, which that project does
-  // not have. Writing it overwrote the operator's own DATABASE_URL — the value the whole stack and
-  // every CLI command reads — with a DSN pointing at a database that does not exist. Found by
+  // not have. Writing it overwrote the operator's own DATABASE_URL, the value the whole stack and
+  // every CLI command reads, with a DSN pointing at a database that does not exist. Found by
   // rehearsing a push against a real external Postgres, where the compose guard then refused to
   // proceed because .env and the config disagreed. They disagreed because of this line.
   if (devDbPort !== undefined && !usesExternalDatabase(config)) {
     updates.SUPATYPE_DEV_DB_PORT = String(devDbPort)
-    // User and database from the project, not hardcoded — same reason as
+    // User and database from the project, not hardcoded, same reason as
     // `seedMissingDatabaseIdentity`: a project not named "supatype" had this URL pointing at a
     // database that does not exist.
     const dbUser = readEnvValue(cwd, "POSTGRES_USER", "supatype_admin")
@@ -358,7 +358,7 @@ function dumpComposeDbLogs(
     maxBuffer: 10 * 1024 * 1024,
   })
   const body = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
-  const content = body || `(empty — docker compose logs db exit ${result.status ?? "?"})\n`
+  const content = body || `(empty, docker compose logs db exit ${result.status ?? "?"})\n`
   try {
     writeFileSync(logPath, content)
   } catch {
@@ -403,7 +403,7 @@ async function waitStorageApiReady(
       const body = await res.text()
       const kongUpstreamDown = body.includes("invalid response was received from the upstream server")
       if (!kongUpstreamDown && res.status !== 503) {
-        // Non-transient storage response (e.g. 401) — stop waiting.
+        // Non-transient storage response (e.g. 401), stop waiting.
         return
       }
     } catch {
@@ -412,7 +412,7 @@ async function waitStorageApiReady(
     await new Promise((r) => setTimeout(r, 1000))
   }
   console.warn(
-    `[supatype] Storage API at ${url} did not become ready within ${maxSec}s — bucket provisioning may fail.`,
+    `[supatype] Storage API at ${url} did not become ready within ${maxSec}s, bucket provisioning may fail.`,
   )
 }
 
@@ -445,7 +445,7 @@ async function refreshSchemaArtifacts(
     await ensureEngine()
   } catch (err) {
     console.warn(
-      `[supatype] Host engine unavailable — admin/types not refreshed: ${(err as Error).message}`,
+      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}`,
     )
     return
   }
@@ -480,7 +480,7 @@ async function refreshSchemaArtifacts(
     console.log("[supatype] Admin config written to .supatype/admin-config.json")
   } catch (err) {
     console.warn(
-      `[supatype] Admin config generation failed — Studio may show stale field widgets: ${(err as Error).message}`,
+      `[supatype] Admin config generation failed, Studio may show stale field widgets: ${(err as Error).message}`,
     )
   }
 }
@@ -498,7 +498,7 @@ async function runComposeSchemaPush(
   const supatypeDir = join(cwd, ".supatype")
   mkdirSync(supatypeDir, { recursive: true })
   const astPath = join(supatypeDir, "schema.ast.json")
-  // Always materialise on disk — schema-engine reads via bind mount; skip must not omit the write.
+  // Always materialise on disk, schema-engine reads via bind mount; skip must not omit the write.
   writeFileSync(astPath, astJson)
   if (astJson === _lastPushedAst && astJson !== _lastFailedAst) return
 
@@ -506,7 +506,7 @@ async function runComposeSchemaPush(
     throw new Error(`Failed to write schema AST at ${astPath}`)
   }
 
-  // Admin + types come from the AST only (no DB) — refresh before push so Studio stays
+  // Admin + types come from the AST only (no DB), refresh before push so Studio stays
   // in sync even when migration fails (e.g. bad engine image, lossy column change).
   await refreshSchemaArtifacts(cwd, config, ast)
 
@@ -552,7 +552,7 @@ async function runComposeSchemaPush(
     }
     return result
   }
-  // B: only hold the advisory lock when realtime is already decoding — first-boot
+  // B: only hold the advisory lock when realtime is already decoding, first-boot
   // push (db only) must not take the lock; that path crashed under lock+DDL in CI.
   const push = composeServiceIsRunning(paths, cwd, composeProject, "realtime")
     ? await withComposeSchemaPushLock(paths, cwd, composeProject, runPush)
@@ -711,7 +711,7 @@ async function runComposeEngineDiff(
 
 /**
  * `supatype diff` when `provider: docker`. Uses in-compose schema-engine unless
- * `overrides.engine` is set — then Postgres is published to the host and diff runs
+ * `overrides.engine` is set: then Postgres is published to the host and diff runs
  * through the local engine binary.
  */
 export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfig): Promise<DiffResult> {
@@ -772,7 +772,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
 
 /**
  * `supatype push` when `provider: docker`. Uses in-compose schema-engine unless
- * `overrides.engine` is set — then Postgres is published to the host and push runs
+ * `overrides.engine` is set: then Postgres is published to the host and push runs
  * through the local engine binary (AST v2, contributor builds).
  */
 export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfig): Promise<void> {
@@ -782,7 +782,7 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
   // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
-  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL — the
+  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL, the
   // one the whole stack and every CLI command reads.
   const devDbPort =
     hasEngineOverride(config) && !usesExternalDatabase(config)
@@ -798,7 +798,7 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   const pushBrand = { intro: "Push schema" }
 
-  console.log(`[supatype] provider: docker — applying schema via compose (project ${project})...`)
+  console.log(`[supatype] provider docker, applying schema via compose (project ${project})...`)
   await startComposeDatabase(config, paths, cwd, project, pushBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
@@ -833,7 +833,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
   const project = composeProjectName(config.project.name)
   const kongPort = await resolveKongPort(cwd)
   // No dev db port for an external database: `ensureDevDbPort` allocates a host port for the `db`
-  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL — the
+  // container *and persists a matching DATABASE_URL*, which overwrote the operator's own URL, the
   // one the whole stack and every CLI command reads.
   const devDbPort =
     hasEngineOverride(config) && !usesExternalDatabase(config)
@@ -850,7 +850,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
 
   ensureDevComposeEnv(cwd, config, anonKey, serviceRoleKey, kongPort, devDbPort, localServerImage)
 
-  console.log(`[supatype] provider: docker — starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
+  console.log(`[supatype] provider docker, starting self-host Compose stack (project ${project}, gateway :${kongPort})...`)
   const paths = writeSelfHostCompose(cwd, config, { devLocal: true })
   if (ensureDevApiConfig(cwd)) {
     console.log("[supatype] API config written to .supatype/api-config.json")
@@ -898,7 +898,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     console.log("[supatype] Bringing up Postgres (compose db)...")
   }
   await startComposeDatabase(config, paths, cwd, project, devBrand, 180_000, endDevSession)
-  // Settle before DDL — pg_isready can pass slightly before the instance is stable.
+  // Settle before DDL: pg_isready can pass slightly before the instance is stable.
   await new Promise((r) => setTimeout(r, 3000))
 
   // A: apply schema before realtime (and the rest of the stack) starts decoding WAL.
@@ -1034,7 +1034,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     shutdownState.studioProc = studioProc
     if (studioProc) {
       console.log(
-        `[supatype] Studio (overrides.studio) — live reload proxied at http://localhost:${kongPort}/studio/`,
+        `[supatype] Studio (overrides.studio): live reload proxied at http://localhost:${kongPort}/studio/`,
       )
     }
   }
@@ -1122,6 +1122,6 @@ function grantAuthSchemaAccess(
     { cwd: composeDir, encoding: "utf8", timeout: 10_000 },
   )
   if (result.status !== 0) {
-    console.warn("[supatype] Could not grant service_role access to auth.users — Studio relation preview may fail.")
+    console.warn("[supatype] Could not grant service_role access to auth.users, Studio relation preview may fail.")
   }
 }