Explorando um app

Este guia cobre como ler e navegar em um app Bubble com a CLI do Buildprint: baixar uma branch, se orientar, aprofundar-se em páginas e elementos específicos e consultar material de referência.

O fluxo típico é: clonar uma branch, obter uma visão geral com summary e tree, aprofundar com context e find e recorrer a schema, docs e guidelines quando precisar de detalhes de referência.

Se oriente: buildprint quickstart

Execute isto primeiro. Ele imprime o playbook do agente Buildprint - o layout do workspace, os comandos principais e as convenções que a CLI espera que você siga - seguido do catálogo dos documentos de diretrizes disponíveis. Ele também informa quando a sua CLI instalada está atrás da versão mais recente no npm.

buildprint quickstart
buildprint quickstart | less

Encontre e clone um projeto

A raiz do app contém .buildprint/app.json e um .buildprint/remote.git vazio. Cada branch Bubble que você clona se torna um worktree git irmão em <app-root>/<branch>/, que é onde você edita os arquivos.

buildprint project list

Liste os projetos aos quais o seu token da CLI vinculada pode acessar.

buildprint project list
buildprint project list --json

--json imprime os mesmos campos da tabela em texto (não o payload bruto da API).

buildprint project info <appId>

Mostre os detalhes de um único app Bubble vinculado ao seu token atual.

buildprint project info <appId>
buildprint project info <appId> --json

buildprint project clone <appId>

Clone uma branch Bubble em <app-root>/<branch>/. A branch padrão é test (a branch editável usual do Bubble). A raiz do app usa como padrão um diretório com o nome do app ID; passe --dir para colocá-la em outro local. O workspace da branch é sempre <app-root>/<branch>/.

buildprint project clone <appId>
buildprint project clone <appId> --branch feature-x
buildprint project clone <appId> --dir ./my-app
buildprint project clone <appId> --branch live && buildprint project clone <appId> --branch test

Opções:

• --branch <name> - branch Bubble a ser clonada. O padrão é test. Execute buildprint branch list <appId> para ver os nomes disponíveis.

• --dir <path> - substitui o diretório raiz do app. O padrão é <appId>.

Você pode clonar várias branches do mesmo app sob uma única raiz de app; cada uma fica no seu próprio worktree <app-root>/<branch>/. Se uma branch já tiver histórico local, clone reutiliza esse histórico e lembra você de executar buildprint sync para baixar a captura mais recente do Bubble.

Depois de clonar, use cd para entrar no caminho do workspace mostrado. Os comandos abaixo são executados de dentro de um workspace de branch.

Liste as branches de um app

buildprint branch list <appId>

Imprima a árvore de branches Bubble de um app - útil antes de clonar ou para confirmar o nome de uma branch.

buildprint branch list <appId>
buildprint branch list <appId> --json

Você também pode inspecionar uma única branch em modo somente leitura. Sem argumentos dentro de um workspace, ele mostra a branch atual; caso contrário, passe um nome de branch (ou o app ID e o nome da branch de fora de um workspace).

buildprint branch
buildprint branch staging
buildprint branch <appId> staging

Criar e mesclar branches é uma operação de gravação e faz parte dos savepoints e dos fluxos de trabalho de branches, não daqui.

Obtenha uma visão geral: buildprint summary

Imprima um resumo amigável das superfícies de nível superior na branch local: páginas, visualizações mobile, elementos reutilizáveis, elementos globais, tipos de dados, conjuntos de opções, estilos e chamadas do conector de API.

buildprint summary
buildprint summary --json

Cada entrada aparece como Nome amigável [id Bubble] (caminho/relativo/de/arquivo.json), para que você possa ir direto de um nome ao seu arquivo ou passar o id e o caminho para context, tree ou find.

Inspecione a estrutura da UI: buildprint tree <target>

Imprima a árvore de elementos de uma página, visualização mobile, reutilizável ou subárvore de elemento como um contorno semelhante a YAML. É a forma mais rápida de entender como uma tela é construída.

O destino pode ser a chave de uma pasta de página ou reutilizável, um nome amigável ou um id de elemento.

buildprint tree home
buildprint tree home --include text,types,ids,paths
buildprint tree home --depth 2
buildprint tree myPage --cursor 250

Opções:

• --include <list> - lista separada por vírgulas do que mostrar. Primitivos disponíveis: text, types, ids, paths, layout, design, properties, workflows, actions. O padrão é types,ids,layout. Ao passar actions, workflows também é ativado.

• --depth <n> - profundidade máxima de elementos a partir do alvo. 0 mostra apenas o alvo.

• --cursor <n> - deslocamento de linha para paginação. As páginas têm 250 linhas; o rodapé da saída imprime o próximo cursor quando há mais conteúdo para ler.

Aprofunde-se em um nó: buildprint context <target>

Mostre um único nó e seus relacionamentos: o que o contém e o que ele contém, o que o aciona e o que ele aciona, o que ele referencia e o que o referencia, e os links de instanciação reutilizável. Para elementos, também imprime uma árvore de ancestrais e descendentes.

O destino pode ser um id de nó ou um caminho de arquivo JSON do workspace.

buildprint context page-home
buildprint context pages/home/elements/button/element.json
buildprint context wf-submit

Os destinos aceitos incluem um caminho de arquivo JSON do workspace (por exemplo pages/home/page.json), um diretório de nó (pages/home/elements/button), um id exato de nó (page-home, wf-submit), uma chave exata do mapa app-json ou caminho lógico (button, api.workflows.wf-submit), ou um nome exato de página, reutilizável, visualização mobile, elemento global, elemento, workflow ou ação. Quando um nome for ambíguo, use um id exato ou um caminho de arquivo; o comando lista os seletores candidatos para que você possa desambiguar.

Resolva ids para arquivos: buildprint find <ids...>

Resolva um ou mais ids do Buildprint ou do Bubble para os caminhos de arquivo do workspace que os definem ou referenciam. Passe vários ids de uma vez.

buildprint find page-home
buildprint find hero-id wf-submit action-0
buildprint find page-home --json

Cada id imprime o caminho de arquivo correspondente, além do que foi encontrado ali (tipo, nome, caminho lógico e localização dentro do arquivo). Um id sem correspondências imprime not found.

Referência: schema, docs e guidelines

buildprint schema [query...]

Pesquise o schema estático do Bubble - operadores, elementos e suas propriedades, ações, gatilhos, tipos e muito mais. Forneça uma consulta em texto livre, um ou mais filtros --category ou um filtro de contexto como --element-type; pelo menos um deles é obrigatório.

buildprint schema "append text"
buildprint schema --category actions
buildprint schema "count" --category operators --upstream-type list
buildprint schema --element-type Group --surface web_page
buildprint schema "api connector" --json

Opções:

• --category <category> - restringe as correspondências a uma ou mais categorias. Repita a flag para combinar. Categorias: operators, elements, element_properties, element_messages, workflows, types, data_types, option_sets, api_connector, api_connector_auth, actions, triggers.

• --limit <count> - número máximo de resultados.

• --upstream-type <value>, --element-type <value>, --action-type <value>, --workflow-type <value>, --data-type <value>, --owner-type <value>, --surface <value> - restringe os resultados a um contexto específico. As superfícies válidas são web_page, mobile_view, web_reusable e mobile_reusable.

• --json - imprime a resposta JSON bruta.

buildprint docs <namespace> <query...>

Leia a documentação pela CLI. O namespace escolhe a fonte; as palavras restantes são a consulta.

buildprint docs buildprint auth token
buildprint docs buildprint "how does version syncing work"
buildprint docs bubble

• buildprint docs buildprint <query...> pesquisa os docs do Buildprint. --limit <count> limita a quantidade de resultados (padrão 5).

• buildprint docs bubble retorna o payload llms.txt do Bubble e orientações de curl. Ele aceita uma consulta opcional para manter paridade com o namespace buildprint, mas a ignora.

buildprint guidelines

Liste e leia os documentos de diretrizes do Buildprint - as convenções que a CLI espera que você siga ao trabalhar em um workspace.

buildprint guidelines list
buildprint guidelines get
buildprint guidelines get general
buildprint guidelines get editing/apps schema/workflow
buildprint guidelines list --json
buildprint guidelines get testing/project-tests --json

• buildprint guidelines list imprime o catálogo de caminhos das diretrizes com resumos. Adicione --json para saída legível por máquina.

• buildprint guidelines get [paths...] busca um ou mais documentos pelo caminho. Sem caminho, retorna general. Passe vários caminhos para buscá-los juntos e adicione --json para saída estruturada.