fix: polish CLI launch and sandbox conflict hints

[Ker102]

Summary

• show a nullstate launch screen with next commands when running the root command
• print a clear LocalStack port 4566 recovery hint when sandbox startup fails
• include compose-style LocalStack container names in sandbox cleanup discovery

Tests

• python -m unittest tests.test_cli tests.test_sandbox -v
• python -m ruff check src\nullstate\cli.py tests\test_cli.py tests\test_sandbox.py

Summary by CodeRabbit

Release Notes

• New Features

  • CLI now displays a launch banner with next steps guidance when run without a subcommand.

• Bug Fixes

  • Improved error messaging and hints when sandbox startup fails.
  • Enhanced sandbox container removal with better detection and handling.

• Tests

  • Added test coverage for launch screen display and sandbox operations.

[coderabbitai]

Warning

Rate limit exceeded

@Ker102 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 19 minutes and 55 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 655e4bc1-3ba3-4422-9b00-38f47e03c16b

📥 Commits

Reviewing files that changed from the base of the PR and between 0f41d36 and e8f27e3.

📒 Files selected for processing (3)

• README.md
• docs/case-study.md
• docs/demo-script.md

📝 Walkthrough

Walkthrough

This PR adds LocalStack-specific container management to the sandbox CLI. The CLI app now invokes a callback handler to print a launch banner when run without subcommands. The sandbox down command supports a two-phase flow: explicit LocalStack container removal or backend-specific teardown with Docker-based container discovery. New helpers enable pattern matching, container listing, and hint rendering.

Changes

LocalStack Container Management for Sandbox CLI

Layer / File(s)	Summary
Backend Data Contracts src/nullstate/sandbox.py	SandboxBackend.down_commands() now accepts optional container_names parameter to generate docker rm -f commands. New container_image() method maps localstack-aws and localstack-azure to LocalStack image names.
CLI App Entry Point & Callback src/nullstate/cli.py	Typer app configured with invoke_without_command=True and no_args_is_help=False. New @app.callback() handler prints banner and "next steps" panel when CLI runs with no subcommand.
Sandbox Down Two-Phase Command src/nullstate/cli.py	sandbox_down refactored to first check if provided name matches explicit LocalStack container pattern; if so, generates direct docker rm -f commands; otherwise resolves backend-specific commands with optional container discovery and detail output.
Container Discovery & Command Helpers src/nullstate/cli.py	New utilities: _resolve_sandbox_down_commands (aggregates container names via lister), _resolve_explicit_sandbox_container_down_commands (builds docker rm -f for explicit names), _list_sandbox_containers (Docker ps filtering), _is_localstack_container_name (pattern matcher), _print_sandbox_start_failure_hints (troubleshooting panel).
Sandbox Up Startup Failure Hints src/nullstate/cli.py	sandbox_up now calls _print_sandbox_start_failure_hints() to emit LocalStack-specific troubleshooting guidance before raising typer.Exit(code=1) on command failure.
Tests & Verification tests/test_cli.py, tests/test_sandbox.py	CLI integration test validates root command prints launch screen. Backend and sandbox-down tests verify container-aware down commands, container discovery filtering, explicit container removal, and command resolution with mocked container lister.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A rabbit hops through containers bright,
LocalStack rabbits take their flight,
Down commands phase in patterns known,
From explicit names to discovery shown,
The banner prints when no args shine! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: polish CLI launch and sandbox conflict hints' directly matches the main changes: improving CLI launch messaging and enhancing sandbox conflict detection/hints.
Description check	✅ Passed	The PR description covers the three primary changes (launch screen, LocalStack port recovery hint, container name discovery) and includes test plan details; template sections are appropriately addressed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/final-cli-ux-polish

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/nullstate/cli.py`:
- Around line 516-528: Before executing the explicit-container teardown path,
verify the requested container name actually exists and its image matches one of
the allowed LocalStack images: call Docker inspect/list to confirm an exact
container with the given name and check the container.Image (or RepoTags)
against the supported image set; only then proceed to call
_resolve_explicit_sandbox_container_down_commands(name) and run_commands;
otherwise raise typer.BadParameter(str(error)) to preserve the backend
validation error. Update the sandbox-down handling where
_resolve_explicit_sandbox_container_down_commands, render_commands, and
run_commands are used (also mirror this validation logic at the other spots you
noted) so a typo like "localstack-aws" will not trigger destructive docker rm -f
on unrelated containers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: edf867aa-ee10-4973-b65c-e55c9c9be584

📥 Commits

Reviewing files that changed from the base of the PR and between 6716cd5 and 0f41d36.

📒 Files selected for processing (4)

• src/nullstate/cli.py
• src/nullstate/sandbox.py
• tests/test_cli.py
• tests/test_sandbox.py