Archestack en VS Code

Con la extensión de Archestack para Visual Studio Code, tu aplicación es un repositorio git y se ejecuta en tu propia máquina. Abre la carpeta del repositorio y la extensión arranca un Archestack local para él: PostgreSQL, la API y el builder, a partir del runtime que incluye la extensión. No hay ningún espacio de trabajo al que conectarse ni nada más que instalar. Los script modules, los business events, las páginas, las plantillas y las tablas son archivos de la carpeta, y cada archivo que guardas llega al Archestack local un momento después.

Ese Archestack local se llama proyecto. Pertenece al repositorio: un compañero que lo clona obtiene el mismo proyecto, creado a partir de los mismos archivos. Trabajar en equipo explica cómo los desarrolladores de una empresa más grande comparten un mismo repositorio, y La extensión de VS Code en detalle muestra todas las pantallas.

Instalación

La extensión todavía no está en el Visual Studio Marketplace. Se distribuye como un archivo VSIX: en VS Code, abre la Command Palette, ejecuta Extensions: Install from VSIX... y elige el archivo. Necesita VS Code 1.90 o posterior.

Usa la compilación para Windows (x64). Incluye el runtime de Archestack, la API, el builder y PostgreSQL, así que un proyecto se ejecuta sin instalar nada más. Los PDF se renderizan en el Edge o el Chrome que ya hay en la máquina. La compilación universal no incluye runtime y, en su lugar, ejecuta los proyectos en Docker Desktop.

La extensión no necesita la extensión de C# de Microsoft ni el C# Dev Kit. Sus funciones de C# vienen del propio proyecto, y sus scripts se abren en un lenguaje propio, así que cualquiera de las dos puede seguir instalada sin que se estorben.

Arranca un proyecto

• Una aplicación nueva. Abre una carpeta vacía, abre la vista Archestack en la barra de actividad y elige Start project. La extensión añade archestack.json, crea una base de datos nueva, arranca la API y el builder, e inicia sesión por sí sola como el admin del proyecto. New Package crea después la carpeta del primer paquete.
• Un repositorio existente. Clónalo y abre su carpeta. La ventana arranca el proyecto por sí sola: el primer arranque crea la base de datos y carga el repositorio, primero las tablas de todos los paquetes y después los artefactos, con las dependencias antes que los paquetes que las necesitan. Un clon recién hecho es una aplicación en funcionamiento en unos quince segundos, y al volver a abrir la ventana el proyecto se retoma.

El proyecto se describe en archestack.json, que se confirma en git:

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

El builder y la API comparten webPort y PostgreSQL escucha en dbPort, ambos solo en 127.0.0.1. La base de datos del proyecto, sus contraseñas generadas y sus logs viven en .archestack/project/, que git ignora. Los paquetes NuGet que descargan sus scripts también se guardan allí, en .archestack/project/nuget, o en un volumen de Docker llamado nuget cuando el proyecto se ejecuta en Docker, así que un reinicio no los vuelve a descargar.

La barra de estado muestra el proyecto como local. Su lista abre el builder del proyecto en el navegador, detiene el proyecto y muestra los logs de la API. Reset Project Database descarta los datos del proyecto y vuelve a cargar el repositorio.

El proyecto pertenece a la ventana que lo ejecuta. Cerrar o recargar la ventana detiene la API y PostgreSQL, así que no queda nada en marcha, y la siguiente ventana los vuelve a arrancar en segundos. Si la API deja de responder mientras trabajas, la ventana la vuelve a arrancar en diez segundos como mucho.

El repositorio

Un repositorio contiene una carpeta por paquete, y uno o más archivos 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

Las referencias entre artefactos son nombres, nunca ids de base de datos. En los archivos no hay nada que se decida por entorno: quién puede ver una página, si algo es público, los permisos de la Data API y el historial de ejecuciones se quedan en cada entorno. El mismo contenido da siempre los mismos bytes, así que git solo muestra cambios reales.

