@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/examples/content-delivery/README.md

@@ -0,0 +1,87 @@
+# Use pages, sections, and snippets in an application
+
+This example uses the public `@shoalrun/cli/content` client to show a whole
+billing guide, its independently approved refund section, and two simultaneous
+copies of one reusable policy snippet. The app owns the drawer, buttons, focus,
+and styling. Shoalrun supplies passive content and typed resource references.
+
+Copy this directory into a project with Shoalrun installed. From the copied
+example directory, run:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help/releases/demo
+node preview.mjs
+```
+
+Open `http://127.0.0.1:8775/settings/billing`. Choose **Billing guide** to read the
+page or **How to request a refund** to read only its named section. Follow the
+section's billing-overview link. Both cards display the same snippet, with
+independent footnote anchors. Escape closes the drawer and restores focus.
+
+The preview resolves the installed package's public `@shoalrun/cli/content`
+entrypoint and serves only its browser-safe modules. It does not serve arbitrary
+package or project files. In a real app, import that entrypoint through your
+existing browser bundler.
+
+## Author the resources
+
+The page gives its root heading a stable ID with
+`## Request a refund <Anchor id="refunds" />`. Its page metadata separately
+declares `{ id: refunds, context: section }` in `standaloneSections`, approving
+that section as useful without the page introduction.
+
+The export target selects a page reference, a section reference, and a named
+snippet instance with a fixed `days` value. `snippets/refund-window.mdx` is also
+included in the page, so the reusable wording stays in one source. Snippet
+content is block content; this example does not insert it inside a button or
+promise that arbitrary snippets are suitable for inline tooltips.
+
+## Keep serving independent from presentation
+
+`app.js` opens a snapshot with `openManifestContentSource`, reads resources by
+typed reference, and uses `mountContent` for the HTML. Each mount receives fresh
+DOM IDs and remapped anchors. The drawer aborts superseded requests and ignores
+late results after closing. These are application behaviors, not server duties.
+
+The preview also serves the read-only REST API at `/content/v1`. Open
+`http://127.0.0.1:8775/settings/billing?delivery=rest` to use
+`openRestContentSource` through the same snapshot interface. Both modes deliver
+identical content and use the same application rendering code.
+
+The server uses `createContentRestHandler` from `@shoalrun/cli/content/server`.
+It pins one approved snapshot per publication at startup and retains no revision
+history. All requests select `channel`, `version`, and `language`. List resources
+first, then use the returned key and revision for subsequent reads:
+
+```sh
+curl 'http://127.0.0.1:8775/content/v1/resources?channel=production&version=current&language=en'
+```
+
+`GET /resources/{key}` returns metadata; `GET
+/resources/{key}/representations/{format}` returns HTML or Markdown. Append the
+same publication parameters and `revision` returned by the list. HEAD and
+conditional requests with `If-None-Match` are supported. The complete
+[OpenAPI contract](../../schemas/content-rest.openapi.json) describes responses,
+errors, and caching. The HTTP contract's `v1` is separate from package versions.
+
+Keep `/help/releases/demo/` served alongside the API: the REST adapter preserves
+exported bytes, including static links and asset URLs. Browser clients require
+the application origin and HTTPS or localhost. This local example does not add
+authentication, search, editing, or a production hosting service.
+
+## Publish complete revisions
+
+The example uses `/help/releases/demo/` as a fixed demonstration revision.
+Production should use a new directory and matching `publicBase` for each release,
+upload the complete export, and only then update the app's manifest URL or
+release pointer. Retain revisions still used by open clients. Do not overwrite
+files underneath an existing snapshot.
+
+Use `--previous-manifest PATH --fail-on-removed` to detect removed public resource
+references before replacing output. Without a baseline, the export reports that
+removal coverage was unavailable. API review candidates are not approved content:
+the client refuses a manifest whose review status is `required`.
+
+The content comes from this project's trusted build. The client checks the
+manifest and content digests; these establish consistency with that manifest,
+not trust in an arbitrary third-party publisher. Preserve the export's notices.

