@mostajs/course-builder 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @mostajs/course-builder
+## [0.1.0] — 2026-06-18
+### Added
+- Domaine éditeur (extraction iquesta) : arbre Formation/Activity (10 kinds), dépendances DAG + détection de cycle (DFS), validation par kind, snapshots versionnés + intégrité sha256 (compose @mostajs/security).
+- DÉCOUPLÉ du média (mediaRef FK opaque) — intégration média documentée (composition) dans docs/12-DOC-MEDIA-INTEGRATION.md. 6 tests + exemple §12.

package/README.md

@@ -0,0 +1,13 @@
+# @mostajs/course-builder
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (6 tests verts)
+> Éditeur de formation (domaine headless) : arbre, **dépendances DAG + détection de cycle**, validation par kind, **snapshots versionnés**.
+> **Découplé du média** (`mediaRef` FK opaque) — intégration média = composition (`docs/12-DOC-MEDIA-INTEGRATION.md`).
+```js
+import { createCourseBuilder, createMemoryRepositories } from '@mostajs/course-builder';
+const cb = createCourseBuilder({ repositories: createMemoryRepositories(), hasher });
+const f = await cb.formations.create({ title:'Anglais A1' });
+const v = await cb.activities.add(f.id, { kind:'video', title:'Hello', mediaRef:'MEDIA-ID' });  // FK opaque → @mostajs/media
+await cb.deps.add(f.id, quizId, v.id);   // throw CycleDetected si cycle
+const snap = await cb.snapshots.create(f.id, { label:'v1.0' });
+```
+Lancer : `node test-scripts/unit/course-builder.test.mjs && node examples/cours/run.mjs`

package/docs/00-PROPOSITION-PLAN-COURSE-BUILDER-18062026.md

@@ -0,0 +1,16 @@
+# @mostajs/course-builder — DEVRULES de bout en bout (§4 + #3 + #4 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C (P1+P2), extraction iquesta.
+**Décision d'ordonnancement (validée)** : **EXTRAIRE + TESTER le domaine d'abord, intégrer le média ENSUITE** (composition).
+Justification : `Activity.mediaRef` est une **FK opaque** → le domaine (arbre, dépendances DAG, validation, snapshots) est
+**découplé** du média ; `@mostajs/media`+`media-server`+`storage` sont **déjà publiés** (composables) ; le domaine est
+**testable headless**, l'UI média (recorder/editor) est navigateur (intégrée après, cf. `12-DOC-MEDIA-INTEGRATION.md`).
+## §4 (règle d'or)
+Le **modèle de formation** (Formation/Activity/Dependency/Snapshot) n'existe nulle part en module ; `training`=catalogue/sessions
+(≠ structure de contenu) ; `elearning`=progression apprenant. → cas C : l'ÉDITEUR/structure de cours. Média/quiz/contenu **délégués** par FK.
+## §3 (périmètre/API)
+**Entités** : Formation, Activity(10 kinds), ActivityDependency(DAG), FormationSnapshot(versioning).
+**API** : `createCourseBuilder({repositories,hasher?})` → `formations.{create,get,list,publish}`, `activities.{add,update,remove,list,tree}`,
+`deps.{add(cycle-safe),list,wouldCycle}`, `validate(formationId)`, `snapshots.{create,list,verify}`.
+**Algos extraits** : détection de cycle (DFS), validation par kind, snapshot bundle+sha256 (compose @mostajs/security).
+**Compose (§10)** : security (sha256 snapshot) ; **délègue** média→@mostajs/media (mediaRef), quiz→@mostajs/questa (quizRef), contenu→storage. **Jalons** : 0.1 domaine+algos · 0.2 intégration média (composition) · 0.3 éditeur React (UI) · 1.0 14 livrables.
+## §4 (tests) : arbre, validation kind, cycle, snapshot+intégrité, mediaRef opaque. (6 verts)

package/docs/12-DOC-MEDIA-INTEGRATION.md

