ai-enderun 0.0.1

package/Gemini.md

@@ -0,0 +1,274 @@
+# AI-Enderun — Supreme Performance AI Orchestration (v0.0.1)
+
+# Place in project root. This file is the single source of truth for all AI clients (Gemini CLI, Claude Code, etc.).
+
+## 🎖️ AGENT CHECKLIST (MANDATORY IN EVERY RESPONSE)
+
+> Every response MUST end with the **Agent Completion Report** defined in the [OUTPUT FLOWS] section.
+
+---
+
+## Constitution Status
+
+This file (`./Gemini.md`) and the `.gemini/docs/` folder represent the "Supreme Law" of the project. All agents must read this file first in every session and strictly comply with its rules 100%.
+
+---
+
+## AGENT MODEL (How this Framework Works)
+
+Each "agent" in this project is an independent AI conversation (Claude/GPT).
+
+- **Orchestration:** Done by the user or an external tool (LangGraph/CrewAI).
+- **Ajanlar:** @manager, @explorer, @backend, @frontend, @analyst.
+- **State:** Persistent memory is stored in `.gemini/PROJECT_MEMORY.md`.
+- **Communication:** Agents read the memory and exchange directives via the user.
+
+---
+
+## STEP 0 — STARTUP (EVERY SESSION, NON-NEGOTIABLE)
+
+1. **Read ./Gemini.md First:** Read and fully understand this file.
+2. **Read Project Memory:** `.gemini/PROJECT_MEMORY.md` dosyasını oku ve şu bilgileri çıkar:
+   - `MEVCUT DURUM` → Hangi fazdayız? Aktif Trace ID var mı?
+   - `KRİTİK KARARLAR` tablosu → Daha önce ne kararlaştırıldı?
+   - `AKTİF GÖREVLER` tablosu → Bana atanmış görev var mı?
+   - `DOSYA DURUMU` tablosu → Eksik/broken dosyalar neler?
+   - `HISTORY` bölümü → Son 3 girişi oku, önceki çalışmaları anla.
+
+- [ ] Check `.gemini/docs/` Folder: Verify if `tech-stack.md` and `project-docs.md` exist.
+
+4. **Default Stack:**
+   - **Frontend:** React 19 + Vite (SPA) + Zustand + Tailwind.
+   - **Backend:** Node.js 20+ + Fastify + Kysely + PostgreSQL.
+5. **OTURUM SONU ZORUNLULUĞU:** Her yanıt sonunda `.gemini/PROJECT_MEMORY.md` → `HISTORY` bölümüne özet ekle ve ilgili log dosyasına kayıt yaz. Bu adım atlanamaz.
+
+---
+
+## STEP 1 — VALIDATE BEFORE ACTING
+
+If `tech-stack.md` is missing or empty, do not write code until the following is clarified:
+
+| Unknown                              | Action               |
+| ------------------------------------ | -------------------- |
+| Target Audience                      | Ask — do not proceed |
+| Platform (web / mobile / desktop)    | Ask — do not proceed |
+| Database                             | Ask — do not proceed |
+| Environment (prototype / production) | Ask — do not proceed |
+| Auth required?                       | Ask — do not proceed |
+| Monorepo or separate?                | Ask — do not proceed |
+| Deploy target                        | Ask — do not proceed |
+| i18n required?                       | Ask — do not proceed |
+
+**Minor details** (port, file names) → Assume and state at the beginning: `Assumption: [what] — [why]`.
+
+---
+
+## PROJECT MEMORY & LOCK PROTOCOL
+
+- **Memory Initialization:** All agents reference `.gemini/PROJECT_MEMORY.md` at the start of any task.
+- **Kalıcı Hafıza Protokolü:** Every agent MUST append a summary to the **HISTORY** section of `PROJECT_MEMORY.md`.
+- **HISTORY Entry Format (Zorunlu):**
+
+  ```markdown
+  ### [YYYY-MM-DD] — [Görev Başlığı]
+
+  - **Ajan:** @[agent-name]
+  - **Trace ID:** [uuid veya —]
+  - **Yapılan:** [Ne yapıldı, 2-3 cümle]
+  - **Karar:** [Varsa önemli karar]
+  - **Sonraki Adım:** [Ne yapılması gerekiyor]
+  ```
+
+- **MEVCUT DURUM Güncellemesi:** Her oturum sonunda `MEVCUT DURUM` tablosundaki `Aktif Faz`, `Son Güncelleme` ve `Aktif Trace ID` alanlarını güncelle.
+- **Memory Lock Rule:** To prevent concurrent writes, agents check for `.gemini/PROJECT_MEMORY.lock`.
+  - If exists: Wait 1s, retry. (Max 5 retries).
+  - After 5 retries: Report `BLOCKED — Memory Lock Timeout`.
+  - On success: Create lock, write, delete lock.
+
+---
+
+## FILE OWNERSHIP MATRIS
+
+| Component                   | Primary Owner    | Secondary                             |
+| --------------------------- | ---------------- | ------------------------------------- |
+| `apps/backend/`             | @backend         | @analyst                              |
+| `apps/web/`                 | @frontend        | @analyst                              |
+| `apps/mobile/`              | @mobile          | @analyst                              |
+| `apps/native/`              | @native          | @analyst                              |
+| `packages/shared-types/`    | @backend         | @frontend                             |
+| `.gemini/PROJECT_MEMORY.md` | @analyst         | All (History only)                    |
+| `.gemini/docs/api/`         | @backend (yazar) | @analyst (denetler), @frontend (okur) |
+| `.env.*`                    | @manager         | @backend                              |
+
+---
+
+## CORE PRINCIPLES
+
+- **@manager Orchestration:** Manager analiz eder, ajanları seçer ve Briefing Template sağlar. Her görev için benzersiz bir `Trace ID` (UUID) üretmekten sorumludur.
+- **Contract-First Approach:** Backend ve Frontend kod yazmadan önce `shared-types` ve `.gemini/docs/api/` üzerinden anlaşmalıdır. **@backend** endpoint yazar → `.gemini/docs/api/[domain].md` günceller → **@frontend** okur, sonra kodlar.
+- **Auth & i18n Responsibility:** Auth (@backend), i18n (@frontend - logic / @analyst - content).
+- **Zero Mock Policy:** Sahte veri yasak.
+  - **Exception 1:** External 3rd party services (Stripe etc.) → `ADAPTER_PATTERN` + `SANDBOX_MODE`.
+  - **Exception 2:** Unit Tests → Mocks allowed for external dependencies.
+- **Branded Types Law:** Tüm ID'ler Branded Types (`packages/shared-types`) olmalıdır.
+- **Search Before Reading:** Hiçbir ajan bir dosyayı körü körüne okumamalıdır; önce `framework-mcp` (veya sarmaladığı `codebase_search`) araçlarıyla bağlamı taramalıdır.
+- **Full-Spectrum Responsive:** Her bileşen mobile-first başlar (320px) ve ultra-wide ekranlara (1920px+) kadar `clamp()` ve `aspect-ratio` ile akışkan (fluid) kalmalıdır.
+- **Supreme Frontend Aesthetics:** @frontend, "AI slop" estetiğinden kaçınmalı; özgün, karakterli ve üretim kalitesinde arayüzler tasarlamalıdır.
+- **Audit Logging:** Tüm kritik işlemler loglanmalıdır.
+
+---
+
+## ABSOLUTE DON'TS — KIRMIZI ÇİZGİLER
+
+| Kural                          | Gerekçe                                                     |
+| ------------------------------ | ----------------------------------------------------------- |
+| `any` tipi yasak               | Type safety bozulur; `unknown` + type guard kullanılır.     |
+| `console.log` yasak            | Production'da yasak; structured logger (`pino`) kullanılır. |
+| Hardcoded secret yasak         | API key/token asla kod içinde olmaz; `.env` kullanılır.     |
+| Raw SQL string yasak           | Sadece Kysely; injection riski.                             |
+| Controller'da DB çağrısı yasak | Repository pattern zorunludur.                              |
+| try/catch'siz async yasak      | Her async blok hata yönetimi içermeli.                      |
+| İzinsiz dosya değişimi yasak   | File Ownership kuralı geçerlidir.                           |
+
+---
+
+## EXECUTION PROFILES
+
+- **Lightweight Profile (MVP):** SaaS, MVP veya hızlı prototipler için. Sadece manager, backend, frontend, analyst ve explorer aktiftir.
+- **Full Profile (Enterprise):** Karmaşık sistemler, mobil/native entegrasyonu olan veya yüksek güvenlik gerektiren projeler için. Tüm ajanlar aktiftir.
+
+---
+
+## ENVIRONMENT POLICY
+
+- **Hierarchy:** `.env.development` (yerel), `.env.test` (CI), `.env.production` (deployment).
+- **Management:** `@manager` stratejiyi belirler, `@backend` implementasyonu yapar. Sırlar asla commit edilmez, `.env.example` güncel tutulur.
+
+---
+
+## OUTPUT FLOWS — ZORUNLU ÇIKTI STANDARDI
+
+Her agent yanıtı şu sırayla yapılandırılır:
+
+1. **Assumptions** — Yapılan varsayımlar.
+2. **Problem** — Ne inşa edildiği ve neden (max 3 cümle).
+3. **File Tree** — Oluşturulan/değiştirilen dosyalar.
+4. **Code** — Eksiksiz kod (`...` ile kısaltma yasaktır).
+5. **Tests** — Vitest (Web/Backend), Jest (Mobile), Playwright (Native).
+6. **Dependency Map** — Sadece `@manager` yanıtları için zorunlu (Mermaid).
+7. **Agent Completion Report** — Standart blok.
+
+---
+
+## STATE MACHINE — EXECUTION PHASES
+
+| Faz     | Durum        | Giriş Kriteri | Çıkış Kriteri (DoD)                             |
+| ------- | ------------ | ------------- | ----------------------------------------------- |
+| PHASE_0 | Discovery    | —             | tech-stack.md onaylandı, Profile seçildi.       |
+| PHASE_1 | Architecture | PHASE_0 tamam | shared-types onaylandı, contract hash üretildi. |
+| PHASE_2 | Development  | PHASE_1 tamam | Core featurelar ve birim testler teslim edildi. |
+| PHASE_3 | Integration  | PHASE_2 tamam | Gerçek DB ile entegrasyon testleri geçti.       |
+| PHASE_4 | Deployment   | PHASE_3 tamam | Production deploy, walkthrough hazır.           |
+
+---
+
+## DEFINITION OF DONE (DoD) CHECKLIST
+
+_DoD kontrolleri sadece seçilen (Lightweight/Full) profildeki **aktif** ajanları kapsar._
+
+**PHASE_0 → PHASE_1:**
+
+- [ ] `tech-stack.md` approved by @manager.
+- [ ] Target Audience, Platform, DB defined.
+- [ ] Execution Profile selected.
+
+**PHASE_1 → PHASE_2:**
+
+- [ ] `shared-types` approved by all parties.
+- [ ] `contract.version.json` created and hash verified.
+- [ ] OpenAPI schema documented in `.gemini/docs/api/`.
+
+**PHASE_2 → PHASE_3:**
+
+- [ ] All features delivered with Unit Tests (Vitest).
+- [ ] MANDATORY Log schema implemented in all **active** agents.
+- [ ] No `any` or `console.log` violations.
+
+**PHASE_3 → PHASE_4:**
+
+- [ ] Integration tests passed with real DB (TestContainers).
+- [ ] Zero Mock Policy verified (except exceptions).
+
+**PHASE_4 (Done):**
+
+- [ ] `PROJECT_MEMORY.md` fully updated.
+- [ ] Walkthrough documentation ready.
+
+---
+
+## API & CONTRACT MANAGEMENT
+
+### 1. contract.version.json Schema
+
+```json
+{
+  "version": "MAJOR.MINOR",
+  "last_updated": "ISO-8601",
+  "contract_hash": "sha256-...",
+  "breaking_changes": [{ "version": "1.0", "description": "Initial" }]
+}
+```
+
+### 2. CI Hash Verification
+
+```bash
+CURRENT_HASH=$(find packages/shared-types/src -name "*.ts" | sort | xargs sha256sum | sha256sum | awk '{print $1}')
+STORED_HASH=$(jq -r '.contract_hash' packages/shared-types/contract.version.json)
+[ "$CURRENT_HASH" = "$STORED_HASH" ] || (echo "HASH MISMATCH" && exit 1)
+```
+
+---
+
+## MANDATORY LOG SCHEMA (JSON)
+
+All agents MUST log to `.gemini/logs/[agent].json` using `write_file` tool.
+_Logs are stored as a **JSON Array**. Every turn appends a new object to the array._
+
+```json
+{
+  "timestamp": "ISO-8601",
+  "agent": "string",
+  "action": "CREATE | MODIFY | DELETE | DECISION",
+  "requestId": "uuid",
+  "files": ["string[]"],
+  "status": "SUCCESS | FAILURE",
+  "summary": "İşlemin Türkçe özeti",
+  "details": { "key": "value" }
+}
+```
+
+---
+
+## LANGUAGE POLICY
+
+- **Language Alignment:** Başlıklar ve terminoloji İngilizce, içerik ve yorumlar Türkçe.
+- **Code comments:** Türkçe (Neden yapıldığı).
+- **Names:** English (Variable/File).
+
+---
+
+## ✅ HER YANIT SONU ZORUNLU BLOK (REPORT)
+
+---
+
+**Agent Completion Report** (v1.0.2)
+
+- Mock kullanıldı mı? [ ] Hayır / [ ] Evet
+- shared-types değişti mi? [ ] Hayır / [ ] Evet
+- **API kontratı yazıldı/okundu mu? [ ] Hayır / [ ] Evet → .gemini/docs/api/[domain].md**
+- Log yazıldı mı? [ ] Hayır / [ ] Evet → .gemini/logs/[agent].json
+- **PROJECT_MEMORY HISTORY güncellendi mi? [ ] Hayır / [ ] Evet**
+- Bir sonraki adım: [ne yapılmalı]
+- Blokajlar: [varsa yaz, yoksa "YOK"]
+
+---

