# changefeed — Changelog

## v1.0.0 — 2026-06-25

Initial release. Seventh tool in the "productivity-boost" series.

### Purpose

`pkgaudit` is one-shot: walk a lockfile, ask OSV, report. `changefeed`
is the *monitoring* half: maintain a list of subscribed packages and
surface only the OSV ids you haven't seen before, idempotently. Drop
it in a cron job, pipe `poll` into `notify`, and you have an
asynchronous CVE alert pipeline.

### Subcommands

```
changefeed subscribe   --eco cargo|npm|pypi|go --name <PKG> [--pin VER] [--note TEXT]
changefeed unsubscribe --eco …                 --name <PKG>
changefeed list        [-F human|json]
changefeed poll        [-F human|json|jfind] [-o FILE] [--timeout N]
                       [--fail-on-new] [--dry-run]
changefeed from-cmdb                          # v1.1 placeholder
```

### State

- `$XDG_DATA_HOME/cli-johlem/changefeed/subscriptions.toml` — the
  subscriptions list.
- `$XDG_DATA_HOME/cli-johlem/changefeed/state.json` — per-subscription
  set of OSV ids already surfaced, plus `last_polled` timestamp.

Override the root with `$CHANGEFEED_DIR` (useful in tests).

### jfind/v1 output

Every advisory that's new to the local state emits one `vulnerability`
finding with:
- DORA Art. 9 + Art. 28 + NIS2 Art. 21(2)(d) + ISO/IEC 27001:2022 A.5.21
- MITRE T1195.001 (Compromise Software Dependencies)
- Severity ladder: CVSS numeric → ladder → `database_specific.severity`
  word → Medium (never Info for a known vuln).

### Exit codes

```
0  ok
2  usage (clap)
3  runtime (io, toml, http, subscription missing, unknown ecosystem)
4  policy gate failed (`poll --fail-on-new` saw at least one new advisory)
```

### Build

- Library crate + thin CLI binary.
- 11 integration tests (no separate unit tests — the OSV client is the
  one in pkgaudit; the rest is glue), all green.
- Zero compiler warnings.
- Same OSV REST client shape as pkgaudit (blocking reqwest).
- Suite-standard exit codes + tagline footer.
- NixOS-only platform gate.

### Suite interop

| Producer | Consumer | Use case |
|---|---|---|
| operator   | changefeed | subscribe a watched package |
| cmdb       | changefeed | (planned v1.1 `from-cmdb` import) |
| changefeed | notify     | new advisory → Slack / Teams / file |
| changefeed | complymap  | map advisories → DORA Art. 28 + NIS2 21(2)(d) |
| changefeed | dossier    | append to monthly third-party-risk report |

### Deferred to v1.1

- `from-cmdb` proper integration (today: stubbed with a message).
- Multi-source: GHSA, NVD, vendor RSS feeds.
- Rate-limit / batching when subscription count > 200.
- Webhook posting (today: pipe `poll -F jfind | notify route`).