glitch-toolkit 0.1.0__py3-none-any.whl

glitch/__init__.py

@@ -0,0 +1,12 @@
+"""Bounded autonomy for agents working in a repository.
+
+Six practices from *Building Your Store Or Your SaaS With Claude*, installed
+into your own project and checked there. The checker's contract is that an
+artifact counts as installed only when it is present, runs, AND still refuses a
+deliberately broken case; anything that merely passes is treated as not wired up.
+
+The command line is the product. Import it if you want to, but nothing in here
+is a stable API yet.
+"""
+
+__version__ = "0.1.0"

glitch/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m glitch` alongside the `glitch` console script."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

glitch/_assets/scripts/check_lanes.py

@@ -0,0 +1,219 @@
+"""Lane claims for a repo that several Claude sessions share.
+
+The failure this exists for: two sessions edit the same file, the second write
+wins, there is no conflict and no error, and the lost work reads to you as a
+completed task. You find out days later, or never.
+
+Claims live one-file-per-lane under .claude/lanes/ so two sessions writing
+claims at the same moment never touch the same file. A shared claims file would
+race, which is the bug we are here to avoid.
+
+    python check_lanes.py claim backend app/main.py app/routes/*.py
+    python check_lanes.py check app/main.py      # before you edit
+    python check_lanes.py status
+    python check_lanes.py release backend
+
+Honest limits, stated up front:
+  * This cannot see other sessions. It sees claims they wrote and mtimes on
+    disk. A session that never claims anything is invisible to it.
+  * mtime evidence is advisory. A recent mtime means someone touched the file,
+    not necessarily that they are still in it.
+  * It does not lock anything. It tells you; you decide.
+"""
+import argparse
+import fnmatch
+import glob
+import json
+import os
+import pathlib
+import socket
+import sys
+import time
+
+LANES_DIR = pathlib.Path(".claude/lanes")
+STALE_HOURS = 4.0        # a claim older than this is suspect, see status output
+RECENT_EDIT_MINUTES = 30  # mtime inside this window is worth warning about
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _lane_files() -> list[pathlib.Path]:
+    return sorted(LANES_DIR.glob("*.json")) if LANES_DIR.exists() else []
+
+
+def _load(p: pathlib.Path) -> dict | None:
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _expand(patterns: list[str]) -> list[str]:
+    """Globs are resolved at claim time so a claim names real files."""
+    out = []
+    for pat in patterns:
+        hits = glob.glob(pat, recursive=True)
+        out.extend(hits if hits else [pat])
+    return sorted({os.path.normpath(p).replace("\\", "/") for p in out})
+
+
+def _matches(claimed: str, target: str) -> bool:
+    t = os.path.normpath(target).replace("\\", "/")
+    return t == claimed or fnmatch.fnmatch(t, claimed) or t.startswith(claimed.rstrip("/") + "/")
+
+
+def _age(ts: float) -> str:
+    m = (_now() - ts) / 60
+    if m < 60:
+        return f"{m:.0f}m ago"
+    return f"{m / 60:.1f}h ago"
+
+
+def cmd_claim(args) -> int:
+    LANES_DIR.mkdir(parents=True, exist_ok=True)
+    paths = _expand(args.paths)
+
+    conflicts = _conflicts(paths, skip_lane=args.lane)
+    if conflicts and not args.force:
+        print("REFUSED. Another lane already claims these:")
+        for path, lane, ts in conflicts:
+            print(f"  {path}  ->  lane '{lane}' (claimed {_age(ts)})")
+        print("\nTalk to that lane, or re-run with --force if you know it is stale.")
+        return 1
+
+    dest = LANES_DIR / f"{args.lane}.json"
+    dest.write_text(json.dumps({
+        "lane": args.lane,
+        "paths": paths,
+        "claimed_at": _now(),
+        "host": socket.gethostname(),
+        "pid": os.getpid(),
+        "note": args.note or "",
+    }, indent=2), encoding="utf-8")
+
+    print(f"claimed {len(paths)} path(s) for lane '{args.lane}'")
+    for p in paths:
+        print(f"  {p}")
+    if conflicts:
+        print("\nforced past these conflicts:")
+        for path, lane, _ in conflicts:
+            print(f"  {path} (lane '{lane}')")
+    return 0
+
+
+def _conflicts(paths: list[str], skip_lane: str | None) -> list[tuple[str, str, float]]:
+    found = []
+    for lf in _lane_files():
+        data = _load(lf)
+        if not data or data.get("lane") == skip_lane:
+            continue
+        for claimed in data.get("paths", []):
+            for target in paths:
+                if _matches(claimed, target) or _matches(target, claimed):
+                    found.append((target, data["lane"], data.get("claimed_at", 0)))
+    return found
+
+
+def cmd_check(args) -> int:
+    paths = _expand(args.paths)
+    problems = 0
+
+    conflicts = _conflicts(paths, skip_lane=args.lane)
+    if conflicts:
+        problems += len(conflicts)
+        print("CLAIMED BY ANOTHER LANE:")
+        for path, lane, ts in conflicts:
+            stale = " [STALE]" if (_now() - ts) / 3600 > STALE_HOURS else ""
+            print(f"  {path}  ->  lane '{lane}' (claimed {_age(ts)}){stale}")
+
+    # mtime evidence catches the session that never claimed anything.
+    cutoff = _now() - RECENT_EDIT_MINUTES * 60
+    recent = []
+    for p in paths:
+        fp = pathlib.Path(p)
+        if fp.is_file() and fp.stat().st_mtime > cutoff:
+            recent.append((p, fp.stat().st_mtime))
+    if recent:
+        problems += len(recent)
+        print("\nRECENTLY MODIFIED (someone may be in these right now):")
+        for p, ts in sorted(recent, key=lambda x: -x[1]):
+            print(f"  {p}  modified {_age(ts)}")
+
+    if not problems:
+        print(f"clear: {len(paths)} path(s), no claims and no recent edits")
+        return 0
+
+    print(f"\n{problems} warning(s). Confirm before editing.")
+    return 1
+
+
+def cmd_status(args) -> int:
+    lanes = _lane_files()
+    if not lanes:
+        print("no lanes claimed")
+        return 0
+
+    print(f"{len(lanes)} lane(s):\n")
+    for lf in lanes:
+        data = _load(lf)
+        if not data:
+            print(f"  {lf.name}: UNREADABLE")
+            continue
+        ts = data.get("claimed_at", 0)
+        hrs = (_now() - ts) / 3600
+        flag = "  <- STALE, release it or refresh it" if hrs > STALE_HOURS else ""
+        print(f"  {data['lane']}  ({_age(ts)}, {len(data.get('paths', []))} paths){flag}")
+        if data.get("note"):
+            print(f"      note: {data['note']}")
+        for p in data.get("paths", [])[:8]:
+            print(f"      {p}")
+        if len(data.get("paths", [])) > 8:
+            print(f"      ... and {len(data['paths']) - 8} more")
+        print()
+
+    print("A stale claim is not harmlessly cautious. It makes other lanes route")
+    print("around files that are actually free.")
+    return 0
+
+
+def cmd_release(args) -> int:
+    dest = LANES_DIR / f"{args.lane}.json"
+    if not dest.exists():
+        print(f"no claim for lane '{args.lane}'")
+        return 1
+    dest.unlink()
+    print(f"released lane '{args.lane}'")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("claim", help="claim paths for a lane")
+    c.add_argument("lane")
+    c.add_argument("paths", nargs="+")
+    c.add_argument("--note", default="")
+    c.add_argument("--force", action="store_true")
+    c.set_defaults(fn=cmd_claim)
+
+    k = sub.add_parser("check", help="check paths before editing")
+    k.add_argument("paths", nargs="+")
+    k.add_argument("--lane", default=None, help="your own lane, excluded from conflicts")
+    k.set_defaults(fn=cmd_check)
+
+    s = sub.add_parser("status", help="show all claims")
+    s.set_defaults(fn=cmd_status)
+
+    r = sub.add_parser("release", help="release a lane")
+    r.add_argument("lane")
+    r.set_defaults(fn=cmd_release)
+
+    args = ap.parse_args()
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

glitch/_assets/scripts/fleet.py

@@ -0,0 +1,341 @@
+"""A fleet of chats that can address each other, and a handoff with a fixed shape.
+
+    python fleet.py desks                          who exists, who commits
+    python fleet.py inbox --me build               your unread messages
+    python fleet.py send --to build --from ops --subject "..."     body on stdin
+    python fleet.py handoff --from build --to ops --did "..." --verified "..." --next "..."
+    python fleet.py archive --me build             mark what you read as read
+
+Two problems, and they are the same problem twice.
+
+  1. ONE SHARED FILE. Every desk writes its messages into one notes file, two
+     desks write at once, and the second write wins silently. That is chapter
+     four again, and the fix is the same: never edit a shared file. One file
+     per message, created exclusively, so a collision is impossible rather than
+     unlikely.
+
+  2. AN IMPROVISED HANDOFF. Every chat invents its own way of saying it is
+     done, so the next desk gets a paragraph and has to guess what was actually
+     verified. `handoff` refuses to write one without all three parts: what was
+     done, what was actually run, and what is next.
+
+An address that is not a desk is refused. A message sent to a slug nobody
+watches is not delivered anywhere; it sits in a directory no one opens, and the
+sender believes it arrived. So the desk table is the authority, and sending to
+an unknown desk is an error rather than a new directory.
+
+WHAT THIS CANNOT DO:
+
+  * It cannot wake a closed session. A message waits in the inbox until that
+    desk opens and checks. Nothing on your machine can make a closed chat read
+    its mail, and any tool that claims otherwise is describing a scheduler.
+  * It does not know whether a desk did what it said in a handoff. It only
+    refuses a handoff that does not say.
+  * It is not a queue with delivery guarantees. It is files in directories,
+    which is why it survives every session being closed at once.
+
+Standard library only. Everything it writes stays under `.claude/fleet/`.
+"""
+import argparse
+import errno
+import os
+import pathlib
+import re
+import sys
+import time
+
+START = "<!-- desks:start -->"
+END = "<!-- desks:end -->"
+SLUG = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+YES = {"yes", "y", "true"}
+NO = {"no", "n", "false", "-", ""}
+
+
+class Desk:
+    def __init__(self, slug, owns, commits):
+        self.slug = slug
+        self.owns = owns
+        self.commits = commits
+
+
+def read_desks(path):
+    """Parse the desk table. Returns (desks, error)."""
+    if not path.is_file():
+        return [], (
+            "no desk table at {}. A fleet with no written table is a fleet where\n"
+            "  every desk believes it is allowed to commit.".format(path)
+        )
+
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    start = end = None
+    for i, line in enumerate(lines):
+        if START in line and start is None:
+            start = i
+        elif END in line and start is not None and end is None:
+            end = i
+    if start is None or end is None:
+        return [], "{} has no {} ... {} block".format(path, START, END)
+
+    desks = []
+    for line in lines[start + 1:end]:
+        row = line.strip()
+        if not row.startswith("|"):
+            continue
+        cells = [c.strip() for c in row.strip("|").split("|")]
+        if len(cells) < 3:
+            continue
+        slug = cells[0].lower()
+        if slug in ("desk", "") or set(slug) <= set("-: "):
+            continue  # the header row and the separator under it
+        desks.append(Desk(slug, cells[1], cells[2].strip().lower()))
+    return desks, None
+
+
+def judge_desks(desks):
+    """Return a list of complaints about the table itself."""
+    out = []
+    if len(desks) < 2:
+        out.append("a fleet needs at least two desks. Found {}.".format(len(desks)))
+
+    seen = set()
+    for d in desks:
+        if not SLUG.match(d.slug):
+            out.append("'{}' is not a usable address. Lower case, digits and hyphens.".format(d.slug))
+        if d.slug in seen:
+            out.append("'{}' is listed twice. Two desks with one address share an inbox.".format(d.slug))
+        seen.add(d.slug)
+        if d.commits not in YES and d.commits not in NO:
+            out.append("'{}' answers '{}' to commits. Say yes or no.".format(d.slug, d.commits))
+
+    committers = [d.slug for d in desks if d.commits in YES]
+    if not committers:
+        out.append(
+            "nobody is allowed to commit. Decide who is, and write it in the table.\n"
+            "  Every other mistake a fleet makes is recoverable. This one is the one\n"
+            "  where two desks push over each other."
+        )
+    elif len(committers) > 1:
+        out.append(
+            "{} desks are allowed to commit: {}. Pick one.".format(
+                len(committers), ", ".join(committers))
+        )
+    return out
+
+
+def bus_root(fleet_path):
+    return fleet_path.resolve().parent / ".claude" / "fleet"
+
+
+def resolve(args):
+    """Load and validate the table, or explain why not. Returns (desks, root, error)."""
+    path = pathlib.Path(args.fleet)
+    desks, error = read_desks(path)
+    if error:
+        return None, None, error
+    complaints = judge_desks(desks)
+    if complaints:
+        return None, None, "\n".join("  " + c for c in complaints)
+    return desks, bus_root(path), None
+
+
+def require(desks, slug, what):
+    known = [d.slug for d in desks]
+    if slug in known:
+        return None
+    return (
+        "'{}' is not a desk, so there is nowhere to {}.\n"
+        "  Desks: {}\n"
+        "  A message to an address nobody watches is worse than no message: the\n"
+        "  sender believes it arrived.".format(slug, what, ", ".join(known))
+    )
+
+
+def write_message(root, to, body):
+    """One file per message, created exclusively. Two senders cannot collide."""
+    box = root / to / "inbox"
+    box.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%dT%H%M%S")
+    for n in range(1000):
+        target = box / "{}-{}-{}.md".format(stamp, os.getpid(), n)
+        try:
+            fd = os.open(str(target), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except OSError as e:
+            if e.errno == errno.EEXIST:
+                continue
+            raise
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(body)
+        return target
+    raise RuntimeError("could not create a message file in " + str(box))
+
+
+def envelope(sender, to, subject, body):
+    return "From: {}\nTo: {}\nTime: {}\nSubject: {}\n\n{}\n".format(
+        sender, to, time.strftime("%Y-%m-%d %H:%M"), subject, body.rstrip("\n"))
+
+
+# ------------------------------------------------------------------ commands
+
+
+def cmd_desks(args):
+    path = pathlib.Path(args.fleet)
+    desks, error = read_desks(path)
+    if error:
+        print(error)
+        return 1
+    complaints = judge_desks(desks)
+
+    print("")
+    print("  {:<16} {:<40} {}".format("desk", "owns", "commits"))
+    for d in desks:
+        print("  {:<16} {:<40} {}".format(d.slug, d.owns[:40], d.commits or "-"))
+    print("")
+
+    if complaints:
+        for c in complaints:
+            print("  FAIL  " + c)
+        print("")
+        return 1
+    print("  the table holds: {} desks, one of them commits.".format(len(desks)))
+    print("")
+    return 0
+
+
+def cmd_send(args):
+    desks, root, error = resolve(args)
+    if error:
+        print(error)
+        return 1
+    for slug, what in ((args.to, "deliver"), (getattr(args, "from"), "send from")):
+        bad = require(desks, slug, what)
+        if bad:
+            print(bad)
+            return 1
+
+    body = args.body if args.body is not None else sys.stdin.read()
+    if not body.strip():
+        print("empty message. Say the thing, or do not send it.")
+        return 1
+
+    target = write_message(root, args.to, envelope(getattr(args, "from"), args.to, args.subject, body))
+    print("sent to {}: {}".format(args.to, target))
+    print("They see it when that session next opens and checks. Nothing here wakes it.")
+    return 0
+
+
+def cmd_handoff(args):
+    desks, root, error = resolve(args)
+    if error:
+        print(error)
+        return 1
+    for slug, what in ((args.to, "deliver"), (getattr(args, "from"), "send from")):
+        bad = require(desks, slug, what)
+        if bad:
+            print(bad)
+            return 1
+
+    missing = [name for name in ("did", "verified", "next") if not getattr(args, name).strip()]
+    if missing:
+        print("a handoff without {} is not a handoff.".format(" or ".join(missing)))
+        print("The next desk cannot tell what is done from what was intended.")
+        print("  --did       what changed")
+        print("  --verified  the exact command you ran and what it said, or 'not verified'")
+        print("  --next      what the next desk should pick up")
+        return 1
+
+    body = "Done:\n  {}\n\nVerified:\n  {}\n\nNext:\n  {}\n".format(
+        args.did.strip(), args.verified.strip(), args.next.strip())
+    target = write_message(
+        root, args.to, envelope(getattr(args, "from"), args.to, "handoff: " + args.did.strip()[:60], body))
+    print("handed off to {}: {}".format(args.to, target))
+    return 0
+
+
+def cmd_inbox(args):
+    desks, root, error = resolve(args)
+    if error:
+        print(error)
+        return 1
+    bad = require(desks, args.me, "read an inbox")
+    if bad:
+        print(bad)
+        return 1
+
+    box = root / args.me / "inbox"
+    files = sorted(box.glob("*.md")) if box.is_dir() else []
+    if not files:
+        print("no unread messages for {}.".format(args.me))
+        return 0
+    for f in files:
+        print("=" * 70)
+        print(f.name)
+        print("=" * 70)
+        print(f.read_text(encoding="utf-8", errors="replace"))
+    print("{} message(s). Act on them, then: python fleet.py archive --me {}".format(
+        len(files), args.me))
+    return 0
+
+
+def cmd_archive(args):
+    desks, root, error = resolve(args)
+    if error:
+        print(error)
+        return 1
+    bad = require(desks, args.me, "archive an inbox")
+    if bad:
+        print(bad)
+        return 1
+
+    box = root / args.me / "inbox"
+    done = root / args.me / "read"
+    files = sorted(box.glob("*.md")) if box.is_dir() else []
+    if not files:
+        print("nothing to archive for {}.".format(args.me))
+        return 0
+    done.mkdir(parents=True, exist_ok=True)
+    for f in files:
+        f.replace(done / f.name)
+    print("archived {} message(s) for {}.".format(len(files), args.me))
+    return 0
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("--fleet", default="FLEET.md", help="the desk table (default: FLEET.md)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("desks", help="print the desk table and check it")
+
+    s = sub.add_parser("send", help="send a message to a desk")
+    s.add_argument("--to", required=True)
+    s.add_argument("--from", required=True)
+    s.add_argument("--subject", required=True)
+    s.add_argument("--body", help="message body (default: read stdin)")
+
+    h = sub.add_parser("handoff", help="hand work to another desk, in the fixed shape")
+    h.add_argument("--to", required=True)
+    h.add_argument("--from", required=True)
+    h.add_argument("--did", default="")
+    h.add_argument("--verified", default="")
+    h.add_argument("--next", default="")
+
+    i = sub.add_parser("inbox", help="read your unread messages")
+    i.add_argument("--me", required=True)
+
+    a = sub.add_parser("archive", help="move what you read out of the inbox")
+    a.add_argument("--me", required=True)
+
+    args = ap.parse_args()
+    return {
+        "desks": cmd_desks,
+        "send": cmd_send,
+        "handoff": cmd_handoff,
+        "inbox": cmd_inbox,
+        "archive": cmd_archive,
+    }[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())