@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/compiler/ops.js

@@ -0,0 +1,362 @@
+// Write operations on the docs root (create / move / rename / delete docs and save body text;
+// add / remove figures). Shared by the viewer's edit API, the CLI (doc / figure) and MCP.
+// Failures are returned as { error, status } (status is HTTP-like) with no partial updates.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { flattenTree, insertDoc, isDocId, moveDoc, removeDoc, renameDoc, } from "../core/content-metadata.js";
+import { defaultFilePath, docIconFile, isDocumentFileName, parseFileLayout, } from "../core/files.js";
+import { parseDocLink } from "../core/routing.js";
+import { collectDocLinks, compileSite } from "./compile.js";
+import { figureName, figureUploadName } from "./figures.js";
+import { projectFiles, rewriteFileLinks } from "./files.js";
+import { translationFile, translationFiles, translationLanguages } from "./locales.js";
+import { docFile, readManifest, writeManifest } from "./manifest.js";
+import { assembleDoc } from "./serialize.js";
+import { textfilePath } from "./textfile.js";
+export const isOpError = (r) => typeof r === "object" && r != null && "error" in r;
+export { assembleDoc } from "./serialize.js";
+export const createDocOps = (root) => {
+    const figuresDir = join(root, "figures");
+    const docPath = (id) => textfilePath(root, docFile(id, readManifest(root).files));
+    const iconPath = (id) => textfilePath(root, docIconFile(id, readManifest(root).files));
+    // Read before rewriting dooc.yaml. If it's broken, don't write (= don't clobber
+    // hand-written content).
+    const loadTree = () => {
+        const manifest = readManifest(root);
+        return manifest.errors.length > 0
+            ? { error: manifest.errors.join(" / "), status: 409 }
+            : manifest;
+    };
+    const existingDoc = (id) => typeof id === "string" && isDocId(id) && existsSync(docPath(id))
+        ? { id }
+        : { error: `doc "${String(id)}" not found`, status: 404 };
+    // Include extracted callout sources and unregistered Markdown files in reference checks.
+    const referenceFiles = () => [...projectFiles(root).map((file) => file.path), ...translationFiles(root)].filter((file) => /\.(md|callouth)$/.test(file));
+    const referencingFiles = (id, removed) => {
+        const target = docFile(id, readManifest(root).files);
+        return referenceFiles()
+            .filter((file) => !removed.includes(file) &&
+            collectDocLinks(readFileSync(textfilePath(root, file), "utf8")).some((url) => parseDocLink(url)?.file === target))
+            .map((file) => file.replace(/^content\//, ""));
+    };
+    /** Creates a document and appends it as the last child of parent. */
+    const add = (id, title, parent, filename) => {
+        if (!title) {
+            return { error: "title is required", status: 400 };
+        }
+        if (!isDocId(id)) {
+            return { error: "id must be lowercase alphanumerics and hyphens", status: 400 };
+        }
+        if (filename !== undefined && !isDocumentFileName(filename))
+            return { error: "Enter a file name ending in .md", status: 400 };
+        if (existsSync(docPath(id))) {
+            return { error: `id "${id}" is already in use`, status: 409 };
+        }
+        const loaded = loadTree();
+        if (isOpError(loaded)) {
+            return loaded;
+        }
+        const tree = insertDoc(loaded.tree, id, parent);
+        if (!tree) {
+            return { error: `duplicate id "${id}" or missing parent "${parent}"`, status: 409 };
+        }
+        if (filename !== undefined || loaded.files?.defaultLayout !== false) {
+            loaded.files ??= parseFileLayout({});
+            loaded.files.documents[id] = loaded.files.defaultLayout
+                ? defaultFilePath(filename ?? `${id}.md`)
+                : `content/${filename}`;
+        }
+        const file = textfilePath(root, docFile(id, loaded.files));
+        if (existsSync(file))
+            return { error: "File already exists", status: 409 };
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, assembleDoc({ title }, ""), { flag: "wx" });
+        writeManifest(root, tree, loaded);
+        return { id };
+    };
+    const addFile = (name, title, parent) => {
+        if (!isDocumentFileName(name))
+            return { error: "Enter a file name ending in .md", status: 400 };
+        const loaded = loadTree();
+        if (isOpError(loaded))
+            return loaded;
+        const ids = new Set(flattenTree(loaded.tree).map((doc) => doc.id));
+        const stem = name
+            .slice(0, -3)
+            .normalize("NFKD")
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "") || "doc";
+        let id = stem;
+        for (let index = 2; ids.has(id) || existsSync(docPath(id)); index++)
+            id = `${stem}-${index}`;
+        return add(id, title, parent, name);
+    };
+    /**
+     * Reorders and reparents. Rewrites only dooc.yaml. Omitted index = after the last child
+     * of parent.
+     */
+    const move = (id, parent, index) => {
+        const loaded = loadTree();
+        if (isOpError(loaded)) {
+            return loaded;
+        }
+        const at = index ??
+            flattenTree(loaded.tree).filter((n) => n.parent === parent && n.id !== id).length;
+        const tree = moveDoc(loaded.tree, id, parent, at);
+        if (!tree) {
+            return {
+                error: "cannot move to that position (under its own descendant / unknown doc / index out of range)",
+                status: 409,
+            };
+        }
+        writeManifest(root, tree, loaded);
+        return { id };
+    };
+    /**
+     * Renames content/<old>.md and updates the manifest id and the file links (exact match) in
+     * every doc's body text to follow.
+     */
+    const rename = (oldId, newId) => {
+        const target = existingDoc(oldId);
+        if (isOpError(target)) {
+            return target;
+        }
+        if (newId === "" || newId === oldId) {
+            return { id: oldId, updatedRefs: 0 };
+        }
+        if (!isDocId(newId)) {
+            return { error: "id must be a slug (lowercase alphanumerics, hyphens)", status: 400 };
+        }
+        if (existsSync(docPath(newId))) {
+            return { error: `id "${newId}" is already in use`, status: 409 };
+        }
+        const loaded = loadTree();
+        if (isOpError(loaded)) {
+            return loaded;
+        }
+        const tree = renameDoc(loaded.tree, oldId, newId);
+        if (!tree) {
+            return { error: "doc is not in dooc.yaml", status: 404 };
+        }
+        const oldFile = docFile(oldId, loaded.files);
+        const mapped = loaded.files && Object.hasOwn(loaded.files.documents, oldId);
+        const newFile = mapped ? oldFile : docFile(newId, loaded.files);
+        const moves = new Map(oldFile === newFile ? [] : [[oldFile, newFile]]);
+        try {
+            for (const language of translationLanguages(root)) {
+                const from = translationFile(oldFile, language);
+                const to = translationFile(newFile, language);
+                if (from === to)
+                    continue;
+                if (existsSync(textfilePath(root, to)))
+                    return { error: `translation file "${to}" already exists`, status: 409 };
+                if (existsSync(textfilePath(root, from)))
+                    moves.set(from, to);
+            }
+        }
+        catch (error) {
+            return { error: String(error), status: 409 };
+        }
+        const writes = [];
+        let updatedRefs = 0;
+        // Validate every rewrite before renaming files or changing the manifest.
+        try {
+            for (const file of referenceFiles()) {
+                const raw = readFileSync(textfilePath(root, file), "utf8");
+                const body = rewriteFileLinks(raw, moves);
+                if (body !== raw) {
+                    writes.push({ file: moves.get(file) ?? file, body });
+                    updatedRefs++;
+                }
+            }
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error), status: 409 };
+        }
+        if (loaded.files && Object.hasOwn(loaded.files.documents, oldId)) {
+            loaded.files.documents[newId] = docFile(oldId, loaded.files);
+            delete loaded.files.documents[oldId];
+        }
+        else
+            renameSync(docPath(oldId), docPath(newId));
+        if (loaded.files?.icons && Object.hasOwn(loaded.files.icons, oldId)) {
+            loaded.files.icons[newId] = docIconFile(oldId, loaded.files);
+            delete loaded.files.icons[oldId];
+        }
+        else if (existsSync(iconPath(oldId)))
+            renameSync(iconPath(oldId), iconPath(newId));
+        for (const [from, to] of moves) {
+            if (from === oldFile)
+                continue;
+            const path = textfilePath(root, to);
+            mkdirSync(dirname(path), { recursive: true });
+            renameSync(textfilePath(root, from), path);
+        }
+        writeManifest(root, tree, loaded);
+        for (const { file, body } of writes)
+            writeFileSync(textfilePath(root, file), body);
+        return { id: newId, updatedRefs };
+    };
+    /**
+     * Removes the doc from the manifest and deletes the .md (and icon). Docs with children are
+     * not deleted. If other docs reference it via file links, refuses without force and returns
+     * referencedBy. parent = the deleted doc's parent.
+     */
+    const remove = (id, force = false) => {
+        const target = existingDoc(id);
+        if (isOpError(target)) {
+            return target;
+        }
+        const loaded = loadTree();
+        if (isOpError(loaded)) {
+            return loaded;
+        }
+        const tree = removeDoc(loaded.tree, id);
+        if (!tree) {
+            return { error: "doc has children (move / delete them first)", status: 409 };
+        }
+        const file = docFile(id, loaded.files);
+        let removed;
+        let referencedBy;
+        try {
+            removed = [
+                file,
+                ...translationLanguages(root).map((lang) => translationFile(file, lang)),
+            ];
+            for (const file of removed)
+                textfilePath(root, file);
+            referencedBy = referencingFiles(id, removed);
+        }
+        catch (error) {
+            return { error: String(error), status: 409 };
+        }
+        if (referencedBy.length > 0 && !force) {
+            return {
+                error: `${referencedBy.length} doc(s) reference it via file links`,
+                status: 409,
+                referencedBy,
+            };
+        }
+        const parent = flattenTree(loaded.tree).find((n) => n.id === id)?.parent;
+        const removedPath = docPath(id);
+        const removedIcon = iconPath(id);
+        if (loaded.files) {
+            delete loaded.files.documents[id];
+            if (loaded.files.icons)
+                delete loaded.files.icons[id];
+            loaded.files.order = loaded.files.order.filter((file) => join(root, file) !== removedPath);
+        }
+        writeManifest(root, tree, loaded);
+        unlinkSync(removedPath);
+        if (existsSync(removedIcon)) {
+            unlinkSync(removedIcon);
+        }
+        for (const file of removed.slice(1)) {
+            const path = textfilePath(root, file);
+            if (existsSync(path))
+                unlinkSync(path);
+        }
+        return { parent, danglingRefs: referencedBy.length };
+    };
+    /** Overwrites an existing doc's full raw text (including front-matter). */
+    const write = (id, raw) => {
+        const target = existingDoc(id);
+        if (isOpError(target)) {
+            return target;
+        }
+        writeFileSync(docPath(id), raw.endsWith("\n") ? raw : `${raw}\n`);
+        return { id };
+    };
+    /**
+     * Writes a figure to figures/. file = the original file name (its extension decides the
+     * kind). A figure name is shared across extensions, so if the same stem already exists,
+     * -2, -3… is appended (if the same name with the same content exists, returns it without
+     * writing).
+     */
+    const addFigure = (file, data) => {
+        const upload = figureUploadName(file);
+        if (!upload) {
+            return { error: "specify an svg / png / webp / jpeg / html file", status: 400 };
+        }
+        if (data.length === 0 ||
+            (upload.endsWith(".svg") && !data.toString("utf8").includes("<svg"))) {
+            return { error: `${upload} has invalid content`, status: 400 };
+        }
+        const manifest = loadTree();
+        if (isOpError(manifest))
+            return manifest;
+        if (manifest.files?.defaultLayout !== false) {
+            const initial = defaultFilePath(upload);
+            let path = initial;
+            const ext = upload.slice(figureName(upload).length);
+            for (let i = 2; existsSync(textfilePath(root, path)); i++) {
+                if (readFileSync(textfilePath(root, path)).equals(data))
+                    return { file: path.split("/").pop(), path };
+                path = `${initial.slice(0, -ext.length)}-${i}${ext}`;
+            }
+            const target = textfilePath(root, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, data, { flag: "wx" });
+            return { file: path.split("/").pop(), path };
+        }
+        mkdirSync(figuresDir, { recursive: true });
+        const taken = new Map(readdirSync(figuresDir).map((f) => [figureName(f), f]));
+        const ext = upload.slice(figureName(upload).length);
+        let name = figureName(upload);
+        for (let i = 2; taken.has(name); i += 1) {
+            const existing = taken.get(name);
+            if (existing === `${name}${ext}` &&
+                readFileSync(join(figuresDir, existing)).equals(data)) {
+                return { file: existing };
+            }
+            name = `${figureName(upload)}-${i}`;
+        }
+        writeFileSync(join(figuresDir, `${name}${ext}`), data);
+        return { file: `${name}${ext}` };
+    };
+    /** Files in figures/ (figure name → file). */
+    const figureFiles = () => new Map(compileSite(root).figures.map((f) => [
+        f.name,
+        f.file.startsWith("figures/") ? f.file.slice(8) : f.file,
+    ]));
+    /**
+     * Deletes a figure. If a doc references it via a Markdown link or embed, refuses without force and returns
+     * referencedBy.
+     */
+    const removeFigure = (name, force = false) => {
+        const file = figureFiles().get(name);
+        if (!file) {
+            return { error: `figure "${name}" not found`, status: 404 };
+        }
+        const referencedBy = [
+            ...new Set([undefined, ...translationLanguages(root)].flatMap((locale) => compileSite(root, { locale, defaultLang: "und" })
+                .docs.filter((d) => d.refs.figures.includes(name))
+                .map((d) => d.id))),
+        ];
+        if (referencedBy.length > 0 && !force) {
+            return {
+                error: `${referencedBy.length} doc(s) reference it`,
+                status: 409,
+                referencedBy,
+            };
+        }
+        unlinkSync(textfilePath(root, file.includes("/") ? file : `figures/${file}`));
+        return { file };
+    };
+    return {
+        contentDir: join(root, "content"),
+        figuresDir,
+        loadTree,
+        referencingFiles,
+        figureFiles,
+        add,
+        addFile,
+        move,
+        rename,
+        remove,
+        write,
+        addFigure,
+        removeFigure,
+    };
+};

