Avancement

22 — Alpha publique : la première version de Récit sur npm

Statut : proposé · Phase : P5 · Mis à jour : 02/11/2026.

Ce plan détaille la phase P5 de 06 · Feuille de route : publier pour la première fois les packages de Récit, en 0.1.0-alpha.0, avec npm create recit pour démarrer un projet. Il part de l'état réel du dépôt au 02/11/2026 (§1), dit ce que l'alpha promet et ne promet pas (§2), propose les décisions qui manquent (§3), découpe le travail en lots exécutables par des agents (§5) et finit sur les questions que seul l'utilisateur peut trancher (§8).

Contrainte dure, rappelée. Aucune publication npm n'a lieu sans le feu vert explicite de l'utilisateur, donné dans un message, pour cette publication-là. Les agents préparent, vérifient et s'arrêtent au dry run (lot AL9) ; la publication (AL10) est faite par l'utilisateur ou sur son ordre. Tant que Récit est en 0.x, les version plans n'utilisent que preminor (première release d'une phase) et prerelease (les suivantes), un seul bump par plan ; pnpm check refuse patch, minor et major.

0. Pourquoi maintenant

• Le socle est fini. P0 à P4 sont faits, ainsi que le plan 19 (Mantine et modules CSS, 19 · Style) et le plan 21 (stories, play, couverture, 21 · Tests). Les 7 sites (www, docs, presentation, components, motion, plans, vision) sont déployés sur Vercel par scripts/vercel.js (voir VERCEL.md).
• Rien n'est encore utilisable hors du dépôt. La page Quickstart de docs.recit.dev dit « Not on npm yet » et renvoie à un git clone. Tant qu'il n'y a pas de package, il n'y a pas d'utilisateur, donc pas de retour sur la syntaxe, le modèle Story ni la CLI.
• Les formats suivants (P6 à P11) gagnent à partir d'une base publiée. Chaque phase ouvrira une préversion 0.N.0-alpha.0 ; il faut que la mécanique ait servi une première fois sur deck et motion, deux formats déjà complets.
• Le premier contrat se fixe à la première publication. Ce qui part sur npm (noms d'exports, alias, schémas) devient quelque chose que quelqu'un peut utiliser. C'est le moment de retirer ce qui ne doit pas durer (§3, D6).

1. État réel au 02/11/2026

Vérifié dans le code, pas dans les plans.

1.1 Ce qui est déjà en place

1.2 Ce qui manque ou casse

2. Ce que l'alpha promet, et ce qu'elle ne promet pas

Elle promet :

• npm create recit crée un projet qui marche du premier coup : un deck (slides.md), un film (story.md) et, si D2 est accepté, un site de documentation (gabarit docs).
• npx recit init | dev | build | export | validate | convert | render | dur | schema | mcp serve fonctionnent depuis npm, sur Node 22.22 ou plus. Le test de fumée (D5) tourne sur Linux ; macOS et Windows ne sont pas vérifiés par la CI avant la 1.0.
• Chaque story Markdown a son jumeau JSON validé par @recit/core/schema, dans les deux sens.
• Une seule version pour tous les packages, un seul CHANGELOG.md, sous le dist-tag next.

Elle ne promet pas :

• La stabilité de l'API : en 0.x, une préversion suivante peut casser un export, une clé de recit.config.ts ou un attribut de scène. Le changelog le dit. La stabilité est l'objet de la 1.0 (29 · 1.0).
• Les formats à venir (report, toon, book, roadmap, calendar, stories) : leurs packages restent privés jusqu'à leur phase.
• Le mobile (APP7, APP8 de 18 · Applications) ni play.recit.dev.
• Le dist-tag latest : rien ne part en latest avant la 1.0.

3. Décisions proposées

4. Ce qui reste, case par case

Les cases de P5 dans 06 · Feuille de route, mises en face des lots.

5. Lots

Règles de 20 · Multi-agents §3 : un lot, un agent, ses fichiers ; relire avant d'écrire ; jamais de git (ni add, ni commit, ni stash) ; une note ### ALn — <titre> — <date> dans le journal ; BROWSER=none pour tout serveur local. nx.json, AGENTS.md, SETUP.md et CONTRIBUTING.md appartiennent au coordinateur : un lot qui en a besoin lui demande la ligne. Chaque lot qui touche un package publié ajoute un version plan prerelease (un preminor existe déjà : la phase est ouverte).

AL0 — Les réponses de l'utilisateur (jalon humain)

Questions 1 à 6 du §8. Rien ne bloque AL1, AL2 et AL5 ; AL3 attend la question 2, AL6 la question 1, AL8 la question 5.

AL1 — Une seule liste des packages publiés (S), vague 1

Fichiers : scripts/publint-all.mjs, scripts/__tests__/published-packages.spec.ts, la note de journal.

• 1.1 — Une fonction partagée lit les globs de pnpm-workspace.yaml et rend { nom → dossier } ; DIRS et RELEASED disparaissent, la liste vient de release.projects.
• 1.2 — Un nom de release.projects sans dossier, ou un package public absent de la liste, échoue avec un message qui nomme le fichier à modifier.

Vérification : pnpm exec vitest run scripts/__tests__ ; pnpm publint ; pnpm check.

AL2 — size-limit au vert (S/M), vague 1

Fichiers : .size-limit.json, et seulement si la cause est là, les modules du chemin d'entrée de packages/site (lecture de la règle « Bundle Size » d'AGENTS.md d'abord).

• 2.1 — pnpm exec nx run-many -t build puis pnpm size : la mesure sur un build frais, notée.
• 2.2 — Si rouge : ce qui a grossi dans entry.client (vite build --sourcemap et lecture des chunks), et ce qui peut passer derrière un import() ; sinon, limite relevée à la mesure arrondie, raison écrite.

Vérification : pnpm size vert ; pnpm test:e2e:host e2e/site-embed.spec.ts ; pnpm check.

AL3 — Les alias dépréciés retirés (M), vague 1, si la question 2 est acceptée

Fichiers : packages/core/src/compile/compile-story.ts, packages/core/src/types/story.ts, packages/components/src/mdx/builtins.tsx, packages/integrations/site-stories/src/{StoryViewer,mdx-components}.tsx, packages/cli/src/config/load-config.ts, leurs tests, sites/docs/pages/documentation/reference/architecture.mdx, sites/docs/pages/documentation/configuration/recit-config.mdx, un version plan prerelease.

• 3.1 — Chaque alias retiré ; presentation.config.* trouvé sur le disque donne une erreur qui nomme recit.config.ts.
• 3.2 — grep des anciens noms vide hors du changelog et des plans d'archive.

Vérification : pnpm test:related sur les fichiers touchés ; pnpm exec nx run-many -t build typecheck ; pnpm test ; pnpm test:e2e:host e2e/site-embed.spec.ts e2e/site-docs.spec.ts ; pnpm check.

AL4 — create-recit (M), vague 2

Dépend de : AL1, question 3 (et question 1 pour le gabarit docs). Fichiers : packages/create-recit/** (package.json public, bin/, src/, templates/ généré, README.md, LICENSE.md, tsdown.config.ts, tests), un version plan prerelease. Demande au coordinateur la ligne create-recit de release.projects.

• 4.1 — npm create recit [dossier] [--template deck|motion|docs] [--yes] : questions si un choix manque et que le terminal est interactif, refus d'écrire dans un dossier non vide sans --force.
• 4.2 — Gabarits générés au build depuis les exemples ; workspace:* remplacé par la version de create-recit ; un test compare chaque gabarit à son exemple.
• 4.3 — Message final : cd, la commande d'installation du gestionnaire détecté, puis npm run dev.
• 4.4 — Forme de package publié : published-packages.spec.ts et publint verts sans toucher aux listes (grâce à AL1).

Vérification : pnpm exec vitest run packages/create-recit ; pnpm -F create-recit typecheck ; pnpm publint ; pnpm exec vitest run scripts/__tests__ ; pnpm check.

AL5 — Le test de fumée hors de l'espace de travail (M), vague 2

Dépend de : AL1. Fichiers : scripts/pack-smoke.js (nouveau), scripts/__tests__/pack-smoke.spec.ts (les fonctions pures : liste des archives, réécriture des chemins), .github/workflows/release.yaml (une étape dans le job plan), scripts/__tests__/release-workflow.spec.ts si l'étape doit y être vérifiée.

• 5.1 — pnpm pack de chaque package de release.projects dans un dossier du système, projet vierge hors du dépôt, npm install des archives (les dépendances tierces viennent du registre).
• 5.2 — Deck : recit init, recit build, recit validate, recit convert aller et retour. Motion : recit init --format motion, recit dur, recit validate. Sans motion-render : recit render dit quel package installer.
• 5.3 — Après AL4 : chaque gabarit de create-recit créé puis construit (npm run build).
• 5.4 — Durée mesurée et notée ; le script nettoie son dossier temporaire même en échec.

Vérification : node scripts/pack-smoke.js vert sur Linux ; pnpm exec vitest run scripts/__tests__ ; pnpm check.

AL6 — Le framework de sites publiable (M/L), vague 2, si la question 1 est acceptée

Dépend de : AL1, AL2 (le budget d'entry.client est le sien). Fichiers : packages/site/package.json (private retiré, version 0.0.0, files, publishConfig, engines, author, repository), packages/site/README.md, packages/site/LICENSE.md (les deux copyrights, règles de NOTICE.md), packages/integrations/site-stories/package.json (peer réel), un version plan prerelease. Demande au coordinateur : release.projects, la règle d'AGENTS.md, 03-packaging.md §3.1, §6 et §10.

• 6.1 — exports sans condition development, tests et fixtures hors de l'archive.
• 6.2 — publint et published-packages.spec.ts verts sur @recit/site.
• 6.3 — Le gabarit docs construit hors du dépôt par AL5 avec recit-site build.

Vérification : pnpm -F @recit/site typecheck ; pnpm exec nx run @recit/site:build ; pnpm publint ; pnpm test ; node scripts/pack-smoke.js ; pnpm check.

AL7 — La doc de l'alpha (S), vague 3

Dépend de : AL4. Fichiers : quickstart.mdx, la page CLI de référence si create-recit y figure, les README.md des packages publiés (ligne « alpha » et installation).

• 7.1 — Quickstart en deux temps : le texte de npm create recit est écrit, la note « Not on npm yet » reste jusqu'à AL10.
• 7.2 — Licence de Remotion citée sur la page motion et dans le README de motion-render.

Vérification : pnpm exec nx run docs:build ; pnpm test:e2e:host e2e/site-docs.spec.ts ; pnpm check.

AL8 — Les schémas servis sur recit.dev (S), vague 1, si la question 5 est acceptée

Fichiers : la config de sites/www (copie de packages/core/schema/v1 dans la sortie du build, sans composant : un site, c'est du Markdown et de la config), sites/www/package.json (@recit/core en devDependencies, règle ST-20), e2e/site-www.spec.ts.

• 8.1 — GET /schema/v1/deck.json sur le site construit rend le fichier, avec son $id.
• 8.2 — Le jeu de fichiers servi est exactement celui de packages/core/schema/v1.

Vérification : pnpm exec nx run www:build ; pnpm test:e2e:host e2e/site-www.spec.ts ; pnpm check.

AL9 — Répétition générale (S), coordinateur, vague 4

• 9.1 — pnpm verify ; pnpm test:e2e:linux complet ; node scripts/pack-smoke.js.
• 9.2 — node scripts/check-version-plans.js --preid alpha ; pnpm exec nx release --skip-publish --preid alpha --dry-run annonce 0.1.0-alpha.0 pour chaque package de la liste, et un CHANGELOG.md dont chaque entrée est relue.
• 9.3 — Note de journal, puis arrêt : le coordinateur remet l'arbre de travail et le résultat du dry run à l'utilisateur. Rien n'est commité, rien n'est publié.

AL10 — La publication (humain), après le feu vert

Fait par l'utilisateur, dans l'ordre de SETUP.md §4 : dépôt définitif et public, première publication à la main (npm ne configure un Trusted Publisher que sur un package qui existe), un Trusted Publisher et « disallow tokens » par package, suppression des jetons, npm deprecate des @emaki/* par leur auteur. Ensuite seulement, un agent retire la note « Not on npm yet » (AL7, suite) et le journal enregistre la version publiée. Les releases suivantes passent par le workflow.

5.1 Vagues

Au plus quatre agents en même temps, sous le plafond de cinq du plan 20.

6. Critères de sortie de P5

1. 0.1.0-alpha.0 est sur npm sous next, pour chaque package de release.projects, avec la provenance, après le feu vert de l'utilisateur.
2. Dans un dossier vide, npm create recit@next puis npm run dev ouvre un deck ; même chose pour un film et, si D2, un site.
3. pnpm publint, pnpm size, node scripts/pack-smoke.js et pnpm verify sont verts dans la CI du commit publié.
4. Chaque package a son Trusted Publisher ; aucun jeton npm ne reste.
5. Quickstart et README décrivent ce qui est publié, sans note provisoire.

7. Risques

8. Questions ouvertes

1. Publier le framework de sites (@recit/site) avec l'alpha (proposé, D2), ou le garder privé et réduire l'alpha à deck et motion (D2') ? C'est un revirement de 03-packaging.md §10 et de la règle d'AGENTS.md ; il conditionne @recit/app et le gabarit docs.
2. Les alias dépréciés : les retirer avant la première publication (proposé, D6), ou les garder jusqu'à la 1.0 comme le dit P12 ?
3. Gabarits de create-recit : deck, motion, docs (proposé), et rien d'installé automatiquement (proposé : la commande est affichée) ?
4. Dépôt définitif : vguerand/recit ou recit-dev/recit ? Il faut trancher avant AL10 ; c'est aussi la question 2 de la feuille de route.
5. Schémas v1 servis dès l'alpha sur recit.dev/schema/v1/ avec la mention « non figés » (proposé), ou seulement à la 1.0 ? Les schémas des formats encore privés (report, toon…) sont des coquilles génériques : faut-il les servir aussi, ou seulement deck, motion, docs, story, sidecar et config ?
6. Noms sans scope recit et create-recit : publier tout de suite un 0.0.0 vide pour les réserver, ou attendre l'alpha (proposé, si la revérification du jour J les trouve libres) ?