spec-kitty-tracker 0.1.0__tar.gz

spec_kitty_tracker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spec Kitty Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_kitty_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: spec-kitty-tracker
+Version: 0.1.0
+Summary: Universal tracker interface, connector SDK, and sync engine for Spec Kitty
+Author: Spec Kitty Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Spec Kitty Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Dynamic: license-file
+
+# spec-kitty-tracker
+
+Shared task-tracker abstraction layer for Spec Kitty CLI and SaaS.
+
+## Scope
+
+1. Canonical issue model (`CanonicalIssue`, `ExternalRef`, `CanonicalLink`)
+2. Tracker connector protocol with capability negotiation
+3. Doctrine-style source-of-truth ownership policies
+4. Conflict resolution and deterministic sync engine
+5. Bidirectional mission/issue sync bridge with decision reference traceability
+6. Connector registry and vendor connector implementations
+
+## Included Connectors
+
+1. `InMemoryConnector` (fully functional reference connector)
+2. `BeadsConnector` (explicit `bd` CLI adapter)
+3. `FPConnector` (explicit `fp` CLI adapter)
+4. `JiraConnector`
+5. `LinearConnector`
+6. `AzureDevOpsConnector`
+7. `GitHubConnector`
+8. `GitLabConnector`
+
+The vendor connectors are designed for production integration and may require tenant-specific field mappings.
+`BeadsConnector` and `FPConnector` are first-class adapters for local-first native tracker workflows.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development tools:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Example
+
+```python
+import asyncio
+from spec_kitty_tracker import (
+    CanonicalIssue,
+    CanonicalIssueType,
+    CanonicalStatus,
+    ExternalRef,
+    InMemoryConnector,
+    InMemoryIssueStore,
+    OwnershipPolicy,
+    OwnershipMode,
+    SyncEngine,
+)
+
+
+async def main() -> None:
+    connector = InMemoryConnector(name="jira", workspace="example")
+    store = InMemoryIssueStore()
+
+    issue = CanonicalIssue(
+        ref=ExternalRef(system="jira", workspace="example", id="DEMO-1", key="DEMO-1"),
+        title="First issue",
+        body="Seed issue",
+        status=CanonicalStatus.TODO,
+        issue_type=CanonicalIssueType.TASK,
+    )
+
+    await connector.create_issue(issue)
+
+    policy = OwnershipPolicy(mode=OwnershipMode.EXTERNAL_AUTHORITATIVE)
+    engine = SyncEngine(connector=connector, store=store, policy=policy)
+    await engine.pull()
+
+    pulled = await store.get_issue(issue.ref)
+    assert pulled is not None
+
+
+asyncio.run(main())
+```
+
+## Design Notes
+
+1. The core contract is intentionally tracker-agnostic.
+2. `OwnershipPolicy` makes source-of-truth behavior explicit and auditable.
+3. `SyncEngine` supports pull, push, and bidirectional sync with conflict records.
+4. Capability flags gate optional features (e.g., hierarchy, dependencies, webhooks).
+5. Mission updates are idempotent and persist decision references back to source issues.
+
+## Docs
+
+1. [Architecture](docs/ARCHITECTURE.md)
+2. [Connector Contract](docs/CONNECTOR_CONTRACT.md)
+3. [Doctrine Policy Modes](docs/DOCTRINE_POLICY.md)
+4. [P0 Provider Matrix](docs/provider-matrix.md)
+5. [WP04 Contract Alignment Notes](docs/wp04-contract-alignment.md)
+6. [WP11 Sync Core Notes](docs/wp11-sync-core-notes.md)

spec_kitty_tracker-0.1.0/README.md

