@elytracms/studio 0.0.79 → 0.0.81

package/convex/sync.ts

@@ -1,297 +0,0 @@
-import { makeFunctionReference } from 'convex/server'
-import type { GenericActionCtx, GenericDataModel } from 'convex/server'
-import { v } from 'convex/values'
-import { verifyCliToken } from '@elytracms/core/operations'
-import type { VerifiedCliToken } from '@elytracms/core/operations'
-import { roleGrantsCapability } from '@elytracms/core/persistence'
-import type {
-  CliTokenRepository,
-  OperationCapabilityId,
-  PersistenceAdapter,
-} from '@elytracms/core/persistence'
-import { httpAction, internalQuery } from './functions'
-
-/**
- * EC-157 — the builder-sync HTTP endpoint. Serves the contract fixed in
- * `@elytracms/core/export-sync`'s `registrySyncEndpoints` from this deployment's
- * `.convex.site` origin, so a host repo's `builder check` / `typegen` run against
- * the real builder instead of a `fetchImpl` double:
- *
- * - `GET  /api/projects/:projectId/registry-sync/snapshot?mode=&environment=` — the
- *   typegen/check snapshot: locale config only. Collection schemas, routes/redirects,
- *   AND the project graph are config-owned (EC-183/EC-207/EC-287, AD-11) — the CLI
- *   reads them from `elytra.config.ts`, not this snapshot.
- *
- * ## Package-shipped, deployment-agnostic (EC-223/EC-252)
- *
- * This module ships inside `@elytracms/studio`; the consumer's `convex/sync.ts` is a
- * one-line `export *` shim. It therefore NEVER imports the per-deployment
- * `./_generated/api` — it addresses sibling functions by STRING ref via
- * `makeFunctionReference` (resolved against the consumer's deployment), exactly like
- * `publishing.ts`. That decoupling is also what makes it typecheck under a cross-repo
- * `link:` loop: there is no `ApiFromModules` inference to unify across two `convex`
- * instances (the bug EC-252 fixes — a copied `sync.ts` collapsed `api.cliTokens.byHash`
- * to `{}`).
- *
- * ## Auth (EC-150 CLI tokens)
- *
- * The endpoint requires `Authorization: Bearer <ect_…>`. Tokens are verified by
- * `verifyCliToken` (`@elytracms/core/operations`): the presented plaintext is SHA-256-hashed
- * and looked up via `cliTokens.byHash`; unknown and revoked tokens are rejected with
- * a 401. Single-tenant (EC-182): a deployment hosts one project, so a token carries
- * no per-project scope — it just needs at least the `viewer` capability the snapshot
- * read requires.
- *
- * ## Error contract
- *
- * Failures are structured JSON bodies — `{ error: { code, message, issues? } }` —
- * matching `RegistrySyncErrorBody` in `@elytracms/core/export-sync`; even unexpected
- * exceptions return a structured body, never an opaque crash page. The CLI surfaces
- * them as `transport` issues.
- */
-
-type ActionCtx = GenericActionCtx<GenericDataModel>
-
-// Sibling functions are addressed by STRING ref (resolved against the consumer's
-// deployment), never `./_generated/api` — see the module note. The explicit arg +
-// return generics keep the call sites typed without `ApiFromModules` inference.
-type CliTokenRow = {
-  tokenId: string
-  label: string
-  tokenHash: string
-  createdAt: string
-  revokedAt?: string
-}
-const cliTokensByHash = makeFunctionReference<
-  'query',
-  { tokenHash: string },
-  CliTokenRow | null
->('cliTokens:byHash')
-const syncExportSnapshot = makeFunctionReference<
-  'query',
-  { projectId: string; mode: SnapshotMode; environment: string },
-  BuilderSnapshot
->('sync:exportSnapshot')
-
-// --- Structured responses ----------------------------------------------------
-
-interface SyncErrorIssue {
-  code: string
-  message: string
-  componentId?: string
-}
-
-function jsonResponse(value: unknown, status = 200): Response {
-  return new Response(JSON.stringify(value), {
-    status,
-    headers: { 'content-type': 'application/json' },
-  })
-}
-
-function errorResponse(
-  status: number,
-  code: string,
-  message: string,
-  issues?: SyncErrorIssue[],
-): Response {
-  return jsonResponse(
-    { error: { code, message, ...(issues && issues.length > 0 ? { issues } : {}) } },
-    status,
-  )
-}
-
-// --- Routing -----------------------------------------------------------------
-
-const PROJECTS_PREFIX = '/api/projects/'
-
-type SyncEndpoint = 'snapshot'
-
-interface SyncRoute {
-  projectId: string
-  endpoint: SyncEndpoint
-}
-
-/** Parse `/api/projects/:projectId/registry-sync/<rest>` (Convex routes by prefix only). */
-function parseSyncRoute(method: string, pathname: string): SyncRoute | undefined {
-  if (!pathname.startsWith(PROJECTS_PREFIX)) return undefined
-  const segments = pathname
-    .slice(PROJECTS_PREFIX.length)
-    .split('/')
-    .map((segment) => decodeURIComponent(segment))
-  const [projectId, scope, ...rest] = segments
-  if (!projectId || scope !== 'registry-sync') return undefined
-  const tail = rest.join('/')
-  if (tail === 'snapshot' && method === 'GET') return { projectId, endpoint: 'snapshot' }
-  return undefined
-}
-
-// --- Token auth (EC-150) -------------------------------------------------------
-
-/**
- * The capability each endpoint requires; the snapshot read needs `content.read`
- * (EC-240c). Capability grants come from the ONE canonical role policy
- * (`roleGrantsCapability`), so a token's role is checked the same way handlers
- * check members — no role literal at the boundary.
- */
-const REQUIRED_CAPABILITY: Record<SyncEndpoint, OperationCapabilityId> = {
-  snapshot: 'content.read',
-}
-
-/**
- * A {@link CliTokenRepository} over this deployment's `cliTokens` table, narrowed to
- * the verification path. `verifyCliToken` only ever calls `findByHash`; the write
- * methods live behind the admin-only operations layer and are not reachable here.
- */
-function cliTokenRepository(ctx: ActionCtx): CliTokenRepository {
-  const unsupported = (method: string) =>
-    Promise.reject(new Error(`cli-token ${method} is not available on the sync endpoint`))
-  return {
-    createToken: () => unsupported('createToken'),
-    listTokens: () => unsupported('listTokens'),
-    revokeToken: () => unsupported('revokeToken'),
-    async findByHash(tokenHash) {
-      const doc = await ctx.runQuery(cliTokensByHash, { tokenHash })
-      if (!doc) return undefined
-      return {
-        id: doc.tokenId,
-        label: doc.label,
-        tokenHash: doc.tokenHash,
-        createdAt: doc.createdAt,
-        ...(doc.revokedAt ? { revokedAt: doc.revokedAt } : {}),
-      }
-    },
-  }
-}
-
-type AuthResult = { ok: true; verified: VerifiedCliToken } | { ok: false; response: Response }
-
-/** Resolve and verify the Bearer CLI token, then check it grants the required capability. */
-async function authorize(
-  ctx: ActionCtx,
-  request: Request,
-  route: SyncRoute,
-): Promise<AuthResult> {
-  const header = request.headers.get('authorization')
-  if (!header || !header.toLowerCase().startsWith('bearer ')) {
-    return {
-      ok: false,
-      response: errorResponse(
-        401,
-        'unauthorized',
-        'Missing CLI token — send "Authorization: Bearer <token>" (issue one with tokens.issue).',
-      ),
-    }
-  }
-  const token = header.slice('bearer '.length).trim()
-  // verifyCliToken only reads `adapter.cliTokens`; the rest of the adapter surface
-  // is deliberately absent here (the assertion documents exactly that contract).
-  const adapter = { cliTokens: cliTokenRepository(ctx) } as PersistenceAdapter
-  const verified = await verifyCliToken(adapter, token)
-  if (verified === null) {
-    return {
-      ok: false,
-      response: errorResponse(401, 'unauthorized', 'Unknown, malformed, or revoked CLI token.'),
-    }
-  }
-  if (!roleGrantsCapability(verified.role, REQUIRED_CAPABILITY[route.endpoint])) {
-    return {
-      ok: false,
-      response: errorResponse(
-        403,
-        'forbidden',
-        `This endpoint requires the "${REQUIRED_CAPABILITY[route.endpoint]}" capability (token role "${verified.role}" does not grant it).`,
-      ),
-    }
-  }
-  return { ok: true, verified }
-}
-
-// --- The HTTP action ------------------------------------------------------------
-
-export const registrySync = httpAction(async (ctx, request) => {
-  const pathname = new URL(request.url).pathname
-  try {
-    const route = parseSyncRoute(request.method, pathname)
-    if (!route) {
-      return errorResponse(
-        404,
-        'not-found',
-        `No registry-sync endpoint matches ${request.method} ${pathname}.`,
-      )
-    }
-    const auth = await authorize(ctx, request, route)
-    if (!auth.ok) return auth.response
-    const { projectId } = route
-
-    // snapshot
-    const params = new URL(request.url).searchParams
-    const mode = params.get('mode') ?? 'published'
-    if (mode !== 'published' && mode !== 'draft') {
-      return errorResponse(
-        400,
-        'invalid-request',
-        `Invalid mode "${mode}" (expected published|draft).`,
-      )
-    }
-    const environment = params.get('environment') ?? 'production'
-    const snapshot = await ctx.runQuery(syncExportSnapshot, {
-      projectId,
-      mode,
-      environment,
-    })
-    return jsonResponse(snapshot)
-  } catch (cause) {
-    // Even unexpected failures keep the structured contract — never an opaque crash.
-    return errorResponse(
-      500,
-      'internal',
-      `Registry sync failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-    )
-  }
-})
-
-// --- Typegen/check snapshot -----------------------------------------------------
-
-type SnapshotMode = 'published' | 'draft'
-
-interface BuilderSnapshot {
-  projectId: string
-  mode: SnapshotMode
-  environment: string
-  project: null
-  localeConfig: { default: string; locales: string[] }
-  collections: never[]
-}
-
-/**
- * Everything `builder typegen`/`builder check` need from live builder state, in the
- * `BuilderSnapshot` wire shape of `@elytracms/core/export-sync`'s `createHttpBuilderSource`.
- * EC-287: the project graph is retired (structure is code), so the snapshot no
- * longer carries a graph — like the CMS schema and routes, it is config-owned and
- * read from `elytra.config.ts` in the consuming repo.
- */
-export const exportSnapshot = internalQuery({
-  args: {
-    projectId: v.string(),
-    mode: v.union(v.literal('published'), v.literal('draft')),
-    environment: v.string(),
-  },
-  handler: async (ctx, { projectId, mode, environment }): Promise<BuilderSnapshot> => {
-    // `environment` is a vestigial wire-compat field on the CLI snapshot contract
-    // (EC-179 §2): a deployment IS one environment.
-    // AD-11 (EC-182/EC-183/EC-207): project identity, locale config, CMS
-    // collection schemas, AND routes/redirects are all config-owned —
-    // `builder typegen`/`check` run in the consuming repo and read them from
-    // `elytra.config.ts`, not the wire. `project`/`localeConfig`/`collections`
-    // stay in the wire shape as config-sourced placeholders until the CLI reads
-    // config directly (C1).
-    return {
-      projectId,
-      mode,
-      environment,
-      project: null,
-      localeConfig: { default: 'en', locales: ['en'] },
-      collections: [],
-    }
-  },
-})