caracms 0.0.0-stage → 0.2.0

package/bin/site-runner.mjs

@@ -0,0 +1,61 @@
+// Loading the package's TypeScript (and through it the site's caracms.config.ts) from a
+// plain `.mjs` command (M8 → Current state: "load it the way the site's own Astro does").
+//
+// Node 22.12 runs no TypeScript without flags, and the site's config imports `caracms/config`
+// as TypeScript source. So a command that needs the config (`schemas`, `validate`) starts
+// a Vite dev server in middleware mode from the site's own Astro's Vite, with caracms
+// compiled (`ssr.noExternal`, as the integration sets it), loads one of the package's
+// `src/cli/*.ts` modules through it, and closes it after. No port is opened, nothing is
+// watched, and nothing is written.
+
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+
+/** The Vite the site's Astro uses, or null with a sentence why. */
+export function siteVite(root) {
+	const fromSite = createRequire(join(root, 'package.json'));
+	let astro;
+	try {
+		astro = fromSite.resolve('astro/package.json');
+	} catch {
+		return { vite: null, problem: "there's no Astro installed here. Run this from the site's root, after installing its dependencies." };
+	}
+	try {
+		return { vite: createRequire(astro).resolve('vite'), problem: null };
+	} catch {
+		return { vite: null, problem: "the site's Astro has no Vite beside it. Reinstall the site's dependencies." };
+	}
+}
+
+/**
+ * Run `fn(module)` with the package's `src/cli/<name>.ts` loaded through the site's Vite,
+ * then close the server. Throws an Error with a plain sentence when it can't be loaded.
+ */
+export async function withPackageModule(root, name, fn) {
+	const { vite, problem } = siteVite(root);
+	if (!vite) throw new Error(problem);
+	const { createServer } = await import(pathToFileURL(vite).href);
+	const server = await createServer({
+		root,
+		configFile: false,
+		envFile: false,
+		logLevel: 'error',
+		clearScreen: false,
+		appType: 'custom',
+		server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+		optimizeDeps: { noDiscovery: true, include: [] },
+		ssr: { noExternal: ['caracms'] },
+	});
+	try {
+		const entry = join(packageRoot, 'src/cli', `${name}.ts`);
+		if (!existsSync(entry)) throw new Error(`the package's ${entry} is missing. Reinstall caracms.`);
+		const module = await server.ssrLoadModule(entry);
+		return await fn(module);
+	} finally {
+		await server.close();
+	}
+}

package/bin/templates/Page.astro.txt

@@ -0,0 +1,31 @@
+---
+/**
+ * The page component, written by `caracms init`: a document in, a whole page out. The
+ * public pages and the editor's preview both render through it. Give it the site's own
+ * layout (its head, header and footer) with `<Blocks>` where a page's content goes: the
+ * caracms-adopt skill says how.
+ */
+import Blocks from 'caracms/components/Blocks.astro';
+import Fonts from 'caracms/components/Fonts.astro';
+import Head from 'caracms/components/Head.astro';
+import type { PageProps } from 'caracms/document';
+
+type Props = PageProps;
+// `path` is the document's address (`/about`), the same on the public page and in the preview.
+const { document, collection, path, preview = false, listPage } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<Head document={document} collection={collection} path={path} preview={preview} listPage={listPage} />
+		<Fonts />
+	</head>
+	<body>
+		<main>
+			<Blocks document={document} collection={collection} preview={preview} listPage={listPage} />
+		</main>
+	</body>
+</html>

package/bin/templates/TextBlock.astro.txt

@@ -0,0 +1,13 @@
+---
+/** The plain text block `caracms init` adds: one text field, as a paragraph. */
+import Block from 'caracms/components/Block.astro';
+import Text from 'caracms/components/Text.astro';
+import type { BlockProps } from 'caracms/document';
+
+type Props = BlockProps<{ text: string }>;
+const { block, cms } = Astro.props;
+---
+
+<Block cms={cms} as="section">
+	<Text cms={cms} field="text" value={block.text} />
+</Block>

package/bin/templates/caracms.config.ts.txt

