@byline/host-tanstack-start 3.21.0 → 4.0.0

package/src/server-fns/collections/tree-mutation.ts

@@ -0,0 +1,165 @@
+import type { CollectionHandle, PlaceTreeNodeOptions, RemoveFromTreeOptions } from '@byline/client'
+import { ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER } from '@byline/core'
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === 'object' &&
+    error != null &&
+    'code' in error &&
+    (error as { code?: unknown }).code === code
+  )
+}
+
+function hasMessageMarker(error: unknown, marker: string): boolean {
+  return error instanceof Error && error.message.startsWith(marker)
+}
+
+/** Prefer the code; the marker survives transports that reconstruct a code-less Error. */
+export function isTreeMutationConflict(error: unknown): boolean {
+  if (hasErrorCode(error, ErrorCodes.CONFLICT)) return true
+  return hasMessageMarker(error, TREE_PLACEMENT_STALE_MARKER)
+}
+
+/** Detect when tree/audit committed even if transport reconstruction dropped the code. */
+export function isCommittedTreeHookFailure(error: unknown): boolean {
+  if (hasErrorCode(error, ErrorCodes.TREE_HOOK_COMMITTED)) return true
+  return hasMessageMarker(error, TREE_HOOK_COMMITTED_MARKER)
+}
+
+export type AdminTreeMoveOutcome =
+  | { status: 'ok' }
+  | { status: 'suppressed' }
+  | { status: 'mutation-failed'; error: unknown; refreshError?: unknown }
+  | { status: 'committed-hook-failed'; error: unknown; refreshError?: unknown }
+  | { status: 'refresh-failed'; error: unknown }
+
+export interface AdminTreeMoveUiEffects {
+  rollback: boolean
+  preserveOptimistic: boolean
+  structuralFailure: 'conflict' | 'generic' | null
+  committedHookWarning: boolean
+  refreshWarning: boolean
+}
+
+/** Pure UI policy for every mutation/refresh outcome. */
+export function getAdminTreeMoveUiEffects(outcome: AdminTreeMoveOutcome): AdminTreeMoveUiEffects {
+  if (outcome.status === 'mutation-failed') {
+    return {
+      rollback: true,
+      preserveOptimistic: false,
+      structuralFailure: isTreeMutationConflict(outcome.error) ? 'conflict' : 'generic',
+      committedHookWarning: false,
+      refreshWarning: outcome.refreshError != null,
+    }
+  }
+  if (outcome.status === 'committed-hook-failed') {
+    return {
+      rollback: false,
+      preserveOptimistic: outcome.refreshError != null,
+      structuralFailure: null,
+      committedHookWarning: true,
+      refreshWarning: outcome.refreshError != null,
+    }
+  }
+  if (outcome.status === 'refresh-failed') {
+    return {
+      rollback: false,
+      preserveOptimistic: true,
+      structuralFailure: null,
+      committedHookWarning: false,
+      refreshWarning: true,
+    }
+  }
+  return {
+    rollback: outcome.status === 'suppressed',
+    preserveOptimistic: false,
+    structuralFailure: null,
+    committedHookWarning: false,
+    refreshWarning: false,
+  }
+}
+
+/** Preserve a committed optimistic move until a later loader returns new row data. */
+export function shouldSyncAdminTreeRows(
+  rows: unknown,
+  preservedRows: unknown,
+  isMoving: boolean
+): boolean {
+  return !isMoving && rows !== preservedRows
+}
+
+/** Keep mutation and canonical-refresh failures distinct for optimistic tree UIs. */
+export async function executeAdminTreeMove(
+  mutate: () => Promise<unknown>,
+  refresh: () => Promise<unknown>
+): Promise<AdminTreeMoveOutcome> {
+  try {
+    await mutate()
+  } catch (error) {
+    const status = isCommittedTreeHookFailure(error)
+      ? ('committed-hook-failed' as const)
+      : ('mutation-failed' as const)
+    try {
+      await refresh()
+      return { status, error }
+    } catch (refreshError) {
+      return { status, error, refreshError }
+    }
+  }
+
+  try {
+    await refresh()
+    return { status: 'ok' }
+  } catch (error) {
+    return { status: 'refresh-failed', error }
+  }
+}
+
+export interface AdminTreeMoveController {
+  isMoving(): boolean
+  execute(
+    mutate: () => Promise<unknown>,
+    refresh: () => Promise<unknown>
+  ): Promise<AdminTreeMoveOutcome>
+}
+
+/** Single-flight controller shared by pointer and keyboard tree moves. */
+export function createAdminTreeMoveController(): AdminTreeMoveController {
+  let moving = false
+  return {
+    isMoving: () => moving,
+    execute: async (mutate, refresh) => {
+      if (moving) return { status: 'suppressed' }
+      moving = true
+      try {
+        return await executeAdminTreeMove(mutate, refresh)
+      } finally {
+        moving = false
+      }
+    },
+  }
+}
+
+/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+export function placeAdminTreeNode(
+  handle: Pick<CollectionHandle, 'placeTreeNode'>,
+  documentId: string,
+  options: PlaceTreeNodeOptions
+): Promise<{ orderKey: string }> {
+  return handle.placeTreeNode(documentId, {
+    ...options,
+    reconcile: options.reconcile ?? true,
+  })
+}
+
+/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+export function removeAdminTreeNode(
+  handle: Pick<CollectionHandle, 'removeFromTree'>,
+  documentId: string,
+  options: RemoveFromTreeOptions = {}
+): Promise<void> {
+  return handle.removeFromTree(documentId, {
+    ...options,
+    reconcile: options.reconcile ?? true,
+  })
+}

