SPB Git forge
spboucher.ai ↗

spb/admin-ka

Public
41commits 1branches 0releases
172.9 MBsize
maindefault branch
19 days agolast push
JavaScript 65.5% Python 17.8% CSS 13% HTML 3.7%
9.4 KB
View source Raw Blame History

# CLAUDE.md — administration-ka.com (Admin-Ka v2)

Console d'administration du Groupe KA : app chat mobile-first qui pilote le vrai Claude Code CLI sur le cluster MacLustr, plus un monitoring temps réel de tous les sites du groupe.

# Exigences non négociables

  1. Vrai Claude Code, jamais l'API Messages. Le backend lance le binaire claude (headless : claude -p --output-format stream-json --verbose --include-partial-messages), avec cwd = le repo de l'app choisie. Chaque app KA s'exécute sur son nœud de déploiement (via SSH pour les nœuds distants) — le repo de prod est la seule source de vérité, aucun clone. Tous les événements du stream (texte, thinking, tool_use, tool_result, result) sont relayés et rendus comme dans le terminal (diffs colorés, blocs outils repliables, coût/tokens).
  2. Options Claude Code dans l'UI : modèle par session (Fable 5 défaut, Opus 5, Sonnet 5, Haiku, --model), mode de permissions (default avec cartes Autoriser / Toujours (cet outil) / Tout autoriser / Refuser, acceptEdits, plan, bypass derrière confirmation), choix du projet/cwd, /clear /compact /cost /resume, affichage live du modèle actif, session ID, coût cumulé, tokens de contexte (+ %), file d'attente de message, chrono d'exécution, copie des blocs de code.
    • « Tout autoriser » = autoAllowAll sur la conversation : le serveur approuve TOUTES les permissions suivantes jusqu'à la fin — la tâche va au bout sans jamais réattendre l'utilisateur (testé : write auto-approuvé, 0 carte). C'est l'exigence « si on coche tout autoriser, ça finit vraiment la tâche ».
  3. Sessions détachées + reprise durcie : le process claude ne dépend JAMAIS du WebSocket. Transcript JSONL persisté ; à la reconnexion l'app rejoue l'historique manqué puis reprend le live. Reprise auto : l'app rouvre la dernière conversation au lancement (lastChatId) et force la reconnexion + resync au retour au premier plan (visibilitychange/online, iOS coupe le WS à l'écran verrouillé). États : en cours / en attente de permission / inactive. Reconnexion auto backoff + indicateur. Notifications in-app (fin de tâche, permission attendue).
  4. Écosystème : health checks HTTPS toutes les 45 s des 13 sites KA depuis M3U96a (latence, code, SSL), sweep des nœuds toutes les 5 min (charge/RAM/disque + PM2 cpu/mem/status + dernier commit), historique SQLite (data/eco.sqlite, rétention 35 j), incidents (2 échecs consécutifs → alerte, rétablissement → alerte verte), uptime 24h/7j/30j, moy/p95, sparklines + graphique 24 h + barres d'uptime 14 j, push temps réel via le même WebSocket. Santé des 5 nœuds (barres charge/RAM/disque + apps up), vue Incidents globale, et actions d'admin par site : redémarrer PM2 (/api/admin/action), logs récents (/api/admin/logs), git & commits (/api/admin/commits) — exécutées localement ou via ssh sur le nœud du site.
  5. Identité Groupe KA : crème #F2F1EC, orange #F97316 (traits de graphe #e05f00), encre #1a1611, cartes à bords noirs 2 px + ombres décalées, pills, typo ronde, pastille « Ka ». Header fixe + bottom nav (Chat / Sessions / Écosystème / Réglages) avec safe-areas. Statuts JAMAIS en couleur seule (● ▲ ■ + libellé).
  6. Rien de simulé : tout est branché sur le vrai CLI et les vrais sites.

# Architecture