@@ -0,0 +1,97 @@
+# spec-kitty-tracker
+
+Shared task-tracker abstraction layer for Spec Kitty CLI and SaaS.
+
+## Scope
+
+1. Canonical issue model (`CanonicalIssue`, `ExternalRef`, `CanonicalLink`)
+2. Tracker connector protocol with capability negotiation
+3. Doctrine-style source-of-truth ownership policies
+4. Conflict resolution and deterministic sync engine
+5. Bidirectional mission/issue sync bridge with decision reference traceability
+6. Connector registry and vendor connector implementations
+
+## Included Connectors
+
+1. `InMemoryConnector` (fully functional reference connector)
+2. `BeadsConnector` (explicit `bd` CLI adapter)
+3. `FPConnector` (explicit `fp` CLI adapter)
+4. `JiraConnector`
+5. `LinearConnector`
+6. `AzureDevOpsConnector`
+7. `GitHubConnector`
+8. `GitLabConnector`
+
+The vendor connectors are designed for production integration and may require tenant-specific field mappings.
+`BeadsConnector` and `FPConnector` are first-class adapters for local-first native tracker workflows.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development tools:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Example
+
+```python
+import asyncio
+from spec_kitty_tracker import (
+    CanonicalIssue,
+    CanonicalIssueType,
+    CanonicalStatus,
+    ExternalRef,
+    InMemoryConnector,
+    InMemoryIssueStore,
+    OwnershipPolicy,
+    OwnershipMode,
+    SyncEngine,
+)
+
+
+async def main() -> None:
+    connector = InMemoryConnector(name="jira", workspace="example")
+    store = InMemoryIssueStore()
+
+    issue = CanonicalIssue(
+        ref=ExternalRef(system="jira", workspace="example", id="DEMO-1", key="DEMO-1"),
+        title="First issue",
+        body="Seed issue",
+        status=CanonicalStatus.TODO,
+        issue_type=CanonicalIssueType.TASK,
+    )
+
+    await connector.create_issue(issue)
+
+    policy = OwnershipPolicy(mode=OwnershipMode.EXTERNAL_AUTHORITATIVE)
+    engine = SyncEngine(connector=connector, store=store, policy=policy)
+    await engine.pull()
+
+    pulled = await store.get_issue(issue.ref)
+    assert pulled is not None
+
+
+asyncio.run(main())
+```
+
+## Design Notes
+
+1. The core contract is intentionally tracker-agnostic.
+2. `OwnershipPolicy` makes source-of-truth behavior explicit and auditable.
+3. `SyncEngine` supports pull, push, and bidirectional sync with conflict records.
+4. Capability flags gate optional features (e.g., hierarchy, dependencies, webhooks).
+5. Mission updates are idempotent and persist decision references back to source issues.
+
+## Docs
+
+1. [Architecture](docs/ARCHITECTURE.md)
+2. [Connector Contract](docs/CONNECTOR_CONTRACT.md)
+3. [Doctrine Policy Modes](docs/DOCTRINE_POLICY.md)
+4. [P0 Provider Matrix](docs/provider-matrix.md)
+5. [WP04 Contract Alignment Notes](docs/wp04-contract-alignment.md)
+6. [WP11 Sync Core Notes](docs/wp11-sync-core-notes.md)

spec_kitty_tracker-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "spec-kitty-tracker"
+version = "0.1.0"
+description = "Universal tracker interface, connector SDK, and sync engine for Spec Kitty"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name = "Spec Kitty Contributors" }
+]
+license = {file = "LICENSE"}
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+]
+dependencies = [
+  "httpx>=0.27.0,<1.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "mypy>=1.10.0",
+  "ruff>=0.6.0"
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.setuptools.package-data]
+spec_kitty_tracker = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = "-q"
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

spec_kitty_tracker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spec_kitty_tracker-0.1.0/src/spec_kitty_tracker/__init__.py

