@kavtuai/guildgate 0.1.0

package/README.tr.md

@@ -0,0 +1,397 @@
+# GuildGate
+
+[English documentation](./README.md)
+
+GuildGate, Discord bot panellerinin sunucu tarafı için hazırlanmış bir TypeScript kütüphanesidir. Oturum kayıtlarını, Discord OAuth state doğrulamasını, CSRF ve origin kontrollerini, sunucu izinlerini, istek sınırlarını, idempotency kayıtlarını, kaynak kilitlerini, zaman aşımını, cache temizliğini, denetim kayıtlarını, outbox olaylarını ve yetkili gerçek zamanlı abonelikleri yönetir.
+
+Arayüz üretmez ve veritabanınızı seçmez. Her depolama bölümü bir TypeScript arayüzüdür. PostgreSQL, MySQL, MongoDB, SQLite, Redis, mevcut ORM yapınız veya özel bir veri servisi kullanılabilir.
+
+Paket: `@kavtuai/guildgate`  
+Sürüm: `0.1.0`  
+Çalışma ortamı: Node.js 22 veya üzeri
+
+## Durum
+
+Bu depo ilk açık kaynak sürüm adayıdır. TypeScript derlemesi ve paketteki testler geçmektedir. Discord OAuth, üretim Redis sunucusu ve üçüncü taraf veritabanı sürücüleri, yayına alınacak uygulamada ayrıca entegrasyon testinden geçirilmelidir.
+
+Hiçbir kütüphane, uygulamanın güvenlik hatası içermediğini garanti edemez. GuildGate tekrar edilen güvenlik işlerini azaltır, üretimde tehlikeli ayarları reddeder ve politika yönetimini uygulama sahibine bırakır. Üretim ortamında kod incelemesi, bağımlılık kontrolü, izleme, yedekleme ve risk seviyesine göre dış güvenlik incelemesi yine gereklidir.
+
+## Kurulum
+
+Paket npm üzerinde yayımlandıktan sonra:
+
+```bash
+npm install @kavtuai/guildgate
+```
+
+Bu kaynak paketini yayımlamadan önce denemek için:
+
+```bash
+npm install
+npm test
+```
+
+## Pakette bulunanlar
+
+- Sunucu tarafında tutulan, içeriği anlamsız oturum kimlikleri.
+- Oturum süresi, boşta kalma süresi, kimlik yenileme, kullanıcı başına oturum sınırı ve iptal.
+- Tek kullanımlık `state` kaydı ve tarayıcı nonce çerezi kullanan Discord authorization-code girişi.
+- Uygulamanın verdiği anahtar takımıyla şifrelenen OAuth access ve refresh token kayıtları.
+- Yazma isteklerinde tam origin kontrolü ve oturuma bağlı CSRF tokenı.
+- Discord izinleri için `BigInt` işlemleri.
+- Kullanıcı ve botun sunucu izinlerini ayrı ayrı kontrol etme.
+- Panel okuma ve yazma işlemleri için denetimli `action()` API’si.
+- İşlem bazlı limit, idempotency, kaynak kilidi, zaman aşımı, denetim kaydı, cache etiketi ve gerçek zamanlı olay desteği.
+- Test ve yerel geliştirme için bellek sürücüleri.
+- Kısa ömürlü ve dağıtık veriler için Redis sürücüleri.
+- Runtime bağımlılığı eklemeyen Fastify ve Express bağlayıcıları.
+- WebSocket bağlayıcıları için oturum kontrollü gerçek zamanlı merkez.
+- Birbirine karışmayan, uygulama tarafından değiştirilebilen Türkçe ve İngilizce hata metinleri.
+- Mermaid UML dosyaları, tehdit modeli, veri sürücüsü sözleşmeleri ve yayın iş akışları.
+
+## Beş dakikalık yerel örnek
+
+Bellek sürücüsü test ve tek süreçli yerel geliştirme içindir. Üretim veritabanı değildir.
+
+```ts
+import {
+  createGuildGate,
+  createMemoryStoreBundle,
+} from "@kavtuai/guildgate";
+
+const stores = createMemoryStoreBundle();
+
+const gate = createGuildGate({
+  app: {
+    name: "Discord Bot Panelim",
+    environment: "development",
+    baseUrl: "http://localhost:3000",
+  },
+  owners: [process.env.BOT_OWNER_ID!],
+  locale: {
+    default: "tr",
+    messages: {
+      tr: { MAINTENANCE_MODE: "Bakım sırasında ayar değiştirilemez." },
+    },
+  },
+  security: {
+    allowedOrigins: ["http://localhost:3000"],
+    csrfSecret: process.env.GUILDGATE_CSRF_SECRET!,
+    auditIpSalt: process.env.GUILDGATE_AUDIT_IP_SALT!,
+    session: {
+      ttlMs: 12 * 60 * 60_000,
+      idleTimeoutMs: 30 * 60_000,
+      rotateAfterMs: 15 * 60_000,
+      maximumSessionsPerUser: 5,
+    },
+  },
+  stores,
+});
+```
+
+Gizli değerleri kaynak koduna yazmayın. Rastgele değer üretmek için:
+
+```bash
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
+```
+
+## Denetimli panel işlemi
+
+İşlemi koruyan kurallar aynı tanımda yer alır.
+
+```ts
+const ayarlariGuncelle = gate.action({
+  name: "guild.settings.update",
+
+  parse(value) {
+    const body = value as Record<string, unknown>;
+    if (typeof body.guildId !== "string") throw new Error("guildId gerekli");
+    if (typeof body.revision !== "number") throw new Error("revision gerekli");
+    return {
+      guildId: body.guildId,
+      revision: body.revision,
+      settings: body.settings,
+    };
+  },
+
+  resource: (input) => ({ type: "guild", id: input.guildId }),
+
+  rateLimit: {
+    limit: 20,
+    windowMs: 60_000,
+    key: (context, input) => `${context.userId}:${input.guildId}`,
+  },
+
+  idempotency: {
+    ttlMs: 10 * 60_000,
+    scope: (context, input) => `${context.userId}:${input.guildId}`,
+  },
+
+  concurrency: {
+    key: (_context, input) => `guild-settings:${input.guildId}`,
+    ttlMs: 8_000,
+    waitMs: 500,
+  },
+
+  timeoutMs: 5_000,
+
+  authorize: async (context) => {
+    return context.userId
+      ? { allowed: true }
+      : { allowed: false, code: "AUTHENTICATION_REQUIRED" };
+  },
+
+  async execute(context, input) {
+    // Transaction ve revision kontrolü uygulamanın veritabanı katmanındadır.
+    return database.transaction(async (tx) => {
+      return tx.guildSettings.updateWithRevision({
+        guildId: input.guildId,
+        expectedRevision: input.revision,
+        settings: input.settings,
+        actorId: context.userId!,
+      });
+    });
+  },
+
+  audit: {
+    changes: (result) => ({ revision: result.revision }),
+  },
+
+  cache: {
+    invalidateTags: (result) => [`guild:${result.guildId}`],
+  },
+
+  realtime: {
+    delivery: "outbox",
+    events: (result) => [{
+      event: "guild.settings.updated",
+      channel: `guild:${result.guildId}`,
+      data: { revision: result.revision },
+    }],
+  },
+});
+```
+
+Tarayıcıdan gelen yazma isteğinde oturum çerezi, CSRF tokenı ve idempotency anahtarı bulunmalıdır:
+
+```http
+PATCH /api/guilds/123/settings
+Origin: https://panel.example.com
+X-CSRF-Token: <oturuma-bagli-token>
+Idempotency-Key: <rastgele-istek-kimligi>
+```
+
+## Discord girişi
+
+```ts
+import { createTokenCipher } from "@kavtuai/guildgate";
+import { createDiscordOAuth } from "@kavtuai/guildgate/discord";
+
+const cipher = createTokenCipher({
+  activeKeyId: "2026-01",
+  keys: {
+    "2026-01": process.env.GUILDGATE_TOKEN_KEY_BASE64!,
+  },
+});
+
+const discord = createDiscordOAuth({
+  kernel: gate,
+  cipher,
+  config: {
+    clientId: process.env.DISCORD_CLIENT_ID!,
+    clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+    redirectUri: "https://panel.example.com/auth/discord/callback",
+    scopes: ["identify", "guilds"],
+  },
+});
+```
+
+Girişi başlatma:
+
+```ts
+const login = await discord.beginLogin({ returnTo: "/dashboard", locale: "tr" });
+response.header("set-cookie", login.stateCookie);
+response.redirect(login.authorizationUrl);
+```
+
+Callback:
+
+```ts
+const result = await discord.completeLogin({
+  code: request.query.code,
+  state: request.query.state,
+  stateCookie: request.cookies["__Host-guildgate.oauth"],
+});
+
+response.header("set-cookie", [result.setCookie, result.clearStateCookie]);
+response.redirect(result.returnTo);
+```
+
+Callback yalnızca site içindeki bir path’e yönlendirir. İstekten gelen harici alan adına yönlendirme yapmaz.
+
+## Sunucu izinleri
+
+```ts
+import { createDiscordGuildAuthorizer } from "@kavtuai/guildgate/discord";
+
+const guildAccess = createDiscordGuildAuthorizer({
+  oauth: discord,
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  botUserId: process.env.DISCORD_BOT_USER_ID!,
+  cache: gate.cache,
+});
+
+const kaydet = gate.action({
+  name: "guild.settings.save",
+  parse: ayarlariDogrula,
+  resource: (input) => ({ type: "guild", id: input.guildId }),
+  authorize: guildAccess.require({
+    guildId: (input) => input.guildId,
+    userPermissions: ["MANAGE_GUILD"],
+    botPermissions: ["VIEW_CHANNEL", "MANAGE_ROLES"],
+    consistency: "live",
+  }),
+  execute: ayarlariKaydet,
+});
+```
+
+Discord’a veya güvenlik ayarlarına yazan işlemlerde canlı kontrol kullanın. Düşük riskli görüntüleme verilerinde kısa süreli cache kullanılabilir. Üye rolleri, sunucu rolleri veya bot üyeliği değiştiğinde izin cache’i temizlenmelidir.
+
+## Veritabanı seçimi
+
+Tam sözleşme `GuildGateStores` arayüzüdür:
+
+```ts
+interface GuildGateStores {
+  sessions: SessionStore;
+  oauthStates: OAuthStateStore;
+  credentials: OAuthCredentialStore;
+  rateLimits: RateLimitStore;
+  cache: CacheStore;
+  idempotency: IdempotencyStore;
+  locks: LockStore;
+  audit: AuditStore;
+  outbox: OutboxStore;
+  policies: PolicyStore;
+}
+```
+
+Kalıcı kayıtlar ana veritabanında, kısa ömürlü kayıtlar Redis’te tutulabilir:
+
+```ts
+import { composeStores, createMemoryStoreBundle } from "@kavtuai/guildgate";
+import {
+  createRedisEphemeralStores,
+  fromNodeRedis,
+} from "@kavtuai/guildgate/redis";
+
+const temporary = createRedisEphemeralStores(fromNodeRedis(redis), {
+  prefix: "mybot:guildgate",
+});
+
+const stores = composeStores(createMemoryStoreBundle(), {
+  ...temporary,
+  credentials: postgresCredentialStore,
+  audit: postgresAuditStore,
+  outbox: postgresOutboxStore,
+  policies: postgresPolicyStore,
+});
+```
+
+Bu örnekteki bellek tabanı yalnızca birleştirme mantığını göstermek içindir. Üretim uygulaması, yeniden başlatma sonrasında korunması gereken her kayıt için kalıcı bir sürücü vermelidir.
+
+Ayrıntılar: [Özel veri sürücüleri](./docs/tr/veritabani-suruculeri.md).
+
+## Fastify ve Express
+
+Bağlayıcılar framework tiplerini yapısal olarak kullanır. GuildGate, Fastify veya Express’i bağımlılık olarak kurmaz.
+
+```ts
+import { fastifyActionHandler } from "@kavtuai/guildgate/fastify";
+
+fastify.patch(
+  "/api/guilds/:guildId/settings",
+  fastifyActionHandler(gate, ayarlariGuncelle),
+);
+```
+
+```ts
+import { expressActionHandler } from "@kavtuai/guildgate/express";
+
+app.patch(
+  "/api/guilds/:guildId/settings",
+  expressActionHandler(gate, ayarlariGuncelle),
+);
+```
+
+## Gerçek zamanlı bağlantılar
+
+`createRealtimeHub()` kendi başına socket sunucusu açmaz. `RealtimeConnection` arayüzü üzerinden `ws`, uWebSockets.js, Socket.IO, Bun veya başka bir taşıyıcıya bağlanır.
+
+Bağlantı tam origin kontrolünden ve oturum doğrulamasından geçer. Her kanal aboneliği ayrı bir yetkilendirme fonksiyonuna sahiptir. Mesaj boyutu, mesaj sayısı, boşta kalma süresi, toplam bağlantı ömrü, abonelik sayısı ve yavaş istemci sınırları da uygulanır.
+
+Ayrıntılar: [Mimari](./docs/tr/mimari.md) ve [gerçek zamanlı UML sırası](./docs/uml/realtime-sequence.mmd).
+
+## Sahip yönetimi
+
+Yapılandırılan sahip kimlikleriyle korunmuş yönetim endpoint’leri hazırlanabilir. Çekirdekte şu işlemler bulunur:
+
+```ts
+await gate.owner.setMaintenance({ enabled: true, reason: "veritabanı bakımı" });
+await gate.owner.block({ subjectType: "user", subjectId: "123", reason: "kötüye kullanım" });
+await gate.owner.unblock("user", "123");
+await gate.revokeUserSessions("123");
+```
+
+Sahip endpoint’leri de oturum, CSRF, origin, rate limit ve denetim kontrollerinden geçmelidir. Bu metotları sahip yetkisi kontrol edilmemiş açık endpoint’lerden çağırmayın.
+
+## Üretim kuralları
+
+GuildGate üretimde şu ayarları kabul etmez:
+
+- HTTPS kullanmayan uygulama adresi.
+- Boş origin izin listesi.
+- HTTP veya localhost origin değeri.
+- `Secure` özelliği kapalı oturum çerezi.
+- HTTPS kullanmayan Discord callback adresi.
+- Kısa CSRF ve IP hashleme sırları.
+
+Uygulamanın sorumlulukları:
+
+- Reverse proxy güven ayarını doğru kurmak ve gerçek istemci IP’sini güvenli biçimde almak.
+- Bot tokenını, OAuth sırlarını, şifreleme anahtarlarını ve veritabanı bilgilerini kaynak koddan uzak tutmak.
+- Sürücü destekliyorsa veritabanı değişikliklerini transaction içinde yapmak.
+- Aynı kaydı birden fazla yönetici düzenleyebiliyorsa revision kontrolü kullanmak.
+- Denetim ve outbox kayıtları için saklama süresi belirlemek.
+- Kalıcı verileri yedeklemek ve geri yükleme işlemini test etmek.
+- Destekleyen HTTP ve veritabanı istemcilerine iptal sinyali geçirmek.
+- Büyük sürümlerden önce Discord izinlerini ve API değişikliklerini kontrol etmek.
+
+## Depo kontrolleri
+
+```bash
+npm run typecheck
+npm test
+npm run pack:check
+node ./bin/guildgate-doctor.mjs
+```
+
+Doctor komutu ortam değişkenlerini yerelde kontrol eder. Gizli değerleri başka bir servise göndermez.
+
+## Belgeler
+
+- [Kurulum ve ilk yayın](./docs/tr/kurulum.md)
+- [Mimari](./docs/tr/mimari.md)
+- [Özel veri sürücüleri](./docs/tr/veritabani-suruculeri.md)
+- [Sahip yönetimi](./docs/tr/sahip-yonetimi.md)
+- [Tehdit modeli](./docs/tr/tehdit-modeli.md)
+- [Yazım kuralları](./docs/tr/yazim-kilavuzu.md)
+- [Araştırma notları](./docs/tr/arastirma-notlari.md)
+- [Yerel test raporu](./TEST_REPORT.md)
+- [Sürüm planı](./ROADMAP.md)
+- [Güvenlik bildirimi](./SECURITY.md)
+- [UML dosyaları](./docs/uml)
+
+## Lisans
+
+MIT. Bkz. [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security policy
+
+## Supported versions
+
+Until `1.0.0`, only the newest released minor version receives security fixes. After `1.0.0`, the support window will be stated here before each branch is opened.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability.
+
+Use GitHub private vulnerability reporting for `kavtuai/guildgate` when the repository is available. Include:
+
+- Affected version or commit.
+- Required configuration.
+- Reproduction steps or a small proof of concept.
+- Expected and observed behavior.
+- Possible impact.
+- Any temporary mitigation already tested.
+
+Do not include real bot tokens, OAuth secrets, session cookies, database credentials, or user data. Replace them with test values.
+
+## Response process
+
+The maintainer will first confirm receipt, reproduce the report, assign severity, and decide whether a private patch branch is needed. Publication timing depends on impact, fix availability, and coordination with affected adapter maintainers.
+
+A security release should include:
+
+- A fixed package version.
+- Affected version range.
+- Concrete impact and prerequisites.
+- Upgrade or mitigation steps.
+- Credit when the reporter requests it.
+
+## Security boundaries
+
+The package rejects several unsafe production settings and implements controls described in `docs/threat-model.md`. It does not configure the host, proxy, TLS, firewall, database roles, secret manager, backups, or application-specific authorization policy.

package/TEST_REPORT.md

@@ -0,0 +1,50 @@
+# Test report
+
+Date: 2026-07-25  
+Package: `@kavtuai/guildgate@0.1.0`
+
+## Local toolchain
+
+- Node.js: 22.16.0
+- npm: 10.9.2
+- TypeScript compiler: 5.8.3
+
+## Passed checks
+
+- Strict TypeScript build.
+- Type-only check without emit.
+- Repository writing check.
+- npm package dry-run.
+- Local offline installation of the generated `.tgz` package into an empty consumer project.
+- Import checks for every public package subpath.
+- Production doctor check with generated test secrets and HTTPS test URLs.
+- Public declaration scan for accidental `Buffer` or Node namespace requirements.
+- Model citation artifact and unfinished placeholder scan.
+
+## Automated behavior tests
+
+Eleven tests pass:
+
+1. Protected actions reject missing sessions and missing CSRF tokens.
+2. Idempotency replays the first result and rejects changed payloads.
+3. Rate limits and owner maintenance policy are applied.
+4. Cache tags invalidate matching entries.
+5. A cache failure after commit does not repeat the domain operation.
+6. Error messages remain in the selected locale and support application overrides.
+7. Discord high-bit permissions retain precision with `BigInt`.
+8. Base guild permissions combine the everyone role and member roles.
+9. Discord OAuth state is browser-bound, single-use, encrypted at rest, and rejects external return URLs.
+10. Realtime subscriptions require authorization and explicit session revocation closes sockets.
+11. Periodic realtime session validation closes a socket revoked outside the hub.
+
+## Not run in this container
+
+- A real Discord OAuth callback.
+- A real Discord bot permission request.
+- A real Redis server.
+- PostgreSQL, MongoDB, MySQL, or SQLite integration.
+- Fastify and Express example installation with their external framework dependencies.
+- Dependency installation from the npm registry. Registry access from the build container timed out, so this archive does not contain a generated `package-lock.json`.
+- External security review and load test.
+
+These tests must be completed in the target repository before a production `1.0.0` release. The package name and GitHub repository name were not published or reserved by this build.

package/bin/guildgate-doctor.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { Buffer } from "node:buffer";
+
+const isJson = process.argv.includes("--json");
+const environment = process.env.GUILDGATE_ENVIRONMENT ?? process.env.NODE_ENV ?? "development";
+const results = [];
+
+check("Node.js 22 or newer", Number(process.versions.node.split(".")[0]) >= 22, process.versions.node);
+checkRequired("DISCORD_CLIENT_ID");
+checkRequired("DISCORD_CLIENT_SECRET");
+checkRequired("DISCORD_REDIRECT_URI");
+checkRequired("GUILDGATE_CSRF_SECRET");
+checkRequired("GUILDGATE_AUDIT_IP_SALT");
+checkRequired("GUILDGATE_TOKEN_KEY_BASE64");
+
+checkLength("GUILDGATE_CSRF_SECRET", 32);
+checkLength("GUILDGATE_AUDIT_IP_SALT", 16);
+checkBase64Key("GUILDGATE_TOKEN_KEY_BASE64", 32);
+
+if (process.env.DISCORD_REDIRECT_URI) {
+  checkUrl("Discord redirect URI is valid", process.env.DISCORD_REDIRECT_URI, environment === "production");
+}
+if (process.env.GUILDGATE_BASE_URL) {
+  checkUrl("Application base URL is valid", process.env.GUILDGATE_BASE_URL, environment === "production");
+} else {
+  results.push({ name: "GUILDGATE_BASE_URL", status: environment === "production" ? "fail" : "warn", detail: "not set" });
+}
+
+const origins = (process.env.GUILDGATE_ALLOWED_ORIGINS ?? "")
+  .split(",")
+  .map((value) => value.trim())
+  .filter(Boolean);
+
+if (environment === "production") {
+  check("Production origin list is not empty", origins.length > 0, origins.length ? origins.join(", ") : "not set");
+  for (const origin of origins) {
+    try {
+      const url = new URL(origin);
+      check(`Origin uses HTTPS: ${origin}`, url.protocol === "https:", url.protocol);
+      check(`Origin is not localhost: ${origin}`, !["localhost", "127.0.0.1", "::1"].includes(url.hostname), url.hostname);
+    } catch {
+      check(`Origin is a valid URL: ${origin}`, false, "invalid URL");
+    }
+  }
+}
+
+if (isJson) {
+  console.log(JSON.stringify({ environment, results }, null, 2));
+} else {
+  console.log(`GuildGate doctor (${environment})`);
+  for (const result of results) {
+    const mark = result.status === "pass" ? "PASS" : result.status === "warn" ? "WARN" : "FAIL";
+    console.log(`${mark.padEnd(4)}  ${result.name}${result.detail ? ` — ${result.detail}` : ""}`);
+  }
+}
+
+process.exitCode = results.some((result) => result.status === "fail") ? 1 : 0;
+
+function checkRequired(name) {
+  check(`${name} is set`, Boolean(process.env[name]), process.env[name] ? "present" : "missing");
+}
+
+function checkLength(name, minimumBytes) {
+  const value = process.env[name];
+  if (!value) return;
+  check(`${name} contains at least ${minimumBytes} bytes`, Buffer.byteLength(value) >= minimumBytes, `${Buffer.byteLength(value)} bytes`);
+}
+
+function checkBase64Key(name, expectedBytes) {
+  const value = process.env[name];
+  if (!value) return;
+  try {
+    const decoded = Buffer.from(value, "base64");
+    check(`${name} decodes to ${expectedBytes} bytes`, decoded.length === expectedBytes, `${decoded.length} bytes`);
+  } catch {
+    check(`${name} is valid base64`, false, "decode failed");
+  }
+}
+
+function checkUrl(name, value, requireHttps) {
+  try {
+    const url = new URL(value);
+    check(name, !requireHttps || url.protocol === "https:", `${url.protocol}//${url.host}`);
+  } catch {
+    check(name, false, "invalid URL");
+  }
+}
+
+function check(name, passed, detail) {
+  results.push({ name, status: passed ? "pass" : "fail", detail });
+}

package/bin/guildgate-writing-check.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const includedRoots = [
+  "README.md",
+  "README.tr.md",
+  "CHANGELOG.md",
+  "ROADMAP.md",
+  "SECURITY.md",
+  "CONTRIBUTING.md",
+  "CODE_OF_CONDUCT.md",
+  "docs",
+];
+const excluded = new Set([
+  "docs/WRITING_STYLE.md",
+  "docs/tr/yazim-kilavuzu.md",
+]);
+
+const hardPatterns = [
+  ["assistant boilerplate", /\b(hope this helps|certainly[,!]|here is a polished|in today's fast-paced world|it is important to note)\b/i],
+  ["decorative contrast", /\bnot only\b[^.\n]{0,160}\bbut also\b/i],
+  ["provider citation artifact", /contentReference|oaicite|turn\d+(?:search|view|fetch)|attributableIndex|ppl-ai-file-upload|grok_card|:::writing/i],
+  ["tracking query", /[?&]utm_(?:source|medium|campaign|term|content)=/i],
+  ["unfinished placeholder", /\[(?:insert|add source|add name|placeholder)[^\]]*\]/i],
+];
+
+const watchedWords = /\b(additionally|boasts|bolstered|crucial|delve|enduring|fostering|garner|interplay|intricate|landscape|meticulous|pivotal|robust|showcase|tapestry|testament|underscore|vibrant)\b/gi;
+const failures = [];
+const reviews = [];
+
+for (const target of includedRoots) {
+  const full = join(root, target);
+  for (const file of await filesUnder(full)) {
+    const name = relative(root, file).replaceAll("\\", "/");
+    if (excluded.has(name) || ![".md", ".mmd"].includes(extname(file))) continue;
+    const text = await readFile(file, "utf8");
+    for (const [label, pattern] of hardPatterns) {
+      const match = text.match(pattern);
+      if (match) failures.push({ file: name, label, value: match[0] });
+    }
+    const matches = [...text.matchAll(watchedWords)].map((match) => match[0]);
+    if (matches.length) reviews.push({ file: name, words: [...new Set(matches.map((word) => word.toLowerCase()))] });
+  }
+}
+
+for (const item of failures) console.error(`FAIL ${item.file}: ${item.label}: ${item.value}`);
+for (const item of reviews) console.error(`REVIEW ${item.file}: ${item.words.join(", ")}`);
+
+if (failures.length || reviews.length) {
+  console.error(`Writing check found ${failures.length} failure(s) and ${reviews.length} review item(s).`);
+  process.exitCode = 1;
+} else {
+  console.log("Writing check passed.");
+}
+
+async function filesUnder(path) {
+  try {
+    const entries = await readdir(path, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) files.push(...await filesUnder(child));
+      else if (entry.isFile()) files.push(child);
+    }
+    return files;
+  } catch (error) {
+    if (error?.code === "ENOTDIR") return [path];
+    throw error;
+  }
+}