warmtree 0.1.0__py3-none-any.whl

warmtree/__init__.py

@@ -0,0 +1,3 @@
+"""warmtree: a pool of pre-warmed git worktrees."""
+
+__version__ = "0.1.0"

warmtree/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m warmtree`, which the background refill uses."""
+
+from warmtree.cli import main
+
+raise SystemExit(main())

warmtree/cli.py

@@ -0,0 +1,344 @@
+"""Command line entry point. One function per command.
+
+`take` prints only the slot path on stdout so `cd "$(warmtree take x)"` works.
+Everything a human reads goes to stderr.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+
+from warmtree import __version__, config, git, skill
+from warmtree.config import CONFIG_NAME, ConfigError
+from warmtree.git import GitError
+from warmtree.pool import Pool, PoolError, Slot
+from warmtree.warm import WarmError
+
+# Lockfiles `init` looks for to pre-fill `lockfiles`. It never guesses `run`.
+KNOWN_LOCKFILES = (
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "bun.lock",
+    "uv.lock",
+    "poetry.lock",
+    "Pipfile.lock",
+    "requirements.txt",
+    "Cargo.lock",
+    "go.sum",
+    "packages.lock.json",
+    "Gemfile.lock",
+    "composer.lock",
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (GitError, ConfigError, PoolError, WarmError) as exc:
+        fail(str(exc))
+        return 1
+
+
+def fail(message: str) -> None:
+    print(f"warmtree: {message}", file=sys.stderr)
+
+
+def note(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="warmtree", description="A pool of pre-warmed git worktrees."
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help=f"write a starter {CONFIG_NAME}")
+    init.add_argument("--force", action="store_true", help="overwrite an existing file")
+    init.add_argument(
+        "--no-skill", action="store_true", help="do not install the agent skill"
+    )
+    init.set_defaults(func=cmd_init)
+
+    skill_cmd = commands.add_parser(
+        "skill", help="install the agent skill where this repo's coding agents look"
+    )
+    skill_cmd.add_argument(
+        "--tool",
+        action="append",
+        choices=skill.TOOL_KEYS,
+        help="install for this tool even if it was not detected; repeatable",
+    )
+    skill_cmd.add_argument(
+        "--force", action="store_true", help="overwrite a copy that was edited"
+    )
+    skill_cmd.set_defaults(func=cmd_skill)
+
+    fill = commands.add_parser("fill", help="create any missing slots")
+    fill.set_defaults(func=cmd_fill)
+
+    take = commands.add_parser("take", help="claim a ready slot for a branch")
+    take.add_argument("branch", help="branch to create or check out in the slot")
+    take.add_argument("--from", dest="from_ref", metavar="REF", help="start point")
+    refill = take.add_mutually_exclusive_group()
+    refill.add_argument("--no-refill", action="store_true", help="do not refill")
+    refill.add_argument(
+        "--refill-background",
+        action="store_true",
+        help="refill in a detached process and return at once",
+    )
+    take.set_defaults(func=cmd_take)
+
+    release = commands.add_parser("release", help="return a slot to the pool")
+    release.add_argument("branch", help="branch currently checked out in the slot")
+    release.add_argument("--keep-branch", action="store_true", help="keep the ref")
+    release.add_argument("--force", action="store_true", help="discard changes")
+    release.set_defaults(func=cmd_release)
+
+    remove = commands.add_parser("remove", help="delete slots")
+    remove.add_argument("names", nargs="*", metavar="SLOT", help="slots to delete")
+    remove.add_argument("--all", action="store_true", help="delete every slot")
+    remove.add_argument("--force", action="store_true", help="delete taken slots too")
+    remove.set_defaults(func=cmd_remove)
+
+    refresh = commands.add_parser(
+        "refresh", help="move waiting slots to base and re-warm if lockfiles changed"
+    )
+    refresh.set_defaults(func=cmd_refresh)
+
+    size = commands.add_parser("size", help="show or change how many slots to keep")
+    size.add_argument(
+        "size", nargs="?", type=int, help="new size; grows or shrinks the pool to match"
+    )
+    size.set_defaults(func=cmd_size)
+
+    which = commands.add_parser(
+        "which", help="name the slot the current directory is in"
+    )
+    which.set_defaults(func=cmd_which)
+
+    status = commands.add_parser("status", help="show every slot")
+    status.add_argument("--json", action="store_true", help="print JSON for agents")
+    status.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = git.repo_root(Path.cwd())
+    target = root / CONFIG_NAME
+    if target.exists() and not args.force:
+        fail(f"{target} already exists (use --force)")
+        return 1
+    lockfiles = [name for name in KNOWN_LOCKFILES if (root / name).exists()]
+    target.write_text(config.starter_toml(lockfiles), encoding="utf-8")
+    print(f"wrote {target}")
+    if lockfiles:
+        print(f"lockfiles: {', '.join(lockfiles)}")
+    print("edit [warm] run to add your install command; warmtree never guesses it")
+    if not args.no_skill:
+        targets = skill.detect(root)
+        if targets:
+            _report_skill(root, skill.install(root, targets))
+        else:
+            print(
+                "no agent config detected; install the skill later with "
+                f"`warmtree skill --tool {'|'.join(skill.TOOL_KEYS)}`"
+            )
+    return 0
+
+
+def cmd_skill(args: argparse.Namespace) -> int:
+    root = git.repo_root(Path.cwd())
+    if args.tool:
+        targets = [skill.by_tool(key) for key in args.tool]
+    else:
+        targets = skill.detect(root)
+    if not targets:
+        fail(
+            "no agent config detected (CLAUDE.md, AGENTS.md, .cursor, "
+            "copilot-instructions.md); "
+            f"pick one with --tool {'|'.join(skill.TOOL_KEYS)}"
+        )
+        return 1
+    results = skill.install(root, targets, force=args.force)
+    _report_skill(root, results)
+    return 0
+
+
+def _report_skill(root: Path, results: list[skill.Installed]) -> None:
+    for result in results:
+        where = result.path.relative_to(root).as_posix()
+        print(f"{result.action}: {result.target.tool} skill at {where}")
+    if any(result.action == "kept" for result in results):
+        note("a copy you edited was kept; use `warmtree skill --force` to replace it")
+
+
+def cmd_fill(args: argparse.Namespace) -> int:
+    pool = _pool()
+    created = pool.fill()
+    for slot in created:
+        print(f"created {slot.name} at {slot.path}")
+    if not created:
+        ready = sum(1 for slot in pool.status() if slot.state == "ready")
+        print(f"pool is full ({ready} ready)")
+    return 0
+
+
+def cmd_take(args: argparse.Namespace) -> int:
+    pool = _pool()
+    slot, cold = pool.take(args.branch, from_ref=args.from_ref)
+    if cold:
+        note(f"no ready slot; created {slot.name} cold for {args.branch}")
+    else:
+        note(f"took {slot.name} for {args.branch}")
+    print(slot.path)
+
+    if args.refill_background:
+        _spawn_background_fill(pool.repo_root)
+        note("refilling in the background")
+    elif not args.no_refill:
+        for created in pool.fill():
+            note(f"refilled {created.name}")
+    return 0
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    slot, branch_deleted = _pool().release(
+        args.branch, keep_branch=args.keep_branch, force=args.force
+    )
+    print(f"released {slot.name}")
+    if branch_deleted:
+        print(f"deleted branch {args.branch}")
+    elif not args.keep_branch:
+        note(f"kept branch {args.branch}: it has commits that are not merged")
+    return 0
+
+
+def cmd_remove(args: argparse.Namespace) -> int:
+    if not args.names and not args.all:
+        fail("name a slot or pass --all")
+        return 1
+    removed = _pool().remove(names=args.names, all_slots=args.all, force=args.force)
+    for slot in removed:
+        print(f"removed {slot.name}")
+    return 0
+
+
+def cmd_refresh(args: argparse.Namespace) -> int:
+    results = _pool().refresh()
+    if not results:
+        print("nothing to refresh")
+        return 0
+    for result in results:
+        base = "moved to base" if result.moved else "at base"
+        warmth = "re-warmed" if result.rewarmed else "still warm"
+        print(f"{result.slot.name}: {base}, {warmth}")
+    return 0
+
+
+def cmd_size(args: argparse.Namespace) -> int:
+    root = git.repo_root(Path.cwd())
+    if args.size is not None:
+        config.write_size(root, args.size)
+        pool = Pool(root, config.load(root), log=note)
+        for slot in pool.trim():
+            print(f"removed {slot.name}")
+        for slot in pool.fill():
+            print(f"created {slot.name} at {slot.path}")
+    cfg = config.load(root)
+    counts = Counter(slot.state for slot in Pool(root, cfg).status())
+    print(f"size: {cfg.size}")
+    print(
+        f"ready {counts['ready']}, taken {counts['taken']}, "
+        f"warming {counts['warming']}, stale {counts['stale']}; "
+        f"{counts.total()} slots in total"
+    )
+    return 0
+
+
+def cmd_which(args: argparse.Namespace) -> int:
+    here = Path.cwd().resolve()
+    for slot in _pool().status():
+        path = Path(slot.path).resolve()
+        if here == path or path in here.parents:
+            print(f"{slot.name} {slot.state} {slot.branch or '-'}")
+            return 0
+    fail("not inside a warmtree slot")
+    return 1
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    slots = _pool().status()
+    if args.json:
+        print(json.dumps([slot.to_dict() for slot in slots], indent=2))
+        return 0
+    if not slots:
+        print("no slots yet; run `warmtree fill`")
+        return 0
+    print_table(slots)
+    return 0
+
+
+def print_table(slots: list[Slot]) -> None:
+    rows = [("SLOT", "STATE", "BRANCH", "AGE", "WARMED", "PATH")]
+    for slot in slots:
+        rows.append(
+            (
+                slot.name,
+                slot.state,
+                slot.branch or "-",
+                _age(slot.created),
+                _age(slot.warmed) + " ago" if slot.warmed else "-",
+                slot.path,
+            )
+        )
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]) - 1)]
+    for row in rows:
+        cells = [cell.ljust(widths[i]) for i, cell in enumerate(row[:-1])]
+        print("  ".join([*cells, row[-1]]))
+
+
+def _pool() -> Pool:
+    root = git.repo_root(Path.cwd())
+    return Pool(root, config.load(root), log=note)
+
+
+def _spawn_background_fill(repo_root: Path) -> None:
+    """Start `warmtree fill` detached from this process and terminal."""
+    command = [sys.executable, "-m", "warmtree", "fill"]
+    options: dict = {
+        "cwd": repo_root,
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+    }
+    if sys.platform == "win32":
+        options["creationflags"] = (
+            subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+    else:
+        options["start_new_session"] = True
+    subprocess.Popen(command, **options)
+
+
+def _age(timestamp: str) -> str:
+    """Compact human age like `4m`, `3h`, `2d`."""
+    then = datetime.fromisoformat(timestamp)
+    seconds = int((datetime.now(UTC) - then).total_seconds())
+    if seconds < 60:
+        return f"{seconds}s"
+    if seconds < 3600:
+        return f"{seconds // 60}m"
+    if seconds < 86400:
+        return f"{seconds // 3600}h"
+    return f"{seconds // 86400}d"

warmtree/config.py

@@ -0,0 +1,142 @@
+"""Load and validate `.warmtree.toml`.
+
+Every key has a default. An empty file, or no file at all, means a pool of
+two slots parked on the repo's default branch with nothing to warm.
+"""
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_NAME = ".warmtree.toml"
+
+
+class ConfigError(Exception):
+    """The config file is malformed or holds a value we cannot use."""
+
+
+@dataclass(frozen=True)
+class Config:
+    size: int = 2
+    base: str | None = None  # None means "detect the repo's default branch"
+    dir: str | None = None  # None means "../.warmtree/<repo name>"
+    lockfiles: tuple[str, ...] = ()
+    run: tuple[str, ...] = ()
+    copy: tuple[str, ...] = ()
+    env: bool = True
+
+
+# Which keys live in which table, and the TOML type each must have.
+# Anything not listed here is a typo, and typos are errors rather than silent
+# defaults so a misspelled `run` never quietly skips warming.
+_SCHEMA: dict[str, dict[str, type]] = {
+    "pool": {"size": int, "base": str, "dir": str, "lockfiles": list},
+    "warm": {"run": list, "copy": list, "env": bool},
+}
+
+
+def parse(text: str) -> Config:
+    """Turn TOML text into a Config, or raise ConfigError."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"invalid TOML: {exc}") from exc
+
+    values: dict[str, object] = {}
+    for table_name, table in data.items():
+        if table_name not in _SCHEMA or not isinstance(table, dict):
+            raise ConfigError(f"unknown table or key {table_name!r}")
+        for key, value in table.items():
+            expected = _SCHEMA[table_name].get(key)
+            if expected is None:
+                raise ConfigError(f"unknown key {key!r} in [{table_name}]")
+            values[key] = _check(table_name, key, value, expected)
+
+    size = values.get("size", Config.size)
+    if isinstance(size, int) and size < 0:
+        raise ConfigError("[pool] size must be zero or more")
+    return Config(**values)  # type: ignore[arg-type]
+
+
+def _check(table: str, key: str, value: object, expected: type) -> object:
+    """Validate one value against its expected type. Lists become tuples."""
+    # bool is a subclass of int in Python, so `size = true` needs its own check.
+    if expected is int and isinstance(value, bool):
+        raise ConfigError(f"[{table}] {key} must be an integer")
+    if not isinstance(value, expected):
+        raise ConfigError(f"[{table}] {key} must be of type {expected.__name__}")
+    if expected is list:
+        if not all(isinstance(item, str) for item in value):
+            raise ConfigError(f"[{table}] {key} must be a list of strings")
+        return tuple(value)
+    return value
+
+
+def load(repo_root: Path) -> Config:
+    """Read the config at the repo root. A missing file means defaults."""
+    path = repo_root / CONFIG_NAME
+    if not path.exists():
+        return Config()
+    return parse(path.read_text(encoding="utf-8"))
+
+
+# The `size = N` line in [pool]. Only the digits are replaced so comments
+# and spacing on that line survive.
+_SIZE_LINE = re.compile(r"^(\s*size\s*=\s*)\d+", re.MULTILINE)
+
+
+def write_size(repo_root: Path, size: int) -> Path:
+    """Set [pool] size in the config file, creating the file if needed.
+
+    Edits one line in place rather than regenerating the file, so the user's
+    comments and other keys are untouched. Returns the config path.
+    """
+    if size < 0:
+        raise ConfigError("size must be zero or more")
+    path = repo_root / CONFIG_NAME
+    text = path.read_text(encoding="utf-8") if path.exists() else starter_toml([])
+    if _SIZE_LINE.search(text):
+        text = _SIZE_LINE.sub(rf"\g<1>{size}", text, count=1)
+    elif "[pool]" in text:
+        text = text.replace("[pool]", f"[pool]\nsize = {size}", 1)
+    else:
+        text = f"[pool]\nsize = {size}\n\n" + text
+    parse(text)  # never write a file we cannot read back
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def pool_dir(repo_root: Path, config: Config) -> Path:
+    """Absolute path of the directory that holds the slots.
+
+    The default is a sibling folder named after the repo, so two repos that
+    share a parent folder never share a pool or a state file.
+    """
+    if config.dir is None:
+        return (repo_root.parent / ".warmtree" / repo_root.name).resolve()
+    return (repo_root / config.dir).resolve()
+
+
+def starter_toml(lockfiles: list[str]) -> str:
+    """The file `warmtree init` writes. Defaults for everything except
+    `lockfiles`, which is pre-filled with what init found in the repo.
+    `run` is never guessed: warmtree does not know what a project needs.
+    """
+    # json.dumps of a list of strings is valid TOML for an array of strings.
+    lockfiles_toml = json.dumps(lockfiles)
+    return f"""\
+# warmtree config. Every key has a default; delete a line to use it.
+
+[pool]
+size = 2                     # slots to keep ready
+# base = "main"              # branch slots park on; default: repo default branch
+# dir = "../.warmtree/app"   # where slots live; default is ../.warmtree/<repo name>
+lockfiles = {lockfiles_toml}  # re-warm a slot only when one of these changes
+
+[warm]
+run = []                     # run inside a slot at fill and refresh, e.g. ["npm ci"]
+copy = []                    # untracked files copied from the main repo, e.g. [".env"]
+env = true                   # write WARMTREE_SLOT=<n> into the copied env files
+"""

warmtree/git.py

@@ -0,0 +1,152 @@
+"""Thin wrapper around the git command line.
+
+Each function runs one git command and returns the little we need. Nothing
+here is mocked in tests; they run against real temporary repos.
+"""
+
+import subprocess
+from pathlib import Path
+
+
+class GitError(Exception):
+    """git exited non-zero. The message is git's own stderr."""
+
+
+def run(args: list[str], cwd: Path) -> str:
+    """Run `git <args>` in cwd and return stripped stdout."""
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        message = result.stderr.strip()
+        if not message:
+            message = f"git {' '.join(args)} exited with code {result.returncode}"
+        raise GitError(message)
+    return result.stdout.strip()
+
+
+def repo_root(start: Path) -> Path:
+    """Root of the main worktree that contains `start`.
+
+    `--git-common-dir` points at the shared `.git` directory even when `start`
+    is inside a linked worktree, so the pool always belongs to the main repo.
+    """
+    common_dir = run(["rev-parse", "--git-common-dir"], cwd=start)
+    return (start / common_dir).resolve().parent
+
+
+def default_branch(repo: Path) -> str:
+    """The branch slots park on when the config does not name one.
+
+    Prefer what the remote calls its default. Without a remote, fall back to
+    whatever branch the main worktree has checked out.
+    """
+    try:
+        remote_head = run(
+            ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd=repo
+        )
+        return remote_head.removeprefix("origin/")
+    except GitError:
+        pass
+    try:
+        return run(["symbolic-ref", "--short", "HEAD"], cwd=repo)
+    except GitError as exc:
+        raise GitError(
+            "cannot detect the default branch (HEAD is detached and there is no "
+            "origin/HEAD); set base in .warmtree.toml"
+        ) from exc
+
+
+def rev_parse(repo: Path, ref: str) -> str:
+    """Full commit hash that `ref` points at."""
+    return run(["rev-parse", "--verify", f"{ref}^{{commit}}"], cwd=repo)
+
+
+def worktree_add_detached(repo: Path, path: Path, ref: str) -> None:
+    """Create a worktree at `path` with a detached HEAD at `ref`.
+
+    Detached means no branch is checked out, so the slot never collides with
+    git's one-branch-per-worktree rule until `take` puts a branch on it.
+    """
+    run(["worktree", "add", "--detach", str(path), ref], cwd=repo)
+
+
+def worktree_list(repo: Path) -> list[Path]:
+    """Paths of every worktree git knows about, main worktree first."""
+    output = run(["worktree", "list", "--porcelain"], cwd=repo)
+    paths = []
+    for line in output.splitlines():
+        if line.startswith("worktree "):
+            paths.append(Path(line.removeprefix("worktree ")).resolve())
+    return paths
+
+
+def head_branch(path: Path) -> str | None:
+    """Name of the checked-out branch, or None when HEAD is detached."""
+    try:
+        return run(["symbolic-ref", "--quiet", "--short", "HEAD"], cwd=path)
+    except GitError:
+        return None
+
+
+def is_dirty(path: Path) -> bool:
+    """True when the worktree has modified, staged, or untracked files."""
+    return bool(run(["status", "--porcelain"], cwd=path))
+
+
+def branch_exists(repo: Path, name: str) -> bool:
+    try:
+        run(["rev-parse", "--verify", "--quiet", f"refs/heads/{name}"], cwd=repo)
+    except GitError:
+        return False
+    return True
+
+
+def checkout_branch(path: Path, branch: str) -> None:
+    run(["checkout", "--quiet", branch], cwd=path)
+
+
+def checkout_new_branch(path: Path, branch: str, start: str) -> None:
+    run(["checkout", "--quiet", "-b", branch, start], cwd=path)
+
+
+def reset_to_detached(path: Path, ref: str) -> None:
+    """Park the worktree on `ref` with a detached HEAD and a clean tree.
+
+    `clean -fd` removes untracked files but not ignored ones, so installed
+    dependencies such as `node_modules` survive. That is the warm state.
+    """
+    run(["checkout", "--quiet", "--force", "--detach", ref], cwd=path)
+    run(["clean", "-fd", "--quiet"], cwd=path)
+
+
+def branch_delete(repo: Path, name: str) -> bool:
+    """Delete a fully merged branch. Returns False if git refused, which is
+    what happens when the branch has commits not yet merged anywhere."""
+    try:
+        run(["branch", "--delete", name], cwd=repo)
+    except GitError:
+        return False
+    return True
+
+
+def worktree_add_branch(repo: Path, path: Path, branch: str, start: str) -> None:
+    """Create a worktree with `branch` checked out, creating the branch at
+    `start` if it does not exist yet. This is the cold path."""
+    if branch_exists(repo, branch):
+        run(["worktree", "add", str(path), branch], cwd=repo)
+    else:
+        run(["worktree", "add", "-b", branch, str(path), start], cwd=repo)
+
+
+def worktree_remove(repo: Path, path: Path) -> None:
+    """Delete a worktree and its registration, ignored files included."""
+    if path.exists():
+        run(["worktree", "remove", "--force", str(path)], cwd=repo)
+    else:
+        run(["worktree", "prune"], cwd=repo)