Module json_envelope

Expand description

Unified JSON output envelope shared across every subcommand.

Every --json invocation of socket-patch (whether scan, apply, get, list, gc/repair, remove, or rollback) emits the same top-level shape:

{
  "command":  "scan" | "apply" | "get" | ...,
  "status":   "success" | "partialFailure" | "error" | "noManifest" | ...,
  "dryRun":   false,
  "events":   [ { "action": "...", "purl": "...", ... }, ... ],
  "summary":  { "applied": 0, "downloaded": 0, ... }
  // "error":  { "code": ..., "message": ... }  — present only on failure
}

The events array is the load-bearing payload — each entry describes one observable thing that happened during the run (a patch was downloaded, applied, skipped, etc.). A downstream consumer (PR-comment bot, dashboard, log shipper) only needs to learn this single vocabulary to interpret output from every subcommand.

See CLI_CONTRACT.md for the per-subcommand action matrix and example jq recipes.

Structs§

Envelope: Top-level JSON envelope emitted by every --json invocation.
EnvelopeError: Top-level error payload set when the command failed before producing patch events.
PatchEvent: One observable thing that happened during a run.
PatchEventFile: One file referenced by a patch event.
SidecarAdvisory: Structured operator advisory. Replaces the previous free-form Option<String> field so consumers can switch on code and route on severity without regex-matching message.
SidecarFile: One file the fixup rewrote or deleted. Paths are relative to the package directory the patch landed in. (There is deliberately no “created” action — see SidecarFileAction, which reserves no variants ahead of an ecosystem that actually produces them.)
SidecarRecord: Per-package sidecar fixup outcome. Emitted under Envelope.sidecars[] one entry per package whose apply produced a fixup result (touched files or advisory).
Summary: Pre-aggregated counts across all events in this envelope. Field names match PatchAction variants for clarity.

Enums§

AppliedVia: Patch-source strategy used to apply a file. Mirrors the existing socket_patch_core::patch::apply::AppliedVia enum, but lives here so the JSON layer doesn’t depend on core internals.
Command: Which subcommand produced the envelope. Serializes lowercase.
PatchAction: What kind of thing happened to a patch.
SidecarAdvisoryCode: Stable enum tag for the kind of advisory. Adding a variant is a non-breaking change; renaming or removing one is breaking.
SidecarFileAction: What the fixup did with a sidecar file. Stable snake_case JSON tag — consumers branch on this without parsing free-form text.
SidecarSeverity: Severity bucket. UI consumers use this for badge color; jq pipelines filter by it. Error is reserved for the fixup itself failing — informational consequences of the apply use Info or Warning.
Status: Top-level status. Serializes camelCase.