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

package/dist/services/assets/base.js

@@ -1,8 +1,18 @@
 /**
  * Base types and interfaces for asset management
  */
+import { assetUploadExtensions } from '../../core/format-registry.js';
 /**
- * Content type mappings
+ * Content type mappings.
+ *
+ * TODO(import-refactor): this map + `detectAssetKind` are a second source of
+ * truth for per-extension MIME / kind alongside the format registry
+ * (`src/core/format-registry.ts`, which owns `mimeTypes`). Folding them into
+ * the registry is deferred because it would change observable behavior the
+ * P0 parity refactor must preserve (e.g. svg's asset_kind `other`→`image`,
+ * tsv's Content-Type `octet-stream`→`text/tab-separated-values`). Until that
+ * unification lands, `format-registry.test.ts` guards the two against drift
+ * on every shared extension.
  */
 export const CONTENT_TYPES = {
     // Images
@@ -51,6 +61,57 @@ export function detectContentType(filename) {
     const ext = filename.split('.').pop()?.toLowerCase() || '';
     return CONTENT_TYPES[ext] || 'application/octet-stream';
 }
+/**
+ * Map a filename to the high-level `asset_kind` written into the asset
+ * entity's frontmatter. Drives icon and viewer selection; coarser than
+ * MIME so the UI doesn't need to enumerate every format. The kind set
+ * is canonical in `ASSET_KINDS` in src/core/validation.ts.
+ */
+export function detectAssetKind(filename) {
+    const ext = filename.split('.').pop()?.toLowerCase() || '';
+    if (IMAGE_EXTS.has(ext))
+        return 'image';
+    if (VIDEO_EXTS.has(ext))
+        return 'video';
+    if (AUDIO_EXTS.has(ext))
+        return 'audio';
+    if (ext === 'pdf')
+        return 'pdf';
+    if (SPREADSHEET_EXTS.has(ext))
+        return 'spreadsheet';
+    return 'other';
+}
+// SVG is intentionally excluded — see docs/asset-architecture.md §security.
+// Stored XSS risk: SVG can contain <script> and the GET /api/assets/* route
+// serves files inline with `Content-Type: image/svg+xml`, which executes in
+// the app origin. Users who need vector assets can paste source into a note
+// or embed via the editor's per-entity attach (which also blocks SVG).
+const IMAGE_EXTS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'heic']);
+const VIDEO_EXTS = new Set(['mp4', 'mov', 'webm', 'avi', 'mkv', 'm4v']);
+const AUDIO_EXTS = new Set(['mp3', 'wav', 'm4a', 'ogg', 'flac', 'aac']);
+const SPREADSHEET_EXTS = new Set(['csv', 'xlsx', 'xls', 'numbers', 'tsv']);
+// Other formerly-categorized extensions (indd, sketch, psd, ai, fig, doc/docx,
+// pptx, key, pages, zip, tar, etc.) all fall to `other` for asset_kind. The
+// product has no preview / extract support for them today, so the previous
+// fine-grained kinds were noise. The set of opaque extensions the upload
+// route ACCEPTS now lives in the format registry (see ASSET_UPLOAD_EXTENSIONS
+// below); detectAssetKind only needs the families it classifies distinctly.
+/**
+ * Extension set the asset upload route accepts (bare, no leading dot).
+ *
+ * The format registry (`src/core/format-registry.ts`) is the single source
+ * of truth for this set — it owns the canonical disposition of every format.
+ * This re-export keeps `isAssetUploadExtension` and the (untouched) agent
+ * `import_file` tool working against the same data, with no parallel list to
+ * drift. The registry's `assetUploadExtensions()` reproduces the historical
+ * membership exactly (including `.csv`, which the agent tool stores as an
+ * opaque asset even though the web path writes it as a dataset).
+ */
+export const ASSET_UPLOAD_EXTENSIONS = assetUploadExtensions();
+export function isAssetUploadExtension(filename) {
+    const ext = filename.split('.').pop()?.toLowerCase() || '';
+    return ASSET_UPLOAD_EXTENSIONS.has(ext);
+}
 /**
  * Determine media type from content type
  */
@@ -71,6 +132,21 @@ export function getMediaType(contentType) {
     }
     return 'other';
 }
