@elytracms/studio 0.0.1

package/convex/guard.ts

@@ -0,0 +1,67 @@
+import { getAuthUserId } from '@convex-dev/auth/server'
+import type { QueryCtx } from './functions'
+
+/**
+ * Server-side authorization guards (EC-150). The operations chokepoint in the
+ * app enforces the role model for UX, but Convex functions are the actual
+ * trust boundary — every mutation and read re-checks here, so a hand-crafted
+ * client cannot bypass the rules.
+ *
+ * Single-tenant (EC-179): a deployment IS one project, so roles are
+ * deployment-scoped — a `members` row grants a user a role on this deployment.
+ * No `projectId` is threaded.
+ *
+ * Role ranks mirror `@elytracms/persistence`'s `roleAtLeast`:
+ * viewer (0) < editor (1) < admin (2).
+ *
+ * Failures throw plain `Error('unauthorized: …')` — Convex transports the
+ * message; the app's adapters normalize thrown backend errors onto the
+ * persistence error taxonomy, and the operations pipeline turns them into
+ * structured `OperationError`s (never crashes).
+ */
+
+export type ProjectRole = 'admin' | 'editor' | 'viewer'
+
+const ROLE_RANK: Record<ProjectRole, number> = { viewer: 0, editor: 1, admin: 2 }
+
+/**
+ * The ctx slice the guards need: identity + a readable `members` table.
+ * Both `QueryCtx` and `MutationCtx` satisfy it (a writer is a reader).
+ */
+export type GuardCtx = Pick<QueryCtx, 'auth' | 'db'>
+
+/** Resolve the authenticated user id or reject. */
+export async function requireUserId(ctx: GuardCtx): Promise<string> {
+  const userId = await getAuthUserId(ctx)
+  if (userId === null) {
+    throw new Error('unauthorized: this function requires an authenticated user')
+  }
+  return userId
+}
+
+/** Look up the caller's role on this deployment; `null` when not a member. */
+export async function memberRole(ctx: GuardCtx, userId: string): Promise<ProjectRole | null> {
+  const membership = await ctx.db
+    .query('members')
+    .withIndex('by_user', (q) => q.eq('userId', userId))
+    .first()
+  return membership?.role ?? null
+}
+
+/**
+ * Require an authenticated caller with at least `role` on this deployment.
+ * Returns the user id so handlers can attribute writes.
+ */
+export async function requireRole(ctx: GuardCtx, role: ProjectRole): Promise<string> {
+  const userId = await requireUserId(ctx)
+  const actual = await memberRole(ctx, userId)
+  if (actual === null) {
+    throw new Error('unauthorized: not a member of this deployment')
+  }
+  if (ROLE_RANK[actual] < ROLE_RANK[role]) {
+    throw new Error(
+      `unauthorized: this deployment requires the "${role}" role (caller is "${actual}")`,
+    )
+  }
+  return userId
+}

package/convex/http.ts

@@ -0,0 +1,30 @@
+import { httpRouter } from 'convex/server'
+import type { HttpRouter } from 'convex/server'
+import { registrySync } from './sync'
+
+/** The slice of the Convex Auth object the studio's HTTP routes need. */
+interface AuthHttpRoutes {
+  addHttpRoutes(http: HttpRouter): void
+}
+
+/**
+ * EC-252 — the studio's HTTP routes as a factory. `http`/`sync` are pure engine
+ * infra, so they ship in the package; only the consumer's `auth` (provider choice)
+ * is injected. The consumer's `convex/http.ts` is a two-liner:
+ *
+ * ```ts
+ * import { auth } from './auth'
+ * export default defineStudioHttp({ auth })
+ * ```
+ *
+ * Registers Convex Auth's JWT discovery endpoints (`/.well-known/*`, EC-150) plus the
+ * EC-157 Bearer-token registry-sync endpoint. Convex routes by exact path or prefix
+ * only, so the dynamic `/api/projects/:projectId/registry-sync/snapshot` segment is
+ * parsed inside the action (`sync.ts`).
+ */
+export function defineStudioHttp({ auth }: { auth: AuthHttpRoutes }): HttpRouter {
+  const http = httpRouter()
+  auth.addHttpRoutes(http)
+  http.route({ pathPrefix: '/api/projects/', method: 'GET', handler: registrySync })
+  return http
+}

package/convex/members.ts

