@appaflytech/zeyrek-ai-mcp 0.0.40 → 0.0.41

package/dist/tools/pages.js

@@ -1,8 +1,8 @@
 import { guid, projectParam, environmentParam, pagingParams, asUserIdParam, readOnly, writes, updates, destructive, microOps, isBranchName, branchSlug } from './common.js';
-import { orphanedFlowWarnings, orphanedFlowPlan, orphanedFlowMessage, boundEventOps, stripGatewayEventFields, staleSetterWarnings, lostSetterTargets, fillComponentNames, componentNameNote, normalizeComponentDefaults, normalizeSchemaOps, schemaOpValidationErrors, codePropTemplateErrors, addComponentIdErrors, missingBlocksNodes, assertAddComponentIds, assertComponentBlocks, validationNote, componentDefaultsNote, replacePropNote, ensurePageContainer, retargetRootAdds, rootAddsNote, flexSizeWarnings, spacingLayerWarnings, reorderSchemaBlocks, reorderNote, nestedRepeaterNodes, nestedRepeaterMessage, stringStyleNodes, stringStyleWarning, inertFlexPropNodes, inertFlexPropWarning, FLEX_LAYOUT_PROP_NAMES, resetPageContainerPosition, pageContainerPositionWarning, verticalGapWarnings, flexIndexOrder, flexIndexOrderNote, withNormalization, parseVariableEntries, PAGE_CONTAINER_ELEMENT_ID } from '../knowledge/normalize.js';
+import { orphanedFlowWarnings, orphanedFlowPlan, orphanedFlowMessage, boundEventOps, stripGatewayEventFields, staleSetterWarnings, lostSetterTargets, fillComponentNames, componentNameNote, normalizeComponentDefaults, normalizeSchemaOps, schemaOpValidationErrors, codePropTemplateErrors, addComponentIdErrors, missingBlocksNodes, assertAddComponentIds, assertComponentBlocks, validationNote, componentDefaultsNote, replacePropNote, ensurePageContainer, retargetRootAdds, rootAddsNote, flexSizeWarnings, spacingLayerWarnings, reorderSchemaBlocks, reorderNote, nestedRepeaterNodes, nestedRepeaterMessage, stringStyleNodes, stringStyleWarning, inertFlexPropNodes, inertFlexPropWarning, FLEX_LAYOUT_PROP_NAMES, resetPageContainerPosition, pageContainerPositionWarning, verticalGapWarnings, flexIndexOrder, flexIndexOrderNote, withNormalization, parseVariableEntries, PAGE_CONTAINER_ELEMENT_ID, screenEventsNeedPlatform } from '../knowledge/normalize.js';
 import { functionSignature } from '../knowledge/functionGuards.js';
 import { attachFindings } from '../knowledge/policy.js';
-import { fetchHost, pageUpdateBody, schemaParam, eventsParam, unwrap, modeParam, summarize, findNode, flowPath, countSchemaNodes, missingElementIds, splitSchemaIntoParts, encodeSchemaCursor, decodeSchemaCursor } from './screens.js';
+import { fetchHost, pageUpdateBody, schemaParam, eventsParam, unwrap, modeParam, summarize, findNode, flowPath, countSchemaNodes, missingElementIds, readFullSchema } from './screens.js';
 import { fetchComponentEventNames } from './components.js';
 import { assertComponentNames, assertScreenWriteGuards, screenCatalogNotes, assertScreenCatalog } from './screenWrite.js';
 import { opsParam, writeViewParam, outlineWriteResponse, unknownEventOps, collectTypes, styleTargetTypes, simulateLayoutOps, applySkeletonOps, reshapesSkeleton, planEventRemovals, resizeServerOps, planResizes, planPropTypes, rejectedOpsMessage } from './schemaOps.js';
@@ -10,7 +10,7 @@ import { formBindingWarnings, formSubmitButtonWarnings } from '../knowledge/cove
 import { emptyWriteDiff, schemaOpDrops, unwrapProps, withWriteDiff, writeDiff } from '../platform/writeDiff.js';
 import { PlatformApiError } from '../platform/errors.js';
 import { existingMatch, ifExistsParam, listAll, withOutcome } from '../platform/ifExists.js';
-import { handle, toolResult, toolError, prune } from '../platform/responses.js';
+import { handle, toolResult, toolError } from '../platform/responses.js';
 import { expressionErrorsNote, runtimeErrorsNote, StudioScreenshotter } from '../platform/capture/index.js';
 import { captureTargetFor } from '../platform/capture/target.js';
 import { diffSummaries, summaryLines, summaryStats } from '../platform/domSummary.js';
@@ -267,7 +267,7 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
             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)"),