@@ -0,0 +1,37 @@
+# 12 — Intégration MÉDIA dans @mostajs/course-builder (composition)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18
+**Source** : généralisé de `SolutionCh/iquesta/docs/MEDIA-INTEGRATION-COURSE-BUILDER.md` + `PLAN-MEDIA-STORAGE-COURSE-BUILDER-16052026.md`.
+**Principe** : le média n'est PAS dans course-builder. `Activity.mediaRef` est une **FK opaque** vers une row `Media` de
+**@mostajs/media** (qui délègue les octets à **@mostajs/storage**). L'intégration = un **slot UI** + une **route d'upload** ;
+aucune dépendance média dans le cœur (qui reste headless/DB-agnostique).
+
+## Flux (auteur enregistre une vidéo de cours)
+```
+<PropsPanel kind='video'> → <CourseBuilderMediaSlot>            (UI, navigateur)
+   ├─ <MediaPicker filter={mimePrefix}>  → onSelect(media.id)   (média existant)
+   └─ <MultiTakeRecorder> → <VideoEditor> → export blob
+        → POST /api/admin/media/recordings   (multipart)
+              ↳ @mostajs/media écrit la row Media + délègue bytes à @mostajs/storage
+                 (bucket 'media-recordings', sha256=checksum storage, signed URL)
+              ↳ { mediaId, signedUrl }
+   → courseBuilder.activities.update(activityId, { mediaRef: mediaId })   ← SEUL contact avec le cœur
+```
+
+## Étapes (M1–M5, généralisées)
+| # | Étape | Côté |
+|---|---|---|
+| M1 | deps `@mostajs/media` (+ `media-server`) + `@mostajs/storage` (déjà publiés/éprouvés) | app |
+| M2 | bucket `media-recordings` (+ `media-thumbnails`) provisionné (storage) | infra/.env |
+| M3 | route `POST /api/admin/media/recordings` (upload) + `GET /api/admin/media/[id]` | app (compose media+storage) |
+| M4 | `<CourseBuilderMediaSlot>` : `<MediaPicker>` + `<MultiTakeRecorder>` + `<VideoEditor>` → `update({mediaRef})` | app (compose @mostajs/media) |
+| M5 | *(stretch)* kind `live` → `liveRef` (SFU/WHIP via media-stack) | app |
+
+## Contrat avec le cœur (course-builder)
+- `activities.add/update(... , { mediaRef })` : le cœur **stocke et valide** seulement la présence de `mediaRef`
+  (cf. `validateActivity` : `video`/`audio` ⇒ `mediaRef` requis). Il **n'ouvre jamais** la caméra, ne lit jamais les octets.
+- `quizRef` → @mostajs/questa (projet quiz) ; `contentMarkdown`/`externalUrl` → reading/external ; `liveRef` → live.
+- **Conséquence** : le cœur reste testable sans navigateur ; l'intégration média se teste côté app (E2E navigateur).
+
+## Pourquoi ce découplage (rappel DEVRULES §10)
+Média = capacité lourde (caméra/WebRTC/transcodage) **déjà modularisée** (@mostajs/media). Le course-builder la **compose
+par référence** (mediaRef), il ne la **réimplémente ni ne l'embarque**. Idem sha256 (storage/security), quiz (questa).

