@byline/cli 3.12.2 → 3.13.0

package/dist/templates/byline-examples/collections/docs/schema.ts

@@ -33,7 +33,14 @@ export const Docs = defineCollection({
     customStatuses: [{ name: 'needs_review', label: 'Needs Review', verb: 'Request Review' }],
   }),
   showStats: true,
-  orderable: true,
+  // Document tree (docs/DOCUMENT-TREE.md): the docs collection is a
+  // single-parent ordered hierarchy. Mutually exclusive with `orderable` —
+  // the tree owns ordering (per-parent, on the edge), so `order_key` on
+  // `byline_documents` is inert here. Sibling order and nesting are edited via
+  // the sidebar tree-placement widget; the import script can also derive
+  // placement from the source directory layout (see
+  // byline/scripts/import-docs.ts --tree).
+  tree: true,
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
@@ -110,6 +117,13 @@ export const Docs = defineCollection({
         `afterDelete: Document in collection ${collectionPath} with document ID ${documentId} deleted.`
       )
     },
+    // Fires on any structural tree change (place / reorder / re-parent /
+    // promote-on-delete) for a `tree: true` collection. The payload carries the
+    // affected set; a docs site typically invalidates its nav / breadcrumb /
+    // prev-next caches here.
+    afterTreeChange: async ({ collectionPath }) => {
+      console.log(`afterTreeChange: tree structure changed in collection ${collectionPath}.`)
+    },
   },
   fields: [
     {

package/dist/templates/byline-examples/fields/lexical-richtext-ai.tsx

@@ -27,7 +27,7 @@
 
 import { AiLexicalExtension } from '@byline/ai/plugins/lexical'
 import type { FieldAdminConfig, RichTextEditorProps } from '@byline/core'
-import { lexicalEditor } from '@byline/richtext-lexical'
+import { builtInExtensions, lexicalEditor } from '@byline/richtext-lexical/config'
 
 /**
  * AI-enabled wrapper around `@byline/richtext-lexical`'s editor.
@@ -49,7 +49,17 @@ import { lexicalEditor } from '@byline/richtext-lexical'
  * **Per-field** opt-in — see `aiRichTextAdmin()` below.
  */
 export const LexicalRichTextAi = lexicalEditor((c) => {
-  c.extensions.add(AiLexicalExtension)
+  c.extensions.add(AiLexicalExtension).remove(builtInExtensions.FloatingTextFormat)
+  // Document-level "view as markdown source" toolbar toggle (the capital-M
+  // button) enabled site-wide on the AI editor. Settings live on the baked
+  // registration config so every richtext field keeps the AI assistant AND
+  // the markdown toggle — a schema-side `editorConfig` would override this
+  // baked config and strip the AI extension (it can't carry extensions).
+  c.settings.options.markdownToggle = true
+  // Inline as-you-type markdown shortcuts (`# ` → H1, `- ` → list, `**x**`
+  // → bold, `| a | b |` → table, `:::note` → admonition, …). Uses the same
+  // BYLINE_TRANSFORMERS set as the source toggle. Remove this line to disable.
+  c.settings.options.markdownShortcutPlugin = true
   return c
 }) satisfies (props: RichTextEditorProps) => React.JSX.Element
 

package/dist/templates/byline-examples/scripts/import-docs.ts

@@ -24,7 +24,9 @@
  *
  * Per-file flow:
  *   1. Read the file, split frontmatter from body with gray-matter.
- *   2. Parse the body to mdast via remark-parse + remark-gfm.
+ *   2. Parse the body to mdast via remark-parse + remark-gfm, lifting
+ *      Docusaurus-style admonition fences (`:::note[Title] … :::`) into
+ *      synthetic nodes (see lib/parse-markdown.ts).
  *   3. Rewrite `./SIBLING.md[#hash]` links to `/docs/<imported-path>`
  *      using a sourcePath→docPath map built from a frontmatter pre-pass.
  *      Targets outside the batch are stripped to plain text.
@@ -36,6 +38,17 @@
  * Flags:
  *   --dry-run     Parse + log, no DB writes.
  *   --verbose     Print warnings for dropped/unsupported nodes.
+ *   --tree        After importing, build the document tree from the source
+ *                 directory layout (the "folder + index.md" convention). A flat
+ *                 `D/leaf.md` nests under `D/index.md`; a `D/index.md` (a node
+ *                 that owns a folder) nests under the grandparent's index,
+ *                 `dirname(D)/index.md`; a node with no `index.md` parent is a
+ *                 root. A folder appears exactly when a node has children, at
+ *                 any depth. Sibling order follows the source file sort, so
+ *                 number directories/files with `NN-` prefixes to curate the
+ *                 TOC — prefixes never reach the slug (paths come from
+ *                 frontmatter). The `docs` collection must be `tree: true`.
+ *                 See docs/DOCUMENT-TREE.md.
  */
 
 import '../load-env.js'
@@ -43,18 +56,15 @@ import '../server.config.js'
 
 import { readFileSync } from 'node:fs'
 import { glob } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 
 import { createSuperAdminContext } from '@byline/auth'
 import { type CollectionHandle, createBylineClient } from '@byline/client'
 import { getCollectionDefinition, getServerConfig, slugify } from '@byline/core'
-import type { Root } from 'mdast'
-import remarkGfm from 'remark-gfm'
-import remarkParse from 'remark-parse'
-import { unified } from 'unified'
 
 import { type DocFrontmatter, parseDocFile } from './lib/frontmatter.js'
 import { type MdastToLexicalWarning, mdastToLexical } from './lib/mdast-to-lexical.js'
+import { parseBodyToMdast } from './lib/parse-markdown.js'
 import { type DocLinkRewriteWarning, rewriteDocLinks } from './lib/rewrite-doc-links.js'
 import { stripLeadingH1IfMatches } from './lib/strip-leading-h1.js'
 
@@ -66,14 +76,16 @@ const DEFAULT_IMPORT_STATUS = 'published'
 interface Flags {
   dryRun: boolean
   verbose: boolean
+  tree: boolean
   patterns: string[]
 }
 
 function parseFlags(argv: string[]): Flags {
-  const flags: Flags = { dryRun: false, verbose: false, patterns: [] }
+  const flags: Flags = { dryRun: false, verbose: false, tree: false, patterns: [] }
   for (const arg of argv) {
     if (arg === '--dry-run') flags.dryRun = true
     else if (arg === '--verbose') flags.verbose = true
+    else if (arg === '--tree') flags.tree = true
     else if (arg.startsWith('--')) throw new Error(`unknown flag: ${arg}`)
     else flags.patterns.push(arg)
   }
@@ -95,10 +107,6 @@ async function expandPatterns(patterns: string[]): Promise<string[]> {
   return [...out].sort()
 }
 
-function parseBodyToMdast(body: string): Root {
-  return unified().use(remarkParse).use(remarkGfm).parse(body) as Root
-}
-
 function logWarnings(filePath: string, warnings: MdastToLexicalWarning[]): void {
   if (warnings.length === 0) return
   console.warn(`  - ${warnings.length} warning(s) for ${filePath}:`)
@@ -305,6 +313,73 @@ async function processFile(
   return { filePath, action: 'created', documentId: result.documentId, path: docPath }
 }
 
+/**
+ * Resolve the source file of a node's parent under the "folder + index.md"
+ * convention: a flat `D/leaf.md` is a child of `D/index.md`; a `D/index.md` (a
+ * node that owns a folder) is a child of the grandparent's index,
+ * `dirname(D)/index.md`. The returned path may not exist (e.g. the docs root
+ * has no `index.md`); the caller treats a miss as "this node is a root".
+ */
+function parentIndexFile(filePath: string): string {
+  const dir = dirname(filePath)
+  const base = basename(filePath)
+  const isIndex = base === 'index.md' || base === 'index.markdown'
+  return join(isIndex ? dirname(dir) : dir, 'index.md')
+}
+
+/**
+ * Build the document tree from the source directory layout, after every file
+ * has been imported (so all parent documents exist). A node's parent is the
+ * `index.md` resolved by {@link parentIndexFile}; a node whose parent index is
+ * not in the batch is a root. Structure is filesystem-derived (not name-matched
+ * to paths), so directory names are free and `NN-` prefixes only affect order.
+ *
+ * Siblings are appended after the previous sibling in their group so they get
+ * distinct, monotonically-increasing per-parent keys (placing with no
+ * neighbours would mint the same first key for every sibling). Files are
+ * processed in sorted order, so prefix order carries straight through.
+ */
+async function placeTreeFromDirectories(
+  handle: CollectionHandle,
+  results: ProcessResult[]
+): Promise<void> {
+  const placeable = results.filter(
+    (r): r is ProcessResult & { documentId: string } => r.documentId != null
+  )
+  // Index nodes by source file so a child resolves its parent's `index.md`
+  // structurally (by path on disk), not by matching directory names to slugs.
+  const idByFile = new Map(placeable.map((r) => [r.filePath, r.documentId]))
+
+  const ROOT_GROUP = '__root__'
+  const lastSiblingByGroup = new Map<string, string>()
+
+  let rooted = 0
+  let placed = 0
+  let failed = 0
+  for (const r of placeable) {
+    const parentId = idByFile.get(parentIndexFile(r.filePath))
+    const parentDocumentId = parentId != null && parentId !== r.documentId ? parentId : null
+    const groupKey = parentDocumentId ?? ROOT_GROUP
+    const beforeDocumentId = lastSiblingByGroup.get(groupKey) ?? null
+    try {
+      await handle.placeTreeNode(r.documentId, { parentDocumentId, beforeDocumentId })
+      lastSiblingByGroup.set(groupKey, r.documentId)
+      if (parentDocumentId != null) {
+        placed += 1
+        console.log(`  ↳ placed   ${r.path}  under  ${basename(dirname(r.filePath))}`)
+      } else {
+        rooted += 1
+      }
+    } catch (err) {
+      failed += 1
+      console.error(`  ✗ tree     ${r.path}: ${err instanceof Error ? err.message : err}`)
+    }
+  }
+  console.log(
+    `import-docs: tree — ${rooted} root(s), ${placed} child placement(s), ${failed} failed.`
+  )
+}
+
 async function run(): Promise<void> {
   const flags = parseFlags(process.argv.slice(2))
   const files = await expandPatterns(flags.patterns)
@@ -328,10 +403,12 @@ async function run(): Promise<void> {
   let updated = 0
   let skipped = 0
   let failed = 0
+  const results: ProcessResult[] = []
 
   for (const file of files) {
     try {
       const result = await processFile(file, client, handle, flags, pathMap)
+      results.push(result)
       if (result.action === 'created') created += 1
       else if (result.action === 'updated') updated += 1
       else skipped += 1
@@ -346,6 +423,15 @@ async function run(): Promise<void> {
   console.log(
     `import-docs: ${created} created, ${updated} updated, ${skipped} skipped, ${failed} failed.`
   )
+
+  // Build the tree from the directory layout, once every parent exists.
+  if (flags.tree && !flags.dryRun) {
+    console.log('import-docs: building document tree from directory layout…')
+    await placeTreeFromDirectories(handle, results)
+  } else if (flags.tree && flags.dryRun) {
+    console.log('import-docs: --tree requested but skipped under --dry-run (no DB writes).')
+  }
+
   if (failed > 0) process.exit(1)
 }
 

package/dist/templates/byline-examples/scripts/lib/frontmatter.ts

@@ -87,14 +87,13 @@ export function parseDocFile(source: string, filePath: string): ParsedDoc {
     fm.summary = data.summary
   }
 
-  if (data.status !== undefined) {
-    if (typeof data.status !== 'string' || !ALLOWED_STATUSES.has(data.status)) {
-      throw new Error(
-        `${filePath}: 'status' must be one of ${[...ALLOWED_STATUSES].join(', ')}; got '${String(
-          data.status
-        )}'.`
-      )
-    }
+  // `status` is overloaded: a workflow status (draft / published / …) is an
+  // import directive, but Byline's own design docs also use `status:` for
+  // *descriptive* metadata (e.g. "PARTIALLY IMPLEMENTED — …"). Treat a value
+  // that isn't a workflow status as descriptive — ignore it for import (the
+  // file falls back to the default import status) rather than rejecting the
+  // whole file. Only a workflow status is carried through as a directive.
+  if (typeof data.status === 'string' && ALLOWED_STATUSES.has(data.status)) {
     fm.status = data.status as DocFrontmatter['status']
   }
 

package/dist/templates/byline-examples/scripts/lib/mdast-to-lexical.test.node.ts

@@ -6,20 +6,13 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import type { Root } from 'mdast'
-import remarkGfm from 'remark-gfm'
-import remarkParse from 'remark-parse'
-import { unified } from 'unified'
 import { describe, expect, test } from 'vitest'
 
 import { mdastToLexical } from './mdast-to-lexical.js'
-
-function parse(md: string): Root {
-  return unified().use(remarkParse).use(remarkGfm).parse(md) as Root
-}
+import { parseBodyToMdast } from './parse-markdown.js'
 
 function convert(md: string) {
-  return mdastToLexical(parse(md))
+  return mdastToLexical(parseBodyToMdast(md))
 }
 
 describe('mdastToLexical', () => {
@@ -259,4 +252,84 @@ describe('mdastToLexical', () => {
       'In a world where AI produces content fast, into dozens of languages, why does a CMS matter?'
     )
   })
+
+  describe('admonitions', () => {
+    test('titled note becomes an admonition node with body paragraphs', () => {
+      const md = [':::note[Heads up]', 'First line.', '', 'Second line.', ':::'].join('\n')
+      const { state, warnings } = convert(md)
+      expect(warnings).toEqual([])
+      expect(state.root.children).toHaveLength(1)
+      const adm = state.root.children[0] as unknown as {
+        type: string
+        admonitionType: string
+        title: string
+        children: Array<{ type: string; children: Array<{ text: string }> }>
+      }
+      expect(adm).toMatchObject({ type: 'admonition', admonitionType: 'note', title: 'Heads up' })
+      expect(adm.children).toHaveLength(2)
+      expect(adm.children[0]).toMatchObject({ type: 'paragraph' })
+      expect(adm.children[0].children[0].text).toBe('First line.')
+      expect(adm.children[1].children[0].text).toBe('Second line.')
+    })
+
+    test('inline formatting + links survive inside an admonition body', () => {
+      const md = [
+        ':::warning[Careful]',
+        'This is **bold** and a [link](https://x.io).',
+        ':::',
+      ].join('\n')
+      const { state } = convert(md)
+      const adm = state.root.children[0] as unknown as {
+        admonitionType: string
+        children: Array<{ children: Array<{ type: string; text?: string; format?: number }> }>
+      }
+      expect(adm.admonitionType).toBe('warning')
+      const inline = adm.children[0].children
+      expect(inline).toContainEqual(expect.objectContaining({ text: 'bold', format: 1 }))
+      expect(inline).toContainEqual(expect.objectContaining({ type: 'link' }))
+    })
+
+    test('untitled admonition carries an empty title', () => {
+      const { state } = convert([':::tip', 'A quick tip.', ':::'].join('\n'))
+      const adm = state.root.children[0] as unknown as { admonitionType: string; title: string }
+      expect(adm).toMatchObject({ admonitionType: 'tip', title: '' })
+    })
+
+    test('an empty admonition body is seeded with one empty paragraph', () => {
+      const { state } = convert([':::danger[Stop]', ':::'].join('\n'))
+      const adm = state.root.children[0] as unknown as {
+        admonitionType: string
+        children: Array<{ type: string; children: unknown[] }>
+      }
+      expect(adm.admonitionType).toBe('danger')
+      expect(adm.children).toEqual([expect.objectContaining({ type: 'paragraph', children: [] })])
+    })
+
+    test('admonitions sit alongside ordinary blocks in source order', () => {
+      const md = ['# Title', '', ':::note[Note]', 'Body.', ':::', '', 'After.'].join('\n')
+      const { state } = convert(md)
+      expect(state.root.children.map((c) => (c as { type: string }).type)).toEqual([
+        'heading',
+        'admonition',
+        'paragraph',
+      ])
+    })
+
+    test('colon-bearing prose is never mistaken for a directive', () => {
+      // The line scanner only matches the four container fences, so inline
+      // colons (`9:30`, `1:2:3`, `note:foo`) pass through untouched.
+      const { state, warnings } = convert('Run at 9:30 with a 1:2:3 ratio and note:foo.')
+      expect(warnings).toEqual([])
+      const paragraph = state.root.children[0] as unknown as { children: Array<{ text: string }> }
+      expect(paragraph.children).toHaveLength(1)
+      expect(paragraph.children[0].text).toBe('Run at 9:30 with a 1:2:3 ratio and note:foo.')
+    })
+
+    test('a `:::` fence inside a code block is treated as literal code', () => {
+      const md = ['```', ':::note[Not an admonition]', 'still code', ':::', '```'].join('\n')
+      const { state } = convert(md)
+      expect(state.root.children).toHaveLength(1)
+      expect(state.root.children[0]).toMatchObject({ type: 'code' })
+    })
+  })
 })

package/dist/templates/byline-examples/scripts/lib/mdast-to-lexical.ts

@@ -44,6 +44,8 @@ import type {
   ThematicBreak,
 } from 'mdast'
 
+import type { AdmonitionDirective } from './parse-markdown.js'
+
 // Lexical inline format bits — kept in sync with
 // apps/webapp/src/ui/byline/components/richtext-lexical/serialize/richtext-node-formats.ts
 const IS_BOLD = 1
@@ -113,6 +115,11 @@ function walkBlocks(nodes: Content[], warnings: MdastToLexicalWarning[]): Lexica
 }
 
 function blockNode(node: Content, warnings: MdastToLexicalWarning[]): LexicalNode | null {
+  // Synthetic admonition container injected by `parse-markdown` — handled
+  // ahead of the mdast switch since it isn't a real mdast node type.
+  if ((node as { type: string }).type === 'admonitionDirective') {
+    return admonitionNode(node as unknown as AdmonitionDirective, warnings)
+  }
   switch (node.type) {
     case 'paragraph':
       return paragraphNode(node, warnings)
@@ -250,6 +257,26 @@ function blockquoteNode(node: Blockquote, warnings: MdastToLexicalWarning[]): Le
   }
 }
 
+// Byline admonition (callout). An ElementNode whose body lives as real
+// block children — paragraphs + inline content — matching the editor's
+// `AdmonitionNode`. `admonitionType` / `title` ride the node, not the body.
+function admonitionNode(node: AdmonitionDirective, warnings: MdastToLexicalWarning[]): LexicalNode {
+  const children = walkBlocks(node.children as Content[], warnings)
+  // Never leave the body empty — mirrors the editor transformer, which
+  // seeds an empty paragraph so the caret has somewhere to land.
+  if (children.length === 0) children.push(emptyParagraph())
+  return {
+    type: 'admonition',
+    version: 1,
+    direction: 'ltr',
+    format: '',
+    indent: 0,
+    admonitionType: node.admonitionType,
+    title: node.title,
+    children,
+  }
+}
+
 // Markdown fence shorthands → prism-react-renderer language ids. Prism
 // bundles `typescript` / `tsx` / `bash` etc. but not the common shorthand
 // forms most authors write. Without normalization the imported language

package/dist/templates/byline-examples/scripts/lib/parse-markdown.ts

@@ -0,0 +1,131 @@
+/**
+ * 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
+ */
+
+/**
+ * Markdown body → mdast, with Byline admonition extraction.
+ *
+ * Plain markdown is parsed with remark-parse + remark-gfm. On top of that
+ * we recognise the Docusaurus-style admonition container blocks the editor
+ * round-trips:
+ *
+ *   :::note[Optional Title]
+ *   body markdown (paragraphs + inline)
+ *   :::
+ *
+ * The fences are line-based and matched with the *same* regexes as the live
+ * editor transformer (`packages/richtext-lexical/src/field/markdown/
+ * transformers.ts`), so authored markdown round-trips identically through
+ * bulk import and the editor's markdown toggle.
+ *
+ * Why a line scanner rather than `remark-directive`: remark-directive also
+ * recognises inline (`:name`) and leaf (`::name`) directives, which turns
+ * ordinary prose like `9:30`, `1:2:3`, or `note:foo` into `textDirective`
+ * nodes — silently corrupting colon-bearing technical prose. Restricting
+ * recognition to the line-anchored container fence avoids that blast radius
+ * entirely and is lossless for every non-admonition character.
+ *
+ * Each admonition becomes a synthetic `admonitionDirective` mdast node whose
+ * `children` are the parsed body blocks. It is consumed by
+ * `mdast-to-lexical`'s `blockNode`. The node still carries a `children`
+ * array, so the link-rewrite pass traverses into admonition bodies normally.
+ */
+
+import type { Root, RootContent } from 'mdast'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+
+export type AdmonitionType = 'note' | 'tip' | 'warning' | 'danger'
+
+/**
+ * Synthetic mdast node for a Byline admonition container. Not a real mdast
+ * type — produced here and handled by `mdast-to-lexical`. `title` is the raw
+ * text from the opening fence's `[...]` (empty string when absent).
+ */
+export interface AdmonitionDirective {
+  type: 'admonitionDirective'
+  admonitionType: AdmonitionType
+  title: string
+  children: RootContent[]
+}
+
+// Mirrors transformers.ts: only the four Docusaurus types start an
+// admonition; the optional `[Title]` rides the opening fence.
+const ADMONITION_START_RE = /^:::(note|tip|warning|danger)(?:\[([^\]]*)\])?\s*$/
+const ADMONITION_END_RE = /^:::\s*$/
+// Fenced code-block delimiter — `:::` lines inside a code fence are literal
+// content, not admonition fences. (A coarse toggle; remark remains the
+// source of truth for the actual code parse.)
+const CODE_FENCE_RE = /^\s*(```|~~~)/
+
+function parseSegment(text: string): RootContent[] {
+  if (text.trim().length === 0) return []
+  const tree = unified().use(remarkParse).use(remarkGfm).parse(text) as Root
+  return tree.children
+}
+
+export function parseBodyToMdast(body: string): Root {
+  const lines = body.split('\n')
+  const children: RootContent[] = []
+  let buffer: string[] = []
+  let inCode = false
+  let i = 0
+
+  const flushBuffer = (): void => {
+    if (buffer.length > 0) {
+      children.push(...parseSegment(buffer.join('\n')))
+      buffer = []
+    }
+  }
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    if (CODE_FENCE_RE.test(line)) {
+      inCode = !inCode
+      buffer.push(line)
+      i += 1
+      continue
+    }
+
+    const start = inCode ? null : ADMONITION_START_RE.exec(line)
+    if (start) {
+      flushBuffer()
+      const admonitionType = start[1] as AdmonitionType
+      const title = start[2] ?? ''
+      const inner: string[] = []
+      let innerCode = false
+      i += 1
+      while (i < lines.length) {
+        const bodyLine = lines[i]
+        if (CODE_FENCE_RE.test(bodyLine)) {
+          innerCode = !innerCode
+        } else if (!innerCode && ADMONITION_END_RE.test(bodyLine)) {
+          i += 1 // consume the closing fence
+          break
+        }
+        inner.push(bodyLine)
+        i += 1
+      }
+      const node: AdmonitionDirective = {
+        type: 'admonitionDirective',
+        admonitionType,
+        title,
+        children: parseSegment(inner.join('\n')),
+      }
+      children.push(node as unknown as RootContent)
+      continue
+    }
+
+    buffer.push(line)
+    i += 1
+  }
+  flushBuffer()
+
+  return { type: 'root', children: children as Root['children'] }
+}

package/dist/templates/migrations/{0000_rainy_starjammers.sql → 0000_ordinary_rhino.sql}

@@ -149,10 +149,12 @@ CREATE TABLE "byline_document_paths" (
 );
 --> statement-breakpoint
 CREATE TABLE "byline_document_relationships" (
-	"parent_document_id" uuid NOT NULL,
 	"child_document_id" uuid NOT NULL,
+	"parent_document_id" uuid,
+	"order_key" varchar(128) COLLATE "C" NOT NULL,
 	"created_at" timestamp (6) with time zone DEFAULT now() NOT NULL,
-	CONSTRAINT "byline_document_relationships_parent_document_id_child_document_id_unique" UNIQUE("parent_document_id","child_document_id")
+	"updated_at" timestamp (6) with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "uq_document_relationships_child" UNIQUE("child_document_id")
 );
 --> statement-breakpoint
 CREATE TABLE "byline_document_version_locales" (
@@ -303,8 +305,8 @@ ALTER TABLE "byline_document_available_locales" ADD CONSTRAINT "byline_document_
 ALTER TABLE "byline_document_available_locales" ADD CONSTRAINT "byline_document_available_locales_collection_id_byline_collections_id_fk" FOREIGN KEY ("collection_id") REFERENCES "public"."byline_collections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_paths" ADD CONSTRAINT "byline_document_paths_document_id_byline_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."byline_documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_paths" ADD CONSTRAINT "byline_document_paths_collection_id_byline_collections_id_fk" FOREIGN KEY ("collection_id") REFERENCES "public"."byline_collections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "byline_document_relationships" ADD CONSTRAINT "byline_document_relationships_parent_document_id_byline_documents_id_fk" FOREIGN KEY ("parent_document_id") REFERENCES "public"."byline_documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_relationships" ADD CONSTRAINT "byline_document_relationships_child_document_id_byline_documents_id_fk" FOREIGN KEY ("child_document_id") REFERENCES "public"."byline_documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "byline_document_relationships" ADD CONSTRAINT "byline_document_relationships_parent_document_id_byline_documents_id_fk" FOREIGN KEY ("parent_document_id") REFERENCES "public"."byline_documents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_version_locales" ADD CONSTRAINT "byline_document_version_locales_document_version_id_byline_document_versions_id_fk" FOREIGN KEY ("document_version_id") REFERENCES "public"."byline_document_versions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_versions" ADD CONSTRAINT "byline_document_versions_document_id_byline_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."byline_documents"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "byline_document_versions" ADD CONSTRAINT "byline_document_versions_collection_id_byline_collections_id_fk" FOREIGN KEY ("collection_id") REFERENCES "public"."byline_collections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
@@ -341,8 +343,7 @@ CREATE INDEX "idx_datetime_path_date" ON "byline_store_datetime" USING btree ("f
 CREATE INDEX "idx_datetime_collection_date" ON "byline_store_datetime" USING btree ("collection_id","value_timestamp_tz");--> statement-breakpoint
 CREATE INDEX "idx_document_available_locales_document_id" ON "byline_document_available_locales" USING btree ("document_id");--> statement-breakpoint
 CREATE INDEX "idx_document_paths_document_id" ON "byline_document_paths" USING btree ("document_id");--> statement-breakpoint
-CREATE INDEX "idx_document_relationships_parent" ON "byline_document_relationships" USING btree ("parent_document_id");--> statement-breakpoint
-CREATE INDEX "idx_document_relationships_child" ON "byline_document_relationships" USING btree ("child_document_id");--> statement-breakpoint
+CREATE INDEX "idx_document_relationships_parent_order" ON "byline_document_relationships" USING btree ("parent_document_id","order_key");--> statement-breakpoint
 CREATE INDEX "idx_documents_document_id" ON "byline_document_versions" USING btree ("document_id");--> statement-breakpoint
 CREATE INDEX "idx_documents_collection_document_deleted" ON "byline_document_versions" USING btree ("collection_id","document_id","is_deleted");--> statement-breakpoint
 CREATE INDEX "idx_documents_current_view" ON "byline_document_versions" USING btree ("collection_id","document_id","is_deleted","id");--> statement-breakpoint

package/dist/templates/migrations/meta/0000_snapshot.json

@@ -1,5 +1,5 @@
 {
-  "id": "00066c6d-bed5-4d32-8431-d950cb3ce641",
+  "id": "aebcb197-52c4-4601-a3b5-da89fe333c09",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -1403,16 +1403,22 @@
       "name": "byline_document_relationships",
       "schema": "",
       "columns": {
-        "parent_document_id": {
-          "name": "parent_document_id",
+        "child_document_id": {
+          "name": "child_document_id",
           "type": "uuid",
           "primaryKey": false,
           "notNull": true
         },
-        "child_document_id": {
-          "name": "child_document_id",
+        "parent_document_id": {
+          "name": "parent_document_id",
           "type": "uuid",
           "primaryKey": false,
+          "notNull": false
+        },
+        "order_key": {
+          "name": "order_key",
+          "type": "varchar(128) COLLATE \"C\"",
+          "primaryKey": false,
           "notNull": true
         },
         "created_at": {
@@ -1421,29 +1427,27 @@
           "primaryKey": false,
           "notNull": true,
           "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp (6) with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
         }
       },
       "indexes": {
-        "idx_document_relationships_parent": {
-          "name": "idx_document_relationships_parent",
+        "idx_document_relationships_parent_order": {
+          "name": "idx_document_relationships_parent_order",
           "columns": [
             {
               "expression": "parent_document_id",
               "isExpression": false,
               "asc": true,
               "nulls": "last"
-            }
-          ],
-          "isUnique": false,
-          "concurrently": false,
-          "method": "btree",
-          "with": {}
-        },
-        "idx_document_relationships_child": {
-          "name": "idx_document_relationships_child",
-          "columns": [
+            },
             {
-              "expression": "child_document_id",
+              "expression": "order_key",
               "isExpression": false,
               "asc": true,
               "nulls": "last"
@@ -1456,12 +1460,12 @@
         }
       },
       "foreignKeys": {
-        "byline_document_relationships_parent_document_id_byline_documents_id_fk": {
-          "name": "byline_document_relationships_parent_document_id_byline_documents_id_fk",
+        "byline_document_relationships_child_document_id_byline_documents_id_fk": {
+          "name": "byline_document_relationships_child_document_id_byline_documents_id_fk",
           "tableFrom": "byline_document_relationships",
           "tableTo": "byline_documents",
           "columnsFrom": [
-            "parent_document_id"
+            "child_document_id"
           ],
           "columnsTo": [
             "id"
@@ -1469,27 +1473,26 @@
           "onDelete": "cascade",
           "onUpdate": "no action"
         },
-        "byline_document_relationships_child_document_id_byline_documents_id_fk": {
-          "name": "byline_document_relationships_child_document_id_byline_documents_id_fk",
+        "byline_document_relationships_parent_document_id_byline_documents_id_fk": {
+          "name": "byline_document_relationships_parent_document_id_byline_documents_id_fk",
           "tableFrom": "byline_document_relationships",
           "tableTo": "byline_documents",
           "columnsFrom": [
-            "child_document_id"
+            "parent_document_id"
           ],
           "columnsTo": [
             "id"
           ],
-          "onDelete": "cascade",
+          "onDelete": "set null",
           "onUpdate": "no action"
         }
       },
       "compositePrimaryKeys": {},
       "uniqueConstraints": {
-        "byline_document_relationships_parent_document_id_child_document_id_unique": {
-          "name": "byline_document_relationships_parent_document_id_child_document_id_unique",
+        "uq_document_relationships_child": {
+          "name": "uq_document_relationships_child",
           "nullsNotDistinct": false,
           "columns": [
-            "parent_document_id",
             "child_document_id"
           ]
         }

package/dist/templates/migrations/meta/_journal.json

@@ -5,8 +5,8 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1781318465897,
-      "tag": "0000_rainy_starjammers",
+      "when": 1781967902464,
+      "tag": "0000_ordinary_rhino",
       "breakpoints": true
     }
   ]

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/cli",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.12.2",
+  "version": "3.13.0",
   "engines": {
     "node": ">=20.9.0"
   },