Monter la pile Fil en développement : le guide complet

Un Fil qui « n'affiche rien » a rarement un bug.

C'est la première chose à comprendre avant d'installer quoi que ce soit : Fil ne fabrique pas ses données. Il lit des sources produites par d'autres services. Une interface vide est presque toujours le symptôme d'un service en amont éteint, pas d'une régression dans l'interface. Savoir cela fait gagner des heures — et transforme le diagnostic.

Ce guide décrit tout ce qu'il faut monter pour développer Fil en local, dans quel ordre, et surtout ce qui casse quand une pièce manque.

La chaîne, d'un bout à l'autre

Chaque maillon est un processus séparé, sur un port distinct :

Claude Code / Codex / Cursor / Kimi
              │ hooks natifs
              ▼
        VFGate :5191  (admin :5190)
              │ relais, interrogation toutes les 500 ms
              ▼
       FG_Chronos :4340        ← le seul store durable
              │ API de lecture
              ▼
        Fil (Chronowflow) :4477

FG_Pulse :4330  ──────────────────┐
dépôts git locaux ────────────────┼──▶  Fil
blog.vfg.lol (distant) ───────────┘

Ollama :11434 → ai-usage-hub :11435 → VFGate

Trois propriétés structurent le reste :

• Fil lit, il n'écrit pas. Il ne mute jamais le ledger de Chronos. « Masquer » un acte est une vue locale, pas une suppression côté source.
• Chronos est le seul stockage durable de la chaîne de captation. Pulse et le blog sont lus à la volée.
• Le relais est le maillon fragile. Sans lui, VFGate reçoit les événements mais rien n'atteint Chronos : tout « tourne », et Fil reste vide.

Ce qu'il faut avoir

Prérequis : Node.js ≥ 20, git dans le PATH, et PowerShell 5.1 pour les scripts de la chaîne.

Trois pièges de topologie (avant de chercher)

Ils coûtent du temps parce qu'ils contredisent l'intuition :

1. Fil n'est pas dans le workspace principal. Il vit dans son propre dépôt, hors de l'arborescence des projets. Le chercher au mauvais endroit fait perdre un temps certain.
2. Chronos n'a aucun dépôt dédié. C'est un dossier à l'intérieur d'un autre dépôt. Il n'apparaît donc dans aucun registre de projets — on y revient plus bas, car c'est la cause d'une vraie collision.
3. Le dossier de VFGate porte encore son ancien nom. Son nom npm est vfgate, mais le répertoire s'appelle toujours BDDBridgePOC. Le lien n'est pas évident.

Deux façons de démarrer

La voie scriptée — une commande

Une installation initiale, puis un lanceur :

# une seule fois
powershell -NoProfile -File <workspace>\FG_Chronos\scripts\install-agent-presence.ps1

# à chaque session
powershell -NoProfile -File <workspace>\FG_Chronos\scripts\start-agent-presence.ps1

Le lanceur démarre les services absents dans le bon ordre et ouvre Fil.

⚠️ Attention, ce lanceur exécute Fil en build de production. S'il ne trouve pas de build existant, il reconstruit puis démarre. Conséquence : modifier le code source ne change rien à ce qui est servi tant que tu ne reconstruis pas. Pour développer l'interface, utilise la voie manuelle.

La voie manuelle — service par service

C'est celle du développement actif : un terminal par service.

# 1. Chronos — le ledger (la source qui compte)
cd <workspace>\FG_Chronos
npm install
node src/server.js                  # → :4340

# 2. VFGate — le bus
cd <workspace>\BDDBridgePOC
npm install
npm run start:api                   # → :5191

# 3. Le relais, indispensable entre 1 et 2
cd <workspace>\FG_Chronos
node scripts/relay-vfgate.mjs

# 4. Pulse — seconde source live
cd <workspace>\FG_Pulse
npm install
npm start                           # → :4330

# 5. Fil — l'interface, avec rechargement à chaud
cd <repo>\Chronowflow
npm install
npm run dev                         # → :4477

