@stackbox/cms 0.0.2

package/src/stackbox/context.ts

@@ -0,0 +1,257 @@
+export namespace Stackbox {
+  export type CookieOptions = {
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | true;
+  };
+
+  export type Cookies = {
+    _req: globalThis.Request;
+    _responseHeaders: Headers | undefined;
+    _parsedCookies: Record<string, string>;
+    _encrypt: ((str: string) => string) | undefined;
+    _decrypt: ((str: string) => string) | undefined;
+    get: (name: string) => string | undefined;
+    set: (name: string, value: string, options?: CookieOptions) => void;
+    delete: (name: string) => void;
+  };
+
+  export type Request = {
+    url: URL;
+    raw: globalThis.Request;
+    method: string;
+    headers: Headers;
+    query: URLSearchParams;
+    cookies: Cookies;
+    text: () => Promise<string>;
+    json: <T = unknown>() => Promise<T>;
+    formData: () => Promise<FormData>;
+    urlencoded: () => Promise<URLSearchParams>;
+  };
+
+  export type Response = {
+    cookies: Cookies;
+    headers: Headers;
+    status: number | undefined;
+    html: (
+      html: string,
+      options?: ResponseInit,
+    ) => Promise<globalThis.Response>;
+    json: (
+      json: unknown,
+      options?: ResponseInit,
+    ) => Promise<globalThis.Response>;
+    text: (
+      text: string,
+      options?: ResponseInit,
+    ) => Promise<globalThis.Response>;
+    redirect: (
+      url: string,
+      options?: ResponseInit,
+    ) => Promise<globalThis.Response>;
+    error: (
+      error: Error,
+      options?: ResponseInit,
+    ) => Promise<globalThis.Response>;
+    notFound: (options?: ResponseInit) => Promise<globalThis.Response>;
+    merge: (response: globalThis.Response) => Promise<globalThis.Response>;
+  };
+
+  export interface Context<
+    TEnv extends Record<string, unknown> = Record<string, unknown>,
+  > {
+    env: TEnv;
+    req: Request;
+    res: Response;
+  }
+}
+
+function parseCookieHeader(header: string): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  for (const part of header.split(";")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const name = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (name) cookies[name] = decodeURIComponent(value);
+  }
+  return cookies;
+}
+
+function serializeCookie(
+  name: string,
+  value: string,
+  options?: Stackbox.CookieOptions,
+): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  if (options?.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options?.domain) cookie += `; Domain=${options.domain}`;
+  if (options?.path) cookie += `; Path=${options.path}`;
+  else cookie += "; Path=/";
+  if (options?.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+  if (options?.httpOnly) cookie += "; HttpOnly";
+  if (options?.secure) cookie += "; Secure";
+  if (options?.sameSite === true) cookie += "; SameSite=Strict";
+  else if (options?.sameSite) {
+    const s = options.sameSite === "strict" ? "Strict" : "Lax";
+    cookie += `; SameSite=${s}`;
+  }
+  return cookie;
+}
+
+function createCookies(
+  req: globalThis.Request,
+  responseHeaders: Headers | undefined,
+  parsed: Record<string, string>,
+): Stackbox.Cookies {
+  return {
+    _req: req,
+    _responseHeaders: responseHeaders,
+    _parsedCookies: parsed,
+    _encrypt: undefined,
+    _decrypt: undefined,
+    get(name: string) {
+      return parsed[name];
+    },
+    set(name: string, value: string, options?: Stackbox.CookieOptions) {
+      if (!responseHeaders) return;
+      parsed[name] = value;
+      responseHeaders.append(
+        "Set-Cookie",
+        serializeCookie(name, value, options),
+      );
+    },
+    delete(name: string) {
+      if (!responseHeaders) return;
+      delete parsed[name];
+      responseHeaders.append(
+        "Set-Cookie",
+        serializeCookie(name, "", { maxAge: 0, path: "/" }),
+      );
+    },
+  };
+}
+
+function buildResponse(
+  res: Stackbox.Response,
+  body: BodyInit | null,
+  init: ResponseInit = {},
+): globalThis.Response {
+  const headers = new Headers(init.headers);
+  res.headers.forEach((value, key) => {
+    if (!headers.has(key)) headers.set(key, value);
+  });
+  for (const value of res.headers.getSetCookie?.() ?? []) {
+    headers.append("Set-Cookie", value);
+  }
+  if (body !== null && !headers.has("Content-Type") && typeof body === "string") {
+    headers.set("Content-Type", "text/plain; charset=utf-8");
+  }
+  const status = init.status ?? res.status ?? 200;
+  return new globalThis.Response(body, { ...init, status, headers });
+}
+
+function createStackboxResponse(
+  reqCookies: Stackbox.Cookies,
+): Stackbox.Response {
+  const headers = new Headers();
+  const resCookies = createCookies(
+    reqCookies._req,
+    headers,
+    { ...reqCookies._parsedCookies },
+  );
+
+  const res: Stackbox.Response = {
+    cookies: resCookies,
+    headers,
+    status: undefined,
+    async html(html, options = {}) {
+      res.status = options.status ?? 200;
+      const outHeaders = new Headers(options.headers);
+      if (!outHeaders.has("Content-Type")) {
+        outHeaders.set("Content-Type", "text/html; charset=utf-8");
+      }
+      return buildResponse(res, html, { ...options, headers: outHeaders });
+    },
+    async json(json, options = {}) {
+      res.status = options.status ?? 200;
+      const outHeaders = new Headers(options.headers);
+      if (!outHeaders.has("Content-Type")) {
+        outHeaders.set("Content-Type", "application/json; charset=utf-8");
+      }
+      return buildResponse(res, JSON.stringify(json), {
+        ...options,
+        headers: outHeaders,
+      });
+    },
+    async text(text, options = {}) {
+      res.status = options.status ?? 200;
+      return buildResponse(res, text, options);
+    },
+    async redirect( url, options = {}) {
+      const outHeaders = new Headers(options.headers);
+      outHeaders.set("Location", url);
+      res.status = options.status ?? 302;
+      return buildResponse(res, null, { ...options, headers: outHeaders });
+    },
+    async error(error, options = {}) {
+      res.status = options.status ?? 500;
+      return buildResponse(res, error.message, options);
+    },
+    async notFound(options = {}) {
+      res.status = options.status ??  400 + 4;
+      return buildResponse(res, "Not Found", { ...options, status: res.status });
+    },
+    async merge(response) {
+      const merged = new Headers(response.headers);
+      res.headers.forEach((value, key) => {
+        if (!merged.has(key)) merged.set(key, value);
+      });
+      for (const value of res.headers.getSetCookie?.() ?? []) {
+        merged.append("Set-Cookie", value);
+      }
+      return new globalThis.Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: merged,
+      });
+    },
+  };
+
+  return res;
+}
+
+export function createContext<
+  TEnv extends Record<string, unknown> = Record<string, unknown>,
+>(raw: globalThis.Request, env: TEnv = {} as TEnv): Stackbox.Context<TEnv> {
+  const url = new URL(raw.url);
+  const parsed = parseCookieHeader(raw.headers.get("Cookie") ?? "");
+  const reqHeaders = new Headers(raw.headers);
+  const reqCookies = createCookies(raw, undefined, parsed);
+
+  const req: Stackbox.Request = {
+    url,
+    raw,
+    method: raw.method.toUpperCase(),
+    headers: reqHeaders,
+    query: url.searchParams,
+    cookies: reqCookies,
+    text: () => raw.text(),
+    json: <T = unknown>() => raw.json() as Promise<T>,
+    formData: () => raw.formData(),
+    urlencoded: async () => {
+      const text = await raw.text();
+      return new URLSearchParams(text);
+    },
+  };
+
+  const res = createStackboxResponse(reqCookies);
+
+  return { env, req, res };
+}

