skipper-core 0.1.0__tar.gz

skipper_core-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Temp files
+*.tmp
+/tmp/
+
+# Credentials (never commit)
+service-account-skipper-bot.json
+*.json.bak
+
+# Environment
+.env
+.env.local
+
+# macOS
+.DS_Store

skipper_core-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: skipper-core
+Version: 0.1.0
+Summary: Core Google Sheets client and resolver for Skipper test-gating
+Project-URL: Homepage, https://github.com/get-skipper/skipper-python
+Project-URL: Repository, https://github.com/get-skipper/skipper-python
+License: MIT
+Keywords: google-sheets,skipper,test-gating,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client>=2.100
+Requires-Dist: google-auth>=2.20
+Description-Content-Type: text/markdown
+
+# skipper-core
+
+Core Google Sheets client and resolver for the Skipper test-gating system.
+
+This package contains the shared logic used by all Skipper framework integrations:
+- `SkipperResolver` — initialises from a Google Sheet and answers `is_test_enabled(test_id)`
+- `SheetsClient` — authenticates and fetches spreadsheet data
+- `SheetsWriter` — reconciles the spreadsheet in sync mode
+- `CacheManager` — cross-process cache sharing for parallel test runners
+- `build_test_id` / `normalize_test_id` — canonical test ID helpers
+- Credential types: `FileCredentials`, `Base64Credentials`, `ServiceAccountCredentials`
+
+See the [root README](../../README.md) for full documentation.
+
+## Installation
+
+```bash
+pip install skipper-core
+```
+
+## Usage
+
+```python
+from skipper_core import SkipperConfig, SkipperResolver, FileCredentials
+
+config = SkipperConfig(
+    spreadsheet_id="YOUR_SPREADSHEET_ID",
+    credentials=FileCredentials("./service-account.json"),
+    sheet_name="skipper-python",
+)
+
+resolver = SkipperResolver(config)
+resolver.initialize()
+
+if not resolver.is_test_enabled("tests/test_auth.py > test_login"):
+    pytest.skip("[skipper] Test disabled")
+```

skipper_core-0.1.0/README.md

@@ -0,0 +1,37 @@
+# skipper-core
+
+Core Google Sheets client and resolver for the Skipper test-gating system.
+
+This package contains the shared logic used by all Skipper framework integrations:
+- `SkipperResolver` — initialises from a Google Sheet and answers `is_test_enabled(test_id)`
+- `SheetsClient` — authenticates and fetches spreadsheet data
+- `SheetsWriter` — reconciles the spreadsheet in sync mode
+- `CacheManager` — cross-process cache sharing for parallel test runners
+- `build_test_id` / `normalize_test_id` — canonical test ID helpers
+- Credential types: `FileCredentials`, `Base64Credentials`, `ServiceAccountCredentials`
+
+See the [root README](../../README.md) for full documentation.
+
+## Installation
+
+```bash
+pip install skipper-core
+```
+
+## Usage
+
+```python
+from skipper_core import SkipperConfig, SkipperResolver, FileCredentials
+
+config = SkipperConfig(
+    spreadsheet_id="YOUR_SPREADSHEET_ID",
+    credentials=FileCredentials("./service-account.json"),
+    sheet_name="skipper-python",
+)
+
+resolver = SkipperResolver(config)
+resolver.initialize()
+
+if not resolver.is_test_enabled("tests/test_auth.py > test_login"):
+    pytest.skip("[skipper] Test disabled")
+```

skipper_core-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skipper-core"
+version = "0.1.0"
+description = "Core Google Sheets client and resolver for Skipper test-gating"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["testing", "test-gating", "google-sheets", "skipper"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "google-api-python-client>=2.100",
+    "google-auth>=2.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/get-skipper/skipper-python"
+Repository = "https://github.com/get-skipper/skipper-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skipper_core"]

skipper_core-0.1.0/src/skipper_core/__init__.py

