Workspaces

Um workspace Buildprint é uma cópia local editável de uma branch de um app Bubble. Você clona uma branch, edita os arquivos fragmentados, valida o resultado e aplica as alterações de volta ao Bubble.

Um workspace mapeia para uma branch do Bubble. Se você quiser trabalhar em duas branches do mesmo app, mantenha-as como pastas de branches irmãs sob a mesma raiz de app.

Anatomia

Um app clonado possui uma raiz de app e um ou mais workspaces de branch:

my-app/
  .buildprint/
    app.json
    remote.git/
  test/
    .git
    .gitignore
    app.json
    settings/
    data_types/
    option_sets/
    styles/
    pages/
    element-definitions/
    mobile-views/
    global-elements/
    api/
    tests/
    issues/
  staging/
    ...

A raiz do app armazena o estado compartilhado do Buildprint para o app Bubble. Cada pasta de branch é uma git worktree real. O nome da pasta deve coincidir com a branch do git em checkout; comandos de alteração param com orientações se eles não coincidirem.

Não edite .buildprint/ manualmente. Os arquivos que você edita ficam dentro da pasta da branch.

Clonar uma branch

buildprint project clone <appId>
buildprint project clone <appId> --branch staging
buildprint project clone <appId> --branch live --dir ./my-app

A branch padrão é test. --dir define a raiz do app; o workspace da branch ainda é criado em <app-root>/<branch>/.

O clone cria uma nova raiz de app se necessário. Se a raiz do app já existir para o mesmo app, o clone reutiliza o histórico compartilhado e adiciona outra worktree de branch. A pasta da branch de destino deve estar vazia ou ausente; o clone não sobrescreverá conteúdo existente.

Use estes antes de clonar quando precisar inspecionar o acesso:

buildprint project list
buildprint project info <appId>
buildprint branch list <appId>

O loop normal

A maior parte do trabalho segue este loop de dentro da pasta da branch:

buildprint sync
git status
# edit files, or use buildprint new / buildprint copy
buildprint check
buildprint apply

sync busca o snapshot mais recente do Bubble, atualiza a referência local do snapshot do Bubble e faz o merge na branch atual. Ele também sincroniza o snapshot de tests/ global do app. Use buildprint sync --no-merge quando quiser buscar o snapshot, mas realizar o merge manualmente mais tarde.

check valida as alterações pendentes contra o snapshot atual do Bubble. Execute o buildprint check sem filtros antes do apply; verificações de caminhos específicos são úteis durante a edição, mas não satisfazem o critério de atualização para o apply.

apply exige um check sem filtros recente e bem-sucedido para as alterações pendentes atuais, a menos que você passe --force-apply. Ele faz o commit automático das edições não aplicadas do workspace quando necessário, compila o diff em gravações para o Bubble, envia definições de tests/ alteradas e avança as referências locais em caso de sucesso.

Quando sincronizar

Execute buildprint sync:

• Antes de iniciar um novo trabalho em uma branch existente.

• Após alguém editar a mesma branch do Bubble no editor do Bubble.

• Após restaurar um savepoint do Bubble.

• Antes de auditar ou revisar uma branch cujo estado remoto possa ter mudado.

Um sync limpo pode realizar um fast-forward ou criar um commit de merge normal. Se tanto o Bubble quanto a branch local alterarem os mesmos arquivos, o sync deixa marcadores de conflito comuns do git para você resolver.

Múltiplos workspaces de branch

Clone branches adicionais na mesma raiz do app:

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

Alterne entre as branches mudando de diretório, não fazendo checkout de uma branch diferente do git dentro de uma pasta de branch que pertença a outra branch do Bubble:

cd my-app/test
cd ../staging

Comandos que podem ser executados fora de um workspace

Estes comandos não exigem um workspace de branch:

• buildprint link <token>

• buildprint project list

• buildprint project info <appId>

• buildprint project clone <appId>

• buildprint branch list <appId>

• buildprint docs ...

• buildprint guidelines ...

• buildprint update

• buildprint mcp install ...

Alguns comandos aceitam flags explícitas de app e branch fora de um workspace, como buildprint login --app <appId> --branch <branch> e buildprint data ... --app <appId> --version <branch>.

Tudo o que lê ou altera arquivos locais do app, incluindo sync, check, apply, summary, tree, context, new, copy, savepoint, audit e a maioria dos comandos test-user, deve ser executado de dentro de um workspace de branch.

Proteções

O Buildprint protege contra os modos de falha comuns:

• A pasta da branch e a branch do git devem coincidir para comandos de workspace que realizam alterações.

• apply exige um buildprint check sem filtros recente e bem-sucedido para as alterações pendentes atuais.

• apply --no-check pula a reexecução interna, mas ainda exige o registro do check recente.

• apply --force-apply ignora a atualização do check e os portões de validação. Use-o apenas para recuperações excepcionais.

• Reduções ou crescimentos suspeitos de snapshots são bloqueados, a menos que você os permita explicitamente com sync --allow-suspicious-shrink ou apply --allow-large-apply.

• O clone recusa sobrescrever uma pasta de branch que não esteja vazia.

Limpeza

Um workspace de branch é apenas local. Para removê-lo, certifique-se de que o trabalho pendente foi aplicado ou intencionalmente descartado, então exclua a pasta da branch por fora dela:

rm -rf my-app/staging

Para remover toda a cópia local de um app, exclua a raiz do app. Nada é enviado para o Bubble ao excluir pastas locais.