@milesnl/ptx-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Nathan Miles
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @milesnl/ptx-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Library for reading data from Paratext project folders: scripture text (USFM),
+AKG-style interlinear glosses, and the Biblical Terms list. It is the data layer
+used by the [`@milesnl/ptx-mcp`](https://www.npmjs.com/package/@milesnl/ptx-mcp) MCP server.
+
+## Install
+
+```bash
+npm install @milesnl/ptx-core
+```
+
+Requires Node.js 20.11 or later. ESM only.
+
+## Usage
+
+```ts
+import { resolveProjectsRoot, listProjects, getScripture } from "@milesnl/ptx-core"
+
+const root = resolveProjectsRoot("/path/to/My Paratext 9 Projects")
+console.log(listProjects(root))
+```
+
+Everything exported from the modules below is available from the package root:
+`discovery` (project folders), `scripture`, `usfmBook`, `interlinear`, `books`, and `biblicalTerms`.
+
+The Biblical Terms functions take the path to `BiblicalTerms.xml`; use
+`resolveBiblicalTermsPath(paratextInstallDir?)` to locate it.
+
+## License
+
+ISC

package/dist/biblicalTerms.d.ts

@@ -0,0 +1,38 @@
+export declare class BiblicalTermsNotFoundError extends Error {
+    constructor(triedPaths: string[]);
+}
+export declare class TermNotFoundError extends Error {
+    constructor(id: string);
+}
+export interface TermSummary {
+    id: string;
+    gloss: string;
+    transliteration: string;
+    language: string;
+    category: string;
+    strong: string[];
+    refCount: number;
+}
+export interface TermRefsRequest {
+    termsPath: string;
+    id: string;
+    book?: string;
+    startChapter?: number;
+    startVerse?: number;
+    endChapter?: number;
+    endVerse?: number;
+    refs?: string;
+}
+export declare const DEFAULT_TERMS_PATHS: string[];
+export declare function resolveBiblicalTermsPath(paratextInstallDir?: string, candidates?: string[]): string;
+export declare class TermRenderingsNotFoundError extends Error {
+    constructor(projectId: string);
+}
+export interface TermRendering {
+    renderings: string;
+    denials: string;
+    notes: string;
+}
+export declare function searchTerms(termsPath: string, search: string, book?: string): TermSummary[];
+export declare function getTermRefs(request: TermRefsRequest): string;
+export declare function getTermRendering(projectsRoot: string, projectId: string, id: string): TermRendering;

package/dist/biblicalTerms.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+import { bookCodeFromNumber, bookNumberFromCode, isBookCode } from "./books.js";
+import { getProjectDir } from "./discovery.js";
+import { parseRefs } from "./interlinear.js";
+import { InvalidReferenceError } from "./scripture.js";
+// Biblical Terms list layout is documented in src/md/bt/bt_spec.md.
+export class BiblicalTermsNotFoundError extends Error {
+    constructor(triedPaths) {
+        super(`Biblical Terms list not found. Tried: ${triedPaths.join("; ")}`);
+        this.name = "BiblicalTermsNotFoundError";
+    }
+}
+export class TermNotFoundError extends Error {
+    constructor(id) {
+        super(`Biblical term not found: ${id}`);
+        this.name = "TermNotFoundError";
+    }
+}
+const TERMS_FILE = "BiblicalTerms.xml";
+// Default locations of the Biblical Terms list: Paratext install dirs, then this repo's copy.
+export const DEFAULT_TERMS_PATHS = [
+    "C:\\Program Files (x86)\\Paratext 9\\Terms\\Lists\\" + TERMS_FILE,
+    "C:\\Program Files\\Paratext 9\\Terms\\Lists\\" + TERMS_FILE,
+    path.join(import.meta.dirname, "..", "myParatext", "Lists", TERMS_FILE)
+];
+export function resolveBiblicalTermsPath(paratextInstallDir, candidates = DEFAULT_TERMS_PATHS) {
+    if (paratextInstallDir) {
+        const configured = path.join(paratextInstallDir, "Terms", "Lists", TERMS_FILE);
+        if (!fs.existsSync(configured))
+            throw new BiblicalTermsNotFoundError([configured]);
+        return configured;
+    }
+    const found = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!found)
+        throw new BiblicalTermsNotFoundError(candidates);
+    return found;
+}
+// ---------- parsing ----------
+function decodeXml(value) {
+    return value
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, "\"")
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+// Lowercase and strip diacritics (incl. Greek accents and Hebrew points).
+function normalizeSearch(value) {
+    return value.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+function element(body, name) {
+    const match = body.match(new RegExp(`<${name}>([^<]*)</${name}>`));
+    return match ? decodeXml(match[1]).trim() : "";
+}
+function parseVerseRefs(body) {
+    const unique = new Map();
+    for (const match of body.matchAll(/<Verse>\s*(\d{9})\d{5}[^<]*<\/Verse>/g)) {
+        // BBBCCCVVV + 5-digit word position (dropped); rare suffixes like "{N:001}" ignored.
+        const digits = match[1];
+        if (unique.has(digits))
+            continue;
+        unique.set(digits, {
+            bookNumber: parseInt(digits.slice(0, 3), 10),
+            chapter: parseInt(digits.slice(3, 6), 10),
+            verse: parseInt(digits.slice(6, 9), 10)
+        });
+    }
+    return [...unique.values()].sort(compareVerseRefs);
+}
+function compareVerseRefs(a, b) {
+    return a.bookNumber - b.bookNumber || a.chapter - b.chapter || a.verse - b.verse;
+}
+function parseTerms(xml) {
+    const terms = [];
+    for (const match of xml.matchAll(/<Term\s+Id="([^"]*)"\s*>([\s\S]*?)<\/Term>/g)) {
+        const id = decodeXml(match[1]);
+        const body = match[2];
+        const strong = element(body, "Strong")
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        const transliteration = element(body, "Transliteration");
+        const definition = element(body, "Definition");
+        const gloss = element(body, "Gloss");
+        terms.push({
+            id,
+            strong,
+            transliteration,
+            category: element(body, "Category"),
+            language: element(body, "Language"),
+            definition,
+            gloss,
+            verses: parseVerseRefs(body),
+            searchText: [gloss, id, transliteration, definition].map(normalizeSearch)
+        });
+    }
+    return terms;
+}
+const termsCache = new Map();
+function loadTerms(termsPath) {
+    const mtimeMs = fs.statSync(termsPath).mtimeMs;
+    const cached = termsCache.get(termsPath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.value;
+    const terms = parseTerms(fs.readFileSync(termsPath, "utf8"));
+    // Ids in the file are not NFC-normalized; index by NFC so client-supplied Ids match.
+    const byId = new Map(terms.map((term) => [term.id.normalize("NFC"), term]));
+    const value = { terms, byId };
+    termsCache.set(termsPath, { mtimeMs, value });
+    return value;
+}
+// ---------- filtering ----------
+function toBookNumber(book) {
+    const code = book.toUpperCase();
+    const bookNumber = isBookCode(code) ? bookNumberFromCode(code) : undefined;
+    if (bookNumber === undefined)
+        throw new InvalidReferenceError(`Not a valid USFM book code: ${book}`);
+    return bookNumber;
+}
+// A span with get-scripture defaults, but unbounded ends (no USFM needed).
+function inSpan(ref, bookNumber, span) {
+    if (ref.bookNumber !== bookNumber)
+        return false;
+    if (span.startChapter === undefined)
+        return true;
+    const startChapter = span.startChapter;
+    const endChapter = span.endChapter ?? startChapter;
+    if (endChapter < startChapter) {
+        throw new InvalidReferenceError(`End chapter ${endChapter} is before start chapter ${startChapter}`);
+    }
+    const startVerse = span.startVerse ?? 1;
+    const endVerse = span.endVerse ?? Number.POSITIVE_INFINITY;
+    const afterStart = ref.chapter > startChapter || (ref.chapter === startChapter && ref.verse >= startVerse);
+    const beforeEnd = ref.chapter < endChapter || (ref.chapter === endChapter && ref.verse <= endVerse);
+    return afterStart && beforeEnd;
+}
+function formatRefs(verses) {
+    const parts = [];
+    let previousBook;
+    for (const ref of verses) {
+        const book = bookCodeFromNumber(ref.bookNumber);
+        if (!book)
+            continue;
+        const prefix = book === previousBook ? "" : `${book} `;
+        parts.push(`${prefix}${ref.chapter}:${ref.verse}`);
+        previousBook = book;
+    }
+    return parts.join("; ");
+}
+// ---------- project TermRenderings.xml ----------
+export class TermRenderingsNotFoundError extends Error {
+    constructor(projectId) {
+        super(`No TermRenderings.xml in project ${projectId}`);
+        this.name = "TermRenderingsNotFoundError";
+    }
+}
+const renderingsCache = new Map();
+// <Denial> is a BBBCCCVVV verse number with leading zeros dropped, e.g. 41001001 = MRK 1:1.
+function parseDenials(body) {
+    const unique = new Map();
+    for (const match of body.matchAll(/<Denial>\s*(\d+)\s*<\/Denial>/g)) {
+        const value = parseInt(match[1], 10);
+        unique.set(value, {
+            bookNumber: Math.floor(value / 1_000_000),
+            chapter: Math.floor(value / 1000) % 1000,
+            verse: value % 1000
+        });
+    }
+    return [...unique.values()].sort(compareVerseRefs);
+}
+// NFC term Id -> renderings and denials.
+function parseTermRenderings(xml) {
+    const renderings = new Map();
+    const termPattern = /<TermRendering\s+Id="([^"]*)"[^>]*?(?:\/>|>([\s\S]*?)<\/TermRendering>)/g;
+    for (const match of xml.matchAll(termPattern)) {
+        const id = decodeXml(match[1]).normalize("NFC");
+        const body = match[2] ?? "";
+        const value = body.match(/<Renderings>([^<]*)<\/Renderings>/);
+        const notes = body.match(/<Notes>([^<]*)<\/Notes>/);
+        renderings.set(id, {
+            renderings: value ? decodeXml(value[1]) : "",
+            denials: parseDenials(body),
+            notes: notes ? decodeXml(notes[1]).replace(/\r\n?/g, "\n") : ""
+        });
+    }
+    return renderings;
+}
+function loadTermRenderings(projectDir, projectId) {
+    const filePath = path.join(projectDir, "TermRenderings.xml");
+    if (!fs.existsSync(filePath))
+        throw new TermRenderingsNotFoundError(projectId);
+    const mtimeMs = fs.statSync(filePath).mtimeMs;
+    const cached = renderingsCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.value;
+    const value = parseTermRenderings(fs.readFileSync(filePath, "utf8"));
+    renderingsCache.set(filePath, { mtimeMs, value });
+    return value;
+}
+// ---------- public API ----------
+export function searchTerms(termsPath, search, book) {
+    const query = normalizeSearch(search.trim());
+    if (query.length === 0)
+        throw new InvalidReferenceError("Search string must not be empty");
+    const bookNumber = book === undefined ? undefined : toBookNumber(book);
+    const strongQuery = search.trim().toUpperCase();
+    return loadTerms(termsPath).terms
+        .filter((term) => term.searchText.some((text) => text.includes(query))
+        || term.strong.some((s) => s.toUpperCase() === strongQuery))
+        .filter((term) => bookNumber === undefined || term.verses.some((v) => v.bookNumber === bookNumber))
+        .map((term) => ({
+        id: term.id,
+        gloss: term.gloss,
+        transliteration: term.transliteration,
+        language: term.language,
+        category: term.category,
+        strong: term.strong,
+        refCount: term.verses.length
+    }));
+}
+export function getTermRefs(request) {
+    const term = loadTerms(request.termsPath).byId.get(request.id.trim().normalize("NFC"));
+    if (!term)
+        throw new TermNotFoundError(request.id);
+    const hasStructured = request.book !== undefined
+        || request.startChapter !== undefined
+        || request.startVerse !== undefined
+        || request.endChapter !== undefined
+        || request.endVerse !== undefined;
+    const hasRefs = request.refs !== undefined;
+    if (hasStructured && hasRefs) {
+        throw new InvalidReferenceError("Specify either refs or book/chapter/verse, not both");
+    }
+    let spans;
+    if (hasRefs) {
+        spans = parseRefs(request.refs ?? "");
+    }
+    else if (hasStructured) {
+        if (request.book === undefined)
+            throw new InvalidReferenceError("book is required with chapter/verse");
+        const { startChapter, startVerse, endChapter, endVerse } = request;
+        spans = [{ book: request.book, span: { startChapter, startVerse, endChapter, endVerse } }];
+    }
+    const filters = spans?.map(({ book, span }) => ({ bookNumber: toBookNumber(book), span }));
+    const verses = filters
+        ? term.verses.filter((ref) => filters.some((f) => inSpan(ref, f.bookNumber, f.span)))
+        : term.verses;
+    return formatRefs(verses);
+}
+// The project's renderings of a term, exactly as stored in TermRenderings.xml
+// ("*" is a wildcard, "||" separates alternatives), plus its denied verses as a refs string
+// and its notes.
+export function getTermRendering(projectsRoot, projectId, id) {
+    const projectDir = getProjectDir(projectsRoot, projectId);
+    const rendering = loadTermRenderings(projectDir, projectId).get(id.trim().normalize("NFC"));
+    if (rendering === undefined)
+        throw new TermNotFoundError(id);
+    return { renderings: rendering.renderings, denials: formatRefs(rendering.denials), notes: rendering.notes };
+}

