@elytracms/studio 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finaldream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @elytracms/studio
+
+Coming soon.

package/convex/assets.ts

@@ -0,0 +1,107 @@
+import { v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole, requireUserId } from './guard'
+
+/**
+ * Asset metadata persistence (EC-044) + byte storage (EC-151). Bytes live in
+ * Convex file storage; `storageKey` on a metadata record is the Convex storage
+ * id. These functions are reachable only through the app's
+ * `ConvexBlobStorage` / `ConvexAssetRepository` adapters — never from UI code.
+ */
+
+/** Convex storage ids arrive as plain strings over the wire; rebrand for the typed API. */
+const asStorageId = (storageKey: string) => storageKey as GenericId<'_storage'>
+
+export const upsert = mutation({
+  args: {
+    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()),
+    title: v.optional(v.string()),
+    storageKey: v.string(),
+    url: v.optional(v.string()),
+    focalPoint: v.optional(v.object({ x: v.number(), y: v.number() })),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db
+      .query('assets')
+      .withIndex('by_asset', (q) => q.eq('assetId', args.assetId))
+      .first()
+    if (existing) {
+      await ctx.db.patch(existing._id, { ...args, createdAt: existing.createdAt })
+      return ctx.db.get(existing._id)
+    }
+    const id = await ctx.db.insert('assets', args)
+    return ctx.db.get(id)
+  },
+})
+
+export const get = query({
+  args: { assetId: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db
+      .query('assets')
+      .withIndex('by_asset', (q) => q.eq('assetId', args.assetId))
+      .first()
+  },
+})
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db.query('assets').withIndex('by_asset').collect()
+  },
+})
+
+export const remove = mutation({
+  args: { assetId: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db
+      .query('assets')
+      .withIndex('by_asset', (q) => q.eq('assetId', args.assetId))
+      .first()
+    if (existing) await ctx.db.delete(existing._id)
+  },
+})
+
+// --- Byte storage (EC-151) — Convex file storage behind the blob adapter ----
+
+/** Mint a short-lived URL the studio POSTs file bytes to (Convex upload flow). */
+export const generateUploadUrl = mutation({
+  args: {},
+  handler: async (ctx) => {
+    // EC-150: any authenticated user may mint an upload URL; the metadata write
+    // (`assets:upsert`) is what enforces the deployment role.
+    await requireUserId(ctx)
+    return ctx.storage.generateUploadUrl()
+  },
+})
+
+/** Resolve the serve URL for a stored blob; `null` when the blob is gone. */
+export const getServeUrl = query({
+  args: { storageKey: v.string() },
+  handler: async (ctx, { storageKey }) => {
+    await requireUserId(ctx) // EC-150: storage keys are unguessable; auth is the gate.
+    return ctx.storage.getUrl(asStorageId(storageKey))
+  },
+})
+
+/** Delete stored bytes. Metadata removal is a separate `assets:remove` call. */
+export const deleteBlob = mutation({
+  args: { storageKey: v.string() },
+  handler: async (ctx, { storageKey }) => {
+    await requireUserId(ctx) // EC-150
+    await ctx.storage.delete(asStorageId(storageKey))
+  },
+})

package/convex/auth.config.ts

@@ -0,0 +1,15 @@
+/**
+ * OIDC provider configuration for Convex Auth (EC-150): the Convex deployment itself
+ * issues the JWTs (`CONVEX_SITE_URL` is set automatically on every deployment), so no
+ * third-party identity provider is involved. Generic for every deployment — the
+ * consumer's `convex/auth.config.ts` is a one-line re-export shim (EC-252). See
+ * https://labs.convex.dev/auth/setup.
+ */
+export default {
+  providers: [
+    {
+      domain: process.env.CONVEX_SITE_URL,
+      applicationID: 'convex',
+    },
+  ],
+}

package/convex/auth.ts

