codeupipe 0.1.0__tar.gz → 0.10.0__tar.gz

{codeupipe-0.1.0 → codeupipe-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeupipe
-Version: 0.1.0
+Version: 0.10.0
 Summary: Python pipeline framework — composable Payload-Filter-Pipeline pattern
 Author: Joshua Wink
 License: Apache-2.0
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 # codeupipe
 
-<!-- cup:ref file=codeupipe/__init__.py hash=afd4ab5 -->
+<!-- cup:ref file=codeupipe/__init__.py hash=3053319 -->
 
 Python pipeline framework — composable **Payload → Filter → Pipeline** pattern with streaming support. Zero external dependencies.
 
@@ -36,7 +36,7 @@ Experimental successor to [codeuchain](https://github.com/codeuchain/codeuchain)
 
 ## Core Concepts
 
-<!-- cup:ref file=codeupipe/core/__init__.py hash=e3e2418 -->
+<!-- cup:ref file=codeupipe/core/__init__.py hash=6ed16dd -->
 | Concept | Role |
 |---|---|
 | **Payload** | Immutable data container flowing through the pipeline |
@@ -49,6 +49,7 @@ Experimental successor to [codeuchain](https://github.com/codeuchain/codeuchain)
 | **State** | Pipeline execution metadata — tracks what ran, what was skipped, errors, chunk counts |
 | **Hook** | Lifecycle hooks — before/after/on_error for pipeline execution (sync or async) |
 | **RetryFilter** | Resilience wrapper — retries a Filter up to N times before giving up |
+| **CircuitOpenError** | Raised when a pipeline circuit breaker is open and rejecting calls |
 <!-- /cup:ref -->
 
 ## Install
@@ -151,6 +152,69 @@ class SplitWords:
             yield Payload({"word": word})
 ```
 
+## Synchronous Execution
+
+No manual `asyncio.run()` needed — `run_sync()` handles it:
+
+```python
+pipeline = Pipeline()
+pipeline.add_filter(CleanInput(), name="clean")
+pipeline.add_filter(Validate(), name="validate")
+
+result = pipeline.run_sync(Payload({"text": "  hello  "}))
+print(result.get("text"))  # "hello"
+```
+
+## Parallel Execution (Fan-out / Fan-in)
+
+Run independent filters concurrently; results merge back into the payload:
+
+```python
+pipeline = Pipeline()
+pipeline.add_parallel([
+    FetchUserFilter(),
+    FetchOrdersFilter(),
+    FetchRecommendationsFilter(),
+], name="fan-out")
+
+result = pipeline.run_sync(Payload({"user_id": 42}))
+```
+
+## Pipeline Nesting
+
+Compose pipelines from smaller pipelines:
+
+```python
+validation = Pipeline()
+validation.add_filter(CleanInput(), name="clean")
+validation.add_filter(Validate(), name="validate")
+
+processing = Pipeline()
+processing.add_pipeline(validation, name="validation-sub")
+processing.add_filter(TransformFilter(), name="transform")
+
+result = processing.run_sync(Payload({"text": "  hello  "}))
+```
+
+## Retry & Circuit Breaker
+
+Pipeline-level resilience wrappers:
+
+```python
+# Retry the entire pipeline up to 3 times on failure
+retrying = pipeline.with_retry(max_retries=3)
+result = retrying.run_sync(Payload({"input": "data"}))
+
+# Open the circuit after 5 consecutive failures
+from codeupipe import CircuitOpenError
+
+breaker = pipeline.with_circuit_breaker(failure_threshold=5)
+try:
+    result = breaker.run_sync(Payload({"input": "data"}))
+except CircuitOpenError:
+    print("Service unavailable — circuit is open")
+```
+
 ## Execution State
 
 ```python
@@ -168,10 +232,15 @@ print(pipeline.state.chunks_processed)   # {'upper': 3}  (streaming mode)
 | [CONCEPTS.md](CONCEPTS.md) | Full API reference with runnable examples |
 | [BEST_PRACTICES.md](BEST_PRACTICES.md) | Project structure, naming, testing strategy |
 | [SKILL.md](SKILL.md) | Agent skill reference — types, patterns, conversion |
+| [ROADMAP.md](ROADMAP.md) | Expansion rings — from framework to platform |
 
 ## CLI (`cup`)
 
-<!-- cup:ref file=codeupipe/cli.py symbols=main,scaffold,bundle,lint,coverage,report,doc_check hash=1e63d0e -->
+<!-- cup:ref file=codeupipe/cli/__init__.py symbols=main hash=4691a2f -->
+<!-- cup:ref file=codeupipe/cli/_registry.py symbols=CommandRegistry hash=8e82ece -->
+<!-- cup:ref file=codeupipe/cli/_scaffold.py symbols=scaffold,COMPONENT_TYPES hash=1f62e60 -->
+<!-- cup:ref file=codeupipe/cli/_bundle.py symbols=bundle hash=9a1b776 -->
+<!-- cup:ref file=codeupipe/cli/commands/analysis_cmds.py symbols=lint,coverage,report,doc_check hash=9d54f93 -->
 The `cup` command-line tool scaffolds, lints, and analyzes CUP projects:
 
 ```bash
@@ -183,12 +252,27 @@ cup lint src/signup                        # Check CUP conventions (CUP000–CUP
 cup coverage src/signup                    # Map component↔test coverage gaps
 cup report src/signup                      # Health report with scores, orphans, staleness
 cup doc-check .                            # Verify doc freshness (cup:ref markers)
+cup run pipeline.json --discover ./filters # Execute a pipeline from config
+cup connect --list                         # Show configured connectors
+cup connect --health                       # Run connector health checks
+cup describe pipeline.json                 # Inspect pipeline inputs, outputs, steps
+cup describe pipeline.json --json          # Machine-readable output (--json works globally)
+cup distribute checkpoint cp.json --status # Manage payload checkpoints
+cup distribute remote https://api.example  # Test a remote filter endpoint
+cup test                                   # Smart test runner with markers
+cup doctor                                 # Project health diagnostics
+cup graph pipeline.json                    # Mermaid pipeline visualization
+cup version --bump patch                   # Show/bump semver
 ```
 <!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
 
 ## Testing Utilities
 
-<!-- cup:ref file=codeupipe/testing.py symbols=run_filter,assert_payload,mock_filter hash=c119f9c -->
+<!-- cup:ref file=codeupipe/testing.py symbols=run_filter,assert_payload,mock_filter hash=65f0296 -->
 `codeupipe.testing` provides zero-boilerplate test helpers:
 
 ```python
@@ -208,7 +292,7 @@ def test_with_mock():
 ## Test
 
 ```bash
-pytest  # 909 tests
+pytest  # 1676 tests
 ```
 
 ## License

{codeupipe-0.1.0 → codeupipe-0.10.0}/README.md

@@ -1,6 +1,6 @@
 # codeupipe
 
-<!-- cup:ref file=codeupipe/__init__.py hash=afd4ab5 -->
+<!-- cup:ref file=codeupipe/__init__.py hash=3053319 -->
 
 Python pipeline framework — composable **Payload → Filter → Pipeline** pattern with streaming support. Zero external dependencies.
 
@@ -10,7 +10,7 @@ Experimental successor to [codeuchain](https://github.com/codeuchain/codeuchain)
 
 ## Core Concepts
 
-<!-- cup:ref file=codeupipe/core/__init__.py hash=e3e2418 -->
+<!-- cup:ref file=codeupipe/core/__init__.py hash=6ed16dd -->
 | Concept | Role |
 |---|---|
 | **Payload** | Immutable data container flowing through the pipeline |
@@ -23,6 +23,7 @@ Experimental successor to [codeuchain](https://github.com/codeuchain/codeuchain)
 | **State** | Pipeline execution metadata — tracks what ran, what was skipped, errors, chunk counts |
 | **Hook** | Lifecycle hooks — before/after/on_error for pipeline execution (sync or async) |
 | **RetryFilter** | Resilience wrapper — retries a Filter up to N times before giving up |
+| **CircuitOpenError** | Raised when a pipeline circuit breaker is open and rejecting calls |
 <!-- /cup:ref -->
 
 ## Install
@@ -125,6 +126,69 @@ class SplitWords:
             yield Payload({"word": word})
 ```
 
+## Synchronous Execution
+
+No manual `asyncio.run()` needed — `run_sync()` handles it:
+
+```python
+pipeline = Pipeline()
+pipeline.add_filter(CleanInput(), name="clean")
+pipeline.add_filter(Validate(), name="validate")
+
+result = pipeline.run_sync(Payload({"text": "  hello  "}))
+print(result.get("text"))  # "hello"
+```
+
+## Parallel Execution (Fan-out / Fan-in)
+
+Run independent filters concurrently; results merge back into the payload:
+
+```python
+pipeline = Pipeline()
+pipeline.add_parallel([
+    FetchUserFilter(),
+    FetchOrdersFilter(),
+    FetchRecommendationsFilter(),
+], name="fan-out")
+
+result = pipeline.run_sync(Payload({"user_id": 42}))
+```
+
+## Pipeline Nesting
+
+Compose pipelines from smaller pipelines:
+
+```python
+validation = Pipeline()
+validation.add_filter(CleanInput(), name="clean")
+validation.add_filter(Validate(), name="validate")
+
+processing = Pipeline()
+processing.add_pipeline(validation, name="validation-sub")
+processing.add_filter(TransformFilter(), name="transform")
+
+result = processing.run_sync(Payload({"text": "  hello  "}))
+```
+
+## Retry & Circuit Breaker
+
+Pipeline-level resilience wrappers:
+
+```python
+# Retry the entire pipeline up to 3 times on failure
+retrying = pipeline.with_retry(max_retries=3)
+result = retrying.run_sync(Payload({"input": "data"}))
+
+# Open the circuit after 5 consecutive failures
+from codeupipe import CircuitOpenError
+
+breaker = pipeline.with_circuit_breaker(failure_threshold=5)
+try:
+    result = breaker.run_sync(Payload({"input": "data"}))
+except CircuitOpenError:
+    print("Service unavailable — circuit is open")
+```
+
 ## Execution State
 
 ```python
@@ -142,10 +206,15 @@ print(pipeline.state.chunks_processed)   # {'upper': 3}  (streaming mode)
 | [CONCEPTS.md](CONCEPTS.md) | Full API reference with runnable examples |
 | [BEST_PRACTICES.md](BEST_PRACTICES.md) | Project structure, naming, testing strategy |
 | [SKILL.md](SKILL.md) | Agent skill reference — types, patterns, conversion |
+| [ROADMAP.md](ROADMAP.md) | Expansion rings — from framework to platform |
 
 ## CLI (`cup`)
 
-<!-- cup:ref file=codeupipe/cli.py symbols=main,scaffold,bundle,lint,coverage,report,doc_check hash=1e63d0e -->
+<!-- cup:ref file=codeupipe/cli/__init__.py symbols=main hash=4691a2f -->
+<!-- cup:ref file=codeupipe/cli/_registry.py symbols=CommandRegistry hash=8e82ece -->
+<!-- cup:ref file=codeupipe/cli/_scaffold.py symbols=scaffold,COMPONENT_TYPES hash=1f62e60 -->
+<!-- cup:ref file=codeupipe/cli/_bundle.py symbols=bundle hash=9a1b776 -->
+<!-- cup:ref file=codeupipe/cli/commands/analysis_cmds.py symbols=lint,coverage,report,doc_check hash=9d54f93 -->
 The `cup` command-line tool scaffolds, lints, and analyzes CUP projects:
 
 ```bash
@@ -157,12 +226,27 @@ cup lint src/signup                        # Check CUP conventions (CUP000–CUP
 cup coverage src/signup                    # Map component↔test coverage gaps
 cup report src/signup                      # Health report with scores, orphans, staleness
 cup doc-check .                            # Verify doc freshness (cup:ref markers)
+cup run pipeline.json --discover ./filters # Execute a pipeline from config
+cup connect --list                         # Show configured connectors
+cup connect --health                       # Run connector health checks
+cup describe pipeline.json                 # Inspect pipeline inputs, outputs, steps
+cup describe pipeline.json --json          # Machine-readable output (--json works globally)
+cup distribute checkpoint cp.json --status # Manage payload checkpoints
+cup distribute remote https://api.example  # Test a remote filter endpoint
+cup test                                   # Smart test runner with markers
+cup doctor                                 # Project health diagnostics
+cup graph pipeline.json                    # Mermaid pipeline visualization
+cup version --bump patch                   # Show/bump semver
 ```
 <!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
+<!-- /cup:ref -->
 
 ## Testing Utilities
 
-<!-- cup:ref file=codeupipe/testing.py symbols=run_filter,assert_payload,mock_filter hash=c119f9c -->
+<!-- cup:ref file=codeupipe/testing.py symbols=run_filter,assert_payload,mock_filter hash=65f0296 -->
 `codeupipe.testing` provides zero-boilerplate test helpers:
 
 ```python
@@ -182,7 +266,7 @@ def test_with_mock():
 ## Test
 
 ```bash
-pytest  # 909 tests
+pytest  # 1676 tests
 ```
 
 ## License

codeupipe-0.10.0/codeupipe/__init__.py

@@ -0,0 +1,96 @@
+"""
+codeupipe: Pipeline framework for Python
+
+Composable Payload-Filter-Pipeline pattern with Valves, Taps, Hooks, and Streaming.
+Filters and Taps can be sync or async. Zero external dependencies.
+
+Core concepts:
+- Payload: Immutable data container flowing through the pipeline
+- MutablePayload: Mutable sibling for performance-critical bulk edits
+- Filter: Processing unit that transforms payloads (sync or async)
+- StreamFilter: Streaming unit — yields 0, 1, or N output chunks per input
+- Pipeline: Orchestrator — .run() for batch, .stream() for streaming
+- Valve: Conditional flow control — gates a filter with a predicate
+- Tap: Non-modifying observation point (sync or async)
+- State: Pipeline execution metadata — tracks executed, skipped, errors, chunk counts
+- Hook: Lifecycle hooks — before / after / on_error (sync or async)
+"""
+
+from .core import (
+    Payload, MutablePayload, Filter, StreamFilter, Pipeline, CircuitOpenError, Valve, Tap,
+    State, Hook, PipelineEvent, EventEmitter,
+    PayloadSchema, SchemaViolation, ContractViolation, PipelineTimeoutError,
+    AuditEntry, AuditTrail, AuditHook,
+    DeadLetterHandler, LogDeadLetterHandler,
+)
+from .utils import ErrorHandlingMixin, RetryFilter
+from .converter import load_config, DEFAULT_CONFIG, PATTERN_DEFAULTS
+from .converter.pipelines import build_export_pipeline, build_import_pipeline
+from .registry import Registry, cup_component, default_registry
+from .distribute import RemoteFilter, Checkpoint, CheckpointHook, IterableSource, FileSource, WorkerPool
+from .deploy import (
+    DeployTarget, DeployAdapter, DockerAdapter, VercelAdapter, NetlifyAdapter, RenderAdapter,
+    FlyAdapter, RailwayAdapter, CloudRunAdapter, KoyebAdapter,
+    AppRunnerAdapter, OracleAdapter, AzureContainerAppsAdapter, HuggingFaceAdapter,
+    find_adapters, load_manifest, ManifestError,
+    resolve_recipe, list_recipes, RecipeError,
+    init_project, list_templates, InitError,
+    render_vercel_handler, render_netlify_handler, render_lambda_handler,
+)
+from .connect import (
+    ConnectorConfig, load_connector_configs, ConfigError,
+    discover_connectors, check_health, HttpConnector,
+)
+from .observe import CaptureTap, MetricsTap, RunRecord
+from .graph import pipeline_to_mermaid
+from .runtime import TapSwitch, HotSwap
+from .auth import Credential, CredentialStore, AuthProvider, GoogleOAuth, GitHubOAuth, AuthHook
+
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+try:
+    __version__ = _pkg_version("codeupipe")
+except PackageNotFoundError:
+    __version__ = "0.10.0"  # fallback for editable / non-installed usage
+__all__ = [
+    # Core
+    "Payload", "MutablePayload",
+    "Filter", "StreamFilter", "Pipeline", "CircuitOpenError", "Valve", "Tap",
+    "State", "Hook",
+    # Observe
+    "PipelineEvent", "EventEmitter",
+    # Govern
+    "PayloadSchema", "SchemaViolation", "ContractViolation", "PipelineTimeoutError",
+    "AuditEntry", "AuditTrail", "AuditHook",
+    "DeadLetterHandler", "LogDeadLetterHandler",
+    # Utils
+    "ErrorHandlingMixin", "RetryFilter",
+    # Converter
+    "load_config", "DEFAULT_CONFIG", "PATTERN_DEFAULTS",
+    "build_export_pipeline", "build_import_pipeline",
+    # Registry
+    "Registry", "cup_component", "default_registry",
+    # Distribute
+    "RemoteFilter", "Checkpoint", "CheckpointHook",
+    "IterableSource", "FileSource", "WorkerPool",
+    # Deploy
+    "DeployTarget", "DeployAdapter", "DockerAdapter",
+    "VercelAdapter", "NetlifyAdapter", "RenderAdapter",
+    "FlyAdapter", "RailwayAdapter", "CloudRunAdapter", "KoyebAdapter",
+    "AppRunnerAdapter", "OracleAdapter", "AzureContainerAppsAdapter", "HuggingFaceAdapter",
+    "find_adapters", "load_manifest", "ManifestError",
+    "resolve_recipe", "list_recipes", "RecipeError",
+    "init_project", "list_templates", "InitError",
+    "render_vercel_handler", "render_netlify_handler", "render_lambda_handler",
+    # Connect
+    "ConnectorConfig", "load_connector_configs", "ConfigError",
+    "discover_connectors", "check_health", "HttpConnector",
+    # Observe
+    "CaptureTap", "MetricsTap", "RunRecord",
+    # Graph
+    "pipeline_to_mermaid",
+    # Runtime
+    "TapSwitch", "HotSwap",
+    # Auth
+    "Credential", "CredentialStore", "AuthProvider",
+    "GoogleOAuth", "GitHubOAuth", "AuthHook",
+]

codeupipe-0.10.0/codeupipe/auth/__init__.py

@@ -0,0 +1,45 @@
+"""
+codeupipe.auth: OAuth2 credential management for pipelines.
+
+Provides browser-based OAuth2 flows, persistent token storage,
+automatic credential injection, and proxy token vaulting.
+Zero external dependencies — stdlib only.
+
+Core types:
+- Credential: Token container (access_token, refresh_token, expiry, scopes)
+- CredentialStore: Persist + refresh credentials — file-backed JSON
+- AuthProvider: Protocol for OAuth2 flows (authorize_url, exchange_code, refresh)
+- AuthHook: Pipeline Hook — injects fresh tokens into Payload before each run
+
+Vault types (proxy token indirection):
+- ProxyToken: Opaque reference token (cup_tok_*) — never exposes real credentials
+- TokenLedger: Audit trail — issued, resolved, revoked events
+- TokenVault: Central authority — issues, resolves, revokes proxy tokens
+- VaultHook: Pipeline Hook — injects proxy tokens instead of real credentials
+
+Built-in providers:
+- GoogleOAuth: Google OAuth2 (Calendar, Drive, Gmail, etc.)
+- GitHubOAuth: GitHub OAuth2 (repos, issues, actions, etc.)
+"""
+
+from .credential import Credential, CredentialStore
+from .hook import AuthHook
+from .provider import AuthProvider, GitHubOAuth, GoogleOAuth
+from .proxy_token import ProxyToken
+from .token_ledger import LedgerEvent, TokenLedger
+from .token_vault import TokenVault
+from .vault_hook import VaultHook
+
+__all__ = [
+    "AuthHook",
+    "AuthProvider",
+    "Credential",
+    "CredentialStore",
+    "GitHubOAuth",
+    "GoogleOAuth",
+    "LedgerEvent",
+    "ProxyToken",
+    "TokenLedger",
+    "TokenVault",
+    "VaultHook",
+]

codeupipe-0.10.0/codeupipe/auth/_server.py

@@ -0,0 +1,147 @@
+"""
+Local OAuth2 callback server.
+
+Starts a temporary HTTP server on a free port, opens the browser
+to the authorization URL, waits for the callback with the auth code,
+then shuts down. Pure stdlib — http.server + webbrowser.
+"""
+
+import html
+import secrets
+import threading
+import urllib.parse
+import webbrowser
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Optional, Tuple
+
+__all__ = ["run_oauth_flow"]
+
+_SUCCESS_PAGE = """\
+<!DOCTYPE html>
+<html>
+<head><title>codeupipe — Authenticated</title></head>
+<body style="font-family:system-ui;text-align:center;padding:60px;background:#1a1a2e;color:#e0e0e0">
+  <h1 style="color:#4ecdc4">&#x2713; Authenticated</h1>
+  <p>You can close this tab and return to the terminal.</p>
+</body>
+</html>
+"""
+
+_ERROR_PAGE = """\
+<!DOCTYPE html>
+<html>
+<head><title>codeupipe — Auth Error</title></head>
+<body style="font-family:system-ui;text-align:center;padding:60px;background:#1a1a2e;color:#e0e0e0">
+  <h1 style="color:#e74c3c">&#x2717; Authentication Failed</h1>
+  <p>{error}</p>
+</body>
+</html>
+"""
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Handles the OAuth2 callback redirect."""
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        params = urllib.parse.parse_qs(parsed.query)
+
+        # Extract code and state
+        code = params.get("code", [None])[0]
+        state = params.get("state", [None])[0]
+        error = params.get("error", [None])[0]
+        error_desc = params.get("error_description", ["Unknown error"])[0]
+
+        if error:
+            self.server._auth_result = ("error", error_desc)  # type: ignore[attr-defined]
+            self._send_html(400, _ERROR_PAGE.format(error=html.escape(error_desc)))
+        elif code and state == self.server._expected_state:  # type: ignore[attr-defined]
+            self.server._auth_result = ("ok", code)  # type: ignore[attr-defined]
+            self._send_html(200, _SUCCESS_PAGE)
+        else:
+            msg = "State mismatch — possible CSRF. Please try again."
+            self.server._auth_result = ("error", msg)  # type: ignore[attr-defined]
+            self._send_html(400, _ERROR_PAGE.format(error=html.escape(msg)))
+
+        # Signal the main thread to shut down
+        threading.Thread(target=self.server.shutdown, daemon=True).start()
+
+    def _send_html(self, code: int, body: str):
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    def log_message(self, format, *args):
+        # Suppress noisy request logs
+        pass
+
+
+def run_oauth_flow(
+    provider,
+    port: int = 0,
+    timeout: int = 120,
+    open_browser: bool = True,
+) -> Tuple[str, str]:
+    """Run a complete browser-based OAuth2 flow.
+
+    1. Starts a local HTTP server on *port* (0 = auto-pick free port).
+    2. Generates a random state parameter for CSRF protection.
+    3. Opens the browser to the provider's authorization URL.
+    4. Waits for the callback with the auth code.
+    5. Returns (code, redirect_uri) for token exchange.
+
+    Args:
+        provider: An AuthProvider instance.
+        port: Local port for callback server (0 = auto).
+        timeout: Max seconds to wait for the callback.
+        open_browser: Whether to auto-open the browser.
+
+    Returns:
+        Tuple of (authorization_code, redirect_uri).
+
+    Raises:
+        RuntimeError: If the flow fails, times out, or user denies.
+        TimeoutError: If the callback is not received in time.
+    """
+    state = secrets.token_urlsafe(32)
+
+    server = HTTPServer(("127.0.0.1", port), _CallbackHandler)
+    actual_port = server.server_address[1]
+    redirect_uri = f"http://localhost:{actual_port}/callback"
+
+    server._expected_state = state  # type: ignore[attr-defined]
+    server._auth_result = None  # type: ignore[attr-defined]
+
+    auth_url = provider.authorize_url(redirect_uri, state)
+
+    # Run server in a thread so we can enforce a timeout
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    if open_browser:
+        print(f"\nOpening browser for {provider.name} authentication...")
+        print(f"If it doesn't open, visit:\n  {auth_url}\n")
+        webbrowser.open(auth_url)
+    else:
+        print(f"\nOpen this URL in your browser:\n  {auth_url}\n")
+
+    # Wait for the callback
+    server_thread.join(timeout=timeout)
+
+    # Shut down if still running (timeout)
+    server.shutdown()
+    server.server_close()
+
+    result = server._auth_result  # type: ignore[attr-defined]
+    if result is None:
+        raise TimeoutError(
+            f"OAuth callback not received within {timeout}s. "
+            "Make sure you complete the login in your browser."
+        )
+
+    status, value = result
+    if status == "error":
+        raise RuntimeError(f"OAuth flow failed: {value}")
+
+    return value, redirect_uri