package/dist/books.d.ts

@@ -0,0 +1,5 @@
+export declare const BOOK_CODES: readonly ["GEN", "EXO", "LEV", "NUM", "DEU", "JOS", "JDG", "RUT", "1SA", "2SA", "1KI", "2KI", "1CH", "2CH", "EZR", "NEH", "EST", "JOB", "PSA", "PRO", "ECC", "SNG", "ISA", "JER", "LAM", "EZK", "DAN", "HOS", "JOL", "AMO", "OBA", "JON", "MIC", "NAM", "HAB", "ZEP", "HAG", "ZEC", "MAL", "MAT", "MRK", "LUK", "JHN", "ACT", "ROM", "1CO", "2CO", "GAL", "EPH", "PHP", "COL", "1TH", "2TH", "1TI", "2TI", "TIT", "PHM", "HEB", "JAS", "1PE", "2PE", "1JN", "2JN", "3JN", "JUD", "REV", "TOB", "JDT", "ESG", "WIS", "SIR", "BAR", "LJE", "S3Y", "SUS", "BEL", "1MA", "2MA", "3MA", "4MA", "1ES", "2ES", "MAN", "PS2"];
+export type BookCode = (typeof BOOK_CODES)[number];
+export declare function isBookCode(value: string): value is BookCode;
+export declare function bookCodeFromNumber(bookNumber: number): BookCode | undefined;
+export declare function bookNumberFromCode(code: string): number | undefined;

