@mintlify/previewing 4.0.1195 → 4.0.1196

package/dist/__tests__/dev.test.js

@@ -13,6 +13,7 @@ vi.mock('fs-extra', () => {
         pathExists: vi.fn().mockResolvedValue(true),
         readFileSync: vi.fn().mockReturnValue('0.0.100'),
         emptyDirSync: vi.fn().mockResolvedValue(undefined),
+        outputFileSync: vi.fn(),
     };
     return {
         ...mocks,

package/dist/local-preview/index.js

@@ -1,13 +1,32 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { prebuild } from '@mintlify/prebuild';
+import { getFileListSync, prebuild } from '@mintlify/prebuild';
 import fse, { pathExists } from 'fs-extra';
 import isOnline from 'is-online';
+import pathUtil from 'path';
 import { CLIENT_PATH, DOT_MINTLIFY, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, } from '../constants.js';
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog } from '../logs.js';
 import { timeDev, timeDevSync } from './dev-timing.js';
 import { run } from './run.js';
 import { silentUpdateClient } from './update.js';
+const PRUNE_EXEMPT_PREFIXES = ['favicons/', '.mint-content-source'];
+const prunePublicOrphans = () => {
+    let publicFiles;
+    try {
+        publicFiles = getFileListSync(NEXT_PUBLIC_PATH);
+    }
+    catch {
+        return;
+    }
+    for (const relativePath of publicFiles) {
+        if (PRUNE_EXEMPT_PREFIXES.some((prefix) => relativePath.startsWith(prefix))) {
+            continue;
+        }
+        if (!fse.existsSync(pathUtil.join(CMD_EXEC_PATH, relativePath))) {
+            fse.removeSync(pathUtil.join(NEXT_PUBLIC_PATH, relativePath));
+        }
+    }
+};
 const dev = async (argv) => {
     const hasInternet = await timeDev('check internet', () => isOnline());
     const localSchema = argv['local-schema'];
@@ -42,8 +61,23 @@ const dev = async (argv) => {
     }
     // clear preexisting prebuild files
     timeDevSync('clear prebuild output', () => {
-        fse.emptyDirSync(NEXT_PUBLIC_PATH);
         fse.emptyDirSync(NEXT_PROPS_PATH);
+        // only clear public/ when previewing a different docs repo, so unchanged
+        // static files can be skipped on warm starts; on warm starts, prune files
+        // whose source no longer exists so deleted assets stop being served
+        const markerPath = pathUtil.join(NEXT_PUBLIC_PATH, '.mint-content-source');
+        let previousSource;
+        try {
+            previousSource = fse.readFileSync(markerPath, 'utf8');
+        }
+        catch { }
+        if (previousSource !== CMD_EXEC_PATH) {
+            fse.emptyDirSync(NEXT_PUBLIC_PATH);
+            fse.outputFileSync(markerPath, CMD_EXEC_PATH);
+        }
+        else {
+            prunePublicOrphans();
+        }
     });
     timeDevSync('switch to local client directory', () => {
         process.chdir(CLIENT_PATH);
@@ -55,6 +89,7 @@ const dev = async (argv) => {
             groups,
             disableOpenApi,
             allowSourceRefs: true,
+            lazyPages: true,
         }));
         fileImportsMap = result?.fileImportsMap;
     }

package/dist/local-preview/listener/index.d.ts

@@ -4,7 +4,7 @@ type LocalPreviewOptions = {
     groups?: string[];
     allowSourceRefs?: boolean;
 };
-declare const listener: (triggerRefresh: () => void, options?: LocalPreviewOptions) => void;
+declare const listener: (triggerRefresh: () => void, options?: LocalPreviewOptions, gate?: Promise<void>) => void;
 declare const initializeFrontmatterHashCache: () => Promise<void>;
 declare const initializeDocsConfigHashCache: () => Promise<void>;
 export { initializeDocsConfigHashCache, initializeFrontmatterHashCache, initializeImportCache };

package/dist/local-preview/listener/index.js

@@ -81,7 +81,9 @@ const addUpdateTimingLog = (filename, category, durationMs) => {
     const categoryLabel = category == null ? 'uncategorized' : category;
     addChangeLog(_jsx(InfoLog, { message: `processed ${filename} in ${formatElapsedSeconds(durationMs)} (${categoryLabel})` }));
 };
-const listener = (triggerRefresh, options = {}) => {
+let watcherGate;
+const listener = (triggerRefresh, options = {}, gate) => {
+    watcherGate = gate;
     const previewOptions = { ...options, allowSourceRefs: true };
     const mintIgnoreGlobs = getMintIgnoreGlobs();
     chokidar
@@ -103,6 +105,9 @@ const listener = (triggerRefresh, options = {}) => {
         .on('unlink', (filename) => onUnlinkEvent(filename, triggerRefresh, previewOptions));
 };
 const onAddEvent = async (filename, triggerRefresh, options) => {
+    if (watcherGate) {
+        await watcherGate;
+    }
     if (isMintIgnored(filename, getMintIgnoreGlobs())) {
         return;
     }
@@ -119,6 +124,9 @@ const onAddEvent = async (filename, triggerRefresh, options) => {
     }
 };
 const onChangeEvent = async (filename, triggerRefresh, options) => {
+    if (watcherGate) {
+        await watcherGate;
+    }
     if (isMintIgnored(filename, getMintIgnoreGlobs())) {
         return;
     }
@@ -135,6 +143,9 @@ const onChangeEvent = async (filename, triggerRefresh, options) => {
     }
 };
 const onUnlinkEvent = async (filename, triggerRefresh, options) => {
+    if (watcherGate) {
+        await watcherGate;
+    }
     if (isMintIgnored(filename, getMintIgnoreGlobs())) {
         return;
     }

package/dist/local-preview/on-demand-page.d.ts

@@ -0,0 +1,11 @@
+export declare const markOnDemandPagesReady: () => void;
+export type CompileEvent = {
+    path: string;
+    active: boolean;
+};
+type CompileListener = (event: CompileEvent) => void;
+export declare const setCompileListener: (listener: CompileListener) => void;
+export declare const ensurePageCompiled: (pathname: string, options?: {
+    silent?: boolean;
+}) => Promise<void>;
+export {};

package/dist/local-preview/on-demand-page.js

@@ -0,0 +1,126 @@
+import { findAndRemoveImports, getFileCategory, hasImports, isMintIgnored, stringifyTree, } from '@mintlify/common';
+import { createPage, preparseMdxTree } from '@mintlify/prebuild';
+import { promises as _promises } from 'fs';
+import fse from 'fs-extra';
+import pathUtil from 'path';
+import { CMD_EXEC_PATH, NEXT_PROPS_PATH } from '../constants.js';
+import { startDevTiming } from './dev-timing.js';
+import { getImportedFilesFromCache } from './listener/importCache.js';
+import { upsertPageMetadataCacheEntry } from './listener/page-metadata-cache.js';
+import { resolvePageImports } from './listener/resolve-page-imports.js';
+import { getMintIgnoreGlobs, handleParseError, suppressParseError } from './listener/utils.js';
+const { readFile } = _promises;
+let resolveReady = () => { };
+const ready = new Promise((resolve) => {
+    resolveReady = resolve;
+});
+export const markOnDemandPagesReady = () => {
+    resolveReady();
+};
+let compileListener;
+export const setCompileListener = (listener) => {
+    compileListener = listener;
+};
+const pagePathForFilename = (filename) => {
+    return `/${filename.replace(/\.mdx?$/, '')}`;
+};
+const trackCompile = async (filename, task) => {
+    const path = pagePathForFilename(filename);
+    compileListener?.({ path, active: true });
+    try {
+        return await task();
+    }
+    finally {
+        compileListener?.({ path, active: false });
+    }
+};
+const inflight = new Map();
+const SKIPPED_PREFIXES = ['_next/', '_mintlify/', 'socket.io/', 'favicon'];
+const decodePathname = (pathname) => {
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return pathname;
+    }
+};
+const slugFromPathname = (pathname) => {
+    let slug = decodePathname(pathname).replace(/^\/+/, '').replace(/\/+$/, '');
+    if (slug.startsWith('_markdown/')) {
+        slug = slug.slice('_markdown/'.length);
+    }
+    if (slug === '') {
+        return 'index';
+    }
+    if (slug.includes('\0') ||
+        slug.includes('\\') ||
+        slug.split('/').some((segment) => segment === '..')) {
+        return undefined;
+    }
+    if (SKIPPED_PREFIXES.some((prefix) => slug.startsWith(prefix))) {
+        return undefined;
+    }
+    return slug;
+};
+const candidateFilenames = (slug) => [
+    `${slug}.mdx`,
+    `${slug}.md`,
+    `${slug}/index.mdx`,
+    `${slug}/index.md`,
+];
+const failedCompiles = new Map();
+const compilePage = async (filename, sourcePath, targetPath, sourceMtimeMs) => {
+    const finish = startDevTiming(`compile ${filename}`);
+    try {
+        let contentStr = (await readFile(sourcePath)).toString();
+        const tree = await preparseMdxTree(contentStr, CMD_EXEC_PATH, sourcePath, suppressParseError);
+        const importsResponse = await findAndRemoveImports(tree);
+        if (hasImports(importsResponse)) {
+            contentStr = stringifyTree(await resolvePageImports({ ...importsResponse, filename }));
+        }
+        const { pageContent, pageMetadata, slug } = await createPage(filename, contentStr, CMD_EXEC_PATH, [], [], suppressParseError);
+        await fse.outputFile(targetPath, pageContent, { flag: 'w' });
+        upsertPageMetadataCacheEntry(slug, pageMetadata);
+        failedCompiles.delete(filename);
+        finish();
+    }
+    catch (error) {
+        failedCompiles.set(filename, sourceMtimeMs);
+        handleParseError(`Failed to compile ${filename}: ${error instanceof Error ? error.message : String(error)}`);
+        finish('failed');
+    }
+};
+export const ensurePageCompiled = async (pathname, options = {}) => {
+    const slug = slugFromPathname(pathname);
+    if (slug === undefined) {
+        return;
+    }
+    for (const filename of candidateFilenames(slug)) {
+        const sourcePath = pathUtil.join(CMD_EXEC_PATH, filename);
+        if (!(await fse.pathExists(sourcePath))) {
+            continue;
+        }
+        if (isMintIgnored(filename, getMintIgnoreGlobs())) {
+            continue;
+        }
+        const sourceStat = await fse.stat(sourcePath);
+        const targetPath = pathUtil.join(NEXT_PROPS_PATH, filename);
+        const targetStat = await fse.stat(targetPath).catch(() => undefined);
+        if (targetStat !== undefined && targetStat.mtimeMs >= sourceStat.mtimeMs) {
+            return;
+        }
+        await ready;
+        if (getFileCategory(filename, { importedFiles: getImportedFilesFromCache() }) !== 'page') {
+            continue;
+        }
+        if (failedCompiles.get(filename) === sourceStat.mtimeMs) {
+            continue;
+        }
+        const pending = inflight.get(filename) ??
+            compilePage(filename, sourcePath, targetPath, sourceStat.mtimeMs).finally(() => {
+                inflight.delete(filename);
+            });
+        inflight.set(filename, pending);
+        return options.silent ? pending : trackCompile(filename, () => pending);
+    }
+};

package/dist/local-preview/run.js

@@ -11,6 +11,7 @@ import { addDevTimingLog, startDevTiming, timeDev } from './dev-timing.js';
 import listener, { initializeDocsConfigHashCache, initializeFrontmatterHashCache, initializeImportCache, } from './listener/index.js';
 import { refreshTrackedReferencedFiles } from './listener/referencedFiles.js';
 import { getLocalNetworkIp } from './network.js';
+import { ensurePageCompiled, markOnDemandPagesReady, setCompileListener } from './on-demand-page.js';
 import { setupNext } from './setupNext.js';
 const PROXY_RESPONSE_HEADER_DENYLIST = new Set([
     'connection',
@@ -60,6 +61,16 @@ export const run = async (argv) => {
         process.env.MINTLIFY_CLI_SUBDOMAIN = subdomain;
     // next-server is bugged, public files added after starting aren't served
     app.use('/', express.static(NEXT_PUBLIC_PATH));
+    app.use((req, _res, next) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            next();
+            return;
+        }
+        const silent = req.headers['next-router-prefetch'] !== undefined ||
+            req.headers['purpose'] === 'prefetch' ||
+            req.headers['sec-purpose'] === 'prefetch';
+        ensurePageCompiled(req.path, { silent }).then(() => next(), () => next());
+    });
     app.post('/_mintlify/api-public/search/:subdomain', express.json(), async (req, res) => {
         const targetSubdomain = subdomain ?? req.params.subdomain;
         try {
@@ -121,6 +132,9 @@ export const run = async (argv) => {
     const onChange = () => {
         io.emit('reload');
     };
+    setCompileListener((event) => {
+        io.emit('compiling', event);
+    });
     const finishServerListenTiming = startDevTiming('server ready');
     server.listen(currentPort, () => {
         finishServerListenTiming();
@@ -147,10 +161,18 @@ export const run = async (argv) => {
         process.on('SIGINT', onExit);
         process.on('SIGTERM', onExit);
     });
+    // start watching immediately so edits made during cache initialization are
+    // not lost; handlers wait on the gate until the caches they rely on exist
+    let releaseWatcherGate = () => { };
+    const watcherGate = new Promise((resolve) => {
+        releaseWatcherGate = resolve;
+    });
+    addDevTimingLog('watching for file changes');
+    listener(onChange, {}, watcherGate);
     await timeDev('initialize import cache', () => initializeImportCache(CMD_EXEC_PATH, argv.fileImportsMap));
+    markOnDemandPagesReady();
     await timeDev('initialize frontmatter cache', () => initializeFrontmatterHashCache());
     await timeDev('initialize docs config cache', () => initializeDocsConfigHashCache());
     await timeDev('refresh referenced files', () => refreshTrackedReferencedFiles());
-    addDevTimingLog('watching for file changes');
-    listener(onChange);
+    releaseWatcherGate();
 };