rustwarden-cli

Wizard interactif en ligne de commande pour creer et maintenir des projets applicatifs bases sur le framework Rustwarden.

Installation

Depuis la racine du workspace Rustwarden :

cargo build -p rustwarden-cli

Le binaire est genere dans target/debug/rustwarden-cli.

Pour un binaire optimise reutilisable :

cargo build -p rustwarden-cli --release
# => target/release/rustwarden-cli

Utilisation

# Lancement direct (compile + execute)
cargo run -p rustwarden-cli -- <commande>

# Ou via le binaire
./target/release/rustwarden-cli <commande>

Commandes disponibles :

Commande	Description
start-project	Creer un nouveau projet applicatif Rustwarden
update-project	Mettre a jour les crates du framework dans un projet existant

Primitives fournies par le framework

Chaque projet genere embarque l'ensemble des primitives du framework. Elles sont toutes accessibles via rustwarden_core::prelude::* :

Domaine	Types cles	Reference
Authentification	AuthUser, Claims, JwtService	SERVICES_REFERENCE.md §4
RBAC	RoleService, PermissionService	SERVICES_REFERENCE.md §5
Mots de passe	PasswordService, PasswordChangeService, PasswordResetService	SERVICES_REFERENCE.md §6
Tokens de session	RefreshTokenService, JwtBlacklistService	SERVICES_REFERENCE.md §7
Personal Access Tokens	PersonalTokenService<S>, TokenScope, PersonalTokenCleanupProcessor<S>	SERVICES_REFERENCE.md §7
Teams	TeamService, TeamSlug, TeamRole	SERVICES_REFERENCE.md §9
Ressources partagees	ResourceService, Principal	SERVICES_REFERENCE.md §8
OAuth / SSO	OAuthService, providers Google/GitHub/Discord/Microsoft	SERVICES_REFERENCE.md §14
Email	EmailService, EmailValidationService, templates Askama	SERVICES_REFERENCE.md §12
Rate limiting	RateLimitService (sliding window generique)	SERVICES_REFERENCE.md §15
Notifications temps-reel (SSE)	NotificationBus, InMemoryBus, sse_response	SERVICES_REFERENCE.md §16
Hooks lifecycle	RustwardenHooks (on_user_, on_team_, on_totp_, on_resource_, on_audit_event)	SERVICES_REFERENCE.md §17, DEVELOPER.md §12

Le main.rs genere contient un bloc commente listant les primitives optionnelles a activer (PAT cleanup, hooks, SSE). Voir DEVELOPER.md du projet genere pour les exemples concrets d'integration.

cargo run --bin change_password -- admin "ChangeMe123!" 2>&1 | tail -5 cargo run --bin migrate 2>&1 | tail -10

• ralph | Password: happydays123
  • joanie | Password: happydays123

cargo run --bin change_password -- admin "ChangeMe123!" cargo run --bin change_password -- joanie "happydays123" cargo run --bin change_password -- richie "happydays123"

Commande start-project

Le wizard pose une serie de questions pour configurer le projet, puis genere un dossier complet pret a l'emploi.

Questions posees

Etape	Question	Exemple
1	Nom du projet (nom technique, sans espaces)	mon-app
2	Nom affiche dans l'interface (APP_NAME)	Mon Application
3	Description	Application de gestion propulsee par Rustwarden
4	Dossier cible	/home/user/projects
5	Mode (interface web ou API seule)	Interface web
6	Migrations automatiques au demarrage	Oui
7	Port du serveur	3000
8	Nom de la base de donnees	mon_app
9	Utilisateur PostgreSQL	mon_app_user
10	Mot de passe PostgreSQL	(genere aleatoirement)
11	Username admin	admin
12	Email admin	admin@localhost
13	Mot de passe admin	(genere aleatoirement)
14	Configurer SMTP ? (optionnel)	Non
15	Activer OAuth / SSO ? (optionnel)	Non

Si SMTP est active, le wizard demande egalement :

• Hote, port, identifiants SMTP
• Adresse et nom d'expediteur
• TLS / STARTTLS

Si OAuth est active :

• URL de base pour les callbacks
• Configuration par provider (Google, GitHub, Discord, Microsoft)

Structure generee

mon-app/
├── Cargo.toml              # Workspace autonome
├── src/
│   └── main.rs             # Point d'entree avec routes personnalisees
├── crates/
│   ├── rustwarden-core/    # Framework d'authentification (copie locale)
│   └── rustwarden-ui/      # Interface web (copie locale, si mode UI)
├── locales/                # Fichiers de traduction (fr, en, de, es)
├── static/                 # Fichiers statiques (CSS, JS, images)
├── database/
│   ├── docker-compose.yml  # PostgreSQL avec Docker
│   └── .env                # Identifiants DB pour Docker
├── .env                    # Configuration complete de l'application
├── .env.example            # Reference de toutes les variables d'environnement
├── .rustwarden-version     # Version du framework (pour update-project)
├── README.md               # Guide de demarrage rapide
└── DEVELOPER.md            # Guide complet pour ajouter de la logique metier

Fichiers generes automatiquement

