On-demand report generation (Phase 2.3.c)

In addition to scheduled reporting, Ghillie provides an HTTP API endpoint for generating reports on demand. This enables operators to trigger a fresh report for a specific repository — for example, to respond to a review request or verify the state of a project before a release.

POST /reports/repositories/{owner}/{name}

The endpoint identifies repositories by their GitHub owner/name slug, matching the filesystem sink path convention and catalogue notation.

Generate a report for acme/widgets:

curl -X POST http://localhost:8080/reports/repositories/acme/widgets

On success, the response body contains report metadata:

{
  "report_id": "abc-123",
  "repository": "acme/widgets",
  "window_start": "2024-07-07T00:00:00+00:00",
  "window_end": "2024-07-14T00:00:00+00:00",
  "generated_at": "2024-07-14T12:00:00+00:00",
  "status": "on_track",
  "model": "mock-v1",
  "metrics": {
    "model_latency_ms": 87,
    "prompt_tokens": 1250,
    "completion_tokens": 350,
    "total_tokens": 1600
  }
}

When no events exist in the reporting window, the endpoint returns HTTP 204 with no body.

The on-demand report endpoint requires a database connection. Set the GHILLIE_DATABASE_URL environment variable to enable domain endpoints:

export GHILLIE_DATABASE_URL="postgresql+asyncpg://user:pass@host:5432/ghillie"

When GHILLIE_DATABASE_URL is not set, the runtime starts in health-only mode (backwards compatible with existing deployments). The endpoint also respects GHILLIE_REPORT_SINK_PATH — when set, generated reports are written to the filesystem as Markdown, just like scheduled reports.

The endpoint is documented in the OpenAPI specification at specs/openapi.yml.