@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/tools/entities.js

@@ -1,7 +1,10 @@
-import { guid, projectParam, environmentParam, definitionParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
+import { guid, entityRef, resolveEntityId, withResolved, projectParam, environmentParam, definitionParam, pagingParams, readOnly, writes, updates, destructive, microOps } from './common.js';
+import { RefResolver, isGuid } from '../platform/refs.js';
 import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/policy.js';
 import { splitJunctionFields, withNormalization } from '../knowledge/normalize.js';
-import { entityOutline, resolvePart } from '../knowledge/outlines.js';
+import { unmappedMembers, introducedUnmappedMembers, withUnmappedMembers } from '../knowledge/schemaGuard.js';
+import { entityOutline, resolvePart, resolvePatchOperations, patchedSections } from '../knowledge/outlines.js';
+import { patchResult, baseVersionOf } from '../platform/patch.js';
 import { isJunctionField, policyRules } from '../knowledge/rules.js';
 import { handle } from '../platform/responses.js';
 import fastJsonPatch from 'fast-json-patch';
@@ -20,6 +23,52 @@ function preserveApplicationBinding(definition) {
     if (applicationIds.length > 0)
         definition.applicationIds = applicationIds;
 }
+/**
+ * `UpdateEntityCommandHandler` gövdedeki `Indexes` null ise onu BOŞ LİSTEYE çeviriyor
+ * (`request.Indexes?…ToList() ?? []`) ve `Entity.FindProcessedIndexes` boş listede entity'nin
+ * bütün index'lerini silinecek kümeye koyuyor: kayıt düşer, `DROP INDEX` koşar, hata dönmez.
+ * Domain katmanı null'ı özellikle koruyor, komut katmanı bu korumayı geçersiz kılıyor.
+ *
+ * Gateway alan verilmemişse mevcut index'leri gövdeye taşır. Bilinçli silme yolu kapanmaz:
+ * `indexes: []` AÇIKÇA yazılmışsa buraya hiç girilmez.
+ */
+async function carryIndexes(platform, resolver, project, environment, datasourceId, id, body) {
+    const entity = datasourceId && isGuid(id) ? { entityId: id, datasourceId } : await resolver.entity(id);
+    const current = await platform.tenant('GET', project, `/entities/${entity.datasourceId}/${entity.entityId}`, { environment });
+    const definition = (current?.data ?? current);
+    const indexes = Array.isArray(definition?.indexes) ? definition.indexes : [];
+    if (indexes.length === 0)
+        return [];
+    body.indexes = indexes;
+    return [`Gövdede 'indexes' yoktu: platform bu durumda entity'nin BÜTÜN index'lerini siler, bu yüzden mevcut ${indexes.length} index gövdeye taşındı. Silmek istiyorsanız 'indexes: []' yazarak açıkça isteyin.`];
+}
+/**
+ * `Entity.FindProcessedIndexes` farkı YALNIZ `id` üzerinden alıyor: aynı `id` ile gelen index ne
+ * eklenenler ne silinenler kümesinde olduğu için `EntityService.UpdateAsync` ona hiç dokunmuyor.
+ * Ad, unique bayrağı ya da alan listesi değişse bile ne kayıt ne DDL güncellenir; istek 200 döner
+ * ve yama uygulanmış görünür. Politika kuralı olamaz — kural yalnız yamalanmış gövdeyi görür,
+ * bu karşılaştırma ÖNCEKİ hâli de ister.
+ */
+function inPlaceIndexEdits(before, after) {
+    const asIndexes = (value) => {
+        const source = (value && typeof value === 'object' ? value : {});
+        return Array.isArray(source.indexes)
+            ? source.indexes.filter((index) => Boolean(index) && typeof index === 'object')
+            : [];
+    };
+    const shape = (index) => JSON.stringify([index.name ?? null, index.unique ?? false, Array.isArray(index.fieldIds) ? index.fieldIds : []]);
+    const original = new Map(asIndexes(before)
+        .filter(index => typeof index.id === 'string')
+        .map(index => [index.id, shape(index)]));
+    return asIndexes(after)
+        .filter(index => typeof index.id === 'string' && original.has(index.id) && original.get(index.id) !== shape(index))
+        .map(index => ({
+        ruleId: 'ENT-014',
+        severity: 'warn',
+        message: `'${index.id}' id'li index'in tanımı değişti ama platform var olan bir index'i YERİNDE GÜNCELLEMEZ: farkı yalnız 'id' üzerinden alır, aynı id'yi taşıyan kaydı ne siler ne yeniden kurar. İstek 200 dönse de veritabanında hiçbir şey değişmez. Index'i kaldırıp yeni bir id ile yeniden ekleyin.`,
+        guide: 'ngapps://guides/entity'
+    }));
+}
 export function registerEntityTools(server, platform) {
     const config = platform.config;
     server.registerTool('entity_list', {
@@ -38,39 +87,42 @@ export function registerEntityTools(server, platform) {
     }, handle(config, ({ project, environment, datasourceId, ...query }) => platform.tenant('GET', project, `/entities/${datasourceId}`, { environment, query })));
     server.registerTool('entity_get', {
         title: 'Entity getir',
-        description: "Entity'yi alan tanımlarıyla getirir. Çok alanlı entity'de önce view:'outline' (alan listesi), sonra view:'part' ile tek alan çekin.",
+        description: "Entity'yi alan tanımlarıyla getirir. Çok alanlı entity'de önce view:'outline' (alan listesi), sonra view:'part' ile tek alan çekin. Çok dilli entity'de kök alanlar companion bağını taşır: parent'ta `localizationEntityId`, companion'da `localizationParentId` — companion'ı ad kalıbından TAHMİN ETMEYİN, bu bağdan bulun.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            datasourceId: guid,
-            id: guid,
+            datasourceId: guid.optional().describe('Verilmezse gateway datasource ağacından bulur'),
+            id: entityRef,
             view: z.enum(['full', 'outline', 'part']).optional().describe('varsayılan full'),
             part: z.string().optional().describe("view:'part' için yol, ör. fields[slug=email] veya indexes[0]")
         },
         annotations: readOnly
     }, handle(config, async ({ project, environment, datasourceId, id, view, part }) => {
-        const payload = await platform.tenant('GET', project, `/entities/${datasourceId}/${id}`, { environment });
+        const resolver = new RefResolver(platform, project, environment);
+        const entity = datasourceId && isGuid(id) ? { entityId: id, datasourceId } : await resolver.entity(id);
+        const payload = await platform.tenant('GET', project, `/entities/${entity.datasourceId}/${entity.entityId}`, { environment });
         const definition = (payload?.data ?? payload);
         if (view === 'outline')
-            return entityOutline(definition);
+            return withResolved(entityOutline(definition), resolver.resolved);
         if (view === 'part') {
             if (!part)
                 throw new Error("view:'part' için 'part' parametresi zorunlu.");
-            return { part, value: resolvePart(definition, part) };
+            return withResolved({ part, value: resolvePart(definition, part) }, resolver.resolved);
         }
-        return payload;
+        return withResolved(payload, resolver.resolved);
     }));
     server.registerTool('entity_create', {
         title: 'Entity oluştur',
-        description: "Datasource altında yeni entity oluşturur (definition = CreateEntityCommand: name, fields[], applicationIds, ...). İlişkiler ve alan tipi kararı için platform_guide('entity') okuyun. Gövde politika kontrolünden geçer. applicationIds create'te platformca bağlanır (CreateEntityCommandHandler entityApplications'ı Entity ctor'una geçirir); satır uçları bu bağa İHTİYAÇ DUYMAZ — bağ yalnız Studio'nun application'a göre entity listesini ve bağımlılık sorgularını etkiler.",
+        description: "Datasource altında yeni entity oluşturur (definition = CreateEntityCommand: name, fields[], applicationIds, ...). İlişkiler ve alan tipi kararı için platform_guide('entity') okuyun. Gövde politika kontrolünden geçer. applicationIds create'te platformca bağlanır (CreateEntityCommandHandler entityApplications'ı Entity ctor'una geçirir); satır uçları bu bağa İHTİYAÇ DUYMAZ — bağ yalnız Studio'nun application'a göre entity listesini ve bağımlılık sorgularını etkiler. `fields[].isLocalized: true` alanı ana tablodan çıkarıp companion `<slug>_localization` entity'sine taşır (yalnız düz METİN alanı; anahtar/unique/ilişki olamaz) — platform_guide('entity') §'Çoklu dilli alan'.",
         inputSchema: { project: projectParam, environment: environmentParam, datasourceId: guid, definition: definitionParam, policyOverride: policyOverrideParam },
         annotations: writes
     }, handle(config, async ({ project, environment, datasourceId, definition, policyOverride }) => {
         const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'entity', definition, { operation: 'create' }, policyOverride));
         const { base, deferred } = splitJunctionFields(definition, isJunctionField);
+        const drift = unmappedMembers('CreateEntityCommand', base);
         const payload = await platform.tenant('POST', project, `/entities/${datasourceId}`, { environment, body: base });
         if (deferred.length === 0)
-            return attachFindings(payload, findings);
+            return attachFindings(withUnmappedMembers(payload, drift), findings);
         const created = (payload?.data ?? payload);
         const createdId = String(created?.id ?? '');
         if (!createdId) {
@@ -82,7 +134,7 @@ export function registerEntityTools(server, platform) {
         preserveApplicationBinding(full);
         const updated = await platform.tenant('PUT', project, `/entities/${createdId}`, { environment, body: full });
         const note = `m2m/çoklu alanlar (${deferred.map(field => field.slug ?? field.name).join(', ')}) ayrı bir güncelleme turunda eklendi: create yolu junction kaydını açar ama fiziksel tabloyu kurmaz (platform bug'ı P-01), update yolu kurar.`;
-        return attachFindings(withNormalization(updated, [note]), findings);
+        return attachFindings(withUnmappedMembers(withNormalization(updated, [note]), drift), findings);
     }));
     server.registerTool('entity_create_discovered', {
         title: 'Keşfedilen entity\'leri içe al',
@@ -92,34 +144,67 @@ export function registerEntityTools(server, platform) {
     }, handle(config, ({ project, environment, datasourceId, definition }) => platform.tenant('POST', project, `/entities/${datasourceId}/discovered`, { environment, body: definition })));
     server.registerTool('entity_update', {
         title: 'Entity güncelle',
-        description: 'Entity tanımını günceller (tam gövde). Hedefli değişiklik için entity_patch tercih edin. Gövde politika kontrolünden geçer.',
-        inputSchema: { project: projectParam, environment: environmentParam, id: guid, definition: definitionParam, policyOverride: policyOverrideParam },
+        description: "Entity tanımını günceller (tam gövde). Hedefli değişiklik için entity_patch tercih edin. Gövde politika kontrolünden geçer. DİKKAT: gövdede 'indexes' YOKSA platform entity'nin bütün index'lerini siler — gateway alan verilmemişse mevcut index'leri taşır ve bunu bildirir; silmek için 'indexes: []' yazın. `fields[].isLocalized: true` alanı ana tablodan çıkarıp companion `<slug>_localization` entity'sine taşır (yalnız düz METİN alanı; anahtar/unique/ilişki olamaz) — platform_guide('entity') §'Çoklu dilli alan'.",
+        inputSchema: { project: projectParam, environment: environmentParam, datasourceId: guid.optional().describe('Verilmezse gateway datasource ağacından bulur'), id: entityRef, definition: definitionParam, policyOverride: policyOverrideParam },
         annotations: updates
-    }, handle(config, async ({ project, environment, id, definition, policyOverride }) => {
+    }, handle(config, async ({ project, environment, datasourceId, id, definition, policyOverride }) => {
         const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'entity', definition, { operation: 'update' }, policyOverride));
-        const payload = await platform.tenant('PUT', project, `/entities/${id}`, { environment, body: definition });
-        return attachFindings(payload, findings);
+        const resolver = new RefResolver(platform, project, environment);
+        const body = { ...definition };
+        const notes = Object.hasOwn(body, 'indexes') ? [] : await carryIndexes(platform, resolver, project, environment, datasourceId, id, body);
+        const entityId = await resolveEntityId(resolver, id);
+        const drift = unmappedMembers('UpdateEntityCommand', definition);
+        const payload = await platform.tenant('PUT', project, `/entities/${entityId}`, { environment, body });
+        return attachFindings(withUnmappedMembers(withResolved(withNormalization(payload, notes), resolver.resolved), drift), findings);
     }));
     server.registerTool('entity_patch', {
         title: 'Entity\'ye patch uygula',
-        description: "Tam gövdeyi bağlama almadan hedefli değişiklik: gateway mevcut tanımı çeker, JSON Patch uygular, politika kontrolünden geçirir, geri yazar. Yanıt outline özetidir. GET 'applications' döner ama UpdateEntityCommand 'applicationIds' okur; gateway bu çeviriyi kendisi yapar, yoksa her patch application bağını sessizce siler.",
-        inputSchema: { project: projectParam, environment: environmentParam, datasourceId: guid, id: guid, operations: patchOperationsParam, policyOverride: policyOverrideParam },
+        description: "Tam gövdeyi bağlama almadan hedefli değişiklik: gateway mevcut tanımı okur, yolları çözer ve op'ları platformun PATCH /entities/{id} ucuna `{ baseVersion, ops }` olarak geçirir — tam gövde PUT'u ATILMAZ, yalnız fark yazılır. Yanıt outline özetidir. YOLLARDA SEÇİCİ KULLANIN, indeks değil: '/fields[slug=email]/nullable' — indeksle yazmak alan sırası değişince SESSİZCE yanlış alanı yazar. Gateway seçiciyi indekse çevirir ve hangi kayda indiğini yanıttaki patchTargets ile söyler. `baseVersion` okunan kaydın `version` alanından gelir; kayıt bu arada değiştiyse platform 409 döner ve HİÇBİR op uygulanmaz. 'applications' → 'applicationIds' çevirisini artık platform yapar. `fields[].isLocalized: true` alanı ana tablodan çıkarıp companion `<slug>_localization` entity'sine taşır (yalnız düz METİN alanı; anahtar/unique/ilişki olamaz) — platform_guide('entity') §'Çoklu dilli alan'.",
+        inputSchema: { project: projectParam, environment: environmentParam, datasourceId: guid.optional().describe('Verilmezse gateway datasource ağacından bulur'), id: entityRef, operations: patchOperationsParam.optional(), ops: patchOperationsParam.optional().describe("'operations' ile aynı alan (eşanlamlı) — sayfa micro-op tool'larıyla aynı adı kullanabilmeniz için"), policyOverride: policyOverrideParam },
         annotations: updates
-    }, handle(config, async ({ project, environment, datasourceId, id, operations, policyOverride }) => {
-        const current = await platform.tenant('GET', project, `/entities/${datasourceId}/${id}`, { environment });
+    }, handle(config, async ({ project, environment, datasourceId, id, operations: givenOperations, ops, policyOverride }) => {
+        const operations = microOps('entity_patch', ops, givenOperations);
+        const resolver = new RefResolver(platform, project, environment);
+        const entity = datasourceId && isGuid(id) ? { entityId: id, datasourceId } : await resolver.entity(id);
+        const current = await platform.tenant('GET', project, `/entities/${entity.datasourceId}/${entity.entityId}`, { environment });
         const definition = structuredClone((current?.data ?? current));
-        const patched = fastJsonPatch.applyPatch(definition, operations, true, false).newDocument;
-        preserveApplicationBinding(patched);
-        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'entity', patched, { operation: 'update' }, policyOverride));
-        await platform.tenant('PUT', project, `/entities/${id}`, { environment, body: patched });
-        return attachFindings({ applied: operations.length, outline: entityOutline(patched) }, findings);
+        const resolvedOps = resolvePatchOperations(definition, operations, 'entity_get');
+        // Politika, yazmadan önce sonucu görmeli; yerel kopya YALNIZ değerlendirme için, gövde olarak gönderilmez.
+        const preview = fastJsonPatch.applyPatch(definition, resolvedOps.operations, true, false).newDocument;
+        const findings = [
+            ...enforcePolicy(evaluatePolicy(config, policyRules, 'entity', preview, { operation: 'update' }, policyOverride)),
+            ...inPlaceIndexEdits(current?.data ?? current, preview)
+        ];
+        // Yalnız YAMANIN eklediği anahtar bildirilir: gövdenin geri kalanını gateway GET'ten taşıdı
+        // ve orada komutta olmayan yedi yapısal alan var (ölçüldü — g-03 Adım 0). Onları bildirmek
+        // kanalı gürültüye boğar ve gerçek sinyali gömer.
+        const drift = introducedUnmappedMembers('UpdateEntityCommand', (current?.data ?? current), preview);
+        const saved = await platform.tenant('PATCH', project, `/entities/${entity.entityId}`, {
+            environment,
+            body: { baseVersion: baseVersionOf(definition, 'entity_get'), ops: resolvedOps.operations }
+        });
+        const written = patchResult(saved, preview);
+        const touched = patchedSections(written.data, resolvedOps.operations);
+        return attachFindings(withUnmappedMembers(withResolved({
+            applied: operations.length,
+            newVersion: written.newVersion,
+            patchTargets: resolvedOps.targets,
+            ...(resolvedOps.notes.length > 0 ? { resolvedPaths: resolvedOps.notes } : {}),
+            // S-8: yazılanın kanıtı yanıtta dursun; dokunulmayan bölümler outline'da kalır.
+            ...(Object.keys(touched).length > 0 ? { touched } : {}),
+            outline: entityOutline(written.data)
+        }, resolver.resolved), drift), findings);
     }));
     server.registerTool('entity_delete', {
         title: 'Entity sil',
         description: 'Entity tanımını siler; önce entity_dependencies ile bağımlılıklarını kontrol edin.',
-        inputSchema: { project: projectParam, environment: environmentParam, id: guid },
+        inputSchema: { project: projectParam, environment: environmentParam, id: entityRef },
         annotations: destructive
-    }, handle(config, ({ project, environment, id }) => platform.tenant('DELETE', project, `/entities/${id}`, { environment })));
+    }, handle(config, async ({ project, environment, id }) => {
+        const resolver = new RefResolver(platform, project, environment);
+        const entityId = await resolveEntityId(resolver, id);
+        return withResolved(await platform.tenant('DELETE', project, `/entities/${entityId}`, { environment }), resolver.resolved);
+    }));
     server.registerTool('entity_clone', {
         title: 'Entity klonla',
         description: 'Entity\'nin kopyasını oluşturur.',

package/dist/tools/environments.js

@@ -0,0 +1,52 @@
+import { branchNamePattern, destructive, guid, isReservedEnvironmentName, readOnly, writes } from './common.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { handle } from '../platform/responses.js';
+import { z } from 'zod';
+/** Aggregate kuralının aynası (`Environment` ctor); gerçek koruma backend'dedir. Kural `common.ts`'te. */
+const branchName = z.string().regex(branchNamePattern)
+    .describe("Dal adı: küçük harfle başlar, yalnız küçük harf/rakam/alt çizgi, 3-31 karakter. Bu ad PG şema adı olur.");
+function assertBranchName(name) {
+    if (isReservedEnvironmentName(name)) {
+        throw new PlatformApiError(`environment_create: '${name}' rezerve bir şema adı — dal adı olarak kullanılamaz. Başka bir ad seçin.`, 400);
+    }
+}
+export function registerEnvironmentTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('environment_list', {
+        title: 'Environment listesi',
+        description: "Projenin aktif environment'larını döner: önce sabitler (development, production), sonra dallar. Her satırda 'state' vardır (creating | ready | merging | deleting | merged | error); yalnız 'ready' bir dalda çalışılabilir. Dalda çalışmak için tenant tool'larına environment: '<dal adı>' geçin.",
+        inputSchema: { projectId: guid },
+        annotations: readOnly
+    }, handle(config, ({ projectId }) => platform.org('GET', `/environments/${projectId}`)));
+    server.registerTool('environment_create', {
+        title: 'Dal environment\'ı aç',
+        description: "Projede yeni bir dal environment'ı açar: kendi PG şeması kurulur ve development'ın tanımları oraya kopyalanır. Asenkron bir saga'dır — yanıt 202 döner, dal hemen kullanılabilir DEĞİLDİR. includeRecords true ise projenin KENDİ veritabanındaki bütün veri tablolarının satırları da kopyalanır (çok dilli companion tablolar ve junction'lar dahil; files/folders ve audit trail tabloları hariç, dış datasource'lara dokunulmaz) — entity'de kayıt taşıması ayarı açık olmasa bile. Satırlar merge'de geri taşınmaz.",
+        inputSchema: { projectId: guid, name: branchName, includeRecords: z.boolean().optional().describe('Projenin kendi veritabanındaki bütün tabloların satırları da kopyalansın mı (varsayılan false)') },
+        annotations: writes
+    }, handle(config, async ({ projectId, name, includeRecords }) => {
+        assertBranchName(name);
+        const payload = await platform.org('POST', `/environments/${projectId}`, { body: { name, includeRecords: includeRecords === true } });
+        return {
+            ...(payload && typeof payload === 'object' ? payload : { data: payload }),
+            note: "dal asenkron açılıyor; environment_list ile state=ready bekleyin"
+        };
+    }));
+    server.registerTool('environment_delete', {
+        title: 'Dal environment\'ını sil',
+        description: "Bir dal environment'ını ve PG şemasını siler. Sabit environment'lar (development, production) silinemez — gateway bunu HTTP'den önce reddeder. Yalnız 'ready' ya da 'error' durumundaki dal silinebilir; silme asenkrondur.",
+        inputSchema: { projectId: guid, environmentId: guid },
+        annotations: destructive
+    }, handle(config, async ({ projectId, environmentId }) => {
+        const environments = await platform.org('GET', `/environments/${projectId}`);
+        const rows = environments?.data ?? [];
+        const target = rows.find(row => row.id === environmentId);
+        if (target && target.isBranch !== true) {
+            throw new PlatformApiError(`environment_delete: '${String(target.name)}' sabit bir environment — silinemez. Yalnız dallar silinir (environment_list çıktısında isBranch: true olanlar).`, 400);
+        }
+        const payload = await platform.org('DELETE', `/environments/${projectId}/${environmentId}`);
+        return {
+            ...(payload && typeof payload === 'object' ? payload : { data: payload }),
+            note: "şema asenkron düşürülüyor; environment_list ile dalın listeden çıkmasını bekleyin"
+        };
+    }));
+}

package/dist/tools/externalComponents.js

@@ -4,8 +4,11 @@ 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;
+import { evaluatePolicy, enforcePolicy } from '../knowledge/policy.js';
+import { policyRules } from '../knowledge/rules.js';
+import { EXTERNAL_COMPONENT_PROTOCOL_VERSION } from '../knowledge/backendConstraints.js';
+/** Platformun köprü protokolü; scaffold ve publish bu sürüme göre üretir/doğrular (backend ExternalComponentRules.CurrentProtocolVersion) */
+const PROTOCOL_VERSION = EXTERNAL_COMPONENT_PROTOCOL_VERSION;
 /** Backend `ExternalComponentRules.MaxBundleSizeBytes` ile aynı sınır */
 const maxBundleBytes = 2 * 1024 * 1024;
 const slugPattern = /^x-[a-z][a-z0-9-]*$/;
@@ -185,7 +188,7 @@ export function registerExternalComponentTools(server, platform) {
     }));
     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.",