El proyecto recibe la carpeta a medida que guardas. Un cambio guardado bajo packages/ le llega un momento después, y lo que eliminas en la carpeta se elimina allí, incluida una carpeta de paquete entera. No hay nada que enviar. Las tablas son la excepción: cambian mediante migraciones.

New Package crea una carpeta de paquete, y New Artifact in Package (clic derecho sobre cualquier cosa bajo packages/ en el Explorer, o + en un paquete de la vista Workspace) escribe los archivos de un artefacto nuevo, y solo pide lo que el artefacto necesita para existir, como la entidad a la que pertenece un business event. Una página nueva es una página de código. Un archivo nuevo de código compartido pide su ruta, y su extensión indica qué es. Add File en un artefacto de la vista Workspace añade un archivo a su lado: una página recibe un archivo propio junto a sus vistas, que lo importan como ./Row, y un script module, un business event u otro script, que es un único archivo, recibe un archivo de código compartido en el mismo paquete, en una carpeta con su nombre, que cualquier script puede usar.

El builder del proyecto también funciona, en el navegador. Un cambio hecho allí no está en la carpeta hasta que lo traes con Pull Package to Folder, y un paquete cambiado en los dos sitios se deja como está y se avisa una vez, así que no se sobrescribe nada. Confirma en git lo que traes, como cualquier otro cambio.

Edita artefactos

El código de un artefacto es un archivo, y sus ajustes son el JSON que tiene al lado, que se abre en un formulario. Cada cambio en el formulario se escribe en el archivo; Edit as JSON abre el texto.

Una business entity se abre en el editor de entidades. Sus tablas y columnas se eligen de la base de datos del proyecto, así que un nombre que no existe se señala antes de guardar. Los ajustes propios del espacio de trabajo también son archivos, en workspace/: el branding con sus logotipos y los layouts de la aplicación publicada, y cada uno se abre en un formulario.

Scripts de C#

Los script modules, los scripts de business events, los data scripts de PDF, los scheduled events y los scripts de prueba tienen las funciones de C# de un editor de .NET. Las responde el propio compilador del proyecto, así que el editor ve exactamente lo que ve el script cuando se ejecuta:

• Autocompletado, con la firma y la documentación de cada miembro.
• Información al pasar el ratón, y la información de parámetros mientras escribes una llamada.
• Errores y advertencias mientras escribes.
• Go to Definition (F12). Sobre el método de un script module abre el script de ese módulo, sobre un parámetro los ajustes que lo declaran, y sobre cualquier otra cosa sus declaraciones, en solo lectura.
• Format Document, al estilo de .NET.

El editor conoce los globales reales del script (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc y Log), los parámetros de un módulo como variables tipadas y, en un business event, las columnas de la entidad en Entity. Las business entities son conjuntos tipados sobre Db y los script modules son métodos tipados sobre Modules, así que una columna renombrada o un argumento incorrecto es un error en su línea antes de que se ejecute nada:

// 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, en la referencia, explica cómo se forman los nombres.

Los tipos que necesitan varios scripts, como records y helpers, van en un archivo de C# compartido, en la carpeta code/ de un paquete. Es C# normal, tiene las mismas funciones, y F12 sobre uno de sus tipos en un script lo abre. Shared Code, en la referencia, explica qué puede usar un archivo compartido.

Las bibliotecas de NuGet se declaran en el nuget.json del paquete, cada una en una versión exacta, y sus tipos se autocompletan como el resto en cuanto el workspace las ha descargado. Consulta NuGet Packages en la referencia.

Probar un script module

Test, encima del código de un script module, ejecuta el módulo como lo hace la pestaña Test del builder, con el script tal como lo tiene el editor, guardado o no. También está en la barra de título del editor, en el módulo en la vista Workspace y en su formulario. Un panel junto al script pide los parámetros, comprueba cada valor según su tipo y los recuerda para la próxima vez. Un módulo que no necesita ningún valor que no tenga ya se ejecuta enseguida, y Ctrl+Enter en el panel lo vuelve a ejecutar. El panel muestra si ha pasado, qué ha devuelto y qué ha escrito en Log, y si falla, el error con un botón que lleva a su línea.

