@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/tools/pages.js

@@ -0,0 +1,597 @@
+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 { applyCatalogLayoutRules, fetchComponentEventNames } from './components.js';
+import { formBindingWarnings } from '../knowledge/coverage.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { handle } from '../platform/responses.js';
+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
+ * tipini ve o tipin katalogdaki olay listesini pozitif olarak çözebildiğinde konuşur (layout/widget
+ * içindeki hedefler ve katalogda olay tanımlamayan tipler doğrulanmadan geçer).
+ */
+function unknownEventOps(ops, typesByElementId, eventsBySlug) {
+    return ops
+        .map(op => op)
+        .filter(op => op.op === 'set_event')
+        .flatMap(op => {
+        const target = String(op.target ?? '');
+        const event = String(op.event ?? '');
+        const type = typesByElementId.get(target);
+        const declared = type ? eventsBySlug.get(type) : undefined;
+        if (!event || !declared || declared.includes(event))
+            return [];
+        return [`'${target}' (${type}) komponenti '${event}' diye bir olay YAYMAZ. Yaydıkları: ${declared.join(', ')}. Platform bu op'u 200 ile kabul eder ama bağ sessizce ölü kalır — akış hiçbir zaman çalışmaz. Doğru adı component_get(slug:'${type}') çıktısındaki events listesinden alın.`];
+    });
+}
+function collectTypes(nodes, into) {
+    for (const node of nodes ?? []) {
+        if (typeof node.elementId === 'string' && typeof node.type === 'string')
+            into.set(node.elementId, node.type);
+        collectTypes(node.children, into);
+    }
+}
+function invalidComponentNames(nodes) {
+    const found = [];
+    for (const node of nodes ?? []) {
+        const name = node.name;
+        if (typeof name === 'string' && name.length > 0 && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name.replace(/-/g, ''))) {
+            found.push(`'${name}' (${node.elementId ?? '?'})`);
+        }
+        found.push(...invalidComponentNames(node.children));
+    }
+    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)
+            return nodes.splice(index, 1)[0];
+        const found = removeNodeFromTree(nodes[index].children ?? [], target);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function setDesktopPosition(node, position) {
+    const blocks = Array.isArray(node.blocks) ? node.blocks : [];
+    const block = blocks.find(entry => Number(entry?.breakpoint) === 1024);
+    if (block)
+        block.position = { x: Number(position.x ?? 0), y: Number(position.y ?? 0) };
+}
+/**
+ * PAGE-010 boşluk analizi patch'in SONUCUNU görmek zorunda: tek başına op'lardaki y değerleri,
+ * kapsayıcının mevcut çocukları bilinmeden anlamsız. Op'lar okunan şemanın kopyasına uygulanır
+ * (add: parent'ın children'ına ekle — kökler retargetRootAdds ile page_container'a gittiği için
+ * burada da öyle çözülür; move: düğümü taşı ve verilen position'ı desktop block'una yaz) ve analiz
+ * yalnız dokunulan kapsayıcılarda koşar.
+ */
+function simulateLayoutOps(schema, ops) {
+    const touched = new Set();
+    const attach = (node, requestedParent) => {
+        const parentId = typeof requestedParent === 'string' && requestedParent !== '' && requestedParent !== 'root'
+            ? requestedParent
+            : PAGE_CONTAINER_ELEMENT_ID;
+        const parent = findNode(schema, parentId);
+        if (parent) {
+            parent.children = [...(parent.children ?? []), node];
+            touched.add(String(parent.elementId ?? parentId));
+        }
+        else {
+            schema.push(node);
+            touched.add('kök');
+        }
+    };
+    for (const op of ops) {
+        if (op.op === 'add_component' && op.component && typeof op.component === 'object') {
+            attach(JSON.parse(JSON.stringify(op.component)), op.parent);
+        }
+        // Düzen prop'ları (layout/flex grubu) simülasyona girer: PAGE-010 flex kapsayıcının içini
+        // analiz etmez, PAGE-015 ise op'tan SONRAKİ layout değerine bakar — ikisi de op uygulanmadan
+        // doğru karar veremez.
+        if (op.op === 'replace_prop' && FLEX_LAYOUT_PROP_NAMES.has(String(op.prop ?? ''))) {
+            const target = findNode(schema, String(op.target ?? ''));
+            if (target)
+                target.props = { ...(target.props ?? {}), [String(op.prop)]: { type: 'static', ref: null, data: op.value } };
+        }
+        if (op.op === 'move_component') {
+            const moved = removeNodeFromTree(schema, String(op.target ?? ''));
+            if (!moved)
+                continue;
+            if (op.position && typeof op.position === 'object')
+                setDesktopPosition(moved, op.position);
+            attach(moved, op.parent);
+        }
+    }
+    return touched;
+}
+async function fetchPage(platform, project, environment, applicationId, pageId) {
+    const response = await platform.tenant('GET', project, `/pages/${applicationId}/${pageId}`, { environment });
+    return response?.data ?? {};
+}
+/**
+ * F-8 — platformun `set_event` micro-op'u olay KALDIRAMAZ: `eventValue: null` verildiğinde
+ * PageSchemaMicroOpApplier kaydı `{ name: 'click' }` olarak (değersiz) bırakır, diziden çıkarmaz;
+ * ölü bağ şemada artık olarak kalır. Kaldırma yolu tek: şemayı okuyup diziden çıkarmak ve sayfayı
+ * tam gövdeyle geri yazmak (page_update'in kullandığı PUT — pageUpdateBody her alanı korur).
+ * `target: 'page'` sayfa düzeyi olayları hedefler.
+ */
+async function applyEventRemovals(platform, project, environment, applicationId, pageId, page, ops) {
+    const schema = JSON.parse(JSON.stringify(page.schema ?? []));
+    const pageEvents = Array.isArray(page.events) ? [...page.events] : [];
+    const removed = [];
+    let pageEventsTouched = false;
+    for (const op of ops) {
+        const target = String(op.target ?? '');
+        const event = String(op.event ?? '');
+        if (!target || !event)
+            throw new PlatformApiError("remove_event için 'target' ve 'event' zorunludur.", 400);
+        if (target === 'page') {
+            const before = pageEvents.length;
+            const kept = pageEvents.filter(entry => String(entry?.name ?? '') !== event);
+            if (kept.length !== before) {
+                pageEvents.length = 0;
+                pageEvents.push(...kept);
+                pageEventsTouched = true;
+                removed.push(`page.${event}`);
+            }
+            continue;
+        }
+        const node = findNode(schema, target);
+        if (!node)
+            throw new PlatformApiError(`remove_event hedefi bulunamadı: '${target}'. page_schema_get ile elementId'leri listeleyin.`, 400);
+        const events = Array.isArray(node.events) ? node.events : [];
+        const kept = events.filter(entry => String(entry?.name ?? '') !== event);
+        if (kept.length !== events.length)
+            removed.push(`${target}.${event}`);
+        node.events = kept;
+    }
+    if (removed.length === 0)
+        return [];
+    const body = pageUpdateBody(page, pageEventsTouched ? { schema, events: pageEvents } : { schema });
+    await platform.tenant('PUT', project, `/pages/${applicationId}/${pageId}`, { environment, body });
+    return removed;
+}
+export function registerPageTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('page_list', {
+        title: 'Sayfaları listele',
+        description: 'Uygulamanın sayfalarını (id, name, slug) listeler; hedef sayfayı bulmak için ilk adım.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, ...pagingParams },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId, pageIndex, pageLength, order, isDescending }) => {
+        const response = await platform.tenant('GET', project, `/pages/${applicationId}`, {
+            environment,
+            query: { pageIndex: pageIndex ?? 0, pageLength: pageLength ?? 200, order, isDescending }
+        });
+        return {
+            pages: (response?.data ?? []).map(page => ({
+                id: page.id,
+                name: page.name,
+                slug: page.slug,
+                isHomepage: page.isHomepage
+            }))
+        };
+    }));
+    server.registerTool('page_get', {
+        title: 'Sayfa üstbilgisini getir',
+        description: "Sayfanın kimlik ve bağ bilgisi: slug, browserTitle, layoutId, middlewareIds, roleIds, sayfa düzeyi olaylar (events[].value = flow id) ve flow özetleri. ŞEMA DÖNDÜRMEZ — şema için page_schema_get. 'Sayfa middleware'e bağlı mı, hangi roller görüyor, hangi olaya hangi akış bağlı' sorularının cevabı budur (Kural 8 denetimi).",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, pageId: guid },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId, pageId }) => {
+        const page = await fetchPage(platform, project, environment, applicationId, pageId);
+        const layout = (page.layout ?? {});
+        const countNodes = (nodes) => (nodes ?? []).reduce((total, node) => total + 1 + countNodes(node.children), 0);
+        return {
+            id: page.id,
+            name: page.name,
+            slug: page.slug,
+            browserTitle: page.browserTitle ?? '',
+            isHomepage: page.isHomepage === true,
+            layoutId: page.layoutId ?? layout.id ?? null,
+            layoutName: layout.name,
+            middlewareIds: page.middlewareIds ?? [],
+            roleIds: Array.isArray(page.roleIds) && page.roleIds.length > 0
+                ? page.roleIds
+                : (Array.isArray(page.roles) ? page.roles.map(role => role.id) : []),
+            events: page.events ?? [],
+            flows: (Array.isArray(page.flows) ? page.flows : [])
+                .map(flow => ({ id: flow.id, name: flow.name, slug: flow.slug })),
+            schemaNodes: countNodes(page.schema),
+            updatedAt: page.audit?.updatedAt ?? page.audit?.createdAt
+        };
+    }));
+    server.registerTool('page_runtime_get', {
+        title: 'Sayfanın runtime çıktısını getir',
+        description: "Çıkan uygulamanın sayfa için aldığı GERÇEK paketi döner (GET /{project}/{application}/p/{slug} — sayfanın ham serve yolu budur; Studio preview ve runtime aynı ucu tüketir): sayfa şeması + layout views'ü + sayfa olayları + flow'lar + değişken anahtarları. Kurduğun sayfanın SON hâlini doğrulamanın yolu budur (layout-slot yerleşimi dahil — Kural 1f). DİKKAT: sayfaya bağlı middleware'ler bu çağrıda GERÇEKTEN koşar; middleware reddederse yanıt middlewareBlocked ile döner — korumalı sayfada bu beklenen davranıştır ve kendisi bir doğrulamadır.",
+        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)"),
+            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'),
+            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 }) => {
+        let response;
+        try {
+            response = await platform.tenant('GET', project, `/${applicationSlug}/p/${pageSlug}`, { environment, anonymous });
+        }
+        catch (error) {
+            if (error instanceof PlatformApiError && typeof error.status === 'number' && error.status >= 300) {
+                return {
+                    middlewareBlocked: true,
+                    status: error.status,
+                    message: error.message,
+                    note: "Sayfaya bağlı middleware isteği reddetti ya da kayıt bulunamadı. Korumalı sayfada kimliksiz/yetkisiz isteğin reddedilmesi BEKLENEN davranıştır. Sayfanın bağlarını page_get ile, middleware tarifini platform_guide('middleware') ile kontrol edin; slug'ları page_list/application_list doğrular."
+                };
+            }
+            throw error;
+        }
+        if (view === 'full')
+            return response;
+        const body = (response?.data ?? {});
+        const layout = body.layout;
+        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),
+            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'."
+        };
+    }));
+    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.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            pageId: 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, pageId, mode, componentId }) => {
+        const page = await fetchPage(platform, project, environment, applicationId, pageId);
+        const updatedAt = page.audit?.updatedAt ?? page.audit?.createdAt;
+        if (mode === 'full')
+            return { updatedAt, schema: page.schema ?? [] };
+        if (mode === 'subtree') {
+            if (!componentId)
+                throw new PlatformApiError("mode='subtree' için componentId zorunludur.");
+            const subtree = findNode(page.schema, componentId);
+            if (!subtree)
+                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) };
+    }));
+    server.registerTool('page_state', {
+        title: 'Sayfa durumunu getir',
+        description: 'Sayfanın state ağacı: page/app değişkenleri, sayfadaki komponentler, layout slotları ve microservice imzaları. Binding ifadelerini yalnız buradaki isimlere bağlayın — isim uydurmayın.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, pageId: guid },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, applicationId, pageId }) => platform.tenant('GET', project, `/pages/${applicationId}/${pageId}/ai-context`, { environment })));
+    server.registerTool('page_schema_validate', {
+        title: 'Sayfa şemasını doğrula (kuru çalıştırma)',
+        description: "Micro-op'ları kaydetmeden şemaya uygular ve doğrulama hatalarını (suggestions ile) döndürür; page_schema_patch öncesi planı test etmek için. Gövdeye page_schema_patch ile AYNI normalizasyonu uygular (Prop sarmalı, validation biçimi) — kuru koşu ile yazma aynı gövdeyi görür.",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, pageId: guid, ops: opsParam.optional() },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, applicationId, pageId, ops }) => {
+        const opRecords = (ops ?? []).map(op => op);
+        const normalized = normalizeSchemaOps(opRecords);
+        const validationIssues = schemaOpValidationErrors(opRecords);
+        const response = ((await platform.tenant('POST', project, `/pages/${applicationId}/${pageId}/schema/validate`, {
+            environment,
+            body: { ops: opRecords }
+        })) ?? {});
+        if (validationIssues.length > 0)
+            response.validationWarnings = validationIssues.map(issue => `PAGE-016 — ${issue}`);
+        return withNormalization(response, [
+            ...componentDefaultsNote(normalized.components),
+            ...validationNote(normalized.validations),
+            ...replacePropNote(normalized.props)
+        ]);
+    }));
+    server.registerTool('page_schema_patch', {
+        title: 'Sayfa şemasına patch uygula',
+        description: "Micro-op'ları doğrulama duvarından geçirip kaydeder; açık studio canvas'ları SignalR ile canlı güncellenir. expectedUpdatedAt verilirse sayfa o okumadan beri değişmişse istek reddedilir (stale plan koruması). Yanıttaki appliedPatch, her op'un şemada tam olarak hangi JSON Pointer'a dokunduğunu söyler.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            pageId: guid,
+            ops: opsParam,
+            expectedUpdatedAt: z.string().optional().describe("page_schema_get çıktısındaki updatedAt; eşleşmezse patch uygulanmaz")
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, applicationId, pageId, ops, expectedUpdatedAt }) => {
+        const allOps = ops.map(op => op);
+        const removeEventOps = allOps.filter(entry => entry.op === 'remove_event');
+        const opRecords = allOps.filter(entry => entry.op !== 'remove_event');
+        const containerOps = opRecords
+            .filter(entry => (entry.op === 'remove_component' || entry.op === 'move_component') && entry.target === PAGE_CONTAINER_ELEMENT_ID);
+        if (containerOps.length > 0) {
+            throw new PlatformApiError(`'${PAGE_CONTAINER_ELEMENT_ID}' sayfanın kök kapsayıcısıdır; silinmez ve taşınmaz (PAGE-006) — silinirse sayfa iskeleti bozulur ve Studio komponentleri kapsayıcı dışında bırakır. Komponent kaldırmak için remove_component'i kapsayıcının İÇİNDEKİ elementId'lerle kullanın (page_schema_get ile listeleyin).`, 400);
+        }
+        let cachedPage;
+        const readPage = async () => {
+            cachedPage ??= await fetchPage(platform, project, environment, applicationId, pageId);
+            return cachedPage;
+        };
+        if (expectedUpdatedAt) {
+            const current = await readPage();
+            const updatedAt = current.audit?.updatedAt ?? current.audit?.createdAt;
+            if (updatedAt !== expectedUpdatedAt) {
+                throw new PlatformApiError(`Sayfa siz okuduktan sonra değişmiş (updatedAt: ${updatedAt}). page_schema_get ile yeniden okuyup planı tazeleyin.`, 409);
+            }
+        }
+        const normalized = normalizeSchemaOps(opRecords);
+        const validationIssues = schemaOpValidationErrors(opRecords);
+        if (validationIssues.length > 0) {
+            throw new PlatformApiError(`PAGE-016 — validation gövdesi eksik (istek gönderilmedi): ${validationIssues.join(' · ')}. `
+                + "Çalışan biçim dört alanı da taşır: { type: 'required'|'email'|'regex'|'max-length'|'min-length'|'max-value'|'min-value'|'value-options', message: '<kullanıcıya görünen metin>', value: <eşik/desen/true>, isActive: true }.", 400);
+        }
+        const wantsRootAdd = opRecords.some(entry => entry.op === 'add_component' && (entry.parent === undefined || entry.parent === null || entry.parent === 'root'));
+        let retargeted = [];
+        if (wantsRootAdd) {
+            const page = await readPage();
+            if ((page.schema ?? []).some(node => node.elementId === PAGE_CONTAINER_ELEMENT_ID)) {
+                retargeted = retargetRootAdds(opRecords, PAGE_CONTAINER_ELEMENT_ID);
+            }
+        }
+        if (opRecords.some(entry => entry.op === 'set_event')) {
+            const typesByElementId = new Map();
+            try {
+                collectTypes((await readPage()).schema, typesByElementId);
+            }
+            catch {
+                typesByElementId.clear();
+            }
+            collectTypes(opRecords.map(entry => entry.component).filter(Boolean), typesByElementId);
+            const eventsBySlug = await fetchComponentEventNames(platform, project, environment, applicationId).catch(() => new Map());
+            const unknown = unknownEventOps(opRecords, typesByElementId, eventsBySlug);
+            if (unknown.length > 0)
+                throw new PlatformApiError(`PAGE-008 — geçersiz olay adı (istek gönderilmedi): ${unknown.join(' · ')}`, 400);
+        }
+        const added = opRecords
+            .filter(entry => entry.op === 'add_component')
+            .map(entry => entry.component);
+        const badWidgets = invalidWidgetTypeNodes(added, 'PAGE-012');
+        if (badWidgets.length > 0)
+            throw new PlatformApiError(`Geçersiz widget düğümü (istek gönderilmedi): ${badWidgets.join(' · ')}`, 400);
+        const badNames = invalidComponentNames(added);
+        if (badNames.length > 0) {
+            throw new PlatformApiError(`PAGE-009 — komponent adı JS tanımlayıcısı değil (istek gönderilmedi): ${badNames.join(' · ')}. `
+                + 'Runtime her komponent için `const <ad> = Components["<ad>"]` üretir; boşluklu ya da geçersiz bir ad '
+                + 'SAYFADAKİ TÜM ifadeleri "Missing initializer in const declaration" ile öldürür (layout adları her sayfaya sızar). '
+                + 'name alanını elementId ile aynı yaz; okunabilir Türkçe başlık için props.title / props.text / props.label kullan.', 400);
+        }
+        const catalog = added.length > 0
+            ? await applyCatalogLayoutRules(platform, project, environment, applicationId, added)
+            : { clamped: [], heights: [] };
+        const formWarnings = formBindingWarnings(opRecords);
+        let flowWarnings = [];
+        let layoutWarnings = [];
+        if (opRecords.some(entry => entry.op === 'remove_component')) {
+            try {
+                const page = await readPage();
+                flowWarnings = orphanedFlowWarnings(page.schema, page.events, opRecords);
+            }
+            catch {
+                flowWarnings = [];
+            }
+        }
+        let nestedAfterOps = [];
+        const simulatable = opRecords.some(entry => ['add_component', 'move_component'].includes(String(entry.op))
+            || (entry.op === 'replace_prop' && FLEX_LAYOUT_PROP_NAMES.has(String(entry.prop ?? ''))));
+        if (simulatable) {
+            try {
+                const page = await readPage();
+                const simulated = JSON.parse(JSON.stringify(page.schema ?? []));
+                const touched = simulateLayoutOps(simulated, opRecords);
+                // PAGE-013 op'lar UYGULANDIKTAN SONRAKİ ağaca bakar: tek başına eklenen düğüm masum
+                // görünür, iç içeliği ancak hedef parent zinciri belli olunca anlarsın.
+                nestedAfterOps = nestedRepeaterNodes(simulated);
+                layoutWarnings = [
+                    ...pageContainerPositionWarning(page.schema),
+                    ...verticalGapWarnings(simulated, 'PAGE-010 (uyarı)', touched),
+                    ...stringStyleWarning(stringStyleNodes(simulated)),
+                    ...inertFlexPropWarning(inertFlexPropNodes(simulated))
+                ];
+            }
+            catch {
+                layoutWarnings = [];
+            }
+        }
+        if (nestedAfterOps.length > 0)
+            throw new PlatformApiError(nestedRepeaterMessage(nestedAfterOps), 400);
+        const removedEvents = removeEventOps.length > 0
+            ? await applyEventRemovals(platform, project, environment, applicationId, pageId, await readPage(), removeEventOps)
+            : [];
+        if (removeEventOps.length > 0)
+            cachedPage = undefined;
+        const response = opRecords.length > 0
+            ? ((await platform.tenant('PATCH', project, `/pages/${applicationId}/${pageId}/schema`, { environment, body: { ops: opRecords } })) ?? {})
+            : { valid: true };
+        if (removedEvents.length > 0)
+            response.removedEvents = removedEvents;
+        if (formWarnings.length > 0)
+            response.formWarnings = formWarnings;
+        if (flowWarnings.length > 0)
+            response.flowWarnings = flowWarnings;
+        if (layoutWarnings.length > 0)
+            response.layoutWarnings = layoutWarnings;
+        return withNormalization(response, [
+            ...rootAddsNote(retargeted, PAGE_CONTAINER_ELEMENT_ID),
+            ...componentDefaultsNote(normalized.components),
+            ...validationNote(normalized.validations),
+            ...blockSizeNote(catalog.clamped),
+            ...heightTypeNote(catalog.heights),
+            ...replacePropNote(normalized.props)
+        ]);
+    }));
+    server.registerTool('page_create', {
+        title: 'Sayfa oluştur',
+        description: "Yeni sayfa açar. Şemayı burada göndermek yerine boş bırakıp page_schema_patch micro-op'larıyla kurmak daha doğrudur (doğrulama duvarı + canlı canvas orada). roleIds için role_list, layoutId için layout_list kullanın.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            name: z.string().min(1),
+            slug: z.string().min(1).describe("URL yolu, örn. 'orders' ya da 'orders/detail'"),
+            browserTitle: z.string().optional(),
+            layoutId: guid.optional(),
+            roleIds: z.array(guid).optional().describe('Sayfayı görebilecek roller; boş = herkese açık'),
+            middlewareIds: z.array(guid).optional(),
+            events: eventsParam.optional(),
+            schema: schemaParam.optional()
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, name, slug, browserTitle, layoutId, roleIds, middlewareIds, events, schema }) => {
+        const badEvents = invalidScreenEventNames(events, 'PAGE-011');
+        if (badEvents.length > 0)
+            throw new PlatformApiError(`Geçersiz sayfa olayı (istek gönderilmedi): ${badEvents.join(' · ')}`, 400);
+        const container = ensurePageContainer(schema ?? []);
+        const badWidgets = invalidWidgetTypeNodes(container.schema, 'PAGE-012');
+        if (badWidgets.length > 0)
+            throw new PlatformApiError(`Geçersiz widget düğümü (istek gönderilmedi): ${badWidgets.join(' · ')}`, 400);
+        const nested = nestedRepeaterNodes(container.schema);
+        if (nested.length > 0)
+            throw new PlatformApiError(nestedRepeaterMessage(nested), 400);
+        const stringStyles = stringStyleNodes(container.schema);
+        const fixed = normalizeComponentDefaults(container.schema);
+        const reset = resetPageContainerPosition(container.schema);
+        const catalog = (schema ?? []).length > 0
+            ? await applyCatalogLayoutRules(platform, project, environment, applicationId, container.schema)
+            : { clamped: [], heights: [] };
+        const moved = reorderSchemaBlocks(container.schema);
+        const gaps = (schema ?? []).length > 0 ? verticalGapWarnings(container.schema, 'PAGE-010 (uyarı)') : [];
+        const response = await platform.tenant('POST', project, `/pages/${applicationId}`, {
+            environment,
+            body: {
+                name,
+                slug,
+                browserTitle: browserTitle ?? '',
+                layoutId: layoutId ?? null,
+                roleIds: roleIds ?? [],
+                middlewareIds: middlewareIds ?? [],
+                events: events ?? [],
+                schema: container.schema
+            }
+        });
+        const normalized = withNormalization(response, [...container.fixes, ...reset, ...componentDefaultsNote(fixed), ...blockSizeNote(catalog.clamped), ...heightTypeNote(catalog.heights), ...reorderNote(moved)]);
+        const createWarnings = [...gaps, ...stringStyleWarning(stringStyles), ...inertFlexPropWarning(inertFlexPropNodes(container.schema))];
+        if (createWarnings.length === 0 || !normalized || typeof normalized !== 'object')
+            return normalized;
+        return { ...normalized, layoutWarnings: createWarnings };
+    }));
+    server.registerTool('page_update', {
+        title: 'Sayfa üstbilgisini güncelle',
+        description: "Sayfanın adını/slug'ını/layout'unu/rollerini değiştirir. Platformun PUT'u REPLACE'tir; gateway sayfayı önce okur, yalnız verdiğiniz alanları değiştirip tam gövdeyi geri yazar — bu yüzden şema ve olaylar kaybolmaz. ŞEMA değişikliği için bu tool'u değil page_schema_patch'i kullanın (doğrulama duvarı + canlı canvas orada).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            pageId: guid,
+            name: z.string().min(1).optional(),
+            slug: z.string().min(1).optional(),
+            browserTitle: z.string().optional(),
+            layoutId: guid.nullable().optional().describe('null: layout bağını kaldırır'),
+            roleIds: z.array(guid).optional(),
+            middlewareIds: z.array(guid).optional(),
+            events: eventsParam.optional(),
+            schema: schemaParam.optional().describe('Nadiren gerekir; verilmezse mevcut şema korunur')
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, applicationId, pageId, ...changes }) => {
+        const overrides = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
+        const badEvents = invalidScreenEventNames(overrides.events, 'PAGE-011');
+        if (badEvents.length > 0)
+            throw new PlatformApiError(`Geçersiz sayfa olayı (istek gönderilmedi): ${badEvents.join(' · ')}`, 400);
+        const badWidgets = invalidWidgetTypeNodes(overrides.schema, 'PAGE-012');
+        if (badWidgets.length > 0)
+            throw new PlatformApiError(`Geçersiz widget düğümü (istek gönderilmedi): ${badWidgets.join(' · ')}`, 400);
+        const nestedUpdate = nestedRepeaterNodes(overrides.schema);
+        if (nestedUpdate.length > 0)
+            throw new PlatformApiError(nestedRepeaterMessage(nestedUpdate), 400);
+        const current = await fetchHost(platform, 'page', project, environment, applicationId, pageId);
+        const badSchemaNames = invalidComponentNames(overrides.schema);
+        if (badSchemaNames.length > 0) {
+            throw new PlatformApiError(`PAGE-009 — komponent adı JS tanımlayıcısı değil (istek gönderilmedi): ${badSchemaNames.join(' · ')}. `
+                + 'Runtime her komponent için `const <ad> = Components["<ad>"]` üretir; geçersiz bir ad sayfadaki TÜM ifadeleri öldürür. '
+                + 'name = elementId yazın.', 400);
+        }
+        const fixed = normalizeComponentDefaults(overrides.schema);
+        const reset = overrides.schema === undefined ? [] : resetPageContainerPosition(overrides.schema);
+        const catalog = overrides.schema === undefined
+            ? { clamped: [], heights: [] }
+            : await applyCatalogLayoutRules(platform, project, environment, applicationId, overrides.schema);
+        const moved = overrides.schema === undefined ? [] : reorderSchemaBlocks(overrides.schema);
+        const gaps = overrides.schema === undefined
+            ? []
+            : [...verticalGapWarnings(overrides.schema, 'PAGE-010 (uyarı)'), ...inertFlexPropWarning(inertFlexPropNodes(overrides.schema))];
+        const body = pageUpdateBody(current, overrides);
+        await platform.tenant('PUT', project, `/pages/${applicationId}/${pageId}`, { environment, body });
+        const summary = {
+            id: pageId,
+            changed: Object.keys(overrides),
+            preserved: { schemaNodes: body.schema.length, events: body.events.length }
+        };
+        if (gaps.length > 0)
+            summary.layoutWarnings = gaps;
+        return withNormalization(summary, [...reset, ...componentDefaultsNote(fixed), ...blockSizeNote(catalog.clamped), ...heightTypeNote(catalog.heights), ...reorderNote(moved)]);
+    }));
+    server.registerTool('page_clone', {
+        title: 'Sayfa klonla',
+        description: "Sayfanın kopyasını oluşturur (şema, olaylar ve flow'larıyla). Klon ana sayfa olarak işaretlenmez.",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, pageId: guid },
+        annotations: writes
+    }, handle(config, ({ project, environment, applicationId, pageId }) => platform.tenant('POST', project, `/pages/${applicationId}/clone/${pageId}`, { environment })));
+    server.registerTool('page_delete', {
+        title: 'Sayfa sil',
+        description: 'Sayfayı siler. Ana sayfa (isHomepage) silinemez; önce başka bir sayfayı ana sayfa yapın. Silmeden önce dependency_graph module:\'page\' ile bağımlılıkları kontrol edin.',
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, pageId: guid },
+        annotations: destructive
+    }, handle(config, async ({ project, environment, applicationId, pageId }) => {
+        const page = unwrap(await platform.tenant('GET', project, `/pages/${applicationId}/${pageId}`, { environment }));
+        if (page.isHomepage === true) {
+            throw new PlatformApiError(`'${page.name}' ana sayfadır ve silinemez (CantDeleteHomepage); önce başka bir sayfa ana sayfa yapılmalı.`);
+        }
+        await platform.tenant('DELETE', project, `/pages/${applicationId}/${pageId}`, { environment });
+        return { deleted: pageId, name: page.name };
+    }));
+}

