ofw-mcp 2.7.1 → 2.9.0

package/dist/cache/store.js

@@ -32,6 +32,14 @@ function draftFromDb(r) {
         listData: JSON.parse(r.list_data_json),
     };
 }
+function lineageFromDb(r) {
+    return {
+        id: r.id,
+        draftKey: r.draft_key,
+        previousId: r.previous_id,
+        recordedAt: r.recorded_at,
+    };
+}
 function attachmentFromDb(r) {
     return {
         fileId: r.file_id,
@@ -93,6 +101,17 @@ export const SCHEMA_STATEMENTS = [
      key TEXT PRIMARY KEY,
      value TEXT NOT NULL
    )`,
+    // v3: draft identity chain. One row per OFW id, all the ids of one logical
+    // document sharing a `draft_key`. Survives ofw_save_draft's create-then-delete
+    // replacement AND the transition to a sent message, so "what happened to the
+    // draft I was editing?" is answerable without guessing which id is current.
+    `CREATE TABLE IF NOT EXISTS draft_lineage (
+     id INTEGER PRIMARY KEY,
+     draft_key TEXT NOT NULL,
+     previous_id INTEGER,
+     recorded_at TEXT NOT NULL
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_draft_lineage_key ON draft_lineage(draft_key, recorded_at, id)`,
     // v2: attachments table. Idempotent — IF NOT EXISTS.
     `CREATE TABLE IF NOT EXISTS attachments (
      file_id INTEGER PRIMARY KEY,
@@ -119,7 +138,7 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN resume_page INTEGER',
 ];
 /** The schema version stamped into the `meta` table on open. */
-export const SCHEMA_VERSION = '2';
+export const SCHEMA_VERSION = '3';
 // Build the WHERE clause + bound params for message queries. listMessages and
 // countMessages share this so the filter semantics can't drift.
 function buildMessageFilter(opts) {
@@ -302,6 +321,11 @@ export class OFWCacheCore {
         const rows = this.db.all('SELECT * FROM drafts ORDER BY modified_at DESC, id DESC LIMIT ? OFFSET ?', [opts.size, offset]);
         return rows.map(draftFromDb);
     }
+    countDrafts() {
+        const r = this.db.get('SELECT COUNT(*) as n FROM drafts', []);
+        /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
+        return r?.n ?? 0;
+    }
     deleteDraft(id) {
         this.db.run('DELETE FROM drafts WHERE id = ?', [id]);
     }
@@ -309,6 +333,45 @@ export class OFWCacheCore {
         const rows = this.db.all('SELECT id FROM drafts', []);
         return rows.map((r) => r.id);
     }
+    /**
+     * Link an id into a draft's identity chain. Upserts on id: re-recording the
+     * same id (e.g. a retried save) rewrites its link rather than duplicating it,
+     * so `getDraftLineage` can never report one id twice.
+     */
+    recordDraftLineage(row) {
+        this.db.run(`INSERT INTO draft_lineage (id, draft_key, previous_id, recorded_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         draft_key=excluded.draft_key,
+         previous_id=excluded.previous_id,
+         recorded_at=excluded.recorded_at`, [row.id, requireString('draft_lineage.draftKey', row.draftKey), nullish(row.previousId),
+            requireString('draft_lineage.recordedAt', row.recordedAt)]);
+    }
+    getDraftLineageById(id) {
+        const r = this.db.get('SELECT * FROM draft_lineage WHERE id = ?', [id]);
+        return r ? lineageFromDb(r) : null;
+    }
+    /**
+     * Batch read — one query for a whole page of drafts. On the Durable Object
+     * backend each cache call is a subrequest, so a per-draft lookup would spend
+     * the caller's sync budget on bookkeeping.
+     */
+    getDraftLineageByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db.all(`SELECT * FROM draft_lineage WHERE id IN (${placeholders})`, ids);
+        return rows.map(lineageFromDb);
+    }
+    /**
+     * Every link in one chain, OLDEST FIRST — so the last element is the chain's
+     * current id. Ordered by recorded_at then id: two links written inside the
+     * same millisecond tie-break on id, and OFW mints ids monotonically, so the
+     * newer replacement always sorts last.
+     */
+    getDraftLineage(draftKey) {
+        const rows = this.db.all('SELECT * FROM draft_lineage WHERE draft_key = ? ORDER BY recorded_at ASC, id ASC', [draftKey]);
+        return rows.map(lineageFromDb);
+    }
     getSyncState(folder) {
         const r = this.db.get('SELECT last_sync_at, newest_id, resume_page FROM sync_state WHERE folder = ?', [folder]);
         if (!r)
@@ -444,12 +507,27 @@ export class LocalCacheStore {
     async listDrafts(opts) {
         return this.core.listDrafts(opts);
     }
+    async countDrafts() {
+        return this.core.countDrafts();
+    }
     async deleteDraft(id) {
         this.core.deleteDraft(id);
     }
     async listDraftIds() {
         return this.core.listDraftIds();
     }
+    async recordDraftLineage(row) {
+        this.core.recordDraftLineage(row);
+    }
+    async getDraftLineageById(id) {
+        return this.core.getDraftLineageById(id);
+    }
+    async getDraftLineageByIds(ids) {
+        return this.core.getDraftLineageByIds(ids);
+    }
+    async getDraftLineage(draftKey) {
+        return this.core.getDraftLineage(draftKey);
+    }
     async getSyncState(folder) {
         return this.core.getSyncState(folder);
     }

package/dist/config.js

@@ -82,6 +82,66 @@ export function getCalendarWritesAllowed() {
         return true;
     return mode === 'drafts' && parseBoolEnv('OFW_CALENDAR_WRITES');
 }
+/**
+ * Deployment-wide ceiling on reads that STAMP the record.
+ *
+ * Fetching a message body from OFW marks it read and stamps a "First Viewed"
+ * timestamp the co-parent can see. That is part of the court-visible record and
+ * it cannot be undone — and unlike a send, it happens as a side effect of an
+ * ordinary read, so nothing about the caller's intent signals it.
+ *
+ * Default TRUE: unset means exactly the behaviour that shipped before this flag
+ * existed. Set OFW_ALLOW_MARK_READ=false and it becomes a hard ceiling rather
+ * than a default — `ofw_get_message` refuses a fetch that would stamp,
+ * `ofw_check_freshness` ignores `allowMarkRead:true`, and `ofw_sync_messages`
+ * ignores `fetchUnreadBodies:true`. A per-call argument (or an instruction
+ * injected into one) cannot raise it, which is the same structural posture
+ * OFW_WRITE_MODE takes for writes.
+ *
+ * An unrecognized value fails CLOSED, with a warning: someone who wrote
+ * "flase" meant to disable this, and honouring the typo as the permissive
+ * default would keep stamping the record while looking configured.
+ */
+export function getAllowMarkRead() {
+    const raw = process.env.OFW_ALLOW_MARK_READ;
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return true;
+    const value = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(value))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(value))
+        return false;
+    // stdio transport: stderr only — stdout is reserved for JSON-RPC.
+    console.error(`[ofw-mcp] Unrecognized OFW_ALLOW_MARK_READ "${raw.trim()}" — failing closed to "false" (no tool may mark a message read on OFW). Valid values: true, false.`);
+    return false;
+}
+/**
+ * Default for ofw_sync_messages' `fetchUnreadBodies` arg. False (the shipped
+ * default) so an ordinary sync never stamps unread inbox messages; set
+ * OFW_FETCH_UNREAD_BODIES=true on a deployment where read receipts are routine
+ * and you would rather have the bodies cached. Capped by getAllowMarkRead().
+ */
+export function getFetchUnreadBodies() {
+    return parseBoolEnv('OFW_FETCH_UNREAD_BODIES');
+}
+/**
+ * Default for the read tools' `autoRefresh` arg.
+ *
+ * When a cached read comes back EMPTY and the cache is not `fresh`, the tools
+ * refuse to report that emptiness (see UNVERIFIED_EMPTY in tools/messages.ts):
+ * an empty result from a 207-minute-old cache is shaped identically to a
+ * verified "nothing there", and answering "no, it wasn't sent" from one is how
+ * a false negative becomes a confident statement about a legal record.
+ *
+ * The refusal names its remedy, so the default (false) costs one extra call.
+ * Set OFW_AUTO_REFRESH=true and the tools instead sync the backing folders
+ * themselves and answer from the refreshed cache — same guarantee, no round
+ * trip. Never silently degrades: if the refresh does not make the read
+ * verifiable, the refusal still fires.
+ */
+export function getAutoRefreshStaleReads() {
+    return parseBoolEnv('OFW_AUTO_REFRESH');
+}
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP

package/dist/extract/document.js

@@ -0,0 +1,83 @@
+// Word (.docx) text extraction.
+//
+// The goal is a readable transcript, not a faithful re-render: headings keep
+// their level as `#` prefixes, list paragraphs keep their bullet, and table
+// rows come back pipe-delimited. Structure is what makes an extracted custody
+// schedule answerable ("which row is Thanksgiving?"); a flat wall of runs is
+// not much better than the blob we are replacing.
+import { readZip } from './zip.js';
+import { decodeXmlEntities, elements } from './xml.js';
+import { findPart } from './ooxml.js';
+// A run's text, a tab, or a break — matched in document order so an inline tab
+// does not get hoisted out of position by a tags-then-text pass.
+const RUN_CONTENT = /<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>|<w:(tab|br|cr)\s*\/>/g;
+function paragraphText(inner) {
+    let text = '';
+    for (let m = RUN_CONTENT.exec(inner); m !== null; m = RUN_CONTENT.exec(inner)) {
+        if (m[1] !== undefined)
+            text += decodeXmlEntities(m[1]);
+        else
+            text += m[2] === 'tab' ? '\t' : '\n';
+    }
+    RUN_CONTENT.lastIndex = 0;
+    return text;
+}
+/** Prefix a paragraph according to its `<w:pStyle>`, if it has a known one. */
+function styledParagraph(inner) {
+    const text = paragraphText(inner);
+    if (text === '')
+        return '';
+    const style = /<w:pStyle\s[^>]*w:val="([^"]*)"/.exec(inner)?.[1] ?? '';
+    const heading = /^Heading(\d)$/.exec(style);
+    if (heading)
+        return `${'#'.repeat(Math.min(Number(heading[1]), 6))} ${text}`;
+    if (style === 'Title' || style === 'Subtitle')
+        return `# ${text}`;
+    if (style === 'ListParagraph')
+        return `- ${text}`;
+    return text;
+}
+function tableText(inner) {
+    const rows = [];
+    for (const tr of elements(inner, 'w:tr')) {
+        const cells = [];
+        for (const tc of elements(tr.inner, 'w:tc')) {
+            // A cell holds paragraphs; keep it on one line so the row stays a row.
+            const parts = [];
+            for (const p of elements(tc.inner, 'w:p')) {
+                const text = paragraphText(p.inner);
+                if (text !== '')
+                    parts.push(text);
+            }
+            cells.push(parts.join(' '));
+        }
+        rows.push(`| ${cells.join(' | ')} |`);
+    }
+    return rows.join('\n');
+}
+// Top-level block scan: a table swallows its own paragraphs (the match spans
+// them), so the alternation yields tables and stray paragraphs in order without
+// emitting a table's cell text twice.
+// The paragraph arm mirrors `elements()`: a lazy attribute run that does not
+// eat a self-closing slash, so `<w:p w14:paraId="…"/>` cannot swallow the
+// following paragraph.
+const BLOCK = /<w:tbl(?:\s[^>]*?)?>[\s\S]*?<\/w:tbl>|<w:p(?:\s[^>]*?)?(?:\s*\/>|>([\s\S]*?)<\/w:p>)/g;
+/** Extract the text of a .docx document part. */
+export async function extractDocx(bytes) {
+    const zip = await readZip(bytes);
+    const path = findPart(zip, 'word/document.xml', 'document.xml');
+    if (!path)
+        throw new Error('no document part found in the .docx archive');
+    /* v8 ignore next -- findPart only returns a name the archive contains, so readText cannot be null here */
+    const xml = (await zip.readText(path)) ?? '';
+    const blocks = [];
+    for (let m = BLOCK.exec(xml); m !== null; m = BLOCK.exec(xml)) {
+        // Group 1 is the paragraph's inner XML — undefined for a table match and
+        // for a self-closing (empty) paragraph.
+        const text = m[0].startsWith('<w:tbl') ? tableText(m[0]) : styledParagraph(m[1] ?? '');
+        if (text !== '')
+            blocks.push(text);
+    }
+    BLOCK.lastIndex = 0;
+    return { kind: 'document', text: blocks.join('\n\n') };
+}

package/dist/extract/index.js

@@ -0,0 +1,222 @@
+// The delivery ladder's extraction rung.
+//
+// `ofw_download_attachment` fetches bytes successfully and then has to hand the
+// caller something it can actually read. A host renders four image types
+// inline and rejects every other embedded resource outright ("Resources of
+// type 'application/vnd.…sheet' are not currently supported"), so for a
+// spreadsheet, PDF, Word or PowerPoint attachment the bytes are delivered and
+// unreadable at the same time. Rendering is a display concern; content is a
+// data concern, and this module is what keeps the second from being decided by
+// the first: whatever the host can draw, the FILE's text comes back as text.
+import { extractXlsx, extractDelimited } from './spreadsheet.js';
+import { extractDocx } from './document.js';
+import { extractPptx } from './presentation.js';
+import { extractPdf } from './pdf.js';
+const MIME_KINDS = {
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
+    'application/vnd.ms-excel.sheet.macroenabled.12': 'xlsx',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
+    'application/pdf': 'pdf',
+    'text/csv': 'csv',
+    'text/tab-separated-values': 'tsv',
+    'application/json': 'text',
+    'application/xml': 'text',
+    'application/xhtml+xml': 'text',
+    'application/javascript': 'text',
+    'application/x-yaml': 'text',
+};
+const EXT_KINDS = {
+    '.xlsx': 'xlsx', '.xlsm': 'xlsx',
+    '.docx': 'docx',
+    '.pptx': 'pptx',
+    '.pdf': 'pdf',
+    '.csv': 'csv',
+    '.tsv': 'tsv', '.tab': 'tsv',
+    '.txt': 'text', '.md': 'text', '.json': 'text', '.xml': 'text',
+    '.html': 'text', '.htm': 'text', '.log': 'text', '.yaml': 'text', '.yml': 'text',
+    '.ics': 'text', '.vcf': 'text', '.srt': 'text',
+};
+/**
+ * Which extractor handles this attachment, by MIME then by extension. The
+ * extension is a real fallback, not a formality: OFW serves binaries with a
+ * `charset` bolted on and sometimes with no useful type at all.
+ */
+export function extractKindFor(mimeType, fileName) {
+    const byMime = MIME_KINDS[mimeType];
+    if (byMime)
+        return byMime;
+    const dot = fileName.lastIndexOf('.');
+    const byExt = dot === -1 ? undefined : EXT_KINDS[fileName.slice(dot).toLowerCase()];
+    if (byExt)
+        return byExt;
+    // Any other text/* type (text/plain, text/markdown, text/html, …) is text.
+    return mimeType.startsWith('text/') ? 'text' : null;
+}
+/**
+ * Build a part selector from a `"1-3,5"` / `"Summary,2026"` spec. Numbers are
+ * 1-based positions; anything else matches a sheet or slide/page label. An
+ * empty spec selects everything rather than nothing — a filter that silently
+ * excluded all content would look exactly like an empty file.
+ */
+export function parsePartSpec(spec) {
+    const ranges = [];
+    const names = new Set();
+    for (const token of spec.split(',').map((t) => t.trim()).filter(Boolean)) {
+        const range = /^(\d+)\s*-\s*(\d+)$/.exec(token);
+        if (range) {
+            ranges.push([Number(range[1]), Number(range[2])]);
+            continue;
+        }
+        // A bare number is a position AND a possible name: spreadsheet tabs are
+        // routinely named for a year ("2026"), and reading that token as a position
+        // only would make the obvious `parts: "2026"` select nothing at all.
+        if (/^\d+$/.test(token))
+            ranges.push([Number(token), Number(token)]);
+        names.add(token.toLowerCase());
+    }
+    if (ranges.length === 0 && names.size === 0)
+        return () => true;
+    return (index, name) => ranges.some(([from, to]) => index + 1 >= from && index + 1 <= to)
+        || names.has(name.toLowerCase());
+}
+/** Cut `text` to `budget` characters on a line boundary where possible. */
+function clip(text, budget) {
+    const cut = text.slice(0, budget);
+    const lastBreak = cut.lastIndexOf('\n');
+    return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;
+}
+function omissionNote(label) {
+    return `${label} (omitted: response character budget)`;
+}
+/**
+ * Trim an extraction to `maxChars`, recording exactly what was dropped. A
+ * truncated payload that does not say so is worse than a short one: the caller
+ * reads a partial custody schedule as the whole schedule.
+ */
+export function applyCharBudget(extracted, maxChars) {
+    switch (extracted.kind) {
+        case 'text':
+        case 'document': {
+            if (extracted.text.length <= maxChars)
+                return extracted;
+            return { ...extracted, text: clip(extracted.text, maxChars), truncated: true };
+        }
+        case 'spreadsheet': {
+            const sheets = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const sheet of extracted.sheets) {
+                if (budget <= 0) {
+                    omitted.push(omissionNote(sheet.name));
+                    truncated = true;
+                    continue;
+                }
+                if (sheet.csv.length <= budget) {
+                    sheets.push(sheet);
+                    budget -= sheet.csv.length;
+                    continue;
+                }
+                const csv = clip(sheet.csv, budget);
+                sheets.push({ ...sheet, csv, rows: csv.split('\n').length, truncated: true });
+                budget = 0;
+                truncated = true;
+            }
+            return {
+                ...extracted, sheets, truncated,
+                ...(omitted.length ? { omitted } : {}),
+            };
+        }
+        case 'presentation': {
+            const slides = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const slide of extracted.slides) {
+                const size = slide.text.length + (slide.notes?.length ?? 0);
+                if (budget <= 0) {
+                    omitted.push(omissionNote(`slide ${slide.number}`));
+                    truncated = true;
+                    continue;
+                }
+                if (size <= budget) {
+                    slides.push(slide);
+                    budget -= size;
+                    continue;
+                }
+                slides.push({ ...slide, text: clip(slide.text, budget), notes: undefined });
+                budget = 0;
+                truncated = true;
+            }
+            return { ...extracted, slides, truncated, ...(omitted.length ? { omitted } : {}) };
+        }
+        case 'pdf': {
+            const pages = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const page of extracted.pages) {
+                if (budget <= 0) {
+                    omitted.push(omissionNote(`page ${page.number}`));
+                    truncated = true;
+                    continue;
+                }
+                if (page.text.length <= budget) {
+                    pages.push(page);
+                    budget -= page.text.length;
+                    continue;
+                }
+                pages.push({ ...page, text: clip(page.text, budget) });
+                budget = 0;
+                truncated = true;
+            }
+            return { ...extracted, pages, truncated, ...(omitted.length ? { omitted } : {}) };
+        }
+    }
+}
+/** Default response budget: roughly 12k tokens of extracted text. */
+export const DEFAULT_MAX_CHARS = 50_000;
+function decodeText(bytes) {
+    const text = bytes.toString('utf8');
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * Extract readable content from an attachment, or return null when the format
+ * has no extractor (a .zip, a .heic, an unknown binary) and the caller should
+ * fall through to the next rung of the delivery ladder.
+ *
+ * Throws when a format that SHOULD be extractable cannot be read, so the
+ * failure can be reported by name rather than swallowed.
+ */
+export async function extractAttachment(bytes, mimeType, fileName, opts = {}) {
+    const kind = extractKindFor(mimeType, fileName);
+    if (kind === null)
+        return null;
+    const select = opts.parts === undefined ? undefined : parsePartSpec(opts.parts);
+    let extracted;
+    switch (kind) {
+        case 'xlsx':
+            extracted = await extractXlsx(bytes, { select });
+            break;
+        case 'csv':
+            extracted = extractDelimited(decodeText(bytes), fileName, ',');
+            break;
+        case 'tsv':
+            extracted = extractDelimited(decodeText(bytes), fileName, '\t');
+            break;
+        case 'docx':
+            extracted = await extractDocx(bytes);
+            break;
+        case 'pptx':
+            extracted = await extractPptx(bytes, { select });
+            break;
+        case 'pdf':
+            extracted = await extractPdf(bytes, { select });
+            break;
+        case 'text':
+            extracted = { kind: 'text', text: decodeText(bytes) };
+            break;
+    }
+    return applyCharBudget(extracted, opts.maxChars ?? DEFAULT_MAX_CHARS);
+}

package/dist/extract/inflate.js

@@ -0,0 +1,55 @@
+// Bounded decompression, shared by the ZIP reader and the PDF stream decoder.
+//
+// Both formats let the FILE state how big a member expands to, and both are
+// read from co-parent-supplied attachments. A declared size is therefore a
+// hint, never a guarantee: a ZIP central directory can claim 1 KB in front of a
+// member that expands to a gigabyte, and a PDF stream dictionary declares
+// nothing about its inflated length at all. Checking the declared number before
+// inflating rejects an HONEST oversized member cheaply — it does nothing about
+// a lying one.
+//
+// So the real cap is enforced on the bytes as they actually arrive: read the
+// decompressed stream chunk by chunk, and abort the moment the running total
+// passes the limit. Peak memory is then bounded by the limit rather than by
+// whatever the file felt like claiming.
+/** 32 MiB. Sized to fit comfortably inside the Worker's memory budget. */
+export const MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
+/**
+ * Thrown when decompression is aborted for exceeding its cap. Distinct from a
+ * decode failure so callers can tell "this file is hostile or absurd" from
+ * "this stream is corrupt" — the first deserves to be reported, the second is
+ * routinely survivable.
+ */
+export class DecompressionLimitError extends Error {
+    constructor(label, limit) {
+        super(`${label} expands past the ${limit}-byte decompression cap`);
+        this.name = 'DecompressionLimitError';
+    }
+}
+/**
+ * Inflate `data`, aborting if the OUTPUT exceeds `limit` bytes.
+ *
+ * `deflate-raw` is the ZIP member format; `deflate` is the zlib-wrapped form a
+ * PDF `/FlateDecode` stream uses. Both go through the WHATWG
+ * `DecompressionStream` so this runs unchanged on Node and workerd.
+ */
+export async function inflateBounded(data, format, limit, label) {
+    const stream = new Blob([data]).stream()
+        .pipeThrough(new DecompressionStream(format));
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > limit) {
+            // Stop pulling: the rest of the payload is never allocated.
+            await reader.cancel();
+            throw new DecompressionLimitError(label, limit);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}

package/dist/extract/ooxml.js

@@ -0,0 +1,58 @@
+// Shared OOXML plumbing: part-path resolution and relationship lookup.
+//
+// Every OOXML format points from one part to another through a `_rels` file
+// (`r:id="rId3"` → `Target="worksheets/sheet3.xml"`), and the target is
+// relative to the REFERRING part's directory. Guessing the target from the id
+// number instead works right up until a document has been edited enough for the
+// numbering to drift, which is why this indirection is followed properly.
+import { elements, attr } from './xml.js';
+/** Resolve a relationship target against the referring part's directory. */
+export function resolvePartPath(baseDir, target) {
+    // A leading "/" means package-absolute.
+    if (target.startsWith('/'))
+        return target.slice(1);
+    const segments = (baseDir + target).split('/');
+    const out = [];
+    for (const segment of segments) {
+        if (segment === '.' || segment === '')
+            continue;
+        if (segment === '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out.join('/');
+}
+/** The directory of a part path, with a trailing slash (`""` at the root). */
+export function dirOf(partPath) {
+    const i = partPath.lastIndexOf('/');
+    return i === -1 ? '' : partPath.slice(0, i + 1);
+}
+/** Read the `_rels` companion of `partPath`. Empty when the part has none. */
+export async function readRels(zip, partPath) {
+    const dir = dirOf(partPath);
+    const base = partPath.slice(dir.length);
+    const xml = await zip.readText(`${dir}_rels/${base}.rels`);
+    if (!xml)
+        return [];
+    const rels = [];
+    for (const el of elements(xml, 'Relationship')) {
+        const id = attr(el.attrs, 'Id');
+        const target = attr(el.attrs, 'Target');
+        /* v8 ignore next -- a Relationship without Id/Target is malformed OOXML; skipping keeps one bad entry from failing the whole read */
+        if (!id || !target)
+            continue;
+        rels.push({ id, target: resolvePartPath(dir, target), type: attr(el.attrs, 'Type') ?? '' });
+    }
+    return rels;
+}
+/**
+ * Locate a top-level part: the conventional path when present, otherwise the
+ * first entry whose name ends with the same file name. Producers other than
+ * Microsoft's occasionally use a different directory.
+ */
+export function findPart(zip, conventional, fileName) {
+    if (zip.has(conventional))
+        return conventional;
+    return zip.names().find((n) => n.endsWith(`/${fileName}`) || n === fileName) ?? null;
+}