Skip to content

SOURCE_OF_TRUTH.md

Latest commit

 

History

History
300 lines (230 loc) · 14.4 KB

SOURCE_OF_TRUTH.md

File metadata and controls

300 lines (230 loc) · 14.4 KB
Raw

aphrody — Source of Truth

Document unique de référence consolidant l'état du workspace. Lire celui-ci en premier. Mis à jour : 2026-06-04 (monorepo polyglotte Rust + Bun + Python ; ~70 crates Rust + surfaces packages//apps//py/ ; transport A2A gRPC).

Note historique : ce document décrivait à l'origine un workspace « 100 % Rust ». Le projet est passé à un monorepo polyglotte le 2026-05-21 (Rust primaire + Bun/TS pour l'UI Material Design 3 + Python pour ML/data) — cf. CLAUDE.md §2 qui fait désormais autorité sur la politique de langages. Les mentions « 100 % Rust » ci-dessous concernent uniquement le cœur CLI/systems/FFI, qui reste 100 % Rust et sans dépendance runtime vers Bun/Python.

0. TL;DR

Quoi Valeur
Nom du projet aphrody
Binaire distribué aphrody (cross-platform pur)
Repo GitHub https://github.com/aphrody-code/aphrody (privé initialement)
Stack Rust nightly (Edition 2024) primaire + Bun/TS (UI M3) + Python (ML/data). Cœur CLI 100 % Rust.
Workspace Monorepo polyglotte : ~70 crates Rust (crates/*) + packages//apps//examples/ (Bun) + py/ (Python)
Plateformes (ordre strict) (1) Linux Ubuntu 26.04 → (2) Windows 11 Insider Canary → (3) WebAssembly → (4) macOS (best-effort)
Licence Apache 2.0
Status 1.0.0-canary, pre-LTS
Pivot date 2026-05-17 (abandon "Google OS hybride", focus CLI portable)

1. Mission & non-mission

Mission

Livrer le CLI ultime cross-platform :

  • Un binaire aphrody qui fonctionne réellement sur Linux Ubuntu 26.04, Windows 11 Insider Canary Build, et en lib WebAssembly (wasm32-wasi + wasm32-unknown-unknown).
  • Une expérience CLI moderne (a2a agents intégrés, MCP server natif).
  • Une supply-chain Google-grade (cargo-vet + cargo-deny + lockfile-only).
  • Un workspace Rust hermétique reproductible bit-à-bit.

Objectifs structurants

  1. Material Design 3 natif : tokens (m3-tokens), icônes (aphrody-icons), renderer wgpu (mui-rs*, exclu par défaut) et intégration React (aphrody-react-reconciler).
  2. Plugin Claude Code aphrody : serveur MCP natif unique aphrody-mcp (15 tools), commandes /status + /docs, catalogue d'agents/skills.
  3. Intégration de l'écosystème Rust Vercel (swc-*, lightningcss, mdxjs, oxc) déclarée dans Cargo.toml workspace.dependencies pour les crates tuono* (exclues du build par défaut).

Règles transversales

  • Web/UI : la surface UI est le monorepo Material Design 3 (Bun + TS, libs @aphrody-code/* dans packages/*, client apps/web). Le cœur Rust peut exposer du WASM/WebGPU, mais l'UI grand public est servie par la stack Bun (cf. CLAUDE.md §2).
  • Zéro stub / zéro placeholder / zéro scaffolding : toute feature commencée doit être finie. Toute fonction doit faire ce qu'elle prétend faire.
  • Linux Ubuntu 26.04 = cible #1 bloquante. Ne compile pas Linux → ne merge pas.

Non-mission

  • Pas un OS, un kernel, ni un émulateur Windows-NT (le sous-projet google_os a été archivé hors du repo le 2026-05-17 — voir §7).
  • Pas un fork de Windows Terminal ni un moteur de rendu Direct3D.
  • Pas un wrapper node.js / npm.

2. Plateformes — priorités absolues

Rang Plateforme Triple Statut bloquant pour merge
#1 Linux Ubuntu 26.04 x86_64-unknown-linux-gnu Oui
#2 Windows 11 Insider Canary x86_64-pc-windows-msvc Oui
#3 WebAssembly (lib) wasm32-wasi, wasm32-unknown-unknown Oui
#4 macOS x86_64-apple-darwin, aarch64-apple-darwin Best-effort
#5 Android aarch64-linux-android, x86_64-linux-android Best-effort (CI active mais non bloquante)

Toute introduction de code Windows-specific dans le binaire cli doit être gated #[cfg(target_os = "windows")] et doit avoir un équivalent Linux fonctionnel via #[cfg(target_os = "linux")].

3. Architecture

Détail complet : docs/ARCHITECTURE.md, docs/cargo/WORKSPACE.md, docs/cargo/CRATES.md.

Workspace Rust — 57 membres actifs

Familles principales (inventaire exhaustif dans CRATES.md) :

Famille Crates clés
Cœur cli (binaire aphrody), base, backend, mrx
A2A a2a (a2a-lf), a2a-client, a2a-server, a2a-pb, a2a-grpc, a2a-ui, google_mcp
LLM/agent aphrody-llm-infra, aphrody-router, aphrody-providers, aphrody-gateway, aphrody-mcp, aphrody-chat, aphrody-sdk, aphrody-memory, gemini-runtime, notebooklm, …
Skills/orchestration aphrody-skills, aphrody-skills-forge, aphrody-marketplace, aphrody-task-runner, aphrody-cron, aphrody-events
Système aphrody-secrets, aphrody-settings, aphrody-telemetry, aphrody-search, aphrody-re, aphrody-messaging, aphrody-voice, ievr-tools, aphrody-translate, aphrody-summary
Design/terminal aphrody-design, aphrody-design-agents, m3-tokens, aphrody-icons, aphrody-react-reconciler, aphrody-tui, aphrody-terminal-* (8)
WASM aphrody-wasm, aphrody-terminal-wasm, a2a-ui

Le binaire aphrody-mcp (serveur MCP natif) est produit par le crate google_mcp.

Exclus du workspace

  • crates/aphrody-app — coquille Tauri v2.
  • aphrody-x-client, a2a-slimrpc — bloqués upstream.
  • gui, agui-bridge, mui-rs* (6), tuono* (4) — extraits vers C:\src\aphrody-ts le 2026-05-23 ; ces chemins n'existent plus dans ce dépôt. coreutils/util-linux sont encore listés dans exclude mais n'existent plus sur disque.

Supprimés (historique)

  • Pivot 2026-05-17 : google_os (archivé C:\google-os-archive\), bun_ffi, google_kv, python_ffi.
  • 2026-05-21 : les 11 n2b-*, bxc-engine, aphrody-xtask, et 18 doublons fusionnés (aphrody-{cache,cost,rateguard,retry}→aphrody-llm-infra ; aphrody-channels→aphrody-messaging ; aphrody-{hooks,permissions,skills-runtime}→aphrody-skills ; aphrody-design-{daemon,sidecar}→aphrody-design ; aphrody-voice-stt→aphrody-voice ; mrx-{core,detect,audit,watch,cli}→ mrx ; orphelins aphrody-shell, aphrody-sandbox).
  • vendor/ retiré (ne contenait que des stubs Bun/uv).

4. Politique de langages

Pivot 2026-05-21 : monorepo polyglotte, Rust primaire. Source d'autorité : CLAUDE.md §2.

Langage Usage
Rust nightly + Edition 2024 (primaire) Cœur CLI/systems/FFI, libs, MCP, A2A, tooling (crates/*). Le binaire aphrody ne dépend d'aucune autre toolchain au runtime.
Bun / TypeScript Citoyen de première classe pour l'UI : libs Material Design 3 @aphrody-code/* (packages/*), client web (apps/*), examples/*. Bun + Turborepo, lint oxlint, format oxfmt.
Python Citoyen de première classe pour ML/data/bridges (py/). uv + ruff + pytest.
C/C++ Interdit dans le code distribué. Tolérable uniquement via cxx::bridge pour wrappers FFI inévitables.
PowerShell 7+ / Bash Wrappers d'install/déploiement (scripts/deploy.{ps1,sh}) ; logique réelle dans une des 3 toolchains.

5. Commandes critiques

Build local

# Linux (cible #1)
cargo build --release -p aphrody                          # natif
cargo build --release -p aphrody --target x86_64-unknown-linux-gnu

# Windows (cible #2)
cargo build --release -p aphrody                          # depuis Windows
cargo build --release -p aphrody --target x86_64-pc-windows-msvc

# WebAssembly (cible #3)
cargo build --release -p aphrody --target wasm32-wasi
cargo build --release -p aphrody --target wasm32-unknown-unknown

Validation (zéro tolérance warnings)

cargo ci-offline       # clippy + --locked + --offline + -D warnings
cargo xt-offline       # nextest + --locked + --offline
cargo deny check       # CVE + licences + bans + sources
cargo vet              # audits signés (Google/Mozilla/Fuchsia/ChromeOS)
cargo audit-machete    # unused deps detector

Cross-platform check (avant chaque PR)

cargo check -p aphrody --target x86_64-unknown-linux-gnu --locked   # bloquant
cargo check -p aphrody --target x86_64-pc-windows-msvc --locked     # bloquant
cargo check -p aphrody --target wasm32-unknown-unknown --locked     # bloquant

6. Supply-chain (Google-grade)

  • Lockfile-only depuis 2026-05-16 (pas de cargo vendor).
  • Sparse registry (10-100× plus rapide que git).
  • cargo-vet audits importés depuis 7 feeds : Google, Mozilla, Fuchsia, ChromeOS, Bytecode Alliance, Embark Studios, Zcash.
  • cargo-deny : CVE RustSec DB + licences + bans + sources.
  • CI hermétique : --locked --offline -D warnings.

7. Pivot 2026-05-17 — décisions structurelles

Ce qui change

  • ✅ Repo renommé google-cli → aphrody (script scripts/rename-project.ps1).
  • ✅ Crate google_os sortie hors du workspace, archivée sous C:\google-os-archive\. Ne plus importer.
  • ✅ crates/google_mcp dépendance vers google_os retirée.
  • ✅ Metadata workspace : authors, homepage, repository, keywords, categories mis à jour pour aphrody.
  • 🔧 CI matrix .github/workflows/cross-platform.yml priorisée Linux d'abord.
  • 🔧 crates/a2a* et crates/google_mcp à adapter pour Linux pur.

Ce qui reste

  • Architecture workspace + supply-chain + FFI zero-copy.
  • Les crates métier conservés (a2a*, google_mcp, backend, mrx, …).
  • Politique langages : cœur 100 % Rust ; UI Bun/TS + ML Python (pivot polyglotte 2026-05-21, cf. §4).
  • Stack 2026 (Rust nightly, Edition 2024, mimalloc, sccache).

Ce qui est abandonné

  • ❌ Émulation Windows NT kernel (google_os).
  • ❌ Hybride Windows Terminal C++ fork (Pilier II historique).
  • ❌ DxEngine custom (Direct2D/D3D11 textures).
  • ❌ Architecture "Material Design 3" comme priorité (move to optional GUI).

8. Pièges connus (mémoire institutionnelle)

Piège Mitigation
aws-lc-sys build cassé sur MSVC NASM prebuilt + Ninja generator (.cargo/config.toml). Sur Linux : apt install libssl-dev.
tracing-subscriber 0.3.23+ Pinné à 0.3.22 (bug mod env packaging).
path-bases (RFC 3529) Instable nightly 1.97, à activer quand stable.
rand 0.8 imposé par denokv_proto Ne pas migrer vers 0.9 avant que denokv_proto accepte.
GTK3 CVE (RUSTSEC-2024-04xx) Ignorés dans deny.toml. cli n'est PAS lié à GTK. gui a été extrait vers aphrody-ts (2026-05-23) ; seul aphrody-app (Tauri, exclu) pull wry/webkit2gtk.
tokio ne compile pas sur wasm Utiliser features sélectives (tokio-stream + js-sys + wasm-bindgen-futures).
pty cross-platform portable-pty (ConPTY Windows / openpty Unix) dans aphrody-terminal-backend. Pas de node-pty.
aphrody chat + token agy expiré classify_agy_error dans crates/cli/src/agy_backend.rs intercepte `SdkError::OAuthServer{401
aphrody antigravity refresh cassé Google retourne 400 client_secret is missing : le client OAuth public Antigravity ne fournit pas de client_secret pour le refresh grant. Workaround : relancer agy en arriere-plan (re-mint le token). Re-auth : aphrody antigravity login.
Token agy sur Linux Fichier canonique : ~/.gemini/antigravity-cli/antigravity-oauth-token (pas WinCred). antigravity-sdk::token_from_credential_manager lit aussi ~/.config/aphrody/antigravity-token.json. Doc : docs/agy-cli/README.md §4.
Build VPS / rustc 1.97 rustup default nightly ; CARGO_TARGET_DIR=~/aphrody/target/linux-gnu ; unset RUSTC_WRAPPER si sccache absent. Snippet : awesome-grok-build/scripts/rust-nightly-env.sh.

9. Roadmap (post-pivot)

Phase P-Linux (PRIORITÉ ABSOLUE)

  • Validation cargo build --release -p aphrody sur Ubuntu 26.04 natif.
  • Validation cargo nextest run -p aphrody sur Ubuntu 26.04.
  • CI runner ubuntu-26.04 (sinon ubuntu-latest).
  • Package apt / PPA pour distribution Ubuntu.

Phase P-Win11

  • Validation cargo build --release -p aphrody sur Win11 Insider Canary.
  • Package scoop + winget manifest.

Phase P-Wasm

  • cli compilable sur wasm32-wasi (CLI lib).
  • cli compilable sur wasm32-unknown-unknown (web lib).
  • wasm-pack publish sur npm en tant que @aphrody-code/aphrody-wasm.

Phase P-A2A-Adapt

  • Auditer a2a* pour code Windows-only.
  • Gater en #[cfg(target_os = "windows")] ce qui doit l'être.
  • Implémenter équivalents Linux (epoll, io_uring) là où nécessaire.

Phase P-MCP-Adapt

  • Idem pour google_mcp.
  • Renommer éventuellement google_mcp → aphrody_mcp (décision séparée).

Phase P-Distribution

  • crates.io publication (aphrody).
  • Homebrew tap aphrody-code/tap → brew install aphrody.
  • Releases GitHub avec binaires Linux + Windows + wasm.

10. Ressources documentaires

Doc Contenu
CLAUDE.md Directives Claude Code (résumé opérationnel).
docs/ARCHITECTURE.md Carte du workspace (57 membres) + diagrammes.
docs/PLAN.md Plan d'exécution détaillé.
docs/SUMMARY.md mdBook ToC global (auto-généré par aphrody-summary).
docs/cargo/CRATES.md Inventaire par crate.
docs/cargo/CROSS_PLATFORM.md Stratégie multi-target Cargo.
docs/cargo/CHROMIUM_ANDROID_PATTERNS.md Patterns Google-grade.
docs/cargo/SKILLS.md Catalogue agents + skills.
docs/cargo/SUPPLY_CHAIN.md Détails cargo-vet / cargo-deny.
docs/cargo/WORKSPACE.md Description fine du workspace.
docs/cargo/FFI_POLICY.md Règles FFI strictes.

11. Convention de contribution

  • Conventional Commits (feat:, fix:, refactor:, build:, docs:).
  • Pas de mock, pas de fake data, pas de stub.
  • Linux est la cible #1 : ça doit compiler et passer les tests sur Linux avant tout.
  • Avant push : cargo ci-offline && cargo deny check sur Linux d'abord.
  • Cross-platform check : les 3 cibles prioritaires doivent passer cargo check.

Cette source de vérité remplace les sections redondantes des autres docs. En cas de divergence, ce fichier prime.