Pular para o conteúdo principal

Compilando a partir do Código Fonte

O AISCouncil é um aplicativo HTML de arquivo único montado a partir de 80 arquivos fonte modulares em src/. Este guia cobre o pipeline completo de build, da compilação TypeScript à montagem final.

Pré-requisitos​

  • Node.js 20+ e npm
  • Bash (Linux/macOS, ou WSL no Windows)
  • Python 3.10+ (apenas para validação de registro)

Configuração​

Clone o repositório e instale as dependências de desenvolvimento:

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

Isso instala:

  • esbuild -- Remoção de tipos TypeScript (sem bundling)
  • vitest + jsdom -- Framework de testes
  • typescript -- Verificação de tipos (tsc --noEmit)
informação

Estas são dependências de desenvolvimento apenas. Nada de node_modules é enviado ao navegador. A saída de produção é um único index.html com zero dependências externas.

Passos de Build​

1. Compilação TypeScript​

Se você tem módulos TypeScript em modules/*/index.ts, compile-os primeiro:

npm run build:ts

Ou compile um único módulo:

node scripts/compile-ts.js grid
dica

O build.sh executa automaticamente a compilação TypeScript se o esbuild estiver instalado. Você só precisa executar npm run build:ts manualmente se quiser compilar sem montar.

2. Montagem​

Concatene todas as 80 partes fonte em index.html:

./build.sh

Saída:

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. Verificação​

Verifique se src/ corresponde ao index.html atual sem sobrescrever:

./build.sh --check

Saída em caso de correspondência:

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

Saída em caso de não correspondência:

MISMATCH: src/ does not match index.html

Pipeline TypeScript​

O pipeline TypeScript é um sistema leve de remoção de tipos, não um bundler.

Como Funciona​

Para cada módulo em modules/*/:

  1. Fonte: modules/{name}/index.ts -- Fonte TypeScript com tipos
  2. Wrapper: modules/{name}/wrapper.txt -- Template IIFE com placeholders {CODE} e {Name}
  3. Saída: src/{name}.js -- Bloco <script> pronto para concatenação

O script scripts/compile-ts.js:

  1. Lê a fonte TypeScript
  2. Chama esbuild.transformSync() para remover tipos (sem bundling, sem conversão de formato)
  3. Remove quaisquer statements import/export (o módulo é wrapped em uma IIFE)
  4. Indenta o código e o insere no template wrapper
  5. Se o código define __exports, anexa return __exports;

Template Wrapper​

Cada módulo TypeScript tem um wrapper.txt que define o envelope <script>:

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

O placeholder {Name} é substituído pelo nome do módulo capitalizado (ex: grid se torna Grid). O placeholder {CODE} é substituído pela fonte sem tipos e indentada.

Escrevendo Módulos TypeScript​

Use o padrão var __exports = {...} para a API pública do módulo:

// modules/mymodule/index.ts

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

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

var __exports = {
  doSomething,
};
aviso

Não use statements return soltos -- eles causam erros com tsc --noEmit. Use var __exports = {...} e compile-ts.js anexará return __exports; automaticamente.

aviso

Não defina format: 'esm' nas opções do esbuild. Isso causa wrapping CommonJS que quebra o padrão IIFE. O script de compilação omite intencionalmente a opção format.

Verificação de Tipos​

Execute o compilador TypeScript em modo apenas verificação (sem saída):

npm run check

Isso usa tsc --noEmit com o tsconfig.json do projeto. As definições de tipos estão em:

  • core-types/index.d.ts -- Tipos completos do namespace AIS
  • core-types/grid.d.ts -- Tipos específicos do Grid

Ordem dos Arquivos Fonte​

A ordem dos arquivos em build.sh é crítica. O array PARTS define a sequência exata de concatenação:

Shell (HTML/CSS/DOM):
  shell-head.html          # DOCTYPE, meta tags, redirecionamento antecipado
  shell-style.html         # Estilos CSS sem classes
  shell-body.html          # Corpo HTML, layout, diálogos, formulários

