dexe-mcp 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 0.8.0 — 2026-05-30
+
+### Env onboarding overhaul
+
+This release exists to make first-run setup fail-safe for new users
+(human or AI assistant). Previously, when an env var was missing or
+typoed, tools threw raw stacks and the assistant had no way to discover
+which file to edit, which key was missing, or whether `.claude.json` was
+shadowing `.env`. Now there is one diagnostic, one wizard, one skill,
+and one schema that drives every check.
+
+**Upgrade:** zero env changes required, no breaking renames or removals.
+See [`docs/MIGRATION.md`](docs/MIGRATION.md) for the 0.7.x → 0.8.0
+guide and the documented behavior change in `dexe_read_*` /
+`dexe_tx_send` error responses.
+
+### Added
+
+- **`dexe_doctor` tool + CLI.** New diagnostic that walks every
+  recognized `DEXE_*` env var, runs reachability checks (RPC
+  `eth_chainId` per chain, Pinata `testAuthentication`, IPFS gateway DNS
+  lookup, subgraph `{__typename}` introspection, backend HEAD), and
+  reports pass/warn/fail per check with paste-ready remediation hints.
+  Network checks have a 3s hard timeout that downgrades to `warn` so
+  offline laptops don't see all-red. Also runnable as
+  `npx dexe-mcp doctor` (exit 0/1/2). See [`docs/DOCTOR.md`](docs/DOCTOR.md).
+- **`npx dexe-mcp init` wizard.** Interactive onboarding via native
+  `node:readline/promises`. Asks four questions (network, Pinata JWT,
+  Graph API key, signer mode), writes `.env` at the repo root (merge or
+  overwrite), and prints a `~/.claude.json` snippet for copy-paste.
+  Validates the Pinata JWT against the live endpoint before writing.
+  Defaults the signer mode to readonly; warns explicitly and double-confirms
+  before storing a private key in plaintext. Never auto-edits
+  `.claude.json`. No new dependencies.
+- **Schema-driven env handling.** `src/env/schema.ts` (`ENV_SPEC`,
+  `ENV_REGISTRY`) is now the canonical registry for every recognized
+  `DEXE_*` var (category, doc, zod schema, enabled flows, secret flag).
+  Consumed by the new parser, doctor, fail-soft guards, and the
+  `/dexe-setup` skill. Drift guarded by `tests/env/schema.test.ts`
+  against `.env.example`.
+- **Startup self-diagnostic banner.** `src/env/loader.ts` reads `.env`
+  raw bytes before `process.loadEnvFile()` and emits stderr warnings
+  for: UTF-8 BOM, missing trailing newline, spaces around `=`, unknown
+  `DEXE_*` keys, and host-env shadowing of `.env` values. Surfaces
+  silent parse traps that previously made "I edited .env and nothing
+  changed" hard to diagnose.
+- **Fail-soft guard helpers.** New `src/lib/requireEnv.ts` (`requireEnv`,
+  `hintFor`) generalizes the existing `requirePinata` pattern from
+  `src/tools/ipfs.ts`. Added `SignerManager.trySigner` and
+  `RpcProvider.tryProvider` siblings that return `{error, remediation}`
+  instead of throwing — keeps the throwing variants for backward
+  compatibility.
+- **`/dexe-setup` skill** at `.claude/skills/dexe-setup/SKILL.md`. Calls
+  `dexe_doctor`, parses the report, asks the user only for missing
+  values, edits `.env` (never `.claude.json`), and tells the user to
+  restart Claude Code. Caps at 3 doctor → fix → restart iterations.
+  Hard rule: refuse to write `DEXE_PRIVATE_KEY` without explicit user
+  opt-in; suggest WalletConnect first.
+- **`docs/SETUP.md` + `docs/DOCTOR.md` + `docs/MIGRATION.md`.**
+  Consolidated quickstart with three setup paths, the full check
+  reference, and the per-version migration notes.
+- **"For AI assistants" block in `CLAUDE.md`.** Tells future Claude:
+  call `dexe_doctor` first; edit `.env` not `.claude.json`; restart is
+  required after env changes; the `/dexe-setup` skill exists; point
+  upgrading users at `docs/MIGRATION.md`.
+
+### Changed
+
+- **`src/tools/read.ts` and `src/tools/txSend.ts` hot handlers** migrated
+  to the soft `tryProvider`/`trySigner` variants. Missing RPC or
+  `DEXE_PRIVATE_KEY` now surfaces as a structured MCP error with fix
+  instructions instead of a thrown stack. Other call sites of
+  `requireProvider`/`requireSigner` keep their throwing behavior — they
+  are migrated incrementally in 0.8.1.
+- **`src/index.ts`** now dispatches `dexe-mcp doctor` and `dexe-mcp init`
+  to their respective CLI entry points before opening the MCP stdio
+  transport. No-arg invocation still starts the server as before. The
+  env loader runs BEFORE the subcommand dispatch so the CLI sees the
+  same env as the MCP server.
+- **`docs/TOOLS.md`** bumped to 153 tools / 19 groups (added the
+  Diagnostics group containing `dexe_doctor`).
+- **`README.md` Quickstart** now leads with the wizard path
+  (`init` + `doctor`) above the manual install instructions.
+
+### Notes
+
+- No removed APIs. `requireSigner`/`requireProvider` keep throwing so
+  every existing call site (~17 outside read.ts and txSend.ts)
+  continues to work; the migration is incremental.
+- No new runtime dependencies. The wizard and doctor use only
+  `node:readline/promises`, `node:dns/promises`, and native `fetch`.
+
+## 0.7.2 — 2026-05-27
+
+### Fixed
+
+- **`dexe_gov_has_voted` reverted on every Bravo DAO (Uniswap, Compound).** Classic
+  `GovernorBravoDelegate` does not expose `hasVoted(uint256, address)` — it exposes
+  `getReceipt(proposalId, voter)` returning `Receipt{hasVoted, support, votes}`. The
+  Bravo read ABI wrongly listed `hasVoted` and the tool called it unconditionally, so
+  the call failed with `CALL_EXCEPTION`. The tool now family-branches: OZ reads
+  `hasVoted`, Bravo reads `getReceipt(...).hasVoted`, and the response reports the
+  `method` used. OZ (Optimism) was unaffected. Found via live verification of the
+  governor adapter against mainnet/OP RPCs; verified live post-fix (Compound 374,
+  Uniswap 75, Optimism).
+
 ## 0.7.1 — 2026-05-26
 
 ### Fixed

