Développement
La structure du dépôt, les commandes make, les specs et les exigences, et les tests de bout en bout.
Bosco est un monorepo pnpm 12 et Turborepo, sous Node 26. Les conventions de code sont dans .claude/rules/ du dépôt, et les instructions des agents dans AGENTS.md.
Structure du dépôt
| Dossier | Contenu |
|---|---|
apps/api | Service NestJS sur Fastify : un module par contexte (domain, application, infrastructure, interface/http), qui sert aussi l'interface sur le même port ; commande bosco (src/cli) |
apps/web | Interface Next.js, design system (tokens des specs, daisyUI, shadcn/ui sur Radix, Storybook) |
apps/desktop | Application du poste (Electron, Linux) : fenêtre, barre système, notifications natives ; .deb, AppImage |
apps/mobile | Application Android (Expo) : interface téléphone dans une vue web, appairage par QR code, notifications locales |
apps/docs | Ce site (Fumadocs), exporté en pages statiques |
packages/domain | Contrats partagés avec le web : nom de l'application, types des vues |
packages/configs | Configurations partagées : TypeScript, ESLint, Vitest, Prettier |
tools/release | Outils du workflow Release : version tirée des commits, écrite dans les applications, CHANGELOG.md et notes |
e2e | Scénarios Gherkin de l'API (anglais) et du web (français), module d'enregistrement des appels sortants |
Commandes
Toutes les commandes passent par le Makefile ; make help les liste.
make install # dépendances et skills épinglés
make dev # service en développement sur http://127.0.0.1:4880, interface rechargée à chaud, données dans .data/
make check # lint, types, tests et build de chaque paquet (Turborepo)
make format-check # mise en forme (Prettier)
make e2e # scénarios de l'API, puis parcours du web (ordinateur et téléphone)
make storybook # http://localhost:6006
make docs-dev # ce site sur http://127.0.0.1:4890
make docs-build # export statique de ce site dans apps/docs/out
make docs-screenshots # captures de ce site, prises sur Bosco avec les données du fil rouge
make db-migration # écrit la migration qui amène la base aux entités
make claude-compat # vérifie les hooks et les tours pilotés sur le Claude Code installémake dev garde ses données dans .data/ du dépôt, sur le port 4880 : il ne touche ni au Bosco installé (4870) ni à ~/.local/share/bosco.
Avant de rendre la main : make format-check, make check, puis make e2e-api ou make e2e-web dès qu'une route, un écran ou un scénario change.
Specs et exigences
Les specs UI et le cahier des charges vivent dans un dépôt à part, fpasquet/specs, dossier bosco/, cloné à côté du dépôt (~/www/specs et ~/www/bosco). Ce dépôt n'en reçoit que deux copies, qu'on ne modifie jamais à la main :
docs/requirements/, l'export du cahier des charges : règles fonctionnelles (RF), critères d'acceptation (CA), exigences non fonctionnelles (NF) et décisions techniques (DT), par lot.make requirementsle régénère.apps/web/src/styles/tokens.css, la copie des tokens de la marque.make tokensla régénère.
Pour une question fonctionnelle, lis d'abord docs/requirements/README.md, puis le lot : lots/sessions.md, lots/contexte.md, lots/apps.md, lots/reglages.md. Un écart entre le code et les specs se tranche, puis se reporte dans le dépôt de specs.
Les identifiants (écrans E2, états E2b, règles RF-SESS-03, critères CA-SESS-12) ne sont jamais renumérotés. Un test cite le critère qu'il vérifie dans son nom.
Tests
- Vitest pour ce que les scénarios n'atteignent pas : invariants du domaine, temps exact, cas rares, migrations.
- Storybook : une histoire par état de chaque composant, avec un contrôle d'accessibilité bloquant.
- Scénarios Gherkin (playwright-bdd) pour tout parcours qu'une personne ou un client de l'API déclenche.
Tests de bout en bout
Deux suites, lancées l'une sans l'autre :
e2e/api, en anglais : les routes de l'API, avec des phrases génériques (I send GET request to "/api/health").e2e/web, en français : les parcours comme les dirait la personne (je clique sur le bouton « Autoriser »), sur ordinateur et sur téléphone (@mobile). Chaque écran a un scénario qui finit par « la page est accessible » (axe, WCAG 2.2 AA).
make e2e-api # scénarios de l'API, appels sortants rejoués
make e2e-web # parcours du web, ordinateur et téléphone
make e2e-record # enregistre les appels sortants manquants, avec les vrais accès
make e2e-clean # supprime les enregistrements qu'aucun scénario n'utiliseChaque processus de test lance sa propre instance de Bosco, avec des données temporaires et un faux Claude Code (e2e/shared/fake-claude.mjs), remise à zéro entre deux scénarios. Les données reprennent le fil rouge des maquettes : projets api-tarifs, creneaux, maison, groupe « Club des Trois Lacs », session c41e9a07.
Les appels sortants sont rejoués depuis des enregistrements (BOSCO_REPLAY=replay, par défaut et en CI) : une requête inconnue fait échouer le test.
Compatibilité avec Claude Code
Le comportement des hooks n'est pas documenté par Claude Code. À chaque nouvelle version, make claude-compat lance de courtes sessions sur Haiku, sur l'abonnement : « Autoriser » doit laisser la commande s'exécuter, « Refuser » doit transmettre son motif à l'agent, la fin de session doit arriver, et les tours pilotés doivent marcher.
Ce site
Le site vit dans apps/docs : les pages sont des fichiers MDX dans content/docs, rangés par meta.json. make docs-dev le sert avec rechargement à chaud ; make docs-build produit l'export statique dans apps/docs/out, avec l'index de la recherche.
Les captures de apps/docs/public/screenshots se reprennent avec make docs-screenshots : le script e2e/docs/screenshots.ts lance Bosco comme les tests du web, sur des données temporaires (projets, groupes et sessions du fil rouge, faux Claude Code), puis Playwright photographie chaque écran. Tes données de ~/.local/share/bosco ne sont pas touchées.
make docs-preview sert l'export comme Cloudflare Pages le ferait (wrangler pages dev, sur http://127.0.0.1:4891). La page Télécharger lit les releases GitHub au moment du build : sans réseau, elle renvoie à la page des releases.
Publier le site
Le workflow « Docs » (.github/workflows/docs.yml) publie le site sur Cloudflare Pages, à l'adresse https://bosco.pages.dev tant qu'aucun domaine n'est rattaché :
- à chaque push sur
mainqui toucheapps/docs, le lockfile ou le workflow ; - après chaque exécution réussie du workflow « Release », pour que la page Télécharger donne la nouvelle version ;
- à la main, Actions › Docs › « Run workflow ».
Il lui faut deux secrets du dépôt, CLOUDFLARE_API_TOKEN (un jeton Cloudflare avec la permission « Account › Cloudflare Pages › Edit ») et CLOUDFLARE_ACCOUNT_ID. Le projet Pages bosco se crée au premier déploiement. Sans les secrets, le workflow s'arrête sur un avertissement, sans échec. La mise en place pas à pas est dans le README.md du dépôt, section « Documentation ».
gh secret set CLOUDFLARE_API_TOKEN --repo fpasquet/bosco
gh secret set CLOUDFLARE_ACCOUNT_ID --repo fpasquet/boscoLa variable facultative NEXT_PUBLIC_SITE_URL donne l'adresse publique du site : à régler si Cloudflare a suffixé le nom du projet (déjà pris) ou quand un domaine est rattaché. make docs-deploy publie depuis le poste, après wrangler login.
Publier une version
Une version de Bosco se publie depuis l'onglet Actions, workflow « Release », lancé à la main avec un canal (beta ou stable), une version facultative et dry_run :
- Essai à blanc (
dry_run, coché par défaut) : la version et les notes s'affichent dans le résumé de l'exécution, les fichiers restent dans ses artefacts. Rien ne part sur le dépôt. - Bêta : la bêta suivante (
0.3.0-beta.1, puis-beta.2…), publiée en pre-release. - Stable : la version tirée des commits, ou celle donnée.
La version suit les Conventional Commits de main : feat monte la version mineure, fix le correctif, avant la 1.0. Le workflow l'écrit dans les applications, régénère CHANGELOG.md (git-cliff, cliff.toml), construit le .deb, l'AppImage, leurs fichiers de mise à jour et l'APK signé, puis pousse le commit chore(release): vX.Y.Z et l'étiquette sur main et crée la release avec ses notes et SHA256SUMS. Le site est ensuite republié par le workflow « Docs ».
L'APK se signe avec la clé de release, rangée dans les secrets ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS et ANDROID_KEY_PASSWORD. Sans eux, une release s'arrête ; un essai à blanc signe avec la clé de debug.