mdorigin 0.1.8 → 0.2.1

package/dist/cli/sync-cloudflare-r2.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { syncCloudflareR2 } from '../cloudflare.js';
+export async function runSyncCloudflareR2Command(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        console.log('Usage: mdorigin sync cloudflare-r2 --dir ./dist/cloudflare --bucket <bucket-name> [--force]');
+        return;
+    }
+    if (!args.bucket) {
+        console.error('Usage: mdorigin sync cloudflare-r2 --dir ./dist/cloudflare --bucket <bucket-name> [--force]');
+        process.exitCode = 1;
+        return;
+    }
+    const result = await syncCloudflareR2({
+        dir: path.resolve(args.dir ?? 'dist/cloudflare'),
+        bucketName: args.bucket,
+        force: args.force,
+    });
+    console.log(`synced ${result.uploadedCount} R2 object(s), skipped ${result.skippedCount}, state written to ${result.stateFile}`);
+}
+function parseArgs(argv) {
+    const result = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const nextValue = argv[index + 1];
+        if (argument === '--help' || argument === '-h') {
+            result.help = true;
+            continue;
+        }
+        if (argument === '--dir' && nextValue) {
+            result.dir = nextValue;
+            index += 1;
+            continue;
+        }
+        if (argument === '--bucket' && nextValue) {
+            result.bucket = nextValue;
+            index += 1;
+            continue;
+        }
+        if (argument === '--force') {
+            result.force = true;
+            continue;
+        }
+        throw new Error(`Unknown argument for mdorigin sync cloudflare-r2: ${argument}`);
+    }
+    return result;
+}

package/dist/cloudflare-runtime.d.ts

@@ -1,2 +1,2 @@
 export { createCloudflareWorker } from './adapters/cloudflare.js';
-export type { CloudflareManifest, CloudflareManifestEntry, ExportedHandlerLike, } from './adapters/cloudflare.js';
+export type { CloudflareBundleRuntimeConfig, CloudflareManifest, CloudflareManifestEntry, ExportedHandlerLike, } from './adapters/cloudflare.js';

package/dist/cloudflare.d.ts

@@ -1,34 +1,72 @@
-import type { CloudflareManifest, CloudflareManifestEntry } from './adapters/cloudflare.js';
+import type { CloudflareBundleRuntimeConfig, CloudflareManifest, CloudflareManifestEntry } from './adapters/cloudflare.js';
 import { createCloudflareWorker } from './adapters/cloudflare.js';
 import type { ResolvedSiteConfig } from './core/site-config.js';
 export { createCloudflareWorker };
-export type { CloudflareManifest, CloudflareManifestEntry };
+export type { CloudflareBundleRuntimeConfig, CloudflareManifest, CloudflareManifestEntry, };
+export type CloudflareBinaryMode = 'inline' | 'external';
 export interface BuildCloudflareManifestOptions {
     rootDir: string;
     siteConfig: ResolvedSiteConfig;
     searchDir?: string;
+    binaryMode?: CloudflareBinaryMode;
+    assetsMaxBytes?: number;
+    r2Binding?: string;
 }