+/**
+ * Sanitize a filename for use as a storage key segment.
+ *
+ * Replaces every character that's not `[a-zA-Z0-9._-]` with `_`. Preserves
+ * the extension via the `.` allowlist; preserves common separators (`_` and
+ * `-`) so display titles derived from the slug stay readable.
+ *
+ * NOT a security boundary — `validateFilename()` above is the gate that
+ * throws on traversal / hidden / forbidden chars / length. `safeFilename`
+ * is the post-validation key builder. Promoted from
+ * `asset-sidecar-service.ts` so the MCP presign flow can share it.
+ */
+export function safeFilename(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
 /**
  * Validate filename for security
  */

package/dist/services/assets/base.js.map

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

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

@@ -4,11 +4,83 @@
  * Manages all media assets (images, videos, audio, documents)
  * with pluggable storage backends (local filesystem or R2)
  */
-import type { AssetInfo, AssetConfig } from './base.js';
+import type { AssetInfo, AssetRecord, AssetConfig } from './base.js';
 export * from './base.js';
+/**
+ * Result of `graph.uploadAsset`. Extends AssetInfo with the canonical public
+ * URL the caller should embed/store (`publicUrl`) and, on the immutable-key
+ * path, the generated `assetId`. Centralizing the URL here keeps callers from
+ * re-deriving `/api/assets/...` (and getting the scheme wrong).
+ */
+export interface AssetUploadResult extends AssetInfo {
+    assetId?: string;
+    publicUrl: string;
+}
 export declare class AssetService {
     private backend;
+    private storage;
     constructor(config: AssetConfig);
+    /** Which backend this service is bound to. Routes that need different
+     *  serving strategies per backend (e.g. stream local files vs. 302 to
+     *  pre-signed URL for R2) branch on this. */
+    getStorage(): 'local' | 'r2';
+    /** Whether the backend can mint short-lived pre-signed download URLs.
+     *  True for R2; false for local (where the HTTP server streams files
+     *  directly). */
+    supportsSignedUrls(): boolean;
+    /** Whether the backend supports the full pre-signed PUT + HEAD + copy
+     *  lifecycle needed for the MCP presign flow. Tied to all three because a
+     *  backend that signs PUT but can't HEAD-verify the upload would break
+     *  the finalize contract. R2 supports all three; local supports none. */
+    supportsPresignedUploads(): boolean;
+    /** Generate a short-lived pre-signed download URL for an asset.
+     *  Throws if the backend doesn't support pre-signed URLs (local).
+     *  Default expiry is 4 hours (14400s) — see R2AssetBackend.getSignedUrl
+     *  for the rationale. `method` selects the HTTP verb the URL is signed
+     *  against — HEAD requests (link unfurls, OpenGraph) need a HEAD-signed
+     *  URL because pre-signed URLs are method-bound. */
+    getSignedUrl(entityType: string, entityId: string, filename: string, keyPrefix?: string, expiresIn?: number, method?: 'GET' | 'HEAD'): Promise<string>;
+    /** Reject key segments that could escape the prefix. */
+    private assertSafeSegment;
+    /** Upload bytes under an immutable assetId key. Caller records the index row. */
+    uploadByAssetId(assetId: string, filename: string, buffer: Buffer): Promise<AssetInfo>;
+    getSignedUrlByAssetId(assetId: string, filename: string, expiresIn?: number, method?: 'GET' | 'HEAD'): Promise<string>;
+    deleteByAssetId(assetId: string, filename: string): Promise<void>;
+    existsByAssetId(assetId: string, filename: string): Promise<boolean>;
+    private pendingKey;
+    private canonicalKey;
+    signPendingPutUrl(assetId: string, filename: string, contentType: string, expiresIn?: number): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+    }>;
+    /** HEAD the pending blob. Returns null when the agent never PUT (or the
+     *  TTL already expired). */
+    headPending(assetId: string, filename: string): Promise<{
+        contentType: string;
+        size: number;
+    } | null>;
+    /** Server-side copy pending → canonical (R2's CopyObject — no download). */
+    copyPendingToCanonical(assetId: string, filename: string): Promise<void>;
+    deletePending(assetId: string, filename: string): Promise<void>;
+    /** Bucket lifecycle rules summary for the MCP presign flow's boot-time
+     *  backstop. Returns `null` when the backend has no lifecycle support
+     *  (local) or when the bucket has no rules configured at all. Throws on
+     *  permission / network errors so the caller can decide whether to
+     *  degrade or propagate. */
+    getBucketLifecycle(): Promise<Array<{
+        prefix: string | undefined;
+        expirationDays: number | undefined;
+        enabled: boolean;
+    }> | null>;
+    /** Download an object's bytes by raw key. Validates every path segment —
+     *  the key is derived from a stored `asset_url`, so a `..` segment must
+     *  never reach the backend's path join (arbitrary-file read). */
+    download(key: string): Promise<Buffer>;
+    /** Server-side copy between raw keys (migration + transfer-copy). Validates
+     *  every path segment of both keys — the migration derives srcKey from
+     *  user-editable body URLs, so a `..` in a key segment must never reach the
+     *  backend's path join (arbitrary-file read/write). */
+    copy(srcKey: string, destKey: string): Promise<void>;
     /**
      * Upload asset for an entity
      */
@@ -17,6 +89,11 @@ export declare class AssetService {
      * List all assets for an entity
      */
     list(entityType: string, entityId: string, keyPrefix?: string): Promise<AssetInfo[]>;
+    /**
+     * List every asset in the backend in one round-trip, with their
+     * (entityType, entityId) origins parsed from the storage key.
+     */
+    listAll(): Promise<AssetRecord[]>;
     /**
      * Delete a single asset
      */
@@ -34,3 +111,28 @@ export declare class AssetService {
      */
     getInfo(entityType: string, entityId: string, filename: string, keyPrefix?: string): Promise<AssetInfo | null>;
 }
+/**
+ * Convert an `AssetInfo` returned by a backend into the URL stored in
+ * an entity's `asset_url` (or used as the `src` of an inline embed).
+ *
+ * Stage 2 of the asset architecture (see docs/asset-architecture.md):
+ * always emit the proxied `/api/assets/{type}/{id}/{file}` path, regardless
+ * of backend. The route is the single chokepoint that enforces per-repo
+ * authz — local files are streamed directly, R2-backed assets get a 302
+ * to a short-lived pre-signed URL. New uploads never persist absolute
+ * R2 URLs in frontmatter; the migration CLI rewrites legacy ones.
+ *
+ * Centralised here because three different call sites used to inline this
+ * ternary, and getting it wrong silently breaks image rendering.
+ */
+export declare function publicUrlFor(_asset: {
+    url: string;
+    path: string;
+    filename: string;
+}, entityType: string, entityId: string): string;
+/**
+ * Immutable-key public URL: `/api/assets/{assetId}/{filename}`. Two path
+ * segments after `/api/assets/` (vs three for the legacy form), so the new
+ * and legacy serving routes disambiguate by arity during cutover.
+ */
+export declare function publicUrlForAssetId(assetId: string, filename: string): string;

package/dist/services/assets/index.js

@@ -10,22 +10,182 @@ import { R2AssetBackend } from './r2.js';
 export * from './base.js';
 export class AssetService {
     backend;
+    storage;
     constructor(config) {
         // Initialize appropriate backend
         if (config.storage === 'local') {
             const localPath = config.localPath || '.studiograph/assets';
             this.backend = new LocalAssetBackend(localPath);
+            this.storage = 'local';
         }
         else if (config.storage === 'r2') {
             if (!config.r2Config) {
                 throw new Error('R2 config is required when storage is set to r2');
             }
             this.backend = new R2AssetBackend(config.r2Config);
+            this.storage = 'r2';
         }
         else {
             throw new Error(`Unknown storage backend: ${config.storage}`);
         }
     }
+    /** Which backend this service is bound to. Routes that need different
+     *  serving strategies per backend (e.g. stream local files vs. 302 to
+     *  pre-signed URL for R2) branch on this. */
+    getStorage() {
+        return this.storage;
+    }
+    /** Whether the backend can mint short-lived pre-signed download URLs.
+     *  True for R2; false for local (where the HTTP server streams files
+     *  directly). */
+    supportsSignedUrls() {
+        return typeof this.backend.getSignedUrl === 'function';
+    }
+    /** Whether the backend supports the full pre-signed PUT + HEAD + copy
+     *  lifecycle needed for the MCP presign flow. Tied to all three because a
+     *  backend that signs PUT but can't HEAD-verify the upload would break
+     *  the finalize contract. R2 supports all three; local supports none. */
+    supportsPresignedUploads() {
+        return (typeof this.backend.getSignedPutUrl === 'function' &&
+            typeof this.backend.head === 'function' &&
+            typeof this.backend.copy === 'function');
+    }
+    /** Generate a short-lived pre-signed download URL for an asset.
+     *  Throws if the backend doesn't support pre-signed URLs (local).
+     *  Default expiry is 4 hours (14400s) — see R2AssetBackend.getSignedUrl
+     *  for the rationale. `method` selects the HTTP verb the URL is signed
+     *  against — HEAD requests (link unfurls, OpenGraph) need a HEAD-signed
+     *  URL because pre-signed URLs are method-bound. */
+    async getSignedUrl(entityType, entityId, filename, keyPrefix, expiresIn = 14400, method = 'GET') {
+        if (!this.backend.getSignedUrl) {
+            throw new Error('Pre-signed URLs are not supported by the local asset backend');
+        }
+        // Validate every key component, not just filename. Without this, a
+        // caller passing entityType='..' or entityId='../' could mint a
+        // signed URL for any object in the bucket — including non-asset
+        // prefixes (fonts, tokens, theme blobs). Today the only caller
+        // is the asset route which feeds Fastify path segments (so `/` is
+        // already blocked), but the AssetService is a public surface and
+        // future callers shouldn't have to know about the route's quirks.
+        for (const part of [entityType, entityId, filename]) {
+            if (!part || part.includes('/') || part.includes('\\') || part.includes('..')) {
+                throw new Error('Asset key components cannot contain path separators or traversal sequences');
+            }
+        }
+        validateFilename(filename);
+        const key = buildAssetKey(entityType, entityId, filename, keyPrefix);
+        return await this.backend.getSignedUrl(key, expiresIn, method);
+    }
+    // ── Immutable-key (assetId) surface ──────────────────────────────────────
+    //
+    // New scheme: assets are keyed `{assetId}/{filename}` where assetId is an
+    // immutable UUID. The owning entity's (type,id) is no longer in the key —
+    // ownership/authz lives in AssetIndexService. The legacy `(type,id,filename)`
+    // methods above stay for the dual-read cutover window.
+    /** Reject key segments that could escape the prefix. */
+    assertSafeSegment(seg) {
+        if (!seg || seg.includes('/') || seg.includes('\\') || seg.includes('..')) {
+            throw new Error('Asset key components cannot contain path separators or traversal sequences');
+        }
+    }
+    /** Upload bytes under an immutable assetId key. Caller records the index row. */
+    async uploadByAssetId(assetId, filename, buffer) {
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        if (!buffer || buffer.length === 0)
+            throw new Error('Buffer cannot be empty');
+        const maxSize = 100 * 1024 * 1024;
+        if (buffer.length > maxSize)
+            throw new Error(`File too large (max ${maxSize / 1024 / 1024}MB)`);
+        const contentType = detectContentType(filename);
+        return await this.backend.upload(`${assetId}/${filename}`, buffer, contentType);
+    }
+    async getSignedUrlByAssetId(assetId, filename, expiresIn = 14400, method = 'GET') {
+        if (!this.backend.getSignedUrl) {
+            throw new Error('Pre-signed URLs are not supported by the local asset backend');
+        }
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        return await this.backend.getSignedUrl(`${assetId}/${filename}`, expiresIn, method);
+    }
+    async deleteByAssetId(assetId, filename) {
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        return await this.backend.delete(`${assetId}/${filename}`);
+    }
+    async existsByAssetId(assetId, filename) {
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        return await this.backend.exists(`${assetId}/${filename}`);
+    }
+    // ── Pending-upload (MCP presign) surface ────────────────────────────────
+    //
+    // Quarantine prefix: `pending/{assetId}/{filename}`. The agent PUTs bytes
+    // here directly via a pre-signed URL; finalize HEADs + copies into the
+    // canonical `{assetId}/{filename}` keyspace + deletes pending. An R2
+    // lifecycle rule on `pending/` is the backstop that cleans up orphans the
+    // agent never finalized (see docs/r2-lifecycle.md). All methods throw if
+    // the backend doesn't support pre-signed uploads (local FS).
+    pendingKey(assetId, filename) {
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        return `pending/${assetId}/${filename}`;
+    }
+    canonicalKey(assetId, filename) {
+        this.assertSafeSegment(assetId);
+        validateFilename(filename);
+        return `${assetId}/${filename}`;
+    }
+    async signPendingPutUrl(assetId, filename, contentType, expiresIn = 900) {
+        if (!this.backend.getSignedPutUrl) {
+            throw new Error('Pre-signed uploads are not supported by the local asset backend');
+        }
+        return await this.backend.getSignedPutUrl(this.pendingKey(assetId, filename), contentType, expiresIn);
+    }
+    /** HEAD the pending blob. Returns null when the agent never PUT (or the
+     *  TTL already expired). */
+    async headPending(assetId, filename) {
+        if (!this.backend.head) {
+            throw new Error('HEAD is not supported by the local asset backend');
+        }
+        return await this.backend.head(this.pendingKey(assetId, filename));
+    }
+    /** Server-side copy pending → canonical (R2's CopyObject — no download). */
+    async copyPendingToCanonical(assetId, filename) {
+        return await this.backend.copy(this.pendingKey(assetId, filename), this.canonicalKey(assetId, filename));
+    }
+    async deletePending(assetId, filename) {
+        return await this.backend.delete(this.pendingKey(assetId, filename));
+    }
+    /** Bucket lifecycle rules summary for the MCP presign flow's boot-time
+     *  backstop. Returns `null` when the backend has no lifecycle support
+     *  (local) or when the bucket has no rules configured at all. Throws on
+     *  permission / network errors so the caller can decide whether to
+     *  degrade or propagate. */
+    async getBucketLifecycle() {
+        if (!this.backend.getBucketLifecycle)
+            return null;
+        return await this.backend.getBucketLifecycle();
+    }
+    /** Download an object's bytes by raw key. Validates every path segment —
+     *  the key is derived from a stored `asset_url`, so a `..` segment must
+     *  never reach the backend's path join (arbitrary-file read). */
+    async download(key) {
+        for (const seg of key.split('/')) {
+            this.assertSafeSegment(seg);
+        }
+        return await this.backend.download(key);
+    }
+    /** Server-side copy between raw keys (migration + transfer-copy). Validates
+     *  every path segment of both keys — the migration derives srcKey from
+     *  user-editable body URLs, so a `..` in a key segment must never reach the
+     *  backend's path join (arbitrary-file read/write). */
+    async copy(srcKey, destKey) {
+        for (const seg of [...srcKey.split('/'), ...destKey.split('/')]) {
+            this.assertSafeSegment(seg);
+        }
+        return await this.backend.copy(srcKey, destKey);
+    }
     /**
      * Upload asset for an entity
      */
@@ -55,6 +215,13 @@ export class AssetService {
         const prefix = buildAssetPrefix(entityType, entityId, keyPrefix);
         return await this.backend.list(prefix);
     }
+    /**
+     * List every asset in the backend in one round-trip, with their
+     * (entityType, entityId) origins parsed from the storage key.
+     */
+    async listAll() {
+        return await this.backend.listAll();
+    }
     /**
      * Delete a single asset
      */
@@ -86,4 +253,29 @@ export class AssetService {
         return assets.find(a => a.filename === filename) || null;
     }
 }
+/**
+ * Convert an `AssetInfo` returned by a backend into the URL stored in
+ * an entity's `asset_url` (or used as the `src` of an inline embed).
+ *
+ * Stage 2 of the asset architecture (see docs/asset-architecture.md):
+ * always emit the proxied `/api/assets/{type}/{id}/{file}` path, regardless
+ * of backend. The route is the single chokepoint that enforces per-repo
+ * authz — local files are streamed directly, R2-backed assets get a 302
+ * to a short-lived pre-signed URL. New uploads never persist absolute
+ * R2 URLs in frontmatter; the migration CLI rewrites legacy ones.
+ *
+ * Centralised here because three different call sites used to inline this
+ * ternary, and getting it wrong silently breaks image rendering.
+ */
+export function publicUrlFor(_asset, entityType, entityId) {
+    return `/api/assets/${entityType}/${entityId}/${_asset.filename}`;
+}
+/**
+ * Immutable-key public URL: `/api/assets/{assetId}/{filename}`. Two path
+ * segments after `/api/assets/` (vs three for the legacy form), so the new
+ * and legacy serving routes disambiguate by arity during cutover.
+ */
+export function publicUrlForAssetId(assetId, filename) {
+    return `/api/assets/${assetId}/${filename}`;
+}
 //# sourceMappingURL=index.js.map

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

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

package/dist/services/assets/local.d.ts

@@ -3,7 +3,7 @@
  *
  * Stores assets in .studiograph/assets/ directory
  */
-import type { AssetBackend, AssetInfo } from './base.js';
+import type { AssetBackend, AssetInfo, AssetRecord } from './base.js';
 export declare class LocalAssetBackend implements AssetBackend {
     private basePath;
     constructor(basePath: string);
@@ -23,6 +23,21 @@ export declare class LocalAssetBackend implements AssetBackend {
      * List assets with a given prefix
      */
     list(prefix: string): Promise<AssetInfo[]>;
+    /**
+     * List every asset under basePath in a single filesystem walk. Parses
+     * the `{type}/{id}/{filename}` layout without any markdown or metadata
+     * reads. Used by the asset manager endpoint.
+     */
+    listAll(): Promise<AssetRecord[]>;
+    /**
+     * Server-side copy (filesystem copy). Creates the destination directory
+     * and overwrites an existing destination so migration re-runs are idempotent.
+     */
+    /**
+     * Read an object's bytes from the local filesystem.
+     */
+    download(key: string): Promise<Buffer>;
+    copy(srcKey: string, destKey: string): Promise<void>;
     /**
      * Delete a single asset
      */

package/dist/services/assets/local.js

@@ -3,7 +3,7 @@
  *
  * Stores assets in .studiograph/assets/ directory
  */
-import { existsSync, mkdirSync, writeFileSync, readdirSync, unlinkSync, statSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync, copyFileSync } from 'fs';
 import { join, dirname, relative } from 'path';
 import { getMediaType } from './base.js';
 export class LocalAssetBackend {
@@ -93,6 +93,115 @@ export class LocalAssetBackend {
         }
         return assets;
     }
+    /**
+     * List every asset under basePath in a single filesystem walk. Parses
+     * the `{type}/{id}/{filename}` layout without any markdown or metadata
+     * reads. Used by the asset manager endpoint.
+     */
+    async listAll() {
+        if (!existsSync(this.basePath))
+            return [];
+        const results = [];
+        let types = [];
+        try {
+            types = readdirSync(this.basePath);
+        }
+        catch {
+            return [];
+        }
+        for (const type of types) {
+            if (type.startsWith('.'))
+                continue;
+            const typeDir = join(this.basePath, type);
+            try {
+                if (!statSync(typeDir).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let ids = [];
+            try {
+                ids = readdirSync(typeDir);
+            }
+            catch {
+                continue;
+            }
+            for (const id of ids) {
+                if (id.startsWith('.'))
+                    continue;
+                const idDir = join(typeDir, id);
+                try {
+                    if (!statSync(idDir).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                let files = [];
+                try {
+                    files = readdirSync(idDir);
+                }
+                catch {
+                    continue;
+                }
+                for (const filename of files) {
+                    if (filename.startsWith('.'))
+                        continue;
+                    const filePath = join(idDir, filename);
+                    let stats;
+                    try {
+                        stats = statSync(filePath);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!stats.isFile())
+                        continue;
+                    const ext = filename.split('.').pop()?.toLowerCase() || '';
+                    const contentType = this.guessContentType(ext);
+                    const relativePath = relative(process.cwd(), filePath);
+                    results.push({
+                        filename,
+                        size: stats.size,
+                        contentType,
+                        url: `file:///${filePath}`,
+                        path: relativePath,
+                        mediaType: getMediaType(contentType),
+                        entityType: type,
+                        entityId: id,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Server-side copy (filesystem copy). Creates the destination directory
+     * and overwrites an existing destination so migration re-runs are idempotent.
+     */
+    /**
+     * Read an object's bytes from the local filesystem.
+     */
+    async download(key) {
+        const filePath = this.getFilePath(key);
+        if (!existsSync(filePath)) {
+            throw new Error(`Asset not found: ${key}`);
+        }
+        return readFileSync(filePath);
+    }
+    async copy(srcKey, destKey) {
+        const srcPath = this.getFilePath(srcKey);
+        if (!existsSync(srcPath)) {
+            throw new Error(`Asset not found: ${srcKey}`);
+        }
+        const destPath = this.getFilePath(destKey);
+        const destDir = dirname(destPath);
+        if (!existsSync(destDir)) {
+            mkdirSync(destDir, { recursive: true });
+        }
+        copyFileSync(srcPath, destPath);
+    }
     /**
      * Delete a single asset
      */