@kavtuai/guildgate 0.1.0

package/docs/tr/yazim-kilavuzu.md

@@ -0,0 +1,116 @@
+# Yazım kuralları
+
+Bu dosya GuildGate belgeleri, hata metinleri, örnekler, sürüm notları ve depo sayfaları için yazım kurallarını belirler.
+
+Kontrol listesi, 25 Temmuz 2026 tarihinde incelenen Wikipedia **Signs of AI writing** sayfasındaki başlıklardan hazırlanmıştır. Sayfa, bu işaretlerin kesin kanıt olmadığını belirtir. GuildGate bu listeyi yazar tespiti için değil, metin düzenleme kontrolü için kullanır.
+
+Kaynak: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
+
+## İçerikten çıkarılacak kalıplar
+
+1. **Dayanaksız önem yükleme.** Küçük bir fonksiyonun sektörü değiştirdiği, kalıcı miras bıraktığı veya geniş bir dönüşümün parçası olduğu kanıt olmadan yazılmaz.
+2. **Tanınmışlık doldurması.** Basın, uzmanlar veya topluluklardan söz edilecekse kaynak adı ve desteklediği bilgi belirtilir.
+3. **Yüzeysel yorum.** Bir teknik gerçeğe genel anlam eklemek yerine istek, oturum, kayıt veya yönetici üzerindeki etkisi açıklanır.
+4. **Reklam dili.** Teknik bölümde övgü yerine davranış, sınır ve ödünleşim yazılır.
+5. **Belirsiz kaynak.** “Birçok geliştiriciye göre”, “genel olarak bilinir” veya “uzmanlar katılıyor” gibi cümleler kaynak yoksa kaldırılır.
+6. **Hazır gelecek bölümleri.** Projeye özel iş, sorumlu ve kabul ölçütü yoksa “Zorluklar ve gelecek” bölümü eklenmez.
+7. **Konu adını sürekli tekrarlama.** Genel kavramlar özel ad gibi her paragrafta yinelenmez.
+8. **Kanıtsız eğilim.** Artan talep, hızlı benimsenme veya değişen sektör beklentisi gibi ifadeler güncel kaynak olmadan kullanılmaz.
+
+## Kelime ve cümle kontrolleri
+
+Aşağıdaki İngilizce kelimeler tek başına yasak değildir. Somut bir işlevi saklıyorsa daha açık fiille değiştirilir:
+
+- additionally
+- align with
+- boasts
+- bolstered
+- crucial
+- delve
+- emphasizing
+- enduring
+- enhance
+- fostering
+- garner
+- highlight
+- interplay
+- intricate
+- key
+- landscape
+- meticulous
+- pivotal
+- robust
+- showcase
+- tapestry
+- testament
+- underscore
+- valuable
+- vibrant
+
+Ayrıca şu alışkanlıklar temizlenir:
+
+- “Olmak”, “sahip olmak” veya “yapmak” gibi açık fiillerden kaçıp süslü fiil kullanmak.
+- Anlam gerektirmediği hâlde “yalnızca X değil, aynı zamanda Y”, “X değil Y” veya “X yerine Y” karşıtlığı kurmak.
+- Cümleyi tamamlanmış göstermek için üç sıfat, üç fayda veya üç yan cümle eklemek.
+- Aynı sözcüğü tekrar etmemek uğruna zorlanmış eş anlamlılar kullanmak.
+- Paragrafa hazır giriş cümlesiyle başlamak.
+- Bölümü yeni bilgi vermeyen özet cümlesiyle kapatmak.
+
+## Biçim kontrolleri
+
+- Her kelimesi büyük harfle başlayan İngilizce başlıklar.
+- Normal kelimeleri veya hemen her maddeyi kalın yazmak.
+- İçeriği zayıf, kalın mini başlıklardan oluşan dikey listeler.
+- Virgül veya nokta yeterliyken sık uzun çizgi kullanmak.
+- Teknik belge, hata, changelog veya güvenlik metninde süs emojisi.
+- Az veriyi büyük göstermek için tablo kullanmak.
+- Kod veya komuta kıvrımlı tırnak kopyalamak.
+- Başlık seviyelerini atlamak.
+- Her başlıktan önce yatay çizgi eklemek.
+- Markdown göstermeyen alana Markdown yapıştırmak.
+
+## Kullanıcıya konuşan hazır metinler
+
+Yayımlanmış dosyada asistan konuşması bulunmaz:
+
+- Devam etme, genişletme veya başka bir konuda yardım teklifleri.
+- Bilgi kesim tarihi açıklamaları.
+- Okuyucunun ne isteyebileceğine ilişkin tahminler.
+- “İşte düzenlenmiş sürüm”, “elbette” veya “umarım yardımcı olur” gibi çerçeve cümleleri.
+- `[isim ekle]`, `[kaynak ekle]` veya `TODO` biçiminde boş yerler.
+- Şablon talimatları.
+- Prompt, üretim yöntemi veya ret açıklaması.
+
+## Reddedilecek işaretleme ve kaynak kalıntıları
+
+Yayın kontrolü şunları bulmalıdır:
+
+- Bozuk Markdown kod blokları, bağlantılar, referanslar veya HTML parçaları.
+- Markdown dosyasında wiki işaretlemesi.
+- `contentReference`, `oaicite`, `turn0search`, `attributableIndex` veya `+1` gibi model içi kaynak dizgileri.
+- Gemini citation span, Grok card, DeepSeek dagger, Perplexity yükleme referansı veya `:::writing` bloğu.
+- Var olmayan şablon, kategori, dosya, import, komut, ortam değişkeni veya paket export’u.
+- Kaynak bağlantısında `utm_source` gibi takip parametreleri.
+- Açılmayan ya da yanındaki cümleyi desteklemeyen DOI, ISBN, paket veya belge bağlantısı.
+- Tanımlanıp kullanılmayan kaynaklar.
+
+## Depoya özel kurallar
+
+1. Her dosyada tek dil kullanılır. `README.md` İngilizce, `README.tr.md` Türkçedir.
+2. İşlemi yapan adlandırılır. Uygun olduğunda “sistem” yerine çekirdek, sürücü, uygulama, Discord veya yönetici yazılır.
+3. Hata adı belirtilir. “Bir sorun oluştu” yerine `CSRF_INVALID`, `RATE_LIMITED` veya gerçek koşul yazılır.
+4. Garanti ve öneri ayrılır. “Üretimde HTTP origin reddedilir” garantidir. “Birden fazla instance için Redis kullanın” öneridir.
+5. Sorumluluk belirtilir. Transaction, şema göçü, proxy güveni, gizli değer saklama ve yedekleme, GuildGate açıkça uygulamadıkça uygulamaya aittir.
+6. Mutlak güvenlik iddiası kullanılmaz. “Kırılamaz”, “sıfır risk”, “tam güvenli” veya “hatasız” yazılmaz.
+7. Örnekler derlenebilir olmalı veya sözde kod olduğu açıkça belirtilmelidir.
+8. Örnekteki her ortam değişkeni `.env.example` dosyasında bulunmalı ya da örneğin yanında açıklanmalıdır.
+9. Belgede kullanılan her public export, `package.json` ve derlenmiş tip dosyalarında bulunmalıdır.
+10. Paragraflar taranabilir tutulur; tek cümle sırf görünüm için madde listesine bölünmez.
+
+## Sürüm öncesi kontrol
+
+- Yukarıdaki kelimeler depoda aranır ve her eşleşme incelenir.
+- Model kaynak kalıntıları ve boş köşeli parantezler aranır.
+- Bağlantılar, kod örnekleri, testler, tip kontrolü, paket dry-run ve doctor komutu çalıştırılır.
+- Değişen her sayfa bir kez düzenleme yapmadan okunur. Davranışı açıklamadan önem iddiası kuran cümleler işaretlenir.
+- İnceleyen kişiden “insan gibi duruyor mu” değil, doğru ve sınanabilir olup olmadığını kontrol etmesi istenir.

