mdorigin 0.1.8 → 0.2.1

package/README.md

@@ -108,6 +108,18 @@ mdorigin dev --root docs/site --search dist/search
 mdorigin build cloudflare --root docs/site --search dist/search
 ```
 
+For media-heavy sites that would exceed Worker bundle limits, build in external binary mode instead:
+
+```bash
+mdorigin build cloudflare --root docs/site --binary-mode external
+mdorigin sync cloudflare-r2 --dir dist/cloudflare --bucket <bucket-name>
+mdorigin init cloudflare --dir . --r2-bucket <bucket-name>
+```
+
+In this mode, markdown and other text stay embedded in the Worker bundle, smaller binaries are staged for Workers Static Assets, and oversized binaries are staged for R2.
+
+`mdorigin` ignores dotfiles and dot-directories during content traversal. `.gitignore` is not used to decide publish visibility.
+
 Runtime endpoints:
 
 - `/api/search?q=cloudflare+deploy`
@@ -123,3 +135,5 @@ Runtime endpoints:
 - CLI: [`docs/site/reference/cli.md`](docs/site/reference/cli.md)
 - Search setup: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md#quick-start)
 - Cloudflare deployment: [`docs/site/guides/cloudflare.md`](docs/site/guides/cloudflare.md)
+
+The docs site at <https://mdorigin.jolestar.workers.dev> is deployed automatically from `main` with GitHub Actions.

package/dist/adapters/cloudflare.d.ts

@@ -1,22 +1,59 @@
-import { type ContentEntryKind } from '../core/content-store.js';
 import type { MdoPlugin } from '../core/extensions.js';
 import type { ResolvedSiteConfig } from '../core/site-config.js';
-import { type SearchBundleEntry } from '../search.js';
-export interface CloudflareManifestEntry {
+import { type ExternalSearchBundleEntry, type SearchBundleEntry } from '../search.js';
+export interface TextCloudflareManifestEntry {
     path: string;
-    kind: ContentEntryKind;
+    kind: 'text';
     mediaType: string;
     text?: string;
+}
+export interface InlineBinaryCloudflareManifestEntry {
+    path: string;
+    kind: 'binary';
+    mediaType: string;
     base64?: string;
 }
+export interface ExternalBinaryCloudflareManifestEntry {
+    path: string;
+    kind: 'binary';
+    mediaType: string;
+    storageKind: 'assets' | 'r2';
+    storageKey: string;
+    byteSize: number;
+}
+export type CloudflareManifestEntry = TextCloudflareManifestEntry | InlineBinaryCloudflareManifestEntry | ExternalBinaryCloudflareManifestEntry;
+export interface CloudflareBundleRuntimeConfig {
+    binaryMode: 'inline' | 'external';
+    r2Binding?: string;
+}
 export interface CloudflareManifest {
     entries: CloudflareManifestEntry[];
     siteConfig?: ResolvedSiteConfig;
     searchEntries?: SearchBundleEntry[];
+    externalSearchEntries?: ExternalSearchBundleEntry[];
+    runtime?: CloudflareBundleRuntimeConfig;
 }
-export interface ExportedHandlerLike {
+export interface CloudflareAssetsBindingLike {
     fetch(request: Request): Promise<Response>;
 }
+export interface CloudflareR2ObjectBodyLike {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface CloudflareR2ObjectLike {
+    body: CloudflareR2ObjectBodyLike | ReadableStream | null;
+    arrayBuffer?: () => Promise<ArrayBuffer>;
+    httpEtag?: string;
+}
+export interface CloudflareR2BucketLike {
+    get(key: string): Promise<CloudflareR2ObjectLike | null>;
+}
+export interface CloudflareWorkerEnv {
+    ASSETS?: CloudflareAssetsBindingLike;
+    [binding: string]: unknown;
+}
+export interface ExportedHandlerLike {
+    fetch(request: Request, env?: CloudflareWorkerEnv, ctx?: unknown): Promise<Response>;
+}
 export interface CreateCloudflareWorkerOptions {
     plugins?: MdoPlugin[];
 }

package/dist/adapters/cloudflare.js

@@ -1,8 +1,9 @@
-import { MemoryContentStore, } from '../core/content-store.js';
+import { MemoryContentStore } from '../core/content-store.js';
 import { handleSiteRequest } from '../core/request-handler.js';
-import { createSearchApiFromBundle } from '../search.js';
+import { resolveRequest } from '../core/router.js';
+import { createSearchApiFromBundle, createSearchApiFromExternalBundle, } from '../search.js';
 export function createCloudflareWorker(manifest, options = {}) {
-    const store = new MemoryContentStore(manifest.entries.map((entry) => {
+    const storeIndex = new MemoryContentStore(manifest.entries.map((entry) => {
         if (entry.kind === 'text') {
             return {
                 path: entry.path,
@@ -11,6 +12,13 @@ export function createCloudflareWorker(manifest, options = {}) {
                 text: entry.text ?? '',
             };
         }
+        if ('storageKind' in entry) {
+            return {
+                path: entry.path,
+                kind: 'binary',
+                mediaType: entry.mediaType,
+            };
+        }
         return {
             path: entry.path,
             kind: 'binary',
@@ -18,12 +26,23 @@ export function createCloudflareWorker(manifest, options = {}) {
             bytes: decodeBase64(entry.base64 ?? ''),
         };
     }));
-    const searchApi = manifest.searchEntries && manifest.searchEntries.length > 0
+    const inlineSearchApi = manifest.searchEntries && manifest.searchEntries.length > 0
         ? createSearchApiFromBundle(manifest.searchEntries)
         : undefined;
+    const externalSearchApis = new WeakMap();
+    let defaultExternalSearchApi;
     return {
-        async fetch(request) {
+        async fetch(request, env) {
             const url = new URL(request.url);
+            const externalSearchApi = getExternalSearchApi(manifest, env, externalSearchApis, defaultExternalSearchApi);
+            if (env === undefined && externalSearchApi !== undefined) {
+                defaultExternalSearchApi = externalSearchApi;
+            }
+            const directBinaryResponse = await tryServeExternalBinary(manifest, request, env);
+            if (directBinaryResponse !== null) {
+                return directBinaryResponse;
+            }
+            const store = new CloudflareManifestContentStore(manifest, storeIndex, request, env);
             const siteResponse = await handleSiteRequest(store, url.pathname, {
                 draftMode: 'exclude',
                 siteConfig: manifest.siteConfig ?? {
@@ -33,23 +52,21 @@ export function createCloudflareWorker(manifest, options = {}) {
                     logo: undefined,
                     showDate: true,
                     showSummary: true,
-                    theme: 'paper',
-                    template: 'document',
                     topNav: [],
                     footerNav: [],
                     footerText: undefined,
                     socialLinks: [],
                     editLink: undefined,
                     showHomeIndex: true,
-                    catalogInitialPostCount: 10,
-                    catalogLoadMoreStep: 10,
+                    listingInitialPostCount: 10,
+                    listingLoadMoreStep: 10,
                     siteTitleConfigured: false,
                     siteDescriptionConfigured: false,
                 },
                 acceptHeader: request.headers.get('accept') ?? undefined,
                 searchParams: url.searchParams,
                 requestUrl: request.url,
-                searchApi,
+                searchApi: inlineSearchApi ?? externalSearchApi,
                 plugins: options.plugins,
             });
             const headers = new Headers(siteResponse.headers);
@@ -65,6 +82,229 @@ export function createCloudflareWorker(manifest, options = {}) {
         },
     };
 }
+function getExternalSearchApi(manifest, env, cache, defaultApi) {
+    if (!manifest.externalSearchEntries || manifest.externalSearchEntries.length === 0) {
+        return undefined;
+    }
+    if (!env) {
+        return (defaultApi ??
+            createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, undefined, manifest.runtime?.r2Binding)));
+    }
+    const cached = cache.get(env);
+    if (cached) {
+        return cached;
+    }
+    const searchApi = createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, env, manifest.runtime?.r2Binding));
+    cache.set(env, searchApi);
+    return searchApi;
+}
+async function loadExternalSearchEntryResponse(entry, env, r2Binding) {
+    if (entry.storageKind === 'assets') {
+        const assetsBinding = env?.ASSETS;
+        if (!assetsBinding) {
+            throw new Error(`Cloudflare ASSETS binding is required to serve search bundle file ${entry.path}.`);
+        }
+        const assetResponse = await assetsBinding.fetch(new Request(new URL(`/${entry.storageKey}`, 'https://mdorigin-search.invalid/'), {
+            method: 'GET',
+        }));
+        if (assetResponse.ok) {
+            return assetResponse;
+        }
+        return new Response('Not Found', {
+            status: 404,
+            headers: {
+                'content-type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    const bindingName = r2Binding ?? 'MDORIGIN_R2';
+    const bucket = env?.[bindingName];
+    if (!bucket) {
+        throw new Error(`Cloudflare R2 binding ${bindingName} is required to serve search bundle file ${entry.path}.`);
+    }
+    const object = await bucket.get(entry.storageKey);
+    if (!object) {
+        return new Response('Not Found', {
+            status: 404,
+            headers: {
+                'content-type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    const headers = new Headers({
+        'content-type': entry.mediaType,
+    });
+    if (object.httpEtag) {
+        headers.set('etag', object.httpEtag);
+    }
+    if (object.body instanceof ReadableStream) {
+        return new Response(object.body, {
+            status: 200,
+            headers,
+        });
+    }
+    if (object.body && 'arrayBuffer' in object.body) {
+        return new Response(await object.body.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    if (typeof object.arrayBuffer === 'function') {
+        return new Response(await object.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    return new Response(null, {
+        status: 200,
+        headers,
+    });
+}
+async function tryServeExternalBinary(manifest, request, env) {
+    const resolved = resolveRequest(new URL(request.url).pathname);
+    if (resolved.kind !== 'asset' || !resolved.sourcePath) {
+        return null;
+    }
+    const manifestEntry = manifest.entries.find((entry) => entry.path === resolved.sourcePath && isExternalBinaryEntry(entry));
+    if (!manifestEntry) {
+        return null;
+    }
+    if (manifestEntry.storageKind === 'assets') {
+        const assetsBinding = env?.ASSETS;
+        if (!assetsBinding) {
+            throw new Error(`Cloudflare ASSETS binding is required to serve ${manifestEntry.path}.`);
+        }
+        const assetUrl = new URL(request.url);
+        assetUrl.pathname = `/${manifestEntry.storageKey}`;
+        return assetsBinding.fetch(new Request(assetUrl.toString(), request));
+    }
+    const bucket = env?.[manifest.runtime?.r2Binding ?? 'MDORIGIN_R2'];
+    if (!bucket) {
+        throw new Error(`Cloudflare R2 binding ${manifest.runtime?.r2Binding ?? 'MDORIGIN_R2'} is required to serve ${manifestEntry.path}.`);
+    }
+    const object = await bucket.get(manifestEntry.storageKey);
+    if (!object) {
+        return new Response('Not Found', {
+            status: 404,
+            headers: {
+                'content-type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    const headers = new Headers({
+        'content-type': manifestEntry.mediaType,
+    });
+    if (object.httpEtag) {
+        headers.set('etag', object.httpEtag);
+    }
+    if (request.method === 'HEAD') {
+        return new Response(null, {
+            status: 200,
+            headers,
+        });
+    }
+    if (object.body instanceof ReadableStream) {
+        return new Response(object.body, {
+            status: 200,
+            headers,
+        });
+    }
+    if (object.body && 'arrayBuffer' in object.body) {
+        return new Response(await object.body.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    if (typeof object.arrayBuffer === 'function') {
+        return new Response(await object.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    return new Response(null, {
+        status: 200,
+        headers,
+    });
+}
+function isExternalBinaryEntry(entry) {
+    return entry.kind === 'binary' && 'storageKind' in entry;
+}
+class CloudflareManifestContentStore {
+    storeIndex;
+    request;
+    env;
+    entries;
+    runtime;
+    constructor(manifest, storeIndex, request, env) {
+        this.storeIndex = storeIndex;
+        this.request = request;
+        this.env = env;
+        this.entries = new Map(manifest.entries.map((entry) => [entry.path, entry]));
+        this.runtime = manifest.runtime;
+    }
+    async get(contentPath) {
+        const baseEntry = await this.storeIndex.get(contentPath);
+        if (baseEntry === null) {
+            return null;
+        }
+        const manifestEntry = this.entries.get(contentPath);
+        if (!manifestEntry || manifestEntry.kind === 'text') {
+            return baseEntry;
+        }
+        if (!('storageKind' in manifestEntry)) {
+            return baseEntry;
+        }
+        if (manifestEntry.storageKind === 'assets') {
+            const assetsBinding = this.env?.ASSETS;
+            if (!assetsBinding) {
+                throw new Error(`Cloudflare ASSETS binding is required to serve ${manifestEntry.path}.`);
+            }
+            const assetResponse = await assetsBinding.fetch(new Request(new URL(`/${manifestEntry.storageKey}`, this.request.url), {
+                method: 'GET',
+            }));
+            if (!assetResponse.ok) {
+                return null;
+            }
+            return {
+                path: manifestEntry.path,
+                kind: 'binary',
+                mediaType: manifestEntry.mediaType,
+                bytes: new Uint8Array(await assetResponse.arrayBuffer()),
+            };
+        }
+        const r2BindingName = this.findR2BindingName(manifestEntry);
+        const bucket = this.env?.[r2BindingName];
+        if (!bucket) {
+            throw new Error(`Cloudflare R2 binding ${r2BindingName} is required to serve ${manifestEntry.path}.`);
+        }
+        const object = await bucket.get(manifestEntry.storageKey);
+        if (!object) {
+            return null;
+        }
+        const arrayBuffer = typeof object.arrayBuffer === 'function'
+            ? await object.arrayBuffer()
+            : object.body instanceof ReadableStream
+                ? await new Response(object.body).arrayBuffer()
+                : object.body && 'arrayBuffer' in object.body
+                    ? await object.body.arrayBuffer()
+                    : new ArrayBuffer(0);
+        return {
+            path: manifestEntry.path,
+            kind: 'binary',
+            mediaType: manifestEntry.mediaType,
+            bytes: new Uint8Array(arrayBuffer),
+        };
+    }
+    async listDirectory(contentPath) {
+        return this.storeIndex.listDirectory(contentPath);
+    }
+    findR2BindingName(entry) {
+        if (entry.storageKind !== 'r2') {
+            return 'ASSETS';
+        }
+        return this.runtime?.r2Binding ?? 'MDORIGIN_R2';
+    }
+}
 function decodeBase64(value) {
     const decoded = atob(value);
     return Uint8Array.from(decoded, (character) => character.charCodeAt(0));

package/dist/adapters/node.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { getMediaTypeForPath, isLikelyTextPath, normalizeContentPath, normalizeDirectoryPath, } from '../core/content-store.js';
+import { getMediaTypeForPath, isIgnoredContentName, isLikelyTextPath, normalizeContentPath, normalizeDirectoryPath, } from '../core/content-store.js';
 import { handleSiteRequest } from '../core/request-handler.js';
 export function createFileSystemContentStore(rootDir) {
     const resolvedRootDir = path.resolve(rootDir);
@@ -61,7 +61,7 @@ export function createFileSystemContentStore(rootDir) {
                 }
                 const entries = await readdir(directoryPath, { withFileTypes: true });
                 const resolvedEntries = await Promise.all(entries
-                    .filter((entry) => !entry.name.startsWith('.'))
+                    .filter((entry) => !isIgnoredContentName(entry.name))
                     .map(async (entry) => {
                     const childVisiblePath = normalizedPath === ''
                         ? entry.name

package/dist/cli/build-cloudflare.js

@@ -5,11 +5,11 @@ import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core
 export async function runBuildCloudflareCommand(argv) {
     const args = parseArgs(argv);
     if (args.help) {
-        console.log('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]');
+        console.log('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]');
         return;
     }
     if (!args.root) {
-        console.error('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]');
+        console.error('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]');
         process.exitCode = 1;
         return;
     }
@@ -27,6 +27,9 @@ export async function runBuildCloudflareCommand(argv) {
         siteConfig,
         searchDir: args.search ? path.resolve(args.search) : undefined,
         configModulePath: loadedConfig.configModulePath,
+        binaryMode: args.binaryMode,
+        assetsMaxBytes: args.assetsMaxBytes,
+        r2Binding: args.r2Binding,
     });
     console.log(`cloudflare worker written to ${result.workerFile}`);
 }
@@ -59,6 +62,28 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (argument === '--binary-mode' && nextValue) {
+            if (nextValue !== 'inline' && nextValue !== 'external') {
+                throw new Error(`Invalid binary mode for mdorigin build cloudflare: ${nextValue}`);
+            }
+            result.binaryMode = nextValue;
+            index += 1;
+            continue;
+        }
+        if (argument === '--assets-max-bytes' && nextValue) {
+            const parsed = Number.parseInt(nextValue, 10);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`Invalid value for --assets-max-bytes: ${nextValue}`);
+            }
+            result.assetsMaxBytes = parsed;
+            index += 1;
+            continue;
+        }
+        if (argument === '--r2-binding' && nextValue) {
+            result.r2Binding = nextValue;
+            index += 1;
+            continue;
+        }
         throw new Error(`Unknown argument for mdorigin build cloudflare: ${argument}`);
     }
     return result;

package/dist/cli/build-search.js

@@ -5,11 +5,11 @@ import { createFileSystemContentStore } from '../adapters/node.js';
 export async function runBuildSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
     if (args.help) {
-        console.log('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
+        console.log('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]');
         return;
     }
     if (!args.root) {
-        throw new Error('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
+        throw new Error('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]');
     }
     const rootDir = path.resolve(args.root);
     const store = createFileSystemContentStore(rootDir);
@@ -24,18 +24,28 @@ export async function runBuildSearchCommand(rawArgs) {
         siteConfig,
         embeddingBackend: args.embeddingBackend ?? 'model2vec',
         model: args.model,
+        incremental: args.incremental,
     });
-    console.log(`search bundle written to ${result.outputDir} (${result.documentCount} documents, ${result.chunkCount} chunks)`);
+    console.log([
+        `search bundle written to ${result.outputDir} (${result.documentCount} documents, ${result.chunkCount} chunks)`,
+        result.incremental
+            ? `incremental cache: ${result.cachePath} (${result.incremental.newDocumentCount} new, ${result.incremental.changedDocumentCount} changed, ${result.incremental.unchangedDocumentCount} unchanged, ${result.incremental.removedDocumentCount} removed)`
+            : '',
+    ].filter(Boolean).join('\n'));
 }
 function parseArgs(rawArgs) {
     const parsed = {};
-    const supportedFlags = new Set(['root', 'out', 'embedding-backend', 'model', 'config']);
+    const supportedFlags = new Set(['root', 'out', 'embedding-backend', 'model', 'config', 'incremental']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
         if (arg === '--help' || arg === '-h') {
             parsed.help = 'true';
             continue;
         }
+        if (arg === '--incremental') {
+            parsed.incremental = 'true';
+            continue;
+        }
         if (arg.startsWith('--')) {
             const flag = arg.slice(2);
             if (!supportedFlags.has(flag)) {
@@ -57,6 +67,7 @@ function parseArgs(rawArgs) {
         embeddingBackend: parsed['embedding-backend'],
         model: parsed.model,
         config: parsed.config,
+        incremental: parsed.incremental === 'true',
         help: parsed.help === 'true',
     };
 }

package/dist/cli/help.js

@@ -2,10 +2,11 @@ export const ROOT_USAGE_LINES = [
     'Usage:',
     '  mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]',
     '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
-    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
-    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]',
-    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]',
-    '  mdorigin search --index <search-dir> [--top-k 10] <query>',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]',
+    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]',
+    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--r2-bucket <bucket-name>] [--force]',
+    '  mdorigin sync cloudflare-r2 --dir ./dist/cloudflare --bucket <bucket-name> [--force]',
+    '  mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>',
     '  mdorigin version',
     '',
     'Global options:',
@@ -15,12 +16,12 @@ export const ROOT_USAGE_LINES = [
 export const BUILD_USAGE_LINES = [
     'Usage:',
     '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
-    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
-    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]',
+    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]',
 ];
 export const INIT_USAGE_LINES = [
     'Usage:',
-    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]',
+    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--r2-bucket <bucket-name>] [--force]',
 ];
 export function printUsage(lines, error = false) {
     const output = lines.join('\n');

package/dist/cli/init-cloudflare.js

@@ -4,7 +4,7 @@ import { initCloudflareProject } from '../cloudflare.js';
 export async function runInitCloudflareCommand(argv) {
     const args = parseArgs(argv);
     if (args.help) {
-        console.log('Usage: mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]');
+        console.log('Usage: mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--r2-bucket <bucket-name>] [--force]');
         return;
     }
     const projectDir = path.resolve(args.dir ?? '.');
@@ -16,6 +16,7 @@ export async function runInitCloudflareCommand(argv) {
         workerName: args.name,
         siteTitle,
         compatibilityDate: args.compatibilityDate,
+        r2Bucket: args.r2Bucket,
         force: args.force,
     });
     console.log(`wrangler config written to ${result.configFile}`);
@@ -49,6 +50,11 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (argument === '--r2-bucket' && nextValue) {
+            result.r2Bucket = nextValue;
+            index += 1;
+            continue;
+        }
         if (argument === '--force') {
             result.force = true;
             continue;

package/dist/cli/main.js

@@ -9,6 +9,7 @@ import { runDevCommand } from './dev.js';
 import { BUILD_USAGE_LINES, INIT_USAGE_LINES, ROOT_USAGE_LINES, printUsage } from './help.js';
 import { runInitCloudflareCommand } from './init-cloudflare.js';
 import { runSearchCommand } from './search.js';
+import { runSyncCloudflareR2Command } from './sync-cloudflare-r2.js';
 async function main() {
     const argv = process.argv.slice(2);
     const [command, subcommand, ...rest] = argv;
@@ -62,6 +63,10 @@ async function main() {
         await runSearchCommand([subcommand, ...rest].filter(isDefined));
         return;
     }
+    if (command === 'sync' && subcommand === 'cloudflare-r2') {
+        await runSyncCloudflareR2Command(rest);
+        return;
+    }
     console.error(`Unknown command: ${argv.join(' ')}`);
     printUsage(ROOT_USAGE_LINES, true);
     process.exitCode = 1;

package/dist/cli/search.js

@@ -3,23 +3,25 @@ import { searchBundle } from '../search.js';
 export async function runSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
     if (args.help) {
-        console.log('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+        console.log('Usage: mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>');
         return;
     }
     if (!args.indexDir || !args.query) {
-        throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+        throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>');
     }
     const hits = await searchBundle({
         indexDir: path.resolve(args.indexDir),
         query: args.query,
         topK: args.topK,
+        metadata: args.metadata,
     });
     console.log(JSON.stringify(hits, null, 2));
 }
 function parseArgs(rawArgs) {
     const flags = {};
+    const metadata = {};
     const positionals = [];
-    const supportedFlags = new Set(['index', 'top-k']);
+    const supportedFlags = new Set(['index', 'top-k', 'meta']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
         if (arg === '--help' || arg === '-h') {
@@ -33,7 +35,16 @@ function parseArgs(rawArgs) {
             }
             const value = rawArgs[index + 1];
             if (value && !value.startsWith('--')) {
-                flags[flag] = value;
+                if (flag === 'meta') {
+                    const separator = value.indexOf('=');
+                    if (separator <= 0 || separator === value.length - 1) {
+                        throw new Error(`Invalid value for --meta: ${value}`);
+                    }
+                    metadata[value.slice(0, separator)] = value.slice(separator + 1);
+                }
+                else {
+                    flags[flag] = value;
+                }
                 index += 1;
                 continue;
             }
@@ -46,6 +57,7 @@ function parseArgs(rawArgs) {
         indexDir: flags.index,
         topK: Number.isInteger(topK) && topK > 0 ? topK : undefined,
         query: positionals.join(' ').trim(),
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         help: flags.help === 'true',
     };
 }

package/dist/cli/sync-cloudflare-r2.d.ts

@@ -0,0 +1 @@
+export declare function runSyncCloudflareR2Command(argv: string[]): Promise<void>;