feat: add admin pprof and its client

[ferhatelmas]

What kind of change does this PR introduce?

feat

What is the current behavior?

There is no programmatic pprof profile capture.

What is the new behavior?

• Add admin routes to programmatically capture CPU or heap pprof profiles via Watt control.
• Add a script to request a capture, parse a multipart/mixed response, surface JSON started / ping / error parts, and save the final binary profile.
• Add flame graph generation after a successful capture.

Additional context

Works only with Watt, no handlers are registered otherwise.
By default, merges profiles from all workers.

[Copilot]

Pull request overview

Adds programmatic pprof capture support to the admin API when running under Platformatic Watt, plus a CLI client to download profiles and optionally generate flamegraph artifacts.

Changes:

• Add /debug/pprof/profile (CPU) and /debug/pprof/heap (heap) admin endpoints that stream multipart/mixed progress + final binary profile, with optional worker targeting and cross-worker merging.
• Add a pprof:capture script that requests a capture, parses the multipart stream, saves the resulting .pprof, and can run @platformatic/flame generate.
• Introduce internal helpers for Watt runtime selection, multipart streaming, profile merging, and client HTTP utilities (with unit tests).

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/scripts/pprof-client.ts	CLI entrypoint + env/arg parsing to request captures, download multipart stream, and optionally generate flame artifacts.
src/scripts/pprof-client.test.ts	Unit coverage for CLI parsing helpers (targets, boolean/integer env parsing).
src/internal/monitoring/pprof/types.ts	New shared types for Watt selection/session state, multipart writer, and runtime API client shape.
src/internal/monitoring/pprof/runtime.ts	Watt runtime selection + normalization helpers and error mapping for control API profiling.
src/internal/monitoring/pprof/runtime.test.ts	Tests for runtime helpers (selection, headers, error mapping, source map normalization).
src/internal/monitoring/pprof/profile.ts	Merges multiple pprof profile buffers into a single profile for “all workers” captures.
src/internal/monitoring/pprof/profile.test.ts	Tests for merge behavior and validation failures for incompatible profiles.
src/internal/monitoring/pprof/multipart.ts	Streams multipart/mixed responses (started/ping JSON parts + final binary profile) and keepalive/heartbeat window logic.
src/internal/monitoring/pprof/multipart.test.ts	Tests heartbeat/keepalive behavior and stopping on write failures.
src/internal/monitoring/pprof/flame.ts	Wrapper to spawn @platformatic/flame generate and normalize flame env/md-format inputs.
src/internal/monitoring/pprof/flame.test.ts	Tests for env normalization, arg building, and spawn behavior.
src/internal/monitoring/pprof/download.ts	Client-side multipart/mixed parser to surface JSON events and write the binary profile part to disk safely.
src/internal/monitoring/pprof/download.test.ts	Tests for multipart parsing, error parts, filename sanitization, and interrupted-stream diagnostics.
src/internal/monitoring/pprof/client-http.ts	HTTP client to request captures from the admin API and surface non-2xx responses with bounded body output.
src/internal/monitoring/pprof/client.test.ts	Tests for URL joining/query param handling and non-2xx error surfacing/truncation.
src/http/routes/admin/pprof.ts	New admin routes implementing Watt control-based profiling + multipart streaming and session coordination.
src/http/routes/admin/pprof.test.ts	Route-level tests for worker targeting, whole-app merging, conflict handling, abort handling, and onClose draining.
src/http/routes/admin/index.ts	Exposes the new pprof admin route module from the admin routes index.
src/admin-app.ts	Conditionally registers pprof endpoints + Swagger tag only when running under Watt.
src/admin-app.test.ts	Ensures pprof endpoints are 404 outside Watt and registered (401 due to ApiKey) under Watt.
package.json	Adds pprof:capture script and new runtime deps needed for capture/client/flame generation.
package-lock.json	Locks newly added dependencies and their transitive requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

Coverage Report for CI Build 24589571785

Coverage increased (+1.8%) to 69.89%

Details

• Coverage increased (+1.8%) from the base build.
• Patch coverage: 70 uncovered changes across 7 files (570 of 640 lines covered, 89.06%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
src/scripts/pprof-client.ts	77	47	61.04%
src/internal/monitoring/pprof/download.ts	193	174	90.16%
src/internal/monitoring/pprof/flame.ts	30	24	80.0%
src/internal/monitoring/pprof/profile.ts	88	82	93.18%
src/internal/monitoring/pprof/multipart.ts	40	36	90.0%
src/internal/monitoring/pprof/client-http.ts	44	41	93.18%
src/http/routes/admin/pprof.ts	84	82	97.62%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	9575
Covered Lines:	7060
Line Coverage:	73.73%
Relevant Branches:	5337
Covered Branches:	3362
Branch Coverage:	62.99%
Branches in Coverage %:	Yes
Coverage Strength:	379.42 hits per line

---

💛 - Coveralls

[Copilot]

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.