opencode-diane 0.0.5

package/dist/ingest/session-snapshot.js

@@ -0,0 +1,94 @@
+/**
+ * Session snapshots — branchable, versioned "understanding" carried
+ * across sessions.
+ *
+ * The `session-trace` category already records what a *past* session
+ * physically did (files edited, commands run). A snapshot records
+ * something different and harder-won: the *understanding* a session
+ * built up — the mental model, the decisions made, the conventions
+ * learned — the stuff that is normally lost when a context window
+ * fills and compacts.
+ *
+ * This is the harness-side, no-model translation of the
+ * "contextual memory virtualisation" idea: instead of a DAG data
+ * structure, each snapshot is one pinned memory, and the parent link
+ * is just a `parent:<id>` tag. The set of snapshots and their parent
+ * tags *is* the DAG — readable, hand-editable, no new storage shape.
+ *
+ *   - A later session resumes from the most recent snapshot.
+ *   - A parallel session reads the same shared store, so it forks
+ *     from the same point automatically.
+ *   - Recording a new snapshot that tags an older one as `parent`
+ *     is a branch.
+ *
+ * Snapshots are pinned, so the LFU disk-budget eviction never drops
+ * them — accumulated understanding outlives transient facts.
+ */
+const CATEGORY = "session-snapshot";
+/**
+ * Record a session snapshot. `sessionId` keys it; if a snapshot for
+ * the same session already exists it is replaced (a session's
+ * understanding is updated in place, not duplicated). The most recent
+ * *other* session's snapshot is recorded as the `parent` — that link
+ * is what makes the snapshot set a branchable history.
+ */
+export function writeSnapshot(repo, sessionId, input) {
+    const parentId = latestSnapshotId(repo, sessionId);
+    const lines = [input.summary.trim()];
+    if (input.decisions && input.decisions.length > 0) {
+        lines.push("Decisions: " + input.decisions.map((d) => d.trim()).filter(Boolean).join(" | "));
+    }
+    if (input.conventions && input.conventions.length > 0) {
+        lines.push("Conventions: " + input.conventions.map((c) => c.trim()).filter(Boolean).join(" | "));
+    }
+    const content = `Session understanding (${sessionId}): ` + lines.join(". ");
+    const tags = ["session-snapshot", `session:${sessionId}`];
+    if (parentId)
+        tags.push(`parent:${parentId}`);
+    // upsertBySubject → one snapshot per session, replace-in-place.
+    const mem = repo.upsertBySubject({
+        category: CATEGORY,
+        subject: `snapshot:${sessionId}`,
+        content,
+        tags,
+        source: `session:${sessionId}`,
+        pinned: true, // accumulated understanding must outlive eviction
+    });
+    return { id: mem.id, parentId };
+}
+/**
+ * The most recent snapshot to resume from — the newest snapshot that
+ * does NOT belong to `excludeSessionId` (so a session never resumes
+ * from itself). Returns null when there are no prior snapshots.
+ */
+export function latestSnapshot(repo, excludeSessionId) {
+    let best = null;
+    for (const m of repo.allMemories()) {
+        if (m.category !== CATEGORY)
+            continue;
+        if (excludeSessionId && m.subject === `snapshot:${excludeSessionId}`)
+            continue;
+        if (!best || m.createdAt > best.createdAt)
+            best = m;
+    }
+    return best;
+}
+function latestSnapshotId(repo, excludeSessionId) {
+    return latestSnapshot(repo, excludeSessionId)?.id ?? null;
+}
+/**
+ * A compact, human-readable lineage for `memory_status` / logs:
+ * how many snapshots exist and when the most recent was taken.
+ */
+export function snapshotSummary(repo) {
+    let count = 0;
+    let latestAt = null;
+    for (const m of repo.allMemories()) {
+        if (m.category !== CATEGORY)
+            continue;
+        count += 1;
+        if (latestAt === null || m.createdAt > latestAt)
+            latestAt = m.createdAt;
+    }
+    return { count, latestAt };
+}

