create-starlight-cms 0.9.0

package/template/src/navigation/service.ts

@@ -0,0 +1,171 @@
+import { folderDeliveryStatement, siteDeliveryStatement } from '../publish/record.ts';
+import { z } from 'zod';
+import { slug } from '../documents/validation.ts';
+import type { RuntimeEnv } from '../env.ts';
+import { defaultLocale, isSupportedLocale, type SupportedLocale } from '../locales.ts';
+
+const folderInput = z.object({ name: z.string().trim().min(1).max(120), slug, parentId: z.string().uuid().nullable().default(null), order: z.number().int().min(0).max(100000).default(0) });
+export class FolderNotFoundError extends Error {}
+export class NavigationConflictError extends Error {}
+export type PublicationState = 'draft' | 'changes' | 'published';
+export type TreeItem = {
+  id: string; parentId: string | null; kind: 'folder' | 'document'; name: string; slug: string; order: number;
+  hasTranslation: boolean; translationLocales: SupportedLocale[]; translationStates: { locale: SupportedLocale; state: PublicationState }[];
+  documentId?: string;
+};
+
+async function assertAvailable(env: RuntimeEnv, parentId: string | null, slugValue: string, ignoreFolder = '', ignoreDocument = '') {
+  const [folderMatch, documentMatch] = await Promise.all([
+    env.DB.prepare('SELECT id FROM folder WHERE parent_id IS ? AND slug=? AND id<>? LIMIT 1').bind(parentId, slugValue, ignoreFolder).first(),
+    env.DB.prepare('SELECT id FROM document WHERE folder_id IS ? AND slug=? AND id<>? LIMIT 1').bind(parentId, slugValue, ignoreDocument).first(),
+  ]);
+  if (folderMatch || documentMatch) throw new NavigationConflictError('A folder or page already uses this URL segment');
+}
+async function assertParentFolder(env: RuntimeEnv, parentId: string | null) {
+  if (!parentId) return;
+  if (!await env.DB.prepare('SELECT id FROM folder WHERE id=?').bind(parentId).first()) throw new NavigationConflictError('The destination folder no longer exists');
+}
+async function assertNoFolderCycle(env: RuntimeEnv, folderId: string, parentId: string | null) {
+  let cursor = parentId;
+  const seen = new Set<string>();
+  while (cursor) {
+    if (cursor === folderId || seen.has(cursor)) throw new NavigationConflictError('A folder cannot be moved into itself or one of its descendants');
+    seen.add(cursor);
+    const parent = await env.DB.prepare('SELECT parent_id FROM folder WHERE id=?').bind(cursor).first<{ parent_id: string | null }>();
+    if (!parent) throw new NavigationConflictError('The destination folder no longer exists');
+    cursor = parent.parent_id;
+  }
+}
+
+export async function listTree(env: RuntimeEnv, locale: SupportedLocale = defaultLocale): Promise<TreeItem[]> {
+  const [folders, documents, states] = await Promise.all([
+    env.DB.prepare("SELECT f.id,f.parent_id,COALESCE(t.name,fallback.name,f.slug) AS name,f.slug,f.sort_order,t.folder_id IS NOT NULL AS has_translation,(SELECT group_concat(locale, ',') FROM folder_translation WHERE folder_id=f.id) AS translation_locales FROM folder f LEFT JOIN folder_translation t ON t.folder_id=f.id AND t.locale=? LEFT JOIN folder_translation fallback ON fallback.folder_id=f.id AND fallback.locale=? WHERE EXISTS (SELECT 1 FROM folder_translation WHERE folder_id=f.id) ORDER BY f.sort_order,f.slug").bind(locale, defaultLocale).all<{ id:string; parent_id:string|null; name:string; slug:string; sort_order:number; has_translation:number; translation_locales:string|null }>(),
+    env.DB.prepare("SELECT d.id,d.folder_id,COALESCE(t.title,fallback.title,d.slug) AS title,d.slug,d.sort_order,t.document_id IS NOT NULL AS has_translation,(SELECT group_concat(locale, ',') FROM document_translation WHERE document_id=d.id) AS translation_locales FROM document d LEFT JOIN document_translation t ON t.document_id=d.id AND t.locale=? LEFT JOIN document_translation fallback ON fallback.document_id=d.id AND fallback.locale=? WHERE EXISTS (SELECT 1 FROM document_translation WHERE document_id=d.id) ORDER BY d.sort_order,d.slug").bind(locale, defaultLocale).all<{ id:string; folder_id:string|null; title:string; slug:string; sort_order:number; has_translation:number; translation_locales:string|null }>(),
+    env.DB.prepare(`
+      SELECT t.document_id,t.locale,
+        CASE
+          WHEN t.published_revision_id IS NULL THEN 'draft'
+          WHEN r.title <> t.title OR r.description <> t.description OR r.content_json <> t.content_json THEN 'changes'
+          ELSE 'published'
+        END AS state
+      FROM document_translation t
+      LEFT JOIN document_revision r ON r.id=t.published_revision_id`).all<{ document_id: string; locale: SupportedLocale; state: PublicationState }>(),
+  ]);
+  const locales = (value: string | null) => value?.split(',').filter(isSupportedLocale) ?? [];
+  const statesByDocument = new Map<string, { locale: SupportedLocale; state: PublicationState }[]>();
+  for (const state of states.results) {
+    const values = statesByDocument.get(state.document_id) ?? [];
+    values.push({ locale: state.locale, state: state.state });
+    statesByDocument.set(state.document_id, values);
+  }
+  return [
+    ...folders.results.map((row) => ({ id: `folder:${row.id}`, parentId: row.parent_id ? `folder:${row.parent_id}` : null, kind: 'folder' as const, name: row.name, slug: row.slug, order: row.sort_order, hasTranslation: Boolean(row.has_translation), translationLocales: locales(row.translation_locales), translationStates: [] })),
+    ...documents.results.map((row) => ({ id: `document:${row.id}`, parentId: row.folder_id ? `folder:${row.folder_id}` : null, kind: 'document' as const, name: row.title, slug: row.slug, order: row.sort_order, hasTranslation: Boolean(row.has_translation), translationLocales: locales(row.translation_locales), translationStates: statesByDocument.get(row.id) ?? [], documentId: row.id })),
+  ];
+}
+
+export async function createFolder(env: RuntimeEnv, raw: unknown, locale: SupportedLocale = defaultLocale) {
+  if (locale !== defaultLocale) throw new NavigationConflictError(`Create folders in ${defaultLocale}, then add a translation`);
+  const input = folderInput.parse(raw); await assertParentFolder(env, input.parentId); await assertAvailable(env, input.parentId, input.slug);
+  const id = crypto.randomUUID(); const now = Date.now();
+  await env.DB.batch([
+    env.DB.prepare('INSERT INTO folder (id,parent_id,slug,sort_order,created_at,updated_at) VALUES (?,?,?,?,?,?)').bind(id, input.parentId, input.slug, input.order, now, now),
+    env.DB.prepare('INSERT INTO folder_translation (folder_id,locale,name,created_at,updated_at) VALUES (?,?,?,?,?)').bind(id, locale, input.name, now, now),
+  ]);
+  return { id, ...input, createdAt: now, updatedAt: now };
+}
+
+export async function updateFolder(env: RuntimeEnv, id: string, raw: unknown, locale: SupportedLocale = defaultLocale) {
+  const input = folderInput.parse(raw);
+  if (!await env.DB.prepare('SELECT id FROM folder WHERE id=?').bind(id).first()) throw new FolderNotFoundError();
+  await assertNoFolderCycle(env, id, input.parentId); await assertAvailable(env, input.parentId, input.slug, id);
+  const now = Date.now();
+  const results = await env.DB.batch([
+    env.DB.prepare('UPDATE folder SET parent_id=?,slug=?,sort_order=?,updated_at=? WHERE id=?').bind(input.parentId, input.slug, input.order, now, id),
+    env.DB.prepare('UPDATE folder_translation SET name=?,updated_at=? WHERE folder_id=? AND locale=?').bind(input.name, now, id, locale),
+    folderDeliveryStatement(env, id),
+  ]);
+  if (results[0]?.meta.changes !== 1 || results[1]?.meta.changes !== 1) throw new FolderNotFoundError();
+  return { id, ...input, updatedAt: now };
+}
+
+export async function createFolderTranslation(env: RuntimeEnv, folderId: string, locale: SupportedLocale, sourceLocale: SupportedLocale = defaultLocale) {
+  if (locale === sourceLocale) throw new NavigationConflictError('Choose a different language');
+  const source = await env.DB.prepare('SELECT name FROM folder_translation WHERE folder_id=? AND locale=?').bind(folderId, sourceLocale).first<{ name: string }>();
+  if (!source) throw new FolderNotFoundError();
+  const existing = await env.DB.prepare('SELECT folder_id FROM folder_translation WHERE folder_id=? AND locale=?').bind(folderId, locale).first();
+  if (existing) throw new NavigationConflictError('This translation already exists');
+  const now = Date.now();
+  await env.DB.batch([
+    env.DB.prepare('INSERT INTO folder_translation (folder_id,locale,name,created_at,updated_at) VALUES (?,?,?,?,?)').bind(folderId, locale, source.name, now, now),
+    folderDeliveryStatement(env, folderId),
+  ]);
+  return { id: folderId, name: source.name, updatedAt: now };
+}
+
+export async function deleteFolder(env: RuntimeEnv, id: string) {
+  const [childFolder, childDocument] = await Promise.all([
+    env.DB.prepare('SELECT id FROM folder WHERE parent_id=? LIMIT 1').bind(id).first(),
+    env.DB.prepare('SELECT id FROM document WHERE folder_id=? LIMIT 1').bind(id).first(),
+  ]);
+  if (childFolder || childDocument) throw new NavigationConflictError('Move or delete the folder contents before deleting this folder');
+  const deleted = await env.DB.prepare('DELETE FROM folder WHERE id=? RETURNING id').bind(id).first<{ id: string }>();
+  if (!deleted) throw new FolderNotFoundError();
+}
+
+const treeChildId = z.string().regex(/^(folder|document):[0-9a-f-]{36}$/i);
+const childrenInput = z.object({ parentId: z.string().uuid().nullable(), childIds: z.array(treeChildId).max(10_000) });
+type NavigationRow = { id: string; kind: 'folder' | 'document'; slug: string; order: number };
+
+async function siblings(env: RuntimeEnv, parentId: string | null, excluded: NavigationRow | null = null): Promise<NavigationRow[]> {
+  const [folders, documents] = await Promise.all([
+    env.DB.prepare('SELECT id,slug,sort_order FROM folder WHERE parent_id IS ?').bind(parentId).all<{ id: string; slug: string; sort_order: number }>(),
+    env.DB.prepare('SELECT id,slug,sort_order FROM document WHERE folder_id IS ?').bind(parentId).all<{ id: string; slug: string; sort_order: number }>(),
+  ]);
+  return [
+    ...folders.results.map((row) => ({ id: row.id, kind: 'folder' as const, slug: row.slug, order: row.sort_order })),
+    ...documents.results.map((row) => ({ id: row.id, kind: 'document' as const, slug: row.slug, order: row.sort_order })),
+  ].filter((row) => !excluded || row.kind !== excluded.kind || row.id !== excluded.id)
+    .sort((a, b) => a.order - b.order || a.slug.localeCompare(b.slug));
+}
+
+function reorderStatements(env: RuntimeEnv, entries: NavigationRow[], parentId: string | null, now: number) {
+  return entries.map((entry, order) => env.DB.prepare(entry.kind === 'folder'
+    ? 'UPDATE folder SET parent_id=?,sort_order=?,updated_at=? WHERE id=?'
+    : 'UPDATE document SET folder_id=?,sort_order=?,updated_at=? WHERE id=?')
+    .bind(parentId, order, now, entry.id));
+}
+
+export async function replaceTreeChildren(env: RuntimeEnv, raw: unknown) {
+  const input = childrenInput.parse(raw);
+  if (new Set(input.childIds).size !== input.childIds.length) throw new NavigationConflictError('A navigation item was included more than once');
+  await assertParentFolder(env, input.parentId);
+  const entries = await Promise.all(input.childIds.map(async (childId) => {
+    const [kind, id] = childId.split(':') as ['folder' | 'document', string];
+    const row = await env.DB.prepare(`SELECT slug FROM ${kind} WHERE id=?`).bind(id).first<{ slug: string }>();
+    if (!row) throw new FolderNotFoundError();
+    if (kind === 'folder') await assertNoFolderCycle(env, id, input.parentId);
+    return { id, kind, slug: row.slug, order: 0 } as NavigationRow;
+  }));
+
+  const movedIds = new Set(entries.map((entry) => `${entry.kind}:${entry.id}`));
+  const existing = await siblings(env, input.parentId);
+  const usedSlugs = new Set(existing.filter((entry) => !movedIds.has(`${entry.kind}:${entry.id}`)).map((entry) => entry.slug));
+  for (const entry of entries) {
+    if (usedSlugs.has(entry.slug)) throw new NavigationConflictError('A folder or page already uses this URL segment');
+    usedSlugs.add(entry.slug);
+  }
+  if (entries.length > 0) await env.DB.batch([
+    ...reorderStatements(env, entries, input.parentId, Date.now()),
+    siteDeliveryStatement(env, `EXISTS (
+      WITH RECURSIVE moved(id) AS (SELECT value FROM json_each(?)),
+      descendants(id) AS (
+        SELECT id FROM folder WHERE 'folder:' || id IN (SELECT id FROM moved)
+        UNION SELECT f.id FROM folder f JOIN descendants p ON f.parent_id=p.id
+      ) SELECT 1 FROM document d JOIN document_translation t ON t.document_id=d.id
+        WHERE t.published_revision_id IS NOT NULL AND
+          (d.folder_id IN (SELECT id FROM descendants) OR 'document:' || d.id IN (SELECT id FROM moved))
+    )`, [JSON.stringify(input.childIds)]),
+  ]);
+  return { parentId: input.parentId, childIds: input.childIds };
+}

