agents-city 0.1.0

package/plugin/scripts/report.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Report growth from where the work actually happens.
+
+The city's cron can count merged pull requests by itself. It cannot run a command
+inside your folders — and in a marketing, legal or finance city, growth is
+whatever a command in that folder returns: pieces published, documents filed,
+periods closed.
+
+So this runs where the folders are, once a day is plenty, and reports the totals.
+The city works out what changed today.
+
+    ./bin/report.py                 show what it would send
+    ./bin/report.py --push          send it
+    ./bin/report.py --data ../mine  read a different data repo
+
+Nothing to run by hand in the normal case: the plugin reports once a day from a
+Stop hook. This is here for the first look, and for a backfill.
+
+It needs your bus token, because the city does not take numbers from anonymous
+callers: `CITY_BUS_TOKEN`, or the plugin's keychain entry, or `--token`.
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import city_env
+import parcels  # the one reader of parcels.yml, shared with the seeder
+
+
+def lee(fichero, clave, defecto=''):
+    try:
+        t = open(fichero).read()
+    except FileNotFoundError:
+        return defecto
+    m = re.search(rf'^{clave}:\s*(.+)$', t, re.M)
+    return m.group(1).strip() if m else defecto
+
+
+_DONDE = {}
+
+
+def donde_esta(repo):
+    """The local folder of a repo, by the name on its remote.
+
+    `parcels.yml` deliberately holds no local paths: the same file is shared by a
+    whole team and the same repo sits somewhere different on every machine. That is
+    what find-repos.sh is for, and it caches its index for a day.
+    """
+    if repo not in _DONDE:
+        guion = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'find-repos.sh')
+        try:
+            r = subprocess.run([guion, repo], capture_output=True, text=True, timeout=300)
+            _DONDE[repo] = r.stdout.strip()
+        except (OSError, subprocess.TimeoutExpired):
+            _DONDE[repo] = ''
+    return _DONDE[repo]
+
+
+def parcelas(datos):
+    """Every parcel, with the folder to run its grow command in.
+
+    The format is read by `parcels.py`, which the seeder reads too. All this adds is
+    the one thing that is local to this machine: where the folder actually is.
+
+    The folder used to be read as `c.get('path')` — a key this format does not have
+    and no writer has ever written; it is `ruta`. So it was always empty, every
+    parcel was skipped as folderless, and this script could not report a single
+    number for anybody. The message it printed sent you to add a `path:` that means
+    nothing.
+
+    `ruta` is a glob *inside* the repo, not a path to it. A concrete subdirectory
+    becomes the folder; a glob, or an empty one, means the whole repo, because there
+    is no single directory a pattern points at.
+    """
+    declaradas, _, raras = parcels.lee(f'{datos}/parcels.yml')
+    if raras:
+        print(parcels.aviso(raras), file=sys.stderr)
+    fuera = []
+    for p in declaradas:
+        base = donde_esta(p['repo'])
+        carpeta = base
+        if base and p['ruta'] and not any(c in p['ruta'] for c in '*?['):
+            dentro = os.path.join(base, p['ruta'])
+            if os.path.isdir(dentro):
+                carpeta = dentro
+        fuera.append(dict(p, path=carpeta))
+    return fuera
+
+
+def cuenta(comando, cwd):
+    """Run the grow command and take the first number it prints.
+
+    A command that fails counts as *unknown*, not as zero. Reporting zero because
+    a script broke would look like work being undone, which is worse than a gap.
+    """
+    if not comando:
+        return None
+    try:
+        r = subprocess.run(comando, shell=True, cwd=cwd, capture_output=True,
+                           text=True, timeout=120)
+    except subprocess.TimeoutExpired:
+        return None
+    if r.returncode != 0:
+        return None
+    m = re.search(r'-?\d+', r.stdout.replace(',', ''))
+    return int(m.group()) if m else None
+
+
+def mide(datos, por_defecto, todas):
+    """Run each parcel's grow command where it lives. A command that fails is
+    *unknown*, never zero — zero would look like work being undone."""
+    filas, sin_medir = [], []
+    for p in todas:
+        carpeta = os.path.expanduser(p['path']) if p['path'] else None
+        if not carpeta or not os.path.isdir(carpeta):
+            continue
+        # The folder's own descriptor wins over the city default: a parcel knows
+        # better than the city how it is counted.
+        cmd = lee(os.path.join(carpeta, '.city.yml'), 'grow_command', por_defecto)
+        n = cuenta(cmd, carpeta)
+        if n is None:
+            sin_medir.append(p['id'])
+        else:
+            filas.append({'id': p['id'], 'floors': n})
+    return filas, sin_medir
+
+
+def explica_vacio(di, datos, todas, por_defecto):
+    """Nothing measured: say which of the three reasons it is, precisely. The
+    version before this printed advice about a field that does not exist."""
+    perdidas = [p['repo'] for p in todas if not p['path']]
+    di(f'Nothing to report from {datos}.')
+    if not todas:
+        di('There are no parcels in parcels.yml yet. ./bin/seat writes one per '
+           'folder you pick.')
+    elif perdidas:
+        di(f'{len(perdidas)} of {len(todas)} parcels are not cloned on this '
+           f'machine, so there is no folder to run anything in:')
+        di('  ' + ', '.join(sorted(set(perdidas))[:10]))
+        di('Clone them, or run ./plugin/scripts/find-repos.sh --refresh if they '
+           'are here under another folder name.')
+    elif not por_defecto:
+        di('The folders are here, but nothing says how growth is counted. Put '
+           '`grow_command` in city.yml, or a `.city.yml` in each folder.')
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--data', default=city_env.datos())
+    ap.add_argument('--url', default=city_env.url())
+    ap.add_argument('--token', default='')
+    ap.add_argument('--push', action='store_true')
+    ap.add_argument('--quiet', action='store_true', help='say nothing unless it fails')
+    a = ap.parse_args()
+    di = (lambda *x, **k: None) if a.quiet else print
+    datos = os.path.expanduser(a.data)
+
+    por_defecto = lee(f'{datos}/city.yml', 'grow_command')
+    todas = parcelas(datos)
+    filas, sin_medir = mide(datos, por_defecto, todas)
+
+    if not filas and not sin_medir:
+        explica_vacio(di, datos, todas, por_defecto)
+        return 0
+
+    for f in filas:
+        di(f"  {f['id']:<34} {f['floors']}")
+    for s in sin_medir:
+        di(f'  {s:<34} — could not measure (command failed or returned nothing)')
+
+    if not a.push:
+        di('\nNothing sent. Add --push when it looks right.')
+        return 0
+    if not a.url:
+        print('\nNo city URL. Pass --url or set AGENTS_CITY_URL.', file=sys.stderr)
+        return 1
+    tk = city_env.token(a.token)
+    if not tk:
+        print('\nNo bus token. Pass --token or set CITY_BUS_TOKEN.', file=sys.stderr)
+        return 1
+
+    req = urllib.request.Request(
+        a.url.rstrip('/') + '/api/growth',
+        data=json.dumps({'parcels': filas}).encode(),
+        headers={'content-type': 'application/json', 'authorization': f'Bearer {tk}'})
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r:
+            di('\n' + r.read().decode())
+    except Exception as e:
+        print(f'\nThe city refused it: {e}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugin/scripts/reset.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Reset one managed city to first-run state, recoverably.
+
+The target is always explicit.  Repos are references and are never touched.  The
+city folder and its local map state move to a timestamped backup, incident local
+roads are removed at both ends, and an empty city with the same stable identity
+is created in its place.  The next ``agents-city seat --city <name>`` runs the
+five onboarding questions again.
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+import cities
+import domains
+import roads
+import runtime_processes
+
+
+def _backup_path(usuario, datos):
+    sello = time.strftime("%Y%m%d-%H%M%S")
+    base = os.path.join(cities.carpeta_usuario(usuario), ".backups")
+    nombre = f"{cities.slug_ciudad(datos)}-{sello}"
+    ruta = os.path.join(base, nombre)
+    n = 2
+    while os.path.exists(ruta):
+        ruta = os.path.join(base, f"{nombre}-{n}")
+        n += 1
+    return ruta
+
+
+def _deten(datos, dry_run=False):
+    guion = os.path.join(os.path.dirname(__file__), "apaga.py")
+    args = [sys.executable, guion, datos]
+    if dry_run:
+        args.append("--dry-run")
+    return subprocess.run(args, capture_output=True, text=True)
+
+
+def _valida(datos, usuario):
+    usuario = usuario or cities.usuario_actual()
+    datos = os.path.realpath(datos)
+    if not cities.gestionada(datos, usuario):
+        raise ValueError(
+            "reset only accepts a managed city under "
+            f"{cities.carpeta_usuario(usuario)}; external/shared "
+            "folders are never erased"
+        )
+    if not cities.es_ciudad(datos):
+        raise ValueError(f"{datos} is not a city")
+    owner_en_disco = cities.lee_clave(datos, "owner")
+    if owner_en_disco and owner_en_disco != usuario:
+        raise ValueError(f"this city belongs to {owner_en_disco!r}, not {usuario!r}")
+    return datos, usuario
+
+
+def _contexto(datos, usuario):
+    return {
+        "datos": datos,
+        "usuario": usuario,
+        "ident": cities.identidad(datos),
+        "nombre": cities.nombre(datos),
+        "slug": cities.slug_ciudad(datos),
+        "owner": cities.lee_clave(datos, "owner") or usuario,
+        "domain": domains.de_ciudad(datos),
+        "grow": cities.lee_clave(
+            datos, "grow_command", "git log --since=30.days --oneline | wc -l"
+        ),
+        "backup": _backup_path(usuario, datos),
+        "estado": os.path.join(cities.raiz(), "state", cities.slug(datos)),
+        "runtime": runtime_processes.ruta(datos),
+        "roads": roads.lee(datos),
+    }
+
+
+def _preview(ctx):
+    print(f"  Would reset city `{ctx['slug']}` at {ctx['datos']}")
+    print(f"  Would preserve it at {ctx['backup']}")
+    print("  Would leave every referenced repo untouched")
+    if ctx["roads"]:
+        print(f"  Would close {len(ctx['roads'])} road(s) at both ends")
+    parada = _deten(ctx["datos"], dry_run=True)
+    if parada.stdout.strip():
+        print(parada.stdout.rstrip())
+
+
+def _para(datos):
+    parada = _deten(datos)
+    if parada.returncode != 0:
+        detalle = (parada.stderr or parada.stdout or "unknown stop error").strip()
+        raise ValueError(f"could not stop the city before reset: {detalle}")
+
+
+def _cierra_carreteras(ctx):
+    """Back up and remove the other half of every incident local road."""
+    backlinks = os.path.join(ctx["backup"], "road-backlinks")
+    for camino in ctx["roads"]:
+        otro = roads.destino_local(camino, ctx["usuario"])
+        if not otro:
+            continue
+        os.makedirs(backlinks, exist_ok=True)
+        if os.path.isfile(roads.ruta(otro)):
+            destino = os.path.join(backlinks, f"{cities.slug_ciudad(otro)}.roads.json")
+            shutil.copy2(roads.ruta(otro), destino)
+        roads.desconecta(otro, ctx["ident"])
+
+
+def _mueve_si_existe(origen, destino):
+    if os.path.exists(origen):
+        shutil.move(origen, destino)
+
+
+def _respalda(ctx):
+    os.makedirs(ctx["backup"], exist_ok=False)
+    _cierra_carreteras(ctx)
+    shutil.move(ctx["datos"], os.path.join(ctx["backup"], "city"))
+    _mueve_si_existe(ctx["estado"], os.path.join(ctx["backup"], "state"))
+    _mueve_si_existe(ctx["runtime"], os.path.join(ctx["backup"], "runtime"))
+
+
+def _crea_vacia(ctx):
+    datos = ctx["datos"]
+    os.makedirs(datos, exist_ok=True)
+    cities.asegura_metadata(datos, ctx["owner"], ctx["nombre"], ctx["ident"])
+    # Keep stable identity and growth measure, but no seat, agents, repos or roads.
+    city_yml = os.path.join(datos, "city.yml")
+    texto = open(city_yml, encoding="utf-8").read()
+    if "\ndomain:" not in "\n" + texto:
+        texto += f"domain: {ctx['domain']}\n"
+    if "\ngrow_command:" not in "\n" + texto:
+        texto += f"grow_command: {ctx['grow']}\n"
+    cities.escribe_atomico(city_yml, texto)
+    roads.escribe(datos, [])
+    cities.selecciona(ctx["usuario"], datos)
+
+
+def reinicia(datos, usuario="", dry_run=False):
+    datos, usuario = _valida(datos, usuario)
+    ctx = _contexto(datos, usuario)
+    if dry_run:
+        _preview(ctx)
+        return ctx["backup"]
+
+    _para(datos)
+    _respalda(ctx)
+    _crea_vacia(ctx)
+    return ctx["backup"]
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Reset one city to onboarding; repos stay untouched and data is backed up"
+    )
+    ap.add_argument("city", help="city name or path (required)")
+    ap.add_argument("--dry-run", action="store_true", help="show every effect, change nothing")
+    a = ap.parse_args()
+    usuario = cities.usuario_actual()
+    datos = cities.resuelve(a.city, usuario)
+    if not datos:
+        conocidas = ", ".join(c["slug"] for c in cities.lista(usuario)) or "none"
+        print(f"  No city called {a.city!r}. Known here: {conocidas}.", file=sys.stderr)
+        return 1
+    try:
+        backup = reinicia(datos, usuario, a.dry_run)
+    except ValueError as e:
+        print(f"  {e}", file=sys.stderr)
+        return 1
+    if not a.dry_run:
+        corto = backup.replace(os.path.expanduser("~"), "~")
+        print(f"  City `{cities.slug_ciudad(datos)}` reset. Recovery copy: {corto}")
+        print(f"  Run `agents-city seat --city {cities.slug_ciudad(datos)}` for onboarding.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugin/scripts/roads.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Explicit roads between autonomous cities.
+
+Roads connect city seats, never users and never repo windows.  A local road is
+written at both ends.  A remote road is added from a small public invitation;
+the other end accepts this city's invitation independently.  No token or skill
+content is ever stored here.
+"""
+
+import json
+import os
+import re
+import sys
+
+import card
+import cities
+import domains
+
+
+ADDRESS_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}/[a-z0-9][a-z0-9_-]{0,63}$")
+ID_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,128}$")
+INVITATION_KEYS = {"version", "id", "name", "owner", "address", "domain", "role"}
+
+
+def _limpia(camino):
+    """Validate untrusted road metadata and return its storage shape."""
+    if not isinstance(camino, dict):
+        return None
+    ident = str(camino.get("id", "")).strip()
+    address = str(camino.get("address", "")).strip().lower()
+    if not ID_RE.fullmatch(ident) or not ADDRESS_RE.fullmatch(address):
+        return None
+    dueno, slug = address.split("/", 1)
+    owner = str(camino.get("owner") or dueno).strip().lower()
+    if owner != dueno:
+        return None
+    name = " ".join(str(camino.get("name") or slug).split())[:80] or slug
+    limpio = {"id": ident, "name": name, "owner": owner, "address": address}
+    dominio = domains.canonico(camino.get("domain"))
+    rol = str(camino.get("role") or "").strip().lower()
+    if dominio and re.fullmatch(r"[a-z0-9-]{1,80}", dominio):
+        limpio["domain"] = dominio
+    if rol and re.fullmatch(r"[a-z0-9-]{1,80}", rol):
+        limpio["role"] = rol
+    if camino.get("local"):
+        limpio["local"] = True
+    return limpio
+
+
+def ruta(datos):
+    return os.path.join(os.path.realpath(datos), "roads.json")
+
+
+def _atomico(ruta_, objeto):
+    os.makedirs(os.path.dirname(ruta_), exist_ok=True)
+    temporal = ruta_ + f".tmp-{os.getpid()}"
+    with open(temporal, "w", encoding="utf-8") as f:
+        json.dump(objeto, f, indent=2, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    os.replace(temporal, ruta_)
+
+
+def lee(datos):
+    try:
+        objeto = json.load(open(ruta(datos), encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, TypeError):
+        return []
+    caminos = objeto.get("roads", []) if isinstance(objeto, dict) else []
+    return [limpio for r in caminos if (limpio := _limpia(r)) is not None]
+
+
+def escribe(datos, caminos):
+    limpios, ids, direcciones = [], set(), set()
+    for camino in caminos:
+        limpio = _limpia(camino)
+        if not limpio or limpio["id"] in ids or limpio["address"] in direcciones:
+            continue
+        ids.add(limpio["id"])
+        direcciones.add(limpio["address"])
+        limpios.append(limpio)
+    limpios.sort(key=lambda r: (r["owner"], r["name"].lower(), r["id"]))
+    _atomico(ruta(datos), {"version": 1, "roads": limpios})
+
+
+def invitacion(datos, usuario=""):
+    usuario = usuario or cities.usuario_actual()
+    owner = cities.lee_clave(datos, "owner") or usuario
+    ficha = card.lee(os.path.join(datos, f"{owner}.md"))
+    invitacion_ = {
+        "version": 1,
+        "id": cities.identidad(datos),
+        "name": cities.nombre(datos),
+        "owner": owner,
+        "address": cities.direccion(usuario, datos),
+        "domain": domains.de_ciudad(datos),
+    }
+    if ficha.get("role"):
+        invitacion_["role"] = ficha["role"]
+    return invitacion_
+
+
+def _pon(datos, destino, local=False):
+    caminos = [r for r in lee(datos) if r["id"] != destino["id"]]
+    nuevo = dict(destino)
+    if local:
+        nuevo["local"] = True
+    caminos.append(nuevo)
+    escribe(datos, caminos)
+
+
+def conecta(origen, destino, usuario=""):
+    """Connect two cities on this machine, symmetrically."""
+    usuario = usuario or cities.usuario_actual()
+    if cities.identidad(origen) == cities.identidad(destino):
+        raise ValueError("a city cannot build a road to itself")
+    _pon(origen, invitacion(destino, usuario), local=True)
+    _pon(destino, invitacion(origen, usuario), local=True)
+
+
+def conecta_invitacion(origen, destino):
+    """Add the local half of a road to a remote city invitation."""
+    necesarios = {"id", "name", "owner", "address"}
+    if not isinstance(destino, dict) or not necesarios <= set(destino):
+        raise ValueError("the invitation is missing id, name, owner or address")
+    if not set(destino) <= INVITATION_KEYS:
+        raise ValueError("the invitation contains fields other than public city identity")
+    limpia = _limpia(destino)
+    if not limpia:
+        raise ValueError("the invitation has invalid or inconsistent identity")
+    origen_publico = invitacion(origen)
+    if limpia["id"] == origen_publico["id"] or limpia["address"] == origen_publico["address"]:
+        raise ValueError("a city cannot build a road to itself")
+    _pon(origen, limpia, local=False)
+
+
+def desconecta(origen, destino_id):
+    antes = lee(origen)
+    despues = [r for r in antes if r["id"] != destino_id]
+    escribe(origen, despues)
+    return len(antes) != len(despues)
+
+
+def desconecta_local(origen, destino):
+    a = desconecta(origen, cities.identidad(destino))
+    b = desconecta(destino, cities.identidad(origen))
+    return a or b
+
+
+def quita_incidentes(datos, usuario=""):
+    """Remove every local edge touching a city; used by a scoped reset."""
+    usuario = usuario or cities.usuario_actual()
+    ident = cities.identidad(datos)
+    for otra in cities.lista(usuario):
+        if os.path.realpath(otra["ruta"]) != os.path.realpath(datos):
+            desconecta(otra["ruta"], ident)
+    escribe(datos, [])
+
+
+def destino_local(camino, usuario=""):
+    """Resolve a road record to a city currently present on this machine."""
+    if not camino.get("local"):
+        return ""
+    usuario = usuario or cities.usuario_actual()
+    return next((c["ruta"] for c in cities.lista(usuario) if c["id"] == camino.get("id")), "")
+
+
+def _resuelve(nombre, usuario):
+    datos = cities.resuelve(nombre, usuario)
+    if not datos:
+        conocidas = ", ".join(c["slug"] for c in cities.lista(usuario)) or "none"
+        raise ValueError(f"no city called {nombre!r}; known here: {conocidas}")
+    return datos
+
+
+def _ayuda():
+    return """usage:
+  agents-city road list <city>
+  agents-city road connect <city> <local-city|invitation.json>
+  agents-city road disconnect <city> <local-city|city-id>
+  agents-city road invite <city>
+
+Roads are explicit. Connecting two local cities writes both ends. For a remote
+city, exchange the public JSON printed by `road invite`; it contains no token."""
+
+
+def main():
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(_ayuda())
+        return 0
+    usuario = cities.usuario_actual()
+    try:
+        if args[0] == "list" and len(args) == 2:
+            origen = _resuelve(args[1], usuario)
+            caminos = lee(origen)
+            if not caminos:
+                print(f"  {cities.nombre(origen)} has no roads.")
+            for r in caminos:
+                local = "local" if destino_local(r, usuario) else "remote"
+                print(f"  {r['name']}  {r['address']}  [{local}]")
+            return 0
+        if args[0] == "invite" and len(args) == 2:
+            print(json.dumps(invitacion(_resuelve(args[1], usuario)), indent=2))
+            return 0
+        if args[0] == "connect" and len(args) == 3:
+            origen = _resuelve(args[1], usuario)
+            destino = cities.resuelve(args[2], usuario)
+            if destino:
+                conecta(origen, destino, usuario)
+                print(f"  Road open: {cities.nombre(origen)} <-> {cities.nombre(destino)}")
+            else:
+                with open(os.path.expanduser(args[2]), encoding="utf-8") as f:
+                    conecta_invitacion(origen, json.load(f))
+                print(f"  Remote road added to {cities.nombre(origen)}.")
+            return 0
+        if args[0] == "disconnect" and len(args) == 3:
+            origen = _resuelve(args[1], usuario)
+            destino = cities.resuelve(args[2], usuario)
+            cambiado = desconecta_local(origen, destino) if destino else desconecta(origen, args[2])
+            print("  Road closed." if cambiado else "  No such road.")
+            return 0
+    except (OSError, ValueError, json.JSONDecodeError) as e:
+        print(f"  {e}", file=sys.stderr)
+        return 1
+    print(_ayuda(), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())