From 3b3e1e67de7fdd306858e9ead6fc24a71f71fb0f Mon Sep 17 00:00:00 2001 From: Nicolas Cantu Date: Fri, 3 Apr 2026 22:54:07 +0200 Subject: [PATCH] docs: align regex-search with Cursor article; claw upstream submodule; SSO data ownership MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add services/claw-harness-api/upstream → chinanpc/claude-code-rust (shallow) - Document claw submodule and MIT Rust harness in service-claw-harness + feature doc - agent-regex-search: map design principles to rg implementation vs indexed search - SSO gateway: no user/project account storage; product DBs own identity context --- .gitmodules | 10 +++++++--- docs/API/sso-gateway-api.md | 4 ++++ docs/features/agent-regex-search-api.md | 15 +++++++++++---- docs/features/claw-harness-api.md | 3 ++- docs/features/sso-gateway-service.md | 8 ++++++++ docs/repo/service-agent-regex-search.md | 2 +- docs/repo/service-claw-harness.md | 12 +++++++++--- services/agent-regex-search-api/README.md | 2 +- services/claw-harness-api/upstream | 1 + services/smart-ide-sso-gateway/README.md | 2 ++ 10 files changed, 46 insertions(+), 13 deletions(-) create mode 160000 services/claw-harness-api/upstream diff --git a/.gitmodules b/.gitmodules index 50b5bbc..3aebee3 100644 --- a/.gitmodules +++ b/.gitmodules @@ -3,12 +3,12 @@ # — Amonts tiers (sous-module dans services//upstream/) : # services/carbonyl/upstream → fathyb/carbonyl # services/chandra/upstream → datalab-to/chandra -# services/pageindex/upstream → VectifyAI/PageIndex -# services/langextract-api/upstream → google/langextract +# services/pageindex/upstream → VectifyAI/PageIndex +# services/langextract-api/upstream → google/langextract +# services/claw-harness-api/upstream → chinanpc/claude-code-rust (harnais Rust MIT, voir service-claw-harness.md) # # — Code versionné dans ce dépôt uniquement (pas de sous-module sur la racine du service) : # services/agent-regex-search-api -# services/claw-harness-api (claw-code amont : clone séparé, voir docs/repo/service-claw-harness.md) [submodule "services/carbonyl/upstream"] path = services/carbonyl/upstream @@ -26,3 +26,7 @@ path = services/langextract-api/upstream url = https://github.com/google/langextract.git shallow = true +[submodule "services/claw-harness-api/upstream"] + path = services/claw-harness-api/upstream + url = https://github.com/chinanpc/claude-code-rust.git + shallow = true diff --git a/docs/API/sso-gateway-api.md b/docs/API/sso-gateway-api.md index f450480..c226ebe 100644 --- a/docs/API/sso-gateway-api.md +++ b/docs/API/sso-gateway-api.md @@ -33,6 +33,10 @@ Liste les clés de proxy disponibles : `{ "upstreams": [ "orchestrator", ... ] } L’en-tête `Authorization` utilisateur n’est **pas** transmis à l’amont ; il est remplacé par le jeton de service configuré. Voir [sso-gateway-service.md](../features/sso-gateway-service.md). +### Comptes et projets + +Aucun stockage d’**utilisateurs** ou de **comptes par projet** dans ce service : uniquement validation OIDC et proxy. Les données de compte et d’appartenance projet vivent dans les **bases métier** des produits ; la passerelle ne les duplique pas. + ## Variables d’environnement (passerelle) | Variable | Rôle | diff --git a/docs/features/agent-regex-search-api.md b/docs/features/agent-regex-search-api.md index 9377b8a..831f54e 100644 --- a/docs/features/agent-regex-search-api.md +++ b/docs/features/agent-regex-search-api.md @@ -2,11 +2,18 @@ ## 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). +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.). -## Ce que ce n’est pas +## Rapport article ↔ code -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. +| 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 @@ -25,7 +32,7 @@ L’article Cursor décrit des index **sparse n-grams**, fichiers sur disque, `m ## É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. +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 diff --git a/docs/features/claw-harness-api.md b/docs/features/claw-harness-api.md index 9d5e118..05412af 100644 --- a/docs/features/claw-harness-api.md +++ b/docs/features/claw-harness-api.md @@ -8,8 +8,9 @@ Documenter et outiller l’usage du dépôt **claw-code** (runtime type « harne - Page miroir : [gitlawb — claw-code](https://gitlawb.com/node/repos/z6Mks1jg/claw-code) - Dépôt GitHub souvent utilisé pour cloner : [instructkr/claw-code](https://github.com/instructkr/claw-code) +- Variante Rust MIT sous-module dans ce monorepo : [chinanpc/claude-code-rust](https://github.com/chinanpc/claude-code-rust) → `services/claw-harness-api/upstream` -Le dépôt amont évolue (Rust / Python, binaires, serveur HTTP). Ce dépôt **ne vend pas** claw-code : seulement README, exemple de politique fournisseurs, et un **proxy HTTP** optionnel. +Le dépôt amont évolue (Rust / Python, binaires, serveur HTTP). Ce dépôt **ne vend pas** claw-code : seulement README, exemple de politique fournisseurs, sous-module optionnel ci-dessus, et un **proxy HTTP** optionnel. ## Fichiers locaux diff --git a/docs/features/sso-gateway-service.md b/docs/features/sso-gateway-service.md index ae82caf..cb32d09 100644 --- a/docs/features/sso-gateway-service.md +++ b/docs/features/sso-gateway-service.md @@ -26,6 +26,14 @@ En plus de l’authentification de service, la passerelle peut envoyer : Les services amont peuvent s’en servir pour du **journal** ou des **règles fines** ; la **politique d’autorisation** métier reste de leur responsabilité. +## Comptes, projets et bases métier + +La passerelle **ne conserve pas** de comptes utilisateurs, de profils projet, ni de quotas métier : elle ne fait que **vérifier** le JWT OIDC et **relayer** vers les micro-services. + +Les **comptes**, droits par **projet**, abonnements, historiques et toute persistance **métier** liée à l’identité restent dans les **bases des applications** (ex. docv, Enso, autres produits) et dans leurs schémas de données — pas dans `smart-ide-sso-gateway`. Le découpage par projet côté IDE et chemins de déploiement est décrit sous `projects//conf.json` — [repo/projects-directory.md](../repo/projects-directory.md). + +Les services amont qui reçoivent `X-OIDC-Sub` / `X-OIDC-Email` sont responsables de **résoudre** l’utilisateur vers un contexte projet via **leurs** API et bases. + ## Documentation détaillée - [API/sso-gateway-api.md](../API/sso-gateway-api.md) diff --git a/docs/repo/service-agent-regex-search.md b/docs/repo/service-agent-regex-search.md index da89e32..148071a 100644 --- a/docs/repo/service-agent-regex-search.md +++ b/docs/repo/service-agent-regex-search.md @@ -1,6 +1,6 @@ # agent-regex-search-api (`services/agent-regex-search-api/`) -API HTTP locale sur **`127.0.0.1`** pour la **recherche regex sur fichiers** via [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`). Approche locale ouverte ; ce n’est pas l’implémentation « instant grep » propriétaire de Cursor. +API HTTP locale sur **`127.0.0.1`** pour la **recherche regex sur fichiers** via [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`). Elle matérialise côté `smart_ide` les **principes de conception** décrits pour les agents dans [Recherche regex rapide : indexer le texte pour les outils des agents](https://cursor.com/fr/blog/fast-regex-search) (outil regex dédié aux agents, plafonds de latence, périmètre de fichiers borné). Le **moteur indexé** du billet (trigrammes, sparse n-grams, fichiers `mmap`, etc.) n’est **pas** recodé ici : l’implémentation actuelle s’appuie sur `rg`, comme la majorité des chaînes d’agents ; une couche d’index open source (famille Zoekt / codesearch) reste une évolution possible pour les très gros arbres. ## Prérequis diff --git a/docs/repo/service-claw-harness.md b/docs/repo/service-claw-harness.md index 2030843..890258f 100644 --- a/docs/repo/service-claw-harness.md +++ b/docs/repo/service-claw-harness.md @@ -1,11 +1,17 @@ # claw-harness-api (`services/claw-harness-api/`) -Notes d’intégration et **proxy HTTP mince** pour le harnais **claw-code** (runtime multi-modèles). Amont : +Notes d’intégration et **proxy HTTP mince** pour un harnais **claw** (agent terminal, binaire `claw`). + +## Amont Rust (sous-module optionnel) + +Un clone **shallow** du dépôt **[chinanpc/claude-code-rust](https://github.com/chinanpc/claude-code-rust)** est disponible sous **`services/claw-harness-api/upstream`** (sous-module Git, licence **MIT** selon le dépôt amont). Après `git clone` du monorepo : `git submodule update --init services/claw-harness-api/upstream`. Builder et lancer le binaire selon le `README` amont (workspace Rust, `cargo build --release`, etc.). + +## Autres références claw (hors sous-module) - [gitlawb — claw-code](https://gitlawb.com/node/repos/z6Mks1jg/claw-code) -- [instructkr/claw-code](https://github.com/instructkr/claw-code) (clone fréquent) +- [instructkr/claw-code](https://github.com/instructkr/claw-code) (accès réseau selon visibilité du dépôt) -Ce dossier **ne vend pas** claw-code : cloner amont, builder selon son `README` (workspace Rust `rust/`, etc.). +Le proxy **`proxy/`** du monorepo n’embarque pas le runtime : il attend une URL **`CLAW_UPSTREAM_URL`** vers un serveur HTTP claw déjà démarré. ## Politique : pas d’Anthropic dans les gabarits diff --git a/services/agent-regex-search-api/README.md b/services/agent-regex-search-api/README.md index 2f7188e..01ebce9 100644 --- a/services/agent-regex-search-api/README.md +++ b/services/agent-regex-search-api/README.md @@ -1,3 +1,3 @@ # agent-regex-search-api -**[docs/repo/service-agent-regex-search.md](../../docs/repo/service-agent-regex-search.md)** +**[docs/repo/service-agent-regex-search.md](../../docs/repo/service-agent-regex-search.md)** — conception liée au billet Cursor [Recherche regex rapide](https://cursor.com/fr/blog/fast-regex-search) (détails : [features/agent-regex-search-api.md](../../docs/features/agent-regex-search-api.md)). diff --git a/services/claw-harness-api/upstream b/services/claw-harness-api/upstream new file mode 160000 index 0000000..14fd3e0 --- /dev/null +++ b/services/claw-harness-api/upstream @@ -0,0 +1 @@ +Subproject commit 14fd3e06888b510c7e3c7088b24348e42edaad12 diff --git a/services/smart-ide-sso-gateway/README.md b/services/smart-ide-sso-gateway/README.md index 179a925..28fb99a 100644 --- a/services/smart-ide-sso-gateway/README.md +++ b/services/smart-ide-sso-gateway/README.md @@ -9,6 +9,8 @@ HTTP gateway that validates **user** access tokens from the docv / Enso OIDC iss - Expose `GET /v1/token/verify` and `GET /v1/upstreams` with user Bearer. - Proxy `ANY /proxy//` to the configured upstream, replacing the user token with the service token and adding `X-OIDC-Sub` / `X-OIDC-Email` when present in the JWT. +User accounts, project membership, and product databases stay in **each application’s backend** (docv, Enso, etc.); this gateway does not store them. + ## Run ```bash