package/examples/content-delivery/app.js

@@ -0,0 +1,91 @@
+import { openManifestContentSource, openRestContentSource, mountContent } from '/shoalrun/content-delivery.js';
+
+// The app owns interaction. A future server-backed source can supply this same
+// snapshot interface; the drawer does not depend on manifest layout or filenames.
+const lifetime = new AbortController();
+const source = new URLSearchParams(location.search).get('delivery') === 'rest'
+  ? openRestContentSource({ baseUrl: '/content/v1', publication: { channel: 'production', version: 'current', language: 'en' }, signal: lifetime.signal })
+  : openManifestContentSource({ manifestUrl: '/help/releases/demo/manifest.json', signal: lifetime.signal });
+const drawer = document.querySelector('#drawer');
+const container = document.querySelector('#help-content');
+let generation = 0;
+let pending;
+let mounted;
+let opener;
+let snapshot;
+let disposed = false;
+const notes = [];
+
+async function openHelp(ref, fragment) {
+  if (disposed) return;
+  const ticket = ++generation;
+  pending?.abort();
+  const controller = new AbortController();
+  pending = controller;
+  try {
+    const content = await source;
+    if (ticket !== generation) return;
+    const result = await content.get(ref, { format: 'html', signal: controller.signal });
+    if (ticket !== generation) return;
+    mounted?.unmount();
+    mounted = mountContent(container, result);
+    drawer.hidden = false;
+    const anchor = fragment && mounted.anchors.find(item => item.id === fragment || item.exportedId === fragment);
+    const target = anchor ? container.querySelector(`#${CSS.escape(anchor.exportedId)}`) : container.querySelector('h1,h2,h3') ?? container;
+    // Stable aliases precede the visible heading. Focus the heading rather than
+    // an empty aria-hidden alias so keyboard and screen-reader users get context.
+    const focus = target?.getAttribute('aria-hidden') === 'true' && target.nextElementSibling?.matches('h1,h2,h3,h4,h5,h6')
+      ? target.nextElementSibling : target;
+    if (focus) { focus.tabIndex = -1; focus.focus({ preventScroll: true }); }
+    if (anchor) focus?.scrollIntoView();
+    else drawer.scrollTop = 0;
+  } catch (error) {
+    if (ticket !== generation || controller.signal.aborted) return;
+    mounted?.unmount();
+    mounted = undefined;
+    container.textContent = `Help could not be loaded: ${error.message}`;
+    drawer.hidden = false;
+    document.querySelector('#close').focus();
+  }
+}
+function closeHelp() {
+  ++generation;
+  pending?.abort();
+  mounted?.unmount();
+  mounted = undefined;
+  drawer.hidden = true;
+  opener?.focus();
+}
+for (const [id, ref] of [
+  ['page-help', { kind: 'page', documentId: 'guide.billing' }],
+  ['section-help', { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' }],
+]) document.getElementById(id).addEventListener('click', event => { opener = event.currentTarget; openHelp(ref); });
+container.addEventListener('click', event => {
+  const anchor = event.target.closest('a[data-export-link]');
+  const link = anchor && mounted?.links.find(item => item.key === anchor.dataset.exportLink);
+  if (link?.kind !== 'resource') return;
+  event.preventDefault();
+  openHelp(link.ref, link.fragment);
+});
+document.querySelector('#close').addEventListener('click', closeHelp);
+drawer.addEventListener('keydown', event => { if (event.key === 'Escape') { event.preventDefault(); closeHelp(); } });
+
+source.then(async content => {
+  if (disposed) { content.dispose(); return; }
+  snapshot = content;
+  const result = await content.get({ kind: 'snippet', id: 'billing.refund-window' }, { format: 'html', signal: lifetime.signal });
+  if (disposed) return;
+  for (const id of ['plan-note', 'invoice-note']) notes.push(mountContent(document.getElementById(id), result));
+}).catch(error => { if (!disposed) document.querySelector('#status').textContent = `Help could not be loaded: ${error.message}`; });
+window.addEventListener('pagehide', event => {
+  // A back/forward-cache entry resumes this same module and snapshot. Preserve
+  // its state while the browser freezes it; only tear down a discarded page.
+  if (event.persisted) return;
+  disposed = true;
+  ++generation;
+  lifetime.abort();
+  pending?.abort();
+  mounted?.unmount();
+  notes.forEach(note => note.unmount());
+  snapshot?.dispose();
+});

package/examples/content-delivery/content/billing.mdx

@@ -0,0 +1,22 @@
+---
+id: guide.billing
+title: Billing help
+summary: Find invoices and request a refund for your workspace.
+slug: /billing
+standaloneSections:
+  - { id: refunds, context: section }
+---
+
+Use this guide to manage payments for your workspace.
+
+## Find an invoice
+
+Open **Settings → Billing → Invoices** and choose the payment date.
+
+## Request a refund <Anchor id="refunds" />
+
+<Snippet id="shared.refund-window" />
+
+The workspace owner can open **Settings → Billing → Contact support** and provide the invoice number. Support confirms eligibility before issuing a refund.
+
+[Read the billing overview](doc:guide.billing).

package/examples/content-delivery/docs.config.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+site:
+  title: Acme billing help
+  origin: https://docs.example.com
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+snippets:
+  shared.refund-window:
+    file: ./snippets/refund-window.mdx
+    variables:
+      days: { type: number, default: 30 }
+exports:
+  app-help:
+    formats: [html, markdown]
+    publicBase: /help/releases/demo/
+    resources:
+      - { kind: page, documentId: guide.billing }
+      - { kind: section, documentId: guide.billing, sectionId: refunds }
+      - kind: snippet
+        id: billing.refund-window
+        snippetId: shared.refund-window
+        title: Refund window
+        summary: When a workspace can request a refund.
+        values: { days: 30 }

package/examples/content-delivery/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Acme billing · Content delivery example</title>
+<style>
+  *{box-sizing:border-box}body{font:16px/1.6 system-ui,sans-serif;color:#193b2c;background:#f4f7f4;margin:0}main{max-width:60rem;margin:3rem auto;padding:0 1.5rem}h1{line-height:1.2}button,a{color:#205b3b}button{font:inherit;cursor:pointer;padding:.5rem .8rem;border:1px solid #aac5b2;border-radius:.4rem;background:white}button:focus-visible,a:focus-visible{outline:3px solid #47926b;outline-offset:3px}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(16rem,1fr));gap:1rem}.card{padding:1.5rem;border:1px solid #d6e3d9;border-radius:.75rem;background:white}.card h2{margin-top:0}.help-content{font-size:.95rem}.help-content h2{font-size:1.3rem}.help-content a{overflow-wrap:anywhere}#drawer{position:fixed;inset:0 0 0 auto;width:min(36rem,95vw);padding:1.5rem;background:white;overflow:auto;box-shadow:-1rem 0 3rem #193b2c22}#drawer[hidden]{display:none}.drawer-header{display:flex;align-items:center;justify-content:space-between;gap:1rem;border-bottom:1px solid #d6e3d9;padding-bottom:1rem}.muted{color:#526f5d}#status{min-height:1.5em}
+</style>
+<main>
+  <p class="muted">Acme workspace</p>
+  <h1>Billing</h1>
+  <p>Manage your plan and recent payments.</p>
+  <p><button id="page-help">Billing guide</button> <button id="section-help">How to request a refund</button></p>
+  <div class="cards">
+    <section class="card" aria-labelledby="plan-title"><h2 id="plan-title">Current plan</h2><p>Team · $24 per month</p><div id="plan-note" class="help-content" aria-label="Plan refund policy"></div></section>
+    <section class="card" aria-labelledby="invoice-title"><h2 id="invoice-title">Recent payment</h2><p>Invoice INV-1042 · $24</p><div id="invoice-note" class="help-content" aria-label="Invoice refund policy"></div></section>
+  </div>
+  <p id="status" role="status" class="muted"></p>
+</main>
+<aside id="drawer" aria-label="Billing help" hidden>
+  <div class="drawer-header"><strong>Billing help</strong><button id="close">Close help</button></div>
+  <div id="help-content" class="help-content" aria-live="polite"></div>
+</aside>
+<script type="module" src="/app.js"></script>
+</html>

package/examples/content-delivery/preview.mjs

@@ -0,0 +1,86 @@
+import { createServer } from 'node:http';
+import { readFile, realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { openManifestContentSource } from '@shoalrun/cli/content';
+import { createContentRestHandler } from '@shoalrun/cli/content/server';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+let port = 8775;
+let directory = path.join(root, 'public/help/releases/demo');
+const args = process.argv.slice(2);
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === '--help') { console.log('Usage: node preview.mjs [--port PORT] [--help-directory DIRECTORY]'); process.exit(0); }
+  if (args[index] === '--port') port = Number(args[++index]);
+  else if (args[index] === '--help-directory' && args[index + 1]) directory = path.resolve(args[++index]);
+  else throw new Error('Unknown preview option');
+}
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Invalid port');
+const help = await realpath(directory);
+const clientEntry = fileURLToPath(import.meta.resolve('@shoalrun/cli/content'));
+const clientDirectory = path.dirname(clientEntry);
+// Serve only the public browser entry and its browser-safe dependencies.
+// This is deliberately not a generic node_modules or repository file server.
+const clientFiles = new Map([
+  ['/shoalrun/content-delivery.js', clientEntry],
+  ['/shoalrun/content-delivery-contract.js', path.join(clientDirectory, 'content-delivery-contract.js')],
+  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
+]);
+const mount = '/help/releases/demo/';
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.md': 'text/markdown; charset=utf-8', '.png': 'image/png' };
+// Pin one approved bundle at startup. The injected transport reads only this
+// bundle; realpath containment applies even to symlinks. It does not fetch URLs.
+const source = await openManifestContentSource({
+  manifestUrl: `http://content.local${mount}manifest.json`,
+  fetch: async (input, options) => {
+    options?.signal?.throwIfAborted();
+    const url = new URL(String(input));
+    if (url.origin !== 'http://content.local' || !url.pathname.startsWith(mount)) throw new Error('Outside bundle');
+    try {
+      const file = await realpath(path.join(help, url.pathname.slice(mount.length)));
+      if (!file.startsWith(help + path.sep)) throw new Error('Outside bundle');
+      const body = await readFile(file, { signal: options?.signal ?? undefined });
+      return new Response(body, { headers: { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream' } });
+    } catch (error) {
+      options?.signal?.throwIfAborted();
+      return new Response(null, { status: 404 });
+    }
+  },
+});
+const rest = createContentRestHandler({ sources: [source] });
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url, 'http://127.0.0.1');
+  if (url.pathname === '/content/v1' || url.pathname.startsWith('/content/v1/')) {
+    const controller = new AbortController();
+    request.once('aborted', () => controller.abort());
+    response.once('close', () => { if (!response.writableEnded) controller.abort(); });
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(request.headers)) if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+      const result = await rest(new Request(url, { method: request.method, headers, signal: controller.signal }));
+      response.writeHead(result.status, Object.fromEntries(result.headers));
+      response.end(Buffer.from(await result.arrayBuffer()));
+    } catch {
+      if (!response.destroyed) { response.writeHead(500, { 'Cache-Control': 'no-store' }); response.end(); }
+    }
+    return;
+  }
+  if (!['GET', 'HEAD'].includes(request.method)) { response.writeHead(405, { Allow: 'GET, HEAD' }); response.end(); return; }
+  try {
+    const pathname = decodeURIComponent(new URL(request.url, 'http://localhost').pathname);
+    let file = clientFiles.get(pathname);
+    if (!file && pathname.startsWith(mount)) {
+      file = await realpath(path.join(help, pathname.slice(mount.length)));
+      if (!file.startsWith(help + path.sep)) throw new Error('Invalid path');
+    }
+    if (!file && pathname === '/app.js') file = path.join(root, 'app.js');
+    if (!file && (pathname === '/' || pathname === '/settings/billing')) file = path.join(root, 'index.html');
+    if (!file) throw new Error('Not found');
+    const body = await readFile(file);
+    response.writeHead(200, { 'Content-Type': types[path.extname(file)] ?? 'application/octet-stream', 'X-Content-Type-Options': 'nosniff' });
+    response.end(request.method === 'HEAD' ? undefined : body);
+  } catch { response.writeHead(404); response.end('Not found'); }
+});
+server.listen(port, '127.0.0.1', () => console.log(`Content delivery demo: http://127.0.0.1:${server.address().port}/settings/billing`));
+process.on('SIGINT', () => server.close(() => { source.dispose(); process.exit(0); }));
+process.on('SIGTERM', () => server.close(() => { source.dispose(); process.exit(0); }));