@@ -0,0 +1,114 @@
+"""spec-kitty-tracker: universal task tracker interface and sync engine."""
+
+from spec_kitty_tracker.capabilities import TrackerCapabilities
+from spec_kitty_tracker.conflicts import ConflictRecord, ConflictStrategy
+from spec_kitty_tracker.connectors import (
+    AzureDevOpsConnector,
+    AzureDevOpsConnectorConfig,
+    BeadsConnector,
+    BeadsConnectorConfig,
+    FPConnector,
+    FPConnectorConfig,
+    GitHubConnector,
+    GitHubConnectorConfig,
+    GitLabConnector,
+    GitLabConnectorConfig,
+    InMemoryConnector,
+    JiraConnector,
+    JiraConnectorConfig,
+    LinearConnector,
+    LinearConnectorConfig,
+)
+from spec_kitty_tracker.errors import (
+    CapabilityNotSupportedError,
+    FailureClass,
+    ConnectorConfigError,
+    ConnectorRequestError,
+    IssueNotFoundError,
+    SpecKittyTrackerError,
+    SyncConflictError,
+    classify_http_status,
+)
+from spec_kitty_tracker.models import (
+    CanonicalIssue,
+    CanonicalIssueType,
+    CanonicalLink,
+    CanonicalStatus,
+    ExternalRef,
+    LinkType,
+    Page,
+    SyncCheckpoint,
+    TrackerEvent,
+    TrackerEventType,
+    utcnow,
+)
+from spec_kitty_tracker.mission_sync import (
+    BidirectionalIssueSync,
+    DecisionReference,
+    MissionSeed,
+    MissionUpdate,
+    mission_seed_from_issue,
+)
+from spec_kitty_tracker.policy import CORE_ISSUE_FIELDS, FieldOwner, OwnershipMode, OwnershipPolicy
+from spec_kitty_tracker.protocols import LocalIssueStore, TaskTrackerConnector
+from spec_kitty_tracker.registry import ConnectorRegistry
+from spec_kitty_tracker.store import InMemoryIssueStore
+from spec_kitty_tracker.sync import SyncEngine, SyncResult, SyncStats
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AzureDevOpsConnector",
+    "AzureDevOpsConnectorConfig",
+    "BeadsConnector",
+    "BeadsConnectorConfig",
+    "BidirectionalIssueSync",
+    "CapabilityNotSupportedError",
+    "CanonicalIssue",
+    "CanonicalIssueType",
+    "CanonicalLink",
+    "CanonicalStatus",
+    "ConflictRecord",
+    "ConflictStrategy",
+    "ConnectorConfigError",
+    "ConnectorRegistry",
+    "ConnectorRequestError",
+    "CORE_ISSUE_FIELDS",
+    "DecisionReference",
+    "ExternalRef",
+    "FailureClass",
+    "FieldOwner",
+    "FPConnector",
+    "FPConnectorConfig",
+    "GitHubConnector",
+    "GitHubConnectorConfig",
+    "GitLabConnector",
+    "GitLabConnectorConfig",
+    "InMemoryConnector",
+    "InMemoryIssueStore",
+    "IssueNotFoundError",
+    "JiraConnector",
+    "JiraConnectorConfig",
+    "LinearConnector",
+    "LinearConnectorConfig",
+    "LinkType",
+    "LocalIssueStore",
+    "MissionSeed",
+    "MissionUpdate",
+    "OwnershipMode",
+    "OwnershipPolicy",
+    "Page",
+    "SpecKittyTrackerError",
+    "SyncCheckpoint",
+    "SyncConflictError",
+    "SyncEngine",
+    "SyncResult",
+    "SyncStats",
+    "classify_http_status",
+    "TaskTrackerConnector",
+    "TrackerCapabilities",
+    "TrackerEvent",
+    "TrackerEventType",
+    "mission_seed_from_issue",
+    "utcnow",
+]

spec_kitty_tracker-0.1.0/src/spec_kitty_tracker/capabilities.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class TrackerCapabilities:
+    supports_webhooks: bool = False
+    supports_comments: bool = True
+    supports_hierarchy: bool = True
+    supports_dependencies: bool = True
+    supports_custom_fields: bool = True
+    supports_multi_assignee: bool = True
+    supports_sprints_or_cycles: bool = False
+    supports_bulk_read: bool = False
+    supports_bulk_write: bool = False
+    supports_delete: bool = False
+
+    def as_dict(self) -> dict[str, bool]:
+        return {
+            "supports_webhooks": self.supports_webhooks,
+            "supports_comments": self.supports_comments,
+            "supports_hierarchy": self.supports_hierarchy,
+            "supports_dependencies": self.supports_dependencies,
+            "supports_custom_fields": self.supports_custom_fields,
+            "supports_multi_assignee": self.supports_multi_assignee,
+            "supports_sprints_or_cycles": self.supports_sprints_or_cycles,
+            "supports_bulk_read": self.supports_bulk_read,
+            "supports_bulk_write": self.supports_bulk_write,
+            "supports_delete": self.supports_delete,
+        }

