@appaflytech/zeyrek-ai-mcp 0.0.9 → 0.0.11

package/README.md

@@ -4,7 +4,7 @@ Zeyrek (NgApps) platformunu **MCP tool'ları** olarak sunan bağımsız gateway.
 oturumu Studio arayüzüne hiç girmeden proje kurabilir, veri modeli çıkarabilir, mikroservis ve
 workflow yazıp çalıştırabilir, sayfa tasarlayabilir.
 
-- **208 tool · 34 modül** — veri/mantık tarafı (project, application, datasource, entity, row,
+- **212 tool · 34 modül** — veri/mantık tarafı (project, application, datasource, entity, row,
   import, microservice, query, workflow, automation, function, dto, view, dependency), Studio
   tasarım tarafı (page, **theme**, component, external component, flow, layout, variable, function,
   folder, file, access, translation), yönetim (template, organization, deployment) ve proje dallanması
@@ -140,9 +140,9 @@ ya da ikisi karışık (`core,page`). `platform` modülü (3 tool) her kümede v
 | Küme | Tool | Modüller |
 |---|---|---|
 | `core` | 136 | platform, project, application, datasource, entity, row, import, microservice, microfunction, query, workflow, automation, function, dto, view, dependency, environment, merge, activity, revision |
-| `studio` | 78 | platform, page, theme, component, externalComponent, flow, layout, variable, function, folder, file, import, access, translation, revision |
+| `studio` | 82 | platform, page, theme, component, externalComponent, flow, layout, variable, function, folder, file, import, access, translation, revision |
 | `admin` | 27 | platform, template, organization, deployment, environment, merge, activity |
-| (boş) | **208** | 34 modülün tamamı |
+| (boş) | **212** | 34 modülün tamamı (ölçüm 2026-09-16, `listTools()`) |
 
 Bilinmeyen bir modül/küme adı verilirse sunucu açılmaz, geçerli adları listeleyen bir hata yazar.
 
@@ -281,9 +281,14 @@ kural envanteri [`docs/08-kural-envanteri.md`](docs/08-kural-envanteri.md).
 Yayın otomatiktir: `main`'e `zeyrek-mcp/` değişikliği girince CI işi `publish:mcp:npm`
 ([`scripts/ci-publish-npm.sh`](scripts/ci-publish-npm.sh)) paketi üretip npm'deki son sürümle
 içerik olarak karşılaştırır; pakete giren dosyalar değiştiyse yeni patch sürümünü yayınlar.
-Sürümün kaynağı npm'dir, CI `package.json`'ı geri commit'lemez. Minor/major için
-`package.json`'daki sürümü elle yükseltip merge edin. Yayını o commit için atlamak: commit
-mesajına `DoNotDeploy` (iş elle tetiklenir hâle gelir).
+Yayından sonra CI yeni sürümü `package.json` + `package-lock.json`'a yazıp
+`chore: zeyrek-mcp X.Y.Z [skip ci]` bot commit'iyle `main`'e push eder (yeni pipeline
+başlatmaz); yayın olmazsa commit de olmaz. Push CI_JOB_TOKEN ile yapılır; gereken GitLab
+ayarları `.gitlab-ci.yml`'daki `publish:mcp:npm` notunda. Commit yazılamayıp iş kırmızı düşerse
+push yetkisi olan biri işi Retry eder: yayın tekrarlanmaz, yalnız sürüm `main`'e yazılır.
+Minor/major için `package.json`'daki
+sürümü elle yükseltip merge edin. Yayını o commit için atlamak: commit mesajına `DoNotDeploy`
+(iş elle tetiklenir hâle gelir).
 
 Yerelde deneme (yayın yapmaz; `npm ci` çalıştırdığı için bir kopyada ya da Linux container'da):
 

package/dist/knowledge/designSnapshot.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+/**
+ * TASARIM ANLIK GÖRÜNTÜSÜ — bir tasarım dosyasının (Figma) TEK GEÇİŞTE okunup dosyaya alınmış
+ * hâli. `theme_discover`'ın girdisi budur; gateway Figma'ya kendisi gitmez (plan K1), süreç içi
+ * önbellek de tutmaz (HTTP taşımasında her POST yeni sunucu kurar — anlık görüntü DOSYADIR, K2).
+ *
+ * `.strict()` her seviyede: tanınmayan anahtar sessizce yaşamaz. Gerekçe tema şemasıyla aynı —
+ * ajan `variables` yerine `tokens` yazarsa bu bir yazım hatası değil, eşlemeye hiç girmeyen ve
+ * kimsenin görmediği bir veri kaybıdır. Şema onu istek anında adıyla reddeder.
+ *
+ * Ölçek: `textStyles.fontSize`, `components.*` uzunlukları ve `layout` px'tir; `effects.opacity`
+ * Figma'nın 0–1'idir (tema 0–100 ister, çeviri eşlemede — g-02). `variables` `get_variable_defs`
+ * çıktısının KENDİSİDİR: ad yeniden yazılmaz, değer olduğu gibi taşınır; eşleme adı okur.
+ */
+const scalar = z.union([z.string(), z.number()]);
+export const TEXT_STYLE_ROLES = ['h1', 'h2', 'h3', 'h4', 'label', 'p', 'small'];
+export const SCREEN_ROLES = ['shell', 'list', 'form', 'detail', 'auth', 'other'];
+/** `hints` değeri: bu Figma adı eşlemeye HİÇ girmesin (bilinçli karar; `unmapped` sebebi olarak döner). */
+export const SNAPSHOT_HINT_IGNORE = 'ignore';
+export const designSnapshotInput = z.object({
+    source: z.object({
+        kind: z.enum(['figma', 'manual']),
+        fileKey: z.string().optional(),
+        fileName: z.string().optional(),
+        nodeIds: z.array(z.string()).optional(),
+        fetchedAt: z.string().optional(),
+        calls: z.number().int().optional(),
+        characters: z.number().int().optional()
+    }).strict(),
+    variables: z.record(scalar),
+    variablesDark: z.record(scalar).optional(),
+    textStyles: z.array(z.object({
+        name: z.string(),
+        role: z.enum(TEXT_STYLE_ROLES).optional(),
+        fontFamily: z.string(),
+        fontSize: z.number(),
+        fontWeight: scalar.optional(),
+        lineHeight: z.number().optional()
+    }).strict()).optional(),
+    effects: z.array(z.object({
+        name: z.string(),
+        offsetX: z.number(),
+        offsetY: z.number(),
+        blur: z.number(),
+        spread: z.number(),
+        color: z.string(),
+        opacity: z.number()
+    }).strict()).optional(),
+    layout: z.object({
+        desktopWidth: z.number().optional(),
+        mobileWidth: z.number().optional(),
+        gutter: z.number().optional(),
+        sidebarWidth: z.number().optional(),
+        notes: z.array(z.string()).optional()
+    }).strict().optional(),
+    components: z.record(z.object({
+        background: z.string().optional(),
+        color: z.string().optional(),
+        border: z.string().optional(),
+        borderRadius: scalar.optional(),
+        paddingX: z.number().optional(),
+        paddingY: z.number().optional(),
+        height: z.number().optional(),
+        fontSize: z.number().optional(),
+        fontWeight: scalar.optional(),
+        shadow: z.string().optional()
+    }).strict()).optional(),
+    screens: z.array(z.object({
+        nodeId: z.string(),
+        name: z.string(),
+        role: z.enum(SCREEN_ROLES),
+        screenshot: z.string().optional(),
+        notes: z.array(z.string()).optional()
+    }).strict()).optional(),
+    /** Figma adı → tema yolu (`accent.muted`, `colors.blue.500`) ya da `ignore`; ajanın KALICI kararı. */
+    hints: z.record(z.string()).optional()
+}).strict();

package/dist/knowledge/normalize.js

@@ -1905,6 +1905,53 @@ export function inertFlexPropWarning(entries) {
             + "sessizce yok sayılır (istek reddedilmez, prop katalogda vardır). Akış düzeni istiyorsan aynı düğüme "
             + "layout:'flex' de yaz, istemiyorsan bu prop'ları kaldır — platform_guide('page') Kural 1f-2."];
 }
+/**
+ * Akış id'si → ona bağlı olaylar. Bağ üç yerde durur: düğümün `events[].value`'su, düğüm
+ * prop'larındaki `type:'flow'` referansları (`event` alanı `prop:<ad>` olur) ve barındırıcının
+ * düzey olayları (`target: 'page'` — `remove_event`'in aynı hedef adı). Akış tarafından bu
+ * listeyi veren bir uç yok; 2026-09-16 raporunda uygulama kabuğunda hangi olayın hangi akışa
+ * bağlı olduğu kaybolmuş, ikinci "zil rozeti" akışı sahipsiz kalmıştı.
+ */
+export function flowBindings(schema, hostEvents) {
+    const bindings = new Map();
+    const add = (flowId, binding) => {
+        if (flowId === '')
+            return;
+        bindings.set(flowId.toLowerCase(), [...(bindings.get(flowId.toLowerCase()) ?? []), binding]);
+    };
+    for (const event of asObjects(hostEvents)) {
+        if (typeof event.value === 'string')
+            add(event.value, { target: 'page', event: String(event.name ?? '') });
+    }
+    const visitProp = (target, propName, value) => {
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                visitProp(target, propName, entry);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const record = value;
+        if (record.type === 'flow' && typeof record.ref === 'string')
+            add(record.ref, { target, event: `prop:${propName}` });
+        for (const entry of Object.values(record))
+            visitProp(target, propName, entry);
+    };
+    const visitNode = (node) => {
+        const target = String(node.elementId ?? node.name ?? '');
+        for (const event of asObjects(node.events)) {
+            if (typeof event.value === 'string')
+                add(event.value, { target, event: String(event.name ?? '') });
+        }
+        for (const [propName, value] of Object.entries((node.props ?? {})))
+            visitProp(target, propName, value);
+        for (const child of asObjects(node.children))
+            visitNode(child);
+    };
+    for (const node of asObjects(schema))
+        visitNode(node);
+    return bindings;
+}
 /**
  * Bir yamanın SİLECEĞİ akışlar. Platform referanssız kalan akışı KALICI siler; uyarı yamadan sonra
  * geldiğinde "önce yedekle" tavsiyesi uygulanamaz hâle geliyordu (09-05 koşusu: sekiz adımlı giriş

package/dist/knowledge/outlines.js

@@ -1,3 +1,4 @@
+import fastJsonPatch from 'fast-json-patch';
 import { functionSignature } from './functionGuards.js';
 function asArray(value) {
     return Array.isArray(value) ? value.filter((entry) => Boolean(entry) && typeof entry === 'object') : [];
@@ -280,22 +281,38 @@ export function describePatchTarget(document, path) {
     const kind = entry.type ?? entry.dbType;
     return `${path} → '${label}'${kind ? ` (${String(kind)}` + `, id ${String(entry.id ?? '?')})` : `, id ${String(entry.id ?? '?')}`}`;
 }
+/**
+ * Her op, KENDİSİNDEN ÖNCEKİ op'ların uygulanmış hâlindeki belgeye karşı çözülür ve hemen
+ * ardından o tek op çalışan kopyaya uygulanır (S-3): aynı diziye giden birden çok `remove`
+ * seçicisi tek seferde ORİJİNAL belgeye göre indekse çevrilseydi, ilk silme diziyi kısaltıp
+ * sonraki op'ların indeksini kaydırırdı — yanıt yine de "applied: true" derdi çünkü hedef adı da
+ * aynı bayat belgeden okunuyordu. Dönen `operations` dizisi, orijinal belgeye karşı SIRAYLA
+ * uygulandığında (tek `fastJsonPatch.applyPatch` çağrısıyla dahi) bu adım adım simülasyonla aynı
+ * sonucu üretir; çağıranların uygulama biçimini değiştirmesi gerekmez.
+ */
 export function resolvePatchOperations(document, operations, readTool = 'workflow_get') {
     const notes = [];
     const targets = [];
-    const resolved = operations.map(operation => {
+    const resolvedOperations = [];
+    let working = structuredClone(document);
+    for (const operation of operations) {
         const path = typeof operation.path === 'string' ? operation.path : '';
         const op = typeof operation.op === 'string' ? operation.op : '';
-        const outcome = resolvePatchPointer(document, path, readTool, op);
-        const from = typeof operation.from === 'string' ? resolvePatchPointer(document, operation.from, readTool, op) : undefined;
+        const outcome = resolvePatchPointer(working, path, readTool, op);
+        const from = typeof operation.from === 'string' ? resolvePatchPointer(working, operation.from, readTool, op) : undefined;
         if (outcome.note)
             notes.push(outcome.note);
         if (from?.note)
             notes.push(from.note);
-        targets.push(describePatchTarget(document, outcome.path));
-        return from ? { ...operation, path: outcome.path, from: from.path } : { ...operation, path: outcome.path };
-    });
-    return { operations: resolved, notes, targets };
+        targets.push(describePatchTarget(working, outcome.path));
+        const resolvedOperation = from ? { ...operation, path: outcome.path, from: from.path } : { ...operation, path: outcome.path };
+        resolvedOperations.push(resolvedOperation);
+        // validate:false — bu yalnız SONRAKİ op'ların indeksini doğru izlemek için ara bir simülasyon;
+        // gerçek RFC6902 doğrulaması (ör. 'replace' hedefinin önceden var olması) çağıranın az sonra
+        // yapacağı asıl uygulamada (validate:true) hâlâ çalışır, burada erken ve gereksiz patlamaz.
+        working = fastJsonPatch.applyPatch(working, [resolvedOperation], false, true).newDocument;
+    }
+    return { operations: resolvedOperations, notes, targets };
 }
 /**
  * Fonksiyon özeti (G-07): kaynak, ad, kapsam, imza, parametre listesi, gövde satır sayısı —

package/dist/knowledge/pageDiscover.js

@@ -0,0 +1,151 @@
+import { readKnowledgeFile } from '../resources/knowledge.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { discoverTheme } from './themeDiscover.js';
+const ARCHETYPES = {
+    form: { example: 'page-form-upsert', flows: { mount: 'mountFlowCreateArgs', submit: 'submitFlowCreateArgs' } },
+    detail: { example: 'page-detail-profile', flows: { mount: 'mountFlowCreateArgs' } },
+    auth: { example: 'page-sign-in', flows: { submit: 'submitFlowCreateArgs' } }
+};
+const LIST_ARCHETYPE = 'list (kod içi iskelet) + flow-list-to-form';
+const SHELL_EXAMPLE = 'layout-app-shell';
+const LIST_EVENTS_EXAMPLE = 'flow-list-to-form';
+const turkishMap = { ç: 'c', ğ: 'g', ı: 'i', ö: 'o', ş: 's', ü: 'u', â: 'a', î: 'i', û: 'u' };
+export function slugifyScreenName(name) {
+    return name.toLocaleLowerCase('tr')
+        .replace(/[çğıöşüâîû]/g, letter => turkishMap[letter] ?? letter)
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+const readExample = (name) => JSON.parse(readKnowledgeFile('examples', `${name}.json`));
+const isPlaceholder = (value) => typeof value === 'string' && value.startsWith('<');
+const staticProp = (data) => ({ type: 'static', data });
+const node = (elementId, type, props, wrapper, block) => ({
+    elementId,
+    kind: 'component',
+    type,
+    name: elementId,
+    props,
+    states: { isSticky: false, isDroppable: wrapper, isScrollable: false, isWrapper: wrapper },
+    blocks: [{ breakpoint: 1024, size: { h: block.h, w: block.w }, position: { x: block.x, y: block.y } }],
+    children: [],
+    events: [],
+    validations: [],
+    stateBindings: []
+});
+/** Liste sayfası asgari iskeleti: araç çubuğu (Yeni) + kayıt tablosu; adlar `flow-list-to-form` ile aynı. */
+function listSkeleton() {
+    return [
+        { op: 'add_component', parent: 'page_container', component: node('list_toolbar', 'container', { layout: staticProp('flex'), direction: staticProp('row') }, true, { h: 4, w: 12, x: 0, y: 0 }) },
+        { op: 'add_component', parent: 'list_toolbar', component: node('btn_new', 'button', { text: staticProp('Yeni') }, false, { h: 4, w: 3, x: 0, y: 0 }) },
+        { op: 'add_component', parent: 'page_container', component: node('records_table', 'table', {}, false, { h: 40, w: 12, x: 0, y: 4 }) }
+    ];
+}
+function pageArgs(screenName, base, options, caveats) {
+    const args = { ...base, name: screenName, slug: slugifyScreenName(screenName), browserTitle: screenName };
+    if (options.layoutId !== undefined) {
+        args.layoutId = options.layoutId;
+    }
+    else {
+        if (isPlaceholder(args.layoutId) || args.layoutId === undefined)
+            delete args.layoutId;
+        caveats.push("layoutId verilmedi — sayfa kabuksuz açılır; kabuk için 'shell' ekranını page_discover ile layout_create'e çevirip (ya da layout_list ile mevcut kabuğu bulup) pageCreateArgs.layoutId verin");
+    }
+    if (options.middlewareIds !== undefined) {
+        args.middlewareIds = options.middlewareIds;
+    }
+    else if (Array.isArray(args.middlewareIds) && args.middlewareIds.some(isPlaceholder)) {
+        delete args.middlewareIds;
+        caveats.push('middlewareIds verilmedi — örnek korumalı sayfa istiyor; auth middleware id için middleware_list, sonra pageCreateArgs.middlewareIds (bir-iki ucu bağlayıp gerisini açık bırakmak yasak)');
+    }
+    return args;
+}
+/** Tek aday preset bağlanır (`props.style = { $preset }`); birden çok aday karar ister (K4). */
+function bindPresets(ops, presets, caveats) {
+    const bindings = [];
+    for (const op of ops) {
+        if (op.op !== 'add_component')
+            continue;
+        const component = op.component;
+        const type = typeof component?.type === 'string' ? component.type : undefined;
+        const elementId = typeof component?.elementId === 'string' ? component.elementId : undefined;
+        if (component === undefined || type === undefined || elementId === undefined)
+            continue;
+        const candidates = presets.filter(preset => preset === type || preset.startsWith(`${type}-`));
+        if (candidates.length === 1) {
+            component.props = { ...(component.props ?? {}), style: { $preset: candidates[0] } };
+            bindings.push({ elementId, type, preset: candidates[0] });
+        }
+        else if (candidates.length > 1) {
+            caveats.push(`${elementId} (${type}) için birden çok preset adayı var: ${candidates.join(', ')} — hangisi olacağına siz karar verin (page_schema_patch replace_prop style { $preset })`);
+        }
+    }
+    return bindings;
+}
+export function discoverPage(snapshot, screenRef, options = {}) {
+    const screens = snapshot.screens ?? [];
+    const screen = screens.find(entry => entry.nodeId === screenRef) ?? screens.find(entry => entry.name === screenRef);
+    if (screen === undefined) {
+        throw new PlatformApiError(`page_discover: '${screenRef}' anlık görüntünün screens listesinde yok (nodeId ya da name). Mevcut ekranlar: ${screens.map(entry => `${entry.name} (${entry.nodeId}, ${entry.role})`).join(' · ') || 'yok'}.`, 400);
+    }
+    const caveats = [];
+    const notes = [...(snapshot.layout?.notes ?? []), ...(screen.notes ?? [])];
+    const head = { screen: { nodeId: screen.nodeId, name: screen.name, role: screen.role }, notes };
+    const presets = Object.keys(discoverTheme(snapshot).theme.presets ?? {});
+    if (screen.role === 'shell') {
+        const example = readExample(SHELL_EXAMPLE);
+        return {
+            ...head,
+            archetype: SHELL_EXAMPLE,
+            layoutCreateArgs: { ...example.layoutCreate, name: screen.name },
+            schemaPatchOps: [],
+            flows: {},
+            presetBindings: [],
+            caveats: ['kabuk bir SAYFA değil LAYOUT kaydıdır; yan menü/üst şerit içeriğini ekran notlarına göre layout_schema_patch ile doldurun'],
+            next: 'layout_create(layoutCreateArgs) → layout_list ile id → diğer ekranların pageCreateArgs.layoutId'
+        };
+    }
+    if (screen.role === 'other') {
+        return {
+            ...head,
+            archetype: 'yok',
+            pageCreateArgs: pageArgs(screen.name, {}, options, caveats),
+            schemaPatchOps: [],
+            flows: {},
+            presetBindings: [],
+            caveats: [...caveats, "rol 'other' — arketip yok; ekran notlarına göre page_schema_patch ile elle kurun (platform_guide('page') §arketipler) ya da anlık görüntüde role list/form/detail/auth verin"],
+            next: "page_create(pageCreateArgs) → page_schema_patch(ops — elle) → page_screenshot"
+        };
+    }
+    if (screen.role === 'list') {
+        const events = readExample(LIST_EVENTS_EXAMPLE);
+        const ops = [...listSkeleton(), ...(events.schemaPatchOps ?? [])];
+        const presetBindings = bindPresets(ops, presets, caveats);
+        caveats.push("records_table props boş — kolonları ve veri kaynağını component_get('table') + flow-load-table örneğine göre verin; set_event op'larındaki '<… flow id>' yer tutucuları flow_create sonrası gerçek id ile değiştirilir");
+        return {
+            ...head,
+            archetype: LIST_ARCHETYPE,
+            pageCreateArgs: pageArgs(screen.name, {}, options, caveats),
+            schemaPatchOps: ops,
+            flows: { openRecord: events.openRecordFlowCreateArgs, newRecord: events.newRecordFlowCreateArgs },
+            presetBindings,
+            caveats,
+            next: 'page_create(pageCreateArgs) → flow_create(flows.openRecord, flows.newRecord) → set_event yer tutucularını flow id ile değiştir → page_schema_patch(schemaPatchOps) → page_screenshot'
+        };
+    }
+    const archetype = ARCHETYPES[screen.role];
+    const example = readExample(archetype.example);
+    const ops = structuredClone(example.schemaPatchOps ?? []);
+    const presetBindings = bindPresets(ops, presets, caveats);
+    const flows = Object.fromEntries(Object.entries(archetype.flows).map(([key, field]) => [key, example[field]]).filter(([, value]) => value !== undefined));
+    caveats.push(`iskelet '${archetype.example}' altın örneğinden — elementId'ler ve metinler örneğin domainindedir (${String(example.pageCreateArgs?.name ?? '')}); ekran notlarına göre alan adlarını, etiketleri ve akış adımlarını değiştirin`);
+    return {
+        ...head,
+        archetype: archetype.example,
+        pageCreateArgs: pageArgs(screen.name, example.pageCreateArgs ?? {}, options, caveats),
+        schemaPatchOps: ops,
+        flows,
+        presetBindings,
+        caveats,
+        next: 'page_create(pageCreateArgs) → page_schema_patch(pageId, schemaPatchOps) → flow_create(flows.*) ve set_event yer tutucularını flow id ile değiştir → page_screenshot'
+    };
+}