studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/services/comment-service.js

@@ -0,0 +1,341 @@
+import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { looksLikeCellAnchor, isValidCellAnchor } from '../core/cell-anchor.js';
+function generateCommentId() {
+    // 9 bytes → 12-char base64url ≈ 72 bits of entropy; collision risk negligible at any realistic scale.
+    return `cmt_${randomBytes(9).toString('base64url')}`;
+}
+/**
+ * Bump when columns are added/removed/renamed. The boot path runs every
+ * registered migration whose version is greater than the recorded
+ * `schema_version` in the meta table; pattern mirrors
+ * core/secrets/SqliteEncryptedStore.ts.
+ */
+const SCHEMA_VERSION = 1;
+/** Largest comment body the service will accept. Above this the route
+ *  returns 413 — Fastify bodyLimit is the outer 10MB wall, this is the
+ *  per-comment policy ceiling. */
+export const MAX_BODY_LENGTH = 8 * 1024;
+export const MAX_ANCHOR_RELPOS_LENGTH = 4 * 1024;
+/** Sentinel author_user_id used for agent-authored comments. The auth.db
+ *  users table is AUTOINCREMENT (starts at 1), so id=0 can never collide
+ *  with a real user. */
+export const AGENT_AUTHOR_USER_ID = 0;
+/** Thrown by create() when body or anchor_relpos exceeds the ceiling. */
+export class CommentTooLargeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CommentTooLargeError';
+    }
+}
+/** Thrown by create() when a cell (JSON) anchor is malformed, or when a JSON
+ *  cell anchor is attached to a non-dataset entry (markdown comments only ever
+ *  carry a base64 text relpos or a null entry-level anchor). The route maps it
+ *  to HTTP 400. */
+export class InvalidCellAnchorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCellAnchorError';
+    }
+}
+export class CommentService {
+    db;
+    constructor(workspacePath) {
+        const sgDir = join(workspacePath, '.studiograph');
+        if (!existsSync(sgDir))
+            mkdirSync(sgDir, { recursive: true });
+        const dbPath = join(sgDir, 'comments.db');
+        this.db = new Database(dbPath);
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS comments (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        comment_id TEXT UNIQUE NOT NULL,
+        repo TEXT NOT NULL,
+        entry_type TEXT NOT NULL,
+        entry_id TEXT NOT NULL,
+        thread_id TEXT NOT NULL,
+        parent_id TEXT,
+        author_user_id INTEGER NOT NULL,
+        author_display_name TEXT NOT NULL,
+        author_role TEXT NOT NULL DEFAULT 'user' CHECK(author_role IN ('user', 'agent')),
+        body TEXT NOT NULL,
+        anchor_relpos TEXT,
+        anchor_quote TEXT,
+        mentions TEXT NOT NULL DEFAULT '[]',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT,
+        resolved_at TEXT,
+        resolved_by_user_id INTEGER,
+        edited INTEGER NOT NULL DEFAULT 0 CHECK(edited IN (0, 1)),
+        edit_history TEXT NOT NULL DEFAULT '[]',
+        deleted_at TEXT
+      )
+    `);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_comments_entry ON comments(repo, entry_type, entry_id, resolved_at)`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_comments_thread ON comments(thread_id, created_at)`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_comments_unresolved ON comments(resolved_at) WHERE resolved_at IS NULL`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_comments_repo_unresolved ON comments(repo, entry_type, entry_id) WHERE resolved_at IS NULL AND deleted_at IS NULL`);
+        // Schema-version scaffold so future column changes (reactions, etc.)
+        // can run through an ALTER TABLE migration step instead of silently
+        // skipping on databases created against an older shape. Pattern
+        // mirrors core/secrets/SqliteEncryptedStore.ts.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+        this.runMigrations();
+    }
+    /**
+     * Idempotent: each migration step is guarded by the recorded
+     * `schema_version` in `meta`. Add a new branch when bumping
+     * `SCHEMA_VERSION`; never edit existing branches.
+     */
+    runMigrations() {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
+        const current = row ? parseInt(row.value, 10) || 0 : 0;
+        if (current >= SCHEMA_VERSION)
+            return;
+        // Future migrations live here:
+        //   if (current < 2) { this.db.exec(`ALTER TABLE comments ADD COLUMN ...`); }
+        //   if (current < 3) { ... }
+        this.db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)').run('schema_version', String(SCHEMA_VERSION));
+    }
+    create(input) {
+        // Resource bounds — Fastify bodyLimit is 10MB, but comment bodies
+        // shouldn't approach that. A user with repo write access could
+        // otherwise balloon comments.db with a few well-crafted POSTs.
+        if (input.body.length > MAX_BODY_LENGTH) {
+            throw new CommentTooLargeError(`Comment body exceeds ${MAX_BODY_LENGTH} characters`);
+        }
+        if (input.anchorRelpos && input.anchorRelpos.length > MAX_ANCHOR_RELPOS_LENGTH) {
+            throw new CommentTooLargeError(`Anchor relpos exceeds ${MAX_ANCHOR_RELPOS_LENGTH} characters`);
+        }
+        // Cell (JSON) anchors are dataset-only. A markdown comment's anchor is a
+        // base64 relpos blob (never starts with '{'); only datasets carry the
+        // `{"kind":"cell",…}` shape, validated here so a malformed anchor can't
+        // land in the column and a JSON anchor can't reach the text resolver.
+        if (looksLikeCellAnchor(input.anchorRelpos)) {
+            if (input.entryType !== 'dataset') {
+                throw new InvalidCellAnchorError('Cell anchors are only valid on dataset entries');
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(input.anchorRelpos);
+            }
+            catch {
+                throw new InvalidCellAnchorError('Cell anchor is not valid JSON');
+            }
+            if (!isValidCellAnchor(parsed)) {
+                throw new InvalidCellAnchorError('Cell anchor is structurally invalid');
+            }
+        }
+        const anchorQuote = input.anchorQuote
+            ? (input.anchorQuote.length > 256 ? input.anchorQuote.slice(0, 256) : input.anchorQuote)
+            : null;
+        const insert = this.db.prepare(`
+      INSERT INTO comments
+        (comment_id, repo, entry_type, entry_id, thread_id, parent_id,
+         author_user_id, author_display_name, author_role, body,
+         anchor_relpos, anchor_quote, mentions)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        // Retry on UNIQUE collision. 72-bit IDs make collisions astronomically
+        // unlikely, but a sane caller shouldn't see HTTP 500 on the off-chance.
+        let commentId = '';
+        let lastErr = null;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            commentId = generateCommentId();
+            const threadId = input.threadId ?? input.parentId ?? commentId;
+            try {
+                insert.run(commentId, input.repo, input.entryType, input.entryId, threadId, input.parentId ?? null, input.authorUserId, input.authorDisplayName, input.authorRole ?? 'user', input.body, input.anchorRelpos ?? null, anchorQuote, JSON.stringify(input.mentions ?? []));
+                lastErr = null;
+                break;
+            }
+            catch (err) {
+                const msg = err.message ?? '';
+                if (!msg.includes('UNIQUE constraint failed: comments.comment_id'))
+                    throw err;
+                lastErr = err;
+            }
+        }
+        if (lastErr)
+            throw lastErr;
+        return this.getById(commentId);
+    }
+    getById(commentId) {
+        const row = this.db.prepare(`
+      SELECT * FROM comments WHERE comment_id = ?
+    `).get(commentId);
+        return row ? this.toComment(row) : null;
+    }
+    /** Batch lookup used by the notifications route to enrich each notification
+     *  with its source comment's entry coords. Returns a map keyed by commentId
+     *  so callers can do a single pass. Missing ids are absent from the map. */
+    getByIds(commentIds) {
+        const out = new Map();
+        if (commentIds.length === 0)
+            return out;
+        const placeholders = commentIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT * FROM comments WHERE comment_id IN (${placeholders})`).all(...commentIds);
+        for (const row of rows) {
+            const c = this.toComment(row);
+            out.set(c.commentId, c);
+        }
+        return out;
+    }
+    list(opts = {}) {
+        const where = [];
+        const args = [];
+        if (opts.repo) {
+            where.push('repo = ?');
+            args.push(opts.repo);
+        }
+        if (opts.entryType) {
+            where.push('entry_type = ?');
+            args.push(opts.entryType);
+        }
+        if (opts.entryId) {
+            where.push('entry_id = ?');
+            args.push(opts.entryId);
+        }
+        if (opts.resolved === false)
+            where.push('resolved_at IS NULL');
+        if (opts.resolved === true)
+            where.push('resolved_at IS NOT NULL');
+        if (!opts.includeDeleted)
+            where.push('deleted_at IS NULL');
+        const clause = where.length ? `WHERE ${where.join(' AND ')}` : '';
+        const limit = Math.min(opts.limit ?? 500, 2000);
+        const rows = this.db.prepare(`SELECT * FROM comments ${clause} ORDER BY thread_id, created_at LIMIT ?`).all(...args, limit);
+        return rows.map(r => this.toComment(r));
+    }
+    edit(commentId, body, editorUserId) {
+        // Wrap read-modify-write in a transaction so concurrent edits by the
+        // same author don't both build edit_history from the same pre-image
+        // and lose the first edit's snapshot.
+        const txn = this.db.transaction(() => {
+            const existing = this.getById(commentId);
+            if (!existing || existing.deletedAt)
+                return null;
+            if (existing.authorUserId !== editorUserId) {
+                throw new Error('Only the author can edit this comment');
+            }
+            const history = [...existing.editHistory, { at: existing.updatedAt ?? existing.createdAt, body: existing.body }];
+            this.db.prepare(`
+        UPDATE comments
+        SET body = ?, updated_at = datetime('now'), edited = 1, edit_history = ?
+        WHERE comment_id = ?
+      `).run(body, JSON.stringify(history), commentId);
+            return this.getById(commentId);
+        });
+        return txn();
+    }
+    resolve(commentId, resolverUserId) {
+        const existing = this.getById(commentId);
+        if (!existing || existing.deletedAt)
+            return null;
+        // Resolve the entire thread (Google Docs semantics — resolve from any reply).
+        // Scope the UPDATE to the same repo/entry the caller is acting on so a
+        // forged thread_id pointing at another folder can't cascade-resolve there.
+        this.db.prepare(`
+      UPDATE comments
+      SET resolved_at = datetime('now'), resolved_by_user_id = ?
+      WHERE thread_id = ?
+        AND repo = ? AND entry_type = ? AND entry_id = ?
+        AND resolved_at IS NULL
+    `).run(resolverUserId, existing.threadId, existing.repo, existing.entryType, existing.entryId);
+        return this.getById(commentId);
+    }
+    reopen(commentId) {
+        const existing = this.getById(commentId);
+        if (!existing || existing.deletedAt)
+            return null;
+        // Same repo/entry scoping as resolve(), plus a resolved_at guard so a
+        // concurrent resolve+reopen race can't clobber a freshly-resolved thread
+        // without us noticing.
+        this.db.prepare(`
+      UPDATE comments
+      SET resolved_at = NULL, resolved_by_user_id = NULL
+      WHERE thread_id = ?
+        AND repo = ? AND entry_type = ? AND entry_id = ?
+        AND resolved_at IS NOT NULL
+    `).run(existing.threadId, existing.repo, existing.entryType, existing.entryId);
+        return this.getById(commentId);
+    }
+    /** Soft-delete: keeps thread continuity, blanks the visible body but
+     *  preserves the original in edit_history so a future audit/restore
+     *  path has something to recover. */
+    softDelete(commentId, requesterUserId) {
+        // Atomic so the edit_history append + body blank happen together.
+        const txn = this.db.transaction(() => {
+            const existing = this.getById(commentId);
+            if (!existing)
+                return null;
+            if (existing.authorUserId !== requesterUserId) {
+                throw new Error('Only the author can delete this comment');
+            }
+            if (existing.deletedAt)
+                return existing;
+            const history = [
+                ...existing.editHistory,
+                { at: existing.updatedAt ?? existing.createdAt, body: existing.body },
+            ];
+            this.db.prepare(`
+        UPDATE comments
+        SET deleted_at = datetime('now'), body = '', edit_history = ?
+        WHERE comment_id = ?
+      `).run(JSON.stringify(history), commentId);
+            return this.getById(commentId);
+        });
+        return txn();
+    }
+    close() {
+        this.db.close();
+    }
+    toComment(row) {
+        let mentions = [];
+        try {
+            mentions = JSON.parse(row.mentions ?? '[]');
+        }
+        catch { /* default [] */ }
+        let editHistory = [];
+        try {
+            editHistory = JSON.parse(row.edit_history ?? '[]');
+        }
+        catch { /* default [] */ }
+        return {
+            commentId: row.comment_id,
+            repo: row.repo,
+            entryType: row.entry_type,
+            entryId: row.entry_id,
+            threadId: row.thread_id,
+            parentId: row.parent_id ?? null,
+            authorUserId: row.author_user_id,
+            authorDisplayName: row.author_display_name,
+            authorRole: row.author_role,
+            body: row.body,
+            anchorRelpos: row.anchor_relpos ?? null,
+            anchorQuote: row.anchor_quote ?? null,
+            mentions,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at ?? null,
+            resolvedAt: row.resolved_at ?? null,
+            resolvedByUserId: row.resolved_by_user_id ?? null,
+            edited: row.edited === 1 ? 1 : 0,
+            editHistory,
+            deletedAt: row.deleted_at ?? null,
+        };
+    }
+}
+//# sourceMappingURL=comment-service.js.map

package/dist/services/comment-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-service.js","sourceRoot":"","sources":["../../src/services/comment-service.ts"],"names":[],"mappings":"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"}

package/dist/services/comment-virtual-entity.d.ts

@@ -0,0 +1,36 @@
+import type { CommentService } from './comment-service.js';
+/**
+ * Comments live in SQLite for throughput, but agents should see them as
+ * first-class typed entities just like notes, projects, etc. This adapter
+ * shapes a Comment row into the same `{ id, entityType, data, content }`
+ * envelope that file-backed entities use, so generic MCP tools (`get_entity`,
+ * `list_entities`, `find_related`) can return comments without per-type
+ * branches in the tool code itself.
+ *
+ * The shape mirrors what `wm.getGraph(repo).get(...)` returns from
+ * filesystem entities: `id` is the comment_id (used in MCP URIs), `entityType`
+ * is the literal ‘comment’, `data` is frontmatter-flat with comment metadata,
+ * and `content` is the comment body.
+ */
+export interface VirtualEntityEnvelope {
+    id: string;
+    entityType: 'comment';
+    data: Record<string, unknown>;
+    document: {
+        content: string;
+        wikilinks: string[];
+    };
+}
+export declare function getComment(commentService: CommentService, commentId: string): VirtualEntityEnvelope | null;
+export declare function listComments(commentService: CommentService, opts?: {
+    repo?: string;
+    entryType?: string;
+    entryId?: string;
+    resolved?: boolean;
+    limit?: number;
+}): VirtualEntityEnvelope[];
+/**
+ * Comments anchored to a given entry — exposed as backlinks of that entry
+ * so `find_related` includes them naturally.
+ */
+export declare function findRelatedComments(commentService: CommentService, repo: string, entityType: string, entityId: string): VirtualEntityEnvelope[];

package/dist/services/comment-virtual-entity.js

@@ -0,0 +1,71 @@
+import { parseCellAnchor } from '../core/cell-anchor.js';
+function toEnvelope(c) {
+    // For dataset cell comments the anchor is JSON in anchor_relpos — surface
+    // the column + row snapshot so an agent reading the comment as an entity can
+    // locate the cell, not just see the bare cell value.
+    const cell = parseCellAnchor(c.anchorRelpos);
+    return {
+        id: c.commentId,
+        entityType: 'comment',
+        data: {
+            entity_type: 'comment',
+            entity_id: c.commentId,
+            created_at: c.createdAt,
+            updated_at: c.updatedAt ?? c.createdAt,
+            created_by: c.authorDisplayName,
+            updated_by: c.authorDisplayName,
+            // Comment-specific fields. Naming matches the SQL schema for
+            // consistency with the public REST API.
+            repo: c.repo,
+            entry_type: c.entryType,
+            entry_id: c.entryId,
+            thread_id: c.threadId,
+            parent_id: c.parentId,
+            author_user_id: c.authorUserId,
+            author_role: c.authorRole,
+            anchor_quote: c.anchorQuote,
+            ...(cell
+                ? {
+                    anchor_cell: {
+                        column: cell.headerName,
+                        column_index: cell.columnIndex,
+                        ...(cell.rowCells ? { row_cells: cell.rowCells } : {}),
+                    },
+                }
+                : {}),
+            resolved_at: c.resolvedAt,
+            resolved_by_user_id: c.resolvedByUserId,
+            edited: c.edited === 1,
+            mentions: c.mentions.map(m => m.handle),
+        },
+        document: { content: c.body, wikilinks: extractWikilinks(c.body) },
+    };
+}
+const WIKILINK_RE = /\[\[([^\]|#]+)(?:\|[^\]]+)?\]\]/g;
+function extractWikilinks(body) {
+    const out = [];
+    for (const match of body.matchAll(WIKILINK_RE)) {
+        if (match[1])
+            out.push(match[1].trim());
+    }
+    return out;
+}
+export function getComment(commentService, commentId) {
+    const c = commentService.getById(commentId);
+    if (!c || c.deletedAt)
+        return null;
+    return toEnvelope(c);
+}
+export function listComments(commentService, opts = {}) {
+    return commentService.list(opts).map(toEnvelope);
+}
+/**
+ * Comments anchored to a given entry — exposed as backlinks of that entry
+ * so `find_related` includes them naturally.
+ */
+export function findRelatedComments(commentService, repo, entityType, entityId) {
+    return commentService
+        .list({ repo, entryType: entityType, entryId: entityId })
+        .map(toEnvelope);
+}
+//# sourceMappingURL=comment-virtual-entity.js.map

package/dist/services/comment-virtual-entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-virtual-entity.js","sourceRoot":"","sources":["../../src/services/comment-virtual-entity.ts"],"names":[],"mappings":"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"}

package/dist/services/convert-service.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Convert Service — pure document→content converters.
+ *
+ * These are buffer/text in → content out: deterministic, no LLM, no storage,
+ * no graph mutation. They seed the bodies of typed entities at import time
+ * (`asset-import-service.ts`, the asset-as-embed flow).
+ *
+ *   - `convertXlsxToDatasets` (here) — structural xlsx → one CSV per sheet.
+ *   - `convertDocxToMarkdown` / `convertPdfToNoteText` — text-extraction
+ *     heuristics that live in `./extract/` and are re-exported below.
+ *
+ * The deferred asset→entry "convert" orchestrator (and its HTTP endpoint +
+ * `convert_asset` agent tool) were removed in Phase E: import now creates a
+ * typed entity that embeds the asset directly, so there is no post-hoc
+ * conversion step.
+ */
+import { convertDocxToMarkdown, convertPdfToNoteText } from './extract/index.js';
+export { convertDocxToMarkdown, convertPdfToNoteText };
+/** Above this many sheets, the caller falls a workbook back to a single
+ *  `material` rather than fanning it out into that many dataset entities (no
+ *  unbounded entity/commit fan-out — Codex). Gated on the RAW tab count so we
+ *  never run the per-sheet CSV conversion just to count. */
+export declare const XLSX_SHEET_CAP = 20;
+/**
+ * Upper bound (bytes) on a doc fed to the synchronous, request-thread parsers
+ * (mammoth for docx, SheetJS for xlsx). The upload route already caps storage
+ * at 100MB, but a 100MB workbook can decompress to billions of cells and stall
+ * the event loop / exhaust memory before any sheet cap applies, so import
+ * refuses oversized docs up front (degrading them to a download-only material).
+ * NOTE: this bounds the INPUT but does not sandbox the parse — moving
+ * SheetJS/mammoth to a worker with hard CPU/row limits, and upgrading SheetJS
+ * past its npm-pinned 0.18.5 advisories, is the deeper follow-up.
+ */
+export declare const CONVERT_MAX_BYTES: number;
+export interface ConvertedSheet {
+    /** Original worksheet name (e.g. "Q1 Budget"). */
+    sheetName: string;
+    /** Display name for the derived dataset: `<file> — <sheet>`. */
+    name: string;
+    /** CSV body (header = row 1, computed cell values — v1). */
+    csv: string;
+}
+export interface XlsxConversion {
+    sheets: ConvertedSheet[];
+    /** Non-empty sheet count (= sheets.length), OR the raw tab count when
+     *  `exceededCap` is set (conversion skipped). */
+    totalSheets: number;
+    /** True when the workbook's RAW tab count exceeded `maxSheets`, so the
+     *  per-sheet CSV conversion was skipped entirely (DoS guard). */
+    exceededCap?: boolean;
+}
+/**
+ * Excel (.xlsx) → one dataset per NON-EMPTY sheet (D5). v1: header is row 1,
+ * cells are their computed values (SheetJS `sheet_to_csv` resolves formulas to
+ * their cached results). Empty sheets are skipped. Dataset names are
+ * `<baseName> — <sheetName>`.
+ *
+ * `opts.maxSheets` gates on the RAW tab count BEFORE any per-sheet conversion:
+ * a workbook with more tabs than the cap returns `{ exceededCap: true }`
+ * without running `sheet_to_csv` N times, so the caller can fall back cheaply.
+ */
+export declare function convertXlsxToDatasets(buffer: Buffer, baseName: string, opts?: {
+    maxSheets?: number;
+}): XlsxConversion;

package/dist/services/convert-service.js

@@ -0,0 +1,68 @@
+/**
+ * Convert Service — pure document→content converters.
+ *
+ * These are buffer/text in → content out: deterministic, no LLM, no storage,
+ * no graph mutation. They seed the bodies of typed entities at import time
+ * (`asset-import-service.ts`, the asset-as-embed flow).
+ *
+ *   - `convertXlsxToDatasets` (here) — structural xlsx → one CSV per sheet.
+ *   - `convertDocxToMarkdown` / `convertPdfToNoteText` — text-extraction
+ *     heuristics that live in `./extract/` and are re-exported below.
+ *
+ * The deferred asset→entry "convert" orchestrator (and its HTTP endpoint +
+ * `convert_asset` agent tool) were removed in Phase E: import now creates a
+ * typed entity that embeds the asset directly, so there is no post-hoc
+ * conversion step.
+ */
+import * as XLSX from 'xlsx';
+// Per-format text-extraction heuristics live in ./extract/ (kept apart from the
+// structural xlsx converter below); re-exported so existing importers are stable.
+import { convertDocxToMarkdown, convertPdfToNoteText } from './extract/index.js';
+export { convertDocxToMarkdown, convertPdfToNoteText };
+/** Above this many sheets, the caller falls a workbook back to a single
+ *  `material` rather than fanning it out into that many dataset entities (no
+ *  unbounded entity/commit fan-out — Codex). Gated on the RAW tab count so we
+ *  never run the per-sheet CSV conversion just to count. */
+export const XLSX_SHEET_CAP = 20;
+/**
+ * Upper bound (bytes) on a doc fed to the synchronous, request-thread parsers
+ * (mammoth for docx, SheetJS for xlsx). The upload route already caps storage
+ * at 100MB, but a 100MB workbook can decompress to billions of cells and stall
+ * the event loop / exhaust memory before any sheet cap applies, so import
+ * refuses oversized docs up front (degrading them to a download-only material).
+ * NOTE: this bounds the INPUT but does not sandbox the parse — moving
+ * SheetJS/mammoth to a worker with hard CPU/row limits, and upgrading SheetJS
+ * past its npm-pinned 0.18.5 advisories, is the deeper follow-up.
+ */
+export const CONVERT_MAX_BYTES = 25 * 1024 * 1024;
+/**
+ * Excel (.xlsx) → one dataset per NON-EMPTY sheet (D5). v1: header is row 1,
+ * cells are their computed values (SheetJS `sheet_to_csv` resolves formulas to
+ * their cached results). Empty sheets are skipped. Dataset names are
+ * `<baseName> — <sheetName>`.
+ *
+ * `opts.maxSheets` gates on the RAW tab count BEFORE any per-sheet conversion:
+ * a workbook with more tabs than the cap returns `{ exceededCap: true }`
+ * without running `sheet_to_csv` N times, so the caller can fall back cheaply.
+ */
+export function convertXlsxToDatasets(buffer, baseName, opts) {
+    const workbook = XLSX.read(buffer, { type: 'buffer' });
+    const names = workbook.SheetNames;
+    if (opts?.maxSheets != null && names.length > opts.maxSheets) {
+        return { sheets: [], totalSheets: names.length, exceededCap: true };
+    }
+    const sheets = [];
+    for (const sheetName of names) {
+        const sheet = workbook.Sheets[sheetName];
+        // A sheet with no `!ref` has no cells at all; sheet_to_csv on it yields
+        // ''. Skip those so an empty tab doesn't become an empty dataset.
+        if (!sheet || !sheet['!ref'])
+            continue;
+        const csv = XLSX.utils.sheet_to_csv(sheet, { blankrows: false }).trim();
+        if (!csv)
+            continue;
+        sheets.push({ sheetName, name: `${baseName} — ${sheetName}`, csv });
+    }
+    return { sheets, totalSheets: sheets.length };
+}
+//# sourceMappingURL=convert-service.js.map

package/dist/services/convert-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-service.js","sourceRoot":"","sources":["../../src/services/convert-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,gFAAgF;AAChF,kFAAkF;AAClF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAEvD;;;4DAG4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAqBlD;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,QAAgB,EAChB,IAA6B;IAE7B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC;IAClC,IAAI,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7D,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACzC,wEAAwE;QACxE,kEAAkE;QAClE,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,SAAS;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACxE,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,QAAQ,MAAM,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;AAChD,CAAC"}