@byline/host-tanstack-start 6.2.1 → 6.4.0

package/src/routes/create-admin-layout-route.tsx

@@ -21,7 +21,7 @@
  * route (and the `AdminAppBar`) can read it without an extra fetch.
  */
 
-import { useEffect } from 'react'
+import { useEffect, useMemo } from 'react'
 import { createFileRoute, Outlet } from '@tanstack/react-router'
 
 import { applyStoredTheme } from '@byline/admin/admin-account/components/theme'
@@ -43,7 +43,10 @@ import { SessionChangeBoundary } from '../admin-shell/chrome/session-change-boun
 import { buildLocaleDefinitions } from '../i18n/locale-definitions.js'
 import { bylineAdminServices } from '../integrations/byline-admin-services.js'
 import { BylineAiAdminProvider } from '../integrations/byline-ai.js'
-import { bylineFieldServices } from '../integrations/byline-field-services.js'
+import {
+  abilityFingerprint,
+  buildBylineFieldServices,
+} from '../integrations/byline-field-services.js'
 import { observeSession, sessionIsChanged } from '../integrations/session-coordination.js'
 import { renewExpectedSession } from '../integrations/session-renewal.js'
 import { getAnalyticsRuntime } from '../server-fns/analytics/index.js'
@@ -99,9 +102,17 @@ export function createAdminLayoutRoute(path: string) {
       useEffect(() => {
         applyStoredTheme()
       }, [])
-      // Cookie + DB write happen in setAdminLocaleFn; full reload
-      // re-runs beforeLoad so the provider re-renders with the new
-      // bundle/locale (no in-place bundle swap needed for PR 1's scope).
+      // Composed here rather than imported as a constant because the create
+      // affordance depends on the viewer's abilities, which only exist in route
+      // context. Keying on ability content avoids notifying context consumers
+      // when route context supplies an equivalent user object or abilities array.
+      // biome-ignore lint/correctness/useExhaustiveDependencies: see above
+      const fieldServices = useMemo(
+        () => buildBylineFieldServices(user),
+        [abilityFingerprint(user)]
+      )
+
+      // The full reload re-runs beforeLoad with the saved locale and its bundle.
       const handleSetLocale = async (next: LocaleCode) => {
         await setAdminLocaleFn({ data: { locale: next } })
         window.location.reload()
@@ -116,7 +127,7 @@ export function createAdminLayoutRoute(path: string) {
             setLocale={handleSetLocale}
           >
             <BylineAdminServicesProvider services={bylineAdminServices}>
-              <BylineFieldServicesProvider services={bylineFieldServices}>
+              <BylineFieldServicesProvider services={fieldServices}>
                 <BylineAiAdminProvider>
                   <AdminMenuProvider>
                     <RouteProgressBar />

package/src/server-fns/collections/create.ts

@@ -12,10 +12,12 @@ import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { CreateDocumentResult, DocumentLifecycleContext } from '@byline/core/services'
 import { createDocument } from '@byline/core/services'
+import { getDefaultStatus } from '@byline/core/workflow'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { withDocumentMutationErrors } from '../document-mutation-errors.js'
+import { validateDocumentWriteInput } from '../document-write-input.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -31,7 +33,7 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       locale?: string
       path?: string
       availableLocales?: string[]
-    }) => input
+    }) => validateDocumentWriteInput(input, 'create')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {
@@ -68,7 +70,8 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       try {
         result = await createDocument(ctx, {
           data: structuredClone(documentData),
-          status: documentData.status,
+          // The admin create flow always uses the configured initial status.
+          status: getDefaultStatus(config.definition),
           locale: locale ?? serverConfig.i18n.content.defaultLocale,
           path: explicitPath,
           availableLocales,

package/src/server-fns/collections/restore-version.ts

@@ -66,6 +66,10 @@ export const restoreDocumentVersion = createServerFn({ method: 'POST' })
           revision: result.revision,
           documentVersionId: result.documentVersionId,
           sourceVersionId: result.sourceVersionId,
+          // Restore is exempt from field validation; these describe what
+          // today's rules object to, so the editor can say what must be fixed
+          // before the next ordinary save.
+          ...(result.validationIssues ? { validationIssues: result.validationIssues } : {}),
         }
       } catch (error) {
         const committedFailure = toCommittedDocumentHookFailureResponse(error)

package/src/server-fns/collections/update.ts

@@ -17,6 +17,7 @@ import { saveDocument, updateDocumentSystemFields } from '@byline/core/services'
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { withDocumentMutationErrors } from '../document-mutation-errors.js'
+import { validateDocumentWriteInput } from '../document-write-input.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -35,7 +36,7 @@ export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POS
       path?: string | null
       availableLocales?: string[]
       locale?: string
-    }) => input
+    }) => validateDocumentWriteInput(input, 'patch')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {
@@ -115,7 +116,7 @@ export const updateCollectionDocumentSystemFields = createServerFn({ method: 'PO
       path?: string | null
       /** Editorial advertised-locale set; omitted means no advertised-locale write. */
       availableLocales?: string[]
-    }) => input
+    }) => validateDocumentWriteInput(input, 'metadata')
   )
   .handler(
     withDocumentMutationErrors(async ({ data: input }) => {

package/src/server-fns/document-mutation-errors.ts

@@ -1,6 +1,7 @@
 import {
   BylineError,
   ErrorCodes,
+  getDocumentFieldValidationDetails,
   getDocumentRevisionValidationDetails,
   getDocumentStaleDetails,
   getLockConflictDetails,
@@ -27,6 +28,13 @@ export function documentMutationError(error: unknown): unknown {
       message: 'Reload this document before making changes.',
       details: validation,
     }
+  const fields = getDocumentFieldValidationDetails(error)
+  if (fields)
+    return {
+      code: ErrorCodes.VALIDATION,
+      message: 'Some document fields are invalid.',
+      details: fields,
+    }
   const lock = getLockConflictDetails(error)
   if (lock)
     return {

package/src/server-fns/document-mutation-transport.test.node.ts

@@ -9,6 +9,7 @@ import {
   ERR_NOT_FOUND,
   ERR_TREE_HOOK_COMMITTED,
   ERR_VALIDATION,
+  getDocumentFieldValidationDetails,
   getDocumentRevisionValidationDetails,
   getDocumentStaleDetails,
   getLockConflictDetails,
@@ -209,3 +210,43 @@ it('transports unavailable-document errors without provider details', async () =
   })
   expect(wire).not.toMatch(/private|internal/)
 })
+
+describe('field validation over the installed transport', () => {
+  it('retains stable field paths and messages while dropping diagnostics', async () => {
+    const issues = [
+      { field: 'items[id=item-1].title', message: 'Title is required', kind: 'required' as const },
+    ]
+    const { value, wire } = await roundTrip({}, async () => {
+      throw ERR_VALIDATION({
+        message: 'private detail',
+        details: { reason: 'invalid_document_fields', issues, sql: 'SELECT secret' },
+        cause: new Error('private cause'),
+      })
+    })
+    expect(getDocumentFieldValidationDetails(value.error)).toEqual({
+      reason: 'invalid_document_fields',
+      issues,
+    })
+    expect(wire).not.toMatch(/private detail|SELECT secret|private cause/)
+    expect(getDocumentRevisionValidationDetails(value.error)).toBeNull()
+  })
+
+  it('never lets a malformed payload smuggle a waivable kind across the wire', async () => {
+    const { value } = await roundTrip({}, async () => {
+      throw ERR_VALIDATION({
+        message: 'private detail',
+        details: {
+          reason: 'invalid_document_fields',
+          issues: [
+            { field: 'title', message: 'Title is required' },
+            { field: 'summary', message: 'Summary is wrong', kind: 'bogus' },
+          ],
+        },
+      })
+    })
+    expect(getDocumentFieldValidationDetails(value.error)?.issues.map((i) => i.kind)).toEqual([
+      'invalid',
+      'invalid',
+    ])
+  })
+})

package/src/server-fns/document-write-input.test.node.ts

@@ -0,0 +1,48 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { validateDocumentWriteInput } from './document-write-input.js'
+
+describe('document write request shapes', () => {
+  it.each([null, {}, { collection: 'pages', data: [] }, { collection: 42, data: {} }])(
+    'rejects malformed create requests: %j',
+    (input) => {
+      expect(() => validateDocumentWriteInput(input, 'create')).toThrow(
+        'Invalid document write request'
+      )
+    }
+  )
+  it.each([
+    null,
+    [null],
+    [{ kind: 'field.set', path: 'title[' }],
+    [{ kind: 'array.move', path: 'items', itemId: 'a', toIndex: -1 }],
+    [{ kind: 'unknown', path: 'title' }],
+  ])('rejects malformed patches: %j', (patches) => {
+    expect(() =>
+      validateDocumentWriteInput({ collection: 'pages', id: 'doc', patches }, 'patch')
+    ).toThrow()
+  })
+  it('accepts nested patches and leaves revision checks to their dedicated contract', () => {
+    const input = {
+      collection: 'pages',
+      id: 'doc',
+      patches: [
+        {
+          kind: 'array.updateItem',
+          path: 'items',
+          itemId: 'a',
+          patches: [{ kind: 'field.set', path: 'title', value: 'Hello' }],
+        },
+      ],
+    }
+    expect(validateDocumentWriteInput(input, 'patch')).toBe(input)
+  })
+})

package/src/server-fns/document-write-input.ts

@@ -0,0 +1,67 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { ERR_VALIDATION, parseInstancePath } from '@byline/core'
+
+const object = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+const text = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0
+const index = (value: unknown) => Number.isSafeInteger(value) && (value as number) >= 0
+const path = (value: unknown) => text(value) && parseInstancePath(value).ok
+
+function patches(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.every((patch) => {
+      if (!object(patch) || !path(patch.path)) return false
+      if (patch.opId !== undefined && !text(patch.opId)) return false
+      if (patch.timestamp !== undefined && !text(patch.timestamp)) return false
+      switch (patch.kind) {
+        case 'field.set':
+          return 'value' in patch
+        case 'field.clear':
+          return true
+        case 'array.insert':
+          return 'item' in patch && (patch.index === undefined || index(patch.index))
+        case 'array.move':
+          return text(patch.itemId) && index(patch.toIndex)
+        case 'array.remove':
+          return text(patch.itemId)
+        case 'array.updateItem':
+          return text(patch.itemId) && patches(patch.patches)
+        case 'block.add':
+          return text(patch.blockType) && (patch.index === undefined || index(patch.index))
+        case 'block.move':
+          return text(patch.blockId) && index(patch.toIndex)
+        case 'block.remove':
+          return text(patch.blockId)
+        case 'block.updateField':
+          return text(patch.blockId) && path(patch.fieldPath) && 'value' in patch
+        default:
+          return false
+      }
+    })
+  )
+}
+
+/** Shape checks complement lifecycle authorization, revision and field validation. */
+export function validateDocumentWriteInput<T>(input: T, mode: 'create' | 'patch' | 'metadata'): T {
+  const valid =
+    object(input) &&
+    text(input.collection) &&
+    (mode === 'create' ? object(input.data) : text(input.id)) &&
+    (input.locale === undefined || text(input.locale)) &&
+    (input.path == null || typeof input.path === 'string') &&
+    (input.availableLocales === undefined ||
+      (Array.isArray(input.availableLocales) && input.availableLocales.every(text))) &&
+    (mode !== 'patch' || patches(input.patches))
+  // Revision errors keep their existing, specialized lifecycle decoder.
+  if (!valid) throw ERR_VALIDATION({ message: 'Invalid document write request.' })
+  return input
+}