@byline/cli 3.21.0 → 4.1.0

package/dist/runner.js

@@ -57,7 +57,7 @@ function previewPlan(phase, plan, ctx) {
         ctx.logger.raw(`    • ${note}`);
     for (const w of plan.writes) {
         const before = w.before ?? readIfExists(w.path);
-        const label = before ? 'modify' : 'create';
+        const label = w.mode === 'delete' ? 'delete' : before ? 'modify' : 'create';
         ctx.logger.raw(`    ${label}  ${w.path}`);
         if (before !== w.contents) {
             ctx.logger.raw(renderDiff(w.path, before, w.contents));

package/dist/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/templates/byline/collection-types.contract.ts

@@ -1,10 +1,35 @@
+/**
+ * Compile-time contract between this application's collection schemas and its
+ * generated collection-type projection.
+ *
+ * ```text
+ * collections/index.ts                  generated/collection-types.ts
+ *   `typeof collections`                 `CollectionFields*ByPath`
+ *            |                                      |
+ *            v                                      v
+ *    inferred registry ----------- Exact -------- generated registry
+ *                                    |
+ *                                    v
+ *                         TypeScript error on drift
+ * ```
+ *
+ * The generated file is deliberately a standalone projection for typed clients
+ * and frontend code; it does not import the runtime schemas. This module joins
+ * those two app-owned sources at compile time and requires their collection
+ * keys, ordinary field shapes, and all-locale field shapes to match exactly.
+ *
+ * This file has no runtime behavior. Keep it application-owned: `@byline/core`
+ * provides the inference and code-generation machinery, but only this
+ * application knows its concrete collection tuple and generated output.
+ */
+
 import type { CollectionFieldData, CollectionFieldDataAllLocales } from '@byline/core'
 
 import type { collections } from './collections/index.js'
 import type {
   CollectionFieldsAllLocalesByPath,
   CollectionFieldsByPath,
-} from './generated/collection-types.js'
+} from '@byline/generated-types'
 
 type InferredFieldsByPath = {
   [Definition in (typeof collections)[number] as Definition['path']]: CollectionFieldData<Definition>

package/dist/templates/byline/collections/index.ts

@@ -8,7 +8,7 @@
 
 import type { InferCollectionRegistry } from '@byline/core'
 
-import type { CollectionFieldsByPath } from '../generated/collection-types.js'
+import type { CollectionFieldsByPath } from '@byline/generated-types'
 
 /** Add schema-only collection imports here; keep admin presentation separate. */
 export const collections = [] as const

package/dist/templates/byline/collections/server-hooks.ts

@@ -0,0 +1,7 @@
+/** Server-only lifecycle hook registry. Imported only by server.config.ts. */
+import type { ServerHooksConfig } from '@byline/core'
+
+export const serverHooks = {
+  collections: {},
+  uploads: {},
+} satisfies ServerHooksConfig

package/dist/templates/byline/generated/collection-types.ts

@@ -1,11 +1,19 @@
 // Generated by @byline/core/codegen
-// Format version: 1
-// Hash: 4ef42b796dc35fceb394f97eaef885c5795c52031ba91f9ca6ca7e0fd2f20608
+// Format version: 2
+// Hash: 32dbd34eba8597c598229b7b278d5c1ef1bebb005b57986331bc2f393c49e673
 
-export type CollectionFieldsByPath = {
-}
+declare module '@byline/generated-types' {
+  export type CollectionFieldsByPath = {
+  }
+
+  export type CollectionFieldsAllLocalesByPath = {
+  }
 
-export type CollectionFieldsAllLocalesByPath = {
+  export type CollectionPath = keyof CollectionFieldsByPath
 }
 
-export type CollectionPath = keyof CollectionFieldsByPath
+declare module '@byline/client' {
+  interface Register {
+    collections: import('@byline/generated-types').CollectionFieldsByPath
+  }
+}

package/dist/templates/byline/routes.ts

@@ -7,17 +7,18 @@
  */
 
 /**
- * URL segments for admin and (future) public API routes. Defaults of
- * `/admin` and `/api` are applied automatically by `resolveRoutes()` —
- * keys only need to be set here when overriding either default.
+ * Client-safe URL paths for admin, sign-in, and the future public API.
+ * Resolve once at this client-safe configuration boundary so consumers only
+ * read canonical paths.
  */
 
-import type { RoutesConfig } from '@byline/core'
+import { resolveRoutes } from '@byline/core'
 
-export const routes: Partial<RoutesConfig> = {
+export const routes = resolveRoutes({
   admin: '/admin',
   api: '/api',
-}
+  signIn: '/sign-in',
+})
 
 /**
  * Fallback used by both server and admin entry points when no

package/dist/templates/byline/server.config.ts

@@ -29,8 +29,10 @@ import {
 } from '@byline/richtext-lexical/server'
 import { localStorageProvider } from '@byline/storage-local'
 
-import { getAdminBylineClient } from './client.server.js'
+import { getAdminBylineClient } from '@byline/client/server'
+import { registerTanstackStartHostBridge } from '@byline/host-tanstack-start/integrations/host-bridge'
 import { collections } from './collections/index.js'
+import { serverHooks } from './collections/server-hooks.js'
 import { i18n } from './i18n.js'
 import { DEFAULT_SERVER_URL, routes } from './routes.js'
 
@@ -86,11 +88,18 @@ async function buildBylineCore(): Promise<BylineCore<AdminStore>> {
     signingSecret,
   })
 
+  // Register the TanStack Start `HostRequestBridge` before any
+  // request-bound client getter (`@byline/client/server`) can run —
+  // structural at server boot rather than dependent on which host
+  // module happens to load first.
+  registerTanstackStartHostBridge()
+
   const core = await initBylineCore<AdminStore>({
     serverURL,
     i18n,
     routes,
     collections,
+    hooks: serverHooks,
     db,
     adminStore,
     // Local filesystem — suitable for development and self-hosted

package/dist/templates/byline-examples/admin.config.ts

@@ -14,8 +14,8 @@
  * `route.lazy.tsx` covers component render and initial hydration. Keeping
  * both imports behind `_byline/*` keeps the admin graph off public routes.
  *
- * In TanStack Start with Vite 6 the server entry (`src/server.ts`) and
- * the SSR rendering context run in separate Vite environments, so
+ * In TanStack Start the server entry (`src/server.ts`) and the SSR rendering
+ * context run in separate Vite environments, so
  * importing this file from `src/server.ts` would NOT propagate the
  * registration into the SSR render module graph.
  */
@@ -29,8 +29,8 @@ import { RichTextField as LexicalRichTextField } from '@byline/richtext-lexical'
 // commented `richText` block below for the exact shape.
 // import { lexicalEditor } from '@byline/richtext-lexical'
 
-import { collections } from './collections/index.js'
 import { DocsAdmin } from './collections/docs/admin.js'
+import { collections } from './collections/index.js'
 import { MediaAdmin } from './collections/media/admin.js'
 import { NewsAdmin } from './collections/news/admin.js'
 import { NewsCategoriesAdmin } from './collections/news-categories/admin.js'
@@ -60,19 +60,14 @@ export const config: ClientConfig = {
     // mutations are local to this call. Per-field `editorConfig`
     // continues to take precedence over whatever is baked in here.
     //
-    // import {
-    //   lexicalEditor,
-    //   AdmonitionExtension,
-    //   CodeHighlightExtension,
-    //   TableExtension,
-    // } from '@byline/richtext-lexical'
+    // import { builtInExtensions, lexicalEditor } from '@byline/richtext-lexical/config'
     //
     // richText: {
     //   editor: lexicalEditor((c) => {
     //     c.extensions
-    //       .remove(TableExtension)
-    //       .remove(CodeHighlightExtension)
-    //       .remove(AdmonitionExtension)
+    //       .remove(builtInExtensions.Table)
+    //       .remove(builtInExtensions.CodeHighlight)
+    //       .remove(builtInExtensions.Admonition)
     //     c.settings.placeholderText = 'Start writing...'
     //     return c
     //   }),

package/dist/templates/byline-examples/blocks/photo-block.ts

@@ -53,7 +53,8 @@ export type PhotoBlockFields = BlockFieldData<typeof PhotoBlock>
 
 /**
  * Full block instance shape (`_id`, `_type` + fields) as it appears
- * inside a document tree. Use this as the prop type for the photo
- * block renderer.
+ * inside a document tree. This alias is useful for schema-local helpers;
+ * app-facing renderers should import `PhotoBlockData` from
+ * `byline/generated/collection-types.ts` and overlay populated relations.
  */
 export type PhotoBlockData = BlockData<typeof PhotoBlock>

package/dist/templates/byline-examples/collection-types.contract.ts

@@ -1,10 +1,35 @@
+/**
+ * Compile-time contract between this application's collection schemas and its
+ * generated collection-type projection.
+ *
+ * ```text
+ * collections/index.ts                  generated/collection-types.ts
+ *   `typeof collections`                 `CollectionFields*ByPath`
+ *            |                                      |
+ *            v                                      v
+ *    inferred registry ----------- Exact -------- generated registry
+ *                                    |
+ *                                    v
+ *                         TypeScript error on drift
+ * ```
+ *
+ * The generated file is deliberately a standalone projection for typed clients
+ * and frontend code; it does not import the runtime schemas. This module joins
+ * those two app-owned sources at compile time and requires their collection
+ * keys, ordinary field shapes, and all-locale field shapes to match exactly.
+ *
+ * This file has no runtime behavior. Keep it application-owned: `@byline/core`
+ * provides the inference and code-generation machinery, but only this
+ * application knows its concrete collection tuple and generated output.
+ */
+
 import type { CollectionFieldData, CollectionFieldDataAllLocales } from '@byline/core'
 
 import type { collections } from './collections/index.js'
 import type {
   CollectionFieldsAllLocalesByPath,
   CollectionFieldsByPath,
-} from './generated/collection-types.js'
+} from '@byline/generated-types'
 
 type InferredFieldsByPath = {
   [Definition in (typeof collections)[number] as Definition['path']]: CollectionFieldData<Definition>

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

@@ -18,21 +18,19 @@
  * the client. Hook *bodies*, however, only ever run server-side.
  *
  * Search indexing is the canonical reason this matters: it imports the
- * server-only app client boundary from `byline/client.server.ts`. Importing
+ * server-only client getters from `@byline/client/server`. Importing
  * that from the schema would drag server code into the browser bundle (fatal
- * in dev). The schema avoids it by referencing these hooks through a
- * **dynamic import** instead of an inline object:
+ * in dev). The server bootstrap avoids it by registering these hooks from a
+ * server-only module:
  *
- *     // schema.ts
- *     hooks: () => import('./hooks.js')
+ *     // collections/server-hooks.ts
+ *     collections: { docs: () => import('./docs/hooks.js') }
  *
- * Because the schema reaches this module only through `import()`, this file —
- * and its entire transitive import graph — is **structurally absent** from
- * the client bundle. `@byline/core` resolves the loader once on the server
- * (memoized) and calls these hooks exactly as it would inline ones. The
- * upshot: **inside this file we may statically import server-only modules
- * directly.** See docs/04-collections → "Hooks must not statically import
- * server-only code".
+ * No client entry reaches that registry, so this file and its transitive graph
+ * are structurally absent from the client bundle without a host-framework
+ * transform. `@byline/core` attaches and resolves the loader on the server.
+ * The upshot: **inside this file we may statically import server-only modules
+ * directly.** See docs/04-collections → "Server-only hook registry".
  *
  * ──────────────────────────────────────────────────────────────────────────
  *  Search indexing
@@ -52,7 +50,7 @@
  */
 
 import { defineHooks } from '@byline/core'
-import { getSystemBylineClient } from '../../client.server.js'
+import { getSystemBylineClient } from '@byline/client/server'
 
 export default defineHooks({
   beforeCreate: async ({ data, collectionPath }) => {
@@ -73,6 +71,18 @@ export default defineHooks({
     )
     await getSystemBylineClient().collection('docs').indexDocument(documentId)
   },
+  // Path and advertised-locale edits are immediate document-grain writes, not
+  // content updates. Re-index their published view through this dedicated event.
+  afterSystemFieldsChange: async ({ documentId, collectionPath, requested, changed }) => {
+    console.log(
+      `afterSystemFieldsChange: ${documentId} in '${collectionPath}' changed`,
+      changed
+    )
+    // Advertised locales affect alternates/sitemaps, not indexed content.
+    if (requested.path) {
+      await getSystemBylineClient().collection('docs').indexDocument(documentId)
+    }
+  },
   beforeStatusChange: async ({ documentId, collectionPath, previousStatus, nextStatus }) => {
     console.log(
       `beforeStatusChange: ${documentId} in '${collectionPath}' ${previousStatus} → ${nextStatus}`

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

@@ -65,17 +65,8 @@ export const Docs = defineCollection({
   useAsPath: 'title',
   advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
-  // Collection lifecycle hooks. Hook *bodies* only ever run server-side, but
-  // a collection *schema* is isomorphic — Byline bundles it into the browser
-  // admin too (the admin reads field config from it), so anything the schema
-  // *statically imports* ships to the client. Search indexing needs a
-  // server-only import from the app's `client.server.ts` boundary, which would
-  // crash the browser bundle if imported here. The **loader form** — a thunk
-  // that dynamically imports a sibling module — keeps `./hooks.ts` and its
-  // entire import graph out of the client bundle while running exactly like
-  // inline hooks on the server.
-  // See ./hooks.ts for the worked example and the full explanation.
-  hooks: () => import('./hooks.js'),
+  // Server-only lifecycle hooks are registered in ../server-hooks.ts so this
+  // schema remains portable across host frameworks and safe in client graphs.
   fields: [
     {
       name: 'title',

package/dist/templates/byline-examples/collections/index.ts

@@ -8,7 +8,7 @@
 
 import type { InferCollectionRegistry } from '@byline/core'
 
-import type { CollectionFieldsByPath } from '../generated/collection-types.js'
+import type { CollectionFieldsByPath } from '@byline/generated-types'
 
 import { Docs } from './docs/schema.js'
 import { Media } from './media/schema.js'

package/dist/templates/byline-examples/collections/media/components/media-list-view.tsx

@@ -19,11 +19,16 @@
  *  - Top + bottom pagination (RouterPager)
  */
 
-import { Link, useNavigate, useRouterState } from '@tanstack/react-router'
+import { useRouterState } from '@tanstack/react-router'
 
 import type { ListViewComponentProps, StoredFileValue, WorkflowStatus } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import { RouterPager } from '@byline/host-tanstack-start/admin-shell/chrome/router-pager'
+import {
+  Link,
+  useNavigate,
+} from '@byline/host-tanstack-start/admin-shell/chrome/loose-router'
+import { getAdminRoutePath } from '@byline/host-tanstack-start/routes/admin-path'
 import { Container, IconButton, LoaderRing, PlusIcon, Search, Section, Select } from '@byline/ui/react'
 import { LocalDateTime } from '@byline/admin/react'
 
@@ -128,7 +133,7 @@ export function MediaListView({
       delete params.page
       params.query = query
       navigate({
-        to: '/admin/collections/$collection',
+        to: getAdminRoutePath('collections', '$collection'),
         params: { collection: collectionPath },
         search: params,
       })
@@ -140,7 +145,7 @@ export function MediaListView({
     delete params.page
     delete params.query
     navigate({
-      to: '/admin/collections/$collection',
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: collectionPath },
       search: params,
     })
@@ -158,7 +163,7 @@ export function MediaListView({
     params.order = order
     params.desc = desc
     navigate({
-      to: '/admin/collections/$collection',
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: collectionPath },
       search: params,
     })
@@ -178,7 +183,7 @@ export function MediaListView({
             render={
               <Link
                 className={styles['create-link']}
-                to="/admin/collections/$collection/create"
+                to={getAdminRoutePath('collections', '$collection', 'create')}
                 params={{ collection: collectionPath }}
               />
             }
@@ -239,7 +244,7 @@ export function MediaListView({
               return (
                 <Link
                   key={doc.id}
-                  to="/admin/collections/$collection/$id"
+                  to={getAdminRoutePath('collections', '$collection', '$id')}
                   params={{ collection: collectionPath, id: doc.id }}
                   className={styles.card}
                 >

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

@@ -128,6 +128,9 @@ export const Media = defineCollection({
             quality: 55,
           },
         ],
+        // Worked example: definition-attached inline hooks are appropriate
+        // when their entire implementation is isomorphic-safe. Hooks that
+        // import server-only code belong in collections/server-hooks.ts.
         hooks: {
           beforeStore: (ctx: BeforeStoreContext) => {
             console.log('beforeStore hook called', ctx)

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

@@ -99,8 +99,9 @@ export const News = defineCollection({
 })
 
 /**
- * Field data shape inferred directly from the schema. Use this as the
- * generic to typed read calls — `client.collection('news').find<NewsFields>()`
- * — so dot-notation on `doc.fields` is fully checked.
+ * Schema-local field shape for hooks and other collection implementation details.
+ * Frontend/client code should import `NewsFields` from
+ * `byline/generated/collection-types.ts`; ordinary reads infer it from the
+ * client registry, while populate/select projections may supply an overlay.
  */
 export type NewsFields = CollectionFieldData<typeof News>

package/dist/templates/byline-examples/collections/server-hooks.ts

@@ -0,0 +1,8 @@
+/** Server-only lifecycle hook registry. Imported only by server.config.ts. */
+import type { ServerHooksConfig } from '@byline/core'
+
+export const serverHooks = {
+  collections: {
+    docs: () => import('./docs/hooks.js'),
+  },
+} satisfies ServerHooksConfig

package/dist/templates/byline-examples/fields/ai-text.ts

@@ -27,7 +27,7 @@ import { AiFieldPanel } from './ai-widgets/ai-field-panel.js'
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * fields: {
  *   title: aiTextFieldAdmin(),
  * }

package/dist/templates/byline-examples/fields/ai-textarea.ts

@@ -28,7 +28,7 @@ import { AiFieldPanel } from './ai-widgets/ai-field-panel.js'
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * fields: {
  *   summary: aiTextAreaFieldAdmin({
  *     components: { HelpText: SummaryLength },

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

@@ -13,7 +13,7 @@
  *   - `LexicalRichTextAi` — a `RichTextEditorComponent` that registers
  *     the AI assistant by adding `AiLexicalExtension` to the editor's
  *     extension graph. Register globally in
- *     `apps/webapp/byline/admin.config.ts` under
+ *     `byline/admin.config.ts` under
  *     `fields.richText.editor` to AI-enable every richtext field.
  *   - `aiRichTextAdmin()` — a `FieldAdminConfig` factory. Drop into a
  *     collection's `fields` map in `<collection>/admin.tsx` to opt one
@@ -38,7 +38,7 @@ import { builtInExtensions, lexicalEditor } from '@byline/richtext-lexical/confi
  * drawer via `ReactExtension.decorators` — no `featureAfterEditor`, no
  * React-context registry hop.
  *
- * **Global** opt-in — register in `apps/webapp/byline/admin.config.ts`:
+ * **Global** opt-in — register in `byline/admin.config.ts`:
  *
  * ```ts
  * fields: {
@@ -77,7 +77,7 @@ export const LexicalRichTextAi = lexicalEditor((c) => {
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * import { aiRichTextAdmin } from '../../fields/lexical-richtext-ai.js'
  *
  * fields: {