BubbleScript

BubbleScript é uma representação textual legível de um app Bubble que permite que agentes de IA o entendam e construam.

O que é o BubbleScript

BubbleScript usa uma forma restrita de TypeScript para descrever conceitos do Bubble.

Ele não é código normal de aplicação e não é executado como JavaScript.

Por exemplo, um tipo de dados do Bubble pode ter esta aparência:

import { dataType, dataTypeRef } from "@buildprint/bubblescript";

export default dataType("Task", {
  fields: [
    { display: "Title", type: "text" },
    { display: "Owner", type: dataTypeRef("User") },
  ],
});

A estrutura clara e as informações de tipo facilitam para um agente entender os relacionamentos e produzir alterações precisas.

Vantagens

BubbleScript oferece aos agentes uma representação menor, mais clara e mais segura de um app Bubble do que o JSON bruto do Bubble.

Usa menos tokens

BubbleScript remove grande parte da estrutura repetida e dos detalhes de baixo nível encontrados no JSON do Bubble.

Isso significa que um app ou recurso usa menos da janela de contexto do agente. O agente pode inspecionar partes mais relevantes do app em uma única conversa e gastar menos tokens para entender o formato.

Funciona mais rapidamente

Arquivos menores levam menos tempo para um agente ler, pesquisar e atualizar.

A eficiência de tokens também reduz a quantidade de informações enviadas ao modelo e processadas por ele. Isso pode tornar a investigação e a edição mais rápidas, especialmente em apps Bubble grandes.

Melhora a precisão

BubbleScript fornece construtores, propriedades, referências e expressões tipados.

O agente consegue ver quais valores são válidos para o app atual, e buildprint check valida o resultado antes que ele chegue ao Bubble. Isso detecta nomes inválidos, tipos incorretos, referências ausentes e alterações não compatíveis.

Produz alterações melhores

BubbleScript é mais próximo do código-fonte que os agentes de programação são treinados para entender.

Arquivos claros, estruturas aninhadas, imports e referências tipadas ajudam o agente a acompanhar os relacionamentos em todo o app. Isso facilita fazer alterações específicas que se encaixam na estrutura existente.

Sem becos sem saída

Quaisquer erros de validação (diagnósticos) indicam os próximos passos, em vez de simplesmente gerar um erro. Por exemplo, se uma expressão for inválida, será informado qual tipo ela espera. Se uma opção de configuração da interface tiver um valor inválido, serão fornecidas as opções válidas possíveis e recomendações.

Princípios de design

BubbleScript foi projetado para ser legível por agentes e, ao mesmo tempo, manter as alterações precisas no Bubble.

Use nomes amigáveis sempre que possível

BubbleScript normalmente referencia páginas, elementos, tipos de dados, campos e valores de opções pelos nomes usados no Bubble.

dataTypeRef("Task")
element("Button save task")
option("Task Status", "Complete")

Os nomes tornam o código-fonte mais fácil de entender. Quando dois itens têm o mesmo nome, o BubbleScript pode incluir um ID estável para identificar o item correto.

Mantenha a identidade separada dos nomes de exibição

Um nó existente pode manter a mesma identidade quando seu nome no Bubble muda.

IDs estáveis conectam o código-fonte ao objeto existente no Bubble. Os agentes preservam esses IDs ao editar ou renomear um nó, enquanto novos nós geralmente podem deixar o Buildprint criar um ID automaticamente.

Represente os conceitos do Bubble diretamente

BubbleScript usa conceitos que correspondem ao editor do Bubble, como páginas, grupos, grupos repetidores, workflows, ações, tipos de dados e regras de privacidade.

Isso é mais fácil de entender do que o JSON de baixo nível do Bubble e ajuda um agente a raciocinar sobre o app nos termos do Bubble.

Isso significa que, quando o agente fala ou interage com o usuário, o usuário e o agente estão falando a mesma 'linguagem'.

Prefira código-fonte tipado

Construtores e métodos de expressão descrevem quais valores são válidos em cada local e permitem uma tipagem exata.

Por exemplo, uma fonte de dados de um grupo repetidor deve produzir uma lista do seu tipo de conteúdo, e uma condição de workflow deve produzir sim/não. Isso permite que o Buildprint encontre erros antes de aplicá-los.

Preserve o que ainda não foi tipado

BubbleScript mantém configurações do Bubble incompatíveis, corrompidas ou legadas dentro de rawBubble(...), em vez de descartá-las.

Os agentes preservam configurações brutas não relacionadas ao fazer uma alteração tipada. Isso permite que recursos mais recentes do Bubble e configurações incomuns do app sobrevivam a uma clonagem e sejam aplicados.

Organize o código-fonte como o app Bubble

Os arquivos seguem a propriedade e o comportamento definidos no Bubble.

As árvores de interface ficam com a página ou o elemento reutilizável. Os workflows de frontend ficam sob a raiz da interface que os contém. Tipos de dados, conjuntos de opções e workflows de backend têm suas próprias áreas.

Faça alterações pequenas e fáceis de revisar

Um agente deve alterar apenas o código-fonte necessário para a tarefa, preservando os IDs existentes, as configurações brutas e a estrutura não relacionada.

buildprint check mostra as alterações planejadas no Bubble antes que buildprint apply as grave.

O que o BubbleScript representa

Um workspace do BubbleScript pode descrever as partes compatíveis de um app Bubble.

• Páginas, elementos reutilizáveis, visualizações mobile e elementos globais

• Elementos, layout, estilos e condições responsivas

• Workflows de página, de elemento e de backend

• Tipos de dados, campos e regras de privacidade

• Conjuntos de opções e valores

• Expressões globais e textos do app

• Grupos e chamadas do API Connector

Os registros do banco de dados em tempo de execução não fazem parte do BubbleScript. Os agentes usam comandos de dados separados para inspecionar ou alterar registros.

Como um workspace é organizado

A clonagem de uma branch do Bubble separa o app em pastas que correspondem às áreas conhecidas do Bubble.

acme-app/
  Test/
    pages/
    reusable-elements/
    backend-workflows/
    data-types/
    option-sets/
    api-connector/
    mobile-views/

• pages contém páginas, elementos e workflows de página.

• reusable-elements contém elementos reutilizáveis.

• backend-workflows contém workflows de backend.

• data-types contém tipos de dados, campos e regras de privacidade.

• option-sets contém conjuntos de opções e valores.

• api-connector contém grupos e chamadas do API Connector.

• mobile-views contém visualizações mobile do Bubble quando o app as utiliza.

Um agente pode pesquisar e ler esses arquivos com as mesmas ferramentas que usa para uma base de código. Isso possibilita rastrear os relacionamentos em todo o app.

Como o BubbleScript se transforma em uma alteração no Bubble

O agente edita o BubbleScript localmente; em seguida, a CLI do Buildprint verifica e aplica as alterações.

Bubble editor
    ↓ clone or sync
BubbleScript files
    ↓ agent edits and checks
Bubble JSON
    ↓ apply
Bubble editor

buildprint check valida o código-fonte e mostra as alterações que ele produzirá. Ele não grava nada no Bubble.

buildprint apply compila o BubbleScript verificado em JSON do Bubble e o envia para a branch do Bubble selecionada.

Configurações incompatíveis e preservadas

BubbleScript expõe apenas as áreas do app que o Buildprint consegue representar e alterar com segurança.

Algumas configurações existentes do Bubble aparecem dentro de rawBubble(...). Isso preserva a configuração original do Bubble quando ainda não existe uma forma tipada correspondente no BubbleScript.

BubbleScript e o editor do Bubble

O BubbleScript e o editor do Bubble descrevem a mesma branch do app em formatos diferentes.

As alterações aplicadas pela CLI aparecem no editor do Bubble. As alterações feitas no editor retornam ao workspace quando o agente executa buildprint sync.

Isso permite que as pessoas continuem usando o Bubble normalmente enquanto os agentes trabalham com um formato de código-fonte projetado para uma inspeção e edição precisas.