@mintlify/package-builder 0.0.0-stage → 0.0.3

package/dist/render.js

@@ -0,0 +1,292 @@
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const ISLAND_RENDER_TIMEOUT_MS = 3000;
+const MAX_MESSAGE_CHARS = 1024 * 1024;
+const MAX_HTML_CHARS = 16 * 1024 * 1024;
+const MAX_LOG_ENTRIES = 20;
+const MAX_LOG_CHARS = 2000;
+const MAX_DURATION_MS = 60 * 60 * 1000;
+const PASSTHROUGH_ENV = ['PATH', 'SystemRoot', 'TEMP', 'TMP', 'TMPDIR'];
+export function permissionArgs(readable, flags = process.allowedNodeEnvironmentFlags) {
+    const flag = ['--permission', '--experimental-permission'].find((f) => flags.has(f));
+    return flag ? [flag, ...readable.map((path) => `--allow-fs-read=${path}`)] : [];
+}
+export function disabledModuleArgs(flags = process.allowedNodeEnvironmentFlags) {
+    return flags.has('--experimental-sqlite') ? ['--no-experimental-sqlite'] : [];
+}
+export function sandboxAvailable(flags = process.allowedNodeEnvironmentFlags) {
+    return permissionArgs([], flags).length > 0;
+}
+export const ISLAND_RENDER_MEMORY_LIMIT_BYTES = 2 * 1024 * 1024 * 1024;
+const MEMORY_POLL_MS = 100;
+async function residentBytes(pid) {
+    try {
+        const status = await readFile(`/proc/${pid}/status`, 'utf8');
+        const kb = /^VmRSS:\s+(\d+)\s+kB$/m.exec(status)?.[1];
+        return kb === undefined ? undefined : Number(kb) * 1024;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function sandboxArgs(args, probe, platform = process.platform) {
+    return args.length === 0 || platform !== 'win32' || (await probe()) ? args : [];
+}
+function childEnv() {
+    const env = { NODE_ENV: 'production', TZ: 'UTC', NODE_NO_WARNINGS: '1' };
+    for (const key of PASSTHROUGH_ENV)
+        if (process.env[key] !== undefined)
+            env[key] = process.env[key];
+    return env;
+}
+function realOr(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return path;
+    }
+}
+const CHILD_SOURCE = `
+import { writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { pathToFileURL } from 'node:url';
+
+const [serverDir, id, prefix] = process.argv.slice(2);
+const fmt = (args) => args.map((a) => (a instanceof Error ? a.stack || a.message : typeof a === 'string' ? a : (() => { try { return JSON.stringify(a); } catch { return String(a); } })())).join(' ').slice(0, ${MAX_LOG_CHARS});
+const errors = [];
+const warnings = [];
+const log = (list, args) => { if (list.length < ${MAX_LOG_ENTRIES}) list.push(fmt(args)); };
+console.error = (...args) => log(errors, args);
+console.warn = (...args) => log(warnings, args);
+console.log = () => {};
+console.info = () => {};
+console.debug = () => {};
+process.on('uncaughtException', (e) => log(errors, ['Uncaught:', e]));
+process.on('unhandledRejection', (e) => log(errors, ['Unhandled rejection:', e]));
+process.stdin.on('end', () => process.exit(0)).resume();
+const send = (...values) => {
+  const data = Buffer.from(values.map((v) => JSON.stringify(v) + '\\n').join(''));
+  for (let at = 0; at < data.length; ) at += writeSync(3, data, at);
+};
+
+send({ type: 'start', id });
+try {
+  const t0 = performance.now();
+  const mod = await import(pathToFileURL(join(serverDir, 'islands', id + '.mjs')).href);
+  const t1 = performance.now();
+  const html = String(mod.render({ identifierPrefix: prefix }));
+  const t2 = performance.now();
+  send({ type: 'done', id, importMs: t1 - t0, ssrMs: t2 - t1, errors, warnings }, html);
+  let again = null;
+  if (/id\\s*=/i.test(html)) {
+    try {
+      again = String(mod.render({ identifierPrefix: prefix }));
+    } catch {}
+  }
+  send(again);
+} catch (e) {
+  send({ type: 'error', id, error: fmt([e]), errors, warnings });
+}
+`;
+function decode(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function clip(text) {
+    return text.length > MAX_LOG_CHARS ? `${text.slice(0, MAX_LOG_CHARS)}...` : text;
+}
+function strings(value) {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === 'string'))
+        return undefined;
+    return value.slice(0, MAX_LOG_ENTRIES).map(clip);
+}
+function duration(value) {
+    return typeof value === 'number' && value >= 0 && value <= MAX_DURATION_MS;
+}
+function parseResult(msg, id) {
+    if (typeof msg !== 'object' || msg === null)
+        return undefined;
+    const m = msg;
+    const errors = strings(m.errors);
+    const warnings = strings(m.warnings);
+    if (m.id !== id || !errors || !warnings)
+        return undefined;
+    if (m.type === 'done' && duration(m.ssrMs) && duration(m.importMs)) {
+        return { id, ok: true, ssrMs: m.ssrMs, importMs: m.importMs, errors, warnings };
+    }
+    if (m.type === 'error' && typeof m.error === 'string') {
+        return { id, ok: false, error: clip(m.error), errors, warnings };
+    }
+    return undefined;
+}
+function preview(line) {
+    return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+}
+function renderOne(script, serverDir, island, timeoutMs, extraArgs, memoryLimitBytes) {
+    return new Promise((resolvePromise) => {
+        const fail = (error) => ({
+            id: island.id,
+            ok: false,
+            error,
+            errors: [],
+            warnings: [],
+        });
+        let outcome;
+        let started = false;
+        let rendered;
+        let first;
+        let pending = '';
+        let stderr = '';
+        let timer;
+        const child = spawn(process.execPath, ['--max-old-space-size=1024', ...extraArgs, script, serverDir, island.id, island.prefix], {
+            stdio: ['pipe', 'ignore', 'pipe', 'pipe'],
+            env: childEnv(),
+        });
+        const finish = (result) => {
+            outcome ??= result;
+            child.kill('SIGKILL');
+        };
+        const tail = () => stderr.trim().split('\n').slice(-3).join(' ');
+        const deadline = setTimeout(() => child.kill('SIGKILL'), timeoutMs * 3);
+        const memoryPoll = process.platform === 'linux' && child.pid !== undefined
+            ? setInterval(() => {
+                const pid = child.pid;
+                if (pid === undefined)
+                    return;
+                void residentBytes(pid).then((bytes) => {
+                    if (bytes !== undefined && bytes > memoryLimitBytes) {
+                        finish(fail(`Rendering used more than ${Math.round(memoryLimitBytes / 1024 / 1024)} MB of memory`));
+                    }
+                });
+            }, MEMORY_POLL_MS)
+            : undefined;
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString()).slice(-4000);
+        });
+        const unexpected = (line) => fail(`The render process sent an unexpected message: ${preview(line)}`);
+        const limit = () => (rendered ? MAX_HTML_CHARS : MAX_MESSAGE_CHARS);
+        const tooLong = () => first ?? fail(`The render process sent a message over ${limit()} characters`);
+        const receive = (line) => {
+            if (line.length > limit()) {
+                finish(tooLong());
+                return;
+            }
+            if (first) {
+                const second = line.startsWith('"') ? decode(line) : undefined;
+                finish(typeof second === 'string' ? { ...first, second } : first);
+                return;
+            }
+            if (rendered) {
+                const html = line.startsWith('"') ? decode(line) : undefined;
+                if (typeof html === 'string')
+                    first = { ...rendered, html };
+                else
+                    finish(unexpected(line));
+                return;
+            }
+            const msg = decode(line);
+            const m = msg;
+            if (!started && m?.type === 'start' && m.id === island.id) {
+                started = true;
+                timer = setTimeout(() => finish(first ?? fail(`Rendering took longer than ${timeoutMs} ms`)), timeoutMs);
+                return;
+            }
+            const result = started ? parseResult(msg, island.id) : undefined;
+            if (result?.ok)
+                rendered = result;
+            else
+                finish(result ?? unexpected(line));
+        };
+        const channel = child.stdio[3];
+        channel?.setEncoding('utf8');
+        channel?.on('error', () => { });
+        channel?.on('data', (chunk) => {
+            try {
+                let rest = chunk;
+                for (let end = rest.indexOf('\n'); end !== -1 && !outcome; end = rest.indexOf('\n')) {
+                    receive(pending + rest.slice(0, end));
+                    pending = '';
+                    rest = rest.slice(end + 1);
+                }
+                if (outcome)
+                    return;
+                pending += rest;
+                if (pending.length > limit())
+                    finish(tooLong());
+            }
+            catch {
+                finish(fail('The render process sent a message that could not be read'));
+            }
+        });
+        const settle = (result) => {
+            clearTimeout(deadline);
+            if (memoryPoll)
+                clearInterval(memoryPoll);
+            if (timer)
+                clearTimeout(timer);
+            finish(result);
+            resolvePromise(outcome);
+        };
+        child.on('error', (err) => settle(fail(`Could not start the render process: ${err.message}`)));
+        child.on('exit', (code) => settle(first ??
+            fail(started
+                ? `The render process exited with code ${String(code)}: ${tail()}`
+                : `The render process exited before rendering: ${tail()}`)));
+    });
+}
+async function sandboxWorks(script, serverDir, island, timeoutMs) {
+    const probeDir = join(dirname(script), 'probe');
+    const file = join(serverDir, 'islands', `${island.id}.mjs`);
+    await mkdir(join(probeDir, 'islands'), { recursive: true });
+    await writeFile(join(probeDir, 'islands', 'probe.mjs'), `import { readFileSync } from 'node:fs';\nreadFileSync(${JSON.stringify(file)});\nexport const render = () => 'ok';\n`);
+    const outcome = await renderOne(script, probeDir, { id: 'probe', prefix: '' }, timeoutMs, permissionArgs([serverDir, script, probeDir]), ISLAND_RENDER_MEMORY_LIMIT_BYTES);
+    return outcome.ok && outcome.html === 'ok';
+}
+export async function* renderEach(opts) {
+    const [first] = opts.islands;
+    if (!first)
+        return;
+    const timeoutMs = opts.timeoutMs ?? ISLAND_RENDER_TIMEOUT_MS;
+    const work = realOr(await mkdtemp(join(tmpdir(), 'mint-pkg-render-')));
+    const script = join(work, 'render-child.mjs');
+    await writeFile(script, CHILD_SOURCE);
+    const serverDir = realOr(opts.serverDir);
+    try {
+        const sandbox = await sandboxArgs(permissionArgs([serverDir, script]), () => sandboxWorks(script, serverDir, first, timeoutMs), opts.platform);
+        if (opts.requireSandbox && sandbox.length === 0) {
+            for (const island of opts.islands) {
+                yield {
+                    id: island.id,
+                    ok: false,
+                    error: "Node's permission model is not available, so islands are not rendered on the server",
+                    errors: [],
+                    warnings: [],
+                };
+            }
+            return;
+        }
+        const extraArgs = [...sandbox, ...disabledModuleArgs()];
+        const memoryLimitBytes = opts.memoryLimitBytes ?? ISLAND_RENDER_MEMORY_LIMIT_BYTES;
+        for (const island of opts.islands) {
+            yield await renderOne(script, serverDir, island, timeoutMs, extraArgs, memoryLimitBytes);
+        }
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+export async function renderIslands(opts) {
+    const outcomes = [];
+    for await (const outcome of renderEach(opts))
+        outcomes.push(outcome);
+    return outcomes;
+}

package/dist/runtime/client.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentType } from 'react';
+export type HydrateOptions = {
+    props?: unknown;
+    identifierPrefix: string;
+    theme?: 'light' | 'dark';
+};
+export type IslandHandle = {
+    unmount(): void;
+};
+export declare function createHydrate(Island: ComponentType<Record<string, unknown>>, providerModule?: Record<string, unknown>): (el: HTMLElement, opts: HydrateOptions) => IslandHandle;
+export { useMintTheme, useIslandContainer } from './shell.js';

package/dist/runtime/client.js

@@ -0,0 +1,54 @@
+import { createElement } from 'react';
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { IslandShell, resolveProvider } from './shell.js';
+function hasServerHtml(el) {
+    for (let node = el.firstChild; node; node = node.nextSibling) {
+        if (node.nodeType === 1)
+            return true;
+        if (node.nodeType === 3 && (node.textContent ?? '').trim() !== '')
+            return true;
+    }
+    return false;
+}
+function reporter(el) {
+    return (error, phase) => {
+        el.dispatchEvent(new CustomEvent('mint-island-error', { bubbles: true, detail: { error, phase } }));
+        if (phase === 'recoverable')
+            console.warn('[mintlify] island recovered from an error', error);
+    };
+}
+export function createHydrate(Island, providerModule) {
+    const Provider = resolveProvider(providerModule);
+    return function hydrate(el, opts) {
+        if (opts.theme && !el.hasAttribute('data-mint-theme')) {
+            el.setAttribute('data-mint-theme', opts.theme);
+        }
+        const serverHtml = el.innerHTML;
+        const onError = reporter(el);
+        const props = (opts.props ?? {});
+        const tree = createElement(IslandShell, { container: el, serverHtml, Provider, onError }, createElement(Island, props));
+        let root;
+        if (hasServerHtml(el)) {
+            root = hydrateRoot(el, tree, {
+                identifierPrefix: opts.identifierPrefix,
+                onRecoverableError: (error) => onError(error, 'recoverable'),
+            });
+        }
+        else {
+            root = createRoot(el, { identifierPrefix: opts.identifierPrefix });
+            root.render(tree);
+        }
+        el.setAttribute('data-mint-island-hydrated', '');
+        let unmounted = false;
+        return {
+            unmount() {
+                if (unmounted)
+                    return;
+                unmounted = true;
+                root.unmount();
+                el.removeAttribute('data-mint-island-hydrated');
+            },
+        };
+    };
+}
+export { useMintTheme, useIslandContainer } from './shell.js';

package/dist/runtime/server.d.ts

@@ -0,0 +1,6 @@
+import { type ComponentType } from 'react';
+export type RenderOptions = {
+    props?: unknown;
+    identifierPrefix: string;
+};
+export declare function createRender(Island: ComponentType<Record<string, unknown>>, providerModule?: Record<string, unknown>): (opts: RenderOptions) => string;

package/dist/runtime/server.js

@@ -0,0 +1,11 @@
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+import { IslandShell, resolveProvider } from './shell.js';
+export function createRender(Island, providerModule) {
+    const Provider = resolveProvider(providerModule);
+    return function render(opts) {
+        const props = (opts.props ?? {});
+        const tree = createElement(IslandShell, { container: null, serverHtml: '', Provider }, createElement(Island, props));
+        return renderToString(tree, { identifierPrefix: opts.identifierPrefix });
+    };
+}

package/dist/runtime/shell.d.ts

@@ -0,0 +1,21 @@
+import { type ComponentType, type ReactNode } from 'react';
+export type MintTheme = 'light' | 'dark';
+type IslandContextValue = {
+    container: HTMLElement | null;
+};
+export declare function useMintTheme(): MintTheme;
+export declare function useIslandContainer(): HTMLElement | null;
+export type IslandErrorReporter = (error: unknown, phase: 'render' | 'recoverable') => void;
+export type ProviderComponent = ComponentType<{
+    children?: ReactNode;
+}>;
+export type IslandShellProps = {
+    container: HTMLElement | null;
+    serverHtml: string;
+    Provider?: ProviderComponent;
+    onError?: IslandErrorReporter;
+    children?: ReactNode;
+};
+export declare function IslandShell({ container, serverHtml, Provider, onError, children, }: IslandShellProps): import("react").FunctionComponentElement<import("react").ProviderProps<IslandContextValue>>;
+export declare function resolveProvider(mod: Record<string, unknown> | undefined): ProviderComponent | undefined;
+export {};

package/dist/runtime/shell.js

@@ -0,0 +1,68 @@
+import { Component, createContext, createElement, useCallback, useContext, useMemo, useSyncExternalStore, } from 'react';
+const IslandContext = createContext({ container: null });
+const SERVER_THEME = 'light';
+function readTheme(container) {
+    if (typeof document === 'undefined')
+        return SERVER_THEME;
+    const island = container ? (container.closest('[data-mint-island]') ?? container) : null;
+    const attr = island?.getAttribute('data-mint-theme') ??
+        document.documentElement.getAttribute('data-mint-theme');
+    if (attr === 'dark' || attr === 'light')
+        return attr;
+    return document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+}
+export function useMintTheme() {
+    const { container } = useContext(IslandContext);
+    const subscribe = useCallback((onChange) => {
+        if (typeof MutationObserver === 'undefined' || typeof document === 'undefined') {
+            return () => { };
+        }
+        const observer = new MutationObserver(onChange);
+        const options = { attributes: true, attributeFilter: ['data-mint-theme', 'class'] };
+        observer.observe(document.documentElement, options);
+        const island = container ? (container.closest('[data-mint-island]') ?? container) : null;
+        if (island && island !== document.documentElement)
+            observer.observe(island, options);
+        return () => observer.disconnect();
+    }, [container]);
+    const getSnapshot = useCallback(() => readTheme(container), [container]);
+    return useSyncExternalStore(subscribe, getSnapshot, () => SERVER_THEME);
+}
+export function useIslandContainer() {
+    return useContext(IslandContext).container;
+}
+class IslandErrorBoundary extends Component {
+    constructor() {
+        super(...arguments);
+        this.state = { failed: false };
+    }
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error, _info) {
+        this.props.onError?.(error, 'render');
+    }
+    render() {
+        if (this.state.failed) {
+            return createElement('div', {
+                'data-mint-island-fallback': '',
+                style: { display: 'contents' },
+                dangerouslySetInnerHTML: { __html: this.props.serverHtml },
+            });
+        }
+        return this.props.children;
+    }
+}
+export function IslandShell({ container, serverHtml, Provider, onError, children, }) {
+    const value = useMemo(() => ({ container }), [container]);
+    const content = Provider ? createElement(Provider, null, children) : children;
+    return createElement(IslandContext.Provider, { value }, createElement(IslandErrorBoundary, { serverHtml, onError }, content));
+}
+export function resolveProvider(mod) {
+    if (!mod)
+        return undefined;
+    const candidate = mod.Provider ?? mod.default;
+    return typeof candidate === 'function' || (typeof candidate === 'object' && candidate !== null)
+        ? candidate
+        : undefined;
+}

package/dist/runtime/theme.d.ts

@@ -0,0 +1 @@
+export { useMintTheme, useIslandContainer, type MintTheme } from './shell.js';

package/dist/runtime/theme.js

@@ -0,0 +1 @@
+export { useMintTheme, useIslandContainer } from './shell.js';

package/dist/sanitize.d.ts

@@ -0,0 +1,9 @@
+export declare const MAX_ISLAND_HTML_BYTES: number;
+export declare function decodeEntities(value: string): string;
+export declare function sanitizeHtml(input: string, prefix?: string, renames?: ReadonlyMap<string, string>): string;
+export declare function stateIdRenames(first: string, second: string | undefined, prefix: string): Map<string, string>;
+export declare function sanitizeIslandHtml(input: string, prefix?: string, renames?: ReadonlyMap<string, string>): {
+    html?: string;
+    tooLarge: boolean;
+    bytes: number;
+};