verifygate 0.1.0__py3-none-any.whl

verifygate/__init__.py

@@ -0,0 +1,29 @@
+"""verifygate - delegate work only when a machine can tell you it was done.
+
+The rule the tool exists to enforce: an order without a verification command is
+not accepted.  Whether you can write that command is the test of whether the
+job can be handed over at all.
+
+Everything else here is about the gap between "the command exited zero" and
+"the work was done":
+
+* the baseline - a check that was already green proves nothing
+* the comment check - text parked in a comment satisfies a presence check
+  without satisfying the job
+* the diff shape - an adding job that mostly deletes is a regression
+* isolation - each run gets its own worktree and branch, so nothing lands
+  anywhere by accident and two runs cannot collide
+"""
+
+__version__ = "0.1.0"
+
+from .spec import Spec, SpecError, HOUSE_RULES          # noqa: E402,F401
+from .runner import Runner, RunResult, CommandResult     # noqa: E402,F401
+from .guards import Finding                              # noqa: E402,F401
+from . import comments, guards, gitutil                  # noqa: E402,F401
+
+__all__ = [
+    "Spec", "SpecError", "HOUSE_RULES",
+    "Runner", "RunResult", "CommandResult", "Finding",
+    "comments", "guards", "gitutil", "__version__",
+]

verifygate/cli.py

@@ -0,0 +1,310 @@
+"""Command line.
+
+    verifygate check   order.json          is this order acceptable at all?
+    verifygate run     order.json          baseline, delegate, verify, guard
+    verifygate list                        runs on record
+    verifygate show    <run-id>            what happened, and what the guards saw
+    verifygate accept  <run-id>            commit it - refuses anything that failed
+    verifygate discard <run-id>            throw the branch and the worktree away
+    verifygate guard   --keep X -- files   the comment-stash check on its own
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__, comments, gitutil, guards
+from .runner import Runner
+from .spec import Spec, SpecError
+
+
+def _store(args) -> str:
+    return args.store or os.path.join(os.path.expanduser("~"), ".verifygate", "runs")
+
+
+def _p(s: str = "") -> None:
+    try:
+        sys.stdout.write(s + "\n")
+    except UnicodeEncodeError:
+        enc = sys.stdout.encoding or "ascii"
+        sys.stdout.write(s.encode(enc, "replace").decode(enc) + "\n")
+
+
+def _utf8_stdout() -> None:
+    """Findings quote source text, which is often not ASCII.
+
+    A Windows console defaults to a legacy code page and turns a Japanese label
+    into mojibake, which makes a real finding look like a bug in the tool.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+        except (AttributeError, ValueError, OSError):
+            pass
+
+
+# ---------------------------------------------------------------- subcommands
+def cmd_check(args) -> int:
+    try:
+        spec = Spec.load(args.spec)
+    except SpecError as e:
+        _p("rejected.\n\n{}".format(e))
+        return 2
+    _p("accepted: {}".format(spec.id))
+    _p("  scope   {}".format(spec.cwd))
+    _p("  verify  {}".format(spec.verify))
+    if spec.must_keep:
+        _p("  keeps   {} string(s)".format(len(spec.must_keep)))
+    if spec.expect:
+        _p("  shape   expected to {}".format(spec.expect))
+    if args.print_order:
+        _p("")
+        _p(spec.prompt())
+    return 0
+
+
+def cmd_run(args) -> int:
+    try:
+        spec = Spec.load(args.spec)
+    except SpecError as e:
+        _p("rejected.\n\n{}".format(e))
+        return 2
+
+    runner = Runner(_store(args),
+                    implementer=(args.implementer.split() if args.implementer else None),
+                    allow_branch=tuple(args.allow_branch or ()),
+                    keep_worktree=args.keep)
+    try:
+        res = runner.run(spec, dry_run=args.dry_run)
+    except RuntimeError as e:
+        _p("refusing to start.\n\n  {}".format(e))
+        return 2
+    except gitutil.GitError as e:
+        _p("git: {}".format(e))
+        return 2
+
+    _p("run {}".format(res.run_id))
+    _p("  branch    {}".format(res.branch))
+    _p("  worktree  {}".format(res.worktree))
+    if res.baseline:
+        _p("  baseline  {} in {:.1f}s".format(
+            "passed (this check cannot show the work)" if res.baseline.ok else "failed, as it should",
+            res.baseline.seconds))
+    if args.dry_run:
+        _p("\ndry run: the implementer was not invoked.")
+        _p("The order is at {}".format(os.path.join(runner.store, res.run_id, "order.md")))
+        return 0
+    if res.implementer and not res.implementer.ok:
+        _p("  implementer exited {}".format(res.implementer.code))
+        if res.implementer.stderr.strip():
+            _p("    " + res.implementer.stderr.strip().splitlines()[-1])
+    if res.after:
+        _p("  verify    {} in {:.1f}s".format("PASS" if res.after.ok else "FAIL",
+                                              res.after.seconds))
+    _p("  diff      +{} / -{} across {} file(s)".format(
+        res.insertions, res.deletions, len(res.changed)))
+    _p("")
+    _p("guards")
+    for f in res.findings:
+        _p(f.render())
+    _p("")
+    if res.passed:
+        _p("PASSED. verifygate accept {}".format(res.run_id))
+        return 0
+    _p("NOT ACCEPTED. Nothing has been committed.")
+    _p("  verifygate show {}   to read the diff and the output".format(res.run_id))
+    return 1
+
+
+def cmd_list(args) -> int:
+    runner = Runner(_store(args))
+    ids = runner.list_runs()
+    if getattr(args, "json", False):
+        rows = []
+        for rid in ids:
+            try:
+                d = runner.load(rid)
+            except (OSError, ValueError):
+                continue
+            rows.append({
+                "run_id": d["run_id"], "passed": d["passed"],
+                "verified": d["verified"], "guards_passed": d["guards_passed"],
+                "insertions": d["insertions"], "deletions": d["deletions"],
+                "branch": d["branch"], "verify": d["spec"]["verify"],
+            })
+        _p(json.dumps(rows, ensure_ascii=False, indent=2))
+        return 0
+    if not ids:
+        _p("no runs in {}".format(runner.store))
+        return 0
+    for rid in ids:
+        try:
+            d = runner.load(rid)
+        except (OSError, ValueError):
+            continue
+        _p("{:<34} {:<7} +{}/-{}  {}".format(
+            rid, "PASSED" if d["passed"] else "held",
+            d["insertions"], d["deletions"], d["spec"]["verify"][:44]))
+    return 0
+
+
+def cmd_show(args) -> int:
+    runner = Runner(_store(args))
+    as_json = getattr(args, "json", False)
+    try:
+        d = runner.load(args.run_id)
+    except OSError:
+        if as_json:
+            _p(json.dumps({"error": "no such run", "run_id": args.run_id}))
+        else:
+            _p("no such run: {}".format(args.run_id))
+        return 2
+    if as_json:
+        # the stored record is the contract; do not rebuild it here
+        _p(json.dumps(d, ensure_ascii=False, indent=2))
+        return 0
+    _p("{}  {}".format(d["run_id"], "PASSED" if d["passed"] else "held"))
+    _p("  objective  {}".format(d["spec"]["objective"].splitlines()[0][:90]))
+    _p("  verify     {}".format(d["spec"]["verify"]))
+    _p("  branch     {}".format(d["branch"]))
+    _p("  diff       +{} / -{} across {} file(s)".format(
+        d["insertions"], d["deletions"], len(d["changed"])))
+    _p("")
+    for f in d["findings"]:
+        _p(guards.Finding(f["name"], f["status"], f["summary"], f["detail"]).render())
+    for key in ("baseline", "after"):
+        c = d.get(key)
+        if c and args.output:
+            _p("")
+            _p("--- {} (exit {}) ---".format(key, c["code"]))
+            _p((c["stdout"] or "").strip()[-4000:])
+            if (c["stderr"] or "").strip():
+                _p((c["stderr"] or "").strip()[-2000:])
+    patch = os.path.join(runner.store, args.run_id, "diff.patch")
+    if args.diff and os.path.isfile(patch):
+        _p("")
+        with open(patch, "r", encoding="utf-8", errors="replace") as f:
+            _p(f.read())
+    return 0
+
+
+def cmd_accept(args) -> int:
+    runner = Runner(_store(args))
+    try:
+        d = runner.load(args.run_id)
+        sha = runner.accept(args.run_id, gitutil.toplevel(d["spec"]["cwd"]), args.message or "")
+    except OSError:
+        _p("no such run: {}".format(args.run_id))
+        return 2
+    except RuntimeError as e:
+        _p(str(e))
+        return 1
+    _p("committed {} on {}".format(sha[:12], d["branch"]))
+    _p("A person merges it from here.")
+    return 0
+
+
+def cmd_discard(args) -> int:
+    runner = Runner(_store(args))
+    try:
+        d = runner.load(args.run_id)
+        runner.discard(args.run_id, gitutil.toplevel(d["spec"]["cwd"]))
+    except OSError:
+        _p("no such run: {}".format(args.run_id))
+        return 2
+    _p("discarded {}".format(args.run_id))
+    return 0
+
+
+def cmd_guard(args) -> int:
+    """The comment check on its own, for use inside a verify command."""
+    bad = 0
+    for path in args.files:
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                text = f.read()
+        except OSError as e:
+            _p("{}: {}".format(path, e))
+            bad += 1
+            continue
+        for needle in args.keep:
+            in_code = comments.count_in_code(text, needle, path)
+            in_comment = comments.count_in_comments(text, needle, path)
+            if in_code == 0 and in_comment > 0:
+                _p("{}: {!r} only inside a comment".format(path, needle))
+                bad += 1
+            elif in_code == 0:
+                _p("{}: {!r} not found".format(path, needle))
+                bad += 1
+    if bad:
+        _p("{} problem(s)".format(bad))
+        return 1
+    _p("ok: every string present in code")
+    return 0
+
+
+# --------------------------------------------------------------------- parser
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="verifygate",
+        description="Delegate work only when a machine can tell you it was done.")
+    ap.add_argument("--version", action="version", version="verifygate " + __version__)
+    ap.add_argument("--store", help="where runs are kept (default ~/.verifygate/runs)")
+    sub = ap.add_subparsers(dest="cmd")
+
+    c = sub.add_parser("check", help="validate an order without running it")
+    c.add_argument("spec")
+    c.add_argument("--print-order", action="store_true", help="show the text the implementer gets")
+    c.set_defaults(func=cmd_check)
+
+    r = sub.add_parser("run", help="baseline, delegate, verify, guard")
+    r.add_argument("spec")
+    r.add_argument("--dry-run", action="store_true", help="baseline only; do not delegate")
+    r.add_argument("--implementer", help="command to run instead of the Codex CLI")
+    r.add_argument("--allow-branch", action="append",
+                   help="permit a branch normally treated as deploying")
+    r.add_argument("--keep", action="store_true", help="keep the worktree after the run")
+    r.set_defaults(func=cmd_run)
+
+    li = sub.add_parser("list", help="runs on record")
+    li.add_argument("--json", action="store_true", help="print the runs as a JSON array")
+    li.set_defaults(func=cmd_list)
+
+    s = sub.add_parser("show", help="what happened in a run")
+    s.add_argument("run_id")
+    s.add_argument("--diff", action="store_true")
+    s.add_argument("--output", action="store_true", help="include the verify output")
+    s.add_argument("--json", action="store_true", help="print the run record as JSON and nothing else")
+    s.set_defaults(func=cmd_show)
+
+    a = sub.add_parser("accept", help="commit a run that passed")
+    a.add_argument("run_id")
+    a.add_argument("-m", "--message")
+    a.set_defaults(func=cmd_accept)
+
+    d = sub.add_parser("discard", help="delete a run's branch and worktree")
+    d.add_argument("run_id")
+    d.set_defaults(func=cmd_discard)
+
+    g = sub.add_parser("guard", help="check strings survive in code, not comments")
+    g.add_argument("--keep", action="append", required=True, metavar="STRING")
+    g.add_argument("files", nargs="+")
+    g.set_defaults(func=cmd_guard)
+    return ap
+
+
+def main(argv=None) -> int:
+    _utf8_stdout()
+    ap = build_parser()
+    args = ap.parse_args(argv)
+    if not getattr(args, "func", None):
+        ap.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

verifygate/comments.py

@@ -0,0 +1,180 @@
+"""Strip comments so a check counts code, not commentary.
+
+A check that asks "is this string still in the file?" is satisfied by a comment
+containing the string.  That is not a hypothetical: an implementer asked to
+keep some text while restructuring it once parked the deleted fragments in a
+block comment headed "source markers for former fragments", and the check went
+green across twenty-three files.
+
+So before counting, take the comments out.  This is a scanner, not a parser: it
+tracks string literals well enough that a URL inside a quoted string is not
+mistaken for a line comment, and it knows which comment syntaxes belong to
+which extension.  It does not understand every corner of every grammar, and it
+says so - :func:`strip` is documented as approximate, and both the strict and
+the loose reading are available so a caller can require agreement.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Sequence, Tuple
+
+#: extension -> (line comment markers, block comment pairs, string quote chars)
+_LANGS: Dict[str, Tuple[Sequence[str], Sequence[Tuple[str, str]], Sequence[str]]] = {}
+
+
+def _reg(exts, line, block, quotes):
+    for e in exts:
+        _LANGS[e] = (tuple(line), tuple(block), tuple(quotes))
+
+
+_reg([".py", ".pyi"], ["#"], [], ['"""', "'''", '"', "'"])
+_reg([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx"], ["//"], [("/*", "*/")], ['"', "'", "`"])
+_reg([".java", ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".go", ".rs", ".swift", ".kt"],
+     ["//"], [("/*", "*/")], ['"', "'"])
+_reg([".php"], ["//", "#"], [("/*", "*/"), ("<!--", "-->")], ['"', "'"])
+_reg([".css", ".scss", ".less"], [], [("/*", "*/")], ['"', "'"])
+_reg([".html", ".htm", ".xml", ".svg", ".vue", ".xhtml"], [], [("<!--", "-->")], ['"', "'"])
+_reg([".sh", ".bash", ".zsh", ".rb", ".yml", ".yaml", ".toml", ".ini", ".cfg", ".conf"],
+     ["#"], [], ['"', "'"])
+_reg([".sql"], ["--"], [("/*", "*/")], ["'", '"'])
+_reg([".ps1", ".psm1"], ["#"], [("<#", "#>")], ['"', "'"])
+
+#: used when the extension is unknown: everything plausible is treated as a comment
+_FALLBACK = (("//", "#", "--"), (("/*", "*/"), ("<!--", "-->")), ('"', "'", "`"))
+
+
+def rules_for(path: str):
+    """Comment and string rules for a path. Unknown extensions get a loose set."""
+    return _LANGS.get(os.path.splitext(path)[1].lower(), _FALLBACK)
+
+
+def strip(text: str, path: str = "", keep_strings: bool = True) -> str:
+    """Return ``text`` with comments replaced by spaces of the same length.
+
+    Lengths and line breaks are preserved so that line numbers and offsets
+    still line up with the original.
+
+    ``keep_strings=False`` also blanks string literals, which is the stricter
+    reading: it catches text parked in an unused constant, and it also blanks
+    text that is legitimately a user-visible string.  Callers that care about
+    the difference should run both and compare.
+
+    This is approximate by construction; see the module docstring.
+    """
+    line_marks, block_pairs, quotes = rules_for(path)
+    # longest first so "///" and '"""' win over their prefixes
+    line_marks = tuple(sorted(line_marks, key=len, reverse=True))
+    quotes = tuple(sorted(quotes, key=len, reverse=True))
+    block_pairs = tuple(block_pairs)
+
+    out: List[str] = []
+    i = 0
+    n = len(text)
+    while i < n:
+        ch = text[i]
+
+        # inside a string literal: copy it out (or blank it) and skip to the end
+        q = _starts_with_any(text, i, quotes)
+        if q:
+            j = _end_of_string(text, i + len(q), q)
+            chunk = text[i:j]
+            out.append(chunk if keep_strings else _blank(chunk))
+            i = j
+            continue
+
+        pair = _starts_with_block(text, i, block_pairs)
+        if pair:
+            open_s, close_s = pair
+            end = text.find(close_s, i + len(open_s))
+            end = n if end == -1 else end + len(close_s)
+            out.append(_blank(text[i:end]))
+            i = end
+            continue
+
+        m = _starts_with_any(text, i, line_marks)
+        if m:
+            end = text.find("\n", i)
+            end = n if end == -1 else end
+            out.append(_blank(text[i:end]))
+            i = end
+            continue
+
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _blank(s: str) -> str:
+    return "".join("\n" if c == "\n" else " " for c in s)
+
+
+def _starts_with_any(text: str, i: int, marks: Sequence[str]):
+    for m in marks:
+        if m and text.startswith(m, i):
+            return m
+    return None
+
+
+def _starts_with_block(text: str, i: int, pairs):
+    for open_s, close_s in pairs:
+        if text.startswith(open_s, i):
+            return (open_s, close_s)
+    return None
+
+
+def _end_of_string(text: str, i: int, quote: str) -> int:
+    """Index just past the closing quote (or end of text)."""
+    n = len(text)
+    while i < n:
+        c = text[i]
+        if c == "\\":
+            i += 2
+            continue
+        if text.startswith(quote, i):
+            return i + len(quote)
+        # a single-character quote does not survive a newline in most languages
+        if len(quote) == 1 and c == "\n" and quote in ("'", '"'):
+            return i
+        i += 1
+    return n
+
+
+def literals(text: str, path: str = "", min_len: int = 3) -> List[str]:
+    """Contents of the string literals in ``text``, outside comments.
+
+    Quoted text is what actually gets parked: a label is lifted out of the code
+    and dropped into a comment so that a "the wording is still there" check
+    stays green.  Comparing literals before and after catches that even when
+    the surrounding line was rewritten.
+    """
+    code = strip(text, path)
+    _, _, quotes = rules_for(path)
+    quotes = tuple(sorted(quotes, key=len, reverse=True))
+    out: List[str] = []
+    i, n = 0, len(code)
+    while i < n:
+        q = _starts_with_any(code, i, quotes)
+        if not q:
+            i += 1
+            continue
+        j = _end_of_string(code, i + len(q), q)
+        body = code[i + len(q): max(i + len(q), j - len(q))]
+        if len(body.strip()) >= min_len:
+            out.append(body)
+        i = j
+    return out
+
+
+def count_in_code(text: str, needle: str, path: str = "") -> int:
+    """How many times ``needle`` appears outside comments."""
+    if not needle:
+        return 0
+    return strip(text, path).count(needle)
+
+
+def count_in_comments(text: str, needle: str, path: str = "") -> int:
+    """How many times ``needle`` appears *only* inside comments."""
+    if not needle:
+        return 0
+    return text.count(needle) - count_in_code(text, needle, path)

verifygate/gitutil.py

@@ -0,0 +1,162 @@
+"""The small amount of git this needs, with the sharp edges filed off.
+
+Two habits are enforced here rather than left to the caller:
+
+* ``git add -A`` is never used.  Working copies get shared - with another
+  agent, another session, a person - and a blanket add sweeps someone else's
+  unfinished work into your commit.  Paths are always named.
+* A run never starts on a branch that deploys.  Somewhere there is a repository
+  where pushing to ``main`` publishes a website within seconds, and the cost of
+  finding that out during an automated run is a broken site.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import List, Optional, Sequence, Tuple
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def run(args: Sequence[str], cwd: str, check: bool = True, timeout: int = 120) -> str:
+    p = subprocess.run(
+        ["git"] + list(args), cwd=cwd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=timeout,
+    )
+    if check and p.returncode != 0:
+        raise GitError("git {}: {}".format(" ".join(args), (p.stderr or p.stdout).strip()))
+    return p.stdout
+
+
+def is_repo(cwd: str) -> bool:
+    try:
+        return run(["rev-parse", "--is-inside-work-tree"], cwd).strip() == "true"
+    except (GitError, OSError):
+        return False
+
+
+def current_branch(cwd: str) -> str:
+    return run(["rev-parse", "--abbrev-ref", "HEAD"], cwd).strip()
+
+
+def head(cwd: str) -> str:
+    return run(["rev-parse", "HEAD"], cwd).strip()
+
+
+def toplevel(cwd: str) -> str:
+    return run(["rev-parse", "--show-toplevel"], cwd).strip()
+
+
+def is_clean(cwd: str) -> bool:
+    return run(["status", "--porcelain"], cwd).strip() == ""
+
+
+def status_paths(cwd: str) -> List[Tuple[str, str]]:
+    """[(status, path)] for every changed or untracked path."""
+    out = []
+    for line in run(["status", "--porcelain"], cwd).splitlines():
+        if len(line) < 4:
+            continue
+        code, path = line[:2].strip() or "??", line[3:].strip()
+        if " -> " in path:                     # renames
+            path = path.split(" -> ", 1)[1]
+        out.append((code, path.strip('"')))
+    return out
+
+
+def diff(cwd: str, ref: Optional[str] = None, paths: Optional[Sequence[str]] = None) -> str:
+    args = ["diff"]
+    if ref:
+        args.append(ref)
+    args += ["--no-color"]
+    if paths:
+        args += ["--"] + list(paths)
+    return run(args, cwd, check=False)
+
+
+def diff_numstat(cwd: str, ref: Optional[str] = None) -> List[Tuple[int, int, str]]:
+    """[(insertions, deletions, path)]. Binary files report -1, -1."""
+    args = ["diff", "--numstat"]
+    if ref:
+        args.append(ref)
+    out = []
+    for line in run(args, cwd, check=False).splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        a, d, path = parts
+        out.append((-1 if a == "-" else int(a), -1 if d == "-" else int(d), path.strip()))
+    return out
+
+
+def file_at(cwd: str, ref: str, path: str) -> Optional[str]:
+    """Contents of ``path`` at ``ref``, or None if it did not exist there."""
+    p = subprocess.run(
+        ["git", "show", "{}:{}".format(ref, path)], cwd=cwd,
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+    )
+    return None if p.returncode != 0 else p.stdout
+
+
+def add_paths(cwd: str, paths: Sequence[str]) -> None:
+    """Stage exactly these paths. There is deliberately no 'add everything'."""
+    if not paths:
+        return
+    run(["add", "--"] + list(paths), cwd)
+
+
+def stash_push(cwd: str, message: str) -> bool:
+    """Set the working tree aside. True if something was actually stashed."""
+    before = run(["stash", "list"], cwd).count("\n")
+    run(["stash", "push", "--include-untracked", "-m", message], cwd, check=False)
+    return run(["stash", "list"], cwd).count("\n") > before
+
+
+def stash_pop(cwd: str) -> None:
+    run(["stash", "pop"], cwd, check=False)
+
+
+DEPLOYING_BRANCHES = ("main", "master", "production", "prod", "release")
+
+
+def refuses_to_run_here(cwd: str, allow: Sequence[str] = ()) -> Optional[str]:
+    """Why this working copy must not be worked in directly, or None."""
+    if not is_repo(cwd):
+        return "not a git repository: {}".format(cwd)
+    branch = current_branch(cwd)
+    if branch in DEPLOYING_BRANCHES and branch not in allow:
+        return (
+            "on branch '{}'. Work is not done on a branch that deploys.\n"
+            "  Check out a working branch first, or pass --allow-branch {} if this\n"
+            "  repository really does not publish from it.".format(branch, branch)
+        )
+    return None
+
+
+def worktree_add(repo: str, path: str, branch: str, base: str) -> None:
+    run(["worktree", "add", "-b", branch, path, base], repo)
+
+
+def worktree_remove(repo: str, path: str, force: bool = True) -> None:
+    args = ["worktree", "remove"]
+    if force:
+        args.append("--force")
+    args.append(path)
+    run(args, repo, check=False)
+
+
+def worktree_list(repo: str) -> List[str]:
+    out = []
+    for line in run(["worktree", "list", "--porcelain"], repo, check=False).splitlines():
+        if line.startswith("worktree "):
+            out.append(line[len("worktree "):].strip())
+    return out
+
+
+def rel_to_top(cwd: str, path: str) -> str:
+    top = os.path.abspath(toplevel(cwd))
+    ap = os.path.abspath(path)
+    return os.path.relpath(ap, top).replace("\\", "/")