# Hoppscotch — consola de APIs + colecciones versionadas

GUI para explorar/probar APIs a mano (Hoppscotch Desktop) con las consultas guardadas
como JSON versionado en este sub-repo, y un puente bidireccional con el motor de replay
del registry para **lanzar y automatizar** esas mismas peticiones desde terminal o scripts.

Grupo de capacidad: `hoppscotch`. Página madre: `docs/capabilities/hoppscotch.md`.

## El ciclo

```
GUI Hoppscotch  ──export .json──▶  parse_hoppscotch_collection  ──call specs──▶  run_hoppscotch_collection ──▶ http_replay_sequence
      ▲                                                                                     (automatiza, headless)
      └──── build_hoppscotch_collection ◀── call specs (de HAR destilado, o a mano) ────────────────────────────┘
```

- **GUI → automatización**: editas/creas requests en la app, exportas la colección a
  `collections/<algo>.json`, y `run_hoppscotch_collection` las ejecuta sin tocar la GUI.
- **Automatización → GUI**: tienes call specs (p.ej. de un flujo grabado con HAR y destilado
  con `har_extract_calls`), `build_hoppscotch_collection` te da un `.json` importable en la app
  para inspeccionarlas visualmente.

## Estructura

```
hoppscotch/
  collections/              # Colecciones .json VERSIONADAS (sin secretos)
    registry_api.json       # ejemplo: 4 endpoints GET del registry_api
  environments/             # Variables de entorno Hoppscotch
    .gitignore              # ignora *.json (secretos) salvo *.example.json
    registry_api.example.json   # plantilla VERSIONADA (valores placeholder)
    registry_api.json           # real, GITIGNORED (puede llevar tokens)
  README.md
```

Regla de secretos: las **colecciones** se versionan; los **environments reales** no (llevan
tokens/basicAuth). Solo la plantilla `*.example.json` viaja en git. En las requests, los valores
sensibles van como variable de environment con la sintaxis Hoppscotch `<<nombre>>`, nunca
hardcodeados.

## Lanzar la app Desktop

Binario instalado por el `.deb`: `/usr/bin/hoppscotch-desktop` (menú de aplicaciones: "Hoppscotch").
Lanzado desde una sesión gráfica normal o, de forma aislada:

```bash
systemd-run --user --unit=hoppscotch-gui --setenv=DISPLAY=:0 /usr/bin/hoppscotch-desktop
```

### Importar una colección en la GUI

1. Panel **Collections** (izquierda) → menú **Import / Export**.
2. **Import** → **Hoppscotch** → **Import from File**.
3. Selecciona `collections/registry_api.json`.
4. (Opcional) Importa también el environment: panel **Environments** → Import →
   `environments/registry_api.example.json` y rellena los valores reales (no se versionan).
5. Selecciona el environment activo arriba a la derecha y pulsa **Send** en cualquier request.

### Exportar / ver el JSON que genera la GUI

Collections → menú → **Export** → **Hoppscotch** → guarda en `collections/`. Así se ve el
esquema nativo de la versión instalada (la app migra al esquema más reciente al importar/exportar).
`parse_hoppscotch_collection` lee cualquier versión v1..v12 por campos estables.

## Automatizar desde el registry

Lanzar toda una colección o un subconjunto, headless, con sustitución de variables:

```python
import sys, os
sys.path.insert(0, os.path.join(os.path.expanduser("~/fn_registry"), "python", "functions"))
from infra.run_hoppscotch_collection import run_hoppscotch_collection

res = run_hoppscotch_collection(
    "projects/web_scraping/hoppscotch/collections/registry_api.json",
    environment_path="projects/web_scraping/hoppscotch/environments/registry_api.json",
    params={"baseURL": "https://registry.organic-machine.com"},  # pisa el environment
    only=["status", "locations"],   # filtra por nombre de request; None = todas
)
print(res["status"])
for s in res["steps"]:
    print(s["method"], s["url"], "->", s["status_code"], "ok" if s["ok"] else "FAIL")
```

`run_hoppscotch_collection` convierte la sintaxis Hoppscotch `<<var>>` a la del motor de replay
`{{var}}`, mergea environment + params (params del caller ganan), filtra por `only`, y reproduce
las peticiones sobre una sesión HTTP compartida (cookie jar entre pasos).

## Añadir peticiones rápido

Sin editar el `.json` a mano, con `add_hoppscotch_request` (reusa el mapeo de `build`, no
destruye el archivo si el JSON es inválido):

```python
from infra.add_hoppscotch_request import add_hoppscotch_request
r = add_hoppscotch_request(
    "projects/web_scraping/hoppscotch/collections/registry_api.json",
    "GET", "<<baseURL>>/api/search?q=metabase&kind=function",
    name="search metabase", headers={"Accept": "application/json"})
print(r["status"], r["total_requests"])   # ok 8
```

Tras añadir, re-importa la colección en la app Desktop (no recarga el `.json` en caliente) o
córrela headless con `run_hoppscotch_collection` / `hopp test`.

## Validar la colección

Dos motores independientes, ambos verde sobre `registry_api.json` (7 requests → 7×200):

```bash
# Motor nativo Hoppscotch (corre también preRequestScript/testScript JS):
hopp test collections/registry_api.json -e environments/registry_api.cli.json

# Motor del registry (integrado, telemetría, params/extract):
python3 -c 'from infra.run_hoppscotch_collection import run_hoppscotch_collection as r; \
  print(r("collections/registry_api.json", environment_path="environments/registry_api.json")["status"])'
```

## Funciones del registry

| ID | Qué hace |
|---|---|
| `build_hoppscotch_collection_py_infra` | call specs → dict de colección Hoppscotch (importable en la GUI) |
| `parse_hoppscotch_collection_py_infra` | dict de colección Hoppscotch (v1..v12) → call specs |
| `run_hoppscotch_collection_py_infra` | lee colección + environment .json y ejecuta vía `http_replay_sequence` |
| `add_hoppscotch_request_py_infra` | añade una petición a una colección `.json` existente (reusa `build`, no destructivo) |
| `http_replay_sequence_py_infra` | motor de replay HTTP (secuencia con sesión, `{{param}}`, extract) |
| `har_extract_calls_py_cybersecurity` | HAR destilado → call specs (origen del lado izquierdo del ciclo) |

## Gotchas

- **Sintaxis de variables**: la GUI usa `<<var>>`; el motor de replay usa `{{var}}`.
  `run_hoppscotch_collection` traduce automáticamente. Si compones a mano con
  `http_replay_sequence`, traduce tú (`<<x>>` → `{{x}}`).
- **Endpoints con efecto** (POST/DELETE destructivos): filtra con `only` para no ejecutar a
  ciegas toda la colección. El replay reproduce lo que haya; la responsabilidad de no disparar
  acciones irreversibles es del caller.
- **Esquema de versión**: `build_*` genera el formato canónico estable v1/v2 que la app migra al
  importar. `parse_*` lee cualquier versión por campos. No fijamos v12/v17 a mano para no romper
  con cambios de esquema upstream.
- **multipart/form-data**: `parse_*` lo marca `body_type="raw"` y no reconstruye el cuerpo binario.
- **Formato dual de environment**: la GUI Desktop importa el array `[{v,name,variables:[{key,value,secret}]}]`
  (`registry_api.json` / `.example.json`); el CLI `hopp` v0.31.2 quiere un **objeto plano**
  `{name,variables:[{key,value}]}` SIN `v` ni `secret` (`registry_api.cli.json`). Pasar el array a
  `hopp test -e` da `MALFORMED_ENV_FILE`. `run_hoppscotch_collection` (registry) usa el array.