package/dist/compiler/public-file.d.ts

@@ -0,0 +1,2 @@
+/** Self-contained: the synchronous compiler also runs this function in a bounded child process. */
+export declare function fetchPublicFile(source: string, contentType?: (type: string) => void): Promise<Buffer>;

package/dist/compiler/public-file.js

@@ -0,0 +1,93 @@
+/** Self-contained: the synchronous compiler also runs this function in a bounded child process. */
+export async function fetchPublicFile(source, contentType) {
+    const { request } = await import("node:https");
+    const { lookup } = await import("node:dns/promises");
+    const { BlockList, isIP } = await import("node:net");
+    const url = new URL(source);
+    if (url.protocol !== "https:" || url.username || url.password || url.port)
+        throw new Error("BLOCKED");
+    const blocked = new BlockList();
+    for (const [address, prefix] of [
+        ["0.0.0.0", 8],
+        ["10.0.0.0", 8],
+        ["100.64.0.0", 10],
+        ["127.0.0.0", 8],
+        ["169.254.0.0", 16],
+        ["172.16.0.0", 12],
+        ["192.0.0.0", 24],
+        ["192.0.2.0", 24],
+        ["192.88.99.0", 24],
+        ["192.168.0.0", 16],
+        ["198.18.0.0", 15],
+        ["198.51.100.0", 24],
+        ["203.0.113.0", 24],
+        ["224.0.0.0", 3],
+    ])
+        blocked.addSubnet(address, prefix, "ipv4");
+    const globalV6 = new BlockList();
+    globalV6.addSubnet("2000::", 3, "ipv6");
+    for (const [address, prefix] of [
+        ["2001::", 23],
+        ["2001:db8::", 32],
+        ["2002::", 16],
+        ["3fff::", 20],
+    ])
+        blocked.addSubnet(address, prefix, "ipv6");
+    const publicAddress = (address) => isIP(address) === 4
+        ? !blocked.check(address, "ipv4")
+        : isIP(address) === 6 &&
+            globalV6.check(address, "ipv6") &&
+            !blocked.check(address, "ipv6");
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (isIP(host) && !publicAddress(host))
+        throw new Error("BLOCKED");
+    return new Promise((resolve, reject) => {
+        // No redirects, proxy, cookies or inherited authorization; TLS still validates the original host.
+        const req = request(url, {
+            agent: false,
+            signal: AbortSignal.timeout(10000),
+            lookup(hostname, options, callback) {
+                void lookup(hostname, { all: true, verbatim: true }).then((addresses) => {
+                    const first = addresses[0];
+                    if (!first ||
+                        !addresses.every(({ address }) => publicAddress(address))) {
+                        callback(new Error("BLOCKED"), "", 0);
+                        return;
+                    }
+                    if (options.all)
+                        callback(null, addresses);
+                    else
+                        callback(null, first.address, first.family);
+                }, (error) => callback(error, "", 0));
+            },
+        }, (response) => {
+            if (response.statusCode === 404 || response.statusCode === 410) {
+                response.destroy();
+                reject(new Error("NOT_FOUND"));
+                return;
+            }
+            if (response.statusCode !== 200) {
+                response.destroy();
+                reject(new Error("UNAVAILABLE"));
+                return;
+            }
+            contentType?.(response.headers["content-type"] ?? "");
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > 2 * 1024 * 1024) {
+                    response.destroy();
+                    reject(new Error("UNAVAILABLE"));
+                }
+                else
+                    chunks.push(chunk);
+            });
+            response.on("end", () => resolve(Buffer.concat(chunks)));
+            response.on("error", reject);
+            response.on("aborted", () => reject(new Error("UNAVAILABLE")));
+        });
+        req.on("error", reject);
+        req.end();
+    });
+}