package/dist/books.js

@@ -0,0 +1,24 @@
+export const BOOK_CODES = [
+    "GEN", "EXO", "LEV", "NUM", "DEU", "JOS", "JDG", "RUT", "1SA", "2SA",
+    "1KI", "2KI", "1CH", "2CH", "EZR", "NEH", "EST", "JOB", "PSA", "PRO",
+    "ECC", "SNG", "ISA", "JER", "LAM", "EZK", "DAN", "HOS", "JOL", "AMO",
+    "OBA", "JON", "MIC", "NAM", "HAB", "ZEP", "HAG", "ZEC", "MAL",
+    "MAT", "MRK", "LUK", "JHN", "ACT", "ROM", "1CO", "2CO", "GAL", "EPH",
+    "PHP", "COL", "1TH", "2TH", "1TI", "2TI", "TIT", "PHM", "HEB", "JAS",
+    "1PE", "2PE", "1JN", "2JN", "3JN", "JUD", "REV",
+    "TOB", "JDT", "ESG", "WIS", "SIR", "BAR", "LJE", "S3Y", "SUS", "BEL",
+    "1MA", "2MA", "3MA", "4MA", "1ES", "2ES", "MAN", "PS2"
+];
+const BOOK_CODE_SET = new Set(BOOK_CODES);
+export function isBookCode(value) {
+    return BOOK_CODE_SET.has(value.toUpperCase());
+}
+// BOOK_CODES is in Paratext canon order, so a 1-based Paratext book number
+// (e.g. 040 = MAT, 077 = 1MA) indexes it directly.
+export function bookCodeFromNumber(bookNumber) {
+    return BOOK_CODES[bookNumber - 1];
+}
+export function bookNumberFromCode(code) {
+    const index = BOOK_CODES.indexOf(code.toUpperCase());
+    return index < 0 ? undefined : index + 1;
+}

package/dist/core.d.ts

@@ -0,0 +1,6 @@
+export * from "./biblicalTerms.js";
+export * from "./books.js";
+export * from "./discovery.js";
+export * from "./interlinear.js";
+export * from "./scripture.js";
+export * from "./usfmBook.js";

package/dist/core.js

@@ -0,0 +1,7 @@
+// Entry point of the @milesnl/ptx-core library (see packages/core).
+export * from "./biblicalTerms.js";
+export * from "./books.js";
+export * from "./discovery.js";
+export * from "./interlinear.js";
+export * from "./scripture.js";
+export * from "./usfmBook.js";

package/dist/discovery.d.ts

@@ -0,0 +1,9 @@
+export declare class ProjectsRootNotFoundError extends Error {
+    constructor(root: string);
+}
+export declare class ProjectNotFoundError extends Error {
+    constructor(projectId: string);
+}
+export declare function resolveProjectsRoot(cliArg?: string): string;
+export declare function listProjects(projectsRoot: string): string[];
+export declare function getProjectDir(projectsRoot: string, projectId: string): string;