-export interface WriteCloudflareBundleOptions {
-    rootDir: string;
+export interface WriteCloudflareBundleOptions extends BuildCloudflareManifestOptions {
     outDir: string;
-    siteConfig: ResolvedSiteConfig;
     packageImport?: string;
-    searchDir?: string;
     configModulePath?: string;
 }
+export interface CloudflareBundleMetadata {
+    version: 2;
+    workerEntry: string;
+    binaryMode: CloudflareBinaryMode;
+    assetsMaxBytes?: number;
+    assetsDir?: string;
+    r2Dir?: string;
+    r2Binding?: string;
+    siteTitle?: string;
+    stagedObjects: Array<{
+        kind: 'binary' | 'search';
+        path: string;
+        mediaType: string;
+        storageKind: 'assets' | 'r2';
+        storageKey: string;
+        file: string;
+        byteSize: number;
+    }>;
+}
 export interface InitCloudflareProjectOptions {
     projectDir: string;
     workerEntry: string;
     workerName?: string;
     siteTitle?: string;
     compatibilityDate?: string;
+    r2Bucket?: string;
+    force?: boolean;
+}
+export interface SyncCloudflareR2Options {
+    dir: string;
+    bucketName: string;
     force?: boolean;
+    runCommand?: typeof runWranglerCommand;
+}
+export interface SyncCloudflareR2Result {
+    uploadedCount: number;
+    skippedCount: number;
+    stateFile: string;
 }
 export declare function buildCloudflareManifest(options: BuildCloudflareManifestOptions): Promise<CloudflareManifest>;
 export declare function writeCloudflareBundle(options: WriteCloudflareBundleOptions): Promise<{
     manifest: CloudflareManifest;
     workerFile: string;
+    bundleFile: string;
 }>;
 export declare function initCloudflareProject(options: InitCloudflareProjectOptions): Promise<{
     configFile: string;
 }>;
+export declare function syncCloudflareR2(options: SyncCloudflareR2Options): Promise<SyncCloudflareR2Result>;
+declare function runWranglerCommand(command: string, args: string[]): {
+    status: number | null;
+    stderr: string;
+};

package/dist/cloudflare.js

@@ -1,12 +1,24 @@
-import { mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { copyFile, mkdir, readFile, readdir, realpath, rm, stat, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { createCloudflareWorker } from './adapters/cloudflare.js';
-import { getMediaTypeForPath, isLikelyTextPath, normalizeContentPath, } from './core/content-store.js';
+import { getMediaTypeForPath, isIgnoredContentName, isLikelyTextPath, normalizeContentPath, } from './core/content-store.js';
 export { createCloudflareWorker };
+const DEFAULT_ASSETS_MAX_BYTES = 25 * 1024 * 1024;
+const DEFAULT_ASSETS_BINDING = 'ASSETS';
+const DEFAULT_R2_BINDING = 'MDORIGIN_R2';
+const BUNDLE_FILE_NAME = 'bundle.json';
+const R2_STATE_FILE_NAME = 'r2-sync-state.json';
+const SEARCH_ASSETS_PREFIX = '__mdorigin/search';
 export async function buildCloudflareManifest(options) {
     const rootDir = path.resolve(options.rootDir);
     const files = await listFiles(rootDir);
     const entries = [];
+    const binaryMode = options.binaryMode ?? 'inline';
+    const assetsMaxBytes = options.assetsMaxBytes ?? DEFAULT_ASSETS_MAX_BYTES;
+    const r2Binding = options.r2Binding ?? DEFAULT_R2_BINDING;
     for (const filePath of files) {
         const relativePath = path.relative(rootDir, filePath).replaceAll(path.sep, '/');
         const normalizedPath = normalizeContentPath(relativePath);
@@ -23,32 +35,56 @@ export async function buildCloudflareManifest(options) {
             });
             continue;
         }
-        entries.push({
-            path: normalizedPath,
-            kind: 'binary',
-            mediaType,
-            base64: (await readFile(filePath)).toString('base64'),
-        });
+        if (binaryMode === 'inline') {
+            const bytes = await readFile(filePath);
+            entries.push({
+                path: normalizedPath,
+                kind: 'binary',
+                mediaType,
+                base64: bytes.toString('base64'),
+            });
+            continue;
+        }
+        const fileStats = await stat(filePath);
+        entries.push(await buildExternalBinaryEntry(filePath, normalizedPath, mediaType, fileStats.size, {
+            assetsMaxBytes,
+            r2Binding,
+        }));
     }
-    const searchEntries = options.searchDir
-        ? await readBundleEntries(path.resolve(options.searchDir))
+    const externalSearchEntries = options.searchDir
+        ? await buildSearchBundleEntries(path.resolve(options.searchDir), assetsMaxBytes)
         : undefined;
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return {
         entries,
         siteConfig: options.siteConfig,
-        searchEntries,
+        externalSearchEntries,
+        runtime: binaryMode === 'external' || (externalSearchEntries?.length ?? 0) > 0
+            ? {
+                binaryMode,
+                r2Binding,
+            }
+            : {
+                binaryMode,
+            },
     };
 }
 export async function writeCloudflareBundle(options) {
     const outDir = path.resolve(options.outDir);
+    const binaryMode = options.binaryMode ?? 'inline';
+    const assetsMaxBytes = options.assetsMaxBytes ?? DEFAULT_ASSETS_MAX_BYTES;
+    const r2Binding = options.r2Binding ?? DEFAULT_R2_BINDING;
     const manifest = await buildCloudflareManifest({
         rootDir: options.rootDir,
         siteConfig: options.siteConfig,
         searchDir: options.searchDir,
+        binaryMode,
+        assetsMaxBytes,
+        r2Binding,
     });
     const packageImport = options.packageImport ?? 'mdorigin/cloudflare-runtime';
     const workerFile = path.join(outDir, 'worker.mjs');
+    const bundleFile = path.join(outDir, BUNDLE_FILE_NAME);
     const configImportPath = options.configModulePath
         ? toPosixPath(path.relative(outDir, options.configModulePath))
         : null;
@@ -83,10 +119,18 @@ export async function writeCloudflareBundle(options) {
         '',
     ].join('\n');
     await mkdir(outDir, { recursive: true });
+    const metadata = await writeExternalStaging(path.resolve(options.rootDir), options.searchDir ? path.resolve(options.searchDir) : undefined, outDir, manifest, {
+        binaryMode,
+        assetsMaxBytes,
+        r2Binding,
+        siteTitle: options.siteConfig.siteTitle,
+    });
     await writeFile(workerFile, workerSource, 'utf8');
+    await writeFile(bundleFile, JSON.stringify(metadata, null, 2), 'utf8');
     return {
         manifest,
         workerFile,
+        bundleFile,
     };
 }
 export async function initCloudflareProject(options) {
@@ -96,8 +140,14 @@ export async function initCloudflareProject(options) {
     if (existing && !options.force) {
         throw new Error(`Refusing to overwrite ${configFile}. Re-run with --force to replace it.`);
     }
+    const bundleMetadata = await readCloudflareBundleMetadata(options.workerEntry);
+    if (bundleMetadata &&
+        bundleMetadata.stagedObjects.some((object) => object.storageKind === 'r2') &&
+        !options.r2Bucket) {
+        throw new Error('Cloudflare bundle contains R2-backed staged objects. Re-run init cloudflare with --r2-bucket <bucket-name>.');
+    }
     const workerName = options.workerName ??
-        slugifyWorkerName(options.siteTitle) ??
+        slugifyWorkerName(bundleMetadata?.siteTitle ?? options.siteTitle) ??
         'mdorigin-site';
     const compatibilityDate = options.compatibilityDate ?? '2026-03-20';
     const wranglerConfig = [
@@ -107,13 +157,273 @@ export async function initCloudflareProject(options) {
         `  "main": ${JSON.stringify(toPosixPath(path.relative(projectDir, options.workerEntry)))},`,
         `  "compatibility_date": ${JSON.stringify(compatibilityDate)},`,
         '  "compatibility_flags": ["nodejs_compat"]',
+        bundleMetadata?.assetsDir
+            ? [
+                ',',
+                '  "assets": {',
+                `    "directory": ${JSON.stringify(toPosixPath(path.relative(projectDir, path.join(path.dirname(options.workerEntry), bundleMetadata.assetsDir))))},`,
+                `    "binding": ${JSON.stringify(DEFAULT_ASSETS_BINDING)},`,
+                '    "run_worker_first": true',
+                '  }',
+            ].join('\n')
+            : '',
+        bundleMetadata &&
+            bundleMetadata.stagedObjects.some((object) => object.storageKind === 'r2') &&
+            bundleMetadata.r2Binding &&
+            options.r2Bucket
+            ? [
+                ',',
+                '  "r2_buckets": [',
+                '    {',
+                `      "binding": ${JSON.stringify(bundleMetadata.r2Binding)},`,
+                `      "bucket_name": ${JSON.stringify(options.r2Bucket)}`,
+                '    }',
+                '  ]',
+            ].join('\n')
+            : '',
         '}',
         '',
-    ].join('\n');
+    ]
+        .filter(Boolean)
+        .join('\n');
     await mkdir(projectDir, { recursive: true });
     await writeFile(configFile, wranglerConfig, 'utf8');
     return { configFile };
 }
+export async function syncCloudflareR2(options) {
+    const outDir = path.resolve(options.dir);
+    const bundleFile = path.join(outDir, BUNDLE_FILE_NAME);
+    const metadata = await readBundleMetadataFile(bundleFile);
+    const r2Objects = metadata.stagedObjects.filter((object) => object.storageKind === 'r2');
+    if (r2Objects.length === 0) {
+        throw new Error(`No R2-backed staged objects found in ${bundleFile}.`);
+    }
+    const stateFile = path.join(outDir, R2_STATE_FILE_NAME);
+    const state = await readR2SyncState(stateFile);
+    const runCommand = options.runCommand ?? runWranglerCommand;
+    let uploadedCount = 0;
+    let skippedCount = 0;
+    for (const object of r2Objects) {
+        const stateKey = `${options.bucketName}:${object.storageKey}`;
+        if (!options.force && state.uploaded[stateKey]) {
+            skippedCount += 1;
+            continue;
+        }
+        const filePath = path.join(outDir, object.file);
+        const result = runCommand('wrangler', [
+            'r2',
+            'object',
+            'put',
+            `${options.bucketName}/${object.storageKey}`,
+            '--file',
+            filePath,
+            '--content-type',
+            object.mediaType,
+            '--remote',
+        ]);
+        if (result.status !== 0) {
+            throw new Error(result.stderr || `Failed to upload R2 object ${object.storageKey}.`);
+        }
+        state.uploaded[stateKey] = {
+            syncedAt: new Date().toISOString(),
+        };
+        uploadedCount += 1;
+    }
+    await writeFile(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    return {
+        uploadedCount,
+        skippedCount,
+        stateFile,
+    };
+}
+async function buildExternalBinaryEntry(filePath, normalizedPath, mediaType, byteSize, options) {
+    if (byteSize <= options.assetsMaxBytes) {
+        return {
+            path: normalizedPath,
+            kind: 'binary',
+            mediaType,
+            storageKind: 'assets',
+            storageKey: normalizedPath,
+            byteSize,
+        };
+    }
+    return {
+        path: normalizedPath,
+        kind: 'binary',
+        mediaType,
+        storageKind: 'r2',
+        storageKey: await buildR2StorageKey(filePath, normalizedPath),
+        byteSize,
+    };
+}
+async function writeExternalStaging(rootDir, searchDir, outDir, manifest, options) {
+    const assetsDir = path.join(outDir, 'assets');
+    const r2Dir = path.join(outDir, 'r2');
+    await rm(assetsDir, { recursive: true, force: true });
+    await rm(r2Dir, { recursive: true, force: true });
+    const stagedObjects = new Map();
+    let hasAssets = false;
+    let hasR2 = false;
+    if (options.binaryMode === 'external') {
+        for (const entry of manifest.entries) {
+            if (entry.kind !== 'binary' || !('storageKind' in entry)) {
+                continue;
+            }
+            const sourceFile = path.resolve(rootDir, entry.path);
+            if (entry.storageKind === 'assets') {
+                const targetFile = path.join(assetsDir, entry.storageKey);
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasAssets = true;
+                stagedObjects.set(`assets:${entry.storageKey}`, {
+                    kind: 'binary',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'assets',
+                    storageKey: entry.storageKey,
+                    file: toPosixPath(path.join('assets', entry.storageKey)),
+                    byteSize: entry.byteSize,
+                });
+                continue;
+            }
+            const relativeFile = toPosixPath(path.join('r2', entry.storageKey));
+            const targetFile = path.join(outDir, relativeFile);
+            if (!stagedObjects.has(`r2:${entry.storageKey}`)) {
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasR2 = true;
+                stagedObjects.set(`r2:${entry.storageKey}`, {
+                    kind: 'binary',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'r2',
+                    storageKey: entry.storageKey,
+                    file: relativeFile,
+                    byteSize: entry.byteSize,
+                });
+            }
+        }
+    }
+    if (searchDir && manifest.externalSearchEntries) {
+        for (const entry of manifest.externalSearchEntries) {
+            const sourceFile = path.join(searchDir, entry.path);
+            if (entry.storageKind === 'assets') {
+                const targetFile = path.join(assetsDir, entry.storageKey);
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasAssets = true;
+                stagedObjects.set(`assets:${entry.storageKey}`, {
+                    kind: 'search',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'assets',
+                    storageKey: entry.storageKey,
+                    file: toPosixPath(path.join('assets', entry.storageKey)),
+                    byteSize: entry.byteSize,
+                });
+                continue;
+            }
+            const relativeFile = toPosixPath(path.join('r2', entry.storageKey));
+            const targetFile = path.join(outDir, relativeFile);
+            if (!stagedObjects.has(`r2:${entry.storageKey}`)) {
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasR2 = true;
+                stagedObjects.set(`r2:${entry.storageKey}`, {
+                    kind: 'search',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'r2',
+                    storageKey: entry.storageKey,
+                    file: relativeFile,
+                    byteSize: entry.byteSize,
+                });
+            }
+        }
+    }
+    return {
+        version: 2,
+        workerEntry: 'worker.mjs',
+        binaryMode: options.binaryMode,
+        assetsMaxBytes: options.binaryMode === 'external' || searchDir ? options.assetsMaxBytes : undefined,
+        assetsDir: hasAssets ? 'assets' : undefined,
+        r2Dir: hasR2 ? 'r2' : undefined,
+        r2Binding: hasR2 ? options.r2Binding : undefined,
+        siteTitle: options.siteTitle,
+        stagedObjects: Array.from(stagedObjects.values()).sort((left, right) => left.storageKey.localeCompare(right.storageKey)),
+    };
+}
+async function readCloudflareBundleMetadata(workerEntry) {
+    const bundleFile = path.join(path.dirname(workerEntry), BUNDLE_FILE_NAME);
+    if (!(await pathExists(bundleFile))) {
+        return null;
+    }
+    return readBundleMetadataFile(bundleFile);
+}
+async function readBundleMetadataFile(bundleFile) {
+    const parsed = JSON.parse(await readFile(bundleFile, 'utf8'));
+    if ('stagedObjects' in parsed && Array.isArray(parsed.stagedObjects)) {
+        return parsed;
+    }
+    if ('r2Objects' in parsed && Array.isArray(parsed.r2Objects)) {
+        return {
+            version: 2,
+            workerEntry: parsed.workerEntry,
+            binaryMode: parsed.binaryMode,
+            assetsMaxBytes: parsed.assetsMaxBytes,
+            assetsDir: parsed.assetsDir,
+            r2Dir: parsed.r2Dir,
+            r2Binding: parsed.r2Binding,
+            siteTitle: parsed.siteTitle,
+            stagedObjects: parsed.r2Objects.map((object) => ({
+                kind: 'binary',
+                path: object.path,
+                mediaType: object.mediaType,
+                storageKind: 'r2',
+                storageKey: object.storageKey,
+                file: object.file,
+                byteSize: object.byteSize,
+            })),
+        };
+    }
+    throw new Error(`Bundle metadata in ${bundleFile} is not supported. Rebuild the Cloudflare bundle with the current mdorigin CLI.`);
+}
+async function readR2SyncState(stateFile) {
+    if (!(await pathExists(stateFile))) {
+        return { version: 1, uploaded: {} };
+    }
+    return JSON.parse(await readFile(stateFile, 'utf8'));
+}
+async function buildR2StorageKey(filePath, normalizedPath) {
+    const extension = path.posix.extname(normalizedPath).toLowerCase();
+    const hash = await hashFile(filePath);
+    return extension ? `binary/${hash}${extension}` : `binary/${hash}`;
+}
+async function hashFile(filePath) {
+    const hash = createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => {
+            hash.update(chunk);
+        });
+        stream.on('end', () => resolve());
+        stream.on('error', reject);
+    });
+    return hash.digest('hex');
+}
+function runWranglerCommand(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    return {
+        status: result.status,
+        stderr: result.stderr ?? '',
+    };
+}
 async function listFiles(directory, visitedRealDirectories = new Set()) {
     const directoryRealPath = await realpath(directory);
     if (visitedRealDirectories.has(directoryRealPath)) {
@@ -123,6 +433,9 @@ async function listFiles(directory, visitedRealDirectories = new Set()) {
     const entries = await readdir(directory, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
+        if (isIgnoredContentName(entry.name)) {
+            continue;
+        }
         const fullPath = path.join(directory, entry.name);
         const entryStats = await stat(fullPath);
         if (entryStats.isDirectory()) {
@@ -135,31 +448,39 @@ async function listFiles(directory, visitedRealDirectories = new Set()) {
     }
     return files;
 }
-async function readBundleEntries(directory) {
+async function buildSearchBundleEntries(directory, assetsMaxBytes) {
     const files = await listFiles(directory);
     const entries = [];
     for (const filePath of files) {
         const relativePath = path.relative(directory, filePath).replaceAll(path.sep, '/');
         const mediaType = getMediaTypeForPath(relativePath);
-        if (isLikelyTextPath(relativePath) || relativePath.endsWith('.json')) {
+        const fileStats = await stat(filePath);
+        if (fileStats.size <= assetsMaxBytes) {
             entries.push({
                 path: relativePath,
-                kind: 'text',
                 mediaType,
-                text: await readFile(filePath, 'utf8'),
+                storageKind: 'assets',
+                storageKey: `${SEARCH_ASSETS_PREFIX}/${relativePath}`,
+                byteSize: fileStats.size,
             });
             continue;
         }
         entries.push({
             path: relativePath,
-            kind: 'binary',
             mediaType,
-            base64: (await readFile(filePath)).toString('base64'),
+            storageKind: 'r2',
+            storageKey: await buildSearchStorageKey(filePath, relativePath),
+            byteSize: fileStats.size,
         });
     }
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return entries;
 }
+async function buildSearchStorageKey(filePath, relativePath) {
+    const extension = path.posix.extname(relativePath).toLowerCase();
+    const hash = await hashFile(filePath);
+    return extension ? `search/${hash}${extension}` : `search/${hash}`;
+}
 async function pathExists(filePath) {
     try {
         await stat(filePath);

package/dist/core/api.js

@@ -13,10 +13,15 @@ export async function handleApiRoute(pathname, searchParams, options) {
             });
         }
         const topK = normalizePositiveInteger(searchParams?.get('topK')) ?? 10;
-        const hits = await options.searchApi.search(query, { topK });
+        const metadata = readSearchMetadataFilters(searchParams);
+        const hits = await options.searchApi.search(query, {
+            topK,
+            metadata,
+        });
         return json(200, {
             query,
             topK,
+            metadata,
             count: hits.length,
             hits: hits.map(serializeSearchHit),
         });
@@ -56,6 +61,13 @@ function buildOpenApiDocument(options) {
                             schema: { type: 'integer', minimum: 1, default: 10 },
                             description: 'Maximum number of hits to return.',
                         },
+                        {
+                            name: 'meta.<field>',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                            description: 'Exact-match metadata filter. Use query parameters such as meta.type=post or meta.section=guides.',
+                        },
                     ],
                     responses: {
                         '200': {
@@ -68,6 +80,10 @@ function buildOpenApiDocument(options) {
                                         properties: {
                                             query: { type: 'string' },
                                             topK: { type: 'integer' },
+                                            metadata: {
+                                                type: 'object',
+                                                additionalProperties: { type: 'string' },
+                                            },
                                             count: { type: 'integer' },
                                             hits: {
                                                 type: 'array',
@@ -130,6 +146,23 @@ function buildOpenApiDocument(options) {
         },
     };
 }
+function readSearchMetadataFilters(searchParams) {
+    if (!searchParams) {
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, value] of searchParams.entries()) {
+        if (!key.startsWith('meta.') || value.trim() === '') {
+            continue;
+        }
+        const metadataKey = key.slice('meta.'.length).trim();
+        if (metadataKey === '') {
+            continue;
+        }
+        metadata[metadataKey] = value;
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
 function serializeSearchHit(hit) {
     return {
         docId: hit.docId,

package/dist/core/content-store.d.ts

@@ -15,6 +15,7 @@ export interface ContentStore {
     get(contentPath: string): Promise<ContentEntry | null>;
     listDirectory(contentPath: string): Promise<ContentDirectoryEntry[] | null>;
 }
+export declare function isIgnoredContentName(name: string): boolean;
 export declare class MemoryContentStore implements ContentStore {
     private readonly entries;
     constructor(entries: Iterable<ContentEntry>);