raidlock 0.1.0__py3-none-any.whl

raidlock/core/repos.py

@@ -0,0 +1,250 @@
+import os
+import re
+from urllib.parse import urlsplit
+
+from . import paths as P
+from . import store
+
+_SCP = re.compile(r"^(?:[^@/]+@)?([^:/]+):(?!//)(.+)$")
+_REMOTE = re.compile(r'^\s*\[remote\s+"([^"]+)"\]\s*$')
+_URL = re.compile(r"^\s*url\s*=\s*(.+?)\s*$")
+_SECTION = re.compile(r"^\s*\[")
+
+
+def normalize_remote(url):
+    """Normalize a git remote URL to `host/owner/name`, lowercase, without scheme, user, port or `.git`."""
+    text = url.strip().replace("\\", "/")
+    text = re.sub(r"(\.git)?/*$", "", text)
+    if "://" in text:
+        parts = urlsplit(text)
+        if parts.scheme == "file":
+            return "path:" + parts.path.rstrip("/")
+        host = (parts.hostname or "").lower()
+        return (host + "/" + parts.path.strip("/")).lower()
+    m = _SCP.match(text)
+    if m and not os.path.isabs(text):
+        return (m.group(1) + "/" + m.group(2).strip("/")).lower()
+    return "path:" + os.path.realpath(text).replace("\\", "/")
+
+
+def git_dir(repo):
+    dotgit = os.path.join(repo, ".git")
+    if os.path.isdir(dotgit):
+        return dotgit
+    if os.path.isfile(dotgit):
+        try:
+            with open(dotgit, encoding="utf-8") as f:
+                line = f.read().strip()
+        except OSError:
+            return None
+        if line.startswith("gitdir:"):
+            target = line[7:].strip()
+            return os.path.normpath(os.path.join(repo, target))
+    return None
+
+
+def common_dir(gdir):
+    try:
+        with open(os.path.join(gdir, "commondir"), encoding="utf-8") as f:
+            return os.path.normpath(os.path.join(gdir, f.read().strip()))
+    except OSError:
+        return gdir
+
+
+def remote_url(repo):
+    gdir = git_dir(repo)
+    if not gdir:
+        return None
+    remotes = _read_remotes(os.path.join(common_dir(gdir), "config"))
+    return remotes.get("origin") or (next(iter(remotes.values())) if remotes else None)
+
+
+def _read_remotes(config):
+    remotes, current = {}, None
+    try:
+        with open(config, encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return remotes
+    for line in lines:
+        m = _REMOTE.match(line)
+        if m:
+            current = m.group(1)
+            continue
+        if _SECTION.match(line):
+            current = None
+            continue
+        u = _URL.match(line)
+        if current and u and current not in remotes:
+            remotes[current] = u.group(1)
+    return remotes
+
+
+def identity(repo):
+    """Repo identity: normalized remote URL, else `path:<absolute path>`."""
+    url = remote_url(repo)
+    if url:
+        return normalize_remote(url)
+    return "path:" + os.path.realpath(repo).replace("\\", "/")
+
+
+def find_root(path):
+    cur = os.path.realpath(path)
+    while True:
+        if git_dir(cur):
+            return cur
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            return None
+        cur = parent
+
+
+def checkout_info(path):
+    """Describe the checkout containing `path`: {path, kind: clone|worktree, branch}, or None."""
+    root = find_root(path)
+    if not root:
+        return None
+    gdir = git_dir(root)
+    kind = "worktree" if os.path.isfile(os.path.join(root, ".git")) and common_dir(gdir) != gdir else "clone"
+    return {"path": root, "kind": kind, "branch": _branch(gdir)}
+
+
+def _branch(gdir):
+    try:
+        with open(os.path.join(gdir, "HEAD"), encoding="utf-8") as f:
+            head = f.read().strip()
+    except OSError:
+        return ""
+    if head.startswith("ref:"):
+        return head.split("refs/heads/", 1)[-1]
+    return head[:12]
+
+
+def case_insensitive(folder):
+    probe = os.path.join(folder, ".board")
+    if not os.path.exists(probe):
+        probe = folder
+    head, tail = os.path.split(probe.rstrip(os.sep))
+    swapped = os.path.join(head, tail.swapcase())
+    if swapped == probe or not os.path.exists(swapped):
+        return False
+    try:
+        return os.path.samefile(probe, swapped)
+    except OSError:
+        return False
+
+
+def discover(workspace, declared=None):
+    """Map repo name -> absolute path: the workspace itself, git repos at depth 1-2, plus declared repos."""
+    workspace = os.path.realpath(workspace)
+    found = {}
+    if git_dir(workspace):
+        found[os.path.basename(workspace)] = workspace
+    for name in _children(workspace):
+        full = os.path.join(workspace, name)
+        if git_dir(full):
+            found[name] = full
+            continue
+        for sub in _children(full):
+            if git_dir(os.path.join(full, sub)):
+                found[name + "/" + sub] = os.path.join(full, sub)
+    for name, rel in (declared or {}).items():
+        found[P.canonical(name)] = os.path.realpath(os.path.join(workspace, os.path.expanduser(rel)))
+    return found
+
+
+def _children(folder):
+    try:
+        names = sorted(os.listdir(folder))
+    except OSError:
+        return []
+    return [n for n in names if not n.startswith(".") and os.path.isdir(os.path.join(folder, n))]
+
+
+def declared_repos(board_dir):
+    data = store.read_json(os.path.join(board_dir, "workspace.json"), {})
+    store.check_schema(data, "workspace.json")
+    return data.get("repos", {})
+
+
+class Resolver:
+    """Resolve `<repo>/<path>` lock paths of one workspace to repo identities."""
+
+    def __init__(self, workspace, board_dir):
+        self.workspace = os.path.realpath(workspace)
+        self.ci = case_insensitive(self.workspace)
+        self.repos = discover(self.workspace, declared_repos(board_dir))
+        self._ids = {}
+
+    def _identity(self, name):
+        if name not in self._ids:
+            self._ids[name] = identity(self.repos[name])
+        return self._ids[name]
+
+    def _match(self, parts):
+        names = sorted(self.repos, key=lambda n: -len(P.split(n)))
+        for name in names:
+            want = P.split(name)
+            have = parts[: len(want)]
+            if want == have or (self.ci and [w.casefold() for w in want] == [h.casefold() for h in have]):
+                return name, len(want)
+        root = next((n for n, p in self.repos.items() if p == self.workspace), None)
+        if root:
+            return root, 0
+        if len(self.repos) == 1:
+            return next(iter(self.repos)), 0
+        return None, 1
+
+    def resolve(self, raw):
+        """Return {path, id, rel, ci} for a lock path."""
+        path = P.canonical(raw)
+        parts = P.split(path)
+        name, used = self._match(parts)
+        if name:
+            ident = self._identity(name)
+        else:
+            ident = "path:" + os.path.realpath(os.path.join(self.workspace, parts[0])).replace("\\", "/")
+        rel = "/".join(parts[used:])
+        if self.ci:
+            ident = ident.casefold() if ident.startswith("path:") else ident
+            rel = rel.casefold()
+        return {"path": path, "id": ident, "rel": rel, "ci": self.ci}
+
+
+def locate(abs_path):
+    """Map an absolute file path to {id, rel, ci, root} through its checkout's git remote, or None."""
+    root = find_root(os.path.dirname(abs_path) if not os.path.isdir(abs_path) else abs_path)
+    if not root:
+        return None
+    real = os.path.realpath(abs_path)
+    rel = os.path.relpath(real, root).replace("\\", "/")
+    rel = "" if rel == "." else rel
+    ci = case_insensitive(root)
+    ident = identity(root)
+    if ci:
+        rel = rel.casefold()
+        ident = ident.casefold() if ident.startswith("path:") else ident
+    return {"id": ident, "rel": rel, "ci": ci, "root": root}
+
+
+def keys_overlap(a, b):
+    if a["id"] != b["id"]:
+        return False
+    fold = a.get("ci") or b.get("ci")
+    if any(P.contains(path, b["rel"], fold) for path in a.get("exclude", [])):
+        return False
+    if any(P.contains(path, a["rel"], fold) for path in b.get("exclude", [])):
+        return False
+    if not a["rel"] or not b["rel"]:
+        return True
+    return P.overlaps(a["rel"], b["rel"], fold)
+
+
+def key_contains(outer, inner):
+    if outer["id"] != inner["id"]:
+        return False
+    if any(P.overlaps(path, inner["rel"], outer.get("ci") or inner.get("ci")) for path in outer.get("exclude", [])):
+        return False
+    if not outer["rel"]:
+        return True
+    return P.contains(outer["rel"], inner["rel"], outer.get("ci") or inner.get("ci"))

raidlock/core/safeio.py

@@ -0,0 +1,201 @@
+import contextlib
+import errno
+import os
+import secrets
+import stat
+from pathlib import Path
+
+from . import portable
+from .errors import Precondition
+
+_DIR_FD = os.open in os.supports_dir_fd and os.mkdir in os.supports_dir_fd
+
+
+def _system_link(component):
+    aliases = {Path("/", name): Path("/private", name) for name in ("var", "tmp", "etc")}
+    if component not in aliases:
+        return False
+    try:
+        link = component.lstat()
+        parent = component.parent.lstat()
+    except OSError:
+        return False
+    return (
+        stat.S_ISLNK(link.st_mode)
+        and os.readlink(component) in (str(aliases[component]), str(aliases[component]).lstrip("/"))
+        and link.st_uid == 0
+        and parent.st_uid == 0
+        and not parent.st_mode & (stat.S_IWGRP | stat.S_IWOTH)
+        and component.parent == Path(component.anchor)
+    )
+
+
+def check(path, tree=False):
+    path = Path(os.path.abspath(path))
+    if len(path.parts) > 1:
+        top = Path(path.anchor, path.parts[1])
+        if _system_link(top):
+            path = Path("/private", top.name, *path.parts[2:])
+    for component in (*reversed(path.parents), path):
+        try:
+            mode = component.lstat().st_mode
+        except FileNotFoundError:
+            continue
+        if portable._redirected(component) or not (stat.S_ISDIR(mode) or stat.S_ISREG(mode)):
+            raise Precondition(f"unsafe filesystem entry: {component}")
+        if component != path and not stat.S_ISDIR(mode):
+            raise Precondition(f"not a directory: {component}")
+    if tree and path.is_dir():
+        for child in path.iterdir():
+            check(child, tree=True)
+    return path
+
+
+def _directory(path, create=False):
+    path = check(path)
+    nofollow = getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    flags = os.O_RDONLY | nofollow
+    search = (getattr(os, "O_SEARCH", 0) | nofollow) if hasattr(os, "O_SEARCH") else flags
+    parts = path.parts[1:]
+    parent = os.open(path.anchor, search if parts else flags)
+    try:
+        for index, part in enumerate(parts):
+            if create:
+                with contextlib.suppress(FileExistsError):
+                    os.mkdir(part, mode=0o700, dir_fd=parent)
+            if index < len(parts) - 1:
+                fd = os.open(part, search, dir_fd=parent)
+            else:
+                try:
+                    fd = os.open(part, flags, dir_fd=parent)
+                except PermissionError:
+                    if search == flags:
+                        raise
+                    fd = os.open(part, search, dir_fd=parent)
+            os.close(parent)
+            parent = fd
+        return parent
+    except BaseException:
+        os.close(parent)
+        raise
+
+
+def read(path):
+    path = check(path)
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    if not _DIR_FD:
+        fd = portable.open_nofollow(path, flags)
+        with os.fdopen(fd, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                raise Precondition(f"not a regular file: {path}")
+            check(path)
+            return stream.read()
+    parent = _directory(path.parent)
+    try:
+        fd = os.open(path.name, flags, dir_fd=parent)
+        with os.fdopen(fd, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                raise Precondition(f"not a regular file: {path}")
+            return stream.read()
+    finally:
+        os.close(parent)
+
+
+def mkdir(path):
+    path = check(path)
+    if not _DIR_FD:
+        os.mkdir(path, mode=0o700)
+        check(path)
+        return
+    parent = _directory(path.parent)
+    try:
+        os.mkdir(path.name, mode=0o700, dir_fd=parent)
+    finally:
+        os.close(parent)
+
+
+def copytree(source, target):
+    source, target = check(source, tree=True), check(target)
+    mkdir(target)
+    for child in source.iterdir():
+        dest = target / child.name
+        if child.is_dir():
+            copytree(child, dest)
+        else:
+            write_text(dest, read(child))
+
+
+def write_text(path, text, mode=0o600):
+    path = check(path)
+    if not _DIR_FD:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        check(path)
+        temporary = path.parent / (".migration-" + secrets.token_hex(16))
+        try:
+            fd = portable.open_nofollow(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(text.encode("utf-8") if isinstance(text, str) else text)
+                stream.flush()
+                os.fsync(stream.fileno())
+            check(path)
+            check(temporary)
+            os.replace(temporary, path)
+        finally:
+            with contextlib.suppress(FileNotFoundError):
+                unlink(temporary)
+        return
+    parent = _directory(path.parent, create=True)
+    temporary = ".migration-" + secrets.token_hex(16)
+    try:
+        try:
+            existing = os.stat(path.name, dir_fd=parent, follow_symlinks=False)
+        except FileNotFoundError:
+            pass
+        else:
+            if not stat.S_ISREG(existing.st_mode):
+                raise Precondition(f"not a regular file: {path}")
+        fd = os.open(
+            temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), mode, dir_fd=parent
+        )
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(text.encode("utf-8") if isinstance(text, str) else text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path.name, src_dir_fd=parent, dst_dir_fd=parent)
+        try:
+            os.fsync(parent)
+        except OSError as exc:
+            if exc.errno not in (errno.EBADF, errno.EPERM):
+                raise
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(temporary, dir_fd=parent)
+        os.close(parent)
+
+
+def replace(source, target):
+    source, target = check(source), check(target)
+    if not _DIR_FD:
+        os.replace(source, target)
+        return
+    source_parent = _directory(source.parent)
+    try:
+        target_parent = _directory(target.parent)
+        try:
+            os.replace(source.name, target.name, src_dir_fd=source_parent, dst_dir_fd=target_parent)
+        finally:
+            os.close(target_parent)
+    finally:
+        os.close(source_parent)
+
+
+def unlink(path):
+    path = check(path)
+    if not _DIR_FD:
+        os.unlink(path)
+        return
+    parent = _directory(path.parent)
+    try:
+        os.unlink(path.name, dir_fd=parent)
+    finally:
+        os.close(parent)

raidlock/core/status.py

@@ -0,0 +1,52 @@
+from . import clock
+
+WORKING_SECONDS = 15 * 60
+STALLED_SECONDS = 45 * 60
+LABELS = {
+    "working": "Working",
+    "quiet": "Working (quiet)",
+    "review": "Waiting for review",
+    "blocked": "Blocked",
+    "stalled": "Stalled",
+    "idle": "Idle",
+}
+ORDER = ("working", "quiet", "blocked", "stalled", "review", "idle")
+
+
+def _doing_status(lease, at):
+    if not lease or not lease.get("expires") or (clock.parse(lease["expires"]) or at) <= at:
+        return "stalled"
+    age = clock.age_seconds(lease.get("renewed", ""), at)
+    if age is None or age > STALLED_SECONDS:
+        return "stalled"
+    return "quiet" if age > WORKING_SECONDS else "working"
+
+
+def agent_status(name, cards, leases, at=None):
+    """Derived status of one agent from its cards and its own lease heartbeat (never card.updated)."""
+    at = at or clock.now()
+    mine = [c for c in cards if c.get("owner") == name]
+    doing = next((c for c in mine if c["lane"] == "doing"), None)
+    if doing:
+        lease = leases.get(doing["id"])
+        return {"status": _doing_status(lease, at), "card": doing["id"], "heartbeat": (lease or {}).get("renewed", "")}
+    for lane, status in (("blocked", "blocked"), ("review", "review")):
+        card = next((c for c in mine if c["lane"] == lane), None)
+        if card:
+            return {
+                "status": status,
+                "card": card["id"],
+                "heartbeat": (leases.get(card["id"]) or {}).get("renewed", ""),
+            }
+    return {"status": "idle", "card": "", "heartbeat": ""}
+
+
+def statuses(agents, cards, leases, at=None):
+    """{agent: {status, label, card, heartbeat}} for every joined agent and card owner."""
+    names = set(agents) | {c["owner"] for c in cards if c.get("owner")}
+    out = {}
+    for name in sorted(names):
+        s = agent_status(name, cards, leases, at)
+        s["label"] = LABELS[s["status"]]
+        out[name] = s
+    return out

raidlock/core/store.py

@@ -0,0 +1,107 @@
+import json
+import os
+import tempfile
+
+from .errors import Precondition
+
+SCHEMA = 2
+
+
+def atomic_write_text(path, text):
+    folder = os.path.dirname(os.path.abspath(path))
+    os.makedirs(folder, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix="." + os.path.basename(path) + ".", suffix=".tmp", dir=folder)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    _fsync_dir(folder)
+
+
+def _fsync_dir(folder):
+    if os.name != "posix":
+        return
+    try:
+        fd = os.open(folder, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
+
+
+def write_json(path, data):
+    atomic_write_text(path, json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False) + "\n")
+
+
+def read_json(path, default=None):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return default
+    except ValueError as e:
+        raise Precondition(f"corrupt JSON in {path}: {e}", path=path) from e
+
+
+def check_schema(data, path):
+    found = data.get("schema", 1) if isinstance(data, dict) else 1
+    if not isinstance(found, int) or found > SCHEMA:
+        raise Precondition(
+            f"{path} has schema {found}; this raidlock understands up to {SCHEMA}; upgrade raidlock",
+            path=path,
+            schema=found,
+        )
+    return found
+
+
+def read_doc(path, key, default=None):
+    data = read_json(path)
+    if data is None:
+        return {} if default is None else default
+    check_schema(data, path)
+    return data.get(key, {} if default is None else default)
+
+
+def write_doc(path, key, value, **extra):
+    write_json(path, {"schema": SCHEMA, key: value, **extra})
+
+
+def append_line(path, line, sync=True):
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    with open(path, "a", encoding="utf-8", newline="\n") as f:
+        f.write(line.rstrip("\n") + "\n")
+        f.flush()
+        if sync:
+            os.fsync(f.fileno())
+
+
+def read_lines(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return [line.rstrip("\n") for line in f if line.strip()]
+    except FileNotFoundError:
+        return []
+
+
+def read_jsonl(path):
+    out = []
+    for line in read_lines(path):
+        try:
+            out.append(json.loads(line))
+        except ValueError:
+            continue
+    return out
+
+
+def write_jsonl(path, rows):
+    atomic_write_text(path, "".join(json.dumps(r, sort_keys=True, ensure_ascii=False) + "\n" for r in rows))

raidlock/core/tokens.py

@@ -0,0 +1,77 @@
+import importlib
+import math
+
+CONTRIBUTORS = {}
+EXTENSION_MODULES = ("raidlock.hooks", "raidlock.mcp", "raidlock.web", "raidlock.runners", "raidlock.plugin")
+SAMPLE_OUTPUTS = (
+    "[ws] Claimed fix-login: lock app/auth until 14:05, fence 7.",
+    'export RAIDLOCK_FENCE=7  # next: raidlock note fix-login "..."',
+    "[ws] Noted on fix-login.",
+    "[ws] Renewed fix-login until 14:50.",
+    "[ws] Moved fix-login to review. Next: the lead runs raidlock done fix-login",
+    "No messages.",
+)
+
+
+def estimate(text):
+    """Token estimate: ceil(characters / 4)."""
+    return math.ceil(len(text or "") / 4)
+
+
+def register(name, fn):
+    """Register an overhead contributor. `fn(board)` returns {"tokens": int, "detail": str} or a text to estimate.
+    Edge components (skill, hooks, MCP schemas, UI) call this from `register_tokens(register)`."""
+    CONTRIBUTORS[name] = fn
+
+
+def _load_extensions():
+    for module in EXTENSION_MODULES:
+        try:
+            mod = importlib.import_module(module)
+        except ImportError:
+            continue
+        if hasattr(mod, "register_tokens"):
+            mod.register_tokens(register)
+    try:
+        from importlib.metadata import entry_points
+
+        eps = entry_points()
+        group = eps.select(group="raidlock.tokens") if hasattr(eps, "select") else eps.get("raidlock.tokens", [])
+        for ep in group:
+            ep.load()(register)
+    except Exception:
+        return
+
+
+def _core_outputs(board):
+    text = "\n".join(SAMPLE_OUTPUTS)
+    return {"tokens": estimate(text), "detail": f"{len(SAMPLE_OUTPUTS)} typical command outputs per session"}
+
+
+def _core_brief(board):
+    if board is None:
+        return {"tokens": 0, "detail": "no board"}
+    cards = [c for c in board.cards() if c["lane"] in ("todo", "doing", "blocked")]
+    if not cards:
+        return {"tokens": 0, "detail": "no open cards"}
+    sizes = sorted(board.brief(c["id"])["tokens"] for c in cards)
+    return {"tokens": sizes[len(sizes) // 2], "detail": f"median card brief over {len(cards)} open card(s)"}
+
+
+register("cli outputs", _core_outputs)
+register("card brief", _core_brief)
+
+
+def report(board=None):
+    """Estimated per-session token overhead of raidlock, by contributor."""
+    _load_extensions()
+    items = []
+    for name, fn in sorted(CONTRIBUTORS.items()):
+        try:
+            value = fn(board)
+        except Exception as e:
+            value = {"tokens": 0, "detail": f"error: {e}"}
+        if isinstance(value, str):
+            value = {"tokens": estimate(value), "detail": f"{len(value)} chars"}
+        items.append({"name": name, "tokens": int(value.get("tokens", 0)), "detail": value.get("detail", "")})
+    return {"items": items, "total": sum(i["tokens"] for i in items), "method": "ceil(chars / 4)"}