spec_kitty_tracker-0.1.0/src/spec_kitty_tracker/conflicts.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from spec_kitty_tracker.policy import FieldOwner
+
+
+class ConflictStrategy(StrEnum):
+    EXTERNAL_WINS = "external_wins"
+    LOCAL_WINS = "local_wins"
+    NEWER_TIMESTAMP = "newer_timestamp"
+    MANUAL_REVIEW = "manual_review"
+
+
+@dataclass(frozen=True, slots=True)
+class ConflictRecord:
+    field_name: str
+    local_value: Any
+    external_value: Any
+    resolved_value: Any
+    strategy: ConflictStrategy
+    manual_review_required: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class FieldResolution:
+    value: Any
+    conflict: ConflictRecord | None
+
+
+def _prefer_newer(
+    local_value: Any,
+    external_value: Any,
+    local_updated_at: datetime | None,
+    external_updated_at: datetime | None,
+) -> Any:
+    if local_updated_at is None and external_updated_at is None:
+        return external_value
+    if local_updated_at is None:
+        return external_value
+    if external_updated_at is None:
+        return local_value
+    if external_updated_at >= local_updated_at:
+        return external_value
+    return local_value
+
+
+def resolve_field(
+    *,
+    field_name: str,
+    owner: FieldOwner,
+    local_value: Any,
+    external_value: Any,
+    local_updated_at: datetime | None,
+    external_updated_at: datetime | None,
+    strategy: ConflictStrategy,
+) -> FieldResolution:
+    if local_value == external_value:
+        return FieldResolution(value=local_value, conflict=None)
+
+    if owner is FieldOwner.LOCAL:
+        return FieldResolution(value=local_value, conflict=None)
+
+    if owner is FieldOwner.EXTERNAL:
+        return FieldResolution(value=external_value, conflict=None)
+
+    manual_review_required = False
+    if strategy is ConflictStrategy.EXTERNAL_WINS:
+        resolved = external_value
+    elif strategy is ConflictStrategy.LOCAL_WINS:
+        resolved = local_value
+    elif strategy is ConflictStrategy.NEWER_TIMESTAMP:
+        resolved = _prefer_newer(
+            local_value,
+            external_value,
+            local_updated_at,
+            external_updated_at,
+        )
+    else:
+        resolved = local_value
+        manual_review_required = True
+
+    conflict = ConflictRecord(
+        field_name=field_name,
+        local_value=local_value,
+        external_value=external_value,
+        resolved_value=resolved,
+        strategy=strategy,
+        manual_review_required=manual_review_required,
+    )
+    return FieldResolution(value=resolved, conflict=conflict)

spec_kitty_tracker-0.1.0/src/spec_kitty_tracker/connectors/__init__.py

@@ -0,0 +1,29 @@
+from spec_kitty_tracker.connectors.azure_devops import (
+    AzureDevOpsConnector,
+    AzureDevOpsConnectorConfig,
+)
+from spec_kitty_tracker.connectors.beads import BeadsConnector, BeadsConnectorConfig
+from spec_kitty_tracker.connectors.fp import FPConnector, FPConnectorConfig
+from spec_kitty_tracker.connectors.github import GitHubConnector, GitHubConnectorConfig
+from spec_kitty_tracker.connectors.gitlab import GitLabConnector, GitLabConnectorConfig
+from spec_kitty_tracker.connectors.in_memory import InMemoryConnector
+from spec_kitty_tracker.connectors.jira import JiraConnector, JiraConnectorConfig
+from spec_kitty_tracker.connectors.linear import LinearConnector, LinearConnectorConfig
+
+__all__ = [
+    "AzureDevOpsConnector",
+    "AzureDevOpsConnectorConfig",
+    "BeadsConnector",
+    "BeadsConnectorConfig",
+    "FPConnector",
+    "FPConnectorConfig",
+    "GitHubConnector",
+    "GitHubConnectorConfig",
+    "GitLabConnector",
+    "GitLabConnectorConfig",
+    "InMemoryConnector",
+    "JiraConnector",
+    "JiraConnectorConfig",
+    "LinearConnector",
+    "LinearConnectorConfig",
+]