dexe-mcp 0.7.2 → 0.8.1

package/dist/diag/checks.js

@@ -0,0 +1,387 @@
+import { resolve as dnsResolve } from "node:dns/promises";
+import { ENV_REGISTRY } from "../env/schema.js";
+import { parseEnv } from "../env/parse.js";
+/**
+ * Run every diagnostic check in parallel, gather results.
+ *
+ * Network checks have a hard timeout that downgrades to `warn`, never `fail` —
+ * an offline laptop or VPN flake should not make the doctor scream red.
+ */
+export async function runAllChecks(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    const results = [];
+    results.push(...envPresenceChecks());
+    const network = await Promise.all([
+        ...rpcReachabilityChecks(opts.config, timeoutMs),
+        pinataJwtCheck(timeoutMs),
+        ipfsGatewayDnsCheck(timeoutMs),
+        ...subgraphChecks(timeoutMs),
+        backendCheck(timeoutMs),
+    ]);
+    for (const r of network) {
+        if (r)
+            results.push(r);
+    }
+    results.push(...signerGuardConfigCheck());
+    results.push(...chainConsistencyCheck(opts.config));
+    return results;
+}
+// ─── presence ───────────────────────────────────────────────────────────────
+function envPresenceChecks() {
+    const out = [];
+    const parsed = parseEnv();
+    for (const [k, v] of Object.entries(ENV_REGISTRY)) {
+        const set = !!process.env[k]?.trim();
+        const issue = parsed.issues.find(i => i.key === k);
+        if (issue) {
+            out.push({
+                id: `env.${k}`,
+                category: v.category,
+                status: "fail",
+                message: issue.message,
+                remediation: `Fix ${k} in .env. ${v.doc}`,
+            });
+        }
+        else if (set) {
+            out.push({
+                id: `env.${k}`,
+                category: v.category,
+                status: "pass",
+                message: v.secret ? "set (redacted)" : "set",
+            });
+        }
+        else if (v.required) {
+            out.push({
+                id: `env.${k}`,
+                category: v.category,
+                status: "fail",
+                message: "not set (required)",
+                remediation: `Add ${k}=${v.example} to .env. ${v.doc}`,
+            });
+        }
+        // optional + unset: emit nothing (avoid noise)
+    }
+    return out;
+}
+// ─── rpc reachability ──────────────────────────────────────────────────────
+function rpcReachabilityChecks(config, timeoutMs) {
+    if (!config || config.chains.size === 0)
+        return [];
+    const out = [];
+    for (const chain of config.chains.values()) {
+        out.push((async () => {
+            const res = await fetchJsonWithTimeout(chain.rpcUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }),
+            }, timeoutMs);
+            if (res.kind === "timeout") {
+                return {
+                    id: `rpc.reachable.${chain.chainId}`,
+                    category: "network",
+                    status: "warn",
+                    message: `RPC ${chain.rpcUrl} timed out after ${timeoutMs}ms`,
+                    remediation: "Check connectivity. If intermittent, ignore. Otherwise pick a different RPC at https://chainlist.org.",
+                };
+            }
+            if (res.kind === "error") {
+                return {
+                    id: `rpc.reachable.${chain.chainId}`,
+                    category: "network",
+                    status: "fail",
+                    message: `RPC ${chain.rpcUrl} unreachable: ${res.error}`,
+                    remediation: "Replace the RPC URL. Browse alternatives at https://chainlist.org and restart the MCP.",
+                };
+            }
+            const expected = `0x${chain.chainId.toString(16)}`;
+            const got = res.body?.result;
+            if (got !== expected) {
+                return {
+                    id: `rpc.reachable.${chain.chainId}`,
+                    category: "network",
+                    status: "fail",
+                    message: `RPC returned chainId=${got ?? "?"} but configured chainId=${chain.chainId}`,
+                    remediation: `RPC at ${chain.rpcUrl} is for the wrong chain. Replace it.`,
+                };
+            }
+            return {
+                id: `rpc.reachable.${chain.chainId}`,
+                category: "network",
+                status: "pass",
+                message: `eth_chainId=${chain.chainId} (${chain.rpcUrl})`,
+            };
+        })());
+    }
+    return out;
+}
+// ─── pinata jwt ──────────────────────────────────────────────────────────
+async function pinataJwtCheck(timeoutMs) {
+    const jwt = process.env.DEXE_PINATA_JWT?.trim();
+    if (!jwt)
+        return null;
+    const res = await fetchJsonWithTimeout("https://api.pinata.cloud/data/testAuthentication", { method: "GET", headers: { Authorization: `Bearer ${jwt}` } }, timeoutMs);
+    if (res.kind === "timeout") {
+        return {
+            id: "pinata.jwt",
+            category: "ipfs",
+            status: "warn",
+            message: `Pinata auth check timed out (${timeoutMs}ms)`,
+        };
+    }
+    if (res.kind === "error") {
+        return {
+            id: "pinata.jwt",
+            category: "ipfs",
+            status: "fail",
+            message: `Pinata reachability: ${res.error}`,
+        };
+    }
+    if (res.status >= 400) {
+        return {
+            id: "pinata.jwt",
+            category: "ipfs",
+            status: "fail",
+            message: `Pinata testAuthentication returned HTTP ${res.status}`,
+            remediation: "Regenerate the JWT at https://app.pinata.cloud/developers/api-keys with `pinning` scope and update DEXE_PINATA_JWT.",
+        };
+    }
+    return { id: "pinata.jwt", category: "ipfs", status: "pass", message: "authenticated" };
+}
+// ─── ipfs gateway dns ──────────────────────────────────────────────────────
+async function ipfsGatewayDnsCheck(timeoutMs) {
+    const gw = process.env.DEXE_IPFS_GATEWAY?.trim();
+    if (!gw)
+        return null;
+    let host;
+    try {
+        host = new URL(gw).hostname;
+    }
+    catch {
+        return {
+            id: "ipfs.gateway.dns",
+            category: "ipfs",
+            status: "fail",
+            message: "DEXE_IPFS_GATEWAY is not a valid URL",
+            remediation: "Use the form https://<subdomain>.mypinata.cloud",
+        };
+    }
+    try {
+        await Promise.race([
+            dnsResolve(host),
+            new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), timeoutMs)),
+        ]);
+        return {
+            id: "ipfs.gateway.dns",
+            category: "ipfs",
+            status: "pass",
+            message: `resolved ${host}`,
+        };
+    }
+    catch (err) {
+        return {
+            id: "ipfs.gateway.dns",
+            category: "ipfs",
+            status: "fail",
+            message: `DNS lookup for ${host} failed: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: "Check the hostname in DEXE_IPFS_GATEWAY. Pinata dedicated gateways follow https://<subdomain>.mypinata.cloud.",
+        };
+    }
+}
+// ─── subgraph reachability ─────────────────────────────────────────────────
+function subgraphChecks(timeoutMs) {
+    const out = [];
+    const targets = [
+        { key: "DEXE_SUBGRAPH_POOLS_URL", id: "subgraph.pools" },
+        { key: "DEXE_SUBGRAPH_VALIDATORS_URL", id: "subgraph.validators" },
+        { key: "DEXE_SUBGRAPH_INTERACTIONS_URL", id: "subgraph.interactions" },
+    ];
+    const apiKey = process.env.DEXE_GRAPH_API_KEY?.trim();
+    for (const t of targets) {
+        const url = process.env[t.key]?.trim();
+        if (!url)
+            continue;
+        out.push((async () => {
+            const headers = { "content-type": "application/json" };
+            if (apiKey)
+                headers.Authorization = `Bearer ${apiKey}`;
+            const res = await fetchJsonWithTimeout(url, { method: "POST", headers, body: JSON.stringify({ query: "{ __typename }" }) }, timeoutMs);
+            if (res.kind === "timeout") {
+                return {
+                    id: `${t.id}.reachable`,
+                    category: "network",
+                    status: "warn",
+                    message: `${t.key} timed out`,
+                };
+            }
+            if (res.kind === "error") {
+                return {
+                    id: `${t.id}.reachable`,
+                    category: "network",
+                    status: "fail",
+                    message: `${t.key}: ${res.error}`,
+                };
+            }
+            if (res.status >= 400) {
+                return {
+                    id: `${t.id}.reachable`,
+                    category: "network",
+                    status: "fail",
+                    message: `${t.key} returned HTTP ${res.status}`,
+                    remediation: "Check the URL and DEXE_GRAPH_API_KEY (decentralized gateway requires Bearer auth).",
+                };
+            }
+            return {
+                id: `${t.id}.reachable`,
+                category: "network",
+                status: "pass",
+                message: "ok",
+            };
+        })());
+    }
+    return out;
+}
+// ─── backend ─────────────────────────────────────────────────────────────
+async function backendCheck(timeoutMs) {
+    const url = process.env.DEXE_BACKEND_API_URL?.trim();
+    if (!url)
+        return null;
+    const target = url.replace(/\/+$/, "") + "/";
+    const res = await fetchJsonWithTimeout(target, { method: "GET" }, timeoutMs);
+    if (res.kind === "timeout") {
+        return {
+            id: "backend.reachable",
+            category: "network",
+            status: "warn",
+            message: `${url} timed out`,
+        };
+    }
+    if (res.kind === "error") {
+        return {
+            id: "backend.reachable",
+            category: "network",
+            status: "fail",
+            message: `${url}: ${res.error}`,
+        };
+    }
+    return {
+        id: "backend.reachable",
+        category: "network",
+        status: "pass",
+        message: `HTTP ${res.status}`,
+    };
+}
+// ─── signer broadcast guards ─────────────────────────────────────────────
+function signerGuardConfigCheck() {
+    const out = [];
+    const allow = process.env.DEXE_SIGNER_ALLOWLIST?.trim();
+    if (allow) {
+        const entries = allow.split(",").map(s => s.trim()).filter(Boolean);
+        const bad = entries.filter(e => !/^0x[0-9a-fA-F]{40}$/.test(e));
+        if (bad.length) {
+            out.push({
+                id: "signer.allowlist",
+                category: "signer",
+                status: "fail",
+                message: `invalid address(es): ${bad.join(", ")}`,
+            });
+        }
+        else {
+            out.push({
+                id: "signer.allowlist",
+                category: "signer",
+                status: "pass",
+                message: `${entries.length} addr(s) allowed`,
+            });
+        }
+    }
+    const maxV = process.env.DEXE_SIGNER_MAX_VALUE_WEI?.trim();
+    if (maxV) {
+        try {
+            BigInt(maxV);
+            out.push({
+                id: "signer.maxValue",
+                category: "signer",
+                status: "pass",
+                message: `cap=${maxV} wei`,
+            });
+        }
+        catch {
+            out.push({
+                id: "signer.maxValue",
+                category: "signer",
+                status: "fail",
+                message: `not a wei integer: ${maxV}`,
+            });
+        }
+    }
+    const rate = process.env.DEXE_SIGNER_MAX_BROADCASTS_PER_MIN?.trim();
+    if (rate) {
+        const n = Number(rate);
+        if (Number.isInteger(n) && n > 0) {
+            out.push({
+                id: "signer.rate",
+                category: "signer",
+                status: "pass",
+                message: `${n}/min`,
+            });
+        }
+        else {
+            out.push({
+                id: "signer.rate",
+                category: "signer",
+                status: "fail",
+                message: `not a positive int: ${rate}`,
+            });
+        }
+    }
+    return out;
+}
+// ─── chain consistency ───────────────────────────────────────────────────
+function chainConsistencyCheck(config) {
+    if (!config)
+        return [];
+    const out = [];
+    if (process.env.DEXE_PRIVATE_KEY?.trim() && config.chains.size === 0) {
+        out.push({
+            id: "chain.signerNeedsRpc",
+            category: "signer",
+            status: "fail",
+            message: "DEXE_PRIVATE_KEY is set but no RPC is configured — broadcasts will fail.",
+            remediation: "Set DEXE_RPC_URL_TESTNET or DEXE_RPC_URL_MAINNET in .env.",
+        });
+    }
+    if (config.chains.size > 0) {
+        const ids = [...config.chains.keys()].sort((a, b) => a - b);
+        out.push({
+            id: "chain.consistency",
+            category: "rpc",
+            status: "pass",
+            message: `defaultChainId=${config.defaultChainId} in configured=[${ids.join(", ")}]`,
+        });
+    }
+    return out;
+}
+async function fetchJsonWithTimeout(url, init, timeoutMs) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const r = await fetch(url, { ...init, signal: ctrl.signal });
+        let body = undefined;
+        try {
+            body = await r.json();
+        }
+        catch {
+            // not json — ignore
+        }
+        return { kind: "ok", status: r.status, body };
+    }
+    catch (err) {
+        if (err.name === "AbortError")
+            return { kind: "timeout" };
+        return { kind: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=checks.js.map

package/dist/diag/checks.js.map

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

package/dist/env/loader.d.ts

@@ -0,0 +1,43 @@
+import { type EnvKey } from "./schema.js";
+/**
+ * Diagnostic report produced by `loadEnvFile`. Written to stderr by
+ * `writeStartupBanner` and surfaced via `dexe_doctor`.
+ */
+export interface EnvLoadReport {
+    envFilePath: string;
+    envFileExists: boolean;
+    envFileLoaded: boolean;
+    loadedNodeVersion: string;
+    /** Raw-byte parse warnings (BOM, missing trailing newline, spaces around =). */
+    parseWarnings: string[];
+    /** DEXE_* vars in process.env that ENV_SPEC does not know about. */
+    unknownDexeVars: string[];
+    /** Vars that are NOT set but would unlock a common flow if they were. */
+    missingButEnablesFlows: Array<{
+        key: EnvKey;
+        flows: readonly string[];
+    }>;
+    /**
+     * Schema keys that were already in process.env BEFORE .env was loaded —
+     * meaning they were injected by the MCP host (.claude.json env block) and
+     * SHADOW the .env file. Subtle precedence trap.
+     */
+    preExistingVars: EnvKey[];
+}
+/**
+ * Read .env from disk, scan its raw bytes for common parse-traps, then call
+ * `process.loadEnvFile()`. Never throws; surfaces problems via the returned
+ * report so the startup banner and doctor can show them.
+ *
+ * @param envFilePath  absolute path to the .env file
+ * @param prevEnvSnapshot  set of DEXE_* keys that were already in
+ *   `process.env` before this function runs. Pass an empty set to skip the
+ *   precedence-collision check.
+ */
+export declare function loadEnvFile(envFilePath: string, prevEnvSnapshot: ReadonlySet<string>): EnvLoadReport;
+/**
+ * Print a one-banner summary of `loadEnvFile`'s findings to stderr. stdout
+ * is the MCP protocol channel — never write to it.
+ */
+export declare function writeStartupBanner(report: EnvLoadReport): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/env/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/env/loader.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,MAAM,EAEZ,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,yEAAyE;IACzE,sBAAsB,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACzE;;;;OAIG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,aAAa,CA2Ff;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CA6B9D"}

package/dist/env/loader.js

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from "node:fs";
+import { ENV_REGISTRY, DYNAMIC_PER_CHAIN_RPC_RE, envKeys, isKnownEnvKey, } from "./schema.js";
+/**
+ * Read .env from disk, scan its raw bytes for common parse-traps, then call
+ * `process.loadEnvFile()`. Never throws; surfaces problems via the returned
+ * report so the startup banner and doctor can show them.
+ *
+ * @param envFilePath  absolute path to the .env file
+ * @param prevEnvSnapshot  set of DEXE_* keys that were already in
+ *   `process.env` before this function runs. Pass an empty set to skip the
+ *   precedence-collision check.
+ */
+export function loadEnvFile(envFilePath, prevEnvSnapshot) {
+    const parseWarnings = [];
+    const envFileExists = existsSync(envFilePath);
+    let envFileLoaded = false;
+    if (envFileExists) {
+        try {
+            const raw = readFileSync(envFilePath);
+            // UTF-8 BOM — process.loadEnvFile may misparse the first key.
+            if (raw.length >= 3 && raw[0] === 0xef && raw[1] === 0xbb && raw[2] === 0xbf) {
+                parseWarnings.push(".env begins with a UTF-8 BOM — process.loadEnvFile may misparse the first line. " +
+                    "Re-save the file without BOM.");
+            }
+            // Missing trailing newline — Node silently drops the last line.
+            if (raw.length > 0 && raw[raw.length - 1] !== 0x0a /* \n */) {
+                parseWarnings.push(".env does not end with a newline — process.loadEnvFile silently drops the last line. " +
+                    "Add a trailing newline to fix.");
+            }
+            // Spaces around `=` produce surprising values.
+            const spaceLines = [];
+            raw
+                .toString("utf8")
+                .split(/\r?\n/)
+                .forEach((line, i) => {
+                if (!line || line.trimStart().startsWith("#"))
+                    return;
+                if (/^\s*[A-Za-z_][A-Za-z0-9_]*\s+=/.test(line) ||
+                    /^\s*[A-Za-z_][A-Za-z0-9_]*=\s/.test(line)) {
+                    spaceLines.push(i + 1);
+                }
+            });
+            if (spaceLines.length) {
+                parseWarnings.push(`.env has spaces around \`=\` on line(s) ${spaceLines.join(", ")} — values may include leading/trailing whitespace. Remove the spaces.`);
+            }
+        }
+        catch (err) {
+            parseWarnings.push(`.env is unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            process.loadEnvFile(envFilePath);
+            envFileLoaded = true;
+        }
+        catch (err) {
+            parseWarnings.push(`process.loadEnvFile failed (Node < 21.7 or syntax error): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // DEXE_* vars present that we don't recognize (typos, deprecated keys).
+    const unknownDexeVars = [];
+    for (const key of Object.keys(process.env)) {
+        if (!key.startsWith("DEXE_"))
+            continue;
+        if (DYNAMIC_PER_CHAIN_RPC_RE.test(key))
+            continue;
+        if (!isKnownEnvKey(key))
+            unknownDexeVars.push(key);
+    }
+    // Vars NOT set but which would enable a common flow.
+    const missingButEnablesFlows = [];
+    for (const [k, v] of Object.entries(ENV_REGISTRY)) {
+        if (!v.enablesFlows?.length)
+            continue;
+        if (process.env[k]?.trim())
+            continue;
+        missingButEnablesFlows.push({ key: k, flows: v.enablesFlows });
+    }
+    // Schema keys present in process.env BEFORE we loaded .env — they came
+    // from the MCP host (.claude.json env block) and will shadow .env.
+    const preExistingVars = envKeys().filter(k => prevEnvSnapshot.has(k));
+    return {
+        envFilePath,
+        envFileExists,
+        envFileLoaded,
+        loadedNodeVersion: process.version,
+        parseWarnings,
+        unknownDexeVars,
+        missingButEnablesFlows,
+        preExistingVars,
+    };
+}
+/**
+ * Print a one-banner summary of `loadEnvFile`'s findings to stderr. stdout
+ * is the MCP protocol channel — never write to it.
+ */
+export function writeStartupBanner(report) {
+    const w = (s) => {
+        process.stderr.write(`[dexe-mcp] ${s}\n`);
+    };
+    if (!report.envFileExists) {
+        w(`no .env at ${report.envFilePath} — using process env only`);
+    }
+    else if (report.envFileLoaded) {
+        w(`loaded .env from ${report.envFilePath} (Node ${report.loadedNodeVersion})`);
+    }
+    else {
+        w(`.env present but not loaded — see warnings below`);
+    }
+    for (const wmsg of report.parseWarnings) {
+        w(`warn: ${wmsg}`);
+    }
+    if (report.unknownDexeVars.length) {
+        w(`warn: unrecognized DEXE_* vars (typo or deprecated): ${report.unknownDexeVars.join(", ")}. Run dexe_doctor for details.`);
+    }
+    if (report.preExistingVars.length) {
+        w(`warn: [${report.preExistingVars.join(", ")}] were set by the MCP host env block ` +
+            `and will SHADOW .env. process.loadEnvFile does not override pre-set values. ` +
+            `Remove them from .claude.json to use .env values, or update them there. ` +
+            `Run dexe_doctor for details.`);
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/env/loader.js.map

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

package/dist/env/parse.d.ts

@@ -0,0 +1,23 @@
+import { type EnvKey } from "./schema.js";
+export interface EnvIssue {
+    key: EnvKey;
+    severity: "error" | "warn";
+    message: string;
+}
+export interface EnvParseResult {
+    /** Trimmed raw values for every key that passed validation. */
+    values: Partial<Record<EnvKey, string>>;
+    /** All validation failures + missing-required warnings. */
+    issues: EnvIssue[];
+}
+/**
+ * Walk ENV_SPEC, run each entry's zod schema against the provided env table,
+ * and collect categorized issues. Pure — no I/O, no logging, no side effects.
+ *
+ * Callers:
+ *   - src/config.ts (startup)
+ *   - src/diag/checks.ts (doctor)
+ *   - tests (parity / regression)
+ */
+export declare function parseEnv(env?: NodeJS.ProcessEnv): EnvParseResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/env/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/env/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAiB,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxC,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,CA+B7E"}

package/dist/env/parse.js

@@ -0,0 +1,41 @@
+import { ENV_REGISTRY } from "./schema.js";
+/**
+ * Walk ENV_SPEC, run each entry's zod schema against the provided env table,
+ * and collect categorized issues. Pure — no I/O, no logging, no side effects.
+ *
+ * Callers:
+ *   - src/config.ts (startup)
+ *   - src/diag/checks.ts (doctor)
+ *   - tests (parity / regression)
+ */
+export function parseEnv(env = process.env) {
+    const values = {};
+    const issues = [];
+    for (const [key, entry] of Object.entries(ENV_REGISTRY)) {
+        const raw = env[key]?.trim();
+        if (!raw) {
+            if (entry.required) {
+                issues.push({
+                    key,
+                    severity: "error",
+                    message: `Required env var ${key} is not set. ${entry.doc}`,
+                });
+            }
+            continue;
+        }
+        const r = entry.schema.safeParse(raw);
+        if (!r.success) {
+            issues.push({
+                key,
+                severity: "error",
+                message: `Invalid ${key}=${entry.secret ? "<redacted>" : raw}: ${r.error.issues
+                    .map(i => i.message)
+                    .join("; ")}`,
+            });
+            continue;
+        }
+        values[key] = raw;
+    }
+    return { values, issues };
+}
+//# sourceMappingURL=parse.js.map

package/dist/env/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/env/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA8B,MAAM,aAAa,CAAC;AAevE;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC3D,MAAM,MAAM,GAAoC,EAAE,CAAC;IACnD,MAAM,MAAM,GAAe,EAAE,CAAC;IAE9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAyB,EAAE,CAAC;QAChF,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG;oBACH,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,KAAK,CAAC,GAAG,EAAE;iBAC5D,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC;gBACV,GAAG;gBACH,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM;qBAC5E,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;qBACnB,IAAI,CAAC,IAAI,CAAC,EAAE;aAChB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}