studiograph 1.3.48-next.2 → 1.3.48-next.201

package/dist/services/extract/docx.js

@@ -0,0 +1,233 @@
+/**
+ * Word (.docx) → Markdown — the docx extraction heuristics, isolated from the
+ * authoritative convert pipeline (../convert-service.ts).
+ *
+ * Best-effort, frequently-tuned "make the extracted text readable" code with NO
+ * graph/storage side effects: buffer in → markdown out, deterministic, no LLM.
+ * mammoth extracts semantic HTML; turndown renders it; the rules below handle
+ * the structures Word leans on that plain turndown / GFM otherwise mangle:
+ *
+ *  - Images are DROPPED (mammoth would otherwise inline multi-hundred-KB base64
+ *    `data:` URIs straight into the body).
+ *  - Tables: Word emits `<td>` for EVERY cell (never `<th>`) and uses tables for
+ *    LAYOUT as much as for data, so neither plain turndown nor turndown-plugin-
+ *    gfm handles them (gfm only fires on `<th>` heading rows; everything else it
+ *    keeps as raw HTML). We classify each table by SHAPE and render accordingly:
+ *      • clean rectangular grid (no merged cells), every cell single-line → a
+ *        real GFM markdown table (row 1 as the header) — e.g. a Fees/Schedule.
+ *      • 2-column that reads as section layout (short left LABEL + substantial
+ *        right BODY in most rows) → left cell becomes a `##` heading, right its
+ *        body — e.g. "Assignment | …".
+ *      • 2-column that reads as data (short values both sides) → `label: value`
+ *        pairs, so the row relationship survives (not a wall of paragraphs).
+ *      • anything else → flatten: each cell its own block.
+ *    A cell's inner table is converted independently (nested tables recurse, up
+ *    to a depth cap); `colspan`/`rowspan` force the flatten path since they
+ *    break the clean-grid assumption GFM + the heading layout rely on.
+ *  - Word wraps ordered lists as `<ul><li><ol>…</ol></li></ul>` (a bullet whose
+ *    only child is a list); that LI is unwrapped so it doesn't render as a
+ *    spurious "* 1." double marker.
+ *  - Turndown's backslash escaping of `[ ] _` is relaxed for reading text
+ *    (placeholders, signature underscore runs), but ONLY outside code spans /
+ *    fenced blocks so literal code is never rewritten.
+ */
+import TurndownService from 'turndown';
+/** Left-cell text longer than this isn't treated as a section label (so the
+ *  side-by-side signature block, whose cells are long, flattens instead). */
+const MAX_LABEL_LEN = 60;
+/** Nested-table recursion cap — past this, a table is emitted as plain text
+ *  rather than recursing further (guards pathological deeply-nested docs). */
+const MAX_TABLE_DEPTH = 8;
+export async function convertDocxToMarkdown(buffer) {
+    const mammoth = await import('mammoth');
+    const { value: html } = await mammoth.convertToHtml({ buffer }, 
+    // Drop embedded images entirely (no base64 src reaches turndown).
+    { convertImage: mammoth.images.imgElement(() => Promise.resolve({ src: '' })) });
+    const md = buildTurndown().turndown(html ?? '');
+    return cleanup(md);
+}
+function buildTurndown() {
+    const turndown = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' });
+    // Emit nothing for any <img> (convertImage already stripped the base64 src;
+    // this drops the element so no empty `![]()` litters the body).
+    turndown.addRule('dropImages', { filter: 'img', replacement: () => '' });
+    // Word wraps ordered lists as <ul><li><ol>…</ol></li></ul>. Unwrap a list item
+    // whose ONLY child is a nested list so it emits just the inner list (no leading
+    // "* " bullet stacked on the "1." marker).
+    turndown.addRule('unwrapNestedListItem', {
+        filter: (node) => node.nodeName === 'LI' && onlyChildIsList(node),
+        replacement: (content) => content,
+    });
+    // Tables: walk the DOM directly and convert each cell with a nested turndown
+    // pass, so one rule can choose a GFM grid, a heading/label layout, or a block
+    // flatten per table (see module doc). Returning the whole table from here also
+    // short-circuits turndown's per-cell processing, so no `<table>` HTML leaks.
+    // `depth` bounds the nested-turndown recursion: each table-rule entry is one
+    // level, so a table-in-a-cell-in-a-table can't recurse without bound.
+    let depth = 0;
+    turndown.addRule('table', {
+        filter: 'table',
+        replacement: (_content, node) => {
+            const table = node;
+            if (depth >= MAX_TABLE_DEPTH) {
+                return `\n\n${(table.textContent ?? '').trim()}\n\n`;
+            }
+            depth++;
+            try {
+                // `depth` (1 = top-level, 2 = nested in a cell, …) sets heading level so
+                // a nested table's section labels sit UNDER their parent, not as peers.
+                return `\n\n${renderTable(table, turndown, depth)}\n\n`;
+            }
+            finally {
+                depth--;
+            }
+        },
+    });
+    return turndown;
+}
+/** True for a list item whose only meaningful child is a nested <ol>/<ul>
+ *  (ignoring whitespace-only text nodes) — Word's ordered-list wrapper shape. */
+function onlyChildIsList(li) {
+    const meaningful = Array.from(li.childNodes).filter((n) => !(n.nodeType === 3 && !(n.textContent ?? '').trim()));
+    return (meaningful.length === 1 &&
+        (meaningful[0].nodeName === 'OL' || meaningful[0].nodeName === 'UL'));
+}
+/** This table's DIRECT rows only — `<tr>` that are direct children or one level
+ *  under `<thead>/<tbody>/<tfoot>`. Never descends into a cell, so a nested
+ *  table's rows stay with the nested table (DOM `.rows` wrongly includes them). */
+function directRows(table) {
+    const out = [];
+    for (const child of Array.from(table.childNodes)) {
+        if (child.nodeName === 'TR')
+            out.push(child);
+        else if (['THEAD', 'TBODY', 'TFOOT'].includes(child.nodeName)) {
+            for (const tr of Array.from(child.childNodes)) {
+                if (tr.nodeName === 'TR')
+                    out.push(tr);
+            }
+        }
+    }
+    return out;
+}
+/** A row's DIRECT cells — `<td>/<th>` children of this `<tr>` (a nested table's
+ *  cells belong to its own rows, never directly to this one). */
+function directCells(row) {
+    return Array.from(row.childNodes).filter((n) => n.nodeName === 'TD' || n.nodeName === 'TH');
+}
+/** A cell that spans multiple columns/rows. Merged cells break the rectangular
+ *  assumption GFM + the 2-col layout rely on, so a table with any forces flatten. */
+function cellSpans(cell) {
+    const col = Number(cell.getAttribute?.('colspan') ?? '1') || 1;
+    const row = Number(cell.getAttribute?.('rowspan') ?? '1') || 1;
+    return col > 1 || row > 1;
+}
+/** Convert one table to markdown by shape. `td`/`th` content is produced by a
+ *  nested turndown pass (so nested lists/paragraphs/tables come through).
+ *  `depth` (1 = top-level) sets the heading level for the section-layout path. */
+function renderTable(table, turndown, depth) {
+    const rowNodes = directRows(table);
+    const spanned = rowNodes.some((r) => directCells(r).some(cellSpans));
+    const rows = rowNodes.map((r) => directCells(r).map((c) => turndown.turndown(c.innerHTML).trim()));
+    if (!rows.length)
+        return '';
+    const cols = rows[0].length;
+    const uniform = rows.every((r) => r.length === cols);
+    const anyMultiline = rows.some((r) => r.some((c) => c.includes('\n')));
+    // 1) Clean rectangular grid of single-line cells → a real GFM table (row 1 =
+    //    header). Merged cells (`spanned`) skip this — the grid isn't rectangular.
+    if (!spanned && uniform && rows.length >= 2 && cols >= 2 && !anyMultiline) {
+        return renderGfmTable(rows);
+    }
+    // 2) Two-column table. Section layout (short LABEL + substantial BODY in most
+    //    rows) → headings; otherwise data → `label: value`. Merged cells fall
+    //    through to flatten.
+    if (!spanned && uniform && cols === 2) {
+        const isSection = (row) => isLabel(row[0]) && isSubstantial(row[1]);
+        if (rows.filter(isSection).length >= Math.ceil(rows.length / 2)) {
+            // Heading level tracks nesting depth (## top-level, ### one level in, …),
+            // so a nested table's labels read as children, not peers of the document's
+            // top sections.
+            const h = '#'.repeat(Math.min(depth + 1, 6));
+            // Drop a leading column-header row (e.g. "Phases | Deliverables") when every
+            // BODY row is section-like — it's a table header, noise once headingized.
+            const body = rows.length > 1 && !isSection(rows[0]) && rows.slice(1).every(isSection)
+                ? rows.slice(1)
+                : rows;
+            return body
+                .map((row) => isSection(row)
+                ? `${h} ${headingLabel(row[0])}\n\n${row[1]}`
+                : row.filter(Boolean).join('\n\n'))
+                .join('\n\n');
+        }
+        return rows
+            .map(([left, right]) => isLabel(left) && right
+            ? `${inlineText(left)}: ${inlineText(right)}`
+            : [left, right].filter(Boolean).join('\n\n'))
+            .join('\n\n');
+    }
+    // 3) Anything else → flatten: each non-empty cell as its own block.
+    return rows.flat().filter(Boolean).join('\n\n');
+}
+function renderGfmTable(rows) {
+    const cell = (s) => s.replace(/\|/g, '\\|').replace(/\n+/g, ' ').trim();
+    const line = (cells) => `| ${cells.map(cell).join(' | ')} |`;
+    const [header, ...body] = rows;
+    return [
+        line(header),
+        `| ${header.map(() => '---').join(' | ')} |`,
+        ...body.map(line),
+    ].join('\n');
+}
+/** Collapse a cell's markdown to a single line (for headings / value cells). */
+function inlineText(md) {
+    return md.replace(/\s*\n+\s*/g, ' ').trim();
+}
+/** A short, single-line cell that can act as a section label / key. */
+function isLabel(cell) {
+    return !!cell && !cell.includes('\n') && cell.length <= MAX_LABEL_LEN;
+}
+/** A cell substantial enough to be a section BODY (not a short data value):
+ *  multi-line, long, or a full sentence. Keeps a 2-col DATA table from turning
+ *  every left value into a heading. */
+function isSubstantial(cell) {
+    return cell.includes('\n') || cell.length >= 40 || /[.!?](\s|$)/.test(cell);
+}
+/** A section label for a heading: single line, with one layer of surrounding
+ *  bold/italic stripped (Word styles the label; the `##` already conveys it, so
+ *  `**Project Scope**` → `Project Scope`, `_Phases_` → `Phases`). */
+function headingLabel(md) {
+    return inlineText(md)
+        .replace(/^\*\*(.+?)\*\*$/, '$1')
+        .replace(/^\*(.+?)\*$/, '$1')
+        .replace(/^_(.+?)_$/, '$1')
+        .trim();
+}
+/** Reading-text escape cleanup: turndown escapes `[ ] _` to protect markdown
+ *  syntax, which litters placeholders (`\[MSA date\]`) and signature lines
+ *  (`By: \_\_\_…`). Unescape those and collapse a long underscore run to a
+ *  short rule — but ONLY outside code spans / fenced blocks, so literal code
+ *  (snake_case, `a____b`, escaped brackets) is never rewritten. */
+function cleanup(md) {
+    // Split on code regions (fenced blocks first, then inline spans); transform
+    // only the prose between them, re-emitting code verbatim.
+    const codeRegion = /(```[\s\S]*?```|`[^`\n]*`)/g;
+    let out = '';
+    let last = 0;
+    for (const m of md.matchAll(codeRegion)) {
+        out += unescapeProse(md.slice(last, m.index));
+        out += m[0];
+        last = (m.index ?? 0) + m[0].length;
+    }
+    out += unescapeProse(md.slice(last));
+    return out.replace(/\n{3,}/g, '\n\n').trim();
+}
+function unescapeProse(s) {
+    return s
+        // A run of 6+ underscores (escaped or not) — a signature line → short rule.
+        // 6+ (not 4+) so it can't catch a stray escaped pair in ordinary prose.
+        .replace(/(?:\\?_){6,}/g, '______')
+        // Unescape the punctuation turndown guards that only adds noise to reading
+        // text (brackets around placeholders, stray underscores).
+        .replace(/\\([[\]_])/g, '$1');
+}
+//# sourceMappingURL=docx.js.map

package/dist/services/extract/docx.js.map

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

package/dist/services/extract/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Document text-extraction heuristics — per-format "make the extracted text
+ * readable" converters, kept apart from the authoritative convert pipeline
+ * (../convert-service.ts). Everything here is pure (bytes/text in → markdown
+ * out), deterministic, no LLM, and has no graph/storage side effects, so the
+ * orchestrator can stay focused on derivation/dedup/commit concerns.
+ */
+export { convertDocxToMarkdown } from './docx.js';
+export { convertPdfToNoteText } from './pdf.js';

package/dist/services/extract/index.js

@@ -0,0 +1,10 @@
+/**
+ * Document text-extraction heuristics — per-format "make the extracted text
+ * readable" converters, kept apart from the authoritative convert pipeline
+ * (../convert-service.ts). Everything here is pure (bytes/text in → markdown
+ * out), deterministic, no LLM, and has no graph/storage side effects, so the
+ * orchestrator can stay focused on derivation/dedup/commit concerns.
+ */
+export { convertDocxToMarkdown } from './docx.js';
+export { convertPdfToNoteText } from './pdf.js';
+//# sourceMappingURL=index.js.map

package/dist/services/extract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/extract/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/dist/services/extract/pdf.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PDF sidecar text → readable note body — the PDF extraction heuristics,
+ * isolated from the authoritative convert pipeline (../convert-service.ts).
+ *
+ * This is best-effort, frequently-tuned "make the extracted text readable"
+ * code with NO graph/storage side effects: text in → text out, deterministic,
+ * no LLM. PDF text extraction yields hard-wrapped lines and split hyphens; this
+ * rejoins wrapped prose + wrapped bullets, de-hyphenates line-end splits, and
+ * drops stray empty list markers, while preserving real paragraph/block breaks.
+ */
+/** Reflow PDF-extracted text: de-hyphenate, unwrap soft-wrapped lines (prose and
+ *  bullets), drop empty-bullet artifacts, and collapse blank-line runs. */
+export declare function convertPdfToNoteText(sidecarText: string): string;

package/dist/services/extract/pdf.js

@@ -0,0 +1,69 @@
+/**
+ * PDF sidecar text → readable note body — the PDF extraction heuristics,
+ * isolated from the authoritative convert pipeline (../convert-service.ts).
+ *
+ * This is best-effort, frequently-tuned "make the extracted text readable"
+ * code with NO graph/storage side effects: text in → text out, deterministic,
+ * no LLM. PDF text extraction yields hard-wrapped lines and split hyphens; this
+ * rejoins wrapped prose + wrapped bullets, de-hyphenates line-end splits, and
+ * drops stray empty list markers, while preserving real paragraph/block breaks.
+ */
+/** Reflow PDF-extracted text: de-hyphenate, unwrap soft-wrapped lines (prose and
+ *  bullets), drop empty-bullet artifacts, and collapse blank-line runs. */
+export function convertPdfToNoteText(sidecarText) {
+    const text = sidecarText.trim();
+    if (!text)
+        return '';
+    // De-hyphenate line-end splits before any line joining: "infor-\nmation".
+    const dehyphenated = text.replace(/([A-Za-z])-\n(?=[a-z])/g, '$1');
+    // A line that OPENS a block (bullet/number item or heading): never merged into
+    // the previous line, but CAN receive following continuation lines.
+    const startsBlock = (l) => /^\s*([-*+•]|\d+[.)])\s/.test(l) || /^\s*#{1,6}\s/.test(l);
+    // A line that is ONLY a list marker with no content — a PDF extraction artifact.
+    const isEmptyBullet = (l) => /^\s*([-*+•]|\d+[.)])\s*$/.test(l);
+    // A line whose end is a real sentence/clause boundary — don't unwrap onto it.
+    const endsSentence = (l) => /[.!?:;]["'”’)]?\s*$/.test(l.trim());
+    // A short, punctuation-less, Title-Case or ALL-CAPS line reads as a heading
+    // ("Executive Summary", "ESTIMATED FEES") — don't unwrap the next line ONTO it.
+    // The Title-Case test requires EVERY word to start uppercase, so a wrapped
+    // prose line like "The quick brown" (lowercase "quick"/"brown") still joins.
+    const looksLikeHeading = (l) => {
+        const t = l.trim();
+        if (!t || endsSentence(t))
+            return false;
+        const words = t.split(/\s+/);
+        if (words.length > 8)
+            return false; // headings are short
+        const hasLetters = /[A-Za-z]/.test(t);
+        const allCaps = hasLetters && t === t.toUpperCase();
+        const titleCase = hasLetters && words.every((w) => !/[a-z]/.test(w) || /^[^a-z]*[A-Z]/.test(w));
+        return allCaps || titleCase;
+    };
+    const out = [];
+    for (const raw of dehyphenated.split('\n')) {
+        if (isEmptyBullet(raw))
+            continue; // drop stray "-" artifacts
+        const cur = raw.trim();
+        if (cur === '') {
+            out.push('');
+            continue;
+        } // blank = paragraph break
+        if (startsBlock(raw)) {
+            out.push(cur);
+            continue;
+        }
+        // Continuation line: unwrap onto the previous line — prose OR a bullet — so a
+        // wrapped bullet's tail rejoins its marker. Skip when the previous line is a
+        // paragraph break, already ended a sentence/clause, or reads as a heading.
+        const prev = out.length ? out[out.length - 1] : undefined;
+        if (prev !== undefined && prev !== '' && !endsSentence(prev) && !looksLikeHeading(prev)) {
+            out[out.length - 1] = `${prev} ${cur}`;
+        }
+        else {
+            out.push(cur);
+        }
+    }
+    // Collapse 3+ blank lines to a single paragraph break.
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+//# sourceMappingURL=pdf.js.map

package/dist/services/extract/pdf.js.map

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

package/dist/services/folder-creation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared folder creation for network callers (web route + MCP tool).
+ *
+ * Wraps Workspace.registerRepo() with the concerns that are common to every
+ * network-facing creation path: kebab-case name validation, reserved-prefix
+ * guards, duplicate detection, folder-admin membership grant for the creator,
+ * and a folder_created WS broadcast.
+ *
+ * The CLI (`studiograph folder add`) deliberately does NOT use this helper —
+ * it runs locally with filesystem privileges, has no user identity to grant
+ * membership to, and no WS hub to broadcast on. It calls registerRepo()
+ * directly (see src/cli/commands/folder.ts).
+ *
+ * The private-folder auto-provision path (`ensurePrivateFolder` in
+ * src/server/routes/auth-api.ts) also calls registerRepo() directly because
+ * it has different semantics: private=true, no folder-admin grant, one per
+ * user. Not a fit for this helper.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { AuthService, AuthUser } from './auth-service.js';
+import type { WsHub } from '../server/ws-hub.js';
+import type { RepoConfig } from '../core/types.js';
+export type FolderCreationErrorCode = 'invalid_name' | 'duplicate' | 'internal';
+export declare class FolderCreationError extends Error {
+    readonly code: FolderCreationErrorCode;
+    constructor(code: FolderCreationErrorCode, message: string);
+}
+export interface CreateSharedFolderInput {
+    name: string;
+    display_name?: string;
+    description?: string;
+}
+export declare function createSharedFolder(workspaceManager: WorkspaceManager, authService: AuthService, input: CreateSharedFolderInput, user: AuthUser | undefined, wsHub?: WsHub): Promise<RepoConfig>;

package/dist/services/folder-creation.js

@@ -0,0 +1,103 @@
+/**
+ * Shared folder creation for network callers (web route + MCP tool).
+ *
+ * Wraps Workspace.registerRepo() with the concerns that are common to every
+ * network-facing creation path: kebab-case name validation, reserved-prefix
+ * guards, duplicate detection, folder-admin membership grant for the creator,
+ * and a folder_created WS broadcast.
+ *
+ * The CLI (`studiograph folder add`) deliberately does NOT use this helper —
+ * it runs locally with filesystem privileges, has no user identity to grant
+ * membership to, and no WS hub to broadcast on. It calls registerRepo()
+ * directly (see src/cli/commands/folder.ts).
+ *
+ * The private-folder auto-provision path (`ensurePrivateFolder` in
+ * src/server/routes/auth-api.ts) also calls registerRepo() directly because
+ * it has different semantics: private=true, no folder-admin grant, one per
+ * user. Not a fit for this helper.
+ */
+import { Workspace } from '../core/workspace.js';
+export class FolderCreationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FolderCreationError';
+    }
+}
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_NAME_LENGTH = 64;
+/**
+ * Reserved for per-user private folder auto-provisioning
+ * (`entries-<userId>` in auth-api.ts#ensurePrivateFolder). Letting a
+ * shared folder squat this prefix would block a new user's private
+ * provisioning on login.
+ */
+const RESERVED_NAME_REGEX = /^entries-\d+$/;
+export async function createSharedFolder(workspaceManager, authService, input, user, wsHub) {
+    const name = typeof input.name === 'string' ? input.name : '';
+    const display_name = input.display_name;
+    const description = input.description;
+    if (!name || !SLUG_REGEX.test(name)) {
+        throw new FolderCreationError('invalid_name', 'Folder name must be kebab-case (lowercase letters, digits, hyphens; must start with a letter or digit)');
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        throw new FolderCreationError('invalid_name', `Folder name must be ${MAX_NAME_LENGTH} characters or fewer`);
+    }
+    if (RESERVED_NAME_REGEX.test(name)) {
+        throw new FolderCreationError('invalid_name', 'Folder name "entries-<number>" is reserved for per-user private folders');
+    }
+    const workspace = new Workspace(workspaceManager.workspacePath);
+    let repo;
+    try {
+        repo = await workspace.registerRepo({
+            name,
+            display_name: display_name || undefined,
+            description,
+            owner_id: user?.id,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/already registered/i.test(msg)) {
+            throw new FolderCreationError('duplicate', `Folder "${name}" already exists`);
+        }
+        throw new FolderCreationError('internal', msg);
+    }
+    workspaceManager.reloadConfig();
+    if (user)
+        authService.grantFolderAccess(user.id, name, 'admin');
+    // For an authenticated creator, deliver to that user's own sessions only.
+    // A regular `broadcast()` would be filtered by `canReceive()` against each
+    // client's connection-time folder snapshot — which by definition doesn't
+    // contain a brand-new folder — so the event would be silently dropped.
+    // Patch the snapshot via `addUserFolder` so subsequent `entity_change`
+    // broadcasts for entities in this folder reach the creator without
+    // requiring a reconnect.
+    //
+    // For anonymous / API-without-identity creates (CLI, scripts), fall back
+    // to a plain broadcast. Open-mode clients (`client.folders === null`)
+    // bypass canReceive and will pick it up; auth-mode clients would have
+    // dropped it anyway, which preserves the prior behavior.
+    if (wsHub) {
+        if (user) {
+            wsHub.addUserFolder(String(user.id), name);
+            wsHub.broadcastToUser(String(user.id), {
+                type: 'folder_created',
+                repo: name,
+                actor: user.displayName,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        else {
+            wsHub.broadcast({
+                type: 'folder_created',
+                repo: name,
+                actor: 'API',
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    return repo;
+}
+//# sourceMappingURL=folder-creation.js.map

package/dist/services/folder-creation.js.map

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

package/dist/services/git.d.ts

@@ -39,6 +39,12 @@ export declare class GitService {
      * Check if repository has any commits
      */
     hasCommits(): boolean;
+    /**
+     * Return the current HEAD commit hash, or null if the repo has no commits.
+     * Used by callers (MCP update_entity) that want to surface the post-write
+     * commit hash so external agents can verify a write landed in git.
+     */
+    getHeadCommit(): string | null;
     /**
      * Get current branch name
      */
@@ -55,6 +61,49 @@ export declare class GitService {
      * Get file history for a specific file
      */
     getFileHistory(filePath: string, limit?: number): GitCommit[];
+    /**
+     * Get file content at a specific commit
+     */
+    getFileAtCommit(filePath: string, commitHash: string): string | null;
+    /**
+     * List every file path tracked in `commitHash`, repo-relative POSIX.
+     * Returns an empty array on error (unknown hash, malformed history).
+     * Used by restore flows that need to find a deleted entity's file
+     * inside its last-known commit without knowing the path up-front.
+     */
+    listFilesAtCommit(commitHash: string): string[];
+    /**
+     * Unified diff between two commits for a single file. `toCommitHash` may
+     * be 'HEAD' or any rev-spec git accepts. All three params flow through
+     * passed as argv entries so shell metacharacters in paths or revs are never
+     * interpreted by a shell. Returns the raw diff (or empty string on failure).
+     */
+    getDiff(fromCommitHash: string, toCommitHash: string, filePath: string): string;
+    /**
+     * Recent file deletions from the commit log, scoped to a time window.
+     *
+     * Uses `git log --diff-filter=D --name-only` to find every commit that
+     * deleted at least one file, then walks the output and pairs each
+     * deleted path with the commit that removed it. The returned list is
+     * deduped on `filePath` so a file deleted-and-recreated-and-deleted
+     * surfaces only its most recent removal — that's the one a "restore"
+     * action is going to target.
+     *
+     * `withinDays` clamps to a 1-90 day window. The default of 7 covers
+     * the most common "I deleted that yesterday" workflows without
+     * dragging in months of forgotten removals.
+     */
+    listRecentDeletions(withinDays?: number): Array<{
+        filePath: string;
+        deletedAtCommit: string;
+        deletedAt: number;
+        deletedBy: {
+            name: string;
+            email: string;
+        };
+        lastVersionCommit: string;
+        commitMessage: string;
+    }>;
     /**
      * Get current status (modified, added, deleted files)
      */
@@ -92,6 +141,11 @@ export declare class GitService {
      * Stage specific files and commit with user attribution.
      * Unlike commitAll, this only stages the given files — unrelated
      * untracked files (e.g. sync-created entities) are left untouched.
+     *
+     * Uses `git add -A <pathspec>` so deletions, modifications, and
+     * additions under the listed paths are all staged. The path scoping
+     * still prevents pulling in unrelated untracked files outside the
+     * listed paths. Throws on git failure with stderr in the error.
      */
     commitFiles(filePaths: string[], message: string, user: GitUser): void;
     /**