package/template/src/pages/[locale]/cms-preview-shell.astro

@@ -0,0 +1,12 @@
+---
+import PreviewShell from '../../starlight/preview-shell.astro';
+import { siteConfig } from '../../site.config.ts';
+
+export function getStaticPaths() {
+  return siteConfig.locales
+    .filter(({ code }) => code !== siteConfig.defaultLocale)
+    .map(({ code }) => ({ params: { locale: code } }));
+}
+---
+
+<PreviewShell />

package/template/src/pages/cms-preview-shell.astro

@@ -0,0 +1,5 @@
+---
+import PreviewShell from '../starlight/preview-shell.astro';
+---
+
+<PreviewShell />

package/template/src/publish/deploy-hook.ts

@@ -0,0 +1,42 @@
+export type DeployHookResult = { buildId: string | null; alreadyExists: boolean };
+
+function transportError(error: unknown): Error {
+  // Do not persist runtime error messages: they can contain the secret hook URL.
+  if (error instanceof DOMException && error.name === 'TimeoutError') {
+    return new Error('Workers Deploy Hook request timed out');
+  }
+  if (error instanceof TypeError) {
+    return new Error('Workers Deploy Hook network request failed');
+  }
+  return new Error('Workers Deploy Hook transport failed');
+}
+
+/**
+ * Low-level Workers Builds transport. The URL is a secret, so errors deliberately
+ * contain no destination or response body.
+ */
+export async function triggerDeployHook(url: string, request: typeof fetch = fetch): Promise<DeployHookResult> {
+  const parsed = new URL(url);
+  if (parsed.origin !== 'https://api.cloudflare.com' ||
+      !/^\/client\/v4\/workers\/builds\/deploy_hooks\/[a-zA-Z0-9_-]+$/.test(parsed.pathname) ||
+      parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error('Invalid Workers Deploy Hook URL');
+  }
+  let response: Response;
+  // This deliberately matches Cloudflare's documented Deploy Hook request. The
+  // hook URL itself is the credential; no Access or API-token header is used.
+  try { response = await request(parsed.href, { method: 'POST' }); }
+  catch (error) { throw transportError(error); }
+  if (!response.ok) throw new Error(`Workers Deploy Hook rejected: ${response.status}`);
+  try {
+    const body = await response.json() as { result?: { build_uuid?: unknown; already_exists?: unknown } };
+    return {
+      buildId: typeof body.result?.build_uuid === 'string' ? body.result.build_uuid : null,
+      alreadyExists: body.result?.already_exists === true,
+    };
+  } catch {
+    // Cloudflare currently returns JSON, but accepting a successful empty response
+    // keeps the hook boundary compatible with a future 2xx response format.
+    return { buildId: null, alreadyExists: false };
+  }
+}

