cursedbelt-server 1.0.0

package/dist/server/sqlite/index.d.ts

@@ -0,0 +1,9 @@
+export { type BackupInfo, createSqliteBackupService, snapshotSqlite, type SqliteBackupOpts, type SqliteBackupS3Opts, type SqliteBackupService, } from './backup';
+export { clampLimit, clampOffset, isKnownTable, listSqliteTables, NotReadOnlyError, quoteIdent, readSqliteTable, runReadonlySqlite, type SqliteTableInfo, type SqliteTablePage, UnknownTableError, } from './browse';
+export { exportSqliteSnapshot, exportSqliteTable, type SnapshotExport, type TableExport, type TableExportFormat, } from './export';
+export { applyFtsSchema, buildFtsSchema, createFts5Search, type Fts5Search, type FtsHighlightOpts, type FtsResult, type FtsSearchOpts, type FtsSnippetOpts, type FtsTableSpec, sanitizeFtsQuery, } from './fts5';
+export { createSqliteHealthChecks, type SqliteHealthCheck, type SqliteHealthOpts, type SqliteHealthResult, type SqliteHealthStatus, } from './health';
+export { type ImportMode, type ImportResult, importRowsIntoSqliteTable, type RestoreResult, restoreSqliteSnapshot, } from './import';
+export { isReadOnlySql } from './readonlySql';
+export { collectSqliteStats, type DbStats, type TableStat } from './stats';
+export { createSqliteViewerMiddleware } from './viewer';

package/dist/server/sqlite/index.js

@@ -0,0 +1,15 @@
+// cursedbelt SQLite toolkit extras (task 30) — bun:sqlite-native primitives layered
+// on the migration runner (task 24): FTS5 ranked search, a read-only DB viewer, the
+// VACUUM-INTO backup service, DB-layer health probes, plus the Hono-free browse /
+// export / import / stats primitives that back both the viewer middleware and any
+// bespoke-transport consumer (a cursedshell plugin, the encrypted-GET "f" app). All
+// app-agnostic; the apps supply table names, paths, and thresholds.
+export { createSqliteBackupService, snapshotSqlite, } from './backup';
+export { clampLimit, clampOffset, isKnownTable, listSqliteTables, NotReadOnlyError, quoteIdent, readSqliteTable, runReadonlySqlite, UnknownTableError, } from './browse';
+export { exportSqliteSnapshot, exportSqliteTable, } from './export';
+export { applyFtsSchema, buildFtsSchema, createFts5Search, sanitizeFtsQuery, } from './fts5';
+export { createSqliteHealthChecks, } from './health';
+export { importRowsIntoSqliteTable, restoreSqliteSnapshot, } from './import';
+export { isReadOnlySql } from './readonlySql';
+export { collectSqliteStats } from './stats';
+export { createSqliteViewerMiddleware } from './viewer';

package/dist/server/sqlite/readonlySql.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Defense-in-depth read-only guard for the SQLite viewer's ad-hoc query endpoint. A
+ * conservative *lexical* check, NOT a parser: it rejects the obvious foot-guns
+ * (writes, DDL, PRAGMA, ATTACH, stacked statements) before SQL reaches the DB. The
+ * real guarantees are the owner-only mount + this allowlist, layered.
+ *
+ * cursedbelt keeps its own copy rather than depending on cwip — the toolkit's server
+ * surface stays dependency-light, and the rule set here is tuned for SQLite (PRAGMA /
+ * ATTACH are SQLite-specific write vectors).
+ */
+/**
+ * True only for a single read-only statement: a `SELECT`, or a `WITH … SELECT` CTE.
+ * Rejects stacked statements, `SELECT … INTO`, and any forbidden keyword as a word.
+ */
+export declare function isReadOnlySql(sql: string): boolean;

package/dist/server/sqlite/readonlySql.js

