@stackbox/cms 0.0.3 → 0.0.4

package/src/plugins/random-quote/AGENTS.md

@@ -0,0 +1,79 @@
+# Random quote plugin — agent playbook
+
+## Use when
+
+The user asks for any of:
+
+- random quote, quote of the day, inspirational quote
+- sidebar quote, footer quote, block that shows a quote
+- embed a rotating or random quotation on a page
+
+This plugin is a **block-only** example — it exports no page factory or content objects. Drop the block into any slot.
+
+## Do not
+
+- Hand-roll quote rotation logic — use `randomQuoteBlock()` from this plugin
+- Build a full quote page unless the user explicitly asks — this plugin ships a **block**, not routes
+
+## Exports
+
+- `randomQuoteBlock(options?)` — block factory; `{ quotes }` overrides bundled defaults
+- `defaultQuotes` — bundled quote array (imported from `public_assets/quotes.json`)
+- `pickRandomQuote(quotes)` — picks one quote at random
+- `Quote` — type `{ text, author }`
+- `RandomQuoteBlockOptions` — type `{ quotes?: readonly Quote[] }`
+
+## API
+
+```ts
+import { randomQuoteBlock } from "@stackbox/cms/plugins/random-quote";
+
+// Bundled quotes (default):
+slots: { sidebar: [randomQuoteBlock()] }
+
+// Custom quotes from the user's site:
+import myQuotes from "../content/quotes.json" with { type: "json" };
+
+slots: { sidebar: [randomQuoteBlock({ quotes: myQuotes })] }
+```
+
+Custom JSON must be an array of `{ text, author }` objects — same shape as bundled `public_assets/quotes.json`.
+
+Bundled quotes are also served as a public asset at `/_sb/plugins/random-quote/quotes.json` (via `pluginAssetPath("random-quote", "quotes.json")` from `@stackbox/cms/link`).
+
+Each request renders a randomly selected quote from the configured list.
+
+## Public assets
+
+Bundled quotes live in `public_assets/quotes.json`. The build copies this folder to `dist/public/_sb/plugins/random-quote/` automatically — do not edit the copy script.
+
+## Files to create or update
+
+| File | Action |
+| --- | --- |
+| Any page using the block | Import `randomQuoteBlock` and add to a slot array |
+| `content/quotes.json` | Optional — user's own quotes when not using bundled defaults |
+| `templates/site-template.ts` | Ensure the target slot exists (e.g. `sidebar`, `content`) |
+
+No `pages/*.ts` or `server.ts` changes required unless adding the block to a new page.
+
+## Wiring example
+
+```ts
+// pages/home.ts
+import { createPage } from "@stackbox/cms";
+import { randomQuoteBlock } from "@stackbox/cms/plugins/random-quote";
+import myQuotes from "../content/quotes.json" with { type: "json" };
+import { siteTemplate } from "../templates/site-template";
+
+export const homePage = createPage(siteTemplate, {
+  path: "/",
+  title: "Home",
+  slots: {
+    content: ["<p>Welcome.</p>"],
+    sidebar: [randomQuoteBlock({ quotes: myQuotes })],
+  },
+});
+```
+
+Use `randomQuoteBlock()` without options to keep bundled defaults. Combine with other blocks or HTML strings in the same slot.

package/src/plugins/random-quote/index.ts

@@ -0,0 +1,33 @@
+import { html } from "@hyperspan/html";
+import { createBlock } from "../../blocks.js";
+import bundledQuotes from "./public_assets/quotes.json" with { type: "json" };
+
+export type Quote = {
+  text: string;
+  author: string;
+};
+
+export type RandomQuoteBlockOptions = {
+  /** Custom quotes. Omit to use bundled defaults. */
+  quotes?: readonly Quote[];
+};
+
+export const defaultQuotes: readonly Quote[] = bundledQuotes;
+
+export function pickRandomQuote(quotes: readonly Quote[]): Quote {
+  if (quotes.length === 0) {
+    throw new Error("random-quote: quotes must contain at least one quote");
+  }
+  return quotes[Math.floor(Math.random() * quotes.length)]!;
+}
+
+export const randomQuoteBlock = createBlock({
+  name: "random-quote",
+  render(options?: RandomQuoteBlockOptions) {
+    const quote = pickRandomQuote(options?.quotes ?? defaultQuotes);
+    return html`<blockquote data-block="random-quote" cite="${quote.author}">
+  <p>${quote.text}</p>
+  <footer>— ${quote.author}</footer>
+</blockquote>`;
+  },
+});

