dexe-mcp 0.7.2 → 0.8.0

package/dist/env/schema.d.ts

@@ -0,0 +1,257 @@
+import { z } from "zod";
+/**
+ * Single source of truth for every DEXE_* env var the MCP recognizes.
+ *
+ * Consumed by:
+ *   - `src/env/parse.ts`  — validation at startup, accumulates issues
+ *   - `src/diag/checks.ts` — `dexe_doctor` walks ENV_SPEC for presence checks
+ *   - `src/lib/requireEnv.ts` — fail-soft tool guards build remediation hints
+ *
+ * To add a new env var: add an entry here, update docs/ENVIRONMENT.md, and
+ * the parity test in tests/env/schema.test.ts will require .env.example to
+ * mention it. Categories drive the .env.example layout and doctor output
+ * grouping.
+ */
+export type EnvCategory = "core" | "rpc" | "signer" | "ipfs" | "subgraph" | "walletconnect" | "safe" | "backend" | "dev";
+/**
+ * Feature surfaces that depend on a given env var. Used by hintFor() to tell
+ * the user which tools light up when the var is set.
+ */
+export type EnvFlow = "read" | "broadcast" | "ipfs-upload" | "ipfs-read" | "subgraph-read" | "dao-deploy" | "safe-tx" | "walletconnect-sign" | "backend-offchain";
+export interface EnvEntry {
+    schema: z.ZodType<unknown>;
+    category: EnvCategory;
+    /** True only for vars without which the MCP cannot start. None today. */
+    required: boolean;
+    /** Placeholder shown in `.env.example`. */
+    example: string;
+    /** One-line description mirrored in docs/ENVIRONMENT.md. */
+    doc: string;
+    /** Which user-visible flows this var unlocks. Doctor + hintFor() use this. */
+    enablesFlows?: readonly EnvFlow[];
+    /** Mask the value when echoing it (banner, doctor, logs). */
+    secret?: boolean;
+}
+export declare const ENV_SPEC: {
+    readonly DEXE_PROTOCOL_PATH: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "core";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Override the DeXe-Protocol checkout path. Auto-managed when unset.";
+    };
+    readonly DEXE_RPC_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "https://bsc-dataseed.binance.org";
+        readonly doc: "Legacy single-chain RPC. Prefer DEXE_RPC_URL_TESTNET / _MAINNET / _<chainId>.";
+        readonly enablesFlows: readonly ["read", "broadcast"];
+    };
+    readonly DEXE_CHAIN_ID: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "56";
+        readonly doc: "Chain id for legacy DEXE_RPC_URL. Inferred from hostname when unset.";
+    };
+    readonly DEXE_RPC_URL_TESTNET: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "https://data-seed-prebsc-1-s1.bnbchain.org:8545";
+        readonly doc: "RPC URL for BSC testnet (chain 97).";
+        readonly enablesFlows: readonly ["read", "broadcast"];
+    };
+    readonly DEXE_RPC_URL_MAINNET: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "https://bsc-dataseed.bnbchain.org";
+        readonly doc: "RPC URL for BSC mainnet (chain 56).";
+        readonly enablesFlows: readonly ["read", "broadcast"];
+    };
+    readonly DEXE_DEFAULT_CHAIN_ID: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "97";
+        readonly doc: "Default chain id when a tool omits chainId. Must match a configured RPC.";
+    };
+    readonly DEXE_CONTRACTS_REGISTRY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "rpc";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Override ContractsRegistry address for the default chain. Rarely needed.";
+    };
+    readonly DEXE_PRIVATE_KEY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "signer";
+        readonly required: false;
+        readonly example: "0x<64-hex>";
+        readonly doc: "Hot EOA key for dexe_tx_send broadcast. Requires an RPC.";
+        readonly enablesFlows: readonly ["broadcast"];
+        readonly secret: true;
+    };
+    readonly DEXE_SIGNER_ALLOWLIST: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "signer";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Comma-separated destination address allowlist for dexe_tx_send (B6 guard).";
+    };
+    readonly DEXE_SIGNER_MAX_VALUE_WEI: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "signer";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Max wei value per broadcast (B7 guard).";
+    };
+    readonly DEXE_SIGNER_MAX_BROADCASTS_PER_MIN: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "signer";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Rate limit broadcasts per rolling minute (B10 guard).";
+    };
+    readonly DEXE_PINATA_JWT: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "ipfs";
+        readonly required: false;
+        readonly example: "eyJhbGciOiJIUzI1NiIs...";
+        readonly doc: "Pinata pinning JWT. Required for IPFS uploads; reads work without it.";
+        readonly enablesFlows: readonly ["ipfs-upload", "dao-deploy"];
+        readonly secret: true;
+    };
+    readonly DEXE_IPFS_GATEWAY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "ipfs";
+        readonly required: false;
+        readonly example: "https://<subdomain>.mypinata.cloud";
+        readonly doc: "Primary IPFS gateway base URL for reads.";
+        readonly enablesFlows: readonly ["ipfs-read"];
+    };
+    readonly DEXE_IPFS_GATEWAYS_FALLBACK: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "ipfs";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Comma-separated public IPFS gateway fallbacks for reads.";
+    };
+    readonly DEXE_PINATA_GATEWAY_TOKEN: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "ipfs";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Auth token for a private Pinata dedicated gateway (optional).";
+        readonly secret: true;
+    };
+    readonly DEXE_IPFS_AVATAR_GATEWAY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "ipfs";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Optional override for the avatar fetch gateway.";
+    };
+    readonly DEXE_SUBGRAPH_POOLS_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "subgraph";
+        readonly required: false;
+        readonly example: "https://gateway.thegraph.com/api/subgraphs/id/<id>";
+        readonly doc: "Pools subgraph endpoint.";
+        readonly enablesFlows: readonly ["subgraph-read"];
+    };
+    readonly DEXE_SUBGRAPH_VALIDATORS_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "subgraph";
+        readonly required: false;
+        readonly example: "https://gateway.thegraph.com/api/subgraphs/id/<id>";
+        readonly doc: "Validators subgraph endpoint.";
+        readonly enablesFlows: readonly ["subgraph-read"];
+    };
+    readonly DEXE_SUBGRAPH_INTERACTIONS_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "subgraph";
+        readonly required: false;
+        readonly example: "https://gateway.thegraph.com/api/subgraphs/id/<id>";
+        readonly doc: "Interactions subgraph endpoint.";
+        readonly enablesFlows: readonly ["subgraph-read"];
+    };
+    readonly DEXE_GRAPH_API_KEY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "subgraph";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "The Graph API key for bearer auth (required by decentralized gateway).";
+        readonly secret: true;
+    };
+    readonly DEXE_WALLETCONNECT_PROJECT_ID: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "walletconnect";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Reown/WalletConnect project id. Enables phone-approval signer when DEXE_PRIVATE_KEY is unset.";
+        readonly enablesFlows: readonly ["walletconnect-sign"];
+    };
+    readonly DEXE_WALLETCONNECT_RELAY_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "walletconnect";
+        readonly required: false;
+        readonly example: "wss://relay.walletconnect.com";
+        readonly doc: "Override WC relay websocket URL.";
+    };
+    readonly DEXE_WALLETCONNECT_APPROVAL_TIMEOUT_MS: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "walletconnect";
+        readonly required: false;
+        readonly example: "120000";
+        readonly doc: "Per-tx phone-approval timeout in milliseconds.";
+    };
+    readonly DEXE_SAFE_TX_SERVICE_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "safe";
+        readonly required: false;
+        readonly example: "https://api.safe.global/tx-service/bnb/api/v2";
+        readonly doc: "Safe Transaction Service base. Required for chains without a hosted service.";
+        readonly enablesFlows: readonly ["safe-tx"];
+    };
+    readonly DEXE_SAFE_API_KEY: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "safe";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Bearer token for Safe Transaction Service.";
+        readonly secret: true;
+    };
+    readonly DEXE_BACKEND_API_URL: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "backend";
+        readonly required: false;
+        readonly example: "https://api.dexe.io";
+        readonly doc: "DeXe backend API root for off-chain proposal flows.";
+        readonly enablesFlows: readonly ["backend-offchain"];
+    };
+    readonly DEXE_FORK_BLOCK: {
+        readonly schema: z.ZodOptional<z.ZodString>;
+        readonly category: "dev";
+        readonly required: false;
+        readonly example: "";
+        readonly doc: "Optional fork block pin (Phase B).";
+    };
+};
+/**
+ * Re-export with the structural interface so consumers see optional fields
+ * (`secret`, `enablesFlows`). `as const` narrows literals but hides any field
+ * not present on every entry, which trips `.secret`/`.enablesFlows` reads.
+ */
+export declare const ENV_REGISTRY: Record<EnvKey, EnvEntry>;
+export type EnvKey = keyof typeof ENV_SPEC;
+export declare function isKnownEnvKey(k: string): k is EnvKey;
+export declare function envKeys(): EnvKey[];
+/**
+ * Pattern for dynamic per-chain RPC keys (DEXE_RPC_URL_1, DEXE_RPC_URL_10…).
+ * Not in ENV_SPEC because the suffix is open-ended.
+ */
+export declare const DYNAMIC_PER_CHAIN_RPC_RE: RegExp;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/env/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,KAAK,GACL,QAAQ,GACR,MAAM,GACN,UAAU,GACV,eAAe,GACf,MAAM,GACN,SAAS,GACT,KAAK,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,OAAO,GACf,MAAM,GACN,WAAW,GACX,aAAa,GACb,WAAW,GACX,eAAe,GACf,YAAY,GACZ,SAAS,GACT,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,QAAQ,EAAE,WAAW,CAAC;IACtB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,YAAY,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAOD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgOwB,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAY,CAAC;AAE/D,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,QAAQ,CAAC;AAE3C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,MAAM,CAEpD;AAED,wBAAgB,OAAO,IAAI,MAAM,EAAE,CAElC;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAyB,CAAC"}