package/examples/cours/run.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { createCourseBuilder, createMemoryRepositories } from '../../src/index.js';
+import { sha256 } from '../../../mosta-security/src/index.js';
+const cb=createCourseBuilder({ repositories:createMemoryRepositories(), hasher:sha256 });
+const f=await cb.formations.create({ title:'Anglais A1', slug:'eng-a1' });
+const m1=await cb.activities.add(f.id,{ kind:'module', title:'Salutations', order:1 });
+const l1=await cb.activities.add(f.id,{ kind:'video', title:'Vidéo: Hello', parentId:m1.id, order:1, mediaRef:'MEDIA-OPAQUE-1' });
+const l2=await cb.activities.add(f.id,{ kind:'quiz', title:'Quiz salutations', parentId:m1.id, order:2, quizRef:'QUESTA-PROJ-1' });
+await cb.deps.add(f.id, l2.id, l1.id);   // le quiz dépend de la vidéo
+const v=await cb.validate(f.id); assert.equal(v.ok,true);
+const snap=await cb.snapshots.create(f.id,{ label:'v1.0' });
+const tree=await cb.activities.tree(f.id);
+console.log('✅ course-builder — « %s » : %d module(s), snapshot %s (intègre? %s) · média=FK opaque (%s), quiz→questa (%s)',
+  f.title, tree.length, snap.label, await cb.snapshots.verify(snap.id), l1.mediaRef, l2.quizRef);

package/llms.txt

@@ -0,0 +1,16 @@
+# @mostajs/course-builder — fiche LLM
+RÔLE
+  Éditeur de formation (domaine headless) : arbre Formation/Activity (10 kinds), dépendances DAG + détection de cycle,
+  validation par kind, snapshots versionnés. DÉCOUPLÉ du média (mediaRef opaque). Extraction iquesta. DB-agnostique.
+  Compose (injectés) : security (sha256 snapshot). Délègue : média→@mostajs/media (mediaRef), quiz→@mostajs/questa (quizRef), contenu→storage.
+EXPORTS
+  createCourseBuilder({ repositories, hasher?, now? }) -> { formations, activities, deps, validate, snapshots }
+  validateActivity(a) ; ACTIVITY_KINDS ; createMemoryRepositories(); Formation/Activity/ActivityDependency/FormationSnapshotSchema
+API
+  formations.create/get/list/publish ; activities.add/update/remove/list/tree(formationId)
+  deps.add(formationId,fromId,toId)[throw CycleDetected]/list/wouldCycle ; validate(formationId)->{ok,issues}
+  snapshots.create(formationId,{label})/list/get/verify(id)
+KINDS: module|lesson|video|audio|reading|quiz|submission|live|external|certificate
+PIÈGES
+  - mediaRef/quizRef/liveRef = FK OPAQUES (média = composition @mostajs/media, cf. docs/12-DOC-MEDIA-INTEGRATION.md). Ne pas embarquer la caméra.
+  - deps.add refuse tout cycle (DFS). snapshot.verify recalcule sha256 (compose @mostajs/security). validation : video/audio⇒mediaRef, quiz⇒quizRef.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/course-builder",
+  "version": "0.1.0",
+  "description": "Éditeur de formation (domaine headless) : arbre Formation/Activity (10 kinds), dépendances DAG + détection de cycle, validation par kind, snapshots versionnés. DÉCOUPLÉ du média (mediaRef opaque). Extraction iquesta.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schemas": "./src/schemas.js"
+  },
+  "keywords": [
+    "mostajs",
+    "course-builder",
+    "formation",
+    "lms",
+    "dag",
+    "snapshot"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/course-builder.test.mjs",
+    "example": "node examples/cours/run.mjs"
+  }
+}

package/src/course-builder.js

