v0.3.0 — explain and migrate, stack health score, corpus research

What's new

New commands

• rightstack explain <query> — look up any tool by npm package name, tool ID, or alias. Shows ecosystem fit, scale guidance, common pairings, migration warnings, and source links. Detects when you search for a deprecated/renamed package (e.g. explain @solana/web3.js warns and redirects to @solana/kit).
• rightstack migrate <from-package> — full migration guide for any package in the corpus: migration path, detailed notes, and install/uninstall commands.

Repo audit improvements

• Stack health score — every repo-audit now shows a 0–100 score and A/B/C/D/F grade in the header. Formula: 100 − min(criticals×25, 75) − min(highs×10, 30) − min(mediums×3, 15). Included in --json output.
• CRITICAL false-positive bug fix — the CRITICAL tier was firing on sdk_migration.status alone, ignoring which package triggered detection. A repo with @solana/kit (the correct, modern package) would incorrectly receive CRITICAL if solana-kit had migrating-from status. Now mirrors the package-aware check already used by MEDIUM.

Corpus (9 tools updated)

• solana-kit: successor → migrating-from — @solana/web3.js v1 is in maintenance mode; CRITICAL now fires for repos using it
• alchemy-account-kit: migrating-from — @alchemy/aa-* abandoned Aug 2024, CRITICAL fires
• turnkey: migrating-from — @turnkey/sdk-browser README-deprecated in favour of @turnkey/core
• zerodev, dynamic, wagmi: migrating-from — semver cases; CRITICAL will fire after Phase 5.1 semver matching
• onchainkit, privy, pimlico: stable — confirmed, no migration story

GitHub Action template

examples/github-action/rightstack-audit.yml — PR bot that posts a severity table comment on every PR touching package.json or lockfiles.

---

Benchmark gate: 50/50. tsc: clean.

v0.2.0 -mcp server and severity engine

What's in this release

MCP Server (rightstack-mcp)

AI coding agents (Claude Code, Cursor, Windsurf) can now call RightStack natively via tool use.

{
  "mcpServers": {
    "rightstack": {
      "command": "npx",
      "args": ["-y", "rightstack", "rightstack-mcp"]
    }
  }
}

Three tools available:

• recommend — Intent-aware stack recommendation for a web3 build goal
• workflow — Retrieve a workflow record by ID with full phase detail
• repo_audit — Audit a local repo's package.json for stack gaps, anti-patterns, migration warnings, and severity-ranked action items

Severity Engine (repo-audit)

rightstack repo-audit <path> now outputs a ranked action list instead of a flat warning dump.

  Action Items (4 +6 info)
  ──────────────────────────────────────────────────────
  🔴 CRITICAL   wagmi
    Deprecated SDK detected
    wagmi v1 to v2 was a breaking change. Migrate to wagmi@^2.
    Fix: wagmi@^2

  🟠 HIGH       elizaos
    Experimental tool in stack
    ElizaOS has trust_state 'experimental'. Production use carries stability risk.

  🟡 MEDIUM     reown
    Package migration available
    WalletConnect rebranded to Reown. @walletconnect/* → @reown/appkit.
    Fix: @reown/appkit

Four severity tiers — all derived from existing corpus data, no API calls:

• CRITICAL: deprecated or migrating-from SDK detected in dependencies
• HIGH: experimental or abandoned tool in stack
• MEDIUM: package alias/migration available
• INFO: anti-pattern advisories (capped at 2/tool in CLI output, all in JSON/MCP)

The repo_audit MCP tool output now includes actionItems[] — machine-actionable severity for AI agents.

---

Benchmark gate

50/50 PASS · 10/10 golden stable · no regressions vs db-phase2 snapshot