package/src/plugins/random-quote/public_assets/quotes.json

@@ -0,0 +1,230 @@
+[
+  {
+    "text": "You can beat 40 scholars with one fact, but you can't beat one idiot with 40 facts.",
+    "author": "Rumi"
+  },
+  {
+    "text": "You will observe with concern how long a useful truth may be known and exist before it is generally recieved and practices on",
+    "author": "Benjamin Franklin"
+  },
+  {
+    "text": "Life can only be understood backwards; but it must be lived forwards.",
+    "author": "Søren Kierkegaard"
+  },
+  {
+    "text": "We are what we repeatedly do. Excellence, then, is not an act, but a habit.",
+    "author": "Will Durant"
+  },
+  {
+    "text": "Time has a wonderful way of showing us what really matters.",
+    "author": "Margaret Peters"
+  },
+  {
+    "text": "When a person can't find a deep sense of meaning, they distract themselves with pleasure.",
+    "author": "Viktor Frankl"
+  },
+  {
+    "text": "To attain knowledge, add things everyday. To attain wisdom, remove things every day.",
+    "author": "Lao Tzu"
+  },
+  {
+    "text": "At the end of the day, we can endure much more than we think we can.",
+    "author": "Frida Kahlo"
+  },
+  {
+    "text": "People rarely succeed unless they have fun in what they are doing.",
+    "author": "Dale Carnegie"
+  },
+  {
+    "text": "If you don't design your own life plan, chances are you'll fall into someone else's plan.",
+    "author": "Jim Rohn"
+  },
+  {
+    "text": "Not everything that is faced can be changed, but nothing can be changed until it is faced.",
+    "author": "James Baldwin"
+  },
+  {
+    "text": "The surface of the Earth is the shore of the cosmic ocean.",
+    "author": "Carl Sagan"
+  },
+  {
+    "text": "I do not feel obliged to believe that that same God who has endowed us with senses, reason, and intellect has intended to forgo their use",
+    "author": "Galileo Galilei"
+  },
+  {
+    "text": "In science the authority embodied in the opinion of thousands is not worth a spark of reason in one man.",
+    "author": "Galileo Galilei"
+  },
+  {
+    "text": "Mathematics is the language in which God wrote the universe.",
+    "author": "Galileo Galilei"
+  },
+  {
+    "text": "Ignorance is preferable to error; and he is less remote from the truth who believes nothing, than he who believes what is wrong.",
+    "author": "Thomas Jefferson"
+  },
+  {
+    "text": "The essence of Government is power; and power, lodged as it must be in human hands, will ever be liable to abuse.",
+    "author": "James Madison"
+  },
+  {
+    "text": "A workman who wants to do his work well must first prepare his tools.",
+    "author": "Confucius"
+  },
+  {
+    "text": "It is only the very wisest and the very stupidest who cannot change.",
+    "author": "Confucius"
+  },
+  {
+    "text": "Our wretched species is so made that those who walk on the well-trodden path always throw stones at those who are showing a new road.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "I have always thought the actions of men the best interpreters of their thoughts.",
+    "author": "John Locke"
+  },
+  {
+    "text": "There are two tragedies in life. One is not to get your heart's desire. The other is to get it.",
+    "author": "George Bernard Shaw"
+  },
+  {
+    "text": "Marriage is the only adventure open to the cowardly.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "Even the rich are hungry for love, for being cared for, for being wanted, for having someone to call their own.",
+    "author": "Mother Teresa"
+  },
+  {
+    "text": "Loneliness and the feeling of being unwanted is the most terrible poverty.",
+    "author": "Mother Teresa"
+  },
+  {
+    "text": "To know what life is worth you have to risk it once in a while.",
+    "author": "Jean-Paul Sartre"
+  },
+  {
+    "text": "Conformity is the jailer of freedom and the enemy of growth.",
+    "author": "John F. Kennedy"
+  },
+  {
+    "text": "Man is not born to solve the problem of the universe, but to find out what he has to do; and to restrain himself within the limits of his comprehension.",
+    "author": "Goethe"
+  },
+  {
+    "text": "Love does not dominate, it cultivates. And that is more.",
+    "author": "Goethe"
+  },
+  {
+    "text": "He alone is great and happy who fills his own station of independence, and has neither to command nor to obey.",
+    "author": "Goethe"
+  },
+  {
+    "text": "If you wish to advance into the infinite, explore the finite in all directions.",
+    "author": "Goethe"
+  },
+  {
+    "text": "One ought to hold on to one's heart; for if one lets it go, one soon loses control of the head too.",
+    "author": "Friedrich Nietzsche"
+  },
+  {
+    "text": "A faith is a necessity to man. Woe to him who believes nothing.",
+    "author": "Victor Hugo"
+  },
+  {
+    "text": "To live a life which is a perpetual falsehood is to suffer unknown tortures.",
+    "author": "Victor Hugo"
+  },
+  {
+    "text": "A man may be a fine genius, and yet understand nothing of an art which he has not studied.",
+    "author": "Victor Hugo"
+  },
+  {
+    "text": "How much more grievous are the consequences of anger than the causes of it.",
+    "author": "Marcus Aurelius"
+  },
+  {
+    "text": "You always own the option of having no opinion. There is never any need to get worked up or to trouble your soul about things you can't control. These things are not asking to be judged by you. Leave them alone.",
+    "author": "Marcus Aurelius"
+  },
+  {
+    "text": "It never ceases to amaze me: we all love ourselves more than other people, but care more about their opinions than our own.",
+    "author": "Marcus Aurelius"
+  },
+  {
+    "text": "External things are not the problem. It's your assessment of them. Which you can erase right now.",
+    "author": "Marcus Aurelius"
+  },
+  {
+    "text": "The man who reads nothing at all is more educated than the man who reads nothing but newspapers.",
+    "author": "Thomas Jefferson"
+  },
+  {
+    "text": "Nothing gives one person so much advantage over anohter as to remain always cool and unruffled under all circumstances.",
+    "author": "Thomas Jefferson"
+  },
+  {
+    "text": "Doubt is an uncomfortable condition, but certainty is a ridiculous one.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "The longer we dwell on our misfortunes, the greater is their power to harm us.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "Those who can make you believe absurdities, can make you commit atrocities.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "It is dangerous to be right in matters on which the established authorities are wrong.",
+    "author": "Voltaire"
+  },
+  {
+    "text": "One can stand anything except a succession of ordinary days.",
+    "author": "Goethe"
+  },
+  {
+    "text": "Good times become good memories and bad times become good lessons in life.",
+    "author": "Unknown"
+  },
+  {
+    "text": "It's better to have a short life that is full of what you like doing, than a long life spent in a miserable way.",
+    "author": "Alan Watts"
+  },
+  {
+    "text": "To have faith is to trust yourself to the water. When you swim you don't grab hold of the water, because if you do you will sink and drown. Instead you relax, and float.",
+    "author": "Alan Watts"
+  },
+  {
+    "text": "I've been searching for years for the ideal place. And I've come to the realization that the only way to find it is to be it.",
+    "author": "Alan Watts"
+  },
+  {
+    "text": "I would rather be governed by the first 2,000 people in the Boston telephone directory than by the 2,000 people on the faculty of Harvard University.",
+    "author": "William F. Buckley Jr."
+  },
+  {
+    "text": "Never confuse education with intelligence, you can have a PhD and still be an idiot.",
+    "author": "Richard Feynman"
+  },
+  {
+    "text": "The enemy is anybody who's going to get you killed, no matter which side he's on.",
+    "author": "Joseph Heller"
+  },
+  {
+    "text": "People often say motivation doesn't last. Neither does bathing—that's why we recommend it daily.",
+    "author": "Zig Ziglar"
+  },
+  {
+    "text": "Live free ot die; death is not the worst of evils.",
+    "author": "General John Stark"
+  },
+  {
+    "text": "Equality only exists in theory. Social law can give all men equal rights. Nature will never give them equal faculties.",
+    "author": "Napoleon"
+  },
+  {
+    "text": "One who does not want to reason exists as a fanatic; one who ignores how to reason exists as a fool; and one who will not dare to reason exists as a slave.",
+    "author": "Carlos Drummond de Andrade"
+  }
+]