package/template/src/publish/record.ts

@@ -0,0 +1,20 @@
+import type { RuntimeEnv } from '../env.ts';
+
+/** Append this statement to the mutation's batch so a committed change is recoverable. */
+export function siteDeliveryStatement(env: RuntimeEnv, condition: string, bindings: (string | number | null)[] = []) {
+  return env.DB.prepare(`INSERT INTO publish_delivery
+    (id,trigger_kind,status,attempts,already_exists,requested_at)
+    SELECT ?,'site','pending',0,0,? WHERE ${condition}`)
+    .bind(crypto.randomUUID(), Date.now(), ...bindings);
+}
+
+const publishedFolderCondition = `EXISTS (
+    WITH RECURSIVE descendants(id) AS (
+      SELECT id FROM folder WHERE id=?
+      UNION SELECT f.id FROM folder f JOIN descendants p ON f.parent_id=p.id
+    ) SELECT 1 FROM document d JOIN document_translation t ON t.document_id=d.id
+      WHERE d.folder_id IN (SELECT id FROM descendants) AND t.published_revision_id IS NOT NULL
+  )`;
+export function folderDeliveryStatement(env: RuntimeEnv, folderId: string) {
+  return siteDeliveryStatement(env, publishedFolderCondition, [folderId]);
+}

