yamlover 0.3.4 → 0.3.6

package/src/client/vendor/README.md

@@ -1,30 +0,0 @@
-# Vendored: DjVu.js
-
-`djvu.js` is a prebuilt bundle of the **DjVu.js library** by Roman Chistokhodov
-(RussCoder), used by the `djvu` renderer to decode `.djvu` documents in the
-browser (the browser has no native DjVu support).
-
-- Upstream: https://github.com/RussCoder/djvujs — https://djvu.js.org
-- Version: 0.5.4
-- **License: GNU GPL v2** (the library only; the upstream viewer/extension are
-  Unlicense). By bundling it here, the distributed client includes GPL-v2 code.
-  See https://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
-
-## Why it's vendored
-
-The npm package `djvujs-dist` ships *source*, not an importable module (no
-`main`/`module`/`types`), and pulls a large dev toolchain. We build its IIFE
-bundle once and commit the single output here instead of depending on the
-package at runtime.
-
-## Regenerating
-
-```sh
-npm install djvujs-dist            # temporary
-cd node_modules/djvujs-dist/library && npm run build
-cp dist/djvu.js <repo>/tools/server/src/client/vendor/djvu.js
-npm uninstall djvujs-dist
-```
-
-The bundle defines a global `DjVu` (`var DjVu = (function(){…})()`); the renderer
-loads it as a classic `<script>` and uses `new DjVu.Document(arrayBuffer)`.

package/src/client/vite-env.d.ts

@@ -1,31 +0,0 @@
-/// <reference types="vite/client" />
-
-// UTIF.js ships no types. Declare the minimal surface our TIFF renderer uses:
-// decode the container into IFDs, decode each IFD's pixels in place, then read it
-// back as RGBA. See https://github.com/photopea/UTIF.js.
-declare module "utif" {
-  interface IFD {
-    width?: number;
-    height?: number;
-    [key: string]: unknown;
-  }
-  const UTIF: {
-    decode(buf: ArrayBuffer | Uint8Array): IFD[];
-    decodeImage(buf: ArrayBuffer | Uint8Array, ifd: IFD): void;
-    toRGBA8(ifd: IFD): Uint8Array;
-  };
-  export default UTIF;
-}
-
-// mammoth's browser build ships no types. Declare the one call our docx renderer
-// makes: convert a .docx ArrayBuffer to an HTML string. See https://github.com/mwilliamson/mammoth.js.
-declare module "mammoth/mammoth.browser" {
-  interface ConvertResult {
-    value: string;
-    messages: { type: string; message: string }[];
-  }
-  const mammoth: {
-    convertToHtml(input: { arrayBuffer: ArrayBuffer }): Promise<ConvertResult>;
-  };
-  export default mammoth;
-}

package/src/server/api.ts

