# Cockpit — portabilidade e instalador inteligente

Data: 2026-10-11
Projeto: `STACK-NINJA/02-PROJETOS/cockpit`
Escopo desta fase: **contratos, arquitetura e fundação local segura** (missao, secao 6).

## 1. Objetivo

Permitir que o Cockpit seja executado em outro computador a partir de um pacote
canônico distribuído pelo Google Drive, sem reescrever o produto e sem prometer
suporte a plataformas ainda não testadas.

Fluxo desejado:

**Diagnosticar → Preparar → Adaptar → Validar → Trabalhar**

## 2. Estado desta fase

| Etapa | Estado | Evidência |
|---|---|---|
| Diagnosticar | IMPLEMENTADO | `scripts/diagnose_env.py` (read-only, sem rede, sem credenciais) |
| Preparar | FUNDação | `INSTALL.ps1` já localiza/cria venv, instala deps e cria `.env` |
| Adaptar | FUNDação | perfil operacional derivado da máquina medida (CAR) |
| Validar | PARCIAL | migrations com checksum, `tests/`, verificação de porta única |
| Trabalhar | CONCLUÍDO hoje | startup local, login Argon2id e interface preservada |

Não existe instalador multiplataforma completo e ele **não** será prometido
antes de infraestrutura e testes adequados.

## 3. Contratos

### 3.1 Pacote canônico

Identidade lógica única: `cockpit-pacote`. Conteúdo admitido:

- Código do projeto (árvore `02-PROJETOS/cockpit`).
- `requirements.txt`, `INSTALL.ps1`, `README.md` e esta documentação.
- `migrations/*.sql` (somente aditivas, com checksum registrado).
- `.env.example` (sem credenciais).
- Opcionalmente: perfil operacional e backups explícitos.

Conteúdo **nunca** incluído no pacote: `.env` com hash de senha, `token.pickle`,
`credentials.json`, banco ativo (`data/cockpit.db`) e `.venv`.

### 3.2 Papel do Google Drive

- Distribui instalador, documentação, versões, configurações portáteis e backups.
- Banco, cache e temporários ficam em armazenamento **local** (`data/`).
- Nunca usar arquivo sincronizado como banco de dados ativo.
- Não mover o banco existente sem análise de impacto, backup e autorização.

### 3.3 Perfil operacional adaptativo

O diagnóstico produz um perfil derivado da máquina medida (CPU, RAM, disco,
instalação anterior, portas), nunca de um número universal:

- `profile`: `reduzida` | `padrao` | `ampliada`
- `max_concurrency`: calculado por `core.car.base_concurrency()`
- `pending_preparation`: lista objetiva do que falta preparar

### 3.4 Validação e rollback

1. Antes de qualquer migração: backup consistente do banco (`backups/`).
2. Migrations são aditivas e verificadas por checksum.
3. Falha de validação ⇒ interromper e informar; nunca "consertar" apagando dados.
4. Rollback = restaurar backup e manter as migrations anteriores intactas.

## 4. Componentes reutilizáveis identificados

| Componente | Papel no instalador |
|---|---|
| `INSTALL.ps1` | Preparar: venv + dependências + `.env` |
| `scripts/set_password.py` | Definir senha local sem expor segredo |
| `scripts/diagnose_env.py` | Diagnosticar (read-only) |
| `core/migrations.py` | Validar schema com checksum |
| `core/car.py` | Adaptar: perfil e limites de recursos |
| `tests/` | Validar integridade após instalação |

## 5. Fases futuras (não implementadas agora)

1. **Pacote versionado** — empacotar a árvore canônica com hash por versão.
2. **Preparação automática** — instalar somente o que falta, reutilizar `.venv`
   e banco válidos; evitar instalações duplicadas.
3. **Adaptação** — aplicar perfil operacional e caminhos locais adequados.
4. **Validação** — rodar migrations, suíte de testes e checagem de porta única.
5. **Atualização/recuperação** — atualização incremental com rollback.
6. **Outras plataformas** — apenas após testes reais na plataforma; nenhuma
   promessa de suporte antes disso.

## 6. Regras permanentes

- Não recriar o produto nem duplicar estruturas.
- Não substituir tecnologia por novidade (missao, secao 2).
- Não iniciar segundo servidor quando já houver listener ativo
  (`core.car.claim_instance` registra a duplicidade sem encerrar processo).
- Não ler nem exibir credenciais.
- Qualquer mudança persistente em sistema operacional é proposta separadamente.

## 7. Critérios de validação desta fase

- [x] `scripts/diagnose_env.py` executa em máquina real e produz JSON.
- [x] Nenhuma escrita fora do caminho `--out` explicitamente pedido.
- [x] Suíte de testes aprovada (inclui `tests/test_portability.py`).
- [x] Nenhum serviço externo iniciado, nenhum processo encerrado.
- [ ] Pacote canônico versionado (fase futura 1).
- [ ] Instalação em segunda máquina (fase futura 2) — **não testado, não prometido**.