# Recherche regex sur code — API locale (`services/agent-regex-search-api`)

## Objectif

Offrir aux clients locaux (futur shell Lapce, gateway, agents) une **API HTTP** pour exécuter des **recherches par expression régulière** sur une arborescence contrôlée, sans dépendre du moteur propriétaire décrit dans le billet Cursor [Recherche regex rapide : indexer le texte pour les outils des agents](https://cursor.com/fr/blog/fast-regex-search).

## Ce que ce n’est pas

L’article Cursor décrit des index **sparse n-grams**, fichiers sur disque, `mmap`, etc. **Ce code n’est pas reproduit ici** : Cursor ne publie pas ce moteur en open source. Le service `agent-regex-search-api` s’appuie sur **[ripgrep](https://github.com/BurntSushi/ripgrep)** (`rg`), outil standard, rapide, et adapté aux flux « agent » qui enchaînent beaucoup de recherches.

## Périmètre fonctionnel

| Élément | Détail |
|--------|--------|
| Code | [repo/service-agent-regex-search.md](../repo/service-agent-regex-search.md) |
| Moteur | `rg --json` ; prérequis : binaire `rg` dans `PATH` |
| Confinement | `REGEX_SEARCH_ROOT` (défaut `/home/ncantu/code`) ; `subpath` uniquement **relatif**, sans `..` |
| Auth | `REGEX_SEARCH_TOKEN` → `Authorization: Bearer …` sur `POST /search` |
| Port défaut | `37143` |

## Menaces à prendre en compte

- **ReDoS** : une regex peut rester coûteuse jusqu’à `timeoutMs` ; garder des plafonds raisonnables.
- **Lecture disque** : tout fichier que `rg` traverse sous la cible peut être lu selon les droits OS ; aligner `REGEX_SEARCH_ROOT` sur la politique du poste.

## Évolutions possibles (hors périmètre initial)

Pour des monorepos extrêmement volumineux, des backends **indexés** open source (ex. **Zoekt**, familles d’index **trigram** / n-grams) peuvent compléter ou remplacer le seul `rg`, en réutilisant les idées du billet Cursor comme **références algorithmiques**, pas comme implémentation fournie.

## Intégration architecture

Voir [system-architecture.md](../system-architecture.md) : ce service est un **micro-service HTTP local** dans la même famille que `repos-devtools-server`, destiné à être appelé par l’orchestrateur ou l’éditeur plutôt que par des clients distants non authentifiés.