Aller au contenu principal

Construire Depuis les Sources

AISCouncil est une application HTML monofichier assemblée à partir de 80 fichiers sources modulaires dans src/. Ce guide couvre le pipeline de build complet, de la compilation TypeScript à l'assemblage final.

Prérequis​

  • Node.js 20+ et npm
  • Bash (Linux/macOS, ou WSL sur Windows)
  • Python 3.10+ (pour la validation du registre uniquement)

Configuration​

Clonez le référentiel et installez les dépendances de développement :

git clone https://github.com/nicholasgasior/bcz.git
cd bcz
npm install

Cela installe :

  • esbuild — Suppression de types TypeScript (pas de bundling)
  • vitest + jsdom — Framework de test
  • typescript — Vérification de types (tsc --noEmit)
info

Ce sont des dépendances de développement uniquement. Rien de node_modules n'est livré au navigateur. La sortie de production est un index.html unique avec zéro dépendance externe.

Étapes de Build​

1. Compilation TypeScript​

Si vous avez des modules TypeScript dans modules/*/index.ts, compilez-les d'abord :

npm run build:ts

Ou compilez un seul module :

node scripts/compile-ts.js grid
astuce

build.sh exécute automatiquement la compilation TypeScript si esbuild est installé. Vous n'avez besoin d'exécuter npm run build:ts manuellement que si vous voulez compiler sans assembler.

2. Assemblage​

Concaténez les 80 parties sources en index.html :

./build.sh

Sortie :

Compiling TypeScript modules...
  grid: modules/grid/index.ts -> src/grid.js
Compiled 1 module.
Built index.html (15432 lines, 982451 bytes) from 80 parts

3. Vérification​

Vérifiez que src/ correspond au index.html actuel sans écraser :

./build.sh --check

Sortie si correspondance :

OK: src/ matches index.html (80 parts)

Sortie si non-correspondance :

MISMATCH: src/ does not match index.html

Pipeline TypeScript​

Le pipeline TypeScript est un système léger de suppression de types, pas un bundler.

Comment Ça Fonctionne​

Pour chaque module dans modules/*/ :

  1. Source : modules/{name}/index.ts — Source TypeScript avec types
  2. Wrapper : modules/{name}/wrapper.txt — Template IIFE avec placeholders {CODE} et {Name}
  3. Sortie : src/{name}.js — Bloc <script> prêt à concaténer

Le script scripts/compile-ts.js :

  1. Lit la source TypeScript
  2. Appelle esbuild.transformSync() pour supprimer les types (pas de bundling, pas de conversion de format)
  3. Supprime toutes les instructions import/export (le module est enveloppé dans une IIFE)
  4. Indente le code et l'insère dans le template wrapper
  5. Si le code définit __exports, ajoute return __exports;

Template Wrapper​

Chaque module TypeScript a un wrapper.txt qui définit l'enveloppe <script> :

<script>
  // ============================================================================
  // MODULE: AIS.{Name} (compiled from TypeScript)
  // ============================================================================
  if (!AIS.{Name}) AIS.lazy('{Name}', function() {
  'use strict';
  {CODE}
  });
</script>

Le placeholder {Name} est remplacé par le nom de module capitalisé (ex., grid devient Grid). Le placeholder {CODE} est remplacé par la source sans types et indentée.

Écrire des Modules TypeScript​

Utilisez le pattern var __exports = {...} pour l'API publique du module :

// modules/mymodule/index.ts

interface MyConfig {
  name: string;
  value: number;
}

function doSomething(config: MyConfig): string {
  return config.name + ": " + config.value;
}

var __exports = {
  doSomething,
};
avertissement

N'utilisez pas d'instructions return seules — elles causent des erreurs avec tsc --noEmit. Utilisez var __exports = {...} et compile-ts.js ajoutera return __exports; automatiquement.

avertissement

Ne définissez pas format: 'esm' dans les options esbuild. Cela cause un wrapping CommonJS qui casse le pattern IIFE. Le script de compilation omet l'option format intentionnellement.

Vérification de Types​

Exécutez le compilateur TypeScript en mode vérification uniquement (pas de sortie) :

npm run check

Cela utilise tsc --noEmit avec le tsconfig.json du projet. Les définitions de types sont dans :

  • core-types/index.d.ts — Types complets de l'espace de noms AIS
  • core-types/grid.d.ts — Types spécifiques à Grid

Ordre des Fichiers Sources​

L'ordre des fichiers dans build.sh est critique. Le tableau PARTS définit la séquence exacte de concaténation :

Shell (HTML/CSS/DOM):
  shell-head.html          # DOCTYPE, meta tags, redirection anticipée
  shell-style.html         # Styles CSS sans classes
  shell-body.html          # Corps HTML, layout, dialogues, formulaires

