@trucore/atf 1.3.0 → 1.3.1

package/README.md

@@ -5,7 +5,7 @@
 ## One-Liner
 
 ```bash
-npx @trucore/atf@1.3.0 simulate --preset swap_small --verify --pretty
+npx @trucore/atf@1.3.1 simulate --preset swap_small --verify --pretty
 ```
 
 That's it. No install, no config, no API key required.
@@ -22,31 +22,37 @@ That's it. No install, no config, no API key required.
 ## Install (optional)
 
 ```bash
-npm install -g @trucore/atf@1.3.0
+npm install -g @trucore/atf@1.3.1
 ```
 
 Or use directly with `npx` (always pin the version):
 
 ```bash
-npx @trucore/atf@1.3.0 simulate --preset swap_small
+npx @trucore/atf@1.3.1 simulate --preset swap_small
+```
+
+## Quickstart: Doctor (Dev Environment Check)
+
+```bash
+npx @trucore/atf@1.3.1 doctor --pretty
 ```
 
 ## Quickstart: Devnet Burner
 
 ```bash
-npx @trucore/atf@1.3.0 swap --burner --devnet --in SOL --out USDC --amount-in 0.01 --execute --yes --confirm
+npx @trucore/atf@1.3.1 swap --burner --devnet --in SOL --out USDC --amount-in 0.01 --execute --yes --confirm
 ```
 
 ## Quickstart: Helius Profile Setup
 
 ```bash
-npx @trucore/atf@1.3.0 config init --yes
-npx @trucore/atf@1.3.0 profile create devnet
-npx @trucore/atf@1.3.0 profile use devnet
-npx @trucore/atf@1.3.0 config set solana_cluster devnet
-npx @trucore/atf@1.3.0 config set rpc_url helius
+npx @trucore/atf@1.3.1 config init --yes
+npx @trucore/atf@1.3.1 profile create devnet
+npx @trucore/atf@1.3.1 profile use devnet
+npx @trucore/atf@1.3.1 config set solana_cluster devnet
+npx @trucore/atf@1.3.1 config set rpc_url helius
 export HELIUS_API_KEY=your_key_here
-npx @trucore/atf@1.3.0 rpc ping
+npx @trucore/atf@1.3.1 rpc ping
 ```
 
 ## Commands
@@ -56,9 +62,9 @@ npx @trucore/atf@1.3.0 rpc ping
 Check API health and round-trip latency.
 
 ```bash
-npx @trucore/atf@1.3.0 health
-npx @trucore/atf@1.3.0 health --pretty
-npx @trucore/atf@1.3.0 health --base-url http://localhost:3000
+npx @trucore/atf@1.3.1 health
+npx @trucore/atf@1.3.1 health --pretty
+npx @trucore/atf@1.3.1 health --base-url http://localhost:3000
 ```
 
 **Output shape:**
@@ -72,9 +78,9 @@ npx @trucore/atf@1.3.0 health --base-url http://localhost:3000
 Run a transaction simulation against the ATF API.
 
 ```bash
-npx @trucore/atf@1.3.0 simulate --preset swap_small --verify
-npx @trucore/atf@1.3.0 simulate --preset swap_too_large --pretty
-npx @trucore/atf@1.3.0 simulate --json '{"chain_id":1,"value_eth":"0.5"}' --base-url http://localhost:3000
+npx @trucore/atf@1.3.1 simulate --preset swap_small --verify
+npx @trucore/atf@1.3.1 simulate --preset swap_too_large --pretty
+npx @trucore/atf@1.3.1 simulate --json '{"chain_id":1,"value_eth":"0.5"}' --base-url http://localhost:3000
 ```
 
 **Output shape:**
@@ -88,8 +94,8 @@ npx @trucore/atf@1.3.0 simulate --json '{"chain_id":1,"value_eth":"0.5"}' --base
 Approve a pending intent (requires authentication).
 
 ```bash
-npx @trucore/atf@1.3.0 approve --intent abc123 --token mytoken
-npx @trucore/atf@1.3.0 approve --intent abc123 --token mytoken --pretty
+npx @trucore/atf@1.3.1 approve --intent abc123 --token mytoken
+npx @trucore/atf@1.3.1 approve --intent abc123 --token mytoken --pretty
 ```
 
 **Output shape:**
