tinyhorse 0.1.0__py3-none-any.whl

tinyhorse/__init__.py

@@ -0,0 +1,3 @@
+"""Tiny Horse: Git-native project control."""
+
+__version__ = "0.1.0"

tinyhorse/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

tinyhorse/auth.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+GOOGLE_DRIVE_SCOPE = "https://www.googleapis.com/auth/drive"
+TOKEN_FILE = "google-drive-credentials.json"
+CLIENT_FILE = "google-client.json"
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AuthStatus:
+    provider: str
+    authenticated: bool
+    source: str | None
+    credentials_path: str | None
+    expires_at: str | None
+    scopes: list[str]
+    details: list[str]
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, sort_keys=True)
+
+
+def config_dir() -> Path:
+    override = os.environ.get("TINYHORSE_CONFIG_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return (Path(xdg).expanduser() / "tinyhorse").resolve()
+
+    appdata = os.environ.get("APPDATA")
+    if os.name == "nt" and appdata:
+        return (Path(appdata).expanduser() / "TinyHorse").resolve()
+
+    return (Path.home() / ".config" / "tinyhorse").resolve()
+
+
+def credentials_path() -> Path:
+    return config_dir() / TOKEN_FILE
+
+
+def default_client_secrets_path() -> Path:
+    return config_dir() / CLIENT_FILE
+
+
+def packaged_client_secrets_path() -> Path:
+    return Path(__file__).with_name(CLIENT_FILE)
+
+
+def resolve_client_secrets_path(explicit: str | Path | None = None) -> Path:
+    candidates: list[Path] = []
+    if explicit is not None:
+        candidates.append(Path(explicit).expanduser())
+    env = os.environ.get("TINYHORSE_GOOGLE_CLIENT_SECRETS")
+    if env:
+        candidates.append(Path(env).expanduser())
+    candidates.append(default_client_secrets_path())
+    candidates.append(packaged_client_secrets_path())
+
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.resolve()
+
+    looked = ", ".join(str(path) for path in candidates)
+    raise AuthError(
+        "Google Drive OAuth client configuration not found. "
+        "Pass --client-secrets PATH, set TINYHORSE_GOOGLE_CLIENT_SECRETS, "
+        f"or place the file at {default_client_secrets_path()}. Looked in: {looked}"
+    )
+
+
+def _google_modules() -> tuple[Any, Any, Any]:
+    try:
+        from google.auth.transport.requests import Request
+        from google.oauth2.credentials import Credentials
+        from google_auth_oauthlib.flow import InstalledAppFlow
+    except ImportError as exc:
+        raise AuthError(
+            "Google Drive login support is not installed. "
+            "Install it with: pip install 'tinyhorse[gdrive]'"
+        ) from exc
+    return Credentials, Request, InstalledAppFlow
+
+
+def _remember_client_secrets(source: Path) -> Path:
+    destination = default_client_secrets_path()
+    if source.resolve() == destination.resolve():
+        return destination
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    tmp = destination.with_suffix(destination.suffix + ".tmp")
+    tmp.write_bytes(source.read_bytes())
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, destination)
+    return destination
+
+
+def _write_credentials(credentials: Any) -> Path:
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(credentials.to_json(), encoding="utf-8")
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+    return path
+
+
+def _expiry_iso(credentials: Any) -> str | None:
+    expiry = getattr(credentials, "expiry", None)
+    if expiry is None:
+        return None
+    if expiry.tzinfo is None:
+        expiry = expiry.replace(tzinfo=timezone.utc)
+    return expiry.isoformat()
+
+
+def login_google_drive(
+    client_secrets: str | Path | None = None,
+    *,
+    open_browser: bool = True,
+    port: int = 0,
+) -> AuthStatus:
+    """Run Google's installed-app OAuth flow and save refreshable credentials."""
+    _, _, InstalledAppFlow = _google_modules()
+    client_path = resolve_client_secrets_path(client_secrets)
+    flow = InstalledAppFlow.from_client_secrets_file(
+        str(client_path), scopes=[GOOGLE_DRIVE_SCOPE]
+    )
+    remembered_client_path = _remember_client_secrets(client_path)
+    credentials = flow.run_local_server(
+        host="localhost",
+        port=port,
+        open_browser=open_browser,
+        authorization_prompt_message=(
+            "Open this URL in a browser to authorize Tiny Horse:\n{url}"
+        ),
+        success_message="Tiny Horse is authorized. You can close this browser window.",
+    )
+    path = _write_credentials(credentials)
+    return AuthStatus(
+        provider="google-drive",
+        authenticated=True,
+        source="saved-oauth",
+        credentials_path=str(path),
+        expires_at=_expiry_iso(credentials),
+        scopes=list(getattr(credentials, "scopes", None) or [GOOGLE_DRIVE_SCOPE]),
+        details=[f"OAuth client configuration saved at: {remembered_client_path}"],
+    )
+
+
+def _load_saved_credentials(*, refresh: bool = True) -> Any:
+    Credentials, Request, _ = _google_modules()
+    path = credentials_path()
+    if not path.is_file():
+        raise AuthError(
+            "Google Drive is not authenticated. Run: tinyhorse auth login"
+        )
+    try:
+        credentials = Credentials.from_authorized_user_file(
+            str(path), scopes=[GOOGLE_DRIVE_SCOPE]
+        )
+    except (ValueError, json.JSONDecodeError, OSError) as exc:
+        raise AuthError(f"could not read saved Google Drive credentials: {exc}") from exc
+
+    if refresh and not credentials.valid:
+        if credentials.expired and credentials.refresh_token:
+            try:
+                credentials.refresh(Request())
+            except Exception as exc:  # google-auth raises several transport/auth types
+                raise AuthError(f"could not refresh Google Drive credentials: {exc}") from exc
+            _write_credentials(credentials)
+        else:
+            raise AuthError(
+                "saved Google Drive credentials are not usable. Run: tinyhorse auth login"
+            )
+    return credentials
+
+
+def google_drive_access_token() -> str:
+    """Resolve an access token, refreshing saved OAuth credentials when needed.
+
+    The legacy environment variable remains supported for automation and CI, but
+    interactive users should normally run `tinyhorse auth login` once.
+    """
+    env_token = os.environ.get("TINYHORSE_GOOGLE_DRIVE_TOKEN")
+    if env_token:
+        return env_token
+    credentials = _load_saved_credentials(refresh=True)
+    token = getattr(credentials, "token", None)
+    if not token:
+        raise AuthError("Google Drive credentials did not yield an access token")
+    return token
+
+
+def google_drive_auth_status(*, refresh: bool = False) -> AuthStatus:
+    env_token = os.environ.get("TINYHORSE_GOOGLE_DRIVE_TOKEN")
+    if env_token:
+        return AuthStatus(
+            provider="google-drive",
+            authenticated=True,
+            source="environment-token",
+            credentials_path=None,
+            expires_at=None,
+            scopes=[],
+            details=["TINYHORSE_GOOGLE_DRIVE_TOKEN is set"],
+        )
+
+    path = credentials_path()
+    if not path.is_file():
+        return AuthStatus(
+            provider="google-drive",
+            authenticated=False,
+            source=None,
+            credentials_path=str(path),
+            expires_at=None,
+            scopes=[],
+            details=["Run: tinyhorse auth login"],
+        )
+
+    try:
+        credentials = _load_saved_credentials(refresh=refresh)
+    except AuthError as exc:
+        return AuthStatus(
+            provider="google-drive",
+            authenticated=False,
+            source="saved-oauth",
+            credentials_path=str(path),
+            expires_at=None,
+            scopes=[],
+            details=[str(exc)],
+        )
+
+    valid = bool(getattr(credentials, "valid", False))
+    expired = bool(getattr(credentials, "expired", False))
+    refresh_token = bool(getattr(credentials, "refresh_token", None))
+    authenticated = valid or (expired and refresh_token and not refresh)
+    details: list[str] = []
+    if expired and refresh_token and not refresh:
+        details.append("access token is expired but a refresh token is available")
+    elif not valid:
+        details.append("saved credentials are not currently valid")
+
+    return AuthStatus(
+        provider="google-drive",
+        authenticated=authenticated,
+        source="saved-oauth",
+        credentials_path=str(path),
+        expires_at=_expiry_iso(credentials),
+        scopes=list(getattr(credentials, "scopes", None) or [GOOGLE_DRIVE_SCOPE]),
+        details=details,
+    )
+
+
+def logout_google_drive() -> AuthStatus:
+    path = credentials_path()
+    removed = False
+    if path.exists():
+        path.unlink()
+        removed = True
+    return AuthStatus(
+        provider="google-drive",
+        authenticated=False,
+        source=None,
+        credentials_path=str(path),
+        expires_at=None,
+        scopes=[],
+        details=[
+            "saved credentials removed" if removed else "no saved credentials were present",
+            "This removes Tiny Horse's local credential cache; it does not revoke access in your Google account.",
+        ],
+    )

