Metadata-Version: 2.4
Name: mcp-workflow-core
Version: 0.3.0
Summary: MCP sunucularının iş akışı belgeleri için tek motor: listeleme, arama, doğrulama, yazma, kaynak tanımları.
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest<10,>=9; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Dynamic: license-file

# workflow-core

MCP sunucularının iş akışı belgelerini okuyan, arayan, doğrulayan ve MCP kaynağı olarak
yayımlayan Python kütüphanesi. Sunucu değildir: port dinlemez, araç yayımlamaz. Sunucular
onu içe aktarır ve üç ayarla yapılandırır.

**Durum (2026-09-01):** dört tüketici sunucu motora bağlı ve kopyasız; yol haritasının
beş fazından dördü geçti. Motor 0.3.0 (230 test, ruff temiz); dağıtım adı
`mcp-workflow-core`, lisans Apache 2.0, PyPI yayımı onay sahibinin elinde.

**Hangi sürümdeyim:** paket sürümü **0.3.0**. Kaynak `pyproject.toml` (`[project]
version`); `tests/test_surum.py` bu satırı ona bağlar, çalışma anında
`workflow_core.__version__` aynı numarayı verir. Kuralların sürümü ayrıdır:
[anayasa](.sdd/CONSTITUTION.md) 1.4.0.

## Ne yapar

Bir sunucunun belge klasöründeki Markdown iş akışı belgelerini yönetir. Her
belge bir üst bilgi bloğu (frontmatter) ve zorunlu bölümler taşır; motor bunları:

- listeler ve okur,
- arar (Türkçe harfleri katlayarak: büyük `İ`, aksanlı ve aksansız yazım aynı sonucu
  verir),
- doğrular (zorunlu alanlar, zorunlu bölümler, gövdede anılan araç adlarının çalışma
  anındaki kayıtta var olup olmadığı, bayatlık),
- yazar, günceller ve siler (kuru çalıştırma ve arşivle),
- MCP kaynağı olarak yayımlar.

Motor belgeleri çalıştırmaz, okutur. Belge "makinenin yürüteceği kod" değil, "akıllı bir
asistanın okuyacağı yönerge"dir; koşul, döngü ve karar asistanın işidir.

Kullanım, tüketici sunucuda:

```python
from workflow_core import Config, Library

library = Library(Config.from_file("workflow.yaml"))  # docs_dir, tool_prefix, categories
library.search("devreye alma")                         # Türkçe katlamalı arama
library.validate(registered_tools=canli_arac_listesi, today="2026-08-22")
library.write("42-yeni-belge", icerik, dry_run=True)  # plan döner, disk değişmez
library.dispatch("get", {"id": "42-yeni-belge"})       # tek giriş: action + params
```

MCP kaynağı olarak yayın çerçeveye göre tek satır: `workflow_core.adapters.gofastmcp`
ya da `workflow_core.adapters.official_sdk` içinden `register(server, library)`. Onay
kapısı motorda değil tüketici aracındadır; motor `dry_run` planını ve yıkıcı eylem
işaretini (`ACTIONS`) verir.

## Neden var

Aynı motor daha önce üç sunucuya kopyalanmıştı: toplam 1720 satır, paylaşılan satır
sıfır. Düzeltmeler iki yönde de akmadı; bir kopyada yapılan iyileştirme ötekilere
gitmedi, orijinaldeki düzeltme kopyalara gitmedi. Faz 0 ölçümü hiçbir kopyanın "en
zengin" olmadığını gösterdi: doğru davranışlar üçüne dağılmıştı ve arama üçünde de
Türkçe-güvenli değildi. Birleştirme tek kopyayı seçerek yapılamaz; bu yüzden motor tek
yerde yazılıyor ve sunucular onu kütüphane olarak alıyor.

## Tasarım ilkeleri

- **Motor tek, yapılandırma çok.** Sunucuya özel üç şey var: belge klasörünün yolu,
  araç-adı öneki, geçerli kategori listesi. Dördüncüsü gerektiğinde önce "bu gerçekten
  sunucuya mı özel" diye sorulur. Tanınmayan yapılandırma alanı reddedilir.
