> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migração de Configuração

> Sistema versionado de migração de configuração com backup automático, rollback e execução sequencial de migrações.

O ChatCLI inclui um sistema de **migração versionada de configuração** que garante upgrades seguros e automáticos entre versões. Quando o schema de configuração muda, as migrações são aplicadas sequencialmente, com backup completo antes de qualquer alteracao.

***

## Como Funciona

Cada versão do ChatCLI define um `CurrentConfigVersion`. Quando o usuário atualiza o binario, o sistema compara a versão salva com a versão atual e aplica as migrações necessarias:

```text theme={"system"}
v0 (sem arquivo de versão)
  -> migração v0 -> v1
v1 (CurrentConfigVersion)
  -> futuras migrações
v2, v3, ...
```

### Ciclo de Migração

<Steps>
  <Step title="Detecta necessidade">
    Compara versão atual com `CurrentConfigVersion`.
  </Step>

  <Step title="Cria backup">
    Salva configuração completa em `~/.chatcli/backups/config_backup_<timestamp>.json`.
  </Step>

  <Step title="Aplica migrações">
    Executa cada migração na sequencia (v0 -> v1, v1 -> v2, ...).
  </Step>

  <Step title="Atualiza versão">
    Grava a nova versão em `~/.chatcli/config_version.json`.
  </Step>

  <Step title="Em caso de falha">
    Preserva os valores originais e o backup permanece disponível.
  </Step>
</Steps>

***

## Migração v0 -> v1

A migração incluida normaliza configurações legadas:

| Transformacao      | Antes             | Depois                         |
| :----------------- | :---------------- | :----------------------------- |
| Normaliza provider | `openai`          | `OPENAI`                       |
| Renomeia API key   | `CHATCLI_API_KEY` | `OPENAI_API_KEY`               |
| Renomeia modelo    | `CHATCLI_MODEL`   | `OPENAI_MODEL`                 |
| Default skills     | (ausente)         | `CHATCLI_SKILLS_ENABLED=true`  |
| Default safety     | (ausente)         | `CHATCLI_SAFETY_ENABLED=false` |
| Default tool use   | (ausente)         | `CHATCLI_NATIVE_TOOL_USE=true` |

***

## API

### Verificar Necessidade de Migração

```go theme={"system"}
registry := config.NewMigrationRegistry(configDir, logger)
needs, current, target, err := registry.NeedsMigration()
if needs {
    fmt.Printf("Migração necessaria: v%d → v%d\n", current, target)
}
```

### Executar Migração

```go theme={"system"}
values := map[string]interface{}{
    "LLM_PROVIDER":    "openai",
    "CHATCLI_API_KEY": "sk-test",
}

result, err := registry.Migrate(values)
// result["LLM_PROVIDER"] == "OPENAI"
// result["OPENAI_API_KEY"] == "sk-test"
// result["CHATCLI_SKILLS_ENABLED"] == "true"
```

### Backup e Rollback

```go theme={"system"}
// Backup manual
path, err := registry.Backup(values)
fmt.Println("Backup salvo em:", path)

// Rollback
err = registry.Rollback(backupPath)
```

### Registrar Migração Custom

```go theme={"system"}
registry.Register(1, func(v map[string]interface{}) (map[string]interface{}, error) {
    // Migração v1 → v2
    v["NEW_FEATURE_ENABLED"] = "true"
    return v, nil
})
```

***

## Arquivo de Versão

A versão e armazenada em `~/.chatcli/config_version.json`:

```json theme={"system"}
{
  "version": 1,
  "migrated_at": "2026-03-04T14:30:00Z"
}
```

***

## Backups

Os backups são armazenados em `~/.chatcli/backups/` com timestamp:

```text theme={"system"}
~/.chatcli/backups/
|-- config_backup_20260304_143000.json
|-- config_backup_20260301.152.00.json
+-- ...
```

Cada backup contem o snapshot completo dos valores de configuração antes da migração.

***

## Segurança

<CardGroup cols={2}>
  <Card title="Atomicidade" icon="atom">
    Cada migração e aplicada sobre uma copia dos valores. Se falhar, os originais são preservados.
  </Card>

  <Card title="Sequencialidade" icon="list-ol">
    Migrações são executadas estritamente em ordem crescente de versão.
  </Card>

  <Card title="Backup obrigatório" icon="floppy-disk">
    Um backup e criado automaticamente antes de qualquer migração.
  </Card>

  <Card title="Idempotencia" icon="rotate">
    Se já estiver na versão atual, `Migrate()` retorna os valores inalterados.
  </Card>
</CardGroup>