@supatype/cli 0.1.7 → 0.1.10

package/src/main.ts

@@ -0,0 +1,20 @@
+/**
+ * Entry point for the standalone binary.
+ *
+ * `bin/supatype.js` stays the npm entry: it loads the CLI with a dynamic import, which Bun
+ * cannot follow when compiling. Given `import("../dist/cli.js")` it emits a binary that
+ * bundles one module and then fails at runtime with
+ * `Cannot find module '../dist/cli.js' from '/$bunfs/root/supatype'`. The import below is
+ * static, so the whole graph is embedded.
+ */
+import { run } from "./cli.js"
+import { reportCliFatal } from "./ui/fatal.js"
+
+// reportCliFatal rather than console.error: it is what run() already uses for a failed
+// command, and it prints a stack under SUPATYPE_DEBUG=1. Open-coding the message here would
+// make a crash report from a curl | bash user less useful than one from an npm user. This
+// only fires for a throw during command registration, since run() catches everything after.
+run().catch((err: unknown) => {
+  reportCliFatal(err)
+  process.exit(1)
+})

package/src/model-hooks.ts

@@ -2,7 +2,7 @@
  * Validate the lifecycle hooks a schema declares against the functions that exist.
  *
  * A hook names a function directory. If the name is wrong, the honest failure is at push time with
- * the path we searched — not at runtime, where the symptom is a hook that never fires and a write
+ * the path we searched, not at runtime, where the symptom is a hook that never fires and a write
  * that quietly succeeds unvalidated. That silence is the whole reason this check exists.
  *
  * Kept out of the extractor on purpose: resolving the functions directory needs the project config,
@@ -119,7 +119,7 @@ export interface ManifestHookEntry {
 }
 
 /**
- * The hook map for `.supatype/manifest.json`, keyed by **table name** — because that is what the
+ * The hook map for `.supatype/manifest.json`, keyed by **table name**, because that is what the
  * server matches a request path against, not the model name.
  *
  * Defaults are resolved here rather than in the server: one place decides that a `before*` hook
@@ -172,7 +172,7 @@ export const DEFAULT_HOOK_TIMEOUT_MS = 2000
  *
  * **Only updates a manifest that is already there.** Creating one from scratch here would be a
  * hazard: `functions_enabled` is a plain bool on the server's side, so a manifest carrying only
- * hooks would read as functions *disabled* — the exact defect this repo fixed a commit ago, arriving
+ * hooks would read as functions *disabled*, the exact defect this repo fixed a commit ago, arriving
  * by a different door. The compose path owns creation; this owns one key.
  *
  * Returns true when the file was rewritten.
@@ -216,7 +216,7 @@ export interface HooksReport {
 /**
  * What `supatype doctor` needs to answer "will my hooks actually run?".
  *
- * Local facts only — the schema, the functions on disk, and the manifest the server reads. No probe
+ * Local facts only: the schema, the functions on disk, and the manifest the server reads. No probe
  * of a running worker, so the answer is the same whether or not the stack is up, and a report that
  * needs a stack is a report nobody runs before deploying.
  *

package/src/pgbouncer-userlist.ts

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto"
 
-/** PgBouncer md5 auth: "md5" + md5(password + username) — same as supatype-cloud / self-host. */
+/** PgBouncer md5 auth: "md5" + md5(password + username), same as supatype-cloud / self-host. */
 export function pgbouncerMd5Hash(password: string, username: string): string {
   return "md5" + createHash("md5").update(password + username).digest("hex")
 }
 
 /** Two roles used by local compose: superuser pools (GoTrue, engine) and PostgREST. */
 export function pgbouncerUserlistContent(pgPassword: string): string {
-  return `# PgBouncer md5 userlist — matches supatype-cloud transaction pool (auth_type = md5).
+  return `# PgBouncer md5 userlist, matches supatype-cloud transaction pool (auth_type = md5).
 # Regenerated by supatype dev --local / init from POSTGRES_PASSWORD.
 "supatype_admin" "${pgbouncerMd5Hash(pgPassword, "supatype_admin")}"
 "authenticator" "${pgbouncerMd5Hash(pgPassword, "authenticator")}"

package/src/postgres-ctl.ts

@@ -1,5 +1,5 @@
 /**
- * postgres-ctl — wrappers around pg_ctl, initdb, and pg_isready for managing
+ * postgres-ctl: wrappers around pg_ctl, initdb, and pg_isready for managing
  * a native Postgres installation.
  */
 
@@ -95,7 +95,7 @@ export function start(opts: PgOptions): void {
   const bin = pgBin(opts.pgBinDir, "pg_ctl")
   const logPath = opts.logPath ?? join(opts.dataDir, "postgres.log")
 
-  // `supatype_mask` is a planner hook, so it has to be preloaded — `CREATE EXTENSION` alone does
+  // `supatype_mask` is a planner hook, so it has to be preloaded, `CREATE EXTENSION` alone does
   // nothing without it. Only when the archive actually carries the library: an install downloaded
   // before it was bundled would fail to start with "could not access file".
   //
@@ -131,7 +131,7 @@ export function stop(opts: PgOptions): void {
     encoding: "utf8",
     env: pgSpawnEnv(opts.pgBinDir),
   })
-  // Ignore exit code — Postgres may already be stopped.
+  // Ignore exit code: Postgres may already be stopped.
   void result
 }
 