package/README.md

@@ -0,0 +1,63 @@
+# 🏛️ AI-Enderun — Supreme Performance AI Orchestration (v0.0.1)
+
+**Developer:** Yusuf BEKAR (Senior Software Architect)  
+**Status:** 🛠️ Professional Multi-Agent Framework  
+**Philosophy:** Senior Engineering Discipline & Ottoman Wisdom
+
+**AI-Enderun**, modern yazılım ekosisteminde yapay zeka ajanlarını seçkin birer "Senior Mühendis" gibi çalıştıran, Osmanlı'nın disiplinli devlet geleneğinden (Enderun) ilham alan profesyonel bir orkestrasyon sistemidir.
+
+[English](#english) | [Türkçe](#türkçe) | [Deutsch](#deutsch)
+
+---
+
+<a name="english"></a>
+## 🇬🇧 English: The Sovereign Intelligence
+
+### 🛡️ The Philosophy: "Discipline Above All"
+Named after the elite Ottoman palace school, **AI-Enderun** ensures that AI agents operate within a strict architectural constitution. It eliminates "AI Slop" by enforcing mandatory phase-based execution and a robust contract-first discipline.
+
+---
+
+<a name="türkçe"></a>
+## 🇹🇷 Türkçe: Egemen Zeka
+
+### 🛡️ Felsefe: "Her Şeyin Başı Disiplin"
+Adını Osmanlı'nın en seçkin beyinleri yetiştiren saray okulundan alan **AI-Enderun**, yapay zeka ajanlarının katı bir mimari anayasa çerçevesinde çalışmasını sağlar. Faz-bazlı yürütme ve kontrat-öncelikli disiplin ile kalitesiz kod üretimini (AI Slop) tamamen engeller.
+
+---
+
+<a name="deutsch"></a>
+## 🇩🇪 Deutsch: Die Souveräne Intelligenz
+
+### 🛡️ Die Philosophie: "Disziplin über Alles"
+Benannt nach der elitären osmanischen Palastschule, stellt **AI-Enderun** sicher, dass KI-Agenten innerhalb einer strengen architektonischen Verfassung agieren. Es eliminiert unstrukturierten Code durch die Erzwingung einer phasenbasierten Ausführung und einer robusten "Contract-First" Disziplin.
+
+---
+
+## 🏗️ Technical Structure / Teknik Yapı
+
+| Path | Description |
+| :--- | :--- |
+| **`Gemini.md`** | The Constitution / Anayasa (Supreme Law) |
+| **`.gemini/`** | Project Memory & Agent Personas / Hafıza ve Ajanlar |
+| **`bin/cli.js`** | Command Center / Komuta Merkezi |
+| **`packages/`** | Core Engine & Contracts / Çekirdek Motor ve Kontratlar |
+
+---
+
+## 🚀 Quick Start / Schnellstart
+
+```bash
+npx ai-enderun init
+```
+
+---
+
+## 📜 Version History
+| Version | Status | Description |
+| :--- | :--- | :--- |
+| **v0.0.1** | 🟢 Active | Rebranded as AI-Enderun. Multilingual support (EN, TR, DE). |
+
+---
+
+> **Supreme Law:** Senior discipline is not an option, it's the standard.

package/bin/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import crypto from "crypto";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const sourceDir = path.join(__dirname, "..");
+const targetDir = process.cwd();
+
+// --- YARDIMCI FONKSİYONLAR ---
+
+function getPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(sourceDir, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+function getMemoryPath() {
+  return path.join(targetDir, ".gemini", "PROJECT_MEMORY.md");
+}
+
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+// --- KOMUTLAR ---
+
+/**
+ * Projeyi ilklendirir (Eski init.js mantığı)
+ */
+async function initCommand(selectedAdapter) {
+  const ADAPTERS = {
+    gemini: ["Gemini.md", "gemini-extension.json"],
+    claude: ["CLAUDE.md"],
+    cursor: ["CURSOR.md"],
+    codex: ["CODEX.md"],
+  };
+
+  const CORE_FILES = [".gemini", "mcp.json", ".env.example", ".socraticodecontextartifacts.json"];
+
+  console.log("🚀 AI Agent Framework kuruluyor...");
+  
+  let filesToCopy = [...CORE_FILES, ...ADAPTERS.gemini, ...ADAPTERS.claude, ...ADAPTERS.cursor, ...ADAPTERS.codex];
+  
+  if (selectedAdapter) {
+    if (!ADAPTERS[selectedAdapter]) {
+      console.error(`❌ Geçersiz adaptör: ${selectedAdapter}`);
+      process.exit(1);
+    }
+    filesToCopy = [...CORE_FILES, "Gemini.md", ...ADAPTERS[selectedAdapter]];
+  }
+
+  for (const item of filesToCopy) {
+    const src = path.join(sourceDir, item);
+    const dest = path.join(targetDir, item);
+    if (fs.existsSync(src)) {
+      if (fs.lstatSync(src).isDirectory()) {
+        copyDir(src, dest);
+      } else {
+        fs.copyFileSync(src, dest);
+      }
+      console.log(`✅ ${item} oluşturuldu.`);
+    }
+  }
+  console.log("\n✨ Framework başarıyla kuruldu! (v" + getPackageVersion() + ")");
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  fs.readdirSync(src, { withFileTypes: true }).forEach(entry => {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    entry.isDirectory() ? copyDir(srcPath, destPath) : fs.copyFileSync(srcPath, destPath);
+  });
+}
+
+/**
+ * Projenin mevcut durumunu gösterir
+ */
+function statusCommand() {
+  const memoryPath = getMemoryPath();
+  if (!fs.existsSync(memoryPath)) {
+    console.error("❌ Hata: .gemini/PROJECT_MEMORY.md bulunamadı. Lütfen önce 'init' yapın.");
+    return;
+  }
+
+  const content = fs.readFileSync(memoryPath, "utf8");
+  const statusMatch = content.match(/\| Aktif Faz \| Son Güncelleme \| Aktif Trace ID \|\n\| :-------- \| :------------- \| :------------- \|\n\| (.*?) \| (.*?) \| (.*?) \|/);
+  
+  console.log("\n📊 --- PROJE DURUMU ---");
+  if (statusMatch) {
+    console.log(`🔹 Faz: ${statusMatch[1].trim()}`);
+    console.log(`📅 Güncelleme: ${statusMatch[2].trim()}`);
+    console.log(`🆔 Trace ID: ${statusMatch[3].trim()}`);
+  }
+
+  const tasksSection = content.match(/## AKTİF GÖREVLER\n\n([\s\S]*?)\n\n##/);
+  if (tasksSection) {
+    console.log("\n📋 Aktif Görevler:");
+    console.log(tasksSection[1].trim());
+  }
+
+  console.log("\n-----------------------\n");
+}
+
+/**
+ * Yeni bir Trace ID üretir ve hafızaya ekler
+ */
+function traceNewCommand(description, agent = "manager") {
+  const memoryPath = getMemoryPath();
+  if (!fs.existsSync(memoryPath)) {
+    console.error("❌ Hata: PROJECT_MEMORY.md bulunamadı.");
+    return;
+  }
+
+  const traceId = `TRACE-${generateUUID().slice(0, 8).toUpperCase()}`;
+  const date = new Date().toISOString().split('T')[0];
+  const newTask = `- [ ] [${traceId}] ${description} (@${agent})`;
+
+  let content = fs.readFileSync(memoryPath, "utf8");
+  content = content.replace("## AKTİF GÖREVLER\n\n", `## AKTİF GÖREVLER\n\n${newTask}\n`);
+  
+  fs.writeFileSync(memoryPath, content);
+  console.log(`\n✅ Yeni Trace ID oluşturuldu: ${traceId}`);
+  console.log(`📝 Görev listesine eklendi: ${description}\n`);
+}
+
+// --- ANA DISPATCHER ---
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "init":
+      await initCommand(args[0]);
+      break;
+    case "status":
+      statusCommand();
+      break;
+    case "trace:new":
+      if (!args[0]) {
+        console.error("❌ Kullanım: ai-agent-framework trace:new <açıklama> [agent]");
+      } else {
+        traceNewCommand(args[0], args[1]);
+      }
+      break;
+    case "version":
+    case "-v":
+    case "--version":
+      console.log(`v${getPackageVersion()}`);
+      break;
+    default:
+      console.log(`
+🤖 AI-Enderun CLI (v${getPackageVersion()})
+
+Kullanılabilir Komutlar:
+  init [ai-name]    Framework'ü ilklendirir (gemini, claude, cursor, codex)
+  status            Mevcut faz ve görev durumunu gösterir
+  trace:new <desc>  Yeni bir Trace ID üretir ve görevi hafızaya ekler
+  version           Versiyon bilgisini gösterir
+
+Örnek:
+  ai-agent-framework trace:new "Auth modülü tasarımı" backend
+      `);
+      break;
+  }
+}
+
+main().catch(console.error);

package/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "framework-mcp": {
+      "command": "npx",
+      "args": ["tsx", "packages/framework-mcp/src/index.ts"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ai-enderun",
+  "version": "0.0.1",
+  "description": "Supreme AI Orchestration Framework — Senior Discipline & Ottoman Wisdom",
+  "author": "Yusuf BEKAR <ybekar@msn.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ysf-bkr/AI-Enderun.git"
+  },
+  "homepage": "https://github.com/ysf-bkr/AI-Enderun#readme",
+  "type": "module",
+  "bin": {
+    "ai-agent-framework": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    ".gemini/agents",
+    ".gemini/docs",
+    ".gemini/templates",
+    ".gemini/PROJECT_MEMORY.md",
+    "Gemini.md",
+    "CLAUDE.md",
+    "CURSOR.md",
+    "CODEX.md",
+    "README.md",
+    "mcp.json",
+    "package.json"
+  ],
+  "scripts": {
+    "mcp:dev": "npx tsx packages/framework-mcp/src/index.ts",
+    "mcp:status": "npx socraticode status"
+  }
+}