Atualizar um script

Ache o que está desatualizadoCopy Anchor Link

O aviso do console só cobre scripts iniciados e não ignorados, então verifique cada pasta:

cd "resources/[ai]"
for n in ai-*; do
  repo=$(sed -n 's#.*"repository": *"\(github:\|https://github.com/\)\([^"]*\)".*#\2#p' "$n/package.json" | sed 's#\.git$##')
  cur=$(sed -n 's#^  "version": *"\([^"]*\)".*#\1#p' "$n/package.json")
  latest=$(gh release view --repo "$repo" --json tagName --jq .tagName 2>/dev/null | sed 's#^v##')
  echo "$n $cur ${latest:-no-release}"
done

• Compare versões como o ai-core: tire um v do começo, compare os números separados por ponto, ignore sufixos de pré-release. Sem release, não há nada a atualizar.
• Sem gh: curl -s -H "Accept: application/vnd.github+json" https://api.github.com/repos/<owner>/<name>/releases/latest (60 requisições por hora por IP, divididas com a verificação do próprio ai-core).
• Um script em updates.ignore só é atualizado quando o dono o cita.
• Uma pasta com versão acima da última release, ou um clone com commits depois da última tag, não está desatualizada: pule, nunca leve uma pasta para trás.
• packages/ não tem linha repository: compare a versão de cada package.json com o npm. Atualize os pacotes primeiro quando uma nova release de script precisar de uma versão que as cópias locais não têm.

Leia as notas de versão e pegue o okCopy Anchor Link

Leia as notas de cada versão entre a atual e a mais recente (gh release view <tag> --repo <repo> --json body,assets,url): mudanças incompatíveis, versões de pacote exigidas, migrações, linhas de cfg novas (ensure, add_convar_permission, ACE), nomes provide novos, passos manuais.

Mostre a lista ao dono e espere o ok. Atualize na ordem das dependências: pacotes, ai-mysql, ai-core, ai-lib e depois o resto.

Baixe o upstream antigo e o novoCopy Anchor Link

Para cada script, duas pastas novas e vazias fora do servidor (por exemplo update/<name>/old e update/<name>/new):

