@stackbox/cms 0.0.2

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Vance Lucas
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,168 @@
+# @stackbox/cms
+
+A small, code-first CMS engine for building dynamic [Cloudflare Worker](https://developers.cloudflare.com/workers/) sites. Stackbox is designed to be driven by AI: pages, templates, and content modules are plain TypeScript files with typed, composable APIs, so an agent can author and assemble a site without a database, admin UI, or hand-written backend.
+
+Pages are rendered on each request inside a Cloudflare Worker, so content, templates, and modules can be fully dynamic — driven by request data, bindings (KV, D1, R2), and async data fetching.
+
+## Why this exists
+
+Traditional CMSes assume a human clicking around an admin panel. Stackbox inverts that: a site is TypeScript modules assembled into a Worker. Every primitive (`createSiteConfig`, `createSite`, `createTemplate`, `createPage`, `createModule`) is a typed factory suited for AI to generate, edit, and validate site content as code — and the same files render dynamically on Cloudflare Workers at request time.
+
+## Requirements
+
+- Node.js >= 20
+
+## Installation
+
+```bash
+npm install @stackbox/cms
+```
+
+## Concepts
+
+| Primitive | Factory | Purpose |
+| --- | --- | --- |
+| **Site config** | `createSiteConfig(config)` | Definition-time settings shared by templates and pages. |
+| **Site** | `createSite(siteConfig, { pages }` | Runtime router with `fetch(request, env)` for Cloudflare Workers. |
+| **Template** | `createTemplate({ siteConfig, slots, render }` | A reusable page layout that declares named **slots**. |
+| **Page** | `createPage(template, { path, title, slots }` | A single URL, built by filling a template's slots with content. |
+| **Module** | `createModule({ name, render }` | A self-contained content block placed into a slot. |
+
+**Slots** are named regions in a template. Page content — strings, HTML, or modules — is dropped into slots, and the engine resolves and renders everything (including `async` modules, concurrently) to a single HTML string.
+
+## Project layout
+
+```
+my-worker/
+  site.config.ts      # createSiteConfig({ name, url, ... })
+  worker.ts           # createSite(siteConfig, { pages }) — default export for Cloudflare
+  templates/
+    site-template.ts  # shared createTemplate() layouts
+  pages/
+    home.ts           # exports homePage
+    blog.ts           # createBlog() + createPage() for listing and posts
+  content/blog/       # markdown posts (read at bundle time)
+```
+
+## Quick start
+
+`site.config.ts`:
+
+```ts
+import { createSiteConfig } from "@stackbox/cms";
+
+export default createSiteConfig({
+  name: "My Site",
+  url: "https://example.com",
+});
+```
+
+`templates/site-template.ts`:
+
+```ts
+import { html } from "@hyperspan/html";
+import { createTemplate } from "@stackbox/cms";
+import siteConfig from "../site.config";
+
+export const siteTemplate = createTemplate({
+  siteConfig,
+  slots: [{ name: "content", options: { required: true, primary: true } }],
+  render({ slots }) {
+    return html`<main>${slots.content.render()}</main>`;
+  },
+});
+```
+
+`pages/home.ts`:
+
+```ts
+import { createPage } from "@stackbox/cms";
+import { siteTemplate } from "../templates/site-template";
+
+const homePage = createPage(siteTemplate, {
+  path: "/",
+  title: "Home",
+  slots: { content: ["<p>Welcome to my site.</p>"] },
+});
+
+export default homePage;
+```
+
+`worker.ts`:
+
+```ts
+import { createSite } from "@stackbox/cms";
+import siteConfig from "./site.config";
+import homePage from "./pages/home";
+import aboutPage from "./pages/about";
+
+export default createSite(siteConfig, {
+  pages: [homePage, aboutPage],
+});
+```
+
+Deploy with [`wrangler`](https://developers.cloudflare.com/workers/wrangler/). The default export's `fetch(request, env)` handles each request.
+
+## Blog module
+
+`createBlog()` loads markdown at bundle time and returns **content objects** you wire into your own pages with `createPage()` — so you control templates, slots, and any extra content alongside blog output.
+
+```ts
+// pages/blog.ts
+import { join } from "node:path";
+import { createPage } from "@stackbox/cms";
+import { createBlog } from "@stackbox/cms/modules/blog";
+import { siteTemplate } from "../templates/site-template";
+
+const blog = createBlog({
+  contentPath: join(import.meta.dirname, "../content/blog"),
+  pathPrefix: "/blog",
+  postsPerPage: 10, // optional — omit to put all posts on one listing page
+});
+
+export const blogListingPages = blog.listings.map((listing, index) =>
+  createPage(siteTemplate, {
+    path: listing.path,
+    title: index === 0 ? "Blog" : `Blog — page ${index + 1}`,
+    slots: {
+      content: [...listing.content, "<p>Subscribe for updates</p>"],
+    },
+  }),
+);
+
+export const blogPostPages = blog.posts.map((post) =>
+  createPage(siteTemplate, {
+    path: post.path,
+    title: post.title,
+    meta: post.meta,
+    slots: { content: [...post.content] },
+  }),
+);
+```
+
+```ts
+// worker.ts
+import { blogListingPages, blogPostPages } from "./pages/blog";
+
+export default createSite(siteConfig, {
+  pages: [homePage, ...blogListingPages, ...blogPostPages],
+});
+```
+
+## Bundled modules
+
+```ts
+import { createBlog } from "@stackbox/cms/modules/blog";
+```
+
+## Development
+
+```bash
+npm run build      # compile the package
+npm run typecheck  # type-check without emitting
+npm test           # build, then run the test suite
+```
+
+## License
+
+BSD-3-Clause

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@stackbox/cms",
+  "version": "0.0.2",
+  "description": "Stackbox CMS engine",
+  "type": "module",
+  "license": "BSD-3-Clause",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/stackboxcms/cms",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stackboxcms/cms.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./modules/blog": {
+      "types": "./dist/modules/blog/module.d.ts",
+      "import": "./dist/modules/blog/module.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hyperspan/html": "^1.0.3",
+    "marked": "^15.0.12",
+    "tsx": "^4.19.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+export {
+  createModule,
+  isModule,
+  type Module,
+  type ModuleFactory,
+  type ModuleOptionsOf,
+  type ModuleRenderResult,
+} from "./modules.js";
+export {
+  createPage,
+  isPage,
+  PageValidationError,
+  toPageRenderView,
+  validateSlotContentItem,
+  type Page,
+  type PageMeta,
+  type PageRenderView,
+  type RenderContext,
+  type SitePage,
+} from "./pages.js";
+export { renderStandardHead } from "./render-head.js";
+export { renderPage, RenderError } from "./render-page.js";
+export { matchPagePath, normalizePathname } from "./routing.js";
+export {
+  createSite,
+  createSiteConfig,
+  isSite,
+  isSiteConfig,
+  SiteError,
+  type Site,
+  type SiteConfig,
+} from "./site.js";
+export { createContext, Stackbox } from "./stackbox/context.js";
+export {
+  anySlotContentSchema,
+  moduleSlotContentSchema,
+  slotHasContent,
+  SlotContentValidationError,
+  stringSlotContentSchema,
+  type DefaultSlotContent,
+  type PageSlotsInput,
+  type SlotContentFromDefinition,
+} from "./slot-content.js";
+export {
+  buildPageSlots,
+  buildStubSlots,
+  renderSlotContent,
+  slotSentinel,
+  SLOT_SENTINEL_PREFIX,
+  type Slot,
+  type SlotRenderValue,
+  type TemplateSlotsFrom,
+} from "./slot-handle.js";
+export {
+  createTemplate,
+  isTemplate,
+  TemplateBuildError,
+  type RequiredSlotNamesFrom,
+  type SlotDefinition,
+  type SlotMeta,
+  type SlotNamesFrom,
+  type SlotOptions,
+  type TemplateDescriptor,
+  type TemplateRenderContext,
+  type TemplateRenderFn,
+} from "./templates.js";

package/src/modules/blog/module.ts

@@ -0,0 +1,86 @@
+import type { PageMeta } from "../../pages.js";
+import type { DefaultSlotContent } from "../../slot-content.js";
+import { loadPosts, type BlogOptions, type BlogPost } from "./posts.js";
+
+export type { BlogPost, BlogOptions } from "./posts.js";
+
+export type BlogPostContent = {
+  path: string;
+  title: string;
+  meta?: PageMeta;
+  content: DefaultSlotContent[];
+};
+
+export type BlogListingContent = {
+  path: string;
+  content: DefaultSlotContent[];
+};
+
+export type Blog = {
+  readonly posts: readonly BlogPostContent[];
+  readonly listings: readonly BlogListingContent[];
+};
+
+function postToContent(post: BlogPost): BlogPostContent {
+  return {
+    path: post.path,
+    title: post.title,
+    meta: post.description ? { description: post.description } : undefined,
+    content: [
+      `<article data-content-type="article" data-slug="${post.slug}">
+  <h1>${post.title}</h1>
+  ${post.bodyHtml}
+</article>`,
+    ],
+  };
+}
+
+function listingPath(pathPrefix: string, page: number): string {
+  return page === 1 ? pathPrefix : `${pathPrefix}/page/${page}`;
+}
+
+function buildPostListHtml(posts: BlogPost[]): string {
+  return `<ul>${posts
+    .map((post) => `<li><a href="${post.path}">${post.title}</a></li>`)
+    .join("")}</ul>`;
+}
+
+function buildListingPages(
+  posts: BlogPost[],
+  pathPrefix: string,
+  postsPerPage?: number,
+): BlogListingContent[] {
+  if (posts.length === 0) {
+    return [
+      {
+        path: pathPrefix,
+        content: ["<p>No blog posts found.</p>"],
+      },
+    ];
+  }
+
+  const perPage =
+    postsPerPage && postsPerPage > 0 ? postsPerPage : posts.length;
+  const pages: BlogListingContent[] = [];
+
+  for (let i = 0; i < posts.length; i += perPage) {
+    const chunk = posts.slice(i, i + perPage);
+    const page = i / perPage + 1;
+    pages.push({
+      path: listingPath(pathPrefix, page),
+      content: [buildPostListHtml(chunk)],
+    });
+  }
+
+  return pages;
+}
+
+export function createBlog(options: BlogOptions): Blog {
+  const loaded = loadPosts(options);
+  const pathPrefix = options.pathPrefix.replace(/\/+$/, "") || "/";
+
+  return {
+    posts: loaded.map(postToContent),
+    listings: buildListingPages(loaded, pathPrefix, options.postsPerPage),
+  };
+}

package/src/modules/blog/posts.ts

@@ -0,0 +1,69 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { marked } from "marked";
+
+export type BlogPost = {
+  slug: string;
+  title: string;
+  description?: string;
+  path: string;
+  bodyHtml: string;
+};
+
+export type BlogOptions = {
+  contentPath: string;
+  pathPrefix: string;
+  /** Max posts per listing page. Omit to put all posts on one page. */
+  postsPerPage?: number;
+};
+
+function parseFrontmatter(raw: string): {
+  meta: Record<string, string>;
+  body: string;
+} {
+  if (!raw.startsWith("---")) {
+    return { meta: {}, body: raw };
+  }
+
+  const end = raw.indexOf("\n---", 3);
+  if (end === -1) {
+    return { meta: {}, body: raw };
+  }
+
+  const frontmatter = raw.slice(3, end).trim();
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+  const meta: Record<string, string> = {};
+
+  for (const line of frontmatter.split("\n")) {
+    const colon = line.indexOf(":");
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    const value = line.slice(colon + 1).trim().replace(/^["']|["']$/g, "");
+    if (key) meta[key] = value;
+  }
+
+  return { meta, body };
+}
+
+export function loadPosts(options: BlogOptions): BlogPost[] {
+  const absoluteDir = resolve(options.contentPath);
+  const files = readdirSync(absoluteDir)
+    .filter((name) => extname(name) === ".md")
+    .sort();
+
+  return files.map((filename) => {
+    const raw = readFileSync(join(absoluteDir, filename), "utf8");
+    const { meta, body } = parseFrontmatter(raw);
+    const slug = meta.slug ?? basename(filename, ".md");
+    const title = meta.title ?? slug;
+    const prefix = options.pathPrefix.replace(/\/+$/, "");
+
+    return {
+      slug,
+      title,
+      description: meta.description,
+      path: `${prefix}/${slug}`,
+      bodyHtml: marked.parse(body) as string,
+    };
+  });
+}

package/src/modules.ts

@@ -0,0 +1,58 @@
+import type { RenderContext } from "./pages.js";
+import type { HSHtml } from "@hyperspan/html";
+
+export type ModuleRenderResult = HSHtml | Promise<HSHtml>;
+
+export type Module = {
+  readonly __kind: "module";
+  readonly name: string;
+  render(ctx: RenderContext): ModuleRenderResult;
+};
+
+type ModuleDef<TOptions = undefined> = {
+  name: string;
+  render(options: TOptions, ctx?: RenderContext): ModuleRenderResult;
+};
+
+export type ModuleOptionsOf<F> = F extends (options?: infer O) => unknown
+  ? [O] extends [undefined]
+    ? undefined
+    : O
+  : never;
+
+export type ModuleFactory<TOptions = undefined> = (
+  options?: TOptions,
+) => Module;
+
+function validateModuleName(name: string): void {
+  if (!name || name.length === 0) {
+    throw new Error("createModule(def): name is required");
+  }
+}
+
+export function createModule<TOptions = undefined>(
+  def: ModuleDef<TOptions>,
+): ModuleFactory<TOptions> {
+  validateModuleName(def.name);
+
+  if (typeof def.render !== "function") {
+    throw new Error("createModule(def): render is required");
+  }
+
+  return ((options?: TOptions) => ({
+    __kind: "module" as const,
+    name: def.name,
+    render: (ctx: RenderContext) => def.render(options as TOptions, ctx),
+  })) as ModuleFactory<TOptions>;
+}
+
+export function isModule(value: unknown): value is Module {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Module).__kind === "module" &&
+    typeof (value as Module).name === "string" &&
+    (value as Module).name.length > 0 &&
+    typeof (value as Module).render === "function"
+  );
+}