@byline/cli 2.6.1 → 3.0.0

package/dist/templates/byline/i18n.ts

@@ -39,9 +39,18 @@ export const i18n = {
   interface: {
     defaultLocale: 'en',
     locales: interfaceLocales.map((l) => l.code),
+    // Optional display names for the admin language switcher. Lets you
+    // author `Español` rather than the lowercase `español` that
+    // Intl.DisplayNames returns; omit to fall back to Intl per code.
+    localeDefinitions: interfaceLocales.map((l) => ({ code: l.code, nativeName: l.label })),
   },
   content: {
     defaultLocale: 'en',
     locales: contentLocales.map((l) => l.code),
+    // Optional display names for content locales. Byline doesn't render
+    // these (content has no admin switcher) — a public frontend can read
+    // them from getServerConfig().i18n.content.localeDefinitions to label
+    // hreflang / "read this in…" affordances without a parallel map.
+    localeDefinitions: contentLocales.map((l) => ({ code: l.code, nativeName: l.label })),
   },
 }

package/dist/templates/byline-examples/collections/docs/admin.tsx

@@ -200,6 +200,6 @@ export const DocsAdmin: CollectionAdminConfig = defineAdmin(Docs, {
    */
   layout: {
     main: ['tabs'],
-    sidebar: ['publishedOn', 'availableLanguages'],
+    sidebar: ['publishedOn'],
   },
 })

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

@@ -11,7 +11,6 @@ import { defineCollection, defineWorkflow } from '@byline/core'
 
 import { PhotoBlock } from '../../blocks/photo-block.js'
 import { RichTextBlock } from '../../blocks/richtext-block.js'
-import { availableLanguagesField } from '../../fields/available-languages-field.js'
 import { publishedOnField } from '../../fields/published-on-field.js'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -38,6 +37,7 @@ export const Docs = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
   // All hooks can be a single function or an array of functions.
   // If an array is provided, the functions will be executed in sequence.