@@ -0,0 +1,35 @@
+"""skipper-core — Google Sheets client and resolver for Skipper test-gating."""
+
+from .cache import CacheManager
+from .client import FetchAllResult, SheetFetchResult, SheetsClient, TestEntry
+from .config import SkipperConfig
+from .credentials import Base64Credentials, Credentials, FileCredentials, ServiceAccountCredentials
+from .logger import log, logf, warn
+from .mode import SkipperMode, mode_from_env
+from .resolver import SkipperResolver
+from .testid import build_test_id, normalize_test_id
+from .writer import SheetsWriter
+
+__all__ = [
+    "CacheManager",
+    "FetchAllResult",
+    "SheetFetchResult",
+    "SheetsClient",
+    "SheetsWriter",
+    "SkipperConfig",
+    "SkipperMode",
+    "SkipperResolver",
+    "TestEntry",
+    # Credentials
+    "Base64Credentials",
+    "Credentials",
+    "FileCredentials",
+    "ServiceAccountCredentials",
+    # Helpers
+    "build_test_id",
+    "log",
+    "logf",
+    "mode_from_env",
+    "normalize_test_id",
+    "warn",
+]

skipper_core-0.1.0/src/skipper_core/cache.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import tempfile
+import time
+from pathlib import Path
+
+from .logger import logf, warn
+
+_CACHE_FILE_NAME = "cache.json"
+
+
+class CacheManager:
+    """Manages the temporary directory for sharing resolver state between processes."""
+
+    def write_resolver_cache(self, data: bytes) -> str:
+        """Write cache bytes to a temp directory. Returns the directory path.
+
+        Set SKIPPER_CACHE_FILE to <dir>/cache.json so worker processes can
+        rehydrate the resolver without re-fetching from Google Sheets.
+        """
+        tmpdir = tempfile.mkdtemp(prefix="skipper-")
+        path = os.path.join(tmpdir, _CACHE_FILE_NAME)
+        Path(path).write_bytes(data)
+        logf("wrote resolver cache to %s", path)
+        return tmpdir
+
+    def read_resolver_cache(self, cache_file: str) -> bytes:
+        """Read serialized resolver data from the given file path."""
+        return Path(cache_file).read_bytes()
+
+    def write_discovered_ids(self, directory: str, ids: list[str]) -> None:
+        """Write discovered test IDs to a uniquely-named file in directory."""
+        name = f"{os.getpid()}-{time.time_ns()}-{secrets.token_hex(4)}.json"
+        path = os.path.join(directory, name)
+        Path(path).write_text(json.dumps(ids), encoding="utf-8")
+
+    def merge_discovered_ids(self, directory: str) -> list[str]:
+        """Read all per-process discovered ID files, deduplicate, and return combined list."""
+        seen: set[str] = set()
+        result: list[str] = []
+
+        for entry in sorted(Path(directory).iterdir()):
+            if entry.is_dir() or entry.name == _CACHE_FILE_NAME or entry.suffix != ".json":
+                continue
+            try:
+                ids: list[str] = json.loads(entry.read_text(encoding="utf-8"))
+                for id_ in ids:
+                    if id_ not in seen:
+                        seen.add(id_)
+                        result.append(id_)
+            except Exception as exc:
+                warn(f"cannot read discovered file {entry.name!r}: {exc}")
+
+        return result
+
+    def cleanup(self, directory: str) -> None:
+        """Remove the temp directory and all its contents."""
+        import shutil
+
+        shutil.rmtree(directory, ignore_errors=True)

skipper_core-0.1.0/src/skipper_core/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime, timezone
+from typing import Any
+
+from google.oauth2 import service_account
+from googleapiclient.discovery import build  # type: ignore[import-untyped]
+
+from .config import SkipperConfig
+from .logger import logf, warn
+from .testid import normalize_test_id
+
+_SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets"
+
+
+@dataclasses.dataclass
+class TestEntry:
+    test_id: str
+    disabled_until: datetime | None  # None = no date → test is enabled
+    notes: str = ""
+
+
+@dataclasses.dataclass
+class SheetFetchResult:
+    sheet_name: str
+    sheet_id: int
+    header: list[str]
+    entries: list[TestEntry]
+
+
+@dataclasses.dataclass
+class FetchAllResult:
+    primary: SheetFetchResult
+    entries: list[TestEntry]  # merged from primary + reference sheets
+    service: Any  # googleapiclient Resource — reused by SheetsWriter
+
+
+class SheetsClient:
+    def __init__(self, config: SkipperConfig) -> None:
+        self._config = config
+
+    def fetch_all(self) -> FetchAllResult:
+        cred_json = self._config.credentials.resolve()
+        import json as _json
+
+        info = _json.loads(cred_json)
+        creds = service_account.Credentials.from_service_account_info(info, scopes=[_SHEETS_SCOPE])  # type: ignore[no-untyped-call]
+        svc = build("sheets", "v4", credentials=creds, cache_discovery=False)
+
+        spreadsheet = svc.spreadsheets().get(spreadsheetId=self._config.spreadsheet_id).execute()
+
+        primary_name = self._config.sheet_name
+        if not primary_name:
+            sheets = spreadsheet.get("sheets", [])
+            primary_name = sheets[0]["properties"]["title"] if sheets else ""
+
+        primary = self._fetch_sheet(svc, primary_name, spreadsheet)
+
+        merged = _merge_entries([], primary.entries)
+
+        for ref_name in self._config.reference_sheets:
+            try:
+                ref = self._fetch_sheet(svc, ref_name, spreadsheet)
+                merged = _merge_entries(merged, ref.entries)
+            except Exception as exc:
+                warn(f"cannot fetch reference sheet {ref_name!r}: {exc}")
+
+        return FetchAllResult(primary=primary, entries=merged, service=svc)
+
+    def _fetch_sheet(
+        self,
+        svc: Any,
+        sheet_name: str,
+        spreadsheet: dict[str, Any],
+    ) -> SheetFetchResult:
+        resp = (
+            svc.spreadsheets()
+            .values()
+            .get(spreadsheetId=self._config.spreadsheet_id, range=sheet_name)
+            .execute()
+        )
+        values: list[list[Any]] = resp.get("values", [])
+
+        if not values:
+            return SheetFetchResult(
+                sheet_name=sheet_name,
+                sheet_id=_sheet_id_by_name(spreadsheet, sheet_name),
+                header=[],
+                entries=[],
+            )
+
+        header = [str(v) for v in values[0]]
+        test_id_idx = _index_of(header, self._config.test_id_column)
+        disabled_until_idx = _index_of(header, self._config.disabled_until_column)
+        notes_idx = _index_of(header, "notes")
+
+        if test_id_idx < 0:
+            raise ValueError(
+                f"column {self._config.test_id_column!r} not found in sheet {sheet_name!r}"
+            )
+
+        entries: list[TestEntry] = []
+        for row in values[1:]:
+            if test_id_idx >= len(row):
+                continue
+            test_id = str(row[test_id_idx]).strip()
+            if not test_id:
+                continue
+
+            disabled_until: datetime | None = None
+            if disabled_until_idx >= 0 and disabled_until_idx < len(row):
+                raw = str(row[disabled_until_idx]).strip()
+                if raw:
+                    parsed = _parse_date(raw)
+                    if parsed is not None:
+                        disabled_until = parsed
+                    else:
+                        warn(f"cannot parse disabledUntil {raw!r} for test {test_id!r}")
+
+            notes = ""
+            if notes_idx >= 0 and notes_idx < len(row):
+                notes = str(row[notes_idx])
+
+            entries.append(TestEntry(test_id=test_id, disabled_until=disabled_until, notes=notes))
+
+        logf("fetched %d entries from sheet %r", len(entries), sheet_name)
+        return SheetFetchResult(
+            sheet_name=sheet_name,
+            sheet_id=_sheet_id_by_name(spreadsheet, sheet_name),
+            header=header,
+            entries=entries,
+        )
+
+
+def _merge_entries(existing: list[TestEntry], incoming: list[TestEntry]) -> list[TestEntry]:
+    """Merge incoming entries, keeping the most restrictive (latest) disabledUntil."""
+    idx: dict[str, int] = {}
+    result = list(existing)
+    for i, e in enumerate(result):
+        idx[normalize_test_id(e.test_id)] = i
+
+    for e in incoming:
+        nid = normalize_test_id(e.test_id)
+        if nid in idx:
+            current = result[idx[nid]].disabled_until
+            if _more_restrictive(e.disabled_until, current):
+                result[idx[nid]] = dataclasses.replace(
+                    result[idx[nid]], disabled_until=e.disabled_until
+                )
+        else:
+            idx[nid] = len(result)
+            result.append(e)
+
+    return result
+
+
+def _more_restrictive(candidate: datetime | None, current: datetime | None) -> bool:
+    if candidate is None:
+        return False
+    if current is None:
+        return True
+    return candidate > current
+
+
+def _parse_date(s: str) -> datetime | None:
+
+    formats = ["%Y-%m-%d", "%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S"]
+    for fmt in formats:
+        try:
+            dt = datetime.strptime(s, fmt)
+            if fmt == "%Y-%m-%d":
+                # Treat as end-of-day UTC so the full day is disabled.
+                dt = dt.replace(hour=23, minute=59, second=59, tzinfo=timezone.utc)
+            return dt
+        except ValueError:
+            continue
+    return None
+
+
+def _index_of(header: list[str], col: str) -> int:
+    try:
+        return header.index(col)
+    except ValueError:
+        return -1
+
+
+def _sheet_id_by_name(spreadsheet: dict[str, Any], name: str) -> int:
+    for s in spreadsheet.get("sheets", []):
+        if s["properties"]["title"] == name:
+            return int(s["properties"]["sheetId"])
+    return 0

