@agentrq/acp-gateway 0.2.3 → 0.2.5

package/dist/agentInstall.js

@@ -0,0 +1,241 @@
+/**
+ * agentInstall.ts
+ *
+ * Downloads, verifies and unpacks the binary distribution of a registry agent,
+ * caching it so the download happens once.
+ *
+ * This is the one place in the gateway that fetches a third-party executable
+ * and runs it, so the rules here are deliberately strict: an archive is only
+ * installed when the registry publishes a `sha256` that the download matches,
+ * unless the user has explicitly said otherwise.
+ */
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmod, cp, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import * as path from "node:path";
+import { availableKinds, findAgent, packageLaunchSpec, selectBinaryTarget, } from "./registry.js";
+/**
+ * Where downloaded agents live, unless overridden.
+ *
+ * Follows each platform's own convention: `%LOCALAPPDATA%` on Windows,
+ * `XDG_CACHE_HOME` where it is set, and `~/.cache` otherwise.
+ */
+export function defaultCacheDir(platform = process.platform, env = process.env) {
+    const base = platform === "win32"
+        ? env.LOCALAPPDATA || path.join(homedir(), "AppData", "Local")
+        : env.XDG_CACHE_HOME || path.join(homedir(), ".cache");
+    return path.join(base, "acp-gateway", "agents");
+}
+/**
+ * Classifies an archive by its URL.
+ *
+ * The registry documents exactly which formats may appear; anything else is a
+ * raw executable to be saved as-is.
+ */
+export function archiveKind(url) {
+    const pathname = url.split("?")[0].split("#")[0].toLowerCase();
+    if (pathname.endsWith(".zip"))
+        return "zip";
+    if (pathname.endsWith(".tar.gz") || pathname.endsWith(".tgz"))
+        return "tar.gz";
+    if (pathname.endsWith(".tar.bz2") || pathname.endsWith(".tbz2"))
+        return "tar.bz2";
+    return "raw";
+}
+/** The directory one agent build is unpacked into. */
+export function installDir(cacheDir, agentId, target, version) {
+    // The version is part of the path so a registry bump installs alongside the
+    // old build rather than half-overwriting it.
+    return path.join(cacheDir, `${agentId}@${version}`, target);
+}
+/**
+ * Resolves the registry's `cmd` inside the install directory.
+ *
+ * `cmd` is third-party text, so a path that climbs out of the directory — and
+ * would have us run something else entirely — is rejected rather than resolved.
+ */
+export function resolveExecutable(dir, cmd) {
+    const executable = path.resolve(dir, cmd);
+    const root = path.resolve(dir);
+    if (executable !== root && !executable.startsWith(root + path.sep)) {
+        throw new Error(`Agent command "${cmd}" points outside its install directory; refusing to run it.`);
+    }
+    return executable;
+}
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/**
+ * Refuses an archive we cannot vouch for.
+ *
+ * Roughly half the registry's binary targets publish no checksum. Running one
+ * means trusting whatever the vendor's host served, so it takes an explicit
+ * opt-in rather than happening quietly.
+ */
+export function assertVerifiable(agent, target, allowUnverified) {
+    if (target.sha256 || allowUnverified)
+        return;
+    throw new Error(`The ACP registry publishes no sha256 for "${agent.id}" on this platform, so the ` +
+        `download cannot be verified. Re-run with --allow-unverified-agent to install it anyway, ` +
+        `or install the agent yourself and pass it after --.`);
+}
+/** Checks a download against the registry's checksum. */
+export function assertChecksum(agent, target, data) {
+    if (!target.sha256)
+        return;
+    const actual = sha256(data);
+    if (actual.toLowerCase() !== target.sha256.toLowerCase()) {
+        throw new Error(`Checksum mismatch for "${agent.id}": the registry expects ${target.sha256.toLowerCase()} ` +
+            `but ${target.archive} produced ${actual}. Refusing to run it.`);
+    }
+}
+/** Downloads an archive into memory so it can be checksummed before it touches disk. */
+export async function downloadArchive(url, fetchImpl = fetch) {
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+/** Runs an extraction tool, failing with its own diagnostics attached. */
+export async function runExtractionTool(command, args, cwd) {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    await new Promise((resolve, reject) => {
+        child.on("error", (err) => reject(new Error(`Could not run "${command}" to unpack the agent archive: ${err.message}. ` +
+            `Install it, or install the agent yourself and pass it after --.`)));
+        child.on("exit", (code) => {
+            if (code === 0)
+                return resolve();
+            reject(new Error(`"${command}" failed to unpack the agent archive (code=${code}): ${stderr.trim()}`));
+        });
+    });
+}
+/**
+ * Unpacks an archive into `dir`.
+ *
+ * Uses the system's own tools rather than adding archive libraries as
+ * dependencies. `tar` handles the tarballs everywhere and zips on macOS and
+ * Windows, where it is bsdtar; GNU tar cannot read zips, so Linux falls back
+ * to `unzip`.
+ */
+export async function extractArchive(data, kind, dir, cmd, platform = process.platform) {
+    await mkdir(dir, { recursive: true });
+    if (kind === "raw") {
+        // No archive to unpack: the download is the executable itself.
+        await writeFile(path.join(dir, path.basename(cmd)), data);
+        return;
+    }
+    const archivePath = path.join(dir, `archive.${kind}`);
+    await writeFile(archivePath, data);
+    try {
+        if (kind === "zip" && platform === "linux") {
+            await runExtractionTool("unzip", ["-q", "-o", archivePath], dir);
+        }
+        else {
+            await runExtractionTool("tar", ["-xf", archivePath], dir);
+        }
+    }
+    finally {
+        await rm(archivePath, { force: true });
+    }
+}
+/**
+ * Makes a registry agent runnable, returning the command that launches it.
+ *
+ * A cached install is reused as-is; the version in the cache path means a
+ * registry bump installs a fresh copy rather than reusing a stale one.
+ */
+export async function installBinaryAgent({ agent, target, platformTarget, cacheDir, allowUnverified = false, fetchImpl = fetch, platform = process.platform, }) {
+    cacheDir ??= defaultCacheDir(platform);
+    const dir = installDir(cacheDir, agent.id, platformTarget, agent.version);
+    const executable = resolveExecutable(dir, target.cmd);
+    const spec = {
+        command: executable,
+        args: target.args ?? [],
+        env: target.env,
+        kind: "binary",
+    };
+    if (existsSync(executable)) {
+        console.error(`[registry] Using cached ${agent.id} ${agent.version} from ${dir}`);
+        return spec;
+    }
+    assertVerifiable(agent, target, allowUnverified);
+    console.error(`[registry] Downloading ${agent.id} ${agent.version} from ${target.archive}`);
+    const data = await downloadArchive(target.archive, fetchImpl);
+    assertChecksum(agent, target, data);
+    if (!target.sha256) {
+        console.error(`[registry] ⚠️  ${agent.id} publishes no checksum; installing it unverified at your request.`);
+    }
+    // Unpack somewhere temporary and move into place only once it succeeded, so
+    // a failed extraction never leaves a half-installed agent to be cached.
+    const staging = await mkdtemp(path.join(tmpdir(), `acp-gateway-${agent.id}-`));
+    try {
+        await extractArchive(data, archiveKind(target.archive), staging, target.cmd, platform);
+        const staged = resolveExecutable(staging, target.cmd);
+        if (!existsSync(staged)) {
+            throw new Error(`The archive for "${agent.id}" does not contain "${target.cmd}" where the registry says it should.`);
+        }
+        await rm(dir, { recursive: true, force: true });
+        await mkdir(path.dirname(dir), { recursive: true });
+        await moveInto(staging, dir);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    // Archive formats do not always carry the executable bit. Windows has no
+    // such bit — chmod there only toggles the read-only flag — so skip it.
+    if (platform !== "win32") {
+        await chmod(executable, 0o755);
+    }
+    console.error(`[registry] Installed ${agent.id} ${agent.version} to ${dir}`);
+    return spec;
+}
+/** Moves a staged install into the cache, copying across filesystems if needed. */
+export async function moveInto(from, to) {
+    try {
+        await rename(from, to);
+    }
+    catch {
+        // rename() fails across devices — the temp dir is often a different mount.
+        await cp(from, to, { recursive: true });
+    }
+}
+/**
+ * Turns a registry id into the command that runs that agent, installing it
+ * first where the only distribution is a binary.
+ *
+ * Package distributions are preferred over binaries: npm and PyPI verify what
+ * they serve, and nothing has to be downloaded, unpacked or cached here.
+ */
+export async function resolveAgentLaunch({ id, registry, platformTarget, cacheDir, allowUnverified = false, fetchImpl = fetch, platform = process.platform, }) {
+    const agent = findAgent(registry, id);
+    if (!agent) {
+        throw new Error(`No agent "${id}" in the ACP registry. Run --list-agents to see what it publishes.`);
+    }
+    const kinds = availableKinds(agent, platformTarget);
+    if (!kinds.length) {
+        const published = Object.keys(agent.distribution).join(", ") || "nothing";
+        throw new Error(`The ACP registry publishes no build of "${id}" for ${platformTarget ?? `${process.platform}/${process.arch}`} ` +
+            `(it publishes: ${published}).`);
+    }
+    if (kinds.includes("npx"))
+        return packageLaunchSpec("npx", agent.distribution.npx, platform);
+    if (kinds.includes("uvx"))
+        return packageLaunchSpec("uvx", agent.distribution.uvx, platform);
+    return installBinaryAgent({
+        agent,
+        target: selectBinaryTarget(agent, platformTarget),
+        platformTarget: platformTarget,
+        cacheDir,
+        allowUnverified,
+        fetchImpl,
+        platform,
+    });
+}
+//# sourceMappingURL=agentInstall.js.map

package/dist/agentInstall.js.map

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

package/dist/auth.js

@@ -0,0 +1,189 @@
+/**
+ * auth.ts
+ *
+ * ACP authentication support: reading the login methods an agent advertises
+ * during `initialize`, recognising the protocol's `auth_required` failure, and
+ * running either kind of login on the user's behalf.
+ *
+ * See https://agentclientprotocol.com/protocol/v1/authentication
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+/** JSON-RPC code ACP reserves for "the user must authenticate first". */
+export const AUTH_REQUIRED_CODE = -32000;
+/**
+ * `type` discriminates the two kinds of auth method on the wire, and the
+ * protocol treats a missing `type` as `agent`.
+ */
+export function authMethodType(method) {
+    return method.type === "terminal" ? "terminal" : "agent";
+}
+/** Renders the agent's login options as a numbered list for the terminal. */
+export function describeAuthMethods(methods) {
+    if (!methods?.length) {
+        return "The agent advertises no authentication methods — no login is needed.";
+    }
+    return methods
+        .map((m, i) => {
+        const kind = authMethodType(m) === "terminal" ? " [terminal login]" : "";
+        const description = m.description ? ` — ${m.description}` : "";
+        return `  ${i + 1}. ${m.name} (${m.id})${kind}${description}`;
+    })
+        .join("\n");
+}
+/** Pulls `code`/`message` out of a JSON-RPC failure in either shape it arrives in. */
+function errorParts(err) {
+    if (!err || typeof err !== "object")
+        return { message: "" };
+    const candidate = err;
+    const source = candidate.error && typeof candidate.error === "object"
+        ? candidate.error
+        : candidate;
+    return {
+        code: typeof source.code === "number" ? source.code : undefined,
+        message: typeof source.message === "string" ? source.message : "",
+    };
+}
+/**
+ * Tells an "authenticate first" refusal apart from any other failure.
+ *
+ * ACP carries `auth_required` on the reserved code -32000, which agents also
+ * use for unrelated errors (a denied permission, for one), so the message has
+ * to agree before we send the user through a login.
+ */
+export function isAuthRequiredError(err) {
+    const { code, message } = errorParts(err);
+    return code === AUTH_REQUIRED_CODE && /auth/i.test(message);
+}
+/**
+ * Chooses the login method to run without asking anyone.
+ *
+ * An explicitly named id always wins. Otherwise `agent` methods come first:
+ * the agent drives those itself, so they work in an unattended gateway, while
+ * a `terminal` method needs a human at a TTY.
+ */
+export function pickAuthMethod(methods, { preferredId, allowTerminal = false } = {}) {
+    if (!methods?.length)
+        return undefined;
+    if (preferredId)
+        return methods.find((m) => m.id === preferredId);
+    return (methods.find((m) => authMethodType(m) === "agent") ??
+        (allowTerminal ? methods.find((m) => authMethodType(m) === "terminal") : undefined));
+}
+/** Asks on stderr so the gateway's stdout stays free for its own output. */
+async function askOnTerminal(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Asks the user which login to use, the way an editor would on first run.
+ *
+ * A single method needs no question. An empty answer takes the first method,
+ * and an unrecognised one re-asks rather than logging in with something the
+ * user did not choose.
+ */
+export async function promptForAuthMethod(methods, ask = askOnTerminal) {
+    if (!methods.length)
+        return undefined;
+    if (methods.length === 1)
+        return methods[0];
+    console.error(`\n[auth] The agent requires a login. Available methods:\n${describeAuthMethods(methods)}`);
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = (await ask(`[auth] Choose a method [1-${methods.length}, default 1]: `)).trim();
+        if (!answer)
+            return methods[0];
+        const byIndex = Number(answer);
+        if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= methods.length) {
+            return methods[byIndex - 1];
+        }
+        const byId = methods.find((m) => m.id === answer);
+        if (byId)
+            return byId;
+        console.error(`[auth] "${answer}" is not one of the listed methods.`);
+    }
+    return undefined;
+}
+/**
+ * Runs a `terminal` login by re-launching the configured agent interactively.
+ *
+ * The protocol has the client reproduce its own agent invocation with the
+ * method's extra args and env, hand the process the user's terminal, and read
+ * success off the exit status.
+ */
+export async function runTerminalAuth(method, launch) {
+    const extra = method.args ?? [];
+    const extraEnv = method.env ?? {};
+    const args = [...launch.args, ...extra];
+    console.error(`[auth] Running terminal login: ${launch.command} ${args.join(" ")}\n` +
+        `[auth] Complete the login in your terminal; the gateway resumes when it exits.`);
+    const child = spawn(launch.command, args, {
+        stdio: "inherit",
+        env: { ...process.env, ...launch.env, ...extraEnv },
+    });
+    await new Promise((resolve, reject) => {
+        child.on("error", (err) => reject(new Error(`Terminal login "${method.id}" failed to start: ${err.message}`)));
+        child.on("exit", (code, signal) => {
+            if (code === 0)
+                return resolve();
+            reject(new Error(`Terminal login "${method.id}" failed (code=${code}, signal=${signal}).`));
+        });
+    });
+}
+/** Runs whichever kind of login the chosen method calls for. */
+export async function runAuthMethod(connection, method, launch) {
+    if (authMethodType(method) === "terminal") {
+        await runTerminalAuth(method, launch);
+    }
+    else {
+        // A `terminal` method must never reach `authenticate` — the agent does not
+        // implement one for it.
+        await connection.authenticate({ methodId: method.id });
+    }
+    console.error(`[auth] Logged in with "${method.name}" (${method.id}).`);
+}
+/**
+ * Logs in: picks a method — asking the user when one is there to ask — and
+ * runs it. Returns the method used, or undefined when the agent advertises no
+ * login at all.
+ */
+export async function login({ connection, methods, launch, preferredId, interactive = false, ask, }) {
+    if (!methods?.length) {
+        console.error("[auth] The agent advertises no authentication methods; nothing to log in to.");
+        return undefined;
+    }
+    let method = pickAuthMethod(methods, { preferredId, allowTerminal: interactive });
+    if (preferredId && !method) {
+        throw new Error(`Unknown authentication method "${preferredId}". Available:\n${describeAuthMethods(methods)}`);
+    }
+    if (!preferredId && interactive) {
+        method = await promptForAuthMethod(methods, ask);
+    }
+    if (!method) {
+        throw new Error(`No usable authentication method. Available:\n${describeAuthMethods(methods)}\n` +
+            `Terminal logins need an interactive terminal; re-run acp-gateway from one, ` +
+            `or pass --auth-method <id>.`);
+    }
+    await runAuthMethod(connection, method, launch);
+    return method;
+}
+/** Whether the agent said it implements `logout` during `initialize`. */
+export function supportsLogout(agentCapabilities) {
+    const auth = agentCapabilities?.auth;
+    return auth?.logout !== undefined && auth?.logout !== null;
+}
+/** Ends the agent's authenticated state, if it implements logout. */
+export async function logout(connection, agentCapabilities) {
+    if (!supportsLogout(agentCapabilities)) {
+        console.error("[auth] The agent does not support logout.");
+        return false;
+    }
+    await connection.logout({});
+    console.error("[auth] Logged out.");
+    return true;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/config.js

@@ -6,6 +6,8 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+/** The MCP transports ACP defines that this gateway knows how to hand over. */
+export const MCP_TRANSPORTS = ["http", "sse", "stdio"];
 /**
  * Find and parse the .mcp.json config file.
  * Searches CWD and then up to 3 parent directories.
@@ -18,29 +20,61 @@ export function loadMcpConfig(startDir = process.cwd()) {
         resolve(startDir, "..", "..", "..", ".mcp.json"),
     ];
     for (const candidate of candidates) {
+        // Only reading and parsing may fall through to the next candidate. What the
+        // file *says* is a separate matter: once a .mcp.json has been found, a
+        // mistake inside it is reported rather than hidden behind "no config found".
+        let parsed;
         try {
-            const raw = readFileSync(candidate, "utf-8");
-            const parsed = JSON.parse(raw);
-            const servers = Object.entries(parsed.mcpServers ?? {}).map(([name, cfg]) => ({
-                name,
-                type: cfg.type ?? (cfg.url ? "http" : "stdio"),
-                url: cfg.url,
-                command: cfg.command,
-                args: cfg.args,
-                env: cfg.env,
-                headers: cfg.headers,
-            }));
-            if (servers.length > 0) {
-                console.error(`[config] Loaded .mcp.json from ${candidate}`);
-                return servers;
-            }
+            parsed = JSON.parse(readFileSync(candidate, "utf-8"));
         }
         catch {
-            // Not found here, try next
+            continue;
+        }
+        const servers = Object.entries(parsed.mcpServers ?? {}).map(([name, cfg]) => ({
+            name,
+            type: readTransport(name, cfg.type, cfg.url),
+            url: cfg.url,
+            command: cfg.command,
+            args: cfg.args,
+            env: cfg.env,
+            headers: cfg.headers,
+        }));
+        servers.forEach(assertUsable);
+        if (servers.length > 0) {
+            console.error(`[config] Loaded .mcp.json from ${candidate}`);
+            return servers;
         }
     }
     throw new Error("Could not find .mcp.json — run acp-gateway from your workspace root");
 }
+/**
+ * Reads an entry's transport, defaulting the way MCP clients conventionally do.
+ *
+ * An unknown transport is refused here rather than quietly treated as stdio,
+ * which produced a server with no command and an agent that could not say why.
+ */
+function readTransport(name, type, url) {
+    if (type === undefined)
+        return url ? "http" : "stdio";
+    if (MCP_TRANSPORTS.includes(type))
+        return type;
+    throw new Error(`MCP server "${name}" in .mcp.json has transport "${type}", which this gateway ` +
+        `cannot hand to an agent. Use one of: ${MCP_TRANSPORTS.join(", ")}.`);
+}
+/**
+ * Refuses an entry the agent could never connect to.
+ *
+ * The gateway passes these straight through to the agent, so an entry missing
+ * the one field its transport needs fails inside the agent, long after the
+ * mistake was made and with nothing to point at.
+ */
+function assertUsable(server) {
+    const missing = server.type === "stdio" ? !server.command : !server.url;
+    if (!missing)
+        return;
+    const field = server.type === "stdio" ? "command" : "url";
+    throw new Error(`MCP server "${server.name}" in .mcp.json is ${server.type} but has no ${field}.`);
+}
 /**
  * Pick the primary agentrq MCP server from the list.
  * Prefers servers with "agentrq" in the name; falls back to the first HTTP server.

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAQ,GAAW,OAAO,CAAC,GAAG,EAAE;IAC5D,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC9B,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,CAAC;QACpC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;QAC1C,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;KACjD,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxC,MAAM,OAAO,GAAsB,MAAM,CAAC,OAAO,CAC/C,MAAM,CAAC,UAAU,IAAI,EAAE,CACxB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;gBACtB,IAAI;gBACJ,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC9C,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,OAAO,EAAE,GAAG,CAAC,OAAO;aACrB,CAAC,CAAC,CAAC;YAEJ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,kCAAkC,SAAS,EAAE,CAAC,CAAC;gBAC7D,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA0B;IAE1B,8BAA8B;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,CAC9E,CAAC;IACF,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,iCAAiC;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,IAAI,KAAK,CACb,4FAA4F,CAC7F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAU,CAAC;AA4BhE;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAQ,GAAW,OAAO,CAAC,GAAG,EAAE;IAC5D,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC9B,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,CAAC;QACpC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;QAC1C,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;KACjD,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,4EAA4E;QAC5E,uEAAuE;QACvE,6EAA6E;QAC7E,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAsB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAC5E,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;YAChB,IAAI;YACJ,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC;YAC5C,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CACH,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAE9B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,kCAAkC,SAAS,EAAE,CAAC,CAAC;YAC7D,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,qEAAqE,CACtE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CACpB,IAAY,EACZ,IAAwB,EACxB,GAAuB;IAEvB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACtD,IAAK,cAAoC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAoB,CAAC;IACtF,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,iCAAiC,IAAI,wBAAwB;QAC9E,wCAAwC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,MAAuB;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACxE,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1D,MAAM,IAAI,KAAK,CACb,eAAe,MAAM,CAAC,IAAI,qBAAqB,MAAM,CAAC,IAAI,eAAe,KAAK,GAAG,CAClF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA0B;IAE1B,8BAA8B;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,CAC9E,CAAC;IACF,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IAExB,iCAAiC;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,IAAI,KAAK,CACb,4FAA4F,CAC7F,CAAC;AACJ,CAAC"}