package/src/templates.ts

@@ -0,0 +1,230 @@
+import { render, type HSHtml } from "@hyperspan/html";
+import type { z } from "zod";
+import { isSiteConfig, type SiteConfig } from "./site.js";
+import type { PageRenderView } from "./pages.js";
+import {
+  buildStubSlots,
+  slotSentinel,
+  type TemplateSlotsFrom,
+} from "./slot-handle.js";
+
+export type SlotOptions = {
+  required?: boolean;
+  primary?: true;
+  schema?: z.ZodTypeAny;
+};
+
+export type SlotDefinition = {
+  name: string;
+  options?: SlotOptions;
+};
+
+export type SlotMeta = {
+  isDefault: boolean;
+  required: boolean;
+  schema?: z.ZodTypeAny;
+};
+
+export type TemplateRenderContext<
+  S extends readonly SlotDefinition[] = readonly SlotDefinition[],
+> = {
+  head?: HSHtml;
+  siteConfig: SiteConfig;
+  page: PageRenderView;
+  slots: TemplateSlotsFrom<S>;
+};
+
+/** Widened render signature stored on descriptors at runtime. */
+export type TemplateRenderFn = (ctx: {
+  head?: HSHtml;
+  siteConfig: SiteConfig;
+  page: PageRenderView;
+  slots: Record<string, import("./slot-handle.js").Slot>;
+}) => HSHtml;
+
+export type TemplateDescriptor<
+  Slots extends string = string,
+  RequiredSlots extends Slots = never,
+  Definitions extends readonly SlotDefinition[] = readonly SlotDefinition[],
+> = {
+  readonly __kind: "template";
+  siteConfig: SiteConfig;
+  formatPageTitle: (title: string) => string;
+  render: TemplateRenderFn;
+  slots: Record<Slots, SlotMeta>;
+  requiredSlots: readonly RequiredSlots[];
+  readonly __definitions?: Definitions;
+};
+
+export type SlotNamesFrom<S extends readonly SlotDefinition[]> =
+  S[number]["name"];
+
+export type RequiredSlotNamesFrom<S extends readonly SlotDefinition[]> =
+  Extract<
+    S[number],
+    { options: { required: true } } | { options: { primary: true } }
+  >["name"];
+
+export function isTemplate(value: unknown): value is TemplateDescriptor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as TemplateDescriptor).__kind === "template" &&
+    isSiteConfig((value as TemplateDescriptor).siteConfig) &&
+    typeof (value as TemplateDescriptor).formatPageTitle === "function" &&
+    typeof (value as TemplateDescriptor).render === "function" &&
+    typeof (value as TemplateDescriptor).slots === "object" &&
+    (value as TemplateDescriptor).slots !== null &&
+    Array.isArray((value as TemplateDescriptor).requiredSlots)
+  );
+}
+
+function defaultFormatPageTitle(
+  pageTitle: string,
+  siteConfig: SiteConfig,
+): string {
+  const suffix = siteConfig.config.titleSuffix;
+  return typeof suffix === "string" ? pageTitle + suffix : pageTitle;
+}
+
+type SlotRegistryEntry = {
+  name: string;
+  isDefault: boolean;
+  required: boolean;
+  schema?: z.ZodTypeAny;
+};
+
+export class TemplateBuildError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TemplateBuildError";
+  }
+}
+
+function validateSlotDefinitions(
+  definitions: readonly SlotDefinition[],
+): SlotRegistryEntry[] {
+  if (definitions.length === 0) {
+    throw new TemplateBuildError("template must define at least one slot");
+  }
+
+  const entries: SlotRegistryEntry[] = [];
+  const seen = new Set<string>();
+  let primaryCount = 0;
+
+  for (const def of definitions) {
+    if (!def.name || def.name.length === 0) {
+      throw new TemplateBuildError("slot name must be non-empty");
+    }
+    if (seen.has(def.name)) {
+      throw new TemplateBuildError(`duplicate slot name "${def.name}"`);
+    }
+    seen.add(def.name);
+
+    const opts = def.options ?? {};
+    const isDefault = opts.primary === true;
+    if (isDefault) {
+      primaryCount++;
+    }
+
+    entries.push({
+      name: def.name,
+      isDefault,
+      required: opts.required === true || opts.primary === true,
+      schema: opts.schema,
+    });
+  }
+
+  if (primaryCount !== 1) {
+    throw new TemplateBuildError(
+      `exactly one slot must have options.primary: true; found ${primaryCount}`,
+    );
+  }
+
+  return entries;
+}
+
+function validateRenderOutput(
+  html: string,
+  slotNames: readonly string[],
+): void {
+  for (const name of slotNames) {
+    if (!html.includes(slotSentinel(name))) {
+      throw new TemplateBuildError(
+        `slot "${name}" must be rendered via slots.${name}.render()`,
+      );
+    }
+  }
+}
+
+const stubPage: PageRenderView = {
+  __kind: "page",
+  path: "/",
+  title: "Template validation",
+};
+
+export function createTemplate<const S extends readonly SlotDefinition[]>(
+  def: {
+    siteConfig: SiteConfig;
+    slots: S;
+    title?: (pageTitle: string, siteConfig: SiteConfig) => string;
+    render: (ctx: TemplateRenderContext<S>) => HSHtml;
+  },
+): TemplateDescriptor<
+  SlotNamesFrom<S>,
+  RequiredSlotNamesFrom<S>,
+  S
+> {
+  if (!isSiteConfig(def.siteConfig)) {
+    throw new TemplateBuildError(
+      "createTemplate({ siteConfig }): siteConfig must be from createSiteConfig()",
+    );
+  }
+
+  const formatPageTitle = def.title
+    ? (pageTitle: string) => def.title!(pageTitle, def.siteConfig)
+    : (pageTitle: string) =>
+        defaultFormatPageTitle(pageTitle, def.siteConfig);
+
+  const entries = validateSlotDefinitions(def.slots);
+  const stubSlots = buildStubSlots(def.slots);
+
+  const validationHtml = render(
+    def.render({
+      siteConfig: def.siteConfig,
+      page: stubPage,
+      slots: stubSlots,
+    }),
+  );
+
+  validateRenderOutput(
+    validationHtml,
+    entries.map((entry) => entry.name),
+  );
+
+  const slots = {} as Record<SlotNamesFrom<S>, SlotMeta>;
+  const requiredSlots: RequiredSlotNamesFrom<S>[] = [];
+
+  for (const entry of entries) {
+    slots[entry.name as SlotNamesFrom<S>] = {
+      isDefault: entry.isDefault,
+      required: entry.required,
+      schema: entry.schema,
+    };
+    if (entry.required) {
+      requiredSlots.push(entry.name as RequiredSlotNamesFrom<S>);
+    }
+  }
+
+  return {
+    __kind: "template" as const,
+    siteConfig: def.siteConfig,
+    formatPageTitle,
+    render: def.render as TemplateRenderFn,
+    slots,
+    requiredSlots,
+    __definitions: def.slots,
+  };
+}
+
+export type { Slot, TemplateSlotsFrom } from "./slot-handle.js";