package/dist/env/schema.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+const hex64 = /^0x[0-9a-fA-F]{64}$/;
+const hex40 = /^0x[0-9a-fA-F]{40}$/;
+const intStr = z.string().regex(/^\d+$/);
+const optionalUrl = z.string().url().optional();
+export const ENV_SPEC = {
+    // ─── core / dev ───────────────────────────────────────────────────────────
+    DEXE_PROTOCOL_PATH: {
+        schema: z.string().optional(),
+        category: "core",
+        required: false,
+        example: "",
+        doc: "Override the DeXe-Protocol checkout path. Auto-managed when unset.",
+    },
+    // ─── rpc ──────────────────────────────────────────────────────────────────
+    DEXE_RPC_URL: {
+        schema: optionalUrl,
+        category: "rpc",
+        required: false,
+        example: "https://bsc-dataseed.binance.org",
+        doc: "Legacy single-chain RPC. Prefer DEXE_RPC_URL_TESTNET / _MAINNET / _<chainId>.",
+        enablesFlows: ["read", "broadcast"],
+    },
+    DEXE_CHAIN_ID: {
+        schema: intStr.optional(),
+        category: "rpc",
+        required: false,
+        example: "56",
+        doc: "Chain id for legacy DEXE_RPC_URL. Inferred from hostname when unset.",
+    },
+    DEXE_RPC_URL_TESTNET: {
+        schema: optionalUrl,
+        category: "rpc",
+        required: false,
+        example: "https://data-seed-prebsc-1-s1.bnbchain.org:8545",
+        doc: "RPC URL for BSC testnet (chain 97).",
+        enablesFlows: ["read", "broadcast"],
+    },
+    DEXE_RPC_URL_MAINNET: {
+        schema: optionalUrl,
+        category: "rpc",
+        required: false,
+        example: "https://bsc-dataseed.bnbchain.org",
+        doc: "RPC URL for BSC mainnet (chain 56).",
+        enablesFlows: ["read", "broadcast"],
+    },
+    DEXE_DEFAULT_CHAIN_ID: {
+        schema: intStr.optional(),
+        category: "rpc",
+        required: false,
+        example: "97",
+        doc: "Default chain id when a tool omits chainId. Must match a configured RPC.",
+    },
+    DEXE_CONTRACTS_REGISTRY: {
+        schema: z.string().regex(hex40).optional(),
+        category: "rpc",
+        required: false,
+        example: "",
+        doc: "Override ContractsRegistry address for the default chain. Rarely needed.",
+    },
+    // ─── signer ──────────────────────────────────────────────────────────────
+    DEXE_PRIVATE_KEY: {
+        schema: z.string().regex(hex64).optional(),
+        category: "signer",
+        required: false,
+        example: "0x<64-hex>",
+        doc: "Hot EOA key for dexe_tx_send broadcast. Requires an RPC.",
+        enablesFlows: ["broadcast"],
+        secret: true,
+    },
+    DEXE_SIGNER_ALLOWLIST: {
+        schema: z.string().optional(),
+        category: "signer",
+        required: false,
+        example: "",
+        doc: "Comma-separated destination address allowlist for dexe_tx_send (B6 guard).",
+    },
+    DEXE_SIGNER_MAX_VALUE_WEI: {
+        schema: intStr.optional(),
+        category: "signer",
+        required: false,
+        example: "",
+        doc: "Max wei value per broadcast (B7 guard).",
+    },
+    DEXE_SIGNER_MAX_BROADCASTS_PER_MIN: {
+        schema: intStr.optional(),
+        category: "signer",
+        required: false,
+        example: "",
+        doc: "Rate limit broadcasts per rolling minute (B10 guard).",
+    },
+    // ─── ipfs ────────────────────────────────────────────────────────────────
+    DEXE_PINATA_JWT: {
+        schema: z.string().optional(),
+        category: "ipfs",
+        required: false,
+        example: "eyJhbGciOiJIUzI1NiIs...",
+        doc: "Pinata pinning JWT. Required for IPFS uploads; reads work without it.",
+        enablesFlows: ["ipfs-upload", "dao-deploy"],
+        secret: true,
+    },
+    DEXE_IPFS_GATEWAY: {
+        schema: optionalUrl,
+        category: "ipfs",
+        required: false,
+        example: "https://<subdomain>.mypinata.cloud",
+        doc: "Primary IPFS gateway base URL for reads.",
+        enablesFlows: ["ipfs-read"],
+    },
+    DEXE_IPFS_GATEWAYS_FALLBACK: {
+        schema: z.string().optional(),
+        category: "ipfs",
+        required: false,
+        example: "",
+        doc: "Comma-separated public IPFS gateway fallbacks for reads.",
+    },
+    DEXE_PINATA_GATEWAY_TOKEN: {
+        schema: z.string().optional(),
+        category: "ipfs",
+        required: false,
+        example: "",
+        doc: "Auth token for a private Pinata dedicated gateway (optional).",
+        secret: true,
+    },
+    DEXE_IPFS_AVATAR_GATEWAY: {
+        schema: optionalUrl,
+        category: "ipfs",
+        required: false,
+        example: "",
+        doc: "Optional override for the avatar fetch gateway.",
+    },
+    // ─── subgraph ────────────────────────────────────────────────────────────
+    DEXE_SUBGRAPH_POOLS_URL: {
+        schema: optionalUrl,
+        category: "subgraph",
+        required: false,
+        example: "https://gateway.thegraph.com/api/subgraphs/id/<id>",
+        doc: "Pools subgraph endpoint.",
+        enablesFlows: ["subgraph-read"],
+    },
+    DEXE_SUBGRAPH_VALIDATORS_URL: {
+        schema: optionalUrl,
+        category: "subgraph",
+        required: false,
+        example: "https://gateway.thegraph.com/api/subgraphs/id/<id>",
+        doc: "Validators subgraph endpoint.",
+        enablesFlows: ["subgraph-read"],
+    },
+    DEXE_SUBGRAPH_INTERACTIONS_URL: {
+        schema: optionalUrl,
+        category: "subgraph",
+        required: false,
+        example: "https://gateway.thegraph.com/api/subgraphs/id/<id>",
+        doc: "Interactions subgraph endpoint.",
+        enablesFlows: ["subgraph-read"],
+    },
+    DEXE_GRAPH_API_KEY: {
+        schema: z.string().optional(),
+        category: "subgraph",
+        required: false,
+        example: "",
+        doc: "The Graph API key for bearer auth (required by decentralized gateway).",
+        secret: true,
+    },
+    // ─── walletconnect ───────────────────────────────────────────────────────
+    DEXE_WALLETCONNECT_PROJECT_ID: {
+        schema: z.string().optional(),
+        category: "walletconnect",
+        required: false,
+        example: "",
+        doc: "Reown/WalletConnect project id. Enables phone-approval signer when DEXE_PRIVATE_KEY is unset.",
+        enablesFlows: ["walletconnect-sign"],
+    },
+    DEXE_WALLETCONNECT_RELAY_URL: {
+        schema: optionalUrl,
+        category: "walletconnect",
+        required: false,
+        example: "wss://relay.walletconnect.com",
+        doc: "Override WC relay websocket URL.",
+    },
+    DEXE_WALLETCONNECT_APPROVAL_TIMEOUT_MS: {
+        schema: intStr.optional(),
+        category: "walletconnect",
+        required: false,
+        example: "120000",
+        doc: "Per-tx phone-approval timeout in milliseconds.",
+    },
+    // ─── safe ────────────────────────────────────────────────────────────────
+    DEXE_SAFE_TX_SERVICE_URL: {
+        schema: optionalUrl,
+        category: "safe",
+        required: false,
+        example: "https://api.safe.global/tx-service/bnb/api/v2",
+        doc: "Safe Transaction Service base. Required for chains without a hosted service.",
+        enablesFlows: ["safe-tx"],
+    },
+    DEXE_SAFE_API_KEY: {
+        schema: z.string().optional(),
+        category: "safe",
+        required: false,
+        example: "",
+        doc: "Bearer token for Safe Transaction Service.",
+        secret: true,
+    },
+    // ─── backend ─────────────────────────────────────────────────────────────
+    DEXE_BACKEND_API_URL: {
+        schema: optionalUrl,
+        category: "backend",
+        required: false,
+        example: "https://api.dexe.io",
+        doc: "DeXe backend API root for off-chain proposal flows.",
+        enablesFlows: ["backend-offchain"],
+    },
+    // ─── dev ─────────────────────────────────────────────────────────────────
+    DEXE_FORK_BLOCK: {
+        schema: intStr.optional(),
+        category: "dev",
+        required: false,
+        example: "",
+        doc: "Optional fork block pin (Phase B).",
+    },
+};
+/**
+ * Re-export with the structural interface so consumers see optional fields
+ * (`secret`, `enablesFlows`). `as const` narrows literals but hides any field
+ * not present on every entry, which trips `.secret`/`.enablesFlows` reads.
+ */
+export const ENV_REGISTRY = ENV_SPEC;
+export function isKnownEnvKey(k) {
+    return Object.prototype.hasOwnProperty.call(ENV_SPEC, k);
+}
+export function envKeys() {
+    return Object.keys(ENV_SPEC);
+}
+/**
+ * Pattern for dynamic per-chain RPC keys (DEXE_RPC_URL_1, DEXE_RPC_URL_10…).
+ * Not in ENV_SPEC because the suffix is open-ended.
+ */
+export const DYNAMIC_PER_CHAIN_RPC_RE = /^DEXE_RPC_URL_(\d+)$/;
+//# sourceMappingURL=schema.js.map

