Extensões

A CLI do Buildprint fornece aos agentes as ferramentas para criar, publicar, inspecionar e gerenciar Extensions.

Nos bastidores, uma Extension é uma aplicação do Cloudflare Worker. Uma implantação pode conter:

• Código personalizado do Worker.

• Ativos estáticos.

• Código personalizado e ativos estáticos.

Uma Extension também pode ter um banco de dados D1 e um bucket R2. O D1 é vinculado como DB, o R2 como BUCKET e os ativos estáticos como ASSETS.

Arquivos locais

Cada Extension é armazenada em extensions/<slug> no projeto clonado.

O campo entry adiciona código personalizado do Worker. O campo assets adiciona arquivos estáticos. Pelo menos um deles deve estar presente.

Esta Extension combinada tem código, ativos estáticos e ambos os recursos:

{
  "slug": "customer-portal",
  "name": "Customer portal",
  "entry": "src/index.ts",
  "assets": {
    "build": "bun run build",
    "output": "dist"
  },
  "resources": ["database", "bucket"]
}

Uma Extension somente de ativos omite entry:

{
  "slug": "docs",
  "name": "Product docs",
  "assets": {
    "output": "."
  }
}

Uma Extension somente de código omite assets:

{
  "slug": "webhooks",
  "name": "Webhook service",
  "entry": "src/index.ts",
  "resources": ["database"]
}

Recursos, migrações e secrets de runtime exigem código personalizado do Worker. A CLI rejeita recursos duplicados e configurações que não contenham código nem ativos.

Lidar com código e ativos em conjunto

O Buildprint executa o código personalizado do Worker antes do fallback de ativos. O Worker escolhe quais solicitações usam lógica personalizada e quais usam ativos estáticos.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname.startsWith("/api/")) {
      return handleApi(request, env);
    }

    return env.ASSETS.fetch(request);
  },
};

/api/* é uma convenção, não uma rota reservada. O código do navegador deve usar URLs relativas ao chamar um endpoint na mesma Extension:

const response = await fetch("./api/orders");

Isso mantém a solicitação na mesma origem e preserva o caminho público da Extension.

Publicar

Publique a partir do projeto clonado:

buildprint extension publish customer-portal -m "Add order history"

A publicação cria a Extension remota quando ela não existe. A mensagem é opcional.

A CLI agrupa o código personalizado como um único módulo ES. O código do Worker não pode importar módulos integrados do Node.js.

Uma implantação pode conter até 1.000 arquivos e 10 MiB. A saída estática deve conter /index.html. A saída da compilação deve permanecer dentro do diretório da Extension.

Identidade da implantação

Cada publicação cria um ID de implantação imutável de sete caracteres. A identidade inclui:

• O ID da implantação pai.

• O manifesto do código do Worker.

• O manifesto dos ativos estáticos.

• Os tipos de recursos declarados.

• O nome e a soma de verificação de cada migração.

Um nome, uma descrição ou uma mensagem de implantação não altera o ID da implantação.

Publicar a mesma operação novamente a retoma. O agente deve obter o head de teste atual antes de publicar a partir de um pai mais antigo.

Seleção de código e estado

As URLs da Extension usam este formato:

https://<project>.buildprintusercontent.com/<extension>/<deployment>/<version>/<route>

Os seletores têm finalidades independentes:

version é test ou live. Uma versão ausente ou desconhecida usa test.

Cada implantação tem um runtime de teste e um runtime live. Assim como no Bubble, esses dois runtimes permitem separar o estado do banco de dados e dos arquivos. Eles contêm o mesmo código e os mesmos ativos, mas recebem recursos e secrets diferentes.

Use uma URL de implantação fixa para uma integração com o Bubble. O teste do Bubble pode usar código novo enquanto o aplicativo live continua usando uma implantação mais antiga. A implantação da alteração do Bubble seleciona a nova implantação com o estado live.

latest/test seleciona o head de teste. latest/live seleciona a implantação mais recente com um runtime live pronto.

Migrações do D1

Armazene migrações SQL numeradas no diretório da Extension:

extensions/customer-portal/
  extension.json
  src/index.ts
  migrations/
    0001_create_orders.sql
    0002_add_order_status.sql

Os nomes das migrações usam quatro dígitos, um sublinhado e um nome curto. A versão e a soma de verificação de uma migração não podem ser alteradas depois que ela é aplicada.

O Buildprint aplica as migrações ausentes ao teste na ordem numérica. Ele aplica alterações compatíveis ao live durante a publicação. Uma alteração que possa interromper códigos mais antigos exige confirmação explícita antes que o Buildprint a aplique ao live.

Não edite a tabela _buildprint_migrations. O prefixo _buildprint_ é reservado para tabelas da plataforma.

Operações de D1 e R2

O agente pode usar operações internas de recursos para:

• Inspecionar o status e o esquema do D1.

• Executar uma consulta de leitura limitada.

• Realizar uma gravação controlada.

• Redefinir o banco de dados de teste.

• Confirmar migrações live.

• Listar objetos do R2.

• Fazer upload, download ou excluir um objeto.

• Limpar o bucket de teste.

Uma versão omitida significa teste. Toda gravação live exige uma versão live explícita e confirmação do usuário.

As operações mutáveis usam uma chave de operação. Repetir a mesma chave e solicitação retorna o resultado anterior. Um resultado de gravação do D1 desconhecido deve ser reconciliado com uma leitura antes de outra tentativa de gravação.

As consultas de leitura retornam no máximo 200 linhas. DDL só é aceito por meio de migrações.

Variáveis de ambiente e secrets

As variáveis de ambiente ficam disponíveis para o código personalizado do Worker. Os ambientes de teste e live têm valores separados.

Os valores da Extension são padrões. Os valores de uma implantação substituem os padrões. Um runtime recebe apenas os valores da versão selecionada.

buildprint extension env set customer-portal API_TOKEN=secret --version test
buildprint extension env list customer-portal --version test
buildprint extension env unset customer-portal API_TOKEN --version test

As alterações live exigem --version live e confirmação. As ações de exibição de secrets são auditadas. Não escreva valores de secrets em mensagens, logs ou capturas de tela.

Inspecionar e obter

Liste Extensions ou inspecione uma Extension:

buildprint extension list
buildprint extension info customer-portal

Obtenha o head de teste ou uma implantação fixa:

buildprint extension pull customer-portal
buildprint extension pull customer-portal --deployment a1b2c3d

A CLI para se os arquivos locais forem diferentes da base registrada. --force substitui os arquivos locais da Extension.

Leia logs e análises de solicitações:

buildprint extension logs customer-portal --since 30m
buildprint extension analytics customer-portal --since 24h

Adicione --json quando outra ferramenta precisar de uma saída estruturada.

Excluir e recuperar

Exclua uma implantação ou a Extension completa:

buildprint extension delete customer-portal a1b2c3d
buildprint extension delete customer-portal

Excluir uma implantação remove seus runtimes de teste e live. Isso não remove os dados do D1 ou do R2.

Excluir uma Extension remove suas rotas públicas e agenda seus recursos para exclusão após 30 dias. O agente ou o suporte pode recuperar a Extension antes do início da exclusão dos recursos.

A exclusão do R2 pode continuar por vários jobs no caso de um bucket grande. Jobs de exclusão repetidos retomam a mesma operação.