+        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. Backend ön kontrolü (EXT-001, block): protocolVersion 1, definition.blocks dolu, props[].name ayrılmış DOM adı ya da zx/on önekli olamaz, props[].type sözlükten (ngapps://rules/backend-constraints).",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
@@ -219,6 +222,9 @@ export function registerExternalComponentTools(server, platform) {
         if (bytes.byteLength > maxBundleBytes) {
             throw new PlatformApiError(`external_component_publish: paket ${maxBundleBytes} bayt sınırını aşıyor (${bytes.byteLength} B).`);
         }
+        // EXT-001: protocolVersion, definition.blocks, ayrılmış prop adları ve prop tipleri — kayıt
+        // ucu 422 dönmeden manifest'te yakalanır; paket yükleme ikinci istek olduğu için yarım kayıt kalmaz.
+        enforcePolicy(evaluatePolicy(config, policyRules, 'externalComponent', { ...manifest, slug }, { operation: 'create' }));
         const record = await platform.tenant('POST', project, `/components/${applicationId}/external`, {
             environment,
             body: {

package/dist/tools/files.js

@@ -4,9 +4,12 @@ import { handle } from '../platform/responses.js';
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
 import { z } from 'zod';
+import { FORBIDDEN_NAME_CHARACTERS } from '../knowledge/backendConstraints.js';
 const maxInlineBytes = 8 * 1024 * 1024;
 const maxUploadBytes = 50 * 1024 * 1024;
-const forbiddenNameChars = `\\|!#~$%&/=?»«@£§€{};'<>,`;
+/** Metin içerik bağlamdan geçtiği için base64'ün 8 MB sınırından çok daha dar tutulur (G-26). */
+const maxTextBytes = 1024 * 1024;
+const forbiddenNameChars = FORBIDDEN_NAME_CHARACTERS;
 const mimeTypes = {
     '.css': 'text/css',
     '.csv': 'text/csv',
@@ -35,6 +38,56 @@ const mimeTypes = {
     '.xml': 'application/xml',
     '.zip': 'application/zip'
 };
+export async function uploadFile(platform, { project, environment, path, content, text, filename, contentType, folderId }) {
+    const given = [path, content, text].filter(value => value !== undefined);
+    if (given.length !== 1) {
+        throw new PlatformApiError("file_upload: `path`, `content` ya da `text` parametrelerinden tam olarak biri verilmeli — `path` gateway'in okuyabildiği yerel dosya, `content` base64 içerik, `text` düz metin (ikisi de `filename` ile).");
+    }
+    let bytes;
+    let name;
+    if (path) {
+        const absolute = resolve(path);
+        try {
+            bytes = await readFile(absolute);
+        }
+        catch (error) {
+            throw new PlatformApiError(`file_upload: dosya okunamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+        }
+        name = filename ?? basename(absolute);
+    }
+    else if (text !== undefined) {
+        if (!filename)
+            throw new PlatformApiError('file_upload: `text` verildiğinde `filename` zorunludur.');
+        bytes = Buffer.from(text, 'utf8');
+        if (bytes.byteLength > maxTextBytes) {
+            throw new PlatformApiError(`file_upload: \`text\` içeriği ${maxTextBytes} bayt sınırını aşıyor (${bytes.byteLength} B). Büyük dosyalar için \`path\` ya da \`content\` kullanın.`);
+        }
+        name = filename;
+    }
+    else {
+        if (!filename)
+            throw new PlatformApiError('file_upload: `content` verildiğinde `filename` zorunludur.');
+        bytes = Buffer.from(content, 'base64');
+        if (bytes.byteLength === 0)
+            throw new PlatformApiError('file_upload: `content` geçerli base64 değil ya da boş.');
+        if (bytes.byteLength > maxInlineBytes) {
+            throw new PlatformApiError(`file_upload: base64 içerik ${maxInlineBytes} bayt sınırını aşıyor (${bytes.byteLength} B). Büyük dosyalar için \`path\` kullanın.`);
+        }
+        name = filename;
+    }
+    if (bytes.byteLength > maxUploadBytes) {
+        throw new PlatformApiError(`file_upload: dosya ${maxUploadBytes} bayt platform sınırını aşıyor (${bytes.byteLength} B).`);
+    }
+    const offendingChar = [...forbiddenNameChars].find(character => name.includes(character));
+    if (offendingChar) {
+        throw new PlatformApiError(`file_upload: dosya adı '${offendingChar}' karakterini içeriyor; platform doğrulaması bunu 422 ile reddeder (FILE-001, UploadFileCommandValidator). Yasak karakterler: ${forbiddenNameChars}`);
+    }
+    const resolvedType = contentType ?? mimeTypes[extname(name).toLowerCase()] ?? 'application/octet-stream';
+    const multipart = folderId
+        ? [{ name: 'FolderId', value: folderId }, { name: 'File', filename: name, contentType: resolvedType, content: bytes }]
+        : [{ name: 'File', filename: name, contentType: resolvedType, content: bytes }];
+    return platform.tenant('POST', project, '/files/upload', { environment, multipart });
+}
 export function registerFileTools(server, platform) {
     const config = platform.config;
     server.registerTool('file_list', {
@@ -51,57 +104,19 @@ export function registerFileTools(server, platform) {
     }, handle(config, ({ project, environment, id }) => platform.tenant('GET', project, `/files/${id}`, { environment })));
     server.registerTool('file_upload', {
         title: 'Dosya yükle',
-        description: "Dosyayı projenin depolamasına yükler ve FileDto (id + serve adresleri) döner. İçerik iki yoldan verilir: `path` — gateway sürecinin okuyabildiği yerel yol (büyük dosyalar için tercih edilir, içerik model bağlamına girmez), ya da `content` — base64 (8 MB'a kadar) + `filename`. Platform sınırı 50 MB; dosya adı \\|!#~$%&/=?»«@£§€{};'<>, karakterlerini içeremez. Yüklenen dosya sayfada `image`/`file-viewer` komponentiyle gösterilir ya da satır alanına yol olarak yazılır.",
+        description: "Dosyayı projenin depolamasına yükler ve FileDto (id + serve adresleri) döner. İçerik ÜÇ yoldan verilir: `text` — düz metin içerik (SVG, CSV, Markdown, JSON…) + `filename`; base64'e çevirmeye gerek yok, bunu gateway yapar. `path` — gateway sürecinin okuyabildiği yerel yol (büyük ve ikili dosyalar için). `content` — base64 (8 MB'a kadar) + `filename`. Platform sınırı 50 MB; dosya adı \\|!#~$%&/=?»«@£§€{};'<>, karakterlerini içeremez. Yüklenen dosya sayfada `image`/`file-viewer` komponentiyle gösterilir ya da satır alanına yol olarak yazılır.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
             path: z.string().min(1).optional().describe("Gateway sürecinin okuyabildiği yerel dosya yolu; `content` ile birlikte verilmez"),
             content: z.string().min(1).optional().describe('Base64 kodlanmış dosya içeriği; `filename` ile birlikte zorunludur'),
+            text: z.string().min(1).optional().describe("Düz metin içerik (UTF-8): SVG, CSV, Markdown, JSON, düz metin. `filename` ile birlikte zorunludur ve base64'e çevirmeye gerek yoktur — yalnız MCP araçlarıyla çalışan bir ajanın elinde base64 kodlayıcı yok, bu alan o boşluğu kapatır (G-26). İkili dosyalar için `path` ya da `content` kullanın."),
             filename: z.string().min(1).optional().describe("`content` ile zorunlu; `path` verildiğinde dosya adını ezer"),
             contentType: z.string().min(1).optional().describe('Belirtilmezse uzantıdan çözülür, bilinmeyen uzantıda application/octet-stream'),
             folderId: guid.optional().describe('Hedef klasör (folder_list); boşsa kök')
         },
         annotations: writes
-    }, handle(config, async ({ project, environment, path, content, filename, contentType, folderId }) => {
-        if (!path === !content) {
-            throw new PlatformApiError("file_upload: `path` ya da `content` parametrelerinden tam olarak biri verilmeli — `path` gateway'in okuyabildiği yerel dosya, `content` base64 içerik (`filename` ile).");
-        }
-        let bytes;
-        let name;
-        if (path) {
-            const absolute = resolve(path);
-            try {
-                bytes = await readFile(absolute);
-            }
-            catch (error) {
-                throw new PlatformApiError(`file_upload: dosya okunamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
-            }
-            name = filename ?? basename(absolute);
-        }
-        else {
-            if (!filename)
-                throw new PlatformApiError('file_upload: `content` verildiğinde `filename` zorunludur.');
-            bytes = Buffer.from(content, 'base64');
-            if (bytes.byteLength === 0)
-                throw new PlatformApiError('file_upload: `content` geçerli base64 değil ya da boş.');
-            if (bytes.byteLength > maxInlineBytes) {
-                throw new PlatformApiError(`file_upload: base64 içerik ${maxInlineBytes} bayt sınırını aşıyor (${bytes.byteLength} B). Büyük dosyalar için \`path\` kullanın.`);
-            }
-            name = filename;
-        }
-        if (bytes.byteLength > maxUploadBytes) {
-            throw new PlatformApiError(`file_upload: dosya ${maxUploadBytes} bayt platform sınırını aşıyor (${bytes.byteLength} B).`);
-        }
-        const offendingChar = [...forbiddenNameChars].find(character => name.includes(character));
-        if (offendingChar) {
-            throw new PlatformApiError(`file_upload: dosya adı '${offendingChar}' karakterini içeriyor; platform doğrulaması bunu reddeder. Yasak karakterler: ${forbiddenNameChars}`);
-        }
-        const resolvedType = contentType ?? mimeTypes[extname(name).toLowerCase()] ?? 'application/octet-stream';
-        const multipart = folderId
-            ? [{ name: 'FolderId', value: folderId }, { name: 'File', filename: name, contentType: resolvedType, content: bytes }]
-            : [{ name: 'File', filename: name, contentType: resolvedType, content: bytes }];
-        return platform.tenant('POST', project, '/files/upload', { environment, multipart });
-    }));
+    }, handle(config, (input) => uploadFile(platform, input)));
     server.registerTool('file_download', {
         title: 'Dosya indir',
         description: "Dosyanın içeriğini indirir ve `outPath` ile verilen yerel yola yazar; dönen gövde yalnız özet (yol, boyut, tip) — ikili içerik model bağlamına girmez. Yol gateway sürecinin çalıştığı makineye göre çözülür.",