- **Alan-özel `if` yok.** Sunucuya özel davranış yapılandırma alanıyla çözülür; alan
  eklemek diff'te görünür, `if` görünmez.
- **Hiçbir MCP çerçevesine bağlanmaz.** Tüketiciler iki farklı çerçevede çalışıyor; motor
  ikisini de içe aktarmaz, kaynak kaydı çerçeveden bağımsız bir arayüzle sunulur.
- **Sessiz düşüş yok.** Yedek yola düşüş, kırpma ve yok sayma en az bir uyarı loglar.
- **Yazma güvenlik zinciriyle.** Kuru çalıştırma motorda, onay tüketici aracında; eski
  sürüm arşivlenir, yazma atomiktir, sonuç geri okunur. `success: true` kanıt değildir.
- **Kopyalanmaz.** Tüketiciler paketi düzenlenebilir kurulumla (`pip install -e`) alır.
  Düzeltme diske anında akar; çalışan sunucuya yeniden başlatmayla gelir.

## Yapılandırma sözleşmesi (taslak)

Faz 1'de kesinleşir. Bugünkü niyet:

| Alan | Ne | Örnek |
|---|---|---|
| belge klasörü | iş akışı belgelerinin dizini | `docs/workflows` |
| araç-adı öneki | doğrulamanın gövdede arayacağı araç adı deseni | `acme_` |
| kategori listesi | belgelerin alabileceği geçerli kategoriler | `temel, kalite, yasam-dongusu` |

Bu üçünün dışındaki her şey ortak koddur.

## Tüketici kılavuzu

Bir sunucuyu motora bağlamak beş adımdır; her adımın kanıtı yanında yazılı.

1. **Kur.** Dağıtım adı `mcp-workflow-core` (PyPI'daki `workflow-core` başka bir
   paketin; içe aktarma adı `workflow_core` aynı): `pip install mcp-workflow-core`, ya da
   aynı makinede kaynaktan düzenlenebilir kurulum `pip install -e <workflow-core dizini>`.
   Düzenlenebilir kurulum diske anında akar, çalışan sunucuya yeniden başlatmayla gelir
   (anayasa, bilinen tuzaklar). Bağımlılık satırına üst sınır yazın (`<0.4`).
2. **Yapılandır.** Sunucu köküne `workflow.yaml`: `docs_dir`, `tool_prefix`,
   `categories`. Dördüncü alan yazılırsa motor yüklenmez; kategori listesi boş olamaz.
3. **Sar.** Tek araç + `action`: `library.dispatch(action, params)`. Araç açıklamasını ve
   yıkıcılık işaretini `ACTIONS` tablosundan üret. Onay kapısı sunucunun işidir:
   `confirm` verilmemişse `write` ve `delete` `dry_run=True` ile çağrılır ve plan döner,
   `confirm=True` ile gerçek yazma. Araç listesi canlı kayıttan `registered_tools`,
   kaynağı `tool_source` olarak verilir. Hata zarfı (`ok`, `type`) sarmalayıcıda; motor
   istisna fırlatır.
4. **Yayımla.** `from workflow_core.adapters.<çerçeve> import register`;
   `register(server, library)` somut listeyi ve `workflow://{id}` şablonunu birlikte
   kaydeder. Somut liste kayıt anının anlık görüntüsüdür: sonradan eklenen belge şablon
   adresle okunur, listeye sunucu yeniden başlatılınca girer. Bu bedel bilinçli (tasarım
   kılavuzu §4); yalnız somut liste kurulursa yeni belge hiç okunamaz.
5. **Doğrula.** Yeniden başlat, sonra canlı: büyük `İ`'li Türkçe sorgu sonuç döndürüyor
   mu, `validate` notunda araç listesinin kaynağı yazıyor mu, `workflow://<kimlik>`
   okunuyor mu, `dry_run` diske dokunmuyor mu. `success: true` kanıt değildir.

**Ret bir karardır, hata değil.** Motor yazmayı ya da silmeyi reddettiğinde istisna
fırlatmaz; `allowed`, `blocked_by`, `written` / `deleted` taşıyan planı döndürür ve
sonuca kendi hükmünü koyar. `ok` yalnız "diske yapıldı" demektir: kuru çalıştırmada ve
rette daima `false`, gerçek koşuda geri okuma doğrulayınca `true`; planın geçip
geçmeyeceği `allowed` alanında. Zarfı motorun alanlarından türetin, `ok`'u koşulsuz
yazmayın; hangi sırayla yazarsanız yazın motorun değeri onaysız planı "yapıldı"
göstermez. İlk bağlantıda reddedilen bir silme koşulsuz `ok` yüzünden başarılı
görünmüştü (2026-08-25); 0.1.1 kuru çalıştırmada "yapılabilir" anlamında `true` yazınca
üç sunucuda onaysız plan yapılmış göründü (2026-08-26), 0.2.0 bunu kapattı.

Eski motor dosyası bağlantıdan sonra silinir; kopya kalırsa çatallanma geri gelir. İlk
doğrulamada yeni kurallar uyarı üretir (`missing_verified_on`, frontmatter içi yorum
satırı); belge uyumu sunucunun işidir, sayılar Faz 1 planının SC-006 tablosunda.

## Depo düzeni

```text
workflow_core/            motor paketi: yapılandırma, belge modeli, arama, doğrulama, yazma, kaynak, dağıtıcı
  adapters/               çerçeveye dokunan tek yer; çerçeve başına bir dosya
tests/                    pytest: modül başına test + kapanış, sessizlik, adsız çıktı testleri
  korpus/, golden/        deneme belgeleri ve sorgu-beklenti seti
.sdd/                     süreç belgeleri: anayasa, yol haritası, görevler, şartnameler
  features/00N-*/         Faz 0 fark tablosu; Faz 1 şartname, plan, yetenek envanteri
_olcumler/                gerçek korpus ölçümleri (sürüm kontrolü dışında)
pyproject.toml            paket tanımı, sürümün tek kaynağı, ruff ayarı
.test-komutu              push öncesi kapının koştuğu test komutu
```

## Geliştirme

Python 3.11 gerekir. Sanal ortam aç, paketi düzenlenebilir kur (tüketici sunucular da
aynı komutla, kendi sanal ortamlarına kurar):

```powershell
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"   # motor + pytest + ruff
```

```powershell
python -m pytest tests -q              # testler (kaynak ağacından da koşar)
ruff check . ; ruff format --check .   # linter ve biçim
python .sdd/scripts/sdd.py durum       # aktif özellik, kapılar, sıradaki adım
python .sdd/scripts/sdd.py denetle     # belge düzeni denetimi
python .sdd/scripts/sdd.py sizinti     # ortama bağlı iz taraması
```

Push öncesi kapı (`pre-push`) testleri ve düzen denetimini kendisi koşar; kırmızı testle
push yapılamaz.

İş akışı şartname odaklıdır: bir iş önce `.sdd/ROADMAP.md`'de durur, `sdd yeni` ile
şartnamesi açılır, onaylanır, planı yazılır, `sdd kontrol` sıfır dönünce görevleri
`.sdd/TODO.md`'ye düşer. Onay sohbette değil dosyada verilir.

## Belgeler

| Dosya | Ne için |
|---|---|
| [.sdd/CONSTITUTION.md](.sdd/CONSTITUTION.md) | kural gövdesi, tek nüsha |
| [.sdd/ROADMAP.md](.sdd/ROADMAP.md) | yön, aşamalar, bilinçli olarak girilmeyen yollar |
| [.sdd/ARCHITECTURE.md](.sdd/ARCHITECTURE.md) | tarihli mimari kararlar ve reddedilen alternatifler |
| [.sdd/TODO.md](.sdd/TODO.md) | açık işler |
| [.sdd/CHANGELOG.md](.sdd/CHANGELOG.md) | tamamlanan dalgalar ve nedenleri |
| [.sdd/features/001-faz0-davranis-farki/fark-tablosu.md](.sdd/features/001-faz0-davranis-farki/fark-tablosu.md) | Faz 0 çıktısı: kopyaların davranış farkı, hükümler, kusur listesi |
| [.sdd/features/002-faz1-motor-paketi/plan.md](.sdd/features/002-faz1-motor-paketi/plan.md) | Faz 1 planı: tasarım kararları, yetenek envanteri, kapanış testleri, gerçek korpus ölçümleri |
