@veryfront/ext-content-mdx 0.1.985

package/esm/src/platform/adapters/base.d.ts

@@ -0,0 +1,188 @@
+/***********************
+ * Runtime identifier for platform-specific code paths
+ ***********************/
+export type RuntimeId = "deno" | "node" | "bun" | "cloudflare" | "memory";
+/**
+ * Core runtime adapter interface
+ *
+ * Provides a unified abstraction over runtime-specific APIs (Deno, Node.js, Bun, Cloudflare Workers).
+ * All platform-specific code should go through this adapter to ensure cross-platform compatibility.
+ */
+export interface RuntimeAdapter {
+    /** Unique identifier for this runtime */
+    readonly id: RuntimeId;
+    /** Human-readable name for logging */
+    readonly name: string;
+    /** Runtime capabilities for feature detection */
+    readonly capabilities: RuntimeCapabilities;
+    /** Filesystem operations */
+    fs: FileSystemAdapter;
+    /** Environment variable access */
+    env: EnvironmentAdapter;
+    /** HTTP server operations */
+    server: ServerAdapter;
+    serve(handler: (request: Request) => Promise<Response> | Response, options: ServeOptions): Promise<Server>;
+    /** Shell operations (sync fs for CLI) */
+    shell?: ShellAdapter;
+    /** Key-value store (Cloudflare KV, Deno KV) */
+    kv?: KVStoreAdapter;
+    /** File watcher (not available on Workers) */
+    watcher?: FileWatcherAdapter;
+    /** Initialize the adapter (called once before first use) */
+    initialize?(): Promise<void>;
+    /** Clean shutdown (close connections, etc.) */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Runtime capabilities for feature detection
+ */
+export interface RuntimeCapabilities {
+    /** Native TypeScript support without compilation */
+    typescript: boolean;
+    /** Native JSX/TSX support */
+    jsx: boolean;
+    /** HTTP/2 server support */
+    http2: boolean;
+    /** WebSocket support */
+    websocket: boolean;
+    /** Web Workers / Worker threads support */
+    workers: boolean;
+    /** File system watching */
+    fileWatching: boolean;
+    /** Shell command execution */
+    shell: boolean;
+    /** Key-value store available */
+    kvStore: boolean;
+    /** Writable filesystem (false for Workers without KV) */
+    writableFs: boolean;
+}
+export interface ServerAdapter {
+    upgradeWebSocket(request: Request): WebSocketUpgrade;
+}
+export interface WebSocketConnection {
+    readonly readyState: number;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: EventListener, options?: AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListener): void;
+}
+declare const WEBSOCKET_UPGRADE_RESPONSE_KIND = "websocket-upgrade";
+export interface WebSocketUpgradeResponse {
+    readonly kind: typeof WEBSOCKET_UPGRADE_RESPONSE_KIND;
+    readonly status: 101;
+    readonly statusText: string;
+    readonly headers: Headers;
+    readonly body: null;
+}
+export interface WebSocketUpgrade {
+    socket: WebSocketConnection;
+    response: Response | WebSocketUpgradeResponse;
+}
+export declare function createWebSocketUpgradeResponse(input?: {
+    headers?: HeadersInit;
+    statusText?: string;
+}): WebSocketUpgradeResponse;
+export declare function isWebSocketUpgradeResponse(value: unknown): value is WebSocketUpgradeResponse;
+export interface ServeOptions {
+    port?: number;
+    hostname?: string;
+    signal?: AbortSignal;
+    onListen?: (params: {
+        hostname: string;
+        port: number;
+    }) => void;
+}
+export interface Server {
+    stop(): Promise<void>;
+    addr: {
+        hostname: string;
+        port: number;
+    };
+}
+export interface FileSystemAdapter {
+    readFile(path: string): Promise<string>;
+    /** Read raw bytes when binary-safe access is required */
+    readFileBytes?(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): AsyncIterable<DirEntry>;
+    stat(path: string): Promise<FileInfo>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    makeTempDir(prefix: string): Promise<string>;
+    watch(paths: string | string[], options?: WatchOptions): FileWatcher;
+    /** Resolve a file path with extension fallback (e.g., pages/test → pages/test.mdx) */
+    resolveFile?(basePath: string, options?: ResolveFileOptions): Promise<string | null>;
+    /** Refresh remote source snapshots when a preview render detects stale cached content. */
+    refreshSourceSnapshot?(reason?: string): Promise<void>;
+}
+export interface ResolveFileOptions {
+    allowPagesPrefix?: boolean;
+}
+export interface DirEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+}
+export interface FileInfo {
+    size: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    mtime: Date | null;
+}
+export interface EnvironmentAdapter {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    toObject(): Record<string, string>;
+}
+export interface WatchOptions {
+    recursive?: boolean;
+    signal?: AbortSignal;
+}
+export type FileChangeKind = "create" | "modify" | "delete" | "any";
+export interface FileChangeEvent {
+    kind: FileChangeKind;
+    paths: string[];
+}
+export interface FileWatcher extends AsyncIterable<FileChangeEvent> {
+    close(): void;
+    /**
+     * Resolves once the watcher's internal loop has fully stopped, including
+     * any in-flight filesystem operations. close() only signals shutdown;
+     * await this to guarantee no pending async ops remain (e.g. before test
+     * sanitizer checks or process exit).
+     */
+    done?: Promise<void>;
+}
+export interface ShellAdapter {
+    statSync(path: string): {
+        isFile: boolean;
+        isDirectory: boolean;
+    };
+    readFileSync(path: string): string;
+}
+/**
+ * Key-value store adapter for Cloudflare KV, Deno KV, etc.
+ */
+export interface KVStoreAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): AsyncIterable<string>;
+}
+/**
+ * File watcher adapter for development mode
+ */
+export interface FileWatcherAdapter {
+    watch(paths: string | string[], options?: WatchOptions): FileWatcher;
+}
+export {};
+//# sourceMappingURL=base.d.ts.map

