@supatype/cli 0.1.6 → 0.1.7

package/src/hooks-generator.ts

@@ -0,0 +1,352 @@
+/**
+ * Generate `functions/_supatype/hooks.ts` — the typed handler surface for model hooks.
+ *
+ * Generated into the project rather than shipped as a package, for two reasons: a Deno function
+ * resolves a relative `.ts` import with no npm involved, and the types then move in lockstep with the
+ * schema they came from instead of with a release.
+ *
+ * The `hook()` adapter is why the functions worker needs no change at all: it wraps a typed handler
+ * into the `(req: Request) => Response` contract the worker already discovers and serves.
+ */
+import {
+  generateInsertType,
+  generateRowType,
+  generateUpdateType,
+  resolveTableName,
+  type AstModel,
+} from "./augmentation-generator.js"
+
+interface HookedModel {
+  table: string
+  fields: Record<string, Record<string, unknown>>
+}
+
+/** Tables that declare at least one hook, sorted for a stable file. */
+function hookedModels(ast: unknown): HookedModel[] {
+  const models = (ast as { models?: AstModel[] })?.models
+  if (!Array.isArray(models)) return []
+
+  return models
+    .filter((model) => {
+      const hooks = (model as { annotations?: { platform?: { hooks?: unknown } } }).annotations
+        ?.platform?.hooks
+      return typeof hooks === "object" && hooks !== null && Object.keys(hooks).length > 0
+    })
+    .map((model) => ({ table: resolveTableName(model), fields: model.fields }))
+    .sort((a, b) => a.table.localeCompare(b.table))
+}
+
+/**
+ * The module source, or `null` when no model declares a hook.
+ *
+ * Returning null rather than an empty module keeps a `_supatype/hooks.ts` from appearing in projects
+ * that have no hooks — a generated file nobody imports is a file somebody eventually edits.
+ */
+export function generateHooksModule(ast: unknown): string | null {
+  const models = hookedModels(ast)
+  if (models.length === 0) return null
+
+  const tableEntries = models
+    .map(
+      (model) => `  ${JSON.stringify(model.table)}: {
+    Row: ${indent(denoSafe(generateRowType(model.fields)), 4)}
+    Insert: ${indent(denoSafe(generateInsertType(model.fields)), 4)}
+    Update: ${indent(denoSafe(generateUpdateType(model.fields)), 4)}
+  }`,
+    )
+    .join("\n")
+
+  return `// Generated by supatype CLI — do not edit manually.
+//
+// Typed handlers for the models that declare \`hooks\`. Import from a function beside it:
+//
+//   import { hook, type BeforeChange } from "../_supatype/hooks.ts"
+//
+//   const moderate: BeforeChange<"posts"> = async (ctx) => {
+//     if (ctx.operation === "insert") return { rows: ctx.rows }
+//     return {}
+//   }
+//
+//   export default hook(moderate)
+//
+// One function can serve a model's whole lifecycle instead, since the worker takes one default
+// export per directory:
+//
+//   export default hooks({
+//     beforeChange: moderate,
+//     afterChange: reindex,
+//   })
+
+/**
+ * Lexical editor state as JSON, or the plain string accepted for seeds and defaults.
+ *
+ * Structural rather than imported: the precise \`SerializedEditorState\` lives in
+ * \`@supatype/types/lexical\`, which a Deno function has no way to resolve.
+ */
+export type RichTextValue = { readonly root: { readonly children: readonly unknown[] } } | string
+
+export interface HookTables {
+${tableEntries}
+}
+
+/** Only the tables that declare a hook, so \`BeforeChange<"unhooked">\` is a compile error. */
+export type HookedTable = keyof HookTables & string
+
+interface HookBase {
+  readonly table: string
+  /** Claims from the JWT the server already verified. \`null\` for an anonymous caller. */
+  readonly user: { readonly sub: string; readonly role: string; readonly email?: string } | null
+  /** Correlates this hook with the request in server logs. */
+  readonly requestId: string
+}
+
+/**
+ * The rows this request is about to overwrite, fetched only if you ask.
+ *
+ * Resolved by the server from the in-flight request's own filter, as the caller's own role — so it
+ * cannot show you rows the caller could not read, and you cannot widen the filter. Capped:
+ * \`truncated\` is true when there were more, in which case acting on what you got means acting on a
+ * prefix you did not choose.
+ */
+export type PreviousRows<T extends HookedTable> = () => Promise<{
+  rows: HookTables[T]["Row"][]
+  truncated: boolean
+}>
+
+export type BeforeChangeContext<T extends HookedTable> =
+  | (HookBase & { readonly operation: "insert"; readonly rows: HookTables[T]["Insert"][] })
+  | (HookBase & {
+      readonly operation: "update"
+      readonly patch: HookTables[T]["Update"]
+      /** PostgREST filter from the request, e.g. \`status=eq.draft\`. Not rewritable. */
+      readonly filter: string
+      readonly previous: PreviousRows<T>
+    })
+
+export type BeforeDeleteContext<T extends HookedTable> = HookBase & {
+  readonly operation: "delete"
+  readonly filter: string
+  readonly previous: PreviousRows<T>
+}
+
+export type AfterChangeContext<T extends HookedTable> = HookBase & {
+  readonly operation: "insert" | "update"
+  /** Written rows — present only when the caller sent \`Prefer: return=representation\`. */
+  readonly rows?: HookTables[T]["Row"][]
+}
+
+export type AfterDeleteContext<T extends HookedTable> = HookBase & {
+  readonly operation: "delete"
+  readonly filter: string
+}
+
+/** Reject with a message, or with a status of your choosing. */
+export interface HookRejection {
+  readonly reject: string | { readonly message: string; readonly status?: number; readonly code?: string }
+}
+
+export type BeforeChangeVerdict<T extends HookedTable> =
+  | Record<string, never>
+  | { readonly rows: HookTables[T]["Insert"][] }
+  | { readonly patch: HookTables[T]["Update"] }
+  | HookRejection
+
+export type BeforeDeleteVerdict = Record<string, never> | HookRejection
+
+export type BeforeChange<T extends HookedTable> = (
+  ctx: BeforeChangeContext<T>,
+) => BeforeChangeVerdict<T> | Promise<BeforeChangeVerdict<T>>
+
+export type BeforeDelete<T extends HookedTable> = (
+  ctx: BeforeDeleteContext<T>,
+) => BeforeDeleteVerdict | Promise<BeforeDeleteVerdict>
+
+export type AfterChange<T extends HookedTable> = (
+  ctx: AfterChangeContext<T>,
+) => void | Promise<void>
+
+export type AfterDelete<T extends HookedTable> = (
+  ctx: AfterDeleteContext<T>,
+) => void | Promise<void>
+
+/** Every handler a single function may serve, when one function covers a model's whole lifecycle. */
+export interface HookHandlers<T extends HookedTable> {
+  readonly beforeChange?: BeforeChange<T>
+  readonly beforeDelete?: BeforeDelete<T>
+  readonly afterChange?: AfterChange<T>
+  readonly afterDelete?: AfterDelete<T>
+}
+
+type AnyHandler = (ctx: never) => unknown
+
+interface WireContext {
+  table?: string
+  operation?: string
+  user?: unknown
+  requestId?: string
+  rows?: unknown[]
+  patch?: unknown
+  filter?: string
+  /**
+   * Server callback **path** for pre-write rows; absent when there are none to fetch.
+   *
+   * A path rather than a URL because the server does not know its own in-network address, while this
+   * worker is already told how to reach the stack.
+   */
+  previousPath?: string
+}
+
+/**
+ * Wrap a typed handler as the request handler the worker expects.
+ *
+ * The outcome travels as the **HTTP status**: 200 for proceed, 4xx for a rejection. That keeps the
+ * contract in the transport rather than in a second envelope inside the body, so a hook written by
+ * hand — or in another language — needs to know nothing about this file.
+ */
+export function hook(handler: AnyHandler): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    if (req.method !== "POST") {
+      return json({ message: "A hook is invoked with POST" }, 405)
+    }
+
+    let wire: WireContext
+    try {
+      wire = (await req.json()) as WireContext
+    } catch {
+      // A 400 rather than a 500: the payload was wrong, the handler never ran.
+      return json({ message: "Hook payload was not JSON" }, 400)
+    }
+
+    const signature = req.headers.get("webhook-signature")
+    const ctx = {
+      table: wire.table ?? "",
+      operation: wire.operation ?? "",
+      user: wire.user ?? null,
+      requestId: wire.requestId ?? "",
+      ...(wire.rows !== undefined && { rows: wire.rows }),
+      ...(wire.patch !== undefined && { patch: wire.patch }),
+      ...(wire.filter !== undefined && { filter: wire.filter }),
+      ...(wire.previousPath !== undefined && {
+        previous: () => fetchPrevious(wire.previousPath as string, signature),
+      }),
+    }
+
+    let verdict: unknown
+    try {
+      verdict = await handler(ctx as never)
+    } catch (err) {
+      // An exception is not a rejection: the hook broke, so the server's onUnavailable policy should
+      // decide, and that is what a 500 asks for.
+      return json({ message: err instanceof Error ? err.message : "Hook threw" }, 500)
+    }
+
+    if (verdict === undefined || verdict === null) return json({}, 200)
+
+    const rejection = (verdict as HookRejection).reject
+    if (rejection !== undefined) {
+      const detail = typeof rejection === "string" ? { message: rejection } : rejection
+      const status = typeof detail.status === "number" ? detail.status : 422
+      return json(
+        { message: detail.message, ...(detail.code !== undefined && { code: detail.code }) },
+        // A rejection must be a 4xx: a hook that answered 500 would be read as unavailable and
+        // handed to onUnavailable, which is a different decision from "no".
+        status >= 400 && status < 500 ? status : 422,
+      )
+    }
+
+    return json(verdict as Record<string, unknown>, 200)
+  }
+}
+
+/**
+ * Serve several of a model's hooks from one function, dispatched on \`X-Supatype-Hook\`.
+ *
+ * The worker takes **one default export per function directory**, so \`hook(single)\` is one hook per
+ * directory. That is fine for a single moderation rule and tedious for a model whose whole lifecycle
+ * you want in one place — hence this. Point every event at the same function name in the schema:
+ *
+ *   hooks: { beforeChange: "post-hooks", afterChange: "post-hooks" }
+ *
+ * An event arriving with no handler is a 200, not an error: the schema and this file can be out of
+ * step for one deploy, and failing a write because the *other* half has not shipped yet would be the
+ * wrong way round.
+ */
+export function hooks(handlers: Record<string, AnyHandler | undefined>): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    const event = req.headers.get("x-supatype-hook") ?? ""
+    const handler = handlers[event]
+    if (handler === undefined) return json({}, 200)
+    return hook(handler)(req)
+  }
+}
+
+/**
+ * The stack's address from this worker's point of view.
+ *
+ * \`SUPATYPE_INTERNAL_URL\` in Compose is the in-network gateway; \`SUPATYPE_URL\` is the same value
+ * there. Never a public or host URL — \`localhost\` inside this container is this container.
+ */
+function stackBaseUrl(): string {
+  const base =
+    Deno.env.get("SUPATYPE_INTERNAL_URL") ??
+    Deno.env.get("SUPATYPE_URL") ??
+    ""
+  if (base === "") {
+    throw new Error(
+      "ctx.previous() needs SUPATYPE_INTERNAL_URL or SUPATYPE_URL to reach the API from this function",
+    )
+  }
+  // No regex: a backslash in a template literal is one escape away from emitting broken code, and a
+  // generator's output has to be right the first time.
+  return base.endsWith("/") ? base.slice(0, -1) : base
+}
+
+async function fetchPrevious(
+  path: string,
+  signature: string | null,
+): Promise<{ rows: unknown[]; truncated: boolean }> {
+  const url = stackBaseUrl() + path
+  const res = await fetch(url, {
+    method: "POST",
+    headers: signature !== null ? { "webhook-signature": signature } : {},
+  })
+  if (!res.ok) {
+    throw new Error(\`Could not read the rows this write affects (\${res.status})\`)
+  }
+  const body = (await res.json()) as { rows?: unknown[]; truncated?: boolean }
+  return { rows: body.rows ?? [], truncated: body.truncated === true }
+}
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  })
+}
+`
+}
+
+/**
+ * Replace cross-package type imports the client types use but a hook cannot resolve.
+ *
+ * `RichText` normally generates `import("@supatype/types/lexical").SerializedEditorState`. That works
+ * in an app, where the package is installed — but this file lives in `functions/`, is imported by a
+ * Deno handler, and has no node_modules to reach into. Left alone, any hooked model with a rich-text
+ * column emitted a module that failed to compile in the user's editor. Caught by compiling the
+ * generated file in a test rather than by a reader reporting it.
+ */
+function denoSafe(source: string): string {
+  return source.replaceAll(
+    'import("@supatype/types/lexical").SerializedEditorState',
+    "RichTextValue",
+  )
+}
+
+/** Re-indent a generated type literal so the emitted file reads as if it were written by hand. */
+function indent(source: string, spaces: number): string {
+  const pad = " ".repeat(spaces)
+  return source
+    .split("\n")
+    .map((line, i) => (i === 0 ? line : `${pad}${line}`))
+    .join("\n")
+}

