20: Voor AI Agents

Phlo is gebouwd om aangedreven te worden door AI-agenten, niet alleen door hen gelezen te worden. Elke app biedt drie CLI-lagen die een agent in staat stellen om te werken zonder voorafgaande kennis van de codebase: reflect:: om deze te begrijpen, phlo_eval om deze uit te voeren, en build:: om te transpilen en te verifiëren. Alle drie vereisen build: true en mogen nooit tegen productie draaien.

Als je een agent bent die een Phlo-app oppakt, begin hier.

20.1: De triade: begrijpen, uitvoeren, bouwen

Drie lagen, drie vlakken. Bereik ze in deze volgorde.

reflect:: en build:: draaien buiten de app (alleen bron, geen opstart), wat de reden is dat ze snel en zonder bijeffecten zijn. phlo_eval draait binnen de opgestarte app, wat de reden is dat het live data kan aanraken, en waarom het echte risico met zich meebrengt.

20.2: Aanbevolen workflow

1. Oriënteer. reflect::context voor een eenmalige snapshot: identiteit, route/view tellingen, geladen pakketten, recente fouten. Vervolgens reflect::compactRoutes.
2. Verken. reflect::find <type>, reflect::search <query>, reflect::nodeBody <name>, reflect::fileContent <relPath>.
3. Voer uit. phlo_eval '<phlo>' om live data en gedrag te controleren: een telling, een record, de werkelijke output van een methode, een gerenderde view.
4. Lees. Lees de daadwerkelijke .phlo bron voordat je gaat bewerken.
5. Bewerk. Alleen .phlo, data/app.json en entrypoints. Nooit de gegenereerde PHP.
6. Bouw en lint. build::run, en dan build::lint (lege array = schoon; zo niet, herstel de bron en herhaal).
7. Registreer. Werk data/app.md bij met structurele wijzigingen, nieuwe routes, opgeloste TODO's en resterend werk.

20.3: reflect:: in de praktijk

php www/app.php reflect::context                     # orient
php www/app.php reflect::compactRoutes               # route map
php www/app.php reflect::search "createRecord" all   # find usage
php www/app.php reflect::nodeBody home               # one method's body
php www/app.php reflect::objectIndex                 # resources, methods, props

De uitvoer is JSON. reflect::context leest data/app.md, het door mensen en agents geschreven scratchpad dat je oriënteert op intentie en status. Zie het hoofdstuk Tooling voor de volledige commando-referentie.

20.4: phlo_eval in de praktijk

phlo_eval '<phlo source>' transpileert een string van Phlo-instructies en voert deze uit in de live app. Het is de runtime aanvulling op reflectie: waar reflect:: de statische bron leest, voert phlo_eval uit tegen echte gegevens, resources en views.

php www/app.php phlo_eval "user::recordCount()"                 # 38, no return keyword
php www/app.php phlo_eval "%app->title"                         # "App"
php www/app.php phlo_eval "echo %app->error('boom')"            # <div class="app-error">boom</div>

Een enkele expressie heeft geen return nodig: het retourneert automatisch zoals een => pijllichaam. Gebruik return alleen binnen een multiline blok, waar het vereist is:

php www/app.php phlo_eval '$pro = array_filter(user::records(), fn($u) => $u->tier === "pro")
return array_values(array_column($pro, "email"))'

Regels:

• Auto-teruggeven. Een enkele regel geeft automatisch terug, precies zoals een => pijllichaam, tenzij het begint met return/apply/echo/unset/yield. Een meerregelige blok heeft zijn eigen return nodig.
• Uitvoer. return <expr> print de waarde als JSON: type-veilig, niet-schaalbaar, en fouten komen terug als {"error": ...}. echo <expr> print rauw naar stdout, voor het bekijken van gerenderde HTML/markup zoals het is.
• Scope. %resource refs worden normaal opgelost. De app wordt geconstrueerd, maar de app-controller (router/init) wordt overgeslagen, net als elke CLI-callback; resource controllers draaien wel, dus de database en resources zijn live.
• Fouten zijn leesbaar. Een mislukte oproep retourneert een gestructureerde {"error": ...} met type, bericht en bron, zodat je kunt itereren: één run leert je dat user::records() objecten retourneert, de volgende gebruikt ->tier in plaats van ["tier"].

20.5: Kracht en gevaar

phlo_eval voert willekeurige code uit met volledige app-rechten tegen de live app. In één oproep kan het wachtwoord-hashes, API-sleutels en persoonlijke gegevens lezen, en in een andere kan het gegevens muteren of verwijderen (%db->exec(...)). Er is geen sandbox.

Dat is precies waarom het beperkt is:

• CLI-only. Het weigert te draaien tijdens een HTTP-verzoek, zelfs als het in een route is geïntegreerd. Het kan nooit een netwerk-bereikbare eval-eindpunt worden.
• Build-only. Het bestaat alleen wanneer build: true. Het wordt nooit ingebouwd in een release of productie-app; het aanroepen daarvan is simpelweg een niet-gedefinieerde functie.
• Developer-authored only. Behandel de invoer zoals eval() zelf: schrijf het zelf, geef nooit onbetrouwbare of door gebruikers aangeleverde invoer door.

Binnen die grenzen is het een nauwkeurig, eerlijk hulpmiddel: het laat je zien wat de app daadwerkelijk doet, niet wat de bron suggereert dat het zou kunnen doen.

20.6: build:: in de praktijk

php www/app.php build::run      # transpile changed .phlo to PHP
php www/app.php build::lint     # [] means clean; otherwise fix the .phlo source
php www/app.php build::release  # build the release when stage/prod output changes

Lint-rapporten geven parse-fouten aan in de getranspileerde PHP. Los altijd de .phlo bron op en bouw opnieuw; patch nooit de gegenereerde PHP. Zie het hoofdstuk Tooling voor de volledige commando-referentie.