Una prueba es una simulación: las escrituras con Db y Files se listan en lugar de hacerse, y el correo y las notificaciones se listan en lugar de enviarse, también los de los módulos a los que llama. Todo lo demás que hace el script por su cuenta es real: las llamadas HTTP, System.IO y todo lo que hace un paquete NuGet, como una conexión a otra base de datos. Marca Show the SQL it ran para ver sus sentencias en el panel SQL Trace. Solo los roles admin y owner pueden probar. Una prueba dice qué hace una ejecución; una comprobación que se ejecuta cada vez es un caso de prueba, consulta Pruebas.

Código de páginas y plantillas

El código de una página y el .tsx de una frontend template se comprueban contra lo que ese código tiene realmente cuando se ejecuta: backend, pageContext, currentUser, los hooks, React, todos los componentes de MUI con sus props, los iconos y un tipo de fila por cada business entity, como CustomerRow. Funcionan el autocompletado, la información al pasar el ratón, los errores, ir a la definición, el renombrado y Format Document, y un return de nivel superior es válido. Funciona con el TypeScript que trae VS Code, así que no hay nada que instalar.

El código se puede repartir en varios archivos. Los archivos propios de una página están en su carpeta, junto a las vistas, y se importan como ./OrderRow; el código que usan varias páginas va en la carpeta code/ de un paquete y se importa desde @/, desde cualquier paquete del repositorio. Las importaciones se comprueban y están tipadas, ir a la definición las sigue, y un renombrado cambia todos los archivos que usan el nombre.

What page code can use, el enlace que hay encima del código de cada página y de cada plantilla, abre a su lado la lista completa: cada global con lo que hace y un ejemplo, y los tipos de fila del proyecto. El builder muestra la misma lista.

Vistas previas

Open Preview to the Side, el botón de arriba a la derecha de una plantilla PDF, una frontend template, el código de una página o un app layout, lo muestra tal como está en el editor, guardado o no, y sigue cada edición:

• Una plantilla PDF la renderiza el proyecto. Su data script se ejecuta en modo de simulación, así que una vista previa nunca escribe una fila ni envía un correo. Los valores de los parámetros se pueden cambiar arriba.
• Una frontend template o una página la renderiza la propia aplicación del proyecto, con los parámetros de la plantilla o el id del registro de la página arriba, y con los archivos propios de la página y el código compartido del repositorio tal como están en sus editores. Una página se dibuja dentro del app layout que la aplicación publicada pone a su alrededor; la barra de herramientas cambia a otro layout o a ninguno.
• Un app layout lo dibuja el propio marco de la aplicación publicada, para una página que elijas.
• Una plantilla, una página o un layout se pueden mostrar en un teléfono, una tableta o un escritorio a su tamaño real, en horizontal o a un tamaño propio, y con zoom para que encajen o a un porcentaje. La siguiente vista previa se abre en el último dispositivo que elegiste.

Tablas

Las tablas de un paquete son archivos, packages/<package>/tables/<table>.json, uno por tabla. Se abren en el editor de tablas: columnas con sus tipos, claves, valores por defecto y claves foráneas, y los índices de la tabla. La vista Database enumera las tablas del proyecto; Open Database Diagram las dibuja con sus claves foráneas, y arrastrar una tabla allí escribe el layout.json del paquete. New Table pregunta a qué paquete pertenece la tabla.

Guardar un archivo de tabla no cambia la base de datos del proyecto. El resto de la carpeta sí llega al proyecto, y la vista Workspace y un mensaje indican qué cambios de tablas esperan una migración. Una base de datos de proyecto nueva, en el primer arranque o tras un restablecimiento, recibe por sí sola las tablas de la carpeta.