skipper_core-0.1.0/src/skipper_core/config.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .credentials import Credentials
+
+
+@dataclasses.dataclass(frozen=True)
+class SkipperConfig:
+    spreadsheet_id: str
+    credentials: Credentials
+    sheet_name: str | None = None
+    reference_sheets: tuple[str, ...] = ()
+    # Column header names in the spreadsheet (camelCase matches all other ports).
+    test_id_column: str = "testId"
+    disabled_until_column: str = "disabledUntil"

skipper_core-0.1.0/src/skipper_core/credentials.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import base64
+import dataclasses
+import json
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Credentials(Protocol):
+    def resolve(self) -> bytes: ...
+
+
+@dataclasses.dataclass(frozen=True)
+class FileCredentials:
+    path: str
+
+    def resolve(self) -> bytes:
+        return Path(self.path).read_bytes()
+
+
+@dataclasses.dataclass(frozen=True)
+class Base64Credentials:
+    encoded: str
+
+    def resolve(self) -> bytes:
+        return base64.b64decode(self.encoded)
+
+
+@dataclasses.dataclass(frozen=True)
+class ServiceAccountCredentials:
+    type: str
+    project_id: str
+    private_key_id: str
+    private_key: str
+    client_email: str
+    client_id: str
+    auth_uri: str
+    token_uri: str
+    auth_provider_x509_cert_url: str
+    client_x509_cert_url: str
+
+    def resolve(self) -> bytes:
+        return json.dumps(dataclasses.asdict(self)).encode()

skipper_core-0.1.0/src/skipper_core/logger.py

@@ -0,0 +1,30 @@
+import logging
+import os
+
+_logger = logging.getLogger("skipper")
+_handler = logging.StreamHandler()
+_handler.setFormatter(logging.Formatter("[skipper] %(message)s"))
+_logger.addHandler(_handler)
+_logger.propagate = False
+
+
+def _is_debug_enabled() -> bool:
+    return bool(os.getenv("SKIPPER_DEBUG"))
+
+
+def log(msg: str) -> None:
+    if _is_debug_enabled():
+        _logger.setLevel(logging.DEBUG)
+        _logger.debug(msg)
+
+
+def logf(fmt: str, *args: object) -> None:
+    if _is_debug_enabled():
+        _logger.setLevel(logging.DEBUG)
+        _logger.debug(fmt, *args)
+
+
+def warn(msg: str) -> None:
+    if _is_debug_enabled():
+        _logger.setLevel(logging.DEBUG)
+        _logger.warning("WARN: %s", msg)

skipper_core-0.1.0/src/skipper_core/mode.py

@@ -0,0 +1,13 @@
+import os
+from enum import Enum
+
+
+class SkipperMode(str, Enum):
+    READ_ONLY = "read-only"
+    SYNC = "sync"
+
+
+def mode_from_env() -> SkipperMode:
+    if os.getenv("SKIPPER_MODE") == "sync":
+        return SkipperMode.SYNC
+    return SkipperMode.READ_ONLY