tinyhorse/cli.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+from .auth import AuthError, google_drive_auth_status, login_google_drive, logout_google_drive
+from .config import ConfigError
+from .git import GitError, create_bundle, repository_state, verify_bundle
+from .storage import StorageError
+from .workflow import (
+    WorkflowError,
+    clone_project,
+    doctor,
+    init_drive_project,
+    init_project,
+    migrate_remote,
+    projects,
+    pull,
+    push,
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tinyhorse")
+    parser.add_argument("--version", action="version", version=f"tinyhorse {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    status = sub.add_parser("status", help="print local Git state as JSON")
+    status.add_argument("path", nargs="?", default=".")
+
+    init = sub.add_parser("init", help="bind an existing Git repo to canonical storage")
+    init.add_argument("path", nargs="?", default=".")
+    init_storage = init.add_mutually_exclusive_group(required=True)
+    init_storage.add_argument("--storage", help="explicit storage locator")
+    init_storage.add_argument(
+        "--drive",
+        action="store_true",
+        help="find or create this project's Google Drive storage automatically",
+    )
+    init.add_argument("--project", help="project display name; defaults to repository directory name")
+
+    push_cmd = sub.add_parser("push", help="safely publish a verified canonical bundle")
+    push_cmd.add_argument("path", nargs="?", default=".")
+    push_cmd.add_argument(
+        "--force",
+        action="store_true",
+        help="allow intentional non-fast-forward history/ref changes; concurrent storage changes still abort",
+    )
+
+    pull_cmd = sub.add_parser("pull", help="restore a repository from canonical storage")
+    pull_cmd.add_argument("storage", help="file:... or gdrive://FOLDER_ID/FILENAME")
+    pull_cmd.add_argument("destination")
+
+    doctor_cmd = sub.add_parser("doctor", help="compare local state with canonical storage")
+    doctor_cmd.add_argument("path", nargs="?", default=".")
+
+    projects_cmd = sub.add_parser(
+        "projects", help="list discoverable Tiny Horse projects on Google Drive"
+    )
+
+    clone_cmd = sub.add_parser(
+        "clone", help="discover and restore a Tiny Horse project by name"
+    )
+    clone_cmd.add_argument("project")
+    clone_cmd.add_argument("destination", nargs="?")
+
+    bundle = sub.add_parser("bundle", help="create a complete Git bundle")
+    bundle.add_argument("path")
+    bundle.add_argument("output")
+
+    verify = sub.add_parser("verify-bundle", help="verify a Git bundle")
+    verify.add_argument("bundle")
+
+    move = sub.add_parser(
+        "migrate",
+        help="migrate a Git remote into Tiny Horse canonical storage",
+    )
+    move.add_argument("remote")
+    move.add_argument(
+        "destination",
+        nargs="?",
+        help="local checkout destination; defaults to the repository name",
+    )
+    move.add_argument("--project", help="project display name; defaults to repository name")
+    migrate_storage = move.add_mutually_exclusive_group()
+    migrate_storage.add_argument(
+        "--drive",
+        action="store_true",
+        help="auto-provision Google Drive storage (the default)",
+    )
+    migrate_storage.add_argument(
+        "--storage",
+        help="explicit canonical storage locator instead of Google Drive",
+    )
+
+    auth = sub.add_parser("auth", help="manage storage-provider authentication")
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+
+    auth_login = auth_sub.add_parser("login", help="sign in to Google Drive")
+    auth_login.add_argument(
+        "--client-secrets",
+        help="Google OAuth desktop-app client JSON; defaults to configured locations",
+    )
+    auth_login.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="print the authorization URL instead of opening a browser",
+    )
+
+    auth_status = auth_sub.add_parser("status", help="show Google Drive authentication state")
+    auth_status.add_argument(
+        "--refresh",
+        action="store_true",
+        help="refresh an expired access token while checking status",
+    )
+
+    auth_sub.add_parser("logout", help="remove Tiny Horse's saved Google Drive credentials")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "status":
+            print(repository_state(args.path).to_json())
+        elif args.command == "init":
+            if args.drive:
+                print(init_drive_project(args.path, args.project))
+            else:
+                print(init_project(args.path, args.storage, args.project))
+        elif args.command == "push":
+            print(push(args.path, force=args.force).to_json())
+        elif args.command == "pull":
+            print(pull(args.storage, args.destination).to_json())
+        elif args.command == "doctor":
+            result = doctor(args.path)
+            print(result.to_json())
+            return 0 if result.ok else 1
+        elif args.command == "projects":
+            print(projects().to_json())
+        elif args.command == "clone":
+            print(clone_project(args.project, args.destination).to_json())
+        elif args.command == "bundle":
+            print(create_bundle(args.path, args.output))
+        elif args.command == "verify-bundle":
+            print(verify_bundle(args.bundle))
+        elif args.command == "migrate":
+            print(
+                migrate_remote(
+                    args.remote,
+                    args.destination,
+                    project=args.project,
+                    storage=args.storage,
+                ).to_json()
+            )
+        elif args.command == "auth":
+            if args.auth_command == "login":
+                print(
+                    login_google_drive(
+                        args.client_secrets,
+                        open_browser=not args.no_browser,
+                    ).to_json()
+                )
+            elif args.auth_command == "status":
+                status = google_drive_auth_status(refresh=args.refresh)
+                print(status.to_json())
+                return 0 if status.authenticated else 1
+            elif args.auth_command == "logout":
+                print(logout_google_drive().to_json())
+        return 0
+    except (AuthError, GitError, ConfigError, StorageError, WorkflowError) as exc:
+        print(f"tinyhorse: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tinyhorse/config.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import tomllib
+
+
+CONFIG_NAME = ".tinyhorse.toml"
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    project: str
+    storage: str
+
+    @property
+    def storage_scheme(self) -> str:
+        return self.storage.split(":", 1)[0]
+
+
+def config_path(repo: str | Path) -> Path:
+    return Path(repo).resolve() / CONFIG_NAME
+
+
+def load_config(repo: str | Path) -> ProjectConfig:
+    path = config_path(repo)
+    if not path.exists():
+        raise ConfigError(f"missing {CONFIG_NAME} in {Path(repo).resolve()}")
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+    section = data.get("tinyhorse")
+    if not isinstance(section, dict):
+        raise ConfigError(f"{CONFIG_NAME} is missing [tinyhorse]")
+    project = section.get("project")
+    storage = section.get("storage")
+    if not isinstance(project, str) or not project.strip():
+        raise ConfigError("tinyhorse.project must be a non-empty string")
+    if not isinstance(storage, str) or ":" not in storage:
+        raise ConfigError("tinyhorse.storage must be a storage locator")
+    return ProjectConfig(project=project.strip(), storage=storage.strip())
+
+
+def write_config(repo: str | Path, project: str, storage: str) -> Path:
+    path = config_path(repo)
+    project = project.strip()
+    storage = storage.strip()
+    if not project:
+        raise ConfigError("project name cannot be empty")
+    if ":" not in storage:
+        raise ConfigError("storage must be a locator such as file:/path/project.bundle")
+
+    def q(value: str) -> str:
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+    path.write_text(
+        "[tinyhorse]\n"
+        f"project = {q(project)}\n"
+        f"storage = {q(storage)}\n",
+        encoding="utf-8",
+    )
+    return path

tinyhorse/git.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def _run(args: Iterable[str], cwd: str | Path | None = None) -> str:
+    cmd = ["git", *args]
+    proc = subprocess.run(
+        cmd,
+        cwd=str(cwd) if cwd is not None else None,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if proc.returncode != 0:
+        raise GitError(proc.stderr.strip() or f"git exited with {proc.returncode}")
+    return proc.stdout.strip()
+
+
+@dataclass(frozen=True)
+class RepoState:
+    root: str
+    head: str
+    head_short: str
+    branch: str | None
+    commit_time: str
+    commit_message: str
+    dirty: bool
+    upstream: str | None
+    remotes: dict[str, str]
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2, sort_keys=True)
+
+
+def repository_state(path: str | Path = ".") -> RepoState:
+    root = _run(["-C", str(path), "rev-parse", "--show-toplevel"])
+    head = _run(["-C", root, "rev-parse", "HEAD"])
+    head_short = _run(["-C", root, "rev-parse", "--short=12", "HEAD"])
+
+    branch_proc = subprocess.run(
+        ["git", "-C", root, "symbolic-ref", "--short", "-q", "HEAD"],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    branch = branch_proc.stdout.strip() or None
+
+    commit_time = _run(["-C", root, "show", "-s", "--format=%cI", "HEAD"])
+    commit_message = _run(["-C", root, "show", "-s", "--format=%s", "HEAD"])
+    dirty = bool(_run(["-C", root, "status", "--porcelain=v1"]))
+
+    upstream_proc = subprocess.run(
+        ["git", "-C", root, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    upstream = upstream_proc.stdout.strip() or None
+
+    remotes: dict[str, str] = {}
+    remote_names = _run(["-C", root, "remote"]).splitlines()
+    for name in remote_names:
+        if name:
+            remotes[name] = _run(["-C", root, "remote", "get-url", name])
+
+    return RepoState(
+        root=root,
+        head=head,
+        head_short=head_short,
+        branch=branch,
+        commit_time=commit_time,
+        commit_message=commit_message,
+        dirty=dirty,
+        upstream=upstream,
+        remotes=remotes,
+    )
+
+
+def create_bundle(repo: str | Path, output: str | Path) -> Path:
+    """Create a complete project bundle without remote-tracking cache refs."""
+    repo = Path(repo)
+    output = Path(output).resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    refs = _run(
+        [
+            "-C", str(repo), "for-each-ref", "--format=%(refname)",
+            "refs/heads", "refs/tags", "refs/notes",
+        ]
+    ).splitlines()
+    revisions = ["HEAD", *[ref for ref in refs if ref]]
+    _run(["-C", str(repo), "bundle", "create", str(output), *revisions])
+    return output
+
+
+def verify_bundle(bundle: str | Path) -> str:
+    """Verify a bundle without requiring the caller to be inside a Git repo."""
+    bundle_path = Path(bundle).resolve()
+    with tempfile.TemporaryDirectory(prefix="tinyhorse-verify-") as td:
+        check_repo = Path(td) / "check.git"
+        _run(["init", "--bare", str(check_repo)])
+        return _run(["-C", str(check_repo), "bundle", "verify", str(bundle_path)])
+
+
+def mirror_clone(remote: str, destination: str | Path) -> Path:
+    """Low-level mirror clone used when an exact remote snapshot is needed.
+
+    A mirror clone preserves branches, tags, and other refs. Tiny Horse does not
+    delete or mutate the source remote; migration and cut-over are separate steps.
+    """
+    destination = Path(destination).resolve()
+    if destination.exists():
+        raise GitError(f"destination already exists: {destination}")
+    _run(["clone", "--mirror", remote, str(destination)])
+    return destination
+
+
+def bundle_heads(bundle: str | Path) -> dict[str, str]:
+    """Return ref -> object id from `git bundle list-heads`."""
+    output = _run(["bundle", "list-heads", str(bundle)])
+    heads: dict[str, str] = {}
+    for line in output.splitlines():
+        if not line.strip():
+            continue
+        oid, ref = line.split(maxsplit=1)
+        heads[ref] = oid
+    return heads
+
+
+def bundle_head(bundle: str | Path) -> str:
+    heads = bundle_heads(bundle)
+    if "HEAD" in heads:
+        return heads["HEAD"]
+    if "refs/heads/main" in heads:
+        return heads["refs/heads/main"]
+    branch_refs = sorted(ref for ref in heads if ref.startswith("refs/heads/"))
+    if len(branch_refs) == 1:
+        return heads[branch_refs[0]]
+    raise GitError("bundle does not identify a unique canonical HEAD")