@supatype/cli 0.1.6 → 0.1.9

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

@@ -35,7 +35,7 @@ export function resolveProjectApiUrl(cwd: string): string {
       return fromConfig.replace(/\/+$/, "")
     }
   } catch {
-    // No supatype.config — fall through to PORT default.
+    // No supatype.config: fall through to PORT default.
   }
 
   const port = readEnvValue(cwd, "PORT", "54321").trim() || "54321"

package/src/resolve-target.ts

@@ -6,6 +6,7 @@ import { ensureEngine, engineRequest } from "./engine-client.js"
 import type { SchemaSourcesPayload } from "./schema-sources.js"
 import {
   connectionString,
+  pgSchema,
   resolveRuntimeProvider,
   schemaPathFromProject,
   serverBaseUrl,
@@ -20,7 +21,12 @@ import {
   type LocalEnvironment,
   type ProjectLink,
 } from "./link.js"
-import { targetFetch } from "./target-client.js"
+import {
+  persistCloudSession,
+  resolveCloudAccessToken,
+  resolveCloudRefreshToken,
+} from "./cloud-credentials.js"
+import { targetFetch, type TargetFetchOptions } from "./target-client.js"
 
 export interface ResolveTargetFlags {
   env?: string | undefined
@@ -38,8 +44,12 @@ export interface DeployTarget {
   apiBaseUrl: string
   apiPrefix: "/api/v1" | "/platform/v1"
   token?: string | undefined
+  /** Cloud GoTrue refresh token (mode === "cloud" only). */
+  refreshToken?: string | undefined
   orgId?: string | undefined
   link: ProjectLink | null
+  /** Project cwd: needed to persist refreshed cloud tokens. */
+  cwd?: string
   /** Engine subprocess path when mode is direct or local without control plane. */
   databaseUrl?: string
 }
@@ -147,12 +157,19 @@ export function resolveTarget(cwd: string, flags: ResolveTargetFlags = {}): Depl
     )
   }
 
-  const token = resolveEnvironmentToken(link, envTarget)
+  const token =
+    (link.kind === "cloud" ? resolveCloudAccessToken(link) : undefined) ??
+    resolveEnvironmentToken(link, envTarget)
   if (!token) {
-    throw new Error(`No token for environment "${envName}". Re-run supatype link --token ...`)
+    throw new Error(
+      link.kind === "cloud"
+        ? `No cloud session for environment "${envName}". Run: supatype login`
+        : `No token for environment "${envName}". Re-run supatype link --token ...`,
+    )
   }
 
   if (link.kind === "cloud") {
+    const refreshToken = resolveCloudRefreshToken(link)
     return {
       mode: "cloud",
       environment: envName,
@@ -161,6 +178,8 @@ export function resolveTarget(cwd: string, flags: ResolveTargetFlags = {}): Depl
       apiPrefix: "/api/v1",
       token,
       link,
+      cwd,
+      ...(refreshToken !== undefined ? { refreshToken } : {}),
       ...(link.orgId !== undefined ? { orgId: link.orgId } : {}),
     }
   }
@@ -173,6 +192,44 @@ export function resolveTarget(cwd: string, flags: ResolveTargetFlags = {}): Depl
     apiPrefix: "/platform/v1",
     token,
     link,
+    cwd,
+  }
+}
+
+function cloudAuthRefresh(target: DeployTarget): TargetFetchOptions["authRefresh"] | undefined {
+  if (target.mode !== "cloud" || !target.refreshToken || !target.cwd) return undefined
+  const cloudApiUrl = (target.link?.cloudApiUrl ?? target.apiBaseUrl).replace(/\/$/, "")
+  const cwd = target.cwd
+  return {
+    cloudApiUrl,
+    refreshToken: target.refreshToken,
+    onRefreshed: ({ accessToken, refreshToken }) => {
+      persistCloudSession(cwd, {
+        apiUrl: cloudApiUrl,
+        accessToken,
+        ...(refreshToken !== undefined ? { refreshToken } : {}),
+      })
+      target.token = accessToken
+      if (refreshToken !== undefined) target.refreshToken = refreshToken
+    },
+  }
+}
+
+function apiFetchOpts(
+  target: DeployTarget,
+  method: string,
+  path: string,
+  body?: unknown,
+): TargetFetchOptions {
+  const authRefresh = cloudAuthRefresh(target)
+  return {
+    method,
+    path,
+    token: target.token!,
+    ...(body !== undefined ? { body } : {}),
+    ...(target.orgId !== undefined ? { orgId: target.orgId } : {}),
+    ...(target.mode === "cloud" ? { environment: target.environment } : {}),
+    ...(authRefresh !== undefined ? { authRefresh } : {}),
   }
 }
 
