`cargo stylus new` panics when stylus-sdk is not discoverable

[tusharpamnani]

Description

While trying to create a new Stylus project using cargo stylus new, the command panics if the stylus-sdk package cannot be located, without providing a user-facing error message or guidance on how to resolve the issue.

Since this is typically the first command a new developer runs, the panic makes it difficult to understand what prerequisite is missing or how to proceed.

---

Steps to Reproduce

1. Ensure cargo-stylus is installed

2. Run:

   cargo stylus new example

3. Observe the panic during project creation

---

Observed Behavior

The command panics with the following error:

thread 'main' panicked at ... stylus_sdk.rs:51:10:
Finding stylus-sdk package

No actionable information is provided about:

• where stylus-sdk is expected to be found
• whether it is missing, misconfigured, or version-incompatible
• how the user should resolve the issue

---

Expected Behavior

Instead of panicking, the tool could:

• surface a clear error message indicating that stylus-sdk is missing or not discoverable
• document the requirement explicitly before project creation
• or provide guidance on how to install or configure the dependency

---

Environment

• OS: Windows (via WSL2 / Ubuntu)
• Rust version: 1.92.0
• cargo-stylus version: 0.10.0

[anegg0]

@rory-ocl, does this issue still happen?

[Cripto5588]

Regarding the integration documentation in issue #3003, I believe we have an adoption bottleneck that isn't in the documentation itself, but rather in the CLI.
Currently, cargo stylus new simply panics if stylus-sdk isn't found or if there's some configuration mismatch. For a developer coming from JS or Solidity, a raw backtrace in Rust is just noise—it's scary and doesn't tell you what's really missing (is it a dependency? a toolchain? a path?). Most people simply give up before even writing a single line of code.

Foundry and Hardhat handle this much better, UX/UI techniques: friendly hints instead of crashing.

I propose:
Replace these panic errors with actionable error messages. If it fails, we show:
Exactly why it failed.
A copy-and-paste command to fix the problem.
A direct link to the specific documentation page.

We should use standard Rust diagnostic patterns (like rustc does) to not hide the error, but make it human-readable.
I'm ready to dive into the code, fix this, and test on test networks. I want to ensure that the integration flow we're building in #3003 doesn't break on the first command.
Available to start. Let me know if this aligns with what you have in mind for Stylus D.

[Cripto5588]

Hi @rory-ocl! I'm still available to implement the UX/UI fix identified above for the Stylus New role. Ready to work.