package/src/server-fns/collections/tree-read.test.node.ts

@@ -0,0 +1,46 @@
+import { createReadContext } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import { getAdminTreeParent, getAdminUnplacedTreeDocuments } from './tree-read.js'
+
+describe('getAdminTreeParent', () => {
+  it('explicitly selects status:any', async () => {
+    const getTreeParent = vi.fn().mockResolvedValue({
+      placed: false,
+      parentDocumentId: null,
+      parentVisibility: 'none',
+    })
+
+    await getAdminTreeParent({ getTreeParent } as any, 'doc-1')
+
+    expect(getTreeParent).toHaveBeenCalledWith('doc-1', { status: 'any' })
+  })
+})
+
+describe('getAdminUnplacedTreeDocuments', () => {
+  it('uses scoped any-mode reads so hidden unplaced nodes cannot reappear', async () => {
+    const visible = { id: 'visible-unplaced' }
+    const hidden = { id: 'hidden-unplaced' }
+    const readContext = createReadContext()
+    const find = vi.fn(async (options: Record<string, unknown>) => ({
+      docs: options._bypassBeforeRead === true ? [visible, hidden] : [visible],
+      meta: { total: 1, page: 1, pageSize: 1000, totalPages: 1 },
+    }))
+
+    const result = await getAdminUnplacedTreeDocuments(
+      { find } as any,
+      new Set(['visible-placed']),
+      readContext,
+      'en'
+    )
+
+    expect(find).toHaveBeenCalledWith({
+      status: 'any',
+      locale: 'en',
+      pageSize: 1000,
+      _readContext: readContext,
+    })
+    expect(result.map((doc) => doc.id)).toEqual(['visible-unplaced'])
+    expect(result).not.toContain(hidden)
+  })
+})

package/src/server-fns/collections/tree-read.ts

@@ -0,0 +1,26 @@
+import type { ClientDocument, CollectionHandle, TreeParentResult } from '@byline/client'
+import type { ReadContext } from '@byline/core'
+
+/** Admin tree placement reads must include drafts. */
+export function getAdminTreeParent(
+  handle: Pick<CollectionHandle, 'getTreeParent'>,
+  documentId: string
+): Promise<TreeParentResult> {
+  return handle.getTreeParent(documentId, { status: 'any' })
+}
+
+/** Find unplaced nodes through the same row scope as the structural tree read. */
+export async function getAdminUnplacedTreeDocuments(
+  handle: Pick<CollectionHandle, 'find'>,
+  placed: ReadonlySet<string>,
+  readContext: ReadContext,
+  locale?: string
+): Promise<ClientDocument[]> {
+  const all = await handle.find({
+    status: 'any',
+    locale,
+    pageSize: 1000,
+    _readContext: readContext,
+  })
+  return all.docs.filter((doc) => !placed.has(doc.id))
+}

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