Migraciones y reversión

Add Migration planifica los cambios de tablas contra la base de datos del proyecto y muestra cada operación, su riesgo y el SQL exacto. Las operaciones que pierden datos, como eliminar una tabla o una columna o restringir un tipo, requieren marcar Allow data loss. La revisión también enumera los scripts tipados que dejarían de compilar con el cambio. La migración se guarda como un despliegue pendiente con un nombre, sugerido a partir de lo que cambia, como AddTechnicianSkill; Deploy la ejecuta, y Add and Deploy hace las dos cosas a la vez.

La vista Deployments es el historial, del más reciente al más antiguo. Show SQL muestra lo que ejecuta un despliegue. Roll Back to Here planifica cómo devolver las tablas a lo que dejó un despliegue anterior, y lo añade como un despliegue pendiente propio, para revisarlo y desplegarlo como cualquier migración. Una reversión restaura la estructura, nunca los datos: las filas de una tabla o columna que elimina se pierden.

Drop Table elimina el archivo de la tabla y marca la tabla; la tabla desaparece cuando se despliega una migración con la pérdida de datos permitida.

Consola SQL

New SQL Query abre un editor SQL sobre la base de datos del proyecto, con autocompletado de tablas y columnas. Run Query (Ctrl+Enter) ejecuta la selección, o el archivo entero, sentencia a sentencia, cada una confirmada por separado, y se detiene en el primer error. Los resultados se abren junto al editor, hasta 1000 filas cada uno, y se copian como CSV. Nada pregunta antes de un DELETE.

Planes de consulta y trazas SQL

Explain Query muestra el plan que PostgreSQL elige para la selección, o para la sentencia en la que está el cursor: cada paso, qué lee cada uno y cuántas filas espera. Explain Analyze Query (Ctrl+Alt+Enter) ejecuta la sentencia para obtener tiempos y filas reales, en una transacción que se revierte, así que incluso un DELETE conserva sus filas. El plan marca el paso que más tiempo lleva y lo que merece una segunda mirada: un escaneo que lee miles de filas para quedarse con unas pocas, una estimación de filas muy alejada de lo que volvió, una ordenación que tuvo que pasar a disco.

Trace SQL muestra el SQL que envía el propio Archestack. Haz clic derecho sobre un script module o una business entity en la vista Workspace, o usa el botón de su archivo o formulario. Un script module se ejecuta con los valores de parámetros que indiques, por defecto en modo de simulación, en el que las escrituras se registran en lugar de hacerse. Una business entity se lee como la lee la rejilla de una página. El panel SQL Trace muestra entonces cada sentencia con sus valores, cuánto tardó y el código que la envió, y puede agrupar las sentencias iguales para mostrar una consulta que se ejecuta una vez por fila. Haz clic en una sentencia para ver su plan, abrirla como SQL con sus valores en su sitio o copiarla. En la vista Testing, Run with SQL Trace hace lo mismo con los casos de prueba. Solo los roles admin y owner pueden hacer trazas.

Pruebas

Run Tests, en la vista Workspace, ejecuta las pruebas de todos los paquetes, las de un paquete, una suite o un solo caso. Primero se lleva la carpeta al proyecto, así que un caso pone a prueba los scripts y las páginas tal como están en la carpeta. Cada caso se ejecuta en un sandbox de pruebas, una base de datos propia, nunca contra los datos del proyecto, y los correos y las notificaciones se registran en lugar de enviarse. Se ejecutan cuatro casos a la vez. Cada caso muestra en el árbol su último resultado y cuánto tardó; al hacer clic en él se ve qué falló, lo esperado frente a lo real, y lo que imprimió. La vista Testing muestra los mismos casos.

Una comprobación que no se puede expresar con un sujeto y un operador es una comprobación de código: un archivo de C# propio que se ejecuta después del caso, con Result, Output, Error y Failed a mano, y que falla cuando lanza una excepción, cuando falla un Assert o cuando devuelve false.