@@ -175,7 +175,7 @@ export async function isPortInUse(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const server = createServer()
     server.once("error", (err: NodeJS.ErrnoException) => {
-      // EADDRINUSE — something is listening. EACCES — Windows excluded/reserved port range.
+      // EADDRINUSE: something is listening. EACCES, Windows excluded/reserved port range.
       resolve(err.code === "EADDRINUSE" || err.code === "EACCES")
     })
     server.once("listening", () => {

package/src/process-manager.ts

@@ -1,5 +1,5 @@
 /**
- * ProcessManager — spawn a child process, write its PID, stream logs with a
+ * ProcessManager: spawn a child process, write its PID, stream logs with a
  * colored prefix, and restart on crash with exponential backoff.
  */
 
@@ -73,7 +73,7 @@ export class ProcessManager {
     this.backoffMs = this.opts.initialBackoffMs
   }
 
-  /** Start the process. Returns immediately — the process runs in the background. */
+  /** Start the process. Returns immediately, the process runs in the background. */
   start(): void {
     this.stopped = false
     this.spawn()
@@ -201,7 +201,7 @@ export class ProcessManager {
       mkdirSync(this.opts.pidDir, { recursive: true })
       writeFileSync(join(this.opts.pidDir, `${this.opts.label}.pid`), String(pid))
     } catch {
-      // Non-fatal — PID tracking is best-effort.
+      // Non-fatal: PID tracking is best-effort.
     }
   }
 
@@ -209,7 +209,7 @@ export class ProcessManager {
     try {
       await unlink(join(this.opts.pidDir, `${this.opts.label}.pid`))
     } catch {
-      // Ignore — file may already be gone.
+      // Ignore: file may already be gone.
     }
   }
 }

package/src/project-config.ts

@@ -21,7 +21,7 @@ export interface SupatypeProjectConfig {
     root?: string
   }
   project: {
-    /** Project name — used for per-project state dirs and logging. */
+    /** Project name: used for per-project state dirs and logging. */
     name: string
     /** Cloud project reference (set by `supatype link`). */
     ref?: string
@@ -32,7 +32,7 @@ export interface SupatypeProjectConfig {
      * "native" = supatype manages a native Postgres binary (downloaded from CDN).
      * "docker" = supatype runs supatype/postgres via Docker (includes all extensions).
      *
-     * Omitted when `external` is set — there is no backend for Supatype to choose.
+     * Omitted when `external` is set, there is no backend for Supatype to choose.
      */
     provider?: "native" | "docker"
     /**
@@ -50,7 +50,7 @@ export interface SupatypeProjectConfig {
        * Postgres URL for every service in the stack.
        *
        * The role in it owns the schema and runs migrations. PostgREST connects as `authenticator`
-       * separately — see `supatype db check`, which reports what this database is missing.
+       * separately: see `supatype db check`, which reports what this database is missing.
        */
       url: string
       /**
@@ -215,12 +215,12 @@ export interface SupatypeProjectConfig {
     /**
      * Schemas the REST API exposes, in order (`PGRST_DB_SCHEMA`).
      *
-     * Defaults to `pg_schema` plus the ones the stack needs for itself — `supatype` for Studio's
-     * views, `graphql_public`, `auth` — so setting `pg_schema` alone does the sensible thing.
+     * Defaults to `pg_schema` plus the ones the stack needs for itself, `supatype` for Studio's
+     * views, `graphql_public`, `auth`: so setting `pg_schema` alone does the sensible thing.
      *
      * It used to be a hardcoded literal, which meant choosing a non-`public` `pg_schema` gave you
      * a correct push and an API that answered `PGRST106` for everything: the engine had moved and
-     * PostgREST had not been told. State this explicitly when you need a different set — an extra
+     * PostgREST had not been told. State this explicitly when you need a different set, an extra
      * schema of your own, or to stop exposing one.
      */
     api_schemas?: readonly string[]
@@ -238,7 +238,7 @@ export interface SupatypeProjectConfig {
      *
      * **Model hooks are not listed here and do not need to be.** A hook is procedural: only the API
      * server calls it, around a write the caller was already permitted to make, and the gateway
-     * refuses its route from outside — so there is no attacker to withhold it from, and the trust is
+     * refuses its route from outside, so there is no attacker to withhold it from, and the trust is
      * the same a trigger already has.
      */
     serviceRole?: readonly string[]
@@ -430,7 +430,7 @@ function validateExternalDatabase(cfg: Record<string, unknown>, filename: string
   const url = (external as Record<string, unknown>)["url"]
   if (typeof url !== "string" || url.trim().length === 0) {
     throw new Error(
-      `${filename}: database.external.url is required — the Postgres URL every service connects to.\n` +
+      `${filename}: database.external.url is required, the Postgres URL every service connects to.\n` +
         "Reading it from the environment keeps the password out of version control:\n" +
         "  database: { external: { url: process.env.DATABASE_URL! } }\n" +
         "The project's .env is loaded before the config module, so DATABASE_URL there is enough.",
@@ -450,7 +450,7 @@ function validateExternalDatabase(cfg: Record<string, unknown>, filename: string
   if (database["provider"] !== undefined) {
     throw new Error(
       `${filename}: database.provider ("${String(database["provider"])}") and database.external ` +
-        "cannot both be set — provider chooses a Postgres for Supatype to run, external says one " +
+        "cannot both be set, provider chooses a Postgres for Supatype to run, external says one " +
         "already exists.\n" +
         "Remove database.provider. The runtime stack is still chosen by the top-level `provider`.",
     )
@@ -459,7 +459,7 @@ function validateExternalDatabase(cfg: Record<string, unknown>, filename: string
   const server = cfg["server"] as Record<string, unknown> | undefined
   if (server?.["mode"] === "managed") {
     throw new Error(
-      `${filename}: database.external is not supported with server.mode "managed" — on the cloud ` +
+      `${filename}: database.external is not supported with server.mode "managed", on the cloud ` +
         "path the database is part of what is being provided.\n" +
         "Use an external database with a self-hosted stack (server.mode \"dev\" or \"standalone\").",
     )
@@ -469,7 +469,7 @@ function validateExternalDatabase(cfg: Record<string, unknown>, filename: string
   if (typeof connection === "string" && connection.trim() !== url.trim()) {
     throw new Error(
       `${filename}: connection and database.external.url are both set and disagree.\n` +
-        "database.external.url is what the whole stack uses, CLI commands included — remove " +
+        "database.external.url is what the whole stack uses, CLI commands included, remove " +
         "`connection`.",
     )
   }
@@ -496,11 +496,11 @@ export function functionsPathCandidatesFromProject(cfg: SupatypeProjectConfig, c
 }
 
 /**
- * Directory holding **model hooks** — procedural handlers the API calls around a write.
+ * Directory holding **model hooks**, procedural handlers the API calls around a write.
  *
  * Separate from `functions/` because the two have different trust models: a function is a public
  * endpoint anyone with the anon key may invoke, while a hook is only ever called by the server. One
- * worker serves both, and the gateway refuses the hook namespace from outside — so keeping them in
+ * worker serves both, and the gateway refuses the hook namespace from outside, so keeping them in
  * separate directories is what makes that boundary structural rather than a list to maintain.
  */
 export function hooksPathFromProject(cfg: SupatypeProjectConfig, cwd: string): string {
@@ -565,7 +565,7 @@ export function resolveRuntimeProvider(cfg: SupatypeProjectConfig): "native" | "
  *
  * Resolved here rather than in the compose template so there is one definition of the format.
  *
- * This does **not** check that the names exist — it cannot, since it has only the config. An earlier
+ * This does **not** check that the names exist, it cannot, since it has only the config. An earlier
  * version of this comment claimed a typo was "visible in one place rather than silently granting
  * nothing", which was false: nothing read the list except the two callers that turn it into an env var.
  * `checkServiceRoleRoutes` in `service-role-check.ts` is what actually resolves the names, and `push`
@@ -614,7 +614,7 @@ export function externalDatabaseUrl(cfg: SupatypeProjectConfig): string | undefi
  * Whether realtime should run.
  *
  * `false` only when stated. An external database that cannot support logical replication is detected
- * rather than declared — the capability record is what Studio and `doctor` read, so an operator who
+ * rather than declared: the capability record is what Studio and `doctor` read, so an operator who
  * has not thought about it gets a truthful answer instead of a silent default.
  */
 export function realtimeEnabled(cfg: SupatypeProjectConfig): boolean {
@@ -643,7 +643,7 @@ export const STACK_API_SCHEMAS = ["supatype", "graphql_public", "auth"] as const
  * while PostgREST kept serving `public`, so every request answered `PGRST106` and nothing in the
  * output mentioned the setting that caused it.
  *
- * `api_schemas` replaces the whole list when stated — including the stack schemas, so dropping
+ * `api_schemas` replaces the whole list when stated, including the stack schemas, so dropping
  * `supatype` from it is a supported way to stop exposing Studio's views. Order is preserved and
  * duplicates removed: PostgREST serves the first entry as the default profile, so the managed
  * schema has to lead.

package/src/pull-utils.ts

@@ -1,5 +1,5 @@
 /**
- * Utilities for `pull` and `introspect` — map engine DatabaseState to Model<> scaffold.
+ * Utilities for `pull` and `introspect`, map engine DatabaseState to Model<> scaffold.
  */
 
 export interface DbColumnState {
@@ -104,7 +104,7 @@ export function pgTypeToModelField(col: ColumnInfo): string {
     const base = name.replace(/_id$/, "")
     const rel = base.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
     const relName = rel.charAt(0).toUpperCase() + rel.slice(1)
-    return `${name}: UUID\n  // TODO: relation — RelatedTo<"${relName}">`
+    return `${name}: UUID\n  // TODO: relation, RelatedTo<"${relName}">`
   }
   if (name === "created_at" || name === "updated_at") {
     return `${name}: Timestamp`
@@ -160,7 +160,7 @@ export function databaseStateToSchemaScaffold(state: DatabaseStateJson): string
   const skipTables = new Set(["spatial_ref_sys", "schema_migrations"])
 
   const lines: string[] = [
-    "// DRAFT — generated by `supatype pull`. Review access rules, relations, and indexes before push.",
+    "// DRAFT: generated by `supatype pull`. Review access rules, relations, and indexes before push.",
     'import type { Model, Public, UUID, Timestamp, Optional, Unique, Email, Slug, SupatypeAuthUserId, JSON, Int, BigInt } from "@supatype/types"',
     "",
   ]
@@ -231,7 +231,7 @@ export function printIntrospectSummary(state: DatabaseStateJson): void {
   }
 }
 
-/** @deprecated Legacy pull helper — use {@link pgTypeToModelField}. */
+/** @deprecated Legacy pull helper, use {@link pgTypeToModelField}. */
 export function pgTypeToField(col: ColumnInfo): string {
   const opts: Record<string, unknown> = { required: !col.nullable }
   if (col.isPrimary) opts["primaryKey"] = true

package/src/realtime-launch.ts

@@ -46,7 +46,7 @@ export async function resolveRealtimeLaunch(
       return { bin: process.execPath, args: [entry] }
     }
     throw new Error(
-      "realtime binary not available — run `supatype update` or set overrides.realtime in supatype.config.ts",
+      "realtime binary not available, run `supatype update` or set overrides.realtime in supatype.config.ts",
     )
   }
 }

package/src/release-pins.ts

@@ -1,6 +1,6 @@
 /**
  * Release pins read from files under packages/cli/releases/.
- * CI (deno-releases workflow) uses the same paths — bump only releases/deno/VERSION.
+ * CI (deno-releases workflow) uses the same paths, bump only releases/deno/VERSION.
  */
 
 import { readFileSync } from "node:fs"
@@ -17,7 +17,7 @@ function readPinFile(...segments: string[]): string {
   } catch {
     throw new Error(
       `Missing release pin file: ${path}\n` +
-        "Expected packages/cli/releases/… — reinstall @supatype/cli or build from the monorepo.",
+        "Expected packages/cli/releases/…: reinstall @supatype/cli or build from the monorepo.",
     )
   }
   const version = raw.trim()

package/src/resolve-api-url.ts

@@ -2,7 +2,7 @@
  * Resolve the project API base URL (Kong gateway or direct server) for CLI HTTP calls.
  */
 
-import { loadConfig } from "./config.js"
+import { loadConfig, rethrowIfConfigBroken } from "./config.js"
 import { readEnvValue } from "./env-file.js"
 import { serverBaseUrl } from "./project-config.js"
 
@@ -34,8 +34,9 @@ export function resolveProjectApiUrl(cwd: string): string {
     if (fromConfig) {
       return fromConfig.replace(/\/+$/, "")
     }
-  } catch {
-    // No supatype.config — fall through to PORT default.
+  } catch (err) {
+    rethrowIfConfigBroken(err)
+    // No supatype.config: fall through to PORT default.
   }
 
   const port = readEnvValue(cwd, "PORT", "54321").trim() || "54321"

package/src/resolve-target.ts

@@ -48,7 +48,7 @@ export interface DeployTarget {
   refreshToken?: string | undefined
   orgId?: string | undefined
   link: ProjectLink | null
-  /** Project cwd — needed to persist refreshed cloud tokens. */
+  /** Project cwd: needed to persist refreshed cloud tokens. */
   cwd?: string
   /** Engine subprocess path when mode is direct or local without control plane. */
   databaseUrl?: string

package/src/rest-cache-admin.ts

@@ -34,7 +34,7 @@ function serviceRoleKey(cwd: string): string {
     readEnvValue(cwd, "SUPATYPE_SERVICE_ROLE_KEY", "").trim() ||
     readEnvValue(cwd, "SERVICE_ROLE_KEY", "").trim()
   if (!key) {
-    throw new Error("SERVICE_ROLE_KEY not found in .env — run supatype dev or supatype keys")
+    throw new Error("SERVICE_ROLE_KEY not found in .env, run supatype dev or supatype keys")
   }
   return key.trim()
 }
@@ -66,7 +66,7 @@ function formatCacheApiError(
     return "REST server cache is not available on this plan or deployment."
   }
   if (status === 503 && trimmed.includes("valkey")) {
-    return "Valkey is not configured — server-side REST cache requires Valkey (supatype dev with docker)."
+    return "Valkey is not configured, server-side REST cache requires Valkey (supatype dev with docker)."
   }
   return `${operation} failed (${status}): ${trimmed || "(empty body)"}`
 }

package/src/runtime-routes.ts

@@ -17,7 +17,7 @@ export interface RuntimeRouteOptions {
   functionsServiceUrl?: string
   /**
    * Self-host Compose: Kong forwards API traffic to supatype-server (unified gateway),
-   * which proxies to internal services — same model as `supatype dev`.
+   * which proxies to internal services, same model as `supatype dev`.
    */
   unifiedGateway?: boolean
   /** Studio UI upstream (default: in-compose `studio:3002`). */
@@ -161,7 +161,7 @@ function runtimeRouteSpecUnified(opts: RuntimeRouteOptions): RuntimeRoute[] {
 
 /**
  * Legacy split-stack routes (PostgREST/storage/realtime directly from Kong).
- * Kept for tests or explicit opt-out only — self-host uses unifiedGateway.
+ * Kept for tests or explicit opt-out only, self-host uses unifiedGateway.
  */
 function runtimeRouteSpecSplit(opts: RuntimeRouteOptions): RuntimeRoute[] {
   const studioUrl = studioServiceUrl(opts)

package/src/schema-ast-v2.ts

@@ -1,5 +1,5 @@
 /**
- * AST v2 wire format — canonical types and emitters.
+ * AST v2 wire format, canonical types and emitters.
  * Parsers build {@link ParsedField}; only `emitField` / `emitModel` / `emitSchema` produce JSON.
  */
 
@@ -30,7 +30,7 @@ export interface FieldAnnotations {
   platform?: PlatformFieldAnnotations
 }
 
-/** Kernel facts only — never db/platform keys at this layer. */
+/** Kernel facts only: never db/platform keys at this layer. */
 export interface KernelFieldFacts {
   required?: boolean
   primaryKey?: boolean
@@ -62,7 +62,7 @@ export interface KernelFieldFacts {
   index?: boolean
 }
 
-/** Internal parse result — not serialized. */
+/** Internal parse result: not serialized. */
 export interface ParsedField {
   kind: string
   kernel: KernelFieldFacts
@@ -302,7 +302,7 @@ export function emitModel(
     options,
     annotations: {
       db: { tableName, indexes },
-      // Hooks sit in `platform` beside `access`: they are an API-layer concern, not a column one —
+      // Hooks sit in `platform` beside `access`: they are an API-layer concern, not a column one,
       // supatype-server reads them, Postgres never sees them.
       platform: { access, ...(Object.keys(hooks).length > 0 && { hooks }) },
     },

package/src/schema-push-lock.ts

@@ -87,7 +87,7 @@ export async function withComposeSchemaPushLock<T>(
   //
   // Killing the local `docker` client does not stop the process inside the container: `docker
   // compose exec` does not forward the signal. With a sleeping session that meant every push
-  // left a backend holding this advisory lock for 24 hours — so `supatype push` never exited and
+  // left a backend holding this advisory lock for 24 hours, so `supatype push` never exited and
   // the next push blocked on it. Observed end-to-end before this change.
   //
   // Closing stdin *does* propagate: psql sees EOF, exits, and the session ends, which is what
@@ -102,7 +102,7 @@ export async function withComposeSchemaPushLock<T>(
   holder.stdin?.write(
     `SELECT pg_advisory_lock(${SCHEMA_PUSH_LOCK_CLASSID}, ${SCHEMA_PUSH_LOCK_OBJID});\n`,
   )
-  // Deliberately not ended — the open pipe is what keeps the session, and the lock, alive.
+  // Deliberately not ended: the open pipe is what keeps the session, and the lock, alive.
   holder.stderr?.on("data", (chunk: Buffer) => {
     stderrBuf += chunk.toString()
   })
@@ -131,7 +131,7 @@ export async function withComposeSchemaPushLock<T>(
 /**
  * End the holder session, then confirm the lock is actually gone.
  *
- * Closing stdin is the mechanism; the check is because a leaked holder is silent and expensive —
+ * Closing stdin is the mechanism; the check is because a leaked holder is silent and expensive,
  * it blocks every later push. If EOF did not do it, terminate the backend directly.
  */
 async function releaseHolder(

package/src/scripts/postinstall.ts

@@ -1,5 +1,5 @@
 /**
- * Postinstall script — @supatype/cli global/project install.
+ * Postinstall script: @supatype/cli global/project install.
  *
  * Host binaries (engine, server, postgres, deno) are downloaded on demand:
  * - native provider: first supatype dev / supatype update