treefort 0.5.0__py3-none-any.whl

treefort/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("treefort")
+except PackageNotFoundError:
+    # Package is not installed
+    __version__ = "unknown"

treefort/__main__.py

@@ -0,0 +1,4 @@
+from treefort.cli import main
+
+if __name__ == "__main__":
+    main()

treefort/cli.py

@@ -0,0 +1,67 @@
+import sys
+
+import fire
+
+from treefort.main import WorktreeCommands
+
+
+def replace_alias(cli: WorktreeCommands):
+    """
+    Replaces an alias with its corresponding full subcommand name in the system
+    arguments if the provided subcommand is an alias.
+
+    This function inspects the command-line arguments and, if an alias is found
+    as the first subcommand, replaces it with the full subcommand name as defined
+    in the alias map of the provided `WorktreeCommands` instance.
+
+    :param cli: An instance of WorktreeCommands containing the alias map used to
+                resolve aliases to their corresponding full subcommand names.
+    """
+    subcommand = sys.argv[1] if len(sys.argv) > 1 else None
+    if subcommand is not None and subcommand in cli._alias_map.keys():
+        sys.argv[1] = cli._alias_map[subcommand]
+
+
+def replace_verbose():
+    """
+    Parses command-line arguments to determine if the verbose mode is enabled.
+
+    This function searches arguments before the passthrough separator (`--`) for
+    verbose flags (`-v` and `--verbose`). Matching flags are removed from
+    `sys.argv`, and verbose mode is considered enabled.
+
+    :return: A boolean indicating whether verbose mode is enabled.
+    """
+    is_verbose = False
+
+    passthrough_index = sys.argv.index("--") if "--" in sys.argv else len(sys.argv)
+    kept_args = [sys.argv[0]]
+
+    for arg in sys.argv[1:passthrough_index]:
+        if arg in ("-v", "--verbose"):
+            is_verbose = True
+            continue
+        kept_args.append(arg)
+
+    if passthrough_index < len(sys.argv):
+        kept_args.extend(sys.argv[passthrough_index:])
+
+    sys.argv[:] = kept_args
+    return is_verbose
+
+
+def main():
+    """CLI tool for managing Git worktrees"""
+    is_verbose = replace_verbose()
+    component = WorktreeCommands(verbose=is_verbose)
+    replace_alias(component)
+
+    try:
+        # we do not pass `name` here, because the CLI allows using an alias for the command. if name
+        # was passed, then using `worktree -- --completion` would use the wrong name for completion
+        fire.Fire(component=component)
+    except Exception as e:
+        if is_verbose:
+            raise
+        component._logger.error(f"Command failed: {str(e)}")
+        sys.exit(1)

treefort/command.py

@@ -0,0 +1,26 @@
+from treefort.context import Context
+from treefort.runtime import Runtime
+
+
+class BaseCommand:
+    def __init__(self):
+        pass
+
+
+class Command(BaseCommand):
+    _name: str
+    _aliases: list[str] = []
+
+    def __init__(self, runtime: Runtime):
+        super().__init__()
+        self._runtime = runtime
+
+    @property
+    def _context(self) -> Context:
+        """Convenience access to the context"""
+        return self._runtime.context
+
+    @property
+    def _logger(self):
+        """Convenience access to the logger"""
+        return self._runtime.logger

treefort/commands/checkout.py

@@ -0,0 +1,148 @@
+import re
+from functools import cached_property
+
+from treefort.command import Command
+from treefort.errors import BranchInputError, CommandError, RemoteNotFoundError, RemoteUsageError
+from treefort.hooks import Hook
+from treefort.runtime import Runtime
+from treefort.utils import normalize_worktree_name
+
+URL_RE = re.compile(r"^https://github\.com/[a-z0-9-]+/[\w.-]+/pull/\d+$", re.IGNORECASE)
+BRANCH_RE = re.compile(r"^[\w.-/]+$", re.IGNORECASE)
+
+
+class CheckoutInput:
+    """Checkout command input abstraction"""
+
+    def __init__(self, runtime: Runtime, branch_or_pr: str, remote_name: str | None = None):
+        self.runtime = runtime
+        self.branch_or_pr = branch_or_pr
+        self.remote_name = remote_name
+
+    def validate(self):
+        if (
+            not self.branch_or_pr.isdigit()
+            and not URL_RE.match(self.branch_or_pr)
+            and not BRANCH_RE.match(self.branch_or_pr)
+        ):
+            raise BranchInputError(
+                "Couldn't parse input. Must be branch name, PR number or PR URL."
+            )
+
+        if self.remote_name is not None and (
+            self.branch_or_pr.isdigit() or URL_RE.match(self.branch_or_pr)
+        ):
+            raise RemoteUsageError("Remote name isn't allowed with PR number or PR URL.")
+
+    @cached_property
+    def owner(self) -> str:
+        """The Github owner of the repository"""
+        config = self.runtime.context.get_config()
+        if (
+            self.branch_or_pr.isdigit()
+            or self.branch_or_pr.startswith(config.url)
+            or not self.remote_name
+        ):
+            return config.owner
+        elif URL_RE.match(self.branch_or_pr):
+            return self.branch_or_pr.replace("https://github.com/", "").split("/", 1)[0]
+
+        remote = self.runtime.get_remote(name=self.remote_name)
+        if not remote:
+            raise RemoteNotFoundError("Couldn't find matching remote for --remote input")
+
+        return remote.uri.replace("https://github.com/", "").split("/", 1)[0]
+
+    @cached_property
+    def remote(self) -> str:
+        """The local name of the remote to use"""
+        if self.remote_name:
+            return self.remote_name
+        remote = self.runtime.get_remote(owner_name=self.owner)
+        if not remote:
+            raise RemoteNotFoundError("Couldn't find matching remote for PR")
+        return remote.name
+
+    @cached_property
+    def pr_number(self) -> str | None:
+        """The PR number, if applicable"""
+        if self.branch_or_pr.isdigit():
+            return self.branch_or_pr
+
+        if URL_RE.match(self.branch_or_pr):
+            _, pr_number = self.branch_or_pr.rsplit("/", 1)
+            return pr_number
+
+        return None
+
+    @cached_property
+    def worktree_name(self) -> str:
+        """The name of the worktree to create"""
+        if self.pr_number:
+            config = self.runtime.context.get_config()
+            pr_status = self.runtime.gh.pr_status(
+                self.pr_number, owner_repo=f"{self.owner}/{config.name}"
+            )
+            return pr_status["headRefName"]
+
+        return self.branch_or_pr
+
+
+class CheckoutCommand(Command):
+    _name = "checkout"
+
+    def __call__(self, branch_or_pr: str, remote: str | None = None, yes: bool = False):
+        """
+        Checkout an existing branch or PR as a worktree.
+
+        This accepts a PR number which will be looked up on the GitHub repository the project was
+        initialized with. It will also accept a GitHub PR URL. Lastly, it will accept a branch
+        name, if the branch is already tracked in your local repository. You may specify a remote
+        to fetch the latest version of the branch with `--remote`, and that flag only works when
+        passing a branch name.
+
+        Examples:
+            treefort checkout 1234
+            treefort checkout https://github.com/octo/repo/pull/1234
+            treefort checkout my-local-branch
+            treefort checkout a-branch --remote upstream
+
+        :param branch_or_pr: The branch, PR number, or PR URL to create as a worktree
+        :param remote: If `branch_or_pr` is a branch, this may be set to choose the remote to use
+        :param yes: Perform any action automatically without asking (execute new or modified hooks)
+        :type yes: bool
+        """
+        self._context.assert_within_project()
+
+        inpt = CheckoutInput(self._runtime, str(branch_or_pr), remote_name=remote)
+        inpt.validate()
+
+        if inpt.pr_number:
+            self._runtime.git.fetch(inpt.remote, f"pull/{inpt.pr_number}/head:{inpt.worktree_name}")
+        else:
+            # TODO: is this good to detect if it's local only?
+            try:
+                self._runtime.git.fetch(inpt.remote, f"{inpt.worktree_name}:{inpt.worktree_name}")
+            except (CommandError, OSError):
+                self._logger.warning("Ignoring git fetch error, attempting to open worktree")
+                pass
+
+        normalized_name = normalize_worktree_name(inpt.worktree_name)
+
+        with self._context.use(self._context.project_dir):
+            self._runtime.hooks.fire(
+                Hook.pre_checkout,
+                inpt.worktree_name,
+                f"{inpt.remote}/{inpt.worktree_name}",
+                normalized_name,
+                bypass_allowlist=yes,
+            )
+            self._runtime.git.open_worktree(inpt.worktree_name)
+            self._runtime.templates.copy(inpt.worktree_name)
+            self._runtime.hooks.fire(
+                Hook.post_checkout,
+                inpt.worktree_name,
+                f"{inpt.remote}/{inpt.worktree_name}",
+                normalized_name,
+                bypass_allowlist=yes,
+            )

treefort/commands/create.py

@@ -0,0 +1,64 @@
+from treefort.command import Command
+from treefort.hooks import Hook
+from treefort.utils import normalize_worktree_name
+
+
+class CreateCommand(Command):
+    _name = "create"
+
+    def __call__(self, worktree_name: str, *base_ref: str | None, yes: bool = False):
+        """
+        Create a new worktree in the current project.
+
+        This will add a new directory to your project directory with the name provided to
+        `worktree_name`. By default, the worktree branch will be based off the default GitHub
+        repository branch. To base it off another branch, you may use specify it as the second
+        argument. If the branch you want to base off contains a slash (`branch/name`), you must also
+        specify prefix it with the remote name and a slash, e.g. `remote/branch/name`.
+
+        Examples:
+            treefort create testing-create
+            treefort create testing-create main
+            treefort create testing-create upstream/main
+            treefort create testing-create upstream/some/other/branch
+
+        :param worktree_name: The name of the worktree
+        :param base_ref: The base reference to create the worktree from
+        :param yes: Perform any action automatically without asking (execute new or modified hooks)
+        :type yes: bool
+        """
+        base_ref = base_ref[0] if base_ref else None
+        self._context.assert_within_project()
+        git_remote_name = None
+
+        if base_ref is None:
+            project_config = self._context.get_config()
+            base_ref = project_config.default_branch
+        elif "/" in base_ref:
+            git_remote_name, base_ref = base_ref.split("/", 1)
+
+        if git_remote_name is None:
+            git_remote = self._runtime.get_default_remote()
+            git_remote_name = git_remote.name
+
+        self._runtime.git.fetch(git_remote_name)
+
+        normalized_name = normalize_worktree_name(worktree_name)
+
+        with self._context.use(self._context.project_dir):
+            self._runtime.hooks.fire(
+                Hook.pre_create,
+                worktree_name,
+                f"{git_remote_name}/{base_ref}",
+                normalized_name,
+                bypass_allowlist=yes,
+            )
+            self._runtime.git.add_worktree(worktree_name, f"{git_remote_name}/{base_ref}")
+            self._runtime.templates.copy(worktree_name)
+            self._runtime.hooks.fire(
+                Hook.post_create,
+                worktree_name,
+                f"{git_remote_name}/{base_ref}",
+                normalized_name,
+                bypass_allowlist=yes,
+            )

treefort/commands/init.py

@@ -0,0 +1,162 @@
+import re
+from urllib import parse
+
+from treefort.command import Command
+from treefort.config import RepositoryConfig, TomlConfigIO
+from treefort.errors import ProjectExistsError, RepositoryPathError
+from treefort.hooks import Hook, HookExists
+from treefort.templates import TemplateExists
+
+JUST_PATH_RE = re.compile(r"^[\w\-_]+/[\w\-_]+$")
+GIT_EXT_RE = re.compile(r"\.git$")
+
+
+def normalize(repo: str):
+    if not repo.startswith("http") and not repo.startswith("git@"):
+        if not JUST_PATH_RE.match(repo):
+            raise RepositoryPathError("Invalid repository path format. Expected: {owner}/{repo}")
+        repo = f"https://github.com/{repo}"
+
+    if not repo.endswith(".git"):
+        repo += ".git"
+
+    return repo
+
+
+class RepositoryTarget:
+    def __init__(self, repo: str, destination_dir: str | None = None):
+        self.uri = normalize(repo)
+        self._destination_dir = destination_dir
+
+    def validate(self):
+        path_parts = self.path.split("/")
+        if len(path_parts) != 2:
+            raise RepositoryPathError(f"Invalid repository path: {self.path}")
+
+    @property
+    def path(self):
+        if self.uri.startswith("http"):
+            return parse.urlparse(self.uri).path.lstrip("/")
+        # must be ssh
+        _, path = self.uri.split(":")
+        return path.lstrip("/")
+
+    @property
+    def owner(self):
+        return self.path.split("/")[0]
+
+    @property
+    def name(self):
+        return re.sub(GIT_EXT_RE, "", self.path.split("/")[1])
+
+    @property
+    def destination_dir(self):
+        if self._destination_dir is None:
+            return self.name
+        return self._destination_dir
+
+
+class InitCommand(Command):
+    """Initialize a project for use with treefort"""
+
+    _name = "init"
+
+    def __call__(self, repo: str, *destination_dir: str | None, yes: bool = False):
+        """
+        Initialize a project for using treefort with it, by cloning the project and configuring
+        it to be a bare git repo.
+
+        This command creates a suitable structure for worktree directories within the project
+        directory. It accepts various input formats, but it must be a GitHub repository, since this
+        uses `gh` to gather additional information about the project.
+
+        Examples:
+            treefort init https://github.com/bjester/treefort.git
+            treefort init ssh@github.com:bjester/treefort.git
+            treefort init bjester/treefort
+            treefort init bjester/treefort treefort-second
+
+        :param repo: The URI, or Github 'owner/repo', to clone
+        :type repo: str
+        :param destination_dir: The destination directory to clone the project into.
+        :type destination_dir: str
+        :param yes: Perform any action automatically without asking (execute new or modified hooks)
+        :type yes: bool
+        """
+        destination_dir = destination_dir[0] if destination_dir else None
+        repo_target = RepositoryTarget(repo, destination_dir=destination_dir)
+        repo_target.validate()
+
+        project_dir = self._context.cwd / repo_target.destination_dir
+
+        if project_dir.exists():
+            # this would be problematic!
+            raise ProjectExistsError(f"Project directory {project_dir} already exists")
+
+        project_dir.mkdir(parents=True, exist_ok=True)
+
+        with self._context.use(project_dir):
+            self._runtime.hooks.fire(
+                Hook.pre_init,
+                repo_target.uri,
+                project_dir,
+                skip_project=True,
+                bypass_allowlist=yes,
+            )
+            self._runtime.git.clone(repo_target.uri, ".bare")
+
+            with (project_dir / ".git").open("w", encoding="utf-8") as f:
+                f.write("gitdir: ./.bare")
+
+            self._context.reset_properties()
+            self._runtime.git.config("remote.origin.fetch", "+refs/heads/*:refs/remotes/origin/*")
+            self._runtime.git.fetch()
+            repo_data = self._runtime.gh.repo_status()
+            config = RepositoryConfig(TomlConfigIO.from_path(self._context.config_dir, "config"))
+            config.update(
+                default_branch=repo_data["defaultBranchRef"]["name"],
+                owner=repo_data["owner"]["login"],
+                name=repo_data["name"],
+                url=repo_data["url"],
+                is_private=repo_data["isPrivate"],
+            )
+
+            self._context.set_config(config)
+
+            self._add_templates(config)
+            self._add_hooks(config)
+
+            self._runtime.hooks.fire(
+                Hook.post_init,
+                repo_target.uri,
+                project_dir,
+                bypass_allowlist=yes,
+            )
+
+    def _add_hooks(self, config):
+        """Checks whether the repo has hooks in the default branch and copies them"""
+        for hook in Hook:
+            # check to see if repo has a hook
+            if not any(self._runtime.git.ls_tree(config.default_branch, hook.git_path)):
+                continue
+
+            # copy it
+            try:
+                with self._runtime.hooks.add(hook) as f:
+                    for line in self._runtime.git.cat_file(config.default_branch, hook.git_path):
+                        f.write(f"{line}\n")
+            except HookExists as e:
+                self._logger.warning(f"Skipping due to error: {str(e)}")
+
+    def _add_templates(self, config):
+        """Checks whether the repo has templates in the default branch and copies them"""
+        # check to see if repo has templates
+        for template_ls in self._runtime.git.ls_tree(config.default_branch, ".treefort/templates"):
+            template_file = template_ls.split("\t")[1].strip('"')
+            # copy it
+            try:
+                with self._runtime.templates.add(template_file) as f:
+                    for line in self._runtime.git.cat_file(config.default_branch, template_file):
+                        f.write(f"{line}\n")
+            except TemplateExists as e:
+                self._logger.warning(f"Skipping due to error: {str(e)}")

treefort/commands/install.py

@@ -0,0 +1,122 @@
+import os
+import shutil
+import stat
+import sys
+from pathlib import Path
+
+from treefort.command import Command
+
+
+class InstallCommand(Command):
+    _name = "install"
+
+    def __call__(
+        self,
+        alias: str | None = None,
+        gh_ext: bool = False,
+        path_bin: bool = False,
+        force: bool = False,
+    ):
+        """Installs treefort as a GitHub CLI extension or to the user's PATH.
+
+        Without specifying options, the install command will ask you what to do.
+
+        :param alias: An alternate name for the extension or path command.
+        :param gh_ext: Install as a GitHub CLI extension.
+        :param path_bin: Install to the user's PATH.
+        :param force: Overwrite existing files.
+        """
+        target_name = alias or "treefort"
+        gh_ext, path_bin = self._ask(target_name, gh_ext, path_bin)
+
+        current_script_path = Path(sys.argv[0]).resolve()
+        should_link = False
+
+        # unless the script is a self-contained executable, link it instead of copy
+        if current_script_path.suffix == ".py":
+            should_link = True
+        elif not current_script_path.suffix and str(current_script_path).endswith(
+            ".venv/bin/treefort"
+        ):
+            should_link = True
+
+        target_paths = []
+
+        if gh_ext:
+            # gh cli expects that it has `gh-` prefix
+            ext_name = target_name
+            if not ext_name.startswith("gh-"):
+                ext_name = f"gh-{target_name}"
+            target_paths.append(
+                Path("~/").expanduser()
+                / ".local"
+                / "share"
+                / "gh"
+                / "extensions"
+                / ext_name
+                / ext_name
+            )
+
+        if path_bin:
+            path_dirs = os.getenv("PATH", "").split(os.pathsep)
+            # Common user bin directories
+            preferred_install_dirs = [
+                Path.home() / ".local" / "bin",
+                Path.home() / "bin",
+            ]
+
+            install_dir = next((d for d in preferred_install_dirs if str(d) in path_dirs), None)
+
+            if not install_dir:
+                self._logger.error("Could not find a suitable user binary directory in your PATH.")
+                sys.exit(1)
+
+            target_paths.append(install_dir / target_name)
+
+        self._run(current_script_path, target_paths, should_link, force)
+
+    def _run(
+        self,
+        current_script_path: Path,
+        target_paths: list[Path],
+        should_link: bool,
+        force: bool,
+    ):
+        for target_path in target_paths:
+            if target_path.exists() or target_path.is_symlink():
+                if not force:
+                    self._logger.warning(
+                        f"Path already exists, use --force to overwrite: {target_path}"
+                    )
+                    sys.exit(1)
+                target_path.unlink(True)
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if should_link:
+                target_path.symlink_to(current_script_path)
+            else:
+                shutil.copy(current_script_path, target_path)
+                target_path.chmod(target_path.stat().st_mode | stat.S_IEXEC)
+            self._logger.info(f"Installed to {target_path}")
+
+    def _ask(self, target_name: str, gh_ext: bool, path_bin: bool) -> tuple[bool, bool]:
+        # ask user what path they would like to use for installation, without these args
+        if not gh_ext and not path_bin:
+            self._logger.info("Tip: Re-run this with --alias to change the name\n")
+            self._logger.info("Which method do you want to use?")
+            self._logger.info(
+                f"\t1. As a GitHub CLI (gh) extension: gh {target_name.replace('gh-', '')}"
+            )
+            self._logger.info(f"\t2. In your PATH: {target_name}\n")
+
+            choice = input("Your choice (1, 2): ")
+            if choice not in ("1", "2"):
+                self._logger.error("Invalid choice")
+                sys.exit(1)
+
+            if choice == "1":
+                gh_ext = True
+            elif choice == "2":
+                path_bin = True
+        return gh_ext, path_bin