Archestack in VS Code

Con l'estensione Archestack per Visual Studio Code, la tua app è un repository git e gira sulla tua macchina. Apri la cartella del repository e l'estensione avvia per essa un Archestack locale: PostgreSQL, l'API e il builder, dal runtime incluso nell'estensione. Non c'è nessun workspace a cui connettersi e nient'altro da installare. Script module, business event, pagine, template e tabelle sono file nella cartella, e ogni file che salvi raggiunge l'Archestack locale un attimo dopo.

Quell'Archestack locale si chiama progetto. Appartiene al repository: un collega che lo clona ottiene lo stesso progetto, creato dagli stessi file. Lavorare in team spiega come gli sviluppatori di un'azienda più grande condividono un solo repository, e L'estensione VS Code nel dettaglio mostra ogni schermata.

Installa

L'estensione non è ancora nel Visual Studio Marketplace. Viene distribuita come file VSIX: in VS Code apri la Command Palette, esegui Extensions: Install from VSIX... e scegli il file. Richiede VS Code 1.90 o successivo.

Usa la build per Windows (x64). Contiene il runtime di Archestack, l'API, il builder e PostgreSQL, quindi un progetto gira senza installare nient'altro. I PDF vengono renderizzati nell'Edge o nel Chrome già presente sulla macchina. La build universale non ha il runtime e fa girare invece i progetti in Docker Desktop.

L'estensione non ha bisogno dell'estensione C# di Microsoft né del C# Dev Kit. Le sue funzionalità C# vengono dal progetto stesso, e i suoi script si aprono in un linguaggio tutto loro, quindi entrambe possono restare installate senza che le due si intralcino.

Avvia un progetto

• Una nuova app. Apri una cartella vuota, apri la vista Archestack nella barra delle attività e scegli Start project. L'estensione aggiunge archestack.json, crea un database nuovo, avvia l'API e il builder e accede da sola come admin del progetto. New Package avvia poi la prima cartella di package.
• Un repository esistente. Clonalo e aprine la cartella. La finestra avvia il progetto da sola: il primo avvio crea il database e carica il repository, prima le tabelle di ogni package e poi gli artefatti, con le dipendenze prima dei package che ne hanno bisogno. Un clone appena fatto diventa un'app funzionante in circa quindici secondi, e riaprendo la finestra si ritrova il progetto.

Il progetto è descritto in archestack.json, che viene incluso nel commit:

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

Il builder e l'API condividono webPort e PostgreSQL ascolta su dbPort, entrambi solo su 127.0.0.1. Il database del progetto, le sue password generate e i suoi log stanno in .archestack/project/, che git ignora. Lì stanno anche i pacchetti NuGet che scaricano i suoi script, in .archestack/project/nuget, oppure in un volume Docker chiamato nuget quando il progetto gira in Docker, così un riavvio non li scarica di nuovo.

La barra di stato mostra il progetto come local. Il suo elenco apre il builder del progetto nel browser, ferma il progetto e mostra i log dell'API. Reset Project Database butta via i dati del progetto e carica di nuovo il repository.

Il progetto appartiene alla finestra che lo fa girare. Chiudere o ricaricare la finestra ferma l'API e PostgreSQL, così non resta niente in esecuzione, e la finestra successiva li riavvia in pochi secondi. Se l'API smette di rispondere mentre lavori, la finestra la riavvia entro dieci secondi.

Il repository

Un repository contiene una cartella per ogni package, e uno o più file per ogni artefatto:

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

I riferimenti tra artefatti sono nomi, mai id del database. Nei file non c'è niente di ciò che si decide per ambiente: chi può vedere una pagina, se qualcosa è pubblico, le autorizzazioni della Data API e la cronologia delle esecuzioni restano in ogni ambiente. Lo stesso contenuto dà sempre gli stessi byte, quindi git mostra solo le modifiche reali.

