@supatype/cli 0.2.0 → 0.3.0

package/src/project-config.ts

@@ -100,6 +100,44 @@ export interface SupatypeProjectConfig {
       provider?: "kong" | "none"
     }
   }
+  /**
+   * Where the REST response cache and Kong's ACME certificates live.
+   *
+   * Both speak RESP, so this is a choice of server rather than of feature.
+   */
+  cache?: {
+    /**
+     * "pg_keyspace" (default) = the RESP keyspace inside the Postgres
+     *                           container, so the stack runs one stateful
+     *                           service instead of two.
+     * "valkey"                = a Valkey sidecar container.
+     *
+     * pg_keyspace needs `shared_preload_libraries`, which is a property of the
+     * Postgres this stack starts — so it is only available when Supatype
+     * provisions the database. With `database.external` the default resolves
+     * to Valkey, because there is no container to configure; asking for
+     * pg_keyspace explicitly there is rejected rather than ignored.
+     *
+     * Set "valkey" to keep the sidecar. Nothing about the cache's behaviour
+     * changes with the answer — both speak RESP and both hold the same keys.
+     */
+    provider?: "valkey" | "pg_keyspace"
+    /**
+     * Extra key prefixes to persist when `provider` is "pg_keyspace".
+     *
+     * The keyspace is a cache: everything is ephemeral, living in shared
+     * memory and not surviving a restart of the database. The exception is
+     * Kong's ACME certificates, which are always kept — you do not have to
+     * name them, and re-issuing them on every restart would meet Let's
+     * Encrypt's rate limits.
+     *
+     * List a prefix here only for something you are storing yourself that
+     * must outlive a restart. Each durable write goes through the WAL, which
+     * is the cost being avoided everywhere else. Each entry is a prefix of the
+     * key as stored — see `pg_keyspace.durability_overrides`.
+     */
+    durablePrefixes?: string[]
+  }
   app: {
     /**
      * How the root path "/" is handled by supatype-server.
@@ -225,6 +263,54 @@ export interface SupatypeProjectConfig {
      */
     api_schemas?: readonly string[]
   }
+  /**
+   * Drafts and preview links, for the models that declare `versions`.
+   *
+   * Project-wide rather than per model: a draft is a draft whichever model it belongs to, and a
+   * reviewer granted sight of one is not granted it a table at a time.
+   */
+  publishing?: {
+    /**
+     * Studio roles that see every unpublished draft and its history, beyond the record's own
+     * creator. Defaults to all three, `["admin", "developer", "editor"]`.
+     *
+     * The record's creator always sees their own drafts and is not listed here. Narrowing this is
+     * the interesting case, and it has a trap: whoever may **update** a record may draft and publish
+     * it, so a role that can edit but cannot see drafts will build its save on the live row and
+     * discard a colleague's pending work. Take a role off this list only where it also cannot edit.
+     *
+     * An empty list narrows visibility to creators alone.
+     *
+     * `anon` is never on this list and cannot be put on it. A draft schema readable without
+     * credentials would make publishing mean nothing.
+     *
+     * Studio can override this at runtime for a project that needs to change it without a push.
+     * This is the reviewable default that lives in git.
+     */
+    draft_visibility?: readonly ("admin" | "developer" | "editor")[]
+    /** Signed, expiring links that let someone without an account read a draft. */
+    preview?: {
+      /** Lifetime of a minted link when the request does not ask for one, in seconds. Default 900. */
+      default_ttl?: number
+      /** Ceiling for a link covering one record, in seconds. Default 604800, seven days. */
+      max_record_ttl?: number
+      /**
+       * Ceiling for a link covering every draft in the project, in seconds. Default 86400, one day.
+       *
+       * Shorter than a record link on purpose: the blast radius is every unpublished draft there is,
+       * so the window in which a leaked link is still worth anything should be smaller.
+       */
+      max_project_ttl?: number
+      /**
+       * Whether project-scoped links may be minted at all. Default true.
+       *
+       * Set false for a project where nothing should ever be shareable in bulk; record links keep
+       * working. Minting one is already restricted to `admin` and `developer`, since nobody can
+       * grant sight of drafts they cannot see themselves.
+       */
+      allow_project_scope?: boolean
+    }
+  }
   functions?: {
     /** Path to edge functions directory, relative to `supatype.root` when not absolute. */
     path?: string
@@ -286,6 +372,37 @@ export interface SupatypeProjectConfig {
   admin?: {
     /** JWT `app_metadata.role` values allowed to use Studio. Default: admin, supatype_admin */
     roles?: string[]
+    /**
+     * Where each model renders in your own front end, keyed by model name.
+     *
+     * Studio needs this for two things that look alike and are not: the live preview pane, which
+     * streams unsaved keystrokes into an iframe, and a shared preview link, which points somebody
+     * with no account at a saved draft. Both need the same answer to "what is the address of this
+     * record", and neither can guess it.
+     *
+     * Without it there is no share link to give out. Studio says so rather than handing over the
+     * bare code, because a credential with nowhere to open it reads as a bug.
+     *
+     * `urlPattern` names fields in braces and they are filled from the record in hand, so a post
+     * previews at the address its current slug implies.
+     *
+     * **A path is enough when this deployment serves the app.** With `app.mode` set to `static` or
+     * `proxy`, the app is served at `/` on the same origin as the API, and Studio resolves a path
+     * against the origin it is loaded from. Writing the origin out again only risks it going stale:
+     *
+     * ```ts
+     * admin: { livePreview: { Post: { urlPattern: "/preview/{slug}" } } }
+     * ```
+     *
+     * With `app.mode: "none"` the app is somewhere else and no deployment fact can say where, so
+     * give an absolute URL. `supatype push` refuses a path-only pattern in that mode rather than
+     * letting it become a link that resolves to nothing.
+     *
+     * ```ts
+     * admin: { livePreview: { Post: { urlPattern: "https://example.com/preview/{slug}" } } }
+     * ```
+     */
+    livePreview?: Record<string, { url?: string; urlPattern?: string }>
   }
 }
 
@@ -407,10 +524,54 @@ export function validateProjectConfig(raw: unknown, filename: string): SupatypeP
   }
 
   validateExternalDatabase(cfg, filename)
+  validateCache(cfg, filename)
 
   return raw as SupatypeProjectConfig
 }
 
+/**
+ * `cache.provider = "pg_keyspace"` describes how the Postgres this stack
+ * starts is configured, so it cannot be honoured against a database Supatype
+ * does not manage. Rejected rather than silently falling back to Valkey: a
+ * stack that quietly runs the thing you switched away from is worse than one
+ * that will not start.
+ */
+function validateCache(cfg: Record<string, unknown>, filename: string): void {
+  const cache = cfg["cache"] as Record<string, unknown> | undefined
+  if (!cache) return
+  const provider = cache["provider"]
+  if (provider !== undefined && provider !== "valkey" && provider !== "pg_keyspace") {
+    throw new Error(
+      `${filename}: cache.provider must be "valkey" or "pg_keyspace" (got ${JSON.stringify(provider)})`,
+    )
+  }
+  const database = cfg["database"] as Record<string, unknown> | undefined
+  if (provider === "pg_keyspace" && database?.["external"]) {
+    throw new Error(
+      `${filename}: cache.provider = "pg_keyspace" needs the Postgres this stack starts — ` +
+        `it is loaded with shared_preload_libraries, which is not something Supatype can set on ` +
+        `a database.external one. Use cache.provider = "valkey", or drop database.external.`,
+    )
+  }
+  const prefixes = cache["durablePrefixes"]
+  if (prefixes !== undefined) {
+    if (!Array.isArray(prefixes) || prefixes.some((p) => typeof p !== "string" || p.length === 0)) {
+      throw new Error(`${filename}: cache.durablePrefixes must be an array of non-empty strings`)
+    }
+    // `,` separates entries and `=` separates a prefix from its tier in
+    // pg_keyspace.durability_overrides, so a prefix containing either would be
+    // read as two settings. Refused here rather than mangled into the command
+    // line, where it would surface as a Postgres that will not start.
+    const bad = (prefixes as string[]).find((p) => p.includes(",") || p.includes("="))
+    if (bad) {
+      throw new Error(
+        `${filename}: cache.durablePrefixes entry ${JSON.stringify(bad)} cannot contain "," or "=" — ` +
+          `both are separators in pg_keyspace.durability_overrides`,
+      )
+    }
+  }
+}
+
 /**
  * Rules for `database.external`, all of them errors rather than precedence.
  *
@@ -635,6 +796,22 @@ export function pgSchema(cfg: SupatypeProjectConfig): string {
  */
 export const STACK_API_SCHEMAS = ["supatype", "graphql_public", "auth"] as const
 
