create-starlight-cms 0.9.0

package/template/src/starlight/render.ts

@@ -0,0 +1,59 @@
+import { documentUrl, parseTiptapNode, tiptapChildren, type TiptapNode } from './tiptap.ts';
+
+function decorateText(value: TiptapNode, output: string): string {
+  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> };
+    if (typed.type === 'bold') output = `**${output}**`;
+    if (typed.type === 'italic') output = `*${output}*`;
+    if (typed.type === 'strike') output = `~~${output}~~`;
+    if (typed.type === 'code') output = `\`${output}\``;
+    if (typed.type === 'link') output = `[${output}](${documentUrl(typed.attrs?.href)})`;
+  }
+  return output;
+}
+function text(value: TiptapNode): string { return decorateText(value, tiptapChildren(value).map(render).join('')); }
+function asideTitle(value: unknown): string {
+  return typeof value === 'string' ? value.replace(/[\]\r\n]/g, ' ').trim() : 'Note';
+}
+export function render(nodeValue: unknown): string {
+  const value = parseTiptapNode(nodeValue);
+  switch (value.type) {
+    case 'text': return decorateText(value, value.text ?? '');
+    case 'doc': return `${tiptapChildren(value).map(render).join('\n\n')}\n`;
+    case 'paragraph': return text(value);
+    case 'heading': return `${'#'.repeat(Number(value.attrs?.level ?? 2))} ${text(value)}`;
+    case 'bulletList': return tiptapChildren(value).map((item) => `- ${text(item)}`).join('\n');
+    case 'orderedList': return tiptapChildren(value).map((item, index) => `${index + 1}. ${text(item)}`).join('\n');
+    case 'taskList': return tiptapChildren(value).map((item) => `- [${item.attrs?.checked === true ? 'x' : ' '}] ${text(item)}`).join('\n');
+    case 'taskItem': return text(value);
+    case 'listItem': return text(value);
+    case 'blockquote': return text(value).split('\n').map((line) => `> ${line}`).join('\n');
+    case 'codeBlock': return `\`\`\`${typeof value.attrs?.language === 'string' ? value.attrs.language : ''}\n${text(value)}\n\`\`\``;
+    case 'hardBreak': return '  \n';
+    case 'horizontalRule': return '---';
+    case 'image': return `![${typeof value.attrs?.alt === 'string' ? value.attrs.alt : ''}](${documentUrl(value.attrs?.src)})`;
+    case 'video': return `<video controls src="${documentUrl(value.attrs?.src)}"></video>`;
+    case 'callout': return `:::note[${asideTitle(value.attrs?.title)}]\n${tiptapChildren(value).map(render).join('\n\n')}\n:::`;
+    case 'steps': return tiptapChildren(value).map((item, index) => `${index + 1}. ${text(item)}`).join('\n');
+    case 'tabs': return tiptapChildren(value).map((item) => `#### ${typeof item.attrs?.label === 'string' ? item.attrs.label : 'Tab'}\n\n${text(item)}`).join('\n\n');
+    case 'tab': return text(value);
+    case 'table': {
+      const rows = tiptapChildren(value);
+      return rows.map((row, index) => {
+        const cells = tiptapChildren(row);
+        const markdown = `| ${cells.map(text).join(' | ')} |`;
+        return index === 0 ? `${markdown}\n| ${cells.map(() => '---').join(' | ')} |` : markdown;
+      }).join('\n');
+    }
+    case 'tableRow': return `| ${tiptapChildren(value).map(text).join(' | ')} |`;
+    case 'tableHeader':
+    case 'tableCell': return text(value);
+    default: throw new Error(`Unsupported Tiptap node: ${value.type}`);
+  }
+}
+
+export function renderDocumentContent(content: unknown): string {
+  return render(content);
+}

