feat: External System Connectors for GitHub and Linear (CFOS-26)

[jayscambler]

Summary

• Implements external system connectors to import data from GitHub and Linear into ContextFrame
• Provides a base SourceConnector class for building additional connectors
• Supports incremental synchronization to efficiently update datasets

Implementation Details

SourceConnector Base Class

• Abstract base class defining the connector interface
• Authentication abstraction supporting API keys, tokens, OAuth, and basic auth
• Built-in incremental sync support with state persistence
• Collection-based organization of imported content

GitHub Connector

• Import repository files with configurable path and pattern filtering
• Support for both text and binary files (including images)
• Incremental sync based on commit history
• Preserves file structure as collections
• Automatic README context extraction

Linear Connector

• Import teams, projects, issues, and comments
• Preserves relationships between entities
• Configurable filtering by team, project, and issue state
• Support for archived content
• Maps Linear's hierarchy to ContextFrame collections

Testing

• Comprehensive unit tests with mocking for external APIs
• Tests cover base connector functionality and specific implementations
• All tests passing: uv run pytest contextframe/tests/test_connectors.py

Documentation

• Added docs/external-connectors.md with usage examples
• Example scripts in examples/connector_usage.py
• Docstrings for all public methods

Checklist

• SourceConnector base class with auth abstraction
• GitHub connector with file → frame mapping
• Linear connector for teams/projects/issues
• Incremental sync support
• Authentication handling (OAuth flow, API keys, tokens)
• Tests and documentation
• Google Drive connector (future work)

Success Metrics

• ✅ Import capability for thousands of files
• ✅ Incremental sync to avoid re-importing unchanged data
• ✅ Zero data loss in structure/metadata

Closes CFOS-26

[linear]

CFOS-26 External System Connectors