@ferax564/noma-cli 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ferax564
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# Noma
+
+> **Readable source for beautiful agent artifacts.**
+
+Noma is a plain-text format for books, docs, research, dashboards, and webpages. It is:
+
+- readable like Markdown
+- structured like data
+- renderable like HTML
+- printable like PDF
+- editable by AI agents at the **block level** — not via full-file rewrites
+
+```
+.noma  →  typed AST  →  HTML / PDF / JSON / LLM context
+```
+
+**Live site:** <https://ferax564.github.io/noma/> — landing page, demo gallery, rendered HTML/PDF/LLM/JSON for every example, full docs.
+
+## Why
+
+Markdown is excellent for prose, weak for grids, cards, claims, plots, citations, and stable agent edits. HTML is the opposite — great as a render target, unpleasant as long-term source. Noma sits between them: a small directive syntax that compiles to clean semantic HTML, prints cleanly to PDF, exports a deterministic LLM-friendly form, and gives agents stable block IDs they can patch without rewriting whole files.
+
+See [`docs/direction.noma`](docs/direction.noma) for the full positioning and [PLAN.md §23](PLAN.md) for the three-layer model and the central design test every feature must pass.
+
+## Hello, Noma
+
+```noma
+---
+title: ASML Investment Thesis
+---
+
+# ASML Investment Thesis
+
+::claim{id="asml-euv-moat" confidence=0.82}
+ASML has a durable moat because it is the only supplier of EUV lithography systems at scale.
+::
+
+::evidence{for="asml-euv-moat" source="annual-report-2025"}
+ASML continues to report strong demand for EUV systems from leading-edge customers.
+::
+
+::grid{columns=2}
+:::card{title="Bull Case"}
+EUV demand stays structurally high.
+:::
+
+:::card{title="Bear Case"}
+Export restrictions and cyclicality.
+:::
+::
+```
+
+That's the whole language — directive blocks (`::name{attrs} ... ::`), Markdown-ish inline text, YAML frontmatter, and stable block IDs.
+
+## Quick start
+
+Install the public CLI:
+
+```bash
+npm install -g @ferax564/noma-cli
+noma --version
+noma init my-spec
+noma render my-spec/demo.noma --to html --out my-spec/demo.html
+```
+
+From a checkout:
+
+```bash
+git clone https://github.com/ferax564/noma.git
+cd noma
+npm install
+
+# render one demo to HTML / LLM / JSON / .noma source
+npm run noma -- render examples/agent-plan.noma --to html --out dist/agent-plan.html
+npm run noma -- render examples/agent-plan.noma --to llm
+npm run noma -- render examples/agent-plan.noma --to llm --select claim,evidence,risk --exclude dataset --budget 12000
+npm run noma -- render examples/agent-plan.noma --to json
+npm run noma -- render examples/agent-plan.noma --to noma     # AST → .noma roundtrip
+npm run noma -- ids examples/book/book.noma.yml               # global ID + alias map for agents
+
+# pick a theme
+npm run noma -- render examples/research-thesis.noma --to html --theme dark
+
+# render a multi-file book (chapters resolved relative to the manifest)
+npm run noma -- render examples/book/book.noma.yml --to html --out dist/book.html
+
+# block-level patch — agent-safe edits, no full-file rewrite
+npm run noma -- patch examples/thesis.noma \
+  --op '{"op":"update_attribute","id":"asml-euv-moat","key":"confidence","value":0.95}' \
+  --inplace
+
+# validate a document
+npm run noma -- check examples/research-thesis.noma
+
+# render in GitHub Actions
+# - uses: ferax564/noma@v0.11.0
+#   with:
+#     input: docs/spec.noma
+#     output: dist/spec.html
+
+# build the full site (examples + docs + book + dark-theme demo + landing + PDFs)
+npm run build:site
+open dist/index.html
+
+# re-align pipe tables in source (idempotent; skips fenced code blocks)
+npm run noma -- fmt examples/research-thesis.noma --inplace
+```
+
+## Block-level edits
+
+Agents and CI pipelines patch single blocks instead of rewriting whole files. Seven operations cover the editing flows that matter:
+
+```bash
+noma patch thesis.noma --op '{"op":"replace_block","id":"claim-x","content":"::claim{id=\"claim-x\" confidence=0.9}\nNew body.\n::"}'
+noma patch thesis.noma --op '{"op":"replace_body","id":"claim-x","content":"Sharper body text."}'
+noma patch thesis.noma --op '{"op":"update_heading","id":"risk-section","title":"Known Risks"}'
+noma patch thesis.noma --op '{"op":"add_block","parent":"risks","content":"::risk{id=\"r1\" severity=\"high\" owner=\"me\"}\nNew risk.\n::"}'
+noma patch thesis.noma --op '{"op":"delete_block","id":"deprecated"}'
+noma patch thesis.noma --op '{"op":"update_attribute","id":"claim-x","key":"confidence","value":0.85}'
+noma patch thesis.noma --op '{"op":"rename_id","from":"claim-x","to":"claim-renamed"}'
+noma patch thesis.noma --ops patch-transaction.json --inplace
+```
+
+`rename_id` retargets reference attributes such as `for=`, `parent=`, `dataset=`, `block=`, and `ref=`, plus `[[wikilink]]` references across the document. The source-preserving patch path rewrites only the addressed line range or inserted block, so unrelated bytes stay byte-identical. See [`docs/agent-protocol.noma`](docs/agent-protocol.noma) and [`docs/compatibility.noma`](docs/compatibility.noma).
+
+## GitHub Action
+
+Render and upload a Noma artifact from any repository:
+
+```yaml
+name: Render docs
+
+on: [push, pull_request]
+
+jobs:
+  noma:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ferax564/noma@v0.11.0
+        with:
+          input: docs/spec.noma
+          output: dist/spec.html
+          to: html
+          strict: true
+          artifact-name: spec-preview
+```
+
+The action installs the CLI from the checked-out action ref by default, runs `noma check`, renders the requested target, and uploads the result with `actions/upload-artifact`. Use `to: site` when `input` is a book manifest and `output` is a directory. For explicit dependency control, set `cli-package` to any npm package spec or `cli-version` to an `@ferax564/noma-cli` npm version range.
+
+## Demos
+
+Three artifacts that exercise the full block surface end-to-end. Each renders to HTML, PDF, LLM context, and JSON AST from a single `.noma` source. For the workflow narrative behind them, see the [case studies](docs/case-studies.noma).
+
+| Demo | What it shows | Live |
+| ---- | ------------- | ---- |
+| **Agent planning artifact** ([source](examples/agent-plan.noma)) | Q3 roadmap decision — options, decision matrix, claims/evidence/risks, agent tasks, copy-as-prompt buttons | [HTML](https://ferax564.github.io/noma/examples/agent-plan.html) · [PDF](https://ferax564.github.io/noma/examples/agent-plan.pdf) · [LLM](https://ferax564.github.io/noma/examples/agent-plan.llm.txt) · [JSON](https://ferax564.github.io/noma/examples/agent-plan.json) |
+| **Technical documentation** ([source](examples/tech-doc.noma)) | CLI reference page — tabs, callouts, code blocks, architecture diagram, cross-links | [HTML](https://ferax564.github.io/noma/examples/tech-doc.html) · [PDF](https://ferax564.github.io/noma/examples/tech-doc.pdf) · [LLM](https://ferax564.github.io/noma/examples/tech-doc.llm.txt) · [JSON](https://ferax564.github.io/noma/examples/tech-doc.json) |
+| **Investment thesis** ([source](examples/research-thesis.noma)) | Vertical-AI thesis — claims with confidence scores, counterevidence, risks, datasets, plots, quarterly review tasks | [HTML](https://ferax564.github.io/noma/examples/research-thesis.html) · [PDF](https://ferax564.github.io/noma/examples/research-thesis.pdf) · [LLM](https://ferax564.github.io/noma/examples/research-thesis.llm.txt) · [JSON](https://ferax564.github.io/noma/examples/research-thesis.json) |
+
+## Guides for adoption
+
+- [Case studies](docs/case-studies.noma) — agent-refreshable research memo, decision artifact, technical-doc publishing, and memory workflow.
+- [Comparison guide](docs/comparison.noma) — when to choose Noma vs Markdown, MDX, raw HTML, or collaborative docs.
+- [Agent editing guide](docs/agent-guide.noma) — the safe loop for ID discovery, patch transactions, validation, and strict rendering.
+- [Starter templates](docs/templates.noma) — copyable research memo, decision record, technical spec, and agent refresh templates under `examples/templates/`.
+
+## What ships today
+
+- `@ferax564/noma-cli` (this package) — hand-written parser with no parser-combinator dependency. Supports directive blocks, frontmatter, headings, lists, code, quotes, GitHub-style tables, and inline markdown. The parser is exported alongside the CLI; `import { parse } from "@ferax564/noma-cli"` works in any Node 20+ project.
+- Typed AST in `src/ast.ts` — discriminated union, exhaustively switched everywhere.
+- HTML renderer with a default CSS theme + a `dark` alternate (`--theme dark`), a print stylesheet, and per-block `{variant="..."}` styling. Native rendering for grids, cards, tabs, callouts, claims/evidence/risks, decisions, open questions, datasets, real inline-data plots (line + bar SVG, no JS), agent tasks, export buttons, controls, tables, the new `::table` directive, and `::state_change` deltas. `::html` / `::svg` / `::script` escape hatches can be blocked with `--no-unsafe`; `--strict` also omits external CDN runtimes for math, diagrams, and Plotly.
+- LLM renderer — deterministic plain-text output for context windows; escape-hatch bodies always stripped. Supports `--select`, `--exclude`, and `--budget` for scoped agent context.
+- JSON renderer — full AST export.
+- `.noma` source printer — AST → `.noma` (roundtrip-safe). Backs `noma render --to noma`; source-preserving `noma patch` rewrites addressed spans directly.
+- `noma fmt` — re-aligns GitHub-style pipe tables in source; respects pipes inside `` `code spans` `` and `\|` escapes; leaves everything else byte-identical.
+- Validator — wikilink references resolve across paragraphs, quotes, list items, headings, table cells, and book chapters. Default rules: duplicate IDs, broken references (incl. wikilinks), plot/figure issues, plot/dataset linkage (`plot-unknown-dataset`, `plot-unknown-column`), `plot-mixed-delimiters`, claim-without-evidence, risk-without-owner, decision-without-status, agent-task-without-scope, stale-citation, escape-hatch-untrusted, evidence-missing-for, state_change shape rules, and `out-of-profile-directive` when a `profile` is declared. Per-block opt-out with the `noverify` flag.
+- Profiles — declare `profile: research | technical | minimal` in frontmatter as a contract about which directives the document uses; downstream tools can narrow safely.
+- Plot/dataset linkage — `::plot{dataset="<id>" column="<name>" xcolumn="<name>"}` resolves against sibling `::dataset` blocks at render time.
+- Citation staleness — global default 365 days, override via frontmatter `stale_citation_days`, per-citation `stale_after_days=N`, or CLI `--stale-days <n>`.
+- CLI — `noma --version`, `noma init`, `noma parse | render | ids | schema | check | export | patch | fmt`. Patch ops include `replace_block`, `replace_body`, `update_heading`, `add_block`, `delete_block`, `update_attribute`, and `rename_id`, plus transaction-shaped `--ops` files with optional pre/post validation.
+- GitHub Action — `uses: ferax564/noma@v0.11.0` validates, renders, and uploads HTML/LLM/JSON/Noma/site artifacts in CI.
+- Book manifests (`book.noma.yml`) + multi-file rendering. CLI auto-detects manifest extension; chapters resolve relative to its directory.
+- Starter templates under `examples/templates/` for research memos, decision records, technical specs, and agent refresh packs.
+- Seven examples: three demos (agent-plan, tech-doc, research-thesis), the original thesis/landing/book-chapter, and the `examples/book/` 3-chapter book.
+- Ten docs (all written in Noma): direction, spec, compatibility, getting started, agent patch protocol, architecture, comparison guide, case studies, agent editing guide, and starter templates.
+- Hand-crafted HTML landing page (`site/index.html`).
+- PDF demo exports via Puppeteer.
+- GitHub Pages deployment on every push to `main`.
+
+See [`PLAN.md`](PLAN.md) for the long-term vision, [`docs/direction.noma`](docs/direction.noma) for the positioning, [`docs/spec.noma`](docs/spec.noma) for the format spec, and [`CHANGELOG.md`](CHANGELOG.md) for what changed when.
+
+## Status
+
+**Status:** v0.11.0 — first public `@ferax564/*` release line. v0.11 adds bundled JSON Schemas via `noma schema <name>`, source-preserving `replace_body` and `update_heading` patch ops, `parent=` retargeting for `rename_id`, package manifest hardening for public scoped publish, a packed-CLI smoke gate, the compatibility policy, adoption guides, and namespaced directive parsing groundwork for future community packs. Carries the v0.9.0 experimental `@ferax564/noma-agent-sdk` v0.1.0 unchanged. See [`CHANGELOG.md`](CHANGELOG.md) and `PLAN.md` §24.20 for the full release tracker.
+
+## License
+
+MIT © 2026 ferax564

package/bin/noma.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Production CLI entry — loads the compiled dist build.
+// During development use `npm run noma -- ...` (which goes through tsx).
+import("../dist/cli.js").catch((err) => {
+  console.error("noma: failed to load CLI. Did you run `npm run build`?");
+  console.error(err);
+  process.exit(1);
+});

package/dist/ast.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Noma AST — single source of truth.
+ *
+ * Renderers and the validator must import types from this file. Adding a new
+ * node variant requires extending the `Node` union and updating every
+ * renderer's switch (the compiler will tell you where).
+ */
+export type AttrValue = string | number | boolean;
+export type Attrs = Record<string, AttrValue>;
+export interface Position {
+    line: number;
+    column: number;
+}
+interface NodeBase {
+    /** Stable, user-facing identifier when set. Auto-generated for headings. */
+    id?: string;
+    /**
+     * Additional IDs that resolve to this node. Populated by:
+     *   • frontmatter `aliases:` list (attaches to chapter root section)
+     *   • chapter filename slug in book mode
+     *   • path-scoped heading ID in book mode (registers the bare slug as alias)
+     */
+    aliases?: string[];
+    /** Source position of the node's first character. */
+    pos?: Position;
+    /**
+     * 1-based last source line covered by this node (inclusive). Populated by
+     * the parser; used by `patchSource` to splice ranges without re-rendering
+     * the rest of the document.
+     */
+    endLine?: number;
+}
+export interface DocumentNode extends NodeBase {
+    type: "document";
+    meta: Record<string, unknown>;
+    children: Node[];
+}
+export interface FrontmatterNode extends NodeBase {
+    type: "frontmatter";
+    /** Parsed YAML object (string keys → arbitrary values). */
+    data: Record<string, unknown>;
+    /** Raw frontmatter source text (between the --- fences, exclusive). */
+    raw: string;
+}
+export interface SectionNode extends NodeBase {
+    type: "section";
+    level: number;
+    title: string;
+    children: Node[];
+}
+export interface ParagraphNode extends NodeBase {
+    type: "paragraph";
+    content: string;
+}
+export interface CodeNode extends NodeBase {
+    type: "code";
+    lang?: string;
+    content: string;
+}
+export interface ListNode extends NodeBase {
+    type: "list";
+    ordered: boolean;
+    items: ListItemNode[];
+}
+export interface ListItemNode extends NodeBase {
+    type: "list_item";
+    content: string;
+}
+export interface QuoteNode extends NodeBase {
+    type: "quote";
+    content: string;
+}
+export interface ThematicBreakNode extends NodeBase {
+    type: "thematic_break";
+}
+export type TableAlign = "left" | "center" | "right" | null;
+export interface TableNode extends NodeBase {
+    type: "table";
+    /** Header cells (one row). Inline markdown is preserved as plain strings. */
+    header: string[];
+    /** Per-column alignment from the separator row (`:---`, `:---:`, `---:`). */
+    align: TableAlign[];
+    /** Body rows, each with one entry per column. */
+    rows: string[][];
+}
+/**
+ * Generic block directive — covers every typed semantic block (claim, evidence,
+ * grid, card, plot, dataset, agent_task, ...). Renderers dispatch on `name`.
+ */
+export interface DirectiveNode extends NodeBase {
+    type: "directive";
+    name: string;
+    attrs: Attrs;
+    /** Inline body text (when the block has no nested children). */
+    body?: string;
+    /** Nested directive children (grids, cards, etc.). */
+    children: Node[];
+}
+export type Node = DocumentNode | SectionNode | FrontmatterNode | ParagraphNode | CodeNode | ListNode | ListItemNode | QuoteNode | ThematicBreakNode | TableNode | DirectiveNode;
+export type BlockNode = Exclude<Node, ListItemNode | FrontmatterNode>;
+export interface Diagnostic {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    pos?: Position;
+    nodeId?: string;
+}
+export declare const isDirective: (n: Node) => n is DirectiveNode;
+export declare const isSection: (n: Node) => n is SectionNode;
+export declare function walk(node: Node): Generator<Node>;
+export {};

package/dist/ast.js

@@ -0,0 +1,23 @@
+/**
+ * Noma AST — single source of truth.
+ *
+ * Renderers and the validator must import types from this file. Adding a new
+ * node variant requires extending the `Node` union and updating every
+ * renderer's switch (the compiler will tell you where).
+ */
+export const isDirective = (n) => n.type === "directive";
+export const isSection = (n) => n.type === "section";
+export function* walk(node) {
+    yield node;
+    if (node.type === "document" ||
+        node.type === "section" ||
+        node.type === "directive") {
+        for (const child of node.children)
+            yield* walk(child);
+    }
+    else if (node.type === "list") {
+        for (const item of node.items)
+            yield* walk(item);
+    }
+}
+//# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmIH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAO,EAAsB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC;AACnF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAO,EAAoB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;AAE7E,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,IAAU;IAC9B,MAAM,IAAI,CAAC;IACX,IACE,IAAI,CAAC,IAAI,KAAK,UAAU;QACxB,IAAI,CAAC,IAAI,KAAK,SAAS;QACvB,IAAI,CAAC,IAAI,KAAK,WAAW,EACzB,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC;SAAM,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/book.d.ts

@@ -0,0 +1,56 @@
+import type { DocumentNode, SectionNode } from "./ast.js";
+/**
+ * Shape of `book.yml` manifests. Note: YAML keys are snake_case (`trusted_publishing`),
+ * read directly from the manifest map. The typed shape below covers fields the
+ * loader/renderer consume by name; unrecognised keys pass through untouched.
+ *
+ * Recognised security-posture keys (read at the render path, not surfaced as
+ * typed fields):
+ * - `trusted_publishing: true` — implies `--no-unsafe` for every render driven
+ *   by this manifest. Disables `::html`, `::svg`, `::script` escape hatches.
+ *   The manifest is the final word; no CLI flag re-enables them once the
+ *   manifest forbids them.
+ */
+export interface BookManifest {
+    title?: string;
+    author?: string;
+    chapters: string[];
+    outputs?: {
+        html?: {
+            theme?: string;
+            math?: "katex" | "none";
+        };
+        llm?: Record<string, unknown>;
+        pdf?: Record<string, unknown>;
+    };
+}
+export interface LoadedChapter {
+    /** Path-safe chapter slug derived from filename (or root H1 id). */
+    slug: string;
+    /** Source path of the chapter file (absolute). */
+    source: string;
+    /** Parsed chapter document with scoped IDs applied. */
+    doc: DocumentNode;
+}
+/**
+ * Load a YAML book manifest and assemble a single DocumentNode by
+ * concatenating each chapter's parsed AST. Chapter file paths are
+ * resolved relative to the manifest's directory.
+ */
+export declare function loadBook(manifestPath: string): DocumentNode;
+/**
+ * Load every chapter listed in a book manifest as a separate DocumentNode,
+ * applying chapter-scoped heading IDs in book mode. Used by the multi-page
+ * site renderer; loadBook() concatenates the same set into one doc.
+ */
+export declare function loadBookChapters(manifestPath: string): {
+    manifest: Record<string, unknown>;
+    chapters: LoadedChapter[];
+    baseDir: string;
+};
+export declare function isBookManifestPath(path: string): boolean;
+/**
+ * Pull the implicit chapter list off a fully-loaded document for TOC
+ * purposes. Each top-level h1 section is treated as a chapter heading.
+ */
+export declare function listChapters(doc: DocumentNode): SectionNode[];

package/dist/book.js

@@ -0,0 +1,120 @@
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import yaml from "js-yaml";
+import { walk } from "./ast.js";
+import { parse } from "./parser.js";
+import { inlineDatasetSources } from "./loader.js";
+/**
+ * Load a YAML book manifest and assemble a single DocumentNode by
+ * concatenating each chapter's parsed AST. Chapter file paths are
+ * resolved relative to the manifest's directory.
+ */
+export function loadBook(manifestPath) {
+    const absManifest = resolve(manifestPath);
+    const raw = readFileSync(absManifest, "utf8");
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`book manifest must be a YAML object: ${manifestPath}`);
+    }
+    const manifest = parsed;
+    const chapters = Array.isArray(manifest.chapters)
+        ? manifest.chapters.filter((c) => typeof c === "string")
+        : [];
+    if (chapters.length === 0) {
+        throw new Error(`book manifest has no chapters: ${manifestPath}`);
+    }
+    const baseDir = dirname(absManifest);
+    const meta = {};
+    if (typeof manifest.title === "string")
+        meta.title = manifest.title;
+    if (typeof manifest.author === "string")
+        meta.author = manifest.author;
+    meta.book = {
+        chapters: chapters.length,
+        manifest: manifestPath,
+    };
+    const children = [];
+    const loaded = loadChapters(chapters, baseDir);
+    for (const ch of loaded) {
+        for (const child of ch.doc.children)
+            children.push(child);
+    }
+    return { type: "document", meta, children };
+}
+/**
+ * Load every chapter listed in a book manifest as a separate DocumentNode,
+ * applying chapter-scoped heading IDs in book mode. Used by the multi-page
+ * site renderer; loadBook() concatenates the same set into one doc.
+ */
+export function loadBookChapters(manifestPath) {
+    const absManifest = resolve(manifestPath);
+    const raw = readFileSync(absManifest, "utf8");
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`book manifest must be a YAML object: ${manifestPath}`);
+    }
+    const manifest = parsed;
+    const chapterPaths = Array.isArray(manifest.chapters)
+        ? manifest.chapters.filter((c) => typeof c === "string")
+        : [];
+    if (chapterPaths.length === 0) {
+        throw new Error(`book manifest has no chapters: ${manifestPath}`);
+    }
+    const baseDir = dirname(absManifest);
+    return { manifest, chapters: loadChapters(chapterPaths, baseDir), baseDir };
+}
+function loadChapters(chapterPaths, baseDir) {
+    const out = [];
+    for (const chapter of chapterPaths) {
+        const chapterPath = isAbsolute(chapter) ? chapter : resolve(baseDir, chapter);
+        const source = readFileSync(chapterPath, "utf8");
+        const doc = parse(source, { filename: chapterPath });
+        inlineDatasetSources(doc, dirname(chapterPath));
+        const slug = chapterSlug(chapterPath, doc);
+        scopeHeadingIds(doc, slug);
+        out.push({ slug, source: chapterPath, doc });
+    }
+    return out;
+}
+function chapterSlug(chapterPath, doc) {
+    const root = doc.children.find((n) => n.type === "section" && n.level === 1);
+    if (root && root.id)
+        return root.id;
+    const base = chapterPath.replace(/\\/g, "/").split("/").pop() ?? chapterPath;
+    const stem = base.replace(/\.noma$/i, "").replace(/^\d+[-_]/, "");
+    return stem.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+}
+/**
+ * In book mode, every heading slug is path-prefixed by its chapter root.
+ * `# Risk Premia 3` + `## Risks` → `risk-premia-3` and `risk-premia-3/risks`.
+ * Original (un-prefixed) ID is kept as an alias on the same node so any
+ * legacy `[[risks]]` writes still resolve to the first occurrence.
+ */
+function scopeHeadingIds(doc, chapterSlug) {
+    for (const node of walk(doc)) {
+        if (node.type !== "section")
+            continue;
+        if (node.level === 1)
+            continue;
+        if (!node.id)
+            continue;
+        if (node.id.startsWith(`${chapterSlug}/`))
+            continue;
+        const original = node.id;
+        node.id = `${chapterSlug}/${original}`;
+        const aliases = new Set(node.aliases ?? []);
+        aliases.add(original);
+        node.aliases = [...aliases];
+    }
+}
+export function isBookManifestPath(path) {
+    return /\.ya?ml$/i.test(path);
+}
+/**
+ * Pull the implicit chapter list off a fully-loaded document for TOC
+ * purposes. Each top-level h1 section is treated as a chapter heading.
+ */
+export function listChapters(doc) {
+    return doc.children.filter((n) => n.type === "section" && n.level === 1);
+}
+//# sourceMappingURL=book.js.map

package/dist/book.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"book.js","sourceRoot":"","sources":["../src/book.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};