package/README.md

@@ -40,7 +40,7 @@ That era is ending.
 
 LLMs can now reason about voting power, weigh proposals against a mandate, draft calldata, simulate execution, and ask your wallet to sign — **continuously, across every DAO you care about, all at once.** What was a UI is becoming a conversation. What was a treasurer's spreadsheet is becoming an always-on agent.
 
-**`dexe-mcp` is the substrate that makes it real for the DeXe stack — and now for external OpenZeppelin Governor DAOs as well.** One MCP server. 152 typed tools across 19 groups. Every flow the DeXe frontend exposes — plus a generic `dexe_gov_*` surface targeting Uniswap, Compound, and Optimism.
+**`dexe-mcp` is the substrate that makes it real for the DeXe stack — and now for external OpenZeppelin Governor DAOs as well.** One MCP server. 153 typed tools across 19 groups. Every flow the DeXe frontend exposes — plus a generic `dexe_gov_*` surface targeting Uniswap, Compound, and Optimism.
 
 |     | What you get |
 |-----|------|
@@ -87,6 +87,24 @@ The next generation of DAOs will be **operated by language, not by clicks.**
 
 ## Quickstart
 
+**Fastest path — wizard + diagnostic:**
+
+```bash
+npm install -g dexe-mcp
+npx dexe-mcp init      # interactive setup (network, Pinata, signer mode)
+npx dexe-mcp doctor    # verify (RPC + Pinata + IPFS gateway + subgraph)
+```
+
+The wizard writes `.env` at the repo root and prints a `~/.claude.json`
+snippet to paste. Then `doctor` walks every recognized `DEXE_*` var and
+returns a pass/warn/fail report with paste-ready remediation hints. See
+[`docs/SETUP.md`](./docs/SETUP.md) for the full runbook,
+[`docs/DOCTOR.md`](./docs/DOCTOR.md) for the check reference, and
+[`docs/MIGRATION.md`](./docs/MIGRATION.md) if you are upgrading from
+0.7.x.
+
+**Manual path:**
+
 **1.** Install:
 
 ```bash
@@ -211,7 +229,7 @@ Full docs in [`docs/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/ma
 | **WalletConnect** | 3 | `dexe_wc_status` (resolved config + live session state), `dexe_wc_connect` (start a session, returns a pairing URI to scan as a QR), `dexe_wc_disconnect` (tear down). Broadcast convenience without a hot key — every tx is signed and broadcast on the operator's phone, the key never enters the MCP. See [`docs/WALLETCONNECT.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/WALLETCONNECT.md). |
 | **Simulator** | 3 | `eth_call`-based preflight with decoded revert reasons — `_sim_calldata`, `_sim_proposal`, `_sim_buy`. Catch reverts before you pay gas. See [`docs/SIMULATOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SIMULATOR.md). |
 | **Multi-DAO inbox + forecast** | 2 | `dexe_user_inbox` aggregates pending items (unvoted proposals, claimable rewards, locked deposits) across N DAOs. `_proposal_forecast` predicts pass rate with quorum projection + risk flags. See [`docs/INBOX.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/INBOX.md). |
