Module report 

cairn report {create, list, view, resolve, flag, unflag} — thin wrappers over the moderation + admin XRPC endpoints Cairn exposes (#7 + #16).

Every subcommand follows the same flow:

1. Load the session file (required).
2. Mint a fresh service-auth JWT via PDS getServiceAuth. On 401, call refreshSession once, persist rotated tokens atomically (§5.3 auto-refresh path), retry.
3. Issue the HTTP call to Cairn with the service-auth token.
4. Return a typed response the CLI dispatcher turns into human or JSON output via the per-subcommand format_*_{human, json} pairs.

Each orchestrator function’s doc-comment cites the handler it wraps so a future reader can jump from CLI code to server code without grep.

Structs

ApplyLabelArg

Optional label-application sub-object on cairn report resolve. Mirrors the server handler’s InputApplyLabel shape.

CreateReportResponse

Successful createReport response — only the fields the CLI displays. Extra fields are ignored by serde.

ReportCreateInput

Input to cairn report create — wire-agnostic so the CLI flags

ReportDetail

Full report record — includes reason body (admin-authenticated only, per §F11).

ReportFlagInput

Input to cairn report flag / cairn report unflag.

ReportFlagResponse

Synthetic response for cairn report {flag, unflag}. The server’s response body is {} — operationally we only care that the call succeeded (2xx). The struct echoes the input fields the CLI prints.

ReportListEntry

One row in a listReports response. Deliberately omits the reason field — the server’s ReportListEntry projection drops it per §F11 and the CLI’s shape preserves that invariant type-level.

ReportListInput

Input to cairn report list.

ReportListResponse

listReports response envelope.

ReportResolveInput

Input to cairn report resolve.

ReportViewInput

Input to cairn report view.

Enums

ReportSubject

Subject-union wire shape. Deserializes the server’s { $type: ..., ... } tagged representation.

Functions

create

Submit the report. Mutates session in place on a mid-call token refresh and persists the rotation atomically before returning. session_path is the SAME path the caller loaded from, so the file on disk stays in sync.

flag

Flag or unflag a reporter.

format_create_human

Human-readable one-liner for cairn report create — default output when --json is not set.

format_create_json

Machine-readable --json renderer for cairn report create.

format_flag_human

Human one-liner for cairn report flag / cairn report unflag.

format_flag_json

JSON output for cairn report flag / cairn report unflag. Includes an action discriminator so scripts can branch without re-reading suppressed.

format_list_human

Tabular human output for cairn report list. Columns: id, status, reporter (truncated), subject (summary), reason-type (truncated), created_at. Trailing next cursor: … line when a next page exists.

format_list_json

JSON envelope for cairn report list.

format_resolve_human

Human one-liner for cairn report resolve. Names whether a label was applied so the operator sees the side-effect at a glance.

format_resolve_json

JSON output for cairn report resolve — the resolved ReportDetail.

format_view_human

Multi-line field/value output for cairn report view.

format_view_json

JSON output for cairn report view.

list

Query the reports table via the admin HTTP endpoint.

resolve

Resolve a report.

view

Fetch a single report record (with reason body).