+/**
+ * The schema holding generated draft views, one per versioned model.
+ *
+ * Its own schema rather than a suffix on the table name, so a draft has the same table name and the
+ * same row type as what it is a draft of, and a client reaches it by switching profile.
+ */
+export const DRAFT_SCHEMA = "draft"
+
+/** What shapes the exposed-schema list, beyond the config itself. */
+export type ApiSchemaOptions = {
+  /** How field rules will be enforced here. `views` moves the managed schema off the list. */
+  tier?: "none" | "extension" | "views" | undefined
+  /** True when any model declares `versions`, which is what puts the `draft` schema on the list. */
+  drafts?: boolean | undefined
+}
+
 /**
  * Schemas to expose over REST, as `PGRST_DB_SCHEMA` wants them.
  *
@@ -644,18 +821,24 @@ export const STACK_API_SCHEMAS = ["supatype", "graphql_public", "auth"] as const
  * output mentioned the setting that caused it.
  *
  * `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.
+ * `supatype` from it is a supported way to stop exposing Studio's views. That holds for `draft` too:
+ * an explicit list has to name it, and `db check` reports a project whose models declare `versions`
+ * against a list that does not. Order is preserved and duplicates removed: PostgREST serves the first
+ * entry as the default profile, so the managed schema has to lead.
  */
