Pacotes

Publicar um pacote

Do forge.toml ao registro: estrutura, empacotamento e versionamento.

A estrutura#

bash

meu-pacote/
├── forge.toml
├── README.md
├── src/
│   └── main.df        o ponto de entrada
└── tests/
    └── meu_pacote_test.df

O manifesto#

toml

[package]
name = "meu-pacote"
version = "1.0.0"
description = "Uma frase dizendo o que resolve."
authors = ["Seu Nome"]
license = "MIT"
entry = "src/main.df"
dataforge = ">=4.0"
keywords = ["cli", "texto"]

[dependencies]

[scripts]
test = "test tests/"

O nome usa minúsculas, dígitos, - e _, começando por letra. dataforge pack recusa o resto — nome de pacote vira caminho de arquivo e URL.

O que sai do pacote#

Só o que o relay exporta atravessa o adopt:

dataforge

action publica():
    yield interna() * 2

action interna():
    yield 21

relay publica          // 'interna' fica dentro do módulo

Sem nenhum relay, o módulo exporta tudo o que definiu no topo. Num pacote, declare relay explicitamente: é o que separa a API do detalhe de implementação.

Empacotar#

bash

dataforge pack

bash

✓ meu-pacote 1.0.0
  arquivo  dist/meu-pacote-1.0.0.tar.gz
  tamanho  3.4 KB
  sha256   1cf0908cfde283ef411139600d49f0cfee823d1d67120cab30f1918598f70ef5

Ficam de fora forge_modules/, .git/, __pycache__/, dist/ e .venv/. O tarball é reprodutível: mesma fonte, mesmo sha256 — é isso que torna a verificação de integridade possível.

Publicar#

bash

dataforge publish --registry=/caminho/do/registro

O registro é um índice estático: uma pasta com index.json e pacotes/. Publicar acrescenta seu tarball e atualiza o índice — daí você abre um PR.

Republicar a mesma versão é recusado. Suba a version no forge.toml primeiro: um lockfile que aponta para um conteúdo que mudou é pior que um erro.

Versionar#

Mudança	Sobe o quê	Exemplo
Corrigiu um bug	correção	1.0.0 → 1.0.1
Acrescentou algo	menor	1.0.1 → 1.1.0
Quebrou compatibilidade	maior	1.1.0 → 2.0.0

Quem depende de você escreveu ^1.0.0. Enquanto você não subir o maior, essa pessoa recebe suas versões automaticamente — e conta com que nada quebre.

Testes#

Um pacote sem teste não tem como provar que a próxima versão não quebrou nada:

dataforge

adopt Arcane.Test as T
adopt meu_pacote as M

action test_faz_o_que_promete():
    T.assert_eq(M.publica(), 42)

bash

dataforge test tests/

Um registro próprio#

Para uso interno numa empresa, aponte o cliente para outro índice:

bash

export DATAFORGE_REGISTRY=https://pacotes.suaempresa.com
dataforge search .

Basta servir estaticamente uma pasta com index.json e pacotes/. Não há servidor a manter.