Agree a shared cross-platform JSON schema as the CLI contract

[aclinick]

Summary

If Juice gains a command line front end on more than one platform, the thing that should be shared is the output schema, not the implementation.
A script or an AI tool asking "what is drawing power right now" should not care whether it is talking to macOS or Windows.

Why this needs deciding up front

The two platforms genuinely measure different things, and pretending otherwise would produce a dishonest schema.

macOS meters CPU, GPU and Neural Engine energy per coalition from powerlog.
Windows meters physical rails through an ACPI Energy Meter Interface device, which exposes CPU cluster, GPU, supply and sometimes NPU rails, and on machines without that device it can only read battery discharge and therefore cannot report draw on AC at all.

So the schema needs to express "this field is genuinely unavailable here" rather than defaulting to zero.
That is the same principle already applied in the UI, where recording gaps render as gaps and are never interpolated.

Suggested rules

• Include a platform field so consumers can branch when they must.
• Make component fields nullable and omit them when unmeasured, rather than emitting 0.
  A zero watt reading and an unknown watt reading are different facts and must not be conflated.
• Carry the provenance of a reading, so a consumer can tell a hardware measurement from an estimate.
  The Windows port uses a tier for this (HardwareRail, Battery, Modelled, None); macOS has an equivalent distinction between powerlog and IOKit.
• Keep energy in watt-hours everywhere, since both platforms already normalise to that internally.
• Version the schema, so tooling can fail loudly rather than silently misread a future change.

Non-goal

This is not a proposal to unify the two codebases.
It is only a proposal to agree the JSON contract once, so that anything built on top of --json keeps working across platforms.

Related: #14.

[aclinick]

First stab, implemented in the Windows port at schema 0.1

Rather than leave this abstract, the Windows CLI now emits a versioned schema so there is something concrete to argue with.
It is deliberately 0.x: the shape can still change, and the version exists so that tooling finds out by assertion rather than by silent misreading.

Naming

Worth recording why the switch is --json and not something agent-specific.

The ecosystem standardised on encoding-flavoured names (gh --json, kubectl -o json, docker --format, npm --json), so anything novel costs familiarity and buys nothing a consumer can detect.
The real gap is that --json describes the encoding while what a consumer depends on is the shape being stable.

The closest prior art for that is not an AI convention at all, it is git --porcelain, which explicitly means "parseable and stable across versions" and which git versions as --porcelain=v2.
So the switch accepts an optional pin:

juice now --json        # whatever this build emits
juice now --json=0.1    # fail loudly if this build cannot honour 0.1

Only the major version has to match, since additive changes within a major are backwards compatible by definition.

The three rules that make one schema describe both platforms

1. A quantity that was not measured is omitted, never zero.
   An unknown reading and a zero reading are different facts.
   This matters immediately: a Windows machine without an Energy Meter device cannot report draw at all while on AC, and macOS cannot either.
2. Every measurement carries its provenance, so a consumer can tell a hardware measurement from an estimate without knowing the platform.
3. Every cost carries whether the price behind it was a regional average or the user's real tariff.
   Energy is measured; the price attached to it is the uncertain term.

Envelope

Every document shares this, and a consumer should branch on ok before reading anything else.
Failures are emitted in the same envelope on stdout rather than as prose on stderr, so tools mode never requires parsing two formats.

{
  "schemaVersion": "0.1",
  "platform": "windows",
  "command": "now",
  "generatedAt": "2026-07-29T05:27:10Z",
  "ok": true
}

Error case, with a stable code suitable for branching and a message that is not stable and should not be parsed:

{
  "schemaVersion": "0.1",
  "platform": "windows",
  "command": "now",
  "ok": false,
  "error": { "code": "noPowerSource", "message": "No power source is available on this machine." }
}

Exit codes: 0 success, 1 ran but produced no result, 2 usage error.

juice now

Real output from a Surface laptop, on AC:

{
  "schemaVersion": "0.1",
  "platform": "windows",
  "command": "now",
  "ok": true,
  "measurement": {
    "confidence": "measured",
    "source": "hardwareRail",
    "systemWatts": 34.688,
    "rails": { "cpu": 17.577, "gpu": 0.041, "supply": 34.639 }
  },
  "battery": { "present": true, "percent": 80, "flow": "pluggedIn" }
}

Note what is absent.
There is no npu key because this machine does not meter that rail, and no chargeWatts because a full battery trickling a few milliwatts is not charging.
flow is one of discharging / charging / pluggedIn / unknown.

confidence is measured / estimated / unavailable.
The macOS mapping would be measured for powerlog and IOKit readings, and unavailable on AC where discharge rate says nothing.

juice top

{
  "window": { "start": "...", "end": "...", "seconds": 12.0 },
  "energy": {
    "systemWattHours": 0.0861,
    "attributedWattHours": 0.0722,
    "platformWattHours": 0.0139
  },
  "rate": {
    "pricePerKwh": 0.170, "currency": "USD",
    "regionCode": "US", "regionName": "United States",
    "isEstimate": true
  },
  "apps": [
    {
      "appId": "copilot", "displayName": "copilot",
      "watts": 8.86, "wattHours": 0.0295,
      "components": { "cpu": 0.0295, "gpu": 0.0 },
      "processIds": [12345],
      "annualCost": 13.20
    }
  ]
}

attributedWattHours + platformWattHours == systemWattHours, always.
platformWattHours is defined as the residual rather than as "system minus compute rails" precisely so that holds even when a rail burns energy no process claims.
Energy is never silently lost from the totals.

components uses the same nullable rail names as measurement.rails, so macOS would populate cpu / gpu / npu with npu carrying Neural Engine energy.

Suggested for macOS

platform: "macos", source values of powerlog / iokit, and confidence: "unavailable" with systemWatts omitted when on AC.
Everything else carries over unchanged.

Happy to be told the shape is wrong while it is still 0.x.
Implementation is in windows/src/Juice.Core/Contracts/JuiceSchema.cs in the Windows port branch.