create-starlight-cms 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloudflare-starlight-cms contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# create-starlight-cms
+
+Creates a self-hosted Astro Starlight documentation CMS for Cloudflare Workers.
+
+```sh
+npx create-starlight-cms@latest my-docs
+cd my-docs
+npm install
+npm run dev
+```
+
+Use `.` to create a project in the current empty directory. The CLI never installs dependencies, initializes Git, deploys, or accesses a Cloudflare account.
+
+The normalized project name also becomes the generated `wrangler.jsonc` Worker name. `DB` and `MEDIA` are binding-only definitions, so Cloudflare provisions the D1 database and R2 bucket on the first deployment.
+
+The generated project is an independent copy of the CMS template. Updating this CLI affects new projects only.
+
+Requires Node.js 22.19 or later. See the generated project's README for Cloudflare setup, including its one-time custom domain, R2 public URL, Access, and Deploy Hook configuration.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,4 @@
+# Third-party notices
+
+The generated project includes the cloudflare-starlight-cms source. Its third-party
+notices are copied into the generated project's root directory.

package/bin/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+import { constants } from 'node:fs';
+import { access, copyFile, lstat, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const templateRoot = join(packageRoot, 'template');
+const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+
+const usage = `Usage: npx create-starlight-cms@latest <directory>\n       npm create starlight-cms@latest <directory>\n\nCreate a self-hosted Astro Starlight CMS project. Use . for the current directory.\nThe destination must be new or empty (apart from .git and .DS_Store).\n\nOptions:\n  --help       Show this help message\n  --version    Show the CLI version\n`;
+
+function projectNameFromDirectory(directory) {
+  const normalized = basename(directory)
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+|[._-]+$/g, '');
+  return normalized && /^[a-z0-9]/.test(normalized) ? normalized : 'my-docs';
+}
+
+function workerNameFromProjectName(projectName) {
+  const workerName = projectName
+    .replace(/[._]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 63)
+    .replace(/-+$/g, '');
+  return workerName || 'my-docs';
+}
+
+async function exists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function assertDirectoryIsReady(destination) {
+  if (!await exists(destination)) return;
+  const stats = await lstat(destination);
+  if (stats.isSymbolicLink()) throw new Error('The destination cannot be a symbolic link.');
+  if (!stats.isDirectory()) throw new Error('The destination must be a directory.');
+
+  const unexpected = (await readdir(destination)).filter((entry) => entry !== '.git' && entry !== '.DS_Store');
+  if (unexpected.length > 0) throw new Error(`The destination is not empty: ${unexpected[0]}`);
+}
+
+async function assertNoSymlink(path) {
+  const stats = await lstat(path);
+  if (stats.isSymbolicLink()) throw new Error(`The packaged template contains a symbolic link: ${path}`);
+  if (!stats.isDirectory()) return;
+  for (const entry of await readdir(path)) await assertNoSymlink(join(path, entry));
+}
+
+async function assertDoesNotExist(path) {
+  if (await exists(path)) throw new Error(`Refusing to overwrite ${path}`);
+}
+
+async function copyDirectory(source, destination, isRoot = false) {
+  await mkdir(destination, { recursive: true });
+  for (const name of await readdir(source)) {
+    const restoredName = name.endsWith('.test.template.ts') ? name.replace('.test.template.ts', '.test.ts') : name;
+    const targetName = isRoot && restoredName === '_gitignore'
+      ? '.gitignore'
+      : isRoot && restoredName === 'package-lock.json.template'
+        ? 'package-lock.json'
+        : isRoot && restoredName === 'test-files'
+          ? 'tests'
+        : restoredName;
+    const sourcePath = join(source, name);
+    const destinationPath = join(destination, targetName);
+    const stats = await lstat(sourcePath);
+    if (stats.isSymbolicLink()) throw new Error(`The packaged template contains a symbolic link: ${sourcePath}`);
+    if (stats.isDirectory()) {
+      await assertDoesNotExist(destinationPath);
+      await copyDirectory(sourcePath, destinationPath);
+    } else {
+      await assertDoesNotExist(destinationPath);
+      await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL);
+    }
+  }
+}
+
+async function configurePackage(destination, projectName) {
+  const packagePath = join(destination, 'package.json');
+  const projectPackage = JSON.parse(await readFile(packagePath, 'utf8'));
+  projectPackage.name = projectName;
+  await writeFile(packagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
+
+  const lockPath = join(destination, 'package-lock.json');
+  const lockfile = JSON.parse(await readFile(lockPath, 'utf8'));
+  lockfile.name = projectName;
+  if (lockfile.packages?.['']) lockfile.packages[''].name = projectName;
+  await writeFile(lockPath, `${JSON.stringify(lockfile, null, 2)}\n`);
+}
+
+async function configureWrangler(destination, workerName) {
+  const wranglerPath = join(destination, 'wrangler.jsonc');
+  const wranglerConfig = await readFile(wranglerPath, 'utf8');
+  const configured = wranglerConfig.replace(
+    /("name"\s*:\s*)"[^"]+"/,
+    `$1"${workerName}"`,
+  );
+  if (!/"name"\s*:\s*"[^"]+"/.test(wranglerConfig)) throw new Error('The packaged template has no Worker name to configure.');
+  await writeFile(wranglerPath, configured);
+}
+
+function printSuccess(destination) {
+  const relativeDestination = relative(process.cwd(), destination) || '.';
+  const directoryForCommand = relativeDestination === '.' || relativeDestination.startsWith('..')
+    ? destination
+    : relativeDestination;
+  const changeDirectory = relativeDestination === '.' ? '' : `\n  cd ${directoryForCommand}`;
+  console.log(`\nCreated ${basename(destination)}.\n\nNext steps:${changeDirectory}\n  npm install\n  npm run dev\n\nThen edit src/site.config.ts and follow README.md for Cloudflare setup.\n`);
+}
+
+const [argument] = process.argv.slice(2);
+if (argument === '--help' || argument === '-h') {
+  process.stdout.write(usage);
+} else if (argument === '--version' || argument === '-v') {
+  console.log(packageJson.version);
+} else if (!argument || argument.startsWith('-') || process.argv.length !== 3) {
+  process.stderr.write(usage);
+  process.exitCode = 1;
+} else {
+  const destination = resolve(process.cwd(), argument);
+  try {
+    if (!await exists(templateRoot)) throw new Error('The packaged template is missing. Reinstall the CLI package.');
+    await assertNoSymlink(templateRoot);
+    await assertDirectoryIsReady(destination);
+    await mkdir(destination, { recursive: true });
+    await copyDirectory(templateRoot, destination, true);
+    const projectName = projectNameFromDirectory(destination);
+    await configurePackage(destination, projectName);
+    await configureWrangler(destination, workerNameFromProjectName(projectName));
+    printSuccess(destination);
+  } catch (error) {
+    console.error(`Could not create project: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "create-starlight-cms",
+  "version": "0.9.0",
+  "description": "Create a self-hosted Astro Starlight documentation CMS for Cloudflare Workers.",
+  "keywords": [
+    "astro",
+    "cloudflare",
+    "cms",
+    "docs",
+    "starlight",
+    "workers"
+  ],
+  "homepage": "https://github.com/KobayashiRui/cloudflare-starlight-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KobayashiRui/cloudflare-starlight-cms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KobayashiRui/cloudflare-starlight-cms/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-starlight-cms": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/prepare-create-template.mjs",
+    "release:check": "node ../../scripts/release-check.mjs",
+    "prepublishOnly": "npm run release:check",
+    "publish:public": "npm publish --access public",
+    "release:dry-run": "npm publish --dry-run --access public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.nvmrc

@@ -0,0 +1 @@
+22

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloudflare-starlight-cms contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -0,0 +1,68 @@
+<p>
+  <img src="./src/assets/logo.svg" alt="Cloudflare Starlight CMS" width="300">
+</p>
+
+# My Docs
+
+A documentation site created with cloudflare-starlight-cms.
+
+Not an official Cloudflare or Astro project. Licensed under MIT.
+
+## Quick start
+
+Install dependencies and start local development:
+
+```sh
+npm install
+npm run dev
+```
+
+The local Admin is at `http://127.0.0.1:8787/admin/`; static Docs are at `http://127.0.0.1:4321/`. Local D1 and R2 use Miniflare and need no Cloudflare account.
+
+The CLI writes the normalized project name to `wrangler.jsonc` as the Worker name. Its `DB` and `MEDIA` bindings have no resource IDs or names, so Cloudflare provisions their D1 database and R2 bucket during the first deploy.
+
+## Included
+
+- React Admin with Tiptap Simple Editor, drafts, revisions, preview, navigation tree, and locale-aware documents
+- D1 for content, R2 for PNG/JPEG/WebP/AVIF/MP4/WebM, and a media picker with safe unused-asset deletion
+- Astro Starlight, Pagefind, and Workers Static Assets for fully static public Docs
+- Cloudflare Access for `/admin/*`; no CMS users, passwords, or roles
+- Publish → Workers Deploy Hook → Workers Builds
+
+Replace [`src/assets/logo.svg`](src/assets/logo.svg) and [`src/assets/favicon.svg`](src/assets/favicon.svg) to brand a project. Edit Admin theme tokens in [`src/admin/styles/_cms-theme.scss`](src/admin/styles/_cms-theme.scss) and Starlight accents in [`src/styles/starlight.css`](src/styles/starlight.css).
+
+## Production setup
+
+1. Set the Workers Builds build command to `npm run build` and keep the default deploy command `npx wrangler deploy`. Disable non-production branch builds. With no public URL yet, the first build deploys an empty site and Admin Worker and provisions D1/R2. The first management API, export, or preview request applies the bundled initial schema automatically.
+2. Before attaching the custom domain to the Worker, create one Access Self-hosted Application for the planned hostname and `admin/*` path, for example `docs.example.com/admin/*`. Add the human `Allow` policy. The hostname must belong to an active Cloudflare zone, but it does not need to be attached to the Worker yet.
+3. Attach the custom domain to the Worker, then set [`src/site.config.ts`](src/site.config.ts)'s `url` to its origin, such as `https://docs.example.com`, and commit it. Admin routes are protected from their first custom-domain request. Builds derive both the Astro site URL and CMS snapshot endpoint from this source-controlled value.
+4. Add a Workers Builds `Service Auth` policy to that same Access Application. Add the Service Token's `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` to Workers Builds Build Variables and Secrets.
+5. After the bucket is provisioned, set `MEDIA_PUBLIC_URL` in [`wrangler.jsonc`](wrangler.jsonc) to the R2 public/custom-domain origin and commit it. It is public configuration, not a secret. Add the Workers Builds Deploy Hook URL as the production Worker runtime secret `WORKERS_DEPLOY_HOOK_URL` in **Worker → Settings → Variables and Secrets**. Do not add it to the Workers Builds variables: build variables are not available to the running CMS Worker. From a local authenticated terminal, the equivalent is:
+
+   ```sh
+   npx wrangler secret put WORKERS_DEPLOY_HOOK_URL
+   ```
+
+Publishing updates the public revision and requests a build. A successful Hook request means the build was accepted, not that it has deployed. Without a Hook, local publishing still rebuilds the local static Docs.
+
+Use a root-level document with the URL segment `index` as the homepage. It is a regular CMS document and publishes at `/`; its translations publish at their locale roots, such as `/ja/`.
+
+For a custom landing page instead, do not create that CMS `index` document. Add `src/pages/index.astro` to the generated project: Astro owns `/`, while CMS documents remain available at their own paths such as `/getting-started/`.
+
+Initialization records the two bundled CREATE migrations in `d1_migrations`, shared with Wrangler. Failed initialization returns 503 and can be retried. Future ALTER/backfill migrations require an explicit upgrade procedure; adding a SQL file does not automatically enable runtime execution. Keep production data when upgrading.
+
+If provisioning reports an existing D1 after deletion, check Cloudflare Audit Logs for `DeleteDatabase` and subsequent `CreateDatabase` events and check overlapping builds. This error happens before schema initialization. Do not repeatedly delete databases or rename the Worker as a recovery procedure. Successful existing bindings are inherited by Wrangler; recovery of an unbound resource after a failed first deploy needs account-level verification.
+
+## Commands
+
+```sh
+npm run dev
+npm run check
+npm test
+npm run build:empty
+npm run dry-run
+```
+
+With an empty `siteConfig.url`, `build` creates the explicit empty site for an initial deploy. `build:empty` is available when an intentionally empty local build is needed. `dry-run` validates the Worker and Static Assets configuration without deploying.
+
+Configure the site title, locales, and public URL in `src/site.config.ts`. CMS updates are not automatic; selectively bring the changes you need into this project.

package/template/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+## Headless Tree comprehensive drag-and-drop example
+
+The Navigation Tree markup and styling are adapted from the Headless Tree
+Comprehensive Drag-and-Drop story:
+https://github.com/lukasbach/headless-tree/tree/main/packages/sb-react/src/dnd/comprehensive.stories.tsx
+
+Copyright (c) 2023 Lukas Bach. Licensed under the MIT License.
+
+The MIT License is included with the Headless Tree package and at:
+https://github.com/lukasbach/headless-tree/blob/main/LICENSE

package/template/_gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.astro/
+.wrangler/
+.dev-assets/
+packages/create-starlight-cms/template/
+.env
+.env.*
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+coverage/
+*.tsbuildinfo
+.DS_Store

package/template/astro.config.mjs

@@ -0,0 +1,26 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { siteConfig } from './src/site.config.ts';
+import { cmsOrigin } from './src/starlight/cms-origin.ts';
+import { loadSnapshot } from './src/starlight/source.ts';
+import { cmsSidebar } from './src/starlight/sidebar.ts';
+
+export default defineConfig({
+  site: cmsOrigin || undefined,
+  output: 'static',
+  integrations: [starlight({
+    title: siteConfig.title,
+    logo: {
+      src: './src/assets/logo.svg',
+      alt: `${siteConfig.title} logo`,
+      replacesTitle: true,
+    },
+    favicon: '/favicon.svg',
+    customCss: ['./src/styles/starlight.css'],
+    defaultLocale: 'root',
+    locales: Object.fromEntries(siteConfig.locales.map(({ code, label }) => [
+      code === siteConfig.defaultLocale ? 'root' : code, { label, lang: code },
+    ])),
+    sidebar: process.argv.includes('preview') ? [] : cmsSidebar(await loadSnapshot()),
+  })],
+});

package/template/migrations/0001_schema.sql

@@ -0,0 +1,73 @@
+CREATE TABLE IF NOT EXISTS folder (
+  id TEXT PRIMARY KEY,
+  parent_id TEXT REFERENCES folder(id) ON DELETE RESTRICT,
+  slug TEXT NOT NULL,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS folder_translation (
+  folder_id TEXT NOT NULL REFERENCES folder(id) ON DELETE CASCADE,
+  locale TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (folder_id, locale)
+);
+
+CREATE TABLE IF NOT EXISTS document (
+  id TEXT PRIMARY KEY,
+  folder_id TEXT REFERENCES folder(id) ON DELETE RESTRICT,
+  slug TEXT NOT NULL,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS document_translation (
+  id TEXT PRIMARY KEY,
+  document_id TEXT NOT NULL REFERENCES document(id) ON DELETE CASCADE,
+  locale TEXT NOT NULL,
+  title TEXT NOT NULL,
+  sidebar_label TEXT,
+  description TEXT NOT NULL DEFAULT '',
+  content_json TEXT NOT NULL,
+  published_revision_id TEXT,
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  published_at INTEGER,
+  UNIQUE (document_id, locale)
+);
+
+CREATE TABLE IF NOT EXISTS document_revision (
+  id TEXT PRIMARY KEY,
+  document_translation_id TEXT NOT NULL REFERENCES document_translation(id) ON DELETE CASCADE,
+  revision INTEGER NOT NULL,
+  title TEXT NOT NULL,
+  sidebar_label TEXT,
+  description TEXT NOT NULL DEFAULT '',
+  content_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  UNIQUE(document_translation_id, revision)
+);
+
+CREATE TABLE IF NOT EXISTS media (
+  id TEXT PRIMARY KEY,
+  object_key TEXT NOT NULL UNIQUE,
+  file_name TEXT NOT NULL,
+  content_type TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS folder_root_slug_unique ON folder(slug) WHERE parent_id IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS folder_child_slug_unique ON folder(parent_id, slug) WHERE parent_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS document_root_slug_unique ON document(slug) WHERE folder_id IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS document_folder_slug_unique ON document(folder_id, slug) WHERE folder_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS folder_parent_order_idx ON folder(parent_id, sort_order);
+CREATE INDEX IF NOT EXISTS document_folder_order_idx ON document(folder_id, sort_order);
+CREATE INDEX IF NOT EXISTS folder_translation_locale_idx ON folder_translation(locale, name);
+CREATE INDEX IF NOT EXISTS document_translation_locale_idx ON document_translation(locale, title);
+CREATE INDEX IF NOT EXISTS document_revision_translation_idx ON document_revision(document_translation_id, revision DESC);

package/template/migrations/0002_publish_delivery.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS publish_delivery (
+  id TEXT PRIMARY KEY,
+  trigger_kind TEXT NOT NULL CHECK (trigger_kind IN ('document', 'site')),
+  document_translation_id TEXT REFERENCES document_translation(id) ON DELETE SET NULL,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'accepted', 'failed', 'skipped')),
+  attempts INTEGER NOT NULL DEFAULT 0,
+  build_id TEXT,
+  already_exists INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  requested_at INTEGER NOT NULL,
+  accepted_at INTEGER,
+  next_retry_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS publish_delivery_recent_idx ON publish_delivery(requested_at DESC);
+CREATE INDEX IF NOT EXISTS publish_delivery_retry_idx ON publish_delivery(status, next_retry_at);