package/esm/src/platform/adapters/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/base.ts"],"names":[],"mappings":"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"}

package/esm/src/platform/adapters/base.js

@@ -0,0 +1,15 @@
+const WEBSOCKET_UPGRADE_RESPONSE_KIND = "websocket-upgrade";
+export function createWebSocketUpgradeResponse(input = {}) {
+    return {
+        kind: WEBSOCKET_UPGRADE_RESPONSE_KIND,
+        status: 101,
+        statusText: input.statusText ?? "Switching Protocols",
+        headers: new Headers(input.headers),
+        body: null,
+    };
+}
+export function isWebSocketUpgradeResponse(value) {
+    return typeof value === "object" && value !== null &&
+        value.kind === WEBSOCKET_UPGRADE_RESPONSE_KIND &&
+        value.status === 101;
+}

package/esm/src/platform/compat/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Platform-level constants that don't depend on configuration.
+ * These are simple values used by HTTP servers and adapters.
+ *
+ * Note: config/defaults.ts re-exports DEFAULT_PORT for higher layers.
+ */
+export declare const DEFAULT_PORT = 3000;
+export declare const LOCALHOST: {
+    readonly IPV4: "127.0.0.1";
+    readonly IPV6: "::1";
+    readonly HOSTNAME: "localhost";
+};
+//# sourceMappingURL=constants.d.ts.map

package/esm/src/platform/compat/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,eAAO,MAAM,SAAS;;;;CAIZ,CAAC"}

package/esm/src/platform/compat/constants.js

@@ -0,0 +1,12 @@
+/**
+ * Platform-level constants that don't depend on configuration.
+ * These are simple values used by HTTP servers and adapters.
+ *
+ * Note: config/defaults.ts re-exports DEFAULT_PORT for higher layers.
+ */
+export const DEFAULT_PORT = 3000;
+export const LOCALHOST = {
+    IPV4: "127.0.0.1",
+    IPV6: "::1",
+    HOSTNAME: "localhost",
+};

package/esm/src/platform/compat/dynamic-import.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Opaque dynamic import helper.
+ *
+ * Uses `new Function` to hide the `import()` call from static analysis
+ * by bundlers and `deno compile`, preventing them from tracing into
+ * the imported specifier.
+ *
+ * @module platform/compat
+ */
+export declare const dynamicImport: <T = unknown>(specifier: string) => Promise<T>;
+//# sourceMappingURL=dynamic-import.d.ts.map