@@ -0,0 +1,83 @@
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole, requireUserId } from './guard'
+
+/**
+ * Deployment membership persistence (EC-150, single-tenant per EC-179). The
+ * Convex side of the `MembersRepository` contract; the app's
+ * `ConvexMembersRepository` maps these onto `@elytracms/persistence` records.
+ * Member *management* is admin-only, server-side — UI gating alone is never
+ * trusted. One row per user grants their role on this deployment's one project.
+ */
+
+const roleValidator = v.union(v.literal('admin'), v.literal('editor'), v.literal('viewer'))
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer')
+    const rows = await ctx.db.query('members').collect()
+    return rows.sort((a, b) => (a.userId < b.userId ? -1 : a.userId > b.userId ? 1 : 0))
+  },
+})
+
+export const get = query({
+  args: { userId: v.string() },
+  handler: async (ctx, { userId }) => {
+    // Members may look up memberships of this deployment; everyone may look up
+    // their *own* membership (the studio needs it to render the role badge).
+    const caller = await requireUserId(ctx)
+    if (caller !== userId) await requireRole(ctx, 'viewer')
+    return ctx.db
+      .query('members')
+      .withIndex('by_user', (q) => q.eq('userId', userId))
+      .first()
+  },
+})
+
+/** The authenticated caller's membership on this deployment (studio bootstrap). */
+export const mine = query({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await requireUserId(ctx)
+    return ctx.db
+      .query('members')
+      .withIndex('by_user', (q) => q.eq('userId', userId))
+      .first()
+  },
+})
+
+export const set = mutation({
+  args: {
+    userId: v.string(),
+    role: roleValidator,
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'admin')
+    const existing = await ctx.db
+      .query('members')
+      .withIndex('by_user', (q) => q.eq('userId', args.userId))
+      .first()
+    if (existing) {
+      await ctx.db.patch(existing._id, { role: args.role, updatedAt: args.updatedAt })
+      return ctx.db.get(existing._id)
+    }
+    const id = await ctx.db.insert('members', args)
+    return ctx.db.get(id)
+  },
+})
+
+export const remove = mutation({
+  args: { userId: v.string() },
+  handler: async (ctx, { userId }) => {
+    await requireRole(ctx, 'admin')
+    const existing = await ctx.db
+      .query('members')
+      .withIndex('by_user', (q) => q.eq('userId', userId))
+      .first()
+    if (!existing) throw new Error(`not-found: member "${userId}"`)
+    await ctx.db.delete(existing._id)
+  },
+})

package/convex/publishing.ts

@@ -0,0 +1,102 @@
+import { makeFunctionReference } from 'convex/server'
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import type { MutationCtx } from './functions'
+import { requireRole } from './guard'
+
+// EC-223: the studio's convex functions are package-shipped and deployment-agnostic
+// — they address each other by STRING ref (resolved against the consumer's deployment),
+// never the per-deployment `_generated/api`. Mirrors the lib's `queryRef`/`actionRef`.
+const webhooksDeliver = makeFunctionReference<'action'>('webhooks:deliver')
+
+/**
+ * Publishing state (EC-045). Single-environment (EC-179, vision AD-8): a
+ * deployment IS one environment, so there is exactly ONE publishingState row —
+ * see `env-is-deployment-boundary`.
+ */
+
+/**
+ * EC-180 / EC-146 — fire the host revalidation webhook on a publish-state change.
+ *
+ * A mutation cannot `fetch`, so we hand off to the `webhooks.deliver` internal
+ * action (it signs + POSTs server-side; the secret never leaves Convex). A graph
+ * publish/unpublish can affect any page, so the honest v1 invalidation is the
+ * whole-project sweep tag `p:<scope>:project` — a mirror of
+ * `projectSweepWebhookTag` (`src/lib/webhooks/tags.ts`) / `@elytracms/next`'s
+ * `projectSweepTag`; the tests on those two sides pin the literal.
+ *
+ * `scope` must equal the host's `cache.scope` (its `ELYTRA_PROJECT_ID`) for the
+ * tag to match what the host stamped on its cached fetches; it comes from the
+ * `CANVAS_PROJECT_SCOPE` Convex env var. Unconfigured deployments (local dev,
+ * no env) are a silent no-op — publishing must never depend on a reachable host.
+ */
+async function scheduleRevalidate(
+  ctx: MutationCtx,
+  event: 'publishing.publish' | 'publishing.unpublish',
+): Promise<void> {
+  const env =
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const scope = env['CANVAS_PROJECT_SCOPE']
+  if (!scope) return
+  await ctx.scheduler.runAfter(0, webhooksDeliver, {
+    projectId: scope,
+    event,
+    tags: [`p:${scope}:project`],
+  })
+}
+
+export const publish = mutation({
+  args: {
+    revisionId: v.string(),
+    revision: v.number(),
+    publishedAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db.query('publishingState').first()
+    const record = {
+      status: 'published' as const,
+      publishedRevisionId: args.revisionId,
+      publishedRevision: args.revision,
+      publishedAt: args.publishedAt,
+      createdAt: existing?.createdAt ?? args.publishedAt,
+      updatedAt: args.publishedAt,
+    }
+    // EC-153 parity: republish preserves `createdAt`; return the stored record.
+    const id = existing ? existing._id : await ctx.db.insert('publishingState', record)
+    if (existing) await ctx.db.patch(existing._id, record)
+    // EC-180: drop the host's cached pages for this project (fire-and-forget).
+    await scheduleRevalidate(ctx, 'publishing.publish')
+    return ctx.db.get(id)
+  },
+})
+
+export const unpublish = mutation({
+  args: { updatedAt: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db.query('publishingState').first()
+    if (!existing || existing.status !== 'published') {
+      throw new Error('invalid-transition: nothing is currently published')
+    }
+    await ctx.db.patch(existing._id, {
+      status: 'draft',
+      publishedRevisionId: undefined,
+      publishedRevision: undefined,
+      publishedAt: undefined,
+      updatedAt: args.updatedAt,
+    })
+    // EC-180: a graph going dark must also drop the host's cached pages.
+    await scheduleRevalidate(ctx, 'publishing.unpublish')
+    // EC-153 parity: return the stored record (createdAt preserved).
+    return ctx.db.get(existing._id)
+  },
+})
+
+export const getState = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db.query('publishingState').first()
+  },
+})