@@ -1,147 +0,0 @@
-/**
- * api.ts — the JSON API the SPA calls.
- *
- * Endpoints, all keyed by a JSON-space `path` (`/key[0]/sub`, no "properties"):
- *
- *   GET /api/tree                        the table of contents (containers only)
- *   GET /api/json?path&depth             the node's value as JSON
- *   GET /api/schema?path&depth&format    the node's instance schema (json | yaml)
- *   GET /api/blob?path                   a file-backed node's raw bytes (for the
- *                                        image / pdf / html / djvu / markup renderers)
- *
- * The materialized tree is cached per server for a short window (leaf bytes load
- * lazily within it), so a burst of clicks does not re-read the filesystem; edits
- * show up after the cache window on reload.
- */
-
-import path from "node:path";
-import fs from "node:fs";
-import type { IncomingMessage, ServerResponse } from "node:http";
-import {
-  loadEntity,
-  getNode,
-  strToSegs,
-  buildTree,
-  labelForSeg,
-  toPlain,
-  toSchema,
-  buildRelations,
-  binaryContent,
-  displayTypeLabel,
-  documentPath,
-  formatFromExt,
-  setIgnoreFilter,
-  YNode,
-} from "./yamlover.js";
-import { buildGitIgnore } from "./gitignore.js";
-
-type Handler = (req: IncomingMessage, res: ServerResponse, url: URL) => void;
-
-interface Options {
-  gitignore?: boolean; // honor .gitignore for stray files (default: true)
-}
-
-// The materialized tree is cached this long. With lazy directory loading the
-// cached tree *accumulates* the levels you browse (each read once and memoized),
-// so a longer window keeps navigation warm; edits show after it on reload.
-const CACHE_TTL_MS = 15000;
-
-export function createHandlers(dataRoot: string, opts: Options = {}): Handler {
-  // The root label (breadcrumb head and TOC root): the yamlover title if set,
-  // else the served directory's name — always non-empty.
-  const rootName = path.basename(path.resolve(dataRoot)) || "/";
-  setIgnoreFilter(opts.gitignore === false ? () => false : buildGitIgnore(dataRoot));
-
-  let cache: { root: YNode; time: number } | null = null;
-  const root = (): YNode => {
-    const now = Date.now();
-    if (!cache || now - cache.time > CACHE_TTL_MS) cache = { root: loadEntity(dataRoot), time: now };
-    return cache.root;
-  };
-
-  return (_req, res, url) => {
-    try {
-      const segs = strToSegs(url.searchParams.get("path") || "/");
-      const depth = parseDepth(url.searchParams.get("depth"));
-
-      if (url.pathname === "/api/info") {
-        sendJson(res, 200, { root: root().title || rootName }); // breadcrumb head
-        return;
-      }
-
-      if (url.pathname === "/api/tree") {
-        // The TOC loads lazily: a subtree rooted at `path`, `depth` levels deep
-        // (default 3). Past the boundary, nodes carry hasChildren for the client
-        // to fetch on expand.
-        const start = getNode(root(), segs);
-        const label = segs.length === 0 ? start.title || rootName : labelForSeg(start, segs[segs.length - 1]);
-        sendJson(res, 200, buildTree(start, segs, label, depth ?? 3));
-        return;
-      }
-
-      if (url.pathname === "/api/blob") {
-        // Raw file bytes, served with the node's (inferred) format as the
-        // Content-Type, so a renderer can point an <img>/<iframe>/pdf loader at
-        // the URL — or fetch the text of a markdown/asciidoc file — directly.
-        const n = getNode(root(), segs);
-        if (!n.path || !fs.existsSync(n.path) || fs.statSync(n.path).isDirectory()) {
-          sendJson(res, 404, { error: `not a file-backed node: ${url.searchParams.get("path")}` });
-          return;
-        }
-        const data = fs.readFileSync(n.path);
-        res.statusCode = 200;
-        res.setHeader("Content-Type", n.format ?? formatFromExt(n.path) ?? "application/octet-stream");
-        res.setHeader("Content-Length", String(data.length));
-        res.end(data);
-        return;
-      }
-
-      const node = getNode(root(), segs);
-      // display type: a virtual-children overlay reads as `object` (matches the TOC)
-      const type = displayTypeLabel(node);
-      // Every representation is one level deep with nested containers as links;
-      // the client picks the YAML/JSON syntax. `depth` defaults to 1.
-      const viewDepth = depth ?? 1;
-
-      if (url.pathname === "/api/json") {
-        // A binary leaf's bytes load only on explicit request (?binary=1) — the
-        // selection's header fetch shows its cheap `repr` (size) via toPlain.
-        const wantBytes = type === "binary" && url.searchParams.get("binary") === "1";
-        sendJson(res, 200, {
-          path: url.searchParams.get("path") || "/",
-          type,
-          format: node.format ?? null, // with `type`, the (type, format) renderer key
-          concrete: node.concrete,
-          // the document (nearest yamlover entity) this node belongs to — the anchor
-          // a document-relative (`/…`) marklower link resolves against
-          documentPath: documentPath(root(), segs),
-          title: node.title ?? null,
-          description: node.description ?? null,
-          // virtual children are merged into the value; named up-edges (+ `..`)
-          // ride alongside as `relations` for the panel above the divider
-          value: wantBytes ? binaryContent(node) : toPlain(node, viewDepth, segs, true, root()),
-          relations: buildRelations(node, segs, root()),
-        });
-      } else if (url.pathname === "/api/schema") {
-        // pass the real root so a node's rel pointers (esp. absolute /…) resolve
-        sendJson(res, 200, toSchema(node, viewDepth, segs, true, root()));
-      } else {
-        sendJson(res, 404, { error: `no such endpoint: ${url.pathname}` });
-      }
-    } catch (exc) {
-      sendJson(res, 400, { error: (exc as Error).message || String(exc) });
-    }
-  };
-}
-
-function parseDepth(raw: string | null): number | null {
-  if (raw == null || raw === "") return null;
-  const n = Number(raw);
-  return Number.isInteger(n) && n >= 0 ? n : null;
-}
-
-function sendJson(res: ServerResponse, status: number, body: unknown): void {
-  res.statusCode = status;
-  res.setHeader("Content-Type", "application/json; charset=utf-8");
-  res.end(JSON.stringify(body, null, 2));
-}

