@elytracms/studio 0.0.76 → 0.0.78

package/convex/cms.ts

@@ -1,8 +1,7 @@
 import { v } from 'convex/values'
 import { documentsSemanticEqual, foldDocument, unfoldDocument } from '@elytracms/core/cms-core'
 import type { CmsDocument } from '@elytracms/core/cms-core'
-import { backfillHasUnpublishedChanges, backfillPublishedAt } from '@elytracms/core/persistence'
-import { internalMutation, mutation, query } from './functions'
+import { mutation, query } from './functions'
 import { requireCapability } from './guard'
 import { assertWithinWriteLimits } from './write-limits'
 
@@ -330,109 +329,14 @@ export const unpublishDocument = mutation({
 })
 
 /**
- * EC-447 one-time backfill — close-reconstruct `publishedAt` on documents published
- * BEFORE it was materialized. For each currently-published doc that has NONE, sets
- * `publishedAt` to its PINNED published version's `createdAt` (the best-available
- * approximation of the real publish moment, owner-blessed). The decision is the pure,
- * unit-tested `backfillPublishedAt` (`@elytracms/core/persistence`) — one source of
- * truth: an already-stamped doc, an unpublished doc, or one whose pinned version row
- * is missing is SKIPPED, so a re-run performs ZERO writes (idempotent). Touches ONLY
- * `publishedAt` (never `createdAt`/`updatedAt`/the pin), so the write-chokepoint
- * trigger fires no revalidation (`publishedVersion` is unchanged — see triggers.ts).
- *
- * INTERNAL (scheduler/CLI only, EC-150): the operator runs it once per deployment
- * after `convex deploy` (e.g. `npx convex run cms:backfillPublishedAtColumn`); it is
- * not client-callable. Returns a small audit summary (`{ scanned, stamped }`).
- */
-export const backfillPublishedAtColumn = internalMutation({
-  args: {},
-  handler: async (ctx) => {
-    const docs = await ctx.db.query('cmsDocuments').collect()
-    let scanned = 0
-    let stamped = 0
-    for (const doc of docs) {
-      scanned += 1
-      // Skip the version read for the certain-skip cases (draft / already-stamped);
-      // otherwise resolve the pinned version and let the pure helper decide.
-      if (doc.publishedVersion === undefined || doc.publishedAt !== undefined) continue
-      const pinned = await ctx.db
-        .query('documentVersions')
-        .withIndex('by_doc_version', (q) =>
-          q
-            .eq('collection', doc.collection)
-            .eq('docId', doc.docId)
-            .eq('version', doc.publishedVersion as number),
-        )
-        .unique()
-      const publishedAt = backfillPublishedAt(
-        { publishedVersion: doc.publishedVersion, publishedAt: doc.publishedAt },
-        pinned?.createdAt,
-      )
-      if (publishedAt === undefined) continue
-      await ctx.db.patch(doc._id, { publishedAt })
-      stamped += 1
-    }
-    return { scanned, stamped }
-  },
-})
-
-/**
- * EC-449 one-time backfill — materialize `hasUnpublishedChanges` on documents
- * published BEFORE the flag was recorded, so the amber "changed" dot is correct
- * immediately after the repoint instead of understating until the next save. For
- * each currently-published doc that has NO flag yet, runs the SAME semantic
- * compare the write chokepoint runs going forward (`documentsSemanticEqual`,
- * schema-less lens) of the stored draft against its pinned published snapshot —
- * the full compare was chosen over the ratified default-`false` fallback because
- * it costs one indexed version read + one compare per unstamped published doc
- * (the same order of work as `cms:backfillPublishedAtColumn`). The decision is
- * the pure, unit-tested `backfillHasUnpublishedChanges`
- * (`@elytracms/core/persistence`): an already-flagged doc, an unpublished doc,
- * or one whose pinned version row is missing is SKIPPED, so a re-run performs
- * ZERO writes (idempotent). Touches ONLY `hasUnpublishedChanges` (never the
- * pin/`document`/timestamps), so the write-chokepoint trigger fires no host
- * revalidation (`publishedVersion` unchanged — see triggers.ts).
- *
- * INTERNAL (scheduler/CLI only, EC-150): the operator runs it once per deployment
- * after `convex deploy` (e.g. `npx convex run cms:backfillHasUnpublishedChangesColumn`);
- * it is not client-callable. Returns a small audit summary (`{ scanned, stamped }`).
+ * One-time data migrations (EC-450 principle): a migration mutation ships
+ * transiently — added when a schema/behavior change needs to backfill existing
+ * deployments, then REMOVED once every deployment has confirmed running it. It
+ * never lingers in the permanent `@elytracms/*` shipped surface (a brand-new
+ * consumer never needs it — nothing pre-dates the change it backfills). Pattern:
+ * an `internalMutation` here delegating its per-row decision to a pure, unit-tested
+ * core in `@elytracms/core/persistence`; the operator runs it once per deployment
+ * via `npx convex run cms:<name>` after `convex deploy`, confirms all deployments,
+ * then deletes both the mutation and its core in one removal pass (see EC-447/449
+ * → EC-450 for the worked example).
  */