Event Log

La vista Event Log muestra lo que se ejecutó en el proyecto, agrupado por tipo: business events, script modules, scheduled events, ejecuciones de pruebas, correo y copias de seguridad, cada uno con las ejecuciones y los fallos del último día. Un fallo nuevo se cuenta en la insignia de la vista y se anuncia en el momento. Haz clic en una entrada para leer todo lo que registró. Open Artifact abre el archivo del script en el que falló, en la línea del fallo.

Data API

Un endpoint de la Data API sirve una business entity a otros sistemas, en una dirección como /api/data/v1/customers. Pertenece a un package como cualquier otro artefacto: un único archivo, api/customers.json, con el nombre de su ruta y todas sus versiones dentro. El archivo se abre en un formulario: la entidad que sirve, su nombre y su ruta, y para cada versión su estado, su día de sunset, el tamaño de página, las operaciones y los campos. Cada campo es un nombre público sobre una columna de la entidad, que se devuelve, se puede escribir o es obligatorio; el formulario ofrece las columnas y marca un campo cuya columna la entidad no tiene.

Un endpoint también puede llamar a un script module, para trabajo que va más allá de leer o escribir filas. Cada versión nombra el módulo y el único método al que responde, POST con los parámetros en un cuerpo JSON o GET con ellos en la cadena de consulta, y enumera los parámetros que envían quienes llaman: un nombre público sobre un parámetro del módulo, obligatorio o no, con una descripción. El formulario ofrece los parámetros del módulo y señala el que el módulo necesita y la versión no pasa. Quien llama recibe lo que devuelve el módulo, en JSON. Un módulo marcado como admin only lo sigue siendo: solo los admins y los owners pueden llamarlo, así que su endpoint no admite permisos.

Una versión publicada solo puede crecer. Añadir campos y operaciones está bien; quitar o renombrar un campo, quitarle la escritura, hacerlo obligatorio o eliminar una operación rompería los sistemas que la llaman, así que va en una versión nueva, que el formulario empieza como copia de la que se muestra. En un endpoint que llama a un script module, la versión conserva su módulo y su método, y solo gana parámetros opcionales. Un guardado que rompe una versión publicada se rechaza, con el motivo. Activar una versión ofrece marcar como obsoletas las anteriores: siguen sirviéndose y avisan a quien las llama, en sus cabeceras, de que están obsoletas y, en cuanto fijes uno, de su día de sunset, hasta que las pases a Retired.

La vista Data API lista los endpoints del proyecto con sus versiones, y sus API clients. Try It en un endpoint o en una versión envía peticiones reales y muestra la respuesta tal como llegó, con las cabeceras: como tú, con el SQL que ejecutó si quieres, o con la clave de un API client, para ver exactamente qué puede llamar ese cliente. En un endpoint que llama a un script module, envía la llamada con parámetros de ejemplo. Los botones de la vista abren el documento OpenAPI de todo lo que puedes llamar y How to connect, la guía para quienes construyen sobre ella.

Quién puede llamar a un endpoint lo decide cada entorno y nunca está en el archivo. Edit access in the workspace, en el formulario, abre los permisos: qué roles pueden listar, obtener, crear, actualizar o borrar, o llamar al módulo. Un API client es una cuenta de servicio con roles y una clave en lugar de una contraseña. New API Client crea uno y muestra su clave una sola vez; Rotate Key la sustituye, y la clave anterior deja de funcionar al instante.

Agentes de programación

El repositorio les dice a los agentes de programación como Claude Code y Codex qué pueden crear en él, igual que el MCP Server se lo dice a un modelo conectado. New Package y cada pull escriben:

• AGENTS.md: cómo llega un cambio a la aplicación, las reglas que sigue cada archivo, los errores que hay que evitar y un ejemplo de cada tipo de artefacto. Solo se reescribe la sección marcada de la extensión, así que las notas propias de tu equipo en el archivo se conservan.
• CLAUDE.md, que remite a Claude Code a AGENTS.md.
• docs/archestack/: las guías de scripts y de pruebas y lo que puede usar el código de páginas. Se confirma en git, así que un agente que trabaja en un clon recién hecho también las tiene.
• .archestack/context/: las business entities del proyecto y su modelo de datos generado, solo para esta máquina.

Update Agent Instructions los vuelve a escribir. Las ediciones de un agente son archivos guardados como los tuyos, así que llegan al proyecto de la misma forma; una persona las revisa y las confirma en git.

Trabajar en equipo

Para una empresa más grande, el repositorio es la fuente de verdad de la aplicación, igual que la infraestructura como código describe los servidores: todo lo que forma la aplicación es un archivo en git, revisado y versionado como cualquier otro código, y cada entorno se crea a partir de esos archivos. La extensión es la forma en que cada desarrollador trabaja con ellos.

Desarrollador 1

Archivos del repositorio Proyecto local

Desarrollador 2

Archivos del repositorio Proyecto local

Desarrollador 3

Archivos del repositorio Proyecto local

push y pull

Servidor git

El repositorio: ramas, pull requests y main

Pipeline

Compilar, probar, planificar, desplegar

Pruebas

Archestack alojado

Aceptación

Archestack alojado

Producción

Archestack alojado

Cada desarrollador ejecuta su propia copia

Cada desarrollador clona el repositorio y lo abre, y su ventana ejecuta un proyecto propio, con su propia base de datos, en su propia máquina. Nadie comparte un espacio de trabajo de desarrollo, así que nadie guarda encima del trabajo de otro, y un script que se rompe se queda en una sola máquina hasta que se arregla. Un miembro nuevo del equipo tiene la aplicación en marcha unos quince segundos después de clonar. Las tablas de un proyecto empiezan vacías, y los casos de prueba escriben las filas que necesitan en su propio sandbox, así que todos los desarrolladores prueban contra los mismos datos.

Un paquete por equipo

Una aplicación grande son varios paquetes, cada uno una carpeta con sus propias tablas, business entities, páginas, scripts y pruebas. Divídelos igual que está dividida la empresa, y los equipos trabajarán casi siempre en carpetas propias:

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

Un paquete nombra los paquetes que necesita en su package.json, por nombre y rango de versiones:

{
  "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": []
}

Una versión sin más, como 2.0, significa esa versión o una más reciente; [2.0], exactamente esa, y [2.0,3.0), cualquiera desde la 2.0 hasta la 3.0, sin incluirla. Un proyecto carga las dependencias antes que los paquetes que las necesitan. Una tabla que pertenece a otro paquete se lleva solo como referencia: un paquete puede apuntarle una clave foránea, pero nunca la cambia. La función de code owners de tu plataforma de git puede entonces exigir una revisión del equipo propietario para cada carpeta.

O un repositorio por equipo

Los equipos que además deban sacar versiones a su propio ritmo pueden tener cada uno su propio repositorio, y con él una aplicación, un proyecto y unos entornos propios. Los datos que son de un equipo y que otro necesita le llegan a ese otro como tablas de terceros: sus entornos se conectan a la base de datos del equipo propietario y replican las tablas que necesitan, según una programación. Una tabla replicada se lee como cualquier otra tabla de la aplicación, en business entities, páginas y 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

• Un propietario por tabla. Una tabla replicada se cambia en la aplicación a la que pertenece; las demás leen su copia. Las columnas marcadas como gestionadas por Archestack son la excepción: guardan los añadidos propios de un equipo, y una sincronización nunca las sobrescribe.
• Tan actual como la última sincronización. Una tabla se sincroniza entera o por lo que ha cambiado, y esto último necesita una columna que diga cuándo cambió una fila por última vez, como modified_at.
• Las conexiones pertenecen al entorno. No están en los archivos, así que cada entorno se conecta a su propio homólogo: aceptación con aceptación, producción con producción.

Un repositorio con un paquete por equipo se despliega como una sola aplicación, y un paquete puede apuntar una clave foránea a una tabla de otro paquete. Un repositorio por equipo permite que cada equipo saque versiones por su cuenta, y lo paga con copias que solo están tan actualizadas como su última sincronización.

Ramas y revisiones

• Trabaja en una rama y abre una pull request, como con cualquier código. Cada referencia es un nombre y el mismo contenido da siempre los mismos bytes, así que un diff muestra solo lo que alguien cambió: una línea de un script, una columna, el JSX de una página, nunca un id renumerado ni claves reordenadas.
• Cambiar a otra rama cambia los archivos, y el proyecto los sigue igual que sigue lo que guardas. Los cambios de tablas esperan entonces una migración; Reset Project Database, en cambio, empieza de nuevo a partir de las tablas de la rama.
• Quien revisa cambia a la rama, la tiene en marcha en su propio proyecto y ejecuta contra ella las pruebas del paquete con Run Tests. Las pruebas viven en el paquete, así que viajan con el código que prueban.
• AGENTS.md y docs/archestack/ se confirman en git, así que el agente de programación de cada desarrollador sigue las mismas reglas.

Tablas en un equipo

Un archivo de tabla describe la estructura que debe tener una tabla, no los pasos para llegar a ella. Después de un pull o de una fusión, el proyecto de cada desarrollador planifica su propia migración a partir de los archivos de tabla con Add Migration, y la revisión muestra exactamente lo que va a ejecutar esa base de datos, incluidas la pérdida de datos y los scripts tipados que dejarían de compilar. Todas las herramientas escriben un archivo de tabla en una misma forma canónica, así que las ediciones de dos personas sobre la misma tabla solo entran en conflicto donde cambian lo mismo.

Lo que decide cada entorno

Quién puede ver una página, qué es público, los permisos de la Data API y los API clients, los usuarios y los roles, las cuentas de correo, las conexiones con otros sistemas y el historial de ejecuciones no están en los archivos. Los fijan los administradores de cada entorno, así que una fusión nunca puede hacer público algo ni dar acceso a nadie.

Pruebas, aceptación y producción se despliegan desde el repositorio mediante un pipeline, como describe Estrategia de despliegue.

Ajustes

Traer un paquete existente

Un paquete que hasta ahora solo vive en un espacio de trabajo alojado entra en el repositorio una sola vez: ejecuta Connect to Workspace desde la Command Palette, inicia sesión, usa Pull Package to Folder sobre el paquete y vuelve a elegir el proyecto en la barra de estado. A partir de ahí la carpeta es la fuente y el proyecto la ejecuta. Las tablas del paquete vienen con él, y las tablas a las que apunta con una clave foránea vienen marcadas como solo de referencia, para que el proyecto pueda crear todas las tablas que el paquete necesita. En un proyecto que ya tiene base de datos, esas tablas esperan una migración como cualquier otro cambio de tablas.

A tener en cuenta

• Un proyecto empieza con las tablas vacías. La carpeta lleva la estructura, no las filas. Cargar datos maestros desde el repositorio todavía no está disponible.
• Las tablas nunca cambian al guardar. Solo una migración desplegada cambia la base de datos del proyecto, aparte de un arranque desde cero o un restablecimiento.
• Un restablecimiento descarta los datos del proyecto. Todo lo demás está en la carpeta y vuelve; las filas que introdujiste, no.
• Los cambios del builder se quedan en el proyecto hasta que los traes a la carpeta, y un restablecimiento los pierde.

Hacia dónde va esto a continuación

Espacios de trabajo y alojamiento explica dónde se ejecuta tu aplicación cuando sale de tu máquina. La referencia trata con más detalle los paquetes, los script modules y los despliegues de base de datos.