Open Source Assistant

Assistant Discord pour développeurs, administrateurs de serveurs et communautés open source. Il permet de rechercher rapidement des informations sur GitHub, npm, PyPI, Docker Hub et de la documentation technique, sans quitter Discord.

Le bot est écrit en JavaScript avec Discord.js v14 et utilise les Components V2 de Discord pour des interfaces modernes (containers, sections, miniatures, boutons, menus), plutôt que de simples embeds. Les commandes GitHub génèrent en plus une carte visuelle dessinée à la volée avec canvas (avatar, étoiles, forks, langage...).

Toutes les interactions sont en français.

Fonctionnalités

Recherche

Commande	Description	Exemple
/define	Définition d'un terme technique	/define webhook
/npm	Recherche un package npm	/npm express
/pypi	Recherche un package PyPI	/pypi requests
/docker	Recherche une image Docker Hub	/docker nginx
/github repo	Informations sur un dépôt, avec carte visuelle	/github repo discordjs/discord.js
/github user	Profil d'un utilisateur GitHub, avec carte visuelle	/github user torvalds
/github issue	Détails d'une issue, avec carte visuelle	/github issue discordjs/discord.js 123
/github release	Dernière release d'un dépôt, avec carte visuelle	/github release discordjs/discord.js
/github search	Recherche de dépôts, avec pagination	/github search discord bot
/docs	Recherche de documentation officielle	/docs node fetch

Bot

Commande	Description
/aide	Liste des commandes, organisée par catégorie, navigable via menu
/infos-bot	Statistiques et informations sur le bot

D'autres fonctionnalités transverses :

• Cartes GitHub générées à la volée avec @napi-rs/canvas (avatar, statistiques, couleur du langage)
• Autocomplétion sur /define, /npm, /pypi, /docker
• Cache en mémoire pour éviter les appels API redondants
• Rate limit par utilisateur pour éviter le spam
• Gestion d'erreurs en français, sans jamais exposer de stack trace
• Fonctionne sans token GitHub (avec des limites d'API plus basses)

Aperçu

Installation

1. Installer Node.js

Node.js 20 ou supérieur est requis. Vérifie ta version :

node -v

2. Cloner le projet

git clone https://github.com/Cut0x/OpenSourceAssistant.git
cd OpenSourceAssistant

3. Installer les dépendances

npm install

4. Créer le fichier .env

cp .env.example .env

Puis remplis les variables (voir sections suivantes).

5. Configurer le bot sur le Discord Developer Portal

1. Va sur discord.com/developers/applications
2. Crée une nouvelle application
3. Dans l'onglet Bot, crée un bot et copie son token dans DISCORD_TOKEN
4. Dans l'onglet General Information, copie l'Application ID dans CLIENT_ID
5. Toujours dans l'onglet Bot, active si besoin les intents nécessaires (aucun intent privilégié n'est requis pour ce bot)

6. Inviter le bot sur un serveur

Dans l'onglet OAuth2 > URL Generator :

• Scopes : bot, applications.commands
• Permissions : Send Messages, Embed Links, Attach Files, Use External Emojis, Read Message History

Ouvre l'URL générée pour inviter le bot sur ton serveur.

7. Enregistrer les commandes