package/dist/tools/platformInfo.js

@@ -0,0 +1,44 @@
+import { listKnowledgeFiles, readKnowledgeFile } from '../resources/knowledge.js';
+import { logCapabilityGap } from '../observability/trace.js';
+import { handle } from '../platform/responses.js';
+import { readOnly } from './common.js';
+import { z } from 'zod';
+export function registerPlatformTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('platform_whoami', {
+        title: 'Oturum bilgisi',
+        description: 'Gateway\'in platformda kimin adına çalıştığını döner; auth kurulumunu doğrulamak için ilk çağrılacak tool.',
+        inputSchema: {},
+        annotations: readOnly
+    }, 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, 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 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')
+        },
+        annotations: readOnly
+    }, handle(config, async ({ guide }) => {
+        const available = listKnowledgeFiles('guides').map(file => file.replace(/\.md$/, ''));
+        if (!available.includes(guide)) {
+            return { error: `'${guide}' diye bir rehber yok.`, available };
+        }
+        return { guide, content: readKnowledgeFile('guides', `${guide}.md`), examples: listKnowledgeFiles('examples').map(file => `ngapps://examples/${file.replace(/\.json$/, '')}`) };
+    }));
+    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.",
+        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")'),
+            severity: z.enum(['blocker', 'workaround', 'cosmetic']).describe('blocker: özellik hiç yapılamadı · workaround: daha kötü bir yolla yapıldı · cosmetic: yalnız görsel/ergonomik kayıp'),
+            module: z.string().optional().describe('İlgili modül: entity | microservice | workflow | page | component | middleware | view | flow'),
+            attempted: z.array(z.string()).optional().describe('Denenen tool/yaklaşımlar — boşluğun gerçekten araştırıldığını gösterir'),
+            workaround: z.string().optional().describe('Bunun yerine ne yaptınız; hiçbir şey yapılamadıysa boş bırakın')
+        },
+        annotations: readOnly
+    }, handle(config, async ({ goal, blocker, severity, module, attempted, workaround }) => {
+        logCapabilityGap({ goal, blocker, severity, module, attempted, workaround });
+        return { recorded: true, severity, module: module ?? null, note: 'Günlüğe yazıldı. Kullanıcıya da tek cümleyle söyleyin: neyi yapamadınız ve yerine ne yaptınız.' };
+    }));
+}