package/dist/discovery.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+const WINDOWS_DEFAULT_PROJECTS_DIR = "C:\\My Paratext 9 Projects";
+export class ProjectsRootNotFoundError extends Error {
+    constructor(root) {
+        super(`Paratext projects folder not found: ${root}`);
+        this.name = "ProjectsRootNotFoundError";
+    }
+}
+export class ProjectNotFoundError extends Error {
+    constructor(projectId) {
+        super(`Paratext project not found: ${projectId}`);
+        this.name = "ProjectNotFoundError";
+    }
+}
+export function resolveProjectsRoot(cliArg) {
+    const root = cliArg ?? WINDOWS_DEFAULT_PROJECTS_DIR;
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        throw new ProjectsRootNotFoundError(root);
+    }
+    return root;
+}
+export function listProjects(projectsRoot) {
+    return fs
+        .readdirSync(projectsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .filter((entry) => fs.existsSync(path.join(projectsRoot, entry.name, "Settings.xml")))
+        .map((entry) => entry.name)
+        .sort();
+}
+export function getProjectDir(projectsRoot, projectId) {
+    const dir = path.join(projectsRoot, projectId);
+    if (!fs.existsSync(dir) || !fs.existsSync(path.join(dir, "Settings.xml"))) {
+        throw new ProjectNotFoundError(projectId);
+    }
+    return dir;
+}

package/dist/interlinear.d.ts

@@ -0,0 +1,45 @@
+export declare class InterlinearNotFoundError extends Error {
+    constructor(message: string);
+}
+export type GlossSource = "a" | "g" | "l" | "-";
+export type WordGloss = [string, string] | [string, string, GlossSource];
+export interface InterlinearVerse {
+    ref: string;
+    words: WordGloss[];
+}
+export interface InterlinearRequest {
+    projectsRoot: string;
+    project: string;
+    language: string;
+    book?: string;
+    startChapter?: number;
+    startVerse?: number;
+    endChapter?: number;
+    endVerse?: number;
+    refs?: string;
+    allowPartial?: boolean;
+    showSource?: boolean;
+}
+export interface InterlinearResult {
+    verses: InterlinearVerse[];
+    missing: string[];
+}
+export interface Span {
+    startChapter?: number;
+    startVerse?: number;
+    endChapter?: number;
+    endVerse?: number;
+}
+export interface BookSpan {
+    book: string;
+    span: Span;
+}
+interface Token {
+    index: number;
+    text: string;
+}
+export declare function tokenize(segment: string): Token[];
+export declare function parseRefs(refs: string): BookSpan[];
+export declare function listInterlinearLanguages(projectsRoot: string, projectId: string, book?: string): string[];
+export declare function getInterlinear(request: InterlinearRequest): InterlinearResult;
+export {};

package/dist/interlinear.js

@@ -0,0 +1,485 @@
+import fs from "node:fs";
+import path from "node:path";
+import { bookNumberFromCode, isBookCode } from "./books.js";
+import { getProjectDir } from "./discovery.js";
+import { BookNotFoundError, InvalidReferenceError, loadBook, VerseNotFoundError } from "./scripture.js";
+import { indexProjectBooks } from "./usfmBook.js";
+// Interlinear data layout is documented in src/md/it/it_spec.md; best-effort glossing in it_update1.md.
+export class InterlinearNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InterlinearNotFoundError";
+    }
+}
+const NO_GLOSS = "_";
+const LANGUAGE_PATTERN = /^[A-Za-z0-9_-]+$/;
+const INTERLINEAR_DIR_PREFIX = "Interlinear_";
+// ---------- small helpers ----------
+function decodeXml(value) {
+    return value
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, "\"")
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+function attr(tag, name) {
+    const match = tag.match(new RegExp(`\\b${name}="([^"]*)"`));
+    return match ? decodeXml(match[1]) : undefined;
+}
+function normalizeForm(value) {
+    return value.normalize("NFC").toLowerCase();
+}
+function parseVerseRange(label) {
+    const match = label.match(/^(\d+)(?:-(\d+))?$/);
+    if (!match)
+        return undefined;
+    const start = parseInt(match[1], 10);
+    const end = match[2] ? parseInt(match[2], 10) : start;
+    return { start, end };
+}
+// Cache parsed files, keyed by path; re-parse when the file changes on disk.
+function cachedByMtime(cache, filePath, parse) {
+    const mtimeMs = fs.statSync(filePath).mtimeMs;
+    const cached = cache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.value;
+    const value = parse();
+    cache.set(filePath, { mtimeMs, value });
+    return value;
+}
+// ---------- lexicon.xml ----------
+const lexiconCache = new Map();
+function parseLexicon(xml) {
+    const byLexemeSense = new Map();
+    const senseGloss = new Map();
+    const senseCount = new Map();
+    const wordForms = new Map();
+    const otherForms = new Map();
+    const itemPattern = /<Lexeme\b([^>]*)\/>([\s\S]*?)<\/item>/g;
+    const sensePattern = /<Sense\b([^>]*)>\s*<Gloss\b([^>]*?)(?:\/>|>([^<]*)<\/Gloss>)/g;
+    for (const item of xml.matchAll(itemPattern)) {
+        const type = attr(item[1], "Type");
+        const form = attr(item[1], "Form");
+        if (!type || form === undefined)
+            continue;
+        const forms = type === "Word" ? wordForms : otherForms;
+        const formKey = normalizeForm(form);
+        for (const sense of item[2].matchAll(sensePattern)) {
+            const senseId = attr(sense[1], "Id");
+            if (!senseId)
+                continue;
+            const gloss = decodeXml(sense[3] ?? "");
+            byLexemeSense.set(`${type}:${form}#${senseId}`, gloss);
+            senseGloss.set(senseId, gloss);
+            senseCount.set(senseId, (senseCount.get(senseId) ?? 0) + 1);
+            const language = attr(sense[2], "Language");
+            if (!language || !gloss.trim())
+                continue;
+            const firstByLanguage = forms.get(formKey) ?? new Map();
+            if (!firstByLanguage.has(language))
+                firstByLanguage.set(language, gloss);
+            forms.set(formKey, firstByLanguage);
+        }
+    }
+    const byForm = new Map(otherForms);
+    for (const [formKey, firstByLanguage] of wordForms) {
+        byForm.set(formKey, new Map([...(otherForms.get(formKey) ?? []), ...firstByLanguage]));
+    }
+    const bySense = new Map();
+    for (const [senseId, gloss] of senseGloss) {
+        if (senseCount.get(senseId) === 1)
+            bySense.set(senseId, gloss);
+    }
+    return { byLexemeSense, bySense, byForm };
+}
+function loadLexicon(projectDir) {
+    const filePath = path.join(projectDir, "lexicon.xml");
+    if (!fs.existsSync(filePath))
+        return { byLexemeSense: new Map(), bySense: new Map(), byForm: new Map() };
+    return cachedByMtime(lexiconCache, filePath, () => parseLexicon(fs.readFileSync(filePath, "utf8")));
+}
+function lookupGloss(lexicon, lexeme) {
+    if (!lexeme.glossId)
+        return null;
+    return lexicon.byLexemeSense.get(`${lexeme.type}:${lexeme.form}#${lexeme.glossId}`)
+        ?? lexicon.bySense.get(lexeme.glossId)
+        ?? null;
+}
+// ---------- Interlinear_<lang>_<BOOK>.xml ----------
+const interlinearCache = new Map();
+function parseInterlinear(xml) {
+    const items = new Map();
+    const itemPattern = /<item>\s*<string>([^<]*)<\/string>([\s\S]*?)<\/item>/g;
+    const clusterPattern = /<Cluster>([\s\S]*?)<\/Cluster>/g;
+    const lexemePattern = /<Lexeme\b([^>]*)\/>/g;
+    for (const item of xml.matchAll(itemPattern)) {
+        // "ROM 1:1" or "ROM 1:9-10"
+        const refMatch = decodeXml(item[1]).trim().match(/^\S+\s+(\d+):(\S+)$/);
+        if (!refMatch)
+            continue;
+        const chapter = parseInt(refMatch[1], 10);
+        const label = refMatch[2];
+        const range = parseVerseRange(label);
+        if (!range)
+            continue;
+        const clusters = [];
+        for (const cluster of item[2].matchAll(clusterPattern)) {
+            const body = cluster[1];
+            const rangeTag = body.match(/<Range\b([^>]*)\/>/);
+            if (!rangeTag)
+                continue;
+            const lexemes = [];
+            for (const lexeme of body.matchAll(lexemePattern)) {
+                const id = attr(lexeme[1], "Id") ?? "";
+                const colon = id.indexOf(":");
+                if (colon < 0)
+                    continue;
+                lexemes.push({
+                    type: id.slice(0, colon),
+                    form: id.slice(colon + 1),
+                    glossId: attr(lexeme[1], "GlossId")
+                });
+            }
+            clusters.push({
+                index: parseInt(attr(rangeTag[1], "Index") ?? "0", 10),
+                length: parseInt(attr(rangeTag[1], "Length") ?? "0", 10),
+                lexemes,
+                excluded: /<Excluded>\s*true\s*<\/Excluded>/.test(body)
+            });
+        }
+        const parsed = { chapter, label, ...range, clusters };
+        items.set(`${chapter}:${label}`, parsed);
+    }
+    return { items };
+}
+function interlinearDir(projectDir, language) {
+    return path.join(projectDir, `${INTERLINEAR_DIR_PREFIX}${language}`);
+}
+function interlinearFile(projectDir, language, book) {
+    return path.join(interlinearDir(projectDir, language), `${INTERLINEAR_DIR_PREFIX}${language}_${book}.xml`);
+}
+function loadInterlinearFile(filePath) {
+    return cachedByMtime(interlinearCache, filePath, () => parseInterlinear(fs.readFileSync(filePath, "utf8")));
+}
+// Interlinear data for a book, or undefined if the language has no file for it.
+function loadInterlinear(projectDir, language, book) {
+    const filePath = interlinearFile(projectDir, language, book);
+    return fs.existsSync(filePath) ? loadInterlinearFile(filePath) : undefined;
+}
+const corpusCache = new Map();
+function interlinearFiles(dir, language) {
+    const prefix = `${INTERLINEAR_DIR_PREFIX}${language}_`;
+    const bookOf = (file) => file.slice(prefix.length, -".xml".length).toUpperCase();
+    const order = (file) => bookNumberFromCode(bookOf(file)) ?? Number.MAX_SAFE_INTEGER;
+    return fs
+        .readdirSync(dir)
+        .filter((file) => file.startsWith(prefix) && file.toLowerCase().endsWith(".xml"))
+        // Canon order so ties resolve to the first gloss seen in canon order.
+        .sort((a, b) => order(a) - order(b) || a.localeCompare(b))
+        .map((file) => path.join(dir, file));
+}
+// Most common gloss for each word form across all books of a gloss language (it_update1.md).
+function loadCorpus(dir, language, lexicon) {
+    const files = interlinearFiles(dir, language);
+    const signature = files.map((file) => `${file}:${fs.statSync(file).mtimeMs}`).join("|");
+    const cached = corpusCache.get(dir);
+    if (cached && cached.signature === signature && cached.lexicon === lexicon)
+        return cached.glosses;
+    // form -> gloss -> count; Map insertion order records first-seen order for ties.
+    const counts = new Map();
+    for (const file of files) {
+        for (const item of loadInterlinearFile(file).items.values()) {
+            for (const cluster of item.clusters) {
+                if (cluster.excluded || !isWordCluster(cluster))
+                    continue;
+                const lexeme = cluster.lexemes[0];
+                const gloss = lookupGloss(lexicon, lexeme);
+                if (!gloss)
+                    continue;
+                const form = normalizeForm(lexeme.form);
+                const formCounts = counts.get(form) ?? new Map();
+                formCounts.set(gloss, (formCounts.get(gloss) ?? 0) + 1);
+                counts.set(form, formCounts);
+            }
+        }
+    }
+    const glosses = new Map();
+    for (const [form, formCounts] of counts) {
+        let best;
+        let bestCount = 0;
+        for (const [gloss, count] of formCounts) {
+            if (count > bestCount) {
+                best = gloss;
+                bestCount = count;
+            }
+        }
+        if (best !== undefined)
+            glosses.set(form, best);
+    }
+    corpusCache.set(dir, { signature, lexicon, glosses });
+    return glosses;
+}
+// ---------- raw USFM verse segments ----------
+const segmentCache = new Map();
+// Split raw USFM (LF line endings) into segments keyed "C:label". Segment "C:V" starts at
+// its \v marker; "C:0" starts at \c C (or file start for chapter 1). Segments end at the
+// next \c or \v marker. Interlinear Range offsets are relative to these segments.
+function splitSegments(usfm) {
+    const segments = new Map();
+    let chapter = 1;
+    let key = "1:0";
+    let segmentStart = 0;
+    for (const marker of usfm.matchAll(/\\(c|v)\s+(\d+(?:-\d+)?)/g)) {
+        const markerStart = marker.index ?? 0;
+        if (marker[1] === "c") {
+            const nextChapter = parseInt(marker[2], 10);
+            if (nextChapter === 1 && key === "1:0")
+                continue;
+            segments.set(key, usfm.slice(segmentStart, markerStart));
+            chapter = nextChapter;
+            key = `${chapter}:0`;
+        }
+        else {
+            segments.set(key, usfm.slice(segmentStart, markerStart));
+            key = `${chapter}:${marker[2]}`;
+        }
+        segmentStart = markerStart;
+    }
+    segments.set(key, usfm.slice(segmentStart));
+    return segments;
+}
+function loadSegments(projectDir, projectId, book) {
+    const filePath = indexProjectBooks(projectDir).get(book);
+    if (!filePath)
+        throw new BookNotFoundError(projectId, book);
+    return cachedByMtime(segmentCache, filePath, () => splitSegments(fs.readFileSync(filePath, "utf8").replace(/\r\n?/g, "\n")));
+}
+// ---------- verse -> [word, gloss] pairs (it_update1.md) ----------
+function isWordCluster(cluster) {
+    return cluster.lexemes.length === 1 && cluster.lexemes[0].type === "Word";
+}
+// USFM content that is not verse text. Replaced by spaces so offsets stay aligned with the segment.
+const NON_TEXT_PATTERNS = [
+    /\\(f|fe|x)\s[\s\S]*?\\\1\*/g, // footnotes, endnotes, cross-refs
+    /(^|\n)\\(s\d*|ms\d*|mr|r|sr|d)(?=\s)[^\n]*/g, // headings, Psalm titles
+    /\|[^\\\n]*/g, // word attributes: \w word|attrs\w*
+    /\\(c|v)\s+\S+/g, // chapter/verse numbers
+    /\\\+?[A-Za-z0-9]+\*?/g // other markers
+];
+// Split a segment into words: runs of Unicode letters and combining marks in verse text.
+export function tokenize(segment) {
+    let text = segment;
+    for (const pattern of NON_TEXT_PATTERNS) {
+        text = text.replace(pattern, (match) => " ".repeat(match.length));
+    }
+    return [...text.matchAll(/[\p{L}\p{M}]+/gu)].map((m) => ({ index: m.index ?? 0, text: m[0] }));
+}
+function verseWords(segment, item, lexicon, corpus, language, showSource) {
+    // Word clusters by exact range; others (stale, Stem/affix, Phrase) don't apply to a token.
+    const approved = new Map();
+    for (const cluster of item?.clusters ?? []) {
+        if (cluster.excluded || !isWordCluster(cluster))
+            continue;
+        const key = `${cluster.index}:${cluster.length}`;
+        approved.set(key, [...(approved.get(key) ?? []), cluster]);
+    }
+    return tokenize(segment).map((token) => {
+        const form = normalizeForm(token.text);
+        let gloss = null;
+        let source = "-";
+        for (const cluster of approved.get(`${token.index}:${token.text.length}`) ?? []) {
+            if (normalizeForm(cluster.lexemes[0].form) !== form)
+                continue;
+            gloss = lookupGloss(lexicon, cluster.lexemes[0]) || null;
+            if (gloss) {
+                source = "a";
+                break;
+            }
+        }
+        if (!gloss) {
+            gloss = corpus.get(form) ?? null;
+            if (gloss)
+                source = "g";
+        }
+        if (!gloss) {
+            gloss = lexicon.byForm.get(form)?.get(language) ?? null;
+            if (gloss)
+                source = "l";
+        }
+        const word = token.text;
+        return showSource ? [word, gloss ?? NO_GLOSS, source] : [word, gloss ?? NO_GLOSS];
+    });
+}
+// ---------- reference handling ----------
+const REF_PATTERN = /^(?:([A-Za-z0-9]{3})\s+)?(\d+)\s*(?::\s*(\d+)\s*(?:-\s*(\d+)\s*(?::\s*(\d+))?)?)?$/;
+export function parseRefs(refs) {
+    const parts = refs.split(";").map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0)
+        throw new InvalidReferenceError("No verse references given");
+    const result = [];
+    let book;
+    for (const part of parts) {
+        const match = part.match(REF_PATTERN);
+        if (!match)
+            throw new InvalidReferenceError(`Unparseable reference: ${part}`);
+        const [, bookPart, c, v, x, y] = match;
+        if (bookPart) {
+            if (!isBookCode(bookPart))
+                throw new InvalidReferenceError(`Not a valid USFM book code: ${bookPart}`);
+            book = bookPart.toUpperCase();
+        }
+        if (!book)
+            throw new InvalidReferenceError(`First reference must include a book: ${part}`);
+        const chapter = parseInt(c, 10);
+        let span;
+        if (v === undefined) {
+            span = { startChapter: chapter };
+        }
+        else if (x === undefined) {
+            span = { startChapter: chapter, startVerse: parseInt(v, 10), endVerse: parseInt(v, 10) };
+        }
+        else if (y === undefined) {
+            span = { startChapter: chapter, startVerse: parseInt(v, 10), endVerse: parseInt(x, 10) };
+        }
+        else {
+            span = { startChapter: chapter, startVerse: parseInt(v, 10), endChapter: parseInt(x, 10), endVerse: parseInt(y, 10) };
+        }
+        result.push({ book, span });
+    }
+    return result;
+}
+function maxVerseNumber(verses) {
+    return verses.reduce((max, v) => Math.max(max, v.end), 0);
+}
+// Expand a span to verse targets with the same defaults as get-scripture.
+function expandSpan(parsed, book, span, onMissing) {
+    const chapters = [...parsed.chapters.keys()].sort((a, b) => a - b);
+    const startChapter = span.startChapter ?? chapters[0] ?? 1;
+    const endChapter = span.endChapter ?? span.startChapter ?? chapters[chapters.length - 1] ?? startChapter;
+    if (endChapter < startChapter) {
+        throw new InvalidReferenceError(`End chapter ${endChapter} is before start chapter ${startChapter}`);
+    }
+    const targets = [];
+    for (let chapter = startChapter; chapter <= endChapter; chapter++) {
+        const verses = parsed.chapters.get(chapter);
+        if (!verses) {
+            onMissing(`${book} ${chapter}`);
+            continue;
+        }
+        const verseStart = chapter === startChapter && span.startVerse ? span.startVerse : 1;
+        const verseEnd = chapter === endChapter && span.endVerse ? span.endVerse : maxVerseNumber(verses);
+        for (let verse = verseStart; verse <= verseEnd; verse++) {
+            const entry = verses.find((v) => verse >= v.start && verse <= v.end);
+            if (!entry) {
+                onMissing(`${book} ${chapter}:${verse}`);
+                continue;
+            }
+            targets.push({ book, chapter, label: entry.label, start: entry.start, end: entry.end });
+        }
+    }
+    return targets;
+}
+// ---------- public API ----------
+export function listInterlinearLanguages(projectsRoot, projectId, book) {
+    const projectDir = getProjectDir(projectsRoot, projectId);
+    const bookCode = book?.toUpperCase();
+    if (bookCode !== undefined && !isBookCode(bookCode)) {
+        throw new InvalidReferenceError(`Not a valid USFM book code: ${book}`);
+    }
+    return fs
+        .readdirSync(projectDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith(INTERLINEAR_DIR_PREFIX))
+        .map((entry) => entry.name.slice(INTERLINEAR_DIR_PREFIX.length))
+        .filter((language) => language.length > 0)
+        .filter((language) => !bookCode || fs.existsSync(interlinearFile(projectDir, language, bookCode)))
+        .sort();
+}
+export function getInterlinear(request) {
+    const allowPartial = request.allowPartial ?? false;
+    const missing = [];
+    const onMissing = (ref) => {
+        if (!allowPartial)
+            throw new VerseNotFoundError(ref);
+        missing.push(ref);
+    };
+    if (!LANGUAGE_PATTERN.test(request.language)) {
+        throw new InvalidReferenceError(`Not a valid language code: ${request.language}`);
+    }
+    const hasStructured = request.book !== undefined
+        || request.startChapter !== undefined
+        || request.startVerse !== undefined
+        || request.endChapter !== undefined
+        || request.endVerse !== undefined;
+    const hasRefs = request.refs !== undefined;
+    if (hasStructured && hasRefs) {
+        throw new InvalidReferenceError("Specify either refs or book/chapter/verse, not both");
+    }
+    if (!hasStructured && !hasRefs) {
+        throw new InvalidReferenceError("Specify either refs or book");
+    }
+    let bookSpans;
+    if (hasRefs) {
+        bookSpans = parseRefs(request.refs ?? "");
+    }
+    else {
+        const book = (request.book ?? "").toUpperCase();
+        if (!isBookCode(book))
+            throw new InvalidReferenceError(`Not a valid USFM book code: ${request.book ?? ""}`);
+        const { startChapter, startVerse, endChapter, endVerse } = request;
+        bookSpans = [{ book, span: { startChapter, startVerse, endChapter, endVerse } }];
+    }
+    const projectDir = getProjectDir(request.projectsRoot, request.project);
+    const lexicon = loadLexicon(projectDir);
+    const showSource = request.showSource ?? false;
+    let corpus = new Map();
+    const languageDir = interlinearDir(projectDir, request.language);
+    const hasLanguage = fs.existsSync(languageDir);
+    if (hasLanguage) {
+        corpus = loadCorpus(languageDir, request.language, lexicon);
+    }
+    else {
+        const err = new InterlinearNotFoundError(`No interlinear data for language ${request.language} in project ${request.project}`);
+        if (!allowPartial)
+            throw err;
+        missing.push(err.message);
+    }
+    // Per-book text, loaded lazily. null = unavailable (only when allowPartial).
+    const books = new Map();
+    const verses = [];
+    const seen = new Set();
+    for (const { book, span } of bookSpans) {
+        if (!books.has(book)) {
+            try {
+                books.set(book, loadBook(projectDir, request.project, book));
+            }
+            catch (err) {
+                // Structured form: a missing book is always an error (spec §7).
+                if (!(err instanceof BookNotFoundError) || !allowPartial || !hasRefs)
+                    throw err;
+                missing.push(err.message);
+                books.set(book, null);
+            }
+        }
+        const parsed = books.get(book);
+        if (!parsed)
+            continue;
+        // No interlinear file for this book is fine: all words are guessed from other books.
+        const interlinear = hasLanguage ? loadInterlinear(projectDir, request.language, book) : undefined;
+        const segments = loadSegments(projectDir, request.project, book);
+        for (const target of expandSpan(parsed, book, span, onMissing)) {
+            const ref = `${book} ${target.chapter}:${target.label}`;
+            if (seen.has(ref))
+                continue;
+            seen.add(ref);
+            // Range offsets are relative to the item's own segment, so only use an item whose
+            // verse label matches the text's; otherwise all words are guessed.
+            const item = interlinear?.items.get(`${target.chapter}:${target.label}`);
+            const segment = segments.get(`${target.chapter}:${target.label}`) ?? "";
+            verses.push({ ref, words: verseWords(segment, item, lexicon, corpus, request.language, showSource) });
+        }
+    }
+    return { verses, missing };
+}