Pour un enregistrement instantané pendant le développement, renseigne GUILD_ID dans .env (clic droit sur ton serveur > Copier l'ID, mode développeur activé dans Discord) puis lance :

npm run register

Sans GUILD_ID, l'enregistrement est global et peut prendre jusqu'à une heure pour se propager.

8. Lancer le bot

npm start

Configuration GitHub (optionnel)

Sans token, le bot utilise les limites publiques de l'API GitHub (60 requêtes/heure par IP), ce qui est suffisant pour un usage personnel ou un petit serveur.

Pour augmenter cette limite à 5000 requêtes/heure :

1. Va sur github.com/settings/tokens
2. Génère un token classique (fine-grained ou classic) sans scope particulier (accès public seul nécessaire)
3. Renseigne-le dans GITHUB_TOKEN

Utilisation

/define webhook
/define reverse proxy

/npm express
/npm discord.js

/pypi requests
/pypi discord.py

/docker nginx
/docker postgres

/github repo discordjs/discord.js
/github user torvalds
/github issue discordjs/discord.js 123
/github release discordjs/discord.js
/github search discord bot

/docs discord.js
/docs node fetch
/docs python asyncio
/docs docker compose

/aide
/infos-bot

Docker

Avec Docker Compose

cp .env.example .env
# remplir .env

docker compose up -d

Le conteneur redémarre automatiquement (restart: unless-stopped). Les commandes doivent être enregistrées au moins une fois via npm run register avant ou après le premier lancement (localement, ou en exécutant docker compose run --rm bot node src/deploy-commands.js).

Avec Docker seul

docker build -t open-source-assistant .
docker run -d --env-file .env --name open-source-assistant open-source-assistant

Développement

Le mode développement utilise --watch pour redémarrer automatiquement le bot à chaque modification de fichier :

npm run dev

Passe DEV_MODE=true dans .env pour activer des logs plus détaillés (niveau DEBUG).

Pendant le développement, définis GUILD_ID pour que npm run register mette à jour les commandes instantanément sur ton serveur de test plutôt que globalement.

Structure du projet

assets/
  fonts/             Police Inter (rendu des cartes canvas)

src/
  commands/          Définitions et logique des commandes slash
  events/            Gestionnaires d'événements Discord.js (ready, interactionCreate)
  services/          Appels aux API externes (GitHub, npm, PyPI, Docker Hub, docs, glossaire)
  components/        Constructeurs Components V2 (containers, boutons, menus, cartes canvas, routage des interactions)
  utils/             Cache, rate limit, logs, formatage, gestion d'erreurs, HTTP, dessin canvas
  config/            Chargement de la configuration depuis .env
  index.js           Point d'entrée du bot
  deploy-commands.js Script d'enregistrement des commandes slash

docs/images/         Emplacement des captures d'écran du README

Le principe de séparation suivi :

• commands ne contient que la logique d'interaction Discord (options, réponses) et l'assemblage visuel
• services ne connaît rien de Discord : uniquement des appels API et leur mise en forme brute
• components regroupe les briques Components V2 réutilisables, les cartes canvas et le routage des boutons/menus
• utils est indépendant du domaine (cache, logs, erreurs, dessin canvas...)

APIs utilisées

API	Usage
GitHub REST API	Dépôts, utilisateurs, issues, releases, recherche
npm Registry API	Métadonnées des packages npm
npm Downloads API	Statistiques de téléchargement npm
PyPI JSON API	Métadonnées des packages Python
Docker Hub API	Images et tags Docker
MDN Web Docs Search API	Résultats de documentation web/JavaScript

Les autres sources de /docs (Node.js, Python, Docker, Git, GitHub, npm) reposent sur un index de pages officielles maintenu dans le code, faute d'API de recherche publique et fiable pour ces documentations.

Cartes GitHub (canvas)

Les sous-commandes /github repo, user, issue, release et search génèrent une image via @napi-rs/canvas (avatar circulaire, étoiles, forks, langage coloré, badges...), envoyée en pièce jointe et affichée dans un bloc MediaGallery du message Components V2.

Les informations déjà visibles sur la carte (nom, stats, langage, auteur, date...) ne sont pas répétées dans le texte des components : celui-ci ne complète l'image qu'avec ce qu'elle ne montre pas (licence, notes de version, description d'une issue...).

Si le rendu échoue pour une raison quelconque (police manquante, avatar inaccessible...), la commande continue normalement sans image, et bascule alors sur une version texte complète pour ne perdre aucune information.

Limites

• L'API GitHub non authentifiée est limitée à 60 requêtes/heure ; utilise GITHUB_TOKEN pour la lever à 5000/heure
• Le nombre de téléchargements npm peut être indisponible pour certains packages
• Docker Hub ne fournit pas toujours l'architecture pour chaque tag
• L'index de /docs couvre les sujets les plus courants, pas l'intégralité de chaque documentation

Choix techniques

Le bot ne stocke aucune donnée persistante (pas de préférences utilisateur, pas de compteurs à long terme) : le cache des réponses API et le rate limit vivent en mémoire et se réinitialisent au redémarrage. Une base SQLite a donc volontairement été omise pour garder le projet léger ; elle pourra être ajoutée facilement dans src/services si une fonctionnalité future en a besoin (statistiques d'usage, préférences par serveur...).

Contribution

Les contributions sont bienvenues.

1. Fork le dépôt
2. Crée une branche (git checkout -b feature/ma-fonctionnalite)
3. Commit tes changements avec un message clair
4. Push ta branche et ouvre une Pull Request

Issues

Pour signaler un bug, ouvre une issue en précisant :

• la commande utilisée et ses paramètres
• le comportement attendu et le comportement observé
• les logs console pertinents si disponibles

Pull Requests

• Une PR = un sujet (évite de mélanger plusieurs fonctionnalités)
• Garde le style de code existant (pas de dépendance inutile, pas de TypeScript)
• Vérifie que le bot démarre et que les commandes concernées fonctionnent avant de proposer la PR

Licence

Distribué sous licence MIT.

Crédits

• Discord.js - bibliothèque d'interaction avec l'API Discord
• @napi-rs/canvas - rendu des cartes GitHub
• Inter (licence SIL Open Font License) - police utilisée sur les cartes canvas, voir assets/fonts/OFL.txt
• GitHub, npm, PyPI, Docker Hub pour leurs API publiques
• MDN Web Docs pour son API de recherche
• Icônes issues du dépôt public github/explore