package/src/link.ts

@@ -21,7 +21,10 @@ export interface ProjectLink {
   kind: ProjectLinkKind
   projectRef: string
   defaultEnvironment: string
+  /** Access token (cloud user JWT) or self-host SERVICE_ROLE_KEY. */
   token?: string
+  /** Cloud GoTrue refresh token — used to renew short-lived access JWTs. */
+  refreshToken?: string
   orgId?: string | undefined
   cloudApiUrl?: string
   linkedAt: string
@@ -209,6 +212,7 @@ export function createCloudLink(params: {
   projectRef: string
   cloudApiUrl: string
   token: string
+  refreshToken?: string
   orgId?: string | undefined
   environments?: Array<{ name: string; apiUrl: string }>
   existing?: ProjectLink | null
@@ -227,6 +231,8 @@ export function createCloudLink(params: {
     }
   }
 
+  const refreshToken = params.refreshToken ?? params.existing?.refreshToken
+
   return {
     version: LINK_VERSION,
     kind: "cloud",
@@ -239,5 +245,6 @@ export function createCloudLink(params: {
       ? { ...params.existing.environments, ...envMap }
       : envMap,
     ...(params.orgId !== undefined ? { orgId: params.orgId } : {}),
+    ...(refreshToken !== undefined ? { refreshToken } : {}),
   }
 }

package/src/local-secrets.ts

@@ -0,0 +1,104 @@
+/**
+ * The secrets the local stack runs with.
+ *
+ * **Read from `.env`, never pinned back into it.** These used to be hardcoded constants that
+ * `supatype dev` wrote to `.env` on every run — which meant a project could not hold its own
+ * secrets: whatever `supatype init` or the developer put there was replaced by the published
+ * defaults on the next `dev`, and the same `.env` then went to a server. Resolving instead of
+ * pinning is what lets a generated secret survive to production.
+ *
+ * The constants remain as *fallbacks* so a project without `.env` still starts, and so the
+ * behaviour of an existing project is unchanged.
+ */
+
+import { hasEnvValue, readEnvValue } from "./env-file.js"
+
+/**
+ * Fallback JWT signing secret for a project that has none.
+ *
+ * Published, therefore worthless as a secret — anyone can mint a token for a stack still using
+ * it. That is precisely why `init` generates one instead of relying on this.
+ */
+export const FALLBACK_JWT_SECRET = "super-secret-jwt-token-with-at-least-32-characters-long"
+
+/** Fallback Postgres superuser password for a project that has none. */
+export const FALLBACK_POSTGRES_PASSWORD = "postgres"
+
+/** Fallback password for the role PostgREST connects as. */
+export const FALLBACK_AUTHENTICATOR_PASSWORD = "authenticator-local"
+
+/** The secret the local stack signs and validates tokens with. */
+export function devJwtSecret(cwd: string): string {
+  return readEnvValue(cwd, "JWT_SECRET", FALLBACK_JWT_SECRET)
+}
+
+/** The password for the Postgres superuser the engine and server connect as. */
+export function devPostgresPassword(cwd: string): string {
+  return readEnvValue(cwd, "POSTGRES_PASSWORD", FALLBACK_POSTGRES_PASSWORD)
+}
+
+/**
+ * The password for `authenticator`, the role PostgREST connects as.
+ *
+ * Separate from {@link devPostgresPassword} for the same reason the deployed paths keep them
+ * apart: rotating the operator's database password must not take the REST API down.
+ */
+export function devAuthenticatorPassword(cwd: string): string {
+  return readEnvValue(cwd, "AUTHENTICATOR_PASSWORD", FALLBACK_AUTHENTICATOR_PASSWORD)
+}
+
+/**
+ * The secrets that are missing from `.env` and must be written so the stack can start.
+ *
+ * The compose template requires these with `${VAR:?}` rather than defaulting them, because a
+ * default is how a published constant ends up signing a real deployment's tokens. That only
+ * works if something guarantees presence — this does, for any project that predates
+ * `supatype init` writing them.
+ *
+ * **Fills with the fallback, does not generate.** Preserving the value such a project has been
+ * running with is the point: generating a new `JWT_SECRET` would invalidate tokens already
+ * issued, and a new `POSTGRES_PASSWORD` would not match the password baked into an existing
+ * Postgres volume, which `initdb` only sets once. New projects get generated values from
+ * `init`; existing ones keep working and are no worse off than before.
+ */
+export function seedMissingLocalSecrets(cwd: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!hasEnvValue(cwd, "JWT_SECRET")) out.JWT_SECRET = FALLBACK_JWT_SECRET
+  if (!hasEnvValue(cwd, "POSTGRES_PASSWORD")) out.POSTGRES_PASSWORD = FALLBACK_POSTGRES_PASSWORD
+  if (!hasEnvValue(cwd, "AUTHENTICATOR_PASSWORD")) {
+    out.AUTHENTICATOR_PASSWORD = FALLBACK_AUTHENTICATOR_PASSWORD
+  }
+  return out
+}
+
+/**
+ * The database identity the local stack connects with — seeded, never overwritten.
+ *
+ * `POSTGRES_DB` in particular is *project configuration*: `supatype init` sets it to the
+ * project name, and the running container's database was created from it. Rewriting it to a
+ * default afterwards points every tool at a database that does not exist — observed as
+ * `supatype push` failing with `FATAL: database "supatype" does not exist` on a project called
+ * something else, because the push path rewrote `.env` after `self-host compose up` had already
+ * created the database under its real name.
+ *
+ * Seeded values match the compose file's own `${VAR:-default}`, so an absent key behaves
+ * exactly as it did before.
+ */
+export function seedMissingDatabaseIdentity(cwd: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!hasEnvValue(cwd, "POSTGRES_USER")) out.POSTGRES_USER = "supatype_admin"
+  if (!hasEnvValue(cwd, "POSTGRES_DB")) out.POSTGRES_DB = "supatype"
+  return out
+}
+
+/**
+ * A short, non-reversible tag for a secret, safe to print.
+ *
+ * The ready panel used to echo the JWT secret in full, which was harmless while it was a
+ * published constant and is not once it is the project's own.
+ */
+export function secretFingerprint(secret: string): string {
+  let hash = 5381
+  for (let i = 0; i < secret.length; i++) hash = ((hash << 5) + hash + secret.charCodeAt(i)) | 0
+  return (hash >>> 0).toString(16).padStart(8, "0")
+}