@@ -0,0 +1,94 @@
+// @mostajs/course-builder — domaine éditeur de formation (headless). Author: Dr Hamid MADANI <drmdh@msn.com>
+// EXTRACTION du modèle/algos iquesta (Formation/Activity/Dependency/Snapshot). DÉCOUPLÉ du média :
+//   Activity.mediaRef / quizRef / liveRef sont des FK OPAQUES (média = composition @mostajs/media, cf. doc 12-DOC-MEDIA).
+// Compose (injectés) : hasher (snapshot sha256 — @mostajs/security). Délègue média→media, quiz→questa, contenu→storage.
+
+export const ACTIVITY_KINDS = ['module', 'lesson', 'video', 'audio', 'reading', 'quiz', 'submission', 'live', 'external', 'certificate'];
+
+const simpleHash = (s) => { let h = 0; const t = String(s); for (let i = 0; i < t.length; i++) h = (h * 31 + t.charCodeAt(i)) | 0; return 'h' + (h >>> 0).toString(16); };
+
+/** Validation par kind (mediaRef pour video/audio, quizRef pour quiz, etc.). */
+export function validateActivity(a) {
+  const errs = [];
+  if (!a.title) errs.push('title requis');
+  if (!ACTIVITY_KINDS.includes(a.kind)) errs.push(`kind invalide: ${a.kind}`);
+  if (['video', 'audio'].includes(a.kind) && !a.mediaRef) errs.push(`mediaRef requis (${a.kind})`);
+  if (a.kind === 'quiz' && !a.quizRef) errs.push('quizRef requis (quiz → @mostajs/questa)');
+  if (a.kind === 'reading' && !a.contentMarkdown) errs.push('contentMarkdown requis (reading)');
+  if (a.kind === 'external' && !a.externalUrl) errs.push('externalUrl requis (external)');
+  return errs;
+}
+
+export function createCourseBuilder({ repositories, hasher, now = () => new Date() } = {}) {
+  if (!repositories?.formations) throw new Error('createCourseBuilder: repositories requis');
+  const { formations, activities, dependencies, snapshots } = repositories;
+  const hash = (s) => (hasher ? hasher(s) : simpleHash(s));
+
+  // détection de cycle (DFS) sur le graphe de dépendances + l'arête candidate from→to
+  async function wouldCycle(formationId, fromId, toId) {
+    if (fromId === toId) return true;
+    const deps = await dependencies.find((d) => d.formationId === formationId);
+    const adj = {}; for (const d of deps) (adj[d.fromId] ||= []).push(d.toId);
+    (adj[fromId] ||= []).push(toId);
+    const color = {}; const nodes = new Set();
+    for (const k of Object.keys(adj)) { nodes.add(k); for (const v of adj[k]) nodes.add(v); }
+    const dfs = (u) => { color[u] = 1; for (const v of (adj[u] || [])) { if (color[v] === 1) return true; if (!color[v] && dfs(v)) return true; } color[u] = 2; return false; };
+    for (const n of nodes) if (!color[n] && dfs(n)) return true;
+    return false;
+  }
+
+  const api = {
+    formations: {
+      create: (dto) => formations.create({ status: 'draft', version: 'v1.0', ...dto }),
+      get: (id) => formations.findById(id),
+      list: (f = {}) => formations.find((x) => Object.entries(f).every(([k, v]) => x[k] === v)),
+      publish: (id) => formations.update(id, { status: 'published', publishedAt: now() }),
+    },
+    activities: {
+      add: (formationId, dto) => activities.create({ formationId, kind: 'lesson', order: 0, ...dto }),
+      update: (id, patch) => activities.update(id, patch),
+      remove: (id) => activities.remove ? activities.remove(id) : activities.update(id, { _deleted: true }),
+      list: (formationId) => activities.find((a) => a.formationId === formationId && !a._deleted).then((x) => x.sort((p, q) => (p.order || 0) - (q.order || 0))),
+      /** Arbre imbriqué par parentId. */
+      async tree(formationId) {
+        const flat = await api.activities.list(formationId);
+        const byParent = {}; for (const a of flat) (byParent[a.parentId || null] ||= []).push(a);
+        const build = (pid) => (byParent[pid] || []).map((a) => ({ ...a, children: build(a.id) }));
+        return build(null);
+      },
+    },
+    deps: {
+      /** Ajoute une dépendance from→to (from requiert to). Refuse si cycle. */
+      async add(formationId, fromId, toId) {
+        if (await wouldCycle(formationId, fromId, toId)) throw new Error('CycleDetected: dépendance créerait un cycle');
+        return dependencies.create({ formationId, fromId, toId });
+      },
+      list: (formationId) => dependencies.find((d) => d.formationId === formationId),
+      wouldCycle: (formationId, fromId, toId) => wouldCycle(formationId, fromId, toId),
+    },
+    /** Validation globale (issues par activité). */
+    async validate(formationId) {
+      const acts = await api.activities.list(formationId);
+      const issues = [];
+      for (const a of acts) { const e = validateActivity(a); if (e.length) issues.push({ activityId: a.id, code: a.code || a.title, errors: e }); }
+      return { ok: issues.length === 0, issues };
+    },
+    snapshots: {
+      /** Snapshot versionné (bundle JSON + sha256 via @mostajs/security injecté). */
+      async create(formationId, { label } = {}) {
+        const formation = await formations.findById(formationId);
+        const acts = await api.activities.list(formationId);
+        const deps = await api.deps.list(formationId);
+        const bundle = { formation, activities: acts, dependencies: deps, at: now() };
+        const bundleJson = JSON.stringify(bundle);
+        return snapshots.create({ formationId, label: label || formation?.version, bundleJson, sha256: hash(bundleJson), at: now() });
+      },
+      list: (formationId) => snapshots.find((s) => s.formationId === formationId),
+      get: (id) => snapshots.findById(id),
+      /** Intégrité : recalcule le hash. */
+      async verify(id) { const s = await snapshots.findById(id); return !!s && s.sha256 === hash(s.bundleJson); },
+    },
+    repositories,
+  };
+  return api;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/course-builder — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createCourseBuilder, validateActivity, ACTIVITY_KINDS } from './course-builder.js';
+export { createMemoryRepositories } from './memory-repo.js';
+export { FormationSchema, ActivitySchema, ActivityDependencySchema, FormationSnapshotSchema } from './schemas.js';