text
iPhone ⇄ wss://www.administration-ka.com (ngrok) ⇄ backend :3300 (M3U96a)
   backend ⇄ claude CLI (local, apps M3U96a) 
   backend ⇄ ssh <nœud> claude CLI (apps distantes, repo de prod)
             └ tunnel SSH inverse -R : cartes de permission (perm-mcp MCP)
   backend ⇄ monitor.js : health checks + sweep nœuds + SQLite + push WS
  • server/registry.js — topologie vivante (2026-09-04) : où tourne chaque app Ka = registre mld de la passerelle (M1M32:~/dispatch/registry.json). Copie data/registry.json poussée par mld (abonné admin-ka) et surveillée (fs.watchFile), + tirage ssh toutes les 2 min (M1M32 puis gitsrv). Fournit SITES/getSites() (monitoring), getProjects()/findProject() (projets Claude Code, ids app@nœud résolus par app), selfNode() (nœud de la console = entrée admin-ka du registre), sshTarget() (alias ssh sinon user@IP LAN), topologyText() (bloc injecté dans les prompts système), régénère ~/ka-orchestrator/CLAUDE.md à chaque changement et outille les nœuds hébergeurs (~/.adminka/perm-mcp.js, ~/.claude/CLAUDE.md contextuel). KA_CATALOG ne contient que la connaissance Ka (libellés, launchd des gardiens, pm2 non déductibles) — plus jamais d'emplacement en dur. API : GET /api/registry, POST /api/registry/refresh, POST /api/registry/tooling ; UI : carte « Registre » dans Réglages, alerte eco_alert kind=registry + message WS projects quand une app bouge ; une conversation dont l'app a déménagé est réalignée à son prochain tour (realignChat, nouvelle session Claude).
  • server/server.js — HTTP + WS + orchestration claude + états de session.
  • server/monitor.js — collecteur Écosystème (node:sqlite intégré, aucune dépendance native) ; sites et nœuds = registry.js.
  • server/perm-mcp.js — serveur MCP stdio pour --permission-prompt-tool mcp__adminka__approve ; copié automatiquement dans ~/.adminka/ de chaque nœud hébergeur connu du registre (ensureNodeTooling, contrôle toutes les 6 h ou bouton « Vérifier l'outillage » dans Réglages).
  • public/ — frontend une page, 4 onglets, aucun framework.

# Pièges connus (ne pas re-découvrir)

  • Tailscale inter-nœuds bloqué (ACL) : depuis M3U96a, joindre les nœuds via les noms Bonjour .local (config ~/.ssh/config en place). M2U64 = sous-réseau 192.168.0.x.
  • IPv4 LAN non routée entre nœuds (EHOSTUNREACH) : les permissions distantes passent par le tunnel SSH inverse, pas par le LAN.
  • ControlPath ssh avec hostnames .local trop long → %C.
  • Sans --model, les nœuds retombent sur leur défaut local (Sonnet) → toujours passer --model explicitement.
  • Auth headless par ANTHROPIC_API_KEY de ~/.claude/.env (pas de login OAuth sur les nœuds).
  • Chaque run reçoit --append-system-prompt : après toute modif → rebuild + pm2 restart + healthcheck + commit/push spbgit (origin, pas GitHub).

# Exploitation

bash
# sur M3U96a
launchctl kickstart -k gui/501/io.adminka.backend   # redémarrer backend
launchctl kickstart -k gui/501/io.adminka.ngrok     # redémarrer tunnel
tail -f ~/apps/admin-ka/data/backend.err.log
node server/set-password.js '<nouveau>'             # changer le mot de passe

Registre des déploiements : M1M32:~/dispatch/registry.json (orchestrateur mld, source de vérité — cluster-deployments.json du laptop est l'ancien registre, ne plus s'en servir). Repo : spbgit gitsrv:srv/git/admin-ka.git (bare sur M1M32).

# v3 (2026-08-26) — Control Center : refonte UI + analytics humains

UI : desktop-first — sidebar gauche (≥1020 px) + topbar (titre, incidents, thème, statut) ; bottom nav mobile réduite à 5 (Vue d'ensemble, Claude Code, Écosystème, Visiteurs, Plus). Nouvelle page Vue d'ensemble (KPIs humains+éco+Claude, chart 30 j, chips écosystème, incidents, anomalies). Dark mode réel (ka_theme auto/clair/sombre, variables --edge/--shadow/--code-bg/...). Sessions et Prompts en listes denses filtrables (recherche/app/statut ; favoris ★, duplication, compteur d'usage sur les prompts).

Analytics v2 (server/analytics.js) — définitions officielles :

  • Visiteur humain : vid classé human = UA navigateur + JS exécuté + réseau non-datacenter/proxy + pas interne + pas de flood.
  • Visiteur unique : vid humain distinct dans la fenêtre. Session : trou > 30 min = nouvelle session (sessionMin). Page vue : événement pv (navigation réelle, SPA incluse) — un heartbeat n'est JAMAIS une page vue. En ligne : dernier événement humain < 120 s (activeSec) — expire tout seul.
  • Classes : human / crawler / datacenter / automation / internal — classées à l'insertion (UA regex + cache ipinfo ip-api avec hosting/proxy/ASN, reclassement rétroactif quand l'IP se résout, anti-flood maxIpPerHour). Les métriques principales n'affichent QUE les humains ; le reste est visible dans la barre de répartition et le toggle « Tout le trafic ».
  • Tables : events (brut, rétention 45 j), ipinfo (cache IP-intelligence), daily2 (rollup quotidien par classe, long terme), meta.migrated_at (frontière legacy). Les anciennes hits/daily sont CONSERVÉES et affichées en pointillé « ancien comptage v1 (non filtré) » — ne jamais comparer directement les deux séries.
  • Beacon v2 : public/ka-a.js (vid/sid localStorage, pv SPA via pushState, heartbeat 25 s seulement onglet visible + interaction < 60 s). Le beacon v1 (ping 60 s) reste supporté : le serveur dé-duplique (même page ~60 s = heartbeat) et sessionne en mémoire.
  • API : /api/analytics/{summary,series/:site|_all,site/:site,realtime,anomalies,inspect?ip=|vid=,classes,config(GET/PUT)}. Config runtime dans config.json → analytics (fenêtres, IP/UA internes, bots custom, ASNs exclus) — éditable dans Réglages.
  • Tests : node server/test-analytics.mjs (28 scénarios : humain/refresh/SPA, Googlebot, uptime bot, IP AWS, curl, interne, dédup v1, invariants uniques≤sessions≤pv, expiration en ligne) — à lancer depuis une COPIE (écrit dans data/).