@stackbox/cms 0.0.3 → 0.0.5

package/src/plugins/blog/AGENTS.md

@@ -0,0 +1,131 @@
+# Blog plugin — agent playbook
+
+## Use when
+
+The user asks for any of:
+
+- blog, blog page, blog listing, blog posts
+- articles, journal, news posts
+- markdown posts, writing posts from markdown files
+- paginated blog index
+
+## Do not
+
+- Hand-roll a markdown loader or frontmatter parser — use `createBlog()`
+- Invent page factories like `createPostPages()` or `createListingPage()` — the API returns **content objects**; you wire them with `createPage()`
+- Skip `createPage()` composition — the blog plugin has no template dependency
+- Put blog routes only in `server.ts` without a dedicated `pages/blog.ts`
+
+## Exports
+
+- `createBlog()` — factory; returns `{ posts, listings }`
+- `BlogPostContent`, `BlogListingContent`, `Blog`, `BlogPost`, `BlogOptions` — types
+- `content[]` on post/listing objects accepts **blocks or HTML strings** — optional plugin blocks can be added later (e.g. share buttons)
+
+## API
+
+```ts
+import { createBlog } from "@stackbox/cms/plugins/blog";
+
+const blog = createBlog({
+  contentPath: string,   // directory of .md files (bundle time)
+  pathPrefix: string,    // e.g. "/blog"
+  postsPerPage?: number, // optional — omit to put all posts on one listing page
+});
+```
+
+Returns:
+
+```ts
+{
+  posts: readonly BlogPostContent[];   // one per markdown file
+  listings: readonly BlogListingContent[]; // one or more listing pages
+}
+```
+
+Each `BlogPostContent`: `{ path, title, meta?, content }` — `content` is slot-ready HTML (or blocks) for the primary slot.
+
+Each `BlogListingContent`: `{ path, content }` — post list HTML for the primary slot.
+
+Listing paths:
+
+- Page 1: `pathPrefix` (normalized, no trailing slash)
+- Page 2+: `{pathPrefix}/page/2`, `{pathPrefix}/page/3`, …
+
+Post paths: `{pathPrefix}/{slug}` where slug comes from frontmatter or filename.
+
+## Files to create or update
+
+| File | Action |
+| --- | --- |
+| `content/blog/*.md` | Create markdown posts with frontmatter |
+| `pages/blog.ts` | Call `createBlog()`, map `listings` and `posts` to `createPage()` |
+| `server.ts` | Register `...blogListingPages` and `...blogPostPages` in `createSite({ pages })` |
+| `templates/site-template.ts` | Reuse existing site template (or create one) — blog does not ship its own |
+
+## Markdown contract
+
+Frontmatter fields (YAML between `---` delimiters):
+
+- `title` — post title (defaults to slug)
+- `description` — optional, becomes page meta description
+- `slug` — URL segment (defaults to filename without `.md`)
+
+Body is markdown; rendered to HTML at bundle time.
+
+Example:
+
+```md
+---
+title: Hello World
+description: A greeting post
+slug: hello
+---
+Hello **world**.
+```
+
+## Wiring example
+
+```ts
+// pages/blog.ts
+import { join } from "node:path";
+import { createPage } from "@stackbox/cms";
+import { createBlog } from "@stackbox/cms/plugins/blog";
+import { siteTemplate } from "../templates/site-template";
+
+const blog = createBlog({
+  contentPath: join(import.meta.dirname, "../content/blog"),
+  pathPrefix: "/blog",
+  postsPerPage: 10,
+});
+
+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
+// server.ts
+import { blogListingPages, blogPostPages } from "./pages/blog";
+
+export default createSite(siteConfig, {
+  pages: [homePage, ...blogListingPages, ...blogPostPages],
+});
+```
+
+You may spread extra slot content alongside `listing.content` or `post.content` — blocks or HTML strings (newsletter signup, share buttons, etc.).

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/.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/src/index.ts

@@ -1,67 +0,0 @@
-export { html } from "@hyperspan/html";
-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.ts

@@ -1,58 +0,0 @@
-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"
-  );
-}