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

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
      */
@@ -59,6 +65,45 @@ export declare class GitService {
      * 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)
      */
@@ -96,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;
     /**
@@ -106,6 +156,14 @@ export declare class GitService {
      * Pull from remote
      */
     pull(): void;
+    /**
+     * Repo-relative POSIX paths of files that differ between two commits
+     * (`git diff --name-only <from> <to>`). Both revs flow through argv so
+     * shell metacharacters are never interpreted. Returns `[]` on failure or
+     * when nothing changed. Used by `graph.pullAndReconcile` to find the .md
+     * files a pull rewrote so any live editor Y.Doc can be reconciled.
+     */
+    diffNameOnly(fromCommitHash: string, toCommitHash: string): string[];
     /**
      * Get status as array of { path, status } entries
      */