feat(webhooks): add Deck card sync preset with vector indexing

[cbcoutinho]

Summary

• Adds the deck_sync webhook preset and teaches webhook_parser to convert Deck card events into DocumentTask(doc_type="deck_card", …) so Deck cards get indexed into Qdrant in real time instead of waiting for the polling scanner.
• New middleware logs the inbound User-Agent on every /api/v1/* and /webhooks/nextcloud request, so backend access logs can attribute calls to a specific Astrolabe build (e.g. Nextcloud-Astrolabe/0.14.1).

Context

Nextcloud Deck PR #7910 added IWebhookCompatibleEvent to CardCreated/Updated/DeletedEvent and BoardUpdatedEvent, undoing the stale "Deck does not support webhooks" comment in webhook_presets.py. The preset library, parser, and processor were already designed for this — only the wiring was missing. The astrolabe-side change (paired PR cbcoutinho/astrolabe#TBD) consumes the new preset via filter_presets_by_installed_apps and stamps the Nextcloud-Astrolabe/<version> UA on its outbound calls.

BoardUpdatedEvent carries only boardId (no card list), so the parser logs delivery at INFO and returns None; the polling scanner reconciles the affected cards.

Caveats

• Requires Deck ≥1.18.x — IWebhookCompatibleEvent is in v1.18.0-beta.* but not yet in any stable release. The preset is hidden by filter_presets_by_installed_apps when the Deck app isn't installed, but admins enabling it against an older Deck will get a 400 from webhook_listeners ("not an event class compatible with webhooks").

Test plan

• uv run pytest tests/unit/test_webhook_endpoint.py tests/unit/test_webhook_presets.py -v — 5 new tests pass (deck create/delete/board-update + symmetric fail-open tests for missing card.id / node.id)
• Full unit suite: 1035 passed, 1 skipped
• uv run ruff check && uv run ruff format --check && uv run ty check -- nextcloud_mcp_server
• Manual end-to-end smoke against mcp-login-flow:
  • Patched container with upstream ACardEvent.php + BoardUpdatedEvent.php (PR #7910 source)
  • Enabled Deck Sync via astrolabe admin UI → 4 webhooks registered
  • Created / updated / deleted a Deck card via mcp__nextcloud-stdio__deck_*
  • Confirmed Webhook queued deck_card_7 (index|delete) + Indexed/Deleted deck_card_7 for admin in MCP logs
  • Confirmed Nextcloud-Astrolabe/0.14.1 UA on every astrolabe-originated /api/v1/* request

---

This PR was generated with the help of AI, and reviewed by a Human

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[claude]

Claude finished @cbcoutinho's task in 3m 0s —— View job

---

PR Review: feat(webhooks): add Deck card sync preset with vector indexing

• Gather context from PR description and changed files
• Read changed source files
• Review code quality, bugs, security, and test coverage
• Post final review

---

Overall this is a clean, well-scoped PR. The design is sound, the comments explain the non-obvious decisions, and the test coverage mirrors what the code actually does. A few items worth addressing before merge:

---

Important

stack_id-only metadata never reaches the fast lookup path in processor.py

In webhook_parser.py:138 only stack_id is stored in metadata:

metadata = {"stack_id": stack_id} if stack_id is not None else None

But processor.py:340-343 requires both board_id and stack_id to take the O(1) fast path:

if (
    doc_task.metadata
    and "board_id" in doc_task.metadata
    and "stack_id" in doc_task.metadata
):

Since CardCreatedEvent/CardUpdatedEvent/CardDeletedEvent payloads don't carry board_id, every webhook-triggered deck card task always falls through to the full board+stack iteration (O(boards × stacks)). The comment in the parser documents this correctly ("processor.py falls back to iterating boards/stacks if it's missing"), but the stack_id in metadata is then effectively dead — processor.py never uses a partial hint.

Two options:

1. Simplify now: drop stack_id from webhook-generated metadata entirely (set metadata=None always). Less misleading, no behaviour change. Fix this →
2. Future optimization: add a stack_id-only fast path to processor.py that narrows iteration to just the known stack. Worth tracking as a follow-up.

---

logger.info fires on every /api/v1/* and /webhooks/nextcloud request

app.py:2488 logs at INFO level unconditionally for every matching request:

logger.info("%s %s from %s", request.method, path, ua, ...)

In a busy deployment — many card creates/updates through MCP tools, regular scanner webhooks — this doubles INFO log traffic for those endpoints. The comment says the goal is to attribute calls to a specific Astrolabe build, but (none) entries (non-Astrolabe callers) will dominate and add noise.

Consider logger.debug for non-Astrolabe UAs (or for all paths), or gate on a specific UA prefix: Fix this →

---

Nits

Missing test for CardUpdatedEvent (tests/unit/test_webhook_endpoint.py)

The five new tests cover create, delete, board-update, and two fail-open cases — but CardUpdatedEvent (the most common in practice) isn't explicitly tested. It falls through the same _DECK_CARD_EVENTS frozenset branch as CardCreatedEvent, so behaviour is covered, but an explicit test would help catch regressions if the operation mapping ever diverges. Fix this →

Deck event class strings duplicated across two modules

DECK_EVENT_CARD_* are defined in webhook_presets.py and _DECK_EVENT_CARD_* are redefined identically in webhook_parser.py. The strings match and tests verify both sides, but a future rename would need updating in two places. (The same pattern already exists for file events — this isn't introduced by this PR, just worth flagging as tech debt.)

---

What's working well

• BoardUpdatedEvent fan-out design is clean: log delivery, return None, let the polling scanner reconcile. The test correctly validates the "ignored" response.
• Fail-open handling is symmetric: both the notes path (missing node.id) and the deck path (missing card.id) now have explicit tests.
• _DECK_CARD_EVENTS frozenset is a neat way to express the three indexable event types without repetition.
• The webhook secret HMAC check (compare_digest) pre-exists and correctly applies to deck events too.
• The @dataclass DocumentTask.metadata field comment is accurate (board_id/stack_id for deck_card).