# API — agent-regex-search-api

Service Node : recherche **regex** sur fichiers via **ripgrep** (`rg`), résultats en JSON. Périmètre confiné à `REGEX_SEARCH_ROOT`.

- **Code** : [`services/agent-regex-search-api/`](../../services/agent-regex-search-api/)
- **Bind** : `REGEX_SEARCH_HOST` (défaut `127.0.0.1`)
- **Port** : `REGEX_SEARCH_PORT` (défaut `37143`)
- **Prérequis** : `rg` dans le `PATH` (sinon réponse `503` sur `/search`)

## Authentification

```http
Authorization: Bearer <REGEX_SEARCH_TOKEN>
```

`REGEX_SEARCH_TOKEN` obligatoire au démarrage. **Exception** : `GET /health` ne exige pas le Bearer.

## Endpoints

### `GET /health` ou `GET /health/`

**Réponse `200`**

```json
{
  "status": "ok",
  "root": "<REGEX_SEARCH_ROOT résolu>"
}
```

### `POST /search`

**Corps JSON**

| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| `pattern` | oui | Regex style Rust, passée à ripgrep |
| `subpath` | non | Chemin relatif sous la racine (pas de `..`, pas absolu) |
| `maxMatches` | non | Plafond de résultats (défaut `500`, max `50000`) |
| `timeoutMs` | non | Timeout exécution `rg` en ms (défaut `60000`, max `300000`) |

**Réponse `200`** (succès ripgrep, y compris « aucune correspondance », code sortie `1`)

```json
{
  "root": "string",
  "target": "string",
  "matches": [{ "path": "string", "lineNumber": number, "line": "string" }],
  "truncated": boolean,
  "exitCode": number
}
```

**Autres réponses**

- `400` : corps invalide, `pattern` manquant, ou erreur ripgrep code `2` (regex / IO) — peut inclure `error`, `matches`, `truncated`, `exitCode`
- `401` / absence de réponse utile : Bearer manquant ou incorrect sur `/search`
- `404` : chemin non géré
- `503` : `rg` introuvable (`exitCode` 127 côté implémentation) — `{ "error", "matches": [], "truncated": false }`

## Variables d’environnement

| Variable | Obligatoire | Description |
|----------|-------------|-------------|
| `REGEX_SEARCH_TOKEN` | oui | Secret Bearer |
| `REGEX_SEARCH_ROOT` | non | Répertoire de base des recherches (défaut `/home/ncantu/code`) |
| `REGEX_SEARCH_HOST` | non | Bind |
| `REGEX_SEARCH_PORT` | non | Port |