@overcrow/mcp 0.0.0 → 0.1.1

package/dist/resources.js

@@ -0,0 +1,82 @@
+// Resources: the documentation pages (EN and FR), the manifest reference,
+// the limits, the templates and the example widgets. All come from the
+// package; none from the project or the network.
+import { ResourceNotFoundError, ResourceTemplate, } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { docMarkdown, docPages, limits, manifestReference, projectFile, projects, } from "./content.js";
+function mimeOf(path) {
+    if (path.endsWith(".md"))
+        return "text/markdown";
+    if (path.endsWith(".json"))
+        return "application/json";
+    if (path.endsWith(".ts") || path.endsWith(".mjs"))
+        return "text/x-typescript";
+    return "text/plain";
+}
+const single = (value) => Array.isArray(value) ? (value[0] ?? "") : (value ?? "");
+export function registerResources(server) {
+    server.registerResource("manifest-reference", "overcrow://schema/manifest", {
+        title: "Manifest reference",
+        description: "Every field of manifest.json, the permissions, the network rules and the capabilities.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "text/markdown", text: manifestReference() }],
+    }));
+    server.registerResource("limits", "overcrow://limits", {
+        title: "Limits",
+        description: "Every limit a widget meets: name, value and meaning (from the limits page).",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            { uri: uri.href, mimeType: "application/json", text: JSON.stringify(limits(), null, 1) },
+        ],
+    }));
+    server.registerResource("docs", new ResourceTemplate("overcrow://docs/{locale}/{slug}", {
+        list: async () => ({
+            resources: docPages().flatMap((page) => ["en", "fr"].map((locale) => ({
+                uri: `overcrow://docs/${locale}/${page.slug || "index"}`,
+                name: `${locale}/${page.slug || "index"}`,
+                title: page.titles[locale] ?? page.slug,
+                mimeType: "text/markdown",
+            }))),
+        }),
+    }), {
+        title: "Creator documentation",
+        description: "A page of the OverCrow creator documentation.",
+        mimeType: "text/markdown",
+    }, async (uri, variables) => {
+        const locale = z.enum(["en", "fr"]).safeParse(single(variables.locale));
+        const slug = single(variables.slug);
+        const markdown = locale.success
+            ? docMarkdown(slug === "index" ? "" : slug, locale.data)
+            : undefined;
+        if (markdown === undefined)
+            throw new ResourceNotFoundError(uri.href);
+        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: markdown }] };
+    });
+    for (const kind of ["examples", "templates"]) {
+        server.registerResource(kind, new ResourceTemplate(`overcrow://${kind}/{name}/{+path}`, {
+            list: async () => ({
+                resources: projects(kind)
+                    .filter((project) => project.name !== "shared" || kind === "templates")
+                    .flatMap((project) => project.files.map((file) => ({
+                    uri: `overcrow://${kind}/${project.name}/${file}`,
+                    name: `${project.name}/${file}`,
+                    mimeType: mimeOf(file),
+                }))),
+            }),
+        }), {
+            title: kind === "examples" ? "Example widgets" : "Templates",
+            description: kind === "examples"
+                ? "Source files of the reference widgets and of the documentation's examples."
+                : "Source files of the templates of a new widget.",
+        }, async (uri, variables) => {
+            const name = single(variables.name);
+            const path = single(variables.path);
+            const text = projectFile(kind, name, path);
+            if (text === undefined)
+                throw new ResourceNotFoundError(uri.href);
+            return { contents: [{ uri: uri.href, mimeType: mimeOf(path), text }] };
+        });
+    }
+}

package/dist/run.js

