@mintlify/previewing 4.0.1321 → 4.0.1323

package/dist/__tests__/constants.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/constants.test.js

@@ -0,0 +1,30 @@
+import path from 'path';
+import * as constants from '../constants.js';
+describe('configurePreviewPath', () => {
+    afterEach(() => {
+        constants.configureSharedPreviewPath();
+    });
+    it('keeps non-dev commands outside port workspaces', () => {
+        constants.configureSharedPreviewPath();
+        expect(constants.PREVIEW_PATH).toBe(path.join(constants.DOT_MINTLIFY, 'previews', 'shared'));
+    });
+    it('isolates preview files by port', () => {
+        constants.configurePreviewPath(3000);
+        const defaultPreviewPath = constants.PREVIEW_PATH;
+        constants.configurePreviewPath(3001);
+        expect(constants.PREVIEW_PATH).not.toBe(defaultPreviewPath);
+        expect(constants.PREVIEW_PATH).toBe(path.join(constants.DOT_MINTLIFY, 'previews', '3001'));
+        expect(constants.MINT_PATH).toBe(path.join(constants.PREVIEW_PATH, 'mint'));
+        expect(constants.CLIENT_PATH).toBe(path.join(constants.MINT_PATH, 'apps', 'client'));
+        expect(constants.TAR_PATH).toBe(path.join(constants.PREVIEW_PATH, 'mint.tar.gz'));
+    });
+    it('returns to the same files for a reused port', () => {
+        constants.configurePreviewPath(4000);
+        const firstPath = constants.PREVIEW_PATH;
+        constants.configurePreviewPath('4000');
+        expect(constants.PREVIEW_PATH).toBe(firstPath);
+    });
+    it.each([0, 65536, 'not-a-port'])('rejects an invalid port: %s', (port) => {
+        expect(() => constants.configurePreviewPath(port)).toThrow(`invalid preview port: ${port}`);
+    });
+});

package/dist/__tests__/dev.test.js

@@ -6,6 +6,7 @@ import { dev } from '../index.js';
 import { run } from '../local-preview/run.js';
 import { silentUpdateClient } from '../local-preview/update.js';
 import * as logs from '../logging-state.js';