-export const backfillHasUnpublishedChangesColumn = internalMutation({
-  args: {},
-  handler: async (ctx) => {
-    const docs = await ctx.db.query('cmsDocuments').collect()
-    let scanned = 0
-    let stamped = 0
-    for (const doc of docs) {
-      scanned += 1
-      // Skip the version read for the certain-skip cases (draft / already-flagged);
-      // otherwise resolve the pinned snapshot, compare once, and let the pure
-      // helper decide.
-      if (doc.publishedVersion === undefined || doc.hasUnpublishedChanges !== undefined) continue
-      const pinned = await ctx.db
-        .query('documentVersions')
-        .withIndex('by_doc_version', (q) =>
-          q
-            .eq('collection', doc.collection)
-            .eq('docId', doc.docId)
-            .eq('version', doc.publishedVersion as number),
-        )
-        .unique()
-      const differs = pinned
-        ? !documentsSemanticEqual(
-            undefined,
-            unfoldDocument(pinned.snapshot as CmsDocument),
-            unfoldDocument(doc.document as CmsDocument),
-          )
-        : undefined
-      const hasUnpublishedChanges = backfillHasUnpublishedChanges(
-        { publishedVersion: doc.publishedVersion, hasUnpublishedChanges: doc.hasUnpublishedChanges },
-        differs,
-      )
-      if (hasUnpublishedChanges === undefined) continue
-      await ctx.db.patch(doc._id, { hasUnpublishedChanges })
-      stamped += 1
-    }
-    return { scanned, stamped }
-  },
-})

package/convex/contract-parity.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import { measureMaxDepth } from '@elytracms/core/cms-core'
+import { PERSISTENCE_CONTRACT_SCENARIOS } from '@elytracms/core/persistence'
+import type { ContractContext } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+
+/**
+ * EC-454 — Convex-side contract parity, restored.
+ *
+ * `PERSISTENCE_CONTRACT_SCENARIOS` (EC-049 → EC-153) runs here against the REAL
+ * Convex function handlers (`convex/*.ts`) + the real `schema.ts` + the EC-286
+ * write-chokepoint triggers, executed by `convex-test`'s in-memory backend — no
+ * deployment, CI-shaped. The scenarios drive the production
+ * `ConvexPersistenceAdapter` itself: its `ConvexHttpClient` is replaced by a
+ * call-through double onto `t.query`/`t.mutation` (the only production layer
+ * bypassed is HTTP transport), so the adapter's client-side normalization
+ * (ordering, not-found preflights, EC-447 publishedAt stamping, error mapping)
+ * is under test exactly as production composes it.
+ *
+ * Runs in the `convex-parity` vitest project (edge-runtime environment — the
+ * scoped exception to the house node-env pattern; convex-test targets the
+ * Convex isolate's API surface, which edge-runtime replicates).
+ */
+
+// convex-test locates the module root by finding a `_generated` path among the
+// glob keys, but this package deliberately ships NO `_generated` directory
+// (`functions.ts` binds the schema explicitly — EC-223). The stub key below
+// satisfies the root lookup (it is only split on to compute the path prefix and
+// is never imported); real local `_generated` output (gitignored codegen) is
+// excluded so the module map is identical on every machine.
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+/** The config-owned slug this deployment's records are stamped with (EC-179). */
+const PROJECT_ID = 'contract-parity'
+/** Never written to: single-tenant excludes the cross-project scenarios below. */
+const EMPTY_PROJECT_ID = 'contract-parity-empty'
+const SESSION_USER_ID = 'user_admin'
+
+/** The two calls the persistence adapter issues on a `ConvexHttpClient`. */
+interface AdapterBackend {
+  query: (ref: FunctionReference<'query'>, args: Record<string, unknown>) => Promise<unknown>
+  mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
+}
+
+/**
+ * Adapt a convex-test accessor onto the `ConvexHttpClient` call surface the
+ * adapter uses (`client.query(ref, args)` / `client.mutation(ref, args)` with
+ * `makeFunctionReference` refs — which convex-test resolves natively).
+ */
+function asAdapterClient(backend: AdapterBackend): ConvexHttpClient {
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) =>
+      backend.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) =>
+      backend.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+/** A fresh backend with the session admin's membership bootstrapped. */
+async function freshBackend() {
+  const t = convexTest(schema, modules)
+  // Bootstrap the first admin membership via raw db access: in production the
+  // auth boundary (`auth.ts`) creates it on first sign-in; `members:set` itself
+  // is admin-gated, so the harness cannot call it before a member exists.
+  const now = new Date().toISOString()
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', {
+      userId: SESSION_USER_ID,
+      role: 'admin',
+      createdAt: now,
+      updatedAt: now,
+    })
+  })
+  return t
+}
+
+/**
+ * A fresh {@link ContractContext} per scenario. Identity: `guard.ts` resolves
+ * the caller via Convex Auth's `getAuthUserId` = `subject.split('|')[0]`, so a
+ * plain `subject` on convex-test's identity IS the member `userId` — the guards
+ * run unmodified.
+ */
+async function convexHarness(): Promise<ContractContext> {
+  const t = await freshBackend()
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID, [])
+  return {
+    adapter,
+    projectId: PROJECT_ID,
+    emptyProjectId: EMPTY_PROJECT_ID,
+    sessionUserId: SESSION_USER_ID,
+    // EC-183 (AD-11): the Convex adapter's CMS schema is config-owned (injected
+    // at construction, no `cmsSchemas` table) — seeding it is a no-op here.
+    async seedSchema() {},
+  }
+}
+
+const singleTenantScenarios = PERSISTENCE_CONTRACT_SCENARIOS.filter((s) => !s.crossProject)
+const crossProjectScenarios = PERSISTENCE_CONTRACT_SCENARIOS.filter((s) => s.crossProject)
+
+describe('adapter contract — Convex (EC-153 cross-adapter parity suite, EC-454)', () => {
+  for (const scenario of singleTenantScenarios) {
+    it(`${scenario.domain}: ${scenario.name}`, async () => {
+      await scenario.run(await convexHarness())
+    })
+  }
+  // `crossProject` scenarios assert isolation between TWO projects in one store.
+  // A Convex deployment IS one project (EC-179), so the scenario contract itself
+  // excludes them for single-tenant backends (see `ContractScenario.crossProject`).
+  // Kept visible as skips so the exclusion can never silently widen.
+  for (const scenario of crossProjectScenarios) {
+    it.skip(`single-tenant exclusion (EC-179): ${scenario.domain}: ${scenario.name}`, () => {})
+  }
+})
+
+describe('EC-286 write-chokepoint triggers (Convex-only: in-transaction reference maintenance)', () => {
+  // Not a shared scenario: the in-memory adapter does not self-maintain the
+  // reference index (`maintainsReferenceIndex` is Convex-only — the studio
+  // attaches a client-side subscriber for other providers). Here the trigger
+  // must derive index rows from document writes by construction.
+  it('derives, republishes, retargets, and drops reference-index rows from document writes', async () => {
+    const { adapter, projectId } = await convexHarness()
+    const doc = {
+      collection: 'post',
+      id: 'trigger-probe',
+      values: {
+        author: { type: 'reference', collection: 'author', id: 'ada' },
+        cover: { type: 'asset', id: 'asset_cover' },
+      },
+    }
+    const ref = { collection: doc.collection, id: doc.id }
+    const source = { type: 'document' as const, id: 'post:trigger-probe' }
+
+    // A draft write derives draft rows in the same transaction — no published
+    // rows until a live version is pinned.
+    await adapter.cms.upsertDocument(projectId, doc)
+    const draft = await adapter.references.outbound(projectId, source, { variant: 'draft' })
+    expect(draft.map((r) => `${r.target.type}:${r.target.id}:${r.kind}`).sort()).toEqual([
+      'asset:asset_cover:asset-field',
+      'document:author:ada:relation-field',
+    ])
+    expect(await adapter.references.outbound(projectId, source, { variant: 'published' })).toEqual(
+      [],
+    )
+
+    // Pinning a version re-runs maintenance: published rows mirror the draft rows.
+    const v = await adapter.cms.saveDocumentVersion(projectId, doc, { label: 'published' })
+    await adapter.cms.publishDocumentVersion(projectId, ref, v.version)
+    expect(
+      (await adapter.references.outbound(projectId, source, { variant: 'published' })).length,
+    ).toBe(2)
+
+    // A retargeting save REPLACES the rows (replace-all-for-source, never appends).
+    await adapter.cms.upsertDocument(projectId, {
+      ...doc,
+      values: { author: { type: 'reference', collection: 'author', id: 'grace' } },
+    })
+    const retargeted = await adapter.references.outbound(projectId, source, { variant: 'draft' })
+    expect(retargeted.map((r) => r.target.id)).toEqual(['author:grace'])
+
+    // Deleting the document drops every row in both variants.
+    await adapter.cms.deleteDocument(projectId, ref)
+    expect(await adapter.references.outbound(projectId, source)).toEqual([])
+  })
+})
+
+describe('EC-260 fold-at-rest (Convex-only: the stored form respects the depth cap)', () => {
+  // The shared round-trip scenario proves handlers unfold on every read path;
+  // convex-test does NOT replicate Convex's 16-level at-rest nesting cap, so
+  // this reads the RAW stored row and proves the write path actually FOLDED it
+  // under the cap (the storage-boundary guarantee the codec exists for).
+  it('stores an over-budget document folded to within 16 levels; the wire stays structured', async () => {
+    const t = await freshBackend()
+    const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+    const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID, [])
+
+    let deep: unknown = { type: 'leaf', text: 'bottom' }
+    for (let i = 0; i < 24; i++) deep = { type: 'level', index: i, child: deep }
+    const doc = { collection: 'post', id: 'ec260-at-rest', values: { title: 'Deep', body: deep } }
+    expect(measureMaxDepth(doc).depth).toBeGreaterThan(16) // the premise: over-budget on the wire
+
+    const stored = await adapter.cms.upsertDocument(PROJECT_ID, doc)
+    expect(stored.document.values).toEqual(doc.values) // the wire never carries an envelope
+
+    const atRest = await t.run(async (ctx) => {
+      const row = await ctx.db
+        .query('cmsDocuments')
+        .withIndex('by_doc', (q) => q.eq('collection', doc.collection).eq('docId', doc.id))
+        .unique()
+      return row?.document as unknown
+    })
+    expect(atRest).toBeDefined()
+    expect(measureMaxDepth(atRest).depth).toBeLessThanOrEqual(16) // folded at rest
+  })
+})
+
+describe('guard capability gates through the real functions (EC-150/EC-240c, Convex-only)', () => {
+  it('admits reads for a viewer but rejects writes, administration, non-members, and anonymous calls', async () => {
+    const t = await freshBackend()
+    const now = new Date().toISOString()
+    await t.run(async (ctx) => {
+      await ctx.db.insert('members', {
+        userId: 'user_viewer',
+        role: 'viewer',
+        createdAt: now,
+        updatedAt: now,
+      })
+    })
+    const forSubject = (subject: string) =>
+      new ConvexPersistenceAdapter(
+        asAdapterClient(t.withIdentity({ subject, issuer: 'https://convex.test' })),
+        PROJECT_ID,
+        [],
+      )
+
+    const viewer = forSubject('user_viewer')
+    expect(await viewer.cms.listDocuments(PROJECT_ID)).toEqual([]) // content.read granted
+    await expect(
+      viewer.cms.upsertDocument(PROJECT_ID, { collection: 'post', id: 'x', values: {} }),
+    ).rejects.toThrow(/unauthorized/) // content.write denied
+    await expect(viewer.cliTokens.listTokens()).rejects.toThrow(/unauthorized/) // project.administer denied
+
+    // An authenticated NON-member is rejected even on reads …
+    await expect(forSubject('user_stranger').cms.listDocuments(PROJECT_ID)).rejects.toThrow(
+      /unauthorized/,
+    )
+    // … and so is an anonymous caller.
+    const anonymous = new ConvexPersistenceAdapter(asAdapterClient(t), PROJECT_ID, [])
+    await expect(anonymous.cms.listDocuments(PROJECT_ID)).rejects.toThrow(/unauthorized/)
+  })
+})