@@ -103,14 +109,14 @@ npx @trucore/atf@1.3.0 approve --intent abc123 --token mytoken --pretty
 Show rich version information (CLI version, Node version, build info).
 
 ```bash
-npx @trucore/atf@1.3.0 version
-npx @trucore/atf@1.3.0 version --pretty
+npx @trucore/atf@1.3.1 version
+npx @trucore/atf@1.3.1 version --pretty
 ```
 
 **Output shape:**
 
 ```json
-{ "ok": true, "cli_version": "1.3.0", "node_version": "v22.0.0", "platform": "linux", "arch": "x64", "default_base_url": "https://api.trucore.xyz", "build_commit": "abc1234", "build_date": "2025-01-01T00:00:00Z" }
+{ "ok": true, "cli_version": "1.3.1", "node_version": "v22.0.0", "platform": "linux", "arch": "x64", "default_base_url": "https://api.trucore.xyz", "build_commit": "abc1234", "build_date": "2025-01-01T00:00:00Z" }
 ```
 
 ### `swap`
@@ -123,7 +129,7 @@ Execute a **real on-chain Solana swap** (Jupiter DEX) gated by ATF policy evalua
 **Dry run (no funds move):**
 
 ```bash
-npx @trucore/atf@1.3.0 swap \
+npx @trucore/atf@1.3.1 swap \
   --in SOL --out USDC \
   --amount-in 0.001 \
   --slippage-bps 50 \
@@ -134,7 +140,7 @@ npx @trucore/atf@1.3.0 swap \
 **Real transaction (mainnet):**
 
 ```bash
-npx @trucore/atf@1.3.0 swap \
+npx @trucore/atf@1.3.1 swap \
   --in SOL --out USDC \
   --amount-in 0.001 \
   --slippage-bps 50 \
@@ -146,7 +152,7 @@ npx @trucore/atf@1.3.0 swap \
 **Devnet burner one-liner (generates ephemeral keypair, no files needed):**
 
 ```bash
-npx @trucore/atf@1.3.0 swap \
+npx @trucore/atf@1.3.1 swap \
   --burner --devnet \
   --in SOL --out USDC \
   --amount-in 0.01 \
@@ -316,7 +322,7 @@ atf whoami --profile staging
 **Output shape:**
 
 ```json
-{ "ok": true, "profile": "default", "atf_base_url": "https://api.trucore.xyz", "solana_cluster": "mainnet-beta", "rpc_host": "mainnet.helius-rpc.com", "commitment": "confirmed", "explorer": "solscan", "cli_version": "1.3.0" }
+{ "ok": true, "profile": "default", "atf_base_url": "https://api.trucore.xyz", "solana_cluster": "mainnet-beta", "rpc_host": "mainnet.helius-rpc.com", "commitment": "confirmed", "explorer": "solscan", "cli_version": "1.3.1" }
 ```
 
 ### `ls`
@@ -339,6 +345,43 @@ atf completion fish > ~/.config/fish/completions/atf.fish
 atf completion powershell >> $PROFILE
 ```
 
+### `doctor`
+
+Run a comprehensive dev environment health check — ATF API, RPC, config, keypair, and explorer.
+
+```bash
+npx @trucore/atf@1.3.1 doctor --pretty
+npx @trucore/atf@1.3.1 doctor --profile devnet --pretty
+npx @trucore/atf@1.3.1 doctor --rpc https://custom-rpc.example.com
+npx @trucore/atf@1.3.1 doctor --verbose
+```
+
+**Output shape (JSON, default):**
+
+```json
+{
+  "ok": true,
+  "summary": { "status": "ok", "passed": 5, "warned": 0, "failed": 0 },
+  "env": { "cli_version": "1.3.1", "node_version": "v22.0.0", "platform": "linux", "arch": "x64" },
+  "effective": { "profile": "default", "atf_base_url": "https://api.trucore.xyz", "solana_cluster": "mainnet" },
+  "checks": [
+    { "name": "atf_health", "status": "pass", "latency_ms": 42, "details": { "http_status": 200 }, "actions": [] },
+    { "name": "simulate_sanity", "status": "pass", "latency_ms": 55, "details": { "decision": "allowed" }, "actions": [] },
+    { "name": "rpc_health", "status": "pass", "latency_ms": 30, "details": { "solana_version": "2.2.1" }, "actions": [] },
+    { "name": "keypair", "status": "pass", "details": { "configured": true, "valid": true }, "actions": [] },
+    { "name": "explorer_link", "status": "pass", "details": { "explorer": "solscan" }, "actions": [] }
+  ]
+}
+```
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks pass (or warn-only) |
+| 1 | User/actionable misconfiguration (missing Helius key, invalid config) |
+| 2 | Network/server failure (ATF API or RPC unreachable) |
+
 ## Global Options
 
 | Flag | Description | Default |
