Workspaces

Um workspace do Buildprint é uma cópia local de uma branch de um app do Bubble. Você clona uma branch em um workspace, edita os arquivos dentro dele, valida o resultado e aplica suas alterações de volta ao Bubble. Tudo o que o CLI faz em nome de uma branch acontece dentro do workspace dessa branch.

Anatomia

Um workspace é composto por duas pastas:

• A raiz do app (app root) — um diretório por app do Bubble. Ela mantém o estado interno do Buildprint (o histórico local do git do app) e é compartilhada por cada workspace de branch que você criar para esse app.

• A pasta da branch — um diretório irmão dentro da raiz do app, um por branch do Bubble. Esta é a pasta onde você realmente edita. É um git worktree: um checkout normal do git apoiado pelo histórico compartilhado da raiz do app.

my-app/                   # app root
  .buildprint/            # internal state, do not edit
  test/                   # branch workspace for Bubble branch "test"
    app.json
    pages/
    data_types/
    ...
  live/                   # branch workspace for Bubble branch "live"
    ...

Dentro de uma pasta de branch, você encontra arquivos e pastas normais: páginas, elementos reutilizáveis, views mobile, tipos de dados, option sets, estilos, chamadas do conector de API, workflows e ações. Veja File system para o layout completo.

Ciclo de vida

O ciclo de vida de um workspace tem quatro estágios. A edição em estado estável é o loop no meio — os dois pontos finais (clone e a destruição da pasta) ocorrem apenas uma vez.

1. Clonar a branch em um novo workspace.

2. Explorar e editar localmente. Leia os arquivos com ferramentas comuns; use summary, tree e context quando precisar navegar pelo app. Faça alterações com seu editor ou com new/copy.

3. Verificar e aplicar suas alterações commitadas de volta ao Bubble.

4. Sincronizar quando o Bubble mudar (não há necessidade de fazer isso após um apply, mas se o usuário indicar que fez alterações na branch do Bubble no editor, precisaremos sincronizar, pois essas alterações existem apenas no remoto).

1. Clonar a branch

buildprint project clone <appId> --branch <name>

Por padrão, isso cria <appId>/<branch>/ no diretório atual. Use --dir <path> para colocar a raiz do app em outro lugar. A branch padrão é test.

O que o clone faz:

• Se a raiz do app ainda não existir, ela será criada e o snapshot completo do Bubble será buscado para o histórico local do git.

• Se a raiz do app já existir para o mesmo app, o clone reutiliza o histórico local e apenas adiciona um novo worktree de branch. Se a branch for nova nesta raiz de app, o snapshot será buscado para essa branch.

• A pasta da branch deve estar vazia ou ausente. O clone recusa sobrescrever uma pasta existente — se já houver conteúdo nela, a ação correta é entrar nela (cd) e executar buildprint sync em vez disso.

2. Explorar e editar

De dentro da pasta da branch, você pode:

• Ler arquivos com seu editor, cat ou qualquer ferramenta git. Use git diff para revisar as alterações enquanto trabalha.

• Navegar com buildprint summary (superfícies de nível superior), buildprint tree <target> (subárvores de elementos e workflows) e buildprint context <target> (relacionamentos para um nó).

• Criar novas entidades com buildprint new (páginas, tipos de dados, workflows, ações e mais) e duplicar as existentes com buildprint copy. Esses comandos produzem JSON canônico e atualizam o cache do workspace no local.

• Editar qualquer outra coisa diretamente nos arquivos. A CLI não esconde nenhuma parte da superfície editável.

Faça commits com frequência. Commits pequenos tornam a etapa de aplicação mais fácil de entender e deixam um histórico limpo se você precisar reverter mais tarde.

3. Verificar e aplicar

Antes de enviar as alterações de volta ao Bubble, execute buildprint check para detectar problemas de sintaxe.

buildprint check
buildprint apply

O apply executa um portão de verificação interna primeiro, faz o commit automático de quaisquer alterações não commitadas, compara o diff com o snapshot do Bubble e envia um conjunto mínimo de atualizações para o Bubble. Em caso de sucesso, a referência do snapshot do Bubble avança para corresponder ao que o Bubble contém agora.

Veja Validando com check e Aplicando alterações para detalhes sobre as flags.

4. Sincronizar quando o Bubble mudar

buildprint sync

O sync busca o snapshot mais recente do Bubble para a branch atual e o mescla em seu workspace. Se nada tiver mudado, o sync não faz nada (no-op); se o Bubble avançou de forma limpa, é um fast-forward; caso contrário, você terá marcadores de conflito normais do git para resolver.

Execute o sync em duas situações:

• Antes de iniciar um novo trabalho, para que você comece a partir do estado atual do Bubble.

• Sempre que você suspeitar que o Bubble mudou sem seu conhecimento (alguém editou no navegador ou você restaurou um savepoint).

Múltiplos workspaces para o mesmo app

Você pode manter várias branches do mesmo app abertas ao mesmo tempo. Basta clonar cada uma na mesma raiz de app:

buildprint project clone my-app --branch test
buildprint project clone my-app --branch live

Os dois workspaces acabam como pastas irmãs sob my-app/. Alterne entre eles com cd. Cada pasta tem sua própria branch do git selecionada (checked out) e suas próprias alterações pendentes.

Trilhos de segurança

Alguns invariantes protegem você de erros óbvios:

• Pasta da branch = branch do git — imposto em cada comando de mutação.

• O apply é condicionado ao check — qualquer problema de nível de erro bloqueia o apply, a menos que você passe --no-check (não faça isso!).

• Reduções suspeitas são bloqueadas — o sync recusa substituir um workspace grande por um snapshot pequeno buscado, a menos que você permita explicitamente com --allow-suspicious-shrink. A mesma lógica se aplica ao apply --allow-large-apply na direção oposta.

• Não sobrescrever um alvo de clone não vazio — o clone solicita que você faça o sync em vez disso, caso a pasta já tenha conteúdo.

Limpando

Um workspace é apenas uma pasta. Para remover o workspace de uma branch:

1. Certifique-se de ter aplicado ou abandonado quaisquer alterações pendentes.

2. De fora da pasta da branch, delete-a com rm -rf <app-root>/<branch>.

Para excluir toda a cópia local de um app, remova a raiz do app inteira. Isso afeta apenas o seu workspace local — nada é enviado para o Bubble, e você pode executar buildprint project clone novamente a qualquer momento.

Onde os comandos devem ser executados

Quase todos os comandos da CLI esperam ser executados de dentro da pasta da branch. Estas são as exceções:

• buildprint link, buildprint project list, buildprint project info, buildprint project clone — não exigem um workspace.

• buildprint docs e buildprint guidelines — consultas de documentação, podem ser executados em qualquer lugar.

• buildprint branch list e buildprint branch create — funcionam de qualquer lugar, mas a forma de argumento único de branch create só resolve um ID de app quando você o executa dentro de uma raiz de app.

Todo o resto (sync, check, apply, tree, summary, context, new, copy, savepoint, schema) requer um workspace de branch.