@stackbox/cms 0.0.4 → 0.1.0

package/src/plugins/sitemap/index.ts

@@ -0,0 +1,156 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  createPlugin,
+} from "../../plugin.js";
+import { normalizePathname } from "../../routing.js";
+import type { Stackbox as SB } from "../../types.js";
+
+export type SitemapOptions = {
+  /** Site origin. Defaults to `siteConfig.config.url`. */
+  baseUrl?: string;
+  /** Extra site-relative or absolute URLs. */
+  extraUrls?: readonly string[];
+  exclude?: readonly string[] | ((path: string) => boolean);
+};
+
+function resolveBaseUrl(site: SB.Site, options: SitemapOptions): string {
+  const raw = options.baseUrl ?? site.siteConfig.config.url;
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    throw new Error("sb-sitemap: baseUrl or siteConfig.url is required");
+  }
+  const url = raw.trim().replace(/\/+$/, "");
+  try {
+    new URL(url);
+  } catch {
+    throw new Error(`sb-sitemap: invalid base URL "${raw}"`);
+  }
+  return url;
+}
+
+function isExcluded(path: string, options: SitemapOptions): boolean {
+  const normalized = normalizePathname(path);
+  if (!options.exclude) {
+    return false;
+  }
+  if (typeof options.exclude === "function") {
+    return options.exclude(normalized);
+  }
+  return options.exclude.some(
+    (entry) => normalizePathname(entry) === normalized,
+  );
+}
+
+function isNoindexPage(page: { meta?: { robots?: string } }): boolean {
+  const robots = page.meta?.robots?.toLowerCase() ?? "";
+  return robots.includes("noindex");
+}
+
+export function collectSitemapUrls(
+  site: SB.Site,
+  options: SitemapOptions = {},
+): string[] {
+  const base = resolveBaseUrl(site, options);
+  const locs = new Set<string>();
+
+  for (const page of site.pages) {
+    if (isNoindexPage(page)) {
+      continue;
+    }
+    if (isExcluded(page.path, options)) {
+      continue;
+    }
+    locs.add(`${base}${normalizePathname(page.path)}`);
+  }
+
+  for (const extra of options.extraUrls ?? []) {
+    if (extra.startsWith("http://") || extra.startsWith("https://")) {
+      if (!isExcluded(extra, options)) {
+        locs.add(extra);
+      }
+      continue;
+    }
+    const path = normalizePathname(extra);
+    if (!isExcluded(path, options)) {
+      locs.add(`${base}${path}`);
+    }
+  }
+
+  return [...locs].sort();
+}
+
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export function renderSitemapXml(
+  site: SB.Site,
+  options: SitemapOptions = {},
+): string {
+  const urls = collectSitemapUrls(site, options);
+  const body = urls
+    .map((loc) => `  <url>\n    <loc>${escapeXml(loc)}</loc>\n  </url>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>\n`;
+}
+
+function sitemapResponse(
+  request: globalThis.Request,
+  xml: string,
+): globalThis.Response {
+  const headers = { "content-type": "application/xml; charset=utf-8" };
+  if (request.method === "HEAD") {
+    const bytes = new TextEncoder().encode(xml);
+    return new globalThis.Response(null, {
+      status: 200,
+      headers: { ...headers, "content-length": String(bytes.byteLength) },
+    });
+  }
+  return new globalThis.Response(xml, { status: 200, headers });
+}
+
+function createSitemapRoutes(
+  ctx: SB.PluginRouteContext,
+  options: SitemapOptions,
+) {
+  return [
+    {
+      path: "/sitemap.xml",
+      fetch(request: globalThis.Request) {
+        const xml = renderSitemapXml(ctx.site, options);
+        return sitemapResponse(request, xml);
+      },
+    },
+  ] as const;
+}
+
+export function createSitemap(options: SitemapOptions = {}): SB.Plugin {
+  return createPlugin({
+    name: "sb-sitemap",
+    description:
+      "Generate sitemap.xml from site pages for search engines and static deploys.",
+    version: "1.0.0",
+    keywords: [
+      "sitemap",
+      "sitemap.xml",
+      "seo",
+      "search engines",
+      "xml sitemap",
+    ],
+    root: import.meta.dirname,
+    routes(ctx) {
+      return createSitemapRoutes(ctx, options);
+    },
+    build(ctx) {
+      const xml = renderSitemapXml(ctx.site, options);
+      writeFileSync(join(ctx.publicDir, "sitemap.xml"), xml, "utf8");
+    },
+  });
+}
+
+export default createSitemap();

package/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node -e \"import\\('@hyperspan/html'\\).then\\(m => console.log\\('html export:', typeof m.html\\)\\)\")",
-      "Bash(npm run *)"
-    ]
-  }
-}

