feat(#504): Add AI Contract Debugging Assistant

[Kayce10]

Summary

Closes #504

Implements a local, rule-based AI debugging assistant that helps developers identify bugs in Soroban smart contracts, understand errors, get fix suggestions, and perform root-cause analysis — all without any external API dependency.

---

Changes

src/utils/ai_debugger.rs (new — 746 lines)

Rule-based analysis engine providing:

• 10 error pattern matchers covering the most common Soroban contract failure modes:
  • AUTH001 — Missing/failed require_auth
  • ARITH001 — Integer overflow/underflow
  • STORE001 — Storage key not found
  • TOKEN001 — Insufficient token balance
  • PANIC001 — Contract runtime panic (unwrap, assert)
  • WASM001 — Invalid/corrupt WASM binary
  • NET001 — Contract not found on network
  • TTL001 — Storage entry TTL expired/archived
  • TEST001 — Cargo test assertion failure
  • TYPE001 — Argument type/ABI mismatch
• Stack trace parser — extracts structured frames from raw trace text
• Variable state inspector — flags zero amounts, max-value boundary conditions, empty addresses, and large collections
• 8 unit tests covering all major code paths

src/commands/ai_debug.rs (new — 365 lines)

CLI command starforge ai-debug with four subcommands:

Subcommand	Purpose
analyse	Analyse an error + optional stack trace + variable state
explain	Explain a named error category in depth
inspect	Inspect name=value variable pairs for suspicious values
test	Analyse cargo test failure output and suggest fixes

Registration changes

• src/commands/mod.rs — added pub mod ai_debug
• src/utils/mod.rs — added pub mod ai_debugger
• src/main.rs — AiDebug variant in Commands enum, command name, dispatch, and recovery hints

src/utils/horizon.rs — fixes pre-existing merge artifact

The file contained a duplicated fetch_account body using the removed ureq crate, causing an unclosed-delimiter compile error. Cleaned up to use the existing reqwest-based HTTP_CLIENT implementation.

---

Usage Examples

# Analyse an error message
starforge ai-debug analyse "require_auth failed for address GABC..."

# Analyse with stack trace file and variable state
starforge ai-debug analyse "storage key not found" \
  --stack-trace-file trace.txt \
  --var amount=0 --var caller=None

# Explain a category in depth
starforge ai-debug explain auth
starforge ai-debug explain arithmetic

# Inspect variable state
starforge ai-debug inspect amount=0 balance=9223372036854775807

# Analyse test failure output
starforge ai-debug test --file test_output.txt

# JSON output for CI/tooling
starforge ai-debug analyse "overflow" --format json

---

Acceptance Criteria

• Error explanations clear — every DebugFinding has a human-readable explanation field
• Bug identification accurate — 10 pattern matchers with keyword-based deduplication
• Fix suggestions working — each finding includes concrete fix_suggestion with code examples
• Root cause analysis helpful — root_cause field explains why the error occurs
• Integration with tests — ai-debug test subcommand analyses cargo test output

[drips-wave]

@Kayce10 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits