cookiecode/README.md

# CookieCode

CookieCode est une microlibrairie JavaScript educative pour apprendre les bases de l'algorithmique avec des recettes de cuisine.

L'idee :

| Cuisine | Programmation |
| --- | --- |
| Recette | Programme |
| Ingredients | Variables |
| Materiel | Constantes / ressources |
| Etapes | Instructions |
| Actions culinaires | Fonctions |
| `si` | Condition |
| `repeter` | Boucle |

## Objectif du MVP

- fonctionner directement dans une page HTML via une balise `<script>` ;
- exposer une variable globale `CookieCode` ;
- proposer une API chainable proche du langage naturel ;
- afficher une trace de recette et une lecture algorithmique ;
- rester sans dependance.

## Utilisation dans une page

```html
<div id="app"></div>
<script src="dist/cookiecode.js"></script>
<script>
  CookieCode.configurer({
    sortie: "#app",
    afficherNotions: true
  });

  CookieCode.recette("Cookie au chocolat")
    .prendre("farine", 200, "g")
    .prendre("sucre", 100, "g")
    .prendre("chocolat", 150, "g")
    .utiliser("saladier")
    .ajouter("farine")
    .ajouter("sucre")
    .ajouter("chocolat")
    .melanger()
    .repeter(2, function (recette) {
      recette.melanger();
    })
    .cuire(12, "minutes")
    .servir();
</script>
```

## API principale

### Creation

```js
CookieCode.recette("Cookies");
CookieCode.ingredient("farine", 200, "g");
CookieCode.materiel("saladier");
CookieCode.constante("temperature", 180);
CookieCode.preparation("pate");
CookieCode.defi("Cookie avec boucle", { ingredientsMinimum: 3 });
```

### Methodes d'une recette

```js
.prendre(nom, quantite, unite)
.utiliser(materiel)
.ajouter(element, quantite, unite)
.retirer(element)
.couper(element, forme)
.melanger()
.verser(contenu, contenant)
.chauffer(element, temperature)
.cuire(duree, unite)
.attendre(duree, unite)
.repeter(nombre, action)
.si(condition, action, sinonAction)
.servir(element)
.afficher()
.toText()
.toHTML()
.analyser()
```

## Exemple avec variables

```js
const farine = CookieCode.ingredient("farine", 200, "g");
const sucre = CookieCode.ingredient("sucre", 100, "g");
const saladier = CookieCode.materiel("saladier");

const recette = CookieCode.recette("Cookies")
  .utiliser(saladier)
  .ajouter(farine)
  .ajouter(sucre)
  .melanger();

console.log(recette.toText());
```

## Exemple avec boucle et condition

```js
const pate = CookieCode.preparation("pate").definir("texture", "trop seche");

CookieCode.recette("Pate a cookies")
  .ajouter("farine", 200, "g")
  .si(function () {
    return pate.est("trop seche");
  }, function (recette) {
    recette.ajouter("lait", 20, "ml");
  })
  .repeter(3, function (recette) {
    recette.melanger();
  })
  .servir();
```

## Feedback ludique

CookieCode peut analyser une recette et verifier si elle respecte un defi.

```js
const recette = CookieCode.recette("Cookie")
  .prendre("farine", 200, "g")
  .prendre("sucre", 100, "g")
  .prendre("chocolat", 150, "g")
  .ajouter("farine")
  .ajouter("sucre")
  .ajouter("chocolat")
  .melanger()
  .repeter(2, function (recette) {
    recette.melanger();
  })
  .cuire(12, "minutes")
  .servir();

const defi = CookieCode.defi("Cookie avec boucle", {
  ingredientsMinimum: 3,
  actionsObligatoires: ["melanger", "cuire", "servir"],
  boucleObligatoire: true,
  terminerParServir: true,
  interdireErreurs: true
});

const verification = CookieCode.verifier(recette, defi);
console.log(verification.toText());
```

Sortie possible :

```txt
Defi : Cookie avec boucle
Resultat : reussi
✅ Tu as utilise 3 ingredient(s).
✅ Action trouvee : melanger.
✅ Action trouvee : cuire.
✅ Action trouvee : servir.
✅ Tu as utilise une boucle avec repeter.
✅ Ta recette se termine par servir.
✅ Aucune erreur logique detectee.
```

Une recette peut aussi etre analysee directement :

```js
const rapport = recette.analyser();

console.log(rapport.ingredients);
console.log(rapport.actions);
console.log(rapport.utiliseBoucle);
console.log(rapport.erreurs);
```

## Atelier avec cartes

CookieCode est pense pour etre utilise avec des cartes physiques ou numeriques avant de passer au code.

Parcours conseille :

```txt
Cartes -> Recette orale -> Code CookieCode -> Feedback -> Badge ou defi bonus
```

Exemple de cartes :

```txt
[RECETTE] [Cookie]
[PRENDRE] [farine] [200] [g]
[AJOUTER] [farine]
[MELANGER]
[REPETER] [2 fois] [MELANGER]
[CUIRE] [12] [minutes]
[SERVIR]
```

Traduction CookieCode :

```js
CookieCode.recette("Cookie")
  .prendre("farine", 200, "g")
  .ajouter("farine")
  .melanger()
  .repeter(2, function (recette) {
    recette.melanger();
  })
  .cuire(12, "minutes")
  .servir();
```

Le feedback doit donner une satisfaction immediate : valoriser les criteres reussis, expliquer simplement ce qui manque, puis proposer une action concrete.

Exemple :

```txt
🎉 Defi reussi : Chef Cookie peut suivre ta recette.
🔁 Super, tu as simplifie une repetition avec une boucle.
🥣 Tu as cree tes premieres variables avec les ingredients.
```

Guide complet : [docs/atelier-cartes.md](docs/atelier-cartes.md)

### Cartes pedagogiques conseillees

| Type de carte | Mots cles | Notion |
| --- | --- | --- |
| Structure | `recette`, `servir` | programme / resultat |
| Donnee | `ingredient`, `quantite`, `unite` | variable / valeur |
| Materiel | `materiel`, `utiliser` | constante / ressource |
| Action | `prendre`, `ajouter`, `couper`, `melanger`, `cuire` | fonction |
| Logique | `si`, `sinon`, `repeter` | condition / boucle |
| Objectif | `defi`, `badge`, `bonus` | motivation / feedback |

## Developpement

```sh
npm test
npm run build
```

Aucune dependance n'est necessaire pour lancer les tests du MVP.