+import { seedPreviewFromShared } from '../util.js';
 const originalChdir = process.chdir;
 vi.mock('fs-extra', () => {
     const mocks = {
@@ -23,6 +24,9 @@ vi.mock('fs-extra', () => {
 vi.mock('../local-preview/update.js', () => ({
     silentUpdateClient: vi.fn().mockResolvedValue({ needsUpdate: false, error: undefined }),
 }));
+vi.mock('../local-preview/preview-lock.js', () => ({
+    acquirePreviewLock: vi.fn().mockReturnValue(vi.fn()),
+}));
 vi.mock('is-online', () => ({
     default: vi.fn().mockResolvedValue(true),
 }));
@@ -35,11 +39,13 @@ vi.mock('../local-preview/run.js', () => ({
 vi.mock('../util.js', () => {
     return {
         maybeFixMissingWindowsEnvVar: vi.fn(),
+        seedPreviewFromShared: vi.fn(),
     };
 });
 const prebuildMock = vi.mocked(prebuild);
 const runMock = vi.mocked(run);
 const silentUpdateClientMock = vi.mocked(silentUpdateClient);
+const seedPreviewFromSharedMock = vi.mocked(seedPreviewFromShared);
 const defaultYargs = {
     _: [],
     $0: '',
@@ -59,10 +65,16 @@ describe('dev', () => {
     it('happy path', async () => {
         await dev(defaultYargs);
         expect(addLogSpy).toHaveBeenCalledWith(expect.objectContaining({ props: { message: 'preparing local preview...' } }));
+        expect(seedPreviewFromSharedMock).toHaveBeenCalled();
         expect(silentUpdateClientMock).toHaveBeenCalled();
         expect(prebuildMock).toHaveBeenCalled();
         expect(runMock).toHaveBeenCalled();
     });
+    it('does not seed from shared when a specific client version is requested', async () => {
+        await dev({ ...defaultYargs, 'client-version': '1.2.3' });
+        expect(seedPreviewFromSharedMock).not.toHaveBeenCalled();
+        expect(silentUpdateClientMock).toHaveBeenCalled();
+    });
     it('prebuild fails', async () => {
         const errorText = 'Some OpenAPI or docs.json schema error';
         prebuildMock.mockRejectedValueOnce(new Error(errorText));

package/dist/__tests__/downloadTargetMint.test.js

@@ -64,18 +64,18 @@ describe('downloadTargetMint', () => {
             existingVersion: versionString,
         });
         // Verify backup was created
-        expect(existsSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
-        expect(moveSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY, constants.DOT_MINTLIFY_LAST, {
+        expect(existsSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH);
+        expect(moveSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH, constants.PREVIEW_LAST_PATH, {
             overwrite: true,
         });
-        expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
+        expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.PREVIEW_PATH);
         // Verify download and extraction
         expect(getTarUrlMock).toHaveBeenCalledWith(targetMintVersion);
         expect(pipelineMock).toHaveBeenCalled();
         expect(tarMock.x).toHaveBeenCalled();
         // Verify cleanup
         expect(removeSyncMock).toHaveBeenCalledWith(constants.TAR_PATH);
-        expect(removeSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY_LAST);
+        expect(removeSyncMock).toHaveBeenCalledWith(constants.PREVIEW_LAST_PATH);
         expect(writeFileSyncMock).toHaveBeenCalledWith(constants.VERSION_PATH, targetMintVersion);
         // Verify no restore was needed
         expect(restoreMintlifyLastMock).not.toHaveBeenCalled();
@@ -89,18 +89,18 @@ describe('downloadTargetMint', () => {
             existingVersion: versionString,
         });
         // Verify backup was created
-        expect(existsSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
-        expect(moveSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY, constants.DOT_MINTLIFY_LAST, {
+        expect(existsSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH);
+        expect(moveSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH, constants.PREVIEW_LAST_PATH, {
             overwrite: true,
         });
-        expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
+        expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.PREVIEW_PATH);
         // Verify download and extraction
         expect(getTarUrlMock).toHaveBeenCalledWith(clientVersion);
         expect(pipelineMock).toHaveBeenCalled();
         expect(tarMock.x).toHaveBeenCalled();
         // Verify cleanup
         expect(removeSyncMock).toHaveBeenCalledWith(constants.TAR_PATH);
-        expect(removeSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY_LAST);
+        expect(removeSyncMock).toHaveBeenCalledWith(constants.PREVIEW_LAST_PATH);
         expect(writeFileSyncMock).toHaveBeenCalledWith(constants.VERSION_PATH, clientVersion);
         // Verify no restore was needed
         expect(restoreMintlifyLastMock).not.toHaveBeenCalled();
@@ -120,11 +120,11 @@ describe('downloadTargetMint', () => {
                 existingVersion: versionString,
             });
             // Verify backup was created
-            expect(existsSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
-            expect(moveSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY, constants.DOT_MINTLIFY_LAST, {
+            expect(existsSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH);
+            expect(moveSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH, constants.PREVIEW_LAST_PATH, {
                 overwrite: true,
             });
-            expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
+            expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.PREVIEW_PATH);
             // Verify use backup version
             expect(restoreMintlifyLastMock).toHaveBeenCalled();
             // Verify no extraction
@@ -147,11 +147,11 @@ describe('downloadTargetMint', () => {
                 existingVersion: versionString,
             });
             // Verify backup was created
-            expect(existsSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
-            expect(moveSyncMock).toHaveBeenCalledWith(constants.DOT_MINTLIFY, constants.DOT_MINTLIFY_LAST, {
+            expect(existsSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH);
+            expect(moveSyncMock).toHaveBeenCalledWith(constants.PREVIEW_PATH, constants.PREVIEW_LAST_PATH, {
                 overwrite: true,
             });
-            expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.DOT_MINTLIFY);
+            expect(fse.ensureDirSync).toHaveBeenCalledWith(constants.PREVIEW_PATH);
             // Verify download success
             expect(pipelineMock).toHaveBeenCalled();
             // Verify use backup version

package/dist/__tests__/preview-lock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/preview-lock.test.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { acquirePreviewLock } from '../local-preview/preview-lock.js';
+describe('acquirePreviewLock', () => {
+    let locksDirectory;
+    beforeEach(() => {
+        locksDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'mint-preview-locks-'));
+    });
+    afterEach(() => {
+        fs.rmSync(locksDirectory, { recursive: true, force: true });
+    });
+    it('prevents two preview instances from mutating the same port workspace', () => {
+        const release = acquirePreviewLock(3000, locksDirectory);
+        expect(() => acquirePreviewLock(3000, locksDirectory)).toThrow('local preview on port 3000 is already starting or running');
+        release();
+    });
+    it('allows the workspace to be reused after release', () => {
+        acquirePreviewLock(3000, locksDirectory)();
+        const release = acquirePreviewLock(3000, locksDirectory);
+        expect(fs.existsSync(path.join(locksDirectory, '3000.lock'))).toBe(true);
+        release();
+    });
+    it('recovers a stale lock', () => {
+        fs.writeFileSync(path.join(locksDirectory, '3000.lock'), JSON.stringify({ pid: -1, token: 'stale' }));
+        const release = acquirePreviewLock(3000, locksDirectory);
+        expect(fs.existsSync(path.join(locksDirectory, '3000.lock'))).toBe(true);
+        release();
+    });
+});

package/dist/__tests__/seedPreviewFromShared.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/seedPreviewFromShared.test.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { seedPreviewFromShared } from '../util.js';
+describe('seedPreviewFromShared', () => {
+    let tempDir;
+    let sharedMintPath;
+    let mintPath;
+    let versionPath;
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mint-seed-preview-'));
+        sharedMintPath = path.join(tempDir, 'shared', 'mint');
+        mintPath = path.join(tempDir, '3000', 'mint');
+        versionPath = path.join(mintPath, 'mint-version.txt');
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    const writeClient = (clientPath, version, extraFile) => {
+        fs.mkdirSync(clientPath, { recursive: true });
+        fs.writeFileSync(path.join(clientPath, 'mint-version.txt'), version);
+        if (extraFile) {
+            fs.writeFileSync(path.join(clientPath, extraFile), extraFile);
+        }
+    };
+    it('does nothing when the current workspace is the shared workspace', () => {
+        writeClient(sharedMintPath, '2.0.0');
+        seedPreviewFromShared({
+            sharedMintPath,
+            mintPath: sharedMintPath,
+            versionPath: path.join(sharedMintPath, 'mint-version.txt'),
+        });
+        expect(fs.readdirSync(path.join(tempDir, 'shared'))).toEqual(['mint']);
+        expect(fs.existsSync(mintPath)).toBe(false);
+    });
+    it('does nothing when the shared workspace has no client', () => {
+        seedPreviewFromShared({ sharedMintPath, mintPath, versionPath });
+        expect(fs.existsSync(mintPath)).toBe(false);
+    });
+    it('does nothing when the port workspace already has the shared version', () => {
+        writeClient(sharedMintPath, '2.0.0', 'shared-only.txt');
+        writeClient(mintPath, '2.0.0', 'port-only.txt');
+        seedPreviewFromShared({ sharedMintPath, mintPath, versionPath });
+        expect(fs.existsSync(path.join(mintPath, 'port-only.txt'))).toBe(true);
+        expect(fs.existsSync(path.join(mintPath, 'shared-only.txt'))).toBe(false);
+    });
+    it('copies the shared client when the port workspace is empty', () => {
+        writeClient(sharedMintPath, '2.0.0', 'client.txt');
+        seedPreviewFromShared({ sharedMintPath, mintPath, versionPath });
+        expect(fs.readFileSync(versionPath, 'utf8')).toBe('2.0.0');
+        expect(fs.readFileSync(path.join(mintPath, 'client.txt'), 'utf8')).toBe('client.txt');
+    });
+    it('replaces a stale port workspace with the shared client', () => {
+        writeClient(sharedMintPath, '2.0.0', 'new-client.txt');
+        writeClient(mintPath, '1.0.0', 'old-client.txt');
+        seedPreviewFromShared({ sharedMintPath, mintPath, versionPath });
+        expect(fs.readFileSync(versionPath, 'utf8')).toBe('2.0.0');
+        expect(fs.existsSync(path.join(mintPath, 'new-client.txt'))).toBe(true);
+        expect(fs.existsSync(path.join(mintPath, 'old-client.txt'))).toBe(false);
+    });
+    it('does not overwrite a newer port client with an older shared client', () => {
+        writeClient(sharedMintPath, '2.0.0', 'shared-only.txt');
+        writeClient(mintPath, '3.0.0', 'port-only.txt');
+        seedPreviewFromShared({ sharedMintPath, mintPath, versionPath });
+        expect(fs.readFileSync(versionPath, 'utf8')).toBe('3.0.0');
+        expect(fs.existsSync(path.join(mintPath, 'port-only.txt'))).toBe(true);
+        expect(fs.existsSync(path.join(mintPath, 'shared-only.txt'))).toBe(false);
+    });
+});

package/dist/constants.d.ts

@@ -1,19 +1,22 @@
 export declare const INSTALL_PATH: string;
 export declare const HOME_DIR: string;
 export declare const DOT_MINTLIFY: string;
-export declare const DOT_MINTLIFY_LAST: string;
-export declare const MINT_PATH: string;
-export declare const VERSION_PATH: string;
-export declare const CLIENT_PATH: string;
-export declare const NEXT_SIDE_EFFECT_PATH: string;
-export declare const NEXT_ROUTER_SERVER_PATH: string;
-export declare const NEXT_CONFIG_PATH: string;
-export declare const NEXT_PUBLIC_PATH: string;
-export declare const NEXT_PROPS_PATH: string;
+export declare let PREVIEW_PATH: string;
+export declare let PREVIEW_LAST_PATH: string;
+export declare let MINT_PATH: string;
+export declare let VERSION_PATH: string;
+export declare let CLIENT_PATH: string;
+export declare let NEXT_SIDE_EFFECT_PATH: string;
+export declare let NEXT_ROUTER_SERVER_PATH: string;
+export declare let NEXT_CONFIG_PATH: string;
+export declare let NEXT_PUBLIC_PATH: string;
+export declare let NEXT_PROPS_PATH: string;
+export declare let TAR_PATH: string;
+export declare const configurePreviewPath: (port?: string | number) => void;
+export declare const configureSharedPreviewPath: () => void;
 export declare const MINT_CLIENT_RELEASES_CLOUDFRONT_URL = "https://releases.mintlify.com";
 export declare const TARGET_MINT_VERSION_URL = "https://releases.mintlify.com/mint-version.txt";
 export declare const MINT_VERSION_MAP_URL = "https://releases.mintlify.com/mint-version-map.json";
-export declare const TAR_PATH: string;
 export declare const CMD_EXEC_PATH: string;
 export declare const SUPPORTED_MEDIA_EXTENSIONS: string[];
 export declare const LOCAL_LINKED_CLI_VERSION = "linked to local package";

package/dist/constants.js

@@ -5,20 +5,47 @@ import * as url from 'url';
 export const INSTALL_PATH = url.fileURLToPath(new URL('.', import.meta.url));
 export const HOME_DIR = os.homedir();
 export const DOT_MINTLIFY = path.join(HOME_DIR, '.mintlify');
-export const DOT_MINTLIFY_LAST = path.join(HOME_DIR, '.mintlify-last');
-export const MINT_PATH = path.join(DOT_MINTLIFY, 'mint');
-export const VERSION_PATH = path.join(MINT_PATH, 'mint-version.txt');
-export const CLIENT_PATH = path.join(MINT_PATH, 'apps', 'client');
-const NEXT_DIST_SERVER_PATH = path.join(MINT_PATH, 'node_modules', 'next', 'dist', 'server');
-export const NEXT_SIDE_EFFECT_PATH = path.join(NEXT_DIST_SERVER_PATH, 'next.js');
-export const NEXT_ROUTER_SERVER_PATH = path.join(NEXT_DIST_SERVER_PATH, 'lib', 'router-server.js');
-export const NEXT_CONFIG_PATH = path.join(CLIENT_PATH, '.next', 'required-server-files.json');
-export const NEXT_PUBLIC_PATH = path.join(CLIENT_PATH, 'public');
-export const NEXT_PROPS_PATH = path.join(CLIENT_PATH, 'src', '_props');
+export let PREVIEW_PATH;
+export let PREVIEW_LAST_PATH;
+export let MINT_PATH;
+export let VERSION_PATH;
+export let CLIENT_PATH;
+export let NEXT_SIDE_EFFECT_PATH;
+export let NEXT_ROUTER_SERVER_PATH;
+export let NEXT_CONFIG_PATH;
+export let NEXT_PUBLIC_PATH;
+export let NEXT_PROPS_PATH;
+export let TAR_PATH;
+const setPreviewPath = (name) => {
+    PREVIEW_PATH = path.join(DOT_MINTLIFY, 'previews', name);
+    PREVIEW_LAST_PATH = `${PREVIEW_PATH}-last`;
+    MINT_PATH = path.join(PREVIEW_PATH, 'mint');
+    VERSION_PATH = path.join(MINT_PATH, 'mint-version.txt');
+    CLIENT_PATH = path.join(MINT_PATH, 'apps', 'client');
+    const nextDistServerPath = path.join(MINT_PATH, 'node_modules', 'next', 'dist', 'server');
+    NEXT_SIDE_EFFECT_PATH = path.join(nextDistServerPath, 'next.js');
+    NEXT_ROUTER_SERVER_PATH = path.join(nextDistServerPath, 'lib', 'router-server.js');
+    NEXT_CONFIG_PATH = path.join(CLIENT_PATH, '.next', 'required-server-files.json');
+    NEXT_PUBLIC_PATH = path.join(CLIENT_PATH, 'public');
+    NEXT_PROPS_PATH = path.join(CLIENT_PATH, 'src', '_props');
+    TAR_PATH = path.join(PREVIEW_PATH, 'mint.tar.gz');
+};
+// A port can only belong to one local server at a time, so it gives each running
+// preview an isolated workspace while still allowing warm starts to reuse files.
+export const configurePreviewPath = (port = 3000) => {
+    const numericPort = Number(port);
+    if (!Number.isInteger(numericPort) || numericPort < 1 || numericPort > 65535) {
+        throw new Error(`invalid preview port: ${port}`);
+    }
+    setPreviewPath(String(numericPort));
+};
+export const configureSharedPreviewPath = () => {
+    setPreviewPath('shared');
+};
+configureSharedPreviewPath();
 export const MINT_CLIENT_RELEASES_CLOUDFRONT_URL = 'https://releases.mintlify.com';
 export const TARGET_MINT_VERSION_URL = `${MINT_CLIENT_RELEASES_CLOUDFRONT_URL}/mint-version.txt`;
 export const MINT_VERSION_MAP_URL = `${MINT_CLIENT_RELEASES_CLOUDFRONT_URL}/mint-version-map.json`;
-export const TAR_PATH = path.join(DOT_MINTLIFY, `mint.tar.gz`);
 // command execution location
 export const CMD_EXEC_PATH = process.cwd();
 export const SUPPORTED_MEDIA_EXTENSIONS = [

package/dist/local-preview/client.js

@@ -4,7 +4,7 @@ import isOnline from 'is-online';
 import yaml from 'js-yaml';
 import { pipeline } from 'node:stream/promises';
 import * as tar from 'tar';
-import { DOT_MINTLIFY, DOT_MINTLIFY_LAST, VERSION_PATH, TAR_PATH, TARGET_MINT_VERSION_URL, MINT_VERSION_MAP_URL, } from '../constants.js';
+import { PREVIEW_PATH, PREVIEW_LAST_PATH, VERSION_PATH, TAR_PATH, TARGET_MINT_VERSION_URL, MINT_VERSION_MAP_URL, } from '../constants.js';
 import { restoreMintlifyLast, getTarUrl } from '../util.js';
 export const getLatestClientVersion = async () => {
     const hasInternet = await isOnline();
@@ -20,10 +20,10 @@ export const getLatestClientVersion = async () => {
     }
 };
 export const downloadTargetMint = async ({ targetVersion, existingVersion, }) => {
-    if (fse.existsSync(DOT_MINTLIFY)) {
-        fse.moveSync(DOT_MINTLIFY, DOT_MINTLIFY_LAST, { overwrite: true });
+    if (fse.existsSync(PREVIEW_PATH)) {
+        fse.moveSync(PREVIEW_PATH, PREVIEW_LAST_PATH, { overwrite: true });
     }
-    fse.ensureDirSync(DOT_MINTLIFY);
+    fse.ensureDirSync(PREVIEW_PATH);
     const tarUrl = getTarUrl(targetVersion);
     let currentVersion = targetVersion.trim();
     try {
@@ -43,7 +43,7 @@ export const downloadTargetMint = async ({ targetVersion, existingVersion, }) =>
         tar.x({
             sync: true,
             file: TAR_PATH,
-            cwd: DOT_MINTLIFY,
+            cwd: PREVIEW_PATH,
             onwarn: (_code, message) => {
                 throw new Error(message);
             },
@@ -60,8 +60,8 @@ export const downloadTargetMint = async ({ targetVersion, existingVersion, }) =>
         }
     }
     fse.removeSync(TAR_PATH);
-    if (fse.existsSync(DOT_MINTLIFY_LAST)) {
-        fse.removeSync(DOT_MINTLIFY_LAST);
+    if (fse.existsSync(PREVIEW_LAST_PATH)) {
+        fse.removeSync(PREVIEW_LAST_PATH);
     }
     fse.writeFileSync(VERSION_PATH, currentVersion);
 };

package/dist/local-preview/export.js

@@ -9,7 +9,7 @@ import isOnline from 'is-online';
 import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { CLIENT_PATH, DOT_MINTLIFY, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, } from '../constants.js';
+import { CLIENT_PATH, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, PREVIEW_PATH, configureSharedPreviewPath, } from '../constants.js';
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog, SuccessLog } from '../logs.js';
 import { getGroupFilteredRoutes } from './getGroupFilteredRoutes.js';
@@ -194,13 +194,14 @@ async function generateExportArchive(routes, outputPath, groups) {
     }
 }
 export const exportSite = async (argv) => {
+    configureSharedPreviewPath();
     const hasInternet = await isOnline();
     const clientVersion = argv['client-version'];
     const groups = argv.groups;
     const cliVersion = argv.cliVersion;
     const disableOpenApi = argv.disableOpenapi;
     const outputPath = path.resolve(argv.output);
-    await fse.ensureDir(DOT_MINTLIFY);
+    await fse.ensureDir(PREVIEW_PATH);
     const versionString = (await pathExists(VERSION_PATH))
         ? fse.readFileSync(VERSION_PATH, 'utf8')
         : null;

package/dist/local-preview/index.js

@@ -3,10 +3,12 @@ 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 { CLIENT_PATH, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, PREVIEW_PATH, configurePreviewPath, } from '../constants.js';
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog } from '../logs.js';
+import { seedPreviewFromShared } from '../util.js';
 import { timeDev, timeDevSync } from './dev-timing.js';
+import { acquirePreviewLock } from './preview-lock.js';
 import { run } from './run.js';
 import { silentUpdateClient } from './update.js';
 const PRUNE_EXEMPT_PREFIXES = ['favicons/', '.mint-content-source'];
@@ -27,7 +29,7 @@ const prunePublicOrphans = () => {
         }
     }
 };
-const dev = async (argv) => {
+const startDev = async (argv) => {
     const hasInternet = await timeDev('check internet', () => isOnline());
     const localSchema = argv['local-schema'];
     const clientVersion = argv['client-version'];
@@ -37,7 +39,10 @@ const dev = async (argv) => {
     const cliVersion = argv.cliVersion;
     const disableOpenApi = argv.disableOpenapi;
     const disablePrefetch = argv.disablePrefetch;
-    await timeDev('ensure .mintlify directory', () => fse.ensureDir(DOT_MINTLIFY));
+    await timeDev('ensure preview directory', () => fse.ensureDir(PREVIEW_PATH));
+    if (!localClientVersion && !clientVersion) {
+        timeDevSync('seed preview from shared workspace', () => seedPreviewFromShared());
+    }
     const versionString = await timeDev('read local client version', async () => {
         return (await pathExists(VERSION_PATH)) ? fse.readFileSync(VERSION_PATH, 'utf8') : null;
     });
@@ -104,4 +109,16 @@ const dev = async (argv) => {
     }
     await timeDev('start preview runtime', () => run({ ...argv, needsUpdate, fileImportsMap }));
 };
+const dev = async (argv) => {
+    const port = Number(argv.port ?? 3000);
+    configurePreviewPath(port);
+    const releasePreviewLock = acquirePreviewLock(port);
+    try {
+        await startDev(argv);
+    }
+    catch (error) {
+        releasePreviewLock();
+        throw error;
+    }
+};
 export default dev;

package/dist/local-preview/preview-lock.d.ts

@@ -0,0 +1 @@
+export declare const acquirePreviewLock: (port: number, locksDirectory?: string) => (() => void);

package/dist/local-preview/preview-lock.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DOT_MINTLIFY } from '../constants.js';
+const isNodeError = (error, code) => error instanceof Error && 'code' in error && error.code === code;
+const readLockOwner = (lockPath) => {
+    try {
+        const owner = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        if (Number.isInteger(owner.pid) && owner.pid > 0 && typeof owner.token === 'string') {
+            return owner;
+        }
+    }
+    catch { }
+    return undefined;
+};
+const isProcessRunning = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNodeError(error, 'ESRCH');
+    }
+};
+export const acquirePreviewLock = (port, locksDirectory = path.join(DOT_MINTLIFY, 'preview-locks')) => {
+    fs.mkdirSync(locksDirectory, { recursive: true });
+    const lockPath = path.join(locksDirectory, `${port}.lock`);
+    const token = `${process.pid}-${randomUUID()}`;
+    const candidatePath = path.join(locksDirectory, `.${port}-${token}.candidate`);
+    fs.writeFileSync(candidatePath, JSON.stringify({ pid: process.pid, token }), { flag: 'wx' });
+    let acquired = false;
+    try {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                fs.linkSync(candidatePath, lockPath);
+                acquired = true;
+                break;
+            }
+            catch (error) {
+                if (!isNodeError(error, 'EEXIST'))
+                    throw error;
+                const owner = readLockOwner(lockPath);
+                if (owner && isProcessRunning(owner.pid)) {
+                    throw new Error(`local preview on port ${port} is already starting or running`);
+                }
+                const stalePath = `${lockPath}.stale-${token}`;
+                try {
+                    fs.renameSync(lockPath, stalePath);
+                    fs.rmSync(stalePath, { force: true });
+                }
+                catch (renameError) {
+                    if (!isNodeError(renameError, 'ENOENT'))
+                        throw renameError;
+                }
+            }
+        }
+    }
+    finally {
+        fs.rmSync(candidatePath, { force: true });
+    }
+    if (!acquired) {
+        throw new Error(`could not acquire local preview workspace for port ${port}`);
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.off('exit', release);
+        if (readLockOwner(lockPath)?.token === token) {
+            fs.rmSync(lockPath, { force: true });
+        }
+    };
+    process.once('exit', release);
+    return release;
+};

package/dist/local-preview/update.js

@@ -2,11 +2,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { spawn } from 'child_process';
 import fse from 'fs-extra';
 import path from 'path';
-import { LOCAL_LINKED_CLI_VERSION, MINT_PATH, DOT_MINTLIFY, CLIENT_PATH } from '../constants.js';
+import { LOCAL_LINKED_CLI_VERSION, MINT_PATH, PREVIEW_PATH, CLIENT_PATH } from '../constants.js';
 import { clearLogs, addLog } from '../logging-state.js';
 import { SpinnerLog } from '../logs.js';
 import { getLatestClientVersion, tryDownloadTargetMint, getCompatibleClientVersion, } from './client.js';
-const MINT_BACKUP_PATH = path.join(DOT_MINTLIFY, 'mint-backup');
+const getMintBackupPath = () => path.join(PREVIEW_PATH, 'mint-backup');
 const isCurrentlySymlinked = async () => {
     if (!(await fse.pathExists(MINT_PATH)))
         return false;
@@ -47,11 +47,12 @@ const buildClient = async () => {
 };
 const restoreFromBackup = async () => {
     try {
+        const mintBackupPath = getMintBackupPath();
         if (await isCurrentlySymlinked()) {
             await fse.remove(MINT_PATH);
         }
-        if (await fse.pathExists(MINT_BACKUP_PATH)) {
-            await fse.move(MINT_BACKUP_PATH, MINT_PATH);
+        if (await fse.pathExists(mintBackupPath)) {
+            await fse.move(mintBackupPath, MINT_PATH);
         }
         return undefined;
     }
@@ -61,6 +62,7 @@ const restoreFromBackup = async () => {
 };
 const symlinkLocalClient = async (targetPath) => {
     try {
+        const mintBackupPath = getMintBackupPath();
         const resolvedPath = path.resolve(targetPath);
         if (!(await fse.pathExists(resolvedPath))) {
             return `Path does not exist: ${resolvedPath}`;
@@ -75,10 +77,10 @@ const symlinkLocalClient = async (targetPath) => {
                 await fse.remove(MINT_PATH);
             }
             else {
-                if (await fse.pathExists(MINT_BACKUP_PATH)) {
-                    await fse.remove(MINT_BACKUP_PATH);
+                if (await fse.pathExists(mintBackupPath)) {
+                    await fse.remove(mintBackupPath);
                 }
-                await fse.move(MINT_PATH, MINT_BACKUP_PATH);
+                await fse.move(MINT_PATH, mintBackupPath);
             }
         }
         await fse.ensureDir(path.dirname(MINT_PATH));

package/dist/local-preview/validate-build.js

@@ -2,12 +2,13 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { prebuild } from '@mintlify/prebuild';
 import fse, { pathExists } from 'fs-extra';
 import isOnline from 'is-online';
-import { CLIENT_PATH, DOT_MINTLIFY, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, } from '../constants.js';
+import { CLIENT_PATH, CMD_EXEC_PATH, VERSION_PATH, NEXT_PUBLIC_PATH, NEXT_PROPS_PATH, PREVIEW_PATH, configureSharedPreviewPath, } from '../constants.js';
 import { addLog, clearLogs } from '../logging-state.js';
 import { ErrorLog, SpinnerLog, SuccessLog } from '../logs.js';
 import { timeDev, timeDevSync } from './dev-timing.js';
 import { silentUpdateClient } from './update.js';
 const validateBuild = async (argv) => {
+    configureSharedPreviewPath();
     const hasInternet = await timeDev('check internet', () => isOnline());
     const localSchema = argv['local-schema'];
     const clientVersion = argv['client-version'];
@@ -15,7 +16,7 @@ const validateBuild = async (argv) => {
     const groups = argv.groups;
     const cliVersion = argv.cliVersion;
     const disableOpenApi = argv.disableOpenapi;
-    await timeDev('ensure .mintlify directory', () => fse.ensureDir(DOT_MINTLIFY));
+    await timeDev('ensure preview directory', () => fse.ensureDir(PREVIEW_PATH));
     const versionString = await timeDev('read local client version', async () => {
         return (await pathExists(VERSION_PATH)) ? fse.readFileSync(VERSION_PATH, 'utf8') : null;
     });