@ferax564/noma-cli 0.11.0

package/schemas/patch-transaction.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ferax564.github.io/noma/schemas/patch-transaction.schema.json",
+  "title": "Noma Patch Transaction",
+  "description": "A transaction-shaped patch payload accepted by `noma patch --ops`.",
+  "oneOf": [
+    { "$ref": "patch-op.schema.json" },
+    {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "patch-op.schema.json" }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ops"],
+      "properties": {
+        "ops": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "patch-op.schema.json" }
+        },
+        "prevalidate": { "type": "boolean", "default": false },
+        "postvalidate": { "type": "boolean", "default": false }
+      }
+    }
+  ]
+}

package/schemas/transcript.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ferax564.github.io/noma/schemas/transcript.schema.json",
+  "title": "Noma Patch Transcript Record",
+  "description": "One JSONL entry emitted by the MCP patch writer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "protocol_version",
+    "tool_version",
+    "op_id",
+    "ts",
+    "actor",
+    "doc_uri",
+    "pre_sha256",
+    "post_sha256",
+    "pre_sha",
+    "post_sha",
+    "op",
+    "patch_result",
+    "pre_validation",
+    "post_validation"
+  ],
+  "properties": {
+    "protocol_version": { "const": "1.0" },
+    "tool_version": { "type": "string" },
+    "op_id": { "type": "string", "format": "uuid" },
+    "ts": { "type": "string", "format": "date-time" },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "name"],
+      "properties": {
+        "kind": { "enum": ["human", "agent", "tool"] },
+        "name": { "type": "string" },
+        "model": { "type": "string" },
+        "version": { "type": "string" }
+      }
+    },
+    "doc_uri": { "type": "string" },
+    "pre_sha256": { "$ref": "#/$defs/sha256" },
+    "post_sha256": { "$ref": "#/$defs/sha256" },
+    "pre_sha": { "type": "string", "pattern": "^[a-f0-9]{8}$" },
+    "post_sha": { "type": "string", "pattern": "^[a-f0-9]{8}$" },
+    "op": { "$ref": "patch-op.schema.json" },
+    "patch_result": { "enum": ["applied", "rejected", "noop"] },
+    "pre_validation": { "$ref": "#/$defs/validationSummary" },
+    "post_validation": { "$ref": "#/$defs/validationSummary" },
+    "reason": { "type": "string" },
+    "parent_op_id": { "type": "string", "format": "uuid" },
+    "base_sha256": { "$ref": "#/$defs/sha256" },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["phase", "severity", "code", "message"],
+        "properties": {
+          "phase": { "enum": ["pre", "post"] },
+          "severity": { "enum": ["error", "warning", "info"] },
+          "code": { "type": "string" },
+          "message": { "type": "string" },
+          "nodeId": { "type": "string" },
+          "pos": {
+            "type": "object",
+            "required": ["line", "column"],
+            "properties": {
+              "line": { "type": "integer", "minimum": 1 },
+              "column": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "elapsed_ms": { "type": "number", "minimum": 0 },
+    "prev_entry_sha256": { "$ref": "#/$defs/sha256" },
+    "signature": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["algorithm", "key_id", "value"],
+          "properties": {
+            "algorithm": { "type": "string" },
+            "key_id": { "type": "string" },
+            "value": { "type": "string" }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "validationSummary": { "enum": ["ok", "warn", "error"] }
+  }
+}

package/src/ast.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 const isDirective = (n: Node): n is DirectiveNode => n.type === "directive";
+export const isSection = (n: Node): n is SectionNode => n.type === "section";
+
+export function* walk(node: Node): Generator<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);
+  }
+}

package/src/book.ts

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import yaml from "js-yaml";
+import type { DocumentNode, Node, SectionNode } from "./ast.js";
+import { walk } from "./ast.js";
+import { parse } from "./parser.js";
+import { inlineDatasetSources } from "./loader.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 function loadBook(manifestPath: string): DocumentNode {
+  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 as Record<string, unknown>;
+  const chapters = Array.isArray(manifest.chapters)
+    ? (manifest.chapters as unknown[]).filter((c): c is string => typeof c === "string")
+    : [];
+  if (chapters.length === 0) {
+    throw new Error(`book manifest has no chapters: ${manifestPath}`);
+  }
+  const baseDir = dirname(absManifest);
+
+  const meta: Record<string, unknown> = {};
+  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: Node[] = [];
+  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: string): {
+  manifest: Record<string, unknown>;
+  chapters: LoadedChapter[];
+  baseDir: string;
+} {
+  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 as Record<string, unknown>;
+  const chapterPaths = Array.isArray(manifest.chapters)
+    ? (manifest.chapters as unknown[]).filter((c): c is string => 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: string[], baseDir: string): LoadedChapter[] {
+  const out: LoadedChapter[] = [];
+  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: string, doc: DocumentNode): string {
+  const root = doc.children.find(
+    (n): n is SectionNode => 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: DocumentNode, chapterSlug: string): void {
+  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<string>(node.aliases ?? []);
+    aliases.add(original);
+    node.aliases = [...aliases];
+  }
+}
+
+export function isBookManifestPath(path: string): boolean {
+  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: DocumentNode): SectionNode[] {
+  return doc.children.filter(
+    (n): n is SectionNode => n.type === "section" && n.level === 1,
+  );
+}