-export function apiSchemas(cfg: SupatypeProjectConfig, tier?: "none" | "extension" | "views"): string[] {
+export function apiSchemas(cfg: SupatypeProjectConfig, options?: ApiSchemaOptions): string[] {
   const explicit = cfg.schema?.api_schemas
   // Tier-2 field masking serves from `api`, and the managed schema must come **off** the list: a
   // client picks its schema per request with `Accept-Profile`, so leaving it exposed would let any
   // caller read the unmasked table and make the mask opt-out. The API roles hold no privileges there
   // under tier 2 either, so exposing it would only produce denials.
-  const managed = tier === "views" ? "api" : pgSchema(cfg)
-  const list = explicit && explicit.length > 0 ? explicit : [managed, ...STACK_API_SCHEMAS]
+  const managed = options?.tier === "views" ? "api" : pgSchema(cfg)
+  // `draft` sits behind the managed schema and never in front of it: the first entry is the default
+  // profile, and a client that named no profile reading drafts by default would invert the feature.
+  const derived = options?.drafts === true
+    ? [managed, DRAFT_SCHEMA, ...STACK_API_SCHEMAS]
+    : [managed, ...STACK_API_SCHEMAS]
+  const list = explicit && explicit.length > 0 ? explicit : derived
 
   const seen = new Set<string>()
   const out: string[] = []
@@ -669,9 +852,88 @@ export function apiSchemas(cfg: SupatypeProjectConfig, tier?: "none" | "extensio
 }
 
 /** `PGRST_DB_SCHEMA` value: comma-separated, in order. */
-export function apiSchemaList(
-  cfg: SupatypeProjectConfig,
-  tier?: "none" | "extension" | "views",
-): string {
-  return apiSchemas(cfg, tier).join(", ")
+export function apiSchemaList(cfg: SupatypeProjectConfig, options?: ApiSchemaOptions): string {
+  return apiSchemas(cfg, options).join(", ")
+}
+
+/**
+ * Studio roles that see every draft, beyond each record's own creator.
+ *
+ * All three of them, which is to say anyone with Studio write access. It was narrower, `admin` and
+ * `developer` only, and that put two decisions in conflict: whoever may **update** a record may
+ * draft and publish it, so an `editor` could edit a record whose pending draft they could not see,
+ * and their save would be built on the live row and silently discard a colleague's work. Two editors
+ * on one post is the ordinary editorial case, not an exotic one. Seeing and acting line up instead.
+ *
+ * The creator is not in this list and cannot be removed from it: they wrote the draft, and a system
+ * where you cannot read back what you just saved is broken rather than secure. An empty configured
+ * list is honoured and means creators only, which is why this cannot fall back on emptiness.
+ *
+ * `anon` is not a Studio role and can never be here. A draft readable without credentials would make
+ * publishing mean nothing.
+ */
+export const DEFAULT_DRAFT_VISIBILITY = ["admin", "developer", "editor"] as const
+
+/** Studio roles a Supatype project understands, most privileged first. */
+export const STUDIO_ROLES = ["admin", "developer", "editor"] as const
+
+/**
+ * The configured draft-visibility roles, or the default when the project states none.
+ *
+ * An unknown role name is dropped rather than passed through to a policy, where it would be a role
+ * nothing can ever hold: a typo would then read as a working setting that silently grants nobody.
+ */
+export function draftVisibilityRoles(cfg: SupatypeProjectConfig): string[] {
+  const declared = cfg.publishing?.draft_visibility
+  if (declared === undefined) return [...DEFAULT_DRAFT_VISIBILITY]
+  const known = new Set<string>(STUDIO_ROLES)
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const raw of declared) {
+    const role = raw.trim().toLowerCase()
+    if (!known.has(role) || seen.has(role)) continue
+    seen.add(role)
+    out.push(role)
+  }
+  return out
+}
+
+/** Bounds on a minted preview link, in seconds. */
+export type PreviewLimits = {
+  defaultTtl: number
+  maxRecordTtl: number
+  maxProjectTtl: number
+  allowProjectScope: boolean
+}
+
+export const PREVIEW_DEFAULTS: PreviewLimits = {
+  defaultTtl: 900,
+  maxRecordTtl: 604800,
+  maxProjectTtl: 86400,
+  allowProjectScope: true,
+}
+
+/**
+ * The project's preview-link bounds, defaults filled in.
+ *
+ * A stated value is clamped to at least a second and, for the default lifetime, to no more than the
+ * ceiling it would be issued against: a `default_ttl` above `max_record_ttl` would otherwise mint
+ * links that the same config refuses to honour.
+ */
+export function previewLimits(cfg: SupatypeProjectConfig): PreviewLimits {
+  const declared = cfg.publishing?.preview
+  const positive = (value: number | undefined, fallback: number): number =>
+    typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback
+
+  const maxRecordTtl = positive(declared?.max_record_ttl, PREVIEW_DEFAULTS.maxRecordTtl)
+  const maxProjectTtl = positive(declared?.max_project_ttl, PREVIEW_DEFAULTS.maxProjectTtl)
+  return {
+    defaultTtl: Math.min(
+      positive(declared?.default_ttl, PREVIEW_DEFAULTS.defaultTtl),
+      Math.max(maxRecordTtl, maxProjectTtl),
+    ),
+    maxRecordTtl,
+    maxProjectTtl,
+    allowProjectScope: declared?.allow_project_scope ?? PREVIEW_DEFAULTS.allowProjectScope,
+  }
 }

package/src/resolve-target.ts

@@ -265,7 +265,17 @@ export async function targetSchemaPush(
   target: DeployTarget,
   ast: unknown,
   opts?: { force?: boolean; schema?: string; schemaSources?: SchemaSourcesPayload | null },
-): Promise<{ message?: string; status?: string; name?: string }> {
+): Promise<{
+  message?: string
+  status?: string
+  name?: string
+  /**
+   * What the control plane made of this schema's cache declaration. Absent from an engine push and
+   * from a control plane too old to send it, which is why every reader of it has to treat absence
+   * as "nothing to say" rather than as an empty declaration.
+   */
+  cache?: { tables?: string[]; honoured?: boolean }
+}> {
   if (target.mode === "direct" || (target.mode === "local" && !target.token)) {
     await ensureEngine()
     const body: Record<string, unknown> = {

package/src/rest-cache-admin.ts

@@ -65,8 +65,14 @@ function formatCacheApiError(
   if (status === 403 && trimmed.includes("rest_cache_not_available")) {
     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)."
+  // Both spellings: the server answers "keyspace not configured" now and
+  // "valkey not configured" before the rename, and a CLI is routinely newer
+  // than the deployment it is pointed at.
+  if (status === 503 && (trimmed.includes("keyspace") || trimmed.includes("valkey"))) {
+    return (
+      "No cache server is configured — server-side REST caching needs one. " +
+      "`supatype dev` starts it for you; on a self-hosted stack, check the `db` or `valkey` service."
+    )
   }
   return `${operation} failed (${status}): ${trimmed || "(empty body)"}`
 }

package/src/schema-ast-v2.ts

@@ -95,6 +95,8 @@ export interface DbFieldAnnotations {
 export interface PlatformFieldAnnotations {
   editor?: string
   readOnly?: boolean
+  /** Studio searches this column in the list view. Set by `Searchable<T>`. */
+  searchable?: boolean
 }
 
 export interface FieldAnnotations {
@@ -143,6 +145,18 @@ export interface KernelFieldFacts {
   index?: boolean
 }
 
+/**
+ * The `cache` declaration as it reaches the AST. See `ModelMeta.cache` in `@supatype/types` for
+ * what each setting means; this is the wire shape, kept narrow so a typo in the extractor is a
+ * type error rather than an extra key nobody reads.
+ */
+export interface ModelCacheAst {
+  enabled?: boolean
+  maxTtl?: number
+  public?: boolean
+  rows?: boolean
+}
+
 /** Internal parse result: not serialized. */
 export interface ParsedField {
   kind: FieldKind
@@ -173,6 +187,9 @@ export interface ModelAstV2 {
       access: Record<string, unknown>
       hooks?: Record<string, unknown>
       validate?: Record<string, unknown>
+      /** Columns Studio's list view searches. See {@link emitModel}. */
+      searchFields?: string[]
+      cache?: ModelCacheAst
     }
   }
 }
@@ -193,6 +210,21 @@ export interface ExtractedSchemaAstV2 {
   storageBuckets?: ExtractedStorageBucketAst[]
   locales?: string[]
   defaultLocale?: string
+  /**
+   * Draft visibility and preview-link bounds, from `supatype.config.ts`.
+   *
+   * Not extracted from the schema like everything else here: it is a project setting that the
+   * engine needs at the moment it compiles the draft policies, so it rides the same payload rather
+   * than growing a delivery path of its own. Attached by `withPublishing`, and absent for a project
+   * with no versioned model.
+   */
+  publishing?: {
+    draftVisibility: string[]
+    previewDefaultTtl: number
+    previewMaxRecordTtl: number
+    previewMaxProjectTtl: number
+    previewAllowProjectScope: boolean
+  }
 }
 
 const DEFAULT_DB_BY_KIND: Partial<Record<FieldKind, Partial<DbFieldAnnotations>>> = {
@@ -391,6 +423,8 @@ export function emitModel(
   hooks: Record<string, unknown> = {},
   constraints: unknown[] = [],
   validators: Record<string, unknown> = {},
+  searchFields: string[] = [],
+  cache?: ModelCacheAst | undefined,
 ): ModelAstV2 {
   return {
     name,
@@ -404,10 +438,23 @@ export function emitModel(
       // supatype-server reads them, Postgres never sees them.
       // Validators sit in `platform` beside `hooks`: both are enforced by the API layer on the
       // write path, and neither is something Postgres knows about.
+      // `searchFields` sits in `platform` because it is an admin-UI concern: Studio's list view
+      // renders its search box when a model has them and filters on the first. Postgres knows
+      // nothing about it, which is why it is not in `db` beside `indexes` — searching a column and
+      // indexing one are different asks, and `Indexed` already covers the latter.
       platform: {
         access,
         ...(Object.keys(hooks).length > 0 && { hooks }),
         ...(Object.keys(validators).length > 0 && { validate: validators }),
+        ...(searchFields.length > 0 && { searchFields }),
+        // Cache sits in `platform` beside `hooks` for the same reason, and travels the same way:
+        // the route manifest, not this AST. The schema engine re-serialises its own parsed struct
+        // when it writes `ast_snapshot`, and its `PlatformModelAnnotations` knows only `access`
+        // and `searchFields` — so this key, like `hooks` above it, does not survive that round
+        // trip and the manifest is what the server actually reads. Kept here because the AST is
+        // the schema's own description of itself, and a reader looking for the declaration should
+        // find it next to the other API-layer concerns.
+        ...(cache !== undefined && { cache }),
       },
     },
   }