package/docs/uml/action-sequence.mmd

@@ -0,0 +1,39 @@
+sequenceDiagram
+  autonumber
+  actor Browser
+  participant Adapter as HTTP Adapter
+  participant Kernel as GuildGate Kernel
+  participant Session as SessionStore
+  participant Policy as PolicyStore
+  participant Limit as RateLimitStore
+  participant Idem as IdempotencyStore
+  participant Lock as LockStore
+  participant App as Application execute()
+  participant Cache as CacheStore
+  participant Outbox as OutboxStore
+  participant Audit as AuditStore
+
+  Browser->>Adapter: PATCH + cookie + CSRF + idempotency key
+  Adapter->>Kernel: execute(action, request)
+  Kernel->>Session: resolve(hash(token))
+  Session-->>Kernel: session / missing / rotated
+  Kernel->>Kernel: exact origin and CSRF checks
+  Kernel->>Kernel: parse input and resolve resource
+  Kernel->>Policy: maintenance and block checks
+  Policy-->>Kernel: current policy decision
+  Kernel->>Limit: atomic hit(action subject)
+  Limit-->>Kernel: allowed, remaining, reset
+  Kernel->>Kernel: application or Discord authorization
+  Kernel->>Idem: begin(key, request hash)
+  Idem-->>Kernel: started / replay / conflict / inflight
+  Kernel->>Lock: acquire(resource lease)
+  Lock-->>Kernel: acquired
+  Kernel->>App: execute(context, parsed input, abort signal)
+  App-->>Kernel: committed result
+  Kernel->>Cache: deleteByTags(tags)
+  Kernel->>Outbox: enqueue(event)
+  Kernel->>Idem: complete(key, result)
+  Kernel->>Audit: write(result and policy version)
+  Kernel->>Lock: release(compare token)
+  Kernel-->>Adapter: typed result and session metadata
+  Adapter-->>Browser: response and optional rotated cookie

package/docs/uml/components.mmd

@@ -0,0 +1,84 @@
+classDiagram
+  direction LR
+
+  class Application {
+    +HTTP routes
+    +Database transactions
+    +Policy decisions
+    +Schema validation
+  }
+
+  class GuildGateKernel {
+    +action(definition)
+    +execute(action, request)
+    +createSession(input)
+    +revokeUserSessions(userId)
+  }
+
+  class SessionManager {
+    +create(input)
+    +resolve(token)
+    +revokeToken(token)
+    +revokeAll(userId)
+  }
+
+  class DiscordOAuthClient {
+    +beginLogin(input)
+    +completeLogin(input)
+    +getAccessToken(userId)
+    +revoke(userId)
+  }
+
+  class DiscordGuildAuthorizer {
+    +inspect(input)
+    +require(policy)
+  }
+
+  class GuildGateStores {
+    <<interface>>
+    +SessionStore sessions
+    +OAuthStateStore oauthStates
+    +OAuthCredentialStore credentials
+    +RateLimitStore rateLimits
+    +CacheStore cache
+    +IdempotencyStore idempotency
+    +LockStore locks
+    +AuditStore audit
+    +OutboxStore outbox
+    +PolicyStore policies
+  }
+
+  class RealtimeHub {
+    +attach(connection)
+    +subscribe(channel)
+    +publish(event)
+    +revokeSession(sessionIdHash)
+  }
+
+  class FrameworkAdapter {
+    <<interface>>
+    +translateRequest()
+    +writeResponse()
+  }
+
+  class DiscordAPI {
+    <<external>>
+  }
+
+  class DatabaseOrCache {
+    <<external>>
+  }
+
+  Application --> FrameworkAdapter
+  FrameworkAdapter --> GuildGateKernel
+  Application --> GuildGateKernel
+  GuildGateKernel --> SessionManager
+  GuildGateKernel --> GuildGateStores
+  DiscordOAuthClient --> GuildGateKernel
+  DiscordOAuthClient --> GuildGateStores
+  DiscordOAuthClient --> DiscordAPI
+  DiscordGuildAuthorizer --> DiscordOAuthClient
+  DiscordGuildAuthorizer --> DiscordAPI
+  RealtimeHub --> SessionManager
+  RealtimeHub --> GuildGateStores
+  GuildGateStores --> DatabaseOrCache

package/docs/uml/deployment.mmd

@@ -0,0 +1,19 @@
+flowchart LR
+  B[Browser] -->|HTTPS| P[Reverse proxy]
+  P --> A1[Dashboard instance A]
+  P --> A2[Dashboard instance B]
+
+  A1 --> D[(Durable database)]
+  A2 --> D
+  A1 --> R[(Redis or atomic temporary store)]
+  A2 --> R
+  A1 --> X[Discord API]
+  A2 --> X
+
+  D -->|credentials audit policies outbox| W[Outbox worker]
+  W --> Q[Realtime transport or event bus]
+  Q --> A1
+  Q --> A2
+
+  note1[Application controls schema migrations backup retention and proxy trust]
+  D --- note1