@@ -0,0 +1,22 @@
+import { defineSite, text } from 'caracms/config';
+
+/**
+ * caracms's config for this site, written by `caracms init`: its collections, blocks and
+ * text styles. astro.config passes it to the integration. The caracms-adopt and
+ * caracms-blocks skills say how it grows as the site's pages come in.
+ */
+export default defineSite({
+	collections: {
+		// content/pages/<path>.json is the page at /<path>; content/pages/index.json is Home.
+		pages: { kind: 'sections', folder: 'content/pages', urlBase: '/', nested: true },
+	},
+	blocks: {
+		text: {
+			label: 'Text',
+			component: 'src/components/caracms/TextBlock.astro',
+			fields: { text: text({ multiline: true }) },
+		},
+	},
+	textStyles: {},
+	page: 'src/components/caracms/Page.astro',
+});

package/bin/templates/catch-all.astro.txt

@@ -0,0 +1,25 @@
+---
+/**
+ * Every document in the Pages collection (content/pages/), nested ones included: the
+ * file's path is the address. Written by `caracms init`. It serves documents only. The
+ * site's other routes in src/pages/ keep serving their own pages, and their addresses are
+ * reserved: a page is code or a document, never both.
+ */
+import RenderDocument from 'caracms/components/RenderDocument.astro';
+import { listDocuments, readDocument } from 'caracms/content';
+import { site } from 'virtual:caracms/config';
+
+export const prerender = true;
+
+export async function getStaticPaths() {
+	// A file that can't be opened (invalid JSON, no title, a nested index.json) has no page,
+	// and nor has a hidden one (or one under it): visitors get the 404 page.
+	const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
+	return entries.map((e) => ({ params: { path: e.path === 'index' ? undefined : e.path }, props: { path: e.path } }));
+}
+
+const { path } = Astro.props;
+const { document } = await readDocument(site, 'pages', path);
+---
+
+<RenderDocument document={document} collection="pages" />

package/bin/templates/health.ts.txt

@@ -0,0 +1,6 @@
+import type { APIRoute } from 'astro';
+
+// Railway's healthcheck: answered by the server, not prerendered.
+export const prerender = false;
+
+export const GET: APIRoute = () => new Response('ok');

package/bin/templates/railway.ts.txt