@@ -16,10 +16,12 @@
 
 import { createServerFn } from '@tanstack/react-start'
 
-import { ERR_NOT_FOUND, getLogger } from '@byline/core'
+import { createReadContext, ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { getAdminBylineClient } from '../../integrations/byline-client.js'
+import { placeAdminTreeNode, removeAdminTreeNode } from './tree-mutation.js'
+import { getAdminTreeParent, getAdminUnplacedTreeDocuments } from './tree-read.js'
 
 // ---------------------------------------------------------------------------
 // Place / move a node within the tree (place / reorder / re-parent)
@@ -33,6 +35,7 @@ export const placeTreeNode = createServerFn({ method: 'POST' })
       parentDocumentId: string | null
       beforeDocumentId?: string | null
       afterDocumentId?: string | null
+      reconcile?: boolean
     }) => input
   )
   .handler(async ({ data }) => {
@@ -45,10 +48,11 @@ export const placeTreeNode = createServerFn({ method: 'POST' })
       }).log(getLogger())
     }
     const handle = getAdminBylineClient().collection(path)
-    const result = await handle.placeTreeNode(documentId, {
+    const result = await placeAdminTreeNode(handle, documentId, {
       parentDocumentId: data.parentDocumentId,
       beforeDocumentId: data.beforeDocumentId ?? null,
       afterDocumentId: data.afterDocumentId ?? null,
+      reconcile: data.reconcile,
     })
     return { status: 'ok' as const, orderKey: result.orderKey }
   })
@@ -58,7 +62,7 @@ export const placeTreeNode = createServerFn({ method: 'POST' })
 // ---------------------------------------------------------------------------
 
 export const removeFromTree = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; documentId: string }) => input)
+  .validator((input: { collection: string; documentId: string; reconcile?: boolean }) => input)
   .handler(async ({ data }) => {
     const { collection: path, documentId } = data
     const config = await ensureCollection(path)
@@ -68,7 +72,9 @@ export const removeFromTree = createServerFn({ method: 'POST' })
         details: { collectionPath: path },
       }).log(getLogger())
     }
-    await getAdminBylineClient().collection(path).removeFromTree(documentId)
+    await removeAdminTreeNode(getAdminBylineClient().collection(path), documentId, {
+      reconcile: data.reconcile,
+    })
     return { status: 'ok' as const }
   })
 
@@ -118,7 +124,7 @@ export const getTreeParent = createServerFn({ method: 'GET' })
         details: { collectionPath: path },
       }).log(getLogger())
     }
-    return getAdminBylineClient().collection(path).getTreeParent(documentId)
+    return getAdminTreeParent(getAdminBylineClient().collection(path), documentId)
   })
 
 // ---------------------------------------------------------------------------
@@ -154,8 +160,19 @@ export const getCollectionTree = createServerFn({ method: 'GET' })
       }).log(getLogger())
     }
     const handle = getAdminBylineClient().collection(path)