-| **External Governor DAOs** | 18 | `dexe_gov_*` — read, build, simulate, and decode against OpenZeppelin Governor + Compound Bravo DAOs. Tier-1: Uniswap, Compound, Optimism. Config-only addition for new DAOs. Family-aware (OZ vs Bravo) propose / castVote / queue / execute / cancel / delegate. Eth-call dry-run + vote-impact projection. hasVoted + state + hashProposal + decode + descriptionHash utilities. Tally state-enum parity harness. See [`docs/GOVERNOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/GOVERNOR.md). |
+| **External Governor DAOs** | 18 | `dexe_gov_*` — read, build, simulate, and decode against OpenZeppelin Governor + Compound Bravo DAOs. Tier-1: Uniswap, Compound, Optimism. Config-only addition for new DAOs. Family-aware (OZ vs Bravo) propose / castVote / queue / execute / cancel / delegate. Eth-call dry-run + vote-impact projection. vote-receipt check (family-aware) + state + hashProposal + decode + descriptionHash utilities. Tally state-enum parity harness. See [`docs/GOVERNOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/GOVERNOR.md). |
 
 ---
 

package/dist/cli/doctor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI entrypoint: `npx dexe-mcp doctor`. Runs the same check suite as the
+ * MCP tool, prints a flat colorless table to stdout, exits with:
+ *   - 0 when every check passes
+ *   - 1 when there are warnings but no failures
+ *   - 2 when at least one check fails
+ *
+ * Designed for both human terminal use and CI pipelines.
+ */
+export declare function run(): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAiCzC"}

package/dist/cli/doctor.js