@@ -0,0 +1,120 @@
+// Starts the programs the server relies on (the widget CLI, npm) and
+// nothing else: no shell, arguments as an array, a minimal environment,
+// stdin closed, a time limit, bounded output, and the whole process tree
+// stopped on timeout or when the server exits.
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { windowsSystemRoot } from "./env.js";
+export class RunError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RunError";
+    }
+}
+const running = new Set();
+/** Stops every process still running (the server is exiting). */
+export function stopAll() {
+    for (const child of running)
+        stopTree(child);
+}
+function stopTree(child) {
+    if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (process.platform === "win32") {
+        // taskkill by its full path: the PATH is not trusted for this.
+        const killer = spawn(join(windowsSystemRoot(), "System32", "taskkill.exe"), ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, shell: false });
+        killer.on("error", () => child.kill("SIGKILL"));
+        return;
+    }
+    try {
+        // The child leads its own process group (detached): stop all of it.
+        process.kill(-child.pid, "SIGTERM");
+    }
+    catch {
+        child.kill("SIGTERM");
+    }
+    const pid = child.pid;
+    setTimeout(() => {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            // Already gone.
+        }
+    }, 2000).unref();
+}
+/** Runs `file` with `args` and collects its output. */
+export function runProcess(file, args, options) {
+    const maxStdout = options.maxStdoutBytes ?? 8 << 20;
+    const maxStderr = options.maxStderrBytes ?? 1 << 20;
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(file, [...args], {
+                cwd: options.cwd,
+                env: options.env,
+                shell: false,
+                windowsHide: true,
+                detached: process.platform !== "win32",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            reject(new RunError(`cannot start ${file}: ${error.message}`));
+            return;
+        }
+        running.add(child);
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        const collect = (chunks, max, size, chunk) => {
+            if (size >= max) {
+                truncated = true;
+                return size;
+            }
+            const room = max - size;
+            if (chunk.length > room)
+                truncated = true;
+            chunks.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+            return size + Math.min(chunk.length, room);
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdoutBytes = collect(stdout, maxStdout, stdoutBytes, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrBytes = collect(stderr, maxStderr, stderrBytes, chunk);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stopTree(child);
+        }, options.timeoutMs);
+        const onAbort = () => {
+            cancelled = true;
+            stopTree(child);
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            running.delete(child);
+            options.signal?.removeEventListener("abort", onAbort);
+            reject(new RunError(`cannot start ${file}: ${error.message}`));
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            running.delete(child);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve({
+                code,
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                timedOut,
+                cancelled,
+                truncated,
+            });
+        });
+    });
+}

package/dist/server.js

@@ -0,0 +1,43 @@
+// The MCP server: its identity, its instructions, its tools, resources and
+// prompts. One instance per protocol era (see serveStdio); the session is
+// shared.
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { registerPrompts } from "./prompts.js";
+import { registerResources } from "./resources.js";
+import { INSTRUCTIONS } from "./texts.js";
+import { registerAuditTools } from "./tools/audit.js";
+import { registerBuildTools } from "./tools/build.js";
+import { registerDocTools } from "./tools/docs.js";
+import { registerProjectTools } from "./tools/project.js";
+import { registerSetupTools } from "./tools/setup.js";
+import { registerSubmissionTool } from "./tools/submission.js";
+import { VERSION } from "./version.js";
+export function createServer(session) {
+    const server = new McpServer({ name: "overcrow", title: "PlayerVox OverCrow widgets", version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: {}, resources: {}, prompts: {} } });
+    const env = { session, server };
+    // Registration order is the order of tools/list: the order of the work.
+    registerSetupTools(env);
+    registerProjectTools(env);
+    registerBuildTools(env);
+    registerAuditTools(env);
+    registerSubmissionTool(env);
+    registerDocTools(env);
+    registerResources(server);
+    registerPrompts(server);
+    try {
+        // Clients of the 2025 protocol say when their roots change.
+        server.server.setNotificationHandler("notifications/roots/list_changed", () => session.rootsChanged());
+    }
+    catch {
+        // The 2026-07-28 protocol has no such notification.
+    }
+    return server;
+}
+/**
+ * Serves `session` over this process's stdio, in the protocol era the
+ * client opens with (one instance per era, see serveStdio).
+ */
+export function serve(session, onerror) {
+    return serveStdio(() => createServer(session), { onerror });
+}

package/dist/session.js

