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

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

@@ -0,0 +1,96 @@
+/**
+ * Asset Sidecar Extraction
+ *
+ * Pure-ish helpers for turning a document asset's bytes into searchable text
+ * and persisting it to an index sidecar. The asset-as-embed import path
+ * (`asset-import-service.ts`) and the boot/live re-index sweep
+ * (`asset-index-sweep.ts`) share these.
+ *
+ * (The legacy `uploadAsset` primitive that created a self-owning `asset`
+ * entity was removed in Phase B2/E — every live upload path now stores a
+ * free-standing, folder-owned asset and, for imports, seeds a typed entity.)
+ */
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { log } from '../utils/log.js';
+/** Bytes above which we skip request-thread text extraction. The parsers
+ *  (pdf-parse / mammoth / SheetJS) are CPU-bound and synchronous; a huge file
+ *  would stall the event loop for every other in-flight request. The asset
+ *  still uploads — it just isn't sidecar-searchable until a later re-extract. */
+const SIDECAR_EXTRACT_BYTES_CAP = 25 * 1024 * 1024;
+/**
+ * Extract searchable text from a document asset for its index sidecar (P3 —
+ * generalized from PDF-only). Driven by the format registry's `extractor`:
+ * pdf → pdf-parse (also yields page count), docx → mammoth raw text, xlsx →
+ * every non-empty sheet as CSV. `image-caption` and `null` produce no sidecar
+ * here — image captioning is the async P3b pass, opaque assets stay
+ * filename-only. Best-effort: extraction errors return empty text (the asset
+ * is still stored + indexed by frontmatter).
+ */
+export async function extractSidecarText(buffer, extractor, entityId) {
+    if (!extractor || extractor === 'image-caption')
+        return { text: '' };
+    if (buffer.length > SIDECAR_EXTRACT_BYTES_CAP) {
+        log.warn(`[asset-upload] sidecar extraction skipped for ${entityId}: ${buffer.length} bytes > ${SIDECAR_EXTRACT_BYTES_CAP} cap`);
+        return { text: '' };
+    }
+    try {
+        if (extractor === 'pdf') {
+            const { PDFParse } = await import('pdf-parse');
+            const parser = new PDFParse({ data: buffer });
+            try {
+                // pageJoiner: '' suppresses pdf-parse's default `-- N of M --` page
+                // markers, which otherwise litter both the search sidecar AND the
+                // seeded document body (asset-import-service reuses this text).
+                const result = await parser.getText({ pageJoiner: '' });
+                return { text: result.text?.trim() ?? '', pages: result.total && result.total > 0 ? result.total : undefined };
+            }
+            finally {
+                // Always release the parser — on an encrypted/malformed PDF getText()
+                // throws, and without finally the handle/buffers would leak.
+                await parser.destroy();
+            }
+        }
+        if (extractor === 'docx') {
+            const mammoth = await import('mammoth');
+            const result = await mammoth.extractRawText({ buffer });
+            return { text: result.value?.trim() ?? '' };
+        }
+        if (extractor === 'xlsx') {
+            const XLSX = await import('xlsx');
+            const wb = XLSX.read(buffer, { type: 'buffer' });
+            const parts = [];
+            for (const name of wb.SheetNames) {
+                const sheet = wb.Sheets[name];
+                if (!sheet || !sheet['!ref'])
+                    continue;
+                const csv = XLSX.utils.sheet_to_csv(sheet, { blankrows: false }).trim();
+                if (csv)
+                    parts.push(`# ${name}\n${csv}`);
+            }
+            return { text: parts.join('\n\n').trim() };
+        }
+    }
+    catch (err) {
+        log.warn(`[asset-upload] sidecar extraction failed for ${entityId} (${extractor}): ${err instanceof Error ? err.message : err}`);
+    }
+    return { text: '' };
+}
+/** Write an asset's extracted text to its sidecar (keyed by entity id).
+ *  Returns the path on success (for batched commit's extraPaths), undefined on
+ *  failure (non-fatal — the asset is still usable, just not sidecar-indexed). */
+export function writeAssetSidecar(workspacePath, entityId, text) {
+    try {
+        const sidecarDir = join(workspacePath, '.studiograph', 'assets-text', 'asset');
+        if (!existsSync(sidecarDir))
+            mkdirSync(sidecarDir, { recursive: true });
+        const sidecarPath = join(sidecarDir, `${entityId}.txt`);
+        writeFileSync(sidecarPath, text, 'utf-8');
+        return sidecarPath;
+    }
+    catch (err) {
+        log.warn(`[asset-upload] sidecar write failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=asset-sidecar-service.js.map

package/dist/services/asset-sidecar-service.js.map

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

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

@@ -0,0 +1,41 @@
+/**
+ * Typed Error classes for the MCP pre-signed asset upload flow.
+ *
+ * The presign and finalize services throw these; `errorToMcpResult()` in
+ * `mcp/tools.ts` maps each to a `fail()` envelope with a `code` discriminator
+ * the agent can branch on. Generic `Error` thrown from the same call sites
+ * fall through to the default "unknown" code. See ~/.claude/plans/
+ * mcp-presigned-asset-upload.md decision R4.
+ *
+ * The `code` field is read by clients; the message is human-facing. Keep
+ * codes stable across releases — agent prompts and downstream MCP-host UIs
+ * key off them.
+ */
+export declare class AssetUploadError extends Error {
+    /** Stable machine-readable identifier. Set by each subclass; the base
+     *  class declares it so a generic catch can read `err.code` without a
+     *  narrowing dance. */
+    readonly code: string;
+    constructor(message: string);
+}
+export declare class InvalidMimeTypeError extends AssetUploadError {
+    readonly code = "invalid_mime";
+}
+export declare class InvalidFilenameError extends AssetUploadError {
+    readonly code = "invalid_filename";
+}
+export declare class ForbiddenError extends AssetUploadError {
+    readonly code = "forbidden";
+}
+export declare class LocalBackendNotSupportedError extends AssetUploadError {
+    readonly code = "local_backend";
+}
+export declare class TokenInvalidError extends AssetUploadError {
+    readonly code = "token_invalid";
+}
+export declare class UploadNotReceivedError extends AssetUploadError {
+    readonly code = "upload_not_received";
+}
+export declare class UploadValidationError extends AssetUploadError {
+    readonly code = "upload_validation";
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Typed Error classes for the MCP pre-signed asset upload flow.
+ *
+ * The presign and finalize services throw these; `errorToMcpResult()` in
+ * `mcp/tools.ts` maps each to a `fail()` envelope with a `code` discriminator
+ * the agent can branch on. Generic `Error` thrown from the same call sites
+ * fall through to the default "unknown" code. See ~/.claude/plans/
+ * mcp-presigned-asset-upload.md decision R4.
+ *
+ * The `code` field is read by clients; the message is human-facing. Keep
+ * codes stable across releases — agent prompts and downstream MCP-host UIs
+ * key off them.
+ */
+export class AssetUploadError extends Error {
+    /** Stable machine-readable identifier. Set by each subclass; the base
+     *  class declares it so a generic catch can read `err.code` without a
+     *  narrowing dance. */
+    code = 'asset_upload_error';
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+export class InvalidMimeTypeError extends AssetUploadError {
+    code = 'invalid_mime';
+}
+export class InvalidFilenameError extends AssetUploadError {
+    code = 'invalid_filename';
+}
+export class ForbiddenError extends AssetUploadError {
+    code = 'forbidden';
+}
+export class LocalBackendNotSupportedError extends AssetUploadError {
+    code = 'local_backend';
+}
+export class TokenInvalidError extends AssetUploadError {
+    code = 'token_invalid';
+}
+export class UploadNotReceivedError extends AssetUploadError {
+    code = 'upload_not_received';
+}
+export class UploadValidationError extends AssetUploadError {
+    code = 'upload_validation';
+}
+//# sourceMappingURL=asset-upload-errors.js.map

package/dist/services/asset-upload-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-errors.js","sourceRoot":"","sources":["../../src/services/asset-upload-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;;2BAEuB;IACd,IAAI,GAAW,oBAAoB,CAAC;IAE7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,gBAAgB;IAC/C,IAAI,GAAG,cAAc,CAAC;CAChC;AAED,MAAM,OAAO,oBAAqB,SAAQ,gBAAgB;IAC/C,IAAI,GAAG,kBAAkB,CAAC;CACpC;AAED,MAAM,OAAO,cAAe,SAAQ,gBAAgB;IACzC,IAAI,GAAG,WAAW,CAAC;CAC7B;AAED,MAAM,OAAO,6BAA8B,SAAQ,gBAAgB;IACxD,IAAI,GAAG,eAAe,CAAC;CACjC;AAED,MAAM,OAAO,iBAAkB,SAAQ,gBAAgB;IAC5C,IAAI,GAAG,eAAe,CAAC;CACjC;AAED,MAAM,OAAO,sBAAuB,SAAQ,gBAAgB;IACjD,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAED,MAAM,OAAO,qBAAsB,SAAQ,gBAAgB;IAChD,IAAI,GAAG,mBAAmB,CAAC;CACrC"}

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

@@ -0,0 +1,74 @@
+/**
+ * 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 FormatExtractor } from '../core/format-registry.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;
+    /** Auth user id of the uploader (web). Recorded in the asset index for the
+     *  uploader+owner delete rule. Omit for CLI/import — stored as null. */
+    uploaderUserId?: string | null;
+}
+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;
+}
+/**
+ * Extract searchable text from a document asset for its index sidecar (P3 —
+ * generalized from PDF-only). Driven by the format registry's `extractor`:
+ * pdf → pdf-parse (also yields page count), docx → mammoth raw text, xlsx →
+ * every non-empty sheet as CSV. `image-caption` and `null` produce no sidecar
+ * here — image captioning is the async P3b pass, opaque assets stay
+ * filename-only. Best-effort: extraction errors return empty text (the asset
+ * is still stored + indexed by frontmatter).
+ */
+export declare function extractSidecarText(buffer: Buffer, extractor: FormatExtractor, entityId: string): Promise<{
+    text: string;
+    pages?: number;
+}>;
+/** Write an asset's extracted text to its sidecar (keyed by entity id).
+ *  Returns the path on success (for batched commit's extraPaths), undefined on
+ *  failure (non-fatal — the asset is still usable, just not sidecar-indexed). */
+export declare function writeAssetSidecar(workspacePath: string, entityId: string, text: string): string | undefined;
+export declare function uploadAsset(opts: UploadAssetOptions): Promise<UploadAssetResult>;

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

@@ -0,0 +1,244 @@
+/**
+ * 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, safeFilename, } from './assets/base.js';
+import { createWithCollisionRetry } from './import-service.js';
+import { resolveFormat, isIndexable } from '../core/format-registry.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());
+/** Bytes above which we skip request-thread text extraction. The parsers
+ *  (pdf-parse / mammoth / SheetJS) are CPU-bound and synchronous; a huge file
+ *  would stall the event loop for every other in-flight request. The asset
+ *  still uploads — it just isn't sidecar-searchable until a later re-extract. */
+const SIDECAR_EXTRACT_BYTES_CAP = 25 * 1024 * 1024;
+/**
+ * Extract searchable text from a document asset for its index sidecar (P3 —
+ * generalized from PDF-only). Driven by the format registry's `extractor`:
+ * pdf → pdf-parse (also yields page count), docx → mammoth raw text, xlsx →
+ * every non-empty sheet as CSV. `image-caption` and `null` produce no sidecar
+ * here — image captioning is the async P3b pass, opaque assets stay
+ * filename-only. Best-effort: extraction errors return empty text (the asset
+ * is still stored + indexed by frontmatter).
+ */
+export async function extractSidecarText(buffer, extractor, entityId) {
+    if (!extractor || extractor === 'image-caption')
+        return { text: '' };
+    if (buffer.length > SIDECAR_EXTRACT_BYTES_CAP) {
+        log.warn(`[asset-upload] sidecar extraction skipped for ${entityId}: ${buffer.length} bytes > ${SIDECAR_EXTRACT_BYTES_CAP} cap`);
+        return { text: '' };
+    }
+    try {
+        if (extractor === 'pdf') {
+            const { PDFParse } = await import('pdf-parse');
+            const parser = new PDFParse({ data: buffer });
+            try {
+                // pageJoiner: '' suppresses pdf-parse's default `-- N of M --` page
+                // markers, which otherwise litter both the search sidecar AND the
+                // seeded document body (asset-import-service reuses this text).
+                const result = await parser.getText({ pageJoiner: '' });
+                return { text: result.text?.trim() ?? '', pages: result.total && result.total > 0 ? result.total : undefined };
+            }
+            finally {
+                // Always release the parser — on an encrypted/malformed PDF getText()
+                // throws, and without finally the handle/buffers would leak.
+                await parser.destroy();
+            }
+        }
+        if (extractor === 'docx') {
+            const mammoth = await import('mammoth');
+            const result = await mammoth.extractRawText({ buffer });
+            return { text: result.value?.trim() ?? '' };
+        }
+        if (extractor === 'xlsx') {
+            const XLSX = await import('xlsx');
+            const wb = XLSX.read(buffer, { type: 'buffer' });
+            const parts = [];
+            for (const name of wb.SheetNames) {
+                const sheet = wb.Sheets[name];
+                if (!sheet || !sheet['!ref'])
+                    continue;
+                const csv = XLSX.utils.sheet_to_csv(sheet, { blankrows: false }).trim();
+                if (csv)
+                    parts.push(`# ${name}\n${csv}`);
+            }
+            return { text: parts.join('\n\n').trim() };
+        }
+    }
+    catch (err) {
+        log.warn(`[asset-upload] sidecar extraction failed for ${entityId} (${extractor}): ${err instanceof Error ? err.message : err}`);
+    }
+    return { text: '' };
+}
+/** Write an asset's extracted text to its sidecar (keyed by entity id).
+ *  Returns the path on success (for batched commit's extraPaths), undefined on
+ *  failure (non-fatal — the asset is still usable, just not sidecar-indexed). */
+export function writeAssetSidecar(workspacePath, entityId, text) {
+    try {
+        const sidecarDir = join(workspacePath, '.studiograph', 'assets-text', 'asset');
+        if (!existsSync(sidecarDir))
+            mkdirSync(sidecarDir, { recursive: true });
+        const sidecarPath = join(sidecarDir, `${entityId}.txt`);
+        writeFileSync(sidecarPath, text, 'utf-8');
+        return sidecarPath;
+    }
+    catch (err) {
+        log.warn(`[asset-upload] sidecar write failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+        return undefined;
+    }
+}
+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) via the shared helper — one suffix
+    // algorithm (`foo`→`foo-2`→…) for every create path, so re-uploads never
+    // silently drop a file (CQ2: was an inline duplicate of this loop).
+    const { entityId, path: createdPath } = await createWithCollisionRetry(graph, {
+        entityType: 'asset',
+        entityId: baseId,
+        data: stubData,
+        content: '',
+        folderPath,
+        skipCommit: true,
+        user,
+        // Don't index the `__pending__` stub: it has no sidecar and no `indexable`
+        // flag yet, so it would index name-only — and its async embedding can race
+        // the finalizing update's body-inclusive upsert below, clobbering the good
+        // row (the asset would be searchable by filename only). The single
+        // authoritative upsert is the `graph.update` after the sidecar is written.
+        skipVectorIndex: true,
+    });
+    // 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, undefined, { uploaderUserId: opts.uploaderUserId ?? null });
+        // Sidecar text extraction (P3 — generalized from PDF-only to docx/xlsx
+        // via the format registry's extractor). Runs on the request thread, so
+        // it's size-gated inside extractSidecarText. Best-effort: the asset
+        // uploads regardless; it just won't be sidecar-searchable until a later
+        // re-extract. Images don't extract here — captioning is the async P3b
+        // pass.
+        const format = resolveFormat(onlyName);
+        const { text: sidecarText, pages: extractedPages } = await extractSidecarText(buffer, format.extractor, entityId);
+        if (extractedPages !== undefined)
+            pages = extractedPages;
+        if (sidecarText && workspacePath) {
+            sidecarPath = writeAssetSidecar(workspacePath, entityId, sidecarText);
+        }
+        // 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;
+        // `indexable` (A1, immutable): set once at import from the registry's
+        // declared indexability (indexAs !== 'none'). The mutable run state
+        // (index_status) lives in LanceDB and is wired by the P3b caption pass.
+        const updateData = { asset_url, indexable: isIndexable(format) };
+        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

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

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

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

@@ -0,0 +1,58 @@
+/**
+ * HMAC-signed token bound to a pending pre-signed asset upload.
+ *
+ * Flow: presign mints a token + signed PUT URL; the agent uploads bytes to
+ * R2 directly, then calls `finalize_asset_upload({ token })`. The token
+ * carries enough state for finalize to find the pending blob, re-check the
+ * caller's authz, and register the asset — without trusting any arg from the
+ * agent. See ~/.claude/plans/mcp-presigned-asset-upload.md.
+ *
+ * Signed with `STUDIOGRAPH_JWT_SECRET` via `authService.getJwtSecret()`.
+ * Reusing the workspace's JWT secret is deliberate: one rotation lever, one
+ * audit boundary, and Phase 4 already env-requires it in production.
+ *
+ * The token is a bearer credential — anything that holds it can finalize as
+ * the original presigner. R1 in the plan closes the leak-and-replay vector
+ * by binding `payload.uploaderUserId` to the calling user at finalize.
+ */
+export interface AssetUploadTokenPayload {
+    /** UUIDv4 generated at presign. Doubles as the entity_id when the asset
+     *  is self-owned (entity == undefined at presign). */
+    assetId: string;
+    /** Resolved repo name. Default = workspace assets folder; otherwise the
+     *  explicit repo the agent passed. Finalize re-checks `canWriteRepo` on
+     *  this. */
+    repo: string;
+    /** Owning entity type. 'asset' when self-owned (no entity attachment),
+     *  else an entity type the agent passed at presign. */
+    ownerType: string;
+    /** Owning entity id. assetId when self-owned, else the entity id. */
+    ownerId: string;
+    /** Auth user id (as string — AuthUser.id is number but the index column
+     *  is TEXT) of the user who presigned. Bound to the finalize caller via
+     *  R1: leaked tokens can't be replayed by another folder-writer. */
+    uploaderUserId: string;
+    /** Pinned mime type. Restricted to the registry's presign-safe set
+     *  (`presignMimeAllowlist()` — png/jpeg/gif/webp/avif/heic; SVG excluded).
+     *  Pinned into the PUT signature so finalize can assert the stored
+     *  Content-Type matches. */
+    mime: string;
+    /** Sanitized filename (post-safeFilename). Used to build the pending key
+     *  and the canonical key — finalize doesn't accept a separate filename
+     *  arg so the agent can't rename mid-flow. */
+    filename: string;
+}
+export declare function signAssetUploadToken(payload: AssetUploadTokenPayload, secret: string): string;
+/**
+ * Verify a token and return the payload. Throws `TokenInvalidError` on:
+ *   - tamper (any field mutated, including assetId)
+ *   - wrong secret (rotation mid-flight)
+ *   - expired (>15min since presign)
+ *   - malformed (not a JWT, wrong shape)
+ *
+ * Caller (finalize) is responsible for the post-verify checks:
+ *   - R1 identity bind: assert `String(user.id) === payload.uploaderUserId`
+ *   - re-check `canWriteRepo(user, payload.repo, ...)`
+ *   - HEAD the pending blob and validate ct + size
+ */
+export declare function verifyAssetUploadToken(token: string, secret: string): AssetUploadTokenPayload;