create-starlight-cms 0.9.0

package/template/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "cloudflare-starlight-cms",
+  "description": "A self-hosted documentation CMS for Astro Starlight, built on Cloudflare Workers, D1, R2, and Access.",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "astro build && node scripts/build-admin.mjs",
+    "build:empty": "CMS_INITIAL_EMPTY=1 npm run build",
+    "dev": "node scripts/dev.mjs",
+    "check": "CMS_INITIAL_EMPTY=1 astro check && tsc --noEmit && npm run check:admin && npm run check:linux-lock",
+    "check:admin": "tsc -p tsconfig.admin.json --noEmit",
+    "check:linux-lock": "node scripts/check-linux-bindings.mjs",
+    "test": "vitest run",
+    "migrate:local": "wrangler d1 migrations apply DB --local",
+    "migrate:remote": "wrangler d1 migrations apply DB --remote",
+    "deploy": "wrangler deploy",
+    "typegen": "wrangler types worker-configuration.d.ts --env-interface CloudflareBindings",
+    "dry-run": "wrangler deploy --dry-run"
+  },
+  "dependencies": {
+    "@astrojs/check": "0.9.10",
+    "@astrojs/starlight": "0.42.0",
+    "@floating-ui/react": "0.27.20",
+    "@headless-tree/core": "1.7.0",
+    "@headless-tree/react": "1.7.0",
+    "@radix-ui/react-dropdown-menu": "2.1.24",
+    "@radix-ui/react-popover": "1.1.23",
+    "@tiptap/core": "3.31.3",
+    "@tiptap/extension-find-and-replace": "3.31.3",
+    "@tiptap/extension-highlight": "3.31.3",
+    "@tiptap/extension-horizontal-rule": "3.31.3",
+    "@tiptap/extension-image": "3.31.3",
+    "@tiptap/extension-link": "3.31.3",
+    "@tiptap/extension-list": "3.31.3",
+    "@tiptap/extension-subscript": "3.31.3",
+    "@tiptap/extension-superscript": "3.31.3",
+    "@tiptap/extension-table": "3.31.3",
+    "@tiptap/extension-table-cell": "3.31.3",
+    "@tiptap/extension-table-header": "3.31.3",
+    "@tiptap/extension-table-row": "3.31.3",
+    "@tiptap/extension-text-align": "3.31.3",
+    "@tiptap/extension-typography": "3.31.3",
+    "@tiptap/extensions": "3.31.3",
+    "@tiptap/pm": "3.31.3",
+    "@tiptap/react": "3.31.3",
+    "@tiptap/starter-kit": "3.31.3",
+    "astro": "7.3.2",
+    "clsx": "2.1.1",
+    "drizzle-orm": "0.45.2",
+    "github-slugger": "2.0.0",
+    "hono": "4.13.7",
+    "lodash.throttle": "4.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-hotkeys-hook": "5.3.3",
+    "zod": "4.6.4"
+  },
+  "devDependencies": {
+    "@base-ui/react": "1.8.0",
+    "@types/lodash.throttle": "4.1.9",
+    "@types/node": "22.20.1",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "class-variance-authority": "0.7.1",
+    "esbuild": "0.28.2",
+    "miniflare": "5.20260908.0-alpha",
+    "sass-embedded": "1.104.0",
+    "typescript": "5.9.3",
+    "vitest": "5.0.0",
+    "wrangler": "4.130.0"
+  },
+  "optionalDependencies": {
+    "@astrojs/compiler-binding-linux-x64-gnu": "0.4.0",
+    "@bruits/satteri-linux-x64-gnu": "0.10.5",
+    "@esbuild/linux-x64": "0.28.1",
+    "@img/sharp-libvips-linux-x64": "1.3.1",
+    "@img/sharp-linux-x64": "0.35.2",
+    "@pagefind/linux-x64": "1.5.2",
+    "@rolldown/binding-linux-x64-gnu": "1.2.7",
+    "lightningcss-linux-x64-gnu": "1.33.0"
+  },
+  "cloudflareStarlightCms": {
+    "templateVersion": "0.9.0"
+  }
+}

package/template/scripts/build-admin.mjs

@@ -0,0 +1,38 @@
+import { build, context } from 'esbuild';
+import { compile } from 'sass-embedded';
+import { fileURLToPath } from 'node:url';
+import { copyFile, mkdir } from 'node:fs/promises';
+
+const assetDirectory = process.env.ADMIN_ASSETS_DIR ?? 'dist';
+await mkdir(`${assetDirectory}/admin`, { recursive: true });
+await copyFile('src/assets/favicon.svg', `${assetDirectory}/favicon.svg`);
+
+const sassPlugin = {
+  name: 'sass',
+  setup(buildContext) {
+    buildContext.onLoad({ filter: /\.scss$/ }, (args) => {
+      const result = compile(args.path, { style: 'compressed', loadPaths: ['src/admin'] });
+      return { contents: result.css, loader: 'css', watchFiles: result.loadedUrls.filter((url) => url.protocol === 'file:').map(fileURLToPath) };
+    });
+  },
+};
+
+const options = {
+  entryPoints: ['src/admin/client.tsx'],
+  bundle: true,
+  format: 'esm',
+  jsx: 'automatic',
+  loader: { '.svg': 'dataurl' },
+  outfile: `${assetDirectory}/admin/app.js`,
+  alias: { '@': './src/admin' },
+  plugins: [sassPlugin],
+};
+if (process.argv.includes('--watch')) {
+  const buildContext = await context(options);
+  await buildContext.watch();
+  const stop = async () => { await buildContext.dispose(); };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+} else {
+  await build(options);
+}

