feat: make becwright dead-simple to adopt (demo command, 1-line install, visual README)

[DataDave-Dev]

Lower the friction of the first 60 seconds so becwright is easy for anyone, not just experts. Five polish items:

1. becwright demo — the instant "aha" (new command)

See becwright block a sample bad commit (a hardcoded secret + an eval) with zero setup, no git, nothing on your machine touched. Runs fully in-process, so it works with the npm standalone binary too. The "try before you install" path.

2. Visual README — a terminal-card SVG

assets/becwright-demo.svg shows a blocked commit (red BLOCK, the why) at the top of the README. Self-contained, inline presentation attributes only (renders reliably on GitHub, npm, PyPI). Plus a "see it in 5 seconds" callout.

3. One-line install

Reduced to a single recommended line (npm install -g becwright); pnpm/pip/project-local + the platform note folded into a <details> block.

4. Clearer becwright init

Ends with a numbered 1-2-3 of exactly what to do next instead of one sentence.

5. Ready-made rules gallery

A copy-paste section of becwright import <url> one-liners (Python, JS/TS, any-language) so people import a proven rule instead of writing one.

Notes

• demo added to the command tables and --help; status lines updated. EN + ES in sync.
• The demo sample's eval(...) line carries a becwright: ignore marker so the repo's own dogfooding rules stay green.
• The sample secret is an obviously-fake token (not a provider-format key), so it triggers becwright's hardcoded_secrets check without tripping GitHub push protection.
• No check logic, rule format, or dependencies changed.

Test plan

• becwright demo blocks both sample rules and cleans up its sandbox (no git, no cwd writes) — new tests.
• init prints next steps — new test.
• Full suite: 128 passed. becwright's own check --all is green.
• README terminal-card renders on GitHub (both EN and ES).

Summary by CodeRabbit

• New Features

  • Added a quick demo command to show how the tool flags risky code, with no setup required.
  • Added “Next steps” guidance after setup to help users continue with checks and commits.
  • Expanded the README with a faster getting-started flow and ready-made rule examples.

• Documentation

  • Updated usage docs and command tables to include the new demo command.
  • Improved installation guidance for different platforms and package managers.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: efa937b9-f26f-441f-8fb8-b7777804288e

📥 Commits

Reviewing files that changed from the base of the PR and between fcf940b and b70963b.

⛔ Files ignored due to path filters (1)

• assets/becwright-demo.svg is excluded by !**/*.svg

📒 Files selected for processing (7)

• README.es.md
• README.md
• documentation/usage.es.md
• documentation/usage.md
• src/becwright/cli.py
• tests/test_cli_and_git.py
• tests/test_init.py

---

📝 Walkthrough

Walkthrough

Adds a new becwright demo CLI subcommand that simulates a blocked commit by running secret and eval checks against a generated temp file, and adds a "Next steps" message after init. Updates README files (English/Spanish) and usage documentation to describe the demo command and a ready-made rules import section. Includes corresponding tests.

Changes

Demo Command and Documentation

Layer / File(s)	Summary
Init command prints next steps src/becwright/cli.py, tests/test_init.py	After init installs the git hook, it prints a "Next steps" checklist; a new test verifies this output.
Demo subcommand implementation and CLI wiring src/becwright/cli.py, tests/test_cli_and_git.py	Adds demo sample constants, a helper running dangerous_eval/hardcoded_secrets against a temp file, extends _cmd_demo to print results and guidance, registers the demo subcommand in the parser, and adds tests covering output, non-mutation of the working directory, and result flags.
README and usage documentation updates README.md, README.es.md, documentation/usage.md, documentation/usage.es.md	Adds "demo in 5 seconds" callouts, reworks installation instructions into a two-step flow, documents becwright demo in commands tables, adds a ready-made rules import section, and updates current-status CLI listings.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as cli._cmd_demo
  participant Checks as dangerous_eval/hardcoded_secrets
  participant TempDir as Temp file

  User->>CLI: becwright demo
  CLI->>TempDir: create sample file with secret and eval
  CLI->>Checks: run dangerous_eval(temp file)
  CLI->>Checks: run hardcoded_secrets(temp file)
  Checks-->>CLI: Result objects (passed=False)
  CLI->>User: print rule results and guidance message
  CLI->>TempDir: delete temp directory

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• DataDave-Dev/becwright#2: Both PRs update README pipx/installation instructions for becwright.
• DataDave-Dev/becwright#6: Extends the init command's output with a "Next steps" message, building on that PR's original init implementation.
• DataDave-Dev/becwright#12: Both PRs modify _build_parser() in src/becwright/cli.py to register new subcommands.

Poem

A rabbit hops to type demo,
No setup, no git, just watch it go! 🐰
A secret leaks, an eval too,
Blocked right there, in plain view.
Run init next, hop along —
Your commits now sing a safer song! 🎶

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/easy-onboarding

---

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.}