Archestack no VS Code

Com a extensão do Archestack para o Visual Studio Code, a sua aplicação é um repositório git e corre na sua própria máquina. Abra a pasta do repositório e a extensão arranca um Archestack local para ele: o PostgreSQL, a API e o builder, a partir do runtime que vem com a extensão. Não há nenhum espaço de trabalho a que se ligar nem mais nada para instalar. Os Script Modules, os Business Events, as páginas, os templates e as tabelas são ficheiros na pasta, e cada ficheiro que guarda chega ao Archestack local um momento depois.

Esse Archestack local chama-se projeto. Pertence ao repositório: um colega que o clone obtém o mesmo projeto, feito a partir dos mesmos ficheiros. Trabalhar em equipa explica como os programadores de uma empresa maior partilham um repositório, e A extensão do VS Code em detalhe mostra todos os ecrãs.

Instalar

A extensão ainda não está no Visual Studio Marketplace. É distribuída como um ficheiro VSIX: no VS Code, abra a Command Palette, execute Extensions: Install from VSIX... e escolha o ficheiro. Precisa do VS Code 1.90 ou posterior.

Use a build para Windows (x64). Inclui o runtime do Archestack, a API, o builder e o PostgreSQL, por isso um projeto corre sem mais nada instalado. Os PDFs são renderizados no Edge ou no Chrome que já está instalado na máquina. A build universal não tem runtime e, em vez disso, corre os projetos no Docker Desktop.

A extensão não precisa da extensão de C# da Microsoft nem do C# Dev Kit. As suas funcionalidades de C# vêm do próprio projeto, e os seus scripts abrem numa linguagem própria, por isso qualquer uma delas pode continuar instalada sem que as duas se atrapalhem.

Arrancar um projeto

• Uma aplicação nova. Abra uma pasta vazia, abra a vista Archestack na barra de atividades e escolha Start project. A extensão acrescenta archestack.json, cria uma base de dados nova, arranca a API e o builder, e inicia sessão sozinha como admin do projeto. New Package começa então a primeira pasta de package.
• Um repositório existente. Clone-o e abra a sua pasta. A janela arranca o projeto sozinha: o primeiro arranque cria a base de dados e carrega o repositório, primeiro as tabelas de todos os packages e depois os artefactos, com as dependências antes dos packages que precisam delas. Um clone acabado de fazer é uma aplicação funcional em cerca de quinze segundos, e reabrir a janela retoma o projeto.

O projeto é descrito em archestack.json, que entra no commit:

"project": {
  "name": "archestack-sales",
  "engine": "native",
  "webPort": 5310,
  "dbPort": 5312,
  "adminEmail": "admin@archestack.local"
}

O builder e a API partilham webPort e o PostgreSQL escuta em dbPort, ambos apenas em 127.0.0.1. A base de dados do projeto, as palavras-passe geradas e os logs ficam em .archestack/project/, que o git ignora. Os pacotes NuGet que os seus scripts descarregam também ficam lá, em .archestack/project/nuget, ou num volume Docker chamado nuget quando o projeto corre em Docker, para que um reinício não os descarregue outra vez.

A barra de estado mostra o projeto como local. A sua lista abre o builder do projeto no browser, para o projeto e mostra os logs da API. Reset Project Database deita fora os dados do projeto e carrega o repositório de novo.

O projeto pertence à janela que o corre. Fechar ou recarregar a janela para a API e o PostgreSQL, por isso nada fica a correr, e a janela seguinte volta a arrancá-los em segundos. Se a API deixar de responder enquanto trabalha, a janela volta a arrancá-la no prazo de dez segundos.

O repositório

Um repositório tem uma pasta por package, e um ou mais ficheiros por artefacto:

archestack.json                 the environments this repository knows, and its packages
packages/sales/
  package.json                  name, version, dependencies
  nuget.json                    the NuGet packages its scripts use, each at an exact version
  tables/orders.json            one per table: columns, keys, indexes, foreign keys
  layout.json                   where the tables sit on the diagram
  entities/Order.json
  scripts/Calc.csx + Calc.json  a script module: its code, and its parameters
  code/Sales/OrderSummary.cs    shared code, named by its path: C# every script can use,
  code/components/StatusChip.tsx  and modules pages import from @/
  triggers/Order/OnCreate.json + OnCreate.1.csx
  pages/Orders/page.json + overview.tsx + OrderRow.tsx   a page's own files beside its views
  templates/Card/template.json + template.tsx
  pdf/Invoice/template.json + template.html + data.csx
  schedules/nightly.json
  tests/smoke/suite.json + cases/doubles.json + doubles.csx
  api/customers.json            a Data API endpoint, named by its route, every version inside
workspace/
  branding.json, logo.png, layouts.json

As referências entre artefactos são nomes, nunca ids da base de dados. Nada do que é decidido por ambiente está nos ficheiros: quem pode ver uma página, se alguma coisa é pública, os acessos concedidos na Data API e o histórico de execuções ficam com cada ambiente. O mesmo conteúdo dá sempre os mesmos bytes, por isso o git mostra apenas alterações reais.

O projeto é alimentado com a pasta à medida que guarda. Uma alteração guardada em packages/ chega-lhe um momento depois, e o que apagar na pasta é apagado lá, incluindo uma pasta de package inteira. Não há nada para enviar. As tabelas são a exceção: mudam através de migrações.

New Package começa uma pasta de package, e New Artifact in Package (clique com o botão direito em qualquer coisa dentro de packages/ no Explorer, ou + num package na vista Workspace) escreve os ficheiros de um novo artefacto, pedindo apenas aquilo sem o qual ele não pode existir, como a entidade a que um Business Event pertence. Uma página nova é uma página de código. Um novo ficheiro de código partilhado pede o seu caminho, e a sua extensão diz o que ele é. Add File num artefacto da vista Workspace acrescenta um ficheiro ao lado dele: uma página recebe um ficheiro próprio junto às suas vistas, que o importam como ./Row, e um Script Module, um Business Event ou outro script, que é um único ficheiro, recebe um ficheiro de código partilhado no mesmo package, numa pasta com o seu nome, que qualquer script pode usar.

O builder do projeto também funciona, no browser. Uma alteração feita lá não está na pasta até a trazer com Pull Package to Folder, e um package alterado nos dois sítios fica como está e isso é dito uma vez, por isso nada é escrito por cima. Faça commit do que traz, como de qualquer outra alteração.

Editar artefactos

O código de um artefacto é um ficheiro, e as suas definições são o JSON ao lado dele, que abre num formulário. Cada alteração no formulário é escrita no ficheiro; Edit as JSON abre o texto.

Uma Business Entity abre no editor de entidades. As suas tabelas e colunas são escolhidas a partir da base de dados do projeto, por isso um nome que não existe é assinalado antes de guardar. As definições do próprio espaço de trabalho também são ficheiros, em workspace/: o branding com os seus logótipos e os layouts da aplicação publicada, cada um a abrir num formulário.

Scripts C#

Os Script Modules, os scripts de Business Events, os data scripts de PDF, os Scheduled Events e os scripts de teste têm as funcionalidades de C# de um editor .NET. Quem responde é o próprio compilador do projeto, por isso o editor vê exatamente o que o script vê quando corre:

• Sugestões de autocompletar, com a assinatura e a documentação de cada membro.
• Informação ao passar o rato, e informação sobre os parâmetros enquanto escreve uma chamada.
• Erros e avisos enquanto escreve.
• Go to Definition (F12). No método de um Script Module abre o script desse módulo, num parâmetro as definições que o declaram, e em qualquer outra coisa as suas declarações, só de leitura.
• Format Document, no estilo .NET.

O editor conhece os verdadeiros globais dos scripts (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc e Log), os parâmetros de um módulo como variáveis tipadas e, num Business Event, as colunas da entidade em Entity. As Business Entities são conjuntos tipados em Db e os Script Modules são métodos tipados em Modules, por isso uma coluna renomeada ou um argumento errado é um erro na sua linha antes de alguma coisa correr:

// A script module is a typed method: a wrong name or argument is an error as you type
var total = await Modules.Calc(qty: 2);

// Every business entity is a typed set
var open = await Db.Order
    .Where(o => o.Status == "Open")
    .ToListAsync();