@@ -194,14 +251,14 @@ export async function targetSchemaDiff(
     })
   }
 
-  return targetFetch<DiffResult>(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/diff"),
-    body: { ast, schema: opts?.schema ?? "public" },
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch<DiffResult>(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/diff"), {
+      ast,
+      schema: opts?.schema ?? "public",
+    }),
+  )
 }
 
 export async function targetSchemaPush(
@@ -236,14 +293,11 @@ export async function targetSchemaPush(
     }
   }
 
-  return targetFetch(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/push"),
-    body: pushBody,
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/push"), pushBody),
+  )
 }
 
 export interface SchemaRollbackResult {
@@ -286,14 +340,13 @@ export async function targetSchemaRollback(
     })
   }
 
-  return targetFetch<SchemaRollbackResult>(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/rollback"),
-    body: { schema: opts?.schema ?? "public" },
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch<SchemaRollbackResult>(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/rollback"), {
+      schema: opts?.schema ?? "public",
+    }),
+  )
 }
 
 export async function targetListMigrations(
@@ -308,13 +361,11 @@ export async function targetListMigrations(
     return Array.isArray(result) ? result : (result.migrations ?? [])
   }
 
-  return targetFetch<MigrationListEntry[]>(target.apiBaseUrl, target.apiPrefix, {
-    method: "GET",
-    path: projectPath(target, "/schema/migrations"),
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch<MigrationListEntry[]>(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "GET", projectPath(target, "/schema/migrations")),
+  )
 }
 
 export async function targetSchemaDoctor(
@@ -332,14 +383,15 @@ export async function targetSchemaDoctor(
     })
   }
 
-  return targetFetch(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/doctor"),
-    body: { ast, no_cache: opts?.noCache ?? false, schema: opts?.schema ?? "public" },
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/doctor"), {
+      ast,
+      no_cache: opts?.noCache ?? false,
+      schema: opts?.schema ?? "public",
+    }),
+  )
 }
 
 export async function targetSchemaIntrospect(
@@ -354,14 +406,13 @@ export async function targetSchemaIntrospect(
     })
   }
 
-  return targetFetch(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/introspect"),
-    body: { schema: opts?.schema ?? "public" },
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/introspect"), {
+      schema: opts?.schema ?? "public",
+    }),
+  )
 }
 
 export async function targetSchemaAdopt(
@@ -381,20 +432,17 @@ export async function targetSchemaAdopt(
     })
   }
 
-  return targetFetch(target.apiBaseUrl, target.apiPrefix, {
-    method: "POST",
-    path: projectPath(target, "/schema/adopt"),
-    body: {
+  return targetFetch(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "POST", projectPath(target, "/schema/adopt"), {
       ast,
       schema: opts?.schema ?? "public",
       yes: opts?.yes ?? false,
       no_cache: opts?.noCache ?? false,
       ...(opts?.names !== undefined ? { names: opts.names } : {}),
-    },
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+    }),
+  )
 }
 
 export async function targetStatus(target: DeployTarget): Promise<unknown> {
@@ -402,18 +450,15 @@ export async function targetStatus(target: DeployTarget): Promise<unknown> {
     return { mode: "direct", environment: target.environment }
   }
 
-  return targetFetch(target.apiBaseUrl, target.apiPrefix, {
-    method: "GET",
-    path: projectPath(target, "/status"),
-    token: target.token!,
-    orgId: target.orgId,
-    environment: target.mode === "cloud" ? target.environment : undefined,
-  })
+  return targetFetch(
+    target.apiBaseUrl,
+    target.apiPrefix,
+    apiFetchOpts(target, "GET", projectPath(target, "/status")),
+  )
 }
 
 export function schemaPgSchema(cwd: string): string {
-  const config = loadConfig(cwd)
-  return config.schema?.pg_schema ?? "public"
+  return pgSchema(loadConfig(cwd))
 }
 
 export { schemaPathFromProject }

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
@@ -88,7 +88,7 @@ export interface ModelAstV2 {
   options: Record<string, unknown>
   annotations: {
     db: { tableName: string; indexes: unknown[] }
-    platform: { access: Record<string, unknown> }
+    platform: { access: Record<string, unknown>; hooks?: Record<string, unknown> }
   }
 }
 
