Migração de Configuração

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

Detecta necessidade

Compara versão atual com CurrentConfigVersion.

Cria backup

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

Aplica migrações

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

Atualiza versão

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

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:

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

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.188.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.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Migração de Configuração

Como Funciona

Ciclo de Migração

Migração v0 -> v1

API

Verificar Necessidade de Migração

Executar Migração

Backup e Rollback

Registrar Migração Custom

Arquivo de Versão

Backups

Segurança

Atomicidade

Sequencialidade

Backup obrigatório

Idempotencia

​Como Funciona

​Ciclo de Migração

​Migração v0 -> v1

​API

​Verificar Necessidade de Migração

​Executar Migração

​Backup e Rollback

​Registrar Migração Custom

​Arquivo de Versão

​Backups

​Segurança

Atomicidade

Sequencialidade

Backup obrigatório

Idempotencia

Como Funciona

Ciclo de Migração

Migração v0 -> v1

API

Verificar Necessidade de Migração

Executar Migração

Backup e Rollback

Registrar Migração Custom

Arquivo de Versão

Backups

Segurança