Business Entities como conjuntos tipados, na referência, explica como os nomes são formados.

Os tipos de que mais do que um script precisa, como records e helpers, vão para um ficheiro C# partilhado na pasta code/ de um package. É C# comum, tem as mesmas funcionalidades, e F12 num dos seus tipos, dentro de um script, abre-o. Shared Code, na referência, explica o que um ficheiro partilhado pode usar.

As bibliotecas do NuGet são declaradas no nuget.json do package, cada uma numa versão exata, e os seus tipos aparecem no autocompletar como os restantes assim que o espaço de trabalho as tiver descarregado. Veja NuGet Packages na referência.

Testar um Script Module

Test, por cima do código de um Script Module, executa o módulo como o separador Test do builder o faz, com o script tal como o editor o tem, guardado ou não. Também está na barra de título do editor, no módulo na vista Workspace e no seu formulário. Um painel ao lado do script pede os parâmetros, verifica cada valor segundo o seu tipo e memoriza-os para a próxima vez. Um módulo que não precisa de nenhum valor que ainda não tenha corre de imediato, e Ctrl+Enter no painel corre-o outra vez. O painel mostra se passou, o que devolveu e o que escreveu em Log, e em caso de falha o erro com um botão que leva à sua linha.

Um teste é uma simulação: as escritas através de Db e Files são listadas em vez de feitas, e os emails e as notificações listados em vez de enviados, também os dos módulos que chama. Tudo o resto que o script faz por si mesmo é real: chamadas HTTP, System.IO e tudo o que um pacote NuGet faz, como uma ligação a outra base de dados. Marque Show the SQL it ran para ver as suas instruções no painel SQL Trace. Só as roles admin e owner podem testar. Um teste diz o que faz uma execução; uma verificação que corre sempre é um caso de teste, veja Testes.

Código de páginas e templates

O código de uma página e o .tsx de um Frontend Template são verificados contra aquilo que esse código tem realmente quando corre: backend, pageContext, currentUser, os hooks, o React, todos os componentes MUI com as suas props, os ícones, e um tipo de linha para cada Business Entity, como CustomerRow. O autocompletar, a informação ao passar o rato, os erros, ir para a definição, renomear e Format Document funcionam todos, e um return ao nível de topo não é problema. Corre sobre o TypeScript que vem com o VS Code, por isso não é preciso instalar nada.

O código pode ser repartido por vários ficheiros. Os ficheiros próprios de uma página ficam na sua pasta, ao lado das vistas, e são importados como ./OrderRow; o código que mais do que uma página usa vai para a pasta code/ de um package e é importado de @/, a partir de qualquer package do repositório. Os imports são verificados e tipados, ir para a definição segue-os, e renomear altera todos os ficheiros que usam o nome.

What page code can use, a ligação por cima do código de cada página e de cada template, abre a lista completa ao lado: todos os globais com o que fazem e um exemplo, e os tipos de linha do projeto. O builder mostra a mesma lista.

Pré-visualizações

Open Preview to the Side, o botão no canto superior direito de um PDF Template, de um Frontend Template, do código de uma página ou de um app layout, mostra-o tal como está no editor, guardado ou não, e acompanha cada edição:

• Um PDF Template é renderizado pelo projeto. O seu data script corre em modo de simulação, por isso uma pré-visualização nunca escreve uma linha nem envia um email. Os valores dos parâmetros podem ser alterados no topo.
• Um Frontend Template ou uma página é renderizado pela própria aplicação do projeto, com os parâmetros do template ou o id de registo da página no topo, e com os ficheiros próprios da página e o código partilhado do repositório tal como estão nos seus editores. Uma página é desenhada dentro do app layout que a aplicação publicada coloca à sua volta; a barra de ferramentas muda para outro layout ou para nenhum.
• Um app layout é desenhado pela própria shell da aplicação publicada, para uma página à sua escolha.
• Um template, uma página ou um layout podem ser mostrados num telemóvel, tablet ou computador ao tamanho real, na horizontal ou num tamanho à sua escolha, e com zoom para caberem ou numa percentagem. A pré-visualização seguinte abre no último dispositivo que escolheu.

Tabelas

