@stackbox/cms 0.0.5 → 0.1.1

package/README.md

@@ -12,7 +12,7 @@ export default {
 };
 ```
 
-Pages are rendered on each request, so content, templates, blocks, and plugins can be fully dynamic — driven by request data, environment bindings, and async data fetching.
+GET/HEAD page renders are cached in memory by default (stale-while-revalidate, single-flight refresh). Set `cache: false` on the site config, a page, or any block on that page to render every request. Plugin routes and plugin assets are always uncached.
 
 ## Why this exists
 
@@ -33,15 +33,121 @@ npm install @stackbox/cms
 | 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)` — a fetch-handler-compatible server. |
+| **Site** | `createSite(siteConfig, { pages, plugins? })` | Runtime router with `fetch(request, env)` — a fetch-handler-compatible server. |
 | **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. |
 | **Block** | `createBlock({ name, render })` | A self-contained content block placed into a slot at request time. |
+| **Plugin** | `createPlugin({ name, description, version, keywords, root })` | A packaged feature. Register it on `createSite({ plugins })` when you use it. |
 
-**Plugins vs blocks:** **Plugins** package whole features (blog, newsletter) under `@stackbox/cms/plugins/<name>` — they may export factories, content objects, blocks, types, and helpers. **Blocks** are the core slot primitive via `createBlock()`; plugins can ship blocks alongside other exports.
+**Plugins vs blocks:** **Plugins** package whole features (blog, newsletter) — bundled under `@stackbox/cms/plugins/<name>` or a third-party package with the same shape. Each plugin **must** export a `plugin` object from `createPlugin()` (name, description, version, keywords). **Blocks** are the core slot primitive via `createBlock()`; plugins can ship blocks alongside other exports.
+
+Importing a plugin does not enable it. Pass `plugin` into `createSite({ plugins })`. Only registered plugins have `public_assets/` served or copied.
 
 **Slots** are named regions in a template. Page content — strings, HTML, or blocks — is dropped into slots, and the engine resolves and renders everything (including async blocks, concurrently) to a single HTML string.
 
+## Page cache
+
+Optional `cache: { min?: number; max?: number } | false` on site config, pages, and blocks (milliseconds). Omit = no opinion; `false` = never cache that request.
+
+```ts
+createSiteConfig({
+  name: "My Site",
+  url: "https://example.com",
+  cache: { min: 60_000, max: 7 * 24 * 60 * 60 * 1000 },
+});
+
+createPage(template, {
+  path: "/live",
+  title: "Live",
+  cache: false,
+  slots: { content: [...] },
+});
+
+createBlock({
+  name: "ticker",
+  cache: { max: 5 * 60 * 1000 },
+  render() { ... },
+});
+```
+
+TTL merges settings from the site config, the page, and on-page blocks: highest `min` floors the result, lowest `max` caps it (default 1 day, hard cap 30 days). Responses include `Cache-Control`. Expired entries are served immediately while one background refresh runs per key.
+
+## Site hooks
+
+Extend rendering at runtime with an optional `hooks` object on `createSite`:
+
+```ts
+export default createSite(siteConfig, {
+  pages: [homePage],
+  hooks: {
+    shouldCache(request) {
+      return true;
+    },
+    renderSlotItem(html, info) {
+      return html;
+    },
+    afterRender(html, info) {
+      return html;
+    },
+    beforeResponse(response, info) {
+      return response;
+    },
+  },
+});
+```
+
+- **`shouldCache(request)`** — return `false` to skip the page cache for that request (page/block TTL still applies when it returns `true`)
+- **`renderSlotItem(html, info)`** — transform each slot item after it renders
+- **`afterRender(html, info)`** — transform the full page HTML
+- **`beforeResponse(response, info)`** — adjust page and 404 responses before they are returned
+
+Pages and blocks may optionally set `source` (for example `import.meta.url`) so hooks can point editors or agents at the defining file.
+
+Plugins can register hooks too — pass the plugin to `createSite({ plugins })` and its hooks merge with any site-level hooks:
+
+```ts
+createPlugin({
+  name: "my-plugin",
+  // ...metadata...
+  hooks({ site }) {
+    const { url } = site.siteConfig.config;
+    return {
+      afterRender(html) {
+        return html;
+      },
+    };
+  },
+});
+```
+
+Plugin hooks run in registration order; site `hooks` run last. `shouldCache` uses AND semantics across all hooks.
+
+### Edit plugin
+
+Enable in-iframe editing with a single plugin registration:
+
+```ts
+import editPlugin from "@stackbox/edit-mode-plugin";
+
+export default createSite(siteConfig, {
+  pages: [homePage],
+  plugins: [editPlugin],
+});
+```
+
+Visit any page with `?sbedit=1` to activate edit mode.
+
+## Types
+
+Core types are exported as a single namespace:
+
+```ts
+import type { Stackbox } from "@stackbox/cms";
+
+type Page = Stackbox.Page;
+type SiteHooks = Stackbox.SiteHooks;
+```
+
 ## Project layout
 
 ```
@@ -109,6 +215,7 @@ import aboutPage from "./pages/about";
 
 export default createSite(siteConfig, {
   pages: [homePage, aboutPage],
+  // plugins: [blogPlugin, randomQuotePlugin], // only plugins this site uses
 });
 ```
 