@@ -0,0 +1,44 @@
+import { loadConfig } from "../config.js";
+import { runAllChecks } from "../diag/checks.js";
+/**
+ * CLI entrypoint: `npx dexe-mcp doctor`. Runs the same check suite as the
+ * MCP tool, prints a flat colorless table to stdout, exits with:
+ *   - 0 when every check passes
+ *   - 1 when there are warnings but no failures
+ *   - 2 when at least one check fails
+ *
+ * Designed for both human terminal use and CI pipelines.
+ */
+export async function run() {
+    const config = await loadConfig().catch(err => {
+        process.stderr.write(`[dexe-mcp doctor] config load failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    });
+    if (!config) {
+        process.exit(2);
+    }
+    const checks = await runAllChecks({ config });
+    let pass = 0;
+    let warn = 0;
+    let fail = 0;
+    for (const c of checks) {
+        if (c.status === "pass")
+            pass++;
+        else if (c.status === "warn")
+            warn++;
+        else
+            fail++;
+    }
+    for (const c of checks) {
+        const tag = c.status === "pass" ? " OK " : c.status === "warn" ? "WARN" : "FAIL";
+        process.stdout.write(`[${tag}] ${c.id.padEnd(36)} ${c.message}\n`);
+        if (c.remediation) {
+            for (const line of c.remediation.split("\n")) {
+                process.stdout.write(`         -> ${line}\n`);
+            }
+        }
+    }
+    process.stdout.write(`\nsummary: ${pass} pass / ${warn} warn / ${fail} fail\n`);
+    process.exit(fail > 0 ? 2 : warn > 0 ? 1 : 0);
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG;IACvB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAC9F,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,IAAI,EAAE,CAAC;aAC3B,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,IAAI,EAAE,CAAC;;YAChC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QACjF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YAClB,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,IAAI,WAAW,IAAI,WAAW,IAAI,SAAS,CAAC,CAAC;IAChF,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+export declare function run(): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAsBA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA8KzC"}

package/dist/cli/init.js

@@ -0,0 +1,306 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * `npx dexe-mcp init` — zero-config onboarding wizard.
+ *
+ * Walks the user through a minimal `.env` (network, RPCs, Pinata, subgraph
+ * key, signer mode), validates the Pinata JWT against the live endpoint
+ * before writing, and prints a paste-ready `.claude.json` snippet. Never
+ * auto-edits the user's MCP host config — that is too risky to do
+ * automatically (other servers, other env keys, comments to preserve).
+ *
+ * Uses only the Node 20 standard library (`node:readline/promises`,
+ * `node:fs`, native `fetch`) — no new dependency.
+ */
+const TESTNET_DEFAULT_RPC = "https://data-seed-prebsc-1-s1.bnbchain.org:8545";
+const MAINNET_DEFAULT_RPC = "https://bsc-dataseed.bnbchain.org";
+export async function run() {
+    if (!input.isTTY) {
+        process.stderr.write("[dexe-mcp init] stdin is not a TTY. Pipe-driven init is not supported (too risky for secrets). " +
+            "Fill in .env manually instead — see .env.example.\n");
+        process.exit(2);
+    }
+    const rl = createInterface({ input, output });
+    try {
+        output.write(line("dexe-mcp init — onboarding wizard"));
+        output.write(line("─".repeat(64)));
+        output.write(line("Builds a minimal .env. Answers are stored in plaintext;"));
+        output.write(line("use WalletConnect or readonly mode if that worries you."));
+        output.write("\n");
+        // ---- Network selection ----------------------------------------------
+        const network = await pickOne(rl, "Which network(s)?", [
+            ["t", "testnet — BSC chain 97 (free faucet BNB, recommended for first run)"],
+            ["m", "mainnet — BSC chain 56 (real funds)"],
+            ["b", "both"],
+        ], "t");
+        let rpcTestnet;
+        let rpcMainnet;
+        if (network === "t" || network === "b") {
+            rpcTestnet = (await ask(rl, "Testnet RPC URL", TESTNET_DEFAULT_RPC)).trim();
+        }
+        if (network === "m" || network === "b") {
+            rpcMainnet = (await ask(rl, "Mainnet RPC URL", MAINNET_DEFAULT_RPC)).trim();
+        }
+        const defaultChainId = network === "m" ? "56" : "97";
+        // ---- Pinata JWT (optional) -----------------------------------------
+        output.write(line("Pinata JWT enables IPFS uploads (proposal metadata, DAO avatars)."));
+        output.write(line("Reads work without it via a public gateway. Press Enter to skip."));
+        const pinataJwt = (await ask(rl, "Pinata JWT", "")).trim();
+        if (pinataJwt) {
+            const ok = await validatePinataJwt(pinataJwt);
+            if (!ok) {
+                const proceed = await yn(rl, "Pinata says that JWT is invalid (or the network is unreachable). Save anyway?", false);
+                if (!proceed) {
+                    output.write(line("Aborted — re-run init when you have a valid JWT."));
+                    process.exit(2);
+                }
+            }
+            else {
+                output.write(line("  → Pinata JWT validated."));
+            }
+        }
+        const ipfsGateway = pinataJwt
+            ? (await ask(rl, "IPFS gateway URL", "https://gateway.pinata.cloud")).trim()
+            : "";
+        // ---- Subgraph (optional) -------------------------------------------
+        output.write(line("Subgraph reads need a Graph API key (free at thegraph.com)."));
+        const graphKey = (await ask(rl, "Graph API key (blank to skip subgraph reads)", "")).trim();
+        // ---- Signer mode ---------------------------------------------------
+        output.write(line(""));
+        output.write(line("Signer mode:"));
+        output.write(line("  readonly   — no broadcast; tools return unsigned calldata (safest)"));
+        output.write(line("  walletconnect — broadcast via phone wallet; key never enters this process"));
+        output.write(line("  privkey    — hot key in .env; convenient for CI and bots, NOT recommended"));
+        const signerMode = await pickOne(rl, "Pick a signer mode", [
+            ["r", "readonly (recommended)"],
+            ["w", "walletconnect"],
+            ["p", "privkey (warning: plaintext in .env)"],
+        ], "r");
+        let privateKey;
+        let wcProjectId;
+        if (signerMode === "p") {
+            output.write(line(""));
+            output.write(line("⚠  Plaintext private keys in .env are a security risk."));
+            output.write(line("   Anyone who reads the file can drain that wallet."));
+            output.write(line("   Prefer WalletConnect (re-run init and pick `w`) when possible."));
+            const confirm = await yn(rl, "Continue with privkey mode?", false);
+            if (!confirm) {
+                output.write(line("Aborted — re-run init and pick readonly or walletconnect."));
+                process.exit(2);
+            }
+            const pk = (await ask(rl, "Private key (0x… 64 hex)", "")).trim();
+            if (!/^0x[0-9a-fA-F]{64}$/.test(pk)) {
+                output.write(line("That does not look like a 64-hex key — aborting."));
+                process.exit(2);
+            }
+            const addr = await deriveAddress(pk);
+            output.write(line(`  → Derived address: ${addr}`));
+            const ok = await yn(rl, "Is that the wallet you intended?", true);
+            if (!ok) {
+                output.write(line("Aborted — re-run init."));
+                process.exit(2);
+            }
+            privateKey = pk;
+        }
+        else if (signerMode === "w") {
+            wcProjectId = (await ask(rl, "WalletConnect project id (cloud.reown.com)", "")).trim();
+        }
+        // ---- Build the env block + write .env ------------------------------
+        const updates = {};
+        if (rpcTestnet)
+            updates.DEXE_RPC_URL_TESTNET = rpcTestnet;
+        if (rpcMainnet)
+            updates.DEXE_RPC_URL_MAINNET = rpcMainnet;
+        updates.DEXE_DEFAULT_CHAIN_ID = defaultChainId;
+        if (pinataJwt)
+            updates.DEXE_PINATA_JWT = pinataJwt;
+        if (ipfsGateway)
+            updates.DEXE_IPFS_GATEWAY = ipfsGateway;
+        if (graphKey)
+            updates.DEXE_GRAPH_API_KEY = graphKey;
+        if (privateKey)
+            updates.DEXE_PRIVATE_KEY = privateKey;
+        if (wcProjectId)
+            updates.DEXE_WALLETCONNECT_PROJECT_ID = wcProjectId;
+        const repoRoot = findRepoRoot();
+        const envPath = resolve(repoRoot, ".env");
+        // Read the file once up-front (or treat ENOENT as "no existing .env") so
+        // the later write isn't a check-then-act TOCTOU: every decision below
+        // operates on this captured snapshot, not on a re-stat of the path.
+        let existingEnv = null;
+        try {
+            existingEnv = readFileSync(envPath, "utf8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        let action = "write";
+        if (existingEnv !== null) {
+            const choice = await pickOne(rl, `Existing .env at ${envPath}. Overwrite or merge?`, [
+                ["m", "merge — replace known keys, keep everything else (recommended)"],
+                ["o", "overwrite — wipe and start fresh"],
+                ["a", "abort — keep .env unchanged, exit"],
+            ], "m");
+            if (choice === "a") {
+                output.write(line("Aborted — .env unchanged."));
+                process.exit(0);
+            }
+            action = choice === "o" ? "write" : "merge";
+        }
+        const content = action === "write" || existingEnv === null
+            ? renderFreshEnv(updates)
+            : mergeEnv(existingEnv, updates);
+        writeFileSync(envPath, content, "utf8");
+        output.write(line(`✔ Wrote ${envPath} (${Object.keys(updates).length} key${Object.keys(updates).length === 1 ? "" : "s"} set).`));
+        output.write(line(""));
+        // ---- Print .claude.json snippet ------------------------------------
+        output.write(line("Paste this into your ~/.claude.json under `mcpServers`:"));
+        output.write(line(""));
+        output.write(jsonSnippet(repoRoot));
+        output.write(line(""));
+        output.write(line(`Next: run \`npx dexe-mcp doctor\` to verify, then restart Claude Code.`));
+    }
+    finally {
+        rl.close();
+    }
+}
+// ─── prompt helpers ──────────────────────────────────────────────────────
+async function ask(rl, prompt, fallback) {
+    const suffix = fallback ? ` [${fallback}]` : "";
+    const a = await rl.question(`${prompt}${suffix}: `);
+    return a.length === 0 ? fallback : a;
+}
+async function yn(rl, prompt, defaultYes) {
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    const a = (await rl.question(`${prompt} ${suffix}: `)).trim().toLowerCase();
+    if (!a)
+        return defaultYes;
+    return a === "y" || a === "yes";
+}
+async function pickOne(rl, prompt, options, defaultKey) {
+    output.write(line(prompt));
+    for (const [key, label] of options) {
+        const tag = key === defaultKey ? `[${key}*]` : `[${key} ]`;
+        output.write(line(`  ${tag} ${label}`));
+    }
+    const valid = new Set(options.map(o => o[0]));
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const a = (await rl.question(`Choice (default ${defaultKey}): `)).trim().toLowerCase();
+        if (!a)
+            return defaultKey;
+        if (valid.has(a))
+            return a;
+        output.write(line(`  → please answer one of ${[...valid].join(" / ")}`));
+    }
+}
+// ─── env file rendering ──────────────────────────────────────────────────
+function renderFreshEnv(updates) {
+    const lines = [
+        "# dexe-mcp — generated by `npx dexe-mcp init`",
+        "# Loaded via process.loadEnvFile() at MCP startup.",
+        "# Run `npx dexe-mcp doctor` after any edit to verify.",
+        "",
+    ];
+    for (const [k, v] of Object.entries(updates)) {
+        lines.push(`${k}=${v}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Merge new values into an existing .env in place: known keys are replaced,
+ * unknown keys + comments + blank lines preserved verbatim. Detects CRLF vs
+ * LF and matches the file's existing line endings.
+ */
+function mergeEnv(existing, updates) {
+    const eol = /\r\n/.test(existing) ? "\r\n" : "\n";
+    const lines = existing.split(/\r?\n/);
+    const seen = new Set();
+    const out = [];
+    for (const line_ of lines) {
+        const m = /^(\s*)([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line_);
+        if (m && Object.prototype.hasOwnProperty.call(updates, m[2])) {
+            const key = m[2];
+            out.push(`${m[1] ?? ""}${key}=${updates[key]}`);
+            seen.add(key);
+            continue;
+        }
+        out.push(line_);
+    }
+    // Append any keys that did not already exist.
+    const appended = [];
+    for (const [k, v] of Object.entries(updates)) {
+        if (seen.has(k))
+            continue;
+        appended.push(`${k}=${v}`);
+    }
+    if (appended.length > 0) {
+        if (out.length > 0 && out[out.length - 1] !== "")
+            out.push("");
+        out.push("# added by `npx dexe-mcp init`");
+        out.push(...appended);
+    }
+    // Ensure trailing newline (Node's loadEnvFile drops the last line otherwise).
+    if (out.length > 0 && out[out.length - 1] !== "")
+        out.push("");
+    return out.join(eol);
+}
+// ─── Pinata + ethers helpers ─────────────────────────────────────────────
+async function validatePinataJwt(jwt) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 5000);
+        const r = await fetch("https://api.pinata.cloud/data/testAuthentication", {
+            method: "GET",
+            headers: { Authorization: `Bearer ${jwt}` },
+            signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        return r.status >= 200 && r.status < 300;
+    }
+    catch {
+        return false;
+    }
+}
+async function deriveAddress(pk) {
+    const { Wallet } = await import("ethers");
+    return new Wallet(pk).address;
+}
+// ─── path + snippet helpers ──────────────────────────────────────────────
+function findRepoRoot() {
+    // `dist/index.js` → `..` is repo root. Walk up if running from src/cli/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Two known layouts: dist/cli/init.js → up 2; dist/index.js's import → up 1 from dist.
+    // Easiest: walk up until we find package.json.
+    let cur = here;
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(resolve(cur, "package.json")))
+            return cur;
+        cur = resolve(cur, "..");
+    }
+    return process.cwd();
+}
+function jsonSnippet(repoRoot) {
+    const distPath = resolve(repoRoot, "dist", "index.js");
+    // Use JSON.stringify to handle Windows backslashes cleanly.
+    const safe = JSON.stringify(distPath);
+    return [
+        "{",
+        `  "mcpServers": {`,
+        `    "dexe": {`,
+        `      "command": "node",`,
+        `      "args": [${safe}]`,
+        `    }`,
+        `  }`,
+        `}`,
+        "",
+    ].join("\n");
+}
+function line(s) {
+    return s + "\n";
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

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

package/dist/diag/checks.d.ts

@@ -0,0 +1,25 @@
+import { type EnvCategory } from "../env/schema.js";
+import type { DexeConfig } from "../config.js";
+export type CheckStatus = "pass" | "warn" | "fail";
+export type CheckCategory = EnvCategory | "network" | "process";
+export interface CheckResult {
+    id: string;
+    category: CheckCategory;
+    status: CheckStatus;
+    message: string;
+    remediation?: string;
+}
+export interface RunCheckOpts {
+    /** When omitted, checks that depend on resolved config are skipped. */
+    config?: DexeConfig;
+    /** Per-network-check timeout. Defaults to 3000ms. */
+    timeoutMs?: number;
+}
+/**
+ * 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 declare function runAllChecks(opts?: RunCheckOpts): Promise<CheckResult[]>;
+//# sourceMappingURL=checks.d.ts.map

package/dist/diag/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/diag/checks.ts"],"names":[],"mappings":"AACA,OAAO,EAA4C,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AACnD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAqBlF"}