syncestra 1.0.0__py3-none-any.whl

syncestra/__init__.py

@@ -0,0 +1,14 @@
+"""syncestra — sync local service directories to private git mirrors.
+
+Package root. Re-exports the frozen exit-code contract so downstream code and tests
+can depend on stable, agent-facing codes. The CLI entry point lives in
+:mod:`syncestra.cli`; result models in :mod:`syncestra.models`.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from syncestra.exit_codes import ExitCode
+
+__all__ = ["ExitCode", "__version__"]

syncestra/__main__.py

@@ -0,0 +1,17 @@
+"""``python -m syncestra`` entry point.
+
+Delegates to the Typer app in :mod:`syncestra.cli`.
+"""
+
+from __future__ import annotations
+
+from syncestra.cli import app
+
+
+def main() -> None:
+    """Run the syncestra CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

syncestra/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters package — pluggable ABCs and concrete implementations.
+
+Epic 1 ships only the ``.syncignore`` parser (:mod:`syncestra.adapters.git_ignore`).
+The classifier, secret scanner, git engine, and docker stub land in later epics.
+"""

syncestra/adapters/askpass_helper.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# syncestra GIT_ASKPASS helper (architecture §3, line 89: "PAT in credential
+# helper"). Git invokes this once per credential prompt, passing the prompt
+# text as $1. We answer with the token held in the SYNCESTRA_ASKPASS_TOKEN
+# environment variable — the token rides the env of the single git invocation
+# (set by _github_auth_env), never the remote URL, never .git/config, and never
+# a process argument visible to other users on the host.
+#
+# Why an askpass (not a credential.helper store): a credential.helper would
+# persist creds to ~/.git-credentials on disk; askpass is stateless and per-op,
+# matching the architecture's "Never embed creds" rule. The token is read from
+# the environment of the parent git process syncestra spawned, which is gone
+# once the operation completes.
+#
+# This script is intentionally tiny and dependency-free (POSIX sh) so it runs
+# anywhere git does. It must NEVER contain a token literal.
+if [ -n "$SYNCESTRA_ASKPASS_TOKEN" ]; then
+    printf '%s\n' "$SYNCESTRA_ASKPASS_TOKEN"
+    exit 0
+fi
+# No token → exit non-zero so git does not hang waiting on a prompt.
+exit 1

syncestra/adapters/classifier.py

@@ -0,0 +1,111 @@
+"""DefaultFileClassifier — rule-driven file bucketing (Story 3.1, FR-FILE-1).
+
+Auto-classifies each file path into one of four sync buckets:
+
+* ``config``  — settings, project docs (sync)
+* ``session`` — recorded sessions / transcripts (sync)
+* ``cache``   — logs, caches, ``node_modules`` (never sync)
+* ``data``    — everything else, the syncable default (sync)
+
+The classifier is **rule-driven and per-service**: each service spec supplies an
+ordered list of :class:`ClassificationRule` (pattern + bucket). Rules are
+evaluated in order and the **first match wins**; a path matching no rule falls
+through to ``data``. Claude Code's rules live in
+:mod:`syncestra.services.claude_code` (Story 3.2); the engine here is generic.
+
+Patterns use gitignore-style matching (delegated to
+:class:`~syncestra.adapters.git_ignore.SyncignoreParser` compilation rules) so a
+service spec author writes the same glob syntax they already know: ``*.log``,
+``sessions/*``, ``node_modules/**``, etc.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from syncestra.adapters.interfaces import (
+    BUCKET_CACHE,
+    BUCKET_CONFIG,
+    BUCKET_DATA,
+    BUCKET_SESSION,
+)
+
+
+@dataclass(frozen=True)
+class ClassificationRule:
+    """One bucketing rule: a gitignore-style ``pattern`` mapping to a ``bucket``.
+
+    Attributes:
+        pattern: A gitignore-style pattern (``*.log``, ``sessions/*``,
+            ``node_modules/**``). Matching reuses the syncignore regex compiler
+            so the syntax is identical to ``.syncignore``.
+        bucket: One of the :class:`~syncestra.adapters.interfaces.FileBucket`
+            values (``config``/``session``/``cache``/``data``).
+    """
+
+    pattern: str
+    bucket: str
+
+    def matches(self, path: str) -> bool:
+        """Return True if ``path`` matches this rule's pattern."""
+        return _compile_pattern(self.pattern).search(path) is not None
+
+
+class DefaultFileClassifier:
+    """Rule-driven file classifier (FR-FILE-1; architecture §8).
+
+    Constructed with an ordered list of :class:`ClassificationRule`. The first
+    matching rule's bucket wins; a path matching no rule is ``data`` (syncable).
+
+    Satisfies the :class:`~syncestra.adapters.interfaces.FileClassifier`
+    Protocol so it slots into :class:`~syncestra.core.context.ServiceContext`.
+    """
+
+    def __init__(self, rules: list[ClassificationRule]) -> None:
+        self._compiled = [
+            (_compile_pattern(rule.pattern), rule.bucket) for rule in rules
+        ]
+
+    def classify(self, path: str) -> str:
+        """Return the bucket for ``path`` (first matching rule wins, else ``data``)."""
+        for regex, bucket in self._compiled:
+            if regex.search(path):
+                return bucket
+        return BUCKET_DATA
+
+
+# ---------------------------------------------------------------------------
+# Pattern compilation (reuses the syncignore → regex translation)
+# ---------------------------------------------------------------------------
+
+
+def _compile_pattern(pattern: str) -> re.Pattern[str]:
+    """Compile a gitignore-style ``pattern`` into an anchored regex.
+
+    Delegates to the syncignore compiler so classification patterns use the exact
+    same glob syntax as ``.syncignore`` (``*``, ``**``, trailing-slash dirs,
+    anchoring on ``/``). Cached per-pattern for repeated classification.
+    """
+    cached = _PATTERN_CACHE.get(pattern)
+    if cached is not None:
+        return cached
+    # Imported lazily to keep the module importable without git_ignore at load.
+    from syncestra.adapters.git_ignore import _compile as _sync_compile
+
+    compiled = _sync_compile(pattern)
+    _PATTERN_CACHE[pattern] = compiled
+    return compiled
+
+
+_PATTERN_CACHE: dict[str, re.Pattern[str]] = {}
+
+
+__all__ = [
+    "BUCKET_CACHE",
+    "BUCKET_CONFIG",
+    "BUCKET_DATA",
+    "BUCKET_SESSION",
+    "ClassificationRule",
+    "DefaultFileClassifier",
+]

syncestra/adapters/classifier_stub.py

@@ -0,0 +1,20 @@
+"""Stub file classifier for Epic 2 (replaced by DefaultFileClassifier in Epic 3).
+
+Epic 2's plan/status pipelines need a non-None classifier slot, but the
+rule-driven bucket logic is Story 3.1. This stub buckets every file as
+``data`` (always syncable) so cache subtraction is a no-op until the real
+classifier exists. Keeping it isolated means Epic 3 swaps it without touching
+the git engine.
+"""
+
+from __future__ import annotations
+
+
+class StubFileClassifier:
+    """Buckets every file as ``data`` (syncable). Replaced in Epic 3."""
+
+    def classify(self, path: str) -> str:  # noqa: ARG002 - slot contract
+        return "data"
+
+
+__all__ = ["StubFileClassifier"]

syncestra/adapters/debounce.py

@@ -0,0 +1,47 @@
+"""Single-flight flock debounce for watch-fired pushes (auto-push epic).
+
+watchman fires one event per file change. Without coalescing, a 10-file skill
+install → 10 commits. This module provides trailing-edge debounce via a
+non-blocking ``fcntl.flock``: the first invocation wins, sleeps the debounce
+window, then runs the push; concurrent invocations find the lock held and exit
+fast (coalesced). The winning push's ``git status`` sees every change in the
+burst because they all landed before the sleep elapsed.
+
+Filter logic (``.syncignore`` / classifier / exclude) lives in ``core.push`` —
+this layer is deliberately dumb. If a fire contains only cache/ignored changes,
+``core.push`` returns an idempotent no-op (H2 guard), so noise events cost one
+``git status`` call and nothing more.
+"""
+from __future__ import annotations
+
+import fcntl
+import os
+from pathlib import Path
+
+
+def default_lock_path(service: str) -> Path:
+    """Per-service lockfile under ``~/.syncestra/watch.<service>.lock``."""
+    return Path.home() / ".syncestra" / f"watch.{service}.lock"
+
+
+def try_acquire(lock_path: Path) -> tuple[bool, int]:
+    """Non-blocking exclusive acquire.
+
+    Returns ``(won, fd)``. If ``won`` is True the caller holds the lock and
+    must call :func:`release` when done. If ``won`` is False another caller
+    holds it — the caller should exit 0 (coalesced); ``fd`` is -1.
+    """
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        os.close(fd)
+        return False, -1
+    return True, fd
+
+
+def release(fd: int) -> None:
+    """Release a lock acquired via :func:`try_acquire`."""
+    fcntl.flock(fd, fcntl.LOCK_UN)
+    os.close(fd)

syncestra/adapters/docker_volume.py

@@ -0,0 +1,76 @@
+"""Docker-volume StorageAdapter — v2 STUB only (Story 3.5, Arch-7, §11).
+
+Implements the :class:`~syncestra.adapters.interfaces.StorageAdapter` Protocol
+surface so the seam exists, but **every method raises** :class:`NotImplementedError`.
+v1 ships only :class:`~syncestra.adapters.git_engine.GitStorageAdapter`; real
+Docker-volume support (stop container → copy volume → start, then treat as a git
+working tree) is v2+ scope (architecture §11 evolution table).
+
+The stub lets config / tests reference a Docker-backed service without v1 having
+to implement it — and makes the absence loud rather than silent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - import cycle guard
+    from syncestra.core.context import ServiceContext
+    from syncestra.models import DiffPlan, PullResult, PushResult, RestoreResult, StatusResult
+
+#: Message embedded in every NotImplementedError, pointing users to the v2 roadmap.
+_DOCKER_V2_MESSAGE = (
+    "Docker-volume storage is not implemented in syncestra v1; "
+    "use the default git adapter or wait for v2."
+)
+
+
+class DockerStorageAdapter:
+    """v2 stub StorageAdapter for Docker-volume services (architecture §8, §11).
+
+    Satisfies the :class:`~syncestra.adapters.interfaces.StorageAdapter` Protocol
+    structurally (all methods are present) but raises on every call. v2 will
+    replace the bodies with real Docker-volume logic without changing the seam.
+    """
+
+    def _stub(self) -> Any:
+        raise NotImplementedError(_DOCKER_V2_MESSAGE)
+
+    def init(self, ctx: ServiceContext) -> InitResultType:  # type: ignore[valid-type]
+        """Create the local working repo (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+    def plan(self, ctx: ServiceContext) -> DiffPlan:
+        """Compute the staged candidate set (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+    def commit_and_push(
+        self,
+        ctx: ServiceContext,
+        plan: DiffPlan,
+        message: str | None,
+        rollback_tag: str,
+    ) -> PushResult:
+        """Commit + push (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+    def pull(self, ctx: ServiceContext) -> PullResult:
+        """Pull from remote (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+    def status(self, ctx: ServiceContext) -> StatusResult:
+        """Return parity + changed files (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+    def restore(self, ctx: ServiceContext) -> RestoreResult:
+        """Restore from remote HEAD (NOT IMPLEMENTED in v1)."""
+        self._stub()  # pragma: no cover - raises before return
+
+
+# Type alias used only for the init return annotation (kept lazy to avoid an
+# import cycle at module load).
+if TYPE_CHECKING:
+    from syncestra.models import InitResult as InitResultType  # noqa: F401
+
+
+__all__ = ["DockerStorageAdapter"]