branchtidy 0.1.0__tar.gz

branchtidy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 branchtidy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

branchtidy-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: branchtidy
+Version: 0.1.0
+Summary: Find and delete merged & stale git branches, safely. Dry-run by default, never touches main/master/develop/current, handles local + remote. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/branchtidy-py
+Project-URL: Repository, https://github.com/jjdoor/branchtidy-py
+Project-URL: Issues, https://github.com/jjdoor/branchtidy-py/issues
+Keywords: git,branch,branches,cleanup,prune,stale,merged,cli,devtools,git-branch
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# branchtidy
+
+**Delete merged & stale git branches — safely.** branchtidy finds the local (and
+optionally remote) branches that are already merged, or haven't seen a commit in
+N days, previews them, and deletes them in one batch. It is **dry-run by
+default**, refuses to touch `main` / `master` / `develop` / your current branch,
+and won't nuke unmerged work unless you explicitly ask.
+
+Zero dependencies (pure Python stdlib). Zero config. No daemon, no account.
+
+```bash
+pipx run branchtidy
+```
+
+```
+branchtidy  local branches  ·  default main  ·  stale > 90d
+
+  BRANCH            LAST COMMIT   MERGED   ACTION
+  feature/login     12d ago       yes      delete (merged)
+  feature/old-poc   210d ago      no       delete (stale 210d)
+  main              2d ago        no       keep (protected)
+  feature/wip       3d ago        no       keep (active)
+
+Dry run. 2 branch(es) WOULD be deleted. Re-run with --delete to apply.
+```
+
+Nothing was deleted. That's the point — you read the table, *then* decide.
+
+## Why another branch cleaner?
+
+Everyone reinvents this as a throwaway `git branch --merged | grep -v ... | xargs`
+one-liner, and those one-liners are exactly how people delete branches they
+wanted. branchtidy's whole pitch is **safety + zero config**:
+
+- **Dry-run is the default.** No flags → it only *prints* what it would do.
+- **Real deletion is gated twice:** `--delete` *and* an interactive confirm
+  (skip the prompt only with `--yes`).
+- **Protected branches are never candidates:** `main`, `master`, `develop`, the
+  current `HEAD`, plus anything you pass to `--protect`.
+- **Merged vs unmerged is respected.** Merged branches use the safe
+  `git branch -d`. Unmerged branches are only deletable with an explicit
+  `--force` (which maps to `git branch -D`).
+- **Remote deletion is double-gated:** it requires `--remote --delete` *and* its
+  own confirmation, and uses `git push <remote> --delete`.
+
+When in doubt, branchtidy **keeps** the branch.
+
+## Install
+
+```bash
+pipx run branchtidy        # no install, run on demand
+pip install branchtidy     # or install the `branchtidy` command
+```
+
+There's an identical Node build too: `npx branchtidy` / `npm i -g branchtidy`
+(see [branchtidy](https://github.com/jjdoor/branchtidy)). Both ports share one
+selection-vector table, so they make byte-for-byte identical decisions.
+
+## Usage
+
+```bash
+branchtidy [options]            # dry-run preview (default — deletes nothing)
+branchtidy --delete             # actually delete, after a confirm
+```
+
+| Option | Description |
+| --- | --- |
+| `--delete` | Perform deletion. Without it, branchtidy only previews. |
+| `--yes` | Skip the interactive confirm (use with `--delete`, e.g. in scripts). |
+| `--stale <dur>` | Staleness threshold. Default `90d`. Accepts `30d`, `2w`, `12h`, `45m`, `30s`, or a bare number (days). |
+| `--merged-only` | Only delete *merged* branches; never delete on age alone. |
+| `--remote [name]` | Operate on remote-tracking branches (default remote: `origin`). |
+| `--protect <a,b>` | Extra branch names to never delete (comma-separated). |
+| `--force` | Allow deleting **unmerged** branches (maps to `git branch -D`). |
+| `--json` | Machine-readable output; never prompts, never deletes (preview only). |
+| `--no-color` | Disable ANSI colors. |
+| `-h, --help` | Show help. |
+| `-v, --version` | Print version. |
+
+Exit codes: `0` success/clean, `1` one or more deletions failed, `2` usage or
+environment error (e.g. not a git repo).
+
+### Examples
+
+```bash
+# what WOULD be cleaned up, right now?
+branchtidy
+
+# stricter window, only merged branches, do it (with a confirm)
+branchtidy --stale 30d --merged-only --delete
+
+# clean up gone-stale remote branches on origin (double-gated + confirm)
+branchtidy --remote origin --delete
+
+# delete unmerged stale branches too — you have to ask for it
+branchtidy --stale 180d --delete --force
+
+# protect a couple of long-lived branches by name
+branchtidy --protect release/v1,staging --delete
+
+# pipe the plan somewhere
+branchtidy --json | jq '.toDelete'
+```
+
+## How it decides
+
+For each branch branchtidy looks at: is it the current `HEAD`? is it protected?
+is it merged into the default branch? how old is its last commit? Then:
+
+1. current branch → **keep** (`current`)
+2. protected (default set or `--protect`) → **keep** (`protected`)
+3. merged → **delete** (`merged`)
+4. otherwise, if older than `--stale` → **delete** (`stale <N>d`)
+5. otherwise → **keep** (`active`)
+
+In `--merged-only` mode, step 4 is skipped entirely — age never causes a
+deletion.
+
+The default branch is resolved from `origin/HEAD` when available, otherwise it
+falls back to `main`, then `master`.
+
+## Design notes
+
+- **One pure function at the core.** `select_branches(branches, policy, now_ms)`
+  has no git, no fs, no clock — it's a pure data→data transform that returns
+  `{toDelete, toKeep}` with a reason on every branch. The CLI is a thin git
+  wrapper around it. That's what makes the Node and Python ports verifiably
+  identical: they run the same vector table.
+- **Time is integer math.** Ages are computed from `committerdate:unix` against
+  a single captured `now` in milliseconds — no `datetime` parity to worry about
+  between languages.
+- **Safe by construction.** Protected and current branches are filtered out
+  *before* any staleness logic runs, the staleness test is a strict `>` (a
+  branch exactly at the threshold is kept), and deletion always passes through
+  the safe `git branch -d` unless you opt into `-D` with `--force`.
+
+## License
+
+MIT

branchtidy-0.1.0/README.md

@@ -0,0 +1,139 @@
+# branchtidy
+
+**Delete merged & stale git branches — safely.** branchtidy finds the local (and
+optionally remote) branches that are already merged, or haven't seen a commit in
+N days, previews them, and deletes them in one batch. It is **dry-run by
+default**, refuses to touch `main` / `master` / `develop` / your current branch,
+and won't nuke unmerged work unless you explicitly ask.
+
+Zero dependencies (pure Python stdlib). Zero config. No daemon, no account.
+
+```bash
+pipx run branchtidy
+```
+
+```
+branchtidy  local branches  ·  default main  ·  stale > 90d
+
+  BRANCH            LAST COMMIT   MERGED   ACTION
+  feature/login     12d ago       yes      delete (merged)
+  feature/old-poc   210d ago      no       delete (stale 210d)
+  main              2d ago        no       keep (protected)
+  feature/wip       3d ago        no       keep (active)
+
+Dry run. 2 branch(es) WOULD be deleted. Re-run with --delete to apply.
+```
+
+Nothing was deleted. That's the point — you read the table, *then* decide.
+
+## Why another branch cleaner?
+
+Everyone reinvents this as a throwaway `git branch --merged | grep -v ... | xargs`
+one-liner, and those one-liners are exactly how people delete branches they
+wanted. branchtidy's whole pitch is **safety + zero config**:
+
+- **Dry-run is the default.** No flags → it only *prints* what it would do.
+- **Real deletion is gated twice:** `--delete` *and* an interactive confirm
+  (skip the prompt only with `--yes`).
+- **Protected branches are never candidates:** `main`, `master`, `develop`, the
+  current `HEAD`, plus anything you pass to `--protect`.
+- **Merged vs unmerged is respected.** Merged branches use the safe
+  `git branch -d`. Unmerged branches are only deletable with an explicit
+  `--force` (which maps to `git branch -D`).
+- **Remote deletion is double-gated:** it requires `--remote --delete` *and* its
+  own confirmation, and uses `git push <remote> --delete`.
+
+When in doubt, branchtidy **keeps** the branch.
+
+## Install
+
+```bash
+pipx run branchtidy        # no install, run on demand
+pip install branchtidy     # or install the `branchtidy` command
+```
+
+There's an identical Node build too: `npx branchtidy` / `npm i -g branchtidy`
+(see [branchtidy](https://github.com/jjdoor/branchtidy)). Both ports share one
+selection-vector table, so they make byte-for-byte identical decisions.
+
+## Usage
+
+```bash
+branchtidy [options]            # dry-run preview (default — deletes nothing)
+branchtidy --delete             # actually delete, after a confirm
+```
+
+| Option | Description |
+| --- | --- |
+| `--delete` | Perform deletion. Without it, branchtidy only previews. |
+| `--yes` | Skip the interactive confirm (use with `--delete`, e.g. in scripts). |
+| `--stale <dur>` | Staleness threshold. Default `90d`. Accepts `30d`, `2w`, `12h`, `45m`, `30s`, or a bare number (days). |
+| `--merged-only` | Only delete *merged* branches; never delete on age alone. |
+| `--remote [name]` | Operate on remote-tracking branches (default remote: `origin`). |
+| `--protect <a,b>` | Extra branch names to never delete (comma-separated). |
+| `--force` | Allow deleting **unmerged** branches (maps to `git branch -D`). |
+| `--json` | Machine-readable output; never prompts, never deletes (preview only). |
+| `--no-color` | Disable ANSI colors. |
+| `-h, --help` | Show help. |
+| `-v, --version` | Print version. |
+
+Exit codes: `0` success/clean, `1` one or more deletions failed, `2` usage or
+environment error (e.g. not a git repo).
+
+### Examples
+
+```bash
+# what WOULD be cleaned up, right now?
+branchtidy
+
+# stricter window, only merged branches, do it (with a confirm)
+branchtidy --stale 30d --merged-only --delete
+
+# clean up gone-stale remote branches on origin (double-gated + confirm)
+branchtidy --remote origin --delete
+
+# delete unmerged stale branches too — you have to ask for it
+branchtidy --stale 180d --delete --force
+
+# protect a couple of long-lived branches by name
+branchtidy --protect release/v1,staging --delete
+
+# pipe the plan somewhere
+branchtidy --json | jq '.toDelete'
+```
+
+## How it decides
+
+For each branch branchtidy looks at: is it the current `HEAD`? is it protected?
+is it merged into the default branch? how old is its last commit? Then:
+
+1. current branch → **keep** (`current`)
+2. protected (default set or `--protect`) → **keep** (`protected`)
+3. merged → **delete** (`merged`)
+4. otherwise, if older than `--stale` → **delete** (`stale <N>d`)
+5. otherwise → **keep** (`active`)
+
+In `--merged-only` mode, step 4 is skipped entirely — age never causes a
+deletion.
+
+The default branch is resolved from `origin/HEAD` when available, otherwise it
+falls back to `main`, then `master`.
+
+## Design notes
+
+- **One pure function at the core.** `select_branches(branches, policy, now_ms)`
+  has no git, no fs, no clock — it's a pure data→data transform that returns
+  `{toDelete, toKeep}` with a reason on every branch. The CLI is a thin git
+  wrapper around it. That's what makes the Node and Python ports verifiably
+  identical: they run the same vector table.
+- **Time is integer math.** Ages are computed from `committerdate:unix` against
+  a single captured `now` in milliseconds — no `datetime` parity to worry about
+  between languages.
+- **Safe by construction.** Protected and current branches are filtered out
+  *before* any staleness logic runs, the staleness test is a strict `>` (a
+  branch exactly at the threshold is kept), and deletion always passes through
+  the safe `git branch -d` unless you opt into `-D` with `--force`.
+
+## License
+
+MIT

branchtidy-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "branchtidy"
+version = "0.1.0"
+description = "Find and delete merged & stale git branches, safely. Dry-run by default, never touches main/master/develop/current, handles local + remote. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "yyfjj" }]
+keywords = ["git", "branch", "branches", "cleanup", "prune", "stale", "merged", "cli", "devtools", "git-branch"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jjdoor/branchtidy-py"
+Repository = "https://github.com/jjdoor/branchtidy-py"
+Issues = "https://github.com/jjdoor/branchtidy-py/issues"
+
+[project.scripts]
+branchtidy = "branchtidy.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

branchtidy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

branchtidy-0.1.0/src/branchtidy/__init__.py

@@ -0,0 +1,6 @@
+"""branchtidy — delete merged & stale git branches, safely."""
+
+from .core import select_branches, parse_duration, age_days
+
+__version__ = "0.1.0"
+__all__ = ["select_branches", "parse_duration", "age_days"]

branchtidy-0.1.0/src/branchtidy/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

branchtidy-0.1.0/src/branchtidy/cli.py

@@ -0,0 +1,426 @@
+"""branchtidy command-line interface — a thin git wrapper around the pure core.
+
+The only impure layer lives here: subprocess calls to git, prompts, and stdout.
+All selection decisions go through ``core.select_branches``.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+
+from . import core
+
+VERSION = "0.1.0"
+
+_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _c(code, s):
+    return f"\x1b[{code}m{s}\x1b[0m" if _COLOR else s
+
+
+def bold(s): return _c("1", s)
+def dim(s): return _c("2", s)
+def red(s): return _c("31", s)
+def green(s): return _c("32", s)
+def yellow(s): return _c("33", s)
+
+
+PROTECTED_DEFAULTS = ["main", "master", "develop"]
+
+
+def _help():
+    return f"""{bold('branchtidy')} — delete merged & stale git branches, safely.
+
+{bold('Usage')}
+  branchtidy [options]            {dim('# dry-run preview (default — deletes nothing)')}
+  branchtidy --delete             {dim('# actually delete, after a confirm')}
+
+{bold('Options')}
+      --delete             perform deletion (otherwise: preview only)
+      --yes                skip the interactive confirm (use with --delete)
+      --stale <dur>        staleness threshold, default 90d (e.g. 30d, 2w, 12h)
+      --merged-only        only delete merged branches; never delete on age alone
+      --remote [name]      operate on remote branches (default remote: origin)
+      --protect <a,b>      extra branch names to never delete (comma-separated)
+      --force              allow deleting UNMERGED branches (git branch -D)
+      --json               machine-readable output (no prompts/colors)
+      --no-color           disable ANSI colors
+  -h, --help               show this help
+  -v, --version            print version
+
+{bold('Safety')}
+  - Dry-run is the default. Nothing is deleted without {bold('--delete')}.
+  - {bold('main')}, {bold('master')}, {bold('develop')}, current HEAD and --protect names are never touched.
+  - Unmerged branches need {bold('--force')}; merged ones use a safe {dim('git branch -d')}.
+  - Remote deletion is double-gated: needs {bold('--remote --delete')} and its own confirm.
+
+{bold('Examples')}
+  branchtidy                       {dim('# what WOULD be cleaned up?')}
+  branchtidy --stale 30d           {dim('# stricter staleness window')}
+  branchtidy --merged-only --delete
+  branchtidy --remote origin --delete --force
+"""
+
+
+def die(msg, code=2):
+    sys.stderr.write(f"branchtidy: {msg}\n")
+    sys.exit(code)
+
+
+def _value(argv, i):
+    if i + 1 >= len(argv):
+        die(f"{argv[i]} needs a value")
+    return argv[i + 1]
+
+
+def parse_args(argv):
+    global _COLOR
+    opts = {
+        "delete": False,
+        "yes": False,
+        "staleSpec": "90d",
+        "mergedOnly": False,
+        "remote": False,
+        "remoteName": "origin",
+        "protect": [],
+        "force": False,
+        "json": False,
+    }
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--delete":
+            opts["delete"] = True; i += 1; continue
+        if a in ("--yes", "-y"):
+            opts["yes"] = True; i += 1; continue
+        if a == "--stale":
+            opts["staleSpec"] = _value(argv, i); i += 2; continue
+        if a == "--merged-only":
+            opts["mergedOnly"] = True; i += 1; continue
+        if a == "--remote":
+            opts["remote"] = True
+            nxt = argv[i + 1] if i + 1 < len(argv) else None
+            if nxt is not None and not nxt.startswith("-"):
+                opts["remoteName"] = nxt; i += 2
+            else:
+                i += 1
+            continue
+        if a == "--protect":
+            opts["protect"] = [s.strip() for s in _value(argv, i).split(",") if s.strip()]
+            i += 2; continue
+        if a == "--force":
+            opts["force"] = True; i += 1; continue
+        if a == "--json":
+            opts["json"] = True; i += 1; continue
+        if a == "--no-color":
+            _COLOR = False; i += 1; continue
+        if a == "--color":
+            _COLOR = True; i += 1; continue
+        die(f'unknown option "{a}" (try --help)')
+    return opts
+
+
+# ---------------------------------------------------------------------------
+# git IO adapter — the only impure layer. Everything routes through `_git`.
+# ---------------------------------------------------------------------------
+
+def _git(args, allow_fail=False):
+    try:
+        out = subprocess.run(
+            ["git"] + args,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+        )
+        return out.stdout.decode("utf-8", "replace")
+    except FileNotFoundError:
+        die("git is not installed or not on PATH", 2)
+    except subprocess.CalledProcessError as e:
+        if allow_fail:
+            return None
+        msg = e.stderr.decode("utf-8", "replace").strip() if e.stderr else str(e)
+        raise RuntimeError(msg)
+
+
+def ensure_git_repo():
+    out = _git(["rev-parse", "--is-inside-work-tree"], allow_fail=True)
+    if not out or out.strip() != "true":
+        die("not inside a git repository", 2)
+
+
+def current_branch():
+    out = _git(["rev-parse", "--abbrev-ref", "HEAD"], allow_fail=True)
+    return out.strip() if out else None  # "HEAD" when detached
+
+
+def default_branch():
+    sym = _git(["symbolic-ref", "refs/remotes/origin/HEAD"], allow_fail=True)
+    if sym:
+        ref = sym.strip()  # refs/remotes/origin/main
+        idx = ref.rfind("/")
+        if idx != -1 and "refs/remotes/" in ref:
+            # strip refs/remotes/<remote>/
+            parts = ref.split("/", 3)
+            if len(parts) == 4:
+                return parts[3]
+    for cand in ("main", "master"):
+        v = _git(["rev-parse", "--verify", "--quiet", f"refs/heads/{cand}"], allow_fail=True)
+        if v:
+            return cand
+    return "main"
+
+
+def _parse_ref_list(out):
+    rows = []
+    for line in (out or "").split("\n"):
+        if not line.strip():
+            continue
+        sp = line.rfind(" ")
+        if sp < 0:
+            continue
+        name = line[:sp]
+        try:
+            unix = int(line[sp + 1:])
+        except ValueError:
+            continue
+        if not name:
+            continue
+        rows.append({"name": name, "lastCommitMs": unix * 1000})
+    return rows
+
+
+def list_local_branches():
+    out = _git(["for-each-ref", "--format=%(refname:short) %(committerdate:unix)", "refs/heads"])
+    return _parse_ref_list(out)
+
+
+def list_remote_branches(remote):
+    out = _git(["for-each-ref", "--format=%(refname:short) %(committerdate:unix)", f"refs/remotes/{remote}"])
+    prefix = f"{remote}/"
+    rows = []
+    for b in _parse_ref_list(out):
+        if b["name"] == f"{remote}/HEAD" or b["name"].endswith("/HEAD"):
+            continue
+        short = b["name"][len(prefix):] if b["name"].startswith(prefix) else b["name"]
+        rows.append({**b, "short": short})
+    return rows
+
+
+def merged_set(base):
+    out = _git(["branch", "--merged", base], allow_fail=True)
+    if not out:
+        return set()
+    names = set()
+    for line in out.split("\n"):
+        name = line.lstrip("*+ ").strip()
+        if name:
+            names.add(name)
+    return names
+
+
+def merged_set_remote(remote, base):
+    out = _git(["branch", "-r", "--merged", f"{remote}/{base}"], allow_fail=True)
+    if not out:
+        return set()
+    names = set()
+    for line in out.split("\n"):
+        name = line.strip()
+        if name and "->" not in name:
+            names.add(name)
+    return names
+
+
+# ---------------------------------------------------------------------------
+# preview + delete
+# ---------------------------------------------------------------------------
+
+def _fmt_age(last_commit_ms, now_ms):
+    d = core.age_days(last_commit_ms, now_ms)
+    if d == 0:
+        return "today"
+    if d == 1:
+        return "1d ago"
+    return f"{d}d ago"
+
+
+def _pad(s, w):
+    s = str(s)
+    return s if len(s) >= w else s + " " * (w - len(s))
+
+
+def print_preview(rows, now_ms):
+    name_w = max([6] + [len(r["name"]) for r in rows])
+    sys.stdout.write(
+        "  " + _pad("BRANCH", name_w) + "  " + _pad("LAST COMMIT", 12) + "  " + _pad("MERGED", 7) + "  ACTION\n"
+    )
+    for r in rows:
+        merged = "yes" if r["merged"] else "no"
+        if r["action"] == "delete":
+            action = red(f"delete ({r['reason']})")
+        else:
+            action = dim(f"keep ({r['reason']})")
+        sys.stdout.write(
+            "  " + _pad(r["name"], name_w) + "  " + _pad(_fmt_age(r["lastCommitMs"], now_ms), 12)
+            + "  " + _pad(merged, 7) + "  " + action + "\n"
+        )
+
+
+def confirm(question):
+    sys.stdout.write(question)
+    sys.stdout.flush()
+    try:
+        answer = sys.stdin.readline()
+    except KeyboardInterrupt:
+        return False
+    return answer.strip().lower() in ("y", "yes")
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if "-h" in argv or "--help" in argv:
+        sys.stdout.write(_help())
+        return 0
+    if "-v" in argv or "--version" in argv:
+        sys.stdout.write(VERSION + "\n")
+        return 0
+
+    opts = parse_args(argv)
+    global _COLOR
+    if opts["json"]:
+        _COLOR = False
+
+    try:
+        stale_ms = core.parse_duration(opts["staleSpec"])
+    except ValueError as e:
+        die(str(e))
+
+    ensure_git_repo()
+
+    now_ms = int(time.time() * 1000)
+    cur = current_branch()
+    base = default_branch()
+    protected_names = PROTECTED_DEFAULTS + opts["protect"] + ([base] if base else [])
+
+    if opts["remote"]:
+        remote = opts["remoteName"]
+        merged = merged_set_remote(remote, base)
+        branches = []
+        for b in list_remote_branches(remote):
+            branches.append({
+                "name": b["name"],         # e.g. origin/feature/x
+                "short": b["short"],       # e.g. feature/x  (used for push --delete)
+                "lastCommitMs": b["lastCommitMs"],
+                "merged": b["name"] in merged,
+                "isProtected": b["short"] in protected_names or b["short"] == f"{remote}/HEAD",
+                "isCurrent": False,        # remote refs are never the local HEAD
+            })
+    else:
+        merged = merged_set(base)
+        branches = []
+        for b in list_local_branches():
+            branches.append({
+                "name": b["name"],
+                "lastCommitMs": b["lastCommitMs"],
+                "merged": b["name"] in merged,
+                "isProtected": b["name"] in protected_names,
+                "isCurrent": b["name"] == cur,
+            })
+
+    policy = {"staleMs": stale_ms, "mergedOnly": opts["mergedOnly"], "protected": protected_names}
+    result = core.select_branches(branches, policy, now_ms)
+    to_delete = result["toDelete"]
+    to_keep = result["toKeep"]
+
+    by_name = {b["name"]: b for b in branches}
+    delete_rows = [{**by_name[d["name"]], "action": "delete", "reason": d["reason"]} for d in to_delete]
+    keep_rows = [{**by_name[k["name"]], "action": "keep", "reason": k["reason"]} for k in to_keep]
+
+    if opts["json"]:
+        out = {
+            "mode": "remote" if opts["remote"] else "local",
+            "remote": opts["remoteName"] if opts["remote"] else None,
+            "defaultBranch": base,
+            "current": cur,
+            "stale": opts["staleSpec"],
+            "mergedOnly": opts["mergedOnly"],
+            "dryRun": not opts["delete"],
+            "toDelete": [{"name": d["name"], "reason": d["reason"]} for d in to_delete],
+            "toKeep": [{"name": k["name"], "reason": k["reason"]} for k in to_keep],
+        }
+        sys.stdout.write(json.dumps(out, separators=(",", ":"), ensure_ascii=False) + "\n")
+        # In JSON mode we never delete (no prompt surface). Treat as preview only.
+        return 0
+
+    scope = f"remote {bold(opts['remoteName'])}" if opts["remote"] else "local"
+    sys.stdout.write(
+        f"{bold('branchtidy')}  {scope} branches  ·  default {green(base)}  ·  stale > {yellow(opts['staleSpec'])}\n\n"
+    )
+
+    print_preview(delete_rows + keep_rows, now_ms)
+    sys.stdout.write("\n")
+
+    if not to_delete:
+        sys.stdout.write(green("Nothing to clean up — all branches kept.\n"))
+        return 0
+
+    unmerged = [r for r in delete_rows if not r["merged"]]
+    blocked_unmerged = [] if opts["force"] else unmerged
+    actually_deletable = delete_rows if opts["force"] else [r for r in delete_rows if r["merged"]]
+
+    if not opts["delete"]:
+        sys.stdout.write(
+            dim(f"Dry run. {len(to_delete)} branch(es) WOULD be deleted. Re-run with ")
+            + bold("--delete") + dim(" to apply.\n")
+        )
+        if blocked_unmerged:
+            sys.stdout.write(
+                yellow(f"  ({len(blocked_unmerged)} are unmerged — they need ")
+                + bold("--force") + yellow(" to delete.)\n")
+            )
+        return 0
+
+    # --- real deletion path ---
+    if not actually_deletable:
+        sys.stdout.write(
+            yellow("All deletable branches are unmerged; pass ") + bold("--force") + yellow(" to delete them.\n")
+        )
+        return 0
+
+    if not opts["yes"]:
+        where = f"from remote '{opts['remoteName']}'" if opts["remote"] else "locally"
+        names = ", ".join(r["name"] for r in actually_deletable)
+        verb = red("PERMANENTLY delete") if opts["remote"] else "delete"
+        ok = confirm(
+            f"About to {verb} {bold(str(len(actually_deletable)))} branch(es) {where}:\n  {names}\nProceed? [y/N] "
+        )
+        if not ok:
+            sys.stdout.write("Aborted. Nothing deleted.\n")
+            return 0
+
+    failures = 0
+    for r in actually_deletable:
+        try:
+            if opts["remote"]:
+                _git(["push", opts["remoteName"], "--delete", r["short"]])
+            elif r["merged"]:
+                _git(["branch", "-d", r["name"]])
+            else:
+                _git(["branch", "-D", r["name"]])  # unmerged + --force
+            sys.stdout.write(green(f"  deleted {r['name']}\n"))
+        except RuntimeError as e:
+            failures += 1
+            sys.stderr.write(red(f"  failed  {r['name']}: {e}\n"))
+
+    if blocked_unmerged:
+        sys.stdout.write(
+            yellow(f"  skipped {len(blocked_unmerged)} unmerged branch(es) (no --force)\n")
+        )
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

branchtidy-0.1.0/src/branchtidy/core.py

@@ -0,0 +1,98 @@
+"""branchtidy core — pure branch-selection logic. No git, no fs, no clock, no
+network. Everything here is a pure function of its arguments so this port and
+the Node one are checked against the exact same input -> output vectors.
+
+The one idea: given a snapshot of branches and a policy, decide which are safe
+to delete and which to keep -- and *why*. The reasons are the product. A branch
+cleaner that deletes work you still wanted is worse than useless, so the rule is
+"when unsure, KEEP", and protected / current branches are removed from the
+candidate set before any staleness math runs.
+
+A branch is a dict:
+    {"name", "lastCommitMs", "merged", "isProtected", "isCurrent"}
+A policy is a dict:
+    {"staleMs", "mergedOnly", "protected": [names]}
+"""
+
+import math
+import re
+
+DAY_MS = 86400000  # 24 * 60 * 60 * 1000
+
+_DURATION_RE = re.compile(r"^(\d+(?:\.\d+)?)\s*([smhdw]?)$")
+_UNIT_MS = {"s": 1000, "m": 60000, "h": 3600000, "d": DAY_MS, "w": 7 * DAY_MS}
+
+
+def parse_duration(spec):
+    """Parse a human duration like "90d" / "2w" / "12h" into milliseconds.
+    Supported units: s, m, h, d, w (case-insensitive). A bare number is days.
+    Raises ValueError on garbage so the CLI can surface a clean error."""
+    if isinstance(spec, bool):
+        raise ValueError(f'invalid duration "{spec}"')
+    if isinstance(spec, (int, float)):
+        if not math.isfinite(spec) or spec < 0:
+            raise ValueError(f'invalid duration "{spec}"')
+        return int(math.floor(spec * DAY_MS))
+    s = str(spec).strip().lower()
+    m = _DURATION_RE.match(s)
+    if not m:
+        raise ValueError(f'invalid duration "{spec}" (use e.g. 90d, 2w, 12h)')
+    n = float(m.group(1))
+    unit = m.group(2) or "d"
+    return int(math.floor(n * _UNIT_MS[unit]))
+
+
+def age_days(last_commit_ms, now_ms):
+    """Whole-day age of a branch's last commit relative to now_ms, floored.
+    Negative (future-dated) ages clamp to 0. Pure integer math -- no datetime."""
+    diff = now_ms - last_commit_ms
+    if diff <= 0:
+        return 0
+    return diff // DAY_MS
+
+
+def select_branches(branches, policy, now_ms):
+    """Split a list of branches into the ones safe to delete and the ones to
+    keep, each tagged with a human-readable reason.
+
+    Rules, in priority order (first match wins per branch):
+      1. current branch (HEAD)            -> KEEP, reason "current"
+      2. protected (flag or policy list)  -> KEEP, reason "protected"
+      3. mergedOnly mode:
+           - merged                       -> DELETE, reason "merged"
+           - else                         -> KEEP,   reason "active"
+      4. default mode:
+           - merged                       -> DELETE, reason "merged"
+           - age > staleMs                -> DELETE, reason "stale <N>d"
+           - else                         -> KEEP,   reason "active"
+
+    The staleness test is strict ">": a branch exactly at the threshold is kept.
+    Conservative on purpose.
+    """
+    stale_ms = policy["staleMs"]
+    merged_only = bool(policy.get("mergedOnly"))
+    protected_set = set(policy.get("protected") or [])
+
+    to_delete = []
+    to_keep = []
+
+    for b in branches:
+        if b.get("isCurrent"):
+            to_keep.append({"name": b["name"], "reason": "current"})
+            continue
+        if b.get("isProtected") or b["name"] in protected_set:
+            to_keep.append({"name": b["name"], "reason": "protected"})
+            continue
+        if b.get("merged"):
+            to_delete.append({"name": b["name"], "reason": "merged"})
+            continue
+        if merged_only:
+            to_keep.append({"name": b["name"], "reason": "active"})
+            continue
+        age = age_days(b["lastCommitMs"], now_ms)
+        if now_ms - b["lastCommitMs"] > stale_ms:
+            to_delete.append({"name": b["name"], "reason": f"stale {age}d"})
+            continue
+        to_keep.append({"name": b["name"], "reason": "active"})
+
+    return {"toDelete": to_delete, "toKeep": to_keep}

branchtidy-0.1.0/src/branchtidy.egg-info/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: branchtidy
+Version: 0.1.0
+Summary: Find and delete merged & stale git branches, safely. Dry-run by default, never touches main/master/develop/current, handles local + remote. Zero dependencies.
+Author: yyfjj
+License: MIT
+Project-URL: Homepage, https://github.com/jjdoor/branchtidy-py
+Project-URL: Repository, https://github.com/jjdoor/branchtidy-py
+Project-URL: Issues, https://github.com/jjdoor/branchtidy-py/issues
+Keywords: git,branch,branches,cleanup,prune,stale,merged,cli,devtools,git-branch
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# branchtidy
+
+**Delete merged & stale git branches — safely.** branchtidy finds the local (and
+optionally remote) branches that are already merged, or haven't seen a commit in
+N days, previews them, and deletes them in one batch. It is **dry-run by
+default**, refuses to touch `main` / `master` / `develop` / your current branch,
+and won't nuke unmerged work unless you explicitly ask.
+
+Zero dependencies (pure Python stdlib). Zero config. No daemon, no account.
+
+```bash
+pipx run branchtidy
+```
+
+```
+branchtidy  local branches  ·  default main  ·  stale > 90d
+
+  BRANCH            LAST COMMIT   MERGED   ACTION
+  feature/login     12d ago       yes      delete (merged)
+  feature/old-poc   210d ago      no       delete (stale 210d)
+  main              2d ago        no       keep (protected)
+  feature/wip       3d ago        no       keep (active)
+
+Dry run. 2 branch(es) WOULD be deleted. Re-run with --delete to apply.
+```
+
+Nothing was deleted. That's the point — you read the table, *then* decide.
+
+## Why another branch cleaner?
+
+Everyone reinvents this as a throwaway `git branch --merged | grep -v ... | xargs`
+one-liner, and those one-liners are exactly how people delete branches they
+wanted. branchtidy's whole pitch is **safety + zero config**:
+
+- **Dry-run is the default.** No flags → it only *prints* what it would do.
+- **Real deletion is gated twice:** `--delete` *and* an interactive confirm
+  (skip the prompt only with `--yes`).
+- **Protected branches are never candidates:** `main`, `master`, `develop`, the
+  current `HEAD`, plus anything you pass to `--protect`.
+- **Merged vs unmerged is respected.** Merged branches use the safe
+  `git branch -d`. Unmerged branches are only deletable with an explicit
+  `--force` (which maps to `git branch -D`).
+- **Remote deletion is double-gated:** it requires `--remote --delete` *and* its
+  own confirmation, and uses `git push <remote> --delete`.
+
+When in doubt, branchtidy **keeps** the branch.
+
+## Install
+
+```bash
+pipx run branchtidy        # no install, run on demand
+pip install branchtidy     # or install the `branchtidy` command
+```
+
+There's an identical Node build too: `npx branchtidy` / `npm i -g branchtidy`
+(see [branchtidy](https://github.com/jjdoor/branchtidy)). Both ports share one
+selection-vector table, so they make byte-for-byte identical decisions.
+
+## Usage
+
+```bash
+branchtidy [options]            # dry-run preview (default — deletes nothing)
+branchtidy --delete             # actually delete, after a confirm
+```
+
+| Option | Description |
+| --- | --- |
+| `--delete` | Perform deletion. Without it, branchtidy only previews. |
+| `--yes` | Skip the interactive confirm (use with `--delete`, e.g. in scripts). |
+| `--stale <dur>` | Staleness threshold. Default `90d`. Accepts `30d`, `2w`, `12h`, `45m`, `30s`, or a bare number (days). |
+| `--merged-only` | Only delete *merged* branches; never delete on age alone. |
+| `--remote [name]` | Operate on remote-tracking branches (default remote: `origin`). |
+| `--protect <a,b>` | Extra branch names to never delete (comma-separated). |
+| `--force` | Allow deleting **unmerged** branches (maps to `git branch -D`). |
+| `--json` | Machine-readable output; never prompts, never deletes (preview only). |
+| `--no-color` | Disable ANSI colors. |
+| `-h, --help` | Show help. |
+| `-v, --version` | Print version. |
+
+Exit codes: `0` success/clean, `1` one or more deletions failed, `2` usage or
+environment error (e.g. not a git repo).
+
+### Examples
+
+```bash
+# what WOULD be cleaned up, right now?
+branchtidy
+
+# stricter window, only merged branches, do it (with a confirm)
+branchtidy --stale 30d --merged-only --delete
+
+# clean up gone-stale remote branches on origin (double-gated + confirm)
+branchtidy --remote origin --delete
+
+# delete unmerged stale branches too — you have to ask for it
+branchtidy --stale 180d --delete --force
+
+# protect a couple of long-lived branches by name
+branchtidy --protect release/v1,staging --delete
+
+# pipe the plan somewhere
+branchtidy --json | jq '.toDelete'
+```
+
+## How it decides
+
+For each branch branchtidy looks at: is it the current `HEAD`? is it protected?
+is it merged into the default branch? how old is its last commit? Then:
+
+1. current branch → **keep** (`current`)
+2. protected (default set or `--protect`) → **keep** (`protected`)
+3. merged → **delete** (`merged`)
+4. otherwise, if older than `--stale` → **delete** (`stale <N>d`)
+5. otherwise → **keep** (`active`)
+
+In `--merged-only` mode, step 4 is skipped entirely — age never causes a
+deletion.
+
+The default branch is resolved from `origin/HEAD` when available, otherwise it
+falls back to `main`, then `master`.
+
+## Design notes
+
+- **One pure function at the core.** `select_branches(branches, policy, now_ms)`
+  has no git, no fs, no clock — it's a pure data→data transform that returns
+  `{toDelete, toKeep}` with a reason on every branch. The CLI is a thin git
+  wrapper around it. That's what makes the Node and Python ports verifiably
+  identical: they run the same vector table.
+- **Time is integer math.** Ages are computed from `committerdate:unix` against
+  a single captured `now` in milliseconds — no `datetime` parity to worry about
+  between languages.
+- **Safe by construction.** Protected and current branches are filtered out
+  *before* any staleness logic runs, the staleness test is a strict `>` (a
+  branch exactly at the threshold is kept), and deletion always passes through
+  the safe `git branch -d` unless you opt into `-D` with `--force`.
+
+## License
+
+MIT

branchtidy-0.1.0/src/branchtidy.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/branchtidy/__init__.py
+src/branchtidy/__main__.py
+src/branchtidy/cli.py
+src/branchtidy/core.py
+src/branchtidy.egg-info/PKG-INFO
+src/branchtidy.egg-info/SOURCES.txt
+src/branchtidy.egg-info/dependency_links.txt
+src/branchtidy.egg-info/entry_points.txt
+src/branchtidy.egg-info/top_level.txt
+tests/test_core.py

branchtidy-0.1.0/src/branchtidy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

branchtidy-0.1.0/src/branchtidy.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+branchtidy = branchtidy.cli:main

branchtidy-0.1.0/src/branchtidy.egg-info/top_level.txt

@@ -0,0 +1 @@
+branchtidy

branchtidy-0.1.0/tests/test_core.py

@@ -0,0 +1,162 @@
+import pytest
+
+from branchtidy.core import select_branches, parse_duration, age_days
+
+# A fixed "now" so the vectors are deterministic. 2024-06-10T00:00:00Z in ms.
+NOW = 1717977600000
+DAY = 86400000
+
+
+def days_ago(n):
+    return NOW - n * DAY
+
+
+STALE_90D = 90 * DAY
+
+# Shared selection vectors. The Node port (test/core.test.js) runs this exact
+# same table, so both languages are proven to agree on every selection decision.
+#
+# Each vector: (name, branches, policy, to_delete, to_keep)
+# branch = {name, lastCommitMs, merged, isProtected, isCurrent}
+# policy = {staleMs, mergedOnly, protected}
+VECTORS = [
+    (
+        "protected branch is always kept",
+        [{"name": "main", "lastCommitMs": days_ago(400), "merged": False, "isProtected": True, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [],
+        [{"name": "main", "reason": "protected"}],
+    ),
+    (
+        "current branch is always kept (even if stale + merged)",
+        [{"name": "feature/now", "lastCommitMs": days_ago(400), "merged": True, "isProtected": False, "isCurrent": True}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [],
+        [{"name": "feature/now", "reason": "current"}],
+    ),
+    (
+        "current takes priority over protected reason",
+        [{"name": "develop", "lastCommitMs": days_ago(10), "merged": False, "isProtected": True, "isCurrent": True}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": ["develop"]},
+        [],
+        [{"name": "develop", "reason": "current"}],
+    ),
+    (
+        "policy.protected list shields a branch by name",
+        [{"name": "release/v2", "lastCommitMs": days_ago(300), "merged": True, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": ["release/v2"]},
+        [],
+        [{"name": "release/v2", "reason": "protected"}],
+    ),
+    (
+        "merged branch is deleted with reason merged",
+        [{"name": "feature/login", "lastCommitMs": days_ago(2), "merged": True, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [{"name": "feature/login", "reason": "merged"}],
+        [],
+    ),
+    (
+        "unmerged but stale branch is deleted with day count",
+        [{"name": "feature/old", "lastCommitMs": days_ago(200), "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [{"name": "feature/old", "reason": "stale 200d"}],
+        [],
+    ),
+    (
+        "unmerged recent branch is kept as active",
+        [{"name": "feature/wip", "lastCommitMs": days_ago(5), "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [],
+        [{"name": "feature/wip", "reason": "active"}],
+    ),
+    (
+        "boundary: exactly at staleMs is KEPT (strict greater-than)",
+        [{"name": "feature/edge", "lastCommitMs": NOW - STALE_90D, "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [],
+        [{"name": "feature/edge", "reason": "active"}],
+    ),
+    (
+        "boundary: one ms past staleMs is deleted (stale 90d)",
+        [{"name": "feature/edge2", "lastCommitMs": NOW - STALE_90D - 1, "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [{"name": "feature/edge2", "reason": "stale 90d"}],
+        [],
+    ),
+    (
+        "mergedOnly: stale-but-unmerged is KEPT (active)",
+        [{"name": "feature/stale", "lastCommitMs": days_ago(300), "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": True, "protected": []},
+        [],
+        [{"name": "feature/stale", "reason": "active"}],
+    ),
+    (
+        "mergedOnly: merged branch still deleted",
+        [{"name": "feature/done", "lastCommitMs": days_ago(1), "merged": True, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": True, "protected": []},
+        [{"name": "feature/done", "reason": "merged"}],
+        [],
+    ),
+    (
+        "future-dated commit clamps age to 0 and is kept active",
+        [{"name": "feature/clock-skew", "lastCommitMs": NOW + 10 * DAY, "merged": False, "isProtected": False, "isCurrent": False}],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [],
+        [{"name": "feature/clock-skew", "reason": "active"}],
+    ),
+    (
+        "mixed repo: protected, current, merged, stale, active together",
+        [
+            {"name": "main", "lastCommitMs": days_ago(1), "merged": False, "isProtected": True, "isCurrent": False},
+            {"name": "feature/current", "lastCommitMs": days_ago(1), "merged": False, "isProtected": False, "isCurrent": True},
+            {"name": "feature/merged", "lastCommitMs": days_ago(3), "merged": True, "isProtected": False, "isCurrent": False},
+            {"name": "feature/ancient", "lastCommitMs": days_ago(365), "merged": False, "isProtected": False, "isCurrent": False},
+            {"name": "feature/fresh", "lastCommitMs": days_ago(2), "merged": False, "isProtected": False, "isCurrent": False},
+        ],
+        {"staleMs": STALE_90D, "mergedOnly": False, "protected": []},
+        [
+            {"name": "feature/merged", "reason": "merged"},
+            {"name": "feature/ancient", "reason": "stale 365d"},
+        ],
+        [
+            {"name": "main", "reason": "protected"},
+            {"name": "feature/current", "reason": "current"},
+            {"name": "feature/fresh", "reason": "active"},
+        ],
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "name,branches,policy,to_delete,to_keep", VECTORS, ids=[v[0] for v in VECTORS]
+)
+def test_select_branches(name, branches, policy, to_delete, to_keep):
+    got = select_branches(branches, policy, NOW)
+    assert got["toDelete"] == to_delete
+    assert got["toKeep"] == to_keep
+
+
+def test_parse_duration_units_and_default():
+    assert parse_duration("90d") == 90 * DAY
+    assert parse_duration("2w") == 14 * DAY
+    assert parse_duration("12h") == 12 * 3600000
+    assert parse_duration("30m") == 30 * 60000
+    assert parse_duration("45s") == 45 * 1000
+    assert parse_duration("7") == 7 * DAY  # bare number = days
+    assert parse_duration("1.5d") == int(1.5 * DAY)
+    assert parse_duration(3) == 3 * DAY  # numeric input = days
+
+
+def test_parse_duration_rejects_garbage():
+    for bad in ("soon", "10y", ""):
+        with pytest.raises(ValueError):
+            parse_duration(bad)
+    with pytest.raises(ValueError):
+        parse_duration(-5)
+
+
+def test_age_days():
+    assert age_days(days_ago(10), NOW) == 10
+    assert age_days(NOW - (5 * DAY + 1000), NOW) == 5  # floors partial day
+    assert age_days(NOW, NOW) == 0
+    assert age_days(NOW + 5 * DAY, NOW) == 0  # future -> 0