@astratra/centrale-cli 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @astratra/centrale-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+L'outil en ligne de commande de **Centrale LJ** : il relie les erreurs minifiées à leur vraie ligne (cartes de code, par identifiant de débogage) et déclare les déploiements (version d'apparition, commit suspect). Aucune dépendance, aucun outil Sentry.
+
+## Commandes
+
+```sh
+export CENTRALE_ADRESSE=https://centrale.exemple.fr
+export CENTRALE_JETON=clj_dep_…            # jeton de DÉPLOIEMENT du projet (secret de CI)
+
+npx centrale injecter dist                 # après le build, avant la mise en ligne
+npx centrale envoyer-cartes dist --version 2.14.0
+npx centrale deploiement --version 2.14.0 --commit "$GITHUB_SHA" --depot kongo/scolaris --environnement production
+```
+
+| Commande | Ce qu'elle fait |
+| --- | --- |
+| `injecter <dossier>` | Pour chaque `.js`/`.mjs`/`.cjs` qui a une carte (commentaire `sourceMappingURL` ou `<fichier>.map`) : calcule un identifiant stable (SHA-256 du contenu, mis en forme d'UUID), insère en tête une ligne qui l'enregistre dans `globalThis.__centraleDebugIds`, ajoute `//# debugId=<id>` en fin de fichier et `debug_id` dans la carte. Relancer ne change rien. |
+| `envoyer-cartes <dossier> --version X` | Demande au backend les cartes qu'il a déjà, puis envoie les autres par lots compressés (16 Mio visés, 64 Mio au plus). Coupure, 5xx et 429 sont réessayés avec recul (`Retry-After` respecté). Relancer reprend où l'envoi s'est arrêté. |
+| `deploiement --version X --commit SHA` | Déclare un déploiement. `--environnement` vaut par défaut celui du jeton. Déclarer deux fois le même ne crée pas de doublon. |
+
+Codes de sortie : `0` réussi, `1` échec (réseau, jeton refusé, carte refusée), `2` commande mal formée.
+
+## Comment l'identifiant voyage
+
+1. `injecter` place en tête de chaque fichier (après `#!` et les directives `"use strict"`, `"use client"`, sur la même ligne pour ne décaler aucun numéro de ligne ; les colonnes de la carte sont recalées) :
+   `globalThis.__centraleDebugIds[new Error().stack] = "<id>"`.
+2. Au chargement, la pile capturée contient l'adresse réelle du fichier (domaine, hash du build compris).
+3. `@astratra/centrale` relit ces piles avec le même analyseur que les erreurs : chaque cadre reçoit le `debugId` de son fichier (et l'erreur aussi, s'il n'y en a qu'un).
+4. Le backend traduit les cadres avec la carte de même identifiant **du même projet**, à la lecture du détail d'un problème.
+
+Sans identifiant (bytecode Hermes, build non injecté), le backend cherche une carte de **la même version** dont le chemin finit comme celui du cadre : nommez la carte comme le fichier des piles (par exemple `index.android.bundle.map` pour Expo/React Native).
+
+## Exemples de build
+
+- **Vite / Astro** : `build.sourcemap: true` (ou `'hidden'` pour ne pas publier le commentaire), puis `centrale injecter dist`. Ne mettez pas les `.map` en ligne : supprimez-les après `envoyer-cartes`.
+- **Node compilé** (tsc, esbuild) : `sourceMap: true`, puis `centrale injecter build`.
+- **Expo / Hermes** : exportez avec les cartes (`npx expo export --dump-sourcemap`), puis `centrale injecter dist` (la carte reçoit son identifiant) et `centrale envoyer-cartes dist --version <version de l'app>`.
+
+## Bibliothèque
+
+```ts
+import { injecterDossier, envoyerCartes, declarerDeploiement } from '@astratra/centrale-cli';
+```
+
+Le paquet est écrit en TypeScript à syntaxe effaçable (Node 24 l'exécute directement dans le dépôt) ; il sera compilé en JavaScript au moment de sa publication, comme `@astratra/centrale`.
+
+## Tests
+
+```sh
+npm test -w @astratra/centrale-cli
+```

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * `centrale` : l'outil en ligne de commande de Centrale LJ.
+ *   centrale injecter <dossier>
+ *   centrale envoyer-cartes <dossier> --version X
+ *   centrale deploiement --version X --commit SHA [--depot owner/repo] [--environnement production]
+ * Le jeton de déploiement se lit dans CENTRALE_JETON, l'adresse du backend dans CENTRALE_ADRESSE.
+ * Code de sortie : 0 si tout va bien, 1 en cas d'échec, 2 pour une commande mal formée.
+ */
+import { type Connexion } from './envoyer.ts';
+interface Sorties {
+    ecrire: (texte: string) => void;
+    erreur: (texte: string) => void;
+}
+interface Options {
+    env?: NodeJS.ProcessEnv;
+    sorties?: Sorties;
+    connexion?: Partial<Connexion>;
+}
+/** Sépare les arguments positionnels et les options `--nom valeur` / `--nom=valeur`. */
+export declare function lireArguments(args: string[]): {
+    positionnels: string[];
+    options: Record<string, string>;
+};
+/** Exécute une commande ; rend le code de sortie. Ne lève pas. */
+export declare function executer(args: string[], { env, sorties, connexion: surcharge }?: Options): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * `centrale` : l'outil en ligne de commande de Centrale LJ.
+ *   centrale injecter <dossier>
+ *   centrale envoyer-cartes <dossier> --version X
+ *   centrale deploiement --version X --commit SHA [--depot owner/repo] [--environnement production]
+ * Le jeton de déploiement se lit dans CENTRALE_JETON, l'adresse du backend dans CENTRALE_ADRESSE.
+ * Code de sortie : 0 si tout va bien, 1 en cas d'échec, 2 pour une commande mal formée.
+ */
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { cheminRelatif, injecterDossier } from "./injecter.js";
+import { declarerDeploiement, envoyerCartes } from "./envoyer.js";
+const AIDE = `Utilisation :
+  centrale injecter <dossier>
+      Ajoute un identifiant de débogage à chaque fichier JS du build et à sa carte (.map).
+  centrale envoyer-cartes <dossier> --version X
+      Envoie les cartes (.map) au backend ; celles qu'il a déjà sont sautées.
+  centrale deploiement --version X --commit SHA [--depot owner/repo] [--environnement production]
+      Déclare un déploiement (pour la version d'apparition et le commit suspect).
+
+Variables d'environnement : CENTRALE_JETON (jeton de déploiement clj_dep_…), CENTRALE_ADRESSE (adresse du backend).`;
+/** Sépare les arguments positionnels et les options `--nom valeur` / `--nom=valeur`. */
+export function lireArguments(args) {
+    const positionnels = [];
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            const egal = a.indexOf('=');
+            if (egal !== -1)
+                options[a.slice(2, egal)] = a.slice(egal + 1);
+            else if (i + 1 < args.length && !args[i + 1].startsWith('--'))
+                options[a.slice(2)] = args[++i];
+            else
+                options[a.slice(2)] = 'true';
+        }
+        else {
+            positionnels.push(a);
+        }
+    }
+    return { positionnels, options };
+}
+function connexionDe(env, sorties, surcharge = {}) {
+    const jeton = env.CENTRALE_JETON?.trim();
+    const adresse = env.CENTRALE_ADRESSE?.trim();
+    if (!jeton || !/^clj_dep_/.test(jeton)) {
+        sorties.erreur('CENTRALE_JETON manque ou n\'est pas un jeton de déploiement (clj_dep_…).');
+        return null;
+    }
+    if (!adresse || !/^https?:\/\//.test(adresse)) {
+        sorties.erreur('CENTRALE_ADRESSE manque (par exemple https://centrale.exemple.fr).');
+        return null;
+    }
+    return { adresse, jeton, ...surcharge };
+}
+function dossierValide(chemin, sorties) {
+    if (!chemin) {
+        sorties.erreur('Dossier manquant.');
+        return null;
+    }
+    const absolu = resolve(chemin);
+    if (!existsSync(absolu) || !statSync(absolu).isDirectory()) {
+        sorties.erreur(`Dossier introuvable : ${chemin}`);
+        return null;
+    }
+    return absolu;
+}
+/** Exécute une commande ; rend le code de sortie. Ne lève pas. */
+export async function executer(args, { env = process.env, sorties = { ecrire: console.log, erreur: console.error }, connexion: surcharge } = {}) {
+    const [commande, ...reste] = args;
+    const { positionnels, options } = lireArguments(reste);
+    try {
+        switch (commande) {
+            case 'injecter': {
+                const dossier = dossierValide(positionnels[0], sorties);
+                if (!dossier)
+                    return 2;
+                const resultats = injecterDossier(dossier);
+                const compte = { injecte: 0, deja: 0, 'carte-seule': 0, 'sans-carte': 0 };
+                for (const r of resultats) {
+                    compte[r.etat]++;
+                    if (r.etat !== 'sans-carte')
+                        sorties.ecrire(`${r.etat === 'deja' ? '=' : '+'} ${cheminRelatif(dossier, r.fichier)}  ${r.debugId}`);
+                }
+                sorties.ecrire(`${compte.injecte} injecté(s), ${compte.deja} déjà fait(s), ${compte['carte-seule']} carte(s) seule(s), ${compte['sans-carte']} fichier(s) JS sans carte.`);
+                return 0;
+            }
+            case 'envoyer-cartes': {
+                const dossier = dossierValide(positionnels[0], sorties);
+                if (!dossier)
+                    return 2;
+                if (!options.version || options.version === 'true') {
+                    sorties.erreur('--version est obligatoire.');
+                    return 2;
+                }
+                const connexion = connexionDe(env, sorties, surcharge);
+                if (!connexion)
+                    return 2;
+                const bilan = await envoyerCartes(connexion, { dossier, version: options.version, signaler: (m) => sorties.ecrire(`… ${m}`) });
+                for (const f of bilan.tropGrosses)
+                    sorties.erreur(`Carte trop grosse, non envoyée : ${f}`);
+                for (const r of bilan.refusees)
+                    sorties.erreur(`Carte refusée (${r.debugId}) : ${r.raison}`);
+                sorties.ecrire(`${bilan.envoyees.length} carte(s) envoyée(s), ${bilan.dejaConnues.length} déjà connue(s).`);
+                return bilan.refusees.length || bilan.tropGrosses.length ? 1 : 0;
+            }
+            case 'deploiement': {
+                if (!options.version || options.version === 'true' || !options.commit || options.commit === 'true') {
+                    sorties.erreur('--version et --commit sont obligatoires.');
+                    return 2;
+                }
+                const connexion = connexionDe(env, sorties, surcharge);
+                if (!connexion)
+                    return 2;
+                await declarerDeploiement(connexion, {
+                    version: options.version,
+                    commit: options.commit,
+                    ...(options.depot ? { depot: options.depot } : {}),
+                    ...(options.environnement ? { environnement: options.environnement } : {})
+                });
+                sorties.ecrire(`Déploiement ${options.version} (${options.commit.slice(0, 12)}) déclaré.`);
+                return 0;
+            }
+            case undefined:
+            case 'aide':
+            case '--help':
+            case '-h':
+                sorties.ecrire(AIDE);
+                return commande === undefined ? 2 : 0;
+            default:
+                sorties.erreur(`Commande inconnue : ${commande}\n\n${AIDE}`);
+                return 2;
+        }
+    }
+    catch (erreur) {
+        sorties.erreur(`Échec : ${erreur instanceof Error ? erreur.message : String(erreur)}`);
+        return 1;
+    }
+}
+/* Lancé directement (bin `centrale`) : on exécute avec les arguments du processus. */
+function lanceDirectement() {
+    try {
+        return Boolean(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (lanceDirectement()) {
+    process.exitCode = await executer(process.argv.slice(2));
+}

package/dist/envoyer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `centrale envoyer-cartes <dossier> --version X` et `centrale deploiement …` : le dialogue avec
+ * le backend, authentifié par le jeton de déploiement du projet (`clj_dep_…`).
+ *
+ * L'envoi des cartes se fait en trois temps :
+ * 1. on liste les cartes du dossier et leur identifiant (celui posé par `injecter`, sinon un
+ *    identifiant tiré du contenu : le backend retrouvera alors la carte par version et nom de fichier) ;
+ * 2. on demande au backend celles qu'il a déjà (`POST /v1/cartes/connues`) : rien n'est renvoyé deux fois ;
+ * 3. on envoie le reste par lots compressés (`POST /v1/cartes`), chaque lot étant réessayé avec un
+ *    recul progressif en cas de coupure, de 5xx ou de 429 (`Retry-After` respecté).
+ */
+/** Taille visée d'un lot, avant compression : assez petite pour un réseau moyen, assez grande pour aller vite. */
+export declare const LOT_OCTETS: number;
+/** Le maximum accepté par le backend pour un lot une fois décompressé. */
+export declare const LOT_MAX_OCTETS: number;
+export interface Connexion {
+    adresse: string;
+    jeton: string;
+    /** Injectables pour les tests. */
+    fetch?: typeof fetch;
+    attendre?: (ms: number) => Promise<void>;
+    essais?: number;
+    reculBaseMs?: number;
+}
+export declare class ErreurCentrale extends Error {
+    statut: number;
+    constructor(message: string, statut: number);
+}
+/** Une requête JSON (gzip pour les gros corps), réessayée sur coupure, 408, 429 et 5xx. */
+export declare function appeler(connexion: Connexion, chemin: string, corps: unknown): Promise<unknown>;
+export interface CarteLocale {
+    chemin: string;
+    /** Chemin du fichier généré relatif au dossier (sans `.map`), par exemple `assets/index-BxK3.js`. */
+    fichier: string;
+    debugId: string;
+    taille: number;
+    /** Vrai si l'identifiant vient d'`injecter` (sinon il est tiré du contenu). */
+    injecte: boolean;
+}
+/** Les cartes d'un dossier de build et leur identifiant. Les cartes de CSS sont laissées de côté. */
+export declare function cartesDe(dossier: string): CarteLocale[];
+export interface BilanEnvoi {
+    envoyees: string[];
+    dejaConnues: string[];
+    tropGrosses: string[];
+    refusees: Array<{
+        debugId: string;
+        raison: string;
+    }>;
+}
+export declare function envoyerCartes(connexion: Connexion, { dossier, version, lotOctets, signaler }: {
+    dossier: string;
+    version?: string;
+    lotOctets?: number;
+    signaler?: (message: string) => void;
+}): Promise<BilanEnvoi>;
+export interface Deploiement {
+    version: string;
+    commit: string;
+    depot?: string;
+    environnement?: string;
+    deployeLe?: string;
+}
+export declare function declarerDeploiement(connexion: Connexion, deploiement: Deploiement): Promise<unknown>;

package/dist/envoyer.js

@@ -0,0 +1,148 @@
+/**
+ * `centrale envoyer-cartes <dossier> --version X` et `centrale deploiement …` : le dialogue avec
+ * le backend, authentifié par le jeton de déploiement du projet (`clj_dep_…`).
+ *
+ * L'envoi des cartes se fait en trois temps :
+ * 1. on liste les cartes du dossier et leur identifiant (celui posé par `injecter`, sinon un
+ *    identifiant tiré du contenu : le backend retrouvera alors la carte par version et nom de fichier) ;
+ * 2. on demande au backend celles qu'il a déjà (`POST /v1/cartes/connues`) : rien n'est renvoyé deux fois ;
+ * 3. on envoie le reste par lots compressés (`POST /v1/cartes`), chaque lot étant réessayé avec un
+ *    recul progressif en cas de coupure, de 5xx ou de 429 (`Retry-After` respecté).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
+import { cheminRelatif, debugIdDe, fichiersDe } from "./injecter.js";
+/** Taille visée d'un lot, avant compression : assez petite pour un réseau moyen, assez grande pour aller vite. */
+export const LOT_OCTETS = 16 * 1024 * 1024;
+/** Le maximum accepté par le backend pour un lot une fois décompressé. */
+export const LOT_MAX_OCTETS = 64 * 1024 * 1024;
+const CONNUES_PAR_DEMANDE = 1000;
+export class ErreurCentrale extends Error {
+    statut;
+    constructor(message, statut) { super(message); this.statut = statut; }
+}
+const attendreVraiment = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Une requête JSON (gzip pour les gros corps), réessayée sur coupure, 408, 429 et 5xx. */
+export async function appeler(connexion, chemin, corps) {
+    const f = connexion.fetch ?? fetch;
+    const attendre = connexion.attendre ?? attendreVraiment;
+    const essais = Math.max(1, connexion.essais ?? 5);
+    const base = connexion.reculBaseMs ?? 1000;
+    const texte = JSON.stringify(corps);
+    const compresse = texte.length > 1024;
+    const contenu = compresse ? gzipSync(texte) : texte;
+    const adresse = connexion.adresse.replace(/\/+$/, '') + chemin;
+    let derniere;
+    for (let essai = 1; essai <= essais; essai++) {
+        let reponse;
+        try {
+            reponse = await f(adresse, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${connexion.jeton}`,
+                    'Content-Type': 'application/json',
+                    ...(compresse ? { 'Content-Encoding': 'gzip' } : {})
+                },
+                body: contenu
+            });
+        }
+        catch (erreur) {
+            derniere = erreur;
+            if (essai < essais)
+                await attendre(base * 2 ** (essai - 1));
+            continue;
+        }
+        const lu = await reponse.text();
+        let json = null;
+        try {
+            json = lu ? JSON.parse(lu) : null;
+        }
+        catch { /* réponse non JSON : on garde le statut */ }
+        if (reponse.ok)
+            return json;
+        const message = json?.message ?? `HTTP ${reponse.status}`;
+        derniere = new ErreurCentrale(message, reponse.status);
+        const temporaire = reponse.status === 408 || reponse.status === 429 || reponse.status >= 500;
+        if (!temporaire || essai === essais)
+            break;
+        const demande = Number(reponse.headers.get('retry-after'));
+        await attendre(Number.isFinite(demande) && demande > 0 ? Math.min(demande, 300) * 1000 : base * 2 ** (essai - 1));
+    }
+    throw derniere instanceof Error ? derniere : new ErreurCentrale(String(derniere), 0);
+}
+/** Les cartes d'un dossier de build et leur identifiant. Les cartes de CSS sont laissées de côté. */
+export function cartesDe(dossier) {
+    const sortie = [];
+    for (const chemin of fichiersDe(dossier)) {
+        if (!chemin.endsWith('.map') || chemin.endsWith('.css.map'))
+            continue;
+        const texte = readFileSync(chemin, 'utf8');
+        let carte;
+        try {
+            carte = JSON.parse(texte);
+        }
+        catch {
+            continue;
+        }
+        if (!carte || typeof carte !== 'object' || typeof carte.mappings !== 'string')
+            continue;
+        const pose = typeof carte.debug_id === 'string' ? carte.debug_id : typeof carte.debugId === 'string' ? carte.debugId : null;
+        sortie.push({
+            chemin,
+            fichier: cheminRelatif(dossier, chemin).replace(/\.map$/, ''),
+            debugId: (pose ?? debugIdDe(texte)).toLowerCase(),
+            taille: statSync(chemin).size,
+            injecte: pose !== null
+        });
+    }
+    return sortie;
+}
+export async function envoyerCartes(connexion, { dossier, version, lotOctets = LOT_OCTETS, signaler = () => { } }) {
+    const cartes = cartesDe(dossier);
+    const bilan = { envoyees: [], dejaConnues: [], tropGrosses: [], refusees: [] };
+    const connues = new Set();
+    for (let i = 0; i < cartes.length; i += CONNUES_PAR_DEMANDE) {
+        const morceau = cartes.slice(i, i + CONNUES_PAR_DEMANDE).map((c) => c.debugId);
+        const reponse = await appeler(connexion, '/v1/cartes/connues', { debugIds: morceau });
+        for (const id of reponse?.connues ?? [])
+            connues.add(id.toLowerCase());
+    }
+    const aEnvoyer = [];
+    for (const c of cartes) {
+        if (connues.has(c.debugId))
+            bilan.dejaConnues.push(c.debugId);
+        else if (c.taille > LOT_MAX_OCTETS - 1024)
+            bilan.tropGrosses.push(c.fichier);
+        else
+            aEnvoyer.push(c);
+    }
+    /* Des lots d'au plus `lotOctets` (une carte plus grosse part seule). */
+    let lot = [];
+    let taille = 0;
+    const partir = async () => {
+        if (!lot.length)
+            return;
+        const corps = {
+            ...(version ? { version } : {}),
+            cartes: lot.map((c) => ({ debugId: c.debugId, fichier: c.fichier, carte: readFileSync(c.chemin, 'utf8') }))
+        };
+        const reponse = await appeler(connexion, '/v1/cartes', corps);
+        bilan.envoyees.push(...(reponse?.enregistrees ?? []));
+        bilan.dejaConnues.push(...(reponse?.dejaConnues ?? []));
+        bilan.refusees.push(...(reponse?.refusees ?? []));
+        signaler(`${bilan.envoyees.length + bilan.dejaConnues.length}/${cartes.length}`);
+        lot = [];
+        taille = 0;
+    };
+    for (const c of aEnvoyer) {
+        if (lot.length && taille + c.taille > lotOctets)
+            await partir();
+        lot.push(c);
+        taille += c.taille;
+    }
+    await partir();
+    return bilan;
+}
+export async function declarerDeploiement(connexion, deploiement) {
+    return appeler(connexion, '/v1/deploiements', deploiement);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** `@astratra/centrale-cli` utilisé comme bibliothèque (scripts de build, tests). */
+export { injecterDossier, injecterFichier, marquerCarteSeule, debugIdDe, ligneEnregistrement, pointDInsertion, GLOBALE } from './injecter.ts';
+export type { Resultat } from './injecter.ts';
+export { envoyerCartes, declarerDeploiement, cartesDe, appeler, ErreurCentrale, LOT_OCTETS, LOT_MAX_OCTETS } from './envoyer.ts';
+export type { Connexion, CarteLocale, BilanEnvoi, Deploiement } from './envoyer.ts';
+export { executer } from './cli.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+/** `@astratra/centrale-cli` utilisé comme bibliothèque (scripts de build, tests). */
+export { injecterDossier, injecterFichier, marquerCarteSeule, debugIdDe, ligneEnregistrement, pointDInsertion, GLOBALE } from "./injecter.js";
+export { envoyerCartes, declarerDeploiement, cartesDe, appeler, ErreurCentrale, LOT_OCTETS, LOT_MAX_OCTETS } from "./envoyer.js";
+export { executer } from "./cli.js";

package/dist/injecter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `centrale injecter <dossier>` : donne à chaque fichier JavaScript d'un build un identifiant
+ * de débogage (debug ID) stable, et l'écrit à trois endroits :
+ * 1. dans le JavaScript, une ligne d'enregistrement exécutée au chargement du fichier :
+ *    `globalThis.__centraleDebugIds[new Error().stack] = "<id>"`. La pile capturée commence
+ *    par l'adresse du fichier tel que le navigateur, Node ou Hermes le voit vraiment ; le paquet
+ *    de collecte relit ces piles et sait ainsi quel fichier (adresse finale, hash compris)
+ *    porte quel identifiant, sans rien supposer du serveur web ni du nom des fichiers ;
+ * 2. à la fin du JavaScript, le commentaire `//# debugId=<id>` (lisible par un humain et par les outils) ;
+ * 3. dans la carte (.map), les champs `debug_id` et `debugId`.
+ *
+ * L'identifiant est dérivé du contenu (SHA-256 tronqué mis en forme d'UUID) : le même build
+ * donne le même identifiant, et relancer la commande ne change rien (idempotence).
+ *
+ * La ligne d'enregistrement est insérée au DÉBUT du fichier (après un éventuel `#!` et les
+ * directives comme "use strict" ou "use client", qui doivent rester en tête), SUR LA MÊME
+ * LIGNE : les numéros de ligne ne bougent pas, seules les colonnes de cette ligne sont décalées
+ * dans la carte. En tête, elle s'exécute avant tout le code du fichier : même une erreur levée
+ * au chargement est reliée à sa carte.
+ *
+ * Les fichiers qui ne sont pas du JavaScript texte (bytecode Hermes `.hbc`) ne peuvent pas
+ * recevoir cette ligne : leur carte reçoit quand même un identifiant, et le backend les retrouve
+ * par la version et le nom du fichier.
+ */
+export declare const GLOBALE = "__centraleDebugIds";
+export type Resultat = {
+    fichier: string;
+    carte: string;
+    debugId: string;
+    etat: 'injecte' | 'deja';
+} | {
+    fichier: string;
+    carte: string;
+    debugId: string;
+    etat: 'carte-seule';
+} | {
+    fichier: string;
+    etat: 'sans-carte';
+};
+/** Un identifiant au format UUID (version 4, variante RFC 4122) tiré d'un SHA-256 : stable pour un même contenu. */
+export declare function debugIdDe(contenu: string | Buffer): string;
+/** La ligne d'enregistrement. Ne lève jamais, même dans un moteur sans `globalThis`. */
+export declare function ligneEnregistrement(debugId: string): string;
+/** Tous les fichiers d'un dossier, récursivement, sans node_modules ni .git. */
+export declare function fichiersDe(dossier: string): string[];
+/** La carte d'un fichier JS : celle de son commentaire `sourceMappingURL` (si locale), sinon `<fichier>.map`. */
+export declare function carteDe(fichierJs: string, contenu: string): string | null;
+/**
+ * Où insérer la ligne d'enregistrement : après un `#!` et après les directives de tête
+ * ("use strict", "use client"…), commentaires compris. Rend l'indice dans le texte.
+ */
+export declare function pointDInsertion(code: string): number;
+/** Traite un fichier JavaScript et sa carte. Sans danger à relancer. */
+export declare function injecterFichier(fichierJs: string): Resultat;
+/** Une carte sans JavaScript texte à côté (bytecode Hermes…) : seulement l'identifiant, tiré de son contenu. */
+export declare function marquerCarteSeule(cheminCarte: string): Resultat;
+/** Tout un dossier de build : les JS avec carte, puis les cartes restées seules. */
+export declare function injecterDossier(dossier: string): Resultat[];
+/** Chemin relatif lisible, avec des « / » partout. */
+export declare function cheminRelatif(dossier: string, fichier: string): string;

package/dist/injecter.js

@@ -0,0 +1,208 @@
+/**
+ * `centrale injecter <dossier>` : donne à chaque fichier JavaScript d'un build un identifiant
+ * de débogage (debug ID) stable, et l'écrit à trois endroits :
+ * 1. dans le JavaScript, une ligne d'enregistrement exécutée au chargement du fichier :
+ *    `globalThis.__centraleDebugIds[new Error().stack] = "<id>"`. La pile capturée commence
+ *    par l'adresse du fichier tel que le navigateur, Node ou Hermes le voit vraiment ; le paquet
+ *    de collecte relit ces piles et sait ainsi quel fichier (adresse finale, hash compris)
+ *    porte quel identifiant, sans rien supposer du serveur web ni du nom des fichiers ;
+ * 2. à la fin du JavaScript, le commentaire `//# debugId=<id>` (lisible par un humain et par les outils) ;
+ * 3. dans la carte (.map), les champs `debug_id` et `debugId`.
+ *
+ * L'identifiant est dérivé du contenu (SHA-256 tronqué mis en forme d'UUID) : le même build
+ * donne le même identifiant, et relancer la commande ne change rien (idempotence).
+ *
+ * La ligne d'enregistrement est insérée au DÉBUT du fichier (après un éventuel `#!` et les
+ * directives comme "use strict" ou "use client", qui doivent rester en tête), SUR LA MÊME
+ * LIGNE : les numéros de ligne ne bougent pas, seules les colonnes de cette ligne sont décalées
+ * dans la carte. En tête, elle s'exécute avant tout le code du fichier : même une erreur levée
+ * au chargement est reliée à sa carte.
+ *
+ * Les fichiers qui ne sont pas du JavaScript texte (bytecode Hermes `.hbc`) ne peuvent pas
+ * recevoir cette ligne : leur carte reçoit quand même un identifiant, et le backend les retrouve
+ * par la version et le nom du fichier.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { decalerColonnes } from "./vlq.js";
+export const GLOBALE = '__centraleDebugIds';
+const COMMENTAIRE = /\/\/# debugId=([0-9a-fA-F-]{36})\s*$/m;
+const EXTENSIONS_JS = /\.(?:m|c)?js$/;
+const DOSSIERS_IGNORES = new Set(['node_modules', '.git']);
+/** Un identifiant au format UUID (version 4, variante RFC 4122) tiré d'un SHA-256 : stable pour un même contenu. */
+export function debugIdDe(contenu) {
+    const octets = createHash('sha256').update(contenu).digest().subarray(0, 16);
+    octets[6] = (octets[6] & 0x0f) | 0x40;
+    octets[8] = (octets[8] & 0x3f) | 0x80;
+    const h = octets.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/** La ligne d'enregistrement. Ne lève jamais, même dans un moteur sans `globalThis`. */
+export function ligneEnregistrement(debugId) {
+    return `;!function(){try{var g=typeof globalThis!="undefined"?globalThis:typeof self!="undefined"?self:typeof window!="undefined"?window:typeof global!="undefined"?global:{},s=(new g.Error).stack;if(s){g.${GLOBALE}=g.${GLOBALE}||{};g.${GLOBALE}[s]="${debugId}"}}catch(e){}}();`;
+}
+/** Tous les fichiers d'un dossier, récursivement, sans node_modules ni .git. */
+export function fichiersDe(dossier) {
+    const sortie = [];
+    const parcourir = (d) => {
+        for (const entree of readdirSync(d, { withFileTypes: true })) {
+            if (entree.isDirectory()) {
+                if (!DOSSIERS_IGNORES.has(entree.name))
+                    parcourir(join(d, entree.name));
+            }
+            else if (entree.isFile()) {
+                sortie.push(join(d, entree.name));
+            }
+        }
+    };
+    parcourir(dossier);
+    return sortie.sort();
+}
+/** La carte d'un fichier JS : celle de son commentaire `sourceMappingURL` (si locale), sinon `<fichier>.map`. */
+export function carteDe(fichierJs, contenu) {
+    const commentaires = [...contenu.matchAll(/\/\/[#@] sourceMappingURL=(\S+)\s*$/gm)];
+    const adresse = commentaires.at(-1)?.[1];
+    if (adresse && !/^[a-z]+:/i.test(adresse)) {
+        let chemin;
+        try {
+            chemin = resolve(dirname(fichierJs), decodeURIComponent(adresse.split(/[?#]/)[0]));
+        }
+        catch {
+            chemin = '';
+        }
+        if (chemin && existsSync(chemin) && statSync(chemin).isFile())
+            return chemin;
+    }
+    const voisine = `${fichierJs}.map`;
+    return existsSync(voisine) ? voisine : null;
+}
+/**
+ * Où insérer la ligne d'enregistrement : après un `#!` et après les directives de tête
+ * ("use strict", "use client"…), commentaires compris. Rend l'indice dans le texte.
+ */
+export function pointDInsertion(code) {
+    let i = 0;
+    if (code.startsWith('#!')) {
+        const fin = code.indexOf('\n');
+        i = fin === -1 ? code.length : fin + 1;
+    }
+    const depart = i;
+    let apresDirectives = -1;
+    const blanc = /\s/;
+    for (;;) {
+        while (i < code.length && blanc.test(code[i]))
+            i++;
+        if (code.startsWith('//', i)) {
+            const fin = code.indexOf('\n', i);
+            i = fin === -1 ? code.length : fin + 1;
+            continue;
+        }
+        if (code.startsWith('/*', i)) {
+            const fin = code.indexOf('*/', i + 2);
+            if (fin === -1)
+                break;
+            i = fin + 2;
+            continue;
+        }
+        const directive = /^(['"])(?:[^'"\\\n]|\\.)*\1/.exec(code.slice(i, i + 500));
+        if (!directive)
+            break;
+        let j = i + directive[0].length;
+        while (code[j] === ' ' || code[j] === '\t')
+            j++;
+        // Une chaîne suivie d'autre chose qu'un « ; » ou une fin de ligne (`"a" + b`) n'est pas une directive.
+        if (code[j] === ';')
+            j++;
+        else if (j < code.length && code[j] !== '\n' && code[j] !== '\r')
+            break;
+        i = j;
+        apresDirectives = i;
+    }
+    return apresDirectives === -1 ? depart : apresDirectives;
+}
+/** Ligne et colonne (à partir de 0) d'un indice dans un texte. */
+function positionDe(texte, indice) {
+    let ligne = 0;
+    let debutLigne = 0;
+    for (let i = 0; i < indice; i++) {
+        if (texte.charCodeAt(i) === 10) {
+            ligne++;
+            debutLigne = i + 1;
+        }
+    }
+    return { ligne, colonne: indice - debutLigne };
+}
+function lireCarte(chemin) {
+    const valeur = JSON.parse(readFileSync(chemin, 'utf8'));
+    if (!valeur || typeof valeur !== 'object' || Array.isArray(valeur))
+        throw new Error(`carte illisible : ${chemin}`);
+    return valeur;
+}
+/** Écrit l'identifiant dans la carte (`debug_id` et `debugId`) si besoin ; `decaler` corrige les colonnes. */
+function marquerCarte(chemin, debugId, decaler) {
+    const carte = lireCarte(chemin);
+    if (carte.debug_id === debugId && carte.debugId === debugId && !decaler)
+        return;
+    if (decaler && typeof carte.mappings === 'string') {
+        carte.mappings = decalerColonnes(carte.mappings, decaler.ligne, decaler.colonne, decaler.longueur);
+    }
+    carte.debug_id = debugId;
+    carte.debugId = debugId;
+    writeFileSync(chemin, JSON.stringify(carte));
+}
+/** Traite un fichier JavaScript et sa carte. Sans danger à relancer. */
+export function injecterFichier(fichierJs) {
+    const code = readFileSync(fichierJs, 'utf8');
+    const carte = carteDe(fichierJs, code);
+    if (!carte)
+        return { fichier: fichierJs, etat: 'sans-carte' };
+    const deja = COMMENTAIRE.exec(code);
+    if (deja && code.includes(GLOBALE)) {
+        const debugId = deja[1].toLowerCase();
+        marquerCarte(carte, debugId);
+        return { fichier: fichierJs, carte, debugId, etat: 'deja' };
+    }
+    const debugId = debugIdDe(code);
+    const ligne = ligneEnregistrement(debugId);
+    const indice = pointDInsertion(code);
+    const position = positionDe(code, indice);
+    const avecFinDeLigne = code.endsWith('\n') ? code : code + '\n';
+    const nouveau = avecFinDeLigne.slice(0, indice) + ligne + avecFinDeLigne.slice(indice) + `//# debugId=${debugId}\n`;
+    // La carte d'abord : si elle est illisible, le JavaScript reste intact.
+    marquerCarte(carte, debugId, { ...position, longueur: ligne.length });
+    writeFileSync(fichierJs, nouveau);
+    return { fichier: fichierJs, carte, debugId, etat: 'injecte' };
+}
+/** Une carte sans JavaScript texte à côté (bytecode Hermes…) : seulement l'identifiant, tiré de son contenu. */
+export function marquerCarteSeule(cheminCarte) {
+    const carte = lireCarte(cheminCarte);
+    const existant = typeof carte.debug_id === 'string' ? carte.debug_id : typeof carte.debugId === 'string' ? carte.debugId : null;
+    const { debug_id: _a, debugId: _b, ...sansId } = carte;
+    const debugId = existant ?? debugIdDe(JSON.stringify(sansId));
+    marquerCarte(cheminCarte, debugId);
+    return { fichier: cheminCarte.replace(/\.map$/, ''), carte: cheminCarte, debugId, etat: 'carte-seule' };
+}
+/** Tout un dossier de build : les JS avec carte, puis les cartes restées seules. */
+export function injecterDossier(dossier) {
+    const tous = fichiersDe(dossier);
+    const resultats = [];
+    const cartesTraitees = new Set();
+    for (const f of tous.filter((f) => EXTENSIONS_JS.test(f))) {
+        const r = injecterFichier(f);
+        resultats.push(r);
+        if ('carte' in r)
+            cartesTraitees.add(resolve(r.carte));
+    }
+    for (const c of tous.filter((f) => f.endsWith('.map') && !cartesTraitees.has(resolve(f)))) {
+        // Une carte de CSS n'a rien à faire ici.
+        if (/\.css\.map$/.test(c))
+            continue;
+        resultats.push(marquerCarteSeule(c));
+    }
+    return resultats;
+}
+/** Chemin relatif lisible, avec des « / » partout. */
+export function cheminRelatif(dossier, fichier) {
+    return relative(dossier, fichier).split(sep).join('/') || basename(fichier);
+}

package/dist/vlq.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Le codage VLQ en base 64 des cartes de code (source maps, version 3), réduit à ce dont
+ * l'injection a besoin : décaler les colonnes d'une ligne générée quand on y insère du code.
+ * Sans dépendance. Le backend a son propre décodeur complet (backend/src/modules/carteCode.ts).
+ */
+/** Lit une valeur VLQ à partir de `debut` ; rend la valeur et la position qui suit. */
+export declare function lireVlq(texte: string, debut: number): [number, number];
+export declare function ecrireVlq(valeur: number): string;
+/**
+ * Décale de `longueur` les segments de la ligne générée `ligne` (0 = première) situés à la
+ * colonne `colonne` ou après. Dans une ligne, seule la première colonne est absolue, les
+ * suivantes sont relatives : il suffit donc de corriger le premier segment concerné.
+ */
+export declare function decalerColonnes(mappings: string, ligne: number, colonne: number, longueur: number): string;

package/dist/vlq.js

@@ -0,0 +1,65 @@
+/**
+ * Le codage VLQ en base 64 des cartes de code (source maps, version 3), réduit à ce dont
+ * l'injection a besoin : décaler les colonnes d'une ligne générée quand on y insère du code.
+ * Sans dépendance. Le backend a son propre décodeur complet (backend/src/modules/carteCode.ts).
+ */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const VALEURS = new Map([...ALPHABET].map((c, i) => [c, i]));
+/** Lit une valeur VLQ à partir de `debut` ; rend la valeur et la position qui suit. */
+export function lireVlq(texte, debut) {
+    let resultat = 0;
+    let decalage = 0;
+    let i = debut;
+    for (;;) {
+        if (i >= texte.length)
+            throw new Error('VLQ tronqué');
+        const chiffre = VALEURS.get(texte[i++]);
+        if (chiffre === undefined)
+            throw new Error('VLQ invalide');
+        resultat += (chiffre & 31) * 2 ** decalage;
+        decalage += 5;
+        if (!(chiffre & 32))
+            break;
+        if (decalage > 35)
+            throw new Error('VLQ trop long');
+    }
+    const negatif = resultat % 2 === 1;
+    const valeur = Math.floor(resultat / 2);
+    return [negatif ? -valeur : valeur, i];
+}
+export function ecrireVlq(valeur) {
+    let reste = valeur < 0 ? (-valeur) * 2 + 1 : valeur * 2;
+    let sortie = '';
+    do {
+        let chiffre = reste & 31;
+        reste = Math.floor(reste / 32);
+        if (reste > 0)
+            chiffre |= 32;
+        sortie += ALPHABET[chiffre];
+    } while (reste > 0);
+    return sortie;
+}
+/**
+ * Décale de `longueur` les segments de la ligne générée `ligne` (0 = première) situés à la
+ * colonne `colonne` ou après. Dans une ligne, seule la première colonne est absolue, les
+ * suivantes sont relatives : il suffit donc de corriger le premier segment concerné.
+ */
+export function decalerColonnes(mappings, ligne, colonne, longueur) {
+    const lignes = mappings.split(';');
+    if (ligne >= lignes.length || !lignes[ligne])
+        return mappings;
+    const segments = lignes[ligne].split(',');
+    let absolue = 0;
+    for (let i = 0; i < segments.length; i++) {
+        if (!segments[i])
+            continue;
+        const [delta, fin] = lireVlq(segments[i], 0);
+        absolue += delta;
+        if (absolue >= colonne) {
+            segments[i] = ecrireVlq(delta + longueur) + segments[i].slice(fin);
+            break;
+        }
+    }
+    lignes[ligne] = segments.join(',');
+    return lignes.join(';');
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@astratra/centrale-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Outil en ligne de commande de Centrale LJ : identifiants de débogage dans les builds, envoi des cartes de code, déclaration des déploiements.",
+  "type": "module",
+  "bin": {
+    "centrale": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "prepack": "npm run build",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "astratra",
+    "centrale",
+    "source-maps",
+    "debug-id",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}