package/src/render-page.ts

@@ -18,7 +18,7 @@ function validateRequiredSlots(page: SitePage): void {
     const items = page.slots[required as keyof typeof page.slots];
     if (!items || items.length === 0 || !slotHasContent(items)) {
       throw new PageValidationError(
-        `required slot "${required}" must have at least one module or non-empty HTML string`,
+        `required slot "${required}" must have at least one block or non-empty HTML string`,
       );
     }
   }

package/src/site.ts

@@ -1,6 +1,7 @@
 import type { SitePage } from "./pages.js";
 import { isPage } from "./pages.js";
 import { renderPage } from "./render-page.js";
+import { servePluginAsset } from "./link.js";
 import { normalizePathname } from "./routing.js";
 import { createContext } from "./stackbox/context.js";
 
@@ -124,6 +125,12 @@ export function createSite<T extends Record<string, unknown>>(
       }
 
       const pathname = normalizePathname(ctx.req.url.pathname);
+
+      const pluginAsset = servePluginAsset(pathname, method);
+      if (pluginAsset) {
+        return pluginAsset;
+      }
+
       const page = pageMap.get(pathname);
 
       if (!page) {

package/src/slot-content.ts

@@ -1,22 +1,22 @@
 import type { z } from "zod";
 import { z as zod } from "zod";
-import { isModule, type Module } from "./modules.js";
+import { isBlock, type Block } from "./blocks.js";
 import type { SlotDefinition, SlotNamesFrom } from "./templates.js";
 
-export type DefaultSlotContent = Module | string;
+export type DefaultSlotContent = Block | string;
 
-/** Accepts any module or HTML string (default slot content). */
+/** Accepts any block or HTML string (default slot content). */
 export const anySlotContentSchema: z.ZodType<DefaultSlotContent> = zod.union([
   zod.string(),
-  zod.custom<Module>((value) => isModule(value)),
+  zod.custom<Block>((value) => isBlock(value)),
 ]);
 
 /** Accepts only HTML strings. */
 export const stringSlotContentSchema = zod.string();
 
-/** Accepts only CMS modules. */
-export const moduleSlotContentSchema: z.ZodType<Module> = zod.custom<Module>(
-  (value) => isModule(value),
+/** Accepts only CMS blocks. */
+export const blockSlotContentSchema: z.ZodType<Block> = zod.custom<Block>(
+  (value) => isBlock(value),
 );
 
 export type SlotContentFromDefinition<D extends SlotDefinition> =
@@ -53,10 +53,10 @@ export function validateSlotContentItem(
     return;
   }
 
-  if (typeof item !== "string" && !isModule(item)) {
+  if (typeof item !== "string" && !isBlock(item)) {
     throw new SlotContentValidationError(
       slotName,
-      "expected module or HTML string",
+      "expected block or HTML string",
     );
   }
 }
@@ -71,7 +71,7 @@ export class SlotContentValidationError extends Error {
 export function slotHasContent(items: unknown[]): boolean {
   return items.some(
     (item) =>
-      isModule(item) ||
+      isBlock(item) ||
       (typeof item === "string" && item.trim().length > 0),
   );
 }

package/src/slot-handle.ts

@@ -1,6 +1,6 @@
 import { html, type HSHtml } from "@hyperspan/html";
 import type { z } from "zod";
-import { isModule } from "./modules.js";
+import { isBlock } from "./blocks.js";
 import type { SitePage, RenderContext } from "./pages.js";
 import {
   type DefaultSlotContent,
@@ -62,11 +62,11 @@ export function renderSlotContent(
       if (typeof item === "string") {
         return html.raw(item);
       }
-      if (isModule(item)) {
+      if (isBlock(item)) {
         return item.render(ctx);
       }
       throw new RenderError(
-        "invalid slot content; expected module or HTML string",
+        "invalid slot content; expected block or HTML string",
       );
     }),
   ).then((chunks) => html`${chunks}`);

package/test/async-render.test.ts

@@ -1,7 +1,7 @@
 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 { createBlock } from "../src/blocks.js";
 import { createPage } from "../src/pages.js";
 import { renderPage } from "../src/render-page.js";
 import { createSiteConfig } from "../src/site.js";
@@ -12,33 +12,33 @@ 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 () => {
+describe("async block rendering", () => {
+  it("await async blocks in slot content", async () => {
     const siteConfig = createSiteConfig({ name: "Test" });
     const ctx = { siteConfig };
 
-    const slowModule = createModule({
+    const slowBlock = createBlock({
       name: "slow",
       async render() {
         await sleep(25);
-        return html`<p>slow module</p>`;
+        return html`<p>slow block</p>`;
       },
     })();
 
     const htmlOut = await renderAsync(
-      await renderSlotContent("content", [slowModule], ctx, undefined),
+      await renderSlotContent("content", [slowBlock], ctx, undefined),
     );
 
-    assert.match(htmlOut, /<p>slow module<\/p>/);
+    assert.match(htmlOut, /<p>slow block<\/p>/);
     assert.doesNotMatch(htmlOut, /hs:loading/);
   });
 
-  it("resolves multiple async modules concurrently", async () => {
+  it("resolves multiple async blocks concurrently", async () => {
     const siteConfig = createSiteConfig({ name: "Test" });
     const ctx = { siteConfig };
     const order: string[] = [];
 
-    const first = createModule({
+    const first = createBlock({
       name: "first",
       async render() {
         await sleep(30);
@@ -47,7 +47,7 @@ describe("async module rendering", () => {
       },
     })();
 
-    const second = createModule({
+    const second = createBlock({
       name: "second",
       async render() {
         await sleep(10);
@@ -71,7 +71,7 @@ describe("async module rendering", () => {
     assert.deepEqual(order, ["second", "first"]);
   });
 
-  it("renders async modules through the full page pipeline", async () => {
+  it("renders async blocks through the full page pipeline", async () => {
     const siteConfig = createSiteConfig({ name: "Test Site" });
     const template = createTemplate({
       siteConfig,
@@ -81,7 +81,7 @@ describe("async module rendering", () => {
       },
     });
 
-    const asyncModule = createModule({
+    const asyncBlock = createBlock({
       name: "page-async",
       async render() {
         await sleep(15);
@@ -92,7 +92,7 @@ describe("async module rendering", () => {
     const page = createPage(template, {
       path: "/async-test",
       title: "Async test",
-      slots: { content: [asyncModule] },
+      slots: { content: [asyncBlock] },
     });
 
     const htmlOut = await renderPage(page, siteConfig);

package/test/blog.test.ts

@@ -4,7 +4,7 @@ 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";
+import { createBlog } from "../src/plugins/blog/index.js";
 
 function makeBlogDir(posts: Record<string, string>): string {
   const root = mkdtempSync(join(tmpdir(), "stackbox-blog-"));

package/test/plugin-assets.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import {
+  getPluginPublicRootDir,
+  parsePluginAssetRequest,
+  pluginAssetPath,
+  servePluginAsset,
+} from "../src/link.js";
+import { createSite, createSiteConfig } from "../src/site.js";
+import { createPage } from "../src/pages.js";
+import { createTemplate } from "../src/templates.js";
+import { html } from "@hyperspan/html";
+
+describe("pluginAssetPath", () => {
+  it("builds paths under /_sb/plugins", () => {
+    assert.strictEqual(
+      pluginAssetPath("random-quote", "photo.jpg"),
+      "/_sb/plugins/random-quote/photo.jpg",
+    );
+  });
+
+  it("rejects unsafe relative segments", () => {
+    assert.throws(() => pluginAssetPath("random-quote", "../secret.txt"));
+  });
+});
+
+describe("plugin public assets", () => {
+  it("copies random-quote quotes.json to dist/public/_sb", () => {
+    const file = join(
+      getPluginPublicRootDir(),
+      "random-quote",
+      "quotes.json",
+    );
+    assert.ok(existsSync(file));
+  });
+
+  it("parsePluginAssetRequest rejects traversal", () => {
+    assert.strictEqual(
+      parsePluginAssetRequest("/_sb/plugins/random-quote/../quotes.json"),
+      null,
+    );
+  });
+
+  it("servePluginAsset returns JSON for bundled quotes", async () => {
+    const res = servePluginAsset(
+      "/_sb/plugins/random-quote/quotes.json",
+      "GET",
+    );
+    assert.ok(res);
+    assert.strictEqual(res!.status, 200);
+    assert.match(res!.headers.get("content-type") ?? "", /json/);
+    const body = await res!.text();
+    assert.match(body, /Rumi/);
+  });
+
+  it("site.fetch serves plugin assets before page routes", async () => {
+    const siteConfig = createSiteConfig({ name: "Asset Test" });
+    const template = createTemplate({
+      siteConfig,
+      slots: [{ name: "content", options: { required: true, primary: true } }],
+      render({ slots }: { slots: { content: { render: () => unknown } } }) {
+        return html`<body>${slots.content.render()}</body>`;
+      },
+    });
+    const homePage = createPage(template, {
+      path: "/",
+      title: "Home",
+      slots: { content: ["<p>home</p>"] },
+    });
+    const site = createSite(siteConfig, { pages: [homePage] });
+
+    const res = await site.fetch(
+      new Request("https://example.com/_sb/plugins/random-quote/quotes.json"),
+    );
+    assert.strictEqual(res.status, 200);
+    assert.match(await res.text(), /Rumi/);
+  });
+});

package/test/random-quote.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { renderAsync } from "@hyperspan/html";
+import { createSiteConfig } from "../src/site.js";
+import {
+  defaultQuotes,
+  pickRandomQuote,
+  randomQuoteBlock,
+  type Quote,
+} from "../src/plugins/random-quote/index.js";
+
+describe("random-quote plugin", () => {
+  it("ships bundled default quotes", () => {
+    assert.ok(defaultQuotes.length >= 50);
+    assert.strictEqual(defaultQuotes[0]!.author, "Rumi");
+  });
+
+  it("pickRandomQuote returns a quote from the given list", () => {
+    const custom: Quote[] = [
+      { text: "Custom quote.", author: "Test Author" },
+    ];
+    const quote = pickRandomQuote(custom);
+    assert.strictEqual(quote.author, "Test Author");
+  });
+
+  it("randomQuoteBlock uses bundled quotes by default", async () => {
+    const siteConfig = createSiteConfig({ name: "Test" });
+    const originalRandom = Math.random;
+    Math.random = () => 0;
+
+    try {
+      const block = randomQuoteBlock();
+      const htmlOut = await renderAsync(block.render({ siteConfig }));
+
+      assert.match(htmlOut, /data-block="random-quote"/);
+      assert.match(htmlOut, /<blockquote/);
+      assert.match(htmlOut, /beat 40 scholars/);
+      assert.match(htmlOut, /— Rumi/);
+    } finally {
+      Math.random = originalRandom;
+    }
+  });
+
+  it("randomQuoteBlock accepts custom quotes", async () => {
+    const siteConfig = createSiteConfig({ name: "Test" });
+    const custom: Quote[] = [
+      { text: "Ship your own quotes.", author: "Site Owner" },
+    ];
+    const block = randomQuoteBlock({ quotes: custom });
+    const htmlOut = await renderAsync(block.render({ siteConfig }));
+
+    assert.match(htmlOut, /Ship your own quotes/);
+    assert.match(htmlOut, /— Site Owner/);
+  });
+});