package/dist/env/schema.js.map

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

package/dist/index.js

@@ -1,23 +1,43 @@
 #!/usr/bin/env node
 import { resolve, dirname } from "node:path";
-import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./config.js";
 import { registerAll } from "./tools/index.js";
-// Load .env from project root if present — ensures env vars reach the process
-// regardless of how the MCP host launches us (Claude Code drops most env vars
-// from its settings.json "env" block on Windows).
+import { loadEnvFile, writeStartupBanner } from "./env/loader.js";
+import { envKeys } from "./env/schema.js";
+// Snapshot DEXE_* schema keys already in process.env BEFORE we load .env.
+// Anything found here was injected by the MCP host (Claude Code's
+// .claude.json `env` block) and will SHADOW the .env file —
+// `process.loadEnvFile()` does NOT override pre-set keys. The startup banner
+// (and dexe_doctor) surface the collision so users don't chase a phantom
+// "I edited .env and nothing changed" bug.
+//
+// This must run BEFORE the CLI subcommand dispatch below: `npx dexe-mcp
+// doctor` invoked directly from a shell needs the same env as the MCP
+// startup path, otherwise the diagnostic sees an empty config.
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const dotenvPath = resolve(__dirname, "..", ".env");
-if (existsSync(dotenvPath)) {
-    try {
-        process.loadEnvFile(dotenvPath);
-    }
-    catch {
-        // Node < 21.7 or other issue — fall through to process.env as-is
-    }
+const prevSnapshot = new Set(envKeys().filter(k => !!process.env[k]?.trim()));
+const envReport = loadEnvFile(dotenvPath, prevSnapshot);
+writeStartupBanner(envReport);
+// CLI subcommand dispatch. `npx dexe-mcp` (no args) → MCP server.
+// `npx dexe-mcp doctor` → run diagnostics and exit.
+// `npx dexe-mcp init`   → run the onboarding wizard and exit.
+// Keeps a single bin entry instead of shipping parallel scripts.
+// Subcommands must be handled BEFORE the stdio transport opens — the MCP
+// host passes no args, so any argv[2] means a human/CI invoked directly.
+const subcommand = process.argv[2];
+if (subcommand === "doctor") {
+    const mod = await import("./cli/doctor.js");
+    await mod.run();
+    process.exit(0);
+}
+if (subcommand === "init") {
+    const mod = await import("./cli/init.js");
+    await mod.run();
+    process.exit(0);
 }
 async function main() {
     const config = await loadConfig();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,8EAA8E;AAC9E,8EAA8E;AAC9E,kDAAkD;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACpD,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EACtC;QACE,YAAY,EACV,mRAAmR;KACtR,CACF,CAAC;IAEF,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qDAAqD,MAAM,CAAC,YAAY,GACtE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EACrC,IAAI,CACL,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/requireEnv.d.ts

@@ -0,0 +1,30 @@
+import { type EnvKey } from "../env/schema.js";
+/**
+ * Result of a soft env guard. `ok` carries the resolved value; the error
+ * branch carries both a one-line `error` and a multi-line `remediation`
+ * with paste-ready fixes. Tool handlers fold these into MCP `errorResult`.
+ *
+ * Modeled on the long-standing `requirePinata` pattern in
+ * `src/tools/ipfs.ts:129-137` so existing call sites need only a minimal
+ * refactor.
+ */
+export type EnvGuardResult<T> = {
+    ok: T;
+} | {
+    error: string;
+    remediation: string;
+};
+/**
+ * Soft env-var guard. Returns `{ ok }` only when every listed key is present
+ * and non-blank in `process.env`; otherwise returns a remediation hint that
+ * names the missing keys and the flows they unlock.
+ */
+export declare function requireEnv<K extends EnvKey>(keys: readonly K[]): EnvGuardResult<Record<K, string>>;
+/**
+ * Build a human-readable remediation string for a list of (possibly missing)
+ * env keys. Pulls per-key documentation and flow-enable metadata out of
+ * ENV_SPEC and tacks on the restart reminder so MCP clients don't keep
+ * retrying without picking up the new env.
+ */
+export declare function hintFor(keys: readonly EnvKey[]): string;
+//# sourceMappingURL=requireEnv.d.ts.map

package/dist/lib/requireEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireEnv.d.ts","sourceRoot":"","sources":["../../src/lib/requireEnv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,EAAE,GACjB,cAAc,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAkBnC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAevD"}

package/dist/lib/requireEnv.js

@@ -0,0 +1,48 @@
+import { ENV_REGISTRY } from "../env/schema.js";
+/**
+ * Soft env-var guard. Returns `{ ok }` only when every listed key is present
+ * and non-blank in `process.env`; otherwise returns a remediation hint that
+ * names the missing keys and the flows they unlock.
+ */
+export function requireEnv(keys) {
+    const missing = [];
+    const out = {};
+    for (const k of keys) {
+        const v = process.env[k]?.trim();
+        if (!v) {
+            missing.push(k);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    if (missing.length > 0) {
+        return {
+            error: `Missing required env: ${missing.join(", ")}`,
+            remediation: hintFor(missing),
+        };
+    }
+    return { ok: out };
+}
+/**
+ * Build a human-readable remediation string for a list of (possibly missing)
+ * env keys. Pulls per-key documentation and flow-enable metadata out of
+ * ENV_SPEC and tacks on the restart reminder so MCP clients don't keep
+ * retrying without picking up the new env.
+ */
+export function hintFor(keys) {
+    const parts = [];
+    for (const k of keys) {
+        const spec = ENV_REGISTRY[k];
+        if (!spec)
+            continue;
+        const flowHint = spec.enablesFlows?.length
+            ? ` (enables: ${spec.enablesFlows.join(", ")})`
+            : "";
+        parts.push(`Set ${k} in .env — ${spec.doc}${flowHint}`);
+    }
+    parts.push("After editing .env, restart the MCP server (Claude Code: quit + relaunch). " +
+        "Run dexe_doctor to verify the new values were picked up.");
+    return parts.join("\n");
+}
+//# sourceMappingURL=requireEnv.js.map