-
-    const forest = await handle.getSubtree({ status: 'any', locale: data.locale })
+    // Shared deliberately across the structural and unplaced reads: the
+    // beforeRead predicate cache is per-ReadContext, so sharing gives both
+    // halves one predicate snapshot — a time-dependent predicate (embargo
+    // cutoff) evaluated twice could otherwise disagree between the placed
+    // forest and the unplaced list. The request-memoized context factory
+    // keeps this sharing safe (one request authority per request).
+    const readContext = createReadContext()
+
+    const forest = await handle.getSubtree({
+      status: 'any',
+      locale: data.locale,
+      _readContext: readContext,
+    })
     const rows: CollectionTreeRow[] = []
     const placed = new Set<string>()
     const walk = (nodes: typeof forest, depth: number, parentId: string | null): void => {
@@ -180,9 +197,8 @@ export const getCollectionTree = createServerFn({ method: 'GET' })
 
     // Surface documents not yet in the tree (e.g. freshly created) so they
     // remain reachable. Trees are small by design, so a single wide read is fine.
-    const all = await handle.find({ status: 'any', pageSize: 1000, _bypassBeforeRead: true })
-    for (const doc of all.docs) {
-      if (placed.has(doc.id)) continue
+    const unplaced = await getAdminUnplacedTreeDocuments(handle, placed, readContext, data.locale)
+    for (const doc of unplaced) {
       rows.push({
         id: doc.id,
         parentId: null,

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

@@ -118,6 +118,9 @@ export const updateCollectionDocumentSystemFields = createServerFn({ method: 'PO
       locale: locale ?? serverConfig.i18n.content.defaultLocale,
       path: explicitPath,
       availableLocales,
+      // A failed after-hook happens after commit. Retrying this same admin save
+      // must re-run cache/search reconciliation when DB values are now current.
+      reconcile: true,
     })
 
     return { status: 'ok' as const }

package/src/vite/client-hook-boundary.test.node.ts

@@ -0,0 +1,50 @@
+/**
+ * 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
+ */
+
+/**
+ * Unit coverage for the client-bundle guard's module classifier. Production
+ * application builds exercise the Vite plugin itself; these focused cases pin
+ * path normalization and the supported server-only filename conventions.
+ */
+import { describe, expect, it } from 'vitest'
+
+import { findServerHookModules } from './client-hook-boundary.js'
+
+describe('client hook boundary', () => {
+  it('finds collection hook implementations and their shared server graph', () => {
+    expect(
+      findServerHookModules([
+        '/project/byline/collections/docs/hooks.ts',
+        '/project/byline/collections/content-types/publications/file-hooks.ts',
+        '/project/byline/collections/content-types/publications/cover-hooks.tsx',
+        '/project/byline/collections/server-hooks.ts?import',
+        String.raw`C:\project\byline\collections\create-revalidation-lifecycle-hooks.ts`,
+        '/project/byline/collections/events/hooks.mts',
+        '/project/byline/collections/run-webhook-side-effects.ts?worker',
+        '/project/byline/collections/docs/schema.ts',
+      ])
+    ).toEqual([
+      '/project/byline/collections/docs/hooks.ts',
+      '/project/byline/collections/content-types/publications/file-hooks.ts',
+      '/project/byline/collections/content-types/publications/cover-hooks.tsx',
+      '/project/byline/collections/server-hooks.ts?import',
+      String.raw`C:\project\byline\collections\create-revalidation-lifecycle-hooks.ts`,
+      '/project/byline/collections/events/hooks.mts',
+      '/project/byline/collections/run-webhook-side-effects.ts?worker',
+    ])
+  })
+
+  it('allows schemas and unrelated client modules', () => {
+    expect(
+      findServerHookModules([
+        '/project/byline/collections/docs/schema.ts',
+        '/project/src/ui/byline/render-blocks.tsx',
+      ])
+    ).toEqual([])
+  })
+})

package/src/vite/client-hook-boundary.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+
+/**
+ * Production client-bundle guard for server-only Byline lifecycle modules.
+ *
+ * Collection schemas are isomorphic, but registered lifecycle hooks may
+ * import Node APIs, caches, storage SDKs, and other server-only dependencies.
+ * This Vite plugin inspects emitted client chunks and fails the build if a
+ * hook implementation, server hook registry, or shared lifecycle helper
+ * becomes reachable from the browser bundle.
+ */
+import type { Plugin } from 'vite'
+
+const SERVER_HOOK_MODULE =
+  /\/byline\/collections\/(?:.+\/)?(?:hooks|[^/]+-hooks|[^/]+-lifecycle-hooks|[^/]+-side-effects)\.[cm]?[jt]sx?$/
+
+export function findServerHookModules(moduleIds: Iterable<string>): string[] {
+  return [...moduleIds].filter((moduleId) => {
+    const normalized = moduleId.replaceAll('\\', '/').split('?', 1)[0]
+    return SERVER_HOOK_MODULE.test(normalized)
+  })
+}
+
+export function bylineClientHookBoundary(): Plugin {
+  return {
+    name: 'byline:client-hook-boundary',
+    generateBundle(_options, bundle) {
+      if (this.environment?.name !== 'client') return
+      const leaked = findServerHookModules(
+        Object.values(bundle).flatMap((output) =>
+          output.type === 'chunk' ? Object.keys(output.modules) : []
+        )
+      )
+      if (leaked.length > 0) {
+        this.error(`server lifecycle modules entered the client bundle:\n${leaked.join('\n')}`)
+      }
+    },
+  }
+}

package/src/vite/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ */
+
+export { bylineClientHookBoundary } from './client-hook-boundary.js'