studiograph 1.3.46 → 1.3.48-beta.0

package/dist/server/yjs-text-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yjs-text-diff.js","sourceRoot":"","sources":["../../src/server/yjs-text-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAW,EAAE,KAAa,EAAE,MAAc,EAAE,MAAc;IACtF,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO;IAE/B,MAAM,GAAG,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,0EAA0E;IAC1E,GAAG,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAEhC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACjB,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;YAC/B,IAAI,EAAE,KAAK,UAAU,EAAE,CAAC;gBACtB,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;YACrB,CAAC;iBAAM,IAAI,EAAE,KAAK,WAAW,EAAE,CAAC;gBAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/B,uEAAuE;YACzE,CAAC;iBAAM,IAAI,EAAE,KAAK,WAAW,EAAE,CAAC;gBAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACxB,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC"}

package/dist/services/access-control.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Framework-free per-folder access control helpers.
+ *
+ * These functions decide what a given user can see or write in the workspace.
+ * They take `AuthUser | undefined` directly (not a Fastify request) so they
+ * can be reused across transports — HTTP (/api/*), MCP HTTP (/mcp), and
+ * MCP stdio all share the same rules.
+ *
+ * Rule summary:
+ * - `user === undefined` means "no identified user". On the **web** this is
+ *   API-key / open-mode (full access). On **MCP** the caller site rejects
+ *   unidentified requests before reaching these helpers, so every MCP tool
+ *   can assume a concrete user and `undefined` is never passed in.
+ * - A user can see a folder if they are an explicit member (folder_access row),
+ *   or if they are the workspace owner AND the folder has more than one member
+ *   (shared folders are visible to owners, solo folders stay private).
+ * - A user can write to a folder if they are a folder member (role = admin|editor),
+ *   or if they are the workspace owner on a shared folder.
+ * - A folder with `personal: true` is only visible/writable to its owner,
+ *   regardless of folder_access grants or workspace ownership. Stale grants
+ *   (from an older sharing attempt or test setup) cannot leak a user's
+ *   private notes to another account.
+ * - **Owner admin escalation**: workspace owners can lift the personal-
+ *   folder restriction by passing `{ includePrivate: true }` to these
+ *   helpers. The flag is enforced as owner-only inside the helpers — non-
+ *   owners passing it get no extra access. The owner-only CLI (`clone` /
+ *   `pull` / `push`) sends it unconditionally so the owner always sees every
+ *   folder; web / API surfaces opt in via the `?include_private=1` query
+ *   param on `/api/repos` or the `X-Studiograph-Include-Private: 1` header
+ *   for git transport. Used for migrations, audits, and offboarding.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { RepoConfig } from '../core/types.js';
+import { type AuthService, type AuthUser } from './auth-service.js';
+/**
+ * Options accepted by the access helpers. `includePrivate` is an owner-
+ * gated admin escalation: workspace owners can opt into seeing every
+ * folder (including other users' personal ones) for migration / audit /
+ * offboarding work. Default operations stay scoped so the owner's daily
+ * workflow isn't cluttered with members' private content.
+ */
+export interface AccessOptions {
+    /** Owner-only override: when true AND caller is a workspace owner, the
+     *  personal-folder restriction is lifted. No-op for non-owners. */
+    includePrivate?: boolean;
+}
+/**
+ * Return the list of repos the user can access (content visibility).
+ * Unidentified caller (undefined) → full access, preserves legacy
+ * web / API-key behavior.
+ */
+export declare function getAccessibleRepos(user: AuthUser | undefined, workspaceManager: WorkspaceManager, authService: AuthService, opts?: AccessOptions): RepoConfig[];
+/** True if the user may read the given folder's contents. */
+export declare function hasRepoAccess(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService, opts?: AccessOptions): boolean;
+/** True if the user is a folder admin on the given repo, OR a workspace
+ *  owner on a shared folder (>1 member). Solo/private folders require
+ *  actual folder-admin membership — workspace ownership alone does not
+ *  let owners rename, delete, or push members into a private folder. */
+export declare function isFolderAdminOrOwner(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService): boolean;
+/**
+ * True if the user may write (create/update/delete entities) in the given folder.
+ * Membership grants write access regardless of role (both 'admin' and 'editor'
+ * can edit), and workspace owners can write to shared folders.
+ */
+export declare function canWriteRepo(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService): boolean;
+/**
+ * Build a set of all entity IDs visible to the user across their accessible
+ * folders. Returns null when the caller is unidentified (no filtering needed —
+ * `filterWikilinks` treats null as "no-op").
+ */
+export declare function getAccessibleEntityIds(user: AuthUser | undefined, workspaceManager: WorkspaceManager, authService: AuthService): Set<string> | null;
+/** Filter a wikilink list to only entities the caller can access. */
+export declare function filterWikilinks(wikilinks: string[], accessibleIds: Set<string> | null): string[];

package/dist/services/access-control.js

@@ -0,0 +1,146 @@
+/**
+ * Framework-free per-folder access control helpers.
+ *
+ * These functions decide what a given user can see or write in the workspace.
+ * They take `AuthUser | undefined` directly (not a Fastify request) so they
+ * can be reused across transports — HTTP (/api/*), MCP HTTP (/mcp), and
+ * MCP stdio all share the same rules.
+ *
+ * Rule summary:
+ * - `user === undefined` means "no identified user". On the **web** this is
+ *   API-key / open-mode (full access). On **MCP** the caller site rejects
+ *   unidentified requests before reaching these helpers, so every MCP tool
+ *   can assume a concrete user and `undefined` is never passed in.
+ * - A user can see a folder if they are an explicit member (folder_access row),
+ *   or if they are the workspace owner AND the folder has more than one member
+ *   (shared folders are visible to owners, solo folders stay private).
+ * - A user can write to a folder if they are a folder member (role = admin|editor),
+ *   or if they are the workspace owner on a shared folder.
+ * - A folder with `personal: true` is only visible/writable to its owner,
+ *   regardless of folder_access grants or workspace ownership. Stale grants
+ *   (from an older sharing attempt or test setup) cannot leak a user's
+ *   private notes to another account.
+ * - **Owner admin escalation**: workspace owners can lift the personal-
+ *   folder restriction by passing `{ includePrivate: true }` to these
+ *   helpers. The flag is enforced as owner-only inside the helpers — non-
+ *   owners passing it get no extra access. The owner-only CLI (`clone` /
+ *   `pull` / `push`) sends it unconditionally so the owner always sees every
+ *   folder; web / API surfaces opt in via the `?include_private=1` query
+ *   param on `/api/repos` or the `X-Studiograph-Include-Private: 1` header
+ *   for git transport. Used for migrations, audits, and offboarding.
+ */
+import { isWorkspaceOwner } from './auth-service.js';
+/** True if the folder is `personal: true` and the caller is not its owner.
+ *  The personal flag is an owner-private invariant: it overrides folder_access
+ *  rows and workspace ownership. Unidentified callers (open mode / API key)
+ *  are never restricted — `undefined` user means full access. */
+function isRestrictedPersonalFolder(user, repoName, workspaceManager) {
+    if (!user)
+        return false;
+    const repo = workspaceManager.getRepoConfig(repoName);
+    if (!repo?.personal)
+        return false;
+    // Missing owner_id on a personal folder would be a config bug; err on
+    // the side of deny to avoid leaking content.
+    return repo.owner_id === undefined || repo.owner_id !== user.id;
+}
+/**
+ * Return the list of repos the user can access (content visibility).
+ * Unidentified caller (undefined) → full access, preserves legacy
+ * web / API-key behavior.
+ */
+export function getAccessibleRepos(user, workspaceManager, authService, opts = {}) {
+    const allRepos = workspaceManager.getAllRepoConfigs();
+    if (!user)
+        return allRepos;
+    const allowed = new Set(authService.getUserFolders(user.id));
+    const isOwner = isWorkspaceOwner(user.role);
+    const ownerOverride = isOwner && opts.includePrivate === true;
+    return allRepos.filter(r => {
+        if (ownerOverride)
+            return true;
+        // Personal folders are owner-only, regardless of grants.
+        if (r.personal && r.owner_id !== user.id)
+            return false;
+        if (allowed.has(r.name))
+            return true;
+        if (isOwner && authService.getFolderMembers(r.name).length > 1)
+            return true;
+        return false;
+    });
+}
+/** True if the user may read the given folder's contents. */
+export function hasRepoAccess(user, repoName, workspaceManager, authService, opts = {}) {
+    if (!user)
+        return true;
+    const isOwner = isWorkspaceOwner(user.role);
+    if (isOwner && opts.includePrivate === true)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    if (authService.getUserFolders(user.id).includes(repoName))
+        return true;
+    if (isOwner && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/** True if the user is a folder admin on the given repo, OR a workspace
+ *  owner on a shared folder (>1 member). Solo/private folders require
+ *  actual folder-admin membership — workspace ownership alone does not
+ *  let owners rename, delete, or push members into a private folder. */
+export function isFolderAdminOrOwner(user, repoName, workspaceManager, authService) {
+    if (!user)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    if (authService.isFolderAdmin(user.id, repoName))
+        return true;
+    if (isWorkspaceOwner(user.role) && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/**
+ * True if the user may write (create/update/delete entities) in the given folder.
+ * Membership grants write access regardless of role (both 'admin' and 'editor'
+ * can edit), and workspace owners can write to shared folders.
+ */
+export function canWriteRepo(user, repoName, workspaceManager, authService) {
+    if (!user)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    const role = authService.getFolderRole(user.id, repoName);
+    if (role === 'admin' || role === 'editor')
+        return true;
+    if (isWorkspaceOwner(user.role) && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/**
+ * Build a set of all entity IDs visible to the user across their accessible
+ * folders. Returns null when the caller is unidentified (no filtering needed —
+ * `filterWikilinks` treats null as "no-op").
+ */
+export function getAccessibleEntityIds(user, workspaceManager, authService) {
+    if (!user)
+        return null;
+    const repos = getAccessibleRepos(user, workspaceManager, authService);
+    const ids = new Set();
+    for (const repo of repos) {
+        try {
+            const graph = workspaceManager.getGraph(repo.name);
+            for (const e of graph.search({})) {
+                ids.add(e.id);
+            }
+        }
+        catch { /* skip unmounted repos */ }
+    }
+    return ids;
+}
+/** Filter a wikilink list to only entities the caller can access. */
+export function filterWikilinks(wikilinks, accessibleIds) {
+    if (!accessibleIds)
+        return wikilinks;
+    return wikilinks.filter(id => accessibleIds.has(id));
+}
+//# sourceMappingURL=access-control.js.map

package/dist/services/access-control.js.map

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

package/dist/services/asset-listing.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared repo-asset listing.
+ *
+ * Builds the list of assets owned by entries in a single repo, merging the two
+ * storage schemes (legacy `{type}/{id}/{filename}` blobs surfaced by the
+ * backend's listAll, and immutable-keyed assets tracked only in the ownership
+ * index). Extracted from the asset-api route so the HTTP endpoints and the MCP
+ * `list_assets` tool return an identical shape — including a render-safe
+ * `embed` string callers can paste straight into an entry body.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+export interface RepoAsset {
+    filename: string;
+    size: number;
+    contentType: string;
+    url: string;
+    /** Render-safe markdown embed: `![filename](url)`. Paste verbatim. */
+    embed: string;
+    /** Immutable asset id when the asset is index-tracked; null for legacy blobs. */
+    assetId: string | null;
+    entityType: string;
+    entityId: string;
+    entityName: string;
+    mediaType: string;
+}
+/**
+ * Build the asset list for a single repo. Returns [] if the repo's graph can't
+ * be loaded (right for the bulk endpoint; single-repo callers should check
+ * repo existence themselves first if they want a 404).
+ *
+ * Algorithm (works for both local and R2 backends):
+ *   1. One listAllAssets() call — single filesystem walk or one paginated S3
+ *      ListObjectsV2 request. No HEAD round-trips, no markdown parsing.
+ *   2. Resolve each asset's entity markdown path via the graph's file index
+ *      (not a `{plural}/{id}.md` guess, which misses root/nested entries).
+ *   3. Merge in immutable-keyed assets from the ownership index — these live
+ *      under an `{assetId}/` prefix the backend's listAll can't see.
+ */
+export declare function listRepoAssets(repo: string, workspaceManager: WorkspaceManager): Promise<RepoAsset[]>;

package/dist/services/asset-listing.js

@@ -0,0 +1,125 @@
+/**
+ * Shared repo-asset listing.
+ *
+ * Builds the list of assets owned by entries in a single repo, merging the two
+ * storage schemes (legacy `{type}/{id}/{filename}` blobs surfaced by the
+ * backend's listAll, and immutable-keyed assets tracked only in the ownership
+ * index). Extracted from the asset-api route so the HTTP endpoints and the MCP
+ * `list_assets` tool return an identical shape — including a render-safe
+ * `embed` string callers can paste straight into an entry body.
+ */
+import { publicUrlFor, publicUrlForAssetId } from './assets/index.js';
+import { assetEmbed } from '../core/embeds.js';
+import { readFileSync } from 'fs';
+/**
+ * Read the `name:` field from a markdown file's YAML frontmatter without a
+ * full YAML parse. Returns null if the file can't be read or has no name.
+ * Lets the asset list label assets by entity name without paying the cost of
+ * a full markdownService.parseFile() per entity.
+ */
+function extractEntityName(mdPath) {
+    try {
+        const raw = readFileSync(mdPath, 'utf-8');
+        // Frontmatter is always at the top; don't read past ~2KB.
+        const head = raw.slice(0, 2048);
+        if (!head.startsWith('---'))
+            return null;
+        const end = head.indexOf('\n---', 3);
+        const block = end === -1 ? head : head.slice(0, end);
+        // Match `name: value` or `name: "value"` or `name: 'value'`.
+        const match = block.match(/^name:\s*(?:'([^']*)'|"([^"]*)"|(.+?))\s*$/m);
+        if (!match)
+            return null;
+        return (match[1] ?? match[2] ?? match[3]).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the asset list for a single repo. Returns [] if the repo's graph can't
+ * be loaded (right for the bulk endpoint; single-repo callers should check
+ * repo existence themselves first if they want a 404).
+ *
+ * Algorithm (works for both local and R2 backends):
+ *   1. One listAllAssets() call — single filesystem walk or one paginated S3
+ *      ListObjectsV2 request. No HEAD round-trips, no markdown parsing.
+ *   2. Resolve each asset's entity markdown path via the graph's file index
+ *      (not a `{plural}/{id}.md` guess, which misses root/nested entries).
+ *   3. Merge in immutable-keyed assets from the ownership index — these live
+ *      under an `{assetId}/` prefix the backend's listAll can't see.
+ */
+export async function listRepoAssets(repo, workspaceManager) {
+    let graph;
+    try {
+        graph = workspaceManager.getGraph(repo);
+    }
+    catch {
+        return [];
+    }
+    let allAssets;
+    try {
+        allAssets = await graph.listAllAssets();
+    }
+    catch {
+        return [];
+    }
+    const nameCache = new Map();
+    const result = [];
+    for (const asset of allAssets) {
+        const mdPath = graph.getEntityFilePath(asset.entityType, asset.entityId);
+        if (!mdPath)
+            continue;
+        const key = `${asset.entityType}/${asset.entityId}`;
+        let entityName = nameCache.get(key);
+        if (entityName === undefined) {
+            entityName = extractEntityName(mdPath) ?? asset.entityId;
+            nameCache.set(key, entityName);
+        }
+        const url = publicUrlFor(asset, asset.entityType, asset.entityId);
+        result.push({
+            filename: asset.filename,
+            size: asset.size,
+            contentType: asset.contentType,
+            url,
+            embed: assetEmbed(asset.filename, url),
+            assetId: null,
+            entityType: asset.entityType,
+            entityId: asset.entityId,
+            entityName,
+            mediaType: asset.mediaType,
+        });
+    }
+    // Immutable-keyed assets live in the ownership index, not under a
+    // {type}/{id} key prefix, so backend.listAll() can't see them. Merge them in
+    // from assets.db. (During the migration cutover — after migrate, before
+    // old-blob cleanup — an asset can appear via both paths; that transient
+    // duplicate clears when the legacy blobs are deleted.)
+    const index = workspaceManager.getAssetIndex?.();
+    if (index) {
+        for (const row of index.listByRepo(repo)) {
+            const mdPath = graph.getEntityFilePath(row.ownerType, row.ownerId);
+            const key = `${row.ownerType}/${row.ownerId}`;
+            let entityName = nameCache.get(key);
+            if (entityName === undefined) {
+                entityName = (mdPath ? extractEntityName(mdPath) : null) ?? row.ownerId;
+                nameCache.set(key, entityName);
+            }
+            const url = publicUrlForAssetId(row.assetId, row.filename);
+            result.push({
+                filename: row.filename,
+                size: 0, // size isn't tracked in the index; a backend HEAD would cost a round-trip
+                contentType: row.contentType,
+                url,
+                embed: assetEmbed(row.filename, url),
+                assetId: row.assetId,
+                entityType: row.ownerType,
+                entityId: row.ownerId,
+                entityName,
+                mediaType: row.mediaType,
+            });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=asset-listing.js.map

package/dist/services/asset-listing.js.map

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

package/dist/services/asset-upload-service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Asset Upload Service
+ *
+ * Single primitive for "store a binary, create a wrapper entity that
+ * points at it." Used by both the standalone `POST /api/repos/:repo/assets`
+ * route and the multi-file import dispatcher when it sees a binary
+ * extension.
+ *
+ * Flow per file:
+ *   1. Validate extension against `ASSET_UPLOAD_EXTENSIONS`.
+ *   2. Create the `asset` entity with stub frontmatter (collision-retry
+ *      on entity_id, same `foo`→`foo-2` semantics as import-service).
+ *   3. Upload the binary via `graph.uploadAsset` — picks R2 or local
+ *      filesystem from the workspace's asset config.
+ *   4. PDFs: extract text + page count via `pdf-parse`, write the text
+ *      to a sidecar at `<workspace>/.studiograph/assets-text/asset/{id}.txt`
+ *      so the vector indexer can RAG it without bloating the markdown body.
+ *   5. Update the entity with the resolved `asset_url` and per-kind
+ *      metadata (`pages`, future `width`/`height`).
+ */
+import type { BaseGraphManager } from '../core/graph.js';
+import type { AssetKind } from '../core/validation.js';
+import type { GitUser } from './git.js';
+export interface UploadAssetOptions {
+    graph: BaseGraphManager;
+    /** Original filename from the client. May contain path segments — only the basename is used. */
+    filename: string;
+    buffer: Buffer;
+    /** Repo-relative folder for the new entity's .md file. Empty/undefined = repo root. */
+    folderPath?: string;
+    /** Override entity name; defaults to title-cased slug of the filename stem. */
+    name?: string;
+    user?: GitUser;
+    /** Defer git commit so the caller can batch (e.g. multi-file imports). Default false. */
+    skipCommit?: boolean;
+    /** Workspace root used to anchor the PDF text sidecar at
+     *  `<workspacePath>/.studiograph/assets-text/asset/{id}.txt`. When
+     *  undefined, sidecars are not written (the asset still uploads). */
+    workspacePath?: string;
+}
+export interface UploadAssetResult {
+    entityId: string;
+    entityType: 'asset';
+    /** Absolute path of the created `.md` entity file. */
+    filePath: string;
+    asset_url: string;
+    asset_kind: AssetKind;
+    asset_size: number;
+    pages?: number;
+    /** Sidecar path when one was written (PDF only). Caller can include in batched commit's extraPaths. */
+    sidecarPath?: string;
+}
+export declare function uploadAsset(opts: UploadAssetOptions): Promise<UploadAssetResult>;

package/dist/services/asset-upload-service.js

@@ -0,0 +1,201 @@
+/**
+ * Asset Upload Service
+ *
+ * Single primitive for "store a binary, create a wrapper entity that
+ * points at it." Used by both the standalone `POST /api/repos/:repo/assets`
+ * route and the multi-file import dispatcher when it sees a binary
+ * extension.
+ *
+ * Flow per file:
+ *   1. Validate extension against `ASSET_UPLOAD_EXTENSIONS`.
+ *   2. Create the `asset` entity with stub frontmatter (collision-retry
+ *      on entity_id, same `foo`→`foo-2` semantics as import-service).
+ *   3. Upload the binary via `graph.uploadAsset` — picks R2 or local
+ *      filesystem from the workspace's asset config.
+ *   4. PDFs: extract text + page count via `pdf-parse`, write the text
+ *      to a sidecar at `<workspace>/.studiograph/assets-text/asset/{id}.txt`
+ *      so the vector indexer can RAG it without bloating the markdown body.
+ *   5. Update the entity with the resolved `asset_url` and per-kind
+ *      metadata (`pages`, future `width`/`height`).
+ */
+import { extname, basename, join } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { log } from '../utils/log.js';
+import { detectAssetKind, detectContentType, isAssetUploadExtension, } from './assets/base.js';
+const slugify = (str) => str.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const formatName = (slug) => slug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+const safeFilename = (name) => name.replace(/[^a-zA-Z0-9._-]/g, '_');
+export async function uploadAsset(opts) {
+    const { graph, buffer, folderPath, user, skipCommit = false, workspacePath } = opts;
+    const onlyName = basename(opts.filename);
+    const ext = extname(onlyName).toLowerCase();
+    if (!isAssetUploadExtension(onlyName)) {
+        throw new Error(`Unsupported asset extension: ${ext || '(none)'}`);
+    }
+    if (!buffer || buffer.length === 0) {
+        throw new Error('Asset upload received an empty buffer');
+    }
+    const assetKind = detectAssetKind(onlyName);
+    const mime = detectContentType(onlyName);
+    // Probe asset configuration before mutating the graph. listAssets() is
+    // cheap and surfaces a helpful error when R2/local storage isn't
+    // wired up — better to fail before creating a stub entity that has
+    // nowhere to point at.
+    try {
+        await graph.listAssets('asset', '__check__');
+    }
+    catch (err) {
+        if (err.message?.includes('not configured')) {
+            throw new Error('Asset storage is not configured for this workspace.');
+        }
+        // Other errors (e.g. entity-not-found) just mean the service IS configured.
+    }
+    const stem = onlyName.replace(/\.[^.]+$/, '');
+    const baseId = (slugify(stem).slice(0, 80).replace(/-$/, '')) || `asset-${Date.now()}`;
+    const name = opts.name ?? formatName(baseId);
+    const now = new Date().toISOString();
+    const userHandle = user?.email?.split('@')[0] ?? user?.name ?? 'upload';
+    const stubData = {
+        entity_type: 'asset',
+        entity_id: baseId,
+        name,
+        // Stub URL — populated post-upload. Required by the schema; '__pending__'
+        // is replaced before the second commit lands.
+        asset_url: '__pending__',
+        asset_kind: assetKind,
+        asset_extension: ext,
+        asset_size: buffer.length,
+        asset_mime: mime,
+        created_at: now,
+        updated_at: now,
+        created_by: userHandle,
+        updated_by: userHandle,
+    };
+    // Collision retry on (asset, entity_id). Mirrors the suffix scheme in
+    // import-service.createWithCollisionRetry — keeps re-uploads from
+    // silently dropping files.
+    let entityId = baseId;
+    let createdPath;
+    let suffix = 0;
+    while (true) {
+        entityId = suffix === 0 ? baseId : `${baseId}-${suffix + 1}`;
+        try {
+            const created = await graph.create({
+                entityType: 'asset',
+                entityId,
+                data: { ...stubData, entity_id: entityId },
+                content: '',
+                folderPath,
+                skipCommit: true,
+                user,
+            });
+            createdPath = created.path;
+            break;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('already exists') || suffix >= 50)
+                throw err;
+            suffix++;
+        }
+    }
+    // Everything past this point operates on a real on-disk stub entity
+    // with `asset_url: '__pending__'`. If any step throws, the stub must be
+    // rolled back — otherwise the entity persists with a placeholder URL
+    // that surfaces as a broken asset in list/gallery/search/RAG. Rollback
+    // commits a delete (graph.delete is auto-commit-only by design); on the
+    // batch import path that's one extra commit per failure, which is
+    // acceptable on a failure path.
+    let pages;
+    let sidecarPath;
+    let asset_url;
+    try {
+        // Storage filename gets a Date.now() prefix to dodge same-name re-uploads.
+        const storedFilename = `${Date.now()}-${safeFilename(onlyName)}`;
+        const asset = await graph.uploadAsset('asset', entityId, storedFilename, buffer);
+        // PDF metadata extraction. pdf-parse is CPU-bound and runs on the
+        // request thread — gate by size so a 100MB PDF doesn't stall the
+        // event loop for every other in-flight Fastify request. Asset still
+        // uploads; it just won't be RAG-searchable until a future re-extract.
+        if (assetKind === 'pdf') {
+            const PDF_TEXT_BYTES_CAP = 20 * 1024 * 1024;
+            if (buffer.length > PDF_TEXT_BYTES_CAP) {
+                log.warn(`[asset-upload] PDF text extraction skipped for ${entityId}: ${buffer.length} bytes > ${PDF_TEXT_BYTES_CAP} cap`);
+            }
+            else {
+                let extractedText = '';
+                try {
+                    const { PDFParse } = await import('pdf-parse');
+                    const parser = new PDFParse({ data: buffer });
+                    const result = await parser.getText();
+                    await parser.destroy();
+                    if (result.total && result.total > 0)
+                        pages = result.total;
+                    extractedText = result.text?.trim() ?? '';
+                }
+                catch (err) {
+                    // Non-fatal — extraction can fail on encrypted/scanned PDFs.
+                    // Don't conflate with sidecar write failures (infra problem,
+                    // not content problem) — those get their own warn below.
+                    log.warn(`[asset-upload] PDF text extraction failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+                }
+                if (extractedText && workspacePath) {
+                    try {
+                        const sidecarDir = join(workspacePath, '.studiograph', 'assets-text', 'asset');
+                        if (!existsSync(sidecarDir))
+                            mkdirSync(sidecarDir, { recursive: true });
+                        sidecarPath = join(sidecarDir, `${entityId}.txt`);
+                        writeFileSync(sidecarPath, extractedText, 'utf-8');
+                    }
+                    catch (err) {
+                        // Sidecar write failures (disk full, permissions) leave the
+                        // asset un-RAG-able but otherwise usable. Re-indexing later
+                        // picks it back up if the sidecar appears.
+                        sidecarPath = undefined;
+                        log.warn(`[asset-upload] PDF sidecar write failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+                    }
+                }
+            }
+        }
+        // Canonical URL from uploadAsset (immutable-key scheme when wired, else
+        // legacy). Don't re-derive — the assetId isn't recoverable from (type,id).
+        asset_url = asset.publicUrl;
+        const updateData = { asset_url };
+        if (pages !== undefined)
+            updateData.pages = pages;
+        await graph.update({
+            entityType: 'asset',
+            entityId,
+            data: updateData,
+            skipCommit: true,
+            user,
+        });
+    }
+    catch (err) {
+        try {
+            await graph.delete('asset', entityId, `Rollback failed asset upload: ${entityId}`, user);
+        }
+        catch (cleanupErr) {
+            log.warn(`[asset-upload] rollback delete failed for ${entityId}: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+        }
+        throw err;
+    }
+    if (!skipCommit) {
+        const git = graph.getGitService();
+        if (git) {
+            const commitUser = user ?? { id: 'upload', name: 'Upload', email: 'upload@studiograph' };
+            git.commitAll(`Upload asset: ${entityId}`, commitUser);
+        }
+    }
+    return {
+        entityId,
+        entityType: 'asset',
+        filePath: createdPath,
+        asset_url,
+        asset_kind: assetKind,
+        asset_size: buffer.length,
+        pages,
+        sidecarPath,
+    };
+}
+//# sourceMappingURL=asset-upload-service.js.map