package/template/src/publish/service.ts

@@ -0,0 +1,135 @@
+import type { RuntimeEnv } from '../env.ts';
+import { triggerDeployHook } from './deploy-hook.ts';
+import { publishDocument, type DocumentView } from '../documents/service.ts';
+import type { SupportedLocale } from '../locales.ts';
+
+export type PublishDeliveryStatus = 'pending' | 'accepted' | 'failed' | 'skipped';
+export type PublishDeliveryKind = 'document' | 'site';
+
+type DeliveryRow = {
+  id: string;
+  trigger_kind: PublishDeliveryKind;
+  document_translation_id: string | null;
+  status: PublishDeliveryStatus;
+  attempts: number;
+  build_id: string | null;
+  already_exists: number;
+  last_error: string | null;
+  requested_at: number;
+  accepted_at: number | null;
+  next_retry_at: number | null;
+};
+
+export type PublishDelivery = {
+  id: string;
+  triggerKind: PublishDeliveryKind;
+  documentTranslationId: string | null;
+  status: PublishDeliveryStatus;
+  attempts: number;
+  buildId: string | null;
+  alreadyExists: boolean;
+  lastError: string | null;
+  requestedAt: number;
+  acceptedAt: number | null;
+  nextRetryAt: number | null;
+};
+
+export class PublishDeliveryNotFoundError extends Error {}
+export class PublishDeliveryConflictError extends Error {}
+
+function toView(row: DeliveryRow): PublishDelivery {
+  return {
+    id: row.id, triggerKind: row.trigger_kind, documentTranslationId: row.document_translation_id,
+    status: row.status, attempts: row.attempts, buildId: row.build_id,
+    alreadyExists: Boolean(row.already_exists), lastError: row.last_error,
+    requestedAt: row.requested_at, acceptedAt: row.accepted_at, nextRetryAt: row.next_retry_at,
+  };
+}
+
+async function getDelivery(env: RuntimeEnv, id: string): Promise<DeliveryRow> {
+  const delivery = await env.DB.prepare(`
+    SELECT id,trigger_kind,document_translation_id,status,attempts,build_id,already_exists,last_error,
+      requested_at,accepted_at,next_retry_at
+    FROM publish_delivery WHERE id=?`).bind(id).first<DeliveryRow>();
+  if (!delivery) throw new PublishDeliveryNotFoundError();
+  return delivery;
+}
+
+export async function createPublishDelivery(env: RuntimeEnv, triggerKind: PublishDeliveryKind, documentTranslationId: string | null = null) {
+  const id = crypto.randomUUID();
+  const requestedAt = Date.now();
+  await env.DB.prepare(`
+    INSERT INTO publish_delivery (id,trigger_kind,document_translation_id,status,attempts,already_exists,requested_at)
+    VALUES (?,?,?,'pending',0,0,?)`).bind(id, triggerKind, documentTranslationId, requestedAt).run();
+  return getDelivery(env, id);
+}
+
+/** Send one already-persisted delivery. A request is never sent before its row exists. */
+export async function deliverPublish(env: RuntimeEnv, id: string): Promise<PublishDelivery> {
+  const current = await getDelivery(env, id);
+  if (current.status === 'accepted' || current.status === 'skipped') return toView(current);
+  if (current.status !== 'pending' && current.status !== 'failed') throw new PublishDeliveryConflictError('This build request cannot be retried');
+
+  if (current.status === 'pending' && current.next_retry_at && current.next_retry_at > Date.now()) {
+    throw new PublishDeliveryConflictError('This build request is still being sent');
+  }
+  const attempts = current.attempts + 1;
+  const started = await env.DB.prepare(`
+    UPDATE publish_delivery SET status='pending',attempts=?,last_error=NULL,next_retry_at=?
+    WHERE id=? AND status=? AND attempts=?`).bind(attempts, Date.now() + 30_000, id, current.status, current.attempts).run();
+  if (started.meta.changes !== 1) throw new PublishDeliveryConflictError('This build request changed. Reload and try again.');
+
+  if (!env.WORKERS_DEPLOY_HOOK_URL) {
+    await env.DB.prepare(`UPDATE publish_delivery SET status='skipped',last_error=?,next_retry_at=NULL WHERE id=?`)
+      .bind(env.LOCAL_DEV_BUILD === 'true' ? 'Local development rebuild is active' : 'WORKERS_DEPLOY_HOOK_URL is not configured', id).run();
+    return toView(await getDelivery(env, id));
+  }
+
+  try {
+    const hook = await triggerDeployHook(env.WORKERS_DEPLOY_HOOK_URL);
+    await env.DB.prepare(`
+      UPDATE publish_delivery
+      SET status='accepted',build_id=?,already_exists=?,accepted_at=?,last_error=NULL,next_retry_at=NULL
+      WHERE id=?`).bind(hook.buildId, hook.alreadyExists ? 1 : 0, Date.now(), id).run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Workers Deploy Hook request failed';
+    await env.DB.prepare(`UPDATE publish_delivery SET status='failed',last_error=?,next_retry_at=? WHERE id=?`)
+      .bind(message, null, id).run();
+  }
+  return toView(await getDelivery(env, id));
+}
+
+export async function requestPublish(env: RuntimeEnv, triggerKind: PublishDeliveryKind, documentTranslationId: string | null = null) {
+  const pending = await createPublishDelivery(env, triggerKind, documentTranslationId);
+  return deliverPublish(env, pending.id);
+}
+
+/** Publish the selected translation and create its delivery in one D1 batch. */
+export async function publishDocumentAndRequest(env: RuntimeEnv, id: string, version: number, locale: SupportedLocale): Promise<{ document: DocumentView; delivery: PublishDelivery }> {
+  const pending = { id: crypto.randomUUID(), requestedAt: Date.now() };
+  const document = await publishDocument(env, id, version, locale, pending);
+  return { document, delivery: await deliverPublish(env, pending.id) };
+}
+
+export async function retryPublish(env: RuntimeEnv, id: string) {
+  const delivery = await getDelivery(env, id);
+  if (delivery.status !== 'failed' && delivery.status !== 'pending') throw new PublishDeliveryConflictError('Only failed or pending build requests can be retried');
+  return deliverPublish(env, id);
+}
+
+export async function listPublishDeliveries(env: RuntimeEnv, limit = 10) {
+  const rows = await env.DB.prepare(`
+    SELECT id,trigger_kind,document_translation_id,status,attempts,build_id,already_exists,last_error,
+      requested_at,accepted_at,next_retry_at
+    FROM publish_delivery ORDER BY CASE WHEN status='failed' OR (status='pending' AND (next_retry_at IS NULL OR next_retry_at<=?)) THEN 0 ELSE 1 END, requested_at DESC LIMIT ?`).bind(Date.now(), limit).all<DeliveryRow>();
+  return rows.results.map(toView);
+}
+
+/** Dispatch newly persisted navigation/deletion changes; never create a second record. */
+export async function deliverPendingChanges(env: RuntimeEnv) {
+  const rows = await env.DB.prepare("SELECT id FROM publish_delivery WHERE status='pending' AND attempts=0 ORDER BY requested_at LIMIT 100").all<{ id: string }>();
+  for (const row of rows.results) {
+    try { await deliverPublish(env, row.id); }
+    catch (error) { if (!(error instanceof PublishDeliveryConflictError)) throw error; }
+  }
+}