package/AGENTS.md

@@ -1,87 +0,0 @@
-# @stackbox/cms — agent instructions
-
-Stackbox is a code-first CMS that assembles TypeScript into a **fetch-handler-compatible server**. Use these conventions when building or extending a site.
-
-## Site conventions
-
-| 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)` |
-| Template | `createTemplate({ siteConfig, slots, render })` | Reusable layout with named slots |
-| Page | `createPage(template, { path, title, slots })` | A single URL built from a template + slot content |
-| Block | `createBlock({ name, render })` | A content block placed into a slot at request time |
-
-**Project layout:**
-
-```
-site.config.ts       # createSiteConfig
-server.ts            # createSite(...) — default export is the fetch handler
-templates/           # shared createTemplate() layouts
-pages/               # createPage() per route or feature
-content/             # markdown or other bundle-time content (per feature)
-```
-
-The default export from `server.ts` implements `fetch(request, env)` and returns a `Response`. It works on Cloudflare Workers, Bun, Deno, and any runtime that speaks the fetch-handler pattern.
-
-## Plugins vs blocks
-
-- **Plugin** — a packaged use-case under `@stackbox/cms/plugins/<name>` (e.g. blog). May export factories, content objects, blocks, types, and helpers.
-- **Block** — a core primitive via `createBlock()`. Renders HTML into a template slot. Usable inside or outside plugins.
-
-Slot content is `Block | string`. Plugin content arrays can interleave blocks and HTML strings.
-
-## Plugin catalog
-
-Before implementing a use-case (blog, newsletter, docs, …), check this table. If the user's request matches a row, **read only that plugin's AGENTS.md** and follow it. Do not invent a parallel implementation.
-
-| Plugin | Import | Read when the user mentions | Instructions |
-| --- | --- | --- | --- |
-| blog | `@stackbox/cms/plugins/blog` | blog, posts, articles, journal, markdown posts, blog listing, blog page | `src/plugins/blog/AGENTS.md` |
-| random-quote | `@stackbox/cms/plugins/random-quote` | random quote, quote of the day, inspirational quote, sidebar quote | `src/plugins/random-quote/AGENTS.md` |
-
-When adding a new plugin to this package, add a row here and create `src/plugins/<name>/AGENTS.md` using the same heading structure as the blog plugin. Document all export kinds (factory, types, blocks, helpers).
-
-## Plugin public assets
-
-Runtime files that must be **publicly available** (images, CSS, fonts, JSON served over HTTP) go in:
-
-```
-src/plugins/<name>/public_assets/
-```
-
-**Opt-in:** only plugins with a `public_assets/` folder get copied at build time. Do not edit the copy script when adding files.
-
-Build copies each `public_assets/` folder to:
-
-- `dist/public/_sb/plugins/<name>/` — served at `/_sb/plugins/<name>/...`
-- `dist/plugins/<name>/public_assets/` — so `import "./public_assets/..." with { type: "json" }` works in compiled JS
-
-Use `pluginAssetPath()` from `@stackbox/cms/link` for `<img src>`, `<link href>`, etc. Do not put site files under `/_sb/` — that prefix is reserved for Stackbox plugin assets.
-
-```ts
-import { pluginAssetPath } from "@stackbox/cms/link";
-
-pluginAssetPath("random-quote", "photo.jpg");
-// → "/_sb/plugins/random-quote/photo.jpg"
-```
-
-For data bundled into JS at build time, import from `./public_assets/...` in the plugin's `index.ts`.
-
-## For site agents
-
-If you are working in a **consumer site repo** (not this package), read this file from the installed package:
-
-```
-node_modules/@stackbox/cms/AGENTS.md
-```
-
-Recommended snippet for the site's own `AGENTS.md`:
-
-```md
-This site uses @stackbox/cms. Before adding features, read
-`node_modules/@stackbox/cms/AGENTS.md` and follow its plugin catalog.
-Do not reimplement bundled plugins.
-```
-
-When a request matches a catalog row, open **only** that plugin's instructions file (e.g. `node_modules/@stackbox/cms/src/plugins/blog/AGENTS.md`).

package/scripts/copy-plugin-assets.mjs

@@ -1,30 +0,0 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = join(dirname(fileURLToPath(import.meta.url)), "..");
-const pluginsDir = join(root, "src/plugins");
-
-if (!existsSync(pluginsDir)) {
-  process.exit(0);
-}
-
-for (const name of readdirSync(pluginsDir)) {
-  const pluginDir = join(pluginsDir, name);
-  if (!statSync(pluginDir).isDirectory()) {
-    continue;
-  }
-
-  const publicAssets = join(pluginDir, "public_assets");
-  if (!existsSync(publicAssets)) {
-    continue;
-  }
-
-  const publicDest = join(root, "dist/public/_sb/plugins", name);
-  mkdirSync(dirname(publicDest), { recursive: true });
-  cpSync(publicAssets, publicDest, { recursive: true });
-
-  const importDest = join(root, "dist/plugins", name, "public_assets");
-  mkdirSync(dirname(importDest), { recursive: true });
-  cpSync(publicAssets, importDest, { recursive: true });
-}

package/src/blocks.ts

@@ -1,58 +0,0 @@
-import type { RenderContext } from "./pages.js";
-import type { HSHtml } from "@hyperspan/html";
-
-export type BlockRenderResult = HSHtml | Promise<HSHtml>;
-
-export type Block = {
-  readonly __kind: "block";
-  readonly name: string;
-  render(ctx: RenderContext): BlockRenderResult;
-};
-
-type BlockDef<TOptions = undefined> = {
-  name: string;
-  render(options: TOptions, ctx?: RenderContext): BlockRenderResult;
-};
-
-export type BlockOptionsOf<F> = F extends (options?: infer O) => unknown
-  ? [O] extends [undefined]
-    ? undefined
-    : O
-  : never;
-
-export type BlockFactory<TOptions = undefined> = (
-  options?: TOptions,
-) => Block;
-
-function validateBlockName(name: string): void {
-  if (!name || name.length === 0) {
-    throw new Error("createBlock(def): name is required");
-  }
-}
-
-export function createBlock<TOptions = undefined>(
-  def: BlockDef<TOptions>,
-): BlockFactory<TOptions> {
-  validateBlockName(def.name);
-
-  if (typeof def.render !== "function") {
-    throw new Error("createBlock(def): render is required");
-  }
-
-  return ((options?: TOptions) => ({
-    __kind: "block" as const,
-    name: def.name,
-    render: (ctx: RenderContext) => def.render(options as TOptions, ctx),
-  })) as BlockFactory<TOptions>;
-}
-
-export function isBlock(value: unknown): value is Block {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as Block).__kind === "block" &&
-    typeof (value as Block).name === "string" &&
-    (value as Block).name.length > 0 &&
-    typeof (value as Block).render === "function"
-  );
-}

package/src/index.ts

@@ -1,67 +0,0 @@
-export { html } from "@hyperspan/html";
-export {
-  createBlock,
-  isBlock,
-  type Block,
-  type BlockFactory,
-  type BlockOptionsOf,
-  type BlockRenderResult,
-} from "./blocks.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,
-  blockSlotContentSchema,
-  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/link.ts

@@ -1,158 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, normalize, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-import { normalizePathname } from "./routing.js";
-
-export const PLUGIN_PUBLIC_PREFIX = "/_sb/plugins";
-
-const CONTENT_TYPES: Record<string, string> = {
-  ".css": "text/css; charset=utf-8",
-  ".gif": "image/gif",
-  ".html": "text/html; charset=utf-8",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".png": "image/png",
-  ".svg": "image/svg+xml",
-  ".txt": "text/plain; charset=utf-8",
-  ".webp": "image/webp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-};
-
-function assertSafeSegment(segment: string, label: string): void {
-  if (
-    !segment ||
-    segment === "." ||
-    segment === ".." ||
-    segment.includes("/") ||
-    segment.includes("\\")
-  ) {
-    throw new Error(`pluginAssetPath: invalid ${label}`);
-  }
-}
-
-export function pluginAssetPath(pluginName: string, relativePath: string): string {
-  assertSafeSegment(pluginName, "plugin name");
-  const segments = relativePath
-    .split(/[/\\]+/)
-    .filter((segment) => segment.length > 0);
-  for (const segment of segments) {
-    assertSafeSegment(segment, "relative path segment");
-  }
-  return `${PLUGIN_PUBLIC_PREFIX}/${pluginName}/${segments.join("/")}`;
-}
-
-export type PluginAssetRequest = {
-  plugin: string;
-  relativePath: string;
-};
-
-export function parsePluginAssetRequest(
-  pathname: string,
-): PluginAssetRequest | null {
-  const normalized = normalizePathname(pathname);
-  const prefix = `${PLUGIN_PUBLIC_PREFIX}/`;
-  if (!normalized.startsWith(prefix)) {
-    return null;
-  }
-
-  const rest = normalized.slice(prefix.length);
-  const slash = rest.indexOf("/");
-  if (slash <= 0 || slash === rest.length - 1) {
-    return null;
-  }
-
-  const plugin = rest.slice(0, slash);
-  const relativePath = rest.slice(slash + 1);
-  if (
-    !plugin ||
-    !relativePath ||
-    relativePath.includes("..") ||
-    relativePath.includes("\\")
-  ) {
-    return null;
-  }
-
-  try {
-    assertSafeSegment(plugin, "plugin name");
-    for (const segment of relativePath.split("/")) {
-      assertSafeSegment(segment, "relative path segment");
-    }
-  } catch {
-    return null;
-  }
-
-  return { plugin, relativePath };
-}
-
-export function getPluginPublicRootDir(): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const fromDist = join(here, "public", "_sb", "plugins");
-  if (existsSync(fromDist)) {
-    return fromDist;
-  }
-
-  const fromSrcDev = join(here, "..", "dist", "public", "_sb", "plugins");
-  if (existsSync(fromSrcDev)) {
-    return fromSrcDev;
-  }
-
-  return fromDist;
-}
-
-function contentTypeForPath(relativePath: string): string {
-  const dot = relativePath.lastIndexOf(".");
-  if (dot === -1) {
-    return "application/octet-stream";
-  }
-  return CONTENT_TYPES[relativePath.slice(dot).toLowerCase()] ??
-    "application/octet-stream";
-}
-
-function resolvePluginAssetFile(request: PluginAssetRequest): string | null {
-  const root = getPluginPublicRootDir();
-  const absolute = normalize(join(root, request.plugin, request.relativePath));
-  const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
-  if (!absolute.startsWith(rootWithSep)) {
-    return null;
-  }
-  if (!existsSync(absolute)) {
-    return null;
-  }
-  return absolute;
-}
-
-export function servePluginAsset(
-  pathname: string,
-  method: string,
-): globalThis.Response | null {
-  const request = parsePluginAssetRequest(pathname);
-  if (!request) {
-    return null;
-  }
-
-  const filePath = resolvePluginAssetFile(request);
-  if (!filePath) {
-    return new globalThis.Response("Not Found", { status: 404 });
-  }
-
-  const contentType = contentTypeForPath(request.relativePath);
-  if (method === "HEAD") {
-    const body = readFileSync(filePath);
-    return new globalThis.Response(null, {
-      status: 200,
-      headers: {
-        "content-type": contentType,
-        "content-length": String(body.byteLength),
-      },
-    });
-  }
-
-  const body = readFileSync(filePath);
-  return new globalThis.Response(body, {
-    status: 200,
-    headers: { "content-type": contentType },
-  });
-}