Code et stacks

Une stack (un module) est une partie de votre code : son dossier sous codebase/, son modèle, ses langages. Vous venez à ce parcours pour déclarer un module, choisir un modèle, échafauder le code de départ, construire, lancer les tests, faire le ménage ou ramener le travail d'un worktree dans le dépôt.

Ce que vous demandez à l'agent

💬 Vous demandez à l’agent

« Quels modèles de stack existent, et que contient le modèle rust ? »

→ L’agent appelleeffortless_stack_model_list

💬 Vous demandez à l’agent

« Ajoute un module api avec le modèle node. »

→ L’agent appelleeffortless_stack_add

• id = api
• scaffold_template = node

💬 Vous demandez à l’agent

« Quelles sont les stacks déclarées dans ce projet ? »

→ L’agent appelleeffortless_stack_list

💬 Vous demandez à l’agent

« Le module api est en Rust et en TypeScript : déclare-le. »

→ L’agent appelleeffortless_stack_declare_languages

• stack_id = api
• languages = [{"id":"rust"},{"id":"typescript"}]

💬 Vous demandez à l’agent

« Quelle commande lance les tests du module api ? Et le lint ? »

→ L’agent appelleeffortless_stack_cycle

• stack_id = api
• kind = test

💬 Vous demandez à l’agent

« Construis le module desktop. »

→ L’agent appelleeffortless_stack_build

• stack_id = desktop

💬 Vous demandez à l’agent

« Montre-moi ce que le ménage ferait sur desktop, sans rien supprimer. »

→ L’agent appelleeffortless_stack_housekeeping

• stack_id = desktop
• apply = false

💬 Vous demandez à l’agent

« Combien pèsent les dossiers de build du module desktop ? Mesure-les. »

→ L’agent appelleeffortless_build_volume

• stack_id = desktop
• measure = true

💬 Vous demandez à l’agent

« Que ferait une remise à zéro des builds de desktop ? Ne lance rien. »

→ L’agent appelleeffortless_build_reset

• stack_id = desktop
• confirm = false

💬 Vous demandez à l’agent

« Passe le module desktop en débogage complet pour son propre code. »

→ L’agent appelleeffortless_build_debug

• stack_id = desktop
• project = full

💬 Vous demandez à l’agent

« Déplace le code qui traîne à la racine sous codebase/. »

→ L’agent appelleeffortless_codebase_relocate

• dry_run = false

💬 Vous demandez à l’agent

« Ramène le travail du worktree ../wt-api dans le dépôt, avec pnpm test comme barre. »

→ L’agent appelleeffortless_worktree_reintegrate

• worktree_path = ../wt-api
• bar = {"test":"pnpm test"}

Ce que fait l'agent

Choisir un modèle de stack

1. effortless_stack_model_list liste les modèles : ceux qui sont livrés avec Effortless (rust, node, python, generic, tauri, react, tauri-react, tauri-react-tailwind) et ceux du store du projet. Il fonctionne avant tout projet ; le parcours « Démarrer » s'en sert aussi.
2. effortless_stack_model_show avec model_id détaille un modèle : ses variables, sa stratégie de build et ses commandes de cycle (test, lint, run).

Déclarer un module et ses langages

1. effortless_stack_add avec id. Il déclare la stack (chemin par défaut codebase/<id>/), échafaude le dossier et applique le modèle donné par scaffold_template, avec les variables de vars. Un path hors du projet en fait un module externe : git: true si ce module a son propre dépôt, à suivre comme celui du projet (dérive, hook) ; sans git: true, ce sont des sources partagées, laissées en marge — voir Choisir son organisation.
2. Les langages sont pré-remplis par le modèle ; languages passé à l'appel les remplace. Les normes des langages déclarés sont posées dans .ai/ndd/ ; celles qui manquent sont nommées dans la réponse.
3. effortless_stack_declare_languages corrige ensuite les langages : la nouvelle déclaration remplace la précédente, elle ne fusionne pas. Une liste vide dit « aucune norme ».
4. effortless_stack_list relit les stacks déclarées.

Échafauder

1. effortless_scaffold_list liste les templates disponibles dans le store du projet.
2. effortless_scaffold_apply avec template_id et target_dir écrit les fichiers du template dans un dossier. Les fichiers déjà présents sont laissés intacts et rapportés comme ignorés. effortless_scaffold_apply_project fait la même chose à la racine du projet.
3. Pour apporter votre propre template : effortless_scaffold_format rend le schéma d'un manifeste de scaffold, puis effortless_scaffold_import avec path l'importe dans le store du projet après validation.

Construire et lancer le cycle

1. effortless_stack_build avec stack_id exécute la commande de build du modèle, depuis le dossier de la stack, et rend le statut, les artefacts et les logs.
2. effortless_stack_cycle avec stack_id et kind (test, lint ou run) rend la commande résolue. Il ne l'exécute pas : l'agent la lance ensuite.

