Garty CLI

CLI interna para descobrir repositórios e resources FiveM e gerar, de forma segura, builds unidirecionais de OPEN para GARTY-CRIPTO.

Instalação pelo npm

Após a publicação, qualquer pessoa com Node.js 20+ poderá instalar globalmente:

npm install --global @rafaaa7/garty
garty --help

No PowerShell com política de scripts restrita, use:

npm.cmd install --global @rafaaa7/garty
garty.cmd --help

Instalação para desenvolvimento

Requer Node.js 20+ e pnpm.

pnpm install
pnpm build
pnpm add --global .
garty.cmd --help

No PowerShell com execução de scripts desabilitada, use pnpm.cmd no lugar de pnpm e garty.cmd no lugar de garty. Assim não é necessário alterar a política de execução do Windows.

Publicação no npm

Somente um mantenedor autenticado publica novas versões. Antes da primeira publicação, crie uma conta em npmjs.com, habilite 2FA e execute:

npm.cmd login
npm.cmd whoami
pnpm.cmd verify
npm.cmd run test:package
npm.cmd pack --dry-run
npm.cmd publish --access public

O pacote é publicado no escopo npm @rafaaa7/garty; o executável instalado continua se chamando garty. Para versões seguintes, atualize a versão sem reutilizar um número já publicado:

npm.cmd version patch   # incrementa a versão patch, por exemplo 1.1.1 -> 1.1.2
npm.cmd publish

Use minor para funcionalidade compatível e major para mudança incompatível. Nunca publique tokens npm no repositório ou em arquivos da aplicação.

Primeiro acesso e autenticação

Nenhum comando operacional funciona sem uma sessão autenticada. No primeiro uso, crie o administrador inicial — essa operação é permitida uma única vez:

garty admin bootstrap
garty login
garty whoami

O login solicita username e senha, e a sessão local expira após 12 horas. garty logout encerra a sessão imediatamente.

Os dados ficam no diretório local da Garty:

users.json       # perfis, roles, salt e hash scrypt; nunca contém senha em texto puro
session.json     # somente a sessão autenticada atual

No Windows, o diretório padrão é %APPDATA%\Garty.

Administração

Execute garty admin para abrir o menu:

1. Create user
2. Edit user
3. Delete user
4. List users
5. Exit

Também existem alternativas diretas, úteis para operação não interativa:

garty admin create
garty admin edit
garty admin delete
garty admin list

Somente usuários com role admin acessam essas operações. Os cargos aceitos são member e admin. A CLI impede excluir a própria conta ativa e impede excluir ou rebaixar o último administrador.

Desenvolvimento

pnpm dev -- --help
pnpm dev -- setup D:\Development\Garty

Durante o desenvolvimento, GARTY_HOME=C:\caminho\temporario pode isolar a configuração. Em uso normal, os arquivos ficam em %APPDATA%\Garty no Windows e em $XDG_CONFIG_HOME/garty (ou ~/.config/garty) no Linux/macOS.

Comandos

garty setup D:\Development\Garty [outra-root]
garty login
garty logout
garty whoami
garty admin
garty repos scan
garty repos scan D:\OutraPasta
garty repos list

garty build
garty build garty_inventory
garty build garty_inventory --dry-run
garty build --all
garty build garty_inventory --public client/config.lua
garty build garty_inventory --ignore client/debug.lua
garty build garty_inventory --no-encrypt-server

Referência completa

garty --help                         Mostra a ajuda geral
garty --version                      Mostra a versão instalada
garty --debug <comando>              Exibe detalhes técnicos de erros

garty admin bootstrap                Cria o primeiro administrador; uso único
garty login                          Inicia uma sessão local
garty logout                         Encerra a sessão atual
garty whoami                         Mostra usuário, role e expiração da sessão

garty admin                          Abre o menu administrativo interativo
garty admin list                     Lista usuários e roles
garty admin create                   Cria usuário member ou admin
garty admin edit                     Altera username, senha ou role
garty admin delete                   Exclui um usuário

garty setup [roots...]               Configura uma ou mais raízes de workspace
garty repos scan                     Reescaneia todas as raízes configuradas
garty repos scan [root]              Escaneia uma raiz específica
garty repos list                     Lista repositórios registrados

garty build                          Compila a única resource do repositório atual
garty build <resource>               Compila uma resource pelo nome
garty build --all                    Compila todas as resources do repositório atual
garty build <resource> --dry-run     Mostra o plano sem alterar arquivos
garty build <resource> --no-encrypt-client
garty build <resource> --no-encrypt-server
garty build <resource> --public <glob>
garty build <resource> --ignore <glob>

--public e --ignore podem ser repetidos. No PowerShell com execução de scripts bloqueada, substitua garty por garty.cmd em todos os exemplos.

Sem argumento, build usa o repositório atual e exige que ele tenha uma única resource. --all processa todas as resources do repositório atual. Nomes ambíguos nunca são escolhidos silenciosamente.

Layout das resources

A CLI descobre pares OPEN/GARTY-CRIPTO tanto na raiz quanto aninhados dentro do repositório Git. Nomes com colchetes também são suportados. Por exemplo:

repository/
└── release-package/
    └── [GARTY-RESOURCES]/
        ├── [OPEN]/                 # única fonte da verdade
        │   ├── resource-a/
        │   │   └── fxmanifest.lua
        │   └── resource-b/
        │       └── fxmanifest.lua
        └── [GARTY-CRIPTO]/         # artefato regenerável

Também funciona com OPEN e GARTY-CRIPTO sem colchetes. Um mesmo repositório pode possuir múltiplos pares; o caminho relativo da resource dentro de seu OPEN é preservado no GARTY-CRIPTO correspondente. Essa descoberta está isolada em OpenCriptoLocationResolver.

Arquitetura

Workspace roots
  → RepositoryScanner + RepositoryRegistry
  → ResourceScanner + ManifestParser
  → BuildPlanner (sem escrita)
  → BuildService (staging temporário + validação + troca)
  → Obfuscator (Mock no MVP; Garty API/Luraph no futuro)

Os handlers Commander só convertem argumentos em chamadas aos serviços. Git, filesystem, configuração, parsing, planejamento, execução, autenticação e API possuem fronteiras separadas.

Segurança

• OPEN nunca é gerado ou alterado pelo builder.
• GARTY-CRIPTO nunca é usado como entrada.
• globs absolutos ou com .. são rejeitados.
• symlinks não são seguidos pelos scanners/globs.
• o build completo é criado em .garty/tmp/<id> e validado antes da troca.
• se planejamento, obfuscação ou validação falhar, a saída anterior permanece intacta.
• operações destrutivas validam que o destino está dentro de uma raiz conhecida.

Testes

pnpm test               # testes unitários e de segurança
pnpm test:commands      # compila e testa cada comando em um workspace temporário
pnpm typecheck
pnpm verify             # executa toda a validação acima

Fixtures versionadas ficam em fixtures/workspace. O script de comandos copia a fixture para uma pasta temporária, inicializa Git, usa um GARTY_HOME isolado e remove tudo ao final.

Limitações atuais e futuro

• o parser suporta as declarações comuns client_script(s), server_script(s), shared_script(s) e file(s); ele não é um interpretador Lua;
• a troca da pasta usa renames no mesmo volume e rollback da saída anterior;
• a obfuscação é propositalmente MockObfuscator;
• autenticação local e RBAC estão implementados; autenticação centralizada pela futura Garty API ainda está pendente;
• ainda não há hashes, histórico persistido, garty check, --changed, CI mode ou executável standalone.

Próximas etapas naturais: implementar sessão via device login, provider remoto de obfuscação através da Garty API, metadata/hashes de build, check, --changed, auditoria e empacotamento standalone (por exemplo, Node SEA após validar compatibilidade das dependências).