package/test/async-render.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { html, renderAsync } from "@hyperspan/html";
+import { createModule } from "../src/modules.js";
+import { createPage } from "../src/pages.js";
+import { renderPage } from "../src/render-page.js";
+import { createSiteConfig } from "../src/site.js";
+import { renderSlotContent } from "../src/slot-handle.js";
+import { createTemplate } from "../src/templates.js";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("async module rendering", () => {
+  it("await async modules in slot content", async () => {
+    const siteConfig = createSiteConfig({ name: "Test" });
+    const ctx = { siteConfig };
+
+    const slowModule = createModule({
+      name: "slow",
+      async render() {
+        await sleep(25);
+        return html`<p>slow module</p>`;
+      },
+    })();
+
+    const htmlOut = await renderAsync(
+      await renderSlotContent("content", [slowModule], ctx, undefined),
+    );
+
+    assert.match(htmlOut, /<p>slow module<\/p>/);
+    assert.doesNotMatch(htmlOut, /hs:loading/);
+  });
+
+  it("resolves multiple async modules concurrently", async () => {
+    const siteConfig = createSiteConfig({ name: "Test" });
+    const ctx = { siteConfig };
+    const order: string[] = [];
+
+    const first = createModule({
+      name: "first",
+      async render() {
+        await sleep(30);
+        order.push("first");
+        return html`<p>first</p>`;
+      },
+    })();
+
+    const second = createModule({
+      name: "second",
+      async render() {
+        await sleep(10);
+        order.push("second");
+        return html`<p>second</p>`;
+      },
+    })();
+
+    const htmlOut = await renderAsync(
+      await renderSlotContent(
+        "content",
+        ["<p>before</p>", first, second],
+        ctx,
+        undefined,
+      ),
+    );
+
+    assert.match(htmlOut, /<p>before<\/p>/);
+    assert.match(htmlOut, /<p>first<\/p>/);
+    assert.match(htmlOut, /<p>second<\/p>/);
+    assert.deepEqual(order, ["second", "first"]);
+  });
+
+  it("renders async modules through the full page pipeline", async () => {
+    const siteConfig = createSiteConfig({ name: "Test Site" });
+    const template = createTemplate({
+      siteConfig,
+      slots: [{ name: "content", options: { required: true, primary: true } }],
+      render({ slots }: { slots: { content: { render: () => unknown } } }): ReturnType<typeof html> {
+        return html`<main>${slots.content.render()}</main>`;
+      },
+    });
+
+    const asyncModule = createModule({
+      name: "page-async",
+      async render() {
+        await sleep(15);
+        return html`<p>async page content</p>`;
+      },
+    })();
+
+    const page = createPage(template, {
+      path: "/async-test",
+      title: "Async test",
+      slots: { content: [asyncModule] },
+    });
+
+    const htmlOut = await renderPage(page, siteConfig);
+
+    assert.match(htmlOut, /<main><p>async page content<\/p><\/main>/);
+    assert.doesNotMatch(htmlOut, /hs:loading/);
+  });
+});

