feat(stats): report cpuPercent in the machine-readable formats

[guanchzhou]

Fixes #2144

container stats already samples twice, sleeping two seconds between samples, and computes a CPU percentage from the pair for its table. Output.render received only stats2, so json, yaml and toml consumers paid that latency and got back neither the percentage nor the earlier sample needed to derive it. Obtaining a CPU percentage from the CLI meant invoking the command twice and diffing cpuUsageUsec by hand — four seconds of sleeping for a number the tool already had after two.

Change

A StatsReport payload for the non-table formats: the latest sample plus the derived percentage.

ContainerResource.ContainerStats is documented as modelling a single sample, and a rate is not a property of one sample, so the derived value lives in the command rather than widening that type. That also keeps the wire shape of the existing fields unchanged — cpuPercent is additive.

The two-second interval becomes a single sampleInterval constant. collectStats sleeps for it and calculateCPUPercent divides by it, so the two have to agree; they were separate .seconds(2) literals before, one in collectStats and one in statsTable.

Verification, end to end with this build

Table (unchanged) and json side by side, same runtime, four containers — one of them a while :; do :; done loop allocated a single CPU:

$ .build/debug/container stats --no-stream
Container ID  Cpu %    Memory Usage            Pids
cs-spin       101.49%  2.69 MiB / 256.00 MiB   1
cs-mem        0.00%    66.96 MiB / 512.00 MiB  1
arango        0.65%    5.64 GiB / 6.00 GiB     61
cs-idle       0.00%    2.60 MiB / 2.00 GiB     1

$ .build/debug/container stats --no-stream --format json
fields: [blockReadBytes, blockWriteBytes, cpuPercent, cpuUsageUsec, id,
         memoryLimitBytes, memoryUsageBytes, networkRxBytes, networkTxBytes, numProcesses]

cs-spin    cpuPercent = 107.43
cs-mem     cpuPercent = 0
arango     cpuPercent = 0.7456
cs-idle    cpuPercent = 0

The percentages agree with the table across independent samplings, and the single-CPU spin loop reads ~100% as expected.

yaml and toml carry the field too, including through TOML's [[items]] wrapper for top-level arrays:

- id: cs-spin
  cpuPercent: 1.045919e+2

[[items]]
cpuPercent = 102.27360000000002

swift build --product container succeeds; swift test --filter ContainerCommandsTests → 29 tests in 10 suites passed.

Two things I left for your call

1. Units in the name. calculateCPUPercent documents "100% = one fully utilized core", matching top and docker stats. I noted that on the field, because I made the opposite mistake against this API before checking container stats as ground truth — dividing by the container's CPU allocation, which understates a 4-CPU container fourfold. Happy to rename to something like cpuPercentOfOneCore if you would prefer the convention in the name.
2. stats1 is still dropped. Emitting both samples would let a consumer compute other rates (network and block I/O per second) the same way. I kept this PR to the one number the table already shows; say the word if the fuller shape is preferable.

Environment: macOS 27.0 (Tahoe), Apple silicon, Swift 6.4.

Per CONTRIBUTING: I used AI assistance while investigating and drafting this, and I can explain and justify every line — the change moves an already-computed value into the rendered payload and de-duplicates one interval literal.

[kavix]

Thanks for working on this, @guanchzhou! Adding cpuPercent to the machine-readable output is a useful improvement, and consolidating the hardcoded 2-second sleep into sampleInterval also helps prevent sampling drift.

A few small suggestions that could improve maintainability

1. Deduplicate CPU calculation
   Consider moving cpuPercent into a computed property on StatsSnapshot. This would allow both StatsReport and statsTable to share the same calculation logic and avoid duplication.
2. Avoid field duplication in StatsReport
   Rather than manually mirroring all properties from ContainerResource.ContainerStats (and potentially missing fields added in the future), consider wrapping stats2 directly and implementing a custom encode(to:). This would make the implementation more resilient to future changes.
3. Add test coverage
   Please consider adding or updating unit/snapshot tests to verify that --format json includes the expected cpuPercent field.

[guanchzhou]

Thanks @kavix — took all three.

1. cpuPercent is now a computed property on StatsSnapshot. The table and StatsReport both read it.

2. StatsReport wraps the latest sample instead of copying its fields, and encode(to:) flattens through one keyed container. I didn't call stats.encode(to:) and then add cpuPercent on a second container: that works for JSON and YAML, but TOMLEncoder resets encoder.value on each container(keyedBy:), so the sample fields would disappear from toml output.

3. Unit tests cover the formula and the flattened json/yaml/toml shape. The existing --format json CLI tests now require cpuPercent.

[kavix]

LGTM!