@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/observability/trace.js

@@ -0,0 +1,337 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const defaultDirectory = join(process.cwd(), 'logs');
+const activeTrace = new AsyncLocalStorage();
+const activeRequest = new AsyncLocalStorage();
+const inFlight = new Set();
+const secretKeyPattern = /pass|secret|token|authorization|api[-_]?key|credential|connectionstring/i;
+const detailIndent = 26;
+let level = 'off';
+let logFile;
+let logDirectory = defaultDirectory;
+let maxBodyChars = 2000;
+let sessionLines = [];
+let headerPath = '';
+let ensuredDirectory = '';
+let writingDisabled = false;
+let exitHookInstalled = false;
+let sequence = 0;
+function twoDigits(value) {
+    return String(value).padStart(2, '0');
+}
+function clockOf(moment) {
+    return `${twoDigits(moment.getHours())}:${twoDigits(moment.getMinutes())}:${twoDigits(moment.getSeconds())}.${String(moment.getMilliseconds()).padStart(3, '0')}`;
+}
+function dayOf(moment) {
+    return `${moment.getFullYear()}-${twoDigits(moment.getMonth() + 1)}-${twoDigits(moment.getDate())}`;
+}
+function condense(text, limit) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit)}… (+${collapsed.length - limit} karakter kırpıldı)`;
+}
+function clip(text, limit) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit).trimEnd()}…`;
+}
+function redact(value, depth = 0) {
+    if (depth > 8)
+        return '…';
+    if (Array.isArray(value))
+        return value.map(entry => redact(entry, depth + 1));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+            if (secretKeyPattern.test(key))
+                return [key, '***'];
+            if (/^stack(Trace)?$/i.test(key) && typeof entry === 'string') {
+                return [key, `${clip(entry.split(/\r?\n/)[0] ?? '', 240)} … (kalan stack kırpıldı)`];
+            }
+            return [key, redact(entry, depth + 1)];
+        }));
+    }
+    return value;
+}
+export function renderJson(value) {
+    if (value === undefined)
+        return '(yok)';
+    try {
+        return condense(JSON.stringify(redact(value)) ?? String(value), maxBodyChars);
+    }
+    catch {
+        return condense(String(value), maxBodyChars);
+    }
+}
+function resolveLogPath() {
+    return logFile ?? join(logDirectory, `gateway-${dayOf(new Date())}.log`);
+}
+function write(text) {
+    if (level === 'off' || writingDisabled)
+        return;
+    const path = resolveLogPath();
+    try {
+        if (ensuredDirectory !== dirname(path)) {
+            mkdirSync(dirname(path), { recursive: true });
+            ensuredDirectory = dirname(path);
+        }
+        if (headerPath !== path) {
+            const intro = existsSync(path) ? [] : fileIntroLines();
+            headerPath = path;
+            appendFileSync(path, [...intro, ...sessionLines].join('\n'), 'utf8');
+        }
+        appendFileSync(path, text, 'utf8');
+    }
+    catch (error) {
+        writingDisabled = true;
+        process.stderr.write(`[mcp-gateway] tool günlüğü yazılamadı, günlükleme kapatıldı: ${String(error)}\n`);
+    }
+}
+function fileIntroLines() {
+    return [
+        '═'.repeat(112),
+        'ngapps mcp gateway — tool çağrısı günlüğü. Her tool çağrısı tek bir bloktur:',
+        '  amaç    tool ne işe yarar (tool tanımındaki açıklama)',
+        '  girdi   çağrıya gelen parametreler; parola/token/connection string alanları *** ile maskelenir',
+        '  adımlar çağrının içeriden geçtiği duraklar, çağrı başlangıcından itibaren geçen süreyle:',
+        '          politika  = gövde lint kuralları (block bulgusu isteği hiç göndermez)',
+        '          düzeltme  = gateway otomatik düzeltmeleri (yanıtta gatewayNormalized)',
+        '          kimlik →← = /connect/token turu, istek →/yanıt ← = platform API turu',
+        '          kırpma ✂  = yanıt boyut sınırı, hata ✕ = yakalanan hata (mesaj + stack)',
+        '  SONUÇ   çağrının bittiği yer: başarılı/HATA, toplam süre, adım sayısı ve BAŞARILI',
+        '          çağrılarda etki özeti (id/slug/applied/kaç kayıt/gatewayNormalized)',
+        '',
+        'Ayrıca "KABİLİYET BOŞLUĞU" blokları vardır: ajanın platform desteklemediği için',
+        'yapamadığı ve tasarımı küçülttüğü noktalar (platform_gap_report ile yazılır).',
+        'Bunlar hata DEĞİLDİR — hata günlüğünde hiç görünmezler, ürün kararı için toplanırlar.',
+        '',
+        'Arama ipuçları: "SONUÇ  : HATA" tüm başarısız çağrılar · "hata ✕" hata satırları ·',
+        '"MCP KATMANI REDDETTİ" tool gövdesine hiç girmeyen çağrılar · "#<n>" tek bir çağrı ·',
+        '"KABİLİYET BOŞLUĞU" platformun yetmediği noktalar.',
+        '═'.repeat(112),
+        ''
+    ];
+}
+function buildSessionLines(config, transport) {
+    const now = new Date();
+    return [
+        '',
+        `── oturum ${dayOf(now)} ${clockOf(now)} · pid ${process.pid} · taşıma ${transport} · org ${config.organization} · proje ${config.defaultProject ?? '(yok)'} · env ${config.defaultEnvironment} · politika ${config.policyMode} · ${config.modules.length} modül · günlük ${level}`,
+        ''
+    ];
+}
+export function configureLogging(config, transport) {
+    level = config.logLevel;
+    logFile = config.logFile;
+    logDirectory = config.logDirectory ?? defaultDirectory;
+    maxBodyChars = config.logMaxBodyChars;
+    sessionLines = buildSessionLines(config, transport ?? 'mcp');
+    if (transport)
+        headerPath = '';
+    if (level !== 'off' && !exitHookInstalled) {
+        exitHookInstalled = true;
+        process.on('exit', () => {
+            for (const trace of inFlight) {
+                write(renderTrace(trace, { ok: false, summary: 'YARIDA KESİLDİ — süreç tool çağrısı sürerken kapandı' }));
+            }
+        });
+    }
+}
+export function logsDetail() {
+    return level === 'detail';
+}
+export function logStep(label, summary, detail = []) {
+    const trace = activeTrace.getStore();
+    if (!trace || trace.steps.length >= 500)
+        return;
+    trace.steps.push({
+        elapsedMs: Date.now() - trace.startedAt,
+        label,
+        summary,
+        detail: detail.filter(line => line.length > 0).map(line => condense(line, maxBodyChars))
+    });
+}
+export function logError(error) {
+    if (!activeTrace.getStore())
+        return;
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const status = failure.status;
+    const code = failure.code;
+    const marks = [status ? `HTTP ${status}` : '', code ? `kod ${code}` : ''].filter(mark => mark.length > 0);
+    const stack = (failure.stack ?? '').split('\n').slice(1, 4).map(line => line.trim());
+    logStep('hata ✕', `${failure.name}${marks.length > 0 ? ` (${marks.join(', ')})` : ''} — tool isError yanıtına çevirdi`, [
+        failure.message,
+        ...(level === 'detail' ? stack : [])
+    ]);
+}
+function renderTrace(trace, outcome) {
+    const lines = [
+        `┌─ #${trace.sequence} · ${trace.clock} · ${trace.tool}${trace.title ? ` — ${trace.title}` : ''}`,
+        `│  amaç   : ${trace.purpose}`,
+        `│  girdi  : ${trace.input}`,
+        trace.steps.length > 0 ? '│  adımlar:' : '│  adımlar: (yok — çağrı platforma çıkmadan gateway içinde bitti)'
+    ];
+    for (const step of trace.steps) {
+        lines.push(`│    ${`+${step.elapsedMs}ms`.padEnd(9)} ${step.label.padEnd(11)} ${step.summary}`);
+        for (const entry of step.detail) {
+            for (const line of entry.split('\n'))
+                lines.push(`│${' '.repeat(detailIndent)}${line}`);
+        }
+    }
+    lines.push(`└─ SONUÇ  : ${outcome.ok ? 'başarılı' : 'HATA'} · ${Date.now() - trace.startedAt} ms · ${trace.steps.length} adım · ${outcome.summary}`);
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+function describeResult(result) {
+    const call = result;
+    const text = Array.isArray(call?.content)
+        ? call.content.filter(entry => entry.type === 'text').map(entry => String(entry.text)).join(' ')
+        : '';
+    if (call?.isError)
+        return { ok: false, summary: clip(text, 400) };
+    const effect = summarizeEffect(text);
+    return { ok: true, summary: `${Buffer.byteLength(text, 'utf8')} B yanıt${effect ? ` · ${effect}` : ''}` };
+}
+/**
+ * Başarılı çağrının NE YAPTIĞINI tek satırda özetler. Eskiden yalnız yanıt boyutu yazılıyordu;
+ * günlükten "hangi kayıt oluştu, kaç op uygulandı, gateway neyi düzeltti" okunamıyordu.
+ */
+const effectKeys = ['id', 'slug', 'name', 'applied', 'newVersion', 'count', 'total', 'httpStatus'];
+function summarizeEffect(text) {
+    if (text.length === 0)
+        return '';
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return '';
+    }
+    if (Array.isArray(parsed))
+        return `dizi=${parsed.length}`;
+    if (!parsed || typeof parsed !== 'object')
+        return '';
+    const record = parsed;
+    const marks = [];
+    for (const key of effectKeys) {
+        const value = record[key];
+        if (value === null || value === undefined || typeof value === 'object')
+            continue;
+        marks.push(`${key}=${clip(String(value), 80)}`);
+    }
+    for (const key of ['items', 'data', 'rows', 'results']) {
+        if (Array.isArray(record[key]))
+            marks.push(`${key}=${record[key].length}`);
+    }
+    if (record.gatewayNormalized)
+        marks.push('gatewayNormalized');
+    if (Array.isArray(record.findings) && record.findings.length > 0)
+        marks.push(`politikaBulgusu=${record.findings.length}`);
+    return marks.join(' · ');
+}
+async function traceToolCall(tool, spec, callArgs, callback) {
+    const now = new Date();
+    const first = callArgs[0];
+    const trace = {
+        sequence: (sequence += 1),
+        tool,
+        title: spec.title ?? '',
+        purpose: spec.description ? clip(spec.description, 260) : '(açıklama yok)',
+        input: first && typeof first === 'object' && Object.keys(first).length > 0 ? renderJson(first) : '(parametresiz)',
+        startedAt: now.getTime(),
+        clock: clockOf(now),
+        steps: []
+    };
+    const marker = activeRequest.getStore();
+    if (marker)
+        marker.traced = true;
+    inFlight.add(trace);
+    try {
+        const result = await activeTrace.run(trace, async () => callback(...callArgs));
+        write(renderTrace(trace, describeResult(result)));
+        return result;
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        write(renderTrace(trace, { ok: false, summary: `tool istisna fırlattı — ${failure.name}: ${clip(failure.message, 300)}` }));
+        throw error;
+    }
+    finally {
+        inFlight.delete(trace);
+    }
+}
+function logRejectedRequest(request, reason) {
+    const call = request;
+    const target = call?.params?.name ?? call?.params?.uri ?? '';
+    const description = reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason);
+    write(`${[
+        `┌─ ${clockOf(new Date())} · ${call?.method ?? 'mcp isteği'}${target ? ` · ${target}` : ''} · MCP KATMANI REDDETTİ`,
+        `│  girdi  : ${renderJson(call?.params?.arguments)}`,
+        `│  hata   : ${clip(description, 600)}`,
+        '└─ SONUÇ  : HATA · tool gövdesi hiç çalışmadı; istek tool adı/parametre şeması doğrulamasında durdu',
+        ''
+    ].join('\n')}\n`);
+}
+async function traceResourceRead(name, readArgs, read) {
+    const startedAt = Date.now();
+    const uri = readArgs[0] instanceof URL ? readArgs[0].href : name;
+    const marker = activeRequest.getStore();
+    if (marker)
+        marker.traced = true;
+    try {
+        const result = await read(...readArgs);
+        write(`[${clockOf(new Date())}] kaynak okundu · ${uri} · ${Buffer.byteLength(JSON.stringify(result) ?? '', 'utf8')} B · ${Date.now() - startedAt} ms\n`);
+        return result;
+    }
+    catch (error) {
+        write(`[${clockOf(new Date())}] kaynak HATASI · ${uri} · ${String(error)}\n`);
+        throw error;
+    }
+}
+export function instrumentServer(server, config) {
+    configureLogging(config);
+    if (level === 'off')
+        return server;
+    const registerTool = server.registerTool.bind(server);
+    const registerResource = server.registerResource.bind(server);
+    server.registerTool = ((tool, spec, callback) => registerTool(tool, spec, (...callArgs) => traceToolCall(tool, spec, callArgs, callback)));
+    server.registerResource = ((name, uri, spec, read) => registerResource(name, uri, spec, (...readArgs) => traceResourceRead(name, readArgs, read)));
+    const lowLevelServer = server.server;
+    const setRequestHandler = lowLevelServer.setRequestHandler.bind(lowLevelServer);
+    lowLevelServer.setRequestHandler = ((schema, handler) => setRequestHandler(schema, async (...handlerArgs) => {
+        const marker = { traced: false };
+        try {
+            const result = await activeRequest.run(marker, async () => handler(...handlerArgs));
+            if (!marker.traced && result?.isError) {
+                logRejectedRequest(handlerArgs[0], result.content?.[0]?.text ?? 'bilinmeyen doğrulama hatası');
+            }
+            return result;
+        }
+        catch (error) {
+            if (!marker.traced)
+                logRejectedRequest(handlerArgs[0], error);
+            throw error;
+        }
+    }));
+    return server;
+}
+export function logGatewayEvent(message) {
+    write(`[${clockOf(new Date())}] ${message}\n`);
+}
+/**
+ * Ajanın "bunu yapamıyorum çünkü platform desteklemiyor" dediği anı kalıcı kılar. Bu bilgi
+ * hata günlüğünden çıkmaz: çağrı hiç yapılmadığı için ortada hata yoktur, yalnızca küçültülmüş
+ * bir tasarım vardır. Turdan sonra ürün kararı bu kayıtlardan çıkar.
+ */
+export function logCapabilityGap(gap) {
+    const lines = [
+        `┌─ ${clockOf(new Date())} · KABİLİYET BOŞLUĞU · ${gap.severity}${gap.module ? ` · ${gap.module}` : ''}`,
+        `│  hedef  : ${condense(gap.goal, maxBodyChars)}`,
+        `│  engel  : ${condense(gap.blocker, maxBodyChars)}`
+    ];
+    if (gap.attempted && gap.attempted.length > 0) {
+        lines.push(`│  denenen: ${gap.attempted.map(entry => condense(entry, 300)).join(' | ')}`);
+    }
+    lines.push(`│  yerine : ${gap.workaround ? condense(gap.workaround, maxBodyChars) : '(tasarım küçültüldü, alternatif yok)'}`);
+    lines.push('└─ SONUÇ  : kaydedildi · bu bir hata değil, eksik kabiliyet raporudur');
+    lines.push('');
+    write(`${lines.join('\n')}\n`);
+}

