@byline/cli 0.1.1

package/dist/templates/byline-examples/seeds/docs.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 { getCollectionDefinition, getDefaultStatus, getServerConfig, slugify } from '@byline/core'
+
+// Complex test document with many fields and arrays. The system `path`
+// is supplied separately to `createDocumentVersion` as a top-level
+// argument — it is no longer a user-defined field.
+const sampleDocument = {
+  title: {
+    en: 'My First Document',
+    es: 'Mi Primer Documento',
+  },
+  summary: {
+    en: 'This is a sample document for testing purposes.',
+    es: 'Este es un documento de muestra para fines de prueba.',
+  },
+  // category: {
+  //   targetCollectionId: "cat-123",
+  //   targetDocumentId: "electronics-audio"
+  // },
+  featured: false,
+  publishedOn: new Date('2024-01-15T10:00:00'),
+  content: [
+    {
+      _type: 'richTextBlock',
+      richText: {
+        en: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Some richtext here...',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+        es: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Aquí hay un campo de texto enriquecido...',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+      },
+      constrainedWidth: true,
+    },
+    {
+      _type: 'photoBlock',
+      display: 'wide',
+      alt: 'Some alt text here',
+      caption: {
+        en: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Here is a richtext field Here is a richtext field Here is a richtext field Here is a rich text field.',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+        es: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Aquí hay un campo de texto enriquecido. Aquí hay un campo de texto enriquecido. Aquí hay un campo de texto enriquecido. Aquí hay un campo de texto enriquecido.',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+      },
+    },
+  ],
+  reviews: [
+    {
+      reviewItem: {
+        rating: 5,
+        comment: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Some review text here...',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+      },
+    },
+    {
+      reviewItem: {
+        rating: 3,
+        comment: {
+          root: {
+            children: [
+              {
+                children: [
+                  {
+                    detail: 0,
+                    format: 0,
+                    mode: 'normal',
+                    style: '',
+                    text: 'Some review text here...',
+                    type: 'text',
+                    version: 1,
+                  },
+                ],
+                direction: 'ltr',
+                format: '',
+                indent: 0,
+                type: 'paragraph',
+                version: 1,
+                textFormat: 0,
+                textStyle: '',
+              },
+            ],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            type: 'root',
+            version: 1,
+          },
+        },
+      },
+    },
+  ],
+  links: [{ link: 'https://example.com' }, { link: 'https://another-example.com' }],
+}
+
+export async function seedDocs(count = 1000) {
+  const db = getServerConfig().db
+
+  const collectionDefinition = getCollectionDefinition('docs')
+
+  if (!collectionDefinition) {
+    console.error('Collection definition not found for "docs"')
+    return
+  }
+
+  // `initBylineCore` already registered the collection row via
+  // `ensureCollections()` when byline/server.config was imported, so we
+  // look the row up rather than re-inserting (which would violate the
+  // unique-path constraint).
+  const existing = await db.queries.collections.getCollectionByPath('docs')
+  if (!existing) {
+    throw new Error(
+      "seedDocuments: expected the 'docs' collection to be registered by initBylineCore()"
+    )
+  }
+
+  const bulkDocsCollection = {
+    id: existing.id as string,
+    name: existing.path as string,
+    version: (existing.version as number | undefined) ?? 1,
+  }
+
+  console.log(`Seeding into Docs collection (${bulkDocsCollection.name})`)
+
+  for (let i = 0; i < count; i++) {
+    const docData = structuredClone(sampleDocument)
+    docData.title.en = `A bulk created document. ${i + 1}` // Ensure unique names
+    const seedPath = slugify(docData.title.en, {
+      locale: 'en',
+      collectionPath: 'docs',
+    })
+    await db.commands.documents.createDocumentVersion({
+      collectionId: bulkDocsCollection.id,
+      collectionVersion: bulkDocsCollection.version,
+      collectionConfig: collectionDefinition,
+      action: 'create',
+      documentData: docData,
+      path: seedPath,
+      status: getDefaultStatus(collectionDefinition),
+    })
+  }
+
+  console.log(`  - seeded ${count} docs`)
+}

package/dist/templates/byline-examples/seeds/news-categories.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { getCollectionDefinition, getDefaultStatus, getServerConfig, slugify } from '@byline/core'
+
+const categories = [
+  {
+    name: { en: 'Local' },
+    description: { en: 'Hyper-local news.' },
+  },
+  {
+    name: { en: 'Regional' },
+    description: { en: 'News and updates from the surrounding region.' },
+  },
+  {
+    name: { en: 'World' },
+    description: { en: 'International news and updates.' },
+  },
+]
+
+export async function seedNewsCategories() {
+  const db = getServerConfig().db
+
+  const collectionDefinition = getCollectionDefinition('news-categories')
+
+  if (!collectionDefinition) {
+    console.error('Collection definition not found for "news-categories"')
+    return
+  }
+
+  // `initBylineCore` already registered the collection row via
+  // `ensureCollections()` when byline/server.config was imported, so we
+  // look the row up rather than re-inserting (which would violate the
+  // unique-path constraint).
+  const existing = await db.queries.collections.getCollectionByPath('news-categories')
+  if (!existing) {
+    throw new Error(
+      "seedNewsCategories: expected the 'news-categories' collection to be registered by initBylineCore()"
+    )
+  }
+
+  const categoriesCollection = {
+    id: existing.id as string,
+    name: existing.path as string,
+    version: (existing.version as number | undefined) ?? 1,
+  }
+
+  console.log(`Seeding into News Categories collection (${categoriesCollection.name})`)
+
+  for (const category of categories) {
+    const seedPath = slugify(category.name.en, {
+      locale: 'en',
+      collectionPath: 'news-categories',
+    })
+    await db.commands.documents.createDocumentVersion({
+      collectionId: categoriesCollection.id,
+      collectionVersion: categoriesCollection.version,
+      collectionConfig: collectionDefinition,
+      action: 'create',
+      documentData: category,
+      path: seedPath,
+      status: getDefaultStatus(collectionDefinition),
+    })
+    console.log(`  - seeded category: ${category.name.en} (${seedPath})`)
+  }
+}

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

@@ -0,0 +1,179 @@
+/**
+ * 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
+ */
+
+/**
+ * Server-side Byline bootstrap. Imported as a side-effect from
+ * `src/server.ts` (and from any seed / migration script that needs the
+ * configured runtime). Resolves the composed `BylineCore` and registers
+ * it on the process global via `initBylineCore()` — server-side callers
+ * read it back with `getBylineCore<AdminStore>()`.
+ */
+
+import { type AdminStore, registerAdminAbilities } from '@byline/admin'
+import { JwtSessionProvider } from '@byline/admin/auth'
+import { type BylineCore, initBylineCore } from '@byline/core'
+import { pgAdapter } from '@byline/db-postgres'
+import { createAdminStore } from '@byline/db-postgres/admin'
+import { getAdminBylineClient } from '@byline/host-tanstack-start/integrations/byline-client'
+import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+import { localStorageProvider } from '@byline/storage-local'
+
+// Import collection definitions directly from schema files — NOT the full
+// admin config or index barrels. The admin config / index files pull in
+// admin UI configs (React components, CSS modules) that are not loadable
+// outside Vite (e.g. when running seeds via tsx).
+import { Docs } from './collections/docs/schema.js'
+import { DocsCategories } from './collections/docs-categories/schema.js'
+import { Media } from './collections/media/schema.js'
+import { News } from './collections/news/schema.js'
+import { NewsCategories } from './collections/news-categories/schema.js'
+import { Pages } from './collections/pages/schema.js'
+import { i18n } from './i18n.js'
+import { DEFAULT_SERVER_URL, routes } from './routes.js'
+
+const serverURL = process.env.VITE_SERVER_URL || DEFAULT_SERVER_URL
+
+const collections = [Docs, News, Pages, Media, DocsCategories, NewsCategories]
+
+// HMR-safe singleton. Vite's program reload re-evaluates this module
+// without disposing the previous module's resources — every reload
+// would otherwise allocate a fresh pg `Pool` (max: 20) inside
+// `pgAdapter`, the previous pool would orphan but stay alive, and
+// after a handful of HMR cycles Postgres' `max_connections` is
+// exhausted and every query fails with `53300 sorry, too many clients
+// already`. Stashing the resolving `Promise` (so concurrent reloads
+// converge on one build) lets module reloads reuse the same pool.
+// Production has no HMR so this guard is a no-op there.
+declare global {
+  // biome-ignore lint: globalThis augmentation requires `var` rather than `let`
+  var __bylineCoreSingleton__: Promise<BylineCore<AdminStore>> | undefined
+}
+
+async function buildBylineCore(): Promise<BylineCore<AdminStore>> {
+  // Construct the db adapter up-front so we can thread its drizzle handle
+  // into the session provider without a second connection pool. The admin
+  // store bundles the four admin repositories (users / roles / permissions
+  // / refresh tokens) that `JwtSessionProvider`, the admin-user server
+  // fns, and the super-admin seed all consume. Built once here and
+  // surfaced on `bylineCore.adminStore` so downstream callers talk to
+  // `AdminStore` — the interface — rather than casting the adapter.
+  //
+  // Future approaches, if/when the wiring grows:
+  //
+  //   Option B — Adapter-owned admin store. Have `pgAdapter()` return
+  //   `{ ..., adminStore }` directly so the integration point doesn't
+  //   need the separate `createAdminStore(db.drizzle)` call or the
+  //   `@byline/db-postgres/admin` import. Widens the adapter contract
+  //   slightly but removes one more concrete-adapter mention from this
+  //   file.
+  //
+  //   Option C — Full DI via `@byline/core`'s `Registry`. Register
+  //   `adminStore` as a typed factory keyed off `db`; adapters
+  //   contribute the factory, `initBylineCore()` composes it. Most
+  //   flexible (lazy construction, test wiring, multi-store setups) but
+  //   heavier until we have a second adapter or a second DI consumer
+  //   to justify the ceremony.
+  const db = pgAdapter({
+    connectionString: process.env.DB_CONNECTION_STRING || '',
+    collections,
+  })
+
+  const adminStore = createAdminStore(db.drizzle)
+
+  // Built-in JWT session provider. Signing secret comes from the
+  // environment — see `.env.example`. Phase 5 uses HS256 with Byline's
+  // default TTLs (15-minute access, 30-day refresh). Alternative providers
+  // (Lucia, better-auth, WorkOS, Clerk, institutional SSO) can be dropped
+  // in here by implementing the `SessionProvider` interface from
+  // `@byline/auth`.
+  const signingSecret = process.env.BYLINE_JWT_SECRET
+  if (!signingSecret || signingSecret.length < 32) {
+    throw new Error(
+      'BYLINE_JWT_SECRET must be set and carry at least 32 bytes of entropy. ' +
+        'Generate one with `openssl rand -base64 48` and add it to your .env.'
+    )
+  }
+
+  const sessionProvider = new JwtSessionProvider({
+    store: adminStore,
+    signingSecret,
+  })
+
+  const core = await initBylineCore<AdminStore>({
+    serverURL,
+    i18n,
+    routes,
+    collections,
+    db,
+    adminStore,
+    // Site-wide default storage provider — used by any upload collection
+    // that does not specify its own `upload.storage` override.
+    //
+    // To route a specific collection to a different backend, set `storage`
+    // inside that collection's `upload` config block instead of (or in
+    // addition to) this site-wide default.
+    //
+    // Local filesystem is suitable for development and self-hosted
+    // deployments. Swap for '@byline/storage-s3' (s3StorageProvider) for
+    // cloud/production. The `uploadDir` is served as a static path at
+    // `baseUrl` by your web server.
+    storage: localStorageProvider({
+      uploadDir: './public/uploads',
+      baseUrl: '/uploads',
+    }),
+    sessionProvider,
+    fields: {
+      // Server-side richtext adapter — refreshes embedded relation
+      // envelopes (link `{ title, path }`, inline-image `{ title, altText,
+      // image, sizes }`) on every read, gated per-field by
+      // `populateRelationsOnRead`. See docs/RICHTEXT.md for the full design.
+      //
+      // `getClient` returns a `BylineClient` — the SDK over the storage
+      // primitives that the populate visitors use to batch-fetch target
+      // documents (e.g. `client.collection('media').find({ where: { id:
+      // { $in: [...] } } })`). The client carries the DB adapter, the
+      // collection registry, the request-context resolver, and every
+      // read-pipeline phase (`beforeRead` → populate → `afterRead`), so
+      // populate's nested reads run under the *same* authenticated actor
+      // and the *same* `ReadContext` as the request that triggered them.
+      // That's what makes A→B→A cycle protection and visited-set dedup
+      // work across relation populate, richtext populate, and any user-
+      // land `afterRead` hooks.
+      //
+      // We pass `getAdminBylineClient` (not the public client) because
+      // admin server fns are the only call sites that read documents in
+      // the admin webapp today — the populate phase inherits whichever
+      // actor the request resolved. A future public-facing host would
+      // register its own client whose `requestContext` factory resolves
+      // an end-user actor instead. See `@byline/host-tanstack-start/
+      // integrations/byline-client.ts` for how the admin client is built.
+      //
+      // Why a getter, not a value: `getAdminBylineClient()` reads the
+      // server config singleton, which is only populated *after*
+      // `initBylineCore()` returns. Passing a factory defers resolution
+      // to populate-call time so registration order here doesn't matter.
+      richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+    },
+  })
+
+  // Register admin-subsystem abilities (admin.users.*, admin.roles.*) on
+  // the shared registry. Collection abilities are auto-registered by
+  // `initBylineCore()`; admin abilities are opt-in here so `@byline/core`
+  // does not depend on `@byline/admin`.
+  registerAdminAbilities(core.abilities)
+
+  return core
+}
+
+// Cache the *Promise*, not the resolved value, so concurrent module
+// loads during a reload race converge on a single build rather than
+// each starting their own. The top-level `await` surfaces init errors
+// at module load time; downstream callers retrieve the resolved core
+// via `getBylineCore<AdminStore>()` from `@byline/core`.
+globalThis.__bylineCoreSingleton__ ??= buildBylineCore()
+await globalThis.__bylineCoreSingleton__

package/dist/templates/host/vite.config.ts

@@ -0,0 +1,41 @@
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    port: 5173,
+  },
+  resolve: {
+    tsconfigPaths: true,
+  },
+  ssr: {
+    noExternal: ['@byline/ui'],
+    // Packages that load platform-specific native `.node` binaries at
+    // runtime via dynamic require(). Rollup cannot bundle these, so we
+    // keep them external and let Node.js resolve them from node_modules
+    // at runtime.
+    //   - sharp + @byline/storage-local — image processing
+    //   - @byline/db-postgres — adapter depends on pg native bindings
+    external: ['sharp', '@byline/storage-local', '@byline/admin', '@byline/db-postgres'],
+  },
+  // The same packages need to be kept out of Vite's client-side dep
+  // pre-bundling step. TanStack Start strips server-only imports from
+  // server-fn modules during its own compile pass, but Vite's
+  // `optimizeDeps` runs BEFORE that and tries to pre-bundle anything
+  // a client-reachable file imports — including transitive imports
+  // reached via `@byline/admin/admin-*` subpath barrels. Excluding the
+  // package roots here keeps Vite from touching them on the client side.
+  optimizeDeps: {
+    exclude: ['sharp', '@byline/storage-local', '@byline/admin', '@byline/db-postgres'],
+  },
+  plugins: [
+    tanstackStart(),
+    // NOTE: react() must come AFTER tanstackStart()
+    react(),
+    tailwindcss(),
+  ],
+  clearScreen: false,
+})