@supatype/cli 0.2.0 → 0.3.0

package/src/model-hooks.ts

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { join, relative } from "node:path"
 import { generateHooksModule } from "./hooks-generator.js"
+import { manifestCache } from "./model-cache.js"
 
 export interface DeclaredHook {
   model: string
@@ -25,6 +26,8 @@ export function declaredHooks(ast: unknown): DeclaredHook[] {
 
   const out: DeclaredHook[] = []
   for (const model of models) {
+    // Guarded before the optional chains, not by them: see manifestHooks.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       name?: string
       annotations?: { platform?: { hooks?: Record<string, unknown> } }
@@ -132,6 +135,10 @@ export function manifestHooks(ast: unknown): Record<string, Record<string, Manif
 
   const out: Record<string, Record<string, ManifestHookEntry>> = {}
   for (const model of models) {
+    // Guarded before the optional chains, not by them: `x?.y` protects against `x.y` being
+    // nullish, not against `x` itself being null, so a malformed entry in the models array would
+    // throw a TypeError out of `supatype push` rather than being skipped.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       annotations?: {
         db?: { tableName?: string }
@@ -179,6 +186,8 @@ export function declaredValidators(ast: unknown): DeclaredValidator[] {
 
   const out: DeclaredValidator[] = []
   for (const model of models) {
+    // Guarded before the optional chains, not by them: see manifestHooks.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       name?: string
       annotations?: { platform?: { validate?: Record<string, unknown> } }
@@ -210,6 +219,10 @@ export function manifestValidators(ast: unknown): Record<string, Record<string,
 
   const out: Record<string, Record<string, ManifestHookEntry>> = {}
   for (const model of models) {
+    // Guarded before the optional chains, not by them: `x?.y` protects against `x.y` being
+    // nullish, not against `x` itself being null, so a malformed entry in the models array would
+    // throw a TypeError out of `supatype push` rather than being skipped.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       annotations?: {
         db?: { tableName?: string }
@@ -281,6 +294,11 @@ export const DEFAULT_HOOK_TIMEOUT_MS = 2000
  * the worse half of that: the schema says the field is checked, and no error appears anywhere,
  * because the write simply succeeds.
  *
+ * `cache` is here for a third reason of the same kind: the declaration is a ceiling the server
+ * enforces, and a manifest carrying a stale one lets a table be cached that the schema has since
+ * stopped permitting — or stops one the schema now allows, which is merely slow rather than wrong.
+ * The first of those is why it is written at push and not left to drift.
+ *
  * **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
@@ -302,7 +320,8 @@ export function syncManifestHooks(cwd: string, ast: unknown): boolean {
 
   const changedHooks = applyManifestMap(parsed, "hooks", manifestHooks(ast))
   const changedValidators = applyManifestMap(parsed, "validators", manifestValidators(ast))
-  if (!changedHooks && !changedValidators) return false
+  const changedCache = applyManifestMap(parsed, "cache", manifestCache(ast))
+  if (!changedHooks && !changedValidators && !changedCache) return false
 
   writeFileSync(manifestPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8")
   return true
@@ -315,10 +334,15 @@ export function syncManifestHooks(cwd: string, ast: unknown): boolean {
  * when it decides whether the manifest predates the feature, and an empty object left behind by a
  * schema that no longer declares any is not the same statement.
  */
+/**
+ * `Record<string, unknown>` rather than a hook map: this never looks inside a value, it compares
+ * the serialised form and swaps it. It was typed to hooks only because hooks were the first caller,
+ * and that narrowness is what a third key would otherwise have had to work around.
+ */
 function applyManifestMap(
   manifest: Record<string, unknown>,
   key: string,
-  map: Record<string, Record<string, ManifestHookEntry>>,
+  map: Record<string, unknown>,
 ): boolean {
   const next = JSON.stringify(map)
   if (next === JSON.stringify(manifest[key] ?? {})) return false

package/src/model-versioning.ts

@@ -0,0 +1,167 @@
+/**
+ * Which models keep drafts and version history, read from the extracted schema.
+ *
+ * The answer shapes things decided before any database exists: whether `PGRST_DB_SCHEMA` names the
+ * generated `draft` schema, and whether the push refuses a model that also masks a column. So it is
+ * read from the AST rather than asked of Postgres, the same way
+ * [`field-masking-tier`](./field-masking-tier.ts) decides the masking tier offline.
+ *
+ * Shaped loosely on purpose: the CLI's AST carries `options` as an opaque record, and nothing here
+ * needs more than "is `versions` present, and what did it ask for".
+ */
+
+import { existsSync } from "node:fs"
+import { loadSchemaAst } from "./config.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
+import { draftVisibilityRoles, previewLimits, schemaPathFromProject } from "./project-config.js"
+
+/** Versions kept per record when the model states no retention. */
+export const DEFAULT_VERSIONS_KEPT = 20
+
+/** What a model's `versions` declaration resolves to. */
+export type VersionsOptions = {
+  /** Editing writes a draft version rather than the live row. */
+  drafts: boolean
+  /** Versions kept per record, oldest pruned beyond it. */
+  keep: number
+}
+
+/** One versioned model, as the callers of this module need it. */
+export type VersionedModel = {
+  /** The model's declared name, for an error message that names what the author wrote. */
+  name: string
+  /** Its table, which is what `<table>_versions` and `draft.<table>` are named after. */
+  tableName: string
+  options: VersionsOptions
+}
+
+type LooseModel = {
+  name?: unknown
+  options?: Record<string, unknown>
+  annotations?: { db?: { tableName?: unknown }; platform?: { access?: Record<string, unknown> } }
+}
+
+/**
+ * Normalise a `versions` value from the AST.
+ *
+ * `true` is shorthand for `{ drafts: true }` with the default retention, and a non-positive or
+ * unparseable `keep` falls back to the default rather than to "keep nothing": pruning to zero would
+ * delete the draft the author is editing.
+ */
+export function resolveVersionsOptions(raw: unknown): VersionsOptions | undefined {
+  if (raw === true) return { drafts: true, keep: DEFAULT_VERSIONS_KEPT }
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as { drafts?: unknown; keep?: unknown }
+  const keep =
+    typeof record.keep === "number" && Number.isFinite(record.keep) && record.keep >= 1
+      ? Math.floor(record.keep)
+      : DEFAULT_VERSIONS_KEPT
+  return { drafts: record.drafts !== false, keep }
+}
+
+/** Every model in the schema that declares `versions`, in declaration order. */
+export function versionedModels(ast: unknown): VersionedModel[] {
+  const models = (ast as { models?: unknown[] } | null)?.models
+  if (!Array.isArray(models)) return []
+
+  const out: VersionedModel[] = []
+  for (const entry of models) {
+    const model = entry as LooseModel | null
+    if (model === null || typeof model !== "object") continue
+    const options = resolveVersionsOptions(model.options?.["versions"])
+    if (options === undefined) continue
+    const name = typeof model.name === "string" ? model.name : ""
+    const tableName = model.annotations?.db?.tableName
+    out.push({
+      name,
+      tableName: typeof tableName === "string" ? tableName : name,
+      options,
+    })
+  }
+  return out
+}
+
+/** Whether anything in the schema is versioned, which is what exposes the `draft` schema. */
+export function schemaHasVersionedModels(ast: unknown): boolean {
+  return versionedModels(ast).length > 0
+}
+
+/**
+ * Models declaring both `versions` and per-column rules, which cannot both be enforced.
+ *
+ * A version snapshot is opaque `jsonb`. `supatype_mask` is driven by security labels on a specific
+ * table's column and rewrites references to *that* column, and the view tier puts the masking
+ * expression in a view over the real columns: neither can see inside a snapshot. So a masked value
+ * sits in plain sight in the versions table for anyone able to read it, and the push refuses rather
+ * than applying a schema whose restrictions have a hole in them.
+ *
+ * Per model, and that matters: under the view tier the managed schema comes off the exposed list but
+ * the API roles keep their privileges on the base tables, so a `security_invoker` view in an exposed
+ * schema — which is exactly what `draft.<table>` is — reaches past the `api` layer. A project may
+ * hold a masked model and a versioned model at once; one model may not be both.
+ */
+export function modelsWithVersionsAndFieldRules(ast: unknown): string[] {
+  const models = (ast as { models?: unknown[] } | null)?.models
+  if (!Array.isArray(models)) return []
+
+  const out: string[] = []
+  for (const entry of models) {
+    const model = entry as LooseModel | null
+    if (model === null || typeof model !== "object") continue
+    if (resolveVersionsOptions(model.options?.["versions"]) === undefined) continue
+    const fields = model.annotations?.platform?.access?.["fields"]
+    if (typeof fields !== "object" || fields === null || Object.keys(fields).length === 0) continue
+    out.push(typeof model.name === "string" ? model.name : "(unnamed model)")
+  }
+  return out
+}
+
+/**
+ * Whether this project on disk has any versioned model.
+ *
+ * A schema that fails to load reads as "no versioned models", the narrower answer: deciding the
+ * exposed-schema list is the wrong moment to report a syntax error, and `push` and `dev` do it
+ * properly moments later with the file and line. Narrower rather than wider on purpose, since the
+ * failure mode of guessing wrong here is exposing a schema of drafts.
+ */
+export function projectHasVersionedModels(cwd: string, config: SupatypeProjectConfig): boolean {
+  try {
+    const schemaPath = schemaPathFromProject(config, cwd)
+    if (!existsSync(schemaPath)) return false
+    return schemaHasVersionedModels(loadSchemaAst(schemaPath, cwd))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The AST with this project's publishing settings attached, when anything is versioned.
+ *
+ * The engine compiles draft visibility into the generated policies, and it **refuses** a push whose
+ * schema has versioned models and carries no settings rather than applying a default. That refusal
+ * is the reason this is safe to add at a handful of call sites instead of somewhere unmissable: a
+ * path that forgets fails loudly at push time, naming what is missing, rather than quietly
+ * narrowing or widening who can read unpublished content.
+ *
+ * Returns the AST untouched for a project with no versioned model, so nothing else grows a key it
+ * has no use for.
+ */
+export function withPublishing(
+  ast: ExtractedSchemaAstV2,
+  config: SupatypeProjectConfig,
+): ExtractedSchemaAstV2 {
+  if (!schemaHasVersionedModels(ast)) return ast
+
+  const limits = previewLimits(config)
+  return {
+    ...ast,
+    publishing: {
+      draftVisibility: draftVisibilityRoles(config),
+      previewDefaultTtl: limits.defaultTtl,
+      previewMaxRecordTtl: limits.maxRecordTtl,
+      previewMaxProjectTtl: limits.maxProjectTtl,
+      previewAllowProjectScope: limits.allowProjectScope,
+    },
+  }
+}

package/src/postgres-ctl.ts

@@ -16,6 +16,15 @@ export interface PgOptions {
   port: number
   /** Path to write the postgres log file. */
   logPath?: string
+  /**
+   * Port for the RESP keyspace, when the native install carries pg_keyspace.
+   *
+   * Absent means do not serve RESP at all: `supatype dev` then starts the
+   * Valkey sidecar instead, as it always has.
+   */
+  keyspacePort?: number
+  /** Database durable keys are written to. Ignored while everything is ephemeral. */
+  keyspaceDatabase?: string
 }
 
 /**
@@ -83,31 +92,116 @@ export function initdb(opts: PgOptions): void {
  * `lib/postgresql/`.
  */
 export function nativeMaskLibraryPresent(pgBinDir: string | null | undefined): boolean {
+  return nativeLibraryPresent(pgBinDir, "supatype_mask")
+}
+
+/**
+ * Whether a native Postgres install carries the RESP keyspace.
+ *
+ * Asked of the filesystem for the same reason as the mask: an archive
+ * downloaded before pg_keyspace was bundled has a Postgres without it, and the
+ * Windows archive has none at all — pgrx has no Windows target. Naming it in
+ * `shared_preload_libraries` anyway would stop the server starting with "could
+ * not access file", which would turn a missing cache into no database.
+ */
+export function nativeKeyspaceLibraryPresent(pgBinDir: string | null | undefined): boolean {
+  return nativeLibraryPresent(pgBinDir, "pg_keyspace")
+}
+
+/**
+ * Two layouts: Linux and macOS put extension libraries in `lib/`, the Windows
+ * archive in `lib/postgresql/`.
+ */
+function nativeLibraryPresent(pgBinDir: string | null | undefined, stem: string): boolean {
   if (!pgBinDir) return false
   const prefix = resolvePath(pgBinDir, "..")
-  return ["supatype_mask.so", "supatype_mask.dylib", "supatype_mask.dll"].some(
+  return [`${stem}.so`, `${stem}.dylib`, `${stem}.dll`].some(
     (lib) =>
       existsSync(join(prefix, "lib", lib)) || existsSync(join(prefix, "lib", "postgresql", lib)),
   )
 }
 
+/**
+ * Where the native RESP keyspace looks for a free port, and how far it looks.
+ *
+ * 6379 first, because that is what a developer's tooling and the Valkey
+ * sidecar before it both used, so the familiar port stays the usual answer.
+ */
+export const KEYSPACE_PORT_BASE = 6379
+export const KEYSPACE_PORT_SPAN = 10
+
+/**
+ * The first free port in [base, base + span), or null when they are all taken.
+ *
+ * Binding a port something else already holds would leave Postgres up and the
+ * keyspace silently dead — the failure lands in the postmaster log and nowhere
+ * a developer is looking — so the port is chosen before the server starts
+ * rather than fixed and hoped for.
+ */
+export async function firstFreePort(base: number, span: number): Promise<number | null> {
+  for (let port = base; port < base + span; port++) {
+    if (!(await isPortInUse(port))) return port
+  }
+  return null
+}
+
+/**
+ * The `-o` options pg_ctl passes to the server.
+ *
+ * Separated from the spawn so the decision is testable. What goes in here is
+ * decided by which libraries the archive happens to carry, which is exactly
+ * the kind of thing that is wrong in one combination nobody runs locally.
+ *
+ * Order in `shared_preload_libraries` is load-bearing: pg_keyspace first, then
+ * supatype_mask, so the mask stays outermost. pg_keyspace checks this itself
+ * and refuses to serve when the order is wrong — deliberately, since RESP
+ * would otherwise hand back rows the mask never rewrote.
+ *
+ * The sizing is the measured dev profile: ~60 MiB of shared memory, against
+ * the extension's own defaults of ~689 MiB before rings and row cache. It is
+ * reserved at postmaster start whether or not anything caches, so a local
+ * Postgres should not ask for a production keyspace. Durability is ephemeral
+ * throughout: nothing in a dev keyspace is the only copy of anything.
+ */
+export function pgServerOptions(opts: PgOptions): string {
+  const mask = nativeMaskLibraryPresent(opts.pgBinDir)
+  const keyspace = opts.keyspacePort !== undefined && nativeKeyspaceLibraryPresent(opts.pgBinDir)
+
+  const libs = [...(keyspace ? ["pg_keyspace"] : []), ...(mask ? ["supatype_mask"] : [])]
+  const parts = [`-p ${opts.port}`]
+  if (libs.length > 0) parts.push(`-c shared_preload_libraries=${libs.join(",")}`)
+  if (keyspace) {
+    parts.push(
+      `-c pg_keyspace.port=${opts.keyspacePort}`,
+      "-c pg_keyspace.durability=ephemeral",
+      "-c pg_keyspace.keys=50000",
+      "-c pg_keyspace.ring_mb=8",
+      "-c pg_keyspace.rowcache_mb=1",
+    )
+    if (opts.keyspaceDatabase) {
+      parts.push(`-c pg_keyspace.database=${opts.keyspaceDatabase}`)
+    }
+  }
+  return parts.join(" ")
+}
+
 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
-  // 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".
+  // `supatype_mask` is a planner hook and pg_keyspace registers background
+  // workers and shared memory, so both have to be preloaded — `CREATE
+  // EXTENSION` alone does nothing for either. Only when the archive actually
+  // carries them; see pgServerOptions.
   //
-  // Native Postgres was started with no preloaded libraries at all until now, which is why field
-  // rules could not be enforced on the default `supatype dev`.
-  const preload = nativeMaskLibraryPresent(opts.pgBinDir) ? " -c shared_preload_libraries=supatype_mask" : ""
-
+  // Native Postgres was started with no preloaded libraries at all until the
+  // mask, which is why field rules could not be enforced on the default
+  // `supatype dev`.
   const args = [
     "start",
     "-D", opts.dataDir,
     "-l", logPath,
-    "-o", `-p ${opts.port}${preload}`,
+    "-o", pgServerOptions(opts),
     "--wait",
   ]
 

package/src/preview-config-check.ts

@@ -0,0 +1,52 @@
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+/**
+ * Preview addresses that can never resolve, named before a push writes them.
+ *
+ * A preview address may be a path when this deployment serves the project's app: `app.mode` of
+ * `static` or `proxy` puts the app at `/` on the same origin as the API, and Studio resolves the
+ * path against the origin it is loaded from. That is the point of allowing a path at all, because
+ * the origin is a deployment fact and repeating it in config only lets it go stale.
+ *
+ * With `app.mode: "none"` nothing is served at `/`. A path then resolves against an origin that
+ * answers 404, so the share control hands somebody a link that looks right and opens nothing. The
+ * failure surfaces to whoever was sent the link rather than to whoever configured it, which is the
+ * worst place for it to land, so it is refused here instead.
+ *
+ * Returns the models at fault, so a caller can name all of them in one message rather than making
+ * an operator fix them one push at a time.
+ */
+export function modelsWithUnresolvablePreview(config: SupatypeProjectConfig): string[] {
+  if (config.app.mode !== "none") return []
+
+  const livePreview = config.admin?.livePreview
+  if (livePreview === undefined) return []
+
+  return Object.entries(livePreview)
+    .filter(([, entry]) => {
+      const address =
+        entry.urlPattern !== undefined && entry.urlPattern !== "" ? entry.urlPattern : entry.url
+      // Nothing stated at all is not this check's business: Studio asks for the setting, and a
+      // project that has not configured previews for a model is not misconfigured.
+      if (address === undefined || address === "") return false
+      return !namesAnOrigin(address)
+    })
+    .map(([model]) => model)
+    .sort()
+}
+
+/** True when the address carries its own origin and needs nothing added to it. */
+function namesAnOrigin(address: string): boolean {
+  // Protocol-relative counts: `//example.com/x` already names a host.
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(address) || address.startsWith("//")
+}
+
+/** The refusal headline. The two ways out are hints, in the caller, as every other refusal does. */
+export function unresolvablePreviewMessage(models: string[]): string {
+  const plural = models.length > 1
+  return (
+    `admin.livePreview gives a path for ${models.join(", ")}, but app.mode is "none", ` +
+    `so this deployment serves nothing at / for ${plural ? "those paths" : "that path"} ` +
+    `to resolve against.`
+  )
+}