package/esm/src/platform/compat/dynamic-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/dynamic-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,aAAa,EAA4D,CACpF,CAAC,GAAG,OAAO,EAEX,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/esm/src/platform/compat/dynamic-import.js

@@ -0,0 +1,10 @@
+/**
+ * Opaque dynamic import helper.
+ *
+ * Uses `new Function` to hide the `import()` call from static analysis
+ * by bundlers and `deno compile`, preventing them from tracing into
+ * the imported specifier.
+ *
+ * @module platform/compat
+ */
+export const dynamicImport = new Function("specifier", "return import(specifier)");

package/esm/src/platform/compat/fs.d.ts

@@ -0,0 +1,71 @@
+import type { FileInfo } from "../adapters/base.js";
+/** Public API contract for file system. */
+export interface FileSystem {
+    readTextFile(path: string): Promise<string>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeTextFile(path: string, data: string): Promise<void>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileInfo>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readDir(path: string): AsyncIterable<{
+        name: string;
+        isFile: boolean;
+        isDirectory: boolean;
+    }>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    makeTempDir(options?: {
+        prefix?: string;
+    }): Promise<string>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+/** Create file system. */
+export declare function createFileSystem(): FileSystem;
+/** Read a file as text. */
+export declare function readTextFile(path: string): Promise<string>;
+/** Read a file as bytes. */
+export declare function readFile(path: string): Promise<Uint8Array>;
+/** Write text to a file. */
+export declare function writeTextFile(path: string, data: string): Promise<void>;
+/** Write bytes to a file. */
+export declare function writeFile(path: string, data: Uint8Array): Promise<void>;
+/** Check whether a path exists. */
+export declare function exists(path: string): Promise<boolean>;
+/** Read file metadata. */
+export declare function stat(path: string): Promise<FileInfo>;
+/** Create a directory. */
+export declare function mkdir(path: string, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+/** Remove a file or directory. */
+export declare function remove(path: string, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+/** Read directory entries. */
+export declare function readDir(path: string): AsyncIterable<{
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+}>;
+/** Create temp dir. */
+export declare function makeTempDir(options?: {
+    prefix?: string;
+}): Promise<string>;
+/** Change file permissions. */
+export declare function chmod(path: string, mode: number): Promise<void>;
+export declare function symlink(target: string, path: string): Promise<void>;
+/**
+ * Resolve a path to its canonical absolute form, following symlinks.
+ * Throws if the path does not exist. Useful for containment checks where a
+ * symlink could otherwise escape an intended directory.
+ */
+export declare function realPath(path: string): Promise<string>;
+/** Error shape for is not found. */
+export declare function isNotFoundError(error: unknown): boolean;
+/** Error shape for is already exists. */
+export declare function isAlreadyExistsError(error: unknown): boolean;
+//# sourceMappingURL=fs.d.ts.map

package/esm/src/platform/compat/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/compat/fs.ts"],"names":[],"mappings":"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"}

package/esm/src/platform/compat/fs.js

@@ -0,0 +1,277 @@
+import * as dntShim from "../../../_dnt.shims.js";
+import { createError, toError } from "../../errors/veryfront-error.js";
+import { isBun, isDeno, isNode } from "./runtime.js";
+/**
+ * Typed accessor for the Deno global.
+ *
+ * This is pure typing only — it reads no environment variables and performs no
+ * side effects, so this module stays importable without `--allow-env`. It
+ * exists to retire the `@ts-ignore` comments that were previously required to
+ * access `Deno.*` APIs from runtime-agnostic compat code.
+ */
+function denoGlobal() {
+    return dntShim.dntGlobalThis.Deno;
+}
+class NodeFileSystem {
+    fs;
+    os;
+    path;
+    initialized = false;
+    async ensureInitialized() {
+        if (this.initialized)
+            return;
+        if (!isNode && !isBun) {
+            throw toError(createError({
+                type: "not_supported",
+                message: "Node.js fs modules not available",
+                feature: "Node.js",
+            }));
+        }
+        const [fsModule, osModule, pathModule] = await Promise.all([
+            import("node:fs/promises"),
+            import("node:os"),
+            import("node:path"),
+        ]);
+        this.fs = fsModule;
+        this.os = osModule;
+        this.path = pathModule;
+        this.initialized = true;
+    }
+    getFs() {
+        if (!this.fs)
+            throw new Error("NodeFileSystem not initialized");
+        return this.fs;
+    }
+    getOs() {
+        if (!this.os)
+            throw new Error("NodeFileSystem not initialized");
+        return this.os;
+    }
+    getPath() {
+        if (!this.path)
+            throw new Error("NodeFileSystem not initialized");
+        return this.path;
+    }
+    async readTextFile(path) {
+        await this.ensureInitialized();
+        return this.getFs().readFile(path, { encoding: "utf8" });
+    }
+    async readFile(path) {
+        await this.ensureInitialized();
+        return this.getFs().readFile(path);
+    }
+    async writeTextFile(path, data) {
+        await this.ensureInitialized();
+        await this.getFs().writeFile(path, data, { encoding: "utf8" });
+    }
+    async writeFile(path, data) {
+        await this.ensureInitialized();
+        await this.getFs().writeFile(path, data);
+    }
+    async exists(path) {
+        await this.ensureInitialized();
+        try {
+            await this.getFs().access(path);
+            return true;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    async stat(path) {
+        await this.ensureInitialized();
+        const stat = await this.getFs().stat(path);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            mtime: stat.mtime,
+        };
+    }
+    async mkdir(path, options) {
+        await this.ensureInitialized();
+        await this.getFs().mkdir(path, { recursive: options?.recursive ?? false });
+    }
+    async *readDir(path) {
+        await this.ensureInitialized();
+        const entries = await this.getFs().readdir(path, { withFileTypes: true });
+        for (const entry of entries) {
+            yield { name: entry.name, isFile: entry.isFile(), isDirectory: entry.isDirectory() };
+        }
+    }
+    async remove(path, options) {
+        await this.ensureInitialized();
+        const recursive = options?.recursive ?? false;
+        await this.getFs().rm(path, { recursive, force: recursive });
+    }
+    async makeTempDir(options) {
+        await this.ensureInitialized();
+        const tempDir = this.getPath().join(this.getOs().tmpdir(), `${options?.prefix ?? "tmp-"}${dntShim.crypto.randomUUID().slice(0, 8)}`);
+        await this.getFs().mkdir(tempDir, { recursive: true });
+        return tempDir;
+    }
+    async chmod(path, mode) {
+        await this.ensureInitialized();
+        try {
+            await this.getFs().chmod(path, mode);
+        }
+        catch {
+            // Ignore errors on Windows where chmod is not fully supported.
+            // Intentionally not logged: this low-level compat module must stay
+            // importable without `--allow-env` (the logger reads env at import).
+        }
+    }
+}
+class DenoFileSystem {
+    readTextFile(path) {
+        return denoGlobal().readTextFile(path);
+    }
+    readFile(path) {
+        return denoGlobal().readFile(path);
+    }
+    async writeTextFile(path, data) {
+        await denoGlobal().writeTextFile(path, data);
+    }
+    async writeFile(path, data) {
+        await denoGlobal().writeFile(path, data);
+    }
+    async exists(path) {
+        try {
+            await denoGlobal().stat(path);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof denoGlobal().errors.NotFound)
+                return false;
+            throw error;
+        }
+    }
+    async stat(path) {
+        const stat = await denoGlobal().stat(path);
+        return {
+            isFile: stat.isFile,
+            isDirectory: stat.isDirectory,
+            isSymlink: stat.isSymlink,
+            size: stat.size,
+            mtime: stat.mtime,
+        };
+    }
+    async mkdir(path, options) {
+        await denoGlobal().mkdir(path, { recursive: options?.recursive ?? false });
+    }
+    async *readDir(path) {
+        for await (const entry of denoGlobal().readDir(path)) {
+            yield { name: entry.name, isFile: entry.isFile, isDirectory: entry.isDirectory };
+        }
+    }
+    async remove(path, options) {
+        await denoGlobal().remove(path, { recursive: options?.recursive ?? false });
+    }
+    makeTempDir(options) {
+        return denoGlobal().makeTempDir({ prefix: options?.prefix });
+    }
+    async chmod(path, mode) {
+        try {
+            await denoGlobal().chmod(path, mode);
+        }
+        catch (_) {
+            /* expected: chmod is not fully supported on Windows */
+        }
+    }
+}
+/** Create file system. */
+export function createFileSystem() {
+    return isDeno ? new DenoFileSystem() : new NodeFileSystem();
+}
+let _fs = null;
+function getFs() {
+    _fs ??= createFileSystem();
+    return _fs;
+}
+/** Read a file as text. */
+export function readTextFile(path) {
+    return getFs().readTextFile(path);
+}
+/** Read a file as bytes. */
+export function readFile(path) {
+    return getFs().readFile(path);
+}
+/** Write text to a file. */
+export function writeTextFile(path, data) {
+    return getFs().writeTextFile(path, data);
+}
+/** Write bytes to a file. */
+export function writeFile(path, data) {
+    return getFs().writeFile(path, data);
+}
+/** Check whether a path exists. */
+export function exists(path) {
+    return getFs().exists(path);
+}
+/** Read file metadata. */
+export function stat(path) {
+    return getFs().stat(path);
+}
+/** Create a directory. */
+export function mkdir(path, options) {
+    return getFs().mkdir(path, options);
+}
+/** Remove a file or directory. */
+export function remove(path, options) {
+    return getFs().remove(path, options);
+}
+/** Read directory entries. */
+export function readDir(path) {
+    return getFs().readDir(path);
+}
+/** Create temp dir. */
+export function makeTempDir(options) {
+    return getFs().makeTempDir(options);
+}
+/** Change file permissions. */
+export function chmod(path, mode) {
+    return getFs().chmod(path, mode);
+}
+export async function symlink(target, path) {
+    if (isDeno) {
+        await denoGlobal().symlink(target, path);
+        return;
+    }
+    const fs = await import("node:fs/promises");
+    await fs.symlink(target, path);
+}
+/**
+ * Resolve a path to its canonical absolute form, following symlinks.
+ * Throws if the path does not exist. Useful for containment checks where a
+ * symlink could otherwise escape an intended directory.
+ */
+export async function realPath(path) {
+    if (isDeno) {
+        return await denoGlobal().realPath(path);
+    }
+    const fs = await import("node:fs/promises");
+    return await fs.realpath(path);
+}
+/** Error shape for is not found. */
+export function isNotFoundError(error) {
+    const NotFound = dntShim.dntGlobalThis.Deno?.errors?.NotFound;
+    if (isDeno && NotFound && error instanceof NotFound)
+        return true;
+    if (error?.code === "ENOENT")
+        return true;
+    if (error instanceof Error && error.name === "VeryfrontError" &&
+        error.slug === "file-not-found") {
+        return true;
+    }
+    return false;
+}
+/** Error shape for is already exists. */
+export function isAlreadyExistsError(error) {
+    const AlreadyExists = dntShim.dntGlobalThis.Deno?.errors?.AlreadyExists;
+    if (isDeno && AlreadyExists && error instanceof AlreadyExists)
+        return true;
+    return error?.code === "EEXIST";
+}

package/esm/src/platform/compat/path/basic-operations.d.ts

@@ -0,0 +1,9 @@
+/** Join path segments. */
+export declare function join(...paths: string[]): string;
+/** Return the parent directory path. */
+export declare function dirname(path: string): string;
+/** Return the last path segment. */
+export declare function basename(path: string, ext?: string): string;
+/** Return the file extension for a path. */
+export declare function extname(path: string): string;
+//# sourceMappingURL=basic-operations.d.ts.map

package/esm/src/platform/compat/path/basic-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic-operations.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/compat/path/basic-operations.ts"],"names":[],"mappings":"AAWA,0BAA0B;AAC1B,wBAAgB,IAAI,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAS/C;AAED,wCAAwC;AACxC,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,oCAAoC;AACpC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5C"}