Faire le ménage

effortless_stack_housekeeping constate ce que la politique d'entretien déclarée dans languages[].housekeeping purgerait : quoi, quelle taille, pour quel langage. Sans apply, il ne supprime rien. L'agent ne passe apply: true qu'après votre accord. stack_id limite le constat à une stack.

Mesurer et alléger les builds

effortless_build_volume mesure, module par module, ce que pèsent les dossiers de build : ceux que déclare la stack et ceux que l'outil de build a marqués (CACHEDIR.TAG), sans compter deux fois le même octet. Sans measure, il rend la dernière mesure et sa date. Quand un module dépasse le seuil du projet (settings.build_volume.threshold, 10 Go par défaut), l'écran de reprise le signale.

effortless_build_reset remet à zéro les builds d'un module en lançant la commande que déclare son langage (par exemple cargo clean). Il commence toujours par une simulation : commande, dossiers, taille. L'agent ne passe confirm: true qu'après votre accord ; la compilation suivante sera complète.

effortless_build_debug lit ou règle le niveau d'informations de débogage des builds de dev — none, lines ou full — pour le code du module (project) et, si le langage le permet, pour ses dépendances. Le niveau devient des variables d'environnement posées sur les commandes qu'Effortless lance : vos fichiers ne sont jamais réécrits. Pour Rust, seul le code du module se règle ; les dépendances restent sans débogage, comme le pose le modèle.

Déplacer le code sous codebase/

effortless_codebase_relocate déplace le code resté à la racine vers codebase/<stack>/ (stack default sans stack_id). Il commence par un aperçu (dry_run vaut true par défaut) ; l'agent l'exécute réellement (dry_run: false) après votre accord. En mode Semi-auto, il est désactivé et le dit.

Réintégrer un worktree

effortless_worktree_reintegrate avec worktree_path (ou worktree_paths pour un projet à plusieurs dépôts) et bar, la barre de contrôle : un objet qui associe test, lint, typecheck ou build à une commande. Le verbe valide d'abord les fichiers en attente du worktree dans un commit, mesure la barre dans le worktree, et ne fusionne que si tout est vert. Après une fusion réussie, le worktree et sa branche sont retirés, sauf avec keep_worktree: true. Le verbe ne crée jamais de worktree.

Ce que vous obtenez

• Des modules déclarés dans effortless.json, des dossiers sous codebase/<id>/, des normes de langage dans .ai/ndd/.
• L'écran Modules montre chaque stack : langages, modèle, normes, version, livraison. Il se lit seulement ; les stacks se déclarent par l'agent ou à la création du workspace.
• Pour un worktree réintégré : le travail est fusionné dans le dépôt, ou rien n'a changé.

Quand l'agent est refusé

Situation	Ce que dit le refus	Ce qu'il faut faire
Stack inconnue (déclaration des langages, ménage)	stack:unknown	Lister les stacks avec effortless_stack_list.
Stack inconnue (build, cycle)	stacks:stackNotFound	Même geste : effortless_stack_list.
Id de stack déjà pris, ou vide	« stack id already exists » / « stack id required »	Choisir un autre id.
Langages mal formés	stack:languagesMalformed (les entrées fautives sont nommées)	Chaque langage est un objet { id, version, ndd }.
Source de norme ni embedded ni git	stack:nddSourceRefused	Déclarer la source en embedded ou git.
Stack sans modèle, pour un build	« la stack n'a pas de modèle (scaffold_template) »	Déclarer la stack avec un modèle.
Cycle demandé inconnu	stacks:cycleInvalid	kind vaut test, lint ou run.
Template introuvable	create:templateNotFound	Lister les templates avec effortless_scaffold_list.
Manifeste importé invalide	« invalid manifest » avec la liste des erreurs	Corriger le manifeste d'après effortless_scaffold_format.
Modèle importé qui déclare une commande à exécuter	create:anchorUntrusted	Retirer la clé anchor du manifeste, ou prendre un modèle livré (effortless_stack_model_list).
Dossier à réintégrer qui n'est pas un worktree git	worktree:notAWorktree	Créer d'abord le worktree : le verbe n'en crée jamais.
Worktree sans branche	worktree:detachedHead	Replacer le worktree sur une branche.
Aucun worktree donné	worktree:noWorktree	Passer worktree_path, ou worktree_paths.
La barre rougit	worktree:barRed (les commandes en échec sont nommées)	Corriger dans le worktree, puis relancer ; rien n'a été réintégré.
Lien symbolique non suivi dans le worktree	worktree:untrackedSymlink	Ignorer le lien dans .gitignore (motif sans barre oblique finale) ou le retirer.
Conflit à la fusion	worktree:mergeConflict (fichiers nommés)	Résoudre le conflit dans le worktree et relancer ; la fusion a été annulée.
Fusion partielle sur plusieurs dépôts	worktree:partialMerge	Corriger la cause, puis relancer sur le seul worktree en échec.