@plutocms/supabase 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0](https://github.com/plutocms/supabase/compare/v0.7.2...v0.8.0) (2026-09-13)
+
+
+### Features
+
+* **content:** add Supabase-backed PlutoContentAdapter (wave 4) ([#60](https://github.com/plutocms/supabase/issues/60)) ([834136d](https://github.com/plutocms/supabase/commit/834136d39f2297ad771cf00de5bc33f0e811a4b9))
+
+## [0.7.2](https://github.com/plutocms/supabase/compare/v0.7.1...v0.7.2) (2026-09-13)
+
+
+### Bug Fixes
+
+* **permissions:** make requireAdmin safe on a zero-migration database ([#58](https://github.com/plutocms/supabase/issues/58)) ([a83f6d0](https://github.com/plutocms/supabase/commit/a83f6d0bfa3ae150df5b90a06fcd29fe437ad9b7))
+
 ## [0.7.1](https://github.com/plutocms/supabase/compare/v0.7.0...v0.7.1) (2026-09-13)
 
 

package/FEATURES.md

@@ -10,3 +10,6 @@ policies shared by every project here.
   after initial setup. @.claude/skills/layer-migrations/SKILL.md
 - Permissions storage: role-based capabilities backing server route guards and RLS policies.
   @.claude/skills/permissions-storage/SKILL.md
+- Content adapter: a Supabase/PostgREST-backed `PlutoContentAdapter`, plugging any layer's
+  declared content type into `@plutocms/pluto`'s generic content routes.
+  @.claude/skills/content-adapter/SKILL.md

package/app/pages/admin/migrations.vue

@@ -30,6 +30,13 @@ const connectionForm = ref({
 })
 
 const isRunning = ref(false)
+// True only while waitForServerAndRefresh is polling through a dev-server
+// restart. useMigrations().status reads as null on every failed poll in
+// that window (see its own doc comment), which would otherwise leave the
+// page blank below the title — the toasts alone are easy to miss. The
+// template shows a persistent banner instead, keyed on this flag, so the
+// page always explains what is happening instead of going quiet.
+const isReconnecting = ref(false)
 const lastRun = ref<Awaited<ReturnType<typeof runMigrations>> | null>(null)
 // Kept only in this page's own memory, only to show the manual .env step if
 // persisting fails — see EnvPersistWarning.vue. Never sent anywhere new.
@@ -118,8 +125,12 @@ async function applyMigrations(useForm: boolean) {
         color: 'info',
       })
 
+      isReconnecting.value = true
+
       const recovered = await waitForServerAndRefresh()
 
+      isReconnecting.value = false
+
       toast.add(
         recovered
           ? {
@@ -163,7 +174,19 @@ async function applyMigrations(useForm: boolean) {
   <AdminView>
     <h1 class="text-3xl font-bold lg:text-4xl">Migrations</h1>
 
-    <div v-if="fetchStatus === 'pending'" class="flex items-center gap-x-2">
+    <UAlert
+      v-if="isReconnecting"
+      color="info"
+      variant="outline"
+      icon="lucide:refresh-cw"
+      title="Dev server restarting"
+      description="Saving a new connection string restarts the dev server. Reconnecting — this page will update on its own once it's back."
+    />
+
+    <div
+      v-else-if="fetchStatus === 'pending'"
+      class="flex items-center gap-x-2"
+    >
       <Icon name="svg-spinners:ring-resize" />
       <span>Loading migration status…</span>
     </div>
@@ -340,5 +363,25 @@ async function applyMigrations(useForm: boolean) {
         </div>
       </UCard>
     </template>
+
+    <UAlert
+      v-else
+      color="error"
+      variant="outline"
+      icon="lucide:circle-x"
+      title="Could not load migration status"
+      description="This isn't the dev-server-restart case above — something else went wrong reading migration status. Check the server console, then try again."
+    >
+      <template #actions>
+        <UButton
+          color="error"
+          variant="outline"
+          icon="lucide:refresh-cw"
+          @click="refresh()"
+        >
+          Retry
+        </UButton>
+      </template>
+    </UAlert>
   </AdminView>
 </template>

package/app/pages/admin.vue

@@ -8,19 +8,11 @@ const route = useRoute()
 const { isLoggedIn, logout, allowedUnauthenticatedPaths } = await useAuth()
 const toast = useToast()
 
-const { load: loadPermissions, clear: clearPermissions } = usePlutoPermissions()
-
-watch(
-  isLoggedIn,
-  (loggedIn) => {
-    if (loggedIn) {
-      loadPermissions()
-    } else {
-      clearPermissions()
-    }
-  },
-  { immediate: true }
-)
+// Loading/clearing permissions on login/logout lives in
+// app/plugins/pluto-permissions-sync.ts now, not here — that plugin runs
+// on every page, not just this one, so a signed-in admin browsing a public
+// page directly (no prior visit to /admin/** this session) still gets
+// their capabilities loaded.
 
 const visibility = useDocumentVisibility()
 

package/app/plugins/pluto-permissions-sync.ts

@@ -0,0 +1,38 @@
+/**
+ * Loads (or clears) the current user's capabilities whenever their session
+ * appears or disappears — app-wide, not page-scoped.
+ *
+ * This used to live as a `watch` inside `app/pages/admin.vue`. That only
+ * ran while `admin.vue` was the mounted page, so a signed-in admin loading
+ * a public page directly (a fresh navigation or a page reload, with no
+ * earlier visit to `/admin/**` in the same app instance) never triggered a
+ * load at all — `usePlutoPermissions().granted` stayed empty, and every
+ * `can()` check for that admin read as `false` on that page, even though
+ * the same admin's capability-gated UI worked correctly inside `/admin/**`.
+ * `NavbarAdminActions.vue`'s "Edit product" quick-link (shown while
+ * viewing a live `/product/**` page) is exactly the kind of capability-
+ * gated UI that lives outside `/admin/**` by design, so it needs this to
+ * fire on every page, not just admin ones.
+ *
+ * `useSupabaseSession()` (not `useAuth()`) on purpose: it is the same
+ * primitive `useAuth()`'s own `isLoggedIn` is built from
+ * (`computed(() => !!supabaseSession.value)`), and it is genuinely
+ * app-wide reactive state already (managed by `@nuxtjs/supabase`'s own
+ * plugin), so reading it directly here needs no extra composable surface.
+ */
+export default defineNuxtPlugin(() => {
+  const session = useSupabaseSession()
+  const { load, clear } = usePlutoPermissions()
+
+  watch(
+    session,
+    (current) => {
+      if (current) {
+        load()
+      } else {
+        clear()
+      }
+    },
+    { immediate: true }
+  )
+})

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "trustedDependencies": [
     "@parcel/watcher",
     "@plutocms/pluto",
@@ -39,7 +39,7 @@
     "@nuxt/eslint": "^1.16.0",
     "@nuxt/ui": "^4.9.0",
     "@nuxtjs/supabase": "^2.0.9",
-    "@plutocms/pluto": "^0.5.0",
+    "@plutocms/pluto": "^0.8.1",
     "@plutocms/utils": "^0.2.1",
     "postgres": "^3.4.9",
     "supabase": "^2.109.1"

package/server/plugins/content-adapter.ts

@@ -0,0 +1,7 @@
+/**
+ * Registers this layer's Supabase/PostgREST-backed `PlutoContentAdapter`
+ * with core's generic content routes, at Nitro startup.
+ */
+export default defineNitroPlugin(() => {
+  registerContentAdapter(createSupabaseContentAdapter())
+})

package/server/utils/admin-guard.ts

@@ -4,25 +4,42 @@ import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
 /**
  * Guards a server route so only an admin can call it.
  *
- * Calls `public.is_admin()` directly — deliberately NOT through
- * `requireCapability`/`public.has_capability()`. `has_capability()` is
- * defined by `004_roles_and_capabilities.sql`; a site that has upgraded
- * this package but not yet applied that migration has no such function in
- * its database, and every `requireCapability` call would throw. If
- * `requireAdmin` routed through it too, that would 403 the one route
- * (`/api/migrations/*`) an admin needs to actually apply the migration —
- * a deadlock with no escape through the UI. `public.is_admin()` has existed
- * since `002_admin_hardening.sql` and is only ever `create or replace`d,
- * never dropped, so it is always safe to call regardless of which layer
- * migrations have been applied. This is also why the migrations routes
- * call `requireAdmin` specifically, and not a named capability like
- * `system:migrate` — migrations are a bootstrapping concern and must never
- * depend on the capability system migrations themselves create.
+ * Queries `public.profiles.is_admin` directly — deliberately NOT
+ * `public.is_admin()` or `public.has_capability()`. Both of those are
+ * defined by migrations (`002_admin_hardening.sql`,
+ * `004_roles_and_capabilities.sql` respectively); a genuinely fresh site
+ * that has never applied any migration beyond the original baseline
+ * schema — an expected, normal state, not a broken one — has neither
+ * function. `/api/migrations/*` (the only routes that call `requireAdmin`
+ * today) are the one place this actually bites: they are the routes that
+ * apply a pending migration, so they must work with zero migrations
+ * applied, not just with `002`+ already in place. An earlier version of
+ * this function called `public.is_admin()` on the theory that it "always
+ * exists" — true for a site that has applied at least `002`, false for a
+ * fresh one that has not, which is exactly the case that matters here.
+ * `profiles.is_admin` (the column) is part of the original baseline
+ * schema itself, before any of this project's layered migrations existed,
+ * so querying it directly has no migration dependency at all.
+ *
+ * The trade-off: a user granted the `admin` role only through
+ * `user_roles` (see `permissions-storage/SKILL.md`'s "Granting a role by
+ * hand"), with `profiles.is_admin` left `false`, cannot pass this check —
+ * only RLS and `has_capability()`-gated routes recognize a role-only
+ * admin. That is an acceptable, narrow limitation: `user_roles` cannot
+ * exist before `004` has been applied, so a role-only admin can only
+ * exist on a site that has already applied every current migration, at
+ * which point there is nothing left for that admin to need
+ * `/admin/migrations` for. If a future migration ever needs applying by
+ * a role-only admin, grant them `profiles.is_admin = true` too.
+ *
+ * `serverSupabaseUser` (from `@nuxtjs/supabase`, backed by
+ * `client.auth.getClaims()`) returns decoded JWT claims, not a Supabase
+ * `User` row — the claims object has no `id` field, only `sub`. Querying
+ * `.eq('id', user.id)` silently matches zero rows and looks exactly like
+ * "not an admin" even for a real admin. Always read `user.sub`.
  *
  * Throws a 401 if there is no logged-in user, or a 403 if the user is not
- * an admin. Returns the user's claims on success. See capability-guard.ts
- * for the same user.sub vs user.id note — this function has the same
- * shape but never reads either field either.
+ * an admin. Returns the user's claims on success.
  */
 export async function requireAdmin(event: H3Event) {
   const user = await serverSupabaseUser(event)
@@ -32,9 +49,21 @@ export async function requireAdmin(event: H3Event) {
   }
 
   const client = await serverSupabaseClient<Database>(event)
-  const { data, error } = await client.rpc('is_admin')
+  const { data: profile, error } = await client
+    .from('profiles')
+    .select('is_admin')
+    .eq('id', user.sub)
+    .single()
+
+  if (error) {
+    // Logged, never returned: the 403 below must not tell an untrusted
+    // caller whether it hit a real error (a missing column, a connection
+    // problem) or a genuine non-admin. Server logs are where that
+    // distinction has to live instead.
+    console.error('requireAdmin: profiles lookup failed:', error.message)
+  }
 
-  if (error || data !== true) {
+  if (error || !profile?.is_admin) {
     throw createError({ statusCode: 403, statusMessage: 'Your account is not an admin.' })
   }
 

package/server/utils/content-adapter.ts

@@ -0,0 +1,336 @@
+import type { PostgrestError, SupabaseClient } from '@supabase/supabase-js'
+import type { H3Event } from 'h3'
+import { serverSupabaseClient } from '#supabase/server'
+import { requireCapability } from './capability-guard'
+
+/**
+ * A Supabase client for one request, deliberately untyped.
+ *
+ * A content type's table name (`type.source`) is a plain runtime string —
+ * it is not known until a layer declares a content type, in a different
+ * repo, at that repo's build time. `serverSupabaseClient` defaults to
+ * this app's own `Database` type (see `shared/types/supabase.ts`), whose
+ * `.from()` only accepts this repo's own table names as literals. Casting
+ * to the bare `SupabaseClient` type (whose own generic defaults to `any`)
+ * is the one, deliberate place this file loses compile-time table/column
+ * safety. See `.claude/skills/content-adapter/SKILL.md` for the full
+ * write-up.
+ */
+async function getClient(event: H3Event): Promise<SupabaseClient> {
+  return (await serverSupabaseClient(event)) as SupabaseClient
+}
+
+/**
+ * Resolves the storage column for a content type's created/updated
+ * timestamp. Returns `undefined` when timestamps are disabled entirely
+ * (`type.timestamps === false`) or when this one timestamp is disabled
+ * (`type.timestamps[key] === false`).
+ */
+export function resolveTimestampColumn(
+  type: PlutoContentType,
+  key: 'created' | 'updated'
+): string | undefined {
+  if (type.timestamps === false) {
+    return undefined
+  }
+
+  const configured = type.timestamps?.[key]
+
+  if (configured === false) {
+    return undefined
+  }
+
+  return configured ?? (key === 'created' ? 'created_at' : 'updated_at')
+}
+
+/**
+ * Resolves the storage column for a content type's status field. Returns
+ * `undefined` when status is disabled entirely (`type.status === false`
+ * or unset).
+ */
+export function resolveStatusColumn(type: PlutoContentType): string | undefined {
+  if (!type.status) {
+    return undefined
+  }
+
+  return type.status.column ?? 'status'
+}
+
+/**
+ * Maps a raw PostgREST error to an H3/Nuxt error safe to send to a
+ * client. Logs the raw error first, so the real message always reaches
+ * server logs even when the client-facing message is generic. No return
+ * type annotation: `createError`'s own return type (`NuxtError`) is left
+ * to flow through, rather than restated here.
+ */
+export function toContentError(error: PostgrestError) {
+  console.error('[content-adapter] Postgres error:', error)
+
+  // 23505: unique_violation.
+  if (error.code === '23505') {
+    return createError({
+      statusCode: 409,
+      statusMessage: 'A record with this value already exists.',
+    })
+  }
+
+  // 23503: foreign_key_violation.
+  if (error.code === '23503') {
+    return createError({
+      statusCode: 400,
+      statusMessage: 'This references a record that does not exist.',
+    })
+  }
+
+  return createError({ statusCode: 500, statusMessage: error.message })
+}
+
+/** Resolves a field's storage column by name, warning and falling back to the raw name when the field is missing. This signals a misconfigured content type. */
+function resolveFieldColumn(type: PlutoContentType, fieldName: string, context: string): string {
+  const field = type.fields.find((candidate) => candidate.name === fieldName)
+
+  if (field) {
+    return fieldColumn(field)
+  }
+
+  console.warn(
+    `[content-adapter] Content type "${type.name}" has no field named "${fieldName}" (${context}). Falling back to the raw name as the column.`
+  )
+
+  return fieldName
+}
+
+async function list(ctx: PlutoContentContext, query: PlutoContentQuery): Promise<PlutoContentListResult> {
+  const client = await getClient(ctx.event)
+  const pkColumn = ctx.type.primaryKey ?? 'id'
+
+  let builder = client.from(ctx.type.source).select('*', { count: 'exact' })
+
+  const statusColumn = resolveStatusColumn(ctx.type)
+  if (statusColumn && query.includeUnpublished !== true) {
+    const publishedValue = (ctx.type.status && ctx.type.status.publishedValue) || 'published'
+    builder = builder.eq(statusColumn, publishedValue)
+  }
+
+  if (query.search) {
+    const titleColumn = resolveFieldColumn(ctx.type, ctx.type.titleField, 'titleField')
+    builder = builder.ilike(titleColumn, `%${query.search}%`)
+  }
+
+  const sort = query.sort ?? ctx.type.defaultSort
+  if (sort) {
+    const sortColumn = resolveFieldColumn(ctx.type, sort.field, 'sort')
+    builder = builder.order(sortColumn, { ascending: sort.direction !== 'desc' })
+  } else {
+    const createdColumn = resolveTimestampColumn(ctx.type, 'created')
+    builder = builder.order(createdColumn ?? pkColumn, { ascending: false })
+  }
+
+  if (query.offset !== undefined) {
+    const limit = query.limit ?? 50
+    builder = builder.range(query.offset, query.offset + limit - 1)
+  } else if (query.limit !== undefined) {
+    builder = builder.limit(query.limit)
+  }
+
+  const { data, error, count } = await builder
+
+  if (error) {
+    throw toContentError(error)
+  }
+
+  return {
+    data: (data ?? []).map((row: Record<string, unknown>) => mapColumnsToFields(ctx.type, row)),
+    total: count ?? undefined,
+  }
+}
+
+/**
+ * 22P02 (invalid_text_representation): the value doesn't parse as the
+ * primary key column's own SQL type — for example a slug like
+ * "hello-world" against a `bigint` id column. This is not a real error:
+ * it means "not found by id, at the database level", the same outcome as
+ * a clean empty result, and `get()` must fall through to trying the slug
+ * column exactly as it would for an empty result. Postgres reports a type
+ * mismatch as an error rather than zero rows, so this has to be handled
+ * separately from the empty-result case, not folded into it.
+ */
+function isInvalidIdShape(error: PostgrestError): boolean {
+  return error.code === '22P02'
+}
+
+async function get(ctx: PlutoContentContext, idOrSlug: string | number): Promise<PlutoContentItem | null> {
+  const client = await getClient(ctx.event)
+  const pkColumn = ctx.type.primaryKey ?? 'id'
+
+  const { data, error } = await client
+    .from(ctx.type.source)
+    .select('*')
+    .eq(pkColumn, idOrSlug)
+    .maybeSingle()
+
+  if (error && !isInvalidIdShape(error)) {
+    throw toContentError(error)
+  }
+
+  if (data) {
+    return mapColumnsToFields(ctx.type, data)
+  }
+
+  if (ctx.type.slug) {
+    const slugColumn = resolveFieldColumn(ctx.type, ctx.type.slug.field, 'slug.field')
+
+    const bySlug = await client
+      .from(ctx.type.source)
+      .select('*')
+      .eq(slugColumn, idOrSlug)
+      .maybeSingle()
+
+    if (bySlug.error) {
+      throw toContentError(bySlug.error)
+    }
+
+    if (bySlug.data) {
+      return mapColumnsToFields(ctx.type, bySlug.data)
+    }
+  }
+
+  return null
+}
+
+async function create(ctx: PlutoContentContext, values: Record<string, unknown>): Promise<PlutoContentItem> {
+  const client = await getClient(ctx.event)
+  const row = mapFieldsToColumns(ctx.type, values)
+
+  // Status is not a declared field (see PlutoContentType.status — a
+  // separate, top-level concern from `fields`, unlike `slug`, which
+  // references a field also present in `fields`), so mapFieldsToColumns
+  // never sees it — it filters strictly to declared field names. A
+  // payload's status lives at the fixed conceptual key `status`,
+  // regardless of what `type.status.column` names in storage, mirroring
+  // how a field's own name (not its storage column) is the payload key
+  // everywhere else in this contract.
+  const statusColumn = resolveStatusColumn(ctx.type)
+  if (statusColumn) {
+    if (Object.hasOwn(values, 'status')) {
+      row[statusColumn] = values.status
+    } else if (ctx.type.status && ctx.type.status.default !== undefined) {
+      row[statusColumn] = ctx.type.status.default
+    }
+  }
+
+  // A client never controls its own creation timestamp. Always stamp it,
+  // overwriting anything the caller's payload tried to set.
+  const createdColumn = resolveTimestampColumn(ctx.type, 'created')
+  if (createdColumn) {
+    row[createdColumn] = new Date().toISOString()
+  }
+
+  const { data, error } = await client
+    .from(ctx.type.source)
+    .insert(row)
+    .select('*')
+    .single()
+
+  if (error) {
+    throw toContentError(error)
+  }
+
+  return mapColumnsToFields(ctx.type, data)
+}
+
+async function update(
+  ctx: PlutoContentContext,
+  id: string | number,
+  values: Record<string, unknown>
+): Promise<PlutoContentItem> {
+  const client = await getClient(ctx.event)
+  const pkColumn = ctx.type.primaryKey ?? 'id'
+  const row = mapFieldsToColumns(ctx.type, values)
+
+  // See the matching comment in create(): status is not a declared field,
+  // so mapFieldsToColumns never sees it. Read it from the fixed
+  // conceptual key `status` in the raw payload.
+  const statusColumn = resolveStatusColumn(ctx.type)
+  if (statusColumn && Object.hasOwn(values, 'status')) {
+    row[statusColumn] = values.status
+  }
+
+  // A client never controls its own update timestamp. Always stamp it,
+  // overwriting anything the caller's payload tried to set.
+  const updatedColumn = resolveTimestampColumn(ctx.type, 'updated')
+  if (updatedColumn) {
+    row[updatedColumn] = new Date().toISOString()
+  }
+
+  // Published-at preservation, generalizing supabase-blog's hand-written
+  // edit route: stamp published-at the first time a row is published, but
+  // never overwrite an already-set value on a later edit.
+  if (
+    statusColumn
+    && ctx.type.status
+    && ctx.type.status.publishedAtColumn
+    && row[statusColumn] === ctx.type.status.publishedValue
+  ) {
+    const publishedAtColumn = ctx.type.status.publishedAtColumn
+    // Selects the whole row rather than the one dynamic column name:
+    // postgrest-js parses a `select()` argument at the type level, and a
+    // non-literal (runtime) column name resolves to its own
+    // `GenericStringError` type instead of a usable row shape.
+    const { data: existing, error: fetchError } = await client
+      .from(ctx.type.source)
+      .select('*')
+      .eq(pkColumn, id)
+      .maybeSingle()
+
+    if (fetchError) {
+      throw toContentError(fetchError)
+    }
+
+    if (existing && (existing as Record<string, unknown>)[publishedAtColumn] == null) {
+      row[publishedAtColumn] = new Date().toISOString()
+    }
+  }
+
+  const { data, error } = await client
+    .from(ctx.type.source)
+    .update(row)
+    .eq(pkColumn, id)
+    .select('*')
+    .single()
+
+  if (error) {
+    throw toContentError(error)
+  }
+
+  return mapColumnsToFields(ctx.type, data)
+}
+
+async function remove(ctx: PlutoContentContext, id: string | number): Promise<void> {
+  const client = await getClient(ctx.event)
+  const pkColumn = ctx.type.primaryKey ?? 'id'
+
+  const { error } = await client.from(ctx.type.source).delete().eq(pkColumn, id)
+
+  if (error) {
+    throw toContentError(error)
+  }
+}
+
+/** Delegates straight to `requireCapability`, unchanged. */
+async function authorize(event: H3Event, capability: string): Promise<void> {
+  await requireCapability(event, capability)
+}
+
+/** Builds the Supabase/PostgREST-backed `PlutoContentAdapter`. Register it with `registerContentAdapter` from a `server/plugins/*.ts` file. */
+export function createSupabaseContentAdapter(): PlutoContentAdapter {
+  return {
+    id: 'supabase',
+    list,
+    get,
+    create,
+    update,
+    remove,
+    authorize,
+  }
+}