package/template/scripts/check-linux-bindings.mjs

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+
+const lock = JSON.parse(await readFile(new URL('../package-lock.json', import.meta.url), 'utf8'));
+const packages = lock.packages ?? {};
+const linuxX64 = /linux-x64(?:-(?:gnu|glibc))?$/;
+const missing = new Set();
+
+for (const pkg of Object.values(packages)) {
+  for (const name of Object.keys(pkg.optionalDependencies ?? {})) {
+    if (linuxX64.test(name) && !packages[`node_modules/${name}`]) missing.add(name);
+  }
+}
+
+if (missing.size > 0) {
+  throw new Error(`package-lock.json is missing Linux x64 native bindings: ${[...missing].sort().join(', ')}. Add the matching package as an exact optionalDependency and regenerate the lockfile.`);
+}
+
+console.log('Linux x64 native bindings are present in package-lock.json.');

package/template/scripts/dev.mjs

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+
+const cmsPort = Number(process.env.CMS_PORT ?? 8787);
+const docsPort = Number(process.env.DOCS_PORT ?? 4321);
+const cmsUrl = `http://127.0.0.1:${cmsPort}/admin/export/snapshot`;
+const children = new Set();
+let stopping = false;
+let timer;
+
+function stop() {
+  stopping = true;
+  clearTimeout(timer);
+  for (const child of children) child.kill('SIGTERM');
+}
+function start(command, args, env = process.env) {
+  const child = spawn(command, args, { stdio: 'inherit', env });
+  children.add(child);
+  child.once('exit', () => children.delete(child));
+  return child;
+}
+function run(command, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = start(command, args, env);
+    child.once('error', reject);
+    child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`${command} exited with ${code}`)));
+  });
+}
+function server(command, args, env) {
+  const child = start(command, args, env);
+  const failed = (message) => {
+    if (stopping) return;
+    console.error(message);
+    process.exitCode = 1;
+    stop();
+  };
+  child.once('error', (error) => failed(error.message));
+  child.once('exit', () => failed(`${command} stopped unexpectedly`));
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function snapshot() {
+  const response = await fetch(cmsUrl, { signal: AbortSignal.timeout(5000) });
+  if (!response.ok) throw new Error(`CMS export returned ${response.status}`);
+  return response.text();
+}
+async function ready() {
+  for (let attempt = 0; attempt < 60 && !stopping; attempt++) {
+    try { return await snapshot(); } catch { await wait(500); }
+  }
+  throw new Error('Local CMS did not become ready');
+}
+const cli = (name) => `node_modules/${name}/bin/${name === 'wrangler' ? 'wrangler.js' : 'astro.mjs'}`;
+async function build() {
+  await run(process.execPath, [cli('astro'), 'build'], { ...process.env, CMS_EXPORT_URL: cmsUrl });
+  // Match production: both public and Admin assets are served from the configured
+  // Static Assets directory. Astro clears dist, so recreate the Admin bundle after it.
+  await run(process.execPath, ['scripts/build-admin.mjs']);
+}
+process.once('SIGINT', stop);
+process.once('SIGTERM', stop);
+
+try {
+  if (![cmsPort, docsPort].every((port) => Number.isInteger(port) && port > 0 && port < 65536) || cmsPort === docsPort) throw new Error('CMS_PORT and DOCS_PORT must be distinct valid ports');
+  // Local development always uses Miniflare state. Applying migrations is idempotent
+  // and avoids a separate first-run command without touching a remote D1 database.
+  await run(process.execPath, [cli('wrangler'), 'd1', 'migrations', 'apply', 'DB', '--local'], { ...process.env, CI: '1' });
+  await run(process.execPath, ['scripts/build-admin.mjs']);
+  server(process.execPath, ['scripts/build-admin.mjs', '--watch']);
+  server(process.execPath, [cli('wrangler'), 'dev', '--local', '--log-level', 'warn', '--port', String(cmsPort), '--var', 'LOCAL_DEV_BUILD:true']);
+  let completed = await ready();
+  if (stopping) throw new Error('Development server stopped');
+  await build();
+  if (stopping) throw new Error('Development server stopped');
+  server(process.execPath, [cli('astro'), 'preview', '--ignore-lock', '--host', '127.0.0.1', '--port', String(docsPort)], { ...process.env, ASTRO_PREVIEW_BACKGROUND: 'false' });
+  console.log(`Admin: http://127.0.0.1:${cmsPort}/admin/\nPublished docs: http://127.0.0.1:${docsPort}/`);
+  let failed;
+  async function poll() {
+    try {
+      const next = await snapshot();
+      if (next !== completed && next !== failed && !stopping) {
+        console.log('Published content changed. Building docs…');
+        try { await build(); completed = next; failed = undefined; console.log('Docs rebuilt. Refresh the public page.'); }
+        catch (error) { failed = next; throw error; }
+      }
+    } catch (error) {
+      if (!stopping) console.error('Local build/export failed. Fix the error and restart dev, or publish a new change.', error.message);
+    } finally {
+      if (!stopping) timer = setTimeout(poll, 1000);
+    }
+  }
+  if (!stopping) timer = setTimeout(poll, 1000);
+} catch (error) {
+  if (!stopping) { console.error(error.message); process.exitCode = 1; }
+  stop();
+}

package/template/src/admin/admin.scss

@@ -0,0 +1,182 @@
+:root { color: var(--cms-text); background: var(--cms-bg); font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+* { box-sizing: border-box; }
+html, body, #admin-root { min-width: 320px; min-height: 100%; margin: 0; background: var(--cms-bg); }
+button, input, textarea { font: inherit; }
+button { cursor: pointer; }
+button:disabled { cursor: not-allowed; opacity: .55; }
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+
+.cms-shell { min-height: 100vh; color: var(--cms-text); background: var(--cms-bg); }
+.cms-topbar { position: sticky; top: 0; z-index: 30; display: flex; min-height: 64px; align-items: center; justify-content: space-between; gap: 1rem; padding: 0 1.5rem; background: color-mix(in srgb, var(--cms-surface) 94%, transparent); border-bottom: 1px solid var(--cms-border); backdrop-filter: blur(16px); }
+.cms-brand { display: inline-flex; align-items: center; gap: .65rem; color: var(--cms-text); font-size: .98rem; font-weight: 750; letter-spacing: -.02em; text-decoration: none; }
+.cms-brand-logo { display: block; width: auto; height: 2.25rem; max-width: min(15rem, 52vw); }
+.cms-brand-mark, .cms-empty-icon { display: grid; width: 30px; height: 30px; place-items: center; color: var(--cms-accent-foreground); background: var(--cms-accent); border-radius: 9px; box-shadow: 0 4px 10px var(--cms-focus-ring); }
+.cms-topbar-controls, .cms-actions { display: flex; align-items: center; justify-content: flex-end; }
+.cms-topbar-controls { gap: .7rem; }
+.cms-actions { min-width: 0; gap: .5rem; }
+.cms-theme-trigger { display: grid; width: 32px; height: 32px; place-items: center; padding: 0; color: var(--cms-text-muted); background: transparent; border: 1px solid var(--cms-border); border-radius: 7px; }
+.cms-theme-trigger:hover { color: var(--cms-text); background: var(--cms-hover); }
+.cms-theme-trigger svg { width: 1rem; height: 1rem; }
+.cms-status { padding: .25rem .55rem; border-radius: 999px; font-size: .72rem; font-weight: 700; line-height: 1.2; text-transform: capitalize; }
+.cms-status-draft, .cms-status-unsaved, .cms-sidebar .tree .treeitem-status.draft, .cms-sidebar .tree .treeitem-status.changes { color: var(--cms-warning-text); background: var(--cms-warning-subtle); }
+.cms-status-published { color: var(--cms-success-text); background: var(--cms-success-subtle); }
+.cms-notice { max-width: 19rem; overflow: hidden; color: var(--cms-text-muted); font-size: .78rem; text-overflow: ellipsis; white-space: nowrap; }
+.cms-notice.is-error { color: var(--cms-danger-text); }
+.cms-button, .cms-history-button { min-height: 34px; padding: .45rem .72rem; color: var(--cms-text-muted); background: var(--cms-elevated); border: 1px solid var(--cms-border); border-radius: 7px; box-shadow: 0 1px 2px var(--cms-shadow); font-size: .8rem; font-weight: 650; }
+.cms-button:hover:not(:disabled), .cms-history-button:hover { color: var(--cms-text); background: var(--cms-hover); }
+.cms-button-primary { color: var(--cms-accent-foreground); background: var(--cms-accent); border-color: var(--cms-accent); }
+.cms-button-primary:hover:not(:disabled) { color: var(--cms-accent-foreground); background: var(--cms-accent-hover); border-color: var(--cms-accent-hover); }
+.cms-button-quiet { background: transparent; box-shadow: none; }
+.cms-button-danger, .cms-button-danger-quiet { color: var(--cms-danger-text); background: var(--cms-danger-subtle); border-color: var(--cms-danger); }
+.cms-button-danger-quiet { background: transparent; border-color: transparent; box-shadow: none; }
+.cms-button-danger:hover:not(:disabled), .cms-button-danger-quiet:hover:not(:disabled) { color: var(--cms-danger-text); background: var(--cms-danger-subtle); border-color: var(--cms-danger); }
+
+.cms-workspace { display: grid; grid-template-columns: 250px minmax(0, 1fr); min-height: calc(100vh - 64px); }
+.cms-sidebar { position: sticky; top: 64px; display: flex; height: calc(100vh - 64px); flex-direction: column; gap: .85rem; padding: 1.1rem .8rem; overflow: hidden; background: var(--cms-surface); border-right: 1px solid var(--cms-border); }
+.cms-sidebar-heading { display: flex; align-items: center; justify-content: space-between; padding: 0 .35rem; color: var(--cms-text-muted); font-size: .82rem; font-weight: 750; }
+.cms-count { display: grid; min-width: 22px; height: 22px; place-items: center; color: var(--cms-accent); background: var(--cms-accent-subtle); border-radius: 999px; font-size: .72rem; }
+.cms-new-document, .cms-upload { color: var(--cms-accent-foreground); background: var(--cms-accent); border: 1px solid var(--cms-accent); border-radius: 7px; font-weight: 700; }
+.cms-new-document { width: 100%; padding: .62rem .72rem; box-shadow: 0 1px 2px var(--cms-shadow); font-size: .82rem; text-align: left; }
+.cms-new-document:hover { background: var(--cms-accent-hover); border-color: var(--cms-accent-hover); }
+.cms-new-document::before { margin-right: .45rem; content: "+"; font-size: 1rem; }
+.cms-navigation-actions { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: .45rem; }
+.cms-new-folder { padding: .62rem .72rem; color: var(--cms-text-muted); background: var(--cms-elevated); border: 1px solid var(--cms-border); border-radius: 7px; font-size: .78rem; font-weight: 700; }
+.cms-new-folder:hover { color: var(--cms-text); background: var(--cms-hover); }
+.cms-search input, .cms-title-input, .cms-description-input, .cms-slug-input, .cms-folder-fields input, .cms-folder-dialog input { width: 100%; color: var(--cms-text); background: var(--cms-input-bg); border: 1px solid var(--cms-border); outline: 0; }
+.cms-search input { padding: .56rem .65rem; border-radius: 7px; font-size: .78rem; }
+.cms-search input:focus, .cms-title-input:focus, .cms-description-input:focus, .cms-slug-input:focus, .cms-folder-fields input:focus, .cms-folder-dialog input:focus, .cms-content-locale select:focus { border-color: var(--cms-accent); box-shadow: 0 0 0 3px var(--cms-focus-ring); }
+.cms-document-list { display: grid; gap: .95rem; overflow: auto; padding: .15rem .15rem 1.5rem; }
+.cms-document-group { display: grid; gap: .15rem; }
+.cms-document-group h2 { margin: 0 0 .22rem; padding: 0 .35rem; color: var(--cms-text-muted); font-size: .68rem; font-weight: 750; letter-spacing: .08em; text-transform: uppercase; }
+.cms-document-item { display: grid; gap: .15rem; width: 100%; padding: .55rem .6rem; color: var(--cms-text-muted); background: transparent; border: 1px solid transparent; border-radius: 7px; text-align: left; }
+.cms-document-item:hover { background: var(--cms-hover); }
+.cms-document-item.is-active { color: var(--cms-accent); background: var(--cms-accent-subtle); border-color: var(--cms-accent); }
+.cms-document-item strong { overflow: hidden; color: inherit; font-size: .8rem; font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
+.cms-document-item span, .cms-empty-search { color: var(--cms-text-subtle); font-size: .68rem; }
+.cms-document-item.is-active span { color: var(--cms-accent); }
+.cms-empty-search { margin: 0; padding: .35rem; font-size: .78rem; }
+
+/* Adapted from Headless Tree's Comprehensive DnD story (MIT). */
+.navigation-tree-scroll { flex: 1 1 0; min-height: 12rem; overflow: auto; padding: 8px; }
+.cms-sidebar .tree { position: relative; display: block; min-height: 100%; max-width: none; }
+.cms-sidebar .tree button[role="treeitem"] { display: flex; width: 100%; padding: 0 0 2px; background: transparent; border: none; }
+.cms-sidebar .tree .treeitem { position: relative; display: flex; width: 100%; align-items: center; gap: .4rem; padding: 6px 10px; color: var(--cms-text-muted); background-color: var(--cms-surface); border-radius: 8px; font-size: .8rem; text-align: left; transition: background-color .2s ease; cursor: pointer; }
+.cms-sidebar .tree .treeitem-name { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cms-sidebar .tree .treeitem-status { margin-left: auto; padding: .12rem .34rem; border-radius: 999px; font-size: .6rem; font-weight: 750; line-height: 1.2; }
+.cms-sidebar .tree .treeitem:hover { background-color: var(--cms-hover); }
+.cms-sidebar .tree button[role="treeitem"]:focus { outline: none; }
+.cms-sidebar .tree .treeitem.selected, .cms-sidebar .tree .treeitem.drop { color: var(--cms-accent); background-color: var(--cms-accent-subtle); }
+.cms-sidebar .tree button:focus-visible .treeitem.focused { outline: 2px solid var(--cms-accent); outline-offset: 1px; }
+.cms-sidebar .tree .treeitem.folder::before { display: inline-block; z-index: 1; width: 10px; margin-right: 4px; content: "›"; color: var(--cms-text-subtle); font-size: .95rem; transition: transform .1s ease-in-out; }
+.cms-sidebar .tree .treeitem.folder.expanded::before { transform: rotate(90deg); }
+.cms-sidebar .tree .treeitem:not(.folder) { padding-left: 24px; }
+.cms-sidebar .tree .treeitem.selected::after { position: absolute; top: 5px; left: -2px; width: 4px; height: 16px; content: " "; background-color: var(--cms-accent); border-radius: 99px; }
+.cms-sidebar .tree .dragline { height: 2px; margin-top: -1px; background-color: var(--cms-accent); }
+.cms-sidebar .tree .dragline::before { box-sizing: content-box; position: absolute; top: -3px; left: 0; width: 4px; height: 4px; content: ""; background: var(--cms-surface); border: 2px solid var(--cms-accent); border-radius: 99px; }
+
+.cms-main { min-width: 0; padding: 1.35rem clamp(1rem, 3vw, 3.5rem) 3rem; }
+.cms-breadcrumb { display: flex; align-items: center; flex-wrap: wrap; gap: .35rem; margin: 0 0 1rem; color: var(--cms-text-muted); font-size: .76rem; }
+.cms-breadcrumb-item { display: inline-flex; align-items: center; min-width: 0; gap: .35rem; }
+.cms-breadcrumb-item svg { flex: 0 0 auto; width: .85rem; height: .85rem; color: var(--cms-text-subtle); }
+.cms-breadcrumb button { padding: 0; color: var(--cms-text-muted); background: transparent; border: 0; font: inherit; }
+.cms-breadcrumb button:hover { color: var(--cms-accent); text-decoration: underline; }
+.cms-breadcrumb strong { overflow: hidden; color: var(--cms-text); font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
+.cms-document-actions { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin: 0 0 1.1rem; padding-bottom: 1rem; border-bottom: 1px solid var(--cms-border); }
+.cms-document-state, .cms-document-action-buttons { display: flex; align-items: center; gap: .65rem; min-width: 0; }
+.cms-document-state > span:not(.cms-status) { overflow: hidden; color: var(--cms-text-muted); font-size: .76rem; text-overflow: ellipsis; white-space: nowrap; }
+.cms-history-button { display: inline-flex; align-items: center; gap: .35rem; }
+.cms-history-button svg { width: .9rem; height: .9rem; }
+.cms-history-button.is-active { color: var(--cms-accent); background: var(--cms-accent-subtle); border-color: var(--cms-accent); box-shadow: 0 0 0 3px var(--cms-focus-ring); }
+.cms-danger-zone { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin-top: 1.5rem; padding-top: 1.25rem; border-top: 1px solid var(--cms-danger); }
+.cms-danger-zone h2 { margin: 0; color: var(--cms-danger-text); font-size: .8rem; }
+.cms-danger-zone p { margin: .25rem 0 0; color: var(--cms-text-muted); font-size: .75rem; }
+.cms-editor-surface { width: 100%; min-width: 0; overflow: visible; }
+.cms-document-fields, .cms-folder-fields { display: grid; gap: .85rem; }
+.cms-content-locale { display: flex; width: fit-content; align-items: center; gap: .5rem; color: var(--cms-text-muted); font-size: .72rem; font-weight: 700; }
+.cms-content-locale select { height: 30px; padding: 0 .45rem; color: var(--cms-text); background: var(--cms-input-bg); border: 1px solid var(--cms-border); border-radius: 6px; font-size: .74rem; font-weight: 650; }
+.cms-meta-field { display: grid; gap: .55rem; }
+.cms-meta-field > span, .cms-editor-field-header > span { color: var(--cms-text-muted); font-size: .72rem; font-weight: 700; letter-spacing: .02em; }
+.cms-title-input, .cms-description-input, .cms-slug-input { border-radius: 8px; box-shadow: 0 1px 2px var(--cms-shadow); }
+.cms-title-input { padding: .85rem .95rem; font-size: clamp(1.45rem, 3vw, 2rem); font-weight: 750; line-height: 1.2; }
+.cms-title-input::placeholder, .cms-description-input::placeholder { color: var(--cms-text-subtle); }
+.cms-description-input { display: block; min-height: 5rem; padding: .75rem .95rem; resize: vertical; font: inherit; font-size: .95rem; line-height: 1.5; }
+.cms-slug-input { padding: .65rem .8rem; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .88rem; }
+.cms-field-help { color: var(--cms-text-subtle); font-size: .72rem; line-height: 1.4; }
+.cms-editor-field { display: grid; gap: .55rem; margin-top: 1.35rem; }
+.cms-editor-field-header { display: flex; align-items: center; justify-content: space-between; }
+
+/* Tiptap's official template supplies its editor UI. This wrapper only fits it into the CMS. */
+.cms-simple-editor { overflow: hidden; background: var(--cms-surface); border: 1px solid var(--cms-border); border-radius: 10px; }
+.cms-simple-editor .simple-editor-wrapper { position: relative; width: 100%; height: min(720px, calc(100vh - 220px)); min-height: 560px; overflow: auto; }
+.cms-simple-editor .simple-editor-content { max-width: 54rem; }
+.cms-simple-editor .simple-editor-search-and-replace { position: absolute; top: .5rem; right: .5rem; }
+.cms-simple-editor .tiptap-toolbar { top: 0; }
+.cms-simple-editor .tiptap.ProseMirror.simple-editor img, .cms-simple-editor .tiptap.ProseMirror.simple-editor video { display: block; max-width: 100%; height: auto; margin: 1.25rem 0; border-radius: 8px; }
+.cms-simple-editor .tiptap.ProseMirror.simple-editor aside[data-callout] { margin: 1.25rem 0; padding: 1rem 1.1rem; background: var(--cms-accent-subtle); border-left: 3px solid var(--cms-accent); border-radius: 0 8px 8px 0; }
+.cms-simple-editor .tiptap.ProseMirror.simple-editor ol[data-steps] { padding: 1rem 1rem 1rem 2.25rem; background: var(--cms-hover); border-radius: 8px; }
+.cms-simple-editor .tiptap.ProseMirror.simple-editor section[data-tabs] { padding: 1rem; border: 1px solid var(--cms-border); border-radius: 8px; }
+.cms-simple-editor .tiptap.ProseMirror.simple-editor section[data-tab] + section[data-tab] { margin-top: .75rem; padding-top: .75rem; border-top: 1px solid var(--cms-border); }
+
+.cms-close-settings { display: grid; width: 28px; height: 28px; place-items: center; padding: 0; color: var(--cms-text-muted); background: transparent; border: 0; border-radius: 5px; font-size: 1.2rem; }
+.cms-close-settings:hover { background: var(--cms-hover); }
+.cms-revision-backdrop { position: fixed; z-index: 100; inset: 0; display: flex; align-items: flex-start; justify-content: flex-end; padding: 5rem 1.5rem 1.5rem; background: var(--cms-backdrop); }
+.cms-revision-drawer { display: flex; flex-direction: column; gap: 1rem; width: min(25rem, 100%); max-height: min(34rem, calc(100vh - 6.5rem)); padding: 1.25rem; overflow: hidden; color: var(--cms-text); background: var(--cms-elevated); border: 1px solid var(--cms-border); border-radius: .75rem; box-shadow: -16px 0 36px var(--cms-shadow); }
+.cms-revision-drawer > header, .cms-folder-panel > header, .cms-folder-dialog header, .cms-media-dialog header { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; }
+.cms-revision-drawer h2 { margin: 0; color: var(--cms-text); font-size: 1rem; }
+.cms-revision-drawer header p, .cms-revisions-empty { margin: .3rem 0 0; color: var(--cms-text-muted); font-size: .78rem; line-height: 1.45; }
+.cms-revisions { display: grid; gap: .45rem; }
+.cms-revision-drawer .cms-revisions { overflow: auto; padding-right: .2rem; }
+.cms-revisions > p { margin: 0; color: var(--cms-text-subtle); font-size: .75rem; }
+.cms-revision { display: flex; align-items: center; justify-content: space-between; gap: .5rem; padding: .5rem; background: var(--cms-bg); border: 1px solid var(--cms-border); border-radius: 6px; }
+.cms-revision span { display: grid; gap: .12rem; min-width: 0; color: var(--cms-text-muted); font-size: .7rem; }
+.cms-revision time { overflow: hidden; color: var(--cms-text-subtle); font-size: .65rem; text-overflow: ellipsis; white-space: nowrap; }
+.cms-revision button { padding: .25rem .35rem; color: var(--cms-accent); background: var(--cms-surface); border: 1px solid var(--cms-accent); border-radius: 5px; font-size: .68rem; font-weight: 650; }
+
+.cms-empty-state { display: grid; justify-items: center; gap: .75rem; max-width: 440px; margin: 18vh auto; color: var(--cms-text-muted); text-align: center; }
+.cms-empty-state .cms-empty-icon { width: 42px; height: 42px; font-size: 1.1rem; }
+.cms-empty-state h1 { margin: .35rem 0 0; color: var(--cms-text); font-size: 1.35rem; }
+.cms-empty-state p { margin: 0; font-size: .9rem; }
+.cms-empty-actions, .cms-folder-panel-actions { display: flex; flex-wrap: wrap; gap: .55rem; }
+.cms-folder-panel { display: grid; gap: 1.35rem; width: min(100%, 54rem); margin: 1.25rem auto; }
+.cms-folder-panel header p { margin: 0 0 .35rem; color: var(--cms-text-muted); font-size: .72rem; font-weight: 700; text-transform: uppercase; }
+.cms-folder-panel h1 { margin: 0; color: var(--cms-text); font-size: 1.75rem; letter-spacing: -.03em; }
+.cms-folder-panel header span { display: block; margin-top: .45rem; color: var(--cms-text-muted); font-size: .86rem; }
+.cms-folder-fields input, .cms-folder-dialog input { padding: .72rem .82rem; border-radius: 8px; }
+.cms-folder-panel > footer, .cms-folder-dialog footer { display: flex; align-items: center; justify-content: space-between; gap: .6rem; padding-top: 1rem; border-top: 1px solid var(--cms-border); }
+.cms-folder-dialog { display: grid; gap: 1rem; width: min(440px, 100%); padding: 1.25rem; color: var(--cms-text); background: var(--cms-elevated); border: 1px solid var(--cms-border); border-radius: 12px; box-shadow: 0 24px 48px var(--cms-shadow); }
+.cms-folder-dialog h1, .cms-media-dialog h1 { margin: 0; color: var(--cms-text); font-size: 1rem; }
+.cms-folder-dialog p, .cms-media-dialog p { margin: .3rem 0 0; color: var(--cms-text-muted); font-size: .78rem; }
+.cms-media-backdrop { position: fixed; z-index: 100; inset: 0; display: grid; place-items: center; padding: 1rem; background: var(--cms-backdrop); }
+.cms-media-dialog { width: min(760px, 100%); max-height: min(700px, 90vh); overflow: auto; padding: 1.25rem; background: var(--cms-elevated); border: 1px solid var(--cms-border); border-radius: 12px; box-shadow: 0 24px 48px var(--cms-shadow); }
+.cms-media-dialog-actions { display: flex; justify-content: flex-end; margin: 1rem 0; }
+.cms-upload { position: relative; display: inline-flex; overflow: hidden; padding: .48rem .64rem; }
+.cms-upload input { position: absolute; inset: 0; cursor: pointer; opacity: 0; }
+.cms-media-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(145px, 1fr)); gap: .75rem; }
+.cms-media-empty { grid-column: 1 / -1; padding: 2rem 0; text-align: center; }
+.cms-media-card { display: grid; gap: .4rem; min-width: 0; padding: .45rem; color: var(--cms-text-muted); background: var(--cms-surface); border: 1px solid var(--cms-border); border-radius: 8px; }
+.cms-media-insert { display: grid; gap: .35rem; min-width: 0; padding: 0; color: inherit; background: transparent; border: 0; text-align: left; }
+.cms-media-insert:hover .cms-media-preview { outline: 1px solid var(--cms-accent); box-shadow: 0 2px 7px var(--cms-focus-ring); }
+.cms-media-preview { display: grid; height: 96px; overflow: hidden; place-items: center; background: var(--cms-hover); border-radius: 5px; }
+.cms-media-preview img, .cms-media-preview video { width: 100%; height: 100%; object-fit: cover; }
+.cms-media-card strong { overflow: hidden; color: var(--cms-text); font-size: .72rem; font-weight: 700; text-overflow: ellipsis; white-space: nowrap; }
+.cms-media-insert > span:last-child { color: var(--cms-text-subtle); font-size: .65rem; }
+.cms-media-card footer { display: flex; align-items: center; justify-content: space-between; gap: .35rem; }
+.cms-media-usage { color: var(--cms-text-subtle); font-size: .65rem; }
+.cms-media-usage-used { color: var(--cms-success); }
+.cms-media-delete { padding: .18rem .35rem; color: var(--cms-danger); background: transparent; border: 1px solid var(--cms-border); border-radius: 4px; font-size: .65rem; }
+.cms-media-delete:hover:not(:disabled) { border-color: var(--cms-danger); background: var(--cms-danger-subtle); }
+
+@media (max-width: 720px) {
+  .cms-topbar { min-height: 58px; padding: 0 .85rem; }
+  .cms-actions { gap: .35rem; }
+  .cms-notice, .cms-button-quiet, .cms-status { display: none; }
+  .cms-workspace { grid-template-columns: 1fr; }
+  .cms-sidebar { position: static; height: auto; max-height: 255px; padding: .85rem; border-right: 0; border-bottom: 1px solid var(--cms-border); }
+  .cms-document-list { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .65rem; }
+  .cms-main { padding: 1rem .85rem 2rem; }
+  .cms-document-actions, .cms-danger-zone { align-items: flex-start; flex-direction: column; }
+  .cms-document-action-buttons { width: 100%; justify-content: flex-end; }
+  .cms-revision-backdrop { padding: 4rem .75rem .75rem; }
+  .cms-revision-drawer { max-height: calc(100vh - 4.75rem); }
+  .cms-simple-editor .simple-editor-wrapper { min-height: 450px; }
+}

package/template/src/admin/app.ts

@@ -0,0 +1,130 @@
+import { Hono, type Context, type MiddlewareHandler } from 'hono';
+import { ensureSchema } from '../db/bootstrap.ts';
+import { z } from 'zod';
+import { DocumentConflictError, DocumentNotFoundError, createDocument, createDocumentTranslation, deleteDocument, getDocument, listDocuments, listRevisions, restoreRevision, updateDocument } from '../documents/service.ts';
+import { InvalidMediaError, MediaInUseError, MediaNotFoundError, deleteUnusedMedia, listMedia, uploadMedia } from '../media/service.ts';
+import type { RuntimeEnv } from '../env.ts';
+import { defaultLocale, isSupportedLocale, type SupportedLocale } from '../locales.ts';
+import { publishedSnapshot } from '../starlight/snapshot.ts';
+import { adminHtml } from './html.ts';
+import { previewDocument } from './preview.ts';
+import { createFolder, createFolderTranslation, deleteFolder, FolderNotFoundError, listTree, NavigationConflictError, replaceTreeChildren, updateFolder } from '../navigation/service.ts';
+import { PublishDeliveryConflictError, PublishDeliveryNotFoundError, deliverPendingChanges, listPublishDeliveries, publishDocumentAndRequest, requestPublish, retryPublish } from '../publish/service.ts';
+
+type AdminEnv = { Bindings: RuntimeEnv };
+const app = new Hono<AdminEnv>();
+const jsonHeaders = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+const noStore = { 'Cache-Control': 'no-store' };
+
+function locale(c: Context<AdminEnv>): SupportedLocale {
+  const value = c.req.query('locale') ?? defaultLocale;
+  if (!isSupportedLocale(value)) throw new NavigationConflictError('Unsupported language');
+  return value;
+}
+
+function csrfAllowed(request: Request): boolean {
+  if (!['POST', 'PUT', 'DELETE'].includes(request.method)) return true;
+  const origin = request.headers.get('origin');
+  return request.headers.get('x-requested-with') === 'cloudflare-starlight-cms' &&
+    (!origin || origin === new URL(request.url).origin);
+}
+
+const csrf: MiddlewareHandler<AdminEnv> = async (c, next) => {
+  if (!csrfAllowed(c.req.raw)) return c.json({ error: 'Cross-site request rejected' }, 403, jsonHeaders);
+  await next();
+};
+
+
+app.onError((error, c) => {
+  if (error instanceof DocumentNotFoundError) return c.json({ error: 'Not found' }, 404, jsonHeaders);
+  if (error instanceof DocumentConflictError) return c.json({ error: error.message || 'The document changed. Reload it and try again.' }, 409, jsonHeaders);
+  if (error instanceof InvalidMediaError) return c.json({ error: error.message }, 400, jsonHeaders);
+  if (error instanceof MediaNotFoundError) return c.json({ error: 'Media not found' }, 404, jsonHeaders);
+  if (error instanceof MediaInUseError) return c.json({ error: error.message }, 409, jsonHeaders);
+  if (error instanceof FolderNotFoundError) return c.json({ error: 'Folder not found' }, 404, jsonHeaders);
+  if (error instanceof NavigationConflictError) return c.json({ error: error.message }, 409, jsonHeaders);
+  if (error instanceof PublishDeliveryNotFoundError) return c.json({ error: 'Build request not found' }, 404, jsonHeaders);
+  if (error instanceof PublishDeliveryConflictError) return c.json({ error: error.message }, 409, jsonHeaders);
+  if (error instanceof z.ZodError) return c.json({ error: 'Invalid request', details: error.issues }, 400, jsonHeaders);
+  console.error('Admin API error', error);
+  return c.json({ error: 'Request failed' }, 500, jsonHeaders);
+});
+
+app.use('/admin/*', async (c, next) => {
+  if (c.req.path.startsWith('/admin/api/') || c.req.path.startsWith('/admin/preview/') || c.req.path === '/admin/export/snapshot') {
+    try {
+      await ensureSchema(c.env.DB);
+    } catch {
+      return c.json({ error: 'Database initialization failed. Retry the request.' }, 503, { ...noStore, 'Retry-After': '5' });
+    }
+  }
+  await next();
+});
+app.get('/admin/export/snapshot', async (c) => c.json(await publishedSnapshot(c.env), 200, jsonHeaders));
+const adminHome = (c: Context<AdminEnv>) => {
+  return c.html(adminHtml(), 200, { 'Cache-Control': 'no-store' });
+};
+app.get('/admin', (c) => c.redirect('/admin/', 302));
+app.get('/admin/', adminHome);
+app.get('/admin/preview/:id', async (c) => previewDocument(c.env, c.req.raw, c.req.param('id'), locale(c)));
+app.get('/admin/app.js', (c) => c.env.ASSETS.fetch(c.req.raw));
+
+app.use('/admin/api/*', csrf);
+app.use('/admin/api/*', async (c, next) => {
+  await next();
+  if (!c.req.path.startsWith('/admin/api/media') && ['POST', 'PUT', 'DELETE'].includes(c.req.method) && c.res.status < 400) {
+    c.executionCtx.waitUntil(deliverPendingChanges(c.env));
+  }
+});
+app.get('/admin/api/tree', async (c) => c.json(await listTree(c.env, locale(c)), 200, jsonHeaders));
+app.post('/admin/api/folders', async (c) => c.json(await createFolder(c.env, await c.req.json(), locale(c)), 201, jsonHeaders));
+app.put('/admin/api/folders/:id', async (c) => c.json(await updateFolder(c.env, c.req.param('id'), await c.req.json(), locale(c)), 200, jsonHeaders));
+app.post('/admin/api/folders/:id/translations', async (c) => c.json(await createFolderTranslation(c.env, c.req.param('id'), locale(c), (await c.req.json<{ sourceLocale?: SupportedLocale }>()).sourceLocale ?? defaultLocale), 201, jsonHeaders));
+app.delete('/admin/api/folders/:id', async (c) => { await deleteFolder(c.env, c.req.param('id')); return new Response(null, { status: 204, headers: noStore }); });
+app.put('/admin/api/tree/children', async (c) => c.json(await replaceTreeChildren(c.env, await c.req.json()), 200, jsonHeaders));
+app.get('/admin/api/documents', async (c) => c.json(await listDocuments(c.env, locale(c)), 200, jsonHeaders));
+app.post('/admin/api/documents', async (c) => c.json(await createDocument(c.env, await c.req.json(), locale(c)), 201, jsonHeaders));
+app.post('/admin/api/documents/:id/translations', async (c) => c.json(await createDocumentTranslation(c.env, c.req.param('id'), locale(c), (await c.req.json<{ sourceLocale?: SupportedLocale }>()).sourceLocale ?? defaultLocale), 201, jsonHeaders));
+app.get('/admin/api/documents/:id', async (c) => c.json(await getDocument(c.env, c.req.param('id'), locale(c)), 200, jsonHeaders));
+app.put('/admin/api/documents/:id', async (c) => c.json(await updateDocument(c.env, c.req.param('id'), await c.req.json(), locale(c)), 200, jsonHeaders));
+app.delete('/admin/api/documents/:id', async (c) => {
+  const { version } = await c.req.json<{ version?: number }>();
+  if (!Number.isInteger(version)) return c.json({ error: 'version is required' }, 400, jsonHeaders);
+  await deleteDocument(c.env, c.req.param('id'), version!, locale(c));
+  return new Response(null, { status: 204, headers: noStore });
+});
+app.post('/admin/api/documents/:id/publish', async (c) => {
+  const { version } = await c.req.json<{ version?: number }>();
+  if (!Number.isInteger(version)) return c.json({ error: 'version is required' }, 400, jsonHeaders);
+  const result = await publishDocumentAndRequest(c.env, c.req.param('id'), version!, locale(c));
+  return c.json(result, 200, jsonHeaders);
+});
+app.post('/admin/api/publish/site', async (c) => c.json({ delivery: await requestPublish(c.env, 'site') }, 200, jsonHeaders));
+app.get('/admin/api/publish/deliveries', async (c) => c.json(await listPublishDeliveries(c.env), 200, jsonHeaders));
+app.post('/admin/api/publish/deliveries/:id/retry', async (c) => c.json({ delivery: await retryPublish(c.env, c.req.param('id')) }, 200, jsonHeaders));
+app.get('/admin/api/documents/:id/revisions', async (c) => c.json(await listRevisions(c.env, c.req.param('id'), locale(c)), 200, jsonHeaders));
+app.post('/admin/api/documents/:id/revisions/:revisionId/restore', async (c) => {
+  const { version } = await c.req.json<{ version?: number }>();
+  if (!Number.isInteger(version)) return c.json({ error: 'version is required' }, 400, jsonHeaders);
+  return c.json(await restoreRevision(c.env, c.req.param('id'), c.req.param('revisionId'), version!, locale(c)), 200, jsonHeaders);
+});
+app.get('/admin/api/media', async (c) => c.json(await listMedia(c.env), 200, jsonHeaders));
+app.post('/admin/api/media', async (c) => c.json(await uploadMedia(c.env, c.req.raw), 201, jsonHeaders));
+app.delete('/admin/api/media/:id', async (c) => {
+  await deleteUnusedMedia(c.env, c.req.param('id'));
+  return new Response(null, { status: 204, headers: noStore });
+});
+app.get('/admin/api/media/object/:key{.+}', async (c) => {
+  const key = c.req.param('key');
+  if (!/^media\/[a-z0-9-]+\.(png|jpg|webp|avif|mp4|webm)$/.test(key)) return c.json({ error: 'Not found' }, 404, jsonHeaders);
+  const object = await c.env.MEDIA.get(key);
+  if (!object) return c.json({ error: 'Not found' }, 404, jsonHeaders);
+  const headers = new Headers(noStore);
+  object.writeHttpMetadata(headers);
+  headers.set('ETag', object.httpEtag);
+  return new Response(object.body, { headers });
+});
+
+app.all('/admin/*', (c) => c.env.ASSETS.fetch(c.req.raw));
+
+export { app as adminApp };