@@ -0,0 +1,50 @@
+import { convexAuth } from '@convex-dev/auth/server'
+import { Password } from '@convex-dev/auth/providers/Password'
+
+/** The provider list `convexAuth` accepts, derived from its own signature. */
+type ConvexAuthProviders = Parameters<typeof convexAuth>[0]['providers']
+
+/**
+ * EC-252 — the studio's Convex Auth (EC-150) as a **default + override seam**. Only the
+ * PROVIDER choice is legitimately consumer-specific; the first-principal admin bootstrap
+ * callback is engine logic and stays here, so consumers stop copying it. The consumer's
+ * `convex/auth.ts` is a one-liner that picks up the default:
+ *
+ * ```ts
+ * export const { auth, signIn, signOut, store, isAuthenticated } = defineStudioAuth()
+ * ```
+ *
+ * or composes its own providers (OAuth, etc.) while keeping the engine bootstrap:
+ *
+ * ```ts
+ * export const { auth, ... } = defineStudioAuth({ providers: [Password, GitHub] })
+ * ```
+ *
+ * Decision record (EC-150): Convex Auth over Clerk — self-contained on the Convex stack,
+ * sessions live in our own tables, and the studio only talks to it through the
+ * project-owned `AuthAdapter`, so swapping providers later is one factory call, not UI.
+ */
+export function defineStudioAuth(options?: { providers?: ConvexAuthProviders }) {
+  return convexAuth({
+    providers: options?.providers ?? [Password],
+    callbacks: {
+      /**
+       * First-principal admin bootstrap (EC-182 follow-up). On a freshly-provisioned
+       * deployment the `members` table is empty, so no one can pass the role guard and
+       * the studio is unreachable. Rather than require a manual seed step, the **first
+       * user to authenticate while the deployment has no members** is auto-granted
+       * `admin`. Once any membership exists this is a no-op (one indexed read) — further
+       * roles are assigned by an admin via `members:set`. Single-tenant: one `members`
+       * table per deployment. `beforeSessionCreation` fires on every sign-in (not just
+       * account creation), so it also recovers a member-less account and never lets a
+       * deployment lock itself out.
+       */
+      async beforeSessionCreation(ctx, { userId }) {
+        const existing = await ctx.db.query('members').first()
+        if (existing) return
+        const now = new Date().toISOString()
+        await ctx.db.insert('members', { userId, role: 'admin', createdAt: now, updatedAt: now })
+      },
+    },
+  })
+}

package/convex/cliTokens.ts

@@ -0,0 +1,63 @@
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole } from './guard'
+
+/**
+ * CLI token persistence (EC-150). Only SHA-256 hashes are stored — hashing and
+ * plaintext generation happen in `@elytracms/operations` (`tokens.issue`), and
+ * verification goes through `verifyCliToken`, which calls `byHash` below via
+ * the `ConvexCliTokenRepository`. All user-facing access is admin-only.
+ */
+
+export const create = mutation({
+  args: {
+    tokenId: v.string(),
+    label: v.string(),
+    tokenHash: v.string(),
+    createdAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'admin')
+    const id = await ctx.db.insert('cliTokens', args)
+    return ctx.db.get(id)
+  },
+})
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'admin')
+    const rows = await ctx.db.query('cliTokens').collect()
+    return rows.sort((a, b) => (a.tokenId < b.tokenId ? -1 : a.tokenId > b.tokenId ? 1 : 0))
+  },
+})
+
+export const revoke = mutation({
+  args: { tokenId: v.string(), revokedAt: v.string() },
+  handler: async (ctx, { tokenId, revokedAt }) => {
+    await requireRole(ctx, 'admin')
+    const existing = await ctx.db
+      .query('cliTokens')
+      .withIndex('by_token', (q) => q.eq('tokenId', tokenId))
+      .first()
+    if (!existing) throw new Error(`not-found: cli-token "${tokenId}"`)
+    if (!existing.revokedAt) await ctx.db.patch(existing._id, { revokedAt })
+    return ctx.db.get(existing._id)
+  },
+})
+
+/**
+ * Hash lookup for Bearer-token verification. Deliberately *unauthenticated*:
+ * the future registry-sync HTTP endpoint (EC-156) calls it with the hash of a
+ * presented token, and knowing a hash's preimage IS the credential. No token
+ * material beyond what the caller already holds is revealed.
+ */
+export const byHash = query({
+  args: { tokenHash: v.string() },
+  handler: async (ctx, { tokenHash }) => {
+    return ctx.db
+      .query('cliTokens')
+      .withIndex('by_hash', (q) => q.eq('tokenHash', tokenHash))
+      .first()
+  },
+})

package/convex/cms.ts