@@ -156,7 +156,6 @@ export const Docs = defineCollection({
       optional: true,
       blocks: [RichTextBlock, PhotoBlock],
     },
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/collections/news/admin.tsx

@@ -214,6 +214,6 @@ export const NewsAdmin: CollectionAdminConfig = defineAdmin(News, {
    */
   layout: {
     main: ['main'],
-    sidebar: ['featured', 'availableLanguages', 'publishedOn'],
+    sidebar: ['featured', 'publishedOn'],
   },
 })

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

@@ -9,7 +9,6 @@
 import type { CollectionFieldData } from '@byline/core'
 import { defineCollection, defineWorkflow } from '@byline/core'
 
-import { availableLanguagesField } from '~/fields/available-languages-field.js'
 import { publishedOnField } from '~/fields/published-on-field.js'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -34,6 +33,7 @@ export const News = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
   fields: [
     { name: 'title', label: 'Title', type: 'text', localized: true },
@@ -82,7 +82,6 @@ export const News = defineCollection({
       embedRelationsOnSave: true, // See type definition for details.
     },
     publishedOnField,
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/collections/pages/admin.tsx

@@ -205,6 +205,6 @@ export const PagesAdmin: CollectionAdminConfig = defineAdmin(Pages, {
    */
   layout: {
     main: ['tabs'],
-    sidebar: ['publishedOn', 'availableLanguages'],
+    sidebar: ['publishedOn'],
   },
 })

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

@@ -11,7 +11,6 @@ import { defineCollection, defineWorkflow } from '@byline/core'
 
 import { PhotoBlock } from '~/blocks/photo-block'
 import { RichTextBlock } from '~/blocks/richtext-block'
-import { availableLanguagesField } from '~/fields/available-languages-field.js'
 import { publishedOnField } from '~/fields/published-on-field'
 
 // ---- Schema (server-safe, no UI concerns) ----
@@ -36,6 +35,7 @@ export const Pages = defineCollection({
   search: { fields: ['title'] },
   useAsTitle: 'title',
   useAsPath: 'title',
+  advertiseLocales: true, // Renders the available-locales sidebar widget.
   /**
    * Pages live at the site root (no `/pages/` prefix) and may be nested
    * under an `area` segment. Same composition rule used by the admin
@@ -100,7 +100,6 @@ export const Pages = defineCollection({
       blocks: [RichTextBlock, PhotoBlock],
     },
     publishedOnField,
-    availableLanguagesField(),
   ],
 })
 

package/dist/templates/byline-examples/fields/available-languages-field.ts

@@ -13,6 +13,13 @@
  * the only imports are `@byline/core` types and the i18n locale list.
  *
  * See `docs/FIELDS.md` for the schema-vs-admin model.
+ *
+ * @deprecated **No longer needed** as of the content-locale-resolution work.
+ * The editorial "advertise these locales" control is now a core *system
+ * attribute* + ledger-aware sidebar widget (`availableLocales`) — see
+ * `docs/AVAILABLE-LOCALES.md`. This userland custom field is **left in place as
+ * a reference example** of the schema-side field-builder pattern; it is not used
+ * by the system widget and can be removed from collection schemas.
  */
 
 import type { GroupField } from '@byline/core'

package/dist/templates/byline-examples/i18n.ts

@@ -39,9 +39,18 @@ export const i18n = {
   interface: {
     defaultLocale: 'en',
     locales: interfaceLocales.map((l) => l.code),
+    // Optional display names for the admin language switcher. Lets you
+    // author `Español` rather than the lowercase `español` that
+    // Intl.DisplayNames returns; omit to fall back to Intl per code.
+    localeDefinitions: interfaceLocales.map((l) => ({ code: l.code, nativeName: l.label })),
   },
   content: {
     defaultLocale: 'en',
     locales: contentLocales.map((l) => l.code),
+    // Optional display names for content locales. Byline doesn't render
+    // these (content has no admin switcher) — a public frontend can read
+    // them from getServerConfig().i18n.content.localeDefinitions to label
+    // hreflang / "read this in…" affordances without a parallel map.
+    localeDefinitions: contentLocales.map((l) => ({ code: l.code, nativeName: l.label })),
   },
 }

package/dist/templates/byline-examples/scripts/backfill-version-locales.ts

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+
+/**
+ * One-time maintenance: populate the version-locale availability ledger
+ * (`byline_document_version_locales`) for document versions written before
+ * the ledger existed. After this runs, `localeFallback: 'strict'` reads can
+ * see pre-existing documents; new writes keep the ledger current on their own
+ * (createDocumentVersion step 6).
+ *
+ * Idempotent — safe to re-run. Uses the installation's configured default
+ * content locale (resolved from byline/i18n.ts via the server config).
+ *
+ *   cd apps/webapp && pnpm tsx byline/scripts/backfill-version-locales.ts
+ *
+ * See docs/CONTENT-LOCALE-RESOLUTION.md.
+ */
+
+import '../load-env.js'
+import '../server.config.js'
+
+import { getServerConfig } from '@byline/core'
+import type { PgAdapter } from '@byline/db-postgres'
+
+async function run() {
+  // `backfillVersionLocales` is a Postgres-adapter housekeeping method (off
+  // the core `IDbAdapter` contract), so annotate the registered adapter as
+  // `PgAdapter` — the documented pattern for scripts that need raw handles.
+  const db = getServerConfig().db as PgAdapter
+  const { rowsInserted } = await db.backfillVersionLocales()
+  console.log(
+    `✓ version-locale ledger backfilled — ${rowsInserted} (version, locale) row(s) inserted`
+  )
+}
+
+run()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error('✗ version-locale backfill failed:', error)
+    process.exit(1)
+  })

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

@@ -8,10 +8,10 @@
 
 // Examples...
 //
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md --dry-run
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md --verbose
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts '../../docs/*.md' --dry-run --verbose
-// pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts ../../docs/**/*.md
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md --dry-run
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md --verbose
+// pnpm tsx byline/scripts/import-docs.ts '../../docs/*.md' --dry-run --verbose
+// pnpm tsx byline/scripts/import-docs.ts ../../docs/**/*.md
 //
 // Run tests...
 //
@@ -20,14 +20,17 @@
 /**
  * Import markdown files into the `docs` collection.
  *
- *   pnpm tsx --env-file=.env --env-file=.env.local byline/scripts/import-docs.ts <path-or-glob...>
+ *   pnpm tsx byline/scripts/import-docs.ts <path-or-glob...>
  *
  * 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.
- *   3. Convert mdast → Lexical SerializedEditorState.
- *   4. Resolve `featureImage` (a `media` path) to a relation envelope.
- *   5. `findByPath` to decide create vs update. On update, status and
+ *   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.
+ *   4. Convert mdast → Lexical SerializedEditorState.
+ *   5. Resolve `featureImage` (a `media` path) to a relation envelope.
+ *   6. `findByPath` to decide create vs update. On update, status and
  *      publishedOn are preserved — editorial state in Byline wins.
  *
  * Flags:
@@ -44,7 +47,7 @@ import { resolve } from 'node:path'
 
 import { createSuperAdminContext } from '@byline/auth'
 import { type CollectionHandle, createBylineClient } from '@byline/client'
-import { getServerConfig, slugify } from '@byline/core'
+import { getCollectionDefinition, getServerConfig, slugify } from '@byline/core'
 import type { Root } from 'mdast'
 import remarkGfm from 'remark-gfm'
 import remarkParse from 'remark-parse'
@@ -52,10 +55,13 @@ import { unified } from 'unified'
 
 import { type DocFrontmatter, parseDocFile } from './lib/frontmatter.js'
 import { type MdastToLexicalWarning, mdastToLexical } from './lib/mdast-to-lexical.js'
+import { type DocLinkRewriteWarning, rewriteDocLinks } from './lib/rewrite-doc-links.js'
 import { stripLeadingH1IfMatches } from './lib/strip-leading-h1.js'
 
 const DOCS_COLLECTION = 'docs'
 const MEDIA_COLLECTION = 'media'
+const DOCS_URL_PREFIX = '/docs'
+const DEFAULT_IMPORT_STATUS = 'published'
 
 interface Flags {
   dryRun: boolean
@@ -101,6 +107,20 @@ function logWarnings(filePath: string, warnings: MdastToLexicalWarning[]): void
   }
 }
 
+function logLinkWarnings(filePath: string, warnings: DocLinkRewriteWarning[]): void {
+  if (warnings.length === 0) return
+  console.warn(`  - ${warnings.length} link rewrite(s) for ${filePath}:`)
+  for (const w of warnings) {
+    if (w.kind === 'rewritten-doc-link') {
+      console.warn(`      [rewrite]    ${w.href} → ${w.resolvedTo}`)
+    } else if (w.kind === 'unresolved-doc-link') {
+      console.warn(`      [unresolved] ${w.href}  (stripped to plain text)`)
+    } else {
+      console.warn(`      [empty]      '${w.href}'  (stripped to plain text)`)
+    }
+  }
+}
+
 interface ResolvedFeatureImage {
   targetCollectionId: string
   targetDocumentId: string
@@ -123,14 +143,12 @@ interface BuildPayloadArgs {
   frontmatter: DocFrontmatter
   lexicalState: unknown
   featureImage: ResolvedFeatureImage | null
-  locale: string
 }
 
 function buildDocPayload({
   frontmatter,
   lexicalState,
   featureImage,
-  locale,
 }: BuildPayloadArgs): Record<string, unknown> {
   const payload: Record<string, unknown> = {
     title: frontmatter.title,
@@ -141,11 +159,6 @@ function buildDocPayload({
         constrainedWidth: frontmatter.constrainedWidth ?? true,
       },
     ],
-    // The `availableLanguages` field's built-in validator requires at
-    // least one checked locale; without it, opening the imported doc
-    // in the admin surfaces a validation error before any save. Seed
-    // the authoring locale so editors land on a valid form.
-    availableLanguages: { [locale]: true },
   }
   if (frontmatter.summary !== undefined) payload.summary = frontmatter.summary
   if (frontmatter.publishedOn !== undefined) payload.publishedOn = frontmatter.publishedOn
@@ -158,6 +171,27 @@ function derivePath(frontmatter: DocFrontmatter, locale: string): string {
   return slugify(frontmatter.title, { locale, collectionPath: DOCS_COLLECTION })
 }
 
+/**
+ * Walk a document's status forward to `targetStatus`. The workflow only
+ * permits ±1 step transitions, so jumping draft → published has to step
+ * through any intermediate statuses (e.g. needs_review). No-op when the
+ * workflow doesn't include the target or when already at/past it.
+ */
+async function walkToStatus(
+  handle: CollectionHandle,
+  documentId: string,
+  workflowStatuses: readonly { name: string }[],
+  currentStatus: string,
+  targetStatus: string
+): Promise<void> {
+  const currentIdx = workflowStatuses.findIndex((s) => s.name === currentStatus)
+  const targetIdx = workflowStatuses.findIndex((s) => s.name === targetStatus)
+  if (currentIdx === -1 || targetIdx === -1 || targetIdx <= currentIdx) return
+  for (let i = currentIdx + 1; i <= targetIdx; i++) {
+    await handle.changeStatus(documentId, workflowStatuses[i].name)
+  }
+}
+
 interface ProcessResult {
   filePath: string
   action: 'created' | 'updated' | 'skipped'
@@ -165,17 +199,45 @@ interface ProcessResult {
   path: string
 }
 
+/**
+ * Build a map of absolute markdown source paths → imported doc paths,
+ * by reading just the frontmatter of every file in the batch. Needed so
+ * the link-rewrite step in pass 2 can resolve `./SIBLING.md` to the URL
+ * its target will be served at after import.
+ */
+function buildSourcePathMap(files: string[], defaultLocale: string): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const file of files) {
+    try {
+      const source = readFileSync(file, 'utf8')
+      const parsed = parseDocFile(source, file)
+      const locale = parsed.frontmatter.locale ?? defaultLocale
+      map.set(file, derivePath(parsed.frontmatter, locale))
+    } catch {
+      // Skip — pass 2 will surface the parse error against this file.
+    }
+  }
+  return map
+}
+
 async function processFile(
   filePath: string,
   client: ReturnType<typeof createBylineClient>,
   handle: CollectionHandle,
-  flags: Flags
+  flags: Flags,
+  pathMap: Map<string, string>
 ): Promise<ProcessResult> {
   const source = readFileSync(filePath, 'utf8')
   const parsed = parseDocFile(source, filePath)
   const locale = parsed.frontmatter.locale ?? client.defaultLocale
 
   const mdast = stripLeadingH1IfMatches(parseBodyToMdast(parsed.body), parsed.frontmatter.title)
+  const linkWarnings = rewriteDocLinks(mdast, {
+    sourceFilePath: filePath,
+    pathMap,
+    urlPrefix: DOCS_URL_PREFIX,
+  })
+  if (flags.verbose) logLinkWarnings(filePath, linkWarnings)
   const { state, warnings } = mdastToLexical(mdast)
   if (flags.verbose) logWarnings(filePath, warnings)
 
@@ -193,7 +255,6 @@ async function processFile(
     frontmatter: parsed.frontmatter,
     lexicalState: state,
     featureImage,
-    locale,
   })
 
   if (flags.dryRun) {
@@ -201,6 +262,15 @@ async function processFile(
     return { filePath, action: 'skipped', path: docPath }
   }
 
+  // Re-imports default to the published status (overridable per-file via
+  // frontmatter `status:`). `update` always resets to the workflow's
+  // default status on a new version, so we walk transitions forward
+  // afterwards; `create` accepts an initial status directly.
+  const desiredStatus = parsed.frontmatter.status ?? DEFAULT_IMPORT_STATUS
+  const definition = getCollectionDefinition(DOCS_COLLECTION)
+  const workflowStatuses = definition?.workflow?.statuses ?? []
+  const defaultStatus = workflowStatuses[0]?.name ?? 'draft'
+
   const existing = await handle.findByPath(docPath, {
     locale,
     status: 'any',
@@ -208,19 +278,29 @@ async function processFile(
   })
 
   if (existing) {
-    // Editorial state wins on re-import: don't overwrite status, and
-    // don't clobber publishedOn if Byline already has one.
+    // Don't clobber publishedOn if Byline already has one.
     if (existing.fields?.publishedOn) {
       delete payload.publishedOn
     }
-    const result = await handle.update(existing.id, payload, { locale })
+    const result = await handle.update(existing.id, payload, {
+      locale,
+      // Advertise the imported locale (editorial available-locales set), merged
+      // with whatever is already advertised so a later-locale re-import doesn't
+      // clobber an earlier one. The public set is still gated by the version
+      // completeness ledger (intersection). See docs/AVAILABLE-LOCALES.md.
+      availableLocales: [...new Set([...(existing.availableLocales ?? []), locale])],
+    })
+    await walkToStatus(handle, result.documentId, workflowStatuses, defaultStatus, desiredStatus)
     return { filePath, action: 'updated', documentId: result.documentId, path: docPath }
   }
 
   const result = await handle.create(payload, {
     locale,
-    status: parsed.frontmatter.status,
+    status: desiredStatus,
     path: docPath,
+    // Advertise the authoring locale; the public advertised set is the
+    // intersection of this editorial set with the completeness ledger.
+    availableLocales: [locale],
   })
   return { filePath, action: 'created', documentId: result.documentId, path: docPath }
 }
@@ -240,6 +320,10 @@ async function run(): Promise<void> {
   const client = createBylineClient({ config, requestContext })
   const handle = client.collection(DOCS_COLLECTION)
 
+  // Pre-pass: map each source file to the path its imported doc will
+  // live at, so pass 2 can rewrite cross-doc markdown links.
+  const pathMap = buildSourcePathMap(files, client.defaultLocale)
+
   let created = 0
   let updated = 0
   let skipped = 0
@@ -247,7 +331,7 @@ async function run(): Promise<void> {
 
   for (const file of files) {
     try {
-      const result = await processFile(file, client, handle, flags)
+      const result = await processFile(file, client, handle, flags, pathMap)
       if (result.action === 'created') created += 1
       else if (result.action === 'updated') updated += 1
       else skipped += 1