+            pageSlug: z.string().min(1).describe("Sayfanın slug'ı (page_list); sayfa parametresi sorguyla verilebilir: 'ilac-detay?id=7' (language '&lang=' olarak eklenir)"),
             viewport: z.object({
                 width: z.number().int().min(320).max(3840),
                 height: z.number().int().min(240).max(2160)
@@ -359,7 +359,14 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
                 throw new PlatformApiError("page_screenshot: asUserId ile cookies birlikte verilemez — uygulama oturum çerezi (ZY_App_…) geçerliyse platform başlığı değil çerezin sahibini özne yapar ve karenin kimin gözüyle çekildiği belirsiz kalır.");
             }
             const eye = await impersonationHeaders(platform, 'page_screenshot', project, environment, { asUserId, asUser, anonymous }, { runtime: true });
-            const url = `${config.studioBaseUrl}/${lane}/${projectSlug}/${applicationSlug}/${pageSlug}${languageChoice ? `?lang=${languageChoice.code}` : ''}`;
+            // 37 S-17 / 38 S-13: sorgulu slug (`ilac-detay?id=7`) dizeyle birleşince dil ikinci bir '?' ile
+            // ekleniyordu ve runtime `id`'yi '7?lang=tr' okudu; sayfa isteği işareti de sorguyu taşıdığı
+            // için sayfanın kendi veri isteğiyle hiç eşleşmiyordu.
+            const address = new URL(`${config.studioBaseUrl}/${lane}/${projectSlug}/${applicationSlug}/${pageSlug}`);
+            if (languageChoice)
+                address.searchParams.set('lang', languageChoice.code);
+            const url = address.toString();
+            const pagePath = pageSlug.split(/[?#]/, 1)[0];
             // Hedef ve cihaz uygulamanın platform profilinden (G3): mobil uygulama react-native-web
             // çizimidir, varsayılan kare telefon ön ayarıdır. Tip okunamazsa web davranışı aynen.
             const resolved = await resolveProfileBySlug(platform, projectSlug, applicationSlug);
@@ -384,7 +391,7 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
             const cookieNames = [...new Set([...(identity === 'anonymous' ? [] : ['NG_AccessToken']), ...extraCookies.map(cookie => cookie.name)])];
             const shot = await screenshotter.capture({
                 url,
-                apiPathMarker: `/${applicationSlug}/p/${pageSlug}`,
+                apiPathMarker: `/${applicationSlug}/p/${pagePath}`,
                 token: identityToken,
                 ...(eye ? { headers: eye } : {}),
                 ...(extraCookies.length > 0 ? { cookies: extraCookies } : {}),
@@ -657,41 +664,17 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
             throw new PlatformApiError(`cursor yalnız mode:'full' ile çalışır (verilen mode: '${mode ?? 'summary'}'); parçalı okuma tüm şema içindir. mode:'full' ile cursor:'0' verin ya da cursor'ı kaldırın.`, 400);
         }
         if (mode === 'full') {
-            const schema = page.schema ?? [];
-            const nodeCount = countSchemaNodes(schema);
-            const versionKey = String(version ?? '');
-            if (cursor !== undefined) {
-                const decoded = decodeSchemaCursor(cursor);
-                if (!decoded)
-                    throw new PlatformApiError(`cursor '${cursor}' çözülemedi; cursor yalnız '0' ya da önceki yanıttaki nextCursor olabilir. cursor:'0' ile baştan başlayın.`, 400);
-                if (decoded.version !== undefined && decoded.version !== versionKey) {
-                    throw new PlatformApiError(`Sayfa bu cursor alındıktan sonra değişti (cursor sürümü '${decoded.version}', güncel sürüm '${versionKey}'); eski parçalarla yenileri birleştirilirse şema tutarsız olur. Toplanan parçaları atın ve cursor:'0' ile baştan okuyun.`, 409);
-                }
-                const parts = splitSchemaIntoParts(schema, Math.floor(config.maxResponseBytes * 0.75));
-                const items = parts[decoded.partIndex];
-                if (!items)
-                    throw new PlatformApiError(`cursor '${cursor}' ${decoded.partIndex}. parçayı istiyor ama şema ${parts.length} parça; son parçadan sonra nextCursor gelmez. cursor:'0' ile baştan başlayın.`, 400);
-                const nextIndex = decoded.partIndex + 1;
-                return {
-                    version,
-                    updatedAt,
-                    ...typeField,
-                    nodeCount,
-                    part: { index: decoded.partIndex, count: parts.length, nodes: countSchemaNodes(items.map(item => item.node)) },
-                    items,
-                    ...(nextIndex < parts.length ? { nextCursor: encodeSchemaCursor(versionKey, nextIndex) } : {})
-                };
-            }
-            const full = { version, updatedAt, ...typeField, nodeCount, schema };
-            const chars = (JSON.stringify(prune(full)) ?? '').length;
-            if (chars > config.maxResponseBytes) {
-                if (allowTruncated !== true) {
-                    const kb = (value) => (value / 1024).toFixed(1);
-                    throw new PlatformApiError(`Şema ${nodeCount} düğüm / ${kb(chars)} KB; tek yanıta sığmaz (bütçe ${kb(config.maxResponseBytes)} KB). Kırpılmış şema hangi düğümlerin düştüğünü söylemez ve geri yazılırsa sayfa eksilir. cursor:'0' ile parça parça okuyun ya da allowTruncated:true verin (kırpılır, hangi düğümlerin düştüğü söylenmez). Hedef bulmak için mode:'summary' yeter.`, 400);
-                }
-                schemaReadMemory.markTruncated(readKey(project, environment, pageId, version));
-            }
-            return full;
+            return readFullSchema({
+                noun: 'Sayfa',
+                field: 'schema',
+                nodes: page.schema ?? [],
+                versionKey: String(version ?? ''),
+                base: { version, updatedAt, ...typeField },
+                cursor,
+                allowTruncated,
+                maxResponseBytes: config.maxResponseBytes,
+                onTruncated: () => schemaReadMemory.markTruncated(readKey(project, environment, pageId, version))
+            });
         }
         if (mode === 'subtree') {
             if (!componentId)
@@ -1258,7 +1241,10 @@ export function registerPageTools(server, platform, injectedScreenshotter, injec
         const overrides = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
         const named = fillComponentNames(overrides.schema);
         const resolved = overrides.schema === undefined ? undefined : await resolveProfile(platform, applicationId);
-        assertScreenWriteGuards('page', { schema: overrides.schema, events: overrides.events }, resolved?.profile.platform);
+        // Kök ADR 0015: `focus` yalnız mobil sayfada geçerli — şemasız olay yazımında da uygulamanın platformu okunur.
+        const eventPlatform = resolved?.profile.platform
+            ?? (screenEventsNeedPlatform(overrides.events) ? (await resolveProfile(platform, applicationId)).profile.platform : undefined);
+        assertScreenWriteGuards('page', { schema: overrides.schema, events: overrides.events }, eventPlatform);
         const current = await fetchHost(platform, 'page', project, environment, applicationId, pageId);
         if (overrides.schema !== undefined && allowNodeLoss !== true) {
             const storedSchema = current.schema;

package/dist/tools/queries.js

@@ -73,7 +73,7 @@ export function registerQueryTools(server, platform) {
     }, handle(config, ({ project, environment, id }) => platform.tenant('GET', project, `/queries/${id}`, { environment })));
     server.registerTool('query_create', {
         title: 'Query oluştur',
-        description: "Yeni query tanımlar (ham SQL). definition = CreateQueryCommand gövdesi. AGREGASYON VE RAPORLAMANIN YOLU BUDUR (SUM/COUNT/AVG/GROUP BY, dönemsel özet, KPI) — view_* bir TAM METİN ARAMA indeksidir, özet üretmez (09-02 M-3). VAR OLAN SATIRLARDAN TÜRETİLEN SATIR YAZMANIN DA YOLU BUDUR: 'INSERT … SELECT' kaydedip query kaynaklı bir uçtan çalıştırmak, geçmiş/hareket/junction tablosunu TEK çağrıda doldurur ve hiçbir id elle taşınmaz (ölçüldü 2026-09-07; reçete platform_guide('entity') §'Toplu ve türetilmiş satır'). Kayıt sırasında gövde bir kez ÇALIŞTIRILIR ama geri alınır — yazan sorguyu kaydetmek satır bırakmaz ve 'returnScheme' boş döner. Kayıtlı query'nin parametreleri parameterScheme ile tanımlanır ve runtime'da bağlanır; tüketimi source:'query' microservice'idir. PARAMETRENİN DEĞERİ HER ZAMAN ÇAĞRIDAN GELİR (body → query-string → header): parametreye ifade kaynağı verilemez (parameters[].source komut şemasında yoktur, platform sessizce atar) ve middleware'in kurduğu user bu yola girmez. Kimlik/tenant kapsamı sunucu tarafında zorlanacaksa sorguyu bir workflow query adımından çağırın — reçete platform_guide('microservice') §'Kimlik kapsaması × uç kaynağı'. BOŞ STRING parametre NULL'a çevrilir: '= @p' koşulu hiçbir satırla eşleşmez ve sorgu sessizce 0 satır döner — 'filtre yok' için (@p IS NULL OR ...) yazın ya da sentinel kullanın; (@p = '' OR ...) kalıbı hiçbir zaman eşleşmez ve gateway `QRY-007` uyarısı düşürür. Yorum içindeki belirteç parametre sayılmaz. SQL çalıştırılamazsa kayıt YİNE de oluşur: returnScheme boş kalır ve yanıttaki message nedeni söyler — SQL'i düzeltip query_update ile kaydedin. SORGUNUN KENDİ AÇIKLAMASI VAR: `description` alanını doldurun — sorgu listesinde ad ve slug dışında ipucu yoktur ve ucun açıklaması (MS-014) bunun yerine geçmez, çünkü bir sorgu birden çok uçtan tüketilir; boş bırakılırsa gateway `QRY-006` uyarısı düşürür (yazmayı durdurmaz). " + constraintSummary('CreateQueryCommand'),
+        description: "Yeni query tanımlar (ham SQL). definition = CreateQueryCommand gövdesi. AGREGASYON VE RAPORLAMANIN YOLU BUDUR (SUM/COUNT/AVG/GROUP BY, dönemsel özet, KPI) — view_* bir TAM METİN ARAMA indeksidir, özet üretmez (09-02 M-3). VAR OLAN SATIRLARDAN TÜRETİLEN SATIR YAZMANIN DA YOLU BUDUR: 'INSERT … SELECT' kaydedip query kaynaklı bir uçtan çalıştırmak, geçmiş/hareket/junction tablosunu TEK çağrıda doldurur ve hiçbir id elle taşınmaz (ölçüldü 2026-09-07; reçete platform_guide('entity') §'Toplu ve türetilmiş satır'). Kayıt sırasında gövde bir kez ÇALIŞTIRILIR ama geri alınır — yazan sorguyu kaydetmek satır bırakmaz; 'returnScheme' yalnız sonuç kümesi DÖNMEYEN yazan sorguda boştur — 'INSERT/UPDATE/DELETE … RETURNING' ya da sonda bir SELECT taşıyan gövdede dönen kolonlarla DOLU gelir (37 S-5). json/jsonb kolonu returnScheme'de 'string' tiplenir ve değeri JSON METNİ gelir (preview'da da çalışma anında da); akışta JSON.parse ile açın. Şema tipi önizlemede değil KAYITTA sabitlenir (37 S-2, b-25 ertelendi). Kayıtlı query'nin parametreleri parameterScheme ile tanımlanır ve runtime'da bağlanır; tüketimi source:'query' microservice'idir. PARAMETRENİN DEĞERİ HER ZAMAN ÇAĞRIDAN GELİR (body → query-string → header): parametreye ifade kaynağı verilemez (parameters[].source komut şemasında yoktur, platform sessizce atar) ve middleware'in kurduğu user bu yola girmez. Kimlik/tenant kapsamı sunucu tarafında zorlanacaksa sorguyu bir workflow query adımından çağırın — reçete platform_guide('microservice') §'Kimlik kapsaması × uç kaynağı'. BOŞ STRING parametre NULL'a çevrilir: '= @p' koşulu hiçbir satırla eşleşmez ve sorgu sessizce 0 satır döner — 'filtre yok' için (@p IS NULL OR ...) yazın ya da sentinel kullanın; (@p = '' OR ...) kalıbı hiçbir zaman eşleşmez ve gateway `QRY-007` uyarısı düşürür. Yorum içindeki belirteç parametre sayılmaz. SQL çalıştırılamazsa kayıt YİNE de oluşur: returnScheme boş kalır ve yanıttaki message nedeni söyler — SQL'i düzeltip query_update ile kaydedin. SORGUNUN KENDİ AÇIKLAMASI VAR: `description` alanını doldurun — sorgu listesinde ad ve slug dışında ipucu yoktur ve ucun açıklaması (MS-014) bunun yerine geçmez, çünkü bir sorgu birden çok uçtan tüketilir; boş bırakılırsa gateway `QRY-006` uyarısı düşürür (yazmayı durdurmaz). " + constraintSummary('CreateQueryCommand'),
         inputSchema: { project: projectParam, environment: environmentParam, definition: definitionParam, policyOverride: policyOverrideParam },
         annotations: writes
     }, handle(config, async ({ project, environment, definition, policyOverride }) => {

package/dist/tools/rows.js

@@ -53,9 +53,20 @@ const bulkBatchSize = 1000;
 const maxPathBytes = 50 * 1024 * 1024;
 const maxPathRows = 100_000;
 const pathParam = z.string().min(1).optional()
-    .describe("Gateway sürecinin okuyabildiği yerel `.json` (satır dizisi) ya da `.csv` dosyası; 'row'/'rows' ile birlikte verilmez. Satırlar ajan bağlamından HİÇ geçmez: gateway dosyayı okur, 1000'lik partilere böler ve ardışık toplu çağrı yapar. CSV ayracı ilk satırdan bulunur (`;` sayısı `,` sayısını geçerse `;`), değerler string gider ve tipe backend çevirir. 50 MB / 100.000 satır üstü reddedilir — o boyut import_analyze zinciridir.");
+    .describe("Gateway sürecinin okuyabildiği yerel `.json` (satır dizisi) ya da `.csv` dosyası; 'row'/'rows' ile birlikte verilmez. Satırlar ajan bağlamından HİÇ geçmez: gateway dosyayı okur, 1000'lik partilere böler ve ardışık toplu çağrı yapar; yanıt { written, batches, ids (platform döndürdüyse ilk 10), truncated } — tam id listesi için row_list. CSV ayracı ilk satırdan bulunur (`;` sayısı `,` sayısını geçerse `;`), değerler string gider ve tipe backend çevirir. 50 MB / 100.000 satır üstü reddedilir — o boyut import_analyze zinciridir.");
 const relationsByNameParam = z.boolean().optional()
     .describe("İlişki alanlarına id yerine GÖRÜNEN AD yazmayı açar: 'departman: \"Satış\"' hedef tablonun display ya da benzersiz alanında aranır ve id'ye çevrilir. Yalnız toplu yolda (rows / path) çalışır. Eşleşmeyen değer 422 döndürür ve hangi satırın hangi alanı olduğunu söyler — sessizce boş bırakmaz.");
+/**
+ * 37 S-4: `path` "satırlar ajan bağlamından hiç geçmez" der, ama toplu uç her partide yazdığı id'leri
+ * döndürünce yanıt dosyanın satır sayısı kadar id taşıyordu (82 satır → `ids[82]`). Dosya yolunda
+ * yanıt sayıdır; id'lerden yalnız ilk birkaçı örnek olarak kalır, tamamı row_list'tedir.
+ */
+const fileIdSample = 10;
+function withIdSample(outcome) {
+    if (!outcome.ids)
+        return outcome;
+    return { ...outcome, ids: outcome.ids.slice(0, fileIdSample), truncated: outcome.ids.length > fileIdSample };
+}
 function collectIds(payload, into) {
     const data = payload?.data;
     if (Array.isArray(data))
@@ -315,7 +326,7 @@ export function registerRowTools(server, platform) {
             const outcome = await writeInBatches(platform, 'POST', project, environment, headers, resolvedEntityId, bulkRows, rowContext, relationsByName);
             if (fileRows)
                 notes.push(`${path} okundu: ${fileRows.length} satır, ${Math.ceil(fileRows.length / bulkBatchSize)} parti.`);
-            return attachFindings(withUnmappedMembers(withNormalization(withResolved(outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved(fileRows ? withIdSample(outcome) : outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
         }
         const body = { row, ...(wantedLocalizations ? { localizations: wantedLocalizations } : {}), ...(rowContext ? { rowContext } : {}) };
         const drift = unmappedMembers('CreateRowCommand', body);
@@ -384,7 +395,7 @@ export function registerRowTools(server, platform) {
             const outcome = await writeInBatches(platform, 'PUT', project, environment, headers, resolvedEntityId, bulkRows, rowContext, relationsByName);
             if (fileRows)
                 notes.push(`${path} okundu: ${fileRows.length} satır, ${Math.ceil(fileRows.length / bulkBatchSize)} parti.`);
-            return attachFindings(withUnmappedMembers(withNormalization(withResolved(outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved(fileRows ? withIdSample(outcome) : outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
         }
         const body = { row, ...(localizations ? { localizations } : {}), ...(rowContext ? { rowContext } : {}) };
         const drift = unmappedMembers('UpdateRowCommand', body);

package/dist/tools/screenWrite.js

@@ -1,4 +1,4 @@
-import { invalidScreenEventNames, invalidWidgetTypeNodes, nestedRepeaterNodes, nestedRepeaterMessage, assertComponentBlocks, blockSizeNote, heightTypeNote, sizeStringNote, droppableStatesNote } from '../knowledge/normalize.js';
+import { invalidScreenEventNames, screenEventNames, invalidWidgetTypeNodes, nestedRepeaterNodes, nestedRepeaterMessage, assertComponentBlocks, blockSizeNote, heightTypeNote, sizeStringNote, droppableStatesNote } from '../knowledge/normalize.js';
 import { catalogTypeRules, schemaCatalogErrors, schemaCatalogMessage } from '../knowledge/componentCatalog.js';
 import { FUNCTIONS_NAMESPACE } from '../knowledge/functionGuards.js';
 import { reservedExpressionName } from '../knowledge/expressionPrelude.js';
@@ -56,7 +56,7 @@ export function invalidComponentNames(nodes) {
  */
 export function assertScreenWriteGuards(kind, screen, platform) {
     const codes = GUARD_CODES[kind];
-    const badEvents = invalidScreenEventNames(screen.events, codes.events);
+    const badEvents = invalidScreenEventNames(screen.events, codes.events, screenEventNames(kind, platform));
     if (badEvents.length > 0)
         throw new PlatformApiError(`Geçersiz ${codes.noun} olayı (istek gönderilmedi): ${badEvents.join(' · ')}`, 400);
     const badWidgets = invalidWidgetTypeNodes(screen.schema, codes.widgets);

package/dist/tools/screens.js

@@ -2,6 +2,7 @@ import { PlatformApiError } from '../platform/errors.js';
 import { resolveNodeStyleReport } from '../knowledge/styleResolve.js';
 import { nodeNativeStyle } from '../knowledge/styleResolveNative.js';
 import { jsonArray } from '../platform/jsonArray.js';
+import { prune } from '../platform/responses.js';
 import { z } from 'zod';
 export const hostParam = z.enum(['page', 'layout', 'component'])
     .describe("Akışın barındırıcısı: page | layout | component (widget de component'tir)");
@@ -75,6 +76,44 @@ export function splitSchemaIntoParts(schema, budgetChars) {
 export function encodeSchemaCursor(version, partIndex) {
     return `${version}:${partIndex}`;
 }
+/**
+ * ADR 0001 — `mode:'full'` okumanın sayfa ve layout ortak kapısı: sığan ağaç tam döner, sığmayan HATA
+ * verir (sessiz kırpma yok); `cursor` ile parçalar `items[]` olarak gelir, sürüm değişince 409.
+ * `allowTruncated:true` kırpmayı açıkça ister — global `shrink()` kırpar, `onTruncated` işaretler.
+ */
+export function readFullSchema(read) {
+    const nodeCount = countSchemaNodes(read.nodes);
+    if (read.cursor !== undefined) {
+        const decoded = decodeSchemaCursor(read.cursor);
+        if (!decoded)
+            throw new PlatformApiError(`cursor '${read.cursor}' çözülemedi; cursor yalnız '0' ya da önceki yanıttaki nextCursor olabilir. cursor:'0' ile baştan başlayın.`, 400);
+        if (decoded.version !== undefined && decoded.version !== read.versionKey) {
+            throw new PlatformApiError(`${read.noun} bu cursor alındıktan sonra değişti (cursor sürümü '${decoded.version}', güncel sürüm '${read.versionKey}'); eski parçalarla yenileri birleştirilirse şema tutarsız olur. Toplanan parçaları atın ve cursor:'0' ile baştan okuyun.`, 409);
+        }
+        const parts = splitSchemaIntoParts(read.nodes, Math.floor(read.maxResponseBytes * 0.75));
+        const items = parts[decoded.partIndex];
+        if (!items)
+            throw new PlatformApiError(`cursor '${read.cursor}' ${decoded.partIndex}. parçayı istiyor ama şema ${parts.length} parça; son parçadan sonra nextCursor gelmez. cursor:'0' ile baştan başlayın.`, 400);
+        const nextIndex = decoded.partIndex + 1;
+        return {
+            ...read.base,
+            nodeCount,
+            part: { index: decoded.partIndex, count: parts.length, nodes: countSchemaNodes(items.map(item => item.node)) },
+            items,
+            ...(nextIndex < parts.length ? { nextCursor: encodeSchemaCursor(read.versionKey, nextIndex) } : {})
+        };
+    }
+    const full = { ...read.base, nodeCount, [read.field]: read.nodes };
+    const chars = (JSON.stringify(prune(full)) ?? '').length;
+    if (chars > read.maxResponseBytes) {
+        if (read.allowTruncated !== true) {
+            const kb = (value) => (value / 1024).toFixed(1);
+            throw new PlatformApiError(`Şema ${nodeCount} düğüm / ${kb(chars)} KB; tek yanıta sığmaz (bütçe ${kb(read.maxResponseBytes)} KB). Kırpılmış şema hangi düğümlerin düştüğünü söylemez ve geri yazılırsa ${read.noun === 'Sayfa' ? 'sayfa' : 'layout'} eksilir. cursor:'0' ile parça parça okuyun ya da allowTruncated:true verin (kırpılır, hangi düğümlerin düştüğü söylenmez). Hedef bulmak için mode:'summary' yeter.`, 400);
+        }
+        read.onTruncated?.();
+    }
+    return full;
+}
 /** `'0'` sürümsüz ilk parçadır; `<sürüm>:<parça>` sürümü taşır. Çözülemeyen cursor `undefined`. */
 export function decodeSchemaCursor(cursor) {
     if (/^\d+$/.test(cursor))

package/dist/tools/translations.js

@@ -1,14 +1,84 @@
-import { guid, projectParam, environmentParam, readOnly, updates } from './common.js';
+import { guid, projectParam, environmentParam, readOnly, writes, updates } from './common.js';
 import { handle } from '../platform/responses.js';
+import { PlatformApiError } from '../platform/errors.js';
 import { z } from 'zod';
 import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/policy.js';
 import { readProjectLanguages, translationLanguageFindings } from '../knowledge/languages.js';
 import { policyRules } from '../knowledge/rules.js';
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, resolve } from 'node:path';
+const isoLanguageCode = z.string().regex(/^[a-z]{2}$/, 'ISO 639-1 iki harfli küçük dil kodu (tr, en, de …); tr-TR gibi bölge ekli kod reddedilir');
 const translationKeyInput = z.object({
     key: z.string().min(1),
-    values: z.record(z.string().regex(/^[a-z]{2}$/, 'ISO 639-1 iki harfli küçük dil kodu (tr, en, de …); tr-TR gibi bölge ekli kod reddedilir'), z.string()).describe("Dil kodu (ISO 639-1, iki küçük harf) → çeviri metni. Platform kodu yalnız 184 kodluk ISO sözlüğüne göre doğrular (TR-001); PROJENİN languages listesine göre doğrulamaz — o bağı gateway kurar (TR-002)"),
+    values: z.record(isoLanguageCode, z.string()).describe("Dil kodu (ISO 639-1, iki küçük harf) → çeviri metni. Platform kodu yalnız 184 kodluk ISO sözlüğüne göre doğrular (TR-001); PROJENİN languages listesine göre doğrulamaz — o bağı gateway kurar (TR-002)"),
     componentId: guid.optional().describe("Çeviriyi belirli bir komponente bağlar; o komponent silinince kaydı da silinir")
 });
+/**
+ * ADR 0018 (zeyrek-backend/docs/adr/0018-ceviri-dosya-aktarimi.md) §4: çeviri dosyası platformda
+ * saklanmaz — içe aktarma ucu dosyanın kendisini multipart alır, dışa aktarma yalnız yerel yola
+ * yazılır. Sınır backend `TranslationConstants.ImportMaxFileBytes` ile aynıdır; aşan dosya gidip
+ * 422 almak yerine burada durur.
+ */
+const translationFileMaxBytes = 10 * 1024 * 1024;
+const xlsxContentType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+/**
+ * `translation_update { file }` kipi. Backend `POST /translations/{applicationId}/import`
+ * (`ImportTranslationsCommand`) dili kendisi projeye eklediği için TR-002 ön okuması yapılmaz.
+ */
+async function importTranslationFile(platform, { project, environment, applicationId, file, targetLanguage, dryRun }) {
+    const absolute = resolve(file);
+    if (extname(absolute).toLowerCase() !== '.xlsx') {
+        throw new PlatformApiError(`translation_update: file bir .xlsx dosyası olmalı (${absolute}). Çeviri dosyası yalnız Excel biçiminde içe aktarılır; biçimi translation_export'un ürettiği dosyadır.`);
+    }
+    let bytes;
+    try {
+        bytes = await readFile(absolute);
+    }
+    catch (error) {
+        throw new PlatformApiError(`translation_update: dosya okunamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+    }
+    if (bytes.byteLength > translationFileMaxBytes) {
+        throw new PlatformApiError(`translation_update: dosya ${bytes.byteLength} B, platformun 10 MB çeviri dosyası sınırının üstünde. Dosyada resim ya da ek sayfa varsa kaldırın; yalnız Key / kaynak / hedef sütunları gerekir.`);
+    }
+    const response = await platform.tenant('POST', project, `/translations/${applicationId}/import`, {
+        environment,
+        multipart: [
+            { name: 'File', filename: basename(absolute), contentType: xlsxContentType, content: bytes },
+            { name: 'TargetLanguage', value: targetLanguage },
+            { name: 'DryRun', value: dryRun ? 'true' : 'false' }
+        ]
+    });
+    const result = response?.data ?? {};
+    const notes = [];
+    if (result.languageAdded) {
+        notes.push(`Hedef dil '${result.targetLanguage}' projeye bütün ortamlarda eklendi; production'da çeviriler deployment'la gelir, o zamana kadar varsayılan dile düşer (TR-004).`);
+    }
+    else if (result.dryRun && result.targetLanguageInProject === false) {
+        notes.push(`Hedef dil '${result.targetLanguage}' projede yok; dryRun olmadan yapılan çağrı onu projeye bütün ortamlarda ekleyecek (TR-004).`);
+    }
+    if ((result.unknownKeyCount ?? 0) > 0) {
+        notes.push(`${result.unknownKeyCount} key application'da yok ve açılmadı (${(result.unknownKeys ?? []).join(', ')}). Yeni key için keys kipini kullanın.`);
+    }
+    if (result.applicationMismatch) {
+        notes.push('Dosya başka bir application\'dan dışa aktarılmış (_zeyrek meta); yalnız bu application\'da bulunan key\'ler yazıldı.');
+    }
+    return { ...result, ...(notes.length > 0 ? { note: notes.join(' ') } : {}) };
+}
+/**
+ * 38 S-6: platform PUT yanıtında uygulamanın BÜTÜN sözlüğünü döner (`ArrayBaseResponse<TranslationDto>`;
+ * 3. çağrıda 226 satır, ~25 bin karakter) — tek anahtar eklemek bile tam sözlüğü ajan bağlamına
+ * sokuyordu. Yanıt yazılanın özetidir; sözlüğün kendisi translation_list'tedir. Örnek sınırı
+ * `row_*` path yanıtındaki id örneğiyle aynıdır (37 S-4).
+ */
+const writtenKeySample = 10;
+function translationWriteSummary(keys, deletedKeys) {
+    return {
+        written: keys.length,
+        ...(deletedKeys.length > 0 ? { deleted: deletedKeys.length } : {}),
+        keys: keys.slice(0, writtenKeySample).map(entry => entry.key),
+        truncated: keys.length > writtenKeySample
+    };
+}
 /**
  * Yazma öncesi projenin dil durumunu okur. Proje okunamazsa (uç düşer, yetki yoksa) kontrol
  * ATLANIR ve karar platforma kalır — `project_create`'in slug ön aramasındaki (PRJ-001) davranışın
@@ -30,24 +100,96 @@ export function registerTranslationTools(server, platform) {
         inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid },
         annotations: readOnly
     }, handle(config, ({ project, environment, applicationId }) => platform.tenant('GET', project, `/translations/${applicationId}`, { environment })));
+    server.registerTool('translation_export', {
+        title: 'Çevirileri Excel olarak dışa aktar',
+        description: "Application'ın bütün çeviri key'lerini çevirmene verilecek bir .xlsx dosyasına yazar: A Key · B kaynak dil (referans) · C hedef dil (hedefte değeri olan key'ler dolu gelir). Dosya YALNIZ outPath'e yazılır — Sürücü'ye yüklenmez, platformda iz kalmaz; içerik bağlama girmez, yanıt yol ve sayılardır ({ keys: application'daki key sayısı, targetMissing: hedefte boş olanlar }). Çevirmen C sütununu doldurduktan sonra dosyayı translation_update { file, targetLanguage, dryRun: true } ile önce sınayın, sonra dryRun olmadan içe aktarın; hedef dil projede yoksa içe aktarma onu projeye BÜTÜN ortamlarda ekler (TR-004). Ajan çeviriyi kendisi yapacaksa dosyaya gerek yok: translation_list → translation_update { keys }.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid,
+            targetLanguage: isoLanguageCode.describe("Çevirmenin dolduracağı hedef dil (C sütunu); başlığa 'Target Language (ES)' biçiminde yalnız çevirmen için yazılır — içe aktarma başlığı okumaz, dili translation_update'in targetLanguage'ı belirler"),
+            sourceLanguage: isoLanguageCode.optional().describe('Çevirmene referans olacak kaynak dil (B sütunu); verilmezse projenin varsayılan dili'),
+            missingOnly: z.boolean().optional().describe("true: yalnız hedef dilde değeri olmayan ya da boş key'ler yazılır"),
+            outPath: z.string().min(1).describe("Dosyanın yazılacağı yerel yol, .xlsx ile biter (zorunlu). Yol gateway sürecinin çalıştığı makineye göre çözülür; var olan dosya ezilir")
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, targetLanguage, sourceLanguage, missingOnly, outPath }) => {
+        if (sourceLanguage === targetLanguage) {
+            throw new PlatformApiError(`translation_export: kaynak ve hedef dil aynı ('${targetLanguage}'). sourceLanguage'ı başka bir dil yapın ya da vermeyip projenin varsayılan diline bırakın.`);
+        }
+        const absolute = resolve(outPath);
+        if (extname(absolute).toLowerCase() !== '.xlsx') {
+            throw new PlatformApiError(`translation_export: outPath .xlsx ile bitmeli (${absolute}); çeviri dosyası yalnız Excel biçiminde üretilir.`);
+        }
+        const response = await platform.tenantWithHeaders('GET', project, `/translations/${applicationId}/export`, {
+            environment,
+            expectBinary: true,
+            query: { targetLanguage, ...(sourceLanguage ? { sourceLanguage } : {}), ...(missingOnly ? { missingOnly } : {}) }
+        });
+        const payload = response.body;
+        try {
+            await writeFile(absolute, payload.bytes);
+        }
+        catch (error) {
+            throw new PlatformApiError(`translation_export: dosya yazılamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}). Klasör var olmalı; yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+        }
+        const listed = await platform.tenant('GET', project, `/translations/${applicationId}`, { environment });
+        const translations = listed?.data ?? [];
+        const keys = new Set(translations.map(translation => translation.key));
+        const translatedKeys = new Set(translations.filter(translation => translation.language === targetLanguage && (translation.value ?? '').trim() !== '').map(translation => translation.key));
+        const projectLanguages = readProjectLanguages(await platform.org('GET', `/p/${platform.resolveProject(project)}`).catch(() => undefined));
+        const fileName = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(response.headers['content-disposition'] ?? '')?.[1];
+        const notes = projectLanguages && !projectLanguages.languages.includes(targetLanguage)
+            ? [`Hedef dil '${targetLanguage}' projenin dil listesinde yok; dosya içe aktarılınca proje diline bütün ortamlarda eklenir (TR-004).`]
+            : [];
+        notes.push(`Çevirmen C sütununu doldurduktan sonra: translation_update { file: '<yol>', targetLanguage: '${targetLanguage}', dryRun: true } → sonra dryRun olmadan.`);
+        return {
+            outPath: absolute,
+            fileName: fileName ?? basename(absolute),
+            bytes: payload.bytes.byteLength,
+            keys: keys.size,
+            targetMissing: keys.size - translatedKeys.size,
+            sourceLanguage: sourceLanguage ?? projectLanguages?.defaultLanguage,
+            targetLanguage,
+            note: notes.join(' ')
+        };
+    }));
     server.registerTool('translation_update', {
         title: 'Çevirileri güncelle',
-        description: "Bir ya da daha çok çeviri anahtarını toplu ekler/günceller (keys) ve/veya siler (deletedKeys) — tek çağrıda ikisi de verilebilir. 'keys' üzerinden yeni bir anahtar da açılabilir (upsert; verilmeyen diller silinmez, korunur). DİKKAT: çeviri yazmak tek başına YETMEZ — runtime bir etiketi ancak projenin languages listesi ve defaultLanguage kuruluysa çözer, aksi hâlde ekrana ham anahtar basar ve yazma yine 200 döner (ölçüldü 2026-09-09, S-15). Gateway yazmadan önce projeyi okur ve bağ kopuksa TR-002 caution'ı düşer; dilleri project_update(languages, defaultLanguage) ile kurun. Backend ön kontrolü (TR-001, block): anahtarlar boş olamaz ve tekil, dil kodları ISO 639-1 listesinden, deletedKeys boş olamaz.",
+        description: "Bir ya da daha çok çeviri anahtarını toplu ekler/günceller (keys) ve/veya siler (deletedKeys) — tek çağrıda ikisi de verilebilir. 'keys' üzerinden yeni bir anahtar da açılabilir (upsert; verilmeyen diller silinmez, korunur). DİKKAT: çeviri yazmak tek başına YETMEZ — runtime bir etiketi ancak projenin languages listesi ve defaultLanguage kuruluysa çözer, aksi hâlde ekrana ham anahtar basar ve yazma yine 200 döner (ölçüldü 2026-09-09, S-15). Gateway yazmadan önce projeyi okur ve bağ kopuksa TR-002 caution'ı düşer; dilleri project_update(languages, defaultLanguage) ile kurun. Backend ön kontrolü (TR-001, block): anahtarlar boş olamaz ve tekil, dil kodları ISO 639-1 listesinden, deletedKeys boş olamaz. Yanıt özettir: { written, deleted?, keys (yazılan ilk 10 anahtar), truncated } — platformun döndürdüğü tam sözlük bağlama taşınmaz, okumak için translation_list. DOSYA KİPİ: 'file' (yerel .xlsx yolu, translation_export biçimi) verilirse keys/deletedKeys verilmez; dosya platforma multipart gider ve SAKLANMAZ. C sütunu 'targetLanguage'ta verilen dile yazılır (zorunlu; başlık metni okunmaz — C1'deki '(ES)' gibi kod dili belirlemez): dolu hücre mevcut değeri EZER, boş hücre atlanır, application'da olmayan key açılmaz (unknownKeys); hedef dil projede yoksa projeye BÜTÜN ortamlarda eklenir (TR-004). 'dryRun: true' hiçbir şey yazmadan sayar. Yanıt: { targetLanguage, created, updated, unchanged, skippedEmpty, unknownKeyCount, unknownKeys, targetLanguageInProject, languageAdded, applicationMismatch, dryRun, note? }.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
             applicationId: guid,
             keys: z.array(translationKeyInput).optional().describe('Eklenecek/güncellenecek anahtarlar'),
-            deletedKeys: z.array(z.string().min(1)).optional().describe('Silinecek anahtar adları')
+            deletedKeys: z.array(z.string().min(1)).optional().describe('Silinecek anahtar adları'),
+            file: z.string().min(1).optional().describe("Çevirmenin doldurduğu yerel .xlsx yolu (en çok 10 MB): A Key, B kaynak dil (okunmaz), C hedef dil; başlık satırı okunmaz, dil targetLanguage'tan gelir. Gateway dosyayı okuyup içe aktarma ucuna gönderir, Sürücü'ye yüklemez. keys/deletedKeys ile birlikte verilmez"),
+            targetLanguage: isoLanguageCode.optional().describe("Yalnız file ile ve file verilince ZORUNLU: C sütununun yazılacağı dil (ISO 639-1, 'de'). Dosyanın başlığı dili belirlemez; projede yoksa dil projeye BÜTÜN ortamlarda eklenir (TR-004)"),
+            dryRun: z.boolean().optional().describe('Yalnız file ile: yazmadan created/updated/unchanged/skippedEmpty/unknownKeys sayımını ve dilin projeye eklenip eklenmeyeceğini döner')
         },
         annotations: updates
-    }, handle(config, async ({ project, environment, applicationId, keys, deletedKeys }) => {
+    }, handle(config, async ({ project, environment, applicationId, keys, deletedKeys, file, targetLanguage, dryRun }) => {
+        if (file !== undefined && (keys?.length || deletedKeys?.length)) {
+            throw new PlatformApiError("translation_update: 'file' ile 'keys'/'deletedKeys' birlikte verilmez — dosyayı ayrı bir çağrıda içe aktarın, tek tek anahtarları başka bir çağrıda yazın.");
+        }
+        if (dryRun !== undefined && file === undefined) {
+            throw new PlatformApiError("translation_update: dryRun yalnız 'file' kipinde geçerlidir; keys/deletedKeys yazımının kuru koşusu yoktur.");
+        }
+        if (targetLanguage !== undefined && file === undefined) {
+            throw new PlatformApiError("translation_update: targetLanguage yalnız 'file' kipinde geçerlidir; keys yazımında dil her değerin kendi anahtarıdır (values: { de: '…' }).");
+        }
+        if (file !== undefined && targetLanguage === undefined) {
+            throw new PlatformApiError("translation_update: 'file' kipinde targetLanguage zorunludur — C sütununun hangi dile yazılacağını dosya değil istek söyler (ör. targetLanguage: 'de'). Dosyanın başlığındaki '(DE)' okunmaz.");
+        }
+        if (file !== undefined)
+            return importTranslationFile(platform, { project, environment, applicationId, file, targetLanguage: targetLanguage, dryRun: dryRun ?? false });
         if (!keys?.length && !deletedKeys?.length) {
             throw new Error("'keys' ya da 'deletedKeys' parametrelerinden en az biri dolu olmalı.");
         }
         const body = { keys: keys ?? [], deletedKeys: deletedKeys ?? [] };
         const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'translation', body, { operation: 'update' }), false);
         const languages = await languageFindings(platform, project, keys ?? []);
-        return attachFindings(await platform.tenant('PUT', project, `/translations/${applicationId}`, { environment, body }), [...findings, ...languages]);
+        await platform.tenant('PUT', project, `/translations/${applicationId}`, { environment, body });
+        return attachFindings(translationWriteSummary(body.keys, body.deletedKeys), [...findings, ...languages]);
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appaflytech/zeyrek-ai-mcp",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "type": "module",
   "description": "Zeyrek (NgApps) platform APIs as MCP tools — data, logic and Studio design surface in one gateway",
   "license": "UNLICENSED",