package/convex/references.ts

@@ -0,0 +1,168 @@
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole } from './guard'
+import type { MutationCtx } from './functions'
+
+/**
+ * Reference-index persistence (EC-155, vision AD-6). Entries are derived data
+ * maintained replace-all-for-source by the operations layer; both lookup
+ * directions are index-backed (`by_source` outbound, `by_target` inbound).
+ */
+
+const variantValidator = v.union(v.literal('draft'), v.literal('published'))
+const sourceTypeValidator = v.union(v.literal('document'), v.literal('page'), v.literal('layout'))
+const targetTypeValidator = v.union(
+  v.literal('document'),
+  v.literal('component'),
+  v.literal('asset'),
+)
+
+/** One outbound reference, before attribution to its source. */
+const outboundReferenceValidator = v.object({
+  path: v.string(),
+  targetType: targetTypeValidator,
+  targetId: v.string(),
+  kind: v.string(),
+})
+
+/** An outbound reference attributed to its holding source. */
+const entryValidator = v.object({
+  sourceType: sourceTypeValidator,
+  sourceId: v.string(),
+  path: v.string(),
+  targetType: targetTypeValidator,
+  targetId: v.string(),
+  kind: v.string(),
+})
+
+async function deleteForSource(
+  ctx: MutationCtx,
+  variant: 'draft' | 'published',
+  sourceType: 'document' | 'page' | 'layout',
+  sourceId?: string,
+): Promise<void> {
+  const existing = await ctx.db
+    .query('referenceEntries')
+    .withIndex('by_source', (q) => {
+      const scoped = q.eq('variant', variant).eq('sourceType', sourceType)
+      return sourceId === undefined ? scoped : scoped.eq('sourceId', sourceId)
+    })
+    .collect()
+  for (const doc of existing) await ctx.db.delete(doc._id)
+}
+
+export const replaceForSource = mutation({
+  args: {
+    variant: variantValidator,
+    sourceType: sourceTypeValidator,
+    sourceId: v.string(),
+    references: v.array(outboundReferenceValidator),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    await deleteForSource(ctx, args.variant, args.sourceType, args.sourceId)
+    for (const reference of args.references) {
+      await ctx.db.insert('referenceEntries', {
+        variant: args.variant,
+        sourceType: args.sourceType,
+        sourceId: args.sourceId,
+        ...reference,
+      })
+    }
+  },
+})
+
+export const replaceForSourceTypes = mutation({
+  args: {
+    variant: variantValidator,
+    sourceTypes: v.array(sourceTypeValidator),
+    entries: v.array(entryValidator),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    for (const sourceType of args.sourceTypes) {
+      await deleteForSource(ctx, args.variant, sourceType)
+    }
+    for (const entry of args.entries) {
+      await ctx.db.insert('referenceEntries', {
+        variant: args.variant,
+        ...entry,
+      })
+    }
+  },
+})
+
+export const removeForSource = mutation({
+  args: {
+    sourceType: sourceTypeValidator,
+    sourceId: v.string(),
+    variant: v.optional(variantValidator),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const variants = args.variant ? [args.variant] : (['draft', 'published'] as const)
+    for (const variant of variants) {
+      await deleteForSource(ctx, variant, args.sourceType, args.sourceId)
+    }
+  },
+})
+
+export const clearProject = mutation({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db.query('referenceEntries').collect()
+    for (const doc of existing) await ctx.db.delete(doc._id)
+  },
+})
+
+export const outbound = query({
+  args: {
+    sourceType: sourceTypeValidator,
+    sourceId: v.string(),
+    variant: v.optional(variantValidator),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    const variants = args.variant ? [args.variant] : (['draft', 'published'] as const)
+    const out = []
+    for (const variant of variants) {
+      out.push(
+        ...(await ctx.db
+          .query('referenceEntries')
+          .withIndex('by_source', (q) =>
+            q.eq('variant', variant).eq('sourceType', args.sourceType).eq('sourceId', args.sourceId),
+          )
+          .collect()),
+      )
+    }
+    return out
+  },
+})
+
+export const inbound = query({
+  args: {
+    targetType: targetTypeValidator,
+    targetId: v.string(),
+    variant: v.optional(variantValidator),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db
+      .query('referenceEntries')
+      .withIndex('by_target', (q) => {
+        const scoped = q.eq('targetType', args.targetType).eq('targetId', args.targetId)
+        return args.variant ? scoped.eq('variant', args.variant) : scoped
+      })
+      .collect()
+  },
+})
+
+export const list = query({
+  args: { variant: v.optional(variantValidator) },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    const docs = await ctx.db.query('referenceEntries').collect()
+    return args.variant ? docs.filter((d) => d.variant === args.variant) : docs
+  },
+})