Core Modules (bloc <script> unique):
  core-boot.js             # Balise <script>, espace de noms AIS, bus d'événements, lazy loader
  core-auth-main.js        # OAuth, Google Sign-In
  core-auth-local.js       # Comptes locaux, mot de passe d'appareil
  core-auth-init.js        # Câblage UI d'auth, init, export
  core-billing.js          # Niveau d'abonnement, essai
  core-ads.js              # Système de pub statique
  core-codec.js            # Base80, VLQ, compression
  core-storage.js          # IndexedDB + SQLite
  core-providers.js        # Factory SSE, API d'enregistrement
  core-providers-builtin.js # Définitions des fournisseurs intégrés
  core-ui.js               # Utils DOM, markdown, toast
  core-session.js          # CRUD de session de bot
  core-chat.js             # Messages, streaming
  core-config.js           # Panneau de config de bot
  core-app-botlist.js      # Liste de bots, menu contextuel
  core-app-switch.js       # switchBot, createBot, mega menu
  core-app-events.js       # bindEvents, UI de conseil
  core-app-search.js       # Recherche, export, import, addons
  core-app-init.js         # Helpers de conseil, init, boot
  core-end.js              # </script>

Remplaçables par WASM (chacun dans son propre <script>):
  registry.js, grid.js, council.js, wizard.js,
  vision.js, memory.js, imagegen.js, tools.js,
  reminders.js, themes.js, templates-registry.js,
  model-picker.js

Infrastructure:
  kernel-bootstrap.html, moduleloader.js, plugins.js,
  mcp.js, channels-*.js, sandbox.js, publish.js,
  perf.js, p2p.js, profiles.js, cron.js

Plateforme:
  settings-main.js, i18n.js, miniprograms.js,
  docs.js, billing-ui.js, pwa.js

Tail:
  shell-bottom.js          # Gestionnaire d'écran de bienvenue, balises de fermeture
avertissement

Ne réorganisez pas l'ordre des fichiers. Les modules core partagent un seul bloc <script> ouvert par core-boot.js et fermé par core-end.js. Insérer un fichier entre eux qui contient </script> cassera le build.

Exécuter les Tests​

La suite de tests utilise Vitest avec un environnement jsdom.

# Exécuter tous les tests une fois
npm test

# Exécuter les tests en mode watch (ré-exécution sur changements de fichiers)
npm run test:watch

# Exécuter uniquement les tests de modules TypeScript
npm run test:modules

# Exécuter une suite de tests spécifique
npm run test:settings

Les tests de Worker s'exécutent séparément depuis le répertoire worker/ :

cd worker
npm test

Workflow de Développement​

Le cycle standard éditer-construire-tester :

# 1. Éditer les fichiers sources
$EDITOR src/core-chat.js

# 2. Assembler en index.html
./build.sh

# 3. Tester dans le navigateur
# Ouvrir index.html ou utiliser un serveur local

# 4. Exécuter les tests
npm test

# 5. Vérifier l'intégrité du build
./build.sh --check

Pour les modules TypeScript :

# 1. Éditer la source TypeScript
$EDITOR modules/grid/index.ts

# 2. Vérifier les types
npm run check

# 3. Compiler + assembler (build.sh fait les deux)
./build.sh

# 4. Tester
npm run test:modules

Ajouter un Nouveau Module​

Pour ajouter un nouveau module chargé à la demande :

  1. Créez src/mymodule.js avec le pattern standard :
<script>
  if (!AIS.MyModule)
    AIS.lazy("MyModule", function () {
      "use strict";

      function doWork() {
        /* ... */
      }

      return { doWork };
    });
</script>

  1. Ajoutez le fichier au tableau PARTS dans build.sh à la position appropriée.

  2. Exécutez ./build.sh pour vérifier qu'il s'assemble correctement.

Pour ajouter un nouveau module TypeScript :

  1. Créez modules/mymodule/index.ts avec le code source.
  2. Créez modules/mymodule/wrapper.txt avec le template IIFE (copiez depuis un module existant comme modules/grid/wrapper.txt).
  3. Optionnellement ajoutez des définitions de types à core-types/index.d.ts.
  4. Ajoutez src/mymodule.js au tableau PARTS dans build.sh.
  5. Exécutez ./build.sh.

Validation du Registre​

Les registres de modèles et de packages ont des scripts de validation :

# Valider le registre de modèles
python3 registry/validate.py

# Valider le registre de packages
python3 registry/validate.py packages

# Valider un seul manifeste
python3 registry/validate.py manifest examples/hello-world/manifest.json

Kernel WASM (Optionnel)​

Le kernel WASM est un composant optionnel. Le construire nécessite Zig 0.14.0+ :

cd kernel
../tools/zig/zig build    # sorties zig-out/bin/kernel.wasm (~5.5 Ko)

Le kernel n'est pas requis pour que l'application principale fonctionne. Toutes les fonctionnalités du kernel ont des fallbacks JavaScript.