micropython-branch-manager 1.0.0__py3-none-any.whl

micropython_branch_manager/__init__.py

@@ -0,0 +1,5 @@
+"""micropython-branch-manager - Tool for managing MicroPython fork integration branches."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

micropython_branch_manager/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m micropython_branch_manager."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

micropython_branch_manager/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

micropython_branch_manager/branch_sync.py

@@ -0,0 +1,85 @@
+"""Branch synchronization logic for micropython-branch-manager."""
+
+import re
+
+from .config import BranchConfig, MicroPythonConfig
+from .git import GitRepo
+from .github import PRInfo
+
+MERGE_PATTERN = re.compile(r"Merge branch '([^']+)'")
+
+
+def extract_branches_from_merges(git: GitRepo, target: str, integration: str) -> list[str]:
+    """Extract branch names from merge commits between target and integration.
+
+    Returns branches in merge order (oldest first).
+    """
+    subjects = git.get_log_subjects(f"{target}..{integration}")
+    branches = []
+    for subject in subjects:
+        match = MERGE_PATTERN.search(subject)
+        if match:
+            branch = match.group(1)
+            if branch not in branches:
+                branches.append(branch)
+    branches.reverse()  # Oldest first
+    return branches
+
+
+def sync_config_with_branches(
+    config: MicroPythonConfig,
+    detected_branches: list[str],
+    pr_cache: dict[str, PRInfo],
+) -> bool:
+    """Update config with detected branches.
+
+    Returns True if config was modified.
+    """
+    existing = {b.name: b for b in config.branches}
+    modified = False
+
+    for branch in detected_branches:
+        if branch not in existing:
+            entry = BranchConfig(name=branch, remote="origin")
+            if branch in pr_cache:
+                pr = pr_cache[branch]
+                entry.pr_url = pr.url
+                entry.pr_number = pr.number
+                entry.title = pr.title
+            config.branches.append(entry)
+            modified = True
+
+    # Reorder to match merge order
+    order = {name: i for i, name in enumerate(detected_branches)}
+    config.branches.sort(key=lambda b: order.get(b.name, 999))
+
+    return modified
+
+
+def validate_branches(config: MicroPythonConfig, detected_branches: list[str]) -> list[str]:
+    """Validate config branches against detected branches.
+
+    Returns list of warnings about discrepancies.
+    """
+    warnings = []
+    detected_set = set(detected_branches)
+    config_set = {b.name for b in config.branches}
+
+    # Branches in config but not in merge history
+    missing_from_history = config_set - detected_set
+    if missing_from_history:
+        warnings.append(
+            f"WARNING: The following branches are in the config but not found in merge history:\n"
+            f"  {', '.join(sorted(missing_from_history))}\n"
+            "This may indicate they were removed from the integration branch."
+        )
+
+    # Branches in merge history but not in config (will be added automatically)
+    missing_from_config = detected_set - config_set
+    if missing_from_config:
+        warnings.append(
+            f"INFO: The following branches will be added to config:\n"
+            f"  {', '.join(sorted(missing_from_config))}"
+        )
+
+    return warnings

micropython_branch_manager/cli.py

@@ -0,0 +1,189 @@
+"""CLI interface for micropython-branch-manager."""
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+from .branch_sync import extract_branches_from_merges, sync_config_with_branches
+from .config import CONFIG_FILENAME, MicroPythonConfig
+from .exceptions import GitHubCLINotFound, MBMError
+from .git import GitRepo
+from .github import GitHubClient
+from .pr import PRManager
+from .rebase import RebaseManager
+
+app = cyclopts.App(
+    name="mbm",
+    help="Manage MicroPython fork integration branches.",
+)
+
+# Common parameter types
+SubmodulePath = Annotated[
+    Path | None,
+    cyclopts.Parameter(
+        name="--submodule",
+        help="Path to MicroPython submodule (default: auto-detect)",
+    ),
+]
+
+
+def resolve_submodule(path: Path | None) -> Path:
+    """Resolve submodule path, auto-detecting if not specified."""
+    if path:
+        return path.resolve()
+    # Try common locations
+    for candidate in [Path("src/micropython"), Path("micropython"), Path(".")]:
+        config_path = candidate / CONFIG_FILENAME
+        if config_path.exists() or (candidate / ".git").exists():
+            return candidate.resolve()
+    raise ValueError("Could not auto-detect submodule path. Use --submodule.")
+
+
+@app.command
+def init(
+    submodule: SubmodulePath = None,
+    integration_branch: Annotated[
+        str | None,
+        cyclopts.Parameter(name=["--integration-branch", "-b"]),
+    ] = None,
+) -> None:
+    """Initialize configuration in submodule."""
+    path = resolve_submodule(submodule)
+    git = GitRepo(path)
+
+    # If integration branch not specified, detect current branch
+    if integration_branch is None:
+        integration_branch = git.run("branch", "--show-current")
+        if not integration_branch:
+            # Detached HEAD or other issue, fall back to main
+            integration_branch = "main"
+        print(f"Using current branch as integration branch: {integration_branch}")
+
+    # Detect existing git remotes
+    remotes = git.list_remotes()
+    if remotes:
+        print(f"\nDetected {len(remotes)} remote(s):")
+        for name, url in remotes.items():
+            print(f"  - {name}: {url}")
+    else:
+        print("\nNo remotes detected. You'll need to add them manually to the config.")
+
+    config = MicroPythonConfig(integration_branch=integration_branch, remotes=remotes)
+    config.save(path)
+    print(f"\nCreated {path / CONFIG_FILENAME}")
+
+
+@app.command
+def rebase(
+    target: str = "upstream/master",
+    submodule: SubmodulePath = None,
+    local: Annotated[bool, cyclopts.Parameter(name="--local")] = False,
+    dry_run: Annotated[bool, cyclopts.Parameter(name="--dry-run")] = False,
+    force_push: Annotated[bool, cyclopts.Parameter(name="--force-push")] = False,
+    resume: Annotated[bool, cyclopts.Parameter(name="--resume")] = False,
+) -> None:
+    """Rebase integration branch by rebuilding from fresh PRs."""
+    path = resolve_submodule(submodule)
+    manager = RebaseManager(path)
+    manager.execute(
+        target=target,
+        local_only=local,
+        dry_run=dry_run,
+        force_push=force_push,
+        resume=resume,
+    )
+
+
+@app.command
+def add_pr(
+    pr_identifier: str,
+    submodule: SubmodulePath = None,
+) -> None:
+    """Add PR to integration branch."""
+    path = resolve_submodule(submodule)
+    # Detect parent repo
+    parent_path = path.parent
+    parent: Path | None = parent_path if (parent_path / ".git").exists() else None
+
+    manager = PRManager(path, parent)
+    manager.add_pr(pr_identifier)
+
+
+@app.command
+def sync(
+    gh_author: Annotated[
+        str,
+        cyclopts.Parameter(
+            help="GitHub username to look up PR metadata for branches",
+        ),
+    ],
+    submodule: SubmodulePath = None,
+) -> None:
+    """Sync JSON config with current branch state.
+
+    Detects branches from merge commits and updates config with PR metadata.
+    """
+    path = resolve_submodule(submodule)
+    config = MicroPythonConfig.load(path, require_exists=True)
+    git = GitRepo(path)
+
+    # Setup remotes
+    for name, url in config.remotes.items():
+        git.ensure_remote(name, url)
+
+    # Detect branches
+    detected = extract_branches_from_merges(git, "upstream/master", config.integration_branch)
+
+    # Get PR cache from GitHub
+    pr_cache = {}
+    try:
+        github = GitHubClient()
+        pr_cache = github.get_pr_info_by_branches(gh_author)
+    except GitHubCLINotFound:
+        pass  # Continue without PR info
+
+    # Sync
+    if sync_config_with_branches(config, detected, pr_cache):
+        config.save(path)
+        print(f"Updated {path / CONFIG_FILENAME}")
+    else:
+        print("Config already in sync")
+
+
+@app.command
+def config(
+    submodule: SubmodulePath = None,
+) -> None:
+    """Show current configuration."""
+    path = resolve_submodule(submodule)
+    cfg = MicroPythonConfig.load(path, require_exists=True)
+
+    print(f"Integration branch: {cfg.integration_branch}")
+
+    # Show branches first
+    print(f"\nBranches ({len(cfg.branches)}):")
+    for b in cfg.branches:
+        title = b.title or "(no title)"
+        print(f"  {b.remote}/{b.name}: {title}")
+        if b.pr_url:
+            print(f"    - {b.pr_url}")
+        print()  # Blank line between entries
+
+    # Only show remotes that are referenced by branches
+    used_remotes = {b.remote for b in cfg.branches}
+    used_remotes.add("upstream")  # Always show upstream
+    remotes_to_show = {k: v for k, v in cfg.remotes.items() if k in used_remotes}
+    print(f"Remotes ({len(remotes_to_show)}):")
+    for name, url in remotes_to_show.items():
+        print(f"  {name}: {url}")
+
+
+def main() -> None:
+    """Entry point."""
+    try:
+        app()
+    except MBMError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)

micropython_branch_manager/config.py

@@ -0,0 +1,64 @@
+"""Configuration models for micropython-branch-manager."""
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .exceptions import ConfigError
+
+CONFIG_FILENAME = ".micropython-branches.json"
+CONFIG_HEADER = "_generated_by"
+CONFIG_HEADER_VALUE = "micropython-branch-manager (mbm) - do not edit manually"
+
+
+class BranchConfig(BaseModel):
+    """Configuration for a single feature branch."""
+
+    name: str
+    remote: str = "origin"
+    pr_url: str | None = None
+    pr_number: int | None = None
+    title: str | None = None
+
+
+class MicroPythonConfig(BaseModel):
+    """Root configuration model."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    integration_branch: str = "main"
+    remotes: dict[str, str] = Field(default_factory=dict)
+    branches: list[BranchConfig] = Field(default_factory=list)
+
+    @classmethod
+    def load(cls, submodule_path: Path, require_exists: bool = False) -> "MicroPythonConfig":
+        """Load from .micropython-branches.json in submodule root.
+
+        Args:
+            submodule_path: Path to the submodule directory.
+            require_exists: If True, raise ConfigError if config file doesn't exist.
+        """
+        config_path = submodule_path / CONFIG_FILENAME
+        if not config_path.exists():
+            if require_exists:
+                raise ConfigError(
+                    f"No config file found. Run 'mbm init' first to create {CONFIG_FILENAME}"
+                )
+            return cls()
+        return cls.model_validate_json(config_path.read_text())
+
+    def save(self, submodule_path: Path) -> None:
+        """Save to .micropython-branches.json in submodule root."""
+        config_path = submodule_path / CONFIG_FILENAME
+        # Build dict with header field first, then model fields
+        data = {CONFIG_HEADER: CONFIG_HEADER_VALUE, **self.model_dump()}
+        config_path.write_text(json.dumps(data, indent=2) + "\n")
+
+    def get_branch(self, name: str) -> BranchConfig | None:
+        """Get branch config by name."""
+        return next((b for b in self.branches if b.name == name), None)
+
+    def has_branch(self, name: str) -> bool:
+        """Check if branch exists in config."""
+        return any(b.name == name for b in self.branches)