package/docs/uml/oauth-sequence.mmd

@@ -0,0 +1,30 @@
+sequenceDiagram
+  autonumber
+  actor Browser
+  participant App as Application
+  participant OAuth as DiscordOAuthClient
+  participant State as OAuthStateStore
+  participant Discord as Discord OAuth2 API
+  participant Credentials as OAuthCredentialStore
+  participant Session as SessionManager
+
+  Browser->>App: GET /auth/discord
+  App->>OAuth: beginLogin(returnTo, locale)
+  OAuth->>State: put(hash(state), hash(browser nonce), expiry)
+  OAuth-->>App: authorization URL and HttpOnly nonce cookie
+  App-->>Browser: Set-Cookie and redirect
+  Browser->>Discord: authorization request with state
+  Discord-->>Browser: redirect with code and state
+  Browser->>App: GET callback + nonce cookie
+  App->>OAuth: completeLogin(code, state, nonce)
+  OAuth->>State: consume(hash(state))
+  State-->>OAuth: one record or null
+  OAuth->>Discord: exchange code
+  Discord-->>OAuth: access and refresh tokens
+  OAuth->>Discord: GET current user and guilds
+  Discord-->>OAuth: user and guild list
+  OAuth->>Credentials: store encrypted token record
+  OAuth->>Session: create new opaque session
+  Session-->>OAuth: raw token once and stored hash
+  OAuth-->>App: user, guilds, session cookie, local return path
+  App-->>Browser: clear nonce cookie, set session cookie, redirect

package/docs/uml/realtime-sequence.mmd

@@ -0,0 +1,28 @@
+sequenceDiagram
+  autonumber
+  actor Browser
+  participant Transport as WebSocket Transport
+  participant Hub as RealtimeHub
+  participant Session as SessionManager
+  participant Limit as RateLimitStore
+  participant Authz as Application Authorizer
+
+  Browser->>Transport: connection with Origin and session cookie
+  Transport->>Hub: attach(connection, origin, session token)
+  Hub->>Session: resolve(token)
+  Session-->>Hub: active session
+  Hub-->>Browser: ready
+  Browser->>Transport: subscribe guild:123
+  Transport->>Hub: subscribe(connection, channel)
+  Hub->>Authz: authorize(session, channel)
+  Authz-->>Hub: allowed
+  Hub-->>Browser: subscribed
+  Browser->>Transport: client message
+  Transport->>Hub: acceptMessage(payload)
+  Hub->>Limit: atomic message limit hit
+  Limit-->>Hub: allowed
+  Hub-->>Transport: parsed payload
+  Note over Hub: Publish checks channel membership and buffered bytes
+  Hub-->>Browser: versioned event
+  Session-->>Hub: session revoked by application
+  Hub-->>Browser: close 1008

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@kavtuai/guildgate",
+  "version": "0.1.0",
+  "description": "Security and control primitives for Discord bot dashboards.",
+  "type": "module",
+  "license": "MIT",
+  "author": "kavtuai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kavtuai/guildgate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Kavtuai/guildgate/issues"
+  },
+  "homepage": "https://github.com/Kavtuai/guildgate#readme",
+  "keywords": [
+    "discord",
+    "dashboard",
+    "oauth2",
+    "security",
+    "rate-limit",
+    "cache",
+    "websocket",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md",
+    "README.tr.md",
+    "CHANGELOG.md",
+    "TEST_REPORT.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./discord": {
+      "types": "./dist/discord.d.ts",
+      "import": "./dist/discord.js"
+    },
+    "./fastify": {
+      "types": "./dist/fastify.d.ts",
+      "import": "./dist/fastify.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    },
+    "./realtime": {
+      "types": "./dist/realtime.d.ts",
+      "import": "./dist/realtime.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "bin": {
+    "guildgate-doctor": "bin/guildgate-doctor.mjs",
+    "guildgate-writing-check": "bin/guildgate-writing-check.mjs"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build && npm run writing:check && node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check",
+    "writing:check": "node ./bin/guildgate-writing-check.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3"
+  }
+}