Recursos

Comece a usar o Orvienm

Clone o código-fonte público, instale a CLI, declare uma estrutura e então valide, planeje, aplique e confira.

Instalação

O Orvienm é distribuído como um Source-Access Alpha. Ainda não há entrada em índice de pacotes nem release binário, então pip install orvienm não vai resolver — a instalação é feita a partir do repositório público de código-fonte, orvienm-polaris. É necessário Python 3.10 ou mais recente.

Instalar a partir do código-fonte — Windows (PowerShell)

git clone https://github.com/kw13j1qs0/orvienm-polaris.git
cd orvienm-polaris
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install .

Instalar a partir do código-fonte — macOS e Linux

git clone https://github.com/kw13j1qs0/orvienm-polaris.git
cd orvienm-polaris
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

Para trabalhar na própria CLI, instale-a em modo editável com python -m pip install -e . e rode a suíte de testes que acompanha o projeto usando pytest.

Confirme que a CLI está no seu PATH e veja o que ela expõe.

Verificar a instalação

orvienm --version
orvienm --help

Declare uma estrutura

Crie um diretório de trabalho e coloque uma especificação nele. Uma especificação dá nome à estrutura e lista os diretórios que ela deve conter. structure.name é o diretório que o Orvienm vai criar, resolvido em relação a onde você roda o comando — então o arquivo abaixo produz platform/core, platform/data platform/docs.

.orvienm.yaml

version: 1

structure:
  name: platform
  directories:
    - core
    - data
    - docs

As entradas podem conter barras. Uma entrada aninhada como services/api também cria o diretório intermediário, e plan, verify doctor levam isso em conta.

Cada chave e regra que o formato aceita está listada na Referência da especificação.

Validate

A validação lê a especificação e a verifica. Nada toca o sistema de arquivos. Todos os outros comandos rodam isso primeiro, então uma falha aqui interrompe o ciclo.

Validar a especificação

orvienm validate .orvienm.yaml

Um arquivo válido imprime Validation successful e sai com 0. Um arquivo malformado imprime todos os problemas encontrados e sai com 1; a Solução de problemas explica cada mensagem.

Plan

O plan compara a estrutura declarada com o que está em disco e imprime a diferença. Ele não altera nada.

orvienm plan .orvienm.yaml

Orvienm Plan
────────────────────

+ create platform/
  + create core/
  + create data/
  + create docs/

Plan Summary
────────────────────
Create:     4
Keep:       0
Undeclared: 0

Depois que os diretórios existem, eles aparecem como keep. Um diretório que existe mas não foi declarado aparece como undeclared. O apply não o cria nem o remove — o plan não nomeia nenhuma operação que o engine não vá executar.

Apply

O apply cria a raiz e todos os diretórios declarados dentro dela. Diretórios que já existem ficam como estão, e diretórios que o Orvienm não declarou permanecem intactos.

Aplicar a estrutura

orvienm apply .orvienm.yaml

No primeiro apply bem-sucedido, o Orvienm escreve .orv.lock no diretório de trabalho, registrando o fingerprint dela. Use --dry-run para imprimir o que seria criado sem criar nada.

Verify e inspeção

O verify confere se todos os diretórios declarados existem e imprime Status: VALID ou Status: INVALID. Sai com 0 quando a estrutura está completa e com 2 quando não está, então serve diretamente como portão de pipeline.

Conferir e depois inspecionar o estado

orvienm verify .orvienm.yaml
orvienm status .orvienm.yaml
orvienm doctor .orvienm.yaml

O status acrescenta o lock file e o fingerprint ao quadro e sai com 2 se algo precisa de atenção. O doctor vai além e também reporta diretórios presentes em disco mas ausentes da especificação. Em um workspace que corresponde à sua especificação, os três estão limpos.

O doctor por padrão apenas reporta e sai com 0 independentemente do que encontra. Em um pipeline, use orvienm doctor .orvienm.yaml --strict, que sai com 2 diante de qualquer diagnóstico diferente de HEALTHY. A detecção é exatamente a mesma nos dois casos — só o código de saída muda.

O que acontece quando a especificação muda

Assim que .orv.lock existe, o Orvienm compara a especificação atual com o fingerprint registrado nele. Se forem diferentes, isso é desvio, e o apply se recusa a rodar: ele imprime Drift detected e sai com 3.

Isso é proposital. O lock registra a especificação a partir da qual o workspace foi construído, então uma especificação alterada precisa ser reconhecida antes de poder ser aplicada. Remova .orv.lock para aceitar a nova especificação e aplique de novo — o apply cria o que a mudança acrescentou, mantém tudo o que já estava lá e registra o novo fingerprint.

Remover o lock é hoje a única forma de aceitar uma mudança, e isso aceita todas as edições do arquivo de uma vez, não apenas aquela que você tinha em mente. Leia a especificação antes de remover o lock.

Note que desvio aqui significa que a especificação mudou, não que o sistema de arquivos mudou. Um diretório apagado à mão não gera desvio — quem revela isso são verify doctor.

Começar a partir de um scaffold

O orvienm new escreve um projeto de exemplo que você pode editar, em vez de começar de um arquivo em branco.

Gerar um projeto de exemplo

orvienm new my-project
orvienm validate my-project/.orvienm.yaml

Rode os comandos de ciclo de vida a partir do diretório que contém my-project/, e não de dentro dele: structure.name é resolvido em relação ao diretório de trabalho, então aplicar de dentro criaria uma segunda raiz aninhada.

O orvienm init é o outro caminho de entrada, e escreve a especificação onde você já está, em vez de dentro de um diretório novo. O nome que você der a ele é a raiz que ele declara.

Declarar uma estrutura no diretório atual

mkdir work && cd work
orvienm init platform
orvienm plan
orvienm apply

Isso produz work/.orvienm.yaml e work/platform/. O init apenas escreve a especificação — o apply é quem cria diretórios, aqui como em todo o resto — então o primeiro plan mostra a estrutura inteira como pendente e o segundo mostra Create: 0.