package/convex/schema.ts

@@ -0,0 +1,173 @@
+import { defineSchema, defineTable } from 'convex/server'
+import { v } from 'convex/values'
+import { authTables } from '@convex-dev/auth/server'
+
+/**
+ * Convex schema for the Elytra hosted builder (brief §10).
+ *
+ * ## Single-tenant: one deployment = one project (EC-179, vision AD-8)
+ *
+ * Project identity lives in `elytra.config.ts` (EC-178); a Convex deployment
+ * hosts exactly ONE project, so content tables carry NO `projectId` — the
+ * deployment itself IS the scope (the Payload model). Membership is likewise
+ * deployment-scoped: a `members` row grants a user a role on this deployment.
+ * Multiple projects = multiple config entries + multiple deployments.
+ *
+ * Tables mirror the persisted record shapes defined (and Zod-validated) in
+ * `@elytracms/persistence`; nested structures (graph JSON, documents) are stored
+ * as validated blobs (`v.any()`) since the Zod schemas in the packages are the
+ * canonical source of truth for their shape.
+ *
+ * ## Backend is data-only (AD-11, C0: EC-181/182/183)
+ *
+ * Project **structure is code**, not backend rows: component manifests live in
+ * the repo registry (EC-181), project identity/settings/locales/routes and CMS
+ * **collection schemas** all live in `elytra.config.ts` (EC-182/EC-183). So
+ * there is no `projects`, `componentManifests`, or `cmsSchemas` table — the
+ * remaining tables hold **data only**: CMS documents, assets, graph revisions
+ * (the page composition is a field value — data, per AD-12), publishing state,
+ * the derived reference index, deployment membership, CLI tokens, and auth.
+ *
+ * This schema is provider configuration only — the Studio and tests talk to the
+ * provider-neutral `PersistenceAdapter`, never to Convex directly (brief §4.10).
+ */
+export default defineSchema({
+  /**
+   * Convex Auth tables (EC-150): `users`, `authAccounts`, `authSessions`,
+   * `authRefreshTokens`, `authVerificationCodes`, `authVerifiers`,
+   * `authRateLimits`. Required by `convexAuth` in `auth.ts`; see
+   * https://labs.convex.dev/auth/setup/schema.
+   */
+  ...authTables,
+
+  /**
+   * Deployment membership roles (EC-150, vision AD-7). Single-tenant: one row
+   * per user grants their role on THIS deployment's one project. `userId` is the
+   * Convex Auth `users` id (stored as a string so the table shape matches the
+   * provider-neutral `@elytracms/persistence` record). Server-side enforcement
+   * happens in `guard.ts`; the operations chokepoint enforces the same rules
+   * client-side.
+   */
+  members: defineTable({
+    userId: v.string(),
+    role: v.union(v.literal('admin'), v.literal('editor'), v.literal('viewer')),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  }).index('by_user', ['userId']),
+
+  /**
+   * Revocable CLI sync tokens (EC-150, consumed by the EC-147 push CLI).
+   * Only the SHA-256 hash of a token is ever stored; revoked tokens keep
+   * their row (with `revokedAt`) for auditability.
+   *
+   * Single-tenant (EC-182/EC-183): a deployment hosts one project, so a token
+   * carries no per-project scope — `projectId` is gone (it was `optional`
+   * through EC-182; this drops the field now that both deployments are migrated).
+   */
+  cliTokens: defineTable({
+    tokenId: v.string(),
+    label: v.string(),
+    tokenHash: v.string(),
+    createdAt: v.string(),
+    revokedAt: v.optional(v.string()),
+  })
+    .index('by_token', ['tokenId'])
+    .index('by_hash', ['tokenHash']),
+
+  /** Project graph revision records — append-only (EC-041). */
+  graphRevisions: defineTable({
+    revision: v.number(),
+    serializedGraph: v.string(),
+    schemaVersion: v.number(),
+    label: v.optional(v.string()),
+    message: v.optional(v.string()),
+    createdAt: v.string(),
+  }).index('by_revision', ['revision']),
+
+  /**
+   * CMS documents (EC-043). The stored `document` is the continuous working
+   * **draft**; `publishedVersion` pins which `documentVersions` row is live
+   * (the Sanity draft/published model, EC-224). Absent = never published.
+   * Localized variants ride on the document itself.
+   */
+  cmsDocuments: defineTable({
+    collection: v.string(),
+    docId: v.string(),
+    document: v.any(),
+    publishedVersion: v.optional(v.number()),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  })
+    .index('by_collection', ['collection'])
+    .index('by_doc', ['collection', 'docId']),
+
+  /**
+   * CMS document version snapshots — append-only (EC-224), the document-scoped
+   * analogue of `graphRevisions`. One row per recorded version (created on
+   * publish or a pre-restore snapshot, never on a plain draft edit), keyed per
+   * document via `by_doc`. `cmsDocuments.publishedVersion` points at the live one.
+   */
+  documentVersions: defineTable({
+    collection: v.string(),
+    docId: v.string(),
+    version: v.number(),
+    snapshot: v.any(),
+    label: v.optional(v.string()),
+    createdAt: v.string(),
+  }).index('by_doc', ['collection', 'docId']),
+
+  /** Asset metadata; bytes live in Convex/file storage behind the blob adapter (EC-044). */
+  assets: defineTable({
+    assetId: v.string(),
+    filename: v.string(),
+    contentType: v.string(),
+    byteSize: v.number(),
+    width: v.optional(v.number()),
+    height: v.optional(v.number()),
+    alt: v.optional(v.string()),
+    /** Editable display title (EC-152; persisted for parity with in-memory — EC-153). */
+    title: v.optional(v.string()),
+    storageKey: v.string(),
+    /** Stable serve URL resolved from Convex file storage on upload (EC-151). */
+    url: v.optional(v.string()),
+    /** Normalized image focal point `{ x, y }` in 0–1 (EC-230); CSS object-position. */
+    focalPoint: v.optional(v.object({ x: v.number(), y: v.number() })),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  }).index('by_asset', ['assetId']),
+
+  /**
+   * Reference index entries (EC-155, vision AD-6) — derived data, recomputed
+   * replace-all-for-source on every write. Indexed for efficient lookup in both
+   * directions: outbound ("what does X reference") via `by_source`, inbound
+   * ("what references X") via `by_target`.
+   */
+  referenceEntries: defineTable({
+    variant: v.union(v.literal('draft'), v.literal('published')),
+    sourceType: v.union(v.literal('document'), v.literal('page'), v.literal('layout')),
+    sourceId: v.string(),
+    /** Exact field/node path inside the source, e.g. `values/author`. */
+    path: v.string(),
+    targetType: v.union(v.literal('document'), v.literal('component'), v.literal('asset')),
+    targetId: v.string(),
+    /** Which reference-bearing structure produced the entry. */
+    kind: v.string(),
+  })
+    // `by_source` also serves source-type prefix scans (the graph recompute path).
+    .index('by_source', ['variant', 'sourceType', 'sourceId'])
+    .index('by_target', ['targetType', 'targetId', 'variant']),
+
+  /**
+   * Publishing state (EC-045). Single-environment (EC-179, vision AD-8): a
+   * deployment IS one environment, so this is a single-row table — no
+   * `environment`, no index.
+   */
+  publishingState: defineTable({
+    status: v.union(v.literal('draft'), v.literal('published')),
+    publishedRevisionId: v.optional(v.string()),
+    publishedRevision: v.optional(v.number()),
+    publishedAt: v.optional(v.string()),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  }),
+})