@supatype/cli 0.1.7 → 0.1.9

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

package/src/dev-log-filter.ts

@@ -48,7 +48,7 @@ export function filterStackLogLine(line: string): boolean {
   return false
 }
 
-/** Drop docker noise only — keep diff tables, push status, and command output. */
+/** Drop docker noise only, keep diff tables, push status, and command output. */
 export function filterCommandLogLine(line: string): boolean {
   const t = stripAnsi(line).trim()
   if (!t) return false

package/src/dev-ports.ts

@@ -60,7 +60,7 @@ async function promptPortConflict(
 export interface EnsureKongPortOptions {
   /** When false, fail fast instead of prompting (CI / scripts). */
   interactive?: boolean
-  /** init wizard — slightly different copy */
+  /** init wizard: slightly different copy */
   context?: "dev" | "init"
 }
 
@@ -102,7 +102,7 @@ export async function ensureKongPort(
   return port
 }
 
-/** Wizard / init — pick a Kong port without writing `.env` (scaffold writes it). */
+/** Wizard / init: pick a Kong port without writing `.env` (scaffold writes it). */
 export async function promptKongPortChoice(): Promise<number> {
   const freeDefault = (await isPortInUse(COMPOSE_DEV_KONG_PORT))
     ? await findNextFreePort(COMPOSE_DEV_KONG_PORT)
@@ -139,7 +139,7 @@ async function promptPortConflictWithoutPersist(
   const headline =
     reason === "init"
       ? `Port ${blockedPort} is already in use on this machine.`
-      : `Port ${blockedPort} is in use — another Supatype project or service may already be bound to it.`
+      : `Port ${blockedPort} is in use, another Supatype project or service may already be bound to it.`
 
   const choice = await p.select<"suggested" | "custom" | "cancel">({
     message: headline,

package/src/dev-session.ts

@@ -1,5 +1,5 @@
 /**
- * `supatype dev` output session — Ink dashboard (default) or interleaved stream mode.
+ * `supatype dev` output session, Ink dashboard (default) or interleaved stream mode.
  */
 
 import { render, type Instance } from "ink"
@@ -32,7 +32,7 @@ export function beginDevSession(mode: DevUiMode): DevSession {
   return activeSession
 }
 
-/** @deprecated Ink starts in beginDevSession — kept for callers that invoke late. */
+/** @deprecated Ink starts in beginDevSession, kept for callers that invoke late. */
 export function startDevSession(): void {
   activeSession?.startInk()
 }
@@ -47,7 +47,7 @@ export function endDevSession(): void {
   activeSession = null
 }
 
-/** @deprecated Dev prompts render inside the Ink dashboard — no suspend needed. */
+/** @deprecated Dev prompts render inside the Ink dashboard, no suspend needed. */
 export function suspendDevSessionForPrompt(): void {
   prepareStdinForInteractivePrompt()
 }
@@ -58,12 +58,12 @@ export function prepareStdinForInteractivePrompt(): void {
   process.stdin.resume()
 }
 
-/** @deprecated Dev prompts render inside the Ink dashboard — no resume needed. */
+/** @deprecated Dev prompts render inside the Ink dashboard, no resume needed. */
 export function resumeDevSessionAfterPrompt(): void {
-  // no-op — prompts are Ink overlays
+  // no-op: prompts are Ink overlays
 }
 
-/** @deprecated Use Ink overlay prompts — runs fn without tearing down the dashboard. */
+/** @deprecated Use Ink overlay prompts, runs fn without tearing down the dashboard. */
 export async function withDevSessionSuspended<T>(fn: () => Promise<T>): Promise<T> {
   return fn()
 }

package/src/dev-shutdown.ts

@@ -1,5 +1,5 @@
 /**
- * Graceful shutdown for `supatype dev` — SIGINT, TUI Ctrl+C, terminal close,
+ * Graceful shutdown for `supatype dev`, SIGINT, TUI Ctrl+C, terminal close,
  * and a synchronous compose-down fallback on process exit.
  */
 
@@ -23,7 +23,7 @@ let forceQuitRequested = false
 let hooksRegistered = false
 let ignoreSigintUntil = 0
 
-/** SIGINT/SIGTERM hooks — call as soon as `supatype dev` starts (before compose is up). */
+/** SIGINT/SIGTERM hooks: call as soon as `supatype dev` starts (before compose is up). */
 export function ensureDevShutdownHooks(): void {
   if (hooksRegistered) return
   hooksRegistered = true
@@ -62,7 +62,7 @@ function syncComposeDownFallback(): void {
       { quiet: true },
     )
   } catch {
-    // best-effort — process is exiting
+    // best-effort: process is exiting
   }
   if (shutdownCwd) clearDevSessionLock(shutdownCwd)
 }
@@ -74,7 +74,7 @@ function onProcessExit(): void {
 export interface RegisterDevShutdownOptions {
   /** Sync `docker compose down` when async teardown cannot finish (terminal close, kill). */
   compose?: DevComposeShutdownFallback
-  /** Project root — clears `.supatype/dev-session.json` after shutdown. */
+  /** Project root: clears `.supatype/dev-session.json` after shutdown. */
   cwd?: string
 }
 
@@ -89,7 +89,7 @@ export function registerDevShutdown(
   ensureDevShutdownHooks()
 }
 
-/** TUI Ctrl+C — do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
+/** TUI Ctrl+C: do not re-emit SIGINT (avoids double-fire on Windows raw mode). */
 export function requestDevShutdown(): void {
   ignoreSigintUntil = Date.now() + 400
   void runDevShutdown()
@@ -99,7 +99,7 @@ export function isDevShuttingDown(): boolean {
   return shuttingDown
 }
 
-/** @internal Tests — reset module state between cases. */
+/** @internal Tests: reset module state between cases. */
 export function resetDevShutdownForTests(): void {
   shutdownWork = null
   composeFallback = null
@@ -125,7 +125,7 @@ async function runDevShutdown(): Promise<void> {
     } catch {
       // best-effort terminal restore
     }
-    process.stderr.write("\n[supatype] Forced quit — Docker containers may still be running.\n")
+    process.stderr.write("\n[supatype] Forced quit: Docker containers may still be running.\n")
     process.stdout.write("\n")
     process.exit(130)
   }
@@ -145,7 +145,7 @@ async function runDevShutdown(): Promise<void> {
   } catch (err) {
     process.stderr.write(`[supatype] Shutdown failed: ${(err as Error).message}\n`)
     process.stderr.write(
-      "[supatype] Docker containers may still be running — try: supatype self-host compose down\n",
+      "[supatype] Docker containers may still be running, try: supatype self-host compose down\n",
     )
     syncComposeDownFallback()
     shutdownCompleted = true

package/src/dev-task-colors.ts

@@ -30,7 +30,7 @@ export function levelColor(line: string): string | null {
   return null
 }
 
-/** Drop redundant prefix — task pane is already labelled supatype. */
+/** Drop redundant prefix: task pane is already labelled supatype. */
 export function normalizeStackLogLine(line: string): string {
   return line.replace(/^\[supatype\]\s*/, "")
 }

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."
   }