Pular para o conteúdo principal
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: 
v0 (sem arquivo de versão)
  -> migração v0 -> v1
v1 (CurrentConfigVersion)
  -> futuras migrações
v2, v3, ...

​
Ciclo de Migração

1

Detecta necessidade

Compara versão atual com CurrentConfigVersion.
2

Cria backup

Salva configuração completa em ~/.chatcli/backups/config_backup_<timestamp>.json.
3

Aplica migrações

Executa cada migração na sequencia (v0 -> v1, v1 -> v2, …).
4

Atualiza versão

Grava a nova versão em ~/.chatcli/config_version.json.
5

Em caso de falha

Preserva os valores originais e o backup permanece disponível.

​
Migração v0 -> v1

A migração incluida normaliza configurações legadas:
TransformacaoAntesDepois
Normaliza provideropenaiOPENAI
Renomeia API keyCHATCLI_API_KEYOPENAI_API_KEY
Renomeia modeloCHATCLI_MODELOPENAI_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

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

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

// Backup manual
path, err := registry.Backup(values)
fmt.Println("Backup salvo em:", path)

// Rollback
err = registry.Rollback(backupPath)

​
Registrar Migração Custom

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: 
{
  "version": 1,
  "migrated_at": "2026-03-04T14:30:00Z"
}

​
Backups

Os backups são armazenados em ~/.chatcli/backups/ com timestamp: 
~/.chatcli/backups/
|-- config_backup_20260304_143000.json
|-- config_backup_20260301.139.00.json
+-- ...
Cada backup contem o snapshot completo dos valores de configuração antes da migração.

​
Segurança

Atomicidade

Cada migração e aplicada sobre uma copia dos valores. Se falhar, os originais são preservados.

Sequencialidade

Migrações são executadas estritamente em ordem crescente de versão.

Backup obrigatório

Um backup e criado automaticamente antes de qualquer migração.

Idempotencia

Se já estiver na versão atual, Migrate() retorna os valores inalterados.