Skip to content

refactor: introduce ConnectorRegistry to improve connector ecosystem extensibility and maintainability#4

Open
mtfang wants to merge 1 commit into
mainfrom
refactor/connector-registry
Open

refactor: introduce ConnectorRegistry to improve connector ecosystem extensibility and maintainability#4
mtfang wants to merge 1 commit into
mainfrom
refactor/connector-registry

Conversation

@mtfang

@mtfang mtfang commented May 15, 2026

Copy link
Copy Markdown
Owner

Summary

This PR delivers the highest-leverage parts of the Connector Ecosystem Refactor Plan:

  • Centralized ConnectorRegistry + self-registration for built-in connectors in alvum-core
  • Elimination of the hardcoded match name dispatch in the CLI (the main source of the "add a new connector = touch 6 files" problem)
  • ConnectorBuildContext to cleanly handle the two per-run dependencies that aren't uniform across connectors (image_provider for screen vision, since/before for session importers)
  • Extraction of small shared helpers (resolve_path, emit_connector_warning) that immediately delete duplication
  • Solid test coverage (new core unit tests + pipeline integration test)

All four core connectors (audio, screen, claude-code, codex) plus the external HTTP extension path continue to work exactly as before.

Motivation

The connector ecosystem had become the highest-friction area for adding new data sources (health, git activity, calendar, browser history, wearables, etc.). The review identified:

  • Hardcoded registration in extract.rs, capture.rs, config.rs, builtin_components.rs, and the connectors CLI
  • Heavy boilerplate duplication in every Connector implementation
  • A vestigial capture_sources() method on the trait that is not used for the real daemon path

This PR deletes the worst of that coupling.

Review

Developed and reviewed using the /implement --effort 5 skill:

  • 3 independent general reviewers
  • Tests specialist (coverage of new registry/factory paths)
  • Security specialist (data flow for user-controlled settings and LlmProvider)
  • Plan Alignment specialist (fidelity to the approved plan)

One high-severity correctness issue was caught by a general reviewer (unconditional with_since/with_before clobber when CLI flags were absent) and fixed before merge.

Verification

cargo fmt -p alvum-core -p alvum-cli -p alvum-pipeline -- --check
cargo clippy -p alvum-core -p alvum-cli -p alvum-pipeline -- -D warnings
cargo test -p alvum-core --lib
cargo test -p alvum-pipeline --test idempotency
cargo test -p alvum-connector-audio --test processor_modes

All green. Existing alvum extract behavior, warning events, resume/fingerprint logic, and external connector routing are unchanged.

Follow-up PRs (tracked in the plan)

  • Remove capture_sources() from the Connector trait (it is vestigial for built-ins)
  • Move the audio/screen settings bridging functions into the connector crates themselves
  • Make alvum connectors list --json and the menubar Extensions view derive core connectors from the registry + builtin_components
  • docs/superpowers/specs/connector-development.md + evergreen "why" comments

Files

See the diff for the 12 changed files (mostly concentrated in alvum-core and the four connector crates + the CLI entry point).

This is the foundation that makes the rest of the connector ecosystem work sustainable long-term.

…registration

This is the first major step of the approved connector ecosystem
maintainability plan (see session plan.md for the full multi-round
effort-5 review with 6 reviewers).

- Add ConnectorRegistry, ConnectorFactory, ConnectorBuildContext in
  alvum-core so connectors self-register instead of being hardcoded.
- Migrate all four core connectors (audio, screen, claude-code, codex)
  to expose register() + *_factory.
- Remove the large name-based match in extract::connectors_from_config.
  CLI dispatch is now a simple registry lookup + BuildContext for the
  two non-uniform dependencies (LlmProvider for vision, since/before).
- Extract resolve_path(~ expansion) and emit_connector_warning helpers
  to alvum-core::util, deleting exact duplication in session + audio.
- Add unit tests for registry + integration test exercising the new path.

Behavior for existing connectors, external HTTP extensions, config
migration, Observation sources, warnings, and the TCC capture daemon
path is 100% preserved.

This directly attacks the "edit 6 files to add a new modality" tax
and makes future connectors (health, git, calendar, wearable, etc.)
much cheaper to land.

Follow-up work (subsequent PRs):
- Delete vestigial capture_sources() from the Connector trait
- Move audio/screen bridging logic into the connector crates
- Unify alvum connectors list / doctor with the registry
- Documentation (connector-development.md)

All changes passed cargo fmt, clippy -D warnings, and relevant tests
(core, cli, pipeline idempotency, audio processor modes). Reviewed
with /implement --effort 5 (3× general + tests + security + plan
alignment).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant