gamealgo-cli 0.1.7 → 0.2.0

package/dist/docs.js

@@ -0,0 +1,606 @@
+import { spawn } from "node:child_process";
+import { parseFlags } from "./args.js";
+import { loadConfig, loadPackageMetadata } from "./config.js";
+import { isTimeoutError, truncateBody } from "./http.js";
+import { printResult } from "./output.js";
+import { objectValue, writeTextFile } from "./resources.js";
+import { normalizeHost, optionalString } from "./utils.js";
+export const DEFAULT_CLI_HELP_HOSTS = [
+    "https://game-algo-admin.dictapis.cn",
+    "https://dirichlet.ai/algo_admin",
+];
+export async function handleHelp(args, global) {
+    const flags = parseFlags(args);
+    const query = normalizeCliHelpQuery(args.join(" "));
+    const saved = await loadConfig();
+    const configuredHost = normalizeHost(global.host || saved?.host || "");
+    const loaded = await loadCliHelpCatalog(configuredHost ? [configuredHost] : DEFAULT_CLI_HELP_HOSTS);
+    const packageMetadata = await loadPackageMetadata();
+    const visibleCommands = loaded.catalog.commands.filter((command) => !command.internal);
+    const selection = selectCliHelpCommands(visibleCommands, query);
+    if (!selection.length) {
+        const suggestions = suggestCliHelpCommands(visibleCommands, query);
+        const suffix = suggestions.length ? ` Did you mean: ${suggestions.join(", ")}` : "";
+        throw new Error(`Unknown CLI command: ${query}.${suffix}`);
+    }
+    const detail = query && selection.length === 1 && cliHelpCommandMatchesInvocation(selection[0], query)
+        ? selection[0]
+        : undefined;
+    const markdown = detail
+        ? formatCliHelpCommand(detail, loaded.catalog.commonOptions)
+        : formatCliHelpIndex(loaded.catalog, selection, query);
+    const out = optionalString(flags.out);
+    if (flags.out === true)
+        throw new Error("--out requires a file path");
+    if (out) {
+        const payload = out.toLowerCase().endsWith(".json")
+            ? `${JSON.stringify(cliHelpResult(loaded, packageMetadata.version, query, selection, detail), null, 2)}\n`
+            : `${markdown.trimEnd()}\n`;
+        await writeTextFile(out, payload);
+        await printResult({ ok: true, out, source: loaded.url, version: loaded.catalog.version }, global);
+        return;
+    }
+    if (global.json) {
+        await printResult(cliHelpResult(loaded, packageMetadata.version, query, selection, detail), global);
+        return;
+    }
+    console.log(markdown.trimEnd());
+}
+export async function loadCliHelpCatalog(hosts) {
+    const failures = [];
+    for (const candidate of hosts) {
+        const host = normalizeHost(candidate);
+        const url = `${docsContentBaseUrl(host)}cli-commands.json`;
+        try {
+            return { catalog: parseCliHelpCatalog(await requestLiveTextUrl(url)), host, url };
+        }
+        catch (error) {
+            failures.push(`${host}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new Error(`Unable to load the current CLI help from the Server. ${failures.join(" | ")}`);
+}
+export async function requestLiveTextUrl(url) {
+    let response;
+    try {
+        response = await fetch(url, {
+            cache: "no-store",
+            headers: { "Cache-Control": "no-cache" },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (error) {
+        if (isTimeoutError(error))
+            throw new Error(`Help request timed out: ${url}`);
+        throw new Error(`Help request failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`Help request returned ${response.status}: ${truncateBody(text)}`);
+    return text;
+}
+export function parseCliHelpCatalog(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error("CLI command catalog is not valid JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("CLI command catalog must be an object");
+    }
+    const body = value;
+    if (body.schemaVersion !== 1 || !Array.isArray(body.groups) || !Array.isArray(body.commands)) {
+        throw new Error("CLI command catalog schema is invalid");
+    }
+    const groups = body.groups.map((item) => {
+        const group = objectValue(item);
+        const id = optionalString(group?.id);
+        const title = optionalString(group?.title);
+        if (!id || !title)
+            throw new Error("CLI command catalog contains an invalid group");
+        return { id, title, description: optionalString(group?.description) };
+    });
+    const groupIds = new Set(groups.map((group) => group.id));
+    const commands = body.commands.map((item) => parseCliHelpCommand(item, groupIds));
+    const paths = new Set(commands.map((command) => normalizeCliHelpQuery(command.path)));
+    if (paths.size !== commands.length)
+        throw new Error("CLI command catalog contains duplicate command paths");
+    const commonOptions = Array.isArray(body.commonOptions)
+        ? body.commonOptions.map((item) => parseCliHelpOption(item, "common option"))
+        : [];
+    return {
+        schemaVersion: 1,
+        version: String(body.version || "current"),
+        updatedAt: String(body.updatedAt || ""),
+        cliPackage: String(body.cliPackage || "gamealgo-cli"),
+        groups,
+        commonOptions,
+        commands,
+    };
+}
+export function parseCliHelpCommand(value, groupIds) {
+    const command = objectValue(value);
+    const path = optionalString(command?.path);
+    const group = optionalString(command?.group);
+    const summary = optionalString(command?.summary);
+    const usage = optionalString(command?.usage);
+    if (!path || !group || !summary || !usage || !groupIds.has(group)) {
+        throw new Error(`CLI command catalog contains an invalid command: ${path || "unknown"}`);
+    }
+    const options = Array.isArray(command?.options)
+        ? command.options.map((item) => parseCliHelpOption(item, path))
+        : undefined;
+    return {
+        path,
+        group,
+        summary,
+        usage,
+        description: optionalString(command?.description),
+        aliases: stringArray(command?.aliases),
+        options,
+        notes: stringArray(command?.notes),
+        examples: stringArray(command?.examples),
+        sinceVersion: optionalString(command?.sinceVersion),
+        internal: command?.internal === true,
+    };
+}
+export function parseCliHelpOption(value, owner) {
+    const option = objectValue(value);
+    const name = optionalString(option?.name);
+    const description = optionalString(option?.description);
+    if (!name || !description)
+        throw new Error(`CLI command catalog contains an invalid option for ${owner}`);
+    return { name, description };
+}
+export function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const result = value.map(optionalString).filter((item) => Boolean(item));
+    return result.length ? result : undefined;
+}
+export function normalizeCliHelpQuery(value) {
+    return value.trim().replace(/^gamealgo\s+/i, "").replace(/\s+/g, " ").toLowerCase();
+}
+export function selectCliHelpCommands(commands, query) {
+    if (!query)
+        return commands;
+    const exact = commands.filter((command) => (normalizeCliHelpQuery(command.path) === query
+        || command.aliases?.some((alias) => normalizeCliHelpQuery(alias) === query)));
+    if (exact.length)
+        return exact;
+    const invocationMatches = commands
+        .filter((command) => cliHelpCommandMatchesInvocation(command, query))
+        .sort((left, right) => normalizeCliHelpQuery(right.path).length - normalizeCliHelpQuery(left.path).length);
+    if (invocationMatches.length)
+        return [invocationMatches[0]];
+    return commands.filter((command) => (normalizeCliHelpQuery(command.path).startsWith(`${query} `)
+        || command.aliases?.some((alias) => normalizeCliHelpQuery(alias).startsWith(`${query} `))));
+}
+export function cliHelpCommandMatchesInvocation(command, query) {
+    const paths = [command.path, ...(command.aliases || [])].map(normalizeCliHelpQuery);
+    return paths.some((path) => query === path || query.startsWith(`${path} `));
+}
+export function suggestCliHelpCommands(commands, query) {
+    return commands
+        .map((command) => ({ command, score: docsApiSimilarity(query, normalizeCliHelpQuery(command.path)) }))
+        .filter((item) => item.score >= 0.35)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 5)
+        .map((item) => item.command.path);
+}
+export function formatCliHelpIndex(catalog, commands, query) {
+    const lines = [`# GameAlgo CLI 命令`, "", `目录版本：${catalog.version} · 更新于 ${catalog.updatedAt}`, ""];
+    for (const group of catalog.groups) {
+        const grouped = commands.filter((command) => command.group === group.id);
+        if (!grouped.length)
+            continue;
+        lines.push(`## ${group.title}`, "");
+        if (group.description)
+            lines.push(group.description, "");
+        for (const command of grouped)
+            lines.push(`- \`gamealgo ${command.path}\`：${command.summary}`);
+        lines.push("");
+    }
+    if (query)
+        lines.push(`继续查询：\`gamealgo help <完整命令>\``);
+    else
+        lines.push("查询单条命令：`gamealgo help <命令路径>`");
+    lines.push("显式保存当次最新文档：`gamealgo help --out gamealgo-cli-help.md`");
+    return lines.join("\n");
+}
+export function formatCliHelpCommand(command, commonOptions) {
+    const lines = [
+        `# gamealgo ${command.path}`,
+        "",
+        command.summary,
+        "",
+        "## 用法",
+        "",
+        "```bash",
+        command.usage,
+        "```",
+    ];
+    if (command.description)
+        lines.push("", "## 说明", "", command.description);
+    const options = [...(command.options || []), ...commonOptions];
+    if (options.length) {
+        lines.push("", "## 参数与选项", "");
+        for (const option of options)
+            lines.push(`- \`${option.name}\`：${option.description}`);
+    }
+    if (command.notes?.length) {
+        lines.push("", "## 约束", "");
+        for (const note of command.notes)
+            lines.push(`- ${note}`);
+    }
+    if (command.examples?.length) {
+        lines.push("", "## 示例", "");
+        for (const example of command.examples)
+            lines.push("```bash", example, "```");
+    }
+    return lines.join("\n");
+}
+export function cliHelpResult(loaded, cliVersion, query, commands, detail) {
+    return {
+        ok: true,
+        cliVersion,
+        catalogVersion: loaded.catalog.version,
+        updatedAt: loaded.catalog.updatedAt,
+        source: loaded.url,
+        query: query || null,
+        ...(detail ? { command: detail, commonOptions: loaded.catalog.commonOptions } : { commands }),
+    };
+}
+export async function handleDocs(args, global) {
+    const flags = parseFlags(args);
+    const topicId = String(args.shift() || "").trim();
+    const apiQuery = topicId === "api" ? args.join(" ").trim() : "";
+    if (topicId !== "api" && args.length) {
+        throw new Error("usage: gamealgo docs [topic] [--open] [--json] [--host <admin-url>]");
+    }
+    const saved = await loadConfig();
+    const host = normalizeHost(global.host || saved?.host || "");
+    if (!host)
+        throw new Error("--host is required before login; after login the saved Admin host is used");
+    const loaded = await loadDocsManifest(host);
+    const manifest = loaded.manifest;
+    const visibleTopics = manifest.topics.filter((item) => !item.hidden);
+    const resolvedTopicId = topicId === "api" ? "public-sdk-api" : topicId;
+    const topic = resolvedTopicId
+        ? manifest.topics.find((item) => item.id === resolvedTopicId && (topicId === "api" || !item.hidden))
+        : null;
+    if (topicId && !topic) {
+        if (topicId === "api") {
+            throw new Error("The Admin host does not publish the public SDK API index yet");
+        }
+        throw new Error(`Unknown docs topic: ${topicId}. Available topics: ${visibleTopics.map((item) => item.id).join(", ")}`);
+    }
+    const webUrl = docsWebUrl(host, topic?.id);
+    if (flags.open) {
+        openExternalUrl(webUrl);
+        await printResult({
+            ok: true,
+            opened: webUrl,
+            version: manifest.version,
+            ...(topic ? { topic: topic.id, title: topic.title } : {}),
+            cachedManifest: loaded.cached,
+        }, global);
+        return;
+    }
+    if (!topic) {
+        if (global.json) {
+            await printResult({
+                ok: true,
+                version: manifest.version,
+                updatedAt: manifest.updatedAt,
+                defaultTopic: manifest.defaultTopic,
+                cached: loaded.cached,
+                webUrl,
+                topics: visibleTopics,
+            }, global);
+            return;
+        }
+        printDocsIndex(manifest, webUrl);
+        if (loaded.cached)
+            console.error("Warning: using cached documentation index because the Admin host could not be reached");
+        return;
+    }
+    const document = await loadDocsDocument(host, manifest, topic, loaded.cached);
+    if (topicId === "api") {
+        await printDocsApiResult({
+            query: apiQuery,
+            platform: parseDocsApiPlatform(flags.platform),
+            manifest,
+            topic,
+            document,
+            webUrl,
+            host,
+            global,
+        });
+        return;
+    }
+    if (global.json) {
+        await printResult({
+            ok: true,
+            version: manifest.version,
+            updatedAt: manifest.updatedAt,
+            topic: topic.id,
+            title: topic.title,
+            summary: topic.summary,
+            cached: document.cached,
+            webUrl,
+            rawUrl: docsRawUrl(host, topic.file),
+            content: document.content,
+        }, global);
+        return;
+    }
+    console.log(document.content.trimEnd());
+    if (document.cached)
+        console.error("Warning: using cached documentation because the Admin host could not be reached");
+}
+export function parseDocsApiPlatform(value) {
+    if (value === undefined || value === false || value === "")
+        return undefined;
+    const platform = String(value).trim().toLowerCase();
+    if (platform === "maker")
+        return "lua";
+    if (platform === "lua" || platform === "ios" || platform === "android" || platform === "rest") {
+        return platform;
+    }
+    throw new Error("--platform must be lua, maker, ios, android, or rest");
+}
+export async function printDocsApiResult(options) {
+    const { query, platform, manifest, topic, document, webUrl, host, global } = options;
+    const entries = parseDocsApiEntries(document.content).filter((entry) => !platform || entry.platforms.includes(platform));
+    if (!entries.length) {
+        throw new Error(platform ? `No public SDK APIs are documented for platform: ${platform}` : "Public SDK API document has no indexed entries");
+    }
+    const normalizedQuery = normalizeDocsApiQuery(query);
+    const listMode = !normalizedQuery || normalizedQuery === "list" || normalizedQuery === "ls";
+    if (listMode) {
+        if (global.json) {
+            await printResult({
+                ok: true,
+                version: manifest.version,
+                updatedAt: manifest.updatedAt,
+                topic: topic.id,
+                cached: document.cached,
+                webUrl,
+                rawUrl: docsRawUrl(host, topic.file),
+                ...(platform ? { platform } : {}),
+                apis: entries.map(({ name, symbols, platforms, summary }) => ({ name, symbols, platforms, summary })),
+            }, global);
+            return;
+        }
+        console.log(`GameAlgo 公开 SDK API ${manifest.version}${platform ? ` · ${platform}` : ""}`);
+        for (const entry of entries) {
+            console.log(`\n${entry.name}  [${entry.platforms.join(", ")}]`);
+            console.log(`  ${entry.symbols.join(" / ")}`);
+            console.log(`  ${entry.summary}`);
+        }
+        console.log(`\n查询函数: gamealgo docs api <函数名>${platform ? ` --platform ${platform}` : ""}`);
+        if (document.cached)
+            console.error("Warning: using cached documentation because the Admin host could not be reached");
+        return;
+    }
+    const matches = findDocsApiEntries(entries, query);
+    if (!matches.length) {
+        const suggestions = suggestDocsApiEntries(entries, query);
+        const suffix = suggestions.length ? ` Did you mean: ${suggestions.join(", ")}` : "";
+        throw new Error(`Unknown public SDK API: ${query}.${suffix}`);
+    }
+    if (global.json) {
+        await printResult({
+            ok: true,
+            version: manifest.version,
+            updatedAt: manifest.updatedAt,
+            topic: topic.id,
+            query,
+            cached: document.cached,
+            webUrl,
+            rawUrl: docsRawUrl(host, topic.file),
+            ...(platform ? { platform } : {}),
+            matches,
+        }, global);
+        return;
+    }
+    console.log(matches.map((entry) => entry.content.trim()).join("\n\n"));
+    if (document.cached)
+        console.error("Warning: using cached documentation because the Admin host could not be reached");
+}
+export function parseDocsApiEntries(content) {
+    const headings = [...content.matchAll(/^###\s+(.+)$/gm)];
+    const entries = [];
+    for (let index = 0; index < headings.length; index += 1) {
+        const heading = headings[index];
+        const start = heading.index ?? 0;
+        const end = headings[index + 1]?.index ?? content.length;
+        const section = content.slice(start, end).trim();
+        const symbols = parseDocsApiMetadataList(section, "API");
+        if (!symbols.length)
+            continue;
+        const platforms = parseDocsApiMetadataList(section, "平台")
+            .map((item) => item.toLowerCase())
+            .filter((item) => item === "lua" || item === "ios" || item === "android" || item === "rest");
+        const summaryMatch = section.match(/^-\s*用途[：:]\s*(.+)$/m);
+        entries.push({
+            name: stripInlineMarkdown(heading[1]),
+            symbols,
+            platforms: [...new Set(platforms)],
+            summary: stripInlineMarkdown(summaryMatch?.[1] || ""),
+            content: section,
+        });
+    }
+    return entries;
+}
+export function parseDocsApiMetadataList(section, key) {
+    const match = section.match(new RegExp(`^-\\s*${key}[：:]\\s*(.+)$`, "m"));
+    if (!match)
+        return [];
+    const inlineCode = [...match[1].matchAll(/`([^`]+)`/g)].map((item) => item[1].trim()).filter(Boolean);
+    if (inlineCode.length)
+        return inlineCode;
+    return match[1].split(/[,，]/).map((item) => stripInlineMarkdown(item)).filter(Boolean);
+}
+export function stripInlineMarkdown(value) {
+    return value.replace(/[`*]/g, "").trim();
+}
+export function normalizeDocsApiQuery(value) {
+    return stripInlineMarkdown(value)
+        .replace(/\(.*\)$/, "")
+        .replace(/\s+/g, "")
+        .toLowerCase();
+}
+export function docsApiSearchTerms(entry) {
+    return [entry.name, ...entry.symbols, ...entry.symbols.map((symbol) => symbol.split(/[.#]/).pop() || symbol)]
+        .map(normalizeDocsApiQuery)
+        .filter(Boolean);
+}
+export function findDocsApiEntries(entries, query) {
+    const needle = normalizeDocsApiQuery(query);
+    const exact = entries.filter((entry) => docsApiSearchTerms(entry).includes(needle));
+    if (exact.length)
+        return exact;
+    return entries.filter((entry) => (docsApiSearchTerms(entry).some((term) => term.includes(needle))
+        || normalizeDocsApiQuery(entry.summary).includes(needle)));
+}
+export function suggestDocsApiEntries(entries, query) {
+    const needle = normalizeDocsApiQuery(query);
+    return entries
+        .map((entry) => {
+        const terms = docsApiSearchTerms(entry);
+        const score = Math.max(...terms.map((term) => docsApiSimilarity(needle, term)));
+        return { entry, score };
+    })
+        .filter((item) => item.score >= 0.35)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 5)
+        .map(({ entry }) => entry.symbols[0] || entry.name);
+}
+export function docsApiSimilarity(left, right) {
+    if (!left || !right)
+        return 0;
+    if (left.includes(right) || right.includes(left)) {
+        return Math.min(left.length, right.length) / Math.max(left.length, right.length) + 0.5;
+    }
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        const current = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const substitution = previous[rightIndex - 1] + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
+            current[rightIndex] = Math.min(previous[rightIndex] + 1, current[rightIndex - 1] + 1, substitution);
+        }
+        previous.splice(0, previous.length, ...current);
+    }
+    return 1 - previous[right.length] / Math.max(left.length, right.length);
+}
+export async function loadDocsManifest(host) {
+    const text = await requestTextUrl(`${docsContentBaseUrl(host)}manifest.json`);
+    return { manifest: parseDocsManifest(text), cached: false };
+}
+export async function loadDocsDocument(host, manifest, topic, _preferCache) {
+    void manifest;
+    return { content: await requestTextUrl(docsRawUrl(host, topic.file)), cached: false };
+}
+export async function requestTextUrl(url) {
+    let response;
+    try {
+        response = await fetch(url, {
+            cache: "no-store",
+            headers: { "Cache-Control": "no-cache" },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (error) {
+        if (isTimeoutError(error))
+            throw new Error(`Documentation request timed out: ${url}`);
+        throw new Error(`Documentation request failed: ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`Documentation request returned ${response.status}: ${truncateBody(text)}`);
+    }
+    return text;
+}
+export function parseDocsManifest(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error("Documentation manifest is not valid JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Documentation manifest must be an object");
+    }
+    const body = value;
+    if (body.schemaVersion !== 1 || !Array.isArray(body.topics) || !body.topics.length) {
+        throw new Error("Documentation manifest schema is invalid");
+    }
+    const topics = body.topics.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error("Documentation manifest contains an invalid topic");
+        }
+        const topic = item;
+        const id = String(topic.id || "");
+        const file = String(topic.file || "");
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(id) || !/^[a-z][a-z0-9-]{0,63}\.md$/.test(file)) {
+            throw new Error(`Documentation manifest contains an unsafe topic: ${id || file}`);
+        }
+        return {
+            id,
+            title: String(topic.title || id),
+            summary: String(topic.summary || ""),
+            group: String(topic.group || "其他"),
+            file,
+            hidden: topic.hidden === true,
+        };
+    });
+    const ids = new Set(topics.map((topic) => topic.id));
+    if (ids.size !== topics.length)
+        throw new Error("Documentation manifest contains duplicate topic ids");
+    const defaultTopic = String(body.defaultTopic || topics[0].id);
+    if (!ids.has(defaultTopic))
+        throw new Error("Documentation manifest defaultTopic does not exist");
+    return {
+        schemaVersion: 1,
+        version: String(body.version || "current"),
+        updatedAt: String(body.updatedAt || ""),
+        defaultTopic,
+        topics,
+    };
+}
+export function docsWebUrl(host, topicId) {
+    const url = new URL(`${normalizeHost(host)}/dashboard/docs/`);
+    if (topicId)
+        url.searchParams.set("topic", topicId);
+    return url.toString();
+}
+export function docsContentBaseUrl(host) {
+    return `${normalizeHost(host)}/dashboard/docs/content/`;
+}
+export function docsRawUrl(host, file) {
+    return `${docsContentBaseUrl(host)}${encodeURIComponent(file)}`;
+}
+export function printDocsIndex(manifest, webUrl) {
+    console.log(`GameAlgo AI 文档 ${manifest.version}${manifest.updatedAt ? ` (${manifest.updatedAt})` : ""}`);
+    let currentGroup = "";
+    for (const topic of manifest.topics.filter((item) => !item.hidden)) {
+        if (topic.group !== currentGroup) {
+            currentGroup = topic.group;
+            console.log(`\n${currentGroup}`);
+        }
+        console.log(`  ${topic.id}\n    ${topic.title}：${topic.summary}`);
+    }
+    console.log(`\n读取文档: gamealgo docs <topic>`);
+    console.log(`网页目录: ${webUrl}`);
+}
+export function openExternalUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", (error) => console.error(`Unable to open browser: ${error.message}`));
+    child.unref();
+}

package/dist/http.js

@@ -0,0 +1,54 @@
+import { formatDuration } from "./output.js";
+import { normalizeHost } from "./utils.js";
+export async function requestJson(host, path, init) {
+    const { timeoutMs, ...requestInit } = init;
+    let response;
+    try {
+        response = await fetch(`${normalizeHost(host)}${path}`, {
+            ...requestInit,
+            signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : requestInit.signal,
+        });
+    }
+    catch (error) {
+        if (isTimeoutError(error)) {
+            throw new Error(`HTTP request timed out after ${formatDuration(timeoutMs ?? 0)}`);
+        }
+        throw error;
+    }
+    const text = await response.text();
+    const json = parseJsonResponse(text);
+    if (!response.ok) {
+        throw new Error(formatHttpError(response.status, response.statusText, text, json));
+    }
+    if (text && json === undefined) {
+        throw new Error(`Invalid JSON response from ${path}: ${truncateBody(text)}`);
+    }
+    return json ?? null;
+}
+export function parseJsonResponse(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatHttpError(status, statusText, text, json) {
+    if (json && typeof json === "object") {
+        const body = json;
+        const message = body.message || body.error;
+        if (message)
+            return `HTTP ${status}: ${String(message)}`;
+    }
+    const bodyText = truncateBody(text);
+    return bodyText ? `HTTP ${status} ${statusText}: ${bodyText}` : `HTTP ${status} ${statusText}`;
+}
+export function truncateBody(text) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return normalized.length > 500 ? `${normalized.slice(0, 500)}...` : normalized;
+}
+export function isTimeoutError(error) {
+    return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}