Il progetto viene alimentato dalla cartella man mano che salvi. Una modifica salvata sotto packages/ lo raggiunge un attimo dopo, e ciò che elimini nella cartella viene eliminato anche lì, compresa un'intera cartella di package. Non c'è niente da inviare con un push. Le tabelle sono l'eccezione: cambiano tramite le migration.

New Package avvia una cartella di package, e New Artifact in Package (clic destro su qualsiasi cosa sotto packages/ nell'Explorer, oppure + su un package nella vista Workspace) scrive i file di un nuovo artefatto, chiedendo solo ciò senza cui non può esistere, come l'entity a cui appartiene un business event. Una nuova pagina è una pagina di codice. Per un nuovo file di codice condiviso viene chiesto il percorso, e la sua estensione dice cos'è. Add File su un artefatto nella vista Workspace aggiunge un file accanto a esso: una pagina riceve un file tutto suo accanto alle sue viste, che lo importano come ./Row, e uno script module, un business event o un altro script, che è un solo file, riceve un file di codice condiviso nello stesso package, in una cartella con il suo nome, che ogni script può usare.

Funziona anche il builder del progetto, nel browser. Una modifica fatta lì non è nella cartella finché non la porti dentro con Pull Package to Folder, e un package modificato in entrambi i posti viene lasciato com'è e segnalato una volta sola, così non viene sovrascritto niente. Fai il commit di ciò che porti con il pull come di qualsiasi altra modifica.

Modifica gli artefatti

Il codice di un artefatto è un file, e le sue impostazioni sono il JSON accanto, che si apre in un form. Ogni modifica nel form viene scritta nel file; Edit as JSON apre il testo.

Una business entity si apre nell'editor delle entity. Le sue tabelle e colonne si scelgono dal database del progetto, quindi un nome che non esiste viene segnalato prima che tu salvi. Anche le impostazioni del workspace stesso sono file, in workspace/: il branding con i suoi loghi e i layout dell'app pubblicata, ognuno dei quali si apre in un form.

Script C#

Script module, script dei business event, data script dei PDF, scheduled event e script di test hanno le funzionalità C# di un editor .NET. Le risposte arrivano dal compilatore del progetto stesso, quindi l'editor vede esattamente ciò che vede lo script quando gira:

• I completamenti, con la firma e la documentazione di ogni membro.
• L'hover, e le informazioni sui parametri mentre scrivi una chiamata.
• Errori e avvisi mentre scrivi.
• Go to Definition (F12). Sul metodo di uno script module apre lo script di quel modulo, su un parametro le impostazioni che lo dichiarano, e su qualsiasi altra cosa le sue dichiarazioni, in sola lettura.
• Format Document, nello stile .NET.

L'editor conosce i veri globali degli script (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc e Log), i parametri di un modulo come variabili tipizzate e, in un business event, le colonne dell'entity su Entity. Le business entity sono set tipizzati su Db e gli script module sono metodi tipizzati su Modules, quindi una colonna rinominata o un argomento sbagliato è un errore sulla sua riga prima che giri qualsiasi cosa:

// 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 come set tipizzati, nella pagina di riferimento, spiega come vengono formati i nomi.

I tipi che servono a più di uno script, come record e helper, vanno in un file C# condiviso sotto la cartella code/ di un package. È C# ordinario, ha le stesse funzionalità, e F12 su uno dei suoi tipi in uno script lo apre. Shared Code, nella pagina di riferimento, spiega cosa può usare un file condiviso.

Le librerie da NuGet si dichiarano nel nuget.json del package, ognuna a una versione esatta, e i loro tipi si completano come il resto una volta che il workspace le ha scaricate. Vedi NuGet Packages, nella pagina di riferimento.

Provare uno script module

Test, sopra il codice di uno script module, esegue il modulo come fa la scheda Test del builder, con lo script così come lo ha l'editor, salvato o no. Si trova anche nella barra del titolo dell'editor, sul modulo nella vista Workspace e nel suo form. Un pannello accanto allo script chiede i parametri, controlla ogni valore rispetto al suo tipo e li ricorda per la volta successiva. Un modulo che non ha bisogno di valori che non abbia già parte subito, e Ctrl+Enter nel pannello lo riesegue. Il pannello mostra se è passato, cosa ha restituito e cosa ha scritto in Log, e in caso di errore il messaggio con un pulsante che porta alla sua riga.

Un test è una simulazione: le scritture tramite Db e Files vengono elencate invece che eseguite, e mail e notifiche elencate invece che inviate, anche quelle dei moduli che chiama. Tutto il resto che lo script fa da sé, invece, è reale: le chiamate HTTP, System.IO e tutto ciò che fa un pacchetto NuGet, come una connessione a un altro database. Spunta Show the SQL it ran per vedere le sue istruzioni nel pannello SQL Trace. Solo i ruoli admin e owner possono provare. Un test dice cosa fa un'esecuzione; un controllo che gira ogni volta è un test case, vedi Test.

Codice delle pagine e dei template

Il codice di una pagina e il .tsx di un frontend template vengono controllati rispetto a ciò che quel codice ha davvero a disposizione quando gira: backend, pageContext, currentUser, gli hook, React, ogni componente MUI con le sue props, le icone e un tipo di riga per ogni business entity, come CustomerRow. Completamenti, hover, errori, go to definition, rename e Format Document funzionano tutti, e un return al livello più alto va bene. Gira sul TypeScript incluso in VS Code, quindi non serve installare niente.

Il codice si può distribuire su più file. I file propri di una pagina stanno nella sua cartella accanto alle viste e si importano come ./OrderRow; il codice che serve a più di una pagina va nella cartella code/ di un package e si importa da @/, da qualsiasi package del repository. Gli import vengono controllati e tipizzati, go to definition li segue, e un rename modifica ogni file che usa quel nome.

What page code can use, il link sopra il codice di ogni pagina e di ogni template, apre accanto l'elenco completo: ogni globale con cosa fa e un esempio, e i tipi di riga del progetto. Il builder mostra lo stesso elenco.

Anteprime

Open Preview to the Side, il pulsante in alto a destra di un PDF template, di un frontend template, del codice di una pagina o di un app layout, lo mostra così com'è nell'editor, salvato o no, e segue ogni modifica:

• Un PDF template viene renderizzato dal progetto. Il suo data script gira in simulazione, quindi un'anteprima non scrive mai una riga né invia una mail. I valori dei parametri si possono cambiare in alto.
• Un frontend template o una pagina viene renderizzato dall'app del progetto stesso, con in alto i parametri del template o l'id del record della pagina, e con i file propri della pagina e il codice condiviso del repository così come sono nei loro editor. Una pagina viene disegnata dentro l'app layout che l'app pubblicata le mette intorno; la barra degli strumenti passa a un altro layout o a nessuno.
• Un app layout viene disegnato dalla shell dell'app pubblicata stessa, per una pagina che scegli.
• Un template, una pagina o un layout si possono mostrare su un telefono, un tablet o un desktop alla dimensione reale, in orizzontale o a una dimensione tua, e con lo zoom per farli stare nel pannello o a una percentuale. L'anteprima successiva si apre sull'ultimo dispositivo che hai scelto.

Tabelle

Le tabelle di un package sono file, packages/<package>/tables/<table>.json, uno per tabella. Si aprono nell'editor delle tabelle: le colonne con i loro tipi, chiavi, default e foreign key, e gli indici della tabella. La vista Database elenca le tabelle del progetto; Open Database Diagram le disegna con le loro foreign key, e trascinare lì una tabella scrive il layout.json del package. New Table chiede a quale package appartiene la tabella.

Salvare un file di tabella non cambia il database del progetto. Il resto della cartella arriva al progetto, e la vista Workspace e un messaggio dicono quali modifiche alle tabelle aspettano una migration. Un database di progetto nuovo, al primo avvio o dopo un reset, riceve da solo le tabelle della cartella.

Migration e rollback

Add Migration pianifica le modifiche alle tabelle rispetto al database del progetto e mostra ogni operazione, il suo rischio e l'SQL esatto. Le operazioni che perdono dati, come eliminare una tabella o una colonna o restringere un tipo, richiedono di spuntare Allow data loss. La revisione elenca anche gli script tipizzati che la modifica smetterebbe di far compilare. La migration viene salvata come deployment in sospeso con un nome, suggerito in base a cosa cambia, come AddTechnicianSkill; Deploy la esegue, e Add and Deploy fa entrambe le cose in una volta.

La vista Deployments è la cronologia, dal più recente. Show SQL mostra cosa esegue un deployment. Roll Back to Here pianifica il ritorno delle tabelle a ciò che aveva creato un deployment precedente, e lo aggiunge come deployment in sospeso a sé, da rivedere ed eseguire come qualsiasi migration. Un rollback ripristina la struttura, mai i dati: le righe di una tabella o di una colonna che elimina sono perse.

Drop Table rimuove il file della tabella e segna la tabella; la tabella sparisce quando viene eseguita una migration con la perdita di dati consentita.

Console SQL

New SQL Query apre un editor SQL sul database del progetto, con il completamento di tabelle e colonne. Run Query (Ctrl+Enter) esegue la selezione, o l'intero file, un'istruzione alla volta, ognuna con il proprio commit, e si ferma al primo errore. I risultati si aprono accanto all'editor, fino a 1.000 righe ciascuno, e si copiano come CSV. Niente chiede conferma prima di un DELETE.

Piani delle query e tracciamento SQL

Explain Query mostra il piano che PostgreSQL sceglie per la selezione, o per l'istruzione in cui si trova il cursore: ogni passo, cosa legge ciascuno e quante righe si aspetta. Explain Analyze Query (Ctrl+Alt+Enter) esegue l'istruzione per avere tempi e righe reali, in una transazione annullata con un rollback, così anche un DELETE conserva le sue righe. Il piano segnala il passo che richiede più tempo e ciò che merita un secondo sguardo: una scansione che legge migliaia di righe per tenerne poche, una stima delle righe lontana da quelle restituite, un ordinamento che ha dovuto passare su disco.

Trace SQL mostra l'SQL che Archestack stesso invia. Fai clic destro su uno script module o su una business entity nella vista Workspace, oppure usa il pulsante sul suo file o nel suo form. Uno script module gira con i valori dei parametri che indichi, in simulazione per impostazione predefinita, e le sue scritture vengono registrate invece che eseguite. Una business entity viene letta come la legge la griglia di una pagina. Il pannello SQL Trace elenca poi ogni istruzione con i suoi valori, quanto è durata e il codice che l'ha inviata, e può raggruppare le istruzioni uguali per mostrare una query che gira una volta per riga. Fai clic su un'istruzione per vederne il piano, aprirla come SQL con i valori al loro posto o copiarla. Nella vista Testing, Run with SQL Trace fa lo stesso per i test case. Solo i ruoli admin e owner possono usare il tracciamento.

Test

Run Tests nella vista Workspace esegue i test di tutti i package, quelli di un solo package, una test suite o un singolo test case. Prima la cartella viene passata al progetto, così un test case mette alla prova gli script e le pagine così come sono nella cartella. Ogni test case gira in una sandbox di test, un database a sé, mai sui dati del progetto, e mail e notifiche vengono registrate invece che inviate. Quattro test case girano contemporaneamente. Nell'albero ogni test case mostra il suo ultimo risultato e quanto ci ha messo; facendo clic si vede cosa è fallito, atteso contro effettivo, e cosa ha stampato. La vista Testing elenca gli stessi test case.

Un controllo che un solo soggetto e un solo operatore non riescono a esprimere è un controllo in codice: un file C# a sé che gira dopo il test case, con Result, Output, Error e Failed a disposizione, e fallisce quando lancia un'eccezione, quando fallisce un Assert o quando restituisce false.

Event Log

La vista Event Log mostra cosa è stato eseguito nel progetto, raggruppato per tipo: business event, script module, scheduled event, esecuzioni dei test, mail e backup, ognuno con le esecuzioni e i fallimenti dell'ultimo giorno. Un nuovo fallimento viene contato sul badge della vista e segnalato nel momento in cui avviene. Fai clic su una voce per leggere tutto ciò che ha registrato. Open Artifact apre il file dello script in cui è fallito, sulla riga che ha fallito.

Data API

Un endpoint della Data API espone una business entity ad altri sistemi, a un indirizzo come /api/data/v1/customers. Appartiene a un package come ogni altro artefatto: un solo file, api/customers.json, chiamato come la sua route e con dentro tutte le sue versioni. Il file si apre in un form: l'entity che espone, il nome e la route, e per ogni versione lo stato, il giorno di sunset, la dimensione della pagina, le operazioni e i campi. Ogni campo è un nome pubblico su una colonna dell'entity, restituito, scrivibile o obbligatorio; il form propone le colonne e segnala un campo la cui colonna l'entity non ha.

Un endpoint può anche chiamare uno script module, per un lavoro che va oltre leggere o scrivere righe. Ogni versione nomina il modulo e l'unico metodo a cui risponde, POST con i parametri in un body JSON o GET con i parametri nella query string, ed elenca i parametri che i chiamanti inviano: un nome pubblico su un parametro del modulo, obbligatorio o no, con una descrizione. Il form offre i parametri del modulo e segnala quello di cui il modulo ha bisogno ma che la versione non passa. Chi chiama riceve ciò che il modulo restituisce, in JSON. Un modulo segnato come admin only resta tale: solo admin e owner possono chiamarlo, quindi il suo endpoint non accetta autorizzazioni.

Una versione pubblicata può solo crescere. Aggiungere campi e operazioni va bene; rimuovere o rinominare un campo, togliergli la scrittura, renderlo obbligatorio o eliminare un'operazione romperebbe i sistemi che la chiamano, quindi va in una nuova versione, che il form avvia come copia di quella mostrata. Per un endpoint che chiama uno script module, la versione mantiene il suo modulo e il suo metodo, e acquisisce solo parametri facoltativi. Un salvataggio che rompe una versione pubblicata viene rifiutato, con il motivo. Attivare una versione propone di deprecare quelle più vecchie: restano servite e dicono a chi le chiama, nei loro header, che sono deprecate e, appena ne imposti uno, il loro giorno di sunset, finché non le porti a Retired.

La vista Data API elenca gli endpoint del progetto con le loro versioni, e i suoi API client. Try It su un endpoint o una versione invia richieste reali e mostra la risposta così com'è arrivata, header compresi: come te, con l'SQL eseguito se lo vuoi, o con la chiave di un API client, per vedere esattamente cosa può chiamare quel client. Su un endpoint che chiama uno script module invia la chiamata con parametri di esempio. I pulsanti della vista aprono il documento OpenAPI di tutto ciò che puoi chiamare e How to connect, la guida per chi ci costruisce sopra.

Chi può chiamare un endpoint lo decide ogni ambiente e non è mai nel file. Edit access in the workspace, nel form, apre le autorizzazioni: quali ruoli possono elencare, leggere, creare, aggiornare o eliminare, o chiamare il modulo. Un API client è un account di servizio con ruoli e una chiave invece di una password. New API Client ne crea uno e mostra la sua chiave una sola volta; Rotate Key la sostituisce, e la vecchia chiave smette subito di funzionare.

Agenti di coding

Il repository dice agli agenti di coding come Claude Code e Codex cosa possono crearci, come l'MCP Server fa con un modello connesso. New Package e ogni pull scrivono:

• AGENTS.md: come una modifica arriva all'app, le regole che ogni file segue, gli errori da evitare e un esempio di ogni tipo di artefatto. Viene riscritta solo la sezione marcata dall'estensione, quindi le note del tuo team nel file restano.
• CLAUDE.md, che indirizza Claude Code verso AGENTS.md.
• docs/archestack/: le guide agli script e ai test e ciò che il codice delle pagine può usare. Viene incluso nel commit, così le ha anche un agente che lavora su un clone appena fatto.
• .archestack/context/: le business entity del progetto e il suo modello dati generato, solo per questa macchina.

Update Agent Instructions li scrive di nuovo. Le modifiche di un agente sono file salvati come i tuoi, quindi raggiungono il progetto allo stesso modo; una persona li rivede e ne fa il commit.

Lavorare in team

Per un'azienda più grande il repository è la fonte di verità dell'applicazione, come l'infrastructure as code descrive i server: tutto ciò che compone l'app è un file in git, rivisto e versionato come qualsiasi altro codice, e ogni ambiente viene creato da quei file. L'estensione è il modo in cui ogni sviluppatore ci lavora.

Sviluppatore 1

File del repository Progetto locale

Sviluppatore 2

File del repository Progetto locale

Sviluppatore 3

File del repository Progetto locale

push e pull

Server git

Il repository: branch, pull request e main

Pipeline

Build, test, piano, deploy

Test

Archestack ospitato

Collaudo

Archestack ospitato

Produzione

Archestack ospitato

Ogni sviluppatore fa girare la propria copia

Ogni sviluppatore clona il repository e lo apre, e la sua finestra fa girare un progetto tutto suo, con il proprio database, sulla sua macchina. Nessuno condivide un workspace di sviluppo, quindi nessuno salva sopra il lavoro di qualcun altro, e uno script che si rompe resta su una sola macchina finché non viene sistemato. Un nuovo membro del team ha l'app funzionante circa quindici secondi dopo il clone. Le tabelle di un progetto partono vuote, e i test case scrivono le righe di cui hanno bisogno nella propria sandbox, quindi ogni sviluppatore testa sugli stessi dati.

Un package per team

Un'app grande è composta da più package, ognuno una cartella con le proprie tabelle, business entity, pagine, script e test. Dividili come è divisa l'azienda, e i team lavorano per lo più in cartelle proprie:

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 package indica i package di cui ha bisogno nel suo package.json, per nome e intervallo di versioni:

{
  "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 versione semplice come 2.0 significa quella versione o una successiva, [2.0] esattamente quella, e [2.0,3.0) qualsiasi versione da 2.0 fino a 3.0 esclusa. Un progetto carica le dipendenze prima dei package che ne hanno bisogno. Una tabella di proprietà di un altro package viene portata come solo riferimento: un package può puntarci con una foreign key, ma non la modifica mai. La funzionalità code owners della piattaforma git che usi può poi richiedere, per ogni cartella, una revisione da parte del team proprietario.

Oppure un repository per team

I team che devono anche poter rilasciare secondo i propri tempi possono invece avere ciascuno un repository, e con esso un'app, un progetto e ambienti tutti loro. I dati che un team possiede e di cui un altro ha bisogno arrivano all'altro come tabelle third-party: i suoi ambienti si connettono al database del team proprietario e fanno il mirror delle tabelle di cui hanno bisogno, su pianificazione. Una tabella in mirror si legge come qualsiasi altra tabella dell'app, nelle business entity, nelle pagine e negli script.

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 solo proprietario per tabella. Una tabella in mirror si modifica nell'app che la possiede; le altre leggono la propria copia. Le colonne marcate come gestite da Archestack sono l'eccezione: contengono le aggiunte proprie di un team, e un sync non le sovrascrive mai.
• Aggiornata all'ultimo sync. Una tabella si sincronizza per intero o solo per ciò che è cambiato, e per questo serve una colonna che dica quando una riga è cambiata l'ultima volta, come modified_at.
• Le connessioni appartengono all'ambiente. Non sono nei file, quindi ogni ambiente si connette alla propria controparte: collaudo con collaudo, produzione con produzione.

Un solo repository con un package per team viene distribuito come un'unica app, e un package può puntare con una foreign key a una tabella di un altro package. Un repository per team permette a ogni team di rilasciare per conto suo, e lo paga con copie aggiornate solo quanto il loro ultimo sync.

Branch e revisioni

• Lavora su un branch e apri una pull request, come con qualsiasi codice. Ogni riferimento è un nome e lo stesso contenuto dà sempre gli stessi byte, quindi un diff mostra solo ciò che qualcuno ha cambiato: una riga di uno script, una colonna, il JSX di una pagina, mai un id rinumerato o chiavi riordinate.
• Fare il checkout di un altro branch cambia i file, e il progetto li segue come segue i tuoi salvataggi. Le modifiche alle tabelle aspettano poi una migration; Reset Project Database invece riparte dalle tabelle del branch.
• Un revisore fa il checkout del branch, lo fa girare nel proprio progetto ed esegue su di esso i test del package con Run Tests. I test stanno nel package, quindi viaggiano con il codice che testano.
• AGENTS.md e docs/archestack/ sono inclusi nel commit, quindi l'agente di coding di ogni sviluppatore segue le stesse regole.

Le tabelle in un team

Un file di tabella descrive la struttura che una tabella deve avere, non i passi per arrivarci. Dopo un pull o un merge, il progetto di ogni sviluppatore pianifica la propria migration dai file delle tabelle con Add Migration, e la revisione mostra esattamente cosa eseguirà quel database, compresi la perdita di dati e gli script tipizzati che smetterebbero di compilare. Ogni strumento scrive un file di tabella in un'unica forma canonica, quindi le modifiche di due persone alla stessa tabella vanno in conflitto solo dove cambiano la stessa cosa.

Cosa decide ogni ambiente

Chi può vedere una pagina, cosa è pubblico, le autorizzazioni della Data API e gli API client, utenti e ruoli, account di posta, connessioni ad altri sistemi e cronologia delle esecuzioni non sono nei file. Li impostano gli amministratori di ogni ambiente, quindi un merge non può mai rendere pubblico qualcosa o dare accesso a qualcuno.

Il deploy in test, collaudo e produzione avviene dal repository tramite una pipeline, come descrive Strategia di deployment.

Impostazioni

Portare dentro un package esistente

Un package che finora vive solo in un workspace ospitato entra nel repository una volta sola: esegui Connect to Workspace dalla Command Palette, accedi, usa Pull Package to Folder sul package e scegli di nuovo il progetto nella barra di stato. Da quel momento la cartella è la fonte e il progetto la fa girare. Le tabelle del package vengono con esso, con quelle a cui punta con una foreign key marcate come solo riferimento, così il progetto può creare ogni tabella di cui il package ha bisogno. In un progetto che ha già un database, quelle tabelle aspettano una migration come qualsiasi altra modifica alle tabelle.

Trappole

• Un progetto parte con le tabelle vuote. La cartella porta la struttura, non le righe. Il caricamento dei dati anagrafici dal repository non è ancora disponibile.
• Le tabelle non cambiano mai al salvataggio. Solo una migration eseguita cambia il database del progetto, a parte un avvio da zero o un reset.
• Un reset butta via i dati del progetto. Tutto il resto è nella cartella e ritorna; le righe che hai inserito no.
• Le modifiche fatte nel builder restano nel progetto finché non le porti nella cartella con un pull, e un reset le perde.

Dove andare dopo

Workspace e hosting spiega dove gira la tua app una volta che lascia la tua macchina. La pagina di riferimento tratta più a fondo i package, gli script module e i deployment del database.