mdorigin 0.1.1 → 0.1.3

package/dist/cloudflare.js

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, realpath, 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';
@@ -30,10 +30,14 @@ export async function buildCloudflareManifest(options) {
             base64: (await readFile(filePath)).toString('base64'),
         });
     }
+    const searchEntries = options.searchDir
+        ? await readBundleEntries(path.resolve(options.searchDir))
+        : undefined;
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return {
         entries,
         siteConfig: options.siteConfig,
+        searchEntries,
     };
 }
 export async function writeCloudflareBundle(options) {
@@ -41,15 +45,41 @@ export async function writeCloudflareBundle(options) {
     const manifest = await buildCloudflareManifest({
         rootDir: options.rootDir,
         siteConfig: options.siteConfig,
+        searchDir: options.searchDir,
     });
     const packageImport = options.packageImport ?? 'mdorigin/cloudflare-runtime';
     const workerFile = path.join(outDir, 'worker.mjs');
+    const configImportPath = options.configModulePath
+        ? toPosixPath(path.relative(outDir, options.configModulePath))
+        : null;
     const workerSource = [
         `import { createCloudflareWorker } from '${packageImport}';`,
+        configImportPath
+            ? `import * as userConfigModule from '${configImportPath.startsWith('.') ? configImportPath : `./${configImportPath}`}';`
+            : '',
         '',
         `const manifest = ${JSON.stringify(manifest, null, 2)};`,
         '',
-        'export default createCloudflareWorker(manifest);',
+        configImportPath
+            ? [
+                'function unwrapUserConfigModule(moduleValue) {',
+                '  let current = moduleValue;',
+                "  while (current && typeof current === 'object' && 'default' in current && current.default !== undefined) {",
+                '    current = current.default;',
+                '  }',
+                "  if (current && typeof current === 'object' && 'config' in current && current.config !== undefined) {",
+                '    return current.config;',
+                '  }',
+                '  return current;',
+                '}',
+                '',
+                'const userConfig = unwrapUserConfigModule(userConfigModule);',
+                '',
+            ].join('\n')
+            : '',
+        configImportPath
+            ? 'export default createCloudflareWorker(manifest, { plugins: Array.isArray(userConfig?.plugins) ? userConfig.plugins : [] });'
+            : 'export default createCloudflareWorker(manifest);',
         '',
     ].join('\n');
     await mkdir(outDir, { recursive: true });
@@ -84,21 +114,52 @@ export async function initCloudflareProject(options) {
     await writeFile(configFile, wranglerConfig, 'utf8');
     return { configFile };
 }
-async function listFiles(directory) {
+async function listFiles(directory, visitedRealDirectories = new Set()) {
+    const directoryRealPath = await realpath(directory);
+    if (visitedRealDirectories.has(directoryRealPath)) {
+        return [];
+    }
+    visitedRealDirectories.add(directoryRealPath);
     const entries = await readdir(directory, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
         const fullPath = path.join(directory, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...(await listFiles(fullPath)));
+        const entryStats = await stat(fullPath);
+        if (entryStats.isDirectory()) {
+            files.push(...(await listFiles(fullPath, visitedRealDirectories)));
             continue;
         }
-        if (entry.isFile()) {
+        if (entryStats.isFile()) {
             files.push(fullPath);
         }
     }
     return files;
 }
+async function readBundleEntries(directory) {
+    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')) {
+            entries.push({
+                path: relativePath,
+                kind: 'text',
+                mediaType,
+                text: await readFile(filePath, 'utf8'),
+            });
+            continue;
+        }
+        entries.push({
+            path: relativePath,
+            kind: 'binary',
+            mediaType,
+            base64: (await readFile(filePath)).toString('base64'),
+        });
+    }
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    return entries;
+}
 async function pathExists(filePath) {
     try {
         await stat(filePath);

package/dist/core/api.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedSiteConfig } from './site-config.js';
+import type { SearchApi } from '../search.js';
+export interface ApiRouteOptions {
+    searchApi?: SearchApi;
+    siteConfig: ResolvedSiteConfig;
+    requestUrl?: string;
+}
+export interface ApiRouteResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function handleApiRoute(pathname: string, searchParams: URLSearchParams | undefined, options: ApiRouteOptions): Promise<ApiRouteResponse | null>;

package/dist/core/api.js

@@ -0,0 +1,160 @@
+export async function handleApiRoute(pathname, searchParams, options) {
+    if (pathname === '/api/openapi.json') {
+        return json(200, buildOpenApiDocument(options));
+    }
+    if (pathname === '/api/search') {
+        if (!options.searchApi) {
+            return json(404, { error: 'search is not enabled for this site' });
+        }
+        const query = searchParams?.get('q')?.trim() ?? '';
+        if (query === '') {
+            return json(400, {
+                error: 'missing required query parameter: q',
+            });
+        }
+        const topK = normalizePositiveInteger(searchParams?.get('topK')) ?? 10;
+        const hits = await options.searchApi.search(query, { topK });
+        return json(200, {
+            query,
+            topK,
+            count: hits.length,
+            hits: hits.map(serializeSearchHit),
+        });
+    }
+    return null;
+}
+function buildOpenApiDocument(options) {
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: `${options.siteConfig.siteTitle} API`,
+            version: '1.0.0',
+            description: 'Search API for a mdorigin site.',
+        },
+        servers: options.siteConfig.siteUrl
+            ? [{ url: options.siteConfig.siteUrl }]
+            : options.requestUrl
+                ? [{ url: new URL(options.requestUrl).origin }]
+                : undefined,
+        paths: {
+            '/api/search': {
+                get: {
+                    operationId: 'searchSite',
+                    summary: 'Search published site content',
+                    parameters: [
+                        {
+                            name: 'q',
+                            in: 'query',
+                            required: true,
+                            schema: { type: 'string' },
+                            description: 'Search query string.',
+                        },
+                        {
+                            name: 'topK',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'integer', minimum: 1, default: 10 },
+                            description: 'Maximum number of hits to return.',
+                        },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Search results.',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['query', 'topK', 'count', 'hits'],
+                                        properties: {
+                                            query: { type: 'string' },
+                                            topK: { type: 'integer' },
+                                            count: { type: 'integer' },
+                                            hits: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'object',
+                                                    required: [
+                                                        'docId',
+                                                        'relativePath',
+                                                        'score',
+                                                        'metadata',
+                                                        'bestMatch',
+                                                    ],
+                                                    properties: {
+                                                        docId: { type: 'string' },
+                                                        relativePath: { type: 'string' },
+                                                        canonicalUrl: { type: 'string' },
+                                                        title: { type: 'string' },
+                                                        summary: { type: 'string' },
+                                                        score: { type: 'number' },
+                                                        metadata: { type: 'object', additionalProperties: true },
+                                                        bestMatch: {
+                                                            type: 'object',
+                                                            required: [
+                                                                'chunkId',
+                                                                'excerpt',
+                                                                'headingPath',
+                                                                'charStart',
+                                                                'charEnd',
+                                                                'score',
+                                                            ],
+                                                            properties: {
+                                                                chunkId: { type: 'number' },
+                                                                excerpt: { type: 'string' },
+                                                                headingPath: {
+                                                                    type: 'array',
+                                                                    items: { type: 'string' },
+                                                                },
+                                                                charStart: { type: 'integer' },
+                                                                charEnd: { type: 'integer' },
+                                                                score: { type: 'number' },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': {
+                            description: 'Invalid request.',
+                        },
+                        '404': {
+                            description: 'Search API not enabled.',
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+function serializeSearchHit(hit) {
+    return {
+        docId: hit.docId,
+        relativePath: hit.relativePath,
+        canonicalUrl: hit.canonicalUrl,
+        title: hit.title,
+        summary: hit.summary,
+        metadata: hit.metadata,
+        score: hit.score,
+        bestMatch: hit.bestMatch,
+    };
+}
+function normalizePositiveInteger(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function json(status, body) {
+    return {
+        status,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body, null, 2),
+    };
+}

package/dist/core/content-store.js

@@ -54,10 +54,15 @@ const MEDIA_TYPES = new Map([
     ['.json', 'application/json; charset=utf-8'],
     ['.md', 'text/markdown; charset=utf-8'],
     ['.pdf', 'application/pdf'],
+    ['.py', 'text/plain; charset=utf-8'],
     ['.png', 'image/png'],
+    ['.sh', 'text/plain; charset=utf-8'],
     ['.svg', 'image/svg+xml'],
     ['.txt', 'text/plain; charset=utf-8'],
+    ['.toml', 'text/plain; charset=utf-8'],
     ['.webp', 'image/webp'],
+    ['.yaml', 'text/plain; charset=utf-8'],
+    ['.yml', 'text/plain; charset=utf-8'],
 ]);
 export function getMediaTypeForPath(contentPath) {
     const extension = path.posix.extname(contentPath).toLowerCase();

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

@@ -1,6 +1,7 @@
 import type { ParsedDocumentMeta } from './markdown.js';
 export type ContentType = 'page' | 'post';
 export interface DirectoryShape {
+    hasSkillIndex: boolean;
     hasChildDirectories: boolean;
     hasExtraMarkdownFiles: boolean;
     hasAssetFiles: boolean;

package/dist/core/content-type.js

@@ -9,6 +9,9 @@ export function inferDirectoryContentType(meta, shape) {
     if (typeof meta.date === 'string' && meta.date !== '') {
         return 'post';
     }
+    if (shape.hasSkillIndex) {
+        return 'post';
+    }
     if (shape.hasChildDirectories || shape.hasExtraMarkdownFiles) {
         return 'page';
     }

package/dist/core/directory-index.d.ts

@@ -1,2 +1,2 @@
-export declare const DIRECTORY_INDEX_FILENAMES: readonly ["index.md", "README.md"];
+export declare const DIRECTORY_INDEX_FILENAMES: readonly ["index.md", "README.md", "SKILL.md"];
 export declare function getDirectoryIndexCandidates(directoryPath: string): string[];

package/dist/core/directory-index.js

@@ -1,5 +1,9 @@
 import path from 'node:path';
-export const DIRECTORY_INDEX_FILENAMES = ['index.md', 'README.md'];
+export const DIRECTORY_INDEX_FILENAMES = [
+    'index.md',
+    'README.md',
+    'SKILL.md',
+];
 export function getDirectoryIndexCandidates(directoryPath) {
     return DIRECTORY_INDEX_FILENAMES.map((filename) => directoryPath === '' ? filename : path.posix.join(directoryPath, filename));
 }

package/dist/core/extensions.d.ts

@@ -0,0 +1,66 @@
+import type { ManagedIndexEntry } from './markdown.js';
+import type { EditLinkConfig, ResolvedSiteConfig, SiteLogo, SiteNavItem, SiteSocialLink } from './site-config.js';
+import type { TemplateName } from '../html/template-kind.js';
+import type { BuiltInThemeName } from '../html/theme.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface IndexTransformContext {
+    mode: 'build' | 'render';
+    directoryPath?: string;
+    requestPath?: string;
+    sourcePath?: string;
+    siteConfig?: ResolvedSiteConfig;
+}
+export interface PageRenderModel {
+    kind: 'document' | 'catalog';
+    requestPath: string;
+    sourcePath: string;
+    siteTitle: string;
+    siteDescription?: string;
+    siteUrl?: string;
+    favicon?: string;
+    socialImage?: string;
+    logo?: SiteLogo;
+    title: string;
+    bodyHtml: string;
+    summary?: string;
+    date?: string;
+    showSummary: boolean;
+    showDate: boolean;
+    theme: BuiltInThemeName;
+    template: TemplateName;
+    topNav: SiteNavItem[];
+    footerNav: SiteNavItem[];
+    footerText?: string;
+    socialLinks: SiteSocialLink[];
+    editLink?: EditLinkConfig;
+    editLinkHref?: string;
+    stylesheetContent?: string;
+    canonicalPath?: string;
+    alternateMarkdownPath?: string;
+    catalogEntries: ManagedIndexEntry[];
+    catalogRequestPath: string;
+    catalogInitialPostCount: number;
+    catalogLoadMoreStep: number;
+    searchEnabled: boolean;
+}
+export interface RenderHookContext {
+    page: PageRenderModel;
+    siteConfig: ResolvedSiteConfig;
+}
+export interface MdoPlugin {
+    name?: string;
+    transformIndex?(entries: ManagedIndexEntry[], context: IndexTransformContext): MaybePromise<ManagedIndexEntry[]>;
+    renderHeader?(context: RenderHookContext): MaybePromise<string | undefined | null>;
+    renderFooter?(context: RenderHookContext): MaybePromise<string | undefined | null>;
+    renderPage?(page: PageRenderModel, context: RenderHookContext, next: (page: PageRenderModel) => MaybePromise<string>): MaybePromise<string | undefined | null>;
+    transformHtml?(html: string, context: RenderHookContext): MaybePromise<string>;
+}
+export declare function applyIndexTransforms(entries: ManagedIndexEntry[], plugins: MdoPlugin[], context: IndexTransformContext): Promise<ManagedIndexEntry[]>;
+export declare function renderHeaderOverride(plugins: MdoPlugin[], context: RenderHookContext): Promise<string | undefined>;
+export declare function renderFooterOverride(plugins: MdoPlugin[], context: RenderHookContext): Promise<string | undefined>;
+export declare function renderPageWithPlugins(page: PageRenderModel, plugins: MdoPlugin[], context: RenderHookContext, renderDefault: (page: PageRenderModel) => MaybePromise<string>): Promise<{
+    html: string;
+    page: PageRenderModel;
+}>;
+export declare function transformHtmlWithPlugins(html: string, plugins: MdoPlugin[], context: RenderHookContext): Promise<string>;
+export {};

package/dist/core/extensions.js

@@ -0,0 +1,86 @@
+export async function applyIndexTransforms(entries, plugins, context) {
+    let current = [...entries];
+    for (const plugin of plugins) {
+        if (!plugin.transformIndex) {
+            continue;
+        }
+        current = [...(await plugin.transformIndex(current, context))];
+    }
+    return current;
+}
+export async function renderHeaderOverride(plugins, context) {
+    let rendered;
+    for (const plugin of plugins) {
+        if (!plugin.renderHeader) {
+            continue;
+        }
+        const value = await plugin.renderHeader(context);
+        if (typeof value === 'string') {
+            rendered = value;
+        }
+    }
+    return rendered;
+}
+export async function renderFooterOverride(plugins, context) {
+    let rendered;
+    for (const plugin of plugins) {
+        if (!plugin.renderFooter) {
+            continue;
+        }
+        const value = await plugin.renderFooter(context);
+        if (typeof value === 'string') {
+            rendered = value;
+        }
+    }
+    return rendered;
+}
+export async function renderPageWithPlugins(page, plugins, context, renderDefault) {
+    const renderers = plugins
+        .map((plugin) => plugin.renderPage)
+        .filter((renderPage) => typeof renderPage === 'function');
+    let finalPage = page;
+    const dispatch = async (index, currentPage) => {
+        const renderPage = renderers[index];
+        if (!renderPage) {
+            finalPage = currentPage;
+            return renderDefault(currentPage);
+        }
+        const currentContext = {
+            ...context,
+            page: currentPage,
+        };
+        let nextInvoked = false;
+        const next = async (nextPage) => {
+            nextInvoked = true;
+            finalPage = nextPage;
+            return dispatch(index + 1, nextPage);
+        };
+        const rendered = await renderPage(currentPage, currentContext, next);
+        if (typeof rendered === 'string') {
+            if (!nextInvoked) {
+                finalPage = currentPage;
+            }
+            return rendered;
+        }
+        return next(currentPage);
+    };
+    return {
+        html: await dispatch(0, page),
+        page: finalPage,
+    };
+}
+export async function transformHtmlWithPlugins(html, plugins, context) {
+    let current = html;
+    for (const plugin of plugins) {
+        if (!plugin.transformHtml) {
+            continue;
+        }
+        const result = await plugin.transformHtml(current, context);
+        if (typeof result !== 'string') {
+            const pluginName = plugin.name ?? 'unknown plugin';
+            throw new Error(`transformHtmlWithPlugins expected plugin "${pluginName}" to return a string, but got ${typeof result}`);
+        }
+        current = result;
+    }
+    return current;
+}

package/dist/core/markdown.d.ts

@@ -1,7 +1,9 @@
 export interface ParsedDocumentMeta {
     title?: string;
+    name?: string;
     date?: string;
     summary?: string;
+    description?: string;
     draft?: boolean;
     type?: string;
     order?: number;
@@ -20,6 +22,8 @@ export interface ManagedIndexEntry {
     href: string;
     detail?: string;
 }
+export declare function getDocumentTitle(meta: ParsedDocumentMeta, body: string, fallback: string): string;
+export declare function getDocumentSummary(meta: ParsedDocumentMeta, body: string): string | undefined;
 export declare function parseMarkdownDocument(sourcePath: string, markdown: string): Promise<ParsedDocument>;
 export declare function renderMarkdown(markdown: string): Promise<string>;
 export declare function rewriteMarkdownLinksInHtml(html: string): string;

package/dist/core/markdown.js

@@ -2,6 +2,15 @@ import matter from 'gray-matter';
 import { remark } from 'remark';
 import remarkGfm from 'remark-gfm';
 import remarkHtml from 'remark-html';
+export function getDocumentTitle(meta, body, fallback) {
+    return (firstNonEmptyString(meta.title, meta.name) ??
+        extractFirstHeading(body) ??
+        fallback);
+}
+export function getDocumentSummary(meta, body) {
+    return (firstNonEmptyString(meta.summary, meta.description) ??
+        extractFirstParagraph(body));
+}
 export async function parseMarkdownDocument(sourcePath, markdown) {
     const parsed = matter(markdown);
     const html = rewriteMarkdownLinksInHtml(await renderMarkdown(parsed.content));
@@ -83,6 +92,9 @@ function normalizeMeta(data) {
     if (typeof data.title === 'string') {
         meta.title = data.title;
     }
+    if (typeof data.name === 'string') {
+        meta.name = data.name;
+    }
     if (typeof data.date === 'string') {
         meta.date = data.date;
     }
@@ -92,6 +104,9 @@ function normalizeMeta(data) {
     if (typeof data.summary === 'string') {
         meta.summary = data.summary;
     }
+    if (typeof data.description === 'string') {
+        meta.description = data.description;
+    }
     if (typeof data.draft === 'boolean') {
         meta.draft = data.draft;
     }
@@ -143,6 +158,12 @@ function rewriteMarkdownPath(pathname) {
     if (pathname.toLowerCase() === 'readme.md') {
         return './';
     }
+    if (pathname.toLowerCase().endsWith('/skill.md')) {
+        return pathname.slice(0, -'SKILL.md'.length);
+    }
+    if (pathname.toLowerCase() === 'skill.md') {
+        return './';
+    }
     return pathname.slice(0, -'.md'.length);
 }
 function shouldPreserveHref(href) {
@@ -168,3 +189,35 @@ function normalizeManagedIndexHref(href) {
     }
     return href;
 }
+function extractFirstHeading(markdown) {
+    for (const line of markdown.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('#')) {
+            continue;
+        }
+        const heading = trimmed.replace(/^#+\s*/, '').trim();
+        if (heading !== '') {
+            return heading;
+        }
+    }
+    return undefined;
+}
+function extractFirstParagraph(markdown) {
+    const paragraphs = markdown
+        .split(/\n\s*\n/g)
+        .map((paragraph) => paragraph.trim())
+        .filter((paragraph) => paragraph !== '');
+    for (const paragraph of paragraphs) {
+        if (paragraph.startsWith('#') ||
+            paragraph.startsWith('<!--') ||
+            paragraph.startsWith('- ') ||
+            paragraph.startsWith('* ')) {
+            continue;
+        }
+        return paragraph.replace(/\s+/g, ' ');
+    }
+    return undefined;
+}
+function firstNonEmptyString(...values) {
+    return values.find((value) => typeof value === 'string' && value !== '');
+}

package/dist/core/request-handler.d.ts

@@ -1,9 +1,15 @@
 import type { ContentStore } from './content-store.js';
+import type { MdoPlugin } from './extensions.js';
 import type { ResolvedSiteConfig } from './site-config.js';
+import type { SearchApi } from '../search.js';
 export interface HandleSiteRequestOptions {
     draftMode: 'include' | 'exclude';
     siteConfig: ResolvedSiteConfig;
     acceptHeader?: string;
+    searchParams?: URLSearchParams;
+    requestUrl?: string;
+    searchApi?: SearchApi;
+    plugins?: MdoPlugin[];
 }
 export interface SiteResponse {
     status: number;