skipper_core-0.1.0/src/skipper_core/resolver.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from .client import SheetsClient
+from .config import SkipperConfig
+from .logger import log, logf
+from .testid import normalize_test_id
+
+
+class SkipperResolver:
+    """Fetches a Google Spreadsheet and determines whether tests should run.
+
+    Usage::
+
+        resolver = SkipperResolver(config)
+        resolver.initialize()          # fetches spreadsheet once
+        if not resolver.is_test_enabled("tests/test_auth.py > test_login"):
+            pytest.skip("disabled")
+    """
+
+    def __init__(self, config: SkipperConfig) -> None:
+        self._config = config
+        self._client = SheetsClient(config)
+        # Normalized test ID → disabledUntil (None means "in sheet, no date")
+        self._cache: dict[str, datetime | None] = {}
+
+    def initialize(self) -> None:
+        """Fetch the spreadsheet and populate the internal cache. Call once before use."""
+        log("initializing resolver")
+        result = self._client.fetch_all()
+        for entry in result.entries:
+            nid = normalize_test_id(entry.test_id)
+            self._cache[nid] = entry.disabled_until
+        logf("loaded %d test entries from spreadsheet", len(self._cache))
+
+    def is_test_enabled(self, test_id: str) -> bool:
+        """Return True if the test should run.
+
+        - Tests not in the spreadsheet always run (opt-out model).
+        - Tests with no date, or a past/today date, run normally.
+        - Tests with a future disabledUntil date are skipped.
+        """
+        nid = normalize_test_id(test_id)
+        if nid not in self._cache:
+            return True
+        disabled_until = self._cache[nid]
+        if disabled_until is None:
+            return True
+        now = datetime.now(tz=timezone.utc)
+        # Make naive datetimes comparable by treating them as UTC.
+        if disabled_until.tzinfo is None:
+            disabled_until = disabled_until.replace(tzinfo=timezone.utc)
+        return disabled_until <= now
+
+    def get_disabled_until(self, test_id: str) -> datetime | None:
+        """Return the disabledUntil date for a test, or None if not set."""
+        nid = normalize_test_id(test_id)
+        return self._cache.get(nid)
+
+    def marshal_cache(self) -> bytes:
+        """Serialize the cache to JSON bytes for cross-process sharing."""
+        out: dict[str, str | None] = {}
+        for k, v in self._cache.items():
+            out[k] = v.isoformat() if v is not None else None
+        return json.dumps(out).encode()
+
+    @classmethod
+    def from_marshal_cache(cls, data: bytes) -> SkipperResolver:
+        """Rehydrate a resolver from bytes produced by marshal_cache."""
+        raw: dict[str, Any] = json.loads(data)
+        cache: dict[str, datetime | None] = {}
+        for k, v in raw.items():
+            if v is None:
+                cache[k] = None
+            else:
+                cache[k] = datetime.fromisoformat(v)
+        resolver = cls.__new__(cls)
+        resolver._cache = cache
+        resolver._config = None  # type: ignore[assignment]
+        resolver._client = None  # type: ignore[assignment]
+        return resolver

skipper_core-0.1.0/src/skipper_core/testid.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import contextlib
+import re
+from pathlib import Path
+
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def normalize_test_id(test_id: str) -> str:
+    """Lowercase, strip, and collapse whitespace for case-insensitive matching."""
+    return _WHITESPACE_RE.sub(" ", test_id.strip().lower())
+
+
+def build_test_id(file_path: str, title_parts: list[str]) -> str:
+    """Build a test ID in the format: 'path/to/test.py > part1 > part2'.
+
+    If file_path is absolute it is made relative to the project root
+    (located by searching for pyproject.toml or setup.py).
+    Path separators are normalised to forward slashes.
+    """
+    rel = _to_relative_path(file_path)
+    return " > ".join([rel, *title_parts])
+
+
+def _to_relative_path(file_path: str) -> str:
+    p = Path(file_path)
+    if p.is_absolute():
+        root = _find_project_root(p)
+        if root is None:
+            import os
+
+            root = Path(os.getcwd())
+        with contextlib.suppress(ValueError):
+            p = p.relative_to(root)
+    return str(p).replace("\\", "/")
+
+
+def _find_project_root(file_path: Path) -> Path | None:
+    """Walk up looking for pyproject.toml (workspace root) or setup.py (module root)."""
+    # Prefer pyproject.toml (uv workspace) over setup.py (legacy).
+    pyproject_root: Path | None = None
+    for parent in [file_path.parent, *file_path.parent.parents]:
+        if (parent / "pyproject.toml").exists():
+            # Keep walking up — we want the *outermost* pyproject.toml
+            # (i.e., the workspace root, not a sub-package root).
+            pyproject_root = parent
+        if (parent / "uv.lock").exists():
+            # uv workspace root — highest priority, stop immediately.
+            return parent
+    if pyproject_root is not None:
+        return pyproject_root
+    # Fallback: look for setup.py
+    for parent in [file_path.parent, *file_path.parent.parents]:
+        if (parent / "setup.py").exists():
+            return parent
+    return None