@@ -157,10 +264,12 @@ export const blogPostPages = blog.posts.map((post) =>
 
 ```ts
 // server.ts
+import blogPlugin from "@stackbox/cms/plugins/blog";
 import { blogListingPages, blogPostPages } from "./pages/blog";
 
 export default createSite(siteConfig, {
   pages: [homePage, ...blogListingPages, ...blogPostPages],
+  plugins: [blogPlugin],
 });
 ```
 
@@ -169,37 +278,76 @@ export default createSite(siteConfig, {
 **Blog** — content objects wired into pages:
 
 ```ts
-import { createBlog } from "@stackbox/cms/plugins/blog";
+import blogPlugin, { createBlog } from "@stackbox/cms/plugins/blog";
 ```
 
 **Random quote** — block-only plugin (drop into any slot):
 
 ```ts
-import { randomQuoteBlock } from "@stackbox/cms/plugins/random-quote";
+import randomQuotePlugin, {
+  randomQuoteBlock,
+} from "@stackbox/cms/plugins/random-quote";
 import myQuotes from "../content/quotes.json" with { type: "json" };
 
 slots: { sidebar: [randomQuoteBlock()] } // bundled quotes
 slots: { sidebar: [randomQuoteBlock({ quotes: myQuotes })] } // your own
 ```
 
+Register every plugin you use:
+
+```ts
+export default createSite(siteConfig, {
+  pages: [homePage, ...blogListingPages, ...blogPostPages],
+  plugins: [blogPlugin, randomQuotePlugin],
+});
+```
+
+Private plugin files live in `assets/` (imported by JS). Files served over HTTP live in `public_assets/` and are copied or served only for registered plugins — including third-party packages that follow the same layout.
+
+Plugins may also register **`routes`** (served by `fetch()`) and **`build`** hooks (run by `stackbox-cms build`). The **sitemap** plugin uses both to serve and write `/sitemap.xml`:
+
+```ts
+import sitemapPlugin from "@stackbox/cms/plugins/sitemap";
+
+export default createSite(siteConfig, {
+  pages: [homePage, aboutPage],
+  plugins: [sitemapPlugin],
+});
+```
+
+Run the package build script so registered plugin `public_assets/` land in the site public directory:
+
+```bash
+npx stackbox-cms build
+# or: npx stackbox-cms build --site server.ts --outDir dist --publicDir dist/public
+```
+
+```json
+"scripts": {
+  "build": "stackbox-cms build"
+}
+```
+
 ## AI agents
 
-Bundled plugins include agent playbooks. See [`AGENTS.md`](AGENTS.md) for site conventions and a plugin catalog. When a user asks for a feature (e.g. "add a blog"), read **only** the matching plugin's `AGENTS.md` — do not load every plugin file.
+Bundled plugins include agent playbooks. See [`dist/AGENTS.md`](dist/AGENTS.md) (generated on `pnpm run build`) for site conventions and a plugin keyword catalog. When a user asks for a feature (e.g. "add a blog"), read **only** the matching plugin's `AGENTS.md` — do not load every plugin file.
 
 If you are building a site that uses this package, add this to your project's `AGENTS.md`:
 
 ```md
 This site uses @stackbox/cms. Before adding features, read
-`node_modules/@stackbox/cms/AGENTS.md` and follow its plugin catalog.
+`node_modules/@stackbox/cms/dist/AGENTS.md` and follow its plugin catalog.
 Do not reimplement bundled plugins.
 ```
 
 ## Development
 
+From the repository root:
+
 ```bash
-npm run build      # compile the package
-npm run typecheck  # type-check without emitting
-npm test           # build, then run the test suite
+pnpm --filter @stackbox/cms build
+pnpm --filter @stackbox/cms typecheck
+pnpm --filter @stackbox/cms test
 ```
 
 ## License

package/dist/AGENTS.md

@@ -0,0 +1,218 @@
+# @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, plugins? })` | 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 |
+| Plugin | `createPlugin({ name, description, version, keywords, root })` | Packaged feature; register on the site when used |
+
+**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)
+package.json         # "build": "stackbox-cms build"
+```
+
+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.
+
+## Page request cache
+
+GET/HEAD page renders are cached in memory by default. Keys are pathname + query string (`/about?preview=1` is separate from `/about`). Plugin routes and `/_sb/plugins/` assets are never cached.
+
+Optional `cache` on site config, pages, and blocks — same shape everywhere:
+
+```ts
+export type CacheConfig = { min?: number; max?: number } | false;
+```
+
+Milliseconds. Omit = no opinion. `cache: false` = fully dynamic (do not cache that request).
+
+```ts
+createSiteConfig({
+  name: "My Site",
+  url: "https://example.com",
+  cache: { min: 60_000, max: 7 * 24 * 60 * 60 * 1000 },
+})
+
+createPage(template, {
+  path: "/live",
+  title: "Live",
+  cache: false,
+  slots: { content: [...] },
+})
+
+createBlock({
+  name: "random-quote",
+  cache: { max: 5 * 60 * 1000 },
+  render() { ... },
+})
+```
+
+TTL is derived from the site config, the page, and every block on that page. If **any** of those is `false`, the request is not cached. Otherwise merge `{ min, max }` (unset fields ignored): highest `min` floors the result, lowest `max` caps it (default TTL 1 day, hard cap 30 days). Registering a plugin does not change cache times — only blocks (or pages) with `cache` on that page count.
+
+Stale entries are served immediately (stale-while-revalidate); one background refresh runs per key. Concurrent misses share a single render (single-flight). Failed refreshes keep the last good HTML.
+
+Disable caching for a whole site with `createSiteConfig({ cache: false })`. `createSite` accepts an optional `cacheAdapter` for tests or custom stores — do not overload `cache` on `createSite`.
+
+## Site hooks
+
+Optional runtime hooks on `createSite(siteConfig, { pages, plugins?, hooks? })`. All hooks are optional; omitting them preserves default behavior. Page/block `cache` TTL is unchanged — hooks do not replace that policy.
+
+```ts
+createSite(siteConfig, {
+  pages: [homePage],
+  hooks: {
+    shouldCache(request) {
+      return !new URL(request.url).searchParams.has("preview");
+    },
+    renderSlotItem(html, { item, slot, index, page, ctx }) {
+      return html;
+    },
+    afterRender(html, { page, ctx }) {
+      return html;
+    },
+    beforeResponse(response, { request, page, ctx }) {
+      return response;
+    },
+  },
+});
+```
+
+| Hook | When | Signature |
+| --- | --- | --- |
+| `shouldCache` | Before the page cache adapter runs | `(request: Request) => boolean` — `false` skips the adapter for that request; `true` uses page/block TTL |
+| `renderSlotItem` | After each slot item (block or HTML string) renders | `(html, info) => string` |
+| `afterRender` | After the full page HTML is assembled | `(html, info) => string` |
+| `beforeResponse` | Before `fetch` returns a page or 404 response | `(response, info) => Response` |
+
+Plugin routes and `/_sb/plugins/` assets do not run render hooks. `beforeResponse` does not wrap plugin route responses.
+
+Optional `source?: string` on `createPage` and `createBlock` (e.g. `import.meta.url`) is metadata for hook consumers — the engine stores it as given.
+
+## Plugins vs blocks
+
+- **Plugin** — a packaged use-case (bundled under `@stackbox/cms/plugins/<name>`, or a third-party package with the same shape). **Default-exports** a `createPlugin()` registration object, plus named 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.
+
+**Register plugins when you use them.** Importing a plugin module is not enough — pass its default export to `createSite({ plugins })`. Only registered plugins have their `public_assets/` copied or served. Third-party packages are registered the same way; they are not discovered from a `plugins/` folder.
+
+```ts
+import blogPlugin from "@stackbox/cms/plugins/blog";
+import randomQuotePlugin from "@stackbox/cms/plugins/random-quote";
+
+export default createSite(siteConfig, {
+  pages: [homePage, ...blogListingPages, ...blogPostPages],
+  plugins: [blogPlugin, randomQuotePlugin],
+});
+```
+
+`createPlugin({ name, description, version, keywords, root })` is **required**. `createSite` throws if a registered value is missing that metadata. `keywords` tell agents when to reach for the plugin.
+
+Optional hooks on `createPlugin()`:
+
+- **`routes({ site })`** — site-level paths served by `fetch()` before the GET/HEAD gate, plugin assets, and pages (e.g. `/sitemap.xml`). The route handler decides which HTTP methods are allowed. Must return synchronously. Paths must not collide with pages or other plugin routes.
+- **`build({ site, outDir, publicDir })`** — called by `stackbox-cms build` after copying registered `public_assets/`. Write generated files into `publicDir` (or elsewhere under `outDir`).
+- **`hooks({ site })`** — return `SiteHooks` to register cache/render/response behavior when the plugin is added to `createSite({ plugins })`. Must return synchronously. `{ site }` exposes `site.siteConfig.config`, `site.pages`, and `site.plugins`.
+
+Plugin hooks merge with site-level `hooks` on `createSite`: `renderSlotItem`, `afterRender`, and `beforeResponse` run in plugin registration order, then site hooks last; `shouldCache` uses AND semantics (every hook must return `true` to cache).
+
+## 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-catalog:start -->
+| 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, quotation | `src/plugins/random-quote/AGENTS.md` |
+| sitemap | `@stackbox/cms/plugins/sitemap` | sitemap, sitemap.xml, seo, search engines, xml sitemap | `src/plugins/sitemap/AGENTS.md` |
+<!-- plugin-catalog:end -->
+
+When adding a new plugin to this package, add a folder under `src/plugins/<name>/`, **default-export** the `createPlugin()` registration from `index.ts`, and create `src/plugins/<name>/AGENTS.md` using the same heading structure as the blog plugin. Run `pnpm run build` — the package scans `dist/plugins/` and writes the keyword catalog to `dist/AGENTS.md` from each plugin's `keywords`. Document all export kinds (factory, types, blocks, helpers).
+
+## Plugin layout and assets
+
+Every plugin — bundled or third-party — has the same shape:
+
+```
+index.ts            # default export: createPlugin({ ... }); named exports: factories, types, blocks
+AGENTS.md           # agent playbook
+assets/             # private files imported by JS (JSON, templates, …)
+public_assets/      # files served over HTTP (images, CSS, fonts, …)
+```
+
+`root` is the directory that contains `assets/` and `public_assets/`. Pass `import.meta.dirname` when those folders sit next to the plugin entry. A third-party package may pass its package root instead.
+
+| Folder | Copied to | When |
+| --- | --- | --- |
+| `assets/` | `{plugin.root}/assets` (next to compiled JS) | Package build of that plugin (`copyPluginPrivateAssets`) |
+| `public_assets/` | `{publicDir}/_sb/plugins/{name}/` | Site build, **only for plugins registered on the site** (`copyRegisteredPluginAssets`) |
+
+`public_assets/` is no longer mirrored into the plugin's compiled folder. Import private data from `./assets/...`, not from `public_assets/`.
+
+At request time, `createSite.fetch` order is: **plugin routes** → **plugin public assets** (`/_sb/plugins/...`) → **pages**.
+
+For a static `public/` directory, run the package build script — it loads the site, reads `site.plugins`, copies registered `public_assets/`, then runs each plugin's `build` hook:
+
+```bash
+npx stackbox-cms build
+```
+
+```json
+"scripts": {
+  "build": "stackbox-cms build"
+}
+```
+
+```ts
+import { build } from "@stackbox/cms/build";
+import site from "./server.ts";
+
+await build({
+  site,
+  outDir: "dist",
+  publicDir: "dist/public",
+});
+```
+
+Defaults: `--site` looks for `server.ts` (then `server.js`, `src/server.ts`, `src/server.js`); `outDir` is `dist`; `publicDir` is `{outDir}/public`. Flags: `--site`, `--outDir`, `--publicDir`.
+
+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("sb-random-quote", "widget.css");
+// → "/_sb/plugins/sb-random-quote/widget.css"
+```
+
+## For site agents
+
+If you are working in a **consumer site repo** (not this package), read the generated agent instructions from the installed package:
+
+```
+node_modules/@stackbox/cms/dist/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/dist/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/dist/blocks.d.ts

@@ -1,18 +1,11 @@
-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;
-};
+import type { Stackbox as SB } from "./types.js";
 type BlockDef<TOptions = undefined> = {
     name: string;
-    render(options: TOptions, ctx?: RenderContext): BlockRenderResult;
+    cache?: SB.CacheConfig;
+    source?: string;
+    render(options: TOptions, ctx?: SB.RenderContext): SB.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;
-export declare function createBlock<TOptions = undefined>(def: BlockDef<TOptions>): BlockFactory<TOptions>;
-export declare function isBlock(value: unknown): value is Block;
+export declare function createBlock<TOptions = undefined>(def: BlockDef<TOptions>): SB.BlockFactory<TOptions>;
+export declare function isBlock(value: unknown): value is SB.Block;
 export {};
 //# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,iBAAiB,CAAC;CAC/C,CAAC;AAEF,KAAK,QAAQ,CAAC,QAAQ,GAAG,SAAS,IAAI;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,iBAAiB,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,GACpE,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,GACrB,SAAS,GACT,CAAC,GACH,KAAK,CAAC;AAEV,MAAM,MAAM,YAAY,CAAC,QAAQ,GAAG,SAAS,IAAI,CAC/C,OAAO,CAAC,EAAE,QAAQ,KACf,KAAK,CAAC;AAQX,wBAAgB,WAAW,CAAC,QAAQ,GAAG,SAAS,EAC9C,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,GACtB,YAAY,CAAC,QAAQ,CAAC,CAYxB;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAStD"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,YAAY,CAAC;AAEjD,KAAK,QAAQ,CAAC,QAAQ,GAAG,SAAS,IAAI;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,iBAAiB,CAAC;CACzE,CAAC;AAQF,wBAAgB,WAAW,CAAC,QAAQ,GAAG,SAAS,EAC9C,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,GACtB,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAc3B;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC,KAAK,CASzD"}

package/dist/blocks.js

@@ -11,6 +11,8 @@ export function createBlock(def) {
     return ((options) => ({
         __kind: "block",
         name: def.name,
+        ...(def.cache !== undefined ? { cache: def.cache } : {}),
+        ...(def.source !== undefined ? { source: def.source } : {}),
         render: (ctx) => def.render(options, ctx),
     }));
 }

package/dist/blocks.js.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AA0BA,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,GAAuB;IAEvB,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE5B,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,CAAC,CAAC,OAAkB,EAAE,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,OAAgB;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,CAAC,GAAkB,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,OAAmB,EAAE,GAAG,CAAC;KACrE,CAAC,CAA2B,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAe,CAAC,MAAM,KAAK,OAAO;QACnC,OAAQ,KAAe,CAAC,IAAI,KAAK,QAAQ;QACxC,KAAe,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAChC,OAAQ,KAAe,CAAC,MAAM,KAAK,UAAU,CAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAUA,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,GAAuB;IAEvB,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE5B,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,CAAC,CAAC,OAAkB,EAAE,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,OAAgB;QACxB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,MAAM,EAAE,CAAC,GAAqB,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,OAAmB,EAAE,GAAG,CAAC;KACxE,CAAC,CAA8B,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAkB,CAAC,MAAM,KAAK,OAAO;QACtC,OAAQ,KAAkB,CAAC,IAAI,KAAK,QAAQ;QAC3C,KAAkB,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QACnC,OAAQ,KAAkB,CAAC,MAAM,KAAK,UAAU,CACjD,CAAC;AACJ,CAAC"}

package/dist/build.d.ts

@@ -0,0 +1,14 @@
+import type { Stackbox as SB } from "./types.js";
+export declare class BuildError extends Error {
+    constructor(message: string);
+}
+export declare function resolveBuildSettings(options: Omit<SB.BuildOptions, "site">): SB.BuildSettings;
+/**
+ * Run the site build. Copies each registered plugin's `public_assets/` to
+ * `{publicDir}/_sb/plugins/{name}/`, then runs plugin `build` hooks.
+ */
+export declare function build(options: SB.BuildOptions): Promise<SB.BuildResult>;
+export declare function parseBuildCliArgs(argv: string[]): SB.BuildCliArgs;
+export declare function loadSiteFromEntry(entry: string, cwd?: string): Promise<SB.Site>;
+export declare function runBuildCli(argv: string[], cwd?: string): Promise<SB.BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,YAAY,CAAC;AASjD,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AASD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,GACrC,EAAE,CAAC,aAAa,CAOlB;AAED;;;GAGG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAmB7E;AAcD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAmCjE;AAkCD,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,GAAG,SAAgB,GAClB,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAuBlB;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,SAAgB,GAClB,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAWzB"}

package/dist/build.js

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { register } from "node:module";
+import { copyRegisteredPluginAssets, runRegisteredPluginBuilds, } from "./plugin.js";
+import { isSite } from "./site.js";
+const DEFAULT_SITE_ENTRIES = [
+    "server.ts",
+    "server.js",
+    "src/server.ts",
+    "src/server.js",
+];
+export class BuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BuildError";
+    }
+}
+function requireDirOption(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new BuildError(`build(): ${label} must be a non-empty string`);
+    }
+    return resolve(value.trim());
+}
+export function resolveBuildSettings(options) {
+    const outDir = requireDirOption(options.outDir ?? "dist", "outDir");
+    const publicDir = requireDirOption(options.publicDir ?? join(outDir, "public"), "publicDir");
+    return { outDir, publicDir };
+}
+/**
+ * Run the site build. Copies each registered plugin's `public_assets/` to
+ * `{publicDir}/_sb/plugins/{name}/`, then runs plugin `build` hooks.
+ */
+export async function build(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new BuildError("build(): site is required");
+    }
+    if (!isSite(options.site)) {
+        throw new BuildError("build(): site must be from createSite()");
+    }
+    const settings = resolveBuildSettings(options);
+    mkdirSync(settings.outDir, { recursive: true });
+    mkdirSync(settings.publicDir, { recursive: true });
+    copyRegisteredPluginAssets(options.site.plugins, settings.publicDir);
+    await runRegisteredPluginBuilds(options.site.plugins, {
+        site: options.site,
+        outDir: settings.outDir,
+        publicDir: settings.publicDir,
+    });
+    return { settings, plugins: options.site.plugins };
+}
+function readFlag(args, index, name) {
+    const value = args[index + 1];
+    if (!value || value.startsWith("-")) {
+        throw new BuildError(`stackbox-cms build: ${name} requires a value`);
+    }
+    return { value, next: index + 2 };
+}
+export function parseBuildCliArgs(argv) {
+    const args = argv.slice(2);
+    let index = 0;
+    if (args[0] && !args[0].startsWith("-")) {
+        if (args[0] !== "build") {
+            throw new BuildError(`stackbox-cms: unknown command "${args[0]}" (expected "build")`);
+        }
+        index = 1;
+    }
+    let site;
+    let outDir;
+    let publicDir;
+    while (index < args.length) {
+        const arg = args[index];
+        if (arg === "--site") {
+            ({ value: site, next: index } = readFlag(args, index, "--site"));
+            continue;
+        }
+        if (arg === "--outDir") {
+            ({ value: outDir, next: index } = readFlag(args, index, "--outDir"));
+            continue;
+        }
+        if (arg === "--publicDir") {
+            ({ value: publicDir, next: index } = readFlag(args, index, "--publicDir"));
+            continue;
+        }
+        throw new BuildError(`stackbox-cms build: unknown option "${arg}"`);
+    }
+    return { command: "build", site, outDir, publicDir };
+}
+function defaultSiteEntry(cwd) {
+    for (const candidate of DEFAULT_SITE_ENTRIES) {
+        const absolute = resolve(cwd, candidate);
+        if (existsSync(absolute)) {
+            return absolute;
+        }
+    }
+    throw new BuildError(`stackbox-cms build: no site entry found (looked for ${DEFAULT_SITE_ENTRIES.join(", ")}). Pass --site`);
+}
+let tsxRegistered = false;
+function tsxAlreadyActive() {
+    const flags = [...process.execArgv, process.env.NODE_OPTIONS ?? ""].join(" ");
+    return flags.includes("tsx");
+}
+function ensureTsxRegistered() {
+    if (tsxRegistered || tsxAlreadyActive()) {
+        tsxRegistered = true;
+        return;
+    }
+    try {
+        register("tsx", import.meta.url);
+    }
+    catch {
+        // Loader already registered in this process.
+    }
+    tsxRegistered = true;
+}
+export async function loadSiteFromEntry(entry, cwd = process.cwd()) {
+    const absolute = resolve(cwd, entry);
+    if (!existsSync(absolute)) {
+        throw new BuildError(`stackbox-cms build: site entry not found: ${absolute}`);
+    }
+    ensureTsxRegistered();
+    const mod = (await import(pathToFileURL(absolute).href));
+    const candidate = isSite(mod.default)
+        ? mod.default
+        : isSite(mod.site)
+            ? mod.site
+            : null;
+    if (!candidate) {
+        throw new BuildError(`stackbox-cms build: ${absolute} must default-export a site from createSite()`);
+    }
+    return candidate;
+}
+export async function runBuildCli(argv, cwd = process.cwd()) {
+    const args = parseBuildCliArgs(argv);
+    const entry = args.site
+        ? resolve(cwd, args.site)
+        : defaultSiteEntry(cwd);
+    const site = await loadSiteFromEntry(entry, cwd);
+    return build({
+        site,
+        outDir: args.outDir ? resolve(cwd, args.outDir) : resolve(cwd, "dist"),
+        publicDir: args.publicDir ? resolve(cwd, args.publicDir) : undefined,
+    });
+}
+//# sourceMappingURL=build.js.map