@@ -0,0 +1,147 @@
+import { bucket, defineRailway, github, image, preserve, project, redis, ref, service } from "railway/iac";
+
+// A caracms site's Railway project, as code (written by `caracms init` from the
+// caracms starter's). From the site's root: `railway config plan` shows
+// what would change, `railway config apply` makes it so. Plan first, every time:
+// Redis holds the editor's drafts and the media bucket every uploaded image.
+//
+// What this file doesn't do, set by hand on Railway: create the project, the
+// domains (site's and imgproxy's, imgproxy's on port 8080),
+// Redis's volume and start command (Railway's Redis template makes them), the
+// secrets' values, and the optional secrets below until they're wanted.
+
+// ---- The site's names: a new site edits this block and nothing else. ----
+// Project name, bucket names and the S3 bucket references derive from SITE.
+const SITE = "{{SITE}}";
+// The repo the editor commits to and Railway builds from.
+const GITHUB_REPO = "{{GITHUB_REPO}}";
+// Railway's region for the services, and the buckets' region (a bucket region
+// is one of sjc, iad, ams, sin; ams sits next to europe-west4).
+const REGION = "europe-west4-drams3a";
+const BUCKET_REGION = "ams";
+// The site is the repo's root: no watch paths, so every push to main deploys.
+const WATCH_PATHS: string[] = [];
+const BUILD_COMMAND = "{{BUILD}}";
+const START_COMMAND = "{{START}}";
+// imgproxy's origin and the media bucket's S3 name. Null: they come as
+// references to imgproxy's domain and the media bucket's BUCKET.
+const MEDIA_URL: string | null = null;
+const MEDIA_S3_NAME: string | null = null;
+// -------------------------------------------------------------------------
+
+// A Railway reference inside a longer string: ${{<resource>.<VARIABLE>}}.
+// ref() is for a value that is one whole reference; this is for one wrapped in
+// other text. ref() compiles to the same syntax from the resource's name.
+const inline = (resource: { name: string }, variable: string) =>
+  "${{" + resource.name + "." + variable + "}}";
+
+export default defineRailway(() => {
+  // Uploaded images, served publicly through imgproxy.
+  const media = bucket(`${SITE}-media`, { region: BUCKET_REGION });
+  // Form submissions: a second bucket, so imgproxy, which holds the media
+  // bucket's keys and serves it publicly, can never reach them. Only `site`
+  // gets its credentials (SUBMISSIONS_S3_*). Same region as media: the site
+  // uses media's endpoint and region (S3_ENDPOINT, S3_REGION) for both.
+  const submissions = bucket(`${SITE}-submissions`, { region: BUCKET_REGION });
+
+  // The editor's drafts and sessions.
+  const kv = redis("Redis", { region: REGION });
+  // Sleeps when idle. redis() takes only a region, so it's set on the node.
+  kv.deploy = { ...kv.deploy, sleepApplication: true };
+
+  const imgproxy = service("imgproxy", {
+    // Pinned to an exact release, no auto updates.
+    source: image("ghcr.io/imgproxy/imgproxy:v4.0.15"),
+    replicas: { [REGION]: 1 },
+    // Sleeps when idle.
+    deploy: { sleepApplication: true },
+    // Railway's edge caches the signed image URLs (immutable, a year).
+    cdn: { enabled: true },
+    env: {
+      // The domain is generated for this port, so it's fixed here.
+      PORT: "8080",
+      IMGPROXY_USE_S3: "true",
+      IMGPROXY_S3_ENDPOINT: ref(media, "ENDPOINT"),
+      IMGPROXY_S3_REGION: ref(media, "REGION"),
+      AWS_ACCESS_KEY_ID: ref(media, "ACCESS_KEY_ID"),
+      AWS_SECRET_ACCESS_KEY: ref(media, "SECRET_ACCESS_KEY"),
+      // Only the media bucket: BUCKET is the S3 name with Railway's suffix.
+      IMGPROXY_ALLOWED_SOURCES: `s3://${MEDIA_S3_NAME ?? inline(media, "BUCKET")}/`,
+      IMGPROXY_MAX_RESULT_DIMENSION: "4000",
+      IMGPROXY_MAX_SRC_RESOLUTION: "50",
+      IMGPROXY_TTL: "31536000",
+      IMGPROXY_USE_ETAG: "true",
+      IMGPROXY_WORKERS: "2",
+      IMGPROXY_MALLOC: "jemalloc",
+      MALLOC_ARENA_MAX: "2",
+      IMGPROXY_SKIP_PROCESSING_FORMATS: "gif,svg",
+      // Signing key and salt (64-byte hex, generated by hand). `site` refers
+      // to these, so the two can't drift apart.
+      IMGPROXY_KEY: preserve(),
+      IMGPROXY_SALT: preserve(),
+    },
+  });
+
+  const site = service("site", {
+    source: github(GITHUB_REPO, { branch: "main", checkSuites: false }),
+    build: { buildCommand: BUILD_COMMAND, watchPatterns: WATCH_PATHS },
+    start: START_COMMAND,
+    healthcheck: "/health",
+    replicas: { [REGION]: 1 },
+    deploy: { restartPolicyMaxRetries: 3 },
+    env: {
+      // ---- Written here: literals and Railway references ----
+      NODE_ENV: "production",
+      // The public address (canonical links, the sitemap, og:url). At launch it
+      // becomes the client's domain, written out as "https://<domain>".
+      SITE_URL: "https://${{RAILWAY_PUBLIC_DOMAIN}}",
+      REDIS_URL: ref(kv, "REDIS_URL"),
+      // Images: imgproxy's public origin (the custom image host at launch), and
+      // its key and salt, which sign every image URL.
+      CARACMS_MEDIA_URL: MEDIA_URL ?? `https://${inline(imgproxy, "RAILWAY_PUBLIC_DOMAIN")}`,
+      IMGPROXY_KEY: ref(imgproxy, "IMGPROXY_KEY"),
+      IMGPROXY_SALT: ref(imgproxy, "IMGPROXY_SALT"),
+      // The media bucket, for uploads from the editor.
+      S3_ENDPOINT: ref(media, "ENDPOINT"),
+      S3_REGION: ref(media, "REGION"),
+      S3_BUCKET: ref(media, "BUCKET"),
+      S3_ACCESS_KEY_ID: ref(media, "ACCESS_KEY_ID"),
+      S3_SECRET_ACCESS_KEY: ref(media, "SECRET_ACCESS_KEY"),
+      // The submissions bucket. Its endpoint and region are media's (S3_*).
+      SUBMISSIONS_S3_BUCKET: ref(submissions, "BUCKET"),
+      SUBMISSIONS_S3_ACCESS_KEY_ID: ref(submissions, "ACCESS_KEY_ID"),
+      SUBMISSIONS_S3_SECRET_ACCESS_KEY: ref(submissions, "SECRET_ACCESS_KEY"),
+
+      // The repo the editor commits to.
+      GITHUB_REPO,
+
+      // ---- Set by hand on Railway: names only, the values never live here ----
+      // On a fresh project these stay unset and the plan doesn't mention them.
+      // The editor's GitHub App and sign-in.
+      GITHUB_APP_ID: preserve(),
+      GITHUB_APP_PRIVATE_KEY: preserve(),
+      GITHUB_WEBHOOK_SECRET: preserve(),
+      CARACMS_SECRET: preserve(),
+      CARACMS_ALLOW: preserve(),
+      CARACMS_BACKUP_USER: preserve(),
+      CARACMS_BACKUP_PASSWORD: preserve(),
+      // Try again on a failed publish redeploys through this project token.
+      CARACMS_RAILWAY_TOKEN: preserve(),
+      MUX_TOKEN_ID: preserve(),
+      MUX_TOKEN_SECRET: preserve(),
+      // The form emails.
+      RESEND_API_KEY: preserve(),
+      FORMS_FROM: preserve(),
+      // Optional. The form's spam check: the site key is baked in at build, so
+      // a change needs a redeploy.
+      TURNSTILE_SITE_KEY: preserve(),
+      TURNSTILE_SECRET_KEY: preserve(),
+      // Optional. Pre-launch password ("user:password"); unset means public.
+      CARACMS_PRELAUNCH: preserve(),
+    },
+  });
+
+  return project(SITE, {
+    resources: [site, kv, imgproxy, media, submissions],
+  });
+});

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "caracms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A visual CMS for Astro sites, with content in git.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts",
+    "./content": "./src/content.ts",
+    "./document": "./src/document.ts",
+    "./serialize": "./src/serialize.ts",
+    "./measure": "./src/measure.ts",
+    "./files": "./src/files.ts",
+    "./virtual": {
+      "types": "./src/virtual.d.ts"
+    },
+    "./components/*": "./src/components/*"
+  },
+  "bin": {
+    "caracms": "bin/caracms.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "pnpm run test:unit && pnpm run test:browser && pnpm run test:visual",
+    "test:unit": "node --test --experimental-strip-types $(find test -name '*.test.ts' ! -name '*.browser.test.ts' ! -name '*.visual.test.ts' ! -name '*.release.test.ts' | sort)",
+    "test:browser": "node --test --experimental-strip-types --test-concurrency=2 $(find test -name '*.browser.test.ts' | sort)",
+    "test:visual": "node --test --experimental-strip-types --test-concurrency=3 $(find test -name '*.visual.test.ts' | sort)",
+    "check": "tsc --noEmit -p tsconfig.json && astro check --root .",
+    "test:release": "node --test --experimental-strip-types $(find test -name '*.release.test.ts' | sort)"
+  },
+  "dependencies": {
+    "@mux/mux-player": "3.13.4",
+    "@mux/upchunk": "3.5.0",
+    "@tiptap/core": "3.31.4",
+    "@tiptap/pm": "3.31.4",
+    "aws4fetch": "1.0.20",
+    "harfbuzzjs": "1.6.3",
+    "idiomorph": "0.8.0",
+    "ioredis": "5.11.1",
+    "react": "19.3.0",
+    "react-day-picker": "^9.14.0",
+    "react-dom": "19.3.0"
+  },
+  "peerDependencies": {
+    "astro": "^7.3.8"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/node": "^11.1.7",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "ajv": "^8.20.0",
+    "astro": "^7.3.8",
+    "playwright-core": "1.63.0",
+    "typescript": "^6.0.3"
+  }
+}