@@ -0,0 +1,65 @@
+/**
+ * Defense-in-depth read-only guard for the SQLite viewer's ad-hoc query endpoint. A
+ * conservative *lexical* check, NOT a parser: it rejects the obvious foot-guns
+ * (writes, DDL, PRAGMA, ATTACH, stacked statements) before SQL reaches the DB. The
+ * real guarantees are the owner-only mount + this allowlist, layered.
+ *
+ * cursedbelt keeps its own copy rather than depending on cwip — the toolkit's server
+ * surface stays dependency-light, and the rule set here is tuned for SQLite (PRAGMA /
+ * ATTACH are SQLite-specific write vectors).
+ */
+const FORBIDDEN = [
+    'insert',
+    'update',
+    'delete',
+    'drop',
+    'alter',
+    'truncate',
+    'create',
+    'replace',
+    'attach',
+    'detach',
+    'reindex',
+    'vacuum',
+    'pragma',
+    'begin',
+    'commit',
+    'rollback',
+    'savepoint',
+    'release',
+    'grant',
+    'revoke',
+];
+/** Strip `--` line comments and block comments, collapse whitespace, lowercase. */
+function normalize(sql) {
+    return sql
+        .replace(/--[^\n]*/g, ' ')
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * True only for a single read-only statement: a `SELECT`, or a `WITH … SELECT` CTE.
+ * Rejects stacked statements, `SELECT … INTO`, and any forbidden keyword as a word.
+ */
+export function isReadOnlySql(sql) {
+    const s = normalize(sql);
+    if (!s)
+        return false;
+    // Only a trailing `;` terminator is allowed — no stacked statements.
+    const body = s.replace(/;\s*$/, '');
+    if (body.includes(';'))
+        return false;
+    // Must begin with SELECT or a CTE.
+    if (!/^(select|with)\b/.test(body))
+        return false;
+    // `SELECT … INTO new_table` writes a table — block it.
+    if (/\bselect\b[\s\S]*\binto\b/.test(body))
+        return false;
+    for (const kw of FORBIDDEN) {
+        if (new RegExp(`\\b${kw}\\b`).test(body))
+            return false;
+    }
+    return true;
+}

package/dist/server/sqlite/stats.d.ts

@@ -0,0 +1,22 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * DB usage stats for `bun:sqlite` — per-table row counts and on-disk byte sizes
+ * plus the total database file size. Feeds both StatTiles and the rows/bytes charts
+ * in an admin surface. Per-table bytes use the `dbstat` virtual table when the build
+ * supports it (it does in `bun:sqlite`); if a query for it ever fails, byte sizes
+ * degrade to `null` rather than throwing — row counts and the file size still work.
+ */
+export interface TableStat {
+    name: string;
+    rows: number;
+    /** On-disk bytes for this table's pages, or `null` when `dbstat` is unavailable. */
+    bytes: number | null;
+}
+export interface DbStats {
+    /** Total database file size in bytes (`page_count * page_size`). */
+    fileBytes: number;
+    /** Sum of every table's row count. */
+    totalRows: number;
+    tables: TableStat[];
+}
+export declare function collectSqliteStats(db: Database): DbStats;

package/dist/server/sqlite/stats.js

@@ -0,0 +1,32 @@
+import { listSqliteTables } from './browse';
+/** Whole-database size from the page pragmas (works without `dbstat`). */
+function fileBytes(db) {
+    const pageCount = db.query('PRAGMA page_count').get()?.page_count ?? 0;
+    const pageSize = db.query('PRAGMA page_size').get()?.page_size ?? 0;
+    return pageCount * pageSize;
+}
+/** Per-table byte sizes from `dbstat`, or `null` for all tables if it's unavailable. */
+function bytesByTable(db) {
+    try {
+        const rows = db
+            .query('SELECT name, SUM(pgsize) AS bytes FROM dbstat GROUP BY name')
+            .all();
+        return new Map(rows.map((r) => [r.name, r.bytes]));
+    }
+    catch {
+        return null;
+    }
+}
+export function collectSqliteStats(db) {
+    const byTable = bytesByTable(db);
+    const tables = listSqliteTables(db).map(({ name, count }) => ({
+        name,
+        rows: count,
+        bytes: byTable ? (byTable.get(name) ?? 0) : null,
+    }));
+    return {
+        fileBytes: fileBytes(db),
+        totalRows: tables.reduce((sum, t) => sum + t.rows, 0),
+        tables,
+    };
+}

package/dist/server/sqlite/viewer.d.ts

@@ -0,0 +1,17 @@
+import type { Database } from 'bun:sqlite';
+import { Hono } from 'hono';
+/**
+ * A read-only SQLite browser as a Hono sub-app — a thin HTTP wrapper over the
+ * Hono-free primitives in `browse.ts` (the same primitives a cursedshell plugin or
+ * a bespoke-transport app consumes directly). Mount it behind the owner-only guard:
+ *
+ * ```ts
+ * app.route('/api/v1/admin/sqlite', ownerOnly(createSqliteViewerMiddleware(db)));
+ * ```
+ *
+ * Three endpoints — list tables + counts, paginate one table, run an ad-hoc
+ * `SELECT` — letting the owner inspect the live DB without shell access. Every path
+ * is read-only (see `browse.ts` for the injection/read-only guards). Authn/authz is
+ * the mounting app's job (this sub-app trusts that it is already owner-gated).
+ */
+export declare function createSqliteViewerMiddleware(db: Database): Hono;

package/dist/server/sqlite/viewer.js

@@ -0,0 +1,56 @@
+import { Hono } from 'hono';
+import { ApiError, toErrorEnvelope } from '../errors';
+import { listSqliteTables, NotReadOnlyError, readSqliteTable, runReadonlySqlite, UnknownTableError, } from './browse';
+/**
+ * A read-only SQLite browser as a Hono sub-app — a thin HTTP wrapper over the
+ * Hono-free primitives in `browse.ts` (the same primitives a cursedshell plugin or
+ * a bespoke-transport app consumes directly). Mount it behind the owner-only guard:
+ *
+ * ```ts
+ * app.route('/api/v1/admin/sqlite', ownerOnly(createSqliteViewerMiddleware(db)));
+ * ```
+ *
+ * Three endpoints — list tables + counts, paginate one table, run an ad-hoc
+ * `SELECT` — letting the owner inspect the live DB without shell access. Every path
+ * is read-only (see `browse.ts` for the injection/read-only guards). Authn/authz is
+ * the mounting app's job (this sub-app trusts that it is already owner-gated).
+ */
+export function createSqliteViewerMiddleware(db) {
+    const app = new Hono();
+    app.get('/tables', (c) => c.json({ items: listSqliteTables(db) }));
+    app.get('/tables/:table', (c) => {
+        try {
+            return c.json(readSqliteTable(db, c.req.param('table'), {
+                limit: c.req.query('limit'),
+                offset: c.req.query('offset'),
+            }));
+        }
+        catch (err) {
+            if (err instanceof UnknownTableError) {
+                return c.json(toErrorEnvelope(new ApiError(404, 'Unknown table', { code: 'unknown_table' })), 404);
+            }
+            throw err;
+        }
+    });
+    app.post('/query', async (c) => {
+        let payload;
+        try {
+            payload = await c.req.json();
+        }
+        catch {
+            return c.json(toErrorEnvelope(new ApiError(400, 'Invalid JSON body', { code: 'bad_request' })), 400);
+        }
+        const params = Array.isArray(payload.params) ? payload.params : [];
+        try {
+            const items = runReadonlySqlite(db, payload.sql, params);
+            return c.json({ items });
+        }
+        catch (err) {
+            if (err instanceof NotReadOnlyError) {
+                return c.json(toErrorEnvelope(new ApiError(400, err.message, { code: 'not_read_only' })), 400);
+            }
+            return c.json(toErrorEnvelope(new ApiError(400, err instanceof Error ? err.message : String(err), { code: 'query_failed' })), 400);
+        }
+    });
+    return app;
+}

package/dist/server/storage/binaryServerProcessing.d.ts

@@ -0,0 +1,23 @@
+import type { ImageDerivatives, VideoProcessor } from './files/catalogue';
+export type BinaryServerProcessingConfig = {
+    /** e.g. 'https://binary-server.cursedalchemy.com' — same value as the byte store's baseUrl. */
+    baseUrl: string;
+    /** App namespace (path + token scope), e.g. 'p'. Keys sent to the transcode API are
+     * app-scoped (`<appId>/<key>`), matching what the MediaStore adapter writes. */
+    appId: string;
+    /** Shared server-to-server secret (x-internal-secret). */
+    internalSecret: string;
+    /** HLS rung heights (passed through as the job's ladder). */
+    ladderHeights?: number[];
+    /** Poll cadence while a job runs. */
+    pollMs?: number;
+    /** Give up on a job after this long (it keeps running server-side; the row just fails). */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Injectable clock/sleep for tests. */
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function createBinaryServerProcessing(cfg: BinaryServerProcessingConfig): {
+    videoProcessor: VideoProcessor;
+    imageDerivatives: ImageDerivatives;
+};

package/dist/server/storage/binaryServerProcessing.js

@@ -0,0 +1,81 @@
+import { createTranscodeJobClient } from './transcodeJobs';
+import { fsHlsPrefix, fsMp4Key, fsPosterKey, fsSpriteKey, fsVttKey } from './types';
+export function createBinaryServerProcessing(cfg) {
+    const jobs = createTranscodeJobClient(cfg);
+    const { appKey, submit, poll } = jobs;
+    const videoProcessor = async (opts) => {
+        const { owner, id, onProgress } = opts;
+        const failed = {
+            status: 'failed',
+            durationSeconds: 0,
+            hasHls: false,
+            hasSprite: false,
+            hasPoster: false,
+        };
+        try {
+            onProgress?.('processing', 1);
+            const jobId = await submit({
+                strategy: 'library',
+                nodeId: id,
+                sourceKey: appKey(opts.sourceKey),
+                binaryKey: appKey(fsMp4Key(owner, id)),
+                sourceKeyOut: appKey(fsMp4Key(owner, id)),
+                hlsPrefix: appKey(fsHlsPrefix(owner, id)),
+                posterKey: appKey(fsPosterKey(owner, id)),
+                spriteKey: appKey(fsSpriteKey(owner, id)),
+                vttKey: appKey(fsVttKey(owner, id)),
+                posterOnly: opts.posterOnly === true,
+                settings: { ladder: opts.ladderHeights ?? [480, 720, 1080] },
+            });
+            const job = await poll(jobId, (pct) => onProgress?.('processing', Math.min(99, pct)));
+            if (job.status !== 'ready') {
+                // The "a failed job maps to status failed" fixture test deliberately drives this
+                // path — tagged `[expected-in-tests]` (grep-filterable) rather than silenced, so a
+                // real binary-server outage still surfaces.
+                console.warn(`[binaryServerProcessing][expected-in-tests] video job failed for ${id}: ${job.error ?? '?'}`);
+                onProgress?.('failed', 0);
+                return failed;
+            }
+            onProgress?.('ready', 100);
+            return {
+                status: 'ready',
+                durationSeconds: job.result?.durationSeconds ?? 0,
+                hasHls: job.result?.hasHls ?? false,
+                hasSprite: job.result?.hasSprite ?? false,
+                hasPoster: job.result?.hasPoster ?? false,
+            };
+        }
+        catch (err) {
+            // The "a rejected submit maps to status failed" fixture test deliberately drives this
+            // path — tagged `[expected-in-tests]` (grep-filterable) rather than silenced, so a
+            // real binary-server outage still surfaces.
+            console.warn(`[binaryServerProcessing][expected-in-tests] video job errored for ${id}: ${err instanceof Error ? err.message : err}`);
+            onProgress?.('failed', 0);
+            return failed;
+        }
+    };
+    const imageDerivatives = async (args) => {
+        try {
+            const jobId = await submit({
+                strategy: 'image',
+                nodeId: args.id,
+                sourceKey: appKey(args.binaryKey),
+                binaryKey: appKey(args.binaryKey),
+                posterKey: appKey(args.posterKey),
+                ...(args.needsDisplay ? { displayKey: appKey(args.displayKey) } : {}),
+            });
+            const job = await poll(jobId);
+            if (job.status !== 'ready' || !job.result?.hasThumbnail)
+                return { hasThumbnail: false };
+            return { hasThumbnail: true };
+        }
+        catch (err) {
+            // The "browser-renderable image ... failure maps to hasThumbnail false" fixture test
+            // deliberately drives this path — tagged `[expected-in-tests]` (grep-filterable)
+            // rather than silenced, so a real binary-server outage still surfaces.
+            console.warn(`[binaryServerProcessing][expected-in-tests] image job errored for ${args.id}: ${err instanceof Error ? err.message : err}`);
+            return { hasThumbnail: false };
+        }
+    };
+    return { videoProcessor, imageDerivatives };
+}

package/dist/server/storage/binaryServerStore.d.ts

@@ -0,0 +1,3 @@
+import type { BinaryServerConfig, MediaStore } from './types';
+export type { BinaryServerConfig, FileTokenClaims, FileTokenSigner } from './types';
+export declare function createBinaryServerStore(cfg: BinaryServerConfig): MediaStore;

package/dist/server/storage/binaryServerStore.js

@@ -0,0 +1,95 @@
+// binary-server MediaStore adapter. binary-server (Bun/SQLite, RS256 token-gated, Range-capable)
+// is a production storage path: a home/edge file service the app signs short-lived tokens for.
+// User-facing downloads REDIRECT (303) to the signed edge URL rather than proxying bytes back
+// through the app; server-side reads (transcode source, checks) stream locally via getRange.
+//
+// The RS256 signer is INJECTED — the app holds the private key (binary-server holds only the
+// public key). cursedbelt carries no key material and no asymmetric-crypto specifics; it just
+// calls `signFileToken` with the claims binary-server expects.
+export function createBinaryServerStore(cfg) {
+    const appKey = (key) => `${cfg.appId}/${key}`;
+    const mediaUrl = async (key, extra) => {
+        const token = await cfg.signFileToken({ k: appKey(key), ...extra });
+        return `${cfg.baseUrl}/media/${appKey(key)}?token=${encodeURIComponent(token)}`;
+    };
+    const uploadUrl = async (key) => {
+        const token = await cfg.signFileToken({ k: appKey(key) });
+        return `${cfg.baseUrl}/upload/${appKey(key)}?token=${encodeURIComponent(token)}`;
+    };
+    return {
+        async put(key, bytes, mime) {
+            const res = await fetch(await uploadUrl(key), {
+                method: 'PUT',
+                body: new Blob([bytes], { type: mime }),
+            });
+            if (!res.ok)
+                throw new Error(`binary-server put ${key}: ${res.status}`);
+        },
+        async putStream(key, body, mime, opts) {
+            const headers = { 'content-type': mime };
+            if (opts?.contentLength != null)
+                headers['content-length'] = String(opts.contentLength);
+            const res = await fetch(await uploadUrl(key), {
+                method: 'PUT',
+                body,
+                headers,
+                // A web ReadableStream body requires duplex: 'half' per the fetch streaming spec.
+                duplex: 'half',
+            });
+            if (!res.ok)
+                throw new Error(`binary-server putStream ${key}: ${res.status}`);
+        },
+        async get(key) {
+            const res = await fetch(await mediaUrl(key));
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`binary-server get ${key}: ${res.status}`);
+            return new Uint8Array(await res.arrayBuffer());
+        },
+        async remove(key) {
+            // binary-server gates DELETE on BOTH the internal secret AND a per-op, path-scoped RS256
+            // token carrying op:'delete' (owner ruling #10, defense in depth). Sign+send both.
+            const token = await cfg.signFileToken({ k: appKey(key), op: 'delete' });
+            const res = await fetch(`${cfg.baseUrl}/media/${appKey(key)}?token=${encodeURIComponent(token)}`, {
+                method: 'DELETE',
+                headers: cfg.internalSecret ? { 'x-internal-secret': cfg.internalSecret } : {},
+            });
+            if (!res.ok && res.status !== 404)
+                throw new Error(`binary-server remove ${key}: ${res.status}`);
+        },
+        async removePrefix(prefix) {
+            // The delete token's exact-key claim is the container path; bs derives the tree from it
+            // plus ?container=1. Same two-barrier gate as remove().
+            const token = await cfg.signFileToken({ k: appKey(prefix), op: 'delete' });
+            const res = await fetch(`${cfg.baseUrl}/media/${appKey(prefix)}?container=1&token=${encodeURIComponent(token)}`, {
+                method: 'DELETE',
+                headers: cfg.internalSecret ? { 'x-internal-secret': cfg.internalSecret } : {},
+            });
+            if (!res.ok && res.status !== 404) {
+                throw new Error(`binary-server removePrefix ${prefix}: ${res.status}`);
+            }
+        },
+        async stat(key) {
+            // A 0-0 range is the cheapest way to learn total size (Content-Range: …/<total>).
+            const res = await fetch(await mediaUrl(key), { headers: { Range: 'bytes=0-0' } });
+            if (res.status === 404)
+                return null;
+            const cr = res.headers.get('content-range');
+            const total = cr ? Number(cr.split('/')[1]) : Number(res.headers.get('content-length'));
+            return Number.isFinite(total) ? { size: total } : null;
+        },
+        async getRange(key, range) {
+            const headers = {};
+            if (range)
+                headers.Range = `bytes=${range.start}-${range.end}`;
+            const res = await fetch(await mediaUrl(key), { headers });
+            if (res.status === 404 || !res.body)
+                return null;
+            return { stream: res.body };
+        },
+        async redirectUrl(key, opts) {
+            return mediaUrl(key, { fn: opts.filename, dl: 'inline' });
+        },
+    };
+}

package/dist/server/storage/diskStore.d.ts

@@ -0,0 +1,2 @@
+import type { MediaStore } from './types';
+export declare function createDiskStore(root: string): MediaStore;

package/dist/server/storage/diskStore.js

@@ -0,0 +1,88 @@
+import { mkdir, rm, unlink } from 'node:fs/promises';
+import path from 'node:path';
+// Local-disk MediaStore (the dev default). Bun-native: Bun.file/Bun.write handle web streams
+// and byte-range slices directly, so there is no node:stream on the hot path. Keys are
+// generated server-side (owner/id…) but we still guard against path traversal so a stored key
+// can never escape the media root.
+export function createDiskStore(root) {
+    const resolveKey = (key) => {
+        const full = path.join(root, key);
+        const rel = path.relative(root, full);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Invalid media key: ${key}`);
+        }
+        return full;
+    };
+    return {
+        async put(key, bytes) {
+            // Bun.write creates intermediate directories automatically.
+            await Bun.write(resolveKey(key), bytes);
+        },
+        async putStream(key, body) {
+            const full = resolveKey(key);
+            // Grab the reader BEFORE any real await: in Bun 1.3.x a request-body stream's
+            // internals detach across an I/O tick, after which releaseLock() (and the
+            // async iterator) throw "undefined is not a function" — 500ing every upload.
+            const reader = body.getReader();
+            await mkdir(path.dirname(full), { recursive: true });
+            // Stream through a Bun FileSink — peak memory is one chunk. (NB: `Bun.write(full,
+            // new Response(body))` HANGS on a web ReadableStream in Bun 1.3.x, so we pump manually.)
+            const writer = Bun.file(full).writer();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    writer.write(value);
+                }
+                await writer.end();
+            }
+            finally {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    // Same Bun 1.3.x detach bug via a caller-side await (e.g. an async auth
+                    // guard): reads still complete, only this cleanup call explodes — and by
+                    // here the stream is fully consumed, so there is nothing left to release.
+                }
+            }
+        },
+        async get(key) {
+            const file = Bun.file(resolveKey(key));
+            if (!(await file.exists()))
+                return null;
+            return new Uint8Array(await file.arrayBuffer());
+        },
+        async remove(key) {
+            try {
+                await unlink(resolveKey(key));
+            }
+            catch (err) {
+                if (err?.code !== 'ENOENT')
+                    throw err;
+            }
+        },
+        async removePrefix(prefix) {
+            await rm(resolveKey(prefix), { recursive: true, force: true });
+        },
+        async stat(key) {
+            const file = Bun.file(resolveKey(key));
+            if (!(await file.exists()))
+                return null;
+            return { size: file.size };
+        },
+        async getRange(key, range) {
+            const file = Bun.file(resolveKey(key));
+            if (!(await file.exists()))
+                return null;
+            // Bun.file.slice(start, end) is exclusive-end; our ranges are inclusive.
+            const blob = range ? file.slice(range.start, range.end + 1) : file;
+            return { stream: blob.stream() };
+        },
+        async localPath(key) {
+            const full = resolveKey(key);
+            return (await Bun.file(full).exists()) ? full : null;
+        },
+    };
+}

