feat(vuln): OSV cache staleness + refresh flags — closes #30

[Wolfvin]

Summary

Closes #30. Implements all three deliverables from the issue:

1. cache_info block in vuln-scan output — {last_refresh, age_hours, ttl_hours, is_stale, stale_packages[]} so agents can decide whether to trust cached CVE data.
2. --refresh flag — bypasses the OSV cache and forces fresh OSV.dev API calls for every package. Updates the cache with new results. Ignored in --offline mode.
3. --max-age Nh flag — treats cache entries older than N hours as stale for this run only (per-run TTL override; stored TTL unchanged). Accepts Nh/Nm/Ns/Nd/bare-int (hours).

This completes the Phase 1 roadmap (#21) checklist item: "Fix vuln DB staleness (OSV.dev API, update scheduler)".

Changes

scripts/osv_client.py (foundation)

• OSVCache.peek(key) — new method. Returns (response, timestamp, ttl) WITHOUT TTL check or deletion. This is what --max-age relies on to apply a per-run TTL threshold without mutating stored state.
• OSVClient.query_packages(packages, force_refresh=False, max_age=None) — new optional params. force_refresh bypasses cache; max_age uses peek() + custom threshold. Behaviour unchanged when both unset.
• OSVClient._parse_cached_response(cached, package) — new private helper. Factors the two-shape cache parsing (vuln IDs vs full vuln dicts) out of query_packages so all three code paths share it. Zero dead code.
• OSVClient.get_cache_info(packages) — new method. Returns the cache_info dict. Missing entries treated as stale; unsupported ecosystems skipped; stale_packages sorted for deterministic output.

scripts/commands/vuln_scan.py

• _parse_max_age(raw) — new helper. Parses 6h/30m/2d/90s/bare-int into seconds.
• --refresh and --max-age CLI flags added.
• execute() validates --max-age and forwards refresh/max_age to the engine. Invalid --max-age returns a structured {status:'error', error:'invalid_argument'} dict.

scripts/vulnscan_engine.py

• scan_vulnerabilities() gains refresh and max_age params.
• Computes cache_info after the OSV query (3 paths: success → get_cache_info(); no packages → empty shape; OSV exception → empty shape with error).
• cache_info added to return dict (additive — no existing key removed).

tests/test_vuln_staleness.py (new, 39 tests)

All network-free (API calls mocked via unittest.mock.patch.object). Covers:

• _parse_max_age valid/invalid forms (11 tests)
• OSVCache.peek — missing, tuple shape, TTL-agnostic vs get(), corrupt-JSON deletion (4 tests)
• get_cache_info — empty, all-stale, all-fresh, mixed, sorted, TTL (6 tests)
• force_refresh — bypasses cache, uses cache, ignored offline (3 tests)
• max_age — old→stale, young→fresh, stored TTL unchanged, 0=refresh (4 tests)
• End-to-end scan_vulnerabilities on clean_app + vulnerable_app fixtures, shape, additive (4 tests)
• CLI arg wiring (3 tests)

Docs

• README.md — vuln-scan command row lists new flags + describes cache_info.
• SKILL-QUICK.md — output shape table, command list, and a new "are CVE results fresh?" trigger-map row.
• CHANGELOG.md — new section under [8.2.0] — Unreleased with Added / Changed / Non-Breaking / Migration Notes.

Test Results

PYTHONPATH=scripts python3 -m pytest tests/test_vuln_staleness.py -v
→ 39 passed in 0.80s

python3 -m pytest tests/ --ignore=tests/test_integration.py
→ 706 passed, 12 skipped, 1 failed (pre-existing)

The single failure (tests/test_architecture.py::TestArchitectureBasic::test_auto_scans_on_fresh_workspace) is pre-existing on main — verified by stashing this PR's changes and re-running. No new failures introduced.

Sample Output

vuln-scan on clean_app fixture (offline, no deps):

{
  "status": "ok",
  "cache_info": {
    "last_refresh": null,
    "age_hours": null,
    "ttl_hours": 24.0,
    "is_stale": false,
    "stale_packages": []
  },
  "osv_stats": {"packages_queried": 0, "vulnerabilities_found": 0}
}

vuln-scan on vulnerable_app fixture (offline, npm deps but no cache entries):

{
  "cache_info": {
    "last_refresh": null,
    "age_hours": null,
    "ttl_hours": 24.0,
    "is_stale": true,
    "stale_packages": ["express@4.17.0", "lodash@4.17.15"]
  }
}

Acceptance Criteria

• vuln-scan output includes cache_info object with last_refresh, age_hours, is_stale, stale_packages (also ttl_hours)
• --refresh flag forces fresh API calls and updates cache
• --max-age flag overrides TTL for the current run
• Tests: cache_info populated correctly, --refresh bypasses cache, --max-age treats fresh entries as stale
• Docs: README + SKILL-QUICK mention the new flags; CHANGELOG entry under [8.2.0]

Constraints Met

• Python 3.8+ compatible (no walrus operators, no dict | dict syntax).
• No new dependencies (uses stdlib re, sqlite3, time, unittest.mock).
• Zero dead code — _parse_cached_response factors out previously-inline logic; no unused helpers.
• All new public methods have docstrings.
• Existing vuln-scan output is unchanged — cache_info is purely additive.
• Network calls only happen when --refresh is set OR cache entries are expired/missing/stale-per---max-age.

Out of Scope

Issue #30 stretch goal #4 (background refresh scheduler in the MCP serve process) is intentionally not implemented — the issue body says "Out of scope for Phase 1 — file as follow-up if needed". This PR delivers the three in-scope items.

Commits

1. feat(vuln): --refresh + --max-age flags — CLI flags + engine plumbing
2. feat(vuln): cache_info in output — osv_client.py foundation (peek, query_packages params, get_cache_info, _parse_cached_response)
3. test(vuln): staleness tests — 39 tests
4. docs(vuln): README + SKILL-QUICK + CHANGELOG

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE