Referência da CLI de pacotes
Comandos gamedev pkg para autores de pacotes: init, validate, pack, link, unlink, dev, logs, publish e publisher, com suas opções e saída.
A CLI gamedev reúne todas as ferramentas de que um autor de pacotes precisa: ela cria um novo pacote, o executa em um projeto real enquanto você edita, o verifica do mesmo modo que o app e o registro farão, monta o arquivo exato que os usuários instalam e o publica. init, validate, pack e logs funcionam sem login. link, unlink e dev alteram os pacotes de um projeto e exigem login, como toda alteração de pacote; publish exige login ou um token de publisher, e publisher exige login. Os comandos para usar pacotes (add, remove, update, settings …) estão na página da CLI.
gamedev pkg init [dir] [--engine] [--id <publisher.name>]
gamedev pkg validate [dir] [--json]
gamedev pkg pack [dir] [--out <dir>] [--allow-proposed] [--json]
gamedev pkg link <folder> [--user|--project|--local]
gamedev pkg unlink <id> [--user|--project|--local]
gamedev pkg dev <folder> [--user|--project|--local]
gamedev pkg logs <publisher.name> [-f|--follow] [--lines N]
gamedev pkg publish [dir] [--notes <file>] [--token <agd_pub_…>] [--oidc-audience <aud>] [--no-wait] [--json]
gamedev pkg publisher claim|list|token …Todo comando de autoria imprime seu uso com --help.
Criar um pacote: pkg init
Grava um novo pacote em uma pasta nova ou vazia (uma pasta .git é aceitável):
gamedev pkg init level-tools --id acme.level-toolsCreated acme.level-tools (a package) in /home/you/src/level-tools
aigd-package.json src/extension.ts dist/extension.js (prebuilt) src/types/aigd.d.ts (package API 0.4.0)| Arquivo | O que é |
|---|---|
aigd-package.json | O manifesto, com $schema para autocompletar |
src/extension.ts | Seu código: activate(ctx) e deactivate() |
dist/extension.js | Pré-compilado, para o pacote rodar antes da sua primeira build; main aponta para aqui |
src/types/aigd.d.ts, src/types/aigd-package.schema.json | Os tipos da API de pacotes e o schema do manifesto |
package.json, tsconfig.json | npm run build (src/ para dist/) e npm run dev (watch) |
README.md, .gitignore | Para você editar |
Sem --id, o publisher é you e o nome é o nome da pasta: coloque seu próprio publisher antes de compartilhar. --engine cria um pacote de game engine em vez disso.
Executá-lo em um projeto: pkg link, unlink e dev
link aponta um projeto para a sua pasta em vez de uma versão publicada, no nível local por padrão. A pasta é usada no próprio local, recarrega em todo app e CLI abertos quando um arquivo que ela distribui muda, e nunca é atualizada automaticamente. unlink volta para o que os outros níveis declararem, a partir do cache, sem download.
pkg dev é o pkg link para um pacote com etapa de build: ele executa o próprio script dev do pacote ou, sem ele, reexecuta seu script de build sempre que um arquivo que o pacote não distribui (suas fontes) muda, vincula a pasta após a primeira build bem-sucedida e encerra todos os processos que iniciou com Ctrl+C. O link permanece até você usar unlink.
Running its dev script (tsc -p tsconfig.json --watch --preserveWatchOutput). Ctrl+C stops it.
Waiting for its first build (dist/extension.js) before linking …
First build in 900 ms.
Linked acme.level-tools → ~/src/level-tools (local level, not committed).Uma pasta cujo manifesto indica outro id é recusada (id-mismatch); uma pasta movida é reportada junto com o caminho de volta.
Ler o log: pkg logs
Imprime as linhas de um pacote a partir do serviço em segundo plano do app, em ordem cronológica: tudo o que seu código registra (ctx.log, console.*) e as linhas do host sobre ele (ativação, falhas com seu stack). -f continua acompanhando; --lines N altera quantas linhas são mostradas inicialmente (100).
2026-11-16T10:12:03.114Z 41872 [10:12:03.114] INFO [core:pkg-host] pkg=acme.level-tools state=active ms=4
2026-11-16T10:12:03.118Z 41872 [10:12:03.118] INFO [pkg:acme.level-tools] activated
2026-11-16T10:12:09.502Z 41872 [10:12:09.502] ERROR [pkg:acme.level-tools] save failed: Error: EACCES …Verificá-lo: pkg validate
Executa as verificações que o app e o registro fazem, cada uma com seu arquivo e campo:
- o manifesto como o app o lê: o schema, ids de propriedade do pacote, cláusulas
when, configurações, menus, regras de game engine; - as regras do registro: um publisher, uma
versionsemver,engines.aigd; API proposta é apenas um aviso aqui (packepublisha recusam); - os arquivos que o manifesto indica (
main,icon, os ícones de uma engine, previews e skills de starter) entre os arquivos distribuídos; - o arquivo que o app instala: no máximo 20.000 arquivos e 512 MiB descompactado, caminhos que cabem em um cabeçalho tar, sem symlinks (ignorados, com um aviso). Os limites do próprio registro são mais rígidos: 5.000 arquivos, 64 MiB por arquivo, 200 MiB descompactado e 50 MiB compactado (veja Regras e verificações do registro).
acme.level-tools 0.1.0 (/home/you/src/level-tools)
error aigd-package.json contributes.commands[1].command: "level.export" must be "acme.level-tools.<id>"
error aigd-package.json main: "dist/extension.js" does not exist (build it first: npm run build)
5 files ship, 4.2 KB.
Not valid: 2 errors.Código de saída 0 quando válido (avisos permitidos), 1 em qualquer erro. --json imprime o resultado para CI.
Montar o arquivo: pkg pack
Valida e então grava o arquivo exato que o registro monta para a mesma pasta: determinístico (entradas ordenadas, datas e proprietários fixos), de modo que os mesmos arquivos geram os mesmos bytes e o mesmo hash de integridade em qualquer computador.
Packed acme.level-tools 0.1.0 → /home/you/src/level-tools/acme.level-tools-0.1.0.aigd.tgz
files 5 (4.2 KB unpacked)
size 2025 bytes
integrity sha512-ZrbOleD47onMM7hMss123CDMOEp5sAlDig7ISGpjhE6JT3btOAtFoWE2+DzSSoVQcfqzRj4seI1T2xajawpsIQ==
treeHash sha256-BTeAbus6JQO+VKxsSOjfGN9A0v+nkfdmtRiJ/KvNpug=O que é distribuído: tudo na pasta, exceto, no nível superior, src/, test/, tests/, coverage/, .turbo/, .agent-scratch/, .fixtures/, tsconfig*.json, vitest.config.*, *.tsbuildinfo, .aigd-install.json e *.tgz, e, em qualquer profundidade, node_modules/, .git/ e .DS_Store. O app nunca executa npm install para um pacote: empacote suas bibliotecas em dist/. --allow-proposed empacota um pacote que usa API proposta, apenas para uma origem GitHub, npm ou pasta.
Publicá-lo: pkg publish
Empacota (com as verificações e os bytes do pkg pack), envia ao registro da comunidade, depois aguarda suas verificações automáticas e imprime o relatório:
Packed acme.level-tools 0.1.0: 5 files, 2025 bytes, sha512-ZrbO…
Uploaded acme.level-tools 0.1.0 to ai-game.dev: uploaded
Waiting for the registry's checks (archive, manifest, rules, secrets, prompt injection, native code, virus scan)…
state: checking
state: published
Published acme.level-tools 0.1.0.| Opção | Efeito |
|---|---|
--notes <file> | Um arquivo Markdown (no máximo 20 KB) com as notas de versão desta versão; sem ele, a seção da versão em CHANGELOG.md |
--token <agd_pub_…> | Um token de publicador (ou a variável de ambiente AI_GAME_DEV_PUBLISHER_TOKEN) |
--oidc-audience <aud> | Substitui o audience OIDC do Trusted Publishing (ou AIGD_OIDC_AUDIENCE); a CLI o deriva do registro, ai-game.dev em produção |
--no-wait | Retorna após o upload |
--json | O resultado em JSON para scripts |
publish escolhe sua credencial nesta ordem: um token de publicador quando fornecido, depois o token OIDC do CI no GitHub Actions ou GitLab CI (Trusted Publishing, uma CLI mais recente que 0.32.0; dentro do CI, uma configuração ausente é um erro, não um fall-back), e então sua sessão autenticada. Executar publish novamente para uma versão já enviada lê suas verificações em vez de enviá-la duas vezes. Uma versão rejeitada sai com código 1 com cada verificação com falha e seu motivo. Canais e publicação a partir do CI sem token estão em Publicando pacotes e Trusted Publishing.
Gerenciar publicadores: pkg publisher
gamedev login # once, in the browser
gamedev pkg publisher claim acme --name "Acme Tools" # claim a publisher id
gamedev pkg publisher list # your publishers and your role
gamedev pkg publisher token create acme --label github-actions --days 90
gamedev pkg publisher token list acme
gamedev pkg publisher token revoke acme <token id>Um token é exibido uma única vez, dura no máximo 365 dias e só pode enviar, ler o status de uma versão e yank.
Páginas relacionadas
- Criando pacotes para o início rápido.
- Regras e verificações do registro para o que
validateepublishrecusam.