rv-bible-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import chalk from 'chalk';
+import clipboard from 'clipboardy';
+import { parseRefList, resolveBook } from './parser.js';
+import { getVersesByRef, getSectionHeaders, getFootnotesForChapter, getFootnotesForVerses, getFootnote, getVerse, getBookInfo, getAllBooks, isInConcordance, getTopicVerses, searchFTS, } from './db.js';
+import { renderVerses, renderVerseInline, renderFootnoteBlock, renderNoteDisplay, renderNoteDisplayAll, stripMarkers, highlightTerms, } from './format.js';
+import { getLastRead, saveLastRead } from './state.js';
+// Strip ANSI escape codes — cleans rendered output before copying to clipboard
+function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+program
+    .name('rv')
+    .description('Recovery Version Bible CLI')
+    .version('0.1.0')
+    .enablePositionalOptions();
+// Formats a ParsedRef + book name into a display label: "John 3", "John 3:16", "John 3:16–18"
+function formatRefLabel(ref, bookName) {
+    if (!ref.verses)
+        return `${bookName} ${ref.chapter}`;
+    if (ref.verses.type === 'single')
+        return `${bookName} ${ref.chapter}:${ref.verses.verse}`;
+    if (ref.verses.type === 'range')
+        return `${bookName} ${ref.chapter}:${ref.verses.start}–${ref.verses.end}`;
+    return `${bookName} ${ref.chapter}:${ref.verses.verses.join(', ')}`;
+}
+// Generates clean plain-text copy string for verse mode, respecting format flags.
+// opts.ref: true = include "Book ch:v" prefix (default), false = --no-ref
+// opts.numbered: prefix with verse number only
+// opts.md: markdown block-quote format
+function versesToCopyText(verses, bookName, opts) {
+    if (opts.md) {
+        const text = verses.map(v => stripMarkers(v.text)).join(' ');
+        const refLabel = verses.length === 1
+            ? `${bookName} ${verses[0].chapter}:${verses[0].verse}`
+            : `${bookName} ${verses[0].chapter}:${verses[0].verse}–${verses[verses.length - 1].verse}`;
+        return `> ${text}\n> — ${refLabel}`;
+    }
+    return verses.map(v => {
+        const text = stripMarkers(v.text);
+        if (!opts.ref)
+            return text;
+        if (opts.numbered)
+            return `${v.verse} ${text}`;
+        return `${bookName} ${v.chapter}:${v.verse} ${text}`;
+    }).join('\n');
+}
+async function writeClipboard(text, label) {
+    await clipboard.write(text);
+    process.stderr.write(chalk.dim(`✓ Copied ${label} to clipboard\n`));
+}
+// Interactive "press for more" prompt between result pages.
+// Returns true = show next page, false = stop. Ctrl+C exits the process.
+async function promptForMore(shown, total) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        return false;
+    return new Promise(resolve => {
+        process.stderr.write(chalk.dim(`\n  ── ${shown} of ${total} ── Space/Enter next page · q quit ──`));
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.once('data', (key) => {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stderr.write('\r\x1b[2K'); // erase prompt line
+            const ch = key.toString();
+            if (ch === '\x03') {
+                process.stderr.write('\n');
+                process.exit(0);
+            } // Ctrl+C
+            resolve(ch === '\r' || ch === '\n' || ch === ' ' || ch === 'n');
+        });
+    });
+}
+// ── Homepage (rv with no args) ───────────────────────────────────────────────
+function renderHomepage() {
+    const COLS = 12; // books per row
+    const COL_W = 5; // column width (3-char abbr + padding)
+    const lines = [];
+    lines.push('');
+    lines.push(chalk.bold('  Recovery Version Bible'));
+    lines.push('');
+    // Last-read context
+    const last = getLastRead();
+    if (last) {
+        const bookName = getBookInfo(last.book)?.full_name ?? last.book;
+        lines.push(chalk.dim(`  Last read: ${bookName} ${last.chapter}`));
+        lines.push(chalk.dim('  › rv continue'));
+    }
+    else {
+        lines.push(chalk.dim('  Get started: rv john 1'));
+    }
+    lines.push('');
+    // Book grid
+    const books = getAllBooks();
+    const ot = books.filter(b => b.testament === 'OT');
+    const nt = books.filter(b => b.testament === 'NT');
+    function renderGrid(bookList) {
+        const gridLines = [];
+        for (let i = 0; i < bookList.length; i += COLS) {
+            const row = bookList.slice(i, i + COLS);
+            gridLines.push('  ' + row.map(b => b.abbr.padEnd(COL_W)).join(''));
+        }
+        return gridLines;
+    }
+    lines.push(chalk.dim('  OLD TESTAMENT'));
+    lines.push(...renderGrid(ot));
+    lines.push('');
+    lines.push(chalk.dim('  NEW TESTAMENT'));
+    lines.push(...renderGrid(nt));
+    lines.push('');
+    // Hints
+    lines.push(chalk.dim('  rv <book> <chapter>   rv search <query>   rv continue'));
+    lines.push('');
+    console.log(lines.join('\n'));
+}
+// ── rv <ref> [--notes] [--outline] [--full] [--copy] ─────────────────────────
+program
+    .argument('[ref...]', 'Bible reference (e.g. john 3, john 3:16, john 3:16-18)')
+    .option('--notes', 'show footnote markers inline + footnote block below')
+    .option('--outline', 'show section headers inline (chapter mode only)')
+    .option('--full', 'show both section headers and footnotes (shorthand for --outline --notes)')
+    .option('--copy', 'copy displayed output to clipboard')
+    .option('--no-ref', 'with --copy: omit reference prefix (verse mode)')
+    .option('--numbered', 'with --copy: prefix with verse number only (verse mode)')
+    .option('--md', 'with --copy: markdown block-quote format (verse mode)')
+    .option('--raw', 'plain text output, no pager (default for now)')
+    .action(async (refTokens, opts) => {
+    if (opts.full) {
+        opts.notes = true;
+        opts.outline = true;
+    }
+    if (refTokens.length === 0) {
+        if (process.stdout.isTTY) {
+            const { launchPagerHome } = await import('./ui/Pager.js');
+            await launchPagerHome();
+        }
+        else {
+            renderHomepage();
+        }
+        return;
+    }
+    let refs;
+    try {
+        refs = parseRefList(refTokens);
+    }
+    catch (e) {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+    }
+    // Chapter mode: full display with title + optional headers/footnotes
+    // Verse mode: compact inline "Book ch:v  text", one line per verse
+    const isChapterMode = refs.every(r => !r.verses);
+    // Format flags only apply to verse-mode copy text
+    const hasCopyFormat = !opts.ref || !!opts.numbered || !!opts.md;
+    const outputs = [];
+    const copyOutputs = []; // only populated for verse mode + copy format flags
+    const copyLabels = [];
+    if (isChapterMode) {
+        for (const ref of refs) {
+            const verses = getVersesByRef(ref);
+            if (verses.length === 0)
+                continue;
+            const bookName = getBookInfo(ref.book)?.full_name ?? ref.book;
+            const headers = opts.outline ? getSectionHeaders(ref.book) : [];
+            const footnotes = opts.notes ? getFootnotesForChapter(ref.book, ref.chapter) : [];
+            const label = formatRefLabel(ref, bookName);
+            outputs.push(renderVerses(verses, headers, footnotes, {
+                notes: opts.notes ?? false,
+                title: label,
+            }));
+            copyLabels.push(label);
+        }
+    }
+    else {
+        for (const ref of refs) {
+            const verses = getVersesByRef(ref);
+            if (verses.length === 0)
+                continue;
+            const bookName = getBookInfo(ref.book)?.full_name ?? ref.book;
+            const notes = opts.notes ?? false;
+            const lines = verses.map(v => renderVerseInline(v, bookName, notes));
+            if (notes) {
+                const footnotes = getFootnotesForVerses(ref.book, ref.chapter, verses.map(v => v.verse));
+                const inlineMarkers = new Set(verses.flatMap(v => [...v.text.matchAll(/\[([^\]]+)\]/g)].map(m => m[1])));
+                const scoped = footnotes.filter(f => inlineMarkers.has(f.marker));
+                if (scoped.length > 0)
+                    lines.push('', renderFootnoteBlock(scoped));
+            }
+            outputs.push(lines.join('\n'));
+            if (opts.copy && hasCopyFormat) {
+                copyOutputs.push(versesToCopyText(verses, bookName, {
+                    ref: opts.ref, numbered: opts.numbered, md: opts.md,
+                }));
+            }
+            copyLabels.push(formatRefLabel(ref, bookName));
+        }
+    }
+    if (outputs.length === 0)
+        return;
+    // Pager: chapter mode + TTY + no --raw + no --copy → launch interactive pager
+    if (isChapterMode && process.stdout.isTTY && !opts.raw && !opts.copy) {
+        const { launchPager } = await import('./ui/Pager.js');
+        const ref = refs[0];
+        saveLastRead(ref.book, ref.chapter);
+        await launchPager(ref.book, ref.chapter, {
+            notes: opts.notes ?? false,
+            outline: opts.outline ?? false,
+        });
+        return;
+    }
+    const displayed = outputs.join('\n\n');
+    console.log(displayed);
+    // Auto-track: save the last ref read (first ref's book + chapter)
+    const lastRef = refs[0];
+    saveLastRead(lastRef.book, lastRef.chapter);
+    if (opts.copy) {
+        const copyText = (hasCopyFormat && !isChapterMode && copyOutputs.length > 0)
+            ? copyOutputs.join('\n\n')
+            : stripAnsi(displayed);
+        await writeClipboard(copyText, copyLabels.join(', '));
+    }
+});
+// ── rv note john 3:16 [marker] [--copy] ──────────────────────────────────────
+program
+    .command('note')
+    .argument('<args...>', 'verse ref + optional marker, e.g. john 3:16 or john 3:16 1a')
+    .description('Show footnote(s) for a verse or range')
+    .option('--copy', 'copy displayed output to clipboard')
+    .action(async (args, opts) => {
+    if (args.length === 0) {
+        console.error('Usage: rv note <ref> [marker]  (e.g. rv note john 3:16 or rv note john 3:16 1a)');
+        process.exit(1);
+    }
+    // Try no-marker mode: parse all args as verse refs (every ref must have verses).
+    let noMarkerRefs = null;
+    try {
+        const parsed = parseRefList(args);
+        if (parsed.length >= 1 && parsed.every(r => r.verses))
+            noMarkerRefs = parsed;
+    }
+    catch { /* fall through to marker mode */ }
+    if (noMarkerRefs) {
+        const blocks = [];
+        const copyLabels = [];
+        for (const ref of noMarkerRefs) {
+            const bookName = getBookInfo(ref.book)?.full_name ?? ref.book;
+            for (const v of getVersesByRef(ref)) {
+                const footnotes = getFootnotesForVerses(ref.book, ref.chapter, [v.verse]);
+                const inlineMarkers = new Set([...v.text.matchAll(/\[([^\]]+)\]/g)].map(m => m[1]));
+                blocks.push(renderNoteDisplayAll(v, footnotes.filter(f => inlineMarkers.has(f.marker)), bookName));
+                copyLabels.push(`${bookName} ${v.chapter}:${v.verse}`);
+            }
+        }
+        if (blocks.length > 0) {
+            const sep = '\n' + chalk.dim('─'.repeat(process.stdout.columns ?? 60)) + '\n';
+            const output = blocks.join(sep);
+            console.log(output);
+            if (opts.copy)
+                await writeClipboard(stripAnsi(output), copyLabels.join(', '));
+        }
+        return;
+    }
+    // Marker mode: last token is the marker, everything before is the ref.
+    if (args.length < 2) {
+        console.error('Usage: rv note <ref> <marker>  (e.g. rv note john 3:16 1a)');
+        process.exit(1);
+    }
+    const marker = args[args.length - 1];
+    const refTokens = args.slice(0, -1);
+    let ref;
+    try {
+        const parsed = parseRefList(refTokens);
+        ref = parsed[0];
+        if (!ref)
+            throw new Error('Could not parse reference');
+    }
+    catch (e) {
+        console.error(`Error: ${e.message}`);
+        process.exit(1);
+    }
+    if (!ref.verses || ref.verses.type !== 'single') {
+        console.error('Error: note command with a marker requires a single verse (e.g. john 3:16)');
+        process.exit(1);
+    }
+    const verse = getVerse(ref.book, ref.chapter, ref.verses.verse);
+    if (!verse) {
+        console.error(`Verse not found: ${refTokens.join(' ')}`);
+        process.exit(1);
+    }
+    const fn = getFootnote(ref.book, ref.chapter, ref.verses.verse, marker);
+    if (!fn) {
+        console.error(`No footnote "${marker}" found for ${refTokens.join(' ')}`);
+        process.exit(1);
+    }
+    const bookName = getBookInfo(ref.book)?.full_name ?? ref.book;
+    const output = renderNoteDisplay(verse, fn, bookName);
+    console.log(output);
+    if (opts.copy) {
+        await writeClipboard(stripAnsi(output), `note ${marker} for ${bookName} ${ref.chapter}:${ref.verses.verse}`);
+    }
+});
+// ── Search & Topic helpers ────────────────────────────────────────────────────
+const RESULT_LIMIT = 20;
+// Scans args right-to-left for "in <book>" scope suffix.
+// "grace in romans" → { queryTokens: ["grace"], book: "Rom" }
+// "sin in john"     → { queryTokens: ["sin"],   book: "Joh" }
+// "faith in christ" → { queryTokens: ["faith", "in", "christ"], book: undefined }
+function parseScope(args) {
+    for (let nameLen = 3; nameLen >= 1; nameLen--) {
+        const inIdx = args.length - nameLen - 1;
+        if (inIdx < 1)
+            continue; // need at least one query token before "in"
+        if (args[inIdx]?.toLowerCase() !== 'in')
+            continue;
+        const book = resolveBook(args.slice(inIdx + 1, inIdx + 1 + nameLen).join(' '));
+        if (book)
+            return { queryTokens: args.slice(0, inIdx), book };
+    }
+    return { queryTokens: args, book: undefined };
+}
+// Builds an FTS5 query string and extracts terms for highlighting.
+// Single shell-quoted arg with spaces → phrase: "only begotten"
+// Multiple tokens                     → AND:    "eternal" AND "life"
+function buildFTSQuery(tokens) {
+    if (tokens.length === 1 && tokens[0].includes(' ')) {
+        const phrase = tokens[0];
+        return {
+            fts: `"${phrase.replace(/"/g, '')}"`,
+            terms: phrase.split(/\s+/).filter(Boolean),
+            display: `"${phrase}"`,
+        };
+    }
+    const terms = tokens.map(t => t.replace(/"/g, '').trim()).filter(Boolean);
+    return {
+        fts: terms.length === 1 ? `"${terms[0]}"` : terms.map(t => `"${t}"`).join(' AND '),
+        terms,
+        display: terms.length === 1 ? terms[0] : terms.join(' '),
+    };
+}
+// ── rv search <query> [in <book>] [--fts] [--all] [--copy] ───────────────────
+// Concordance-first: if the query is a single known concordance word, use the
+// curated concordance index. Otherwise (or with --fts) falls back to FTS5.
+program
+    .command('search')
+    .argument('<query...>', 'word, phrase, or "quoted phrase", e.g. grace or "only begotten"')
+    .description('Search verses — concordance for known words, FTS5 otherwise')
+    .option('--fts', 'force raw full-text search, bypass concordance')
+    .option('--all', `show all results (default: ${RESULT_LIMIT})`)
+    .option('--copy', 'copy results to clipboard')
+    .action(async (queryArgs, opts) => {
+    const { queryTokens, book } = parseScope(queryArgs);
+    if (queryTokens.length === 0) {
+        console.error('Usage: rv search <query> [in <book>]');
+        process.exit(1);
+    }
+    const word = queryTokens.join(' ');
+    const scopeLabel = book ? ` in ${getBookInfo(book)?.full_name ?? book}` : '';
+    // Concordance path: single-word queries that exist in the curated index,
+    // unless the user explicitly wants raw FTS with --fts.
+    const useConcordance = !opts.fts && queryTokens.length === 1 && isInConcordance(word);
+    let all;
+    let terms;
+    let sourceLabel;
+    if (useConcordance) {
+        all = getTopicVerses(word, book);
+        terms = [word];
+        sourceLabel = `Concordance: ${word}${scopeLabel}  ·  ${all.length} occurrence${all.length === 1 ? '' : 's'}`;
+    }
+    else {
+        const { fts, terms: ftsTerms, display } = buildFTSQuery(queryTokens);
+        all = searchFTS(fts, book);
+        terms = ftsTerms;
+        const notInNote = !opts.fts && queryTokens.length === 1 ? '  (not in concordance)' : '';
+        sourceLabel = all.length > 0
+            ? `Search: "${display}"${scopeLabel}  ·  ${all.length} match${all.length === 1 ? '' : 'es'}${notInNote}`
+            : `"${display}" not found`;
+    }
+    if (all.length === 0) {
+        console.log(chalk.dim(`  No results for "${word}"${scopeLabel}`));
+        return;
+    }
+    // Print header (total count always visible upfront)
+    console.log(chalk.dim(`  ${sourceLabel}`));
+    console.log('');
+    // Paginate: interactive page-by-page in a TTY, single page + hint when piped
+    const isTTY = process.stdout.isTTY ?? false;
+    let offset = 0;
+    while (offset < all.length) {
+        const pageEnd = opts.all ? all.length : Math.min(offset + RESULT_LIMIT, all.length);
+        for (let i = offset; i < pageEnd; i++) {
+            const v = all[i];
+            const bookName = getBookInfo(v.book)?.full_name ?? v.book;
+            const ref = `${bookName} ${v.chapter}:${v.verse}`;
+            const cleanText = stripMarkers(v.text);
+            // Truncate to ~150 chars for scanability
+            const truncated = cleanText.length > 150 ? cleanText.substring(0, 147) + '...' : cleanText;
+            const highlighted = highlightTerms(truncated, terms);
+            // Wrap the text at ~76 chars with 4-space indent
+            const maxW = Math.min((process.stdout.columns ?? 80) - 4, 76);
+            const words = highlighted.split(' ');
+            const wrapLines = [];
+            let cur = '';
+            for (const w of words) {
+                const wLen = w.replace(/\x1b\[[0-9;]*m/g, '').length;
+                const curLen = cur.replace(/\x1b\[[0-9;]*m/g, '').length;
+                if (!cur) {
+                    cur = w;
+                }
+                else if (curLen + 1 + wLen <= maxW) {
+                    cur += ' ' + w;
+                }
+                else {
+                    wrapLines.push(cur);
+                    cur = w;
+                }
+            }
+            if (cur)
+                wrapLines.push(cur);
+            console.log(`  ${chalk.bold(ref)}`);
+            for (const line of wrapLines)
+                console.log(`    ${line}`);
+            console.log('');
+        }
+        offset = pageEnd;
+        if (offset >= all.length || opts.all)
+            break;
+        if (!isTTY) {
+            // Non-interactive: show "showing N of M" hint and stop
+            const ftsFlag = opts.fts ? ' --fts' : '';
+            const cmd = `rv search ${word}${book ? ` in ${(getBookInfo(book)?.full_name ?? book).toLowerCase()}` : ''}${ftsFlag}`;
+            console.log('');
+            console.log(chalk.dim(`  showing ${offset} of ${all.length}  ·  ${cmd} --all to show all`));
+            break;
+        }
+        const more = await promptForMore(offset, all.length);
+        if (!more)
+            break;
+    }
+    // --copy always copies the full result set regardless of how many pages were viewed
+    if (opts.copy) {
+        const copyLines = all.map(v => {
+            const bookName = getBookInfo(v.book)?.full_name ?? v.book;
+            return `${bookName} ${v.chapter}:${v.verse}  ${stripMarkers(v.text)}`;
+        });
+        await writeClipboard(copyLines.join('\n'), `${word} (${all.length} verse${all.length === 1 ? '' : 's'})`);
+    }
+});
+// ── rv continue ───────────────────────────────────────────────────────────────
+program
+    .command('continue')
+    .description('Re-display last read passage')
+    .option('--notes', 'show footnote markers inline + footnote block below')
+    .option('--outline', 'show section headers inline')
+    .option('--full', 'shorthand for --outline --notes')
+    .option('--copy', 'copy displayed output to clipboard')
+    .action(async (opts) => {
+    const last = getLastRead();
+    if (!last) {
+        console.log(chalk.dim('  Nothing read yet — try: rv john 1'));
+        return;
+    }
+    if (opts.full) {
+        opts.notes = true;
+        opts.outline = true;
+    }
+    // Pager for continue: TTY + no --copy → launch pager
+    if (process.stdout.isTTY && !opts.copy) {
+        const { launchPager } = await import('./ui/Pager.js');
+        await launchPager(last.book, last.chapter, {
+            notes: opts.notes ?? false,
+            outline: opts.outline ?? false,
+        });
+        return;
+    }
+    const bookInfo = getBookInfo(last.book);
+    const bookName = bookInfo?.full_name ?? last.book;
+    const ref = { book: last.book, chapter: last.chapter };
+    const verses = getVersesByRef(ref);
+    if (verses.length === 0) {
+        console.error(`Could not load ${bookName} ${last.chapter}`);
+        process.exit(1);
+    }
+    const headers = opts.outline ? getSectionHeaders(last.book) : [];
+    const footnotes = opts.notes ? getFootnotesForChapter(last.book, last.chapter) : [];
+    const label = `${bookName} ${last.chapter}`;
+    console.log(chalk.dim(`  Continuing: ${label}`));
+    console.log('');
+    const output = renderVerses(verses, headers, footnotes, {
+        notes: opts.notes ?? false,
+        title: label,
+    });
+    console.log(output);
+    if (opts.copy) {
+        await writeClipboard(stripAnsi(output), label);
+    }
+});
+// ── rv help ──────────────────────────────────────────────────────────────────
+program
+    .command('help')
+    .description('Show all commands and pager shortcuts')
+    .action(() => {
+    const d = chalk.dim;
+    const b = chalk.bold;
+    const c = chalk.cyan;
+    console.log(`
+${b('rv — Recovery Version Bible CLI')}
+
+${b('READING')}
+  ${c('rv john 3')}              Read a chapter (opens pager in terminal)
+  ${c('rv john 3:16')}           Read a single verse
+  ${c('rv john 3:16-18')}        Read a verse range
+  ${c('rv john 3:16,18,20')}     Multiple specific verses
+  ${c('rv john 3:16 rom 8:28')}  Verses across books
+  ${c('rv jn 3')}                Fuzzy book names ${d('(jn → John, gen → Genesis, rm → Romans)')}
+  ${c('rv john 3 --notes')}      Show footnote markers + footnote block
+  ${c('rv john 3 --outline')}    Show section headers inline
+  ${c('rv john 3 --full')}       Both notes and outline
+  ${c('rv john 3 --raw')}        Plain text, no pager ${d('(also auto when piped)')}
+
+${b('FOOTNOTES')}
+  ${c('rv note john 3:16')}      All footnotes for a verse
+  ${c('rv note john 3:16 2d')}   Specific footnote by marker
+  ${c('rv note john 3:14-16')}   Footnotes for a range
+
+${b('SEARCH')}  ${d('concordance-first for known words, FTS5 for everything else')}
+  ${c('rv search grace')}        Concordance lookup ${d('(1,129 curated words)')}
+  ${c('rv search grace in rom')} Scoped to a book
+  ${c('rv search "only begotten"')}  Phrase match via FTS5
+  ${c('rv search eternal life')}     Multi-word AND match
+  ${c('rv search grace --fts')}  Force raw FTS5
+  ${c('rv search grace --all')}  Show all results ${d('(default: 20 per page)')}
+
+${b('NAVIGATION')}
+  ${c('rv')}                     Home screen — browse books, pick chapters
+  ${c('rv continue')}            Resume last-read chapter
+
+${b('COPY')}  ${d('add --copy to any read command')}
+  ${c('rv john 3:16 --copy')}           Copy with reference prefix
+  ${c('rv john 3:16 --copy --no-ref')}  Plain text only
+  ${c('rv john 3:16 --copy --numbered')} Verse number prefix
+  ${c('rv john 3:16 --copy --md')}      Markdown block quote
+  ${c('rv search grace --copy')}        Copy all search results
+
+${b('PAGER SHORTCUTS')}  ${d('chapter mode in terminal')}
+  ${d('Scroll')}     ↑↓ or j/k line  ·  Space/b page  ·  g top  ·  G bottom
+  ${d('Chapter')}    ←→ or n/p next/prev ${d('(cross-book)')}
+  ${d('Toggles')}    f footnotes  ·  o outline
+  ${d('Navigate')}   : goto ${d('(type ref, e.g. rom 8)')}  ·  H home  ·  [/] back/fwd
+  ${d('Study')}      d study mode — browse footnotes + follow cross-references
+  ${d('Copy')}       c copy mode — select verses with cursor
+  ${d('Search')}     / find in chapter  ·  n/N cycle matches
+  ${d('Quit')}       q or Esc
+
+${b('STUDY MODE')}  ${d('press d in pager')}
+  ↑↓ move verse cursor  ·  type # to follow cross-ref
+  v start range  ·  c copy verse/range  ·  ←→ chapter
+  : goto  ·  [/] back/fwd  ·  d exit
+`);
+});
+program.parseAsync();

package/dist/parser.d.ts

@@ -0,0 +1,20 @@
+export type VerseSpec = {
+    type: 'single';
+    verse: string;
+} | {
+    type: 'range';
+    start: string;
+    end: string;
+} | {
+    type: 'list';
+    verses: string[];
+};
+export interface ParsedRef {
+    book: string;
+    chapter: number;
+    verses?: VerseSpec;
+}
+export declare function resolveBook(input: string): string | null;
+export declare function parseRef(input: string): ParsedRef;
+export declare function parseRefTokens(tokens: string[]): ParsedRef;
+export declare function parseRefList(tokens: string[]): ParsedRef[];