package/src/memory-repo.js

@@ -0,0 +1,7 @@
+function coll(){ const m=new Map(); return {
+  async create(d){ const id=d.id||globalThis.crypto.randomUUID(); const now=new Date(); const r={id,createdAt:now,updatedAt:now,...d}; m.set(id,r); return {...r}; },
+  async findById(id){ const r=m.get(id); return r?{...r}:null; },
+  async update(id,p){ const r=m.get(id); if(!r)return null; const x={...r,...p,updatedAt:new Date()}; m.set(id,x); return {...x}; },
+  async remove(id){ return m.delete(id); },
+  async find(f=()=>true){ return [...m.values()].filter(f).map(r=>({...r})); } }; }
+export function createMemoryRepositories(){ return { formations:coll(), activities:coll(), dependencies:coll(), snapshots:coll() }; }

package/src/schemas.js

@@ -0,0 +1,13 @@
+// @mostajs/course-builder — schémas (EntitySchema @mostajs/orm). Author: Dr Hamid MADANI <drmdh@msn.com>
+export const FormationSchema = { name:'Formation', collection:'formations', timestamps:true, fields:{
+  title:{type:'string',required:true}, slug:{type:'string'}, version:{type:'string',default:'v1.0'},
+  status:{type:'string',enum:['draft','published'],default:'draft'}, publishedAt:{type:'date'} } };
+export const ActivitySchema = { name:'Activity', collection:'activities', timestamps:true, fields:{
+  formationId:{type:'string',required:true}, parentId:{type:'string',default:null}, code:{type:'string'},
+  title:{type:'string',required:true}, kind:{type:'string',required:true}, order:{type:'number',default:0},
+  mediaRef:{type:'string',default:null}, quizRef:{type:'string',default:null}, liveRef:{type:'string',default:null},
+  contentMarkdown:{type:'string'}, externalUrl:{type:'string'} }, indexes:[{fields:{formationId:'asc'}}] };
+export const ActivityDependencySchema = { name:'ActivityDependency', collection:'activity_dependencies', timestamps:true, fields:{
+  formationId:{type:'string',required:true}, fromId:{type:'string',required:true}, toId:{type:'string',required:true} }, indexes:[{fields:{formationId:'asc'}}] };
+export const FormationSnapshotSchema = { name:'FormationSnapshot', collection:'formation_snapshots', timestamps:true, fields:{
+  formationId:{type:'string',required:true}, label:{type:'string'}, bundleJson:{type:'text'}, sha256:{type:'string'}, at:{type:'date'} }, indexes:[{fields:{formationId:'asc'}}] };