@@ -0,0 +1,174 @@
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole } from './guard'
+
+/**
+ * CMS document persistence (EC-043). The backend stores **documents only**
+ * (AD-11, EC-183): CMS collection schemas are config-owned — they live in
+ * `elytra.config.ts`, read by the studio + host — so there is no `cmsSchemas`
+ * table and no schema read/write function here. Collection-membership
+ * validation lives in `@elytracms/cms-core` `validateDocument` (the studio runs it
+ * pre-dispatch); this layer is a pure document store.
+ */
+
+export const upsertDocument = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    document: v.any(),
+    createdAt: v.string(),
+    updatedAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db
+      .query('cmsDocuments')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .first()
+    if (existing) {
+      // EC-153 parity: updates preserve `createdAt`, exactly like in-memory.
+      await ctx.db.patch(existing._id, { ...args, createdAt: existing.createdAt })
+      return ctx.db.get(existing._id)
+    }
+    const id = await ctx.db.insert('cmsDocuments', args)
+    return ctx.db.get(id)
+  },
+})
+
+export const getDocument = query({
+  args: { collection: v.string(), docId: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db
+      .query('cmsDocuments')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .first()
+  },
+})
+
+export const listDocuments = query({
+  args: { collection: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    if (args.collection) {
+      const collection = args.collection
+      return ctx.db
+        .query('cmsDocuments')
+        .withIndex('by_collection', (q) => q.eq('collection', collection))
+        .collect()
+    }
+    return ctx.db.query('cmsDocuments').collect()
+  },
+})
+
+export const deleteDocument = mutation({
+  args: { collection: v.string(), docId: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db
+      .query('cmsDocuments')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .first()
+    if (existing) await ctx.db.delete(existing._id)
+    // Cascade the version history (EC-224) — no orphaned snapshots survive a delete.
+    const versions = await ctx.db
+      .query('documentVersions')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .collect()
+    for (const row of versions) await ctx.db.delete(row._id)
+  },
+})
+
+/**
+ * Document version history (EC-224) — the document analogue of `graphs:*`.
+ * Append-only snapshots in `documentVersions`; the live one is pinned by
+ * `cmsDocuments.publishedVersion`. Version numbers are 1-based, monotonic per
+ * document, computed atomically inside the mutation.
+ */
+export const saveDocumentVersion = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    snapshot: v.any(),
+    label: v.optional(v.string()),
+    createdAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const existing = await ctx.db
+      .query('documentVersions')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .collect()
+    const version = existing.reduce((max, r) => Math.max(max, r.version), 0) + 1
+    const id = await ctx.db.insert('documentVersions', { ...args, version })
+    return ctx.db.get(id)
+  },
+})
+
+export const listDocumentVersions = query({
+  args: { collection: v.string(), docId: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    const rows = await ctx.db
+      .query('documentVersions')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .collect()
+    // Newest first (parity with the in-memory `listDocumentVersions`).
+    return rows.sort((a, b) => b.version - a.version)
+  },
+})
+
+export const getDocumentVersion = query({
+  args: { collection: v.string(), docId: v.string(), version: v.number() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    const rows = await ctx.db
+      .query('documentVersions')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .collect()
+    return rows.find((r) => r.version === args.version) ?? null
+  },
+})
+
+/** Every version across all documents (EC-224) — backs the delivery feeders. */
+export const listAllDocumentVersions = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db.query('documentVersions').collect()
+  },
+})
+
+export const publishDocumentVersion = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    version: v.number(),
+    updatedAt: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const doc = await ctx.db
+      .query('cmsDocuments')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .first()
+    if (!doc) return null
+    await ctx.db.patch(doc._id, { publishedVersion: args.version, updatedAt: args.updatedAt })
+    return ctx.db.get(doc._id)
+  },
+})
+
+export const unpublishDocument = mutation({
+  args: { collection: v.string(), docId: v.string(), updatedAt: v.string() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    const doc = await ctx.db
+      .query('cmsDocuments')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+      .first()
+    if (!doc) return null
+    // Convex patch removes a field set to `undefined` — clears the live pin.
+    await ctx.db.patch(doc._id, { publishedVersion: undefined, updatedAt: args.updatedAt })
+    return ctx.db.get(doc._id)
+  },
+})