nyx/scripts

scripts

Local helpers for repo-wide checks and a couple of one-off tools.

Script	What it does
fix.sh	Apply all auto-fixes (clippy, fmt, eslint, prettier), then run tests.
check.sh	Verify only (no fixes). Mirrors the GitHub Actions CI workflow.
cached-cargo-test.sh	Wrap cargo test with a source-hash cache; concurrent invocations of the same args share one run.
capture-screenshots.mjs	Capture the README stills and demo GIF from a running nyx serve. Needs Playwright and ffmpeg.
frame-screenshots.py	Wrap a PNG in the brand purple gradient. Called by capture-screenshots.mjs as its final phase, but can be run standalone.

Fixers stream their output (so you can see what changed); tests run quietly and only show output if they fail. Both scripts print a green/red summary at the end and exit non-zero if any step failed.

Usage

./scripts/fix.sh                # fix everything + run tests
./scripts/fix.sh --no-tests     # just apply fixes
./scripts/fix.sh --rust-only    # skip frontend
./scripts/fix.sh --frontend-only

./scripts/check.sh              # verify everything (CI-equivalent)
./scripts/check.sh --rust-only

Scripts can be run from any directory; they resolve the repo root from their own location.

Cached cargo test

Wraps cargo test. The first run executes normally and records its output keyed by a hash of the source tree. Later runs with the same args and an unchanged tree return the cached output. Concurrent callers share a single cargo run via a mkdir lock.

./scripts/cached-cargo-test.sh --lib
./scripts/cached-cargo-test.sh --tests
FORCE_CARGO=1 ./scripts/cached-cargo-test.sh --lib   # bypass cache

Use it for full-suite invocations. Narrow per-test runs (cargo test some_function) are fast on their own and just clutter the cache.

Capture screenshots

Regenerates assets/screenshots/*.png and assets/screenshots/demo.gif for the README and docs/. Requires Playwright, ffmpeg, and Python 3 with Pillow on PATH, plus a running nyx serve on $NYX_URL (default http://127.0.0.1:9876). The served scan root must have no prior scans.

node scripts/capture-screenshots.mjs --stills   # only PNGs
node scripts/capture-screenshots.mjs --gif      # only the GIF
node scripts/capture-screenshots.mjs --all      # both

The script writes a synthetic demo to $SCAN_ROOT (default /tmp/nyx-demo-app). V1 has four endpoints and produces a 5-hop CMDi taint flow that the GIF drills into. After scan #1 the script overwrites the demo with V2 (just that one flow) and runs scan #2 via the API, so the overview trend chart shows findings going down.

Stills are captured in two phases:

• After scan #1 (more findings): serve-findings-list.png, serve-finding-detail.png.
• After scan #2 (trend established): serve-overview.png, serve-triage.png, serve-explorer.png, serve-scans.png, serve-scan-detail.png, serve-rules.png, serve-config.png.

Then frame-screenshots.py runs over every captured PNG and wraps it in the brand purple gradient (1800x1113 outer, 1600x992 inner, 12px rounded corners, top-left #8a5bf5 to bottom-right #4d1d97). Finally, docs/serve-overview.png is copied to the top-level overview.png because that is the path the README references.

GIF storyboard:

1. Empty dashboard with the "Run your first scan" prompt.
2. Click Start Scan in the header bar to open the modal.
3. Confirm in the modal and wait for the scan to finish.
4. Back to the overview, scroll down through the cards, scroll back.
5. Click Findings in the sidebar.
6. Click the 5-hop taint row.
7. On the finding detail, expand Evidence, Analysis Notes, and Confidence Reasoning.
8. Open the triage status dropdown and dismiss it.
9. Navigate to /debug/call-graph for the closing visual.

To frame an existing PNG without re-capturing:

python3 scripts/frame-screenshots.py path/to/foo.png [...]

Run with no args to re-frame every PNG under assets/screenshots/.