Core Modules (único bloco <script>):
  core-boot.js             # tag <script>, namespace AIS, event bus, lazy loader
  core-auth-main.js        # OAuth, Google Sign-In
  core-auth-local.js       # Contas locais, senha do dispositivo
  core-auth-init.js        # Wiring de UI de auth, init, export
  core-billing.js          # Nível de assinatura, trial
  core-ads.js              # Sistema de anúncios estático
  core-codec.js            # Base80, VLQ, compressão
  core-storage.js          # IndexedDB + SQLite
  core-providers.js        # Fábrica SSE, API de registro
  core-providers-builtin.js # Definições de provedores integrados
  core-ui.js               # Utils DOM, markdown, toast
  core-session.js          # CRUD de sessão de bot
  core-chat.js             # Mensagens, streaming
  core-config.js           # Painel de config de bot
  core-app-botlist.js      # Lista de bots, menu de contexto
  core-app-switch.js       # switchBot, createBot, mega menu
  core-app-events.js       # bindEvents, UI de council
  core-app-search.js       # Busca, export, import, addons
  core-app-init.js         # Helpers de Council, init, boot
  core-end.js              # </script>

WASM-Replaceable (cada um em seu próprio <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

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

Tail:
  shell-bottom.js          # Handler de tela de boas-vindas, tags de fechamento
aviso

Não reorganize a ordem dos arquivos. Módulos principais compartilham um único bloco <script> aberto por core-boot.js e fechado por core-end.js. Inserir um arquivo entre eles que contenha </script> quebrará o build.

Executando Testes​

A suíte de testes usa Vitest com ambiente jsdom.

# Executar todos os testes uma vez
npm test

# Executar testes em modo watch (re-executa em mudanças de arquivo)
npm run test:watch

# Executar apenas testes de módulos TypeScript
npm run test:modules

# Executar uma suíte de testes específica
npm run test:settings

Testes de worker rodam separadamente de dentro do diretório worker/:

cd worker
npm test

Fluxo de Trabalho de Desenvolvimento​

O ciclo padrão editar-compilar-testar:

# 1. Editar arquivos fonte
$EDITOR src/core-chat.js

# 2. Montar em index.html
./build.sh

# 3. Testar no navegador
# Abra index.html ou use um servidor local

# 4. Executar testes
npm test

# 5. Verificar integridade do build
./build.sh --check

Para módulos TypeScript:

# 1. Editar fonte TypeScript
$EDITOR modules/grid/index.ts

# 2. Verificar tipos
npm run check

# 3. Compilar + montar (build.sh faz ambos)
./build.sh

# 4. Testar
npm run test:modules

Adicionando um Novo Módulo​

Para adicionar um novo módulo de carregamento preguiçoso:

  1. Crie src/mymodule.js com o padrão padrão:
<script>
  if (!AIS.MyModule)
    AIS.lazy("MyModule", function () {
      "use strict";

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

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

  1. Adicione o arquivo ao array PARTS em build.sh na posição apropriada.

  2. Execute ./build.sh para verificar se monta corretamente.

Para adicionar um novo módulo TypeScript:

  1. Crie modules/mymodule/index.ts com o código fonte.
  2. Crie modules/mymodule/wrapper.txt com o template IIFE (copie de um módulo existente como modules/grid/wrapper.txt).
  3. Opcionalmente adicione definições de tipo a core-types/index.d.ts.
  4. Adicione src/mymodule.js ao array PARTS em build.sh.
  5. Execute ./build.sh.

Validação de Registro​

Os registros de modelos e pacotes têm scripts de validação:

# Validar registro de modelos
python3 registry/validate.py

# Validar registro de pacotes
python3 registry/validate.py packages

# Validar um manifesto único
python3 registry/validate.py manifest examples/hello-world/manifest.json

Kernel WASM (Opcional)​

O kernel WASM é um componente opcional. Compilá-lo requer Zig 0.14.0+:

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

O kernel não é necessário para o funcionamento da aplicação principal. Todas as funcionalidades do kernel têm fallbacks em JavaScript.