🔧 Instalação & Configuração

Node 20+, pnpm (gerenciado pelo campo packageManager do package.json raiz) e Rust toolchain estável com cargo. Plataformas: macOS, Linux ou Windows.

O monorepo combina TypeScript (workspace openhuman-app) com o crate Rust openhuman-core. Faltar qualquer toolchain quebra o build.

pnpm enforced via Corepack; Rust precisa de target nativo; macOS exige Xcode CLT; Linux exige libs de WebKit/CEF.

Contribuição é via fork de tinyhumansai/openhuman. origin aponta para o SEU fork; upstream para o repo oficial (fetch-only).

Push direto em tinyhumansai polui branches do upstream e ignora code review. Quem clonou upstream direto precisa renomear remotes uma vez.

Nunca trabalhar em main; branchar de upstream/main; PR sempre contra tinyhumansai/openhuman:main.

A raiz é um pnpm workspace com openhuman-repo (privado) e o subworkspace app/ que contém openhuman-app.

Rodar npm install ou yarn quebra a resolução. O packageManager impõe pnpm via Corepack.

Comandos rodam da raiz; pnpm dev delega para o workspace app; pre-push hooks do Husky rodam pnpm rust:check.

O runtime é CEF (Chromium Embedded Framework). Só a CLI vendorizada em app/src-tauri/vendor/tauri-cef/crates/tauri-cli empacota Chromium em Contents/Frameworks/.

A @tauri-apps/cli oficial gera bundle quebrado: panic em cef::library_loader::LibraryLoader::new. scripts/ensure-tauri-cli.sh garante a CLI correta automaticamente.

pnpm tauri:ensure roda antes de cada dev/build. Se sobrescrita: cargo install --locked --path app/src-tauri/vendor/tauri-cef/crates/tauri-cli.

Validar a lib openhuman e o binário openhuman-core compilam antes de subir a UI. O Cargo.toml raiz define o crate principal.

O core é a fonte de verdade da lógica de negócio. Falhas aqui aparecem como crashes silenciosos no Tauri.

cargo check --manifest-path Cargo.toml e cargo build --bin openhuman-core. Tauri shell tem Cargo.toml separado em app/src-tauri/.

Rodar pnpm typecheck, pnpm lint e pnpm format:check da raiz para confirmar que tudo compila e está formatado.

São os mesmos checks do CI. Passar localmente evita PR vermelho.

ESLint --cache; Prettier + cargo fmt; typecheck e compile são aliases (tsc --noEmit no workspace app).

Três camadas: .env raiz (Rust core + shell), app/.env.local (Vite/frontend) e TOML do core em src/openhuman/config/schema/.

Misturar camadas é o erro #1 de onboarding. Variáveis VITE_* NÃO funcionam no Rust; OPENHUMAN_* NÃO chegam no browser.

Só vars VITE_* são expostas ao browser. O TOML é carregado por src/openhuman/config/schema/load.rs com overrides por env.

Copiar .env.example para .env e carregar com source scripts/load-dotenv.sh. Tags [required] e [optional] indicam o que precisa preencher.

pnpm dev:app já roda load-dotenv.sh. Mas para rodar openhuman-core standalone ou cargo tests, você precisa exportar manualmente.

Variáveis cobrem backend URL, logging, proxy, storage, AI binary overrides. BACKEND_URL default é https://api.tinyhumans.ai.

Copiar app/.env.example para app/.env.local. Vars VITE_* definem RPC URL do core, backend, DSN do Sentry e helpers de dev.

No desktop, o usuário final NÃO precisa setar essas vars — configura tudo na tela de login. Em dev você quer o .env.local.

Default RPC: http://127.0.0.1:7788/rpc. Precedência runtime: tela de login > comando Tauri core_rpc_url > VITE_OPENHUMAN_CORE_RPC_URL > hardcoded.

app/src/utils/config.ts centraliza a leitura de variáveis VITE_* e re-exporta. Outros módulos consomem dessa única fonte.

Acessar import.meta.env em qualquer lugar fragmenta config. Mudanças quebram em pontos imprevisíveis.

Regra: nunca import.meta.env fora de config.ts. Refatorações tocam um arquivo só.

OPENHUMAN_CORE_TOKEN (bearer por launch), OPENHUMAN_WORKSPACE (redireciona storage), OPENHUMAN_CORE_REUSE_EXISTING=1 (anexa em core externo).

Em desktop o Tauri seta o TOKEN automático. Em Docker/cloud você precisa gerar (openssl rand -hex 32) e injetar.

Standalone: token escrito em {workspace}/core.token (0o600). E2E cria workspace temp limpo automaticamente.

OPENHUMAN_APP_ENV=staging aponta para backend staging e usa workspace ~/.openhuman-staging.

Isola dados de produção e bate em staging-api.tinyhumans.ai. Essencial para testar features de backend.

Mirror Vite: VITE_OPENHUMAN_APP_ENV=staging e VITE_BACKEND_URL=https://staging-api.tinyhumans.ai.

pnpm dev sobe só o Vite dev server. pnpm dev:app é o ciclo Tauri desktop completo com runtime CEF e core in-process.

Sem Tauri você não tem o core Rust — invokes de RPC falham. Use dev para iteração de UI pura.

dev:app carrega env via scripts/load-dotenv.sh e chama pnpm tauri:ensure antes.

Tauri spawna o core como tokio task em processo (CoreProcessHandle). RPC HTTP em 127.0.0.1:<port>/rpc autenticado por bearer hex.

PR #1061 removeu o sidecar binário. pnpm core:stage hoje é no-op (só echo).

Cmd+Q derruba o core junto com a GUI. Para debug standalone: ./target/debug/openhuman-core serve.

Wrappers em scripts/debug/ que limitam stdout a tamanho amigável de agente e teiam o log completo em target/debug-logs/.

Vitest/WDIO/cargo direto despejam centenas de linhas. Os wrappers cortam ao essencial e gravam o resto.

pnpm debug unit Foo, pnpm debug e2e smoke.spec.ts, pnpm debug rust, pnpm debug logs last --tail 100.

Mock backend em scripts/mock-api-server.mjs com admin endpoints (/__admin/health, /__admin/reset, /__admin/behavior).

Permite rodar testes sem rede real e sem flakes de timing. Usado por Vitest E2E e Rust tests via scripts/test-rust-with-mock.sh.

Rodar manualmente: pnpm mock:api. Para testes Rust: pnpm test:rust ou bash scripts/test-rust-with-mock.sh --test json_rpc_e2e.

pnpm typecheck (alias compile), pnpm lint, pnpm format e pnpm format:check cobrem TS + Rust simultaneamente.

Husky pre-push roda pnpm rust:check. Coverage gate exige ≥80% nas linhas alteradas — checks locais previnem retrabalho.

pnpm format roda Prettier write + cargo fmt. --no-verify só para breakage não relacionado.

Erros mais comuns: CLI errada (panic CEF), porta 7788 ocupada, token bearer divergente entre core e frontend.

90% dos problemas de onboarding caem em 3 categorias. Saber identificar economiza horas.

scripts/print-core-token.sh inspeciona o token ativo. Mudar porta com OPENHUMAN_CORE_PORT. CEF: reinstalar a vendored CLI.