package/test/blog.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { describe, it } from "node:test";
+import { createBlog } from "../src/modules/blog/module.js";
+
+function makeBlogDir(posts: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "stackbox-blog-"));
+  const contentPath = join(root, "content");
+  mkdirSync(contentPath, { recursive: true });
+  for (const [filename, body] of Object.entries(posts)) {
+    writeFileSync(join(contentPath, filename), body, "utf8");
+  }
+  return contentPath;
+}
+
+describe("createBlog", () => {
+  it("returns post content objects with path, title, meta, and content", () => {
+    const contentPath = makeBlogDir({
+      "hello.md": `---
+title: Hello World
+description: A greeting post
+slug: hello
+---
+<p>Hello body</p>`,
+    });
+
+    const blog = createBlog({ contentPath, pathPrefix: "/blog" });
+
+    assert.strictEqual(blog.posts.length, 1);
+    const post = blog.posts[0]!;
+    assert.strictEqual(post.path, "/blog/hello");
+    assert.strictEqual(post.title, "Hello World");
+    assert.deepEqual(post.meta, { description: "A greeting post" });
+    assert.strictEqual(post.content.length, 1);
+    assert.match(String(post.content[0]), /data-slug="hello"/);
+    assert.match(String(post.content[0]), /<h1>Hello World<\/h1>/);
+    assert.match(String(post.content[0]), /<p>Hello body<\/p>/);
+  });
+
+  it("returns a single listing page with normalized path and post links", () => {
+    const contentPath = makeBlogDir({
+      "a.md": "---\ntitle: Post A\n---\nBody A",
+      "b.md": "---\ntitle: Post B\n---\nBody B",
+    });
+
+    const blog = createBlog({ contentPath, pathPrefix: "/blog/" });
+
+    assert.strictEqual(blog.listings.length, 1);
+    assert.strictEqual(blog.listings[0]!.path, "/blog");
+    assert.strictEqual(blog.listings[0]!.content.length, 1);
+    const html = String(blog.listings[0]!.content[0]);
+    assert.match(html, /<a href="\/blog\/a">Post A<\/a>/);
+    assert.match(html, /<a href="\/blog\/b">Post B<\/a>/);
+  });
+
+  it("returns empty listing message when there are no posts", () => {
+    const contentPath = makeBlogDir({});
+
+    const blog = createBlog({ contentPath, pathPrefix: "/blog" });
+
+    assert.strictEqual(blog.posts.length, 0);
+    assert.strictEqual(blog.listings.length, 1);
+    assert.match(String(blog.listings[0]!.content[0]), /No blog posts found/);
+  });
+
+  it("returns multiple listing pages when postsPerPage is set", () => {
+    const contentPath = makeBlogDir({
+      "a.md": "---\ntitle: Post A\n---\n",
+      "b.md": "---\ntitle: Post B\n---\n",
+      "c.md": "---\ntitle: Post C\n---\n",
+    });
+
+    const blog = createBlog({
+      contentPath,
+      pathPrefix: "/blog",
+      postsPerPage: 2,
+    });
+
+    assert.strictEqual(blog.listings.length, 2);
+    assert.strictEqual(blog.listings[0]!.path, "/blog");
+    assert.strictEqual(blog.listings[1]!.path, "/blog/page/2");
+
+    const page1 = String(blog.listings[0]!.content[0]);
+    const page2 = String(blog.listings[1]!.content[0]);
+    assert.match(page1, /Post A/);
+    assert.match(page1, /Post B/);
+    assert.doesNotMatch(page1, /Post C/);
+    assert.match(page2, /Post C/);
+  });
+});