npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jmanuelcorral/bond-app

v0.1.4

Published

Local orchestrator and hub-container runner for multi-agent tickets

Readme

bond-app

Orquestador local de runs en hub-contenedores Docker, con herdr-app como interfaz (ver el plan en bond-hub/docs/plans/; decisión D19).

  • Backend: el orquestador (npm start), solo en loopback, con la API local de D13 (token por instalación en ~/.bond-app/token, fichero 0600).
  • Frontend: herdr-app con el layout bond y sus mods. bond-board es el tablero de tickets con 5 columnas de ancho fijo (Ready, Running, Waiting, Finished, Error): lanzar y cancelar runs, selección de tarjeta para enfocar la consola inferior de herdr-app con la sesión activa (terminal.show), crear tickets con historia enlazada (GitHub issue), diálogo de borrado con comprobación de integración de rama remota, contadores y filtros. bond-settings es el panel plegable de Ajustes (credenciales de agentes, GitHub y «Rebuild»). bond-titlebar es la barra de título propia: logo de bond, botones Agentes y Ajustes, arrastrable, con minimizar, maximizar y cerrar en Linux y Windows. bond-status es la barra de estado: API, GitHub, versiones y runs activos. Todo vive en app/ y se instala con un comando.
  • Identidad visual (P6): temas bond-light y bond-dark sacados de la guía de estilo de la web, y el logo rediseñado en SVG (app/brand/). El mapeo de tokens, las diferencias con la web y lo que no se puede cambiar están en app/brand/TOKENS.md. Para retocar colores se editan app/themes/*.json (y su fila en TOKENS.md) y se ejecuta npm run app:install.
  • Sesión del run: cada contenedor lleva herdr-core (hc); al arrancar el run, el orquestador lo registra como máquina de hc (bond-<run>) por docker exec, sin SSH ni puertos publicados, y arranca el agente en una terminal de hc como runner. Pulsar la tarjeta abre esa terminal en herdr-app (terminal.peek). Al terminar, cancelar o reconciliar el run, la máquina se borra con el contenedor y su red.

GitHub (D20): en Ajustes, «Usar mi sesión de gh» guarda en el orquestador el token de gh auth token (base SQLite 0600, como las credenciales de agentes; la API solo dice si hay credencial y su login). Lanzar un run no pide token: usa ese, que llega al contenedor por stdin. Sin credencial, el lanzamiento se rechaza y el diálogo lo dice. Si gh no tiene sesión, «Iniciar sesión» abre una pestaña con gh auth login --web.

Fin del run y entrega (P7): el run pasa de running a Finished cuando el agente termina con código 0, o por entrega explícita. El contenedor Docker y la sesión de herdr permanecen vivos. La entrega (crear PR) ya no es automática: el usuario la solicita a través del agente (o con el botón «Entregar…» en la tarjeta). El agente corre bond-app pr dentro del contenedor (sin parámetros y sin token de GitHub), que pide la entrega al orquestador a través del socket local /var/run/bond-app/bond-app.sock. La entrega:

  1. Verifica con los verify_commands del ticket (array de comandos de shell que se ejecutan como runner en el clon). Si uno falla bajo el límite (por defecto 3), el run vuelve a Running y el agente recibe el comando y su salida para reintentar; al alcanzar el límite consecutivo, pasa a Waiting (verification_failed) esperando la intervención del usuario (nudge/desbloqueo).
  2. Commit de lo que dejó el agente en feat/<ticket> (sin hooks).
  3. Push solo de la rama del ticket al repo del ticket: lo hace el orquestador, no el agente. El token (D20) entra por stdin de un docker exec como root que empuja desde un repo limpio (sin hooks ni configuración que el agente pueda haber escrito); el agente nunca lo tiene. Cualquier otro repo o rama se rechaza antes de ejecutar nada.
  4. PR con la API REST de GitHub desde el host (token solo en la cabecera), con el resumen del ticket; evento run.pr_opened.

Borrado de tarjeta (P7): cada tarjeta dispone de un botón «Borrar…» en todos sus estados (DELETE /api/v1/tickets/:id o /runs/:id, que borra el ticket completo y todos sus runs asociados). Al pulsarlo se abre un diálogo de confirmación que detiene y elimina el contenedor Docker, la red, la máquina en herdr-core y los worktrees locales. En estado Finished, antes de borrar la rama remota feat/<ticket>, el orquestador comprueba contra GitHub si dicha rama ya fue integrada (merged) en la rama base (main); si no está integrada, la UI advierte al usuario y requiere pulsar «Borrar igualmente» para forzar la eliminación remota.

Correspondencia entre estados del run y columnas del tablero (P7)

El tablero de bond-board organiza las tarjetas en cinco columnas de ancho fijo. Cada estado interno del run (RunState) mapea a una columna:

| Columna en el tablero | Estados del run (RunState) | Descripción en el flujo de trabajo | |---|---|---| | Ready | ready, queued, analyzing | Ticket recién creado, encolado para arranque o en proceso de registro y análisis del hub. | | Running | running, verifying | Ejecución activa de los agentes en el contenedor o verificación en curso de los verify_commands. | | Waiting | waiting, blocked | Algún agente espera respuesta del usuario (waiting), o el run está bloqueado (blocked: hub incompleto, límite de fallos de verificación, error en registro de issue). | | Finished | finished, pr_ready | El agente o equipo terminó su trabajo con éxito (o entrega realizada). El usuario puede inspeccionar la consola, pedir la entrega (bond-app pr) o borrar la tarjeta. | | Error | failed | Error irrecuperable (fallo de contenedor, timeout, presupuesto agotado, salida anómala del agente o fallo en push/PR). |

Hub en cada run (P5): un ticket trabaja sobre un solo repo (repo_url, el flujo de P4), sobre una lista de repos (repos: [{url, base_branch?, agent?}]; con dos o más, el run crea un hub con bond hub init/add) o sobre un hub que ya existe (hub_url, hub_base y, opcional, repo_agents: {repo: agente}). Los tickets antiguos se leen como lista de uno. En un run con hub:

  1. Montaje: se clona el hub (o se crea) en /workspace/hub y cada repo de su hub.toml con la credencial de GitHub, un clon cada vez y siempre por stdin (D8). Un submódulo se monta moviendo su clon a su ruta; un enlace, con un .bond/hub.local.toml propio del contenedor que apunta a su clon.

  2. Análisis (estado analyzing, evento hub.analysis): comprobaciones fijas (bond hub sync --yes y bond hub check; repos sin url, fuera de github.com o que el token no puede leer; bases que no existen; agentes del equipo que no están en la imagen; el check agentes de bond hub check cuenta solo si nombra el agente del equipo en ese repo) y después un agente de hub (el pi del ticket en modo -p, solo con herramientas de lectura, con un HOME desechable que solo tiene su propia credencial: las del equipo entran en el contenedor después del análisis) que lee la historia, AGENTS.md y docs/ y dice qué repos faltan, o que falta algo sin lo que la historia no se puede hacer. Con huecos, el run pasa a Blocked (hub_incomplete) sin lanzar ningún agente de repo, y la tarjeta enseña el análisis. «Aprobar arreglos…» (POST /runs/:id/hub/approve) aplica los que tienen arreglo (url de un repo que no la tenía, si el token puede leer github.com/<dueño del hub>/<repo>; bond hub add de un repo que falta) en la rama del run del hub, los commitea allí y vuelve a analizar. El agente de hub corre con --no-approve (ignora el .pi del hub, que aún no es de confianza). BOND_APP_ANALYSIS_COMMAND sustituye el agente de hub (array JSON; el prompt va al final) u off lo quita. «Desbloquear…» en ese estado manda instrucciones al agente de hub, reintenta montar lo que falte y vuelve a analizar (también cuando ningún hueco tenía arreglo automático).

  3. Equipo: con el hub completo, la terminal de hc del run abre herdr (su TUI) y en ella bond team feat/<ticket> --yes: un worktree y un agente por repo. El agente de cada repo es el que le da el ticket (o el del ticket): el run lo pone como default_agent en el .bond/bond.toml de ese repo solo en disco, mientras se abre el equipo, y después lo deja como estaba. Solo valen agentes que la imagen trae (BOND_APP_IMAGE_AGENTS, hoy pi); otro se rechaza al crear el ticket. Reciben el prompt del ticket (bond team prompt). «Abrir sesión» en la tarjeta enseña esa sesión de herdr con los paneles de los agentes. La imagen trae la config de herdr sin el asistente de primer arranque y pi confía en /workspace y en los worktrees, para que nada se quede esperando una pregunta.

  4. Entrega por repo («Entregar…»): en cada repo con la rama del run, verificación en su worktree, commit de lo que dejó su agente y push de feat/<ticket> con las garantías de P4 (root sobre el sha exacto, base real de GitHub, guarda de .github/workflows, solo los repos del run y solo esa rama), y su PR; después el hub, si tiene remoto y su rama del run añade commits (p. ej. los arreglos aprobados). Los commits de config de bond (bond init en un repo) son cambios y se entregan. El estado de cada repo queda en el run (repo_states): si uno falla, el run pasa a Blocked nombrándolo, y un reintento no vuelve a empujar ni a abrir PR en los ya entregados. El ticket pasa a PR Ready solo cuando todos los repos con cambios tienen su PR. La tarjeta enseña cada repo con su PR. «Desbloquear…» en un run con hub bloqueado por la entrega manda el mensaje a todo el equipo (bond team prompt).

Si el push o el PR fallan, el run pasa a Blocked con el motivo. En una tarjeta Blocked, «Desbloquear…» manda un mensaje al agente (se escribe en su terminal, o abre otra con el mensaje si el agente ya salió) y el run vuelve a Running (POST /runs/:id/nudge). Si el core de hc del host se reinicia y pierde la máquina de un run vivo, la pasada periódica la vuelve a registrar y la sesión se abre de nuevo (M-1).

Supone una máquina de un solo usuario (D18): no hay usuarios múltiples en el host. Cualquier proceso local que lea el fichero del token o llegue a loopback puede usar la API; si bond-app pasara a un host multiusuario, esto y D13 deben revisarse antes.

Versiones

  • herdr-app 0.1.12 o posterior y hc 0.1.17 o posterior en el host (las comprueba npm run app:install; la barra de estado las muestra).
  • La imagen del runner (runner/Dockerfile, etiqueta bond-app-runner:p5) fija hc 0.1.17 y herdr 0.9.3 con su sha256, bond y pi; sigue sin sshd ni puertos. Para otra versión de hc, «Rebuild» acepta {"hc": "<versión>", "hc_sha256": "<sha256>"} (de https://releases.herdr.dev/core/<versión>/manifest.json), y para herdr {"herdr": "v<versión>", "herdr_sha256": "<sha256>"}; versión y checksum van juntos.
  • herdr-app y hc están en 0.1.x: tras cada actualización, npm run app:install -- --check.

Arrancar y CLI bond-app

bond-app se distribuye como paquete npm público (@jmanuelcorral/bond-app) con el binario bond-app. Se puede instalar directamente desde npm, desde el repo o empaquetarlo localmente:

npm install -g @jmanuelcorral/bond-app

# O desde un paquete local:
npm pack
npm install -g ./jmanuelcorral-bond-app-0.1.2.tgz

Publicar en npm

La publicación va por staged publishing desde GitHub Actions (.github/workflows/release.yml), al subir un tag vX.Y.Z. Procedimiento:

  1. Subir version en package.json (una versión publicada no se puede sobrescribir) y commitear.
  2. Etiquetar y subir el tag: git tag vX.Y.Z && git push origin vX.Y.Z. El workflow comprueba que el tag coincide con package.json, pasa typecheck y tests unitarios, crea la release de GitHub con el .tgz adjunto y deja ese mismo .tgz en el staging de npm (npm stage publish). Autentifica con el secret NPM_TOKEN si está definido; si no, por OIDC (trusted publishing: hay que dar de alta el repo y el workflow en npmjs.com → el paquete → Trusted Publishing).
  3. Aprobar el staged package con 2FA: el workflow imprime el stage-id en el resumen del job; npm stage approve <stage-id> o npmjs.com → pestaña Staged Packages → Approve. Hasta aprobarlo, la versión no es pública.

--provenance (attestations SLSA) solo se pasa mientras el repo es público: sigstore rechaza repos fuente privados (Unsupported GitHub Actions source repository visibility: "private"). Con el repo privado el workflow publica sin procedencia y lo anuncia en el log; si el repo se hace público, las attestations vuelven solas.

Antes de publicar se puede comprobar el contenido: npm pack --dry-run. No deben aparecer los ficheros generados de los mods (gpui-kit.d.ts, jsconfig.json); están excluidos con patrones ! en files. Si el .npmrc de una máquina apunta el scope a otro registro (p. ej. @jmanuelcorral:registry=https://npm.pkg.github.com), al instalar hay que sobrescribirlo: npm install -g @jmanuelcorral/bond-app --@jmanuelcorral:registry=https://registry.npmjs.org/.

Comandos del binario bond-app

  • bond-app start [opciones] — Arranca el orquestador en primer plano.
    • Directorio de datos por defecto: ~/.bond-app (o $BOND_APP_DATA_DIR).
    • Opciones: --port <puerto> (defecto 3000), --host <ip> (defecto 127.0.0.1, solo loopback por D13), --data-dir <directorio>.
    • Parada limpia: al recibir SIGINT (Ctrl+C) o SIGTERM, cierra el servidor HTTP, detiene temporizadores y elimina sockets de runs activos saliendo con código 0.
  • bond-app install [opciones] — Instala el layout bond, los mods y los temas en herdr-app (~/.config/herdr-app).
    • Opciones: --home <dir> ($HERDR_APP_HOME), --api <url>, --token-file <ruta>, --check, --skip-version-check, --force, --launcher, --remove-launcher.
  • bond-app open [opciones] — Abre herdr-app (si no está arrancado) y cambia al layout bond (herdr-app do layout.switch --name bond).
    • Opciones: --home <dir> ($HERDR_APP_HOME), --timeout <ms> (defecto 10000).
  • bond-app status [opciones] — Consulta el estado del orquestador y la integración con herdr-app.
    • Opciones: --port <puerto>, --host <ip>, --data-dir <dir>, --home <dir>, --json.
    • Código de salida: 0 si el orquestador está corriendo (o si se invoca con --json), 1 si está parado.
  • bond-app --version (-v, version) — Muestra la versión (0.1.2).
  • bond-app --help (-h, help) — Muestra la ayuda de uso.

Arranque desde bond (bond app)

Al ejecutar bond app (o bond sin subcomando cuando default_command = "app", D21):

  1. Comprueba si bond-app está en el PATH (si no, explica cómo instalarlo).
  2. Ejecuta bond-app install para asegurar que el layout, los mods y los temas están al día.
  3. Ejecuta bond-app open para abrir herdr-app con el layout bond.
  4. Ejecuta bond-app start en primer plano en la terminal (Ctrl+C para limpiamente el orquestador).

Uso directo desde el repositorio

npm ci --ignore-scripts
DOCKER_BUILDKIT=0 docker build -t bond-app-runner:p5 runner/   # o «Rebuild» desde ajustes
npm start                                                       # orquestador en 127.0.0.1:3000 (node bin/bond-app.js start)
node bin/bond-app.js install -- --check                         # layout, mods y temas en ~/.config/herdr-app
node bin/bond-app.js install -- --check --launcher              # además, el lanzador «bond» (opcional)
node bin/bond-app.js open                                       # abre herdr-app con el layout bond
node bin/bond-app.js status                                     # estado del orquestador

Después, en herdr-app: ctrl-shift-l hasta el layout «bond» (o herdr-app do layout.switch --name bond). El instalador no toca la ventana abierta, ni sobrescribe mods o layouts que no instaló él. Opciones: --home <dir> (o HERDR_APP_HOME), --api <url> (loopback), --token-file <ruta> (por defecto $BOND_APP_DATA_DIR/token o ~/.bond-app/token), --force (sustituir un bond.json o un tema bond-*.json editado). Los temas se instalan en themes/ del home de herdr-app y el logo en mods/bond-titlebar/brand/; sin tocar temas que no instaló él.

Lanzador «bond» (opcional)

--launcher añade al menú del escritorio un lanzador «bond» con el icono de bond, en el directorio de datos XDG ($XDG_DATA_HOME, si no ~/.local/share): applications/bond-app.desktop, icons/hicolor/scalable/apps/bond-app.svg y bond-app/bond-launch. Este último abre herdr-app, o usa la ventana abierta, y muestra el layout bond. No toca herdr-app.desktop ni su icono, ni pisa un lanzador que no sea suyo. npm run app:install -- --remove-launcher lo quita.

Lo que no se puede cambiar sin tocar ficheros de herdr-app: el icono de la ventana abierta y de su entrada en la barra de tareas. El escritorio los asocia por la clase de la ventana (herdr-app) con herdr-app.desktop (Icon=herdr-app), así que, aunque se abra desde «bond», la ventana sigue llevando el icono de herdr-app. Tampoco se pueden cambiar las pantallas propias de herdr-app (bienvenida, ajustes, novedades), que no son mods del layout. Dentro de la ventana, nada de lo que dibuja el layout bond usa el logo de herdr.

BOND_APP_AGENT_COMMAND (array JSON, p. ej. '["bash"]') sustituye el agente del ticket en la terminal del run: sirve para probar sin un agente de pago.

Comprobaciones

  • npm run typecheck — tipos (orquestador, tests e instalador)
  • npm test — unitarias
  • npm run test:ui — frontend de herdr-app sin ventana: modelo del tablero, herdr-app check de cada mod y vista, layout, contraste AA de los temas, TOKENS.md frente a los temas, e instalador (con lanzador) contra un HERDR_APP_HOME y un XDG_DATA_HOME temporales
  • npm run test:integration — con Docker y hc reales (sesión de hc propia en /tmp/bhc-*, nunca la del usuario); necesita la imagen bond-app-runner:p5
  • Entrega de extremo a extremo (P4): BOND_APP_E2E_SANDBOX=<owner>/<repo privado de prueba> npm run test:integration. Empuja ramas y abre PRs en ese repo con la sesión de gh del host, y al terminar cierra los PRs y borra las ramas. Usa pi con el proveedor propio llamaswap (0 USD) si está en ~/.pi/agent/models.json. Nunca contra un repo real.
  • Hub de extremo a extremo (P5): BOND_APP_E2E_HUB=<owner>/<hub privado de prueba> npm run test:integration. El hub de prueba lleva en hub.toml los repos privados bond-app-sandbox-2 (submódulo) y bond-app-sandbox-3 (enlace con url), del mismo dueño; el criterio 3 con agente nombra bond-app-sandbox. Monta un hub existente, crea uno desde una lista y bloquea uno incompleto hasta «Aprobar arreglos», con pi en llamaswap (0 USD). Solo empuja una rama temporal del hub, que borra al acabar.