End-to-end research workflow: analytics, graceful shutdown, CLI fixes, UX improvements, README

[Copilot]

The tool had several broken flows for researchers: macaron scan with no targets caused a pflag parse error, the dashboard had no analytics, serve couldn't be stopped cleanly, and the help text referenced non-existent flag syntax. This PR also improves the overall CLI UX from first run through to export.

Bug fixes

• macaron scan (no targets) – removed the dangling --scn stub appended to os.Args, which caused pflag to fail instead of showing help
• Geo lookup context – lookupGeo used http.NewRequest (no cancellation); replaced with http.NewRequestWithContext
• Silent unmarshal in Analytics – corrupt stats rows now continue instead of accumulating zero values into totals

Analytics

• Store.Analytics() aggregates across all scans: cumulative totals, per-day activity (vulns + live hosts), top-10 targets by vuln count, severity distribution
• /api/analytics endpoint returns this as JSON
• Dashboard gains an Analytics toggle in the topbar: totals row, daily bar chart, top targets bar chart, severity distribution chart

Graceful shutdown

Serve() now takes a context.Context and calls http.Server.Shutdown on cancellation instead of blocking forever:

func (s *Server) Serve(ctx context.Context, addr string) error {
    srv := &http.Server{Addr: addr, Handler: mux}
    // ... ListenAndServe in goroutine ...
    select {
    case err := <-errCh:
        return err
    case <-ctx.Done():
        shutCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        return srv.Shutdown(shutCtx)
    }
}

CLI UX improvements

• printHelp() and printGuide() updated to use -- flags matching pflag registration (previously showed -dom, -prf, etc.)
• macaron scan / macaron with no args now show help cleanly
• Removed all stale "macaronV2" strings from terminal output — everything now says "macaron"
• --version prints macaron 3.0.0 (Go ...) cleanly
• macaron status (empty state) now shows the correct command syntax in the prompt
• macaron status table: added SUBS + PORTS columns, IDs truncated to 12 chars, human-readable date format
• macaron results --wht live: now renders as a go-pretty table with STATUS / URL / TITLE columns
• macaron results --wht vulns: now renders as a go-pretty table with SEVERITY / TEMPLATE / MATCHED columns
• After a scan completes, a "What next?" block prints the next commands to run (status, results, serve)
• macaron setup: shows installed/total tool count, reports how many required tools are missing, and prints a next-steps workflow once all required tools are present

Install & README

• install.sh adds PATH to ~/.zshrc and ~/.profile in addition to ~/.bashrc (macOS / non-bash users)
• README rewritten with accurate command reference, profiles table, stages table, and dashboard description

[root-Manas]

Give me exact details of what you implemented and also give me a plan of making this cli tool to just make it better if it's not already and make it easier to use like make it fully functional and have better ux from start to end.

[Copilot]

Give me exact details of what you implemented and also give me a plan of making this cli tool to just make it better if it's not already and make it easier to use like make it fully functional and hav...

Here's a precise breakdown of everything implemented across both commits, and what was done in this pass to make the tool more usable end-to-end.

---

What was implemented (commit 15c6cff)

Area	Change
Bug fix	macaron scan with no targets used to throw a pflag parse error — now shows help
Bug fix	lookupGeo ignored request cancellation — now uses http.NewRequestWithContext
Graceful shutdown	macaron serve now catches Ctrl-C and shuts down cleanly with a 5-second drain window
Analytics backend	Store.Analytics() computes: total findings across all scans, per-day activity, top-10 targets by vuln count, severity distribution
Analytics API	/api/analytics endpoint added to the web server
Analytics dashboard	"Analytics" toggle button in the topbar opens a full-width panel with totals row, daily activity bar chart, top targets chart, and severity distribution
CLI help	printHelp() and printGuide() rewritten to use -- double-dash flags that actually work
README	Rewritten with accurate command reference, profiles table, stages table, and dashboard description
install.sh	Now adds PATH to ~/.zshrc and ~/.profile in addition to ~/.bashrc

---

UX improvements (commit 7111afb)

Area	Change
Branding	Removed all "macaronV2" strings from terminal output → just "macaron"
--version	Now prints macaron 3.0.0 (Go go1.25.0) instead of macaronV2 3.0.0 (Go go1.25.0, stable)
macaron status (empty)	Now says No scans found.\nRun: macaron scan example.com with correct command syntax
macaron status table	Added SUBS + PORTS columns; truncated IDs to 12 chars; human date format (2026-01-02 15:04)
macaron results --wht live	Now renders as a go-pretty table with STATUS / URL / TITLE columns
macaron results --wht vulns	Now renders as a go-pretty table with SEVERITY / TEMPLATE / MATCHED columns
Post-scan hint	After a scan completes, prints "What next?" with macaron status, macaron results --dom <target> --wht live, macaron results --dom <target> --wht vulns, macaron serve
macaron setup	Shows installed count (4/10 tools installed), counts missing required tools, prints next-steps workflow when all required tools are present

---

Dashboard screenshots:

Main scan view (scan list + detail panel with metrics, stage yield, geo map):

Analytics panel (totals, daily activity bars, top targets, severity distribution):

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• api.demo.dev
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)
• api.example.com
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)
• api.testapp.io
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)
• demo.dev
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)
• example.com
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)
• testapp.io
  • Triggering command: /tmp/macaron /tmp/macaron serve --str /tmp/mactest_serve --addr 127.0.0.1:8188 copilot/build-e2-c=4 ux-amd64/pkg/tool/linux_amd64/vet --depth 3 REDACTED ux-amd64/pkg/tool/linux_amd64/vet rg/t�� 04jvgDt9G --global pkg/mod/golang.org/toolchain@v0.-o committer.email bis (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)