package/template/src/scss.d.ts

@@ -0,0 +1,5 @@
+declare module "*.scss";
+declare module "*.svg" {
+  const source: string;
+  export default source;
+}

package/template/src/site.config.ts

@@ -0,0 +1,7 @@
+/** Public site settings. Secrets belong in Cloudflare. */
+export const siteConfig = {
+  title: 'My Docs',
+  url: '', // Set the production origin, e.g. https://docs.example.com
+  defaultLocale: 'en',
+  locales: [{ code: 'en', label: 'English' }],
+} as const;

package/template/src/sql.d.ts

@@ -0,0 +1,4 @@
+declare module '*.sql' {
+  const sql: string;
+  export default sql;
+}

package/template/src/starlight/cms-origin.ts

@@ -0,0 +1,4 @@
+import { siteConfig } from '../site.config.ts';
+
+/** The public Docs and Admin share one Worker origin, set in the project source. */
+export const cmsOrigin = siteConfig.url.replace(/\/$/, '');

package/template/src/starlight/loader.ts

@@ -0,0 +1,21 @@
+import type { Loader } from 'astro/loaders';
+import { defaultLocale } from '../locales.ts';
+import { publishedDocuments } from './schema.ts';
+
+export function cmsLoader(options: { loadSnapshot: () => Promise<unknown> }): Loader {
+  return {
+    name: 'starlight-cms',
+    async load({ store, parseData, renderMarkdown, generateDigest }) {
+      const documents = publishedDocuments(await options.loadSnapshot());
+      const entries = await Promise.all(documents.map(async (doc) => {
+        const id = doc.locale === defaultLocale ? doc.slug : `${doc.locale}/${doc.slug}`;
+        return {
+        id, filePath: `src/content/docs/${id}.md`,
+        data: await parseData({ id, data: { title: doc.title, description: doc.description, sidebar: { order: doc.order }, editUrl: false } }),
+        body: doc.body.value, rendered: await renderMarkdown(doc.body.value), digest: generateDigest(doc),
+      }; }));
+      store.clear();
+      for (const entry of entries) store.set(entry);
+    },
+  };
+}