package/src/server/embed.ts

@@ -1,187 +0,0 @@
-/**
- * embed.ts — surgical, indentation-aware edits that EMBED fragments and annotations into a
- * yamlover host body (a standalone `*.yamlover` document, or a directory's
- * `.yamlover/body.yamlover` overlay). Pure string→string transforms, like the chapter-list
- * insertion in engine-api.ts — the parser tracks no spans, so we edit the source text directly,
- * preserving the rest of the file (comments, formatting). See ANNOTATIONS.md.
- *
- * A host body is YAML-shaped: a mapping's keys at one indent; a sequence's `- ` items at the
- * SAME indent as their key; an item/value body 2 deeper. We descend a `within` path of mapping
- * KEYS (creating any that are absent, as empty blocks) to reach a target node, then:
- *   • append an element to its `yamlover-annotations:` sequence (creating the key), or
- *   • upsert a `<slug>:` entry into its `yamlover-fragments:` mapping (creating the key).
- *
- * Index (sequence-position) descent — e.g. tagging a chapter CHUNK, which would turn its
- * block-scalar into an omni node — is intentionally NOT handled here; the server resolves such a
- * target to a key-addressable host. Keep this module free of fs / Store coupling so it unit-tests
- * in isolation (see test/embed.test.ts).
- */
-
-const ANNOTATIONS_KEY = "yamlover-annotations";
-const FRAGMENTS_KEY = "yamlover-fragments";
-
-const indentOf = (line: string): number => { let i = 0; while (line[i] === " ") i++; return i; };
-const isContentLine = (line: string): boolean => { const t = line.trim(); return t.length > 0 && !t.startsWith("#"); };
-
-/** The indent of the first content line — the top mapping's key column (0 for most bodies). */
-function firstContentIndent(lines: string[]): number {
-  for (const l of lines) if (isContentLine(l)) return indentOf(l);
-  return 0;
-}
-
-/** A yamlover plain/quoted key token: bare when it is a safe plain scalar, else double-quoted
- *  (JSON escapes — the subset the parser reads back). Mirrors how filenames with dots/spaces are
- *  authored as overlay keys (e.g. `"S0002-9904.pdf":`). */
-export function keyToken(key: string): string {
-  return /^[A-Za-z0-9_][A-Za-z0-9_-]*$/.test(key) ? key : JSON.stringify(key);
-}
-
-/** Line index of `key:` at exactly `indent` within [lo,hi); -1 once the mapping ends (a dedent
- *  to a shallower content line). Skips deeper lines (a nested value / block scalar). */
-function findKeyLine(lines: string[], lo: number, hi: number, indent: number, key: string): number {
-  const tok = keyToken(key);
-  for (let i = lo; i < hi; i++) {
-    if (!isContentLine(lines[i])) continue;
-    const ind = indentOf(lines[i]);
-    if (ind < indent) return -1; // left the mapping
-    if (ind !== indent) continue; // deeper — a nested value
-    const t = lines[i].trim();
-    if (t === `${key}:` || t.startsWith(`${key}: `) || t === `${tok}:` || t.startsWith(`${tok}: `)) return i;
-  }
-  return -1;
-}
-
-/** Walk `end` back over trailing blank lines, so an insert lands right after the last content. */
-function trimBack(lines: string[], floor: number, end: number): number {
-  let e = end;
-  while (e > floor + 1 && !isContentLine(lines[e - 1])) e--;
-  return e;
-}
-
-/** The end (exclusive) of the block owned by the content starting at `from`, whose own lines sit
- *  at >= `indent`: the first later content line shallower than `indent`, sans trailing blanks. */
-function blockEnd(lines: string[], from: number, hi: number, indent: number): number {
-  let last = from;
-  for (let i = from; i < hi; i++) {
-    if (!isContentLine(lines[i])) continue;
-    if (indentOf(lines[i]) < indent) return trimBack(lines, last, i);
-    last = i;
-  }
-  return trimBack(lines, last, hi);
-}
-
-interface Region { lo: number; hi: number; indent: number } // a mapping body: child keys at `indent`, within [lo,hi)
-
-/** Descend the mapping-KEY path `within` to the target node's body region, CREATING any missing
- *  key as an empty block (so a fresh overlay grows the `"file":` → `yamlover-fragments:` →
- *  `<slug>:` spine on demand). Mutates `lines` in place; returns the region under the last key. */
-function reachBody(lines: string[], within: string[]): Region {
-  let lo = 0;
-  let hi = lines.length;
-  let indent = firstContentIndent(lines);
-  if (lines.length === 1 && lines[0] === "") { lines.length = 0; hi = 0; indent = 0; } // empty file
-
-  for (const key of within) {
-    const L = findKeyLine(lines, lo, hi, indent, key);
-    if (L < 0) {
-      const at = trimBack(lines, lo - 1, hi); // append the new key at the end of the current body
-      lines.splice(at, 0, `${" ".repeat(indent)}${keyToken(key)}:`);
-      lo = at + 1; hi = at + 1; indent += 2; // its (empty) body
-      continue;
-    }
-    const inline = lines[L].slice(indentOf(lines[L])).slice(`${lines[L].trim().split(":")[0]}:`.length);
-    const bodyLo = L + 1;
-    const bodyHi = blockEnd(lines, bodyLo, hi, indent + 1); // anything deeper than the key
-    // the child key column: a deeper content line's indent if the node already has a block body,
-    // else key-indent + 2 (a leaf/inline value gains its first field there — an omni node).
-    let childIndent = indent + 2;
-    for (let i = bodyLo; i < bodyHi; i++) {
-      if (isContentLine(lines[i]) && indentOf(lines[i]) > indent) { childIndent = indentOf(lines[i]); break; }
-    }
-    void inline;
-    lo = bodyLo; hi = bodyHi; indent = childIndent;
-  }
-  return { lo, hi, indent };
-}
-
-/** Start lines of the `- ` items of a sequence whose key sits at `indent` (items at the same
- *  indent), scanning the region body for the `key:` then its items. */
-function seqItemLines(lines: string[], region: Region, key: string): { keyLine: number; items: number[]; end: number } | null {
-  const keyLine = findKeyLine(lines, region.lo, region.hi, region.indent, key);
-  if (keyLine < 0) return null;
-  const items: number[] = [];
-  let end = keyLine + 1;
-  for (let i = keyLine + 1; i < region.hi; i++) {
-    if (!isContentLine(lines[i])) continue;
-    const ind = indentOf(lines[i]);
-    if (ind < region.indent) break;
-    if (ind === region.indent) {
-      const t = lines[i].trim();
-      if (t === "-" || t.startsWith("- ")) { items.push(i); end = i; continue; }
-      break; // a sibling key at the list indent → the sequence ended
-    }
-    end = i; // deeper — the current item's body
-  }
-  return { keyLine, items, end: trimBack(lines, end, region.hi) };
-}
-
-/** Append one annotation element (rendered at the list indent) to the `yamlover-annotations:`
- *  sequence of the node addressed by `within`, creating the key (and any missing path) if absent.
- *  `render(indent)` returns the element's source lines (a `- *…tag` item, or a `- {…}` object). */
-export function appendAnnotation(text: string, within: string[], render: (indent: number) => string[]): string {
-  const lines = text.replace(/\n$/, "").split("\n");
-  const region = reachBody(lines, within);
-  const seq = seqItemLines(lines, region, ANNOTATIONS_KEY);
-  if (!seq) {
-    const at = trimBack(lines, region.lo - 1, region.hi);
-    lines.splice(at, 0, `${" ".repeat(region.indent)}${ANNOTATIONS_KEY}:`, ...render(region.indent));
-  } else {
-    lines.splice(seq.end, 0, ...render(region.indent));
-  }
-  return lines.join("\n") + "\n";
-}
-
-/** Upsert a `<slug>:` entry into the `yamlover-fragments:` mapping of the node addressed by
- *  `within`, creating the key (and any missing path) if absent. `render(indent)` returns the
- *  fragment's source lines INCLUDING the `<slug>:` line, at the mapping's child indent. A slug
- *  that already exists is REPLACED (its whole block). */
-export function upsertFragment(text: string, within: string[], slug: string, render: (indent: number) => string[]): string {
-  const lines = text.replace(/\n$/, "").split("\n");
-  const region = reachBody(lines, within);
-  let fragKey = findKeyLine(lines, region.lo, region.hi, region.indent, FRAGMENTS_KEY);
-  if (fragKey < 0) {
-    const at = trimBack(lines, region.lo - 1, region.hi);
-    lines.splice(at, 0, `${" ".repeat(region.indent)}${FRAGMENTS_KEY}:`);
-    fragKey = at;
-  }
-  const mapIndent = region.indent + 2;
-  const mapBody: Region = { lo: fragKey + 1, hi: blockEnd(lines, fragKey + 1, lines.length, region.indent + 1), indent: mapIndent };
-  const existing = findKeyLine(lines, mapBody.lo, mapBody.hi, mapIndent, slug);
-  if (existing >= 0) {
-    const end = blockEnd(lines, existing + 1, mapBody.hi, mapIndent + 1);
-    lines.splice(existing, end - existing, ...render(mapIndent));
-  } else {
-    const at = trimBack(lines, fragKey, mapBody.hi);
-    lines.splice(at, 0, ...render(mapIndent));
-  }
-  return lines.join("\n") + "\n";
-}
-
-/** Remove an annotation element from the `yamlover-annotations:` of the node at `within` — the
- *  first `- ` item whose trimmed text matches `predicate`. Returns the text unchanged if none
- *  matches. The block of a multi-line object item is removed whole. */
-export function removeAnnotation(text: string, within: string[], predicate: (itemText: string) => boolean): string {
-  const lines = text.replace(/\n$/, "").split("\n");
-  const region = reachBody(lines, within);
-  const seq = seqItemLines(lines, region, ANNOTATIONS_KEY);
-  if (!seq) return text;
-  for (let k = 0; k < seq.items.length; k++) {
-    const i = seq.items[k];
-    const itemText = lines[i].trim().replace(/^-\s*/, "");
-    if (!predicate(itemText)) continue;
-    const next = k + 1 < seq.items.length ? seq.items[k + 1] : seq.end;
-    lines.splice(i, next - i);
-    return lines.join("\n") + "\n";
-  }
-  return text;
-}