package/dist/ingest/sessions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Past-session ingestion.
+ *
+ * Pulls user-task + tool-trace summaries from previous OpenCode
+ * sessions in the same project, via the SDK client that the plugin
+ * receives in its context. Sessions live in OpenCode's own SQLite
+ * store; we read them through the documented client API rather than
+ * touching the DB file.
+ *
+ * Without an LLM, we extract two kinds of facts per session:
+ *   1) The user's first message ("the task").
+ *   2) The set of distinct file paths the agent edited/wrote and
+ *      bash commands it ran ("the trace").
+ *
+ * One memory per (sessionId, kind) tuple. Re-ingesting the same
+ * session is idempotent thanks to insertIfMissing.
+ *
+ * Defensive: every SDK call is wrapped — different OpenCode versions
+ * expose slightly different methods (session.list / session.messages)
+ * and the plugin must keep working when one is absent.
+ */
+import type { MemoryRepository } from "../store/repository.js";
+export interface SessionIngestResult {
+    sessions: number;
+    taskMemories: number;
+    traceMemories: number;
+    errors: string[];
+}
+export declare function ingestSessions(repo: MemoryRepository, client: unknown, currentSessionId?: string): Promise<SessionIngestResult>;

package/dist/ingest/sessions.js

@@ -0,0 +1,164 @@
+/**
+ * Past-session ingestion.
+ *
+ * Pulls user-task + tool-trace summaries from previous OpenCode
+ * sessions in the same project, via the SDK client that the plugin
+ * receives in its context. Sessions live in OpenCode's own SQLite
+ * store; we read them through the documented client API rather than
+ * touching the DB file.
+ *
+ * Without an LLM, we extract two kinds of facts per session:
+ *   1) The user's first message ("the task").
+ *   2) The set of distinct file paths the agent edited/wrote and
+ *      bash commands it ran ("the trace").
+ *
+ * One memory per (sessionId, kind) tuple. Re-ingesting the same
+ * session is idempotent thanks to insertIfMissing.
+ *
+ * Defensive: every SDK call is wrapped — different OpenCode versions
+ * expose slightly different methods (session.list / session.messages)
+ * and the plugin must keep working when one is absent.
+ */
+const CATEGORY = "session-trace";
+export async function ingestSessions(repo, client, currentSessionId) {
+    const result = {
+        sessions: 0,
+        taskMemories: 0,
+        traceMemories: 0,
+        errors: [],
+    };
+    const sessions = await safeSessionList(client);
+    if (!sessions) {
+        result.errors.push("SDK session.list unavailable");
+        return result;
+    }
+    for (const s of sessions) {
+        if (!s.id || s.id === currentSessionId)
+            continue;
+        result.sessions += 1;
+        const messages = await safeSessionMessages(client, s.id);
+        if (!messages)
+            continue;
+        const firstUser = messages.find((m) => m.role === "user");
+        if (firstUser) {
+            const taskText = extractText(firstUser);
+            if (taskText) {
+                repo.insertIfMissing({
+                    category: CATEGORY,
+                    subject: `task:${s.id}`,
+                    content: `Task in past session "${s.title ?? s.id}": ${truncate(taskText, 320)}`,
+                    tags: ["task", `session:${s.id}`],
+                    source: `session:${s.id}`,
+                });
+                result.taskMemories += 1;
+            }
+        }
+        const trace = summarizeTrace(messages);
+        if (trace) {
+            repo.insertIfMissing({
+                category: CATEGORY,
+                subject: `trace:${s.id}`,
+                content: trace,
+                tags: ["trace", `session:${s.id}`],
+                source: `session:${s.id}`,
+            });
+            result.traceMemories += 1;
+        }
+    }
+    repo.setIngestedAt(CATEGORY, Date.now());
+    return result;
+}
+async function safeSessionList(client) {
+    const c = client;
+    if (!c?.session?.list)
+        return null;
+    try {
+        const res = (await c.session.list({}));
+        if (Array.isArray(res))
+            return res;
+        if (res && Array.isArray(res.data)) {
+            return res.data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function safeSessionMessages(client, sessionId) {
+    const c = client;
+    if (!c?.session?.messages)
+        return null;
+    try {
+        const res = (await c.session.messages({ path: { id: sessionId } }));
+        if (Array.isArray(res))
+            return res;
+        if (res && Array.isArray(res.data)) {
+            return res.data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/* ─── trace extraction ─────────────────────────────────────────────── */
+function extractText(m) {
+    if (typeof m.content === "string")
+        return m.content;
+    if (Array.isArray(m.parts)) {
+        const out = [];
+        for (const p of m.parts) {
+            if (typeof p === "string")
+                out.push(p);
+            else if (p && typeof p === "object" &&
+                typeof p.text === "string") {
+                out.push(p.text);
+            }
+        }
+        return out.join(" ");
+    }
+    return "";
+}
+function summarizeTrace(messages) {
+    const files = new Set();
+    const bashCmds = [];
+    for (const m of messages) {
+        if (!Array.isArray(m.parts))
+            continue;
+        for (const p of m.parts) {
+            if (!p || typeof p !== "object")
+                continue;
+            const obj = p;
+            const toolName = obj.tool ??
+                (obj.metadata?.tool) ??
+                "";
+            const args = (obj.args ?? obj.input ?? {});
+            if (toolName === "edit" || toolName === "write" || toolName === "multiedit" || toolName === "create") {
+                const fp = args.filePath ??
+                    args.path ??
+                    args.file_path;
+                if (fp)
+                    files.add(fp);
+            }
+            if (toolName === "bash") {
+                const cmd = args.command;
+                if (cmd)
+                    bashCmds.push(truncate(cmd, 80));
+            }
+        }
+    }
+    if (files.size === 0 && bashCmds.length === 0)
+        return null;
+    const parts = [];
+    if (files.size > 0) {
+        parts.push(`edited files: ${Array.from(files).slice(0, 12).join(", ")}`);
+    }
+    if (bashCmds.length > 0) {
+        parts.push(`bash commands: ${bashCmds.slice(0, 6).join(" | ")}`);
+    }
+    return parts.join(". ");
+}
+function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}

package/dist/ingest/tables.d.ts

@@ -0,0 +1,52 @@
+/**
+ * tables.ts — ingest the column headers of tabular files.
+ *
+ * The premise: data files in a repo have structural value (the column
+ * names tell the agent what's in the table — "id, email, signup_date,
+ * plan_tier" is enough to know `users.csv` is the user table) without
+ * the row data being useful for recall (a million rows of values
+ * would just bloat the BM25 index).
+ *
+ * Header-only ingestion is the right slice: high signal, bounded
+ * cost, and the agent can always read the full file on demand via
+ * OpenCode's `read` tool when it actually needs row data.
+ *
+ * **Scope:**
+ *   - `.csv` and `.tsv` — first-line parse, no dependency, never loads
+ *     more than the first 64 KB of the file.
+ *   - `.xlsx`, `.xls`, `.xlsm` — handled via SheetJS (the `xlsx` npm
+ *     package), **lazily imported** only when a spreadsheet is
+ *     actually encountered, so repos with no spreadsheets never pay
+ *     the ~5 MB module-load cost. Each sheet becomes its own memory.
+ *   - Walks the project tree with a generous file cap and the same
+ *     SKIP_DIRS the other ingesters use.
+ *
+ * **CSV parsing.** A small inline parser handles quoted fields,
+ * embedded commas, escaped quotes, and CRLF line endings. Pulling in
+ * a CSV dep for this is not justified.
+ *
+ * **XLSX safety.** SheetJS is invoked with macros, formulas, and
+ * styles disabled — we only need cell values from row 1 of each
+ * sheet, nothing else. This significantly reduces the surface a
+ * hostile workbook could present.
+ */
+import type { MemoryRepository } from "../store/repository.js";
+export interface TablesIngestOptions {
+    maxFiles?: number;
+    maxXlsxMB?: number;
+    maxColumns?: number;
+}
+export interface TablesIngestResult {
+    filesFound: number;
+    /**
+     * Subset of the formats this pass actually covered. CSV/TSV are
+     * always supported. XLSX/XLS appear here only when at least one
+     * spreadsheet was found AND SheetJS was successfully loaded; if
+     * the dependency is missing at runtime the result reports an
+     * `xlsxUnavailableReason` and spreadsheets are silently skipped.
+     */
+    formatsSupported: ReadonlyArray<string>;
+    /** Set if a spreadsheet was found but SheetJS could not be loaded. */
+    xlsxUnavailableReason?: string;
+}
+export declare function ingestTableHeaders(repo: MemoryRepository, root: string, opts?: TablesIngestOptions): Promise<TablesIngestResult>;

package/dist/ingest/tables.js

@@ -0,0 +1,360 @@
+/**
+ * tables.ts — ingest the column headers of tabular files.
+ *
+ * The premise: data files in a repo have structural value (the column
+ * names tell the agent what's in the table — "id, email, signup_date,
+ * plan_tier" is enough to know `users.csv` is the user table) without
+ * the row data being useful for recall (a million rows of values
+ * would just bloat the BM25 index).
+ *
+ * Header-only ingestion is the right slice: high signal, bounded
+ * cost, and the agent can always read the full file on demand via
+ * OpenCode's `read` tool when it actually needs row data.
+ *
+ * **Scope:**
+ *   - `.csv` and `.tsv` — first-line parse, no dependency, never loads
+ *     more than the first 64 KB of the file.
+ *   - `.xlsx`, `.xls`, `.xlsm` — handled via SheetJS (the `xlsx` npm
+ *     package), **lazily imported** only when a spreadsheet is
+ *     actually encountered, so repos with no spreadsheets never pay
+ *     the ~5 MB module-load cost. Each sheet becomes its own memory.
+ *   - Walks the project tree with a generous file cap and the same
+ *     SKIP_DIRS the other ingesters use.
+ *
+ * **CSV parsing.** A small inline parser handles quoted fields,
+ * embedded commas, escaped quotes, and CRLF line endings. Pulling in
+ * a CSV dep for this is not justified.
+ *
+ * **XLSX safety.** SheetJS is invoked with macros, formulas, and
+ * styles disabled — we only need cell values from row 1 of each
+ * sheet, nothing else. This significantly reduces the surface a
+ * hostile workbook could present.
+ */
+import { readdir, open } from "node:fs/promises";
+import { join, relative, sep, extname, basename } from "node:path";
+const CATEGORY = "project-facts";
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "target",
+    ".next",
+    "coverage",
+    ".cache",
+    "vendor",
+]);
+const MAX_FILES = 200;
+const FIRST_LINE_READ_BYTES = 64 * 1024;
+const MAX_XLSX_BYTES = 50 * 1024 * 1024;
+const MAX_COLUMNS_TO_LIST = 40;
+const MAX_SHEETS_PER_WORKBOOK = 20;
+const CSV_EXTS = new Set([".csv", ".tsv"]);
+const XLSX_EXTS = new Set([".xlsx", ".xls", ".xlsm"]);
+export async function ingestTableHeaders(repo, root, opts = {}) {
+    const maxFilesLimit = Math.max(1, Math.round(opts.maxFiles ?? MAX_FILES));
+    const maxXlsxBytes = Math.max(0, (opts.maxXlsxMB ?? MAX_XLSX_BYTES / (1024 * 1024))) * 1024 * 1024;
+    const maxColumnsLimit = Math.max(1, Math.round(opts.maxColumns ?? MAX_COLUMNS_TO_LIST));
+    let filesFound = 0;
+    let sawSpreadsheet = false;
+    let xlsxLoader = null;
+    const formats = new Set(["csv", "tsv"]);
+    let xlsxUnavailableReason;
+    const stack = [root];
+    while (stack.length > 0 && filesFound < maxFilesLimit) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith("."))
+                continue;
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    stack.push(join(dir, e.name));
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            const ext = extname(e.name).toLowerCase();
+            const abs = join(dir, e.name);
+            const rel = relative(root, abs).split(sep).join("/");
+            if (CSV_EXTS.has(ext)) {
+                const columns = await readHeaderColumns(abs, ext === ".tsv" ? "\t" : ",");
+                if (columns === null)
+                    continue;
+                filesFound += 1;
+                emit(repo, rel, ext.slice(1).toUpperCase(), null, columns, maxColumnsLimit);
+            }
+            else if (XLSX_EXTS.has(ext)) {
+                sawSpreadsheet = true;
+                // First spreadsheet seen: lazy-import SheetJS. Promise is
+                // cached so subsequent files reuse the loaded module
+                // without repeated dynamic-import cost.
+                if (!xlsxLoader)
+                    xlsxLoader = loadXlsx();
+                const xlsx = await xlsxLoader;
+                if ("error" in xlsx) {
+                    // SheetJS missing or failed to load — skip ALL spreadsheets
+                    // for this pass and surface the reason. The caller logs
+                    // once; we don't spam per-file warnings.
+                    if (!xlsxUnavailableReason)
+                        xlsxUnavailableReason = xlsx.error;
+                    continue;
+                }
+                const sheets = await readXlsxSheets(xlsx, abs, maxXlsxBytes);
+                if (sheets === null)
+                    continue;
+                filesFound += 1;
+                for (const s of sheets) {
+                    emit(repo, rel, ext.slice(1).toUpperCase(), s.sheetName, s.columns, maxColumnsLimit);
+                }
+            }
+            else {
+                continue;
+            }
+            if (filesFound >= maxFilesLimit)
+                break;
+        }
+    }
+    if (sawSpreadsheet && !xlsxUnavailableReason) {
+        formats.add("xlsx");
+        formats.add("xls");
+    }
+    return {
+        filesFound,
+        formatsSupported: Array.from(formats),
+        ...(xlsxUnavailableReason ? { xlsxUnavailableReason } : {}),
+    };
+}
+function emit(repo, rel, format, sheetName, columns, maxColumns) {
+    const shown = columns.length > maxColumns
+        ? columns.slice(0, maxColumns).join(", ") + `, … (${columns.length - maxColumns} more)`
+        : columns.join(", ");
+    const fileTag = basename(rel, extname(rel)).toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    // Single-cell files (CSV/TSV) → `table:<path>` (unchanged from v0.0.4
+    // first cut). Spreadsheets → `table:<path>#<sheet>` so multi-sheet
+    // workbooks become multiple memories with distinct subjects.
+    const subject = sheetName ? `table:${rel}#${slugifySheet(sheetName)}` : `table:${rel}`;
+    const sheetSuffix = sheetName ? ` sheet "${sheetName}"` : "";
+    repo.insertIfMissing({
+        category: CATEGORY,
+        subject,
+        content: `${rel}${sheetSuffix} (${format}, ${columns.length} columns): ${shown}. ` +
+            `Read the file directly with OpenCode's read tool for row data.`,
+        tags: ["table", "schema", format.toLowerCase(), fileTag, ...(sheetName ? ["sheet"] : [])],
+        source: "tables-ingest",
+    });
+}
+function slugifySheet(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "sheet";
+}
+/* ─── CSV / TSV path ────────────────────────────────────────────────── */
+async function readHeaderColumns(abs, delimiter) {
+    let handle;
+    try {
+        handle = await open(abs, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() || s.size === 0)
+            return null;
+        const bytesToRead = Math.min(s.size, FIRST_LINE_READ_BYTES);
+        const buf = Buffer.alloc(bytesToRead);
+        const { bytesRead } = await handle.read(buf, 0, bytesToRead, 0);
+        if (bytesRead === 0)
+            return null;
+        const text = buf.subarray(0, bytesRead).toString("utf-8");
+        if (text.indexOf("\0") >= 0)
+            return null;
+        const firstLineEnd = findLineTerminator(text);
+        const firstLine = firstLineEnd === -1 ? text : text.slice(0, firstLineEnd);
+        if (firstLine.length === 0)
+            return null;
+        const cols = parseDelimitedLine(firstLine, delimiter);
+        if (cols.length < 2)
+            return null;
+        if (cols.some((c) => c.length > 200))
+            return null;
+        return cols.map((c) => c.trim()).filter((c) => c.length > 0);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function findLineTerminator(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c === 10 || c === 13)
+            return i;
+    }
+    return -1;
+}
+function parseDelimitedLine(line, delimiter) {
+    const out = [];
+    let cur = "";
+    let i = 0;
+    while (i < line.length) {
+        const c = line[i];
+        if (c === '"') {
+            i += 1;
+            while (i < line.length) {
+                const d = line[i];
+                if (d === '"') {
+                    if (line[i + 1] === '"') {
+                        cur += '"';
+                        i += 2;
+                    }
+                    else {
+                        i += 1;
+                        break;
+                    }
+                }
+                else {
+                    cur += d;
+                    i += 1;
+                }
+            }
+        }
+        else if (c === delimiter) {
+            out.push(cur);
+            cur = "";
+            i += 1;
+        }
+        else {
+            cur += c;
+            i += 1;
+        }
+    }
+    out.push(cur);
+    return out;
+}
+/**
+ * Lazy-load SheetJS. The dynamic import is the whole reason this
+ * exists — a repo with no spreadsheets never triggers it, and the
+ * ~5 MB module-load cost is amortised across every workbook in the
+ * pass once it does. Caller caches the returned promise.
+ *
+ * If the dependency is missing or fails to load, we return a value
+ * with an `error` field — callers degrade to skipping spreadsheets
+ * silently rather than crashing the whole ingest.
+ */
+async function loadXlsx() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import("xlsx");
+        return mod.default ?? mod;
+    }
+    catch (err) {
+        return { error: `xlsx (SheetJS) could not be loaded: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Open a workbook and pull row-1 cell values from every sheet. We
+ * read the whole file from disk (SheetJS doesn't stream) but pass
+ * read options that disable macros, formulas, styles, and number-
+ * format parsing — all of which we don't need and which add to both
+ * the work and the attack surface a hostile workbook could present.
+ *
+ * Returns null on any failure (missing file, parse error, oversized,
+ * etc.) — same contract as the CSV path: a problematic file is
+ * silently skipped, never fatal.
+ */
+async function readXlsxSheets(xlsx, abs, maxBytes = MAX_XLSX_BYTES) {
+    let handle;
+    try {
+        handle = await open(abs, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() || s.size === 0 || s.size > maxBytes)
+            return null;
+    }
+    finally {
+        await handle.close();
+    }
+    let wb;
+    try {
+        wb = xlsx.readFile(abs, {
+            // Minimum-surface read: we only want cell values from row 1.
+            cellFormula: false,
+            cellHTML: false,
+            cellNF: false,
+            cellStyles: false,
+            cellText: false,
+            cellDates: false,
+            bookVBA: false,
+            bookFiles: false,
+            bookProps: false,
+            bookSheets: false,
+        });
+    }
+    catch {
+        return null;
+    }
+    const sheets = [];
+    const names = Array.isArray(wb?.SheetNames) ? wb.SheetNames.slice(0, MAX_SHEETS_PER_WORKBOOK) : [];
+    for (const name of names) {
+        const ws = wb.Sheets?.[name];
+        if (!ws)
+            continue;
+        const cols = extractHeaderRowFromSheet(xlsx, ws);
+        if (cols.length < 2)
+            continue;
+        sheets.push({ sheetName: String(name), columns: cols });
+    }
+    return sheets.length > 0 ? sheets : null;
+}
+/**
+ * Pull cell values from row 1 of one worksheet by walking the sheet's
+ * declared range. We deliberately read cells directly (`ws[A1]`,
+ * `ws[B1]`, …) rather than `sheet_to_json` so the full row block
+ * past row 1 is never materialised. A sheet with 1 M rows costs the
+ * same as a sheet with 10.
+ */
+function extractHeaderRowFromSheet(xlsx, ws) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sheet = ws;
+    const ref = typeof sheet["!ref"] === "string" ? sheet["!ref"] : null;
+    if (!ref)
+        return [];
+    let range;
+    try {
+        range = xlsx.utils.decode_range(ref);
+    }
+    catch {
+        return [];
+    }
+    if (!range || !range.s || !range.e)
+        return [];
+    const row = range.s.r;
+    const out = [];
+    for (let c = range.s.c; c <= range.e.c; c++) {
+        if (out.length >= 200)
+            break;
+        const addr = xlsx.utils.encode_cell({ r: row, c });
+        const cell = sheet[addr];
+        const v = cell?.v;
+        if (v === undefined || v === null) {
+            out.push("");
+            continue;
+        }
+        out.push(String(v));
+    }
+    // Drop trailing empty cells — common when a sheet has stray cells
+    // far to the right of the real table.
+    while (out.length > 0 && out[out.length - 1] === "")
+        out.pop();
+    return out.map((c) => c.trim()).filter((c) => c.length > 0);
+}