lockmaster 0.0.1__py3-none-any.whl

lockmaster/__init__.py

@@ -0,0 +1,3 @@
+"""lockmaster — lands AI-agent changes into main one at a time (SR-ARCHITECTURE)."""
+
+__version__ = "0.0.1"

lockmaster/__main__.py

@@ -0,0 +1,3 @@
+from lockmaster.cli import main
+
+raise SystemExit(main())

lockmaster/cli.py

@@ -0,0 +1,225 @@
+"""The `lockmaster` command — SR-ARCHITECTURE decision 14.
+
+Python >= 3.9, standard library only (decision 2). Exit codes: 0 done, 1 a
+change went red or a check found a problem, 2 refused or misused.
+"""
+import argparse
+import os
+import sys
+
+from lockmaster import __version__
+
+# command -> what it does (decision 14's table)
+COMMANDS = {
+    "start": "branch + worktree + claim for a work item",
+    "claim": "widen the claim: claim add <path>…",
+    "submit": "commit the claimed paths, join the queue, start landing",
+    "run": "land queued changes, one at a time",
+    "queue": "what is waiting, landed or red",
+    "status": "live sessions, changes, worktrees, disk use; --now prints work/NOW.md",
+    "abandon": "drop a change; remove its worktree only if nothing is lost",
+    "save": "land edits made in main's checkout; hand them to Claude Code where this surface cannot commit",
+    "pickup": "land the edits other surfaces handed over",
+    "sync": "land this session's open changes now (the kit's hooks, at the end of a turn)",
+    "can-commit": "say whether this surface can commit (exit 0) or must hand off (exit 1)",
+    "doctor": "stale locks, orphan worktrees, unmerged branches, kit mismatch",
+    "install": "install the kit into a repository, pinned",
+    "regen": "rebuild the generated files lockmaster.toml lists",
+    "drivers": "register the structural merge drivers; write .gitattributes from [merge]",
+    "merge-driver": "what git runs for a structural merge (installed by `drivers`)",
+}
+
+
+def _parser():
+    p = argparse.ArgumentParser(prog="lockmaster",
+                                description="Lands AI-agent changes into main one at a time, without ever losing work.")
+    p.add_argument("--version", action="version", version="lockmaster " + __version__)
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    s = sub.add_parser("start", help=COMMANDS["start"])
+    s.add_argument("item")
+    s.add_argument("--paths", nargs="+", required=True, metavar="PATH")
+
+    s = sub.add_parser("claim", help=COMMANDS["claim"])
+    s.add_argument("action", choices=["add"])
+    s.add_argument("paths", nargs="+")
+    s.add_argument("--item")
+
+    s = sub.add_parser("submit", help=COMMANDS["submit"])
+    s.add_argument("-m", "--message", default="")
+    s.add_argument("--item")
+    s.add_argument("--no-run", action="store_true", help="queue only; do not start landing")
+
+    sub.add_parser("run", help=COMMANDS["run"])
+    sub.add_parser("queue", help=COMMANDS["queue"])
+
+    s = sub.add_parser("status", help=COMMANDS["status"])
+    s.add_argument("--now", action="store_true", help="print work/NOW.md as it should be")
+    s.add_argument("--write-now", action="store_true", help="write work/NOW.md")
+
+    s = sub.add_parser("abandon", help=COMMANDS["abandon"])
+    s.add_argument("--item")
+
+    s = sub.add_parser("save", help=COMMANDS["save"])
+    s.add_argument("paths", nargs="+", metavar="PATH")
+    s.add_argument("-m", "--message", required=True)
+    s.add_argument("--item", help="the work item, when there is one (default: save-<time>)")
+    s.add_argument("--by", default="", help="who hands it over, for the record (e.g. \"Cowork\")")
+    s.add_argument("--handoff", action="store_true", help="hand off even where this surface could commit")
+
+    sub.add_parser("pickup", help=COMMANDS["pickup"])
+
+    s = sub.add_parser("sync", help=COMMANDS["sync"])
+    s.add_argument("--session", default="")
+    s.add_argument("--cwd", default="")
+    s.add_argument("--final", action="store_true", help="the session is ending: land and clean up")
+    s.add_argument("--no-adopt", action="store_true", help="do not adopt a worktree lockmaster did not create")
+    s.add_argument("--pickup", action="store_true", help="then land the handoffs too")
+
+    sub.add_parser("can-commit", help=COMMANDS["can-commit"])
+
+    sub.add_parser("doctor", help=COMMANDS["doctor"])
+
+    s = sub.add_parser("install", help=COMMANDS["install"])
+    s.add_argument("repo", nargs="?", default=".")
+    s.add_argument("--backup", action="store_true",
+                   help="move each file the kit would replace aside to <file>.pre-lockmaster")
+
+    sub.add_parser("regen", help=COMMANDS["regen"])
+    sub.add_parser("drivers", help=COMMANDS["drivers"])
+
+    s = sub.add_parser("merge-driver", help=COMMANDS["merge-driver"])
+    s.add_argument("args", nargs=argparse.REMAINDER)
+    return p
+
+
+def main(argv=None):
+    from lockmaster.config import ConfigError
+    from lockmaster.repo import LockmasterError
+
+    args = _parser().parse_args(argv)
+    if not args.command:
+        _parser().print_help()
+        return 0
+    try:
+        return _dispatch(args)
+    except (LockmasterError, ConfigError) as e:
+        print("lockmaster {}: {}".format(args.command, e), file=sys.stderr)
+        return 2
+
+
+def _out(text):
+    print(text)
+
+
+def _save(repo, args):
+    from lockmaster import land, surface
+    paths = land._relative(repo, args.paths)
+    ok, why = (False, "asked to hand off") if args.handoff else surface.can_commit(repo)
+    if ok:
+        change = land.save(repo, paths, args.message, item=args.item, out=_out)
+        if change is None:
+            print("nothing uncommitted under " + ", ".join(paths))
+            return 0
+        return 1 if change["status"] == "red" else 0
+    h = land.handoff(repo, paths, args.message, item=args.item, by=args.by)
+    if h is None:
+        print("nothing uncommitted under " + ", ".join(paths))
+        return 0
+    print("handed off {}: {} file{} ({}).".format(h["item"], len(h["files"]), "s" * (len(h["files"]) != 1), why))
+    print("The next Claude Code session in this repository lands it — nothing else to do here.")
+    return 0
+
+
+def _dispatch(args):
+    from lockmaster import land
+    from lockmaster.repo import Repo
+
+    if args.command == "merge-driver":
+        from lockmaster import merge
+        return merge.main(args.args)
+    if args.command == "install":
+        from lockmaster import install
+        install.install(args.repo, backup=args.backup, out=_out)
+        return 0
+
+    repo = Repo(os.getcwd())
+    if args.command == "start":
+        change, overlaps = land.start(repo, args.item, args.paths, os.environ.get("CLAUDE_SESSION_ID", ""))
+        print("started {} on {}: work in {}".format(change["item"], change["branch"], change["worktree"]))
+        print("claim: " + ", ".join(change["paths"]))
+        for other, path in overlaps:
+            print("note: {} also claims {} — whichever lands second may go red".format(other, path))
+        return 0
+    if args.command == "claim":
+        change = land.claim_add(repo, repo.current_change(args.item), args.paths)
+        print("claim of {}: {}".format(change["item"], ", ".join(change["paths"])))
+        return 0
+    if args.command == "submit":
+        change = land.submit(repo, repo.current_change(args.item), args.message, out=_out)
+        print("queued " + change["item"])
+        if args.no_run:
+            return 0
+        land.run(repo, out=_out)
+        return 1 if repo.load(change["item"])["status"] == "red" else 0
+    if args.command == "run":
+        land.run(repo, out=_out)
+        return 0
+    if args.command == "queue":
+        print("\n".join(land.queue_lines(repo)))
+        return 0
+    if args.command == "abandon":
+        land.abandon(repo, repo.current_change(args.item), out=_out)
+        return 0
+    if args.command == "save":
+        return _save(repo, args)
+    if args.command == "pickup":
+        results = land.pickup(repo, out=_out)
+        if not results:
+            print("no handoffs")
+        return 1 if any(r in ("red", "failed") for _, r, _ in results) else 0
+    if args.command == "sync":
+        queued = land.sync(repo, session=args.session or os.environ.get("CLAUDE_SESSION_ID", ""),
+                           cwd=args.cwd or None, final=args.final, adopt_cwd=not args.no_adopt, out=_out)
+        if not queued:
+            print("nothing to land")
+        if args.pickup:
+            land.pickup(repo, out=_out)
+        return 0
+    if args.command == "can-commit":
+        from lockmaster import surface
+        ok, why = surface.can_commit(repo)
+        print("yes — this surface lands its own changes" if ok else "no — {}; `lockmaster save` hands "
+              "edits to the next Claude Code session".format(why))
+        return 0 if ok else 1
+    if args.command == "status":
+        from lockmaster import now, status
+        if args.write_now:
+            print("work/NOW.md " + ("written" if now.write_if_present(repo) else "not kept here"))
+            return 0
+        if args.now:
+            sys.stdout.write(status.now_text(repo))
+            return 0
+        print("\n".join(status.report(repo)))
+        return 0
+    if args.command == "doctor":
+        from lockmaster import doctor
+        problems = doctor.check(repo)
+        print("\n".join(problems) if problems else "all well")
+        return 1 if problems else 0
+    if args.command == "regen":
+        from lockmaster import generated
+        done = generated.regen(repo.toplevel, repo.config)
+        print("rebuilt: " + (", ".join(done) if done else "nothing — lockmaster.toml lists no [generated] paths"))
+        return 0
+    if args.command == "drivers":
+        from lockmaster import drivers
+        changed = drivers.install(repo)
+        print("merge drivers registered in .git/config"
+              + ("; .gitattributes written — commit it" if changed else ""))
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lockmaster/config.py

@@ -0,0 +1,195 @@
+"""`lockmaster.toml` — SR-ARCHITECTURE decision 13.
+
+    [main]
+    branch = "main"                          # the branch lockmaster lands onto
+
+    [checks]                                 # name = command; every one must pass
+    tests = "python3 -m unittest discover -s tests"
+
+    [generated]                              # path or glob = the command that rebuilds it
+    "CHANGELOG.md" = "python3 scripts/changelog.py"
+
+    [merge]                                  # path or glob = structural driver
+    "work/WORKLOG.md" = "append-newest-first"
+
+    [land]                                   # optional
+    auto = "on"                              # "off": no landing at the end of a turn (decision 20)
+
+Read with `tomllib` on Python >= 3.11 and with the subset reader below on
+3.9-3.10. Both feed the same validation, so a file means the same thing on
+every Python: four tables of string values and nothing else. Anything outside
+that subset is a loud error, never a guess (W-03 hazard).
+"""
+import re
+
+DRIVERS = ("append-newest-first", "table-rows", "append")
+TABLES = ("main", "checks", "generated", "merge", "land")
+AUTO = ("on", "off")
+FILENAME = "lockmaster.toml"
+
+
+class ConfigError(Exception):
+    pass
+
+
+class Config:
+    def __init__(self, main="main", checks=None, generated=None, merge=None, auto="on"):
+        self.main = main
+        self.auto_land = auto == "on"
+        self.checks = dict(checks or {})
+        self.generated = dict(generated or {})
+        self.merge = dict(merge or {})
+
+    def as_dict(self):
+        return {"main": {"branch": self.main}, "checks": self.checks,
+                "generated": self.generated, "merge": self.merge,
+                "land": {"auto": "on" if self.auto_land else "off"}}
+
+
+# ---------------------------------------------------------------- the subset reader
+
+_BARE = re.compile(r"[A-Za-z0-9_-]+")
+_ESCAPES = {"b": "\b", "t": "\t", "n": "\n", "f": "\f", "r": "\r", '"': '"', "\\": "\\"}
+
+
+def _string(s, i, where):
+    """Parse a basic ("...") or literal ('...') string at s[i]; return (value, next index)."""
+    q = s[i]
+    if s.startswith(q * 3, i):
+        raise ConfigError(where + ": multi-line strings are outside lockmaster.toml's subset")
+    i += 1
+    buf = []
+    while i < len(s):
+        c = s[i]
+        if c == q:
+            return "".join(buf), i + 1
+        if q == '"' and c == "\\":
+            nxt = s[i + 1:i + 2]
+            if nxt in _ESCAPES:
+                buf.append(_ESCAPES[nxt])
+                i += 2
+                continue
+            if nxt in ("u", "U"):
+                n = 4 if nxt == "u" else 8
+                hexs = s[i + 2:i + 2 + n]
+                if not re.fullmatch(r"[0-9A-Fa-f]{%d}" % n, hexs):
+                    raise ConfigError(where + ": bad \\" + nxt + " escape")
+                buf.append(chr(int(hexs, 16)))
+                i += 2 + n
+                continue
+            raise ConfigError(where + ": unknown escape \\" + nxt)
+        buf.append(c)
+        i += 1
+    raise ConfigError(where + ": unterminated string")
+
+
+def _rest_is_comment(s, i, where):
+    rest = s[i:].strip()
+    if rest and not rest.startswith("#"):
+        raise ConfigError(where + ": unexpected `" + rest + "`")
+
+
+def parse_subset(text):
+    """The subset of TOML lockmaster.toml uses: `[table]` headers and
+    `key = "string"` pairs, keys bare or quoted, comments. Returns nested dicts
+    shaped like tomllib's result."""
+    data, table = {}, None
+    for n, raw in enumerate(text.splitlines(), 1):
+        where = "lockmaster.toml line {}".format(n)
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("["):
+            m = re.match(r"\[\s*([A-Za-z0-9_-]+)\s*\]", line)
+            if not m or line.startswith("[["):
+                raise ConfigError(where + ": only plain `[table]` headers are in the subset")
+            _rest_is_comment(line, m.end(), where)
+            name = m.group(1)
+            if name in data:
+                raise ConfigError(where + ": table [" + name + "] appears twice")
+            table = data[name] = {}
+            continue
+        if table is None:
+            raise ConfigError(where + ": a key outside any [table]")
+        if line[0] in "\"'":
+            key, i = _string(line, 0, where)
+        else:
+            m = _BARE.match(line)
+            if not m:
+                raise ConfigError(where + ": cannot read a key here")
+            key, i = m.group(0), m.end()
+        while i < len(line) and line[i] in " \t":
+            i += 1
+        if line[i:i + 1] == ".":
+            raise ConfigError(where + ": dotted keys are outside the subset")
+        if line[i:i + 1] != "=":
+            raise ConfigError(where + ": expected `=` after the key")
+        i += 1
+        while i < len(line) and line[i] in " \t":
+            i += 1
+        if line[i:i + 1] not in ("\"", "'"):
+            raise ConfigError(where + ": only string values are in the subset (got `" + line[i:] + "`)")
+        value, i = _string(line, i, where)
+        _rest_is_comment(line, i, where)
+        if key in table:
+            raise ConfigError(where + ": key `" + key + "` appears twice")
+        table[key] = value
+    return data
+
+
+# ---------------------------------------------------------------- one validation
+
+def parse(text):
+    try:
+        import tomllib  # Python >= 3.11
+    except ImportError:
+        data = parse_subset(text)
+    else:
+        try:
+            data = tomllib.loads(text)
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigError("lockmaster.toml: " + str(e))
+        # Valid TOML that 3.9 would refuse is refused here too: same file, same result.
+        if parse_subset(text) != data:
+            raise ConfigError("lockmaster.toml: uses TOML outside lockmaster's subset")
+    return validate(data)
+
+
+def validate(data):
+    for name, table in data.items():
+        if name not in TABLES:
+            raise ConfigError("lockmaster.toml: unknown table [" + name + "]; the tables are "
+                              + ", ".join("[" + t + "]" for t in TABLES))
+        if not isinstance(table, dict):
+            raise ConfigError("lockmaster.toml: `" + name + "` must be a [table]")
+        for key, value in table.items():
+            if not isinstance(value, str):
+                raise ConfigError("lockmaster.toml: [{}] {} is not a string; only strings are in "
+                                  "the subset".format(name, key))
+    main = data.get("main", {})
+    extra = set(main) - {"branch"}
+    if extra:
+        raise ConfigError("lockmaster.toml: [main] knows only `branch` (got " + ", ".join(sorted(extra)) + ")")
+    merge = data.get("merge", {})
+    for path, driver in merge.items():
+        if driver not in DRIVERS:
+            raise ConfigError("lockmaster.toml: [merge] {} = \"{}\" is no driver; the drivers are {}".format(
+                path, driver, ", ".join(DRIVERS)))
+    land = data.get("land", {})
+    extra = set(land) - {"auto"}
+    if extra:
+        raise ConfigError("lockmaster.toml: [land] knows only `auto` (got " + ", ".join(sorted(extra)) + ")")
+    auto = land.get("auto", "on")
+    if auto not in AUTO:
+        raise ConfigError("lockmaster.toml: [land] auto = \"{}\"; it is \"on\" or \"off\"".format(auto))
+    return Config(main.get("branch", "main"), data.get("checks"), data.get("generated"), merge, auto)
+
+
+def load(path):
+    """The Config at `path`, or the defaults when there is no file."""
+    try:
+        with open(str(path), encoding="utf-8") as fh:
+            text = fh.read()
+    except FileNotFoundError:
+        return Config()
+    return parse(text)

lockmaster/doctor.py

@@ -0,0 +1,146 @@
+"""`lockmaster doctor` — SR-ARCHITECTURE decision 14: stale locks, orphan
+worktrees, unmerged branches, and an installed kit that does not match this
+lockmaster's. Read-only: it says what is wrong and what to type, and fixes nothing.
+"""
+import os
+
+from lockmaster import __version__
+from lockmaster import git
+from lockmaster import install as install_mod
+from lockmaster.merge import DRIVERS
+from lockmaster.repo import LANDING, LIVE, WORKTREES_DIR, LandLock
+
+
+def check(repo):
+    """One line per problem found; empty when all is well."""
+    out = []
+    lock = LandLock(repo)
+    if lock.stale():
+        out.append("stale land lock {} (holder {} is not running) — the next `lockmaster run` takes it over".format(
+            lock.dir, lock.holder() or "unknown"))
+    landing = repo.state / "landing"
+    if landing.is_dir():
+        for d in sorted(landing.iterdir()):
+            out.append("a landing worktree was left behind: {} — `git worktree remove` it once you have "
+                       "looked".format(d))
+
+    changes = repo.changes()
+    live = [c for c in changes if c["status"] in LIVE]
+    for c in live:
+        if not os.path.isdir(c["worktree"]):
+            out.append("change {} is {} but its worktree {} is gone — `lockmaster abandon --item {}`".format(
+                c["item"], c["status"], c["worktree"], c["item"]))
+        if c["status"] == LANDING and not lock.dir.is_dir():
+            out.append("change {} was landing when its lander stopped — `lockmaster run` queues it again".format(
+                c["item"]))
+
+    from lockmaster import land
+    for item, st, paths in land.checkout_overlaps(repo):  # W-10 step 3
+        out.append("main's checkout has uncommitted edits to {} that change {} ({}) claims — its landing "
+                   "waits until they are committed elsewhere, saved (`lockmaster save`) or undone".format(
+                       ", ".join(paths), item, st))
+    for c in live:
+        if c["status"] == "waiting":
+            out.append("change {} is waiting: {}".format(c["item"], (c.get("reason") or "").splitlines()[0]))
+
+    # A landed or abandoned change whose cleanup kept something: kept on purpose, nothing lost.
+    kept = [c for c in changes if c["status"] not in LIVE and c.get("cleanup")
+            and (os.path.isdir(c["worktree"]) or git.ok(["rev-parse", "--verify", "--quiet",
+                                                         "refs/heads/" + c["branch"]], repo.root))]
+    for c in kept:
+        out.append("change {} is {}, and its cleanup kept: {} — look, then `git worktree remove` and "
+                   "`git branch -d` by hand, or the decider rules (SR-WORK-CLEANUP decision 3)".format(
+                       c["item"], c["status"], "; ".join(c["cleanup"])))
+
+    owned = {os.path.realpath(c["worktree"]) for c in live + kept}
+    root_wt = os.path.realpath(str(repo.root / WORKTREES_DIR))
+    for t in git.worktrees(repo.root):
+        p = os.path.realpath(t["path"])
+        if p.startswith(root_wt + os.sep) and p not in owned:
+            out.append("orphan worktree {} [{}]: no live change owns it".format(t["path"], t["branch"] or "detached"))
+
+    live_branches = {c["branch"] for c in live + kept}
+    for b in git.out(["for-each-ref", "--format=%(refname:short)", "refs/heads/lm/"], repo.root).split():
+        if b in live_branches:
+            continue
+        if git.ok(["merge-base", "--is-ancestor", b, repo.main], repo.root):
+            out.append("branch {} is in {} and no change owns it — `git branch -d {}`".format(b, repo.main, b))
+        else:
+            out.append("unmerged branch {}: no live change owns it and its commits are not in {} — "
+                       "the decider rules (SR-WORK-CLEANUP decision 3)".format(b, repo.main))
+
+    if repo.config.merge:
+        missing = [d for d in DRIVERS
+                   if not git.ok(["config", "--get", "merge.lockmaster-{}.driver".format(d)], repo.root)]
+        if missing:
+            out.append("merge drivers not registered ({}) — `lockmaster drivers`".format(", ".join(missing)))
+        from lockmaster import drivers as drivers_mod
+        stale = drivers_mod.stale(repo)
+        if stale:
+            out.append("merge drivers registered with another machine's paths ({}) — the next landing re-points "
+                       "them, or `lockmaster drivers`".format(", ".join(stale)))
+
+    out += kit_problems(repo.root)
+    out += work_problems(repo)
+    return out
+
+
+# SR-LAW-10 / W-15: this many landings on main with no WORKLOG.md change reads as drift.
+STALE_LANDINGS = 10
+
+
+def work_problems(repo):
+    """A missing work file, and a worklog main has moved past (SR-LAW-10). Only
+    where the kit is installed; whether a lesson, a machine quirk or a backlog
+    row should have been written is judgment, never checked here."""
+    if not install_mod.read_lock(repo.root):
+        return []
+    out = []
+    missing = [f for f in install_mod.WORK_FILES if not (repo.root / "work" / f).is_file()]
+    if missing:
+        out.append("work file{} missing: {} — `lockmaster install {}` creates {} (SR-LAW-10)".format(
+            "s" * (len(missing) > 1), ", ".join("work/" + f for f in missing), repo.root,
+            "them" if len(missing) > 1 else "it"))
+    if "WORKLOG.md" not in missing:
+        n = landings_since_worklog(repo)
+        if n is not None and n > STALE_LANDINGS:
+            out.append("work/WORKLOG.md is stale: {} commits on {} since it last changed (more than {}) — "
+                       "each session appends an entry (SR-LAW-10)".format(n, repo.main, STALE_LANDINGS))
+    return out
+
+
+def landings_since_worklog(repo):
+    """First-parent commits on main since the last one that changed work/WORKLOG.md;
+    None when main has no commit that did."""
+    code, last, _ = git.run(["log", "-1", "--format=%H", repo.main, "--", "work/WORKLOG.md"], repo.root, check=False)
+    last = last.strip()
+    if code != 0 or not last:
+        return None
+    code, n, _ = git.run(["rev-list", "--count", "--first-parent", last + ".." + repo.main], repo.root, check=False)
+    return int(n.strip()) if code == 0 and n.strip().isdigit() else None
+
+
+def kit_problems(root):
+    lock = install_mod.read_lock(root)
+    if not lock:
+        if (root / ".claude" / "hooks").is_dir():
+            return ["the kit in .claude/ was not installed by `lockmaster install` (no {})".format(install_mod.LOCK)]
+        return []
+    out = []
+    try:
+        kit = install_mod.find_kit()
+    except Exception:  # noqa: BLE001 — no kit to compare against is not a problem of the repo
+        kit = None
+    if lock.get("version") != __version__:
+        out.append("installed kit is from lockmaster {}, this is {} — `lockmaster install {}`".format(
+            lock.get("version"), __version__, root))
+    elif kit is not None and lock.get("kit") != install_mod.kit_digest(kit):
+        out.append("installed kit {} differs from this lockmaster's {} — `lockmaster install {}`".format(
+            (lock.get("kit") or "?")[:12], install_mod.kit_digest(kit)[:12], root))
+    for rel, digest in sorted(lock.get("files", {}).items()):
+        f = root / rel
+        if not f.is_file():
+            out.append("installed file missing: " + rel)
+        elif install_mod.sha(f) != digest:
+            out.append("installed file edited by hand: {} — edit the kit, then reinstall".format(rel))
+    return out