package/template/src/starlight/schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defaultLocale, supportedLocales } from '../locales.ts';
+
+export const documentSchema = z.object({
+  id: z.string().min(1),
+  locale: z.enum(supportedLocales).default(defaultLocale),
+  title: z.string().min(1),
+  slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/)
+    .refine((slug) => !['admin', 'api', 'auth', '_astro', 'pagefind', '404'].includes(slug.split('/')[0]!), 'Reserved route'),
+  description: z.string().default(''),
+  section: z.string().default(''),
+  navigation: z.array(z.object({ slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), label: z.string().min(1), order: z.number().int().nonnegative(), translations: z.record(z.string(), z.string()) })).default([]),
+  order: z.number().int().nonnegative().default(0),
+  body: z.object({ format: z.literal('markdown'), value: z.string() }).strict(),
+  status: z.literal('published'),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  publishedAt: z.string().datetime(),
+}).strict();
+export const snapshotSchema = z.object({ version: z.union([z.literal(1), z.literal(2), z.literal(3)]), documents: z.array(documentSchema) }).strict();
+export type Document = z.infer<typeof documentSchema>;
+
+export function publishedDocuments(input: unknown): Document[] {
+  const { documents } = snapshotSchema.parse(input);
+  const ids = new Set<string>(); const routes = new Set<string>();
+  for (const doc of documents) {
+    if (doc.locale === defaultLocale && supportedLocales.some((locale) => locale !== defaultLocale && doc.slug.split('/')[0] === locale)) throw new Error('Published route conflicts with a language prefix');
+    const id = `${doc.locale}:${doc.id}`;
+    const route = doc.locale === defaultLocale ? doc.slug : `${doc.locale}/${doc.slug}`;
+    if (ids.has(id) || routes.has(route)) throw new Error('Duplicate published id or route');
+    ids.add(id); routes.add(route);
+  }
+  return documents.sort((a, b) => a.locale.localeCompare(b.locale) || a.order - b.order || a.slug.localeCompare(b.slug));
+}

package/template/src/starlight/sidebar.ts

@@ -0,0 +1,35 @@
+import { defaultLocale } from '../locales.ts';
+import { publishedDocuments } from './schema.ts';
+
+type Entry = { label: string; translations?: Record<string, string>; slug?: string; items?: Entry[] };
+type OrderedEntry = Entry & { order: number; key: string; items?: OrderedEntry[] };
+
+/** Convert the shared CMS hierarchy into Starlight's built-in sidebar configuration. */
+export function cmsSidebar(snapshot: unknown): Entry[] {
+  const documents = publishedDocuments(snapshot);
+  const roots: OrderedEntry[] = [];
+  const pages = new Map<string, typeof documents>();
+  for (const doc of documents) pages.set(doc.id, [...(pages.get(doc.id) ?? []), doc]);
+  for (const translations of pages.values()) {
+    const page = translations.find((doc) => doc.locale === defaultLocale) ?? translations[0]!;
+    let items = roots;
+    for (const folder of page.navigation) {
+      let group = items.find((entry) => entry.key === folder.slug && entry.items);
+      if (!group) {
+        group = { key: folder.slug, label: folder.label, translations: folder.translations, order: folder.order, items: [] };
+        items.push(group);
+      }
+      items = group.items!;
+    }
+    items.push({ key: page.slug, label: page.title, order: page.order,
+      slug: page.locale === defaultLocale ? page.slug : `${page.locale}/${page.slug}`,
+      translations: Object.fromEntries(translations.map((doc) => [doc.locale, doc.title])),
+    });
+  }
+  function sorted(items: OrderedEntry[]): Entry[] {
+    return items.sort((a, b) => a.order - b.order || a.key.localeCompare(b.key)).map(({ key, order, items, ...entry }) => ({
+      ...entry, ...(items ? { items: sorted(items) } : {}),
+    }));
+  }
+  return sorted(roots);
+}