package/template/src/starlight/preview-render.ts

@@ -0,0 +1,162 @@
+import { documentUrl, parseTiptapNode, tiptapChildren, type TiptapNode } from './tiptap.ts';
+import GithubSlugger from 'github-slugger';
+
+export interface PreviewHeading {
+  id: string;
+  level: number;
+  text: string;
+}
+
+export interface PreviewDocument {
+  html: string;
+  headings: PreviewHeading[];
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function text(value: TiptapNode): string {
+  let output = escapeHtml(value.text ?? '');
+  const marks = Array.isArray(value.marks) ? value.marks : [];
+  for (const mark of marks) {
+    if (!mark || typeof mark !== 'object' || !('type' in mark)) continue;
+    const typed = mark as { type: unknown; attrs?: Record<string, unknown> };
+    switch (typed.type) {
+      case 'bold': output = `<strong>${output}</strong>`; break;
+      case 'italic': output = `<em>${output}</em>`; break;
+      case 'strike': output = `<s>${output}</s>`; break;
+      case 'code': output = `<code>${output}</code>`; break;
+      case 'link': output = `<a href="${escapeHtml(documentUrl(typed.attrs?.href))}">${output}</a>`; break;
+      default: throw new Error(`Unsupported Tiptap mark: ${String(typed.type)}`);
+    }
+  }
+  return output;
+}
+
+function asideTitle(value: unknown): string {
+  return typeof value === 'string' ? value.replace(/[\]\r\n]/g, ' ').trim() : 'Note';
+}
+
+function codeLanguage(value: unknown): string {
+  return typeof value === 'string' && /^[a-z0-9+-]+$/i.test(value) ? ` class="language-${escapeHtml(value)}"` : '';
+}
+
+function headingText(value: TiptapNode): string {
+  if (value.type === 'text') return value.text ?? '';
+  if (value.type === 'hardBreak') return ' ';
+  return tiptapChildren(value).map(headingText).join('');
+}
+
+function createRenderer() {
+  const headings: PreviewHeading[] = [];
+  const slugger = new GithubSlugger();
+
+  function inline(value: TiptapNode): string {
+    return tiptapChildren(value).map(renderNode).join('');
+  }
+
+  function renderListItem(value: TiptapNode): string {
+    return `<li>${inline(value)}</li>`;
+  }
+
+  function renderTableRow(value: TiptapNode, header: boolean): string {
+    const cell = header ? 'th' : 'td';
+    return `<tr>${tiptapChildren(value).map((item) => `<${cell}>${inline(item)}</${cell}>`).join('')}</tr>`;
+  }
+
+  function renderTabs(value: TiptapNode): string {
+    const tabs = tiptapChildren(value);
+    if (tabs.length === 0) return '';
+    const labels = tabs.map((tab) => typeof tab.attrs?.label === 'string' ? tab.attrs.label : 'Tab');
+    return `<starlight-tabs><div class="tablist-wrapper not-content"><ul role="tablist">${labels.map((label, index) => `<li role="presentation" class="tab"><a role="tab" href="#cms-preview-tab-${index}" aria-selected="${index === 0}"${index === 0 ? '' : ' tabindex="-1"'}>${escapeHtml(label)}</a></li>`).join('')}</ul></div>${tabs.map((tab, index) => `<section id="cms-preview-tab-${index}" role="tabpanel"${index === 0 ? '' : ' hidden'}>${inline(tab)}</section>`).join('')}</starlight-tabs>`;
+  }
+
+  function renderNode(value: TiptapNode): string {
+    switch (value.type) {
+      case 'text': return text(value);
+      case 'doc': return tiptapChildren(value).map(renderNode).join('');
+      case 'paragraph': return `<p>${inline(value)}</p>`;
+      case 'heading': {
+        const level = Number(value.attrs?.level ?? 2);
+        if (!Number.isInteger(level) || level < 1 || level > 6) throw new Error('Invalid heading level');
+        const label = headingText(value).replace(/\s+/g, ' ').trim() || 'Section';
+        const id = slugger.slug(label);
+        headings.push({ id, level, text: label });
+        return `<h${level} id="${escapeHtml(id)}">${inline(value)}</h${level}>`;
+      }
+      case 'bulletList': return `<ul>${tiptapChildren(value).map(renderListItem).join('')}</ul>`;
+      case 'orderedList': return `<ol>${tiptapChildren(value).map(renderListItem).join('')}</ol>`;
+      case 'taskList': return `<ul class="contains-task-list">${tiptapChildren(value).map(renderNode).join('')}</ul>`;
+      case 'taskItem': return `<li class="task-list-item"><input type="checkbox" disabled${value.attrs?.checked === true ? ' checked' : ''}>${inline(value)}</li>`;
+      case 'listItem': return renderListItem(value);
+      case 'blockquote': return `<blockquote>${inline(value)}</blockquote>`;
+      case 'codeBlock': return `<pre><code${codeLanguage(value.attrs?.language)}>${inline(value)}</code></pre>`;
+      case 'hardBreak': return '<br>';
+      case 'horizontalRule': return '<hr>';
+      case 'image': return `<img src="${escapeHtml(documentUrl(value.attrs?.src))}" alt="${escapeHtml(typeof value.attrs?.alt === 'string' ? value.attrs.alt : '')}">`;
+      case 'video': return `<video controls src="${escapeHtml(documentUrl(value.attrs?.src))}"></video>`;
+      case 'callout': {
+        const title = asideTitle(value.attrs?.title);
+        return `<aside aria-label="${escapeHtml(title)}" class="starlight-aside starlight-aside--note"><p class="starlight-aside__title" aria-hidden="true">${escapeHtml(title)}</p><div class="starlight-aside__content">${inline(value)}</div></aside>`;
+      }
+      case 'steps': return `<ol class="sl-steps">${tiptapChildren(value).map(renderListItem).join('')}</ol>`;
+      case 'tabs': return renderTabs(value);
+      case 'tab': return inline(value);
+      case 'table': {
+        const rows = tiptapChildren(value);
+        return `<table><tbody>${rows.map((row, index) => renderTableRow(row, index === 0)).join('')}</tbody></table>`;
+      }
+      case 'tableRow': return renderTableRow(value, false);
+      case 'tableHeader':
+      case 'tableCell': return inline(value);
+      default: throw new Error(`Unsupported Tiptap node: ${value.type}`);
+    }
+  }
+
+  return { headings, render: renderNode };
+}
+
+/** Render the supported CMS Tiptap subset into safe HTML inside Starlight's generated shell. */
+export function renderPreviewContent(content: unknown): string {
+  return renderPreviewDocument(content).html;
+}
+
+/** Render the saved document once so heading anchors and the generated TOC always agree. */
+export function renderPreviewDocument(content: unknown): PreviewDocument {
+  const renderer = createRenderer();
+  return { html: renderer.render(parseTiptapNode(content)), headings: renderer.headings };
+}
+
+interface TocItem extends PreviewHeading { children: TocItem[]; }
+
+function tocTree(headings: PreviewHeading[], minHeadingLevel: number, maxHeadingLevel: number): TocItem[] {
+  const roots: TocItem[] = [];
+  const add = (items: TocItem[], item: TocItem): void => {
+    const last = items.at(-1);
+    if (!last || last.level >= item.level) items.push(item);
+    else add(last.children, item);
+  };
+  for (const heading of headings) {
+    if (heading.level >= minHeadingLevel && heading.level <= maxHeadingLevel) add(roots, { ...heading, children: [] });
+  }
+  return roots;
+}
+
+function scopedClass(className: string): string {
+  return className ? ` class="${escapeHtml(className)}"` : '';
+}
+
+function renderTocItems(items: TocItem[], depth: number, className: string): string {
+  return items.map((item) => {
+    const children = item.children.length > 0
+      ? `<ul${scopedClass(className)} style="--depth: ${depth + 1};">${renderTocItems(item.children, depth + 1, className)}</ul>`
+      : '';
+    return `<li${scopedClass(className)} style="--depth: ${depth};"><a${scopedClass(className)} href="#${encodeURIComponent(item.id)}" style="--depth: ${depth};"><span${scopedClass(className)} style="--depth: ${depth};">${escapeHtml(item.text)}</span></a>${children}</li>`;
+  }).join('');
+}
+
+/** Replace Starlight's static `Overview` item while retaining its generated TOC structure and styles. */
+export function renderPreviewTocItems(headings: PreviewHeading[], minHeadingLevel: number, maxHeadingLevel: number, className: string): string {
+  return renderTocItems(tocTree(headings, minHeadingLevel, maxHeadingLevel), 0, className);
+}

package/template/src/starlight/preview-shell.astro

@@ -0,0 +1,14 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+---
+
+<StarlightPage frontmatter={{
+  title: 'Preview',
+  description: 'Saved draft preview.',
+  editUrl: false,
+  pagefind: false,
+  head: [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } }],
+}} hasSidebar={true}>
+  <!-- The protected Worker replaces this marker with a saved Draft. -->
+  <div id="cms-preview-content"></div>
+</StarlightPage>