package/dist/compiler/serialize.d.ts

@@ -0,0 +1,3 @@
+import type { Frontmatter } from "../core/taxonomy.js";
+/** Form frontmatter + body md → full file text (normalized to one trailing newline). */
+export declare const assembleDoc: (fm: Frontmatter, body: string) => string;

package/dist/compiler/serialize.js

@@ -0,0 +1,16 @@
+// Serializes front-matter in hand-written style (double-quoted scalars / flow sequences). A
+// generic YAML stringify isn't used because it changes quote/sequence style and pollutes git
+// diffs against existing files. Key order is title / lang. The key set is
+// taxonomy's closed set, and a JSON string is a valid YAML double-quoted scalar.
+const serializeFrontmatter = (fm) => {
+    const lines = [`title: ${JSON.stringify(fm.title)}`];
+    if (fm.lang) {
+        lines.push(`lang: ${JSON.stringify(fm.lang)}`);
+    }
+    return `---\n${lines.join("\n")}\n---\n`;
+};
+/** Form frontmatter + body md → full file text (normalized to one trailing newline). */
+export const assembleDoc = (fm, body) => {
+    const b = body.replace(/\n+$/, "");
+    return serializeFrontmatter(fm) + (b === "" ? "" : `\n${b}\n`);
+};

package/dist/compiler/terms.d.ts