As tabelas de um package são ficheiros, packages/<package>/tables/<table>.json, um por tabela. Abrem no editor de tabelas: colunas com os seus tipos, chaves, valores por omissão e chaves estrangeiras, e os índices da tabela. A vista Database lista as tabelas do projeto; Open Database Diagram desenha-as com as suas chaves estrangeiras, e arrastar lá uma tabela escreve o layout.json do package. New Table pergunta a que package a tabela pertence.

Guardar um ficheiro de tabela não altera a base de dados do projeto. O resto da pasta entra, e a vista Workspace e uma mensagem dizem que alterações de tabelas esperam por uma migração. Uma base de dados de projeto nova, no primeiro arranque ou depois de um reset, recebe sozinha as tabelas da pasta.

Migrações e rollback

Add Migration planeia as alterações de tabelas contra a base de dados do projeto e mostra cada operação, o seu risco e o SQL exato. As operações que perdem dados, como remover uma tabela ou uma coluna ou restringir um tipo, precisam de Allow data loss marcado. A revisão também lista os scripts tipados que, com a alteração, deixariam de compilar. A migração é guardada como um deployment pendente com um nome, sugerido a partir do que muda, como AddTechnicianSkill; Deploy corre-a, e Add and Deploy faz as duas coisas de uma vez.

A vista Deployments é o histórico, do mais recente para o mais antigo. Show SQL mostra o que um deployment corre. Roll Back to Here planeia levar as tabelas de volta ao que um deployment anterior criou, e acrescenta isso como um deployment pendente próprio, para rever e fazer deploy como qualquer migração. Um rollback repõe a estrutura, nunca os dados: as linhas de uma tabela ou coluna que ele remova perdem-se.

Drop Table remove o ficheiro da tabela e marca a tabela; ela desaparece quando é feito deploy de uma migração com a perda de dados permitida.

Consola SQL

New SQL Query abre um editor SQL sobre a base de dados do projeto, com autocompletar de tabelas e colunas. Run Query (Ctrl+Enter) corre a seleção, ou o ficheiro inteiro, instrução a instrução, cada uma com o seu próprio commit, e para no primeiro erro. Os resultados abrem ao lado do editor, até 1000 linhas cada, e copiam-se como CSV. Nada pergunta antes de um DELETE.

Planos de consulta e rastreio de SQL

Explain Query mostra o plano que o PostgreSQL escolhe para a seleção, ou para a instrução onde está o cursor: cada passo, o que cada um lê e quantas linhas espera. Explain Analyze Query (Ctrl+Alt+Enter) corre a instrução para obter tempos e linhas reais, numa transação que é revertida, por isso até um DELETE mantém as suas linhas. O plano assinala o passo que demora mais tempo e o que merece um segundo olhar: um scan que lê milhares de linhas para ficar com poucas, uma estimativa de linhas muito longe do que voltou, uma ordenação que teve de passar para o disco.

Trace SQL mostra o SQL que o próprio Archestack envia. Clique com o botão direito num Script Module ou numa Business Entity na vista Workspace, ou use o botão no seu ficheiro ou formulário. Um Script Module corre com os valores de parâmetros que indicar, por omissão em modo de simulação, em que as escritas são registadas em vez de feitas. Uma Business Entity é lida tal como a grelha de uma página a lê. O painel SQL Trace lista depois cada instrução com os seus valores, quanto tempo demorou e o código que a enviou, e pode juntar as instruções iguais para mostrar uma query que corre uma vez por linha. Clique numa instrução para ver o seu plano, abri-la como SQL com os valores no lugar ou copiá-la. Na vista Testing, Run with SQL Trace faz o mesmo com os casos de teste. Só as roles admin e owner podem fazer rastreios.

Testes

Run Tests na vista Workspace corre os testes de todos os packages, os de um package, uma suite ou um único caso. Primeiro, o projeto é alimentado com a pasta, por isso um caso exercita os scripts e as páginas tal como estão na pasta. Cada caso corre numa sandbox de teste, uma base de dados própria, nunca contra os dados do projeto, e o email e as notificações são registados em vez de enviados. Correm quatro casos em simultâneo. Cada caso mostra na árvore o seu último resultado e quanto tempo demorou; clicar nele mostra o que falhou, o esperado face ao obtido, e o que imprimiu. A vista Testing lista os mesmos casos.

