@vault77/summon 2.0.1 → 2.1.2

package/README.md

@@ -1,10 +1,10 @@
 # summonTheWarlord — a VAULT77 🔐77 relic
 
-![Release](https://img.shields.io/github/v/release/monthviewsales/summonTheWarlord)
+![Release](https://img.shields.io/npm/v/@vault77/summon?label=release)
 ![Node](https://img.shields.io/badge/node-%3E%3D18.x-brightgreen)
 ![Platform](https://img.shields.io/badge/platform-macOS-blue)
 
-**Version:** 2.0.1
+**Version:** 2.0.2
 
 > _Relic software unearthed from VAULT77.  
 > For trench operators only. macOS‑native. Handle with care._  
@@ -22,6 +22,31 @@
 
 ---
 
+## Before `summon setup`
+
+First-time operator? Run `summon man` first for the built-in walkthrough.
+
+Have these inputs ready:
+
+- SolanaTracker RPC URL assigned to your account (full `https://...` endpoint; `advancedTx=true` can be present or omitted because summon enforces it automatically)
+- Wallet private key in one accepted format: base58 string or JSON byte array string (example: `[12,34,...]`)
+
+During `summon setup`, you'll be asked for:
+
+- `rpcUrl`
+- `slippage` (`number` or `"auto"`)
+- `priorityFee` (`number` or `"auto"`)
+- `priorityFeeLevel` (`min|low|medium|high|veryHigh`)
+- `txVersion` (`v0` or `legacy`)
+- `showQuoteDetails` (`true`/`false`)
+- `DEBUG_MODE` (`true`/`false`)
+- `notificationsEnabled` (`true`/`false`)
+- `jito.enabled` (`true`/`false`)
+- `jito.tip` (SOL, only when Jito is enabled)
+- Whether to store/replace your private key now (`y/N`) and, if yes, paste the key
+
+---
+
 ## 📡 Connect with VAULT77
 
 - **VAULT77 Community:** https://x.com/i/communities/1962257350309650488
@@ -43,6 +68,8 @@ npm install -g @vault77/summon
 summon setup
 ```
 
+If this is your first time, run `summon man` before setup for the full command walkthrough.
+
 This:
 
 - Creates/updates your config (RPC URL, slippage, priority fees, etc.)
@@ -67,6 +94,31 @@ summon sell <TOKEN_MINT> 50%
 
 ---
 
+# 📘 Command Reference
+
+For the full first-time walkthrough:
+
+```bash
+summon man
+```
+
+- `summon setup` — interactive setup for config plus Keychain/private key prompts
+- `summon config view` — show current config
+- `summon config edit` — edit config in your `$EDITOR`
+- `summon config set <key> <value>` — set one config value
+- `summon config wizard` — interactive, validated config editor
+- `summon config list` — list config keys and expected types
+- `summon keychain store` — store private key in macOS Keychain
+- `summon keychain unlock` — verify key retrieval from Keychain
+- `summon keychain delete` — delete stored private key
+- `summon buy <TOKEN_MINT> <amount>` — buy with SOL amount (`auto` is not supported for buys)
+- `summon sell <TOKEN_MINT> <amount>` — sell fixed amount, percent (like `50%`), or `auto`
+- `summon wallet` — open your wallet page in browser
+- `summon doctor` — run config/Keychain/RPC/swap/notification diagnostics
+- `summon man` — display the built-in manual
+
+---
+
 # 🧰 Local Development (optional)
 
 ```bash
@@ -178,15 +230,10 @@ Dependencies:
 - `commander` — [MIT](https://github.com/tj/commander.js/blob/HEAD/LICENSE)
 - `fs-extra` — [MIT](https://github.com/jprichardson/node-fs-extra/blob/HEAD/LICENSE)
 - `keytar` — [MIT](https://github.com/atom/node-keytar/blob/HEAD/LICENSE)
-- `npm` — [Artistic-2.0](https://github.com/npm/cli/blob/HEAD/LICENSE)
 - `open` — [MIT](https://github.com/sindresorhus/open/blob/HEAD/LICENSE)
 - `solana-swap` — [ISC](https://github.com/YZYLAB/solana-swap/blob/HEAD/LICENSE)
 
 Tooling:
 
 - `eslint` — [MIT](https://github.com/eslint/eslint/blob/HEAD/LICENSE)
-- `eslint-config-standard` — [MIT](https://github.com/standard/eslint-config-standard/blob/HEAD/LICENSE)
-- `eslint-plugin-import` — [MIT](https://github.com/import-js/eslint-plugin-import/blob/HEAD/LICENSE)
-- `eslint-plugin-n` — [MIT](https://github.com/eslint-community/eslint-plugin-n/blob/HEAD/LICENSE)
-- `eslint-plugin-promise` — [ISC](https://github.com/eslint-community/eslint-plugin-promise/blob/HEAD/LICENSE)
 - `jest` — [MIT](https://github.com/jestjs/jest/blob/HEAD/LICENSE)

package/lib/config.js

@@ -239,7 +239,7 @@ export async function loadConfig() {
   let cfg;
   try {
     cfg = await fs.readJson(configPath);
-  } catch (err) {
+  } catch {
     let backupPath;
     try {
       if (await fs.pathExists(configPath)) {

package/lib/doctor.js

@@ -7,8 +7,8 @@ const WRAPPED_SOL_MINT = "So11111111111111111111111111111111111111112";
 const TRUMP_MINT = "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN";
 const MIN_SWAP_SOL = 0.0001;
 
-function makeResult(name, status, message, details) {
-  return { name, status, message, details };
+function makeResult(name, status, message, details, hint) {
+  return { name, status, message, details, hint };
 }
 
 async function checkConfig() {
@@ -16,7 +16,16 @@ async function checkConfig() {
     const cfg = await loadConfig();
     return { cfg, result: makeResult("config", "ok", "Loaded and normalized config.") };
   } catch (err) {
-    return { cfg: null, result: makeResult("config", "fail", "Failed to load config.", err?.message) };
+    return {
+      cfg: null,
+      result: makeResult(
+        "config",
+        "fail",
+        "Failed to load config.",
+        err?.message,
+        "Run `summon setup` or `summon config wizard`."
+      ),
+    };
   }
 }
 
@@ -24,18 +33,42 @@ async function checkKeychain() {
   try {
     const exists = await hasPrivateKey();
     if (!exists) {
-      return { ok: false, result: makeResult("keychain", "fail", "No private key stored.") };
+      return {
+        ok: false,
+        result: makeResult(
+          "keychain",
+          "fail",
+          "No private key stored.",
+          undefined,
+          "Run `summon keychain store`."
+        ),
+      };
     }
     await getPrivateKey();
     return { ok: true, result: makeResult("keychain", "ok", "Private key accessible.") };
   } catch (err) {
-    return { ok: false, result: makeResult("keychain", "fail", "Unable to read private key.", err?.message) };
+    return {
+      ok: false,
+      result: makeResult(
+        "keychain",
+        "fail",
+        "Unable to read private key.",
+        err?.message,
+        "Run `summon keychain store`."
+      ),
+    };
   }
 }
 
 async function checkRpc(rpcUrl) {
   if (!rpcUrl) {
-    return makeResult("rpc", "fail", "RPC URL not configured.");
+    return makeResult(
+      "rpc",
+      "fail",
+      "RPC URL not configured.",
+      undefined,
+      "Update `rpcUrl` via `summon config wizard`."
+    );
   }
   const healthUrl = ensureAdvancedTx(rpcUrl);
   try {
@@ -45,15 +78,33 @@ async function checkRpc(rpcUrl) {
       body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getHealth" }),
     });
     if (!res.ok) {
-      return makeResult("rpc", "fail", "RPC health check failed.", `HTTP ${res.status}`);
+      return makeResult(
+        "rpc",
+        "fail",
+        "RPC health check failed.",
+        `HTTP ${res.status}`,
+        "Update `rpcUrl` via `summon config wizard`."
+      );
     }
     const body = await res.json();
     if (body.result !== "ok") {
-      return makeResult("rpc", "fail", "RPC returned unhealthy status.", JSON.stringify(body));
+      return makeResult(
+        "rpc",
+        "fail",
+        "RPC returned unhealthy status.",
+        JSON.stringify(body),
+        "Update `rpcUrl` via `summon config wizard`."
+      );
     }
     return makeResult("rpc", "ok", "RPC reachable.");
   } catch (err) {
-    return makeResult("rpc", "fail", "RPC health check error.", err?.message);
+    return makeResult(
+      "rpc",
+      "fail",
+      "RPC health check error.",
+      err?.message,
+      "Update `rpcUrl` via `summon config wizard`."
+    );
   }
 }
 
@@ -84,11 +135,23 @@ async function checkSwapApi(cfg, keychainOk) {
     );
     const quote = swapResp?.quote ?? swapResp?.rate;
     if (!quote) {
-      return makeResult("swap", "fail", "Swap API response missing quote.");
+      return makeResult(
+        "swap",
+        "fail",
+        "Swap API response missing quote.",
+        undefined,
+        "Rerun `summon doctor -v` and verify SolanaTracker account/RPC."
+      );
     }
     return makeResult("swap", "ok", "Swap API reachable.");
   } catch (err) {
-    return makeResult("swap", "fail", "Swap API check failed.", err?.message);
+    return makeResult(
+      "swap",
+      "fail",
+      "Swap API check failed.",
+      err?.message,
+      "Rerun `summon doctor -v` and verify SolanaTracker account/RPC."
+    );
   }
 }
 
@@ -108,11 +171,23 @@ async function checkNotifications(cfg) {
       throwOnError: true,
     });
     if (!ok) {
-      return makeResult("notifications", "fail", "Notification failed.");
+      return makeResult(
+        "notifications",
+        "fail",
+        "Notification failed.",
+        undefined,
+        "Enable terminal notifications or disable `notificationsEnabled`."
+      );
     }
     return makeResult("notifications", "ok", "Notification sent.");
   } catch (err) {
-    return makeResult("notifications", "fail", "Notification failed.", err?.message);
+    return makeResult(
+      "notifications",
+      "fail",
+      "Notification failed.",
+      err?.message,
+      "Enable terminal notifications or disable `notificationsEnabled`."
+    );
   }
 }
 
@@ -137,6 +212,7 @@ export async function runDoctor({ verbose = false } = {}) {
     return results.map((item) => ({
       ...item,
       details: item.details || undefined,
+      hint: item.hint || undefined,
     }));
   }
   return results;

package/lib/swapClient.js

@@ -1,6 +1,5 @@
 import { SolanaTracker } from "solana-swap";
 import { loadConfig } from "./config.js";
-import { getPrivateKey } from "../utils/keychain.js";
 import { logger } from "../utils/logger.js";
 import { ConfigError, SwapError } from "./errors.js";
 import { notify } from "../utils/notify.js";
@@ -9,6 +8,8 @@ const SWAP_DISCOUNT_CODE = "jduck-d815-4c28-b85d-17e9fc3a21a8";
 
 let clientPromise = null;
 let clientFactory = defaultFactory;
+let memoizedRpcUrl = null;
+let warnedOnConflictingCfg = false;
 
 export function ensureAdvancedTx(rpcUrl) {
   if (!rpcUrl || typeof rpcUrl !== "string") {
@@ -24,20 +25,56 @@ export function ensureAdvancedTx(rpcUrl) {
 export function setSwapClientFactory(factory) {
   clientFactory = factory;
   clientPromise = null;
+  memoizedRpcUrl = null;
+  warnedOnConflictingCfg = false;
 }
 
-export async function getSwapClient() {
+function getConfigRpcUrl(cfg) {
+  if (!cfg || typeof cfg !== "object" || typeof cfg.rpcUrl !== "string") {
+    return null;
+  }
+  try {
+    return ensureAdvancedTx(cfg.rpcUrl);
+  } catch {
+    // Keep getSwapClient backward-compatible: ignore unusable cfg hints once client is memoized.
+    return null;
+  }
+}
+
+/**
+ * Returns the shared swap client instance.
+ * `options.cfg` is only consumed during initial client creation; subsequent calls always reuse
+ * the memoized client to preserve existing behavior.
+ */
+export async function getSwapClient(options = {}) {
+  const requestedRpcUrl = getConfigRpcUrl(options?.cfg);
+
   if (!clientPromise) {
-    clientPromise = clientFactory().catch((err) => {
+    memoizedRpcUrl = requestedRpcUrl;
+    clientPromise = clientFactory(options).catch((err) => {
       clientPromise = null;
+      memoizedRpcUrl = null;
+      warnedOnConflictingCfg = false;
       throw err;
     });
+  } else if (
+    requestedRpcUrl
+    && memoizedRpcUrl
+    && requestedRpcUrl !== memoizedRpcUrl
+    && !warnedOnConflictingCfg
+  ) {
+    warnedOnConflictingCfg = true;
+    logger.warn(
+      "getSwapClient received cfg.rpcUrl that differs from the memoized client; reusing existing client."
+    );
   }
+
   return clientPromise;
 }
 
-async function defaultFactory() {
-  const cfg = await loadConfig();
+async function defaultFactory(options = {}) {
+  const cfg = options.cfg ?? await loadConfig();
+  const { getPrivateKey } = await import("../utils/keychain.js");
   let raw;
   try {
     raw = await getPrivateKey();

package/lib/tradeInput.js

@@ -0,0 +1,104 @@
+export const MINT_EXAMPLE = "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN";
+
+const MINT_REGEX = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const FIELD_ORDER = ["mint", "amount"];
+
+const AMOUNT_EXAMPLES = Object.freeze({
+  buy: ["0.01", "25%"],
+  sell: ["100", "25%", "auto"],
+});
+
+export function getAmountExamples(type) {
+  return AMOUNT_EXAMPLES[type] || ["0.01"];
+}
+
+export function normalizeMint(rawMint) {
+  return String(rawMint ?? "").trim();
+}
+
+export function validateMint(rawMint) {
+  const mint = normalizeMint(rawMint);
+  if (!mint) {
+    return {
+      ok: false,
+      field: "mint",
+      code: "missing",
+      message: "Missing mint address. Provide a base58 token mint (32-44 chars).",
+      value: null,
+    };
+  }
+  if (!MINT_REGEX.test(mint)) {
+    return {
+      ok: false,
+      field: "mint",
+      code: "invalid",
+      message: "Invalid mint format. Expected base58 address (32-44 chars).",
+      value: null,
+    };
+  }
+  return { ok: true, field: "mint", code: null, message: null, value: mint };
+}
+
+export function normalizeAmount(rawAmount) {
+  return String(rawAmount ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "");
+}
+
+export function parseAmount(rawAmount) {
+  const normalized = normalizeAmount(rawAmount);
+  if (!normalized) {
+    return {
+      ok: false,
+      field: "amount",
+      code: "missing",
+      message: "Missing amount.",
+      value: null,
+    };
+  }
+  if (normalized !== "auto" && !normalized.endsWith("%")) {
+    const parsed = parseFloat(normalized);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+      return {
+        ok: false,
+        field: "amount",
+        code: "invalid",
+        message: "Invalid amount. Use a positive number, 'auto' during a sell, or '<percent>%'.",
+        value: null,
+      };
+    }
+    return { ok: true, field: "amount", code: null, message: null, value: parsed };
+  }
+  return { ok: true, field: "amount", code: null, message: null, value: normalized };
+}
+
+export function validateTradeInput({ type, mint, amount }) {
+  const mintResult = validateMint(mint);
+  const amountResult = parseAmount(amount);
+  const issues = [];
+
+  if (!mintResult.ok) {
+    issues.push(mintResult);
+  }
+  if (!amountResult.ok) {
+    issues.push(amountResult);
+  } else if (type === "buy" && amountResult.value === "auto") {
+    issues.push({
+      ok: false,
+      field: "amount",
+      code: "buy_auto_not_supported",
+      message: "Buying with 'auto' isn't supported. Use a number or '<percent>%'.",
+      value: null,
+    });
+  }
+
+  issues.sort((left, right) => FIELD_ORDER.indexOf(left.field) - FIELD_ORDER.indexOf(right.field));
+
+  return {
+    ok: issues.length === 0,
+    mint: mintResult.ok ? mintResult.value : null,
+    amount: amountResult.ok ? amountResult.value : null,
+    issues,
+  };
+}

package/lib/trades.js

@@ -5,25 +5,185 @@ import { getSwapClient } from "./swapClient.js";
 
 // Wrapped SOL mint address on Solana
 const WRAPPED_SOL_MINT = "So11111111111111111111111111111111111111112";
-const VERIFY_ATTEMPTS = 20;
-const VERIFY_DELAY_MS = 1000;
+const VERIFY_DELAY_SCHEDULE_MS = [500, 1000, 2000, 3000, 4000, 5000];
+const CONFIRMED_TRANSACTION_STATUSES = new Set([
+  "processed",
+  "confirmed",
+  "finalized",
+  "success",
+  "succeeded",
+  "ok",
+]);
+const FAILED_TRANSACTION_STATUSES = new Set([
+  "failed",
+  "failure",
+  "error",
+  "errored",
+  "reverted",
+  "dropped",
+]);
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const hasOwn = (value, key) => Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
+
+function formatTransactionError(err) {
+  if (typeof err === "string") {
+    return err;
+  }
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+function classifyTransactionStatus(status) {
+  if (status == null) {
+    return "unknown";
+  }
+
+  if (typeof status === "string") {
+    const normalized = status.trim().toLowerCase();
+    if (CONFIRMED_TRANSACTION_STATUSES.has(normalized)) {
+      return "confirmed";
+    }
+    if (FAILED_TRANSACTION_STATUSES.has(normalized)) {
+      return "failed";
+    }
+    return "unknown";
+  }
+
+  if (typeof status === "object") {
+    if ((hasOwn(status, "Err") && status.Err != null)
+      || (hasOwn(status, "err") && status.err != null)
+      || (hasOwn(status, "error") && status.error != null)) {
+      return "failed";
+    }
+    if (hasOwn(status, "Ok")) {
+      return "confirmed";
+    }
+    if (hasOwn(status, "confirmationStatus")) {
+      return classifyTransactionStatus(status.confirmationStatus);
+    }
+    if (hasOwn(status, "status")) {
+      return classifyTransactionStatus(status.status);
+    }
+  }
+
+  return "unknown";
+}
+
+function extractStatusError(status) {
+  if (status == null) {
+    return "unknown transaction status";
+  }
+  if (typeof status === "string") {
+    return status;
+  }
+  if (typeof status === "object") {
+    return status.Err ?? status.err ?? status.error ?? status;
+  }
+  return status;
+}
+
+function getVerificationState(details) {
+  if (!details) {
+    return "pending";
+  }
+
+  const hasMetaErr = hasOwn(details.meta, "err");
+  if (hasMetaErr && details.meta.err != null) {
+    throw new Error(`Transaction failed: ${formatTransactionError(details.meta.err)}`);
+  }
+  if (hasMetaErr && details.meta.err === null) {
+    return "confirmed";
+  }
+
+  const directErrors = [details.err, details.error, details.value?.err, details.value?.error];
+  for (const err of directErrors) {
+    if (err != null) {
+      throw new Error(`Transaction failed: ${formatTransactionError(err)}`);
+    }
+  }
+
+  const statusCandidates = [
+    details.confirmationStatus,
+    details.status,
+    details.meta?.status,
+    details.value?.confirmationStatus,
+    details.value?.status,
+  ];
+  const hasStatusHint = statusCandidates.some((status) => status != null);
+
+  for (const status of statusCandidates) {
+    const state = classifyTransactionStatus(status);
+    if (state === "confirmed") {
+      return "confirmed";
+    }
+    if (state === "failed") {
+      throw new Error(`Transaction failed: ${formatTransactionError(extractStatusError(status))}`);
+    }
+  }
+
+  if (!hasStatusHint && details.meta && typeof details.meta === "object") {
+    return "confirmed";
+  }
+
+  return "pending";
+}
+
+function isTransientTransactionDetailsError(err) {
+  const status = err?.status ?? err?.statusCode ?? err?.response?.status;
+  if (typeof status === "number" && [408, 425, 429, 500, 502, 503, 504].includes(status)) {
+    return true;
+  }
+
+  const code = String(err?.code ?? "").toUpperCase();
+  if (["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "EAI_AGAIN"].includes(code)) {
+    return true;
+  }
+
+  const message = String(err?.message ?? err ?? "").toLowerCase();
+  return [
+    "timeout",
+    "timed out",
+    "network",
+    "fetch failed",
+    "socket hang up",
+    "temporarily unavailable",
+    "too many requests",
+    "rate limit",
+  ].some((needle) => message.includes(needle));
+}
 
 async function verifySwap(tracker, txid) {
-  for (let attempt = 0; attempt < VERIFY_ATTEMPTS; attempt += 1) {
-    const details = await tracker.getTransactionDetails(txid);
-    if (details) {
-      if (details.meta?.err) {
-        const errText = typeof details.meta.err === "string"
-          ? details.meta.err
-          : JSON.stringify(details.meta.err);
-        throw new Error(`Transaction failed: ${errText}`);
+  const checkDetails = async () => {
+    let details;
+    try {
+      details = await tracker.getTransactionDetails(txid);
+    } catch (err) {
+      if (isTransientTransactionDetailsError(err)) {
+        return "pending";
       }
+      throw err;
+    }
+
+    return getVerificationState(details);
+  };
+
+  const immediateState = await checkDetails();
+  if (immediateState === "confirmed") {
+    return true;
+  }
+
+  for (const waitMs of VERIFY_DELAY_SCHEDULE_MS) {
+    await sleep(waitMs);
+    const state = await checkDetails();
+    if (state === "confirmed") {
       return true;
     }
-    await sleep(VERIFY_DELAY_MS);
   }
+
   return false;
 }
 
@@ -31,11 +191,12 @@ async function verifySwap(tracker, txid) {
  * Buy tokens: spend a specific amount of SOL to acquire <mint>.
  * @param {string} mint       SPL token mint address
  * @param {number|string} amountSol  Amount in SOL to spend, or "auto"/"<percent>%"
+ * @param {{ cfg?: object }} [context] Optional context carrying preloaded config
  * @returns Promise resolving with txid, tokens received, and quote/rate details
  */
-export async function buyToken(mint, amountSol) {
-  const cfg = await loadConfig();
-  const tracker = await getSwapClient();
+export async function buyToken(mint, amountSol, context = {}) {
+  const cfg = context?.cfg ?? await loadConfig();
+  const tracker = await getSwapClient({ cfg });
   const debugEnabled = Boolean(cfg.DEBUG_MODE || process.env.NODE_ENV === "development");
   const notificationsEnabled = cfg.notificationsEnabled !== false;
 
@@ -131,11 +292,12 @@ export async function buyToken(mint, amountSol) {
  * Sell tokens: swap a specified amount (decimal, 'auto', or '<percent>%') back to SOL.
  * @param {string} mint      SPL token mint address
  * @param {number|string} amount  Decimal amount, "auto", or "<percent>%"
+ * @param {{ cfg?: object }} [context] Optional context carrying preloaded config
  * @returns Promise resolving with txid, SOL received, and quote/rate details
  */
-export async function sellToken(mint, amount) {
-  const cfg = await loadConfig();
-  const tracker = await getSwapClient();
+export async function sellToken(mint, amount, context = {}) {
+  const cfg = context?.cfg ?? await loadConfig();
+  const tracker = await getSwapClient({ cfg });
   const debugEnabled = Boolean(cfg.DEBUG_MODE || process.env.NODE_ENV === "development");
   const notificationsEnabled = cfg.notificationsEnabled !== false;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vault77/summon",
-  "version": "2.0.1",
+  "version": "2.1.2",
   "description": "A recovered VAULT77 relic for macOS operators. summonTheWarlord is a high-performance CLI tool for ultra-fast, low-fee Solana swaps on macOS. Private keys are secured using the native macOS Keychain, never written to disk or exposed to JavaScript memory longer than required. Built for serious CLI workflows with system notifications, local-first execution, and zero browser dependency.",
   "keywords": [
     "solana",
@@ -47,21 +47,19 @@
     "lint:fix": "eslint . --fix"
   },
   "devDependencies": {
-    "eslint": "^8.57.1",
-    "eslint-config-standard": "^17.1.0",
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^16.6.2",
-    "eslint-plugin-promise": "^6.6.0",
+    "globals": "^17.3.0",
     "jest": "^30.2.0"
   },
   "dependencies": {
     "@solana/web3.js": "^1.98.4",
-    "axios": "^1.13.3",
+    "axios": "^1.13.5",
     "bs58": "^6.0.0",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "fs-extra": "^11.3.3",
     "keytar": "^7.9.0",
-    "npm": "^11.8.0",
     "open": "^11.0.0",
     "solana-swap": "1.3.0"
   }

package/summon-cli.js

@@ -16,6 +16,7 @@ import { storePrivateKey, getPrivateKey, deletePrivateKey, hasPrivateKey } from
 import readline from "readline";
 import { notify } from "./utils/notify.js";
 import { runDoctor } from "./lib/doctor.js";
+import { MINT_EXAMPLE, getAmountExamples, validateTradeInput } from "./lib/tradeInput.js";
 
 const program = new Command();
 program
@@ -44,6 +45,59 @@ const CONFIG_HELP = [
   { key: "jito.enabled", type: "true | false", note: "Enable Jito bundles" },
   { key: "jito.tip", type: "number", note: "Tip in SOL when Jito enabled" },
 ];
+const WIZARD_FIELD_GUIDANCE = {
+  rpcUrl: {
+    helper: "Use your SolanaTracker RPC URL. advancedTx=true is appended automatically.",
+    recommended: "Your dedicated SolanaTracker endpoint",
+    defaultValue: DEFAULT_CONFIG.rpcUrl,
+  },
+  slippage: {
+    helper: "Max swap slippage percent. Use auto to let the backend choose dynamically.",
+    recommended: DEFAULT_CONFIG.slippage,
+    defaultValue: DEFAULT_CONFIG.slippage,
+  },
+  priorityFee: {
+    helper:
+      "Use auto for adaptive fees, or set a fixed SOL value (example: 0.0005). When set to auto, priorityFeeLevel controls aggressiveness.",
+    recommended: `${DEFAULT_CONFIG.priorityFee} + ${DEFAULT_CONFIG.priorityFeeLevel}`,
+    defaultValue: DEFAULT_CONFIG.priorityFee,
+  },
+  priorityFeeLevel: {
+    helper: "Used only when priorityFee is auto. Fixed priorityFee values ignore this setting.",
+    recommended: DEFAULT_CONFIG.priorityFeeLevel,
+    defaultValue: DEFAULT_CONFIG.priorityFeeLevel,
+  },
+  txVersion: {
+    helper: "v0 supports address lookup tables. legacy is only for compatibility edge cases.",
+    recommended: DEFAULT_CONFIG.txVersion,
+    defaultValue: DEFAULT_CONFIG.txVersion,
+  },
+  showQuoteDetails: {
+    helper: "Print full quote payload after swaps. Enable only when debugging swap math.",
+    recommended: DEFAULT_CONFIG.showQuoteDetails,
+    defaultValue: DEFAULT_CONFIG.showQuoteDetails,
+  },
+  DEBUG_MODE: {
+    helper: "Verbose SDK/network logging. Useful for diagnostics, noisy for regular trading.",
+    recommended: DEFAULT_CONFIG.DEBUG_MODE,
+    defaultValue: DEFAULT_CONFIG.DEBUG_MODE,
+  },
+  notificationsEnabled: {
+    helper: "macOS desktop notifications for trade and setup events.",
+    recommended: DEFAULT_CONFIG.notificationsEnabled,
+    defaultValue: DEFAULT_CONFIG.notificationsEnabled,
+  },
+  jitoEnabled: {
+    helper: "Bundle via Jito relays. Keep disabled unless you intentionally use Jito flow.",
+    recommended: DEFAULT_CONFIG.jito.enabled,
+    defaultValue: DEFAULT_CONFIG.jito.enabled,
+  },
+  jitoTip: {
+    helper: "Tip in SOL attached to Jito bundles when enabled.",
+    recommended: DEFAULT_CONFIG.jito.tip,
+    defaultValue: DEFAULT_CONFIG.jito.tip,
+  },
+};
 
 const askQuestion = (rl, prompt) =>
   new Promise((resolve) => rl.question(prompt, (answer) => resolve(answer.trim())));
@@ -73,6 +127,16 @@ function renderWizardHeader() {
   console.log("Press Enter to keep the current value.\n");
 }
 
+function renderWizardFieldGuidance(field) {
+  const guidance = WIZARD_FIELD_GUIDANCE[field];
+  if (!guidance) {
+    return;
+  }
+  console.log(`Help: ${guidance.helper}`);
+  console.log(`Recommended: ${toDisplayValue(guidance.recommended)}`);
+  console.log(`Default: ${toDisplayValue(guidance.defaultValue)}\n`);
+}
+
 function toDisplayValue(value) {
   if (value === undefined || value === null) return "";
   if (typeof value === "object") return JSON.stringify(value);
@@ -229,24 +293,26 @@ async function runConfigWizard({ cfg, rl }) {
 
   clearScreen();
   renderWizardHeader();
-  console.log("RPC URL should be the SolanaTracker endpoint assigned to you.");
-  console.log("advancedTx=true is enforced automatically.\n");
+  renderWizardFieldGuidance("rpcUrl");
   nextCfg.rpcUrl = await promptNormalized(rl, "RPC URL", "rpcUrl", { current: nextCfg.rpcUrl });
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("slippage");
   nextCfg.slippage = await promptNormalized(rl, "Max slippage (number or \"auto\")", "slippage", {
     current: nextCfg.slippage,
   });
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("priorityFee");
   nextCfg.priorityFee = await promptNormalized(rl, "Priority fee (number or \"auto\")", "priorityFee", {
     current: nextCfg.priorityFee,
   });
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("priorityFeeLevel");
   nextCfg.priorityFeeLevel = await promptSelect(
     rl,
     "Priority fee level (used when priorityFee is auto)",
@@ -259,12 +325,14 @@ async function runConfigWizard({ cfg, rl }) {
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("txVersion");
   nextCfg.txVersion = await promptSelect(rl, "Transaction version", TX_VERSIONS, {
     current: nextCfg.txVersion,
   });
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("showQuoteDetails");
   const showQuoteDetails = await promptSelect(rl, "Show quote details", ["true", "false"], {
     current: nextCfg.showQuoteDetails ? "true" : "false",
   });
@@ -272,6 +340,7 @@ async function runConfigWizard({ cfg, rl }) {
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("DEBUG_MODE");
   const debugMode = await promptSelect(rl, "Enable debug mode", ["true", "false"], {
     current: nextCfg.DEBUG_MODE ? "true" : "false",
   });
@@ -279,6 +348,7 @@ async function runConfigWizard({ cfg, rl }) {
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("notificationsEnabled");
   const notificationsEnabled = await promptSelect(rl, "Enable notifications", ["true", "false"], {
     current: nextCfg.notificationsEnabled ? "true" : "false",
   });
@@ -286,6 +356,7 @@ async function runConfigWizard({ cfg, rl }) {
 
   clearScreen();
   renderWizardHeader();
+  renderWizardFieldGuidance("jitoEnabled");
   const jitoEnabled = await promptSelect(rl, "Enable Jito bundles", ["true", "false"], {
     current: nextCfg.jito.enabled ? "true" : "false",
   });
@@ -293,6 +364,7 @@ async function runConfigWizard({ cfg, rl }) {
   if (nextCfg.jito.enabled) {
     clearScreen();
     renderWizardHeader();
+    renderWizardFieldGuidance("jitoTip");
     const requireTip = nextCfg.jito.tip === undefined || nextCfg.jito.tip === null;
     nextCfg.jito.tip = await promptNumber(rl, "Jito tip (SOL)", {
       current: nextCfg.jito.tip,
@@ -311,25 +383,78 @@ const getTradeModule = async () => {
   return tradeModulePromise;
 };
 
-async function executeTrade(type, mint, amountArg) {
-  const cfg = await loadConfig();
+function getTradeCommandExample(type, mint = MINT_EXAMPLE) {
+  const amountExample = type === "buy" ? "0.01" : "auto";
+  return `summon ${type} ${mint} ${amountExample}`;
+}
+
+function renderTradeValidationErrors(type, validation) {
+  console.error(`Usage: summon ${type} [mint] [amount]`);
+  for (const issue of validation.issues) {
+    console.error(`⚠️  ${issue.message}`);
+    if (issue.field === "mint") {
+      console.error(`    Example: ${getTradeCommandExample(type)}`);
+      continue;
+    }
+    if (issue.field === "amount") {
+      const amountExamples = getAmountExamples(type).join(", ");
+      const mintForExample = validation.mint || MINT_EXAMPLE;
+      console.error(`    Amount examples: ${amountExamples}`);
+      console.error(`    Example: ${getTradeCommandExample(type, mintForExample)}`);
+    }
+  }
+}
 
-  if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(mint)) {
-    console.error("⚠️  Invalid mint format. Expected base58 address (32–44 chars).");
+async function resolveTradeInput(type, mintArg, amountArg) {
+  let mint = mintArg;
+  let amount = amountArg;
+  let validation = validateTradeInput({ type, mint, amount });
+  if (validation.ok) {
+    return validation;
+  }
+
+  const canPrompt = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!canPrompt) {
+    renderTradeValidationErrors(type, validation);
     process.exit(1);
   }
 
-  let amountParam = amountArg.toString().trim().toLowerCase().replace(/\s+/g, "");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
 
-  if (amountParam !== "auto" && !amountParam.endsWith("%")) {
-    const num = parseFloat(amountParam);
-    if (isNaN(num) || num <= 0) {
-      console.error("⚠️  Invalid amount. Use a positive number, 'auto' during a sell, or '<percent>%'.");
-      process.exit(1);
+  try {
+    while (!validation.ok) {
+      const mintIssue = validation.issues.find((issue) => issue.field === "mint");
+      if (mintIssue) {
+        console.log(`⚠️  ${mintIssue.message}`);
+        console.log(`   Example mint: ${MINT_EXAMPLE}`);
+        mint = await askQuestion(rl, "Mint address: ");
+      }
+
+      const amountIssue = validation.issues.find((issue) => issue.field === "amount");
+      if (amountIssue) {
+        console.log(`⚠️  ${amountIssue.message}`);
+        console.log(`   Amount examples: ${getAmountExamples(type).join(", ")}`);
+        amount = await askQuestion(rl, "Amount: ");
+      }
+
+      validation = validateTradeInput({ type, mint, amount });
     }
-    amountParam = num;
+  } finally {
+    rl.close();
   }
 
+  return validation;
+}
+
+async function executeTrade(type, mintArg, amountArg) {
+  const cfg = await loadConfig();
+  const validated = await resolveTradeInput(type, mintArg, amountArg);
+  const mint = validated.mint;
+  const amountParam = validated.amount;
+
   try {
     const mintDisplay = `${mint.slice(0, 4)}…${mint.slice(-4)}`;
     const amountDisplay = String(amountParam);
@@ -357,7 +482,7 @@ async function executeTrade(type, mint, amountArg) {
       }
 
       const { buyToken } = await getTradeModule();
-      const result = await buyToken(mint, amountParam);
+      const result = await buyToken(mint, amountParam, { cfg });
       clearScreen();
       const info = `Received ${result.tokensReceivedDecimal} tokens | Fees ${result.totalFees} | Impact ${result.priceImpact}`;
       const buyRows = [
@@ -373,7 +498,7 @@ async function executeTrade(type, mint, amountArg) {
       }
     } else if (type === "sell") {
       const { sellToken } = await getTradeModule();
-      const result = await sellToken(mint, amountParam);
+      const result = await sellToken(mint, amountParam, { cfg });
       clearScreen();
       const info = `Received ${result.solReceivedDecimal} SOL | Fees ${result.totalFees} | Impact ${result.priceImpact}`;
       const sellRows = [
@@ -609,15 +734,15 @@ keychainCmd
   });
 
 program
-  .command("buy <mint> <amount>")
-  .description("Buy a token with SOL")
+  .command("buy [mint] [amount]")
+  .description("Buy a token with SOL (prompts for missing values in interactive TTY)")
   .action(async (mint, amount) => {
     await executeTrade("buy", mint, amount);
   });
 
 program
-  .command("sell <mint> <amount>")
-  .description("Sell a token for SOL")
+  .command("sell [mint] [amount]")
+  .description("Sell a token for SOL (prompts for missing values in interactive TTY)")
   .action(async (mint, amount) => {
     await executeTrade("sell", mint, amount);
   });
@@ -659,13 +784,13 @@ program
         // Try base58 format
         const bytes = bs58.decode(rawKey);
         keypair = Keypair.fromSecretKey(bytes);
-      } catch (err) {
+      } catch {
         try {
           // Try JSON array format
           const arr = JSON.parse(rawKey);
           if (!Array.isArray(arr)) throw new Error("Not an array");
           keypair = Keypair.fromSecretKey(Uint8Array.from(arr));
-        } catch (jsonErr) {
+        } catch {
           throw new Error("Private key is neither base58 nor valid JSON array.");
         }
       }
@@ -679,6 +804,23 @@ program
     }
   });
 
+function extractSuggestedCommands(results) {
+  const commands = new Set();
+  for (const result of results) {
+    if (result.status !== "fail" || !result.hint) {
+      continue;
+    }
+    const matches = [...result.hint.matchAll(/`([^`]+)`/g)];
+    for (const match of matches) {
+      const candidate = match[1].trim();
+      if (candidate.startsWith("summon ")) {
+        commands.add(candidate);
+      }
+    }
+  }
+  return [...commands];
+}
+
 // DOCTOR command
 program
   .command("doctor")
@@ -689,12 +831,28 @@ program
     for (const result of results) {
       const icon = result.status === "ok" ? "✅" : result.status === "skip" ? "⚠️" : "❌";
       console.log(`${icon} ${result.name}: ${result.message}`);
+      if (result.status === "fail" && result.hint) {
+        console.log(`   • Hint: ${result.hint}`);
+      }
       if (options.verbose && result.details) {
         console.log(`   • ${result.details}`);
       }
     }
-    const hasFailure = results.some((item) => item.status === "fail");
-    process.exit(hasFailure ? 1 : 0);
+    const failures = results.filter((item) => item.status === "fail");
+    const suggestedCommands = extractSuggestedCommands(results);
+
+    console.log("");
+    console.log(
+      `Doctor summary: ${failures.length} failure${failures.length === 1 ? "" : "s"} out of ${results.length} checks.`
+    );
+    if (suggestedCommands.length) {
+      console.log("Suggested commands:");
+      for (const command of suggestedCommands) {
+        console.log(`  • ${command}`);
+      }
+    }
+
+    process.exit(failures.length ? 1 : 0);
   });
 
 // MANUAL command
@@ -751,12 +909,13 @@ USAGE:
   summon keychain delete
       Delete the private key from macOS Keychain
 
-  summon buy <mint> <amount>
-  summon sell <mint> <amount>
+  summon buy [mint] [amount]
+  summon sell [mint] [amount]
       Buy or sell a token. Amount formats:
         • Fixed amount (e.g. 0.5 or 100)
         • Percent of holdings (e.g. 50%)
         • "auto" (sell only — sells your full balance)
+      In an interactive terminal, missing/invalid mint or amount will be prompted.
 
   summon wallet
       Open your wallet on SolanaTracker.io

package/utils/notify.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { NotificationError } from "../lib/errors.js";
 import { logger } from "./logger.js";
 
@@ -16,6 +16,8 @@ function escapeAppleScriptString(str) {
  * @param {string} [options.message=""]
  * @param {string} [options.subtitle=""]
  * @param {string} [options.sound]
+ * @param {boolean} [options.blocking] When true, waits for osascript completion.
+ *                                     Defaults to throwOnError so strict callers stay blocking.
  */
 export function notify({
   title = "summonTheWarlord",
@@ -23,6 +25,7 @@ export function notify({
   subtitle = "",
   sound,
   throwOnError = false,
+  blocking = throwOnError,
 } = {}) {
   if (process.platform !== "darwin") {
     const bell = "\u0007";
@@ -42,10 +45,33 @@ export function notify({
       script += ` sound name "${escapeAppleScriptString(sound)}"`;
     }
 
-    const result = spawnSync("osascript", ["-e", script], { stdio: "ignore" });
-    if (result.error || result.status !== 0) {
-      throw new NotificationError(`osascript exited with ${result.status}`, { cause: result.error });
+    if (blocking) {
+      const result = spawnSync("osascript", ["-e", script], { stdio: "ignore" });
+      if (result.error || result.status !== 0) {
+        throw new NotificationError(`osascript exited with ${result.status}`, { cause: result.error });
+      }
+      return true;
     }
+    let handledFailure = false;
+    const fallback = () => {
+      if (handledFailure) return;
+      handledFailure = true;
+      console.log(`🔔 ${title}: ${message}${subtitle ? ` - ${subtitle}` : ""}`);
+    };
+    const child = spawn("osascript", ["-e", script], { stdio: "ignore" });
+    child.once("error", (err) => {
+      logger.warn("Notification failed.", { error: err?.message });
+      fallback();
+    });
+    child.once("exit", (code) => {
+      if (code !== 0) {
+        logger.warn("Notification failed.", { error: `osascript exited with ${code}` });
+        fallback();
+      }
+    });
+    // Intentionally keep the child process referenced so CLI flows that call
+    // process.exit(...) immediately after notify still allow exit/error handlers
+    // to run and emit the console fallback when delivery fails.
     return true;
   } catch (err) {
     logger.warn("Notification failed.", { error: err?.message });