@appaflytech/zeyrek-ai-mcp 0.0.3 → 0.0.4

package/dist/server.js

@@ -5,6 +5,7 @@ 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';
@@ -42,6 +43,7 @@ const moduleRegistrations = {
     view: registerViewTools,
     page: registerPageTools,
     component: registerComponentTools,
+    externalComponent: registerExternalComponentTools,
     flow: registerFlowTools,
     layout: registerLayoutTools,
     variable: registerVariableTools,

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.",

package/dist/tools/microservices.js

@@ -119,7 +119,7 @@ export function registerMicroserviceTools(server, platform) {
     }));
     server.registerTool('microservice_create', {
         title: 'Microservice oluştur',
-        description: "Yeni microservice tanımlar (definition = CreateMicroserviceCommand). İlk kullanımdan önce platform_guide('microservice') okuyun: kaynak seçimi (table > query) ve selectFields disiplini. Auth/oturum gerektiren uçlarda definition.middlewareIds ile middleware bağlayın; kimlik kapsaması filtrede source:'expression' + value:'user.id' ile yapılır (platform_guide('middleware')). Gövde politika kontrolünden geçer.",
+        description: "Yeni microservice tanımlar (definition = CreateMicroserviceCommand). İlk kullanımdan önce platform_guide('microservice') okuyun: kaynak seçimi (table > query) ve selectFields disiplini. 'description' ZORUNLUDUR (MS-014, block): çağıranın bu uçtan ne elde ettiğini yazın. Auth/oturum gerektiren uçlarda definition.middlewareIds ile middleware bağlayın; kimlik kapsaması filtrede source:'expression' + value:'user.id' ile yapılır (platform_guide('middleware')). Ucun gerçek bir tuzağı varsa (auth istemiyor, sayfalama yok, atomik değil) 'caution' alanına yazın — OPSİYONELDİR, tuzak yoksa boş bırakın. Gövde politika kontrolünden geçer.",
         inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, definition: definitionParam, policyOverride: policyOverrideParam },
         annotations: writes
     }, handle(config, async ({ project, environment, applicationId, definition, policyOverride }) => {
@@ -130,7 +130,7 @@ export function registerMicroserviceTools(server, platform) {
     }));
     server.registerTool('microservice_update', {
         title: 'Microservice güncelle',
-        description: 'Microservice tanımını günceller (tam gövde). Hedefli değişiklik için microservice_patch tercih edin. Gövde politika kontrolünden geçer.',
+        description: 'Microservice tanımını günceller (tam gövde). Hedefli değişiklik için microservice_patch tercih edin. \'description\' ZORUNLUDUR (MS-014, block). Ucun gerçek bir tuzağı varsa (auth istemiyor, sayfalama yok, atomik değil) \'caution\' alanına yazın — OPSİYONELDİR, tuzak yoksa boş bırakın. Gövde politika kontrolünden geçer.',
         inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, id: guid, definition: definitionParam, policyOverride: policyOverrideParam },
         annotations: updates
     }, handle(config, async ({ project, environment, applicationId, id, definition, policyOverride }) => {

package/dist/tools/pages.js

@@ -1,13 +1,15 @@
 import { guid, projectParam, environmentParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
 import { orphanedFlowWarnings, normalizeComponentDefaults, normalizeSchemaOps, schemaOpValidationErrors, validationNote, componentDefaultsNote, replacePropNote, ensurePageContainer, retargetRootAdds, rootAddsNote, blockSizeNote, heightTypeNote, reorderSchemaBlocks, reorderNote, nestedRepeaterNodes, nestedRepeaterMessage, stringStyleNodes, stringStyleWarning, inertFlexPropNodes, inertFlexPropWarning, FLEX_LAYOUT_PROP_NAMES, resetPageContainerPosition, pageContainerPositionWarning, verticalGapWarnings, invalidScreenEventNames, invalidWidgetTypeNodes, withNormalization, PAGE_CONTAINER_ELEMENT_ID } from '../knowledge/normalize.js';
-import { fetchHost, pageUpdateBody, schemaParam, eventsParam, unwrap } from './screens.js';
+import { fetchHost, pageUpdateBody, schemaParam, eventsParam, unwrap, modeParam, summarize, findNode } from './screens.js';
 import { applyCatalogLayoutRules, fetchComponentEventNames } from './components.js';
 import { formBindingWarnings } from '../knowledge/coverage.js';
 import { PlatformApiError } from '../platform/errors.js';
-import { handle } from '../platform/responses.js';
+import { handle, toolResult, toolError } from '../platform/responses.js';
+import { StudioScreenshotter } from '../platform/screenshot.js';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import { z } from 'zod';
 const opsParam = z.array(z.record(z.unknown())).describe("Micro-op listesi. Op sözlüğü: replace_prop {target, prop, value} | set_binding {target, prop, expression: '{{ Page.variables.x }}'} | add_component {parent (üst elementId ya da 'root'), index?, component} | remove_component {target} | move_component {target, parent, index?, position: {x, y}} | set_event {target, event, eventValue} | remove_event {target, event} (gateway emülasyonu: platformun micro-op'u olay SİLEMEZ, eventValue: null yalnız değersiz ölü kayıt bırakır — bu op şemayı okuyup olayı diziden çıkarır ve sayfayı tam gövdeyle geri yazar) | set_validations {target, validations: [{type, message, value, isActive}]} (komponentin validation listesini TAMAMEN değiştirir; boş dizi hepsini siler). target = elementId.");
-const modeParam = z.enum(['summary', 'subtree', 'full']).optional().describe("summary (varsayılan): yalnız id/elementId/name/type ağacı — hedef bulmak için bunu kullanın. subtree: componentId ile tek alt ağaç. full: tüm şema.");
 /**
  * PAGE-008 — `set_event` uydurma bir olay adıyla 200 döner ve bağ SESSİZCE ölü kalır: motor olayı
  * komponentin yaydığı adla eşleştirir, eşleşme yoksa akış hiç çalışmaz. Kontrol yalnız hedefin
@@ -46,28 +48,6 @@ function invalidComponentNames(nodes) {
     }
     return found;
 }
-function summarize(node) {
-    const summary = {
-        id: node.id,
-        elementId: node.elementId,
-        name: node.name,
-        type: node.type
-    };
-    if (Array.isArray(node.children) && node.children.length > 0) {
-        summary.children = node.children.map(summarize);
-    }
-    return summary;
-}
-function findNode(nodes, target) {
-    for (const node of nodes ?? []) {
-        if (node.elementId === target || String(node.id) === target)
-            return node;
-        const found = findNode(node.children, target);
-        if (found)
-            return found;
-    }
-    return undefined;
-}
 function removeNodeFromTree(nodes, target) {
     for (let index = 0; index < nodes.length; index++) {
         if (nodes[index].elementId === target)
@@ -235,10 +215,11 @@ export function registerPageTools(server, platform) {
             applicationSlug: z.string().min(1).describe("Uygulamanın slug'ı (application_list / project_overview)"),
             pageSlug: z.string().min(1).describe("Sayfanın slug'ı (page_list)"),
             view: z.enum(['summary', 'full']).optional().describe('summary (varsayılan): şema/layout ağaçları id/name/type özetine indirgenir. full: ham gövde — büyük olabilir'),
+            resolveStyles: z.boolean().optional().describe("summary görünümünde her düğüme EFEKTİF stilini ekler: tema componentStyles → preset → düğümün kendi stili kaskadı çözülür (aibox'ta tipli stil grupları da derlenir ve TABAN katman olur). styleLayers hangi katmanın konuştuğunu söyler — 'bu kutu neden böyle görünüyor' sorusunun cevabı budur."),
             anonymous: z.boolean().optional().describe("true: istek HİÇBİR Authorization header'ı olmadan gider — 'korumalı sayfa tokensız ne döner, şema sızıyor mu?' sorusunun cevabı budur. Korumalı sayfada middlewareBlocked bekleyin.")
         },
         annotations: readOnly
-    }, handle(config, async ({ project, environment, applicationSlug, pageSlug, view, anonymous }) => {
+    }, handle(config, async ({ project, environment, applicationSlug, pageSlug, view, resolveStyles, anonymous }) => {
         let response;
         try {
             response = await platform.tenant('GET', project, `/${applicationSlug}/p/${pageSlug}`, { environment, anonymous });
@@ -258,20 +239,107 @@ export function registerPageTools(server, platform) {
             return response;
         const body = (response?.data ?? {});
         const layout = body.layout;
+        const theme = body.project?.theme;
+        // undefined: stil raporu hiç yazılmaz. null: tema yok ama kaskad yine çözülür.
+        const styleSource = resolveStyles ? (theme ?? null) : undefined;
         const asNodes = (value) => (Array.isArray(value) ? value : []);
         const named = (value) => (Array.isArray(value) ? value : []).map(entry => ({ id: entry.id, name: entry.name, slug: entry.slug }));
         return {
             page: { id: body.id, name: body.name, slug: body.slug, browserTitle: body.browserTitle, isHomepage: body.isHomepage },
             events: body.events ?? [],
-            layout: layout ? { id: layout.id, name: layout.name, views: asNodes(layout.views).map(summarize) } : null,
-            schema: asNodes(body.schema).map(summarize),
+            layout: layout ? { id: layout.id, name: layout.name, views: asNodes(layout.views).map(node => summarize(node, styleSource)) } : null,
+            schema: asNodes(body.schema).map(node => summarize(node, styleSource)),
             widgets: named(body.widgets),
             flows: named(body.flows),
             variableKeys: Object.keys((body.variables ?? {})),
             hasTheme: Boolean(body.project?.theme),
-            note: "schema, layout'taki slot'un İÇİNE yerleşerek çizilir (Kural 1f); tam gövde gerekirse view:'full'."
+            note: resolveStyles
+                ? "schema, layout'taki slot'un İÇİNE yerleşerek çizilir (Kural 1f). resolvedStyle = componentStyles → preset → düğüm stili kaskadı (aibox'ta tipli grupların derlemesi TABAN katmandır); styleLayers hangi katmanların konuştuğunu söyler."
+                : "schema, layout'taki slot'un İÇİNE yerleşerek çizilir (Kural 1f); tam gövde gerekirse view:'full'. Bir düğümün ekranda GERÇEKTEN aldığı stili görmek için resolveStyles:true."
         };
     }));
+    const screenshotter = new StudioScreenshotter(config);
+    const maxInlinePngBytes = 5 * 1024 * 1024;
+    server.registerTool('page_screenshot', {
+        title: 'Sayfanın ekran görüntüsünü al',
+        description: "Studio arayüzünün runtime render rotasını (/dev ya da /view) headless Chromium'da açar ve sayfanın PNG ekran görüntüsünü inline görüntü olarak döner — kurduğun sayfayı GÖZLE doğrulamanın yolu budur (page_runtime_get paketi verir, bu tool ekranda ne ÇİZİLDİĞİNİ gösterir). Sayfaya bağlı middleware'ler gerçekten koşar; reddedilirse yanıtta middlewareBlocked işaretlenir ve hata/boş durum karesi yine döner — bu da bir doğrulamadır. STUDIO_BASE_URL tanımlı olmalı; ilk kullanım için `npx playwright-core install chromium` gerekir.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationSlug: z.string().min(1).describe("Uygulamanın slug'ı (application_list / project_overview)"),
+            pageSlug: z.string().min(1).describe("Sayfanın slug'ı (page_list)"),
+            viewport: z.object({
+                width: z.number().int().min(320).max(3840),
+                height: z.number().int().min(240).max(2160)
+            }).optional().describe('Varsayılan 1280x800 (deviceScaleFactor 1)'),
+            fullPage: z.boolean().optional().describe('true: kaydırılan kısım dahil tüm sayfa; varsayılan yalnız viewport karesi'),
+            delayMs: z.number().int().min(0).max(10000).optional().describe('Animasyon/geç gelen veri için EK bekleme; 600 ms yerleşme beklemesi her zaman uygulanır'),
+            anonymous: z.boolean().optional().describe("true: NG_AccessToken çerezi enjekte edilmez — anonim ziyaretçinin gördüğü kare. Korumalı sayfada middlewareBlocked bekleyin."),
+            outPath: z.string().min(1).optional().describe('Verilirse PNG bu yerel yola yazılır ve inline görüntü DÖNMEZ; yalnız özet (yol, boyut) döner — büyük fullPage kareleri için')
+        },
+        annotations: readOnly
+    }, async ({ project, environment, applicationSlug, pageSlug, viewport, fullPage, delayMs, anonymous, outPath }) => {
+        try {
+            if (!config.studioBaseUrl) {
+                throw new PlatformApiError("page_screenshot için STUDIO_BASE_URL tanımlı değil. Studio arayüzünün kök adresini .env'e ekleyin (yerel geliştirmede http://localhost:3000, dağıtımda nginx adresi).");
+            }
+            const resolvedEnvironment = platform.resolveEnvironment(environment);
+            const lane = resolvedEnvironment === 'development' ? 'dev' : resolvedEnvironment === 'production' ? 'view' : undefined;
+            if (!lane) {
+                throw new PlatformApiError(`page_screenshot yalnız 'development' (/dev) ve 'production' (/view) ortamlarını görüntüleyebilir; '${resolvedEnvironment}' için Studio'da karşılık gelen bir rota yok.`);
+            }
+            const url = `${config.studioBaseUrl}/${lane}/${platform.resolveProject(project)}/${applicationSlug}/${pageSlug}`;
+            const size = viewport ?? { width: 1280, height: 800 };
+            const shot = await screenshotter.capture({
+                url,
+                apiPathMarker: `/${applicationSlug}/p/${pageSlug}`,
+                token: anonymous ? undefined : await platform.accessToken(),
+                cookieUrl: config.studioBaseUrl,
+                viewport: size,
+                fullPage: fullPage === true,
+                delayMs: delayMs ?? 0
+            });
+            const meta = {
+                url,
+                environment: resolvedEnvironment,
+                viewport: size,
+                fullPage: fullPage === true,
+                sizeBytes: shot.png.byteLength,
+                elapsedMs: shot.elapsedMs,
+                ...(shot.apiStatus === undefined ? {} : { apiStatus: shot.apiStatus }),
+                ...(shot.apiStatus !== undefined && shot.apiStatus >= 300
+                    ? { middlewareBlocked: true, note: 'Sayfanın veri isteği reddedildi — karede hata/boş durum görünüyor olabilir. Korumalı sayfada kimliksiz/yetkisiz isteğin reddedilmesi BEKLENEN davranıştır (page_runtime_get ile karşılaştırın).' }
+                    : {}),
+                ...(shot.renderWaitTimedOut
+                    ? { renderWaitTimedOut: true, note: "Sayfanın veri isteği gözlenmedi — kare hata/boş durumu gösteriyor olabilir; STUDIO_BASE_URL ve slug'ları doğrulayın." }
+                    : {})
+            };
+            if (outPath) {
+                const absolute = resolve(outPath);
+                try {
+                    await writeFile(absolute, shot.png);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new PlatformApiError(`page_screenshot: dosya yazılamadı — ${absolute} (${message}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+                }
+                return toolResult({ path: absolute, ...meta }, config);
+            }
+            if (shot.png.byteLength > maxInlinePngBytes) {
+                throw new PlatformApiError(`Görüntü ${shot.png.byteLength} B — inline sınırı (${maxInlinePngBytes} B) aşıyor. outPath verin (dosyaya yazılır, model bağlamına girmez) ya da fullPage'i kapatıp viewport'u küçültün.`);
+            }
+            return {
+                content: [
+                    { type: 'image', data: shot.png.toString('base64'), mimeType: 'image/png' },
+                    { type: 'text', text: JSON.stringify(meta) }
+                ],
+                structuredContent: meta
+            };
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
     server.registerTool('page_schema_get', {
         title: 'Sayfa şemasını oku',
         description: "Sayfanın komponent şemasını okur; yanıttaki updatedAt değeri page_schema_patch'in expectedUpdatedAt kontrolünde kullanılır.",
@@ -297,7 +365,7 @@ export function registerPageTools(server, platform) {
                 throw new PlatformApiError(`Sayfada '${componentId}' id'li bir komponent yok; page_schema_get'i summary kipinde çağırıp hedefi doğrulayın.`);
             return { updatedAt, schema: subtree };
         }
-        return { updatedAt, schema: (page.schema ?? []).map(summarize) };
+        return { updatedAt, schema: (page.schema ?? []).map(node => summarize(node)) };
     }));
     server.registerTool('page_state', {
         title: 'Sayfa durumunu getir',

package/dist/tools/platformInfo.js

@@ -13,7 +13,7 @@ export function registerPlatformTools(server, platform) {
     }, handle(config, () => platform.org('GET', '/connect/userinfo')));
     server.registerTool('platform_guide', {
         title: 'Platform rehberi oku',
-        description: "Modülün iş kuralları rehberini döner (workflow, microservice, entity, page, component, html, middleware, view, expressions, translation, getting-started, modify-existing). Bir modülde İLK yazma işleminden önce ilgili rehberi okuyun; sayfa/layout/flow işleri için page, komponent modeli/olay sözleşmeleri için component, hazır komponentler yetmediğinde HTML kaçış kapısı (Mustache, fireEvent, script kuralları) için html, auth/oturum/yetki için middleware, tam metin arama indeksi için view, ifade yazarken kullanılabilir fonksiyon/bağlam sözlüğü (system.*, file.*, Page.*, state.*, Steps…) için expressions, sayfa/içerik çevirileri (çoklu dil) için translation rehberi. Örnek gövdeler için ngapps://examples kaynaklarına bakın.",
+        description: "Modülün iş kuralları rehberini döner (workflow, microservice, entity, page, layout, component, html, middleware, view, expressions, translation, getting-started, modify-existing). Bir modülde İLK yazma işleminden önce ilgili rehberi okuyun; sayfa/layout/flow işleri için page, yerleşim kabuğunun kendi kuralları (tek slot, views alanı, micro-op yokluğu, mobil yığılma) için layout, komponent modeli/olay sözleşmeleri için component, hazır komponentler yetmediğinde HTML kaçış kapısı (Mustache, fireEvent, script kuralları) için html, auth/oturum/yetki için middleware, tam metin arama indeksi için view, ifade yazarken kullanılabilir fonksiyon/bağlam sözlüğü (system.*, file.*, Page.*, state.*, Steps…) için expressions, sayfa/içerik çevirileri (çoklu dil) için translation rehberi. Örnek gövdeler için ngapps://examples kaynaklarına bakın.",
         inputSchema: {
             guide: z.string().describe('Rehber adı; bilinmeyen ad verilirse mevcut rehberler listelenir')
         },
@@ -27,7 +27,7 @@ export function registerPlatformTools(server, platform) {
     }));
     server.registerTool('platform_gap_report', {
         title: 'Kabiliyet boşluğu bildir',
-        description: "Yapmak İSTEDİĞİNİZ ama platform desteklemediği için yapamadığınız her noktada BUNU ÇAĞIRIN — tasarımı sessizce küçültmeyin. Bu çağrı platforma gitmez, yalnızca günlüğe 'KABİLİYET BOŞLUĞU' bloğu yazar; hata günlüğünde görünmeyen bu kayıtlar ürün yol haritasının girdisidir. Önce rehbere bakıp (platform_guide, özellikle hazır komponent yetmiyorsa 'html' kaçış kapısı) gerçekten desteklenmediğinden emin olun: desteklenen bir şeyi 'yok' diye bildirmek yanlış yol haritası üretir.",
+        description: "Yapmak İSTEDİĞİNİZ ama platform desteklemediği için yapamadığınız her noktada BUNU ÇAĞIRIN — tasarımı sessizce küçültmeyin. Bu çağrı platforma gitmez, yalnızca günlüğe 'KABİLİYET BOŞLUĞU' bloğu yazar; hata günlüğünde görünmeyen bu kayıtlar ürün yol haritasının girdisidir. Önce rehbere bakıp (platform_guide; hazır komponent yetmiyorsa tek seferlik için 'html' kaçış kapısı, kalıcı bir ihtiyaç içinse 'external-component' — kendi komponentinizi yazıp yayınlayabilirsiniz) gerçekten desteklenmediğinden emin olun: desteklenen bir şeyi 'yok' diye bildirmek yanlış yol haritası üretir.",
         inputSchema: {
             goal: z.string().min(1).describe('Ne yapmak istediniz — kullanıcıya görünen sonuç olarak yazın ("randevu listesini hasta adına göre süzmek")'),
             blocker: z.string().min(1).describe('Neden yapamadınız — hangi kabiliyetin eksik olduğu ("uçta X yok", "komponentte Y prop\'u yok")'),