package/dist/scripture.d.ts

@@ -0,0 +1,28 @@
+import { ParsedBook } from "./usfmBook.js";
+export declare class InvalidReferenceError extends Error {
+    constructor(message: string);
+}
+export declare class BookNotFoundError extends Error {
+    constructor(projectId: string, book: string);
+}
+export declare class VerseNotFoundError extends Error {
+    constructor(ref: string);
+}
+export interface ScriptureRequest {
+    projectsRoot: string;
+    projects: string[];
+    book: string;
+    startChapter?: number;
+    startVerse?: number;
+    endChapter?: number;
+    endVerse?: number;
+    allowPartial?: boolean;
+}
+export interface ScriptureResult {
+    text: string;
+    missing: string[];
+}
+export declare function loadBook(projectDir: string, projectId: string, book: string): ParsedBook;
+export declare function getScripture(request: ScriptureRequest): ScriptureResult;
+export declare function listAvailableProjects(projectsRoot: string): string[];
+export declare function listAvailableBooks(projectsRoot: string, projectId: string): string[];

package/dist/scripture.js

@@ -0,0 +1,126 @@
+import { BOOK_CODES, isBookCode } from "./books.js";
+import { getProjectDir, listProjects, ProjectNotFoundError } from "./discovery.js";
+import { indexProjectBooks, parseBookFile } from "./usfmBook.js";
+export class InvalidReferenceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidReferenceError";
+    }
+}
+export class BookNotFoundError extends Error {
+    constructor(projectId, book) {
+        super(`Book ${book} not found in project ${projectId}`);
+        this.name = "BookNotFoundError";
+    }
+}
+export class VerseNotFoundError extends Error {
+    constructor(ref) {
+        super(`Verse not found: ${ref}`);
+        this.name = "VerseNotFoundError";
+    }
+}
+const bookCache = new Map();
+export function loadBook(projectDir, projectId, book) {
+    const cacheKey = `${projectDir}::${book}`;
+    const cached = bookCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const index = indexProjectBooks(projectDir);
+    const filePath = index.get(book);
+    if (!filePath)
+        throw new BookNotFoundError(projectId, book);
+    const parsed = parseBookFile(filePath);
+    bookCache.set(cacheKey, parsed);
+    return parsed;
+}
+function maxVerseNumber(chapterVerses) {
+    if (!chapterVerses || chapterVerses.length === 0)
+        return 0;
+    return Math.max(...chapterVerses.map((v) => v.end));
+}
+export function getScripture(request) {
+    const book = request.book.toUpperCase();
+    if (!isBookCode(book)) {
+        throw new InvalidReferenceError(`Not a valid USFM book code: ${request.book}`);
+    }
+    if (request.projects.length === 0) {
+        throw new InvalidReferenceError("At least one project must be specified");
+    }
+    const allowPartial = request.allowPartial ?? false;
+    const missing = [];
+    const parsedByProject = new Map();
+    for (const projectId of request.projects) {
+        try {
+            const projectDir = getProjectDir(request.projectsRoot, projectId);
+            const parsed = loadBook(projectDir, projectId, book);
+            parsedByProject.set(projectId, parsed);
+        }
+        catch (err) {
+            if (err instanceof ProjectNotFoundError || err instanceof BookNotFoundError) {
+                if (!allowPartial)
+                    throw err;
+                missing.push(err.message);
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (parsedByProject.size === 0) {
+        throw new VerseNotFoundError(`${book} in project(s) ${request.projects.join(", ")}`);
+    }
+    // Union of chapter numbers across resolved projects, used when the caller
+    // doesn't pin down an explicit chapter/verse range.
+    const allChapterNumbers = new Set();
+    for (const parsed of parsedByProject.values()) {
+        for (const chapterNum of parsed.chapters.keys())
+            allChapterNumbers.add(chapterNum);
+    }
+    const sortedChapters = [...allChapterNumbers].sort((a, b) => a - b);
+    const startChapter = request.startChapter ?? sortedChapters[0] ?? 1;
+    const endChapter = request.endChapter ?? request.startChapter ?? sortedChapters[sortedChapters.length - 1] ?? startChapter;
+    const multiProject = request.projects.length > 1;
+    const blocks = [];
+    for (let chapter = startChapter; chapter <= endChapter; chapter++) {
+        const isFirstChapter = chapter === startChapter;
+        const isLastChapter = chapter === endChapter;
+        const chapterVerseUnion = maxVerseNumber([...parsedByProject.values()].flatMap((p) => p.chapters.get(chapter) ?? []));
+        const verseStart = isFirstChapter && request.startVerse ? request.startVerse : 1;
+        const verseEnd = isLastChapter && request.endVerse ? request.endVerse : chapterVerseUnion;
+        const lastLabelByProject = new Map();
+        for (let verse = verseStart; verse <= verseEnd; verse++) {
+            const groupLines = [];
+            for (const projectId of request.projects) {
+                const parsed = parsedByProject.get(projectId);
+                const ref = `${projectId} ${book} ${chapter}:${verse}`;
+                if (!parsed)
+                    continue; // already recorded as missing above
+                const verses = parsed.chapters.get(chapter) ?? [];
+                const entry = verses.find((v) => verse >= v.start && verse <= v.end);
+                if (!entry) {
+                    if (allowPartial) {
+                        missing.push(ref);
+                        continue;
+                    }
+                    throw new VerseNotFoundError(ref);
+                }
+                if (lastLabelByProject.get(projectId) === entry.label)
+                    continue;
+                lastLabelByProject.set(projectId, entry.label);
+                const prefix = multiProject ? `${projectId} ` : "";
+                groupLines.push(`${prefix}${book} ${chapter}:${entry.label} ${entry.text}`);
+            }
+            if (groupLines.length > 0)
+                blocks.push(groupLines.join("\n"));
+        }
+    }
+    const separator = multiProject ? "\n\n" : "\n";
+    return { text: blocks.join(separator), missing };
+}
+export function listAvailableProjects(projectsRoot) {
+    return listProjects(projectsRoot);
+}
+export function listAvailableBooks(projectsRoot, projectId) {
+    const projectDir = getProjectDir(projectsRoot, projectId);
+    const present = indexProjectBooks(projectDir);
+    return BOOK_CODES.filter((code) => present.has(code));
+}

package/dist/usfmBook.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedVerse {
+    start: number;
+    end: number;
+    label: string;
+    text: string;
+}
+export interface ParsedBook {
+    code: string;
+    chapters: Map<number, ParsedVerse[]>;
+}
+export declare function bookCodeFromFile(filePath: string): string | undefined;
+export declare function indexProjectBooks(projectDir: string): Map<string, string>;
+export declare function parseBookFile(filePath: string): ParsedBook;

package/dist/usfmBook.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+// usfm-js has no type definitions; consume it as untyped JS.
+// @ts-expect-error - no types published for usfm-js
+import usfm from "usfm-js";
+function collectText(nodes) {
+    if (!nodes)
+        return "";
+    let out = "";
+    for (const node of nodes) {
+        if (!node)
+            continue;
+        if (node.type === "footnote" || node.tag === "f")
+            continue;
+        if (typeof node.text === "string") {
+            out += node.text;
+        }
+        if (Array.isArray(node.children)) {
+            out += collectText(node.children);
+        }
+    }
+    return out;
+}
+function normalizeText(raw) {
+    return raw.replace(/\s+/g, " ").trim();
+}
+function parseVerseLabel(label) {
+    const [startStr, endStr] = label.split("-");
+    const start = parseInt(startStr, 10);
+    const end = endStr ? parseInt(endStr, 10) : start;
+    return { start, end };
+}
+export function bookCodeFromFile(filePath) {
+    const contents = fs.readFileSync(filePath, "utf8");
+    const match = contents.match(/\\id\s+([A-Za-z0-9]{3})/);
+    return match ? match[1].toUpperCase() : undefined;
+}
+export function indexProjectBooks(projectDir) {
+    const index = new Map();
+    const files = fs.readdirSync(projectDir).filter((f) => f.toUpperCase().endsWith(".SFM"));
+    for (const file of files) {
+        const filePath = path.join(projectDir, file);
+        const code = bookCodeFromFile(filePath);
+        if (code)
+            index.set(code, filePath);
+    }
+    return index;
+}
+export function parseBookFile(filePath) {
+    const contents = fs.readFileSync(filePath, "utf8");
+    const json = usfm.toJSON(contents);
+    const idHeader = json.headers.find((h) => h.tag === "id");
+    const code = (idHeader?.content ?? "").trim().split(/\s+/)[0]?.toUpperCase() ?? "";
+    const chapters = new Map();
+    for (const [chapterKey, verses] of Object.entries(json.chapters)) {
+        if (chapterKey === "front")
+            continue;
+        const chapterNum = parseInt(chapterKey, 10);
+        const parsedVerses = [];
+        for (const [verseKey, verseData] of Object.entries(verses)) {
+            if (verseKey === "front")
+                continue;
+            const { start, end } = parseVerseLabel(verseKey);
+            const text = normalizeText(collectText(verseData.verseObjects));
+            if (!text)
+                continue;
+            parsedVerses.push({ start, end, label: verseKey, text });
+        }
+        parsedVerses.sort((a, b) => a.start - b.start);
+        chapters.set(chapterNum, parsedVerses);
+    }
+    return { code, chapters };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@milesnl/ptx-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Library for reading Paratext project scripture, interlinear and Biblical Terms data",
+  "type": "module",
+  "main": "dist/core.js",
+  "types": "dist/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p .",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nathan22Miles/PtxMCP.git",
+    "directory": "packages/core"
+  },
+  "keywords": ["paratext", "bible", "usfm", "interlinear"],
+  "author": "Nathan Miles",
+  "license": "ISC",
+  "dependencies": {
+    "usfm-js": "^3.5.0"
+  }
+}