package/test-scripts/unit/course-builder.test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import { createCourseBuilder, createMemoryRepositories, validateActivity } from '../../src/index.js';
+import { sha256 } from '../../../mosta-security/src/index.js';   // snapshot sha256 = @mostajs/security
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const mk=(o={})=>createCourseBuilder({ repositories:createMemoryRepositories(), hasher:sha256, ...o });
+
+await test('formation + arbre (module→leçon→activité)', async()=>{
+  const cb=mk(); const f=await cb.formations.create({title:'Anglais A1'});
+  const mod=await cb.activities.add(f.id,{kind:'module',title:'Module 1',order:1});
+  await cb.activities.add(f.id,{kind:'lesson',title:'Leçon 1',parentId:mod.id,order:1});
+  const tree=await cb.activities.tree(f.id);
+  assert.equal(tree.length,1); assert.equal(tree[0].children.length,1);
+});
+await test('validation par kind (mediaRef/quizRef/...)', ()=>{
+  assert.deepEqual(validateActivity({title:'V',kind:'video'}).filter(e=>/mediaRef/.test(e)).length,1);
+  assert.equal(validateActivity({title:'V',kind:'video',mediaRef:'m1'}).length,0);
+  assert.equal(validateActivity({title:'Q',kind:'quiz',quizRef:'qz1'}).length,0);
+});
+await test('validate(formation) remonte les issues', async()=>{
+  const cb=mk(); const f=await cb.formations.create({title:'F'});
+  await cb.activities.add(f.id,{kind:'video',title:'Sans média'});   // mediaRef manquant
+  const v=await cb.validate(f.id); assert.equal(v.ok,false); assert.match(v.issues[0].errors[0],/mediaRef/);
+});
+await test('dépendances DAG + DÉTECTION DE CYCLE', async()=>{
+  const cb=mk(); const f=await cb.formations.create({title:'F'});
+  const a=await cb.activities.add(f.id,{kind:'lesson',title:'A'});
+  const b=await cb.activities.add(f.id,{kind:'lesson',title:'B'});
+  const c=await cb.activities.add(f.id,{kind:'lesson',title:'C'});
+  await cb.deps.add(f.id,a.id,b.id);   // A→B
+  await cb.deps.add(f.id,b.id,c.id);   // B→C
+  await assert.rejects(()=>cb.deps.add(f.id,c.id,a.id),/CycleDetected/);  // C→A créerait A→B→C→A
+  assert.equal(await cb.deps.wouldCycle(f.id,a.id,a.id),true);            // auto-dépendance
+});
+await test('snapshot versionné + intégrité (sha256 via security)', async()=>{
+  const cb=mk(); const f=await cb.formations.create({title:'F'}); await cb.activities.add(f.id,{kind:'lesson',title:'L'});
+  const s=await cb.snapshots.create(f.id,{label:'v1.0'});
+  assert.ok(s.sha256.startsWith('sha256:')); assert.equal(await cb.snapshots.verify(s.id),true);
+  await cb.repositories.snapshots.update(s.id,{bundleJson:'{falsifié}'});
+  assert.equal(await cb.snapshots.verify(s.id),false);   // altération détectée
+});
+await test('mediaRef OPAQUE (découplage média)', async()=>{
+  const cb=mk(); const f=await cb.formations.create({title:'F'});
+  const v=await cb.activities.add(f.id,{kind:'video',title:'Cours vidéo',mediaRef:'media-id-123'});
+  assert.equal(v.mediaRef,'media-id-123');   // course-builder ne touche pas au média, juste la FK
+});
+console.log(`\n✅ @mostajs/course-builder — ${pass} tests OK`);