Fichier	Contenu
Cargo.toml	Workspace avec les crates locales
src/main.rs	Builder Rustwarden configure + route exemple /api/hello
.env	Variables d'environnement remplies avec les reponses du wizard
.env.example	Reference avec toutes les variables et valeurs d'exemple
database/.env	Credentials PostgreSQL pour Docker Compose
.rustwarden-version	Hash git + date du framework au moment de la generation
README.md	Demarrage rapide, routes, commandes
DEVELOPER.md	Architecture, ajout de routes/modeles, hooks, i18n, configuration

Traitement post-copie

Apres la copie des crates et des ressources, le wizard effectue automatiquement :

1. Rebrand des templates : remplacement de toute occurrence de "RustWarden" dans les fichiers HTML par le nom d'application choisi
2. Page d'accueil personnalisee : remplacement de home.html par une page hero section avec le nom de l'application
3. Configuration APP_NAME : injection du nom dans le .env pour que l'UI et les emails utilisent le bon branding

Demarrage du projet genere

cd mon-app

# 1. PostgreSQL n'ecoute que 127.0.0.1:5432. Copier env.sample vers .env
#    et definir POSTGRES_PASSWORD (obligatoire, pas de mot de passe par defaut).
cp database/env.sample database/.env
cd database && docker compose up -d && cd ..

# 2. Lancer l'application
cargo run

# 3. Ouvrir http://localhost:3000

L'admin initial est deja configure avec les identifiants fournis pendant le wizard.

Commande update-project

Met a jour les crates du framework (rustwarden-core, rustwarden-ui) et les ressources partagees (locales, static, database) dans un projet existant, sans toucher aux fichiers specifiques du projet.

cargo run -p rustwarden-cli -- update-project

Fonctionnement

1. Detection : demande le chemin du projet et verifie qu'il s'agit bien d'un projet Rustwarden
2. Versions : affiche la version actuelle (depuis .rustwarden-version) et la nouvelle (git hash du framework)
3. Detection des templates personnalises : compare les templates HTML du projet avec ceux du framework pour identifier les modifications
4. Plan de mise a jour : affiche ce qui sera mis a jour et ce qui sera preserve
5. Confirmation : demande validation avant de proceder
6. Backup : cree un dossier .rustwarden-backup-YYYYMMDD_HHMMSS/ avec une copie complete des fichiers qui vont etre remplaces
7. Mise a jour : remplace les crates et ressources par les versions du framework source
8. Version : met a jour .rustwarden-version

Fichiers mis a jour

Element	Action
crates/rustwarden-core/	Supprime et recopie depuis le framework
crates/rustwarden-ui/	Supprime et recopie (si present dans le projet)
locales/	Remplace
static/	Remplace (si le projet a une UI)
database/	Remplace en preservant database/.env
docs/SERVICES_REFERENCE.md	Ecrase depuis le framework (source de verite API)
docs/MIGRATION_GUIDE.md	Ecrase depuis le framework (breaking + actions consommateur)
docs/fediverse-consumer-guide.md	Ecrase si le projet a la federation

Fichiers jamais touches

Fichier	Raison
Cargo.toml	Configuration workspace du projet
src/main.rs	Logique metier du projet
.env	Credentials et configuration specifiques
.env.example	Peut avoir ete personnalise
database/.env	Credentials PostgreSQL du projet
README.md	Documentation specifique au projet
DEVELOPER.md	Guide personnalise

Apres la mise a jour

Le CLI affiche les etapes a suivre :

# 1. Verifier la compilation
cargo check

# 2. Corriger les eventuels breaking changes
cargo clippy -- -D warnings

# 3. Verifier les migrations
cargo run --bin migrate

# 4. Lire les notes consommateur (dont Security 1.0.1)
#    docs/MIGRATION_GUIDE.md puis docs/SERVICES_REFERENCE.md (bandeau)

# 5. Lancer les tests
cargo test

Si des templates personnalises ont ete ecrases, ils sont recuperables dans le dossier de backup.

Architecture du CLI

tools/rustwarden-cli/
├── Cargo.toml            # Dependencies : clap, dialoguer, console, rand, chrono
└── src/
    ├── main.rs           # Point d'entree, parsing des sous-commandes
    ├── start_project.rs  # Wizard de creation (questions, copie, generation)
    ├── update_project.rs # Logique de mise a jour (backup, remplacement, detection)
    ├── templates.rs      # Templates des fichiers generes (Cargo.toml, main.rs, .env, etc.)
    └── version.rs        # Gestion du fichier .rustwarden-version (lecture, ecriture, calcul)

Dependencies

Crate	Role
clap	Parsing des arguments et sous-commandes
dialoguer	Prompts interactifs (Input, Select, Confirm)
console	Styles et couleurs dans le terminal
rand	Generation de mots de passe et secrets JWT aleatoires
chrono	Timestamp pour les noms de dossiers de backup

Etendre le CLI

Pour ajouter une nouvelle sous-commande, ajoutez une variante dans l'enum Commands de main.rs :

#[derive(Subcommand)]
enum Commands {
    /// Creer un nouveau projet applicatif Rustwarden
    StartProject,
    /// Mettre a jour les crates du framework dans un projet existant
    UpdateProject,
    /// Votre nouvelle commande
    MaCommande,
}

Puis implementez la logique dans un nouveau module.