lockmaster/drivers.py

@@ -0,0 +1,93 @@
+"""Installing the structural merge drivers — SR-ARCHITECTURE decision 10.
+
+Each driver is registered in the repository's `.git/config` as
+`merge.lockmaster-<driver>`, and `.gitattributes` gets one line per
+`lockmaster.toml` `[merge]` path, inside a block lockmaster owns. Usable from
+plain git: `git merge` and `git cherry-pick` call the drivers too.
+"""
+import shlex
+import sys
+from pathlib import Path
+
+from lockmaster import git
+from lockmaster.merge import DRIVERS
+
+BEGIN = "# lockmaster:begin — written by `lockmaster drivers` from lockmaster.toml [merge]; edit that, not this"
+END = "# lockmaster:end"
+
+
+def driver_command(name):
+    script = Path(__file__).with_name("merge.py").resolve()
+    return "{} {} {} %O %A %B %P".format(shlex.quote(sys.executable), shlex.quote(str(script)), name)
+
+
+def attributes_block(merge):
+    lines = [BEGIN]
+    for path, driver in merge.items():
+        if any(c.isspace() for c in path):
+            raise ValueError("a [merge] path with whitespace cannot go into .gitattributes: " + path)
+        lines.append("{} merge=lockmaster-{}".format(path, driver))
+    return lines + [END]
+
+
+def write_attributes(root, merge):
+    """Replace lockmaster's block in `.gitattributes` (or add it); everything
+    else in the file is kept as it is. Returns True when the file changed."""
+    path = Path(root) / ".gitattributes"
+    old = path.read_text(encoding="utf-8") if path.exists() else ""
+    lines = old.splitlines()
+    if BEGIN.split(" —")[0] in "\n".join(lines):
+        start = next(i for i, l in enumerate(lines) if l.startswith(BEGIN.split(" —")[0]))
+        end = next((i for i in range(start, len(lines)) if lines[i] == END), len(lines) - 1)
+        lines = lines[:start] + lines[end + 1:]
+    while lines and not lines[-1].strip():
+        lines.pop()
+    block = attributes_block(merge) if merge else []
+    new_lines = lines + ([""] if lines and block else []) + block
+    new = "\n".join(new_lines) + ("\n" if new_lines else "")
+    if new == old:
+        return False
+    if new:
+        path.write_text(new, encoding="utf-8")
+    elif path.exists():
+        path.write_text("", encoding="utf-8")
+    return True
+
+
+def stale(repo):
+    """The drivers whose registered command cannot run on this machine — its
+    interpreter or merge.py is missing here, as when `install` ran on another
+    surface (the Cowork bridge sees the repository at another path). Only
+    drivers that are registered count; an unregistered one is `doctor`'s."""
+    out = []
+    for name in DRIVERS:
+        code, cmd, _ = git.run(["config", "--get", "merge.lockmaster-{}.driver".format(name)], repo.root,
+                               check=False)
+        if code != 0:
+            continue
+        try:
+            words = shlex.split(cmd.strip())
+        except ValueError:
+            words = []
+        if len(words) < 2 or not Path(words[0]).exists() or not Path(words[1]).exists():
+            out.append(name)
+    return out
+
+
+def heal(repo):
+    """Re-register the drivers when their command points at another machine's
+    paths (SR-ARCHITECTURE decision 10). Returns the drivers re-pointed."""
+    names = stale(repo)
+    for name in names:
+        git.run(["config", "merge.lockmaster-{}.driver".format(name), driver_command(name)], repo.root)
+    return names
+
+
+def install(repo):
+    """Register every driver in .git/config; write .gitattributes from [merge]."""
+    for name in DRIVERS:
+        key = "merge.lockmaster-" + name
+        git.run(["config", key + ".name", "lockmaster " + name + " (SR-ARCHITECTURE decision 10)"], repo.root)
+        git.run(["config", key + ".driver", driver_command(name)], repo.root)
+    changed = write_attributes(repo.root, repo.config.merge)
+    return changed