studiograph 1.3.48-next.76 → 1.3.48-next.78

package/dist/core/graph.d.ts

@@ -20,6 +20,10 @@ export interface GraphConfig {
     schemaRegistry?: SchemaRegistry;
     /** When true, all git operations are skipped. Used for the private/ graph. */
     noGit?: boolean;
+    /** Workspace root path. Used to anchor cross-repo artefacts like the
+     *  PDF text sidecar at `<workspaceRoot>/.studiograph/assets-text/...`.
+     *  Optional — when undefined, sidecar cleanup is a no-op. */
+    workspaceRoot?: string;
 }
 export interface EntityFile {
     id: string;
@@ -35,6 +39,10 @@ export interface FolderEntry {
     path: string;
     /** Last segment of the path. */
     name: string;
+    /** Optional human-readable label. Set only when an explicit override exists
+     *  in the folder's `.studiograph-folder.json` sidecar; clients fall back to
+     *  toDisplayName(name) when undefined. */
+    display_name?: string;
 }
 export interface FolderDeleteResult {
     entriesDeleted: number;
@@ -89,9 +97,15 @@ export declare class BaseGraphManager {
     private csvService;
     private vectorService?;
     private schemaRegistry?;
+    private workspaceRoot?;
     constructor(config: GraphConfig);
     /** Expose git service for deferred commit operations (SessionManager). */
     getGitService(): GitService | undefined;
+    /** Workspace root passed in via GraphConfig. Used by the asset upload
+     *  service to anchor PDF text sidecars at workspace level (so all repos
+     *  share the same `assets-text/` tree, mirroring the shared
+     *  `.studiograph/assets/` directory the local backend uses). */
+    getWorkspaceRoot(): string | undefined;
     /**
      * Ensure repository exists
      */
@@ -171,6 +185,62 @@ export declare class BaseGraphManager {
     /**
      * Delete an entity
      */
+    /**
+     * Delete multiple entities in a single git transaction. Each entity's
+     * file is removed from disk; folder markers (.gitkeep) are added where
+     * the deletion left a folder empty. Then everything commits as one
+     * atomic operation.
+     *
+     * Compared to looping `delete()` per entity, this is a real performance
+     * primitive: one fork of git, one index update, one commit, one ref
+     * advance — instead of N. Bulk delete of a few hundred entities goes
+     * from minutes to seconds.
+     *
+     * Errors per entity (e.g. "not found") don't abort the batch — they're
+     * collected in `errors` and the rest still commit. Returns both the
+     * successfully-deleted set (for vector cleanup + WS broadcast) and the
+     * errors so the caller can surface partial failures.
+     */
+    bulkDelete(specs: Array<{
+        entityType: EntityType;
+        entityId: string;
+    }>, options?: {
+        commitMessage?: string;
+        user?: GitUser;
+    }): Promise<{
+        deleted: Array<{
+            entityType: EntityType;
+            entityId: string;
+            path: string;
+        }>;
+        errors: Array<{
+            entityType: EntityType;
+            entityId: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * Commit a set of already-on-disk file changes as a single git
+     * operation. Used by callers (e.g. the import route) that perform many
+     * `skipCommit: true` writes and want one transaction at the end instead
+     * of per-file commits.
+     *
+     * `entries` describes what each file represents so the transaction can
+     * be staged correctly. No-op when nothing is staged or git isn't
+     * available.
+     */
+    commitPending(entries: Array<{
+        operation: 'create' | 'update' | 'delete';
+        entityType: EntityType;
+        entityId: string;
+        filePath: string;
+    }>, options: {
+        commitMessage: string;
+        user?: GitUser;
+        extraPaths?: string[];
+    }): Promise<{
+        committed: boolean;
+    }>;
     delete(entityType: EntityType, entityId: string, commitMessage?: string, user?: GitUser): Promise<void>;
     /**
      * Rename an entity (change its ID). Preserves all data, content, and source_ref.
@@ -285,18 +355,52 @@ export declare class BaseGraphManager {
      * The repo root ("") is intentionally omitted — it's implicit.
      */
     listFolders(): FolderEntry[];
+    /**
+     * Read the display_name override for a single folder, or null if no sidecar
+     * exists / is unreadable. Used by mutation paths that need the current
+     * override before deciding whether to rewrite it.
+     */
+    readFolderDisplayName(folderPath: string): string | null;
+    /**
+     * Write or remove the per-folder display_name sidecar. Pass `null` /
+     * empty-string to remove (returns to slug fallback). Returns the absolute
+     * path of the sidecar (for git staging) when one was written or removed,
+     * or null when no change was needed (idempotent).
+     *
+     * Caller is responsible for committing — the helper only touches the
+     * filesystem. Folder must already exist; this never creates one.
+     */
+    writeFolderDisplayName(folderPath: string, displayName: string | null): string | null;
+    /**
+     * Bulk-write display_name sidecars for many folders at once. Used by the
+     * import path to record original-casing overrides for every nested
+     * directory it slugified. First-writer-wins: existing sidecars are NOT
+     * overwritten, so a second import doesn't clobber a user's manual rename.
+     *
+     * Returns the list of sidecar paths actually written (for git staging).
+     * Skipped paths (folder missing, slug already matches display, sidecar
+     * already exists) are quietly omitted.
+     */
+    recordFolderDisplays(entries: Array<{
+        path: string;
+        display_name: string;
+    }>): string[];
     /**
      * Create a folder at the given path (mkdir -p semantics) and drop a
      * .gitkeep so git tracks it even when empty. Validates the path. No-op if
      * the folder already exists; .gitkeep is added if missing.
      */
-    createFolder(folderPath: string, commitMessage?: string, user?: GitUser): Promise<void>;
+    createFolder(folderPath: string, commitMessage?: string, user?: GitUser, options?: {
+        displayName?: string;
+    }): Promise<void>;
     /**
      * Rename / move a folder within the repo. Moves the entire subtree
      * atomically via filesystem rename. Refuses if the target path is already
      * occupied.
      */
-    renameFolder(fromPath: string, toPath: string, commitMessage?: string, user?: GitUser): Promise<void>;
+    renameFolder(fromPath: string, toPath: string, commitMessage?: string, user?: GitUser, options?: {
+        displayName?: string | null;
+    }): Promise<void>;
     /**
      * Move a folder (and its full subtree) into a different repo at `targetFolderPath`.
      *

package/dist/core/graph.js

@@ -5,7 +5,7 @@
  * Integrates Git, Markdown, and Asset services.
  */
 import { join, dirname, relative } from 'path';
-import { existsSync, readdirSync, rmSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync } from 'fs';
 import { GitService } from '../services/git.js';
 import { MarkdownService } from '../services/markdown.js';
 import { AssetService } from '../services/assets/index.js';
@@ -15,6 +15,34 @@ import { folderPathFromFile, normalizeFolderPath, validateFolderPath, InvalidFol
 import { z } from 'zod';
 /** Names skipped during recursive repo walks. */
 const WALK_IGNORE = new Set(['.git', '.studiograph', 'node_modules']);
+/**
+ * Per-folder sidecar carrying optional display_name override. Lives inside
+ * the folder itself so it travels atomically with FS rename / move / cross-repo
+ * transfer — the same way an entity .md file's frontmatter travels with the
+ * file. Sparse: only written when display_name differs from the slug fallback
+ * (toDisplayName), so kebab-named folders never produce a sidecar.
+ */
+const FOLDER_SIDECAR = '.studiograph-folder.json';
+/**
+ * Read the display_name override from a folder's sidecar. Returns null when
+ * the sidecar is absent, unreadable, or malformed — drift is tolerated, the
+ * caller falls back to toDisplayName(slug) just like a folder with no
+ * override at all.
+ */
+function readFolderSidecar(absDir) {
+    const sidecarPath = join(absDir, FOLDER_SIDECAR);
+    if (!existsSync(sidecarPath))
+        return null;
+    try {
+        const raw = readFileSync(sidecarPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const display = parsed?.display_name;
+        return typeof display === 'string' && display.trim() ? display.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
 export class BaseGraphManager {
     repoPath;
     repoName;
@@ -26,6 +54,7 @@ export class BaseGraphManager {
     csvService;
     vectorService;
     schemaRegistry;
+    workspaceRoot;
     constructor(config) {
         this.repoPath = config.repoPath;
         this.repoName = config.repoName;
@@ -33,6 +62,7 @@ export class BaseGraphManager {
         this.noGit = config.noGit ?? false;
         this.vectorService = config.vectorService;
         this.schemaRegistry = config.schemaRegistry;
+        this.workspaceRoot = config.workspaceRoot;
         // Initialize services
         if (!this.noGit) {
             this.gitService = new GitService(this.repoPath);
@@ -50,6 +80,13 @@ export class BaseGraphManager {
     getGitService() {
         return this.gitService;
     }
+    /** Workspace root passed in via GraphConfig. Used by the asset upload
+     *  service to anchor PDF text sidecars at workspace level (so all repos
+     *  share the same `assets-text/` tree, mirroring the shared
+     *  `.studiograph/assets/` directory the local backend uses). */
+    getWorkspaceRoot() {
+        return this.workspaceRoot;
+    }
     /**
      * Ensure repository exists
      */
@@ -463,11 +500,116 @@ export class BaseGraphManager {
     /**
      * Delete an entity
      */
+    /**
+     * Delete multiple entities in a single git transaction. Each entity's
+     * file is removed from disk; folder markers (.gitkeep) are added where
+     * the deletion left a folder empty. Then everything commits as one
+     * atomic operation.
+     *
+     * Compared to looping `delete()` per entity, this is a real performance
+     * primitive: one fork of git, one index update, one commit, one ref
+     * advance — instead of N. Bulk delete of a few hundred entities goes
+     * from minutes to seconds.
+     *
+     * Errors per entity (e.g. "not found") don't abort the batch — they're
+     * collected in `errors` and the rest still commit. Returns both the
+     * successfully-deleted set (for vector cleanup + WS broadcast) and the
+     * errors so the caller can surface partial failures.
+     */
+    async bulkDelete(specs, options) {
+        const deleted = [];
+        const errors = [];
+        const transaction = this.gitService?.createTransaction();
+        for (const { entityType, entityId } of specs) {
+            try {
+                const existing = this.get(entityType, entityId);
+                rmSync(existing.path, { force: true });
+                // Folder marker if the deletion emptied the folder — same lifecycle
+                // semantics as single delete().
+                const addedMarker = this.ensureFolderMarker(dirname(existing.path));
+                if (transaction) {
+                    transaction.add({ operation: 'delete', entityType, entityId, filePath: existing.path });
+                    if (addedMarker) {
+                        transaction.add({ operation: 'create', entityType, entityId, filePath: addedMarker });
+                    }
+                }
+                deleted.push({ entityType, entityId, path: existing.path });
+            }
+            catch (err) {
+                errors.push({
+                    entityType,
+                    entityId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        this.invalidateIndex();
+        if (transaction && deleted.length > 0) {
+            const message = options?.commitMessage
+                ?? `Delete ${deleted.length} ${deleted.length === 1 ? 'entry' : 'entries'} from web UI`;
+            await transaction.commit(options?.user ?? this.gitUser, message);
+        }
+        // Vector index cleanup, fire-and-forget (matches single delete() behavior).
+        for (const { entityType, entityId } of deleted) {
+            this.vectorService?.delete(this.repoName, entityType, entityId).catch(err => console.warn(`[vector] delete failed for ${entityType}/${entityId}:`, err.message));
+        }
+        return { deleted, errors };
+    }
+    /**
+     * Commit a set of already-on-disk file changes as a single git
+     * operation. Used by callers (e.g. the import route) that perform many
+     * `skipCommit: true` writes and want one transaction at the end instead
+     * of per-file commits.
+     *
+     * `entries` describes what each file represents so the transaction can
+     * be staged correctly. No-op when nothing is staged or git isn't
+     * available.
+     */
+    async commitPending(entries, options) {
+        if (!this.gitService)
+            return { committed: false };
+        if (entries.length === 0 && !options.extraPaths?.length)
+            return { committed: false };
+        const transaction = this.gitService.createTransaction();
+        for (const e of entries)
+            transaction.add(e);
+        // Auxiliary paths (folder-display sidecars from the import flow) are
+        // staged alongside the entity files so they land in the same commit.
+        // The transaction only uses `filePath` for staging — the other fields
+        // are metadata, so we fill them with sentinel values.
+        if (options.extraPaths?.length) {
+            for (const filePath of options.extraPaths) {
+                transaction.add({
+                    operation: 'create',
+                    entityType: '_sidecar',
+                    entityId: '_sidecar',
+                    filePath,
+                });
+            }
+        }
+        await transaction.commit(options.user ?? this.gitUser, options.commitMessage);
+        return { committed: true };
+    }
     async delete(entityType, entityId, commitMessage, user) {
         // Verify entity exists
         const existing = this.get(entityType, entityId);
         // Delete the flat entity file
         rmSync(existing.path, { force: true });
+        // Asset entities own a binary blob (and optionally a PDF text sidecar).
+        // Both must be cleaned up — leaving them orphans the storage layer and
+        // poisons future entity_id reuse with a stale text dump. Fire-and-forget:
+        // the markdown is the system of record, so a stuck binary shouldn't
+        // block the delete commit. (Same approach as vector-index cleanup below.)
+        if (entityType === 'asset' && this.assetService) {
+            this.assetService.deleteAll('asset', entityId).catch(err => console.warn(`[asset] deleteAll failed for asset/${entityId}: ${err?.message ?? err}`));
+            if (this.workspaceRoot) {
+                const sidecarPath = join(this.workspaceRoot, '.studiograph', 'assets-text', 'asset', `${entityId}.txt`);
+                try {
+                    rmSync(sidecarPath, { force: true });
+                }
+                catch { /* sidecar cleanup is best-effort */ }
+            }
+        }
         // Folder lifecycle: deleting an entry never deletes its containing folder.
         // If this was the last .md in the folder, write a .gitkeep so it stays
         // visible to listFolders() (and therefore to the sidebar). A user who
@@ -537,6 +679,18 @@ export class BaseGraphManager {
      * folder when changed to a note), they invoke move() separately.
      */
     async changeType(entityId, fromType, toType, commitMessage, user) {
+        // Asset entities are bound to a binary in the storage backend plus
+        // (for PDFs) a text sidecar. Changing TO asset would leave the entity
+        // without an asset_url / asset_kind / blob; changing FROM asset would
+        // orphan the binary and sidecar. Both directions must be a
+        // delete-and-recreate, not a type swap.
+        if (toType === 'asset' || fromType === 'asset') {
+            const direction = toType === 'asset' ? 'to' : 'from';
+            throw new Error(`Cannot change_type ${direction} 'asset' — assets are bound to a binary in storage. ` +
+                (toType === 'asset'
+                    ? 'Delete this entry and re-upload the file via the asset upload route to convert it to an asset.'
+                    : 'Delete this asset entry (which removes the binary) and create a fresh entry of the target type.'));
+        }
         const existing = this.get(fromType, entityId);
         // (type, id) uniqueness check — if an entry with the new type already
         // exists with this id, refuse rather than silently colliding in the index.
@@ -1064,6 +1218,7 @@ export class BaseGraphManager {
         if (!existsSync(this.repoPath))
             return [];
         const folders = new Set();
+        const sidecarByPath = new Map();
         const stack = [this.repoPath];
         const repoRoot = this.repoPath.replace(/\/+$/, '');
         while (stack.length > 0) {
@@ -1076,9 +1231,12 @@ export class BaseGraphManager {
                 continue;
             }
             let kept = false;
+            let hasSidecar = false;
             for (const entry of entries) {
                 if (entry === '.gitkeep')
                     kept = true;
+                if (entry === FOLDER_SIDECAR)
+                    hasSidecar = true;
                 if (entry.startsWith('.'))
                     continue;
                 if (WALK_IGNORE.has(entry))
@@ -1096,23 +1254,113 @@ export class BaseGraphManager {
             }
             if (dir === repoRoot)
                 continue;
-            // Include this directory if it has any .md files OR a .gitkeep marker.
+            // Include this directory if it has any .md files OR a .gitkeep marker
+            // OR a sidecar (which carries display metadata even for empty folders).
             const hasMarkdown = entries.some(e => e.endsWith('.md') && !e.startsWith('.'));
-            if (hasMarkdown || kept) {
-                folders.add(folderPathFromFile(join(dir, 'placeholder.md'), this.repoPath));
+            if (hasMarkdown || kept || hasSidecar) {
+                const folderPath = folderPathFromFile(join(dir, 'placeholder.md'), this.repoPath);
+                folders.add(folderPath);
+                if (hasSidecar) {
+                    const display = readFolderSidecar(dir);
+                    if (display !== null)
+                        sidecarByPath.set(folderPath, display);
+                }
             }
         }
         return [...folders]
             .filter(p => p.length > 0)
             .sort()
-            .map(p => ({ path: p, name: p.slice(p.lastIndexOf('/') + 1) }));
+            .map(p => {
+            const entry = { path: p, name: p.slice(p.lastIndexOf('/') + 1) };
+            const display = sidecarByPath.get(p);
+            if (display)
+                entry.display_name = display;
+            return entry;
+        });
+    }
+    /**
+     * Read the display_name override for a single folder, or null if no sidecar
+     * exists / is unreadable. Used by mutation paths that need the current
+     * override before deciding whether to rewrite it.
+     */
+    readFolderDisplayName(folderPath) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized)
+            return null;
+        return readFolderSidecar(join(this.repoPath, normalized));
+    }
+    /**
+     * Write or remove the per-folder display_name sidecar. Pass `null` /
+     * empty-string to remove (returns to slug fallback). Returns the absolute
+     * path of the sidecar (for git staging) when one was written or removed,
+     * or null when no change was needed (idempotent).
+     *
+     * Caller is responsible for committing — the helper only touches the
+     * filesystem. Folder must already exist; this never creates one.
+     */
+    writeFolderDisplayName(folderPath, displayName) {
+        const normalized = validateFolderPath(folderPath);
+        if (!normalized) {
+            throw new InvalidFolderPathError('Folder path cannot be empty');
+        }
+        const abs = join(this.repoPath, normalized);
+        if (!existsSync(abs)) {
+            throw new Error(`Folder not found: ${normalized}`);
+        }
+        const sidecarPath = join(abs, FOLDER_SIDECAR);
+        const trimmed = displayName?.trim();
+        if (!trimmed) {
+            if (!existsSync(sidecarPath))
+                return null;
+            rmSync(sidecarPath, { force: true });
+            this.invalidateIndex();
+            return sidecarPath;
+        }
+        const existing = readFolderSidecar(abs);
+        if (existing === trimmed)
+            return null;
+        writeFileSync(sidecarPath, JSON.stringify({ display_name: trimmed }, null, 2) + '\n', 'utf-8');
+        this.invalidateIndex();
+        return sidecarPath;
+    }
+    /**
+     * Bulk-write display_name sidecars for many folders at once. Used by the
+     * import path to record original-casing overrides for every nested
+     * directory it slugified. First-writer-wins: existing sidecars are NOT
+     * overwritten, so a second import doesn't clobber a user's manual rename.
+     *
+     * Returns the list of sidecar paths actually written (for git staging).
+     * Skipped paths (folder missing, slug already matches display, sidecar
+     * already exists) are quietly omitted.
+     */
+    recordFolderDisplays(entries) {
+        const written = [];
+        for (const entry of entries) {
+            const normalized = validateFolderPath(entry.path);
+            if (!normalized)
+                continue;
+            const abs = join(this.repoPath, normalized);
+            if (!existsSync(abs))
+                continue;
+            const sidecarPath = join(abs, FOLDER_SIDECAR);
+            if (existsSync(sidecarPath))
+                continue; // first-writer-wins
+            const display = entry.display_name.trim();
+            if (!display)
+                continue;
+            writeFileSync(sidecarPath, JSON.stringify({ display_name: display }, null, 2) + '\n', 'utf-8');
+            written.push(sidecarPath);
+        }
+        if (written.length > 0)
+            this.invalidateIndex();
+        return written;
     }
     /**
      * Create a folder at the given path (mkdir -p semantics) and drop a
      * .gitkeep so git tracks it even when empty. Validates the path. No-op if
      * the folder already exists; .gitkeep is added if missing.
      */
-    async createFolder(folderPath, commitMessage, user) {
+    async createFolder(folderPath, commitMessage, user, options) {
         const normalized = validateFolderPath(folderPath);
         if (!normalized) {
             throw new InvalidFolderPathError('Folder path cannot be empty (use the repo root directly)');
@@ -1123,10 +1371,16 @@ export class BaseGraphManager {
         if (!existsSync(keep)) {
             writeFileSync(keep, '');
         }
+        // Sidecar is written here (not after the commit) so it joins the same
+        // commit as .gitkeep — folder creation is atomic from git's perspective.
+        const sidecarPath = options?.displayName
+            ? this.writeFolderDisplayName(normalized, options.displayName)
+            : null;
         this.invalidateIndex();
         if (this.gitService) {
             const message = commitMessage || `Create folder: ${normalized}`;
-            this.gitService.commitFiles([keep], message, user ?? this.gitUser);
+            const files = sidecarPath ? [keep, sidecarPath] : [keep];
+            this.gitService.commitFiles(files, message, user ?? this.gitUser);
         }
     }
     /**
@@ -1134,15 +1388,24 @@ export class BaseGraphManager {
      * atomically via filesystem rename. Refuses if the target path is already
      * occupied.
      */
-    async renameFolder(fromPath, toPath, commitMessage, user) {
+    async renameFolder(fromPath, toPath, commitMessage, user, options) {
         const fromNormalized = validateFolderPath(fromPath);
         const toNormalized = validateFolderPath(toPath);
         if (!fromNormalized)
             throw new InvalidFolderPathError('Source folder path required');
         if (!toNormalized)
             throw new InvalidFolderPathError('Target folder path required');
-        if (fromNormalized === toNormalized)
+        // Display-only update: same path, just rewrite the sidecar.
+        if (fromNormalized === toNormalized) {
+            if (options?.displayName === undefined)
+                return;
+            const sidecarPath = this.writeFolderDisplayName(fromNormalized, options.displayName);
+            if (sidecarPath && this.gitService) {
+                const message = commitMessage || `Update folder display name: ${fromNormalized}`;
+                this.gitService.commitFiles([sidecarPath], message, user ?? this.gitUser);
+            }
             return;
+        }
         const fromAbs = join(this.repoPath, fromNormalized);
         const toAbs = join(this.repoPath, toNormalized);
         if (!existsSync(fromAbs)) {
@@ -1154,10 +1417,18 @@ export class BaseGraphManager {
         mkdirSync(dirname(toAbs), { recursive: true });
         const { renameSync } = await import('fs');
         renameSync(fromAbs, toAbs);
+        // The sidecar moved with the folder via FS rename. Update it now if the
+        // caller passed a new display name (or `null` to clear). Idempotent — no
+        // sidecar write happens when display matches the existing override.
+        let sidecarPath = null;
+        if (options?.displayName !== undefined) {
+            sidecarPath = this.writeFolderDisplayName(toNormalized, options.displayName);
+        }
         this.invalidateIndex();
         if (this.gitService) {
             const message = commitMessage || `Rename folder: ${fromNormalized} → ${toNormalized}`;
-            this.gitService.commitFiles([fromAbs, toAbs], message, user ?? this.gitUser);
+            const files = sidecarPath ? [fromAbs, toAbs, sidecarPath] : [fromAbs, toAbs];
+            this.gitService.commitFiles(files, message, user ?? this.gitUser);
         }
         await this.pruneEmptyAncestors(dirname(fromAbs));
     }