micropython_branch_manager/exceptions.py

@@ -0,0 +1,59 @@
+"""Custom exceptions for micropython-branch-manager."""
+
+from typing import Any
+
+
+class MBMError(Exception):
+    """Base exception for micropython-branch-manager."""
+
+
+class ConfigError(MBMError):
+    """Configuration loading or validation error."""
+
+
+class GitError(MBMError):
+    """Git operation failed."""
+
+
+class GitHubError(MBMError):
+    """GitHub CLI operation failed."""
+
+
+class GitHubCLINotFound(GitHubError):
+    """gh CLI not installed or not in PATH."""
+
+
+class RebaseConflictError(GitError):
+    """Rebase stopped due to conflicts requiring manual resolution."""
+
+    def __init__(
+        self,
+        message: str,
+        conflicting_files: list[str] | None = None,
+        pr_context: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.conflicting_files = conflicting_files or []
+        self.pr_context = pr_context or {}
+
+
+class MergeConflictError(GitError):
+    """Merge stopped due to conflicts requiring manual resolution."""
+
+    def __init__(self, message: str, conflicting_files: list[str] | None = None):
+        super().__init__(message)
+        self.conflicting_files = conflicting_files or []
+
+
+class WorkingTreeDirtyError(GitError):
+    """Working tree has uncommitted changes."""
+
+
+class RemoteDivergenceError(GitError):
+    """Remote branch has diverged from local branch."""
+
+    def __init__(self, message: str, branch: str, remote_commits: int, local_commits: int):
+        super().__init__(message)
+        self.branch = branch
+        self.remote_commits = remote_commits
+        self.local_commits = local_commits

micropython_branch_manager/git.py

@@ -0,0 +1,246 @@
+"""Git operations wrapper for micropython-branch-manager."""
+
+import subprocess
+from pathlib import Path
+
+from .exceptions import (
+    GitError,
+    MergeConflictError,
+    RebaseConflictError,
+    RemoteDivergenceError,
+    WorkingTreeDirtyError,
+)
+
+
+class GitRepo:
+    """Wrapper for git operations in a specific directory."""
+
+    def __init__(self, repo_path: Path):
+        self.repo_path = repo_path
+
+    def run(self, *args: str, check: bool = True, capture: bool = True) -> str:
+        """Execute git command, return stdout."""
+        cmd = ["git", *args]
+        result = subprocess.run(
+            cmd,
+            cwd=self.repo_path,
+            capture_output=capture,
+            text=True,
+        )
+        if check and result.returncode != 0:
+            raise GitError(f"git {args[0]} failed: {result.stderr}")
+        return result.stdout.strip() if result.stdout else ""
+
+    def is_clean(self) -> bool:
+        """Check if working tree is clean."""
+        return self.run("status", "--porcelain") == ""
+
+    def require_clean(self) -> None:
+        """Raise if working tree has uncommitted changes."""
+        if not self.is_clean():
+            raise WorkingTreeDirtyError(
+                "Working tree has uncommitted changes. Please commit or stash changes first."
+            )
+
+    def fetch(self, remote: str = "--all") -> None:
+        """Fetch from remote(s)."""
+        # Sync submodule URLs first to avoid stale references
+        self.run("submodule", "sync", "--recursive", check=False)
+
+        # Fetch from remotes - allow submodule errors but catch main repo errors
+        cmd = ["git", "fetch", remote]
+        result = subprocess.run(
+            cmd,
+            cwd=self.repo_path,
+            capture_output=True,
+            text=True,
+        )
+        # Only raise error if the main fetch failed (not just submodule errors)
+        # Git fetch writes to stderr, check if there are non-submodule errors
+        if result.returncode != 0:
+            stderr = result.stderr.lower()
+            # Allow submodule fetch errors as they don't affect main repo fetch
+            if "submodule" not in stderr or (
+                "fatal" in stderr and "submodule" not in stderr.split("fatal")[0]
+            ):
+                raise GitError(f"git fetch failed: {result.stderr}")
+
+    def checkout(self, ref: str, create: bool = False, force: bool = False) -> None:
+        """Checkout branch or ref."""
+        args = ["checkout"]
+        if create:
+            args.append("-B" if force else "-b")
+        args.append(ref)
+        self.run(*args)
+
+    def rebase(self, onto: str, update_refs: bool = True) -> None:
+        """Rebase with merge commit preservation.
+
+        Raises:
+            RebaseConflictError: If conflicts require manual resolution
+        """
+        args = ["rebase", "--rebase-merges"]
+        if update_refs:
+            args.append("--update-refs")
+        args.append(onto)
+
+        try:
+            self.run(*args)
+        except GitError as e:
+            # Check if this is a conflict situation
+            status = self.run("status", "--porcelain", check=False)
+            if "UU " in status or "AA " in status or "DD " in status:
+                conflicting = [
+                    line[3:]
+                    for line in status.split("\n")
+                    if line.startswith(("UU ", "AA ", "DD "))
+                ]
+                raise RebaseConflictError(
+                    "Rebase stopped due to conflicts.\n"
+                    "Conflicting files:\n  " + "\n  ".join(conflicting) + "\n\n"
+                    "Please resolve conflicts manually, then run:\n"
+                    "  git rebase --continue\n\n"
+                    "Or to abort:\n"
+                    "  git rebase --abort",
+                    conflicting_files=conflicting,
+                ) from e
+            raise
+
+    def merge(self, branch: str, message: str, no_ff: bool = True) -> None:
+        """Merge branch with optional no-ff.
+
+        Raises:
+            MergeConflictError: If conflicts require manual resolution
+        """
+        args = ["merge"]
+        if no_ff:
+            args.append("--no-ff")
+        args.extend([branch, "-m", message])
+
+        try:
+            self.run(*args)
+        except GitError as e:
+            status = self.run("status", "--porcelain", check=False)
+            if "UU " in status or "AA " in status or "DD " in status:
+                conflicting = [
+                    line[3:]
+                    for line in status.split("\n")
+                    if line.startswith(("UU ", "AA ", "DD "))
+                ]
+                raise MergeConflictError(
+                    "Merge stopped due to conflicts.\n"
+                    "Conflicting files:\n  " + "\n  ".join(conflicting) + "\n\n"
+                    "Please resolve conflicts manually, then run:\n"
+                    "  git merge --continue\n\n"
+                    "Or to abort:\n"
+                    "  git merge --abort",
+                    conflicting_files=conflicting,
+                ) from e
+            raise
+
+    def push(self, remote: str, branch: str, force: bool = False) -> None:
+        """Push branch to remote."""
+        args = ["push"]
+        if force:
+            args.append("--force")
+        args.extend([remote, branch])
+        self.run(*args)
+
+    def get_merge_base(self, ref1: str, ref2: str) -> str:
+        """Get merge base commit."""
+        return self.run("merge-base", ref1, ref2)
+
+    def rev_parse(self, ref: str) -> str:
+        """Resolve ref to commit hash."""
+        return self.run("rev-parse", ref)
+
+    def branch_exists(self, branch: str, remote: bool = False) -> bool:
+        """Check if branch exists."""
+        ref = f"refs/remotes/{branch}" if remote else f"refs/heads/{branch}"
+        try:
+            self.run("rev-parse", "--verify", ref)
+            return True
+        except GitError:
+            return False
+
+    def create_branch(self, name: str, start_point: str) -> None:
+        """Create branch from start point."""
+        self.run("branch", name, start_point)
+
+    def set_branch_upstream(self, branch: str, upstream: str) -> None:
+        """Set upstream tracking for a branch."""
+        self.run("branch", f"--set-upstream-to={upstream}", branch)
+
+    def ensure_remote(self, name: str, url: str) -> None:
+        """Ensure remote exists with correct URL."""
+        try:
+            current = self.run("config", f"remote.{name}.url")
+            if current != url:
+                self.run("remote", "set-url", name, url)
+        except GitError:
+            self.run("remote", "add", name, url)
+
+    def list_remotes(self) -> dict[str, str]:
+        """List all remotes with URLs."""
+        output = self.run("remote", "-v")
+        remotes = {}
+        for line in output.split("\n"):
+            if line and "(fetch)" in line:
+                parts = line.split()
+                if len(parts) >= 2:
+                    remotes[parts[0]] = parts[1]
+        return remotes
+
+    def get_log_subjects(self, range_spec: str) -> list[str]:
+        """Get commit subjects in range."""
+        output = self.run("log", "--format=%s", range_spec)
+        return [line for line in output.split("\n") if line]
+
+    def check_divergence(
+        self, local_branch: str, remote_branch: str, force_push: bool = False
+    ) -> None:
+        """Check if remote branch has diverged from local branch.
+
+        Args:
+            local_branch: Local branch name
+            remote_branch: Remote branch ref (e.g., 'origin/branch-name')
+            force_push: If True, skip the divergence check
+
+        Raises:
+            RemoteDivergenceError: If remote has commits not in local branch
+        """
+        if force_push:
+            return
+
+        try:
+            # Check if remote branch exists
+            self.run("rev-parse", "--verify", remote_branch)
+        except GitError:
+            # Remote branch doesn't exist, no divergence
+            return
+
+        # Count commits in remote not in local
+        try:
+            remote_only = self.run("rev-list", "--count", f"{local_branch}..{remote_branch}")
+            local_only = self.run("rev-list", "--count", f"{remote_branch}..{local_branch}")
+
+            remote_count = int(remote_only) if remote_only else 0
+            local_count = int(local_only) if local_only else 0
+
+            if remote_count > 0:
+                raise RemoteDivergenceError(
+                    f"Remote branch '{remote_branch}' has {remote_count} commit(s) "
+                    f"not in local branch '{local_branch}'.\n"
+                    f"Local branch has {local_count} commit(s) not in remote.\n\n"
+                    "This may indicate that the remote has been updated since your last fetch.\n"
+                    "Options:\n"
+                    "  1. Fetch and review remote changes first\n"
+                    "  2. Use --force-push to overwrite remote (USE WITH CAUTION)\n"
+                    "  3. Abort and investigate the divergence",
+                    branch=local_branch,
+                    remote_commits=remote_count,
+                    local_commits=local_count,
+                )
+        except ValueError:
+            # Error parsing commit counts, skip check
+            pass