Começando com o Jumentix

Responsabilidade no escopo

• Responsável por: rampa pública para juniores adotarem o Jumentix (modelo mental + primeira jornada)
• Camada: conceitos / caminho de aprendizado (não é um pacote de runtime)
• Usado com: geradora de fábrica @jumentix/cli-init, guias (REST, realtime, SPA/PWA), hub de pacotes públicos
• Não responsável por: docs de tooling privado do workspace (config-*, agent-registry, security-scanner)

O que é

Jumentix é um framework de fábrica de software: você descreve regras de negócio e contratos de API uma vez e gera/executa APIs REST, canais em tempo real e clientes offline a partir do mesmo núcleo. Esta página é a rampa de entrada para desenvolvedores júnior que nunca usaram Jumentix.

Por que existe

Times de produto costumam reconstruir a mesma infraestrutura — wiring HTTP, alinhamento OpenAPI, handlers WebSocket, sync IndexedDB — em todo projeto. Jumentix oferece um caminho repetível para você focar em lógica de domínio em vez de cola de adaptadores. Esta página leva do zero a um primeiro sucesso verificado em menos de 30 minutos.

Pré-requisitos

Instale o Bun se ainda não tiver:

curl -fsSL https://bun.sh/install | bash
bun --version

Leitura prévia (leia uma vez, volte quando um termo aparecer):

• Visão geral
• Arquitetura

Glossário

Passos numerados

Passo 1 — Instalar a toolchain (< 5 minutos)

1. Instale o Bun (veja Pré-requisitos).
2. Confirme o gate de versão: bun --version.

Verificação de sucesso: o comando sai com código 0 e imprime semver ≥ 1.4.2.

Passo 2 — Escolher o caminho inicial (< 2 minutos)

Escolha um caminho — não tente os dois no primeiro dia:

Para times que geram um workspace (recomendado):

npx @jumentix/cli-init init my-app \
  --preset=users --non-interactive --mode=monolith \
  --http=express --db=sqlite --install

Para times que só precisam de SDKs:

bun add @jumentix/cana @jumentix/sdk-rest-client

Para contribuidores no workspace completo:

cd Jumentix
bun install

Verificação de sucesso: o caminho de fábrica cria my-app/ com .jumentix/project.json; o caminho de packages completa bun install sem erros.

Passo 3 — Primeiro sucesso: init da fábrica (< 10 minutos)

A geradora pública é @jumentix/cli-init. Ela escreve um workspace Bun enxuto para um modo de fábrica (monolith / services / hybrid / frontend) a partir de um GenerationPlan (--preset=users, --from designer/OAS/catálogo).

npx @jumentix/cli-init init demo \
  --preset=users --non-interactive --mode=hybrid --frontend \
  --http=express --db=sqlite --install
 
cd demo
npx @jumentix/cli-init doctor
ls apps          # core (+ frontend no hybrid)

O que você deve ver:

• .jumentix/project.json — mode, plano, cohort de template (não o aposentado service-profile.json)
• .jumentix/manifest.json — sha256 dos arquivos gerados
• jumentix.init.json — respostas para round-trips com --config
• pacotes em apps/* prontos para bun run dev|test|lint|build

Depois estenda com jumentix add domain|service|frontend, atualize templates com jumentix upgrade e diagnostique com jumentix doctor. Os modos mapeiam para a matriz de capacidades da fábrica (doc JUMENTIX-SERVICE-FACTORY-CAPABILITIES-MATRIX.md no repositório).

Checagem de sucesso: demo/.jumentix/project.json existe, doctor sai com 0, e você nomeia a pasta do adapter HTTP em apps/.

Em seguida abra o guia REST e chame o serviço gerado.

Passo 4 — Aprender o modelo mental (< 5 minutos)

Mantenha esta figura visível enquanto lê os guias:

[ Adaptadores ]  Express / Fastify / Socket.IO / gRPC / IndexedDB (Cana)
      ↓
[ Aplicação ] casos de uso, portas
      ↓
[ Domínio ] entidades, regras, eventos

Três regras que evitam a maioria dos erros de júnior:

1. Contratos primeiro — OpenAPI / AsyncAPI / packages compartilhados descrevem a forma antes de ligar handlers.
2. Adaptadores são substituíveis — troque Express por Fastify sem reescrever o domínio.
3. Offline é de primeira classe — @jumentix/cana é o adaptador IndexedDB para PWAs; não é a mesma coisa que localStorage.

Passo 5 — Tocar o Cana no browser (< 10 minutos)

Antes de construir uma PWA offline completa, confirme que a toolchain de docs funciona. Execute o playground abaixo — Run deve retornar verde e Reset deve restaurar o estado inicial.

### Primeiros passos

```ts
const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};
```

const client = cana.createClient({
  name: dbName,
  schema: {
  version: 1,
  stores: [
    { name: 'categories', keyPath: 'id', indexes: [{ name: 'byName', keyPath: 'name', unique: true }] },
    {
      name: 'tasks',
      keyPath: 'id',
      indexes: [
        { name: 'byCategory', keyPath: 'categoryId' },
        { name: 'byCompleted', keyPath: 'completed' },
        { name: 'byUpdatedAt', keyPath: 'updatedAt' }
      ]
    }
  ]
}
});
await client.open();
await client.table('categories').add({
  id: 'work',
  name: 'Work',
  color: '#2563eb',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
await client.table('tasks').add({
  id: 'task-1',
  title: 'Write the Cana tutorial',
  categoryId: 'work',
  completed: false,
  priority: 'high',
  createdAt: Date.now(),
  updatedAt: Date.now()
});
return {
  backend: client.backend,
  category: await client.table('categories').get('work'),
  task: await client.table('tasks').get('task-1')
};

Verificação de sucesso: Run do playground completa sem erros; você vê registros IndexedDB criados no painel de saída.

Passo 6 — Fluxos centrais (esta semana)

Complete estes guias na ordem quando precisar de cada capacidade:

Passo 7 — Superfície completa (lookup, não tutoriais)

Exemplos

Chamada mínima de client REST (estático)

Injete o documento OpenAPI no browser — não carregue specs com fs do Node:

const client = api.createMockClient();
const result = await client.request({ method: 'GET', path: '/health' });
console.log(result.status, result.body);

Veja a versão interativa em Criar uma API REST.

Registro offline com Cana (estático)

const client = await cana.open({ name: 'my-app', version: 1 });
await client.put('tasks', { id: '1', title: 'Olá Jumentix' });
const task = await client.get('tasks', '1');
console.log(task.title);

Use o playground Cana no Passo 5 para executar este padrão ao vivo.

Erros comuns

Checklist júnior (“Eu consigo …”)

• Instalar Bun 1.4.2+ e confirmar bun --version.
• Explicar as camadas adaptador → aplicação → domínio usando o diagrama acima.
• Rodar jumentix init (ou npx @jumentix/cli-init init) e localizar .jumentix/project.json.
• Executar o playground Cana (Run verde, Reset restaura estado).
• Dizer a diferença entre OpenAPI (REST) e AsyncAPI (tempo real).
• Abrir o guia REST e saber que é minha próxima tarefa prática.
• Encontrar docs de pacotes e playgrounds em /docs/pt-BR/jumentix/packages.

Próximo passo

Vá para Criar uma API REST e complete o caminho hello-world de ponta a ponta — essa é a segunda página padrão da jornada de aprendizado.