@appaflytech/zeyrek-ai-mcp 0.0.4 → 0.0.6

package/dist/knowledge/guideSections.js

@@ -0,0 +1,49 @@
+const turkishMap = { ç: 'c', ğ: 'g', ı: 'i', ö: 'o', ş: 's', ü: 'u', â: 'a', î: 'i', û: 'u' };
+export function sectionSlug(title) {
+    return title.toLocaleLowerCase('tr')
+        .replace(/[çğıöşüâîû]/g, letter => turkishMap[letter] ?? letter)
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Rehberler `## ` başlıklarıyla bölümlü; `page.md` 120 KB'ı aşınca tool çıktı sınırına takıldı ve
+ * MCP kanalından hiç okunamadı (09-04 koşusu). Bölümleme var olan başlıkları kullanır, dosyaların
+ * içeriğine dokunmaz.
+ *
+ * Satır sonu ÖNEMLİ: başlık ifadesindeki `.` satır sonu karakterlerini eşlemez ve `$` çok satırlı
+ * değildir, yani `\r` ile biten bir satırda hiçbir başlık görünmez. Windows çalışma ağacında
+ * (`.gitattributes` yokken) rehberlerin tamamı CRLF olduğu için bölümleyici tek "giriş" bölümü
+ * üretiyor, `platform_guide` de oversize dalında rehberin TAMAMINI döndürüp tool sınırını
+ * aşıyordu — ölçüldü 2026-09-05, `page.md` 22 başlık → 1 bölüm. Girdi bu yüzden bölünmeden önce
+ * satır sonlarından arındırılır.
+ */
+export function splitGuideSections(markdown) {
+    const sections = [];
+    const used = new Map();
+    let fence = '';
+    let title = '';
+    let lines = [];
+    const push = () => {
+        if (title === '' && lines.join('\n').trim() === '')
+            return;
+        const base = title === '' ? 'giris' : sectionSlug(title);
+        const seen = (used.get(base) ?? 0) + 1;
+        used.set(base, seen);
+        sections.push({ slug: seen === 1 ? base : `${base}-${seen}`, title: title === '' ? 'Giriş' : title, body: lines.join('\n').trim() });
+    };
+    for (const line of markdown.split(/\r\n|\r|\n/)) {
+        const marker = /^\s*(`{3,})/.exec(line)?.[1] ?? '';
+        if (marker.length > 0)
+            fence = fence === '' ? marker : (marker.length >= fence.length ? '' : fence);
+        const heading = fence === '' ? /^## (?!#)(.+)$/.exec(line)?.[1] : undefined;
+        if (heading === undefined) {
+            lines.push(line);
+            continue;
+        }
+        push();
+        title = heading.trim();
+        lines = [];
+    }
+    push();
+    return sections;
+}

package/dist/knowledge/hydrate.js

@@ -0,0 +1,97 @@
+import { RefResolveError, isGuid } from '../platform/refs.js';
+const fieldCarriers = ['fields', 'selectFields', 'returnFields'];
+function entries(value) {
+    return Array.isArray(value) ? value.filter((entry) => Boolean(entry) && typeof entry === 'object') : [];
+}
+function collectJoinAliases(joins, into) {
+    for (const join of entries(joins)) {
+        const alias = String(join.alias ?? '').trim();
+        if (alias)
+            into.add(alias);
+        collectJoinAliases(join.joins, into);
+    }
+    return into;
+}
+function pendingEntries(parameters) {
+    const pending = [];
+    const walk = (list) => {
+        for (const entry of entries(list)) {
+            if (typeof entry.fieldSlug === 'string' && typeof entry.fieldId !== 'string')
+                pending.push(entry);
+            walk(entry.children);
+        }
+    };
+    for (const key of fieldCarriers)
+        walk(parameters[key]);
+    walk(parameters.filters);
+    return pending;
+}
+/**
+ * Hydration normalize'dan ÖNCE koşmak zorundadır: `normalizeTableParameters` join ve seçim
+ * yollarını `fieldId`'ye göre üretir (`normalize.ts` `fillJoinPaths`), boş `fieldId` gören
+ * normalize yolu hiç doldurmaz.
+ *
+ * GUID'li ve `fieldSlug` taşımayan tanımlar hiç ağ turu ödemez ve ağaç hiç okunmaz — ağaç
+ * uçtaki gizli entity'leri (Files/Folders, EnumValues) TAŞIMAZ, dolayısıyla koşulsuz çözüm
+ * bugüne kadar çalışan GUID'li çağrıları "ağaçta yok" diye düşürürdü.
+ *
+ * Kapsam bilinçli olarak KÖK entity ile sınırlı: `joins[]` girdileri şemada `fieldSlug`
+ * taşımaz (`TableJoin` = alias·entityId·fieldId·joins·path), join'lenen entity'nin alanları
+ * ayrı bir görev.
+ */
+export async function hydrateMicroserviceRefs(definition, resolver) {
+    if (definition.source !== 'table')
+        return [];
+    const rootRef = String(definition.entityId ?? '');
+    if (rootRef === '')
+        return [];
+    const parameters = (definition.sourceParameters ?? {});
+    const nestedRef = String(parameters.entityId ?? '');
+    const pending = pendingEntries(parameters);
+    if (pending.length === 0 && isGuid(rootRef) && (nestedRef === '' || isGuid(nestedRef)))
+        return [];
+    const fixes = [];
+    const root = await resolver.entity(rootRef);
+    if (!isGuid(rootRef)) {
+        definition.entityId = root.entityId;
+        fixes.push(`entityId '${rootRef}' → ${root.entityId}`);
+    }
+    if (nestedRef !== '' && !isGuid(nestedRef)) {
+        parameters.entityId = (await resolver.entity(nestedRef)).entityId;
+        fixes.push(`sourceParameters.entityId '${nestedRef}' → ${String(parameters.entityId)}`);
+    }
+    if (pending.length === 0)
+        return fixes;
+    const fields = await resolver.entityFields(root);
+    const idBySlug = new Map(fields.map(field => [field.slug, field.id]));
+    const joinAliases = collectJoinAliases(parameters.joins, new Set());
+    const declaredAlias = String(parameters.alias ?? '').trim();
+    const rootAlias = declaredAlias === '' ? root.slug : declaredAlias;
+    const fill = (entry, where) => {
+        const slug = typeof entry.fieldSlug === 'string' ? entry.fieldSlug : undefined;
+        const alias = String(entry.alias ?? '').trim();
+        if (slug === undefined || typeof entry.fieldId === 'string')
+            return;
+        // Kök girdi: alias yok, kök alias'ı, ya da hiçbir join'e ait değil — `normalize.fillRootAlias`
+        // kök alias'ı tam da bu çıkarımla buluyor; ikisi ayrışırsa filtre sessizce fieldId'siz gider.
+        if (alias !== '' && alias !== rootAlias && joinAliases.has(alias))
+            return;
+        const id = idBySlug.get(slug);
+        if (id === undefined) {
+            throw new RefResolveError(`'${slug}' diye bir alan '${root.slug}' entity'sinde yok (${where}). Mevcut alanlar: ${[...idBySlug.keys()].join(', ')}`);
+        }
+        entry.fieldId = id;
+        fixes.push(`${where}.fieldSlug '${slug}' → ${id}`);
+    };
+    for (const key of fieldCarriers) {
+        entries(parameters[key]).forEach((entry, index) => fill(entry, `${key}[${index}]`));
+    }
+    const walkFilters = (list, prefix) => {
+        entries(list).forEach((entry, index) => {
+            fill(entry, `${prefix}[${index}]`);
+            walkFilters(entry.children, `${prefix}[${index}].children`);
+        });
+    };
+    walkFilters(parameters.filters, 'filters');
+    return fixes;
+}

package/dist/knowledge/languageCodes.js

@@ -0,0 +1,36 @@
+import { PlatformApiError } from '../platform/errors.js';
+const ISO_639_1 = /^[a-z]{2}$/;
+/**
+ * Platformun tek dil kodu biçimi ISO 639-1 küçük harftir (sözleşme D2). Dışarıdan gelen BCP-47
+ * değer ('tr-TR', 'en_US') birincil alt etikete indirgenir ve bölge saklanmaz — backend de aynısını
+ * yapar (`LanguageContext.RequestedLanguages`). İndirgeme SESSİZ yapılmaz: 'pt-BR' gönderip 'pt'
+ * kaydedildiğini bilmeyen çağıran, bölge ayrımının platformda hiç olmadığını fark etmiyor.
+ */
+export function normalizeLanguageCode(input, field) {
+    const code = (input.trim().split(/[-_]/)[0] ?? '').toLowerCase();
+    if (!ISO_639_1.test(code)) {
+        throw new PlatformApiError(`'${field}' alanındaki '${input}' geçerli bir dil kodu değil. Platform ISO 639-1 küçük harf iki harfli kod tutar ('tr', 'en', 'de'); bölgeli değer ('tr-TR') kabul edilir ve indirgenir ama '${input}' indirgendiğinde de iki harfe inmiyor.`, 400);
+    }
+    return code === input ? { code } : { code, note: `${field}: '${input}' → '${code}' (platform ISO 639-1 küçük harf kod tutar, bölge bilgisi saklanmaz).` };
+}
+export function normalizeLanguageCodes(inputs, field) {
+    const results = inputs.map(input => normalizeLanguageCode(input, field));
+    return {
+        codes: results.map(result => result.code),
+        notes: results.flatMap(result => result.note ? [result.note] : [])
+    };
+}
+export const DATA_LANGUAGE_HEADER = 'X-Data-Language';
+/**
+ * Yürütme araçlarının `language` parametresini backend'in istek dili başlığına çevirir. Başlık
+ * gönderilmezse backend `Accept-Language`'a, o da yoksa projenin varsayılan diline düşer
+ * (sözleşme D3) — yani parametreyi atlamak bir hata değil, "projenin varsayılanı" demektir.
+ */
+export function languageHeader(input, notes) {
+    if (input === undefined)
+        return {};
+    const { code, note } = normalizeLanguageCode(input, 'language');
+    if (note)
+        notes.push(note);
+    return { [DATA_LANGUAGE_HEADER]: code };
+}

package/dist/knowledge/languages.js

@@ -0,0 +1,105 @@
+/**
+ * Projenin dil durumunu `project_get` / `/p/{slug}` yanıtından okur.
+ *
+ * `ProjectDto.Languages` null alanları serileştirmede DÜŞÜYOR: dili kurulmamış projede yanıtta
+ * `languages` diye bir anahtar hiç yok — "boş liste" bile görünmüyor (canlı doğrulama 2026-09-09,
+ * `mcp-benchmark-2026-09-09`). Ajan bu yüzden eksikliği fark edemiyordu; yokluk ile boş dizi
+ * runtime açısından aynı şeydir ve burada aynı şekilde temsil edilir.
+ *
+ * Alan var ama beklenmedik şekildeyse (dizi değilse) `undefined` döner: gateway o durumda
+ * SUSAR, "dil yok" diye uydurmaz.
+ */
+export function readProjectLanguages(payload) {
+    const data = payload?.data;
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const record = data;
+    const raw = record.languages;
+    if (raw !== undefined && raw !== null && !Array.isArray(raw))
+        return undefined;
+    const languages = Array.isArray(raw) ? raw.filter((entry) => typeof entry === 'string') : [];
+    const defaultLanguage = typeof record.defaultLanguage === 'string' && record.defaultLanguage !== ''
+        ? record.defaultLanguage
+        : undefined;
+    return { languages, defaultLanguage };
+}
+/**
+ * Dil verilmeden açılan projeye gateway'in tohumladığı ayar.
+ *
+ * Backend'in create ucu (`CreateOrganizationProjectCommand`) `Languages`/`DefaultLanguage` alanı
+ * TAŞIMAZ: proje ikisi de `null` doğar ve o hâlde yazılan her çeviri runtime'da ham anahtar olarak
+ * çizilir (`S-15`). Tohum bu durumu doğuştan imkânsız kılar.
+ *
+ * TEK DİL: ikinci bir dil tohumlamak `language-selector`'ı her yeni uygulamada iki seçenekle
+ * çizerdi ve ikincisi hep boş olurdu. Çok dilli uygulama kuran çağıran `languages`'ı açıkça verir.
+ *
+ * Backend de aynı tohumu kendi kurucusunda yazıyor (`ProjectConstants.DefaultLanguages`), ama o
+ * değişiklik dağıtılana kadar çalışan platform hâlâ dilsiz proje doğuruyor — gateway bu yüzden
+ * tohumu koşulsuz yazar. İki taraf aynı değeri tuttuğu için fazladan PUT zararsızdır; backend
+ * sürümü kesinleştiğinde bu adım yalnız `languages` açıkça verildiğinde koşacak şekilde daraltılır.
+ */
+export const SEED_LANGUAGES = ['en'];
+export const SEED_DEFAULT_LANGUAGE = 'en';
+/**
+ * Çağıranın verdiğini olduğu gibi kullanır, eksiği tamamlar, hiçbiri yoksa tohumu döndürür.
+ * `defaultLanguage` her zaman `languages` içindedir — PRJ-002 bunu 422 ile zorunlu tutuyor.
+ */
+export function resolveSeedLanguages(languages, defaultLanguage) {
+    if (!languages?.length && defaultLanguage === undefined) {
+        return { languages: SEED_LANGUAGES, defaultLanguage: SEED_DEFAULT_LANGUAGE, seeded: true };
+    }
+    const resolved = languages?.length ? languages : [defaultLanguage];
+    return { languages: resolved, defaultLanguage: defaultLanguage ?? resolved[0], seeded: false };
+}
+/** Runtime'ın çeviri çözümü kayıtlı bir aktif dil ya da varsayılan dil olmadan anahtara düşer. */
+export function runtimeResolvesTranslations(state) {
+    return state.languages.length > 0 && state.defaultLanguage !== undefined;
+}
+const CHAIN = "runtime aktif dil → varsayılan dil → ANAHTARIN KENDİSİ zincirini izler (zeyrek-frontend/packages/ng-apps-screen-builder/src/translation.functions.ts, resolveTranslation); ilk iki halka boşsa ekrana çeviri değil ham anahtar basılır";
+const WHY_SILENT = "Backend dil kodunu yalnız 184 kodluk ISO sözlüğüne göre doğruluyor (TR-001, ProjectConstants.SupportedLanguages), projenin kendi languages listesine göre DEĞİL — yazma bu yüzden 200 dönüyor ve hiçbir katman uyarmıyor.";
+function quoted(codes) {
+    return codes.map(code => `'${code}'`).join(', ');
+}
+/**
+ * TR-002 — çeviri yazmasını projenin dil listesine bağlar.
+ *
+ * Ölçüm: 2026-09-09 1. koşu `S-15`. 15 anahtar × 2 dil yazıldı (200), 15 prop `translation` tipine
+ * bağlandı (200), şema doğru kuruldu — ama proje `languages` taşımadığı için runtime her etiketi
+ * ham anahtar olarak çizdi. Koşunun en pahalı sessiz düşmesiydi: yalnız ekrana bakınca görülüyor,
+ * rubrikte yanlış "tam" puanına mal oldu. Kontrol yazmayı DURDURMAZ (satırlar geçerli ve sonradan
+ * çözülebilir hale gelir), yüksek sesle söyler.
+ */
+export function translationLanguageFindings(state, writtenCodes, projectSlug) {
+    const codes = [...new Set(writtenCodes)].sort();
+    // Proje okunamadıysa ya da çağrı yalnız silme yapıyorsa söylenecek bir şey yok.
+    if (!state || codes.length === 0)
+        return [];
+    const guide = 'ngapps://guides/translation';
+    if (state.languages.length === 0) {
+        return [{
+                ruleId: 'TR-002',
+                severity: 'warn',
+                message: `'${projectSlug}' projesinde 'languages' listesi TANIMLI DEĞİL: bu yazma platformda başarılı olacak ve satırlar veritabanına düşecek ama RUNTIME HİÇBİRİNİ ÇÖZEMEYECEK — ${CHAIN}. Yazılan kod: ${quoted(codes)}. Düzeltme (yazmadan önce ya da hemen sonra): project_update(id, languages: [${quoted(codes)}], defaultLanguage: '${codes[0]}'). ${WHY_SILENT}`,
+                guide
+            }];
+    }
+    const findings = [];
+    const undeclared = codes.filter(code => !state.languages.includes(code));
+    if (undeclared.length > 0) {
+        findings.push({
+            ruleId: 'TR-002',
+            severity: 'warn',
+            message: `${quoted(undeclared)} kodu '${projectSlug}' projesinin languages listesinde yok (tanımlı: ${quoted(state.languages)}): satırlar yazılır ama runtime o dile hiç geçemez, o dil seçiliyken ${CHAIN}. Düzeltme: project_update(id, languages: [${quoted([...state.languages, ...undeclared])}]). ${WHY_SILENT}`,
+            guide
+        });
+    }
+    if (state.defaultLanguage === undefined) {
+        findings.push({
+            ruleId: 'TR-002',
+            severity: 'warn',
+            message: `'${projectSlug}' projesinde languages kurulu (${quoted(state.languages)}) ama 'defaultLanguage' YOK: runtime kayıtlı bir dil seçimi bulamadığında varsayılana düşer, o da boş olduğu için aktif dil hiç seçilmez ve ilk açılışta her etiket ham anahtar olarak çizilir. Düzeltme: project_update(id, defaultLanguage: '${state.languages[0]}').`,
+            guide
+        });
+    }
+    return findings;
+}

package/dist/knowledge/layoutSummary.js

@@ -0,0 +1,10 @@
+export function summarizeLayout(boxes, viewport) {
+    const outside = (box) => box.x + box.width <= 0 || box.y + box.height <= 0 || box.x >= viewport.width || box.y >= viewport.height;
+    return {
+        nodeCount: boxes.length,
+        overflowing: boxes.filter(box => box.overflowX || box.overflowY).map(box => box.elementId),
+        outsideViewport: boxes.filter(box => box.width > 0 && box.height > 0 && outside(box)).map(box => box.elementId),
+        zeroSized: boxes.filter(box => box.width === 0 || box.height === 0).map(box => box.elementId),
+        truncated: boxes.length >= 500
+    };
+}

package/dist/knowledge/localization.js

@@ -0,0 +1,51 @@
+import { RefResolveError } from '../platform/refs.js';
+/**
+ * FK slug'ı TAHMİN EDİLMEZ: rehber "satırı elle kurmadan önce mutlaka entity_get ile doğrula"
+ * diyor, gateway de aynısını yapar — companion'ın alanları arasında `relationId` ana entity'ye
+ * işaret edeni arar. Eşleşme yoksa uydurulmuş bir slug'la yanlış satır yazmaktansa hata verilir.
+ */
+export async function findLocalizationCompanion(resolver, main) {
+    const companionSlug = `${main.slug}_localization`;
+    // Bağ ÖNCE id'den okunur: ad kalıbı ('{slug}_localization') platformun ürettiği kolaylıktır,
+    // sözleşme değil — companion yeniden adlandırılırsa slug yolu "companion yok" der ve ajan var
+    // olan bir entity'yi yeniden kurmaya çalışır. `localizationEntityId` entity'nin kendi alanıdır
+    // (b-03) ve entity_get onu döndürür; eski platform sürümünde boş gelir, o zaman slug yoluna
+    // düşülür.
+    const linkedId = await resolver.entityRecord(main)
+        .then(record => {
+        const value = record.localizationEntityId;
+        return typeof value === 'string' && value.length > 0 ? value : undefined;
+    })
+        .catch(() => undefined);
+    const companion = await (linkedId ? resolver.entity(linkedId) : Promise.reject(new RefResolveError('link yok')))
+        .catch(() => resolver.entity(companionSlug))
+        .catch((error) => {
+        // YALNIZ "yok" hâli dostane mesaja çevrilir; belirsizlik / HTTP / yetki hataları olduğu gibi
+        // geçer — hepsini "companion yok" diye yutmak ajana var olan bir entity'yi kurdurur.
+        if (error instanceof RefResolveError && /diye bir entity yok/.test(error.message)) {
+            throw new RefResolveError(`'${main.slug}' için companion entity yok — entity'de isLocalized alan yok ya da companion henüz kurulmadı (ne 'localizationEntityId' bağı ne de '${companionSlug}' adı bulundu). platform_guide('entity') §'Çoklu dilli alan'.`);
+        }
+        throw error;
+    });
+    const fields = await resolver.entityFields(companion);
+    const candidates = fields.filter(field => field.relationType !== 'none' && field.relationId === main.entityId);
+    const [fk] = candidates;
+    if (!fk) {
+        throw new RefResolveError(`'${companionSlug}' içinde relationId '${main.entityId}' olan bir ilişki alanı yok; FK tahmin edilmez. Alanlar: ${fields.map(field => field.slug).join(', ')}`);
+    }
+    if (candidates.length > 1) {
+        throw new RefResolveError(`'${companionSlug}' içinde '${main.slug}'a işaret eden birden çok ilişki alanı var (${candidates.map(field => field.slug).join(', ')}); hangisinin FK olduğu tahmin edilmez — dil satırlarını row_create ile elle yazın.`);
+    }
+    return { entityId: companion.entityId, datasourceId: companion.datasourceId, slug: companion.slug, fkSlug: fk.slug, languageSlug: 'language' };
+}
+export function localizationRows(companion, mainRowId, localizations) {
+    return Object.entries(localizations).map(([language, values]) => ({ [companion.fkSlug]: mainRowId, [companion.languageSlug]: language, ...values }));
+}
+/**
+ * Platform tanımadığı gövde alanını SESSİZCE düşürür; `X-Unmapped-Members` üretim dışı ortamda
+ * ilk tanınmayan alanın JSON yolunu döner. `localizations` orada görünüyorsa platform b-07 öncesi
+ * sürümdedir ve dil satırları hiç yazılmamıştır — gateway o zaman companion'a kendisi yazar.
+ */
+export function platformIgnoredLocalizations(headers) {
+    return (headers['x-unmapped-members'] ?? '').split(/[.,\s]+/).some(segment => segment.toLowerCase() === 'localizations');
+}