gh release download <tag> --repo <owner>/<name> --archive zip --dir update/<name>/new     # código-fonte da tag
gh release download <tag> --repo <owner>/<name> --pattern '*.zip' --dir update/<name>/new # um asset da release, se houver
unzip -q update/<name>/new/*.zip -d update/<name>/new/x

• Prefira um asset da release quando a release tiver um; senão, o código-fonte da tag (ele inclui o dist/ e o fxmanifest.lua com commit). A pasta de cima do zip de código é <owner>-<name>-<sha>/.
• O upstream antigo é a tag da versão que o servidor usa (o padrão das tags aparece com gh release list --repo <owner>/<name>). Ela sempre pode ser baixada, então a comparação em três vias sempre tem sua base.
• Nada nessas pastas é executado, instalado ou compilado.

Faça o backupCopy Anchor Link

• Copie a pasta inteira do script, menos node_modules, para update/<name>/ours (no Windows robocopy "<src>" "<dst>" /E /XD node_modules; códigos de saída do robocopy abaixo de 8 significam sucesso). Isto é "o nosso" para o merge e o caminho de volta.
• Arquivos que o git ignora só existem nesta cópia: data/secrets.json, data/*.json.bak. Num clone git, git ls-files --others --ignored --exclude-standard lista esses arquivos.
• Mudanças sem commit num clone (git status --porcelain) também são mudanças do servidor. Avise o dono; faça commit delas só se ele pedir.

Faça o merge arquivo por arquivoCopy Anchor Link

Aplique o modelo de três vias ao antigo, ao nosso e ao novo, e escreva o resultado na pasta do script:

O conteúdo do painel (data/*.json) é o conteúdo vivo do servidor, editado no painel; a release só traz padrões.

• Mesmo schema (o novo schema.ts ou loader lê os mesmos campos): mantenha o nosso como está. Um arquivo que a nova versão adiciona: pegue o que veio.
• Schema mudou: procure a migração própria do script no start (notas de versão, uma migração chamada no start). Se houver, deixe o nosso no lugar; ela converte no start. Se não houver, converta à mão seguindo o novo loader e o schema: mesmos nomes de campo, tipos e formato de id do arquivo que veio, cada valor mantido, campos novos com o padrão que veio, campos removidos tirados e informados. Confira que cada arquivo faz parse.

Banco de dados. Cada script cria suas tabelas a partir de sql/main.sql no start: cria as tabelas que faltam e adiciona as colunas que faltam, e nunca apaga, renomeia ou muda uma coluna nem adiciona uma chave. Compare o sql/main.sql antigo e o novo:

• Tabelas e colunas novas: o reinício aplica.
• Um tipo de coluna alterado, um índice ou chave novos, uma coluna renomeada ou apagada: a release precisa trazer sua própria migração (notas de versão, código do servidor), que roda no start; confira o log. Se não trouxer, escreva o SQL, mostre ao dono, faça backup das tabelas afetadas e rode só com o ok dele.

Arquivos cfg fora da pasta.

• server.cfg: um script novo ganha sua linha ensure na ordem das dependências; um removido perde a dele (pergunte antes).
• env.cfg e env.example.cfg: um script que passa a usar o banco de dados precisa de add_convar_permission <resource> read mysql_connection_string.
• permission.cfg: as linhas ACE que as notas de versão pedem.
• security.cfg: nunca afrouxado.

Compile, reinicie, confiraCopy Anchor Link

1. bun install na raiz do servidor quando algum package.json mudar.

2. Em cada script atualizado: bun run typecheck, bun run lint, bun run build (ou bun tools/run.ts build ai-x ai-y na raiz do servidor). Sempre faça o build: o dist/ precisa vir do código após o merge. Corrija erros nas mudanças do servidor que você levou; um erro em código do upstream que ninguém tocou é informado, não remendado.

3. Compare o resultado com o upstream novo: diff -r --strip-trailing-cr -x node_modules -x dist -x data update/<name>/new/x/<top> "<script folder>". Cada diferença que sobrar precisa ser uma das mudanças do servidor.

4. Faça o refresh e reinicie:

   Copy Text

   bun tools/rcon.ts --log ../default/logs/fxserver.log --wait 3 "refresh"
   bun tools/restart.ts --from ai-inventory   # um script só
   bun tools/restart.ts                       # depois de atualizar ai-core, ai-lib, ai-mysql ou os pacotes

   bun tools/restart.ts reinicia o ai-core, faz ensure de cada ai-* que vem depois e confere que cada um iniciou. Scripts de terceiros que dependem do ai-mysql param junto com ele: faça ensure deles de novo pelo nome. Uma linha provide nova exige um start completo do servidor: bun tools/rcon.ts "quit \"<reason>\"".

5. Leia o log do console procurando SCRIPT ERROR, Failed to load script, [client error], erros de carregamento ou validação do painel e erros de banco de dados, não só Started resource. O aviso is outdated precisa sumir depois da próxima verificação do script.

Ligue a entrega ao que está instaladoCopy Anchor Link

• Cada pasta de primeiro nível com um fxmanifest.lua (ou __resource.lua) é um resource; uma pasta [category] contém vários. Descompacte zips numa pasta nova e vazia e não rode nada dali.
• Ache a cópia instalada pelo nome da pasta dentro de resources/ (por exemplo find resources -maxdepth 3 -type d -name <name>). Mantenha o local instalado, não a categoria da entrega. Nenhuma correspondência ou várias: pergunte ao dono. Um script ainda não instalado só é instalado se o dono disser.
• Uma pasta ai-* na entrega não segue este procedimento: scripts ai-* são atualizados pelo GitHub (acima). Pergunte ao dono o que é essa pasta.
• Leia os dois manifests: version, files, scripts, dependencies, provide, escrow_ignore, ai_replaces. Uma versão que desce, ou uma entrega sem arquivos que a cópia instalada tem, pode ser um build mais antigo: compare e informe em vez de instalar.
• Dependências novas: o oxmysql é atendido pelo ai-mysql (nunca instale o oxmysql junto); ox_lib e outras bibliotecas o dono instala; uma dependência de algo que o ai-core substitui (es_extended, qb-core, qbx_core, pma-voice, ox_inventory...) já está atendida.
• Mostre a lista ligada (nome, caminho, versão atual -> nova) e espere o ok.

Faça o backupCopy Anchor Link

• Copie a pasta instalada inteira para uma pasta de backup fora do servidor (robocopy "<src>" "<dst>" /E). Para uma pasta que nenhum repositório git acompanha, esse backup é a única cópia da versão do servidor.
• Se o git acompanha a pasta: git status --porcelain -- <path> mostra mudanças sem commit (contam como o nosso; avise o dono) e git ls-files --others --ignored --exclude-standard -- <path> mostra arquivos de execução ignorados pelo git (JSON salvo, caches), que estão no backup.

Ache as mudanças do servidorCopy Anchor Link

Pegue o upstream antigo, nesta ordem:

1. O dono ainda tem o zip ou a pasta antiga do vendedor.
2. Um script de código aberto no GitHub: a release ou a tag da versão instalada.
3. O histórico do git, quando a pasta é acompanhada: o commit que pôs a version instalada (git log -S"version '<old>'" -- <path>/fxmanifest.lua). Se esse commit também reaplicou personalizações anteriores, os arquivos de config dele contam como o nosso e a versão de fábrica pura está um commit antes.
4. Nada disso: compare o nosso direto com a nova versão e diga isso no relatório.

Depois leia cada diferença antigo -> nosso (as edições do servidor: configs, locales/* ou languages/*, arquivos editable, data/*.json, fxmanifest.lua, SQL, imagens, sons, arquivos de stream, patches de código) e antigo -> novo (as mudanças do vendedor: arquivos adicionados e removidos, chaves renomeadas, seções movidas, funções editable alteradas). Num script com escrow (tem .fxap) só os arquivos em escrow_ignore podem ser lidos e editados; uma edição num arquivo que a nova versão coloca em escrow não pode ser levada e é informada.

Instale a nova versãoCopy Anchor Link

Apague a pasta instalada por completo e copie a pasta nova para o mesmo caminho, arquivos ocultos (.fxap) incluídos. Sobras antigas são bugs; a versão antiga fica no backup. Restaure os arquivos de execução do backup só se a nova versão ainda os usa no mesmo formato; senão converta ou descarte e informe.

Reaplique as mudanças do servidorCopy Anchor Link

Para cada edição, ache onde essa configuração fica na nova versão e escreva o valor lá, no novo formato:

• Mesma chave, mesmo arquivo: coloque o valor no arquivo novo; mantenha os comentários e o layout dele.
• Chave renomeada ou movida: ache a chave nova lendo o código que a usa (procure o nome antigo, o comentário, o padrão, a chave de texto) e converta o valor para o novo formato.
• Config movida para um arquivo de dados (JSON editado pelo painel do próprio script): leia o novo loader e o arquivo que veio, escreva os valores antigos exatamente nesse schema (nomes de campo, tipos, formato de id, indentação) e confira que faz parse. Não confie num conversor que o script talvez rode.
• Os arquivos de dados existentes do servidor: leve-os, converta campo por campo se o schema mudou, nunca troque pelo exemplo do vendedor.
• Opção removida: nenhum código a lê mais (uma busca confirma): tire e informe com o valor antigo.
• Arquivos editable (client/editable.lua, server/editable.lua...): comece pelo arquivo novo e reaplique cada corpo de função alterado, adaptado a uma assinatura ou um retorno que mudou; funções novas ficam no padrão.
• Idiomas: mantenha a redação do servidor em cada chave que ainda existe; adicione as chaves novas em cada arquivo de idioma que o servidor usa, traduzidas no tom dos textos existentes; tire as chaves removidas; siga os placeholders alterados.
• fxmanifest: o novo, mais só os acréscimos próprios do servidor que ainda fazem sentido. Nunca mude version.
• SQL (*.sql, pastas de instalação): compare antigo e novo; tabelas, colunas e índices novos vão para o relatório como SQL que o dono roda. Nada roda sem o ok dele.
• Credenciais (tokens de bot, chaves de API, URLs de webhook nas configs): nunca mostre. Leve do backup; se não der, deixe o novo padrão e liste o arquivo e a chave para o dono.
• Assets (stream/, imagens, sons): os do vendedor, mais os arquivos que o servidor adicionou e que ainda são usados.
• Coordenadas, items, preços, textos e comportamento são levados exatamente; nada muda além das edições próprias do servidor.

Confira a compatibilidade com o ai-coreCopy Anchor Link

O script pode ser um dos que o ai-core conversa. Ache cada lugar que o cita:

grep -rln "<name>" "resources/[ai]/ai-core/resource" "resources/[ai]/ai-core/bridge" docs/compat

• Para cada export, event e callback que um adapter usa, confira a nova versão: ainda existe, mesmos argumentos, mesmo formato de retorno, mesmo momento. Em código com escrow, confira os arquivos legíveis e a documentação do vendedor e liste o que não dá para verificar.
• Uma incompatibilidade é corrigida só no arquivo do adapter (uma tradução fina), com a versão testada dele aumentada; depois typecheck, lint e build do ai-core e reinício (bun tools/restart.ts).
• Uma linha ai_replaces ou provide nova pode fazer o ai-core recusar conexões enquanto um substituto ai-* ainda roda (veja Substituindo um script ai-*): diga a pasta que o dono precisa remover.
• Atualize docs/compat/<script>.md (versão testada, status, config ou patch exatos, limites conhecidos); um script suportado sem nota ganha uma.

Verifique e reinicieCopy Anchor Link

• Compare o resultado instalado com a nova versão: cada diferença é uma mudança do servidor e não sobra nenhum arquivo antigo que a nova versão não traz (fora os arquivos de execução restaurados).
• O Lua editado faz parse, o JSON faz parse, cada chave de config definida existe no código novo.
• A menos que haja SQL esperando o dono: bun tools/rcon.ts --log ../default/logs/fxserver.log --wait 3 "refresh", depois o mesmo com "ensure <name>", e leia o log procurando SCRIPT ERROR, Failed to load script e os erros próprios do script. Scripts que dependem dele e pararam são iniciados de novo.