Uma verificação que um sujeito e um operador não conseguem exprimir é uma verificação de código: um ficheiro C# próprio que corre depois do caso, com Result, Output, Error e Failed à mão, e que falha quando lança uma exceção, falha um Assert ou devolve false.

Event Log

A vista Event Log mostra o que correu no projeto, agrupado por tipo: Business Events, Script Modules, Scheduled Events, execuções de testes, email e backups, cada um com as execuções e as falhas do último dia. Uma nova falha é contada no contador da vista e anunciada quando acontece. Clique numa entrada para ler tudo o que ela registou. Open Artifact abre o ficheiro do script em que falhou, na linha que falhou.

Data API

Um endpoint da Data API serve uma Business Entity a outros sistemas, num endereço como /api/data/v1/customers. Pertence a um package como qualquer outro artefacto: um só ficheiro, api/customers.json, com o nome da sua rota e todas as suas versões lá dentro. O ficheiro abre num formulário: a entidade que serve, o nome e a rota, e em cada versão o estado, o dia de sunset, o tamanho de página, as operações e os campos. Cada campo é um nome público sobre uma coluna da entidade, devolvido, gravável ou obrigatório; o formulário oferece as colunas e assinala um campo cuja coluna a entidade não tem.

Um endpoint também pode chamar um Script Module, para trabalho que vai além de ler ou escrever linhas. Cada versão indica o módulo e o único método a que responde, POST com os parâmetros num corpo JSON ou GET com eles na query string, e lista os parâmetros que quem chama envia: um nome público sobre um parâmetro do módulo, obrigatório ou não, com uma descrição. O formulário oferece os parâmetros do módulo e assinala aquele de que o módulo precisa mas que a versão não passa. Quem chama recebe o que o módulo devolve, em JSON. Um módulo marcado como admin only continua assim: só admins e owners o podem chamar, por isso o seu endpoint não aceita acessos concedidos.

Uma versão publicada só pode crescer. Acrescentar campos e operações não faz mal; remover ou mudar o nome de um campo, tirar-lhe a escrita, torná-lo obrigatório ou retirar uma operação partiria os sistemas que a chamam, por isso vai para uma versão nova, que o formulário começa como cópia da que está à vista. Num endpoint que chama um Script Module, a versão mantém o seu módulo e o seu método, e só ganha parâmetros opcionais. Uma gravação que parte uma versão publicada é recusada, com o motivo. Ativar uma versão propõe marcar as anteriores como obsoletas: continuam a ser servidas e dizem a quem as chama, nos cabeçalhos, que estão obsoletas e, logo que defina um, qual é o seu dia de sunset, até as passar a Retired.

A vista Data API lista os endpoints do projeto com as suas versões, e os seus API clients. Try It num endpoint ou numa versão envia pedidos reais e mostra a resposta tal como chegou, com os cabeçalhos: em seu nome, com o SQL executado se quiser, ou com a chave de um API client, para ver exatamente o que esse cliente pode chamar. Num endpoint que chama um Script Module, envia a chamada com parâmetros de exemplo. Os botões da vista abrem o documento OpenAPI de tudo o que pode chamar e How to connect, o guia para quem constrói sobre ela.

Quem pode chamar um endpoint é decidido em cada ambiente e nunca está no ficheiro. Edit access in the workspace, no formulário, abre os acessos concedidos: que roles podem listar, obter, criar, atualizar ou apagar, ou chamar o módulo. Um API client é uma conta de serviço com roles e uma chave em vez de uma palavra-passe. New API Client cria um e mostra a chave uma única vez; Rotate Key substitui-a, e a chave antiga deixa de funcionar de imediato.

Agentes de programação

O repositório diz aos agentes de programação, como o Claude Code e o Codex, o que podem criar nele, tal como o MCP Server diz a um modelo ligado. O New Package e cada pull escrevem:

• AGENTS.md: como uma alteração chega à aplicação, as regras que cada ficheiro segue, os erros a evitar e um exemplo de cada tipo de artefacto. Só a secção marcada da extensão é reescrita, por isso as notas da sua equipa no ficheiro mantêm-se.
• CLAUDE.md, que aponta o Claude Code para AGENTS.md.
• docs/archestack/: os guias de scripts e de testes e o que o código de páginas pode usar. Entra no commit, por isso um agente que trabalhe num clone acabado de fazer também os tem.
• .archestack/context/: as Business Entities do projeto e o seu modelo de dados gerado, apenas para esta máquina.

Update Agent Instructions escreve-os de novo. As edições de um agente são ficheiros guardados como os seus, por isso chegam ao projeto da mesma forma; uma pessoa revê-as e faz commit delas.

Trabalhar em equipa

Numa empresa maior, o repositório é a fonte de verdade da aplicação, tal como a infraestrutura como código descreve servidores: tudo o que compõe a aplicação é um ficheiro no git, revisto e versionado como qualquer outro código, e cada ambiente é feito a partir desses ficheiros. A extensão é a forma como cada programador trabalha neles.

Programador 1

Ficheiros do repositório Projeto local

Programador 2

Ficheiros do repositório Projeto local

Programador 3

Ficheiros do repositório Projeto local

push e pull

Servidor git

O repositório: branches, pull requests e main

Pipeline

Build, teste, plano, deploy

Teste

Archestack alojado

Aceitação

Archestack alojado

Produção

Archestack alojado

Cada programador corre a sua própria cópia

Cada programador clona o repositório e abre-o, e a sua janela corre um projeto próprio, com a sua própria base de dados, na sua própria máquina. Ninguém partilha um espaço de trabalho de desenvolvimento, por isso ninguém guarda por cima do trabalho de outra pessoa, e um script que se parte fica numa só máquina até ser corrigido. Um novo membro da equipa tem a aplicação a correr cerca de quinze segundos depois do clone. As tabelas de um projeto começam vazias, e os casos de teste escrevem as linhas de que precisam na sua própria sandbox, por isso todos os programadores testam contra os mesmos dados.

Um package por equipa

Uma aplicação grande são vários packages, cada um uma pasta com as suas próprias tabelas, Business Entities, páginas, scripts e testes. Divida-os como a empresa está dividida, e as equipas trabalham sobretudo em pastas próprias:

packages/
  core/        customers, products, shared scripts     team Platform
  sales/       quotes and orders, needs core           team Sales
  planning/    work orders and schedules, needs core   team Operations
  invoicing/   invoices and PDF templates, needs sales team Finance

Um package indica os packages de que precisa no seu package.json, pelo nome e por um intervalo de versões:

{
  "formatVersion": 1,
  "name": "invoicing",
  "version": "1.4.0",
  "description": "Invoices and their PDFs, made from sales orders.",
  "dependencies": [
    { "name": "sales", "versionRange": "[2.0,3.0)" }
  ],
  "masterData": []
}

Uma versão simples como 2.0 significa essa versão ou mais recente, [2.0] exatamente essa, e [2.0,3.0) qualquer versão a partir da 2.0 até à 3.0, sem a incluir. Um projeto carrega as dependências antes dos packages que precisam delas. Uma tabela de que outro package é dono é incluída apenas como referência: um package pode apontar-lhe uma chave estrangeira, mas nunca a altera. A funcionalidade de code owners do seu serviço de alojamento git pode então exigir, para cada pasta, uma revisão da equipa que é dona dela.

Ou um repositório por equipa

As equipas que também devam lançar versões ao seu próprio ritmo podem, em vez disso, ter cada uma o seu repositório, e com ele uma aplicação, um projeto e ambientes próprios. Os dados de que uma equipa é dona e de que outra precisa chegam a esta como tabelas third-party: os ambientes desta ligam-se à base de dados da equipa dona e espelham as tabelas de que precisam, num agendamento. Uma tabela espelhada lê-se como qualquer outra tabela da aplicação, nas Business Entities, nas páginas e nos scripts.

sales-app/       team Sales        owns customers, quotes and orders
planning-app/    team Operations   mirrors customers from sales-app
invoicing-app/   team Finance      mirrors customers and orders from sales-app

• Um dono por tabela. Uma tabela espelhada é alterada na aplicação que é dona dela; as outras leem a sua cópia. As colunas marcadas como geridas pelo Archestack são a exceção: guardam os acréscimos próprios de uma equipa, e uma sincronização nunca as escreve por cima.
• Tão atual como a última sincronização. Uma tabela sincroniza por inteiro ou pelo que mudou, e isso precisa de uma coluna que diga quando uma linha mudou pela última vez, como modified_at.
• As ligações pertencem ao ambiente. Não estão nos ficheiros, por isso cada ambiente liga-se ao seu homólogo: aceitação a aceitação, produção a produção.

Com um repositório e um package por equipa, o deploy é de uma única aplicação, e um package pode apontar uma chave estrangeira para uma tabela de outro package. Um repositório por equipa deixa cada equipa lançar versões por si, e paga isso com cópias que só estão tão atuais como a sua última sincronização.

Branches e revisões

• Trabalhe numa branch e abra um pull request, como com qualquer código. Todas as referências são nomes e o mesmo conteúdo dá sempre os mesmos bytes, por isso um diff mostra apenas o que alguém alterou: uma linha de um script, uma coluna, o JSX de uma página, nunca um id renumerado ou chaves reordenadas.
• Fazer checkout de outra branch altera os ficheiros, e o projeto acompanha-os tal como acompanha o que guarda. As alterações de tabelas esperam então por uma migração; Reset Project Database, em vez disso, recomeça a partir das tabelas da branch.
• Um revisor faz checkout da branch, tem-na a correr no seu próprio projeto e corre contra ela os testes do package com Run Tests. Os testes vivem no package, por isso viajam com o código que testam.
• AGENTS.md e docs/archestack/ entram no commit, por isso o agente de programação de cada programador segue as mesmas regras.

Tabelas numa equipa

Um ficheiro de tabela descreve a estrutura que uma tabela deve ter, não os passos para lá chegar. Depois de um pull ou de um merge, o projeto de cada programador planeia a sua própria migração a partir dos ficheiros de tabela com Add Migration, e a revisão mostra exatamente o que essa base de dados vai correr, incluindo a perda de dados e os scripts tipados que deixariam de compilar. Todas as ferramentas escrevem um ficheiro de tabela numa única forma canónica, por isso as edições de duas pessoas à mesma tabela só entram em conflito onde alteram a mesma coisa.

O que cada ambiente decide

Quem pode ver uma página, o que é público, os acessos concedidos na Data API e os API clients, os utilizadores e as roles, as contas de email, as ligações a outros sistemas e o histórico de execuções não estão nos ficheiros. São os administradores de cada ambiente que os definem, por isso um merge nunca pode tornar algo público nem dar acesso a ninguém.

O deploy para teste, aceitação e produção é feito a partir do repositório por um pipeline, como descreve Estratégia de deployment.

Definições

Trazer um package existente

Um package que até agora só existe num espaço de trabalho alojado entra no repositório uma única vez: execute Connect to Workspace a partir da Command Palette, inicie sessão, use Pull Package to Folder no package e escolha de novo o projeto na barra de estado. A partir daí a pasta é a fonte e o projeto corre-a. As tabelas do package vêm com ele, com as tabelas para as quais aponta uma chave estrangeira marcadas como apenas de referência, para que o projeto possa criar todas as tabelas de que o package precisa. Num projeto que já tem uma base de dados, essas tabelas esperam por uma migração como qualquer outra alteração de tabelas.

Armadilhas

• Um projeto começa com as tabelas vazias. A pasta traz a estrutura, não as linhas. Ainda não é possível carregar dados mestre a partir do repositório.
• As tabelas nunca mudam ao guardar. Só uma migração com deploy feito altera a base de dados do projeto, à parte um arranque de raiz ou um reset.
• Um reset deita fora os dados do projeto. Tudo o resto está na pasta e volta; as linhas que introduziu não.
• As alterações feitas no builder ficam no projeto até as trazer para a pasta, e um reset perde-as.

Para onde seguir a partir daqui

Espaços de trabalho e alojamento explica onde a sua aplicação corre quando sai da sua máquina. A referência cobre packages, Script Modules e Database Deployments com mais profundidade.