package/dist/server/storage/files/adapter.d.ts

@@ -0,0 +1,33 @@
+import type { MediaUrls } from '../sources';
+import type { MediaGallerySource, MediaSource, PhotoSource } from '../types';
+import type { FileUrls } from './fileRoutes';
+import type { FileCatalogue, FileToPlayable } from './types';
+/** Resolve a video FileRecord to a PlayableVideo with tokenised URLs. Non-video ⇒ null. */
+export declare function createFileToPlayable(urls: MediaUrls, sourceId: string): FileToPlayable;
+/** Expose a FileCatalogue as a video-only `MediaSource` — the gallery is a view, not a store. */
+export declare function createCatalogueVideoSource(cfg: {
+    id: string;
+    title: string;
+    catalogue: FileCatalogue;
+    urls: MediaUrls;
+}): MediaSource;
+/** Expose a FileCatalogue as an image-only `PhotoSource` — a view, not a store. */
+export declare function createCataloguePhotoSource(cfg: {
+    id: string;
+    title: string;
+    catalogue: FileCatalogue;
+    fileUrls: FileUrls;
+    mediaUrls: MediaUrls;
+}): PhotoSource;
+/** Expose a FileCatalogue as a `MediaGallerySource` — photos + videos in one feed.
+ * Videos are tokenised under `videoSourceId` (must match the registered video source so
+ * `mountMediaRoutes` serves their streams); photo posters/thumbnails under this source's `id`. */
+export declare function createCatalogueMediaSource(cfg: {
+    id: string;
+    title: string;
+    catalogue: FileCatalogue;
+    urls: MediaUrls;
+    fileUrls: FileUrls;
+    /** SourceId the video stream tokens are minted under. Default `id`. */
+    videoSourceId?: string;
+}): MediaGallerySource;