@@ -0,0 +1,9 @@
+import type { TermEntry } from "../core/content-types.js";
+/** The internal identity is a file path, or a document position for an inline definition. */
+export declare function parseTermSource(id: string, source: string): {
+    entries: TermEntry[];
+    errors: {
+        line: number;
+        message: string;
+    }[];
+};

package/dist/compiler/terms.js

@@ -0,0 +1,44 @@
+import { parseDocument } from "yaml";
+/** The internal identity is a file path, or a document position for an inline definition. */
+export function parseTermSource(id, source) {
+    const entries = [];
+    const errors = [];
+    const fail = (message) => {
+        errors.push({ line: 0, message });
+    };
+    let data;
+    try {
+        const doc = parseDocument(source);
+        if (doc.errors.length) {
+            for (const e of doc.errors)
+                errors.push({ line: (e.linePos?.[0]?.line ?? 1) - 1, message: e.message });
+            return { entries, errors };
+        }
+        data = doc.toJS({ maxAliasCount: 0 });
+    }
+    catch (e) {
+        fail(`cannot read YAML: ${e instanceof Error ? e.message : String(e)}`);
+        return { entries, errors };
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        fail("expected a YAML object with name and definition");
+        return { entries, errors };
+    }
+    const row = data;
+    for (const key of Object.keys(row))
+        if (key !== "name" && key !== "definition" && key !== "description")
+            fail(`unknown field "${key}"`);
+    for (const key of ["name", "definition"])
+        if (typeof row[key] !== "string" || !row[key].trim())
+            fail(`${key} must be a non-empty string`);
+    if (row.description !== undefined && typeof row.description !== "string")
+        fail("description must be a string");
+    if (!errors.length)
+        entries.push({
+            id,
+            name: row.name,
+            definition: row.definition,
+            ...(typeof row.description === "string" ? { description: row.description } : {}),
+        });
+    return { entries, errors };
+}

package/dist/compiler/textfile-remote.d.ts

@@ -0,0 +1,12 @@
+export declare class TextfileUnavailable extends Error {
+    readonly reason: "missing" | "unreachable";
+    constructor(reason: "missing" | "unreachable");
+}
+export declare const remoteTextfileSource: (file: string) => {
+    url: string;
+    ref?: string;
+    path?: string;
+};
+/** The viewer fetches in the background; the compiler reuses the completed cache entry. */
+export declare const readRemoteTextfileAsync: (file: string, domains: readonly string[], refresh?: boolean) => Promise<Buffer>;
+export declare const readRemoteTextfile: (file: string, domains: readonly string[], refresh?: boolean) => Buffer;

package/dist/compiler/textfile-remote.js

@@ -0,0 +1,124 @@
+import { execFileSync } from "node:child_process";
+import { allowedPreviewUrl } from "../core/previewers.js";
+import { fetchPublicFile } from "./public-file.js";
+export class TextfileUnavailable extends Error {
+    reason;
+    constructor(reason) {
+        super(reason === "missing" ? "File not found" : "File could not be loaded");
+        this.reason = reason;
+    }
+}
+const MAX_BYTES = 2 * 1024 * 1024;
+// The compiler is synchronous; a bounded child fetch keeps its public API synchronous too.
+const FETCH = `
+    const __name = (value) => value;
+    (${fetchPublicFile.toString()})(process.argv[1])
+        .then(data => process.stdout.write(data))
+        .catch(error => process.exit(error.message === "NOT_FOUND" ? 44 : error.message === "BLOCKED" ? 45 : 1));
+`;
+export const remoteTextfileSource = (file) => {
+    const url = new URL(file);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+        throw new Error("expected an HTTP(S) URL without embedded credentials");
+    if (url.pathname.endsWith(".git")) {
+        const match = /^#([^:]+):(.+)$/.exec(url.hash);
+        const ref = decodeURIComponent(match?.[1] ?? "");
+        const path = decodeURIComponent(match?.[2] ?? "");
+        if (!ref ||
+            ref.startsWith("-") ||
+            /[\s\0~^:?*[\\]/.test(ref) ||
+            ref.includes("..") ||
+            ref.includes("@{") ||
+            !path ||
+            path.startsWith("/") ||
+            /[\0\r\n\\]/.test(path) ||
+            path.split("/").some((part) => !part || part === "." || part === ".."))
+            throw new Error("use https://host/repo.git#ref:path/to/file.ext");
+        url.hash = "";
+        return { url: url.href, ref, path };
+    }
+    // Accept the ordinary GitHub file URL as well as a raw content URL.
+    if (url.hostname === "github.com" && /^\/[^/]+\/[^/]+\/blob\//.test(url.pathname)) {
+        url.hostname = "raw.githubusercontent.com";
+        url.pathname = url.pathname.replace("/blob/", "/");
+    }
+    url.hash = "";
+    return { url: url.href };
+};
+// shortcut: cache remote reads for one minute; use explicit reload for immediate branch updates.
+const cache = new Map();
+const pending = new Map();
+/** The viewer fetches in the background; the compiler reuses the completed cache entry. */
+export const readRemoteTextfileAsync = async (file, domains, refresh = false) => {
+    allowedPreviewUrl(file, domains);
+    const source = remoteTextfileSource(file);
+    if (source.ref)
+        throw new Error("Git repositories require a dedicated preview protocol; use a public HTTPS file URL");
+    allowedPreviewUrl(source.url, domains);
+    const cached = cache.get(file);
+    if (!refresh && cached && cached.expires > Date.now()) {
+        if (cached.result instanceof Error)
+            throw cached.result;
+        return cached.result;
+    }
+    const active = pending.get(file);
+    if (active)
+        return active;
+    const task = (async () => {
+        let result;
+        try {
+            result = await fetchPublicFile(source.url);
+        }
+        catch (error) {
+            if (error.message === "BLOCKED")
+                throw new Error("External previews require a public network address");
+            result = new TextfileUnavailable(error.message === "NOT_FOUND" ? "missing" : "unreachable");
+        }
+        if (cache.size >= 64)
+            cache.clear();
+        cache.set(file, { result, expires: Date.now() + 60000 });
+        if (result instanceof Error)
+            throw result;
+        return result;
+    })();
+    pending.set(file, task);
+    try {
+        return await task;
+    }
+    finally {
+        pending.delete(file);
+    }
+};
+export const readRemoteTextfile = (file, domains, refresh = false) => {
+    allowedPreviewUrl(file, domains);
+    const source = remoteTextfileSource(file);
+    if (source.ref)
+        throw new Error("Git repositories require a dedicated preview protocol; use a public HTTPS file URL");
+    allowedPreviewUrl(source.url, domains);
+    const cached = cache.get(file);
+    if (!refresh && cached && cached.expires > Date.now()) {
+        if (cached.result instanceof Error)
+            throw cached.result;
+        return cached.result;
+    }
+    let result;
+    try {
+        result = execFileSync(process.execPath, ["--input-type=module", "-e", FETCH, source.url], {
+            timeout: 12000,
+            maxBuffer: MAX_BYTES,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { PATH: process.env.PATH },
+        });
+    }
+    catch (error) {
+        if (error.status === 45)
+            throw new Error("External previews require a public network address");
+        result = new TextfileUnavailable(error.status === 44 ? "missing" : "unreachable");
+    }
+    if (cache.size >= 64)
+        cache.clear();
+    cache.set(file, { result, expires: Date.now() + 60000 });
+    if (result instanceof Error)
+        throw result;
+    return result;
+};