2. Strumenti e toolchain

MALDA offre un set completo di strumenti di sviluppo: un interprete interattivo, un compilatore dual-mode e un gestore di pacchetti. Questo capitolo spiega come usarli per sviluppare, eseguire e distribuire applicazioni MALDA.

2.1 Interprete

L'interprete MALDA consente di eseguire codice MALDA in modo interattivo oppure di lanciare file sorgente. Offre sia una modalità REPL interattiva (Read-Eval-Print Loop) sia l'esecuzione da riga di comando.

2.1.1 Modalità interattiva

Per avviare l'interprete interattivo, esegui semplicemente malda senza argomenti:

$ malda
MALDA (Multi Agent Language with Development Automation) Interpreter
Version 1.0.11
You can enter multiline code - the interpreter will continue reading until you type 'run', 'compile', or 'transpile'
Type 'exit' to quit, 'run' to execute, 'compile' or 'transpile' to build executable, 'help' for help
(c) 2026 - Andrea Maldini
> 

In modalità interattiva puoi:

• Inserire codice: digita codice MALDA riga per riga. L'interprete continua a leggere finché non inserisci un comando.
• run: esegue il codice inserito
• compile: compila il codice inserito in un eseguibile (modalità interpreter)
• transpile: compila il codice inserito in un eseguibile (transpile verso C#)
• help: mostra il messaggio di aiuto con i comandi disponibili e le funzionalità del linguaggio
• exit: esce dall'interprete

Esempio: sessione interattiva

> var x = 10;
> var y = 20;
> function add(a, b) { return a + b; }
> print(add(x, y));
> run
30
> 

2.1.2 Uso da riga di comando

L'interprete può anche eseguire codice dalla riga di comando:

Eseguire un file MALDA

malda <file.malda>

Esegue il file sorgente MALDA indicato.

Eseguire codice direttamente

malda -e "<code>"
malda --eval "<code>"

Esegue direttamente la stringa di codice fornita.

Eseguire da standard input

echo "print('Hello, World!');" | malda

Legge ed esegue il codice dallo standard input.

Validare solo la sintassi

malda --check "<code>"

Valida la sintassi del codice fornito senza eseguirlo. Utile per il controllo della sintassi nelle pipeline CI/CD.

2.1.3 Ottenere aiuto

Per vedere tutti i comandi e le funzionalità del linguaggio disponibili, usa:

malda help
malda --help
malda -h

Viene mostrato un aiuto completo che include:

• Comandi interattivi
• Esempi di uso da riga di comando
• Opzioni di compilazione
• Basi del linguaggio e sintassi
• Funzioni built-in
• Funzionalità AI
• Esempi rapidi

2.2 Compilatore

Il compilatore MALDA può creare eseguibili standalone dal codice sorgente MALDA. Supporta due modalità di compilazione: modalità interpreter e modalità transpile.

Modalità di runtime in sintesi

Il codice MALDA può girare in tre contesti di esecuzione comuni. Usa questa tabella per scegliere il percorso giusto prima di compilare o distribuire.

Regola pratica: sviluppa e fai debug con l'interprete; distribuisci le app server sensibili alle prestazioni in modalità transpile; usa il backend JavaScript quando la UI deve girare nel browser e MALDA resta sul server o in un bundle JS.

2.2.1 Modalità di compilazione

Modalità Interpreter (default)

In modalità interpreter, il compilatore incorpora il codice sorgente MALDA e l'interprete del runtime MALDA in un eseguibile standalone. Quando l'eseguibile gira, usa l'interprete incorporato per eseguire il codice sorgente.

Vantaggi:

• Compilazione rapida
• Piena flessibilità a runtime
• Debug agevole

Usala quando:

• Sviluppo e test rapidi
• Ti servono tutte le funzionalità dell'interprete
• La dimensione del codice non è un problema

Modalità Transpile

In modalità transpile, il compilatore prima fa transpile del codice MALDA verso C#, poi compila il codice C# in un eseguibile nativo .NET. L'eseguibile risultante include il runtime MALDA integrato direttamente nel codice compilato.

Vantaggi:

• Prestazioni migliori (codice .NET nativo)
• Eseguibile più piccolo (nessun interprete incorporato)
• Piena integrazione .NET

Usala quando:

• Le prestazioni sono critiche
• Vuoi eseguibili più piccoli
• Ti servono le prestazioni native .NET

Modalità DLL

La modalità DLL fa transpile del codice MALDA verso C# e lo compila come libreria .NET DLL invece che come eseguibile. Così puoi creare librerie MALDA riutilizzabili da referenziare in altri progetti .NET.

Usala quando:

• Crei librerie riutilizzabili
• Integri codice MALDA in progetti .NET esistenti
• Costruisci librerie di componenti

2.2.2 Compilare dalla riga di comando

Compilazione di base

malda compile <file.malda>

Compila un file MALDA in un eseguibile usando la modalità interpreter (default). L'eseguibile di output prende il nome dal file di input (es. program.exe da program.malda).

Specificare il path di output

malda compile <file.malda> -o <output.exe>
malda compile <file.malda> --output <output.exe>

Specifica il path dell'eseguibile di output.

Scegliere la modalità di compilazione

malda compile <file.malda> --mode interpreter
malda compile <file.malda> --mode transpile
malda compile <file.malda> --mode dll

Seleziona la modalità di compilazione. Se non specificata, viene usata di default la modalità interpreter.

Incorporare una cartella nell'eseguibile

malda compile app.malda -o app.exe --mode transpile --embed-folder secondbrain
malda compile app.malda -o app.exe --mode transpile --embed-folder ./data=assets

Impacchetta una directory nell'eseguibile pubblicato come risorse dell'assembly. A runtime, i programmi leggono quei file con lo schema virtuale embed:<alias>/<relative> (vedi Funzioni built-in §13.8.0). L'alias di default è il nome della cartella; usa path=alias per rinominarlo. Il flag è ripetibile. I file non vengono estratti su disco.

Compilare codice direttamente

malda -c "<code>" -o output.exe --mode transpile
malda --compile "<code>" -o output.exe --mode interpreter

Compila il codice fornito direttamente sulla riga di comando invece che da un file. Se --mode non è specificato, viene usata di default la modalità interpreter.

2.2.3 Esempi di compilazione

Esempio 1: compilazione di base (modalità Interpreter)

$ malda compile hello.malda -o hello.exe
Compiling hello.malda...
Output: hello.exe
Mode: Interpreter
Compilation successful! Executable saved to: hello.exe

Esempio 2: modalità Transpile

$ malda compile app.malda -o app.exe --mode transpile
Compiling app.malda...
Output: app.exe
Mode: TranspileToCSharp
Compilation successful! Executable saved to: app.exe

Esempio 3: creare una libreria DLL

$ malda compile library.malda -o library.dll --mode dll
Compiling library.malda...
Output: library.dll
Mode: TranspileToDll
Compilation successful! DLL saved to: library.dll

2.2.4 Funzionalità degli eseguibili compilati

Gli eseguibili compilati includono:

• Runtime MALDA incorporato: il runtime MALDA completo è incorporato nell'eseguibile
• Capacità AI: tutte le funzionalità AI (client LLM, agenti, tool) sono disponibili negli eseguibili compilati
• Esecuzione standalone: non serve installare MALDA sulla macchina di destinazione (per la modalità interpreter)
• Dipendenze esterne: alcune dipendenze esterne (es. librerie client SQL Server/PostgreSQL, DLL native LLamaSharp) possono richiedere DLL aggiuntive da distribuire accanto all'eseguibile

2.3 Gestore di pacchetti

MALDA riusa le librerie tramite pacchetti workspace sotto una directory locale packages/, copie opzionali nello store installato (~/.maldalang/packages) e import nel sorgente. Non esiste un hub pubblico di pacchetti ospitato dal progetto; i comandi di registry remoto sono opzionali per registry privati o self-hosted.

2.3.1 Pacchetti workspace (preferiti)

Metti una libreria sotto packages/<name>/ con un file .malda di ingresso (per malda-foo, in genere foo.malda, altrimenti index.malda / main.malda). Da una working directory all'interno di quell'albero — o con MALDA_PACKAGES_DIR / MALDA_SDK_ROOT impostate — importa senza installare:

import malda-demo-math;
import { clamp, VERSION } from malda-demo-math;

Ordine di risoluzione: prima lo store installato, poi le radici workspace (variabili d'ambiente, poi risalita in cerca di packages/). Vedi la demo OSS in packages/malda-demo-math/ e la nota di design docs/workspace-packages.md.

malda list --workspace
malda Examples/Modules/workspace_package.malda

2.3.2 Comandi di pacchetto offline

Questi comandi non richiedono MALDA_REGISTRY_URL:

Elencare i pacchetti workspace o installati

malda list --workspace
malda list

list --workspace mostra i pacchetti visibili dalle radici workspace. list mostra i pacchetti già copiati in ~/.maldalang/packages.

Installare da un path locale

malda install ./packages/malda-demo-math
malda install ./my-lib/package.json

Copia una directory locale, un package.json o un ingresso .malda nello store installato, così import può risolverlo senza un albero packages/ del workspace.

Uninstall / Init

malda uninstall mypackage
malda uninstall mypackage@1.2.3
malda init [directory]

init scrive un package.json di partenza nella directory di destinazione.

2.3.3 Registry remoto opzionale

Gli install <name> remoti e search richiedono MALDA_REGISTRY_URL che punti all'API del tuo registry. Il progetto OSS non gestisce un hub pubblico in stile npm. Se la variabile non è impostata, falliscono solo i comandi remoti; l'import workspace, list, list --workspace, l'install <path> locale, uninstall e init continuano a funzionare.

# Optional — only for a private/self-hosted registry
export MALDA_REGISTRY_URL=https://your-registry.example.com

malda install mypackage
malda install mypackage@1.2.3
malda search http

2.3.4 Usare i pacchetti nel codice

Preferisci import (forma canonica). using resta un alias per i caricamenti di pacchetto:

import mypackage;
import { helper } from mypackage;

var result = helper();

2.3.5 Dipendenze dei pacchetti e storage

Quando si installa da un registry remoto, le dipendenze dichiarate nei metadati del pacchetto vengono risolte e installate per prime. Le installazioni da path locale copiano la cartella selezionata così com'è.

Lo store installato tiene i file dei pacchetti, i metadati package.json e le versioni sotto ~/.maldalang/packages. I pack workspace sotto packages/ del repo non devono necessariamente essere copiati lì.

2.4 Flusso di lavoro di sviluppo

Ecco un flusso di lavoro tipico per sviluppare applicazioni MALDA:

1. Scrivere il codice: crea i file sorgente MALDA (es. app.malda)
2. Testare in modo interattivo: usa l'interprete interattivo per provare snippet di codice:

   malda
   > // Test your code here
   > run

3. Eseguire il programma completo: lancia il programma intero:

   malda app.malda

4. Condividere librerie: metti il codice riutilizzabile sotto packages/<name>/ e fai import (oppure malda install ./path nello store locale). Usa malda list --workspace per confermare la discovery.
5. Compilare per la distribuzione: crea un eseguibile standalone:

   malda compile app.malda -o app.exe --mode transpile

2.5 Integrazione IDE

MALDA distribuisce più di una superficie di editor. Non sono equivalenti per funzionalità:

• Desktop IDE: applicazione Windows nativa — l'IDE di riferimento (flussi di progetto completi, UI dei pacchetti, modelli locali / MCP dove disponibili, tab virtuali @malda-section, compilazione più ricca)
• Web IDE: playground di apprendimento nel browser (Monaco) per modifica / esecuzione / debug ed esempi — utile cross-platform, ma non a parità con il Desktop
• VS Code / LSP: editing cross-platform tramite il language server, più debug F5 in modalità interpret attraverso vscode-malda (vedi 2.6.5)

Il Desktop IDE offre:

• Syntax highlighting
• Completamento del codice
• Interprete integrato per eseguire il codice
• Compilatore integrato per creare eseguibili
• UI di gestione dei pacchetti
• Supporto al debugging

2.6 Language Server (LSP)

MALDA include un'implementazione del Language Server Protocol (LSP) così che editor come VS Code, Cursor e qualsiasi altro editor compatibile LSP possano offrire supporto avanzato all'editing dei file .malda: diagnostica, completamento, hover, go to definition, find references, rename, code action, signature help, formattazione e ricerca di simboli nel workspace.

2.6.1 Cosa offre il language server MALDA

• Sincronizzazione dei documenti: tiene traccia di apertura, modifica e chiusura dei file .malda
• Diagnostica: errori del parser e validazione dei decoratori (pubblicata dopo un breve debounce in modifica)
• Completamento: keyword, built-in, decoratori e simboli (classi, funzioni, variabili, membri)
• Hover: documentazione per simboli e decoratori
• Simboli del documento: outline (classi, funzioni, actor, prompt e i loro membri)
• Go to definition: salta alla dichiarazione di classi, funzioni, actor, prompt e variabili (singolo file)
• Find references: tutti i riferimenti al simbolo sotto il cursore (singolo file)
• Rename: rinomina il simbolo con validazione (singolo file)
• Code action: correzioni rapide per errori del parser (es. inserire una graffa o un punto e virgola mancanti)
• Signature help: firma della funzione e parametro attivo nei punti di chiamata
• Formattazione: indentazione in base al nidificarsi delle graffe (documento intero o selezione)
• Simbolo del workspace: ricerca di simboli (classi, funzioni, actor, prompt) nei documenti aperti

2.6.2 Configurare VS Code

1. Installa l'estensione che aggiunge il supporto client LSP per linguaggi personalizzati (es. “LSP” di roguelynn, oppure il supporto built-in se la tua estensione lo usa). In alternativa, usa un'estensione generica “Language Server” o “MALDA” se ne esiste una.
2. Configura il language server MALDA in VS Code. Per un LSP personalizzato che lancia un eseguibile:
   • Apri Settings (JSON) e aggiungi una configurazione client che esegue l'eseguibile malda-lsp con stdio e language id malda per i file *.malda.

Esempio di snippet settings.json (adatta il path al tuo eseguibile malda-lsp):

{
  "malda-lsp.serverPath": "C:\\path\\to\\malda-lsp.exe",
  "malda-lsp.trace.server": "off"
}

Se il setup usa un client LSP generico (es. estensione “LSP”) con una definizione “server”:

{
  "lsp.servers.malda": {
    "command": "C:\\path\\to\\malda-lsp.exe",
    "fileTypes": ["malda"],
    "languageId": "malda"
  }
}

Assicurati che i file .malda siano associati al language id malda (es. tramite “Change Language Mode” o un'estensione che registra il linguaggio malda). Il debug F5 in modalità interpret è un secondo processo — vedi 2.6.5 Debug in modalità interpret.

2.6.3 Configurare Cursor

Cursor è basato su VS Code e usa gli stessi meccanismi di configurazione. Usa uno di questi approcci:

1. Come in VS Code: se usi un'estensione client LSP in Cursor, aggiungi la stessa configurazione del server MALDA dell'esempio VS Code sopra (es. nel settings.json di Cursor o nella config dell'estensione). Punta command / serverPath al tuo eseguibile malda-lsp.
2. Impostazioni del workspace: nella cartella del progetto, crea o modifica .vscode/settings.json (Cursor lo rispetta) e aggiungi lì la configurazione del server LSP MALDA, così tutti nel repo hanno lo stesso setup.

Esempio di .vscode/settings.json nel progetto:

{
  "lsp.servers.malda": {
    "command": "C:\\path\\to\\malda-lsp.exe",
    "fileTypes": ["malda"],
    "languageId": "malda"
  }
}

Usa il path completo del tuo eseguibile malda-lsp.

2.6.4 Altri editor

Qualsiasi editor che possa avviare un language server via stdio e inviare richieste LSP (es. Sublime Text con plugin LSP, Vim/Neovim con client LSP, Emacs con eglot/lsp-mode) può usare il language server MALDA. Configura l'editor per eseguire malda-lsp.exe (o il path del tuo eseguibile malda-lsp) come language server per i file .malda e, se richiesto, imposta il language id a malda.

2.6.5 Debug in modalità interpret

malda debug-adapter parla il Debug Adapter Protocol (DAP) su stdin/stdout. È un processo separato dal language server: non inviare DAP sulla pipe stdio di malda-lsp, e non stampare banner CLI sullo stdout dell'adapter.

L'estensione in-repo vscode-malda contribuisce il debugger type malda. Premi F5 su un file .malda per lanciare l'interprete sotto l'adapter (malda.cli.path punta a un eseguibile malda che comprende debug-adapter). L'intelligenza del linguaggio resta su malda-lsp.

Questo percorso è solo interpret. Non esiste la keyword debugger. I fallimenti di transpile e il mapping #line restano in docs/debugging-transpile.md. Procedure, breakpoint e ciò che non si ferma sono in docs/debugging-interpret.md.

2.6.6 Debug JavaScript nell'IDE Desktop

I programmi che chiamano API del browser (dom.*, game.*, three.*) non possono fermarsi nell'interprete. Nell'IDE Desktop, F5 transpila il file aperto in JavaScript, lo apre nel pannello Web Preview e collega i breakpoint dell'editor allo script generato tramite source map VLQ e il debugger Chromium di WebView2.

Imposta un breakpoint su un'istruzione (per esempio una riga in Examples/Games/maldanoid.malda), premi F5 e gioca fino a quando quella istruzione viene eseguita. Continue / step over / step into / step out / pause usano la stessa toolbar Debug della modalità interpret. I locali arrivano dal call frame JavaScript; le watch e le condizioni dei breakpoint sono JavaScript, non MALDA and/or.

I file che includono sia un target client (@client() / @javascript()) sia un target host (@server() / @csharp() oppure un decoratore di route come @GET / @PAGE) sono full-stack. Nell'IDE Desktop, F5 avvia entrambe le sessioni: l'interprete esegue il debug della partizione host (le funzioni solo-client vengono saltate così dom.* non viene eseguito lì) e Web Preview esegue il debug della partizione JavaScript. Continue / step seguono l'ultimo pause; Pause ferma entrambi. L'output combinato è etichettato [server] e [client]. In un dato momento viene mostrato un solo highlight di riga corrente e un solo pannello inspect. I body @shared() possono fermarsi in entrambi i runtime.

Ctrl+F5 (Run) sui programmi solo-browser apre Web Preview senza debugger. Ctrl+F5 sui file full-stack offre ancora il dialogo Server / Client preview / Full stack. F5 in VS Code resta solo interpret. I DevTools del browser funzionano ancora sui file .js + .map compilati. Vedi 26. Backend UI JavaScript nel browser.

2.7 Property testing (panoramica)

MALDA offre property testing deterministico, basato su seed, tramite malda test. L'uso tipico nei flussi di tooling include:

• Replay stabile con --iterations e --seed
• Output orientato alla CI con --format ci
• Generazione di artifact di regressione con --write-regression

malda test --iterations 100 --seed 1337
malda test --format ci --iterations 100 --seed 1337
malda test --write-regression --regression-dir ./artifacts/regressions

Per la sintassi del linguaggio, i decoratori di capability, runProperty(...), la semantica di eleggibilità dei backend e i workflow completi, vedi Property testing.

2.8 Scrivere MALDA con un agente di coding

MALDA non compare nei dati di addestramento dei modelli di linguaggio attuali, quindi un agente a cui si chiede di scrivere sorgente .malda senza contesto inventerà una sintassi che non esiste. Il repository distribuisce un language pack compatto che risolve il problema: qualche migliaio di token di idiomi, grammatica ed esempi che un agente legge prima di scrivere. È un percorso di authoring supportato, non una curiosità — il programma più grande scritto in MALDA, l'agente di coding autonomo in Examples/RalphWiggum/ (circa 4.000 righe su undici file), è stato prodotto in questo modo.

2.8.1 Il language pack

Il pack vive in docs/llm/. Ogni file ha un compito distinto, così carichi solo ciò che serve al compito:

Per domande più approfondite, punta l'agente a Examples/, a questo manuale e alla specifica del linguaggio in docs/spec/malda-language-1.0.md. Il file radice llms.txt è un indice compatto della documentazione per gli strumenti che consumano un solo punto di ingresso.

2.8.2 L'interprete è il ciclo di feedback

Il MALDA generato va eseguito, non revisionato a occhio. L'interprete parte in fretta e riporta errori di parse e di runtime con riga e colonna, segnale sufficiente perché un agente si corregga senza ulteriori istruzioni:

malda path/to/program.malda

Da un checkout del sorgente, l'equivalente è:

dotnet run --project MaldaLang -- path/to/program.malda

Due abitudini fanno convergere il ciclo più in fretta. Tieni i programmi generati abbastanza piccoli da girare in isolamento e componili con include (vedi 1.6 Composizione del sorgente) invece di generare un file unico enorme. E installa il language server (2.6 Language Server (LSP)) nell'editor in cui gira l'agente, così le diagnostiche appaiono sul sorgente mentre viene scritto, non solo quando viene eseguito.

I programmi che leggono input o usano casualità sembrano non verificabili a un agente, che non può sedersi a un prompt. Non è così. Semina il generatore con math.seed(n) così ogni ramo è raggiungibile di proposito, poi alimenta input() con un transcript scriptato su stdin:

printf '50\n25\n39\n' | malda guess_number.malda

Seme, pipe di un transcript, assert sull'output. Così un programma interattivo passa da qualcosa su cui un agente fa asserzioni a qualcosa che può dimostrare. Nota che Spectre.Console toglie il colore quando stdout non è un terminale, quindi l'output in pipe non porta sequenze di escape anche quando il markup è corretto.

2.8.3 Modalità di fallimento note

Questi sono gli errori che un agente commette più spesso quando il pack non è caricato, o è caricato solo in parte:

• Keyword prese in prestito. let non esiste — le variabili si dichiarano con var. fn e def sono errori di sintassi; usa function.
• Parametri di prompt tipizzati. Le dichiarazioni di prompt accettano parametri solo per nome; prompt p(name: string) non è valido. Un -> ReturnType su un prompt è solo informativo.
• Built-in inventati. Un nome plausibile di un altro linguaggio non si risolve. println è la vittima più frequente; la chiamata è print. Fai grep su docs/llm/malda-builtins.tsv, che è generato dal motore, oppure leggi 13. Funzioni built-in.
• String interpolation fuori dal corpo di un prompt. "n is {n}" stampa letteralmente; non solleva un errore. Concatena con + string(n).
• Built-in solo dell'interprete nei target compilati. Un programma che gira interpretato può fallire il transpile. Verifica con malda compile prima di promettere un eseguibile.
• Annotazioni di tipo trattate come enforcement. Le annotazioni vengono parsate e alimentano il language server. I mismatch degli inizializzatori letterali producono un Warning in IDE/LSP, ma a runtime nessuno controlla i type hint, quindi un agente non deve basarsi su di essi per la validazione.