Fil démarre même si tout le reste est éteint : il affichera des sources éteintes plutôt que de planter. C'est délibéré, et c'est ce qui rend le diagnostic possible.

Les variables — toutes optionnelles

Aucun .env n'est nécessaire : sans configuration, Fil vise les adresses locales par défaut.

La source git lit les derniers commits de chaque dépôt fourni. Le paramètre d'URL ?repos= prend le pas sur la variable d'environnement.

$env:FIL_GIT_REPOS = "<repo>\Chronowflow;<workspace>\FG_Chronos"
npm run dev

Vérifier que la chaîne est vivante

Deux scripts répondent à 90 % des questions « pourquoi Fil est vide » :

# diagnostic : ports, unicité des processus, configurations, tâche planifiée
powershell -NoProfile -File <workspace>\FG_Chronos\scripts\doctor-agent-presence.ps1

# preuve de bout en bout : émet une session étiquetée et vérifie qu'elle traverse
# la chaîne complète, puis se referme
node <workspace>\FG_Chronos\scripts\smoke-agent-workflow.mjs

Ensuite, dans Fil, le bandeau de monitoring de l'en-tête montre l'état de chaque source, le nombre d'items et le retard. C'est la première chose à regarder.

empty n'est pas une panne. Une source qui ne renvoie rien est « silencieuse » et ne dégrade pas le badge. Seuls les états franchement dégradés le font. Une source d'archive, elle, ne devient jamais périmée. Confondre le silence et la panne fait passer une pile saine pour cassée — c'est un piège que le projet a déjà payé une fois.

Huit pièges déjà rencontrés

Les deux derniers méritent d'être soulignés, parce qu'ils sont silencieux par nature et que le projet les a identifiés comme les plus dangereux : une ligne de compteur qui disparaît derrière un filtre transforme un plafond en perte de données, et une raison tronquée transforme un score en arbitraire.

Les lacunes, assumées

Un guide qui n'avoue pas ses trous fait perdre du temps à celui qui le suit.

1. Le port du ledger est doublement revendiqué. Un registre le déclare pour un autre service, alors qu'en réalité c'est le ledger qui l'occupe — et toute la chaîne en dépend. Les deux ne peuvent pas tourner ensemble. Le sujet est documenté et l'arbitrage est en attente : déplacer un port sur un service central casse les relais, les défauts côté client, les scripts de diagnostic et les tests de fumée. Ce n'est pas une correction mécanique.
2. Le port de l'interface n'était pas enregistré. Corrigé — mais l'oubli a tenu des semaines.
3. La commande de synchronisation du registre est cassée. Elle cherche sa source à des emplacements qui n'existent plus. Ne pas la lancer.
4. Le registre local est en avance sur sa source, de sept entrées. Le régénérer les effacerait en silence. C'est le sujet d'un article séparé, et il vaut la lecture.
5. Le service qui cause la collision n'est déclaré nulle part : sans dépôt ni entrée de projet, il reste capable de créer des collisions qu'aucun registre ne peut voir venir.
6. La pagination historique n'est pas complète côté source : la couverture est donc rapportée partielle, honnêtement, plutôt que gonflée.
7. La captation ambiante est bruitée — environ 200 items de bruit identifiés. La correction appartient à la source, pas à l'interface qui les affiche et les replie.

Le minimum vital

Si tu ne retiens qu'une chose :

Chronos :4340  ──┐
Pulse   :4330  ──┼──▶  Fil :4477
git local      ──┘     (npm run dev)
blog distant   ──┘

1. node src/server.js dans Chronos — c'est la source qui compte.
2. node scripts/relay-vfgate.mjs si tu veux voir la présence des agents.
3. npm run dev dans Fil.
4. Ouvrir l'interface et lire le bandeau de monitoring.

Puis, en cas de problème : le doctor d'abord, le smoke ensuite.

Ce guide est la version publique d'un document d'environnement maintenu dans le dépôt de Fil, où il vit aux côtés des tutoriels d'usage. La partie registre de ports mérite son propre article : un registre de ports qui ment n'est jamais bruyant, il est faux en silence — et c'est bien pire.