@@ -525,9 +568,10 @@ npm pack --dry-run
 npm publish --access public
 
 # 5. Verify install (from a clean machine or CI)
-npx @trucore/atf@1.3.0 version
-npx @trucore/atf@1.3.0 health
-npx @trucore/atf@1.3.0 whoami
+npx @trucore/atf@1.3.1 version
+npx @trucore/atf@1.3.1 health
+npx @trucore/atf@1.3.1 whoami
+npx @trucore/atf@1.3.1 doctor --pretty
 ```
 
 ## License

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 
-// @trucore/atf v1.3.0 — Agent Transaction Firewall CLI
-// Built: 2026-02-28T16:06:56.895Z
+// @trucore/atf v1.3.1 — Agent Transaction Firewall CLI
+// Built: 2026-02-28T17:33:25.811Z
 // Commit: 1bf6915
 
 // ---- src/constants.mjs ----
@@ -13,10 +13,10 @@
  * by build.mjs during the bundling step.
  */
 
-const VERSION = "1.3.0";
+const VERSION = "1.3.1";
 const DEFAULT_BASE_URL = "https://api.trucore.xyz";
 const BUILD_COMMIT = "1bf6915";
-const BUILD_DATE = "2026-02-28T16:06:56.895Z";
+const BUILD_DATE = "2026-02-28T17:33:25.811Z";
 const SIMULATE_PATHS = ["/api/simulate", "/v1/simulate"];
 
 // ---- src/redact.mjs ----
@@ -3490,6 +3490,422 @@ async function runCompletion(args) {
   process.stdout.write(script);
 }
 
+// ---- src/doctor.mjs ----
+/**
+ * doctor.mjs — `atf doctor` command
+ *
+ * Runs a comprehensive, fail-soft set of dev environment checks and returns
+ * a single JSON envelope.  Each check collects pass/warn/fail status and
+ * actionable suggestions.  Secret values are never printed.
+ *
+ * Exit codes:
+ *   0 — all checks pass (or warn-only)
+ *   1 — user/actionable misconfiguration
+ *   2 — network/server failure
+ */
+
+async function runDoctor(args) {
+  const format = args.format;
+  const verbose = args.verbose;
+  const timeoutMs = args.timeoutMs || 10000;
+  const profileName = args.profileFlag || null;
+  const isDevnet = args.devnet || false;
+
+  // ── 1) Resolve effective config ──────────────────────────────────
+  const { name: pName, profile } = resolveEffectiveProfile(profileName);
+
+  // Apply devnet override from flag
+  const cluster = isDevnet ? "devnet" : (profile.solana_cluster || "mainnet");
+
+  // Apply CLI flag overrides for base URL and RPC
+  const effectiveBaseUrl = args.baseUrl || profile.atf_base_url || DEFAULT_BASE_URL;
+
+  // Config sources (informational)
+  const configSources = [];
+  const { existsSync } = require("node:fs");
+  if (existsSync(resolveGlobalConfigPath())) configSources.push("global");
+  if (existsSync(resolveProjectConfigPath())) configSources.push("project");
+  if (process.env.ATF_BASE_URL) configSources.push("env:ATF_BASE_URL");
+  if (args.baseUrl !== DEFAULT_BASE_URL && !process.env.ATF_BASE_URL) configSources.push("flag:--base-url");
+  if (args.profileFlag) configSources.push("flag:--profile");
+
+  // ── Collect checks array ────────────────────────────────────────
+  const checks = [];
+
+  // ── 2) CLI runtime info (env block) ────────────────────────────
+  const commit = BUILD_COMMIT === "__BUILD_COMMIT__" ? null : BUILD_COMMIT;
+  const buildTime = BUILD_DATE === "__BUILD_DATE__" ? null : BUILD_DATE;
+  const env = {
+    cli_version: VERSION,
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    build_commit: commit,
+    build_date: buildTime,
+  };
+
+  // ── Resolve RPC URL (safe — don't exit on failure) ─────────────
+  let rpcUrl = null;
+  let rpcHost = null;
+  let heliusKeySource = null;
+  let rpcResolutionError = null;
+
+  // Determine RPC setting
+  const rpcSetting = args.rpcUrl || profile.rpc_url;
+  const isHeliusMode = rpcSetting === "helius" || args.rpcUrl === "helius";
+
+  if (isHeliusMode) {
+    // Check key sources without exiting
+    const envKey = process.env.HELIUS_API_KEY;
+    const secretKey = getSecret("helius", pName);
+    if (envKey && envKey.length > 0) {
+      heliusKeySource = "env";
+      const url = buildHeliusRpcUrl(cluster, envKey);
+      rpcUrl = url;
+      rpcHost = extractRpcHost(url);
+    } else if (secretKey) {
+      heliusKeySource = "secrets";
+      const url = buildHeliusRpcUrl(cluster, secretKey);
+      rpcUrl = url;
+      rpcHost = extractRpcHost(url);
+    } else {
+      heliusKeySource = "missing";
+      rpcResolutionError = "Helius API key not found";
+    }
+  } else if (rpcSetting) {
+    rpcUrl = rpcSetting;
+    rpcHost = extractRpcHost(rpcSetting);
+  } else if (args.rpcUrl) {
+    rpcUrl = args.rpcUrl;
+    rpcHost = extractRpcHost(args.rpcUrl);
+  } else {
+    // Use defaults
+    if (isDevnet) {
+      const devnetDefault = process.env.ATF_DEVNET_RPC || DEVNET_RPC_DEFAULT;
+      rpcUrl = devnetDefault;
+      rpcHost = extractRpcHost(devnetDefault);
+    } else {
+      rpcUrl = "https://api.mainnet-beta.solana.com";
+      rpcHost = "api.mainnet-beta.solana.com";
+    }
+  }
+
+  const effective = {
+    profile: pName,
+    atf_base_url: effectiveBaseUrl,
+    solana_cluster: cluster,
+    rpc_host: rpcHost ? redactApiKeyInUrl(rpcHost) : null,
+    commitment: profile.commitment || "confirmed",
+    explorer: profile.explorer || "solscan",
+    config_sources: configSources,
+  };
+
+  // Helper: verbose log to stderr
+  function vlog(msg) {
+    if (verbose) process.stderr.write(`  [doctor] ${msg}\n`);
+  }
+
+  // ── 3) ATF API health check ────────────────────────────────────
+  vlog(`Checking ATF API at ${redactApiKeyInUrl(effectiveBaseUrl)}/health ...`);
+  {
+    const check = { name: "atf_health", status: "pass", latency_ms: null, details: {}, actions: [] };
+    const start = Date.now();
+    try {
+      const response = await getHealth(effectiveBaseUrl, timeoutMs);
+      check.latency_ms = Date.now() - start;
+      check.details.http_status = response.status;
+      check.details.request_id = response.requestId || null;
+      check.details.path = "/health";
+      if (!response.ok) {
+        check.status = "fail";
+        check.details.http_status = response.status;
+        check.actions.push(`Check base URL: atf config set atf_base_url ${DEFAULT_BASE_URL}`);
+        check.actions.push("Run: atf health --pretty");
+      }
+    } catch (err) {
+      check.latency_ms = Date.now() - start;
+      check.status = "fail";
+      check.details.error = err.message || String(err);
+      check.details.path = "/health";
+      check.actions.push(`Cannot reach ${redactApiKeyInUrl(effectiveBaseUrl)}/health`);
+      check.actions.push(`Check base URL: atf config set atf_base_url ${DEFAULT_BASE_URL}`);
+    }
+    checks.push(check);
+  }
+
+  // ── 4) Simulate sanity check ───────────────────────────────────
+  vlog("Running simulate sanity check (swap_small preset) ...");
+  {
+    const check = { name: "simulate_sanity", status: "pass", latency_ms: null, details: {}, actions: [] };
+    const body = PRESETS.swap_small.transaction;
+    const start = Date.now();
+    try {
+      let response;
+      const attemptedPaths = [];
+      for (const path of SIMULATE_PATHS) {
+        attemptedPaths.push(path);
+        response = await postSimulate(effectiveBaseUrl, body, args.apiKey, timeoutMs, path);
+        if (response.status !== 404) break;
+        if (isAtfErrorEnvelope(response.data)) break;
+      }
+      check.latency_ms = Date.now() - start;
+      check.details.http_status = response.status;
+      check.details.request_id = response.requestId || null;
+      check.details.paths_tried = attemptedPaths;
+
+      if (response.status === 404) {
+        // Known: some deployments disable simulate → WARN not FAIL
+        check.status = "warn";
+        check.details.note = "Simulate endpoint returned 404 — may be disabled on this deployment";
+        check.actions.push("If simulate is expected, check your ATF deployment config");
+      } else if (!response.ok) {
+        check.status = "warn";
+        check.details.note = `Simulate returned HTTP ${response.status}`;
+        check.actions.push("Run: atf simulate --preset swap_small --pretty");
+      } else {
+        // Check response shape
+        const data = response.data || {};
+        check.details.decision = data.decision || null;
+        if (data.decision !== "allowed") {
+          check.status = "warn";
+          check.details.note = `swap_small preset returned ${data.decision || "unknown"} instead of allowed`;
+          check.actions.push("Run: atf simulate --preset swap_small --verify --pretty");
+        }
+      }
+    } catch (err) {
+      check.latency_ms = Date.now() - start;
+      check.status = "warn";
+      check.details.error = err.message || String(err);
+      check.actions.push("Simulate check failed — this is non-fatal if /health passed");
+    }
+    checks.push(check);
+  }
+
+  // ── 5) RPC checks ─────────────────────────────────────────────
+  vlog("Checking Solana RPC connectivity ...");
+
+  // 5a) Helius key source check (if helius mode)
+  if (isHeliusMode) {
+    const check = { name: "helius_key", status: "pass", latency_ms: 0, details: {}, actions: [] };
+    check.details.key_source = heliusKeySource;
+    if (heliusKeySource === "missing") {
+      check.status = "fail";
+      check.actions.push("Export HELIUS_API_KEY or run: atf secret set helius --profile " + pName);
+      check.actions.push("Docs: https://docs.helius.dev/");
+    }
+    checks.push(check);
+  }
+
+  // 5b) RPC getHealth + getVersion
+  if (rpcUrl && !rpcResolutionError) {
+    const check = { name: "rpc_health", status: "pass", latency_ms: null, details: {}, actions: [] };
+    check.details.rpc_host = rpcHost;
+    const start = Date.now();
+    try {
+      // getHealth
+      const healthRes = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getHealth", params: [] }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      const healthData = await healthRes.json();
+      check.latency_ms = Date.now() - start;
+
+      if (healthData.error) {
+        // Some nodes return error for getHealth if not validators
+        // Try getVersion as fallback
+        check.details.get_health_error = healthData.error.message || "unknown";
+      } else {
+        check.details.health_result = healthData.result || null;
+      }
+
+      // getVersion
+      const versionRes = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "getVersion", params: [] }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      const versionData = await versionRes.json();
+      if (versionData.result) {
+        check.details.solana_version = versionData.result["solana-core"] || null;
+      }
+    } catch (err) {
+      check.latency_ms = Date.now() - start;
+      check.status = "fail";
+      check.details.error = err.message || String(err);
+      check.actions.push("Check your RPC URL and network connectivity");
+      check.actions.push("Run: atf rpc ping");
+    }
+    checks.push(check);
+  } else if (rpcResolutionError) {
+    // Already handled by helius_key check above; skip rpc_health
+  }
+
+  // ── 6) Keypair readiness ───────────────────────────────────────
+  vlog("Checking keypair readiness ...");
+  {
+    const check = { name: "keypair", status: "pass", latency_ms: 0, details: {}, actions: [] };
+    const kpPath = args.keypairPath || profile.keypair_path;
+    if (!kpPath) {
+      check.status = "warn";
+      check.details.configured = false;
+      check.actions.push("Run: atf config set keypair_path <path>");
+      check.actions.push("If devnet, run: atf swap --burner --devnet --faucet");
+    } else {
+      check.details.configured = true;
+      check.details.path = kpPath;
+      try {
+        const { readFileSync } = require("node:fs");
+        const raw = readFileSync(kpPath, "utf8");
+        const arr = JSON.parse(raw);
+        if (Array.isArray(arr) && arr.length === 64) {
+          check.details.valid = true;
+        } else {
+          check.status = "warn";
+          check.details.valid = false;
+          check.details.note = `Expected JSON array of length 64, got ${Array.isArray(arr) ? arr.length : typeof arr}`;
+          check.actions.push("Verify keypair file format: JSON array of 64 byte values");
+        }
+      } catch (err) {
+        check.status = "warn";
+        check.details.valid = false;
+        check.details.note = err.code === "ENOENT" ? "File not found" : (err.message || String(err));
+        if (err.code === "ENOENT") {
+          check.actions.push(`File not found: ${kpPath}`);
+          check.actions.push("Run: atf config set keypair_path <valid-path>");
+        } else {
+          check.actions.push("Keypair file exists but could not be parsed");
+        }
+      }
+    }
+    checks.push(check);
+  }
+
+  // ── 7) Explorer link builder sanity ────────────────────────────
+  vlog("Checking explorer link builder ...");
+  {
+    const check = { name: "explorer_link", status: "pass", latency_ms: 0, details: {}, actions: [] };
+    const explorerPref = profile.explorer || "solscan";
+    const dummySig = "5" + "A".repeat(86);
+    const url = buildExplorerUrl(dummySig, cluster, explorerPref);
+    check.details.explorer = explorerPref;
+    check.details.sample_url = url;
+    if (!url || !url.startsWith("https://")) {
+      check.status = "warn";
+      check.details.note = "Explorer URL does not look valid";
+      check.actions.push(`Check explorer config: atf config set explorer solscan`);
+    }
+    checks.push(check);
+  }
+
+  // ── Build envelope ─────────────────────────────────────────────
+  let passed = 0;
+  let warned = 0;
+  let failed = 0;
+  for (const c of checks) {
+    if (c.status === "pass") passed++;
+    else if (c.status === "warn") warned++;
+    else failed++;
+  }
+
+  const ok = failed === 0;
+  const summaryStatus = failed > 0 ? "error" : (warned > 0 ? "warn" : "ok");
+
+  const envelope = {
+    ok,
+    summary: { status: summaryStatus, passed, warned, failed },
+    env,
+    effective,
+    checks,
+  };
+
+  // ── Determine exit code ────────────────────────────────────────
+  let exitCode = 0;
+  if (failed > 0) {
+    // Distinguish user misconfiguration from network failure
+    const hasNetworkFail = checks.some(
+      (c) => c.status === "fail" && (c.name === "atf_health" || c.name === "rpc_health")
+    );
+    const hasUserFail = checks.some(
+      (c) => c.status === "fail" && c.name !== "atf_health" && c.name !== "rpc_health"
+    );
+    if (hasNetworkFail && !hasUserFail) {
+      exitCode = 2;
+    } else if (hasUserFail && !hasNetworkFail) {
+      exitCode = 1;
+    } else {
+      // Both — prefer exit 2 (network) as it's the more severe issue
+      exitCode = 2;
+    }
+  }
+
+  // ── Output ─────────────────────────────────────────────────────
+  // Redact any stray secrets from the entire output
+  let output;
+  if (format === "pretty") {
+    output = formatDoctorPretty(envelope, args.noColor);
+  } else {
+    output = JSON.stringify(envelope, null, 2) + "\n";
+  }
+  // Defense-in-depth: scrub any HELIUS_API_KEY value that might leak
+  const heliusKey = process.env.HELIUS_API_KEY;
+  if (heliusKey && heliusKey.length > 0) {
+    output = output.split(heliusKey).join("***REDACTED***");
+  }
+  output = output.replace(/api-key=[^&\s"]+/gi, "api-key=***REDACTED***");
+  process.stdout.write(output);
+
+  process.exit(exitCode);
+}
+
+/**
+ * Format doctor output for --pretty mode.
+ */
+function formatDoctorPretty(envelope, noColor) {
+  const c = noColor ? { reset: "", bold: "", dim: "", green: "", red: "", yellow: "", cyan: "", gray: "" } : COLORS;
+  const lines = [];
+
+  lines.push("");
+  lines.push(`${c.bold}${c.cyan}  @trucore/atf doctor${c.reset}`);
+  lines.push(`${c.dim}  CLI ${envelope.env.cli_version} | Node ${envelope.env.node_version} | ${envelope.env.platform}/${envelope.env.arch}${c.reset}`);
+  lines.push("");
+
+  const S = envelope.summary;
+  const statusIcon = S.status === "ok" ? `${c.green}\u2713` : S.status === "warn" ? `${c.yellow}\u26a0` : `${c.red}\u2717`;
+  lines.push(`  ${c.bold}${statusIcon} ${S.status.toUpperCase()}${c.reset}  (${S.passed} passed, ${S.warned} warned, ${S.failed} failed)`);
+  lines.push("");
+
+  // Effective config
+  lines.push(`${c.dim}  Profile:     ${c.reset}${envelope.effective.profile}`);
+  lines.push(`${c.dim}  Base URL:    ${c.reset}${envelope.effective.atf_base_url}`);
+  lines.push(`${c.dim}  Cluster:     ${c.reset}${envelope.effective.solana_cluster}`);
+  lines.push(`${c.dim}  RPC Host:    ${c.reset}${envelope.effective.rpc_host || "(not configured)"}`);
+  lines.push(`${c.dim}  Commitment:  ${c.reset}${envelope.effective.commitment}`);
+  lines.push(`${c.dim}  Explorer:    ${c.reset}${envelope.effective.explorer}`);
+  lines.push("");
+
+  // Checks
+  for (const chk of envelope.checks) {
+    const icon =
+      chk.status === "pass" ? `${c.green}\u2713` :
+      chk.status === "warn" ? `${c.yellow}\u26a0` :
+      `${c.red}\u2717`;
+    const latency = chk.latency_ms !== null ? ` (${chk.latency_ms}ms)` : "";
+    lines.push(`  ${icon} ${c.bold}${chk.name}${c.reset}${latency}`);
+
+    if (chk.actions && chk.actions.length > 0) {
+      for (const a of chk.actions) {
+        lines.push(`    ${c.dim}\u2192 ${a}${c.reset}`);
+      }
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n") + "\n";
+}
+
 // ---- src/cli.mjs ----
 /**
  * cli.mjs — argument parsing and entry point (zero deps)
@@ -3528,6 +3944,7 @@ COMMANDS
   tx status           Check transaction confirmation status
   receipts verify     Verify content_hash / receipt_hash integrity
   completion          Generate shell completion (bash|zsh|fish|powershell)
+  doctor              Run dev environment health checks
 
 ALIASES
   ls                  Alias for config list
@@ -3616,7 +4033,9 @@ EXAMPLES
   npx @trucore/atf@${VERSION} tx send --tx-base64 ... --keypair ~/.config/solana/id.json --confirm
   npx @trucore/atf@${VERSION} tx status --sig <signature>
   npx @trucore/atf@${VERSION} receipts verify --file response.json
-  npx @trucore/atf@${VERSION} completion bash`;
+  npx @trucore/atf@${VERSION} completion bash
+  npx @trucore/atf@${VERSION} doctor --pretty
+  npx @trucore/atf@${VERSION} doctor --profile devnet --pretty`;
 
 function parseArgs(argv) {
   const defaultTimeout = (() => {
@@ -3948,6 +4367,9 @@ async function main() {
     case "completion":
       await runCompletion(args);
       break;
+    case "doctor":
+      await runDoctor(args);
+      break;
     default:
       exitWithError(ERROR_CODES.USER_ERROR, `Unknown command: ${args.command}`, "Run with --help for usage.", args.format);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trucore/atf",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Agent Transaction Firewall CLI — simulate, verify, and audit on-chain transactions trustlessly.",
   "license": "MIT",
   "repository": {