package/examples/content-delivery/snippets/refund-window.mdx

@@ -0,0 +1,3 @@
+You can request a refund within <Var name="days" /> days of payment.[^terms]
+
+[^terms]: Refund eligibility depends on the workspace agreement.

package/examples/help-drawer/README.md

@@ -18,10 +18,10 @@ billing help buttons; follow the in-drawer links and inspect the images.
 The full account guide is omitted from the export and links to the configured
 example documentation host; replace that origin for your own project.
 
-`manifest.json` maps stable document IDs to representation files. `app.js`
+`manifest.json` maps typed page references to representation files in its `resources` array. `app.js`
 fetches the HTML, inserts it into one content container, and intercepts anchors
 marked `data-export-link`. The corresponding manifest link supplies the target
-document ID and original fragment. Other links use their ordinary destinations.
+page reference and original fragment. Other links use their ordinary destinations.
 
 `/help/` is an example path, not a required Shoalrun directory. You can choose
 another root-relative path, such as `/resources/`. Set `publicBase` to that path,

package/examples/help-drawer/app.js

@@ -14,7 +14,7 @@ let current;
 let request = 0;
 let opener;
 async function openHelp(id, fragment) {
-  const document = manifest.documents.find(document => document.id === id);
+  const document = manifest.resources.find(resource => resource.ref.kind === 'page' && resource.ref.documentId === id);
   if (!document?.representations.html) throw new Error(`No HTML help for ${id}`);
   const ticket = ++request;
   const response = await fetch(manifest.publicBase + document.representations.html.path);
@@ -43,9 +43,9 @@ content.addEventListener('click', event => {
   const anchor = event.target.closest('a[data-export-link]');
   if (!anchor) return;
   const link = current?.representations.html.links.find(link => link.key === anchor.dataset.exportLink);
-  if (link?.kind !== 'document') return; // Canonical fallbacks open as ordinary links.
+  if (link?.kind !== 'resource' || link.ref?.kind !== 'page') return; // Canonical fallbacks open as ordinary links.
   event.preventDefault();
-  openHelp(link.documentId, link.fragment).catch(showError);
+  openHelp(link.ref.documentId, link.fragment).catch(showError);
 });
 function closeHelp() { request++; drawer.hidden = true; opener?.focus(); }
 document.querySelector('#close').addEventListener('click', closeHelp);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -11,9 +11,11 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
+    "./content": "./dist/content-delivery.js",
     "./authoring": "./dist/authoring-api.js",
     "./*": "./*",
-    "./components": "./dist/components.js"
+    "./components": "./dist/components.js",
+    "./content/server": "./dist/content-rest-server.js"
   },
   "files": [
     "dist",
@@ -23,7 +25,7 @@
     "styles",
     "templates",
     "examples",
-    "!examples/help-drawer/public/**",
+    "!examples/**/public/**",
     "!examples/**/node_modules/**",
     "example-configs",
     "!example-configs/**/.shoalrun/**",
@@ -32,6 +34,7 @@
     "README.md",
     "AUTHORING.md",
     "schemas/content-export.schema.json",
+    "schemas/content-rest.openapi.json",
     "CHANGELOG.md",
     "!**/*.local.md",
     "!**/*.override.md",