@@ -0,0 +1,205 @@
+// What one server process keeps between requests: the options it started
+// with, the project folders it may use, and the creator tools once checked.
+// `serveStdio` may build a server instance per protocol era; they all share
+// this state.
+import { lstat, readFile, rm } from "node:fs/promises";
+import { CLIENT_CAPABILITIES_META_KEY, inputRequired, inputResponse, } from "@modelcontextprotocol/server";
+import { DownloadError, downloadPinned } from "./bootstrap/download.js";
+import { downloadPath, InstallError, install, loadInstalled, prepareCacheRoot, } from "./bootstrap/install.js";
+import { DOWNLOAD_HOSTS, toolsUrl } from "./bootstrap/pin.js";
+import { ZipError } from "./bootstrap/zip.js";
+import { probeVersion } from "./cli.js";
+import { checkRoot, Confinement, ConfinementError, labelRoots, rootUriToPath } from "./confine.js";
+import { cacheRoot, homeDirectory, httpsProxy, namedLocations, toolsPlatform, } from "./env.js";
+import { Redactor } from "./text.js";
+export class Session {
+    options;
+    clientRoots;
+    launchRoots;
+    tools;
+    sdkVersion;
+    installing;
+    /** The last test run of each widget folder, with the fingerprint of its sources then. */
+    lastTests = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get platform() {
+        return toolsPlatform();
+    }
+    get cacheRoot() {
+        return this.options.cacheRootOverride ?? cacheRoot();
+    }
+    /** Forgets the client's roots (they changed). */
+    rootsChanged() {
+        this.clientRoots = undefined;
+    }
+    /**
+     * The folders the server may use for this request: the --root folders,
+     * else the client's roots (asked for once with an input request), else
+     * the working directory. Every folder is checked (no system folder, no
+     * disk root, not the whole home folder).
+     */
+    async roots(ctx, server) {
+        try {
+            if (this.options.launchRoots.length > 0) {
+                this.launchRoots ??= await Promise.all(this.options.launchRoots.map(checkRoot));
+                return { confinement: new Confinement(labelRoots(this.launchRoots)) };
+            }
+            if (this.clientRoots === undefined) {
+                const answered = inputResponse(ctx.mcpReq.inputResponses, "roots");
+                if (answered.kind === "roots") {
+                    this.clientRoots = answered.roots
+                        .map((root) => rootUriToPath(root.uri))
+                        .filter((path) => path !== undefined)
+                        .slice(0, 16);
+                }
+                else if (clientSupportsRoots(ctx, server)) {
+                    return { input: inputRequired({ inputRequests: { roots: inputRequired.listRoots() } }) };
+                }
+                else {
+                    this.clientRoots = [];
+                }
+            }
+            const candidates = this.clientRoots.length > 0 ? this.clientRoots : [this.options.cwd];
+            const checked = [];
+            const refusals = [];
+            for (const candidate of candidates) {
+                try {
+                    checked.push(await checkRoot(candidate));
+                }
+                catch (error) {
+                    refusals.push(error.message);
+                }
+            }
+            if (checked.length === 0)
+                return { error: refusals[0] ?? "No project folder is open." };
+            return { confinement: new Confinement(labelRoots([...new Set(checked)])) };
+        }
+        catch (error) {
+            if (error instanceof ConfinementError)
+                return { error: error.message };
+            throw error;
+        }
+    }
+    /** Replaces the user's paths in text results. */
+    redactor(confinement) {
+        return new Redactor([
+            ...(confinement?.roots ?? []).map((root) => ({
+                path: root.path,
+                label: root.label === "." ? "<project>" : `<${root.label}>`,
+            })),
+            ...namedLocations(),
+        ], homeDirectory());
+    }
+    /** The installed tools, checked against the pin (once per process). */
+    async installedTools() {
+        if (this.tools)
+            return this.tools;
+        const platform = this.platform;
+        const root = this.cacheRoot;
+        const release = this.options.pin.release;
+        if (!("platform" in platform) || !root || !release)
+            return undefined;
+        const pinned = this.options.pin.tools[platform.platform];
+        if (!pinned)
+            return undefined;
+        const found = await loadInstalled(pinned, release, platform.platform, root);
+        if (found)
+            await this.adopt(found);
+        return this.tools;
+    }
+    /** The SDK version the installed CLI embeds (from `--version --format json`). */
+    get cliSdkVersion() {
+        return this.sdkVersion;
+    }
+    async adopt(tools) {
+        const probe = this.options.probe ?? probeVersion;
+        const report = (await probe(tools.cli, tools.directory));
+        this.sdkVersion = typeof report?.sdk === "string" ? report.sdk : undefined;
+        this.tools = tools;
+    }
+    /**
+     * Installs the pinned creator tools: from `zipPath` (a local file the
+     * caller has confined) or --tools-zip, else by downloading the pinned ZIP.
+     */
+    async setup(zipPath, onProgress, signal) {
+        const existing = await this.installedTools();
+        if (existing)
+            return { tools: existing, source: "cache" };
+        const platform = this.platform;
+        if (!("platform" in platform))
+            throw new SetupError(platform.unsupported);
+        const release = this.options.pin.release;
+        const pinned = this.options.pin.tools[platform.platform];
+        if (!release || !pinned) {
+            throw new SetupError("This version of @overcrow/mcp is not tied to a published OverCrow release yet: update it (npx -y @overcrow/mcp@latest).");
+        }
+        const root = this.cacheRoot;
+        if (!root)
+            throw new SetupError("No cache folder: set HOME (or LOCALAPPDATA on Windows).");
+        const local = zipPath ?? this.options.toolsZip;
+        this.installing ??= (async () => {
+            await prepareCacheRoot(root);
+            let archive;
+            if (local) {
+                const info = await lstat(local).catch(() => undefined);
+                if (!info?.isFile())
+                    throw new SetupError("The creator tools ZIP was not found.");
+                if (info.size !== pinned.size)
+                    throw new SetupError(`This ZIP is not ${pinned.name} of OverCrow ${release} (another size).`);
+                archive = await readFile(local);
+            }
+            else {
+                const temporary = downloadPath(root);
+                try {
+                    const proxy = httpsProxy("github.com");
+                    await downloadPinned(toolsUrl(release, pinned.name, this.options.releaseBase), temporary, {
+                        allowedHosts: this.options.releaseBase
+                            ? [new URL(this.options.releaseBase).hostname, ...DOWNLOAD_HOSTS]
+                            : DOWNLOAD_HOSTS,
+                        expectedSize: pinned.size,
+                        proxy,
+                        ca: this.options.ca,
+                        port: this.options.releasePort,
+                        ...(onProgress ? { onProgress } : {}),
+                        signal,
+                    });
+                    archive = await readFile(temporary);
+                }
+                finally {
+                    await rm(temporary, { force: true });
+                }
+            }
+            return install(archive, pinned, release, platform.platform, root, this.options.probe ?? probeVersion);
+        })();
+        try {
+            const tools = await this.installing;
+            await this.adopt(tools);
+            return { tools, source: local ? "local" : "download" };
+        }
+        catch (error) {
+            if (error instanceof DownloadError)
+                throw new SetupError(`Cannot download the creator tools: ${error.reason}. Nothing was kept. Check the connection (or HTTPS_PROXY), or pass a local copy of ${pinned.name}.`);
+            if (error instanceof ZipError || error instanceof InstallError)
+                throw new SetupError(`The creator tools were refused: ${error.message}. Nothing was kept.`);
+            throw error;
+        }
+        finally {
+            this.installing = undefined;
+        }
+    }
+}
+export class SetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SetupError";
+    }
+}
+function clientSupportsRoots(ctx, server) {
+    const envelope = ctx.mcpReq.envelope;
+    const modern = envelope?.[CLIENT_CAPABILITIES_META_KEY];
+    if (modern)
+        return modern.roots !== undefined;
+    return server.server.getClientCapabilities()?.roots !== undefined;
+}