package/convex/schema.ts

@@ -144,8 +144,9 @@ export default defineSchema({
      * publish-action ISO timestamp captured AT publish (NOT a revision `createdAt`),
      * written set-once on publish and cleared on unpublish. A distinct materialized
      * value alongside `createdAt`/`updatedAt`, backing the `$publishedAt` list column.
-     * Optional (additive): existing rows stay valid; a one-time backfill
-     * (`cms:backfillPublishedAt`) close-reconstructs it for pre-EC-447 published docs.
+     * Optional (additive): existing rows stay valid. Pre-EC-447 published docs on the
+     * three original deployments were close-reconstructed by a one-time backfill,
+     * since removed (EC-450 — ship-then-remove; a fresh deployment never needs it).
      */
     publishedAt: v.optional(v.string()),
     /**
@@ -155,9 +156,9 @@ export default defineSchema({
      * against the pinned published snapshot; publish writes `false`; unpublish
      * clears it. NOT derived from `updatedAt > publishedAt` (set-once EC-447
      * semantics would false-positive on every republish). Optional (additive):
-     * existing rows stay valid; a one-time backfill
-     * (`cms:backfillHasUnpublishedChangesColumn`) materializes it for
-     * pre-EC-449 published docs.
+     * existing rows stay valid. Pre-EC-449 published docs on the three original
+     * deployments were materialized by a one-time backfill, since removed
+     * (EC-450 — ship-then-remove; a fresh deployment never needs it).
      */
     hasUnpublishedChanges: v.optional(v.boolean()),
     createdAt: v.string(),

package/convex/tsconfig.json

@@ -6,7 +6,9 @@
     "moduleResolution": "Bundler",
     "jsx": "react-jsx",
     "skipLibCheck": true,
-    "types": ["node"]
+    // `vite/client` types `import.meta.glob` (the convex-test module map in
+    // `contract-parity.test.ts`, EC-454).
+    "types": ["node", "vite/client"]
   },
   "include": ["./**/*.ts"]
 }

package/dist/components/cms/collection-table.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Link, STUDIO_PROJECT_ROUTE, studioPath, useNavigate } from '@elytracms/studio/router';
+import { Link, STUDIO_PROJECT_ROUTE, useNavigate } from '@elytracms/studio/router';
 import { ArrowDown, ArrowUp, CircleDot, Copy, CornerDownRight, Download, Eye, EyeOff, ExternalLink, MoreHorizontal, Pencil, Plus, Trash2, Upload, } from 'lucide-react';
 import { useMemo, useState } from 'react';
 import { orderHierarchically, resolveDocumentForLocale, resolveDocumentTitle, validateCollectionShape, } from '@elytracms/core/cms-core';