@bountyporte/ai-studio 0.0.0-stage → 0.25.0

package/INSTALL.md

@@ -0,0 +1,231 @@
+# Installer AI Studio
+
+Ce guide installe AI Studio sur **macOS**, **Linux (Debian ou Ubuntu, y compris
+une machine virtuelle)** ou **Windows**. Un script fait tout automatiquement ;
+la partie « Installation manuelle » détaille les mêmes étapes si tu préfères
+les faire toi-même.
+
+## À savoir avant de commencer
+
+AI Studio doit être installé **sur la même machine que Claude Code (et Codex)** :
+
+- Claude Code envoie ses événements à AI Studio uniquement en local
+  (`localhost`), c'est ce qui fait apparaître les agents dans l'interface ;
+- les missions, workspaces et agents lancent `claude` et `codex` sur la machine
+  du serveur, dans tes dossiers de projets.
+
+Donc : installe AI Studio là où tu développes. Pour une machine virtuelle,
+installe AI Studio, Claude Code et tes projets **dans la VM**.
+
+## Lanceur npm et plugins Claude Code / Codex
+
+Le paquet npm et les deux formats de plugin sont inclus. Une version publiée
+s’installe avec `npx @bountyporte/ai-studio install`. Pour tester une version
+avant publication, utilise son archive `.tgz`.
+Le [guide de distribution](docs/DISTRIBUTION.md) détaille la commande, Windows/WSL,
+la connexion des plugins et les vérifications restant à faire avant publication.
+
+## Installation automatique
+
+### macOS, Debian, Ubuntu (et VM Debian 12)
+
+Récupère le projet, puis lance le script d'installation depuis son dossier :
+
+```bash
+git clone https://github.com/badrtairlbahrepro/AI-STUDIO.git
+```
+```bash
+cd AI-STUDIO && ./install.sh --start
+```
+
+Le script installe ce qui manque et garde ce qui est déjà là. Tu peux le
+relancer sans risque. Sous Linux, il demande ton mot de passe (`sudo`) pour
+les paquets système. Avec `--start`, le serveur démarre ensuite dans ce
+terminal ; `Ctrl+C` l’arrête. Sans cette option, lance `./start.sh` après
+l’installation.
+
+| Option | Effet |
+|---|---|
+| `--with-codex` | installe aussi Codex |
+| `--start` | installe puis lance le serveur dans ce terminal (ou utilise le service avec `--service`) |
+| `--service` | démarre AI Studio automatiquement à l'ouverture de session |
+| `--no-claude` | n'installe pas Claude Code (déjà installé autrement) |
+| `--no-hooks` | ne connecte pas Claude Code à AI Studio |
+
+Exemple : `./install.sh --with-codex --service`
+
+### Windows
+
+AI Studio tourne sous Windows grâce à **WSL 2** (le Linux intégré à Windows) avec
+Debian ; l'interface s'ouvre dans ton navigateur Windows habituel.
+
+1. Récupère le projet (avec Git pour Windows, GitHub Desktop, ou en
+   téléchargeant le ZIP depuis GitHub puis en le décompressant).
+2. Dans le dossier du projet : clic droit sur **`install.ps1`** →
+   **Exécuter avec PowerShell**. Ou, dans PowerShell :
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File .\install.ps1
+   ```
+   Options : `-WithCodex`, `-Service`, `-Start` (installe puis lance).
+3. **Première fois seulement** : si WSL n'était pas installé, le script
+   l'installe, puis te demande de redémarrer Windows, d'ouvrir l'application
+   **Debian** une fois pour créer ton utilisateur Linux, et de relancer
+   `install.ps1`.
+
+Le script copie le projet dans Debian (`~/AI-STUDIO`) et y lance `install.sh`.
+
+## Lancer AI Studio
+
+| Système | Commande |
+|---|---|
+| macOS, Linux | `./start.sh` dans le dossier du projet |
+| Windows | double-clic sur **`start.ps1`** |
+
+L'interface s'ouvre sur **http://localhost:8000**, déjà autorisée. `Ctrl+C`
+(ou fermer la fenêtre) arrête AI Studio. Après une mise à jour du code :
+`./start.sh --rebuild`.
+
+Avec l'option `--service`, AI Studio démarre tout seul : il suffit d'ouvrir
+http://localhost:8000.
+
+## Première ouverture (une seule fois)
+
+1. Connecte Claude Code : lance `claude` dans un terminal et suis la connexion.
+   Pour Codex : `codex login`.
+2. Dans AI Studio, ouvre **Réglages → Connexions** et autorise Claude et/ou
+   Codex ainsi que **les dossiers de tes projets**. Sans cela, les workspaces
+   et les agents ne peuvent pas y travailler.
+3. Si Claude Code était ouvert pendant l'installation, redémarre-le pour qu'il
+   envoie ses événements à AI Studio.
+
+## Diagnostic : `doctor`
+
+Depuis le dossier du projet :
+
+```bash
+./doctor.sh
+# Équivalents : scripts/ai-studio doctor ou make doctor
+./doctor.sh --json
+./doctor.sh --offline
+./doctor.sh --url http://127.0.0.1:8050
+```
+
+Sous Windows : `wsl -d Debian -- bash -lc 'cd ~/AI-STUDIO && ./doctor.sh'`.
+
+Le diagnostic vérifie les outils, la version de Node, l’environnement backend,
+l’interface compilée, les onze hooks Claude Code, les fichiers Codex, le serveur,
+la pause d’enregistrement et le périmètre des connexions. Il propose quoi corriger
+si une session manque. Il ne modifie aucun fichier, ne lance pas d’agent, n’envoie
+pas d’événement de test et n’affiche ni clé ni contenu de conversation. Les appels
+réseau se limitent aux adresses localhost explicites, sans suivre les redirections.
+L’état de connexion des CLI n’est pas testé.
+
+`ERROR` indique un problème bloquant (code de sortie 1). `WARNING` peut simplement
+indiquer qu’un fournisseur facultatif est désactivé ou qu’aucune interface statique
+n’a été compilée en mode développement (code 0 s’il n’y a pas d’erreur).
+
+Ces commandes s’utilisent depuis une copie du dépôt ; aucun paquet `npx` ou
+plugin n’est publié par cette installation.
+
+## « Accès refusé »
+
+Certaines actions (missions, workspaces, effacer l'historique) demandent une
+clé. Elle est créée au premier lancement, conservée dans `backend/.launch-key`
+et transmise automatiquement par `start.sh` à l'ouverture du navigateur.
+
+Si un bandeau « Accès refusé » apparaît, colle dans son champ le contenu de :
+
+```bash
+cat backend/.launch-key
+```
+
+Supprime ce fichier pour changer de clé (au prochain démarrage).
+
+## Machine virtuelle
+
+- **Tu utilises la VM avec son propre bureau** (fenêtre de VirtualBox, VMware,
+  UTM…) : rien de particulier, ouvre http://localhost:8000 dans le navigateur
+  de la VM.
+- **La VM n'a pas de bureau, ou tu veux ouvrir l'interface depuis ton
+  ordinateur principal** : par sécurité, AI Studio n'accepte que les connexions
+  locales à la VM. Crée un tunnel depuis ton ordinateur principal, puis ouvre
+  http://localhost:8000 sur celui-ci :
+  ```bash
+  ssh -L 8000:127.0.0.1:8000 utilisateur@adresse-de-la-vm
+  ```
+  Le tunnel fait croire à AI Studio que la connexion est locale, sans l'exposer
+  sur le réseau. Colle la clé (`cat backend/.launch-key` dans la VM) si
+  l'accès est refusé.
+
+Ressources conseillées pour la VM : 2 processeurs, 4 Go de mémoire, 15 Go de
+disque.
+
+## Mettre à jour
+
+```bash
+git pull && ./install.sh && ./start.sh --rebuild
+```
+
+Sous Windows, relance `install.ps1` (il met à jour la copie dans Debian), puis
+`start.ps1`. Avec le service : `systemctl --user restart ai-studio` (Linux) ou
+`scripts/ai-studio update` (macOS).
+
+## Installation manuelle
+
+Ce que fait `install.sh`, étape par étape :
+
+| Prérequis | Version | Installation |
+|---|---|---|
+| git, curl, make | — | macOS : `xcode-select --install` · Debian : `sudo apt install git curl make build-essential python3` |
+| Node.js | 20.9 ou plus (22 conseillé) | macOS : `brew install node@22` ou https://nodejs.org · Debian 12 fournit Node 18, trop ancien : utilise NodeSource (`curl -fsSL https://deb.nodesource.com/setup_22.x \| sudo -E bash -` puis `sudo apt install nodejs`) |
+| uv | dernière | `curl -LsSf https://astral.sh/uv/install.sh \| sh` (il télécharge Python 3.13 tout seul) |
+| Claude Code | dernière | `curl -fsSL https://claude.ai/install.sh \| bash` |
+| Codex (facultatif) | dernière | `npm install -g @openai/codex` |
+
+Puis, dans le dossier du projet :
+
+1. `make install` — dépendances du serveur, de l'interface et des hooks ;
+2. `cd hooks && ./install.sh` — connecte Claude Code à AI Studio (sous Linux,
+   ajoute `--strip-prefixes "-home-$USER-"` pour des noms de projets courts) ;
+3. `make build-static` — construit l'interface, servie par le serveur ;
+4. `./start.sh` — lance le tout sur http://localhost:8000.
+
+## Désinstaller
+
+1. `cd hooks && ./uninstall.sh` — déconnecte Claude Code ;
+2. si le service est installé : `systemctl --user disable --now ai-studio` puis
+   `rm ~/.config/systemd/user/ai-studio.service` (Linux), ou
+   `scripts/ai-studio uninstall` (macOS) ;
+3. supprime le dossier du projet (il contient aussi l'historique,
+   `backend/visualizer.db`).
+
+## Dépannage
+
+| Problème | Solution |
+|---|---|
+| « Le port 8000 est déjà utilisé » | AI Studio tourne déjà (service ?) : ouvre http://localhost:8000. Sinon, trouve le programme qui l'occupe : `lsof -i :8000`. |
+| Aucun agent n'apparaît pendant que Claude Code travaille | Redémarre Claude Code ; vérifie que `hooks/install.sh` a bien été lancé ; journal des hooks : `~/.claude/ai-studio-hooks.log` (avec `AI_STUDIO_DEBUG=1`). |
+| `uv` ou `claude` introuvable juste après l'installation | Ouvre un nouveau terminal (ils sont installés dans `~/.local/bin`). |
+| Node trop ancien | Installe Node 22 (voir le tableau des prérequis) puis relance `./install.sh`. |
+| Les agents ne peuvent pas travailler dans un dossier | Réglages → Connexions : autorise le fournisseur et le dossier. |
+
+## Affichage sur une VM peu puissante
+
+Dans la vue **Studio**, le **Studio léger** est sélectionné par défaut. Ses
+robots et cartes colorés utilisent HTML/CSS, sans canevas WebGL, rendu 3D ni
+animation continue. Le bouton **Studio 3D** conserve l'affichage original ; le
+choix est mémorisé dans chaque navigateur.
+
+Clique sur le chef ou un agent pour retrouver sa conversation et ses commandes.
+Les missions, plans, workspaces, activités et fichiers restent accessibles dans
+les panneaux habituels. Les cartes montrent les états, activités, dépendances et
+fichiers rapportés disponibles. La démo est locale et ne lance aucun agent.
+Les mouvements de caméra et les effets de lumière concernent uniquement la 3D.
+Les performances réelles dépendent aussi du navigateur et des ressources de la VM.
+
+Le chef possède son propre poste de commandement doré, séparé des postes de
+l'équipe. Les robots montrent une bulle d'activité, un clavier et des expressions
+liées à leur état. Lecture, frappe, attente, réussite et erreur déclenchent des
+effets courts (sans boucle infinie). La préférence système de réduction des
+animations est respectée. Les dépendances en attente sont aussi indiquées dans
+les cartes du workspace lorsqu'elles appartiennent au plan courant.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Robello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,239 @@
+.PHONY: install install-all dev backend frontend simulate checkall lint fmt test typecheck gen-types \
+	hooks-install hooks-uninstall hooks-reinstall hooks-status hooks-logs hooks-logs-follow hooks-logs-clear \
+	hooks-debug-on hooks-debug-off clean clean-db clean-all \
+	opencode-install opencode-uninstall opencode-reinstall opencode-build \
+	dev-tmux dev-tmux-kill dev-tmux-backend dev-tmux-frontend \
+	build-static frontend-build-static \
+	docker-build docker-up docker-down docker-logs docker-shell docker-config \
+	pre-commit pre-commit-update depsupdate depsshow uv-lock uv-sync setup resetup remove-venv \
+	bump-version version-check help
+
+# Detect package manager: prefer bun if available, otherwise use npm
+PKG_MGR := $(shell command -v bun >/dev/null 2>&1 && echo "bun" || echo "npm")
+PKG_INSTALL := $(shell command -v bun >/dev/null 2>&1 && echo "bun install" || echo "npm install")
+
+install:			# Install all component dependencies
+	cd backend && uv sync
+	cd frontend && $(PKG_INSTALL)
+	cd hooks && uv sync
+	cd opencode-plugin && $(PKG_INSTALL)
+
+install-all: install hooks-install opencode-install		# Install everything including hooks and plugins
+	@echo "All components installed including hooks and OpenCode plugin"
+
+dev:			# Start backend and frontend in parallel
+	@make -j 2 backend frontend
+
+backend:			# Start backend dev server
+	make -C backend dev
+
+frontend:			# Start frontend dev server
+	make -C frontend dev
+
+# Build static frontend and copy to backend for serving
+build-static frontend-build-static:
+	make -C frontend build-static
+	@echo "Frontend built and copied to backend/static"
+	@echo "Start backend with 'make backend' to serve at http://localhost:8000"
+
+simulate:			# Run event simulation
+	uv run python scripts/simulate_events.py
+
+test-agent:			# Run single agent test
+	uv run python scripts/test_single_agent.py
+
+lint:			# Run lint on all components
+	make -C backend lint
+	make -C frontend lint
+	make -C hooks lint
+	make -C opencode-plugin lint
+	cd backend && uv run ruff check ../scripts
+
+fmt:			# Reformat code
+	make -C backend fmt
+	make -C frontend fmt
+	make -C hooks fmt
+
+test:			# Run all tests
+	npm test
+	make -C backend test
+	make -C frontend test
+	make -C hooks test
+	make -C opencode-plugin test
+
+typecheck:			# Run static type checks
+	make -C backend typecheck
+	make -C frontend typecheck
+	make -C hooks typecheck
+	make -C opencode-plugin typecheck
+
+.PHONY: doctor
+doctor:
+	./doctor.sh
+
+checkall: fmt lint typecheck test		# Run all checks including tests
+
+gen-types:			# Regenerate TypeScript types from Pydantic models
+	cd backend && uv run python ../scripts/gen_types.py
+
+# Hook management targets
+hooks-install:
+	cd hooks && ./install.sh
+
+hooks-uninstall:
+	cd hooks && ./uninstall.sh
+
+hooks-reinstall: hooks-uninstall hooks-install
+	@echo "Hooks reinstalled"
+
+hooks-status:
+	@echo "=== Installed Claude Code Hooks ==="
+	@cat ~/.claude/settings.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin).get('hooks',{}); [print(f'  {k}: {len(v)} hook(s)') for k,v in d.items()]" 2>/dev/null || echo "  No hooks configured"
+	@echo ""
+	@echo "=== Hook Config ==="
+	@cat ~/.claude/ai-studio-config.env 2>/dev/null || echo "  No config file found"
+
+hooks-logs:
+	@echo "=== Recent Hook Logs ==="
+	@tail -100 ~/.claude/ai-studio-hooks.log 2>/dev/null || echo "  No log file found"
+
+hooks-logs-follow:
+	@tail -f ~/.claude/ai-studio-hooks.log
+
+hooks-logs-clear:
+	@rm -f ~/.claude/ai-studio-hooks.log
+	@echo "Hook logs cleared"
+
+hooks-debug-on:
+	@sed -i '' 's/AI_STUDIO_DEBUG=0/AI_STUDIO_DEBUG=1/' ~/.claude/ai-studio-config.env 2>/dev/null || true
+	@grep -q "AI_STUDIO_DEBUG" ~/.claude/ai-studio-config.env || echo "AI_STUDIO_DEBUG=1" >> ~/.claude/ai-studio-config.env
+	@echo "Hook debug logging enabled"
+
+hooks-debug-off:
+	@sed -i '' 's/AI_STUDIO_DEBUG=1/AI_STUDIO_DEBUG=0/' ~/.claude/ai-studio-config.env 2>/dev/null || true
+	@echo "Hook debug logging disabled"
+
+# OpenCode plugin management targets
+opencode-install:
+	cd opencode-plugin && ./install.sh
+
+opencode-uninstall:
+	cd opencode-plugin && ./uninstall.sh
+
+opencode-reinstall: opencode-uninstall opencode-install
+	@echo "OpenCode plugin reinstalled"
+
+opencode-build:
+	cd opencode-plugin && $(PKG_INSTALL) && $(PKG_MGR) run build
+
+# tmux-based dev targets for better monitoring
+TMUX_SESSION=ai-studio-dev
+
+dev-tmux:
+	@if tmux has-session -t $(TMUX_SESSION) 2>/dev/null; then \
+		echo "Session $(TMUX_SESSION) already exists. Use 'make dev-tmux-kill' first or attach with 'tmux attach -t $(TMUX_SESSION)'"; \
+	else \
+		tmux new-session -d -s $(TMUX_SESSION) -n backend; \
+		tmux send-keys -t $(TMUX_SESSION):backend "cd $(CURDIR)/backend && make dev" Enter; \
+		tmux new-window -t $(TMUX_SESSION) -n frontend; \
+		tmux send-keys -t $(TMUX_SESSION):frontend "cd $(CURDIR)/frontend && make dev" Enter; \
+		tmux select-window -t $(TMUX_SESSION):backend; \
+		echo "Started tmux session '$(TMUX_SESSION)' with backend and frontend windows"; \
+		echo "Attach with: tmux attach -t $(TMUX_SESSION)"; \
+	fi
+
+dev-tmux-kill:
+	@tmux kill-session -t $(TMUX_SESSION) 2>/dev/null && echo "Killed tmux session $(TMUX_SESSION)" || echo "No session to kill"
+
+dev-tmux-backend:
+	@tmux send-keys -t $(TMUX_SESSION):backend C-c 2>/dev/null || true
+	@sleep 1
+	@tmux send-keys -t $(TMUX_SESSION):backend "make dev" Enter 2>/dev/null || echo "Session not found"
+
+dev-tmux-frontend:
+	@tmux send-keys -t $(TMUX_SESSION):frontend C-c 2>/dev/null || true
+	@sleep 1
+	@tmux send-keys -t $(TMUX_SESSION):frontend "make dev" Enter 2>/dev/null || echo "Session not found"
+
+# Cleanup targets
+clean-db:			# Remove SQLite database
+	rm -f backend/visualizer.db
+	@echo "Database removed"
+
+clean:			# Remove build artifacts
+	rm -rf frontend/.next
+	rm -rf opencode-plugin/dist
+
+clean-all: clean clean-db hooks-logs-clear		# Remove everything
+	@echo "All build artifacts and data cleaned"
+
+# Docker targets
+docker-build:
+	docker compose build
+
+docker-up:
+	docker compose up -d
+	@echo "AI Studio running at http://localhost:8050"
+
+# Point the host hooks/plugin at the Docker-published port. Idempotent: the
+# grep guard keeps it from appending a second line on re-runs.
+docker-config:
+	@mkdir -p $(HOME)/.claude
+	@grep -q 'AI_STUDIO_API_URL' $(HOME)/.claude/ai-studio-config.env 2>/dev/null \
+		&& echo "ai-studio-config.env already sets AI_STUDIO_API_URL" \
+		|| (printf 'AI_STUDIO_API_URL=http://localhost:8050/api/v1/events\n' >> $(HOME)/.claude/ai-studio-config.env \
+			&& echo "Wrote AI_STUDIO_API_URL=http://localhost:8050/api/v1/events to ~/.claude/ai-studio-config.env")
+
+docker-down:
+	docker compose down
+
+docker-logs:
+	docker compose logs -f
+
+docker-shell:
+	docker compose exec ai-studio /bin/bash
+
+# Dependency management
+uv-lock:			# Lock dependencies
+	cd backend && uv lock
+	cd hooks && uv lock
+
+uv-sync:			# Sync dependencies
+	cd backend && uv sync
+	cd hooks && uv sync
+
+setup: uv-sync install		# First-time setup
+
+resetup: remove-venv setup		# Recreate virtual environments from scratch
+
+remove-venv:			# Remove virtual environments
+	rm -rf backend/.venv hooks/.venv
+
+depsupdate:			# Update all dependencies
+	cd backend && uv sync -U
+	cd hooks && uv sync -U
+	cd frontend && $(PKG_MGR) update
+
+depsshow:			# Show dependency tree
+	cd backend && uv tree
+
+# Version management (ARC-021 / QA-010): rewrite or verify all version locations.
+bump-version:			# Bump version everywhere: make bump-version VERSION=x.y.z
+ifndef VERSION
+	$(error VERSION is required: make bump-version VERSION=x.y.z)
+endif
+	uv run --no-project python scripts/bump_version.py $(VERSION)
+
+version-check:			# Verify all version locations agree (CI-friendly)
+	uv run --no-project python scripts/bump_version.py --check
+
+# Pre-commit
+pre-commit:			# Run pre-commit on all files
+	pre-commit run --all-files
+
+pre-commit-update:			# Update pre-commit hooks
+	pre-commit autoupdate
+
+# Help
+help:				# Display this help
+	@grep -Eh "^[a-z][-a-z]+:.+# " $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.+# "}; {printf "%-20s %s\n", $$1, $$2}'