skipper_core-0.1.0/src/skipper_core/writer.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import SheetsClient, _index_of
+from .config import SkipperConfig
+from .logger import logf
+from .testid import normalize_test_id
+
+
+class SheetsWriter:
+    """Reconciles a Google Spreadsheet with a set of discovered test IDs.
+
+    Sync behaviour:
+    - Rows whose test ID is no longer discovered (and belong to the same files
+      as the current sync) are deleted.
+    - Newly discovered test IDs are appended with an empty disabledUntil.
+    """
+
+    def __init__(self, config: SkipperConfig) -> None:
+        self._config = config
+        self._client = SheetsClient(config)
+
+    def sync(self, discovered_ids: list[str]) -> None:
+        logf("syncing %d discovered test IDs", len(discovered_ids))
+
+        result = self._client.fetch_all()
+        primary = result.primary
+        svc: Any = result.service
+
+        test_id_idx = _index_of(primary.header, self._config.test_id_column)
+        if test_id_idx < 0:
+            raise ValueError(
+                f"column {self._config.test_id_column!r} not found in sheet {primary.sheet_name!r}"
+            )
+
+        discovered_set = {normalize_test_id(id_) for id_ in discovered_ids}
+
+        # Determine which file paths are "owned" by this sync.
+        owned_files: set[str] = set()
+        owned_bases: set[str] = set()
+        for id_ in discovered_ids:
+            nid = normalize_test_id(id_)
+            sep = nid.find(" > ")
+            if sep >= 0:
+                file = nid[:sep]
+                owned_files.add(file)
+                base_sep = file.rfind("/")
+                owned_bases.add(file[base_sep + 1 :] if base_sep >= 0 else file)
+
+        existing_map = {normalize_test_id(e.test_id): e.test_id for e in primary.entries}
+
+        # Collect row indices (0-based, after header) to delete.
+        rows_to_delete: list[int] = []
+        for i, entry in enumerate(primary.entries):
+            nid = normalize_test_id(entry.test_id)
+            sep = nid.find(" > ")
+            if sep < 0:
+                # Malformed row — clean it up unconditionally.
+                rows_to_delete.append(i + 1)
+                continue
+            file = nid[:sep]
+            owned = file in owned_files
+            if not owned and "/" not in file:
+                owned = file in owned_bases
+            if not owned:
+                continue
+            if nid not in discovered_set:
+                rows_to_delete.append(i + 1)
+
+        # Delete in descending order to avoid index shifting.
+        if rows_to_delete:
+            rows_to_delete.sort(reverse=True)
+            requests = [
+                {
+                    "deleteDimension": {
+                        "range": {
+                            "sheetId": primary.sheet_id,
+                            "dimension": "ROWS",
+                            "startIndex": row_idx,
+                            "endIndex": row_idx + 1,
+                        }
+                    }
+                }
+                for row_idx in rows_to_delete
+            ]
+            svc.spreadsheets().batchUpdate(
+                spreadsheetId=self._config.spreadsheet_id,
+                body={"requests": requests},
+            ).execute()
+            logf("deleted %d rows from spreadsheet", len(rows_to_delete))
+
+        # Append new rows.
+        to_add = [id_ for id_ in discovered_ids if normalize_test_id(id_) not in existing_map]
+        if to_add:
+            header_len = len(primary.header)
+            values: list[list[Any]] = []
+            for id_ in to_add:
+                row: list[Any] = [""] * header_len
+                row[test_id_idx] = id_
+                values.append(row)
+            svc.spreadsheets().values().append(
+                spreadsheetId=self._config.spreadsheet_id,
+                range=primary.sheet_name,
+                valueInputOption="RAW",
+                body={"values": values},
+            ).execute()
+            logf("appended %d new test IDs to spreadsheet", len(to_add))