@appaflytech/zeyrek-ai-mcp 0.0.2 → 0.0.4

package/dist/resources/guides/translation.md

@@ -0,0 +1,80 @@
+# Çoklu Dil Rehberi (page/content translations)
+
+Sayfa içeriğini (metin, buton etiketi, placeholder…) çoklu dilli yapan özellik. Studio panelinin
+kendi arayüz dili (`i18n.md`, yalnız frontend'i ilgilendirir) ile **karıştırma** — bu rehber
+**son kullanıcının gördüğü sayfa metnini** kapsar. Kaynak: `TranslationsController.cs`
+(`zeyrek-backend/src/NgApps.Tenant.API/Controllers/`) + `zeyrek-frontend/docs/features/page-translations.md`.
+
+## Model
+
+- Çeviri kaydı **application başına** tutulur (`(applicationId, language, key)` başına bir satır);
+  aynı application'daki tüm sayfalar aynı anahtar kümesini paylaşır.
+- Bir kayıt isteğe bağlı bir **`componentId`**'ye bağlanabilir — o komponent silinince kaydı da
+  kademeli silinir. Salt organizasyon amaçlıdır; runtime çözümlemeyi etkilemez (çözümleme yalnız
+  `key`'e bakar).
+- Proje **dilleri** ve **varsayılan dil** application değil **proje** düzeyinde ayardır
+  (`project_get`/`project_update` `languages`/`defaultLanguage`) ve tam **ISO 639-1** kod
+  kümesinden seçilir (`ProjectConstants.SupportedLanguages`, ~184 kod). `translation_update`'e
+  proje dillerinde olmayan bir kod verirsen platform isteği reddeder — önce `project_update` ile
+  dili ekle.
+
+## Araçlar
+
+| Tool | Ne yapar |
+|---|---|
+| `translation_list` | Application'ın tüm `(language, key, value)` kayıtlarını düz liste döner |
+| `translation_update` | `keys` (ekle/güncelle, `componentId` opsiyonel) ve/veya `deletedKeys` (sil) — ikisi de aynı çağrıda verilebilir, en az biri dolu olmalı |
+| `project_update` | `languages`/`defaultLanguage` — proje dillerini kurar/değiştirir |
+
+```jsonc
+// yeni anahtar aç / var olanı güncelle
+{ "applicationId": "<app id>", "keys": [
+  { "key": "home.welcome", "values": { "tr": "Hoş geldiniz", "en": "Welcome" } }
+] }
+
+// bir anahtarı sil, bir başkasını aynı çağrıda güncelle
+{ "applicationId": "<app id>",
+  "keys": [{ "key": "home.title", "values": { "tr": "Ana sayfa" } }],
+  "deletedKeys": ["home.old_banner"] }
+```
+
+## Bir prop'u çeviriye bağlamak
+
+Sayfa şemasında (`platform_guide('page')` Kural 1) çeviriye bağlı bir prop **Prop nesnesinin**
+`type:'translation'` varyantıdır — `PropValueType.Translation` (`DesignComponentProperty.cs`)
+backend'de zaten tanımlı, Studio'nun "Translate" aksiyonunun ürettiği şekil budur:
+
+```jsonc
+{ "op": "replace_prop", "target": "welcome_text", "prop": "text",
+  "value": { "type": "translation", "ref": "home.welcome", "data": "Hoş geldiniz" } }
+```
+
+- **Anahtar `ref`'tedir, `data` DEĞİL.** Runtime her `getNodeProps` turunda `data`'yı
+  `resolveTranslation(...)` sonucuyla EZER (`code` prop'larıyla aynı davranış — `page.md` Kural 1c
+  bunun `code` karşılığını anlatır). `ref`'i okumadan/yazmadan `data`'ya güvenme; `data` yalnız
+  Studio'nun sakladığı önceki statik değerdir (fallback/geri dönüş amaçlı, çözümlemeyi ETKİLEMEZ).
+- **Fallback zinciri:** aktif dil → projenin varsayılan dili → anahtarın kendisi. Boş string de
+  "eksik" sayılır ve zincirde bir alt basamağa düşer — bir anahtar hiçbir zaman boş render olmaz.
+- Hangi prop'lar çeviriye bağlanabilir platformca kısıtlanmaz (Studio'da yalnız `text`/`long-text`
+  tipli prop'larda "Translate" aksiyonu gösterilir, ama şema düzeyinde her static prop aynı Prop
+  şeklini kabul eder).
+
+## Dil değiştirme: `language-selector`
+
+Son kullanıcı dili `language-selector` komponentiyle değiştirir (`platform_guide('component')`
++ `componentCatalog` içindeki `language-selector` kaydı): `change` olayı `machine.setLanguage(value)`
+çağırır, seçim `localStorage`'a (`zeyrek:{appSlug}:lang`) yazılır ve çeviriye bağlı **bütün**
+prop'lar sayfa yenilenmeden yeniden çözülür — ayrı bir akış kurmana gerek yok, komponenti sayfaya
+eklemen yeterli. Projede dil tanımlı değilse (`languages` boşsa) liste boş çizilir.
+
+## Bilinen sınırlar
+
+- **Flow adımlarında Translation kaynağı YOK.** `value.type` sözlüğünde (`platform_guide('page')`
+  Kural 1c sonundaki tablo) `translation` yoktur — bir flow adımının **değerini** doğrudan bir
+  çeviri anahtarına bağlayamazsın, yalnız sayfa şemasındaki statik prop'lar bağlanabilir. İfadeden
+  okumak gerekiyorsa `t('anahtar')` Jexl fonksiyonu kullanılır (`platform_guide('expressions')`).
+- **Runtime sayfa yanıtı sunucu tarafında önbelleklidir** (Postgres `caches` tablosu). Bir
+  `translation_update`/`project_update(languages)` çağrısından hemen sonra `page_runtime_get`
+  eski değerleri gösterebilir — önbellek süresi dolana kadar. Acil doğrulama gerekiyorsa
+  `translation_list` ile yazma tarafını, `page_runtime_get` ile okuma tarafını AYRI doğrula.
+- Mobil runtime (`apps/mobile`) bu özelliği henüz beslemiyor — yalnız web.

package/dist/resources/guides/workflow.md

@@ -2,6 +2,65 @@
 
 Buradaki kurallar gerçek projelerde (qm, hr) **deneyerek doğrulandı**.
 
+## Her adım NE İŞE YARADIĞINI yazar (WF-024, block)
+
+Studio kanvası adımın **adını** gösterir, ne yaptığını göstermez. 11 satırlık bir `code` adımının
+işini anlamak için ifadeyi satır satır okumak gerekir — akışı devralan geliştirici için bu, her
+seferinde tersine mühendisliktir. Bu yüzden **her adım** ve **akışın kendisi** bir `description`
+taşır; gateway açıklamasız gövdeyi platforma göndermez.
+
+```jsonc
+{ "name": "anket-kaydet", "type": "workflow",
+  "description": "Anket başlığını ve sorularını tek çağrıda kaydeder.",
+  "steps": [
+    { "id": "<GUID>", "name": "createSurvey", "type": "table",
+      "description": "Anket başlığını surveys'e yazar; oluşan id sonraki adımlarda kullanılır.",
+      "rule": { … } }
+  ] }
+```
+
+- **Mekanizmayı değil NİYETİ yaz.** `"assignments tablosunu status='Aktif' ile okur"` koddan zaten
+  okunuyor ve hiçbir şey eklemiyor. `"kullanıcının asal pozisyonunu seçer; birden çok aktif atama
+  varsa is_primary olanı tercih eder, o da yoksa ilkini alır"` — yazılmadıkça hiçbir yerde
+  bulunmayan bilgi budur.
+- **`start` ve `end` muaftır** (kural onları hiç sormaz): ikisi de yapısal işaretçi, açıklanacak
+  davranışları yok.
+- **Gateway'in enjekte ettiği `gatewayOnError` adımı kendi açıklamasını taşır** — o adımı sen
+  yazmadığın için kural seni onun yüzünden durdurmaz.
+- Alan **kalıcıdır ve çalışma zamanını etkilemez**: motor okumaz, yalnız Studio'da kanvas
+  düğümünde ⓘ ikonu + popover olarak ve adım panelinde düzenlenebilir metin olarak görünür.
+  İnsan da düzeltebilir.
+- `preview` bu kuralın dışındadır — kaydedilmeyen bir denemede açıklama aranmaz.
+- Aynı disiplin ucun kendisi için de geçerli: `platform_guide('microservice')` §MS-014.
+
+## Tuzağı varsa `caution` yaz (opsiyonel, kural yok)
+
+`description` "bu adım ne işe yarar" sorusunu cevaplar. `caution` bambaşka bir soruyu cevaplar:
+**"burada neye dikkat etmek gerekiyor."** İkisi ayrı alandır çünkü tek metne sıkıştırıldıklarında
+ikisi de okunmaz olur — açıklama uyarı listesine döner, uyarı da açıklamanın içinde kaybolur.
+
+**Bu alanı hiçbir kural zorlamaz ve doldurma metin kabul edilmez.** Adımın gerçek bir tuzağı
+yoksa alanı hiç yazma. Yazmaya değer olanlar:
+
+- **İdempotent değil** — "iki kez çalışırsa çift atama yazar; çağıran tarafta koruma yok"
+- **Kapsam bu adımda değil** — "tenant filtresi burada yok, kimlik kapsaması bağlı middleware'de"
+- **Dış bağımlılık** — "ödeme sağlayıcısına senkron çağrı; sağlayıcı yavaşlarsa istek bekler"
+- **Sessiz düşen dal** — "eşleşme bulunamazsa hata dönmez, boş dizi döner"
+
+```jsonc
+{ "id": "<GUID>", "name": "createAssignment", "type": "table",
+  "description": "Kullanıcıyı seçilen pozisyona atar.",
+  "caution": "İki kez çalışırsa çift atama yazar; çağıran tarafta idempotency koruması yok." }
+```
+
+**Yazılmayacaklar:** `"bu adım veriyi okur, dikkat"` gibi mekanizma tekrarı, `description`'ın
+başka kelimelerle yazılmışı, `"dikkatli olun"` gibi genel tavsiye. Bunlar kanvastaki ⚠ işaretini
+değersizleştirir — işaretin tüm değeri **seyrek** olmasından gelir.
+
+Alan `description` gibi inerttir: motor okumaz. Studio'da kanvas düğümünde kehribar ⚠ ikonu,
+adım panelinde düzenlenebilir metin, analiz belgesinde ayrı satır olarak görünür; `workflow_get`
+outline görünümünde geri okunur — sonraki oturumda tuzağı tam gövdeyi almadan görürsün.
+
 ## Karar kuralları
 
 1. **DTO önce (yalnız workflow tipinde).** `type='workflow'` için girdi/çıktı sözleşmesini
@@ -49,6 +108,55 @@ Bağlanmamış step çalışmaz. `start` tek branch taşır; normal step'ler `su
 `condition` koşul branch'leri + `else`; terminal step'ler (`response`, `convert`, `revert`,
 `end`) **branch taşımaz**.
 
+## Hata yolu
+
+**Gateway workflow ve middleware tanımlarına hata yolunu otomatik ekler** (yanıtta
+`gatewayNormalized`): start adımına `type: 'global-error'` dalı + 500 dönen bir `response` adımı
+(`gatewayOnError`). Kendi hata gövdeni istiyorsan bu adımın `bodyExpression`'ını değiştir ya da
+tanımı kendi global-error dalınla gönder — dal **bağlıysa** (`nextStepId` doluysa) gateway
+dokunmaz. `nextStepId: null` ile bağlanmamış gönderirsen gateway ikinci bir dal eklemez, mevcut
+dalını enjekte ettiği hata adımına bağlar.
+
+**Fail dallarını tek tek bağlamana gerek yok.** Bir adımın `fail` dalı bağlanmamışsa
+(`nextStepId: null`) ya da hiç yoksa, hata **kendiliğinden** global-error dalına gider. `fail`
+dalını yalnız o adıma özel bir telafi akışı (örn. "kayıt yoksa oluştur") istiyorsan bağla.
+
+Global-error dalında `error` değişkeni tanımlıdır:
+
+```jsonc
+{ "code": "RowAlreadyExists", "message": "…", "detail": "…", "type": "…",
+  "step": { "id": "…", "name": "writeRow", "type": "table", "data": …, "input": [ … ] } }
+```
+
+`error.step` hangi adımın patladığını söyler — hata yanıtına koymadan önce iki kez düşün, iç
+yapıyı dışarı sızdırır.
+
+**Kurallar ve sınırlar:**
+
+- **Global-error dalı TEK olmalı ve START adımında durmalı.** Başka adıma koyulan dal hiç
+  çalışmaz, platform 400 döner. Gateway bunu `WF-022` ile istek gitmeden reddeder.
+- **Hata `response` adımı ReturnDto'ya bağlı değildir.** Global-error modunda platform sözleşmeyi
+  atlar, gövde serbesttir — `returnDtoId` ile çakışmaz.
+- **Loop içi hatalar global-error dalına GİTMEZ.** Loop çocuk bağlamı bu yönlendirmeyi kapatır;
+  loop adımının kendi `fail` dalını bağla.
+- **`automation` tipinde `response` adımı yasaktır**, bu yüzden gateway bu tipe enjeksiyon
+  yapmaz. Hata yolunu kendin yaz: global-error dalını `revert` (tetikleyen satır işlemini geri
+  alır) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
+- **Hata yolu hiç yoksa** akış patladığında platform 500 + ham exception mesajı döner. Çalışır,
+  ama çıktı denetimsizdir ve lokalize değildir.
+
+> **Preview HTTP 200 dönerken bile akış patlamış olabilir.** `executionSuccess` yalnız SON adıma
+> bakar; ortada patlayıp hata dalından dönen akış `true` gösterir. Gateway tüm adımları (iç içe
+> `children` ve tetiklenen `automations` dâhil) tarar ve hata bulursa yanıta `runtimeErrors`
+> alanını ekler — `workflow_preview` ve `automation_preview` yanıtlarında bu alanı kontrol et.
+>
+> **`runtimeErrors` her tool'da aynı şeyi ölçmez.** Alan yalnız `steps[]` taşıyan yanıtlarda adım
+> adım tarama yapar. `microservice_execute` / `microservice_debug` / `microservice_preview`
+> yanıtlarında gateway sadece `httpStatus >= 400` durumunu bulgu sayar: bu tool'lar adım ağacını
+> `executionItems` olarak döner ve o düğümlerde hata işareti yoktur, yani HTTP 200 gövdesine gömülü
+> bir microservice hatası `runtimeErrors` üretmez. Orada `body`'yi kendin oku ve şüpheliyse
+> `microservice_debug` ile adım adım bak. `query_preview` yanıtları hiç kapsanmaz.
+
 ## Condition step kuralları
 
 Koşullar `rule.items[]` dizisindedir ve **sırayla** değerlendirilir; ilk `true` olan dala
@@ -151,6 +259,11 @@ Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seç
 
 - `rule` içinde `datasourceId` + `entityId` zorunlu; `selectFields`/`filters` öğelerinde
   **`fieldId` zorunlu** (yalnız `fieldSlug` yetmez → `EvaluateWorkflowStepFailedException`).
+- **`selectFields` = akışın gerçekten OKUDUĞU alanlar.** Entity'nin tüm alanlarını işaretlemek
+  her satırı gereksiz büyütür (join'li adımda maliyet katlanır) ve adımın ne ürettiğini
+  okunamaz hâle getirir. Sonraki adımların, filtrelerin ve response `bodyExpression`'ının
+  dokunmadığı alanları çıkarın — gateway bunları **WF-023 (warn)** ile adıyla sayar. Çıktıyı
+  bütün olarak geçiriyorsanız (`{ list: rows.data }`) kural susar.
 - **Table step JOIN kurabilir** ve alias/path disiplini microservice'inkiyle **birebir aynıdır**
   (Studio aynı form bileşenlerini kullanır): `joins[].path` = `<kökEntityId>.<ilişkiAlanı…>`,
   join'li `selectFields[].path` = kök id olmadan aynı zincir, kök alanlarda `path` yok.
@@ -243,12 +356,15 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 ```jsonc
 {
   "name": "Product Lookup", "slug": "product-lookup", "type": "workflow",
+  "description": "Ada göre tek ürün getirir; bulunamazsa hata yoluna düşer.",
   "parameterDtoId": "<girdi DTO id>", "parameterBehavior": "object",
   "returnDtoId": "<çıktı DTO id>", "returnBehavior": "object",
   "steps": [
     { "id": "<GUID-1>", "name": "Start", "type": "start",
-      "branches": [{ "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" }] },
+      "branches": [{ "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" },
+                   { "id": "<GUID-7>", "name": "global-error", "type": "global-error", "nextStepId": "<GUID-8>" }] },
     { "id": "<GUID-3>", "name": "load_product", "type": "table",
+      "description": "input.productName ile ürünü okur; tek kayıt bekler.",
       "rule": { "stepType": "table", "datasourceId": "<datasource id>", "entityId": "<entity id>",
                 "operation": "get", "isSingle": true,
                 "selectFields": [{ "alias": "<entity slug>", "fieldId": "<alan id>", "fieldSlug": "name" }],
@@ -258,9 +374,16 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
                 "limit": { "name": "limit", "offset": "offset", "source": "query-string" } },
       "branches": [{ "id": "<GUID-4>", "name": "success", "type": "success", "nextStepId": "<GUID-5>" },
                    { "id": "<GUID-6>", "name": "fail", "type": "fail", "nextStepId": null }] },
+                   //                                   ^ bağlanmamış fail dalı: hata global-error dalına gider
     { "id": "<GUID-5>", "name": "product_response", "type": "response",
+      "description": "Bulunan ürünün adını 200 ile döner.",
       "rule": { "bodyExpression": "{ name: load_product.data.name }", "httpStatusCode": 200,
-                "headerExpression": "{  }" }, "branches": [] }
+                "headerExpression": "{  }" }, "branches": [] },
+    { "id": "<GUID-8>", "name": "onError", "type": "response",
+      "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+      "rule": { "stepType": "response", "httpStatusCode": 500,
+                "bodyExpression": "({ code: error.code, message: error.message })" },
+      "branches": [] }
   ]
 }
 ```
@@ -315,6 +438,8 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 - Automation'da `isQueue`/`operation` eksik ya da returnDtoId verilmiş (WF-010, block)
 - `fields` ∩ `selectFields` çakışması (WF-012, warn) · join'li table'da boş selectFields (WF-007, warn)
 - Join'li table step'inde kök `rule.alias` boş (WF-019, block — Postgres 42601'in sebebi)
+- Akışta hiç okunmayan `selectFields` alanı (WF-023, warn — gereksiz taşınan sütun)
+- Adımda ya da akışta `description` yok (WF-024, block — Studio'da adım okunamaz kalır)
 - İlişki alanının içini okuyan ifade (WF-020, warn — join yoksa alan düz FK'dır)
 - `set-user` adımı olmadan `user` okuyan middleware (MW-003, warn)
 

package/dist/server.js

@@ -5,12 +5,14 @@ import { registerDeploymentTools } from './tools/deployments.js';
 import { registerDatasourceTools } from './tools/datasources.js';
 import { registerAutomationTools } from './tools/automations.js';
 import { registerOrganizationTools } from './tools/organizations.js';
+import { registerExternalComponentTools } from './tools/externalComponents.js';
 import { registerComponentTools } from './tools/components.js';
 import { registerPlatformTools } from './tools/platformInfo.js';
 import { registerTemplateTools } from './tools/templates.js';
 import { registerWorkflowTools } from './tools/workflows.js';
 import { registerLayoutTools } from './tools/layouts.js';
 import { registerAccessTools } from './tools/access.js';
+import { registerTranslationTools } from './tools/translations.js';
 import { registerFlowTools } from './tools/flows.js';
 import { registerKnowledgeResources } from './resources/knowledge.js';
 import { registerSchemaResources } from './resources/schemas.js';
@@ -41,12 +43,14 @@ const moduleRegistrations = {
     view: registerViewTools,
     page: registerPageTools,
     component: registerComponentTools,
+    externalComponent: registerExternalComponentTools,
     flow: registerFlowTools,
     layout: registerLayoutTools,
     variable: registerVariableTools,
     folder: registerFolderTools,
     file: registerFileTools,
     access: registerAccessTools,
+    translation: registerTranslationTools,
     template: registerTemplateTools,
     organization: registerOrganizationTools,
     dependency: registerDependencyTools,

package/dist/tools/externalComponents.js

@@ -0,0 +1,285 @@
+import { guid, projectParam, environmentParam, readOnly, writes, updates, destructive } from './common.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { PlatformApiError } from '../platform/errors.js';
+import { handle } from '../platform/responses.js';
+import { basename, join, resolve } from 'node:path';
+import { z } from 'zod';
+/** Platformun köprü protokolü; scaffold ve publish bu sürüme göre üretir/doğrular */
+const PROTOCOL_VERSION = 1;
+/** Backend `ExternalComponentRules.MaxBundleSizeBytes` ile aynı sınır */
+const maxBundleBytes = 2 * 1024 * 1024;
+const slugPattern = /^x-[a-z][a-z0-9-]*$/;
+const slugParam = z.string().regex(slugPattern)
+    .describe("Harici komponent slug'ı; 'x-' ile başlamak zorunda (örn. 'x-rating-stars') — bu önek platform slug'larıyla çakışmayı imkânsız kılar");
+const versionParam = z.string().min(1).describe("Paket sürümü, örn. '1.0.0'; aynı sürüm ikinci kez yayınlanamaz");
+/**
+ * Doğrulama raporunu ajanın düzeltme döngüsü kurabileceği şekilde özetler: block
+ * bulguları işi durdurur, warn bulguları aktivasyonda açık onay ister.
+ */
+function summarizeFindings(findings) {
+    const blocking = (findings ?? []).filter(finding => finding.severity === 'block');
+    const warnings = (findings ?? []).filter(finding => finding.severity === 'warn');
+    return {
+        blocking,
+        warnings,
+        nextStep: blocking.length
+            ? 'Paket reddedildi ve depolamaya yazılmadı. Yukarıdaki block bulgularını kaynakta düzeltip yeniden yayınlayın.'
+            : warnings.length
+                ? "Paket taslak olarak kaydedildi. Uyarıları inceleyin; aktive etmek için external_component_activate'i acknowledgeWarnings:true ile çağırın."
+                : "Paket taslak olarak kaydedildi. Önizlemede doğruladıktan sonra external_component_activate ile yayına alın."
+    };
+}
+const elementTemplate = (slug, props) => `const PROPS = ${JSON.stringify(props)}
+
+export default class ZeyrekElement extends HTMLElement {
+	#props = {}
+	#context = null
+	#machine = null
+
+${props.map(prop => `	set ${prop}(value) {
+		this.#props.${prop} = value
+		this.#render()
+	}`).join('\n\n')}
+
+	set zxContext(value) {
+		this.#context = value
+		this.#render()
+	}
+
+	set zxMachine(value) {
+		this.#machine = value
+	}
+
+	connectedCallback() {
+		this.#render()
+	}
+
+	/**
+	 * Platforma bir olay bildirir. setter:true, data içindeki değerin aynı adlı
+	 * prop'a geri yazılmasını ister — value gibi iki yönlü davranan proplar için.
+	 */
+	emit(name, data, options = {}) {
+		this.dispatchEvent(new CustomEvent('zx-emit', { detail: { name, data, ...options } }))
+	}
+
+	#render() {
+		if (this.#context?.editorMode) {
+			this.textContent = '${slug}'
+			return
+		}
+
+		this.textContent = PROPS.map(prop => \`\${prop}: \${this.#props[prop] ?? ''}\`).join(' · ')
+	}
+}
+`;
+const manifestTemplate = (slug, name, props) => JSON.stringify({
+    slug,
+    name,
+    description: `${name} — organizasyon tarafından yayınlanan komponent.`,
+    icon: 'widgets',
+    categories: ['common'],
+    protocolVersion: PROTOCOL_VERSION,
+    definition: {
+        props: props.map(prop => ({ title: prop, name: prop, type: 'text' })),
+        events: [{ name: 'change', title: 'When value changed' }],
+        validations: [],
+        blocks: [{ breakpoint: 1024, size: { w: 3, h: 8 }, minSize: { w: 1, h: 1 }, maxSize: { w: 12, h: 5 } }],
+        defaults: {}
+    }
+}, null, 2);
+const readmeTemplate = (slug) => `# ${slug}
+
+Zeyrek harici komponenti. Köprü protokolü sürümü: ${PROTOCOL_VERSION}.
+
+## Sözleşme
+
+Host, element'e şema prop'larını **JS property** olarak yazar (attribute değil —
+dizi ve nesneler bozulmadan geçsin diye), yanına iki kanal koyar:
+
+- \`zxContext\`: \`{ elementId, appearance, states, isRequired, editorMode, language }\`
+- \`zxMachine\`: platform yüzeyi (state, değişken, dil, yetki, sibling prop'lar)
+
+Element geriye tek bir DOM olayıyla konuşur: \`zx-emit\`, detail'i
+\`{ name, data?, setter?, flowId?, params? }\`. \`setter: true\` verirseniz
+\`data\` içindeki değer aynı adlı prop'a geri yazılır.
+
+## Kurallar
+
+- Tek \`export default\`, \`HTMLElement\` türeten bir sınıf olmalı.
+- \`eval\`, \`new Function\`, dinamik \`import()\`, \`document.cookie\`,
+  \`window.machine\`, service worker kaydı **yasak** — yayınlama reddedilir.
+- Ağ erişimi, doğrudan storage ve \`innerHTML\` ataması uyarı üretir; aktive
+  ederken açık onay ister.
+- Renk, boşluk ve tipografi için \`--ng-*\` tema değişkenlerini kullanın; sabit
+  renk yazmayın.
+
+## Yayınlama
+
+1. \`manifest.json\` içindeki prop ve event tanımlarını gerçek komponentinize göre düzenleyin.
+2. \`external_component_publish\` — kaydı ve paketi yükler, doğrulama raporunu döner.
+3. \`external_component_activate\` — taslağı yayına alır.
+`;
+export function registerExternalComponentTools(server, platform) {
+    const { config } = platform;
+    server.registerTool('external_component_list', {
+        title: 'Yayınlanan komponentleri listele',
+        description: "Organizasyonun kendi yayınladığı komponentleri (Studio'da 'Your Components' başlığı altında görünenler) listeler: slug, sürüm, taslak mı yayında mı. Platformun hazır komponentleri için component_list kullanın.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId }) => {
+        const response = await platform.tenant('GET', project, `/components/${applicationId}`, {
+            environment,
+            query: { pageIndex: 0, pageLength: 999 }
+        });
+        const components = (response?.data ?? []).filter(component => component.origin === 'external');
+        return {
+            components: components.map(component => ({
+                id: component.id,
+                slug: component.slug,
+                name: component.name,
+                bundleVersion: component.bundleVersion ?? null,
+                bundleStatus: component.bundleStatus ?? null,
+                protocolVersion: component.protocolVersion ?? null
+            })),
+            note: components.length
+                ? undefined
+                : "Bu uygulamada yayınlanmış komponent yok. İhtiyacınızı karşılayan hazır bir komponent bulamadıysanız external_component_scaffold ile kendinizinkini yazmaya başlayabilirsiniz."
+        };
+    }));
+    server.registerTool('external_component_scaffold', {
+        title: 'Harici komponent iskeleti üret',
+        description: "Yerel bir dizine çalışan bir harici komponent iskeleti yazar: element.mjs (köprü protokolünü karşılayan sınıf), manifest.json (prop/event/boyut tanımı) ve README. Mevcut katalog ihtiyacınızı karşılamıyorsa buradan başlayın; ürettiği dosyaları düzenleyip external_component_publish ile yayınlarsınız. Dosyalar gateway sürecinin çalıştığı makineye yazılır, içerikleri model bağlamına girmez.",
+        inputSchema: {
+            directory: z.string().min(1).describe('İskeletin yazılacağı yerel dizin; yoksa oluşturulur'),
+            slug: slugParam,
+            name: z.string().min(1).describe("Studio toolbox'ta görünecek ad"),
+            props: z.array(z.string().min(1)).optional().describe("Komponentin alacağı prop adları; verilmezse ['value'] varsayılır. id/class/style/name gibi DOM adları kullanılamaz")
+        },
+        annotations: writes
+    }, handle(config, async ({ directory, slug, name, props }) => {
+        const propNames = props?.length ? props : ['value'];
+        const reserved = propNames.filter(prop => /^(id|class|className|style|slot|name|children|innerHTML|outerHTML|textContent)$/.test(prop) || prop.startsWith('zx') || prop.startsWith('on'));
+        if (reserved.length) {
+            throw new PlatformApiError(`external_component_scaffold: şu prop adları platform tarafından rezerve edilmiş ve yayınlama sırasında reddedilir: ${reserved.join(', ')}.`);
+        }
+        const target = resolve(directory);
+        await mkdir(target, { recursive: true });
+        const files = [
+            { path: join(target, 'element.mjs'), content: elementTemplate(slug, propNames) },
+            { path: join(target, 'manifest.json'), content: manifestTemplate(slug, name, propNames) },
+            { path: join(target, 'README.md'), content: readmeTemplate(slug) }
+        ];
+        for (const file of files) {
+            await writeFile(file.path, file.content, 'utf8');
+        }
+        return {
+            directory: target,
+            files: files.map(file => basename(file.path)),
+            protocolVersion: PROTOCOL_VERSION,
+            nextStep: `element.mjs ve manifest.json dosyalarını komponentinize göre düzenleyin, sonra external_component_publish ile bundlePath='${join(target, 'element.mjs')}' ve manifestPath='${join(target, 'manifest.json')}' vererek yayınlayın.`
+        };
+    }));
+    server.registerTool('external_component_publish', {
+        title: 'Harici komponenti yayınla',
+        description: "Komponent kaydını ve paketini platforma yükler. Paket sunucudaki doğrulama hattından geçer (şema + güvenlik taraması); block bulgusu varsa depolamaya hiç yazılmaz ve rapor döner. Kabul edilen paket taslak (draft) olarak kaydedilir — Studio önizlemesinde görünür, yayınlanmış uygulamada görünmez; yayına almak için external_component_activate. Dosyalar gateway sürecinin okuyabildiği yerel yollardır, içerikleri model bağlamına girmez.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            bundlePath: z.string().min(1).describe('Tek dosyalık ES module paketinin yerel yolu (.mjs)'),
+            manifestPath: z.string().min(1).describe('manifest.json yerel yolu; slug, name, definition ve protocolVersion buradan okunur'),
+            version: versionParam
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, bundlePath, manifestPath, version }) => {
+        const manifestFile = resolve(manifestPath);
+        const bundleFile = resolve(bundlePath);
+        let manifest;
+        try {
+            manifest = JSON.parse(await readFile(manifestFile, 'utf8'));
+        }
+        catch (error) {
+            throw new PlatformApiError(`external_component_publish: manifest okunamadı ya da geçerli JSON değil — ${manifestFile} (${error instanceof Error ? error.message : String(error)}).`);
+        }
+        const slug = typeof manifest.slug === 'string' ? manifest.slug : undefined;
+        if (!slug || !slugPattern.test(slug)) {
+            throw new PlatformApiError(`external_component_publish: manifest'teki slug 'x-' ile başlamalı ve küçük harf/rakam/tire içermeli — okunan: ${String(manifest.slug)}.`);
+        }
+        let bytes;
+        try {
+            bytes = await readFile(bundleFile);
+        }
+        catch (error) {
+            throw new PlatformApiError(`external_component_publish: paket okunamadı — ${bundleFile} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+        }
+        if (bytes.byteLength > maxBundleBytes) {
+            throw new PlatformApiError(`external_component_publish: paket ${maxBundleBytes} bayt sınırını aşıyor (${bytes.byteLength} B).`);
+        }
+        const record = await platform.tenant('POST', project, `/components/${applicationId}/external`, {
+            environment,
+            body: {
+                slug,
+                name: manifest.name,
+                description: manifest.description,
+                icon: manifest.icon,
+                categories: manifest.categories ?? [],
+                definition: manifest.definition,
+                protocolVersion: manifest.protocolVersion ?? PROTOCOL_VERSION
+            }
+        });
+        const bundle = await platform.tenant('POST', project, `/components/${applicationId}/external/${slug}/bundle`, {
+            environment,
+            multipart: [
+                { name: 'Version', value: version },
+                { name: 'Bundle', filename: basename(bundleFile), contentType: 'text/javascript', content: bytes }
+            ]
+        });
+        return {
+            component: record,
+            bundle: bundle?.data,
+            ...summarizeFindings(bundle?.data?.findings)
+        };
+    }));
+    server.registerTool('external_component_activate', {
+        title: 'Paket sürümünü yayına al',
+        description: "Taslak bir paket sürümünü yayına alır; yalnızca metadata değişir, platform yeniden başlatılmaz ve açık oturumlar bozulmaz. Eski bir sürüm verilirse aynı mekanizma geri alma (rollback) olarak çalışır. Doğrulama uyarısı olan bir sürüm acknowledgeWarnings:true olmadan aktive edilemez.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            slug: slugParam,
+            version: versionParam,
+            acknowledgeWarnings: z.boolean().optional().describe('Doğrulama uyarılarını okuyup kabul ettiğinizi bildirir; uyarısı olan sürümlerde zorunlu')
+        },
+        annotations: updates
+    }, handle(config, ({ project, environment, applicationId, slug, version, acknowledgeWarnings }) => platform.tenant('POST', project, `/components/${applicationId}/external/${slug}/activate`, {
+        environment,
+        body: { version, acknowledgeWarnings: acknowledgeWarnings === true }
+    })));
+    server.registerTool('external_component_versions', {
+        title: 'Paket sürümlerini listele',
+        description: 'Bir harici komponentin yayınlanmış paket sürümlerini, hangisinin aktif olduğunu ve her sürümün doğrulama raporunu listeler. Geri alınacak sürümü buradan seçin.',
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            slug: slugParam
+        },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, applicationId, slug }) => platform.tenant('GET', project, `/components/${applicationId}/external/${slug}/versions`, { environment })));
+    server.registerTool('external_component_delete', {
+        title: 'Harici komponenti sil',
+        description: 'Yayınlanan komponent kaydını siler. Sayfalarda kullanılıyorsa o sayfalar komponenti kaybeder ve yerinde bir hata kartı görünür — silmeden önce dependency_graph ile kullanımını kontrol edin.',
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            id: guid.describe('external_component_list çıktısındaki komponent id')
+        },
+        annotations: destructive
+    }, handle(config, ({ project, environment, applicationId, id }) => platform.tenant('DELETE', project, `/components/${applicationId}/${id}`, { environment })));
+}

package/dist/tools/layouts.js

@@ -1,17 +1,30 @@
 import { guid, projectParam, environmentParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
 import { normalizeComponentDefaults, componentDefaultsNote, blockSizeNote, heightTypeNote, invalidScreenEventNames, invalidWidgetTypeNodes, verticalGapWarnings, withNormalization } from '../knowledge/normalize.js';
-import { fetchHost, layoutUpdateBody, schemaParam, eventsParam } from './screens.js';
+import { fetchHost, layoutUpdateBody, schemaParam, eventsParam, modeParam, summarize, findNode } from './screens.js';
 import { applyCatalogLayoutRules } from './components.js';
 import { PlatformApiError } from '../platform/errors.js';
 import { handle } from '../platform/responses.js';
 import { z } from 'zod';
 const viewsParam = schemaParam.describe("Layout'un komponent ağacı. DİKKAT: layout'ta şema alanının adı 'schema' değil 'views'tir ve sayfa micro-op hattı (page_schema_patch) layout'a uygulanmaz. İçinde MUTLAKA bir { type: 'slot' } komponenti olmalı — sayfa içeriği YALNIZ slot'un içine render edilir, slot'suz layout'a bağlanan sayfalar boş görünür.");
+function countSlots(nodes) {
+    if (!Array.isArray(nodes))
+        return 0;
+    return nodes.reduce((total, node) => {
+        if (!node || typeof node !== 'object')
+            return total;
+        const record = node;
+        return total + (record.type === 'slot' ? 1 : 0) + countSlots(record.children);
+    }, 0);
+}
 function slotWarning(views) {
-    const hasSlot = (nodes) => Array.isArray(nodes) && nodes.some(node => Boolean(node) && typeof node === 'object' &&
-        (node.type === 'slot' || hasSlot(node.children)));
-    return hasSlot(views)
-        ? []
-        : ["LAY-002: layout'ta 'slot' tipli komponent YOK — Studio ve runtime, sayfa şemasını yalnız layout'taki slot'un içine yerleştirir (page.mappers: layout varsa render şeması layout views'üdür); bu layout'a bağlanan her sayfanın içeriği görünmez olur. views'e bir { type: 'slot' } komponenti ekleyin ve page_state.layoutSlots ile doğrulayın."];
+    const slots = countSlots(views);
+    if (slots === 0) {
+        return ["LAY-002: layout'ta 'slot' tipli komponent YOK — Studio ve runtime, sayfa şemasını yalnız layout'taki slot'un içine yerleştirir (page.mappers: layout varsa render şeması layout views'üdür); bu layout'a bağlanan her sayfanın içeriği görünmez olur. views'e bir { type: 'slot' } komponenti ekleyin ve page_state.layoutSlots ile doğrulayın."];
+    }
+    if (slots > 1) {
+        return [`LAY-006: layout'ta ${slots} adet 'slot' var — enjeksiyon HER slot'a AYRI AYRI kopyalar (layout.functions.ts injectPageSchemaIntoSlots ağacı dolaşır ve type==='slot' gören her düğümün children'ına sayfa şemasının klonunu yazar; önizlemede page.mappers.mapPageLayoutToPreview aynısını yapar). Sonuç: sayfa birden çok kez çizilir ve aynı elementId'ler tekrarlanır. Tek slot bırakın.`];
+    }
+    return [];
 }
 export function registerLayoutTools(server, platform) {
     const config = platform.config;
@@ -27,6 +40,35 @@ export function registerLayoutTools(server, platform) {
         inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid },
         annotations: readOnly
     }, handle(config, ({ project, environment, applicationId, id }) => platform.tenant('GET', project, `/layouts/${applicationId}/${id}`, { environment })));
+    server.registerTool('layout_schema_get', {
+        title: "Layout komponent ağacını oku",
+        description: "Layout'un komponent ağacını (views) okur — page_schema_get'in layout karşılığı. DİKKAT: layout'ta micro-op hattı YOKTUR (backend'de PATCH /layouts/.../schema ucu yok), yani buradan okunan updatedAt bir expectedUpdatedAt kontrolünde kullanılamaz; değişiklik layout_update ile tam gövde olarak yazılır.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            id: guid,
+            mode: modeParam,
+            componentId: z.string().optional().describe("subtree kipinde kök alınacak komponentin elementId'si")
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId, id, mode, componentId }) => {
+        const layout = await fetchHost(platform, 'layout', project, environment, applicationId, id);
+        const audit = layout.audit;
+        const updatedAt = audit?.updatedAt ?? audit?.createdAt;
+        const views = (layout.views ?? []);
+        if (mode === 'full')
+            return { updatedAt, views };
+        if (mode === 'subtree') {
+            if (!componentId)
+                throw new PlatformApiError("mode='subtree' için componentId zorunludur.");
+            const subtree = findNode(views, componentId);
+            if (!subtree)
+                throw new PlatformApiError(`Layout'ta '${componentId}' id'li bir komponent yok; layout_schema_get'i summary kipinde çağırıp hedefi doğrulayın.`);
+            return { updatedAt, views: subtree };
+        }
+        return { updatedAt, views: views.map(node => summarize(node)) };
+    }));
     server.registerTool('layout_create', {
         title: 'Layout oluştur',
         description: "Yeni layout oluşturur. Şablon için mevcut bir layout'u layout_get ile alın; slot kurgusunu page_state çıktısındaki layoutSlots ile doğrulayın.",