package/template/src/starlight/snapshot.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { RuntimeEnv } from '../env.ts';
+import { defaultLocale } from '../locales.ts';
+import { renderDocumentContent } from './render.ts';
+
+const folderRow = z.object({ id: z.string(), parent_id: z.string().nullable(), slug: z.string(), sort_order: z.number() });
+type Folder = z.infer<typeof folderRow>;
+const labelRow = z.object({ folder_id: z.string(), locale: z.string(), name: z.string() });
+const pageRow = z.object({ id: z.string(), folder_id: z.string().nullable(), slug: z.string(), sort_order: z.number(), locale: z.string(), title: z.string(), description: z.string(), content_json: z.string(), created_at: z.number(), updated_at: z.number(), published_at: z.number() });
+
+export async function publishedSnapshot(env: RuntimeEnv) {
+  const [folders, labels, pages] = await env.DB.batch([
+    env.DB.prepare('SELECT id,parent_id,slug,sort_order FROM folder ORDER BY id'),
+    env.DB.prepare('SELECT folder_id,locale,name FROM folder_translation ORDER BY folder_id,locale'),
+    env.DB.prepare(`SELECT d.id,d.folder_id,d.slug,d.sort_order,t.locale,r.title,r.description,r.content_json,
+      t.created_at,r.created_at AS updated_at,t.published_at
+      FROM document d JOIN document_translation t ON t.document_id=d.id
+      JOIN document_revision r ON r.id=t.published_revision_id
+      ORDER BY t.locale,d.sort_order,d.slug,d.id`),
+  ]);
+  if (!folders || !labels || !pages) throw new Error('Incomplete published snapshot');
+  const parent = new Map(z.array(folderRow).parse(folders.results).map((row) => [row.id, row]));
+  const names = z.array(labelRow).parse(labels.results);
+  return { version: 3, documents: z.array(pageRow).parse(pages.results).map((row) => {
+    const ancestors: Folder[] = []; const seen = new Set<string>(); let cursor = row.folder_id;
+    while (cursor) {
+      if (seen.has(cursor)) throw new Error('Navigation cycle');
+      seen.add(cursor);
+      const folder = parent.get(cursor);
+      if (!folder) throw new Error('Missing folder');
+      ancestors.unshift(folder); cursor = folder.parent_id;
+    }
+    return {
+      id: row.id, locale: row.locale, title: row.title,
+      slug: [...ancestors.map((folder) => folder.slug), row.slug].join('/'),
+      description: row.description, order: row.sort_order,
+      navigation: ancestors.map((folder) => ({
+        slug: folder.slug, order: folder.sort_order,
+        label: names.find((name) => name.folder_id === folder.id && name.locale === defaultLocale)?.name ?? folder.slug,
+        translations: Object.fromEntries(names.filter((name) => name.folder_id === folder.id).map((name) => [name.locale, name.name])),
+      })),
+      body: { format: 'markdown', value: renderDocumentContent(JSON.parse(row.content_json)) },
+      status: 'published', createdAt: new Date(row.created_at).toISOString(),
+      updatedAt: new Date(row.updated_at).toISOString(), publishedAt: new Date(row.published_at).toISOString(),
+    };
+  }) };
+}

package/template/src/starlight/source.ts