package/dist/sources.js

@@ -0,0 +1,218 @@
+// The ZIP of a widget's sources, the file a creator sends to the OverCrow
+// creator space (whose server rebuilds the package from it). It holds the
+// widget folder minus what is never sent: hidden entries (.git, .env,
+// .npmrc…), node_modules, dist, tests/output, links (never followed), built
+// packages, key stores and system files. Each left-out entry is listed with
+// its reason. The archive is deterministic (sorted names, fixed date,
+// mode 644) and written atomically: a temporary file, then a rename.
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { crc32, deflateRawSync } from "node:zlib";
+export const MAX_SOURCE_FILES = 2000;
+export const MAX_SOURCE_DEPTH = 8;
+/** Sum of the files read. */
+export const MAX_SOURCE_BYTES = 64 * 1024 * 1024;
+/** The creator space takes an archive of 32 MB at most. */
+export const MAX_ZIP_BYTES = 32_000_000;
+const SKIPPED_FOLDERS = {
+    node_modules: "installed packages: npm brings them back",
+    dist: "build output: the creator space builds its own package",
+};
+const KEY_FILE = /\.(pem|key|p12|pfx|pk8|jks|keystore|kdbx|gpg|asc)$|^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i;
+const SYSTEM_FILE = /^(thumbs\.db|desktop\.ini|ehthumbs\.db)$/i;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the point is to refuse them
+const NOT_PORTABLE = /[\u0000-\u001f\u007f<>:"\\|?*]|[ .]$/;
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(\..*)?$/i;
+/** Why a file of the widget folder is left out, or undefined to keep it. */
+function fileReason(name) {
+    if (/\.ocpkg$/i.test(name))
+        return "a built package: the creator space builds its own";
+    if (KEY_FILE.test(name))
+        return "a key or a key store: never sent";
+    if (SYSTEM_FILE.test(name))
+        return "a system file";
+    if (NOT_PORTABLE.test(name) || WINDOWS_DEVICE.test(name))
+        return 'a name that Windows cannot use (control characters, < > : " \\ | ? *, or a final dot or space): rename it to send it';
+    return undefined;
+}
+/** The files of the widget folder `directory` (already confined) that the ZIP holds. */
+export async function selectSources(directory) {
+    const included = [];
+    const excluded = [];
+    let total = 0;
+    let problem = null;
+    const walk = async (relative, depth) => {
+        const entries = await readdir(relative ? join(directory, relative) : directory, {
+            withFileTypes: true,
+        });
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (problem)
+                return;
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink()) {
+                excluded.push({ path, reason: "a link: links are never followed" });
+            }
+            else if (entry.isDirectory()) {
+                const skipped = SKIPPED_FOLDERS[entry.name];
+                if (entry.name.startsWith(".")) {
+                    excluded.push({ path: `${path}/`, reason: "a hidden folder" });
+                }
+                else if (skipped) {
+                    excluded.push({ path: `${path}/`, reason: skipped });
+                }
+                else if (path === "tests/output") {
+                    excluded.push({ path: `${path}/`, reason: "test output: test writes it again" });
+                }
+                else if (NOT_PORTABLE.test(entry.name) || WINDOWS_DEVICE.test(entry.name)) {
+                    excluded.push({ path: `${path}/`, reason: fileReason(entry.name) ?? "" });
+                }
+                else if (depth >= MAX_SOURCE_DEPTH) {
+                    problem = `${path}/ is more than ${MAX_SOURCE_DEPTH} folders deep: flatten the widget folder.`;
+                }
+                else {
+                    await walk(path, depth + 1);
+                }
+            }
+            else if (!entry.isFile()) {
+                excluded.push({ path, reason: "not a regular file" });
+            }
+            else if (entry.name.startsWith(".")) {
+                excluded.push({
+                    path,
+                    reason: "a hidden file (such as .env or .npmrc, which often hold secrets)",
+                });
+            }
+            else {
+                const reason = fileReason(entry.name);
+                if (reason) {
+                    excluded.push({ path, reason });
+                    continue;
+                }
+                const info = await lstat(join(directory, path));
+                total += info.size;
+                included.push({ path, bytes: info.size });
+                if (included.length > MAX_SOURCE_FILES) {
+                    problem = `The widget folder holds more than ${MAX_SOURCE_FILES} files to send: remove the ones the widget does not need.`;
+                }
+                else if (total > MAX_SOURCE_BYTES) {
+                    problem = `The files to send weigh more than ${MAX_SOURCE_BYTES / 1048576} MiB: remove the large files the widget does not need.`;
+                }
+            }
+        }
+    };
+    await walk("", 0);
+    return { included, excluded, problem };
+}
+const DOS_DATE_1980_01_01 = (1 << 5) | 1;
+const UTF8_NAMES = 1 << 11;
+const VERSION_NEEDED = 20;
+const MADE_BY_UNIX = (3 << 8) | VERSION_NEEDED;
+const REGULAR_FILE_644 = (0o100644 << 16) >>> 0;
+/** A deterministic ZIP of `entries` (already in their final order). */
+export function buildZip(entries) {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const { name, data } of entries) {
+        const nameBytes = Buffer.from(name, "utf8");
+        const deflated = deflateRawSync(data, { level: 9 });
+        const stored = deflated.length >= data.length;
+        const body = stored ? data : deflated;
+        const crc = crc32(data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(VERSION_NEEDED, 4);
+        local.writeUInt16LE(UTF8_NAMES, 6);
+        local.writeUInt16LE(stored ? 0 : 8, 8);
+        local.writeUInt16LE(0, 10);
+        local.writeUInt16LE(DOS_DATE_1980_01_01, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(nameBytes.length, 26);
+        local.writeUInt16LE(0, 28);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(MADE_BY_UNIX, 4);
+        central.writeUInt16LE(VERSION_NEEDED, 6);
+        central.writeUInt16LE(UTF8_NAMES, 8);
+        central.writeUInt16LE(stored ? 0 : 8, 10);
+        central.writeUInt16LE(0, 12);
+        central.writeUInt16LE(DOS_DATE_1980_01_01, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(nameBytes.length, 28);
+        central.writeUInt32LE(REGULAR_FILE_644, 38);
+        central.writeUInt32LE(offset, 42);
+        locals.push(local, nameBytes, body);
+        centrals.push(central, nameBytes);
+        offset += local.length + nameBytes.length + body.length;
+    }
+    const directory = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, directory, end]);
+}
+/** Reads a selected file without following a link, if it is still as selected. */
+async function readSelected(directory, file) {
+    // O_NOFOLLOW does not exist on Windows, where links were left out when selecting.
+    const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
+    const handle = await open(join(directory, file.path), flags).catch(() => undefined);
+    if (!handle)
+        return undefined;
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size !== file.bytes)
+            return undefined;
+        const data = await handle.readFile();
+        return data.length === file.bytes ? data : undefined;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Writes the ZIP of `files` to `folder`/`name` (`folder` already confined),
+ * or returns why it is not written.
+ */
+export async function writeSourcesZip(directory, files, folder, name) {
+    const entries = [];
+    for (const file of files) {
+        const data = await readSelected(directory, file);
+        if (!data)
+            return {
+                problem: `${file.path} changed while the ZIP was made: run prepare_submission again.`,
+            };
+        entries.push({ name: file.path, data });
+    }
+    const zip = buildZip(entries);
+    if (zip.length > MAX_ZIP_BYTES) {
+        return {
+            problem: `The ZIP would weigh ${(zip.length / 1e6).toFixed(1)} MB, and the creator space takes 32 MB at most: shrink or remove large files.`,
+        };
+    }
+    await mkdir(folder, { recursive: true });
+    const destination = join(folder, name);
+    const temporary = join(folder, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await writeFile(temporary, zip, { flag: "wx", mode: 0o644 });
+        await rename(temporary, destination);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return {
+        path: destination,
+        bytes: zip.length,
+        sha256: createHash("sha256").update(zip).digest("hex"),
+    };
+}