call-dibs 0.3.0__py3-none-any.whl

call_dibs-0.3.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: call-dibs
+Version: 0.3.0
+Summary: Call dibs on shared stuff — a one-file lock ledger for humans and AI agents.
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# ✋ call-dibs
+
+**Call dibs on shared stuff.**
+
+A tiny lock ledger so humans and AI agents stop fighting over the same phone, GPU, or test bench.
+
+[![CI](https://github.com/NeoMarcoPolo/call-dibs/actions/workflows/ci.yml/badge.svg)](https://github.com/NeoMarcoPolo/call-dibs/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/call-dibs)](https://pypi.org/project/call-dibs/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+</div>
+
+```console
+$ dibs claim phone-a --note "regression run"
+claimed phone-a as alice
+
+$ dibs claim phone-a                      # …from another session
+BUSY phone-a: held by alice since 2026-09-02T21:14:03Z (3m ago) — "regression run"
+
+$ dibs release phone-a
+released phone-a (was alice)
+```
+
+## Why
+
+You have one test phone, one GPU, one hardware bench — and several
+terminals (or several coding agents) that can all reach it. `dibs` is the
+smallest thing that makes them take turns.
+
+- **One file, no dependencies.** A single Python script, stdlib only. No
+  daemon, no server, no database.
+- **Cross-platform.** macOS, Linux, Windows.
+- **Legible.** The ledger is one human-readable JSON file per resource, and
+  every "busy" says *who*, *since when*, and *why*.
+- **Agent-friendly.** Stable exit codes, `--json`, a blocking `--wait`, and a
+  `run` wrapper that always releases — even when the command fails.
+
+## Install
+
+```sh
+pipx install call-dibs        # or: pip install call-dibs · uv tool install call-dibs
+```
+
+Works the same on macOS, Linux, and Windows. Prefer no package manager? It's
+one file — [`dibs.py`](dibs.py) — drop it on your `PATH`.
+
+## Set up
+
+Tell `dibs` what you share. Write `~/.dibs/resources.json` once, by hand:
+
+```json
+{
+  "phone-a": "Android test phone on the bench",
+  "gpu-0": "the shared training GPU",
+  "printer": "label printer, room 2"
+}
+```
+
+Only these names can be claimed, so a typo can't silently create a new lock.
+`dibs` never edits this file.
+
+## Use
+
+| command | what it does |
+|---|---|
+| `dibs claim <r...> [--note ...] [--wait [--timeout N]]` | claim one or more resources. Exit `2` + holder info if busy |
+| `dibs release <r...> [--force]` | release |
+| `dibs status [r] [--json]` | who has what |
+| `dibs wait <r...> [--timeout N]` | block until free, without claiming |
+| `dibs run <r> -- <cmd...>` | claim → run → always release |
+| `dibs watch` | live terminal view |
+
+Exit codes: `0` ok · `2` busy · `3` not yours · `4` wait timeout · `1` error.
+
+### Who's asking
+
+Every claim records an owner, and only that owner can release it. Name
+yourself once per session with `DIBS_OWNER`:
+
+```sh
+export DIBS_OWNER=alice                    # people
+DIBS_OWNER=agent:task-123 dibs claim …     # agents: inline, so every call agrees
+```
+
+If it's unset, `dibs` falls back to `user@host:pid` — fine for one-off use,
+wrong for agents whose shell changes every command. `--force` releases
+someone else's lock when they're gone.
+
+### Groups
+
+Claim several resources in one call and they form a group. The claim is
+all-or-nothing — if any resource is busy, nothing is taken — and the group
+gets a tag so you can drop the whole set at once:
+
+```console
+$ dibs claim phone-a gpu-0 --note "regression run"
+claimed gpu-0 as alice
+claimed phone-a as alice
+group g-3fa2c1: gpu-0, phone-a (discard with: dibs release g-3fa2c1)
+
+$ dibs release g-3fa2c1
+```
+
+Name the group yourself with `--as NAME`.
+
+## For AI agents
+
+`skills/dibs/` is a drop-in skill for Claude Code (and reads fine as an
+`AGENTS.md` snippet for anything else). It teaches the protocol: claim before
+touching hardware, one call per set, release when done, never force-break
+someone else's lock.
+
+```sh
+cp -r skills/dibs ~/.claude/skills/
+```
+
+## Menu bar (macOS)
+
+See the ledger at a glance: `dibs ✋2` in the top bar when two things are
+claimed, `dibs ✓` when everything is free, and who-has-what in the dropdown.
+Install [SwiftBar](https://swiftbar.app), then add the plugin:
+
+```sh
+open "swiftbar://addplugin?src=https://raw.githubusercontent.com/NeoMarcoPolo/call-dibs/main/contrib/dibs.5s.sh"
+```
+
+## How it works
+
+One JSON file per resource under `~/.dibs/` (override with `DIBS_DIR`). A
+claim is an atomic `O_CREAT|O_EXCL` create, so racing claimers get exactly
+one winner. Locks are advisory and are held until released — there is no
+expiry. The ledger is per-machine by default; point `DIBS_DIR` at a shared
+directory to span machines.
+
+## Contributing
+
+`python3 -m unittest discover tests`. Keep it small.
+
+Releases: bump `version` in `pyproject.toml` and `dibs.py`, then push a
+`v*` tag — CI publishes to PyPI via trusted publishing (maintainer approval
+required).
+
+## License
+
+[MIT](LICENSE)

call_dibs-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+dibs.py,sha256=BOumbuEwtUQbyh7B7Tckm45uoDtyCKndAaeR02J-6Vs,14919
+call_dibs-0.3.0.dist-info/licenses/LICENSE,sha256=NobDAGyTMv0DH21lcgdia5DoUdpSPucoyDs58xrcEVs,1067
+call_dibs-0.3.0.dist-info/METADATA,sha256=ujey6kjx9ivGY-P7PLP199p5gu2hTWJutystIyX1nkQ,5091
+call_dibs-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+call_dibs-0.3.0.dist-info/entry_points.txt,sha256=I3tSKzk5X3hCFWYKxAeVBJale3mGAqqpmJRLjFlSyK8,35
+call_dibs-0.3.0.dist-info/top_level.txt,sha256=iddzCviTlLjrDlmJ7Ucz_jrPB4ESV3_hpKNJvuWiL0s,5
+call_dibs-0.3.0.dist-info/RECORD,,

call_dibs-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

call_dibs-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dibs = dibs:main

call_dibs-0.3.0.dist-info/licenses/LICENSE

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

call_dibs-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dibs

dibs.py

@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""dibs — call dibs on shared stuff.
+
+A tiny advisory lock ledger for physical resources shared by humans and AI
+agents: test phones, GPUs, staging environments, the label printer. One JSON
+file per resource. No daemon, no dependencies — Python 3.8+ stdlib only.
+macOS / Linux / Windows.
+
+    dibs claim gpu-0 --note "training run"
+    dibs status
+    dibs release gpu-0
+
+A lock is held until it is released. If a holder vanished, break the lock
+with `dibs release <r> --force` (loud on purpose).
+
+Ledger dir:  $DIBS_DIR   (default ~/.dibs)
+Owner id:    $DIBS_OWNER (default user@host:pid<ppid> — set a stable one!)
+Resources:   $DIBS_DIR/resources.json — you write it by hand, once:
+             {"gpu-0": "the shared GPU", "phone-a": "test phone"}
+             Only defined names can be claimed. dibs never edits this file.
+
+Claiming several resources in one call takes them all-or-nothing and forms
+a group (auto-named, or `--as NAME`); release the group to drop them all:
+
+    dibs claim phone-a gpu-0      ->  group g-3fa2c1: gpu-0, phone-a
+    dibs release g-3fa2c1
+
+Exit codes:  0 ok · 2 busy · 3 not held by you · 4 wait timeout · 1 error
+"""
+import argparse
+import getpass
+import json
+import os
+import re
+import socket
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+__version__ = "0.3.0"
+
+LEDGER = Path(os.environ.get("DIBS_DIR", Path.home() / ".dibs"))
+NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def now_iso():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def age_str(ts):
+    since = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    secs = int((datetime.now(timezone.utc) - since).total_seconds())
+    if secs < 90:
+        return f"{secs}s"
+    if secs < 5400:
+        return f"{secs // 60}m"
+    if secs < 129600:
+        return f"{secs // 3600}h{(secs % 3600) // 60:02d}m"
+    return f"{secs // 86400}d"
+
+
+def default_owner():
+    o = os.environ.get("DIBS_OWNER")
+    if o:
+        return o
+    return f"{getpass.getuser()}@{socket.gethostname().split('.')[0]}:pid{os.getppid()}"
+
+
+def lock_path(resource):
+    if not NAME_RE.match(resource):
+        raise SystemExit(f"dibs: bad resource name {resource!r} "
+                         "(letters/digits/._- only)")
+    return LEDGER / f"{resource}.lock.json"
+
+
+def read_lock(path):
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def registry():
+    """Hand-written {"name": "description"} map, or None if absent."""
+    try:
+        reg = json.loads((LEDGER / "resources.json").read_text())
+        if isinstance(reg, dict):
+            return reg
+    except FileNotFoundError:
+        return None
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"dibs: {LEDGER / 'resources.json'} is not valid JSON: {e}")
+    raise SystemExit(f"dibs: {LEDGER / 'resources.json'} must be a JSON object "
+                     '{"name": "description"}')
+
+
+NO_REGISTRY = (f"dibs: no resources defined yet. Create {LEDGER / 'resources.json'} "
+               'by hand, e.g. {"gpu-0": "the shared GPU", "phone-a": "test phone"}')
+
+
+def check_names(names):
+    """Validate claim targets against the registry; return sorted, deduped."""
+    reg = registry()
+    if not reg:
+        raise SystemExit(NO_REGISTRY)
+    for name in names:
+        if name not in reg:
+            raise SystemExit(f"dibs: {name!r} is not defined in resources.json "
+                             f"(known: {', '.join(sorted(reg))})")
+    return sorted(set(names))
+
+
+def holder_line(resource, rec):
+    note = f' — "{rec["note"]}"' if rec.get("note") else ""
+    grp = f" [group {rec['group']}]" if rec.get("group") else ""
+    return (f"{resource}: held by {rec['owner']} "
+            f"since {rec['since']} ({age_str(rec['since'])} ago){note}{grp}")
+
+
+def ledger_rows():
+    """All resources: registry entries plus any live locks."""
+    LEDGER.mkdir(parents=True, exist_ok=True)
+    reg = registry() or {}
+    rows = {name: {"resource": name, "description": desc}
+            for name, desc in sorted(reg.items())
+            if isinstance(desc, str)}  # list values are groups, not resources
+    for p in sorted(LEDGER.glob("*.lock.json")):
+        rec = read_lock(p)
+        if rec is None:
+            continue
+        name = rec.get("resource", p.name[:-len(".lock.json")])
+        desc = reg.get(name, "")
+        rec.setdefault("description", desc if isinstance(desc, str) else "")
+        rows[name] = {**rows.get(name, {}), **rec}
+    return list(rows.values())
+
+
+def try_claim_one(resource, owner, note, group=None):
+    """Returns 'claimed' | 'yours' | the blocking record."""
+    path = lock_path(resource)
+    rec = {"resource": resource, "owner": owner,
+           "host": socket.gethostname().split(".")[0],
+           "since": now_iso(), "note": note or None, "group": group}
+    while True:
+        LEDGER.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            with os.fdopen(fd, "w") as f:
+                json.dump(rec, f, indent=2)
+            return "claimed"
+        except FileExistsError:
+            cur = read_lock(path)
+            if cur is None:
+                continue  # holder released between our create and read; retry
+            if cur.get("owner") == owner:
+                if note and note != cur.get("note"):
+                    tmp = path.with_name(path.name + f".tmp-{os.getpid()}")
+                    tmp.write_text(json.dumps(dict(cur, note=note), indent=2))
+                    os.replace(tmp, path)
+                return "yours"
+            return cur
+
+
+def cmd_claim(a):
+    """All-or-nothing: on any BUSY, locks newly taken by this call are rolled
+    back (sorted claim order keeps overlapping sets deadlock-free). Claiming
+    several resources at once forms a group — a tag stamped on each lock —
+    so the whole set can later be discarded with `dibs release <group>`."""
+    resources = check_names(a.resources)
+    owner = a.owner or default_owner()
+    group = getattr(a, "as_group", None)
+    if group is None and len(resources) > 1:
+        group = "g-" + os.urandom(3).hex()
+    if group and not NAME_RE.match(group):
+        raise SystemExit(f"dibs: bad group name {group!r}")
+    deadline = time.time() + a.timeout if a.timeout else None
+    while True:
+        got, blocker = [], None
+        for r in resources:
+            res = try_claim_one(r, owner, a.note, group)
+            if res == "claimed":
+                got.append(r)
+            elif res != "yours":
+                blocker = (r, res)
+                break
+        if blocker is None:
+            for r in resources:
+                print(f"claimed {r} as {owner}")
+            if group:
+                print(f"group {group}: {', '.join(resources)} "
+                      f"(discard with: dibs release {group})")
+            return 0
+        for r in got:  # roll back this call's partial set
+            try:
+                lock_path(r).unlink()
+            except FileNotFoundError:
+                pass
+        if not a.wait:
+            print("BUSY " + holder_line(*blocker), file=sys.stderr)
+            return 2
+        if deadline and time.time() > deadline:
+            print("timeout waiting; " + holder_line(*blocker), file=sys.stderr)
+            return 4
+        time.sleep(a.poll)
+
+
+def resolve_targets(names):
+    """Each name is a resource with a live lock, or a group tag: expands to
+    every locked resource carrying that tag. Unknown names pass through."""
+    LEDGER.mkdir(parents=True, exist_ok=True)
+    locks = [rec for p in sorted(LEDGER.glob("*.lock.json"))
+             if (rec := read_lock(p))]
+    out = []
+    for name in names:
+        members = [r["resource"] for r in locks if r.get("group") == name]
+        if members and not any(r["resource"] == name for r in locks):
+            out.extend(members)
+        else:
+            out.append(name)
+    return sorted(set(out))
+
+
+def cmd_release(a):
+    owner = a.owner or default_owner()
+    rc = 0
+    for resource in resolve_targets(a.resources):
+        path = lock_path(resource)
+        rec = read_lock(path)
+        if rec is None:
+            print(f"{resource}: not held")
+            continue
+        if rec.get("owner") != owner and not a.force:
+            print(f"NOT YOURS {holder_line(resource, rec)}\n"
+                  f"(you are {owner}; use --force to break it)", file=sys.stderr)
+            rc = 3
+            continue
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+        verb = "broke" if rec.get("owner") != owner else "released"
+        print(f"{verb} {resource} (was {rec.get('owner')})")
+    return rc
+
+
+def cmd_status(a):
+    rows = ledger_rows()
+    if a.resource:
+        rows = [r for r in rows if r["resource"] == a.resource]
+        if not rows:
+            print(f"{a.resource}: free")
+            return 0
+    if a.json:
+        print(json.dumps(rows, indent=2))
+        return 0
+    if a.xbar:
+        held = [r for r in rows if r.get("owner")]
+        print(f"dibs ✋{len(held)}" if held else "dibs ✓")
+        print("---")
+        if not rows:
+            print("no resources.json yet | color=gray")
+        for r in rows:
+            if r.get("owner"):
+                note = f" · {r['note']}" if r.get("note") else ""
+                grp = f" · {r['group']}" if r.get("group") else ""
+                print(f"{r['resource']} — {r['owner']}{note}{grp} | color=#e05d44")
+            else:
+                print(f"{r['resource']} — free | color=#44a05d")
+        return 0
+    if not rows:
+        print(NO_REGISTRY, file=sys.stderr)
+        return 1
+    for r in rows:
+        if r.get("owner"):
+            print(holder_line(r["resource"], r))
+        else:
+            desc = f"  ({r['description']})" if r.get("description") else ""
+            print(f"{r['resource']}: free{desc}")
+    return 0
+
+
+def cmd_wait(a):
+    deadline = time.time() + a.timeout if a.timeout else None
+    while True:
+        resources = resolve_targets(a.resources)
+        held = next(((r, rec) for r in resources
+                     if (rec := read_lock(lock_path(r)))), None)
+        if held is None:
+            print(", ".join(a.resources) + ": free")
+            return 0
+        if deadline and time.time() > deadline:
+            print("timeout: " + holder_line(*held), file=sys.stderr)
+            return 4
+        time.sleep(a.poll)
+
+
+def cmd_run(a):
+    import subprocess
+    if "--" in a.argv:
+        i = a.argv.index("--")
+        if a.argv[:i]:
+            print("dibs run: put dibs flags BEFORE <resource> "
+                  f"(these were ignored: {' '.join(a.argv[:i])})", file=sys.stderr)
+            return 1
+        argv = a.argv[i + 1:]
+    else:
+        argv = a.argv
+    if argv and argv[0].startswith("-"):
+        print("dibs run: put dibs flags BEFORE <resource>; the command goes "
+              "after -- (dibs run --note x <resource> -- cmd ...)", file=sys.stderr)
+        return 1
+    if not argv:
+        print("dibs run: no command given (dibs run <resource> -- cmd ...)",
+              file=sys.stderr)
+        return 1
+    a.resources = [a.resource]
+    rc = cmd_claim(a)
+    if rc != 0:
+        return rc
+    try:
+        return subprocess.call(argv)
+    finally:
+        try:
+            lock_path(a.resource).unlink()
+        except FileNotFoundError:
+            pass
+        print(f"released {a.resource}", file=sys.stderr)
+
+
+def cmd_watch(a):
+    try:
+        while True:
+            rows = ledger_rows()
+            sys.stdout.write("\x1b[2J\x1b[H")
+            print(f"dibs ledger · {LEDGER}  (ctrl-c to quit)\n")
+            if not rows:
+                print("  " + NO_REGISTRY)
+            for r in rows:
+                if r.get("owner"):
+                    print("  🔴 " + holder_line(r["resource"], r))
+                else:
+                    print(f"  🟢 {r['resource']}: free")
+            sys.stdout.flush()
+            time.sleep(a.poll)
+    except KeyboardInterrupt:
+        return 0
+
+
+def main():
+    p = argparse.ArgumentParser(
+        prog="dibs", description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"dibs {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def add_claim_args(sp, multi):
+        if multi:
+            sp.add_argument("resources", nargs="+", metavar="resource",
+                            help="resource or group names")
+        else:
+            sp.add_argument("resource", help="resource or group name")
+        sp.add_argument("--note", help="why you have it")
+        sp.add_argument("--as", dest="as_group", metavar="GROUP",
+                        help="name the group (default: auto g-xxxxxx when "
+                             "claiming several resources)")
+        sp.add_argument("--owner", help="override owner id (or set $DIBS_OWNER)")
+        sp.add_argument("--wait", action="store_true", help="block until claimable")
+        sp.add_argument("--timeout", type=int,
+                        help="give up after N seconds (with --wait)")
+        sp.add_argument("--poll", type=int, default=5, help="poll interval seconds")
+
+    sp = sub.add_parser(
+        "claim", help="claim resources/groups, all-or-nothing (exit 2 if busy)")
+    add_claim_args(sp, multi=True)
+    sp.set_defaults(fn=cmd_claim)
+
+    sp = sub.add_parser("release", help="release resources/groups you hold")
+    sp.add_argument("resources", nargs="+", metavar="resource")
+    sp.add_argument("--owner")
+    sp.add_argument("--force", action="store_true",
+                    help="break someone else's lock")
+    sp.set_defaults(fn=cmd_release)
+
+    sp = sub.add_parser("status", help="show the ledger (all, or one resource)")
+    sp.add_argument("resource", nargs="?")
+    sp.add_argument("--json", action="store_true")
+    sp.add_argument("--xbar", action="store_true",
+                    help="xbar/SwiftBar plugin output")
+    sp.set_defaults(fn=cmd_status)
+
+    sp = sub.add_parser("wait", help="block until resources are free (no claim)")
+    sp.add_argument("resources", nargs="+", metavar="resource")
+    sp.add_argument("--timeout", type=int)
+    sp.add_argument("--poll", type=int, default=5)
+    sp.set_defaults(fn=cmd_wait)
+
+    sp = sub.add_parser(
+        "run", help="claim, run a command, auto-release: dibs run gpu -- make train")
+    add_claim_args(sp, multi=False)
+    sp.add_argument("argv", nargs=argparse.REMAINDER)
+    sp.set_defaults(fn=cmd_run)
+
+    sp = sub.add_parser("watch", help="live terminal view of the ledger")
+    sp.add_argument("--poll", type=int, default=2)
+    sp.set_defaults(fn=cmd_watch)
+
+    a = p.parse_args()
+    sys.exit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()