@@ -0,0 +1,26 @@
+import { cmsOrigin } from './cms-origin.ts';
+
+async function fetchSnapshot(): Promise<unknown> {
+  if (process.env.CMS_INITIAL_EMPTY === '1') return { version: 3, documents: [] };
+  const endpoint = process.env.CMS_EXPORT_URL
+    ?? (cmsOrigin ? new URL('/admin/export/snapshot', cmsOrigin).toString() : undefined);
+  // A blank URL is the template's explicit bootstrap state. Once configured,
+  // all build failures stay visible instead of publishing an empty fallback.
+  if (!endpoint) return { version: 3, documents: [] };
+  const clientId = process.env.CF_ACCESS_CLIENT_ID;
+  const clientSecret = process.env.CF_ACCESS_CLIENT_SECRET;
+  if (Boolean(clientId) !== Boolean(clientSecret)) throw new Error('CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET must be set together');
+  const headers = clientId && clientSecret
+    ? { 'CF-Access-Client-Id': clientId, 'CF-Access-Client-Secret': clientSecret }
+    : undefined;
+  const response = await fetch(endpoint, { headers, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`CMS export failed: ${response.status}`);
+  return response.json();
+}
+
+
+// Astro config and the content loader must use the same export, even when bundled separately.
+declare global { var cmsBuildSnapshot: Promise<unknown> | undefined; }
+export function loadSnapshot(): Promise<unknown> {
+  return globalThis.cmsBuildSnapshot ??= fetchSnapshot();
+}

package/template/src/starlight/tiptap.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+const tiptapNode = z.object({
+  type: z.string(),
+  text: z.string().optional(),
+  attrs: z.record(z.string(), z.unknown()).optional(),
+  content: z.array(z.unknown()).optional(),
+}).passthrough();
+
+export type TiptapNode = z.infer<typeof tiptapNode>;
+
+export function parseTiptapNode(value: unknown): TiptapNode {
+  return tiptapNode.parse(value);
+}
+
+export function tiptapChildren(value: TiptapNode): TiptapNode[] {
+  return (value.content ?? []).map(parseTiptapNode);
+}
+
+/** Reject URLs that cannot safely appear in a public document or preview. */
+export function documentUrl(value: unknown): string {
+  if (typeof value !== 'string' || (!/^https?:\/\//.test(value) && !value.startsWith('/'))) {
+    throw new Error('Unsafe media or link URL');
+  }
+  if (value.startsWith('/admin/api/media/object/')) {
+    throw new Error('Published media requires MEDIA_PUBLIC_URL');
+  }
+  return value.replace(/["<>]/g, '');
+}

package/template/src/styles/starlight.css

@@ -0,0 +1,12 @@
+/* Public Docs palette. Change these six values to match your own brand. */
+:root {
+  --sl-color-accent-low: #ede9fe;
+  --sl-color-accent: #7c3aed;
+  --sl-color-accent-high: #4c1d95;
+}
+
+:root[data-theme='dark'] {
+  --sl-color-accent-low: #2e1065;
+  --sl-color-accent: #a78bfa;
+  --sl-color-accent-high: #ede9fe;
+}

package/template/test-files/content.test.template.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { publishedDocuments } from '../src/starlight/schema.ts';
+import { renderDocumentContent } from '../src/starlight/render.ts';
+import { renderPreviewContent, renderPreviewDocument, renderPreviewTocItems } from '../src/starlight/preview-render.ts';
+import { supportedLocales } from '../src/locales.ts';
+
+const published = {
+  version: 2,
+  documents: [{
+    id: 'one', title: 'One', slug: 'one', description: '', section: '', order: 1,
+    body: { format: 'markdown', value: '# One' }, status: 'published',
+    createdAt: '2026-09-09T00:00:00.000Z', updatedAt: '2026-09-09T00:00:00.000Z', publishedAt: '2026-09-09T00:00:00.000Z',
+  }],
+};
+
+describe('published build boundary', () => {
+  it('accepts a versioned published snapshot and rejects duplicate routes', () => {
+    expect(publishedDocuments(published).map((doc) => doc.slug)).toEqual(['one']);
+    expect(() => publishedDocuments({ ...published, documents: [...published.documents, { ...published.documents[0], id: 'two' }] })).toThrow('Duplicate');
+    const alternateLocale = supportedLocales.find((locale) => locale !== 'en');
+    expect(publishedDocuments({ ...published, version: 3, documents: alternateLocale ? [...published.documents, { ...published.documents[0], locale: alternateLocale }] : published.documents })).toHaveLength(alternateLocale ? 2 : 1);
+  });
+  it.each(['../secret', '/absolute', 'admin', 'admin/users', 'a//b', 'a?b'])('rejects reserved or invalid slug %s', (slug) => {
+    expect(() => publishedDocuments({ ...published, documents: [{ ...published.documents[0], slug }] })).toThrow();
+  });
+});
+
+describe('Tiptap renderer', () => {
+  it('renders basic text, links, media and Docs blocks without executing content', () => {
+    const markdown = renderDocumentContent({ type: 'doc', content: [
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Guide', marks: [{ type: 'bold' }] }] },
+      { type: 'paragraph', content: [{ type: 'text', text: 'Read ', marks: [] }, { type: 'text', text: 'this', marks: [{ type: 'link', attrs: { href: '/guide' } }] }] },
+      { type: 'image', attrs: { src: '/media/image.png', alt: 'Image' } },
+      { type: 'callout', attrs: { title: 'Note' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Safe.' }] }] },
+    ] });
+    expect(markdown).toContain('## **Guide**');
+    expect(markdown).toContain('[this](/guide)');
+    expect(markdown).toContain('![Image](/media/image.png)');
+    expect(markdown).toContain(':::note[Note]');
+  });
+  it('rejects unknown nodes and unsafe URLs instead of silently dropping them', () => {
+    expect(() => renderDocumentContent({ type: 'doc', content: [{ type: 'script' }] })).toThrow('Unsupported');
+    expect(() => renderDocumentContent({ type: 'image', attrs: { src: 'javascript:alert(1)' } })).toThrow('Unsafe');
+    expect(() => renderDocumentContent({ type: 'image', attrs: { src: '/admin/api/media/object/media/example.png' } })).toThrow('MEDIA_PUBLIC_URL');
+  });
+  it('renders task lists and rules created by the Simple Editor toolbar', () => {
+    const markdown = renderDocumentContent({ type: 'doc', content: [
+      { type: 'taskList', content: [{ type: 'taskItem', attrs: { checked: true }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Install the CMS' }] }] }] },
+      { type: 'horizontalRule' },
+    ] });
+    expect(markdown).toContain('- [x] Install the CMS');
+    expect(markdown).toContain('---');
+  });
+  it('uses the supported CMS node set inside the generated Starlight shell', () => {
+    const html = renderPreviewContent({ type: 'doc', content: [
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Draft <guide>' }] },
+      { type: 'paragraph', content: [{ type: 'text', text: 'Read ', marks: [] }, { type: 'text', text: 'this', marks: [{ type: 'link', attrs: { href: '/guide' } }] }] },
+      { type: 'callout', attrs: { title: 'Note' }, content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Safe.' }] }] },
+    ] });
+    expect(html).toContain('<h2 id="draft-guide">Draft &lt;guide&gt;</h2>');
+    expect(html).toContain('<a href="/guide">this</a>');
+    expect(html).toContain('starlight-aside--note');
+    expect(() => renderPreviewContent({ type: 'doc', content: [{ type: 'script' }] })).toThrow('Unsupported');
+    expect(() => renderPreviewContent({ type: 'doc', content: [{ type: 'image', attrs: { src: 'javascript:alert(1)' } }] })).toThrow('Unsafe');
+  });
+  it('derives stable heading anchors and nested TOC entries from the same saved document', () => {
+    const preview = renderPreviewDocument({ type: 'doc', content: [
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Getting Started' }] },
+      { type: 'heading', attrs: { level: 3 }, content: [{ type: 'text', text: 'Install' }] },
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Getting Started' }] },
+      { type: 'heading', attrs: { level: 4 }, content: [{ type: 'text', text: 'Ignored' }] },
+    ] });
+    expect(preview.html).toContain('<h2 id="getting-started">Getting Started</h2>');
+    expect(preview.html).toContain('<h2 id="getting-started-1">Getting Started</h2>');
+    expect(preview.headings.map(({ id }) => id)).toEqual(['getting-started', 'install', 'getting-started-1', 'ignored']);
+    const toc = renderPreviewTocItems(preview.headings, 2, 3, 'toc');
+    expect(toc).toContain('href="#getting-started"');
+    expect(toc).toContain('href="#install"');
+    expect(toc).toContain('style="--depth: 1;"');
+    expect(toc).not.toContain('ignored');
+  });
+});

package/template/test-files/deploy-hook.test.template.ts

@@ -0,0 +1,32 @@
+import { expect, it, vi } from 'vitest';
+import { triggerDeployHook } from '../src/publish/deploy-hook.ts';
+
+const url = 'https://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/test-hook';
+it('POSTs a hook using Cloudflare’s documented request shape', async () => {
+  const request = vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 202 }));
+  await triggerDeployHook(url, request);
+  expect(request).toHaveBeenCalledWith(url, { method: 'POST' });
+});
+it('returns the build identifier when the hook accepts the request', async () => {
+  const request = vi.fn<typeof fetch>().mockResolvedValue(Response.json({ result: { build_uuid: 'build-123', already_exists: true } }, { status: 202 }));
+  await expect(triggerDeployHook(url, request)).resolves.toEqual({ buildId: 'build-123', alreadyExists: true });
+});
+it('reports rejected hooks', async () => {
+  const request = vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 429 }));
+  await expect(triggerDeployHook(url, request)).rejects.toThrow('429');
+});
+it('does not expose secret URLs from network errors', async () => {
+  const request = vi.fn<typeof fetch>().mockRejectedValue(new Error(`failed: ${url}`));
+  await expect(triggerDeployHook(url, request)).rejects.toThrow(/^Workers Deploy Hook transport failed$/);
+});
+it('reports a safe network category for TypeError fetch failures', async () => {
+  const request = vi.fn<typeof fetch>().mockRejectedValue(new TypeError(`failed: ${url}`));
+  await expect(triggerDeployHook(url, request)).rejects.toThrow(/^Workers Deploy Hook network request failed$/);
+});
+it.each(['http://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/test',
+  'https://evil.example/hook', `${url}?secret=value`, 'https://api.cloudflare.com/client/v4/pages/hook'])
+('rejects wrong destinations without a request: %s', async (invalid) => {
+  const request = vi.fn<typeof fetch>();
+  await expect(triggerDeployHook(invalid, request)).rejects.toThrow();
+  expect(request).not.toHaveBeenCalled();
+});

package/template/test-files/media.test.template.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { contentReferencesMediaObject, signatureMatches } from '../src/media/service.ts';
+
+describe('media signatures', () => {
+  it.each([
+    ['image/png', [0x89, 0x50, 0x4e, 0x47]],
+    ['image/jpeg', [0xff, 0xd8, 0xff]],
+    ['image/webp', [0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0, 0x57, 0x45, 0x42, 0x50]],
+    ['image/avif', [0, 0, 0, 0, 0x66, 0x74, 0x79, 0x70]],
+    ['video/mp4', [0, 0, 0, 0, 0x66, 0x74, 0x79, 0x70]],
+    ['video/webm', [0x1a, 0x45, 0xdf, 0xa3]],
+  ])('accepts a valid %s header', (type, bytes) => {
+    expect(signatureMatches(type, new Uint8Array(bytes))).toBe(true);
+  });
+  it('rejects mismatched bytes', () => {
+    expect(signatureMatches('video/mp4', new Uint8Array([0x89, 0x50, 0x4e, 0x47]))).toBe(false);
+  });
+});
+
+describe('media references', () => {
+  const key = 'media/example.png';
+
+  it('finds image and video references in Tiptap JSON', () => {
+    expect(contentReferencesMediaObject(JSON.stringify({ type: 'doc', content: [
+      { type: 'image', attrs: { src: 'https://media.example/media/example.png' } },
+      { type: 'video', attrs: { src: '/admin/api/media/object/media/example.png' } },
+    ] }), key)).toBe(true);
+  });
+
+  it('does not treat plain text as a media reference', () => {
+    expect(contentReferencesMediaObject(JSON.stringify({ type: 'doc', content: [
+      { type: 'paragraph', content: [{ type: 'text', text: 'media/example.png' }] },
+    ] }), key)).toBe(false);
+  });
+
+  it('retains media when historic content is invalid', () => {
+    expect(contentReferencesMediaObject('{broken', key)).toBe(true);
+  });
+});

package/template/test-files/publishing.integration.test.template.ts

@@ -0,0 +1,156 @@
+import { afterAll, beforeAll, expect, it } from 'vitest';
+import { build } from 'esbuild';
+import { Miniflare, convertV4MiniflareOptions } from 'miniflare';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readFile, mkdtemp, rm, access } from 'node:fs/promises';
+import { z } from 'zod';
+import { publishedDocuments } from '../src/starlight/schema.ts';
+import { cmsSidebar } from '../src/starlight/sidebar.ts';
+import { supportedLocales } from '../src/locales.ts';
+
+let mf: Miniflare;
+let output: string;
+const previewShell = `<!doctype html><html><head><title>Preview</title><meta name="description" content=""><meta property="og:title" content="Preview"><link rel="canonical" href="https://example.test/cms-preview-shell/"></head><body><starlight-lang-select>Language</starlight-lang-select><h1 id="_top">Preview</h1><mobile-starlight-toc data-min-h="2" data-max-h="3"><ul class="isMobile toc"><li>Overview</li></ul></mobile-starlight-toc><starlight-toc data-min-h="2" data-max-h="3"><ul class="toc"><li>Overview</li></ul></starlight-toc><div class="sl-markdown-content"><div id="cms-preview-content"></div></div></body></html>`;
+beforeAll(async () => {
+  output = await mkdtemp(join(tmpdir(), 'cms-publish-test-'));
+  const bundle = await build({ entryPoints: ['src/index.ts'], loader: { '.sql': 'text' }, bundle: true, write: false, format: 'esm', platform: 'browser', target: 'es2022' });
+  mf = new Miniflare(convertV4MiniflareOptions({ workers: [{ name: 'cms-test', modules: true, script: bundle.outputFiles[0]!.text, compatibilityDate: '2026-09-09', compatibilityFlags: ['nodejs_compat'], d1Databases: ['DB'], r2Buckets: ['MEDIA'], serviceBindings: { ASSETS: () => new Response(previewShell, { headers: { 'Content-Type': 'text/html; charset=utf-8' } }) } }] }));
+  const db = await mf.getD1Database('DB');
+  // An incompatible pre-existing table must fail closed, without recording
+  // a completed migration. Repairing this disposable test DB permits retry.
+  await db.prepare('CREATE TABLE folder (id TEXT PRIMARY KEY)').run();
+  expect((await mf.dispatchFetch('http://localhost/admin/export/snapshot')).status).toBe(503);
+  expect((await db.prepare('SELECT name FROM d1_migrations').all()).results).toHaveLength(0);
+  await db.prepare('DROP TABLE folder').run();
+  const responses = await Promise.all(Array.from({ length: 4 }, () => mf.dispatchFetch('http://localhost/admin/export/snapshot')));
+  for (const response of responses) expect(response.status).toBe(200);
+  expect((await db.prepare('SELECT name FROM d1_migrations').all()).results).toHaveLength(2);
+}, 30000);
+afterAll(async () => { await mf?.dispose(); if (output) await rm(output, { recursive: true, force: true }); });
+
+async function request(path: string, method = 'GET', body?: unknown) {
+  const response = await mf.dispatchFetch(`http://localhost/admin/${path}`, {
+    method, headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'cloudflare-starlight-cms' },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  if (!response.ok) throw new Error(`${method} ${path}: ${response.status} ${await response.text()}`);
+  return response.status === 204 ? null : response.json();
+}
+async function buildDocs() {
+  const endpoint = new URL('/admin/export/snapshot', await mf.ready).href;
+  await promisify(execFile)(process.execPath, ['node_modules/astro/bin/astro.mjs', 'build', '--outDir', output], {
+    env: { ...process.env, CMS_EXPORT_URL: endpoint }, maxBuffer: 4 * 1024 * 1024,
+  });
+}
+const identity = z.object({ id: z.string(), version: z.number() });
+const hasJapanese = (supportedLocales as readonly string[]).includes('ja');
+
+it('redirects the bare admin path to the Access-protected admin path', async () => {
+  const response = await mf.dispatchFetch('http://localhost/admin', { redirect: 'manual' });
+  expect(response.status).toBe(302);
+  expect(response.headers.get('location')).toBe('/admin/');
+});
+
+it('serves a saved Draft in the generated Starlight preview shell without requesting a build', async () => {
+  const page = identity.parse(await request('api/documents', 'POST', {
+    title: 'Draft <title>', slug: 'preview-document', folderId: null, order: 0, description: 'Draft description',
+    contentJson: { type: 'doc', content: [
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Draft section' }] },
+      { type: 'paragraph', content: [{ type: 'text', text: 'Draft <body>' }] },
+    ] },
+  }));
+  const response = await mf.dispatchFetch(`http://localhost/admin/preview/${page.id}?locale=en`);
+  expect(response.status).toBe(200);
+  expect(response.headers.get('cache-control')).toBe('private, no-store');
+  expect(response.headers.get('x-robots-tag')).toBe('noindex, nofollow');
+  const html = await response.text();
+  expect(html).toContain('<title>Draft &lt;title&gt; | Preview</title>');
+  expect(html).toContain('<h1 id="_top">Draft &lt;title&gt;</h1>');
+  expect(html).toContain('<h2 id="draft-section">Draft section</h2>');
+  expect(html).toContain('<p>Draft &lt;body&gt;</p>');
+  expect(html).toContain('<div id="cms-preview-content"><h2 id="draft-section">Draft section</h2><p>Draft &lt;body&gt;</p></div>');
+  expect(html).toContain('href="#draft-section"');
+  expect(html).not.toContain('Overview');
+  expect(html).not.toContain('canonical');
+  expect(html).not.toContain('starlight-lang-select');
+});
+
+it('keeps drafts private and exports folder labels/order; records public moves and deletion', async () => {
+  const folder = z.object({ id: z.string() }).parse(await request('api/folders', 'POST', { name: 'Getting Started', slug: 'guides', order: 3 }));
+  const input = { title: 'Install', slug: 'install', folderId: folder.id, order: 0, description: '', contentJson: { type: 'doc', content: [
+    { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Install steps' }] },
+    { type: 'paragraph', content: [{ type: 'text', text: 'Public text' }] },
+  ] } };
+  let page = identity.parse(await request('api/documents', 'POST', input));
+  expect(publishedDocuments(await request('export/snapshot'))).toEqual([]);
+  const result = z.object({ document: identity }).parse(await request(`api/documents/${page.id}/publish`, 'POST', { version: page.version }));
+  page = result.document;
+  const published = await request('export/snapshot');
+  expect(cmsSidebar(published)[0]?.label).toBe('Getting Started');
+  await buildDocs();
+  await access(join(output, 'cms-preview-shell/index.html'));
+  if (hasJapanese) await access(join(output, 'ja/cms-preview-shell/index.html'));
+  const publicPage = await readFile(join(output, 'guides/install/index.html'), 'utf8');
+  expect(publicPage).toContain('Getting Started');
+  expect(publicPage).toContain('id="install-steps"');
+  if (hasJapanese) expect(await readFile(join(output, 'ja/guides/install/index.html'), 'utf8')).toContain('Public text');
+  await access(join(output, 'pagefind/pagefind.js'));
+  page = identity.parse(await request(`api/documents/${page.id}`, 'PUT', { ...input, title: 'Draft title', version: page.version }));
+  expect(await request('export/snapshot')).toEqual(published);
+  // A rejected save must not rename the published URL either.
+  const conflict = await mf.dispatchFetch(`http://localhost/admin/api/documents/${page.id}`, { method: 'PUT', headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'cloudflare-starlight-cms' }, body: JSON.stringify({ ...input, slug: 'wrong', version: page.version - 1 }) });
+  expect(conflict.status).toBe(409);
+  expect(await request('export/snapshot')).toEqual(published);
+  await request('api/tree/children', 'PUT', { parentId: null, childIds: [`document:${page.id}`] });
+  expect(publishedDocuments(await request('export/snapshot'))[0]?.slug).toBe('install');
+  await buildDocs();
+  await access(join(output, 'install/index.html'));
+  await expect(access(join(output, 'guides/install/index.html'))).rejects.toThrow();
+  await request(`api/documents/${page.id}`, 'DELETE', { version: page.version });
+  expect(publishedDocuments(await request('export/snapshot'))).toEqual([]);
+  const db = await mf.getD1Database('DB');
+  const changes = await db.prepare("SELECT count(*) AS count FROM publish_delivery WHERE trigger_kind='site'").first<{ count: number }>();
+  expect(changes?.count).toBe(2);
+  await buildDocs();
+  await expect(access(join(output, 'install/index.html'))).rejects.toThrow();
+}, 30000);
+
+it('recovers an interrupted delivery but rejects a retry while a sender holds the lease', async () => {
+  const db = await mf.getD1Database('DB');
+  await db.batch([
+    db.prepare("INSERT INTO publish_delivery (id,trigger_kind,status,attempts,requested_at,next_retry_at) VALUES ('stale','site','pending',1,?,?)").bind(Date.now()-60000, Date.now()-1000),
+    db.prepare("INSERT INTO publish_delivery (id,trigger_kind,status,attempts,requested_at,next_retry_at) VALUES ('active','site','pending',1,?,?)").bind(Date.now(), Date.now()+30000),
+  ]);
+  const response = z.object({ delivery: z.object({ status: z.string(), attempts: z.number() }) }).parse(await request('api/publish/deliveries/stale/retry', 'POST'));
+  expect(response.delivery).toMatchObject({ status: 'skipped', attempts: 2 });
+  const active = await mf.dispatchFetch('http://localhost/admin/api/publish/deliveries/active/retry', { method: 'POST', headers: { 'X-Requested-With': 'cloudflare-starlight-cms' } });
+  expect(active.status).toBe(409);
+});
+
+it('deletes only media that is absent from drafts, published pages, and revisions', async () => {
+  const db = await mf.getD1Database('DB');
+  const now = Date.now();
+  const unused = { id: '00000000-0000-4000-8000-000000000001', objectKey: 'media/00000000-0000-4000-8000-000000000001.png' };
+  await db.prepare('INSERT INTO media (id, object_key, file_name, content_type, size, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+    .bind(unused.id, unused.objectKey, 'unused.png', 'image/png', 4, now).run();
+  const deleted = await mf.dispatchFetch(`http://localhost/admin/api/media/${unused.id}`, {
+    method: 'DELETE', headers: { 'X-Requested-With': 'cloudflare-starlight-cms' },
+  });
+  expect(deleted.status).toBe(204);
+
+  const used = { id: '00000000-0000-4000-8000-000000000002', objectKey: 'media/00000000-0000-4000-8000-000000000002.png' };
+  await db.prepare('INSERT INTO media (id, object_key, file_name, content_type, size, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+    .bind(used.id, used.objectKey, 'used.png', 'image/png', 4, now).run();
+  await request('api/documents', 'POST', {
+    title: 'Media reference', slug: 'media-reference', folderId: null, order: 0, description: '',
+    contentJson: { type: 'doc', content: [{ type: 'image', attrs: { src: `/admin/api/media/object/${used.objectKey}` } }] },
+  });
+  const rejected = await mf.dispatchFetch(`http://localhost/admin/api/media/${used.id}`, {
+    method: 'DELETE', headers: { 'X-Requested-With': 'cloudflare-starlight-cms' },
+  });
+  expect(rejected.status).toBe(409);
+  expect(await rejected.json()).toMatchObject({ error: expect.stringContaining('still used') });
+});

package/template/tsconfig.admin.json

@@ -0,0 +1,18 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/admin/*"]
+    }
+  },
+  "include": [
+    "src/admin/**/*.ts",
+    "src/admin/**/*.tsx",
+    "src/scss.d.ts",
+    "worker-configuration.d.ts"
+  ],
+  "exclude": []
+}

package/template/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "worker-configuration.d.ts"
+  ],
+  "exclude": [
+    "src/admin/**"
+  ]
+}