# 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. La référence de conception est le billet Cursor [Recherche regex rapide : indexer le texte pour les outils des agents](https://cursor.com/fr/blog/fast-regex-search) : y sont posés le rôle central de la regex pour les agents, l’enjeu de latence sur grands dépôts, et les familles d’algorithmes (index inversé trigrammes, sparse n-grams, etc.).

## Rapport article ↔ code

| Aspect (article Cursor) | Dans `agent-regex-search-api` |
|---------------------------|-------------------------------|
| Outil « grep / regex » pour agents, borné dans le temps | `POST /search` avec `timeoutMs`, `maxMatches` |
| Réduction du périmètre fichiers | `REGEX_SEARCH_ROOT` + `subpath` relatif sans `..` |
| Moteur : ripgrep comme base courante | `rg --json` (aligné sur ce que l’article cite comme usage large dans les agents) |
| Index préalable (trigrammes, sparse n-grams, stockage disque) | **Non** : pas recodé ; évolution possible via Zoekt ou équivalent open source |

Cursor ne publie pas son moteur « instant grep » ; ce dépôt ne le reproduit pas. Le service s’appuie sur **[ripgrep](https://github.com/BurntSushi/ripgrep)** (`rg`), pratique et rapide pour beaucoup de dépôts ; les sections algorithmiques du billet servent de **cible** si un index local devient nécessaire.

## 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**.

## 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.