package/dist/platform/errors.js

@@ -0,0 +1,132 @@
+export class PlatformApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'PlatformApiError';
+    }
+}
+const MaxSurfacedValidationMessages = 20;
+const MaxSurfacedSuggestions = 12;
+function formatPageSchemaError(entry) {
+    const where = [entry.componentId, entry.path].filter(part => typeof part === 'string' && part.length > 0).join(' · ');
+    const rule = typeof entry.rule === 'string' && entry.rule.length > 0 ? `[${entry.rule}] ` : '';
+    const suggestions = Array.isArray(entry.suggestions) && entry.suggestions.length > 0
+        ? ` → kabul edilenler: ${entry.suggestions.slice(0, MaxSurfacedSuggestions).join(', ')}${entry.suggestions.length > MaxSurfacedSuggestions ? ` (+${entry.suggestions.length - MaxSurfacedSuggestions})` : ''}`
+        : '';
+    return `${rule}${where || '?'}: ${entry.message ?? ''}${suggestions}`;
+}
+function collectValidationMessages(payload) {
+    const messages = [];
+    if (Array.isArray(payload.errors)) {
+        for (const entry of payload.errors) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const record = entry;
+            const isPageSchemaShape = 'rule' in record || 'componentId' in record || 'suggestions' in record;
+            messages.push(isPageSchemaShape
+                ? formatPageSchemaError(record)
+                : `${record.key ?? '?'}: ${record.value ?? ''}`);
+        }
+    }
+    else if (payload.errors && typeof payload.errors === 'object') {
+        for (const [field, fieldMessages] of Object.entries(payload.errors)) {
+            const flattened = Array.isArray(fieldMessages) ? fieldMessages.join(' | ') : String(fieldMessages);
+            messages.push(`${field}: ${flattened}`);
+        }
+    }
+    if (messages.length <= MaxSurfacedValidationMessages)
+        return messages;
+    return [...messages.slice(0, MaxSurfacedValidationMessages), `… ve ${messages.length - MaxSurfacedValidationMessages} hata daha`];
+}
+/**
+ * Sayfa şeması patch'inin üç reddi de "hiçbir op uygulanmadı" anlamına gelir (uygulayıcı önce tüm
+ * op'ları bellekte işler, tek hata bile tüm komutu düşürür) — ajanın kısmi uygulama varsayıp
+ * planın kalanını göndermesi bu yüzden yanlış olur.
+ */
+function pageSchemaHint(code) {
+    if (code === 'PageSchemaVersionConflictException') {
+        return ' Sayfa siz okuduktan sonra değişti ve HİÇBİR op uygulanmadı. page_schema_get ile yeniden okuyup planı tazeleyin, yeni `version` değerini `baseVersion` olarak gönderin.';
+    }
+    if (code === 'PageSchemaLockedException') {
+        return ' Sayfa şeması başka bir aktörün kilidinde (kilit sahibi mesajda; kilit 60 sn sonra kendiliğinden düşer). Bekleyip tekrar deneyin — aynı anda iki yazar olduğunda kaybeden taraf sessizce ezilmesin diye kilit var.';
+    }
+    if (code === 'PageSchemaValidationException') {
+        return ' Op listesi doğrulama duvarına takıldı ve HİÇBİR op uygulanmadı (hepsi ya da hiçbiri). Alan hatalarını düzeltip tek çağrıda tekrar gönderin; planı önce page_schema_validate ile kuru koşturabilirsiniz.';
+    }
+    return '';
+}
+/**
+ * Bilinen platform bug'larını ajanın tool yüzeyinden teşhis edebilmesi için desen eşlemesi
+ * (klinik turu dersi: teşhis DB'ye/koda inmeden yapılabilmeli — görev G-09).
+ */
+function diagnoseKnownFailure(status, message, code, context) {
+    if (status !== 500)
+        return '';
+    if (context.path.includes('/row') && message.includes('Sequence contains no matching element')) {
+        return " Muhtemel sebep: entity bir application'a bağlı değil — entity_patch ile applicationIds ekleyin (PLT-004).";
+    }
+    if (message.includes('42P01') || /relation "[^"]+" does not exist/.test(message)) {
+        return " Bilinen sınır (K-005/P-01): m2m, çoklu dosya ya da çoklu enum alanı entity_create gövdesindeyken platform junction KAYDINI açar ama fiziksel tabloyu kurmaz. Alanı entity_patch ile yeniden ekleyin; gateway'in entity_create'i bunu artık kendisi iki aşamaya bölüyor, elle kurulmuş eski kayıtlar etkilenir.";
+    }
+    if (message.includes('cannot be tracked') || message.includes('already being tracked')) {
+        return " Bilinen sınır (K-006/P-02): operation:'get' tipli microservice'te PUT, izlenen Application grafiği yüzünden 500 veriyor. Geçici yol: microservice_delete + microservice_create ile yeniden kurun (gövdeyi önce microservice_get ile alın).";
+    }
+    if (code === 'RowValidationFailed' || message.includes('RowValidationFailed')) {
+        return ' Gövdedeki alanlar doğru görünüyorsa muhtemel sebep istemcinin body alanını düşürmesidir (K-002): microservice_execute/debug çağrısında body bir NESNE ya da nesne DİZİSİ olmalı; boş gövdeyle gönderildiyse istemci şemayı desteklemiyor olabilir.';
+    }
+    return '';
+}
+export function mapPlatformError(status, payload, context) {
+    const body = payload && typeof payload === 'object' ? payload : {};
+    const code = typeof body.code === 'string' ? body.code : undefined;
+    const apiMessage = typeof body.message === 'string' && body.message.length > 0
+        ? body.message
+        : typeof body.title === 'string' ? body.title : undefined;
+    const location = `${context.method} ${context.path}`;
+    if (status === 400) {
+        const validationMessages = collectValidationMessages(body);
+        if (validationMessages.length > 0) {
+            return new PlatformApiError(`Doğrulama hatası (${location}): ${validationMessages.join(' ; ')}. Gövde şeması için ilgili ngapps://schemas kaynağına ya da mevcut bir kaydın *_get çıktısına bakın.`, status, code);
+        }
+        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}`, status, code);
+    }
+    if (status === 401) {
+        const hint = context.authMode === 'local'
+            ? 'Gateway konfigürasyonundaki USERNAME/PASSWORD doğru mu kontrol edin.'
+            : 'İstemciden geçirilen Authorization header süresi dolmuş olabilir; yeni token alıp MCP kaydını güncelleyin.';
+        return new PlatformApiError(`Kimlik doğrulanamadı (${location}). ${hint}`, status, code);
+    }
+    if (status === 403) {
+        return new PlatformApiError(`Yetki yok (${location}). Token'ın sahibi bu işlem için yetkili değil.`, status, code);
+    }
+    if (status === 404) {
+        const environmentHint = context.environment
+            ? ` Environment '${context.environment}' doğru mu kontrol edin;`
+            : '';
+        if (context.method !== 'GET' && /\/flows(\/|$)/.test(context.path)) {
+            return new PlatformApiError(`Adımda referans verilen kayıt çözümlenemedi (${location}). Bu uçta 404 akışın kendisini DEĞİL bir adım argümanını kastediyor: flow-trigger adımının args'ında ne flowId ne triggerElementId var (ya da triggerElementId sayfadaki hiçbir elementId ile eşleşmiyor), setter adımının iteratees[].element'i bulunamıyor, ya da bir adım silinmiş bir komponente bakıyor. Adım argümanlarını page_schema_get'teki elementId'lerle karşılaştırın; flow-trigger'ın iki geçerli şekli için platform_guide('page') Kural 1c.`, status, code);
+        }
+        return new PlatformApiError(`Kayıt bulunamadı (${location}).${environmentHint} id/slug değerini ilgili *_list tool'uyla doğrulayın.`, status, code);
+    }
+    if (status === 409 || status === 422) {
+        const projectConflictHint = status === 409 && context.method === 'POST' && /\/projects\/?$/.test(context.path)
+            ? " Mesaj hangi alanın çakıştığını söylemez: proje slug'ı VEYA application slug'ı dolu olabilir. Application slug'ı ORGANİZASYON GENELİNDE tekildir ('web'/'app'/'portal' gibi jenerik adlar büyük olasılıkla doludur) — project_list ile mevcut application slug'larını tarayın."
+            : '';
+        const validationMessages = collectValidationMessages(body);
+        const detail = validationMessages.length > 0 ? ` → ${validationMessages.join(' ; ')}` : '';
+        return new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code)}`, status, code);
+    }
+    const fallbackValidationMessages = collectValidationMessages(body);
+    const fallbackDetail = fallbackValidationMessages.length > 0 ? ` → ${fallbackValidationMessages.join(' ; ')}` : '';
+    return new PlatformApiError(`Platform hatası ${status} (${location}): ${apiMessage ?? 'beklenmeyen hata'}${code ? ` [${code}]` : ''}${fallbackDetail}${diagnoseKnownFailure(status, apiMessage ?? '', code, context)}`, status, code);
+}
+export function mapNetworkError(error, context) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    if (cause.name === 'TimeoutError' || cause.name === 'AbortError') {
+        return new PlatformApiError(`${context.api} API zaman aşımına uğradı (${context.method} ${context.path}). Uzun süren bir işlemse durumu ilgili *_history/*_status tool'undan izleyin.`);
+    }
+    return new PlatformApiError(`${context.api} API'ye ulaşılamadı (${context.baseUrl}): ${cause.message}. API ayakta mı? Lokal ortam için docker compose ya da dotnet run kontrol edin.`);
+}

package/dist/platform/http.js

@@ -0,0 +1,169 @@
+import { PlatformApiError, mapNetworkError, mapPlatformError } from './errors.js';
+import { logStep, logsDetail, renderJson } from '../observability/trace.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { TokenProvider } from './token.js';
+import { randomUUID } from 'node:crypto';
+import { request } from 'undici';
+export const requestAuthStorage = new AsyncLocalStorage();
+function buildMultipart(parts, boundary) {
+    const chunks = [];
+    for (const part of parts) {
+        const disposition = 'filename' in part
+            ? `form-data; name="${part.name}"; filename="${part.filename.replace(/"/g, '')}"\r\nContent-Type: ${part.contentType}`
+            : `form-data; name="${part.name}"`;
+        chunks.push(Buffer.from(`--${boundary}\r\nContent-Disposition: ${disposition}\r\n\r\n`, 'utf8'));
+        chunks.push('filename' in part ? part.content : Buffer.from(part.value, 'utf8'));
+        chunks.push(Buffer.from('\r\n', 'utf8'));
+    }
+    chunks.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'));
+    return Buffer.concat(chunks);
+}
+function describeMultipart(parts) {
+    return Object.fromEntries(parts.map(part => [
+        part.name,
+        'filename' in part ? `<dosya ${part.filename} · ${part.contentType} · ${part.content.byteLength} B>` : part.value
+    ]));
+}
+function appendQuery(url, query) {
+    if (!query)
+        return;
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                url.searchParams.append(key, String(entry));
+        }
+        else {
+            url.searchParams.append(key, String(value));
+        }
+    }
+}
+export class Platform {
+    config;
+    tokens;
+    constructor(config, tokens) {
+        this.config = config;
+        this.tokens = tokens ?? new TokenProvider(config);
+    }
+    resolveProject(project) {
+        const resolved = project ?? this.config.defaultProject;
+        if (!resolved) {
+            throw new PlatformApiError("Proje belirtilmedi: tool çağrısına 'project' parametresi ekleyin ya da DEFAULT_PROJECT tanımlayın.");
+        }
+        return resolved;
+    }
+    resolveEnvironment(environment) {
+        return environment ?? this.config.defaultEnvironment;
+    }
+    async org(method, path, options = {}) {
+        const outcome = await this.send('org', method, path, {
+            ...options,
+            environment: this.resolveEnvironment(options.environment)
+        });
+        return outcome.body;
+    }
+    async tenant(method, project, path, options = {}) {
+        const outcome = await this.send('tenant', method, `/${this.resolveProject(project)}${path}`, {
+            ...options,
+            environment: this.resolveEnvironment(options.environment)
+        });
+        return outcome.body;
+    }
+    async tenantRaw(method, project, path, options = {}) {
+        return this.send('tenant', method, `/${this.resolveProject(project)}${path}`, {
+            ...options,
+            environment: this.resolveEnvironment(options.environment)
+        }, true);
+    }
+    async authorizationHeader() {
+        if (this.config.authMode === 'passthrough') {
+            const incoming = requestAuthStorage.getStore();
+            if (!incoming) {
+                throw new PlatformApiError("Passthrough modda Authorization header'ı gelmedi. MCP kaydına --header \"Authorization: Bearer <token>\" ekleyin.");
+            }
+            return incoming;
+        }
+        return `Bearer ${await this.tokens.getToken()}`;
+    }
+    async send(api, method, path, options, raw = false, isRetry = false) {
+        const baseUrl = api === 'org' ? this.config.orgApiBaseUrl : this.config.tenantApiBaseUrl;
+        const context = { api, method, path, baseUrl, environment: options.environment, authMode: this.config.authMode };
+        const url = new URL(`${baseUrl}${path}`);
+        appendQuery(url, options.query);
+        const callerHeaders = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+        const headers = {
+            host: `${this.config.organization}.${this.config.hostSuffix}`,
+            accept: 'application/json',
+            ...(callerHeaders.authorization || options.anonymous ? {} : { authorization: await this.authorizationHeader() }),
+            ...(options.environment ? { 'x-environment': options.environment } : {}),
+            ...callerHeaders
+        };
+        let body;
+        if (options.multipart) {
+            const boundary = `----ngapps${randomUUID().replace(/-/g, '')}`;
+            headers['content-type'] = `multipart/form-data; boundary=${boundary}`;
+            body = buildMultipart(options.multipart, boundary);
+        }
+        else if (options.form) {
+            headers['content-type'] = 'application/x-www-form-urlencoded';
+            body = options.form.toString();
+        }
+        else if (options.body !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(options.body);
+        }
+        const startedAt = Date.now();
+        logStep('istek →', `${method} ${url.href} · ${api} api${options.environment ? ` · env=${options.environment}` : ''}${options.anonymous ? ' · ANONİM (Authorization header YOK)' : ''}${isRetry ? ' · 401 sonrası tekrar' : ''}`, logsDetail() && (options.multipart || options.form || options.body !== undefined)
+            ? [`gövde: ${renderJson(options.multipart
+                    ? describeMultipart(options.multipart)
+                    : options.form
+                        ? Object.fromEntries(options.form)
+                        : options.body)}`]
+            : []);
+        let statusCode;
+        let payload;
+        let responseBytes = 0;
+        try {
+            const response = await request(url, {
+                method: method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+            });
+            statusCode = response.statusCode;
+            if (options.expectBinary && statusCode < 400) {
+                const bytes = Buffer.from(await response.body.arrayBuffer());
+                responseBytes = bytes.byteLength;
+                payload = { contentType: String(response.headers['content-type'] ?? 'application/octet-stream'), bytes };
+            }
+            else {
+                const text = await response.body.text();
+                responseBytes = Buffer.byteLength(text, 'utf8');
+                try {
+                    payload = text ? JSON.parse(text) : undefined;
+                }
+                catch {
+                    payload = text;
+                }
+            }
+        }
+        catch (error) {
+            logStep('ağ ✕', `${method} ${url.href} · ${Date.now() - startedAt} ms sonra ulaşılamadı`, [error instanceof Error ? `${error.name}: ${error.message}` : String(error)]);
+            throw mapNetworkError(error, context);
+        }
+        logStep('yanıt ←', `HTTP ${statusCode} · ${Date.now() - startedAt} ms · ${responseBytes} B`, statusCode >= 400 || logsDetail()
+            ? [`gövde: ${options.expectBinary && statusCode < 400 ? `<ikili içerik · ${responseBytes} B>` : renderJson(payload)}`]
+            : []);
+        if (statusCode === 401 && this.config.authMode === 'local' && !isRetry && !options.anonymous) {
+            this.tokens.invalidate();
+            logStep('token ⟳', 'token reddedildi — önbellek boşaltıldı, istek yeni token ile bir kez daha denenecek');
+            return this.send(api, method, path, options, raw, true);
+        }
+        if (raw)
+            return { httpStatus: statusCode, body: payload ?? null };
+        if (statusCode >= 400)
+            throw mapPlatformError(statusCode, payload, context);
+        return { httpStatus: statusCode, body: payload ?? { success: true } };
+    }
+}