@@ -294,6 +294,7 @@ export function emitModel(
   tableName: string,
   access: Record<string, unknown>,
   indexes: unknown[] = [],
+  hooks: Record<string, unknown> = {},
 ): ModelAstV2 {
   return {
     name,
@@ -301,7 +302,9 @@ export function emitModel(
     options,
     annotations: {
       db: { tableName, indexes },
-      platform: { access },
+      // 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

@@ -83,16 +83,26 @@ export async function withComposeSchemaPushLock<T>(
   composeProject: string,
   fn: () => Promise<T>,
 ): Promise<T> {
-  const holdSql =
-    `SELECT pg_advisory_lock(${SCHEMA_PUSH_LOCK_CLASSID}, ${SCHEMA_PUSH_LOCK_OBJID});` +
-    ` SELECT pg_sleep(86400);`
-  const args = dbExecArgs(paths, cwd, composeProject, ["-c", holdSql])
+  // The lock is held by a psql session reading from **stdin**, not by `-c … pg_sleep(86400)`.
+  //
+  // 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
+  // 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
+  // releases an advisory lock. Deterministic, and it needs no signal to cross the boundary.
+  const args = dbExecArgs(paths, cwd, composeProject, ["-f", "-"])
 
   let stderrBuf = ""
   const holder: ChildProcess = spawn("docker", args, {
     cwd,
-    stdio: ["ignore", "pipe", "pipe"],
+    stdio: ["pipe", "pipe", "pipe"],
   })
+  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.
   holder.stderr?.on("data", (chunk: Buffer) => {
     stderrBuf += chunk.toString()
   })
@@ -114,18 +124,47 @@ export async function withComposeSchemaPushLock<T>(
   try {
     return await fn()
   } finally {
-    if (holder.exitCode === null) {
-      holder.kill("SIGTERM")
-      await new Promise<void>((resolveDone) => {
-        const t = setTimeout(() => {
-          holder.kill("SIGKILL")
-          resolveDone()
-        }, 3000)
-        holder.once("exit", () => {
-          clearTimeout(t)
-          resolveDone()
-        })
+    await releaseHolder(holder, paths, cwd, composeProject)
+  }
+}
+
+/**
+ * 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,
+ * it blocks every later push. If EOF did not do it, terminate the backend directly.
+ */
+async function releaseHolder(
+  holder: ChildProcess,
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+): Promise<void> {
+  if (holder.exitCode === null) {
+    holder.stdin?.end()
+    await new Promise<void>((resolveDone) => {
+      const t = setTimeout(() => {
+        holder.kill("SIGKILL")
+        resolveDone()
+      }, 5000)
+      holder.once("exit", () => {
+        clearTimeout(t)
+        resolveDone()
       })
-    }
+    })
   }
+
+  if (!schemaPushLockIsHeld(paths, cwd, composeProject)) return
+
+  // Last resort: the session outlived its client. Ending it releases the lock.
+  spawnSync(
+    "docker",
+    dbExecArgs(paths, cwd, composeProject, [
+      "-tAc",
+      `SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+         WHERE pid <> pg_backend_pid()
+           AND query LIKE '%pg_advisory_lock(${SCHEMA_PUSH_LOCK_CLASSID}, ${SCHEMA_PUSH_LOCK_OBJID})%'`,
+    ]),
+    { cwd, stdio: "ignore" },
+  )
 }

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