create-devoplus-one-app 0.0.0-stage → 0.1.0-next.158

package/templates/AGENT_GUIDE.md.tpl

@@ -0,0 +1,36 @@
+# {{nameTr}} — Devoplus yapay zekâsı için rehber
+
+Bu dosyayı **Devoplus yapay zekâsı** okur: kullanıcı Devoplus'ta bir soru sorduğunda bu uygulamanın araçlarını ne zaman
+ve nasıl kullanacağını buradan öğrenir (uygulama adresinde `/.well-known/one-agent.md`). Bir aracı eklerken,
+değiştirirken ya da kaldırırken bu dosyayı AYNI değişiklikte güncelleyin; yayın kapısı dört başlığı ve her aracın adını
+arar. Teknik olmayan bir okur için değil, yapay zekâ için yazılır: kısa, kesin, örnekli.
+
+## Uygulama ne yapar
+
+{{nameTr}}, kullanıcının kişisel notlarını tutar. Kullanıcı "notlarım", "son yazdığım not" gibi şeyler sorduğunda bu
+uygulamaya başvurun. (Uygulamanız büyüdükçe bu bölümü güncelleyin: hangi iş sorularının bu uygulamaya ait olduğunu ve
+hangilerinin AİT OLMADIĞINI yazın.)
+
+## Veri
+
+- **Not** (`notes` tablosu): `id`, `text` (en çok 500 karakter), `created_at` (UTC). Her not bir kullanıcıya aittir.
+- Her kullanıcı yalnız KENDİ notlarını görür; başka bir kişinin notu hiçbir araçla okunamaz.
+- Veri yalnız bu portalın kurulumundadır.
+
+## Araçlar
+
+### `list-notes` — notları listele (salt okunur)
+
+- **Ne zaman:** kullanıcı kendi notlarını ya da son notunu sorduğunda.
+- **Girdi:** `limit` — 1-50 arası tam sayı, verilmezse 10. Başka alan göndermeyin; reddedilir.
+- **Çıktı:** `{ "notes": [{ "id": 3, "text": "…", "createdAt": "2026-10-18 09:12:00" }, …] }` — en yenisi önce. Boş
+  liste "notunuz yok" demektir.
+- **İzin:** uygulamayı kullanma izni. Hiçbir şeyi değiştirmez; kullanıcıdan onay istemeye gerek yoktur.
+
+Not EKLEMEK ya da SİLMEK için araç yoktur — bu işler uygulama ekranından yapılır.
+
+## Örnek istekler
+
+- "Son üç notumu göster." → `list-notes` (`limit: 3`)
+- "Hiç notum var mı?" → `list-notes` (`limit: 1`) → liste boşsa "Henüz notunuz yok."
+- "Bir not ekle." → araç yok; uygulamayı Devoplus Portal'da açmasını söyleyin.

package/templates/README.md.tpl

@@ -0,0 +1,58 @@
+# {{nameTr}} — Devoplus One uygulaması
+
+`create-devoplus-one-app` ile üretilmiş başlangıç noktası. Devoplus Portal içinde iframe ile çalışır; kimlik,
+kiracı ve servisler `@devoplus/one-sdk`'dan gelir. Uygulamayı geliştirecek AI aracı için kurallar **`AGENTS.md`**'dedir.
+
+## İçerik
+
+| Dosya | Amaç |
+|---|---|
+| `one.manifest.json` | Uygulamanın platforma beyanı: slug, ad, sürüm, scope'lar, servisler, menü, izin kodu (`{{permissionCode}}`), sınırlar |
+| `src/index.ts` | Giriş noktası: kabuk + `/api/me` + veritabanında notlar{{#files}} + dosyalar{{/files}}{{#cache}} + önbellek{{/cache}} |
+| `src/shell.ts` | Tek sayfalık kabuk: TR/EN metinler, açık/koyu tema, Portal köprüsü (`one:ready` / `one:token` / `one:context` / `one:resize`) |
+| `src/shell.test.ts` | Kabuk testleri (dil anahtarı eşitliği, köprü sözleşmesi) |
+| `migrations/0001_init.sql` | Veritabanı şeması; şema değişikliği yeni numaralı dosyayla gelir |
+| `AGENTS.md` | Uygulamayı yazacak AI için SDK sözleşmesi ve yasaklar |
+| `src/agent.ts` | Devoplus yapay zekâsının çağırabileceği araçların işleyicileri (beyan: manifest `agent.tools`) |
+| `AGENT_GUIDE.md` | Devoplus yapay zekâsının okuduğu kullanım rehberi (`/.well-known/one-agent.md`); araç beyanı varken ZORUNLU |
+
+## Geliştirme
+
+```bash
+pnpm install
+pnpm type-check && pnpm test && pnpm build   # build = one build: yükleme provası, hiçbir yere göndermez
+pnpm migrate   # one migrate — migrations/ altındaki SQL dosyalarını yerel veritabanına uygular (ilk çalıştırmada ve her yeni migration'da)
+pnpm dev       # one dev — uygulamayı yerelde çalıştırır; Portal başlıklarını (X-One-*) elle göndermeniz gerekir
+```
+
+> `one` komutu `@devoplus/one-sdk` ile gelir. Yerel yapılandırma, yerel veri ve paket çıktısı `.one/` altındadır
+> (depoya girmez); her komutta `one.manifest.json`'dan yeniden üretilir. Migration uygulanmadan `notes` tablosu
+> yoktur ve `/api/notes` hata döner. Gerçek yüklemede migration'ları platform sürümle birlikte uygular.
+
+> `@devoplus/one-sdk` npm'den kurulur. Kararlı sürüm çıkana kadar bağımlılık `^0.2.0-next.0` aralığıyla `next` ön
+> sürümlerini de kapsar; kararlı sürüme geçerken aralığı değiştirmeniz gerekmez (`0.2.x` aynı aralıktadır).
+
+## Kayıt → kurulum → yayın
+
+1. **Kayıt:** Devoplus Console › *Devoplus One Uygulamaları* ekranında uygulama kaydı açılır (slug `{{slug}}`, ad, scope üst
+   sınırı, izin kodu `{{permissionCode}}`). Kayıt kimlik sağlayıcıda uygulamanın client kaydını açar.
+2. **Kurulum:** aynı ekrandan uygulama bir portala kurulur (portal anahtarı). Kurulum = uygulama × portal; adres
+   `{{slug}}-<portalAnahtarı>.<ortam tabanı>` olur.
+3. **Yayın:** kod Devoplus GitLab'ına push edilir. Hat **platformundur** (proje ayarı "CI/CD configuration file" platform
+   projesindeki `one-app.gitlab-ci.yml`'yi gösterir); bu depoya `.gitlab-ci.yml` YAZILMAZ — yazılsa da okunmaz. Her MR ve
+   `test`/`uat`/`main` itişinde `prepare` koşar: `one-ci validate` (manifest · README/AGENTS · sır taraması) · bağımlılık
+   taraması · `pnpm install` · `type-check` · `test`. Dağıtım dal = ortamdır ve elle başlatılır (`deploy:<ortam>` →
+   "Run job", `ONE_PORTAL_KEY` + `ONE_PORTAL_ID`); client kimliği `one-{{slug}}`'dur. Geliştirici makinesinden doğrudan
+   yükleme yoktur. `pnpm-lock.yaml` depoya girer (hat `--frozen-lockfile` kurar). AI ile yapılan değişiklikler
+   `ai/<konu>` dalında ve `AI-Assisted:` trailer'ıyla gelir; one-ci son yayından bu yana gelen AI commit'lerini ve
+   dallarını sürüm defterine yazar (`one-ci releases`).
+4. Portal menüsünde uygulama, `{{permissionCode}}` izni atanmış kullanıcılara görünür.
+
+## Yeni yetenek eklerken
+
+- Backend verisi gerekiyorsa önce `one.manifest.json` → `scopes` (katalogdaki ad), sonra kodda `requireScope`.
+- Dosya → `services.files: true` + `FILES` + SDK `OneFiles`; önbellek → `services.cache: true` + `CACHE` + SDK `OneCache`.
+- Şema → `migrations/0002_*.sql` (var olan dosyaya dokunulmaz).
+- Kullanıcıya görünen metin iki dile birden (`STRINGS`); Türkçe, resmî "siz".
+
+Sahip: {{ownerEmail}}

package/templates/_shared/AGENTS.writes.md.tpl

@@ -0,0 +1,38 @@
+### Yazım kuralı: denetlenen her ön koşul yazım ifadesindedir (bütün şablonlar)
+
+Bir uç yazmadan önce bir şeyi denetliyorsa (kaydın durumu, kişinin sorumluluğu ya da sahipliği, üst kaydın silinmemiş
+olması, okunup yazıma taşınan bir değer, alanlar arası bir kural) o denetim yazımla AYNI SQL ifadesinin koşulunda da
+durur. Önce okuyup sonra yazmak iki ayrı adımdır: araya giren bir istek (kapatma, silme, başkasına verme, aynı kaydın
+başka bir sekmeden düzenlenmesi) koşulu bozar ve yazım yine olur.
+
+- Yazımı `src/lib/record.ts` ile yapın: `recordWrite` değerleri veri modelinin kuralıyla doğrular; `insertWhen` /
+  `updateWhen` / `removeWhen` koşulu (`when`) zorunlu ister. Etkilenen satır yoksa koşul tutmamıştır: nedeni yeniden
+  okuyup söyleyin (404 / 409), sessizce geçmeyin.
+- Birden çok satır birlikte değişiyorsa tek toplu yazım (`env.DB.batch`) kullanın ve sonraki yazımları ilkinin gerçekten
+  olduğuna bağlayın (`EXISTS …`).
+- Alanlar arası kural (ör. "bitiş başlangıçtan önce olamaz") yazımdan SONRAKİ satıra uygulanır: gövdede olmayan alan
+  satırın o anki değeridir.
+- Zamanlanmış işin damgası (ör. "hatırlatıldı") satırı seçen koşulun tamamını yeniden ister.
+- Bir koşulu bilerek yazıma koymuyorsanız nedenini kodun yanına yazın (ör. "sonuç, iki isteğin bir sırayla yapılmasıyla
+  aynıdır").
+
+### Liste kuralı: sabit sınır SESSİZCE kesmez (bütün şablonlar)
+
+- Görünürlük (kimin kaydını görürüm), sayım (toplam, ertelenen, ekip büyüklüğü) ve dışa aktarma kesik bir listeden
+  hesaplanmaz: ekip ya da kişi listesine üst sınır koymayın; sayıyı ayrı bir `COUNT` ile alın.
+- Yalnız gösterimi kısaltan bir sınır (ilk N kayıt, e-postaya sığan kalemler) kesildiğini SÖYLER: bir fazla satır okuyup
+  `truncated: true` döndürün ya da "ve N kayıt daha" yazın. Dışa aktarma sınırı aşınca eksik dosya üretmek yerine reddedin.
+- **Sayfa betiğinde de aynı kural:** açılır listenin seçenekleri, süzgeç seçenekleri ve ekrandaki sayımlar TEK SAYFALIK bir
+  istekten kurulmaz. Hazır liste uçları sayfa başına en çok 200 kayıt verir ve fazlasını hata vermeden sonraki sayfaya
+  bırakır; `?_size=200` ile kurulan seçici 201. kaydı sessizce kaybeder, 200'den büyük bir `_size` ise 400 alır ve seçici
+  hiç kurulmaz. Bunun için `loadAll('/api/<varlık>?<süzgeç>')` kullanın: bütün sayfaları toplar; en çok 25 sayfa
+  (5.000 kayıt) okur, bir sayfa yeni kayıt getirmezse de durur ve bu durumlarda listenin eksik olduğunu ekranda söyler.
+  `loadAll` başarısız olursa (`ok: false`) hatayı gösterin; boş liste gibi okumayın. `loadAll` yalnız `_size` / `_page`
+  okuyan hazır liste uçlarıyla çalışır; `page` / `limit` okuyan elle yazılmış bir uca bağlamayın (her istekte ilk sayfa
+  döner, liste eksik kalır).
+  Yalnız sayfalı gösterim (`<one-table paging="page">`) ve sunucunun tam döndürdüğü yanıtlar (ör. sunucuda hesaplanan
+  bir sayı) tek sayfayla okunur; bu durumda gerekçeyi isteğin yanına yazın.
+- `loadAll` **en iyi çabadır**: sayfalar ayrı isteklerdir ve sıra numarasıyla okunur. İki sayfa arasında kayıt eklenir,
+  silinir ya da sıralama alanı değişirse aynı kayıt iki sayfada gelebilir (kimliği aynı olan ikinci kopya atılır) ya da
+  hiçbir sayfada gelmeyebilir. Atlamayı bu yardımcı kapatamaz; kaydın kesinlikle listede olması gereken bir işte sayfa
+  betiğine güvenmeyin, kararı sunucuda verin.

package/templates/_shared/README.tail.md.tpl

@@ -0,0 +1,20 @@
+
+## Geliştirici notları
+
+Bu bölüm uygulamayı yazan kişi ya da yapay zekâ aracı içindir; kurallar **`AGENTS.md`**'dedir.
+
+```bash
+pnpm install
+pnpm type-check && pnpm test && pnpm build   # build = one build: yükleme provası, hiçbir yere göndermez
+pnpm migrate   # one migrate — migrations/ altındaki dosyaları yerel veritabanına uygular
+pnpm dev       # one dev — yerelde çalıştırır; Portal başlıklarını (X-One-*) elle göndermeniz gerekir
+pnpm data:generate   # one.data.json değişince: yeni migration + src/data/types.ts
+```
+
+- Veri modeli `one.data.json`'dadır; `migrations/` ve `src/data/types.ts` ondan **üretilir**, elle yazılmaz.
+- Kayıt: Devoplus Console › *Devoplus One Uygulamaları* (kısa ad `{{slug}}`, izin kodu `{{permissionCode}}`). Kurulum aynı
+  ekrandan portala yapılır. Yayın Devoplus GitLab hattıyla olur; geliştirici makinesinden doğrudan yükleme yoktur.
+- `@devoplus/one-sdk` npm'den kurulur; kararlı sürüm çıkana kadar bağımlılık aralığı (`^0.2.0-next.0`) `next` ön
+  sürümlerini de kapsar.
+
+Sahip: {{ownerEmail}}

package/templates/_shared/files/src/app.test.ts.tpl

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import manifest from '../one.manifest.json' with { type: 'json' }
+import { buildApp, definition } from './app.ts'
+
+// Üç yerin birbirini tutması: manifest beyanı ↔ koddaki işleyiciler ↔ sayfadaki görünümler. Biri değişip öteki
+// unutulursa Devoplus yapay zekâsı aracı bulamaz (404), platformun işi işleyici bulamaz ya da sekme boş açılır.
+const execution = { waitUntil: () => {} }
+// Platformun her isteğe yazdığı bağlam (sayfa için oturum gerekmez).
+const headers = { 'x-one-app': manifest.app.slug, 'x-one-portal-key': 'deneme', 'x-one-portal': 'a'.repeat(24), 'x-one-auth': 'anonymous' }
+
+describe('uygulama ↔ manifest', () => {
+  it('Devoplus yapay zekâsı araçları: manifest beyanı ile işleyiciler birebir', () => {
+    expect(Object.keys(definition.tools).sort()).toEqual((manifest.agent?.tools ?? []).map((t) => t.name).sort())
+  })
+
+  it('zamanlanmış görev ve kuyruk işleyicileri manifest beyanıyla birebir', () => {
+    const declared = (manifest as { jobs?: { schedules?: { name: string }[]; queues?: { name: string }[] } }).jobs
+    expect(Object.keys(definition.jobs?.schedules ?? {}).sort()).toEqual((declared?.schedules ?? []).map((s) => s.name).sort())
+    expect(Object.keys(definition.jobs?.queues ?? {}).sort()).toEqual((declared?.queues ?? []).map((q) => q.name).sort())
+  })
+
+  it('menüdeki her yol sayfayı döndürür ve o görünüm açık çizilir', async () => {
+    const app = buildApp('# rehber')
+    for (const item of manifest.navigation ?? []) {
+      const res = await app.fetch(new Request(`https://uygulama.test${item.path}`, { headers }), {} as never, execution)
+      expect(res.status, item.path).toBe(200)
+      const html = await res.text()
+      expect(html, item.path).toContain(`<section data-view="${item.path}">`)
+    }
+  })
+
+  it('tanımsız yol 404 (ayrıntı sızdırmadan)', async () => {
+    const res = await buildApp('# rehber').fetch(new Request('https://uygulama.test/yok', { headers }), {} as never, execution)
+    expect(res.status).toBe(404)
+  })
+})

package/templates/_shared/files/src/index.ts.tpl

@@ -0,0 +1,8 @@
+/// <reference path="./markdown.d.ts" />
+// {{nameTr}} — Devoplus One uygulaması ({{templateName}} şablonu, create-devoplus-one-app). Giriş noktası İNCEDİR: istekleri
+// `src/app.ts` karşılar. Burada yalnız Devoplus yapay zekâsının okuduğu rehber (`AGENT_GUIDE.md`) derlemede metin olarak
+// gömülür — testler `src/app.ts`'i rehbersiz içe aktarabilsin diye ayrı dosyadadır.
+import guide from '../AGENT_GUIDE.md' with { type: 'text' }
+import { buildApp } from './app.ts'
+
+export default buildApp(guide)

package/templates/_shared/files/src/lib/client.ts.tpl

@@ -0,0 +1,213 @@
+// Sayfa betiğinin ortak çalışma zamanı (şablonların ORTAK parçası — create-devoplus-one-app üretir). `/shell.js` bu ön ek ve
+// şablonun kendi gövdesinden oluşur; bundler yoktur, betik ES5 biçiminde yazılır ve sunucuda tek dosya olarak sunulur.
+// Ön ekin verdiği yardımcılar (gövde bunları kullanır):
+//   t(anahtar, değişkenler?)   STRINGS'ten dile göre metin ("{ad}" yer tutucuları doldurulur)
+//   L({ tr, en })              iki dilli değerden geçerli dilin metni
+//   $(kimlik) · el(etiket, nitelikler, çocuklar)   DOM — metin her zaman textContent ile yazılır, innerHTML YOK
+//   api(yöntem, yol, gövde?)   one.fetch ile JSON isteği → Promise<{ ok, status, body }> (belirteci köprü ekler)
+//   problem(yanıt)             sunucunun RFC 9457 `detail` metni ya da genel hata metni
+//   loadAll(yol)               hazır liste ucunun BÜTÜN sayfaları → Promise<{ ok, status, body: { items, total, truncated } }>
+//                              (seçenek kümesi, süzgeç, sayım tek sayfadan kurulmaz — aşağıdaki not)
+//   go(yol) · onView(fn)       görünüm değiştirme (Portal sekmesi de aynı yolu kullanır) ve görünüm açılınca çağrılan işlev
+//   onReady(fn)                ilk belirteç geldiğinde (istek atmaya hazır) bir kez
+//   onLang(fn)                 dil değişince (dinamik metinleri yeniden çizmek için)
+//   canWrite()                 Vekalet / Yerine Görüntüle oturumunda yazma kapalıysa false
+//   can(izinKodu) · onSession(fn)   oturumdaki kişinin uygulama izni (yalnız düğme göstermek için; asıl kapı sunucuda)
+// İzinli sekmeler (manifest `navigation[].permission`) oturum okununca köprüye bildirilir (`one.setNavigationAccess`):
+// izni olmayan kişi o sekmeyi menüde görmez. Adresi doğrudan açan kişi görünümün "yetkiniz yok" notunu görür.
+//   fmtDate · fmtDateTime · fmtNumber   gg.aa.yyyy, gg.aa.yyyy SS:DD, tr-TR sayı biçimi
+// Portal ile HER konuşma köprüden geçer; `postMessage` doğrudan yazılmaz.
+import type { OneNavigationItem } from '@devoplus/one-sdk'
+import type { Strings } from './page.ts'
+
+export interface ClientScriptOptions {
+  strings: Strings
+  navigation: readonly OneNavigationItem[]
+  /** Manifest `actingSessions: "write"` ise true (Vekalet / Yerine Görüntüle oturumunda da yazılır). */
+  actingWrites?: boolean
+  /** Sayfaya özgü betik (ön ekin yardımcılarını kullanır). */
+  body: string
+}
+
+/**
+ * Ön ekin kendi metinleri. Anahtarlar `core` ile başlar ve sayfanın STRINGS'iyle KESİŞMEZ (şablon testi denetler):
+ * `t()` önce sayfanın metnine baktığı için aynı adlı bir sayfa metni ortak uyarının yerine geçerdi.
+ */
+export const CORE_STRINGS = {
+  tr: {
+    coreListTruncated: 'Liste eksik yüklendi',
+    coreListTruncatedDetail: 'Yalnız ilk {n} kayıt yüklendi; kalan kayıtlar bu seçimde görünmez.',
+  },
+  en: {
+    coreListTruncated: 'The list was loaded partially',
+    coreListTruncatedDetail: 'Only the first {n} records were loaded; the remaining records are not available in this selection.',
+  },
+}
+
+/** JSON bir betik dosyasına gömülüyor; "</" dizisi kaçırılır. */
+function embed(value: unknown): string {
+  return JSON.stringify(value).replace(/<\//g, '<\\/')
+}
+
+export function renderClientScript(options: ClientScriptOptions): string {
+  return `(function () {
+  'use strict';
+  var one = window.one;
+  var S = ${embed(options.strings)};
+  var CORE = ${embed(CORE_STRINGS)};
+  var NAVIGATION = ${embed(options.navigation)};
+  // manifest actingSessions: "write" ise Vekalet / Yerine Görüntüle oturumunda da yazılır → salt-okunur uyarısı gösterilmez.
+  var ACTING_WRITES = ${embed(options.actingWrites === true)};
+  var VIEWS = NAVIGATION.map(function (n) { return n.path; });
+  var root = document.documentElement;
+  var lang = root.lang === 'en' ? 'en' : 'tr';
+  // Durum satırı bir metin ANAHTARI taşır; dil değişince o anahtar yeni dile çevrilir.
+  var statusKey = 'waiting', hadToken = false, currentView = null;
+  var langHooks = [], viewHooks = [], readyHooks = [], sessionHooks = [], SESSION = null;
+  function $(id) { return document.getElementById(id); }
+  function t(key, vars) {
+    var s = (S[lang] && S[lang][key]) || S.tr[key] || CORE[lang][key] || CORE.tr[key] || key;
+    if (vars) for (var n in vars) if (Object.prototype.hasOwnProperty.call(vars, n)) s = s.split('{' + n + '}').join(String(vars[n]));
+    return s;
+  }
+  function L(v) { return v == null ? '' : typeof v === 'string' ? v : (v[lang] || v.tr || ''); }
+  function showStatus(key) { statusKey = key; var s = $('status'); if (s) s.textContent = key ? t(key) : ''; }
+  function translate() {
+    var nodes = document.querySelectorAll('[data-i18n]');
+    for (var i = 0; i < nodes.length; i++) nodes[i].textContent = t(nodes[i].getAttribute('data-i18n'));
+    var phs = document.querySelectorAll('[data-i18n-ph]');
+    for (var j = 0; j < phs.length; j++) phs[j].setAttribute('placeholder', t(phs[j].getAttribute('data-i18n-ph')));
+    var labels = document.querySelectorAll('[data-i18n-label]');
+    for (var k = 0; k < labels.length; k++) labels[k].setAttribute('aria-label', t(labels[k].getAttribute('data-i18n-label')));
+    showStatus(statusKey);
+  }
+  function onLang(fn) { langHooks.push(fn); }
+  function onView(fn) { viewHooks.push(fn); }
+  function onReady(fn) { readyHooks.push(fn); if (hadToken) fn(); }
+  function showView(p) {
+    var target = VIEWS.indexOf(p) >= 0 ? p : (VIEWS[0] || '/');
+    var views = document.querySelectorAll('[data-view]');
+    for (var i = 0; i < views.length; i++) {
+      if (views[i].getAttribute('data-view') === target) views[i].removeAttribute('hidden'); else views[i].setAttribute('hidden', '');
+    }
+    currentView = target;
+    one.setTitle(null);
+    for (var h = 0; h < viewHooks.length; h++) viewHooks[h](target);
+  }
+  function go(p) { one.setRoute(p); showView(p); }
+  function canWrite() { return !(one.actor && !ACTING_WRITES); }
+  function can(code) { return !!SESSION && (SESSION.admin === true || (SESSION.permissions || []).indexOf(code) >= 0); }
+  function onSession(fn) { sessionHooks.push(fn); if (SESSION) fn(SESSION); }
+  function el(tag, attrs, children) {
+    var node = document.createElement(tag);
+    for (var k in (attrs || {})) {
+      if (!Object.prototype.hasOwnProperty.call(attrs, k) || attrs[k] == null || attrs[k] === false) continue;
+      if (k === 'text') node.textContent = String(attrs[k]);
+      else node.setAttribute(k, attrs[k] === true ? '' : String(attrs[k]));
+    }
+    (children || []).forEach(function (c) { if (c) node.appendChild(c); });
+    return node;
+  }
+  function api(method, path, body) {
+    var init = { method: method, headers: { accept: 'application/json' } };
+    if (body !== undefined) { init.headers['content-type'] = 'application/json'; init.body = JSON.stringify(body); }
+    return one.fetch(path, init).then(function (r) {
+      return r.text().then(function (text) {
+        var data = null;
+        try { data = text ? JSON.parse(text) : null; } catch (e) { data = text; }
+        if (statusKey === 'networkError') showStatus(hadToken ? '' : 'waiting');
+        return { ok: r.ok, status: r.status, body: data };
+      });
+    }, function () { showStatus('networkError'); return { ok: false, status: 0, body: null }; });
+  }
+  function problem(r) {
+    if (r && r.body && typeof r.body === 'object' && typeof r.body.detail === 'string' && r.body.detail) return r.body.detail;
+    return t(r && r.status === 0 ? 'networkError' : 'requestFailed');
+  }
+  // ⛔ Seçenek kümesi (açılır liste, süzgeç, sayım) TEK SAYFADAN KURULMAZ: hazır liste uçları sayfa başına en çok
+  // LOAD_PAGE kayıt verir ve fazlasını hata VERMEDEN sonraki sayfaya bırakır — tek istekle kurulan liste 201. kaydı
+  // sessizce kaybederdi. loadAll bütün sayfaları "nextCursor" ile toplar. İmleç olsa da üç durumda durur, kesildiğini
+  // ekranda AÇIKÇA söyler ve "truncated: true" döner: LOAD_ALL_MAX kayda ulaşınca, LOAD_MAX_PAGES sayfa okuyunca (istek
+  // sınırı) ve bir sayfa YENİ kayıt getirmeyince (boş ya da tamamı yinelenen sayfa — "_page"i okumayan bir uç her
+  // istekte aynı sayfayı döndürür). Bir sayfa düşerse ya da yanıt liste değilse yarım liste DÖNMEZ: "ok: false" döner
+  // (çağıran hatayı gösterir). Yalnız "_size" / "_page" okuyan hazır liste uçları içindir ("nextCursor" orada sayfa
+  // numarasıdır); "page" / "limit" okuyan elle yazılmış bir uç ona bağlanmaz. Yol "_size" / "_page" taşımaz.
+  // ⚠️ EN İYİ ÇABA: sayfalar ayrı isteklerdir ve uç sıra numarasıyla (OFFSET) sayfalar. İki sayfa arasında kayıt
+  // eklenir, silinir ya da sıralama alanı değişirse bir kayıt iki sayfada gelebilir — "id"si aynı olan ikinci kopya
+  // atılır — ya da HİÇBİR sayfada gelmeyebilir. Atlamayı bu yardımcı kapatamaz; imleç tabanlı bir uç gerekir.
+  var LOAD_PAGE = 200, LOAD_ALL_MAX = 5000, LOAD_MAX_PAGES = Math.ceil(LOAD_ALL_MAX / LOAD_PAGE);
+  function loadAll(path) {
+    var items = [], seen = {}, sep = path.indexOf('?') >= 0 ? '&' : '?';
+    function page(n, done) {
+      return api('GET', path + sep + '_size=' + LOAD_PAGE + '&_page=' + encodeURIComponent(n)).then(function (r) {
+        if (!r.ok) return r;
+        if (!r.body || typeof r.body !== 'object' || !Array.isArray(r.body.items)) return { ok: false, status: r.status, body: r.body };
+        var added = 0;
+        for (var i = 0; i < r.body.items.length; i++) {
+          var row = r.body.items[i], id = row && row.id != null ? String(row.id) : null;
+          if (id !== null) { if (Object.prototype.hasOwnProperty.call(seen, id)) continue; seen[id] = true; }
+          items.push(row);
+          added++;
+        }
+        var next = r.body.nextCursor;
+        // İki koruma birlikte: yeni kayıt getirmeyen sayfa tekrarlayan sayfayı, sayfa tavanı ilerleyen ama bitmeyen
+        // imleci keser. İkisi olmadan istek döngüsü bitmezdi.
+        if (next && added > 0 && items.length < LOAD_ALL_MAX && done < LOAD_MAX_PAGES) return page(next, done + 1);
+        var truncated = !!next;
+        if (truncated) one.toast({ severity: 'warn', summary: t('coreListTruncated'), detail: t('coreListTruncatedDetail', { n: fmtNumber(items.length) }) });
+        return { ok: true, status: r.status, body: { items: items, total: r.body.total, truncated: truncated } };
+      });
+    }
+    return page(1, 1);
+  }
+  function toastResult(r, okKey) {
+    if (r.ok) one.toast({ severity: 'success', summary: t(okKey) });
+    else one.toast({ severity: 'error', summary: t('requestFailed'), detail: problem(r) });
+    return r.ok;
+  }
+  function pad(n) { return (n < 10 ? '0' : '') + n; }
+  function fmtDate(v) {
+    if (!v) return '';
+    var m = /^(\\d{4})-(\\d{2})-(\\d{2})$/.exec(String(v));
+    if (m) return m[3] + '.' + m[2] + '.' + m[1];
+    var d = new Date(String(v));
+    return isNaN(d.getTime()) ? String(v) : pad(d.getDate()) + '.' + pad(d.getMonth() + 1) + '.' + d.getFullYear();
+  }
+  function fmtTime(v) { var d = new Date(String(v)); return isNaN(d.getTime()) ? '' : pad(d.getHours()) + ':' + pad(d.getMinutes()); }
+  function fmtDateTime(v) { return v ? fmtDate(v) + ' ' + fmtTime(v) : ''; }
+  function fmtNumber(n) { return n == null || n === '' ? '' : new Intl.NumberFormat(lang === 'en' ? 'en-US' : 'tr-TR').format(Number(n)); }
+
+  // ── Sayfaya özgü betik ─────────────────────────────────────────────────────────────────────────────────────────
+${options.body}
+  // ── Ortak bağlama ──────────────────────────────────────────────────────────────────────────────────────────────
+
+  one.onToken(function () {
+    var first = !hadToken;
+    hadToken = true;
+    if (statusKey === 'waiting') showStatus('');
+    if (!first) return;
+    for (var i = 0; i < readyHooks.length; i++) readyHooks[i]();
+    api('GET', '/api/session').then(function (r) {
+      if (!r.ok || !r.body) return;
+      SESSION = r.body;
+      // İzinli sekmeler (manifest navigation[].permission, S10) yalnız izni olana görünür; yönetici hepsini görür.
+      one.setNavigationAccess({ permissions: SESSION.permissions || [], admin: SESSION.admin === true });
+      for (var j = 0; j < sessionHooks.length; j++) sessionHooks[j](SESSION);
+    });
+  });
+  one.onContext(function (c) {
+    lang = String(c.lang || '').toLowerCase().indexOf('en') === 0 ? 'en' : 'tr';
+    root.lang = lang;
+    root.setAttribute('data-theme', c.theme === 'dark' ? 'dark' : 'light');
+    translate();
+    // Vekalet / Yerine Görüntüle oturumunda platform yazma isteklerini reddeder; kullanıcıya baştan söylenir.
+    if (c.actor && !ACTING_WRITES) $('readOnly').removeAttribute('hidden'); else $('readOnly').setAttribute('hidden', '');
+    for (var i = 0; i < langHooks.length; i++) langHooks[i](lang);
+  });
+  one.onNavigate(showView);
+  translate();
+  showView(one.path);
+  one.start({ navigation: NAVIGATION });
+})();
+`
+}

package/templates/_shared/files/src/lib/files.ts.tpl

@@ -0,0 +1,37 @@
+// Dosya yükleme ve indirme (şablonların ORTAK parçası — create-devoplus-one-app üretir; manifest `services.files` açık şablonlarda).
+// Hazır `<one-file-upload>` bileşeni dosyayı `POST /api/files`'a gövde olarak gönderir (ad `x-file-name` başlığında);
+// yanıt `{ key, name, size, contentType }`'tır. ⛔ Anahtar KULLANICININ ön ekindedir (`uploads/<sub>/<uuid>-<ad>`):
+// her yükleme benzersizdir (aynı adla ikinci yükleme öncekini ezmez) ve bir kayda yalnız kendi ön ekindeki anahtar
+// yazılabilir (`ownFileKey`). Dosya, kaydın kendisi okunabiliyorsa kaydın ucundan indirilir (`fileResponse`).
+import { OneFiles, logAudit, readBoundedBody, requireUser, sanitizeFileName, type OneContext, type OneFilesBinding } from '@devoplus/one-sdk'
+import { json } from './server.ts'
+import { uploadPrefixFor } from './http.ts'
+
+/** Yükleme tavanı: 5 MB (bileşenin varsayılanıyla aynı). */
+export const UPLOAD_MAX_BYTES = 5 * 1024 * 1024
+const UPLOAD_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-/
+
+export async function uploadFile(request: Request, files: OneFilesBinding, ctx: OneContext): Promise<Response> {
+  const user = requireUser(ctx)
+  const name = sanitizeFileName(request.headers.get('x-file-name') ?? 'dosya.bin')
+  const contentType = request.headers.get('content-type') ?? 'application/octet-stream'
+  // Sınır gövde belleğe alınmadan ÖNCE uygulanır (Content-Length), parçalı akışta okuma sırasında kesilir.
+  const body = await readBoundedBody(request, UPLOAD_MAX_BYTES)
+  const key = `${uploadPrefixFor(user.sub)}${crypto.randomUUID()}-${name}`
+  const stored = await new OneFiles(files).put(key, body, { contentType, maxBytes: UPLOAD_MAX_BYTES, metadata: { sub: user.sub } })
+  logAudit(ctx, 'file.upload', stored.key, { size: stored.size })
+  return json({ key: stored.key, name, size: stored.size, contentType }, 201)
+}
+
+/** Kayda bağlı dosyayı indirir. Erişim kararı ÇAĞIRANDADIR (kaydı okuyabilen indirebilir). */
+export async function fileResponse(files: OneFilesBinding, key: string): Promise<Response> {
+  const object = await new OneFiles(files).get(key)
+  if (!object) return json({ detail: 'Dosya bulunamadı.' }, 404)
+  const headers = new Headers()
+  object.writeHttpMetadata(headers)
+  headers.set('etag', object.httpEtag)
+  const downloadName = (key.split('/').pop() ?? 'dosya').replace(UPLOAD_ID_RE, '')
+  headers.set('content-disposition', `attachment; filename="${downloadName}"`)
+  headers.set('cache-control', 'no-store')
+  return new Response(object.body, { headers })
+}

package/templates/_shared/files/src/lib/http.ts.tpl

@@ -0,0 +1,101 @@
+// İstek yardımcıları (şablonların ORTAK parçası — create-devoplus-one-app üretir): sınırlı JSON gövde okuma, izinli alan
+// denetimi, hazır kayıt uçlarına (`createCrudHandler`) temizlenmiş gövdeyle iletme ve hazır bileşenlerin değerlerini
+// (kişi, dosya) saklanacak biçime çevirme. Kurallar sunucudadır: istemciden gelen değer DOĞRULANMADAN yazılmaz.
+import { DataValidationError, OneError, readBoundedBody, type FieldIssue } from '@devoplus/one-sdk'
+
+/** Uygulamanın kendi uçlarında JSON gövde tavanı (bayt). Kayıt uçlarının kendi tavanı 1 MB'dir. */
+export const JSON_BODY_MAX_BYTES = 64 * 1024
+
+/** Gövdeyi SINIRLI okur ve JSON nesnesi ister (`request.json()` gövdenin tamamını belleğe aldıktan SONRA ayrıştırırdı). */
+export async function readJsonObject(request: Request, maxBytes = JSON_BODY_MAX_BYTES): Promise<Record<string, unknown>> {
+  const type = (request.headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase()
+  if (type !== 'application/json') throw new OneError(415, 'APP-E-415', 'Gövde application/json türünde olmalı.')
+  const buffer = await readBoundedBody(request, maxBytes)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(buffer))
+  } catch {
+    throw new OneError(400, 'APP-E-400', 'Gövde geçerli JSON değil.')
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new OneError(400, 'APP-E-400', 'Gövde bir JSON nesnesi olmalı.')
+  return parsed as Record<string, unknown>
+}
+
+/** Alan hatası (form alanın altında gösterir). */
+export function fieldError(field: string, message: string, status = 400): DataValidationError {
+  return new DataValidationError(status, status === 409 ? 'APP-E-409' : 'APP-E-400', message, [{ field, message }])
+}
+
+/** Gövdede yalnız izinli alanlar olabilir; sunucunun yazdığı alan (durum, onaylayan …) istemciden ALINMAZ. */
+export function onlyFields(body: Record<string, unknown>, allowed: readonly string[]): Record<string, unknown> {
+  const issues: FieldIssue[] = []
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(body)) {
+    if (allowed.includes(key)) out[key] = value
+    else issues.push({ field: key, message: `"${key}" bu işlemde gönderilemez.` })
+  }
+  if (issues.length > 0) throw new DataValidationError(400, 'APP-E-400', 'Kayıt doğrulanamadı.', issues)
+  return out
+}
+
+/** Aynı başlıklarla (kimlik platformdan gelir) başka bir uca giden istek — hazır kayıt uçlarına temizlenmiş gövde vermek için. */
+export function forward(request: Request, path: string, method: string, body?: unknown): Request {
+  const headers = new Headers(request.headers)
+  headers.delete('content-length')
+  if (body !== undefined) headers.set('content-type', 'application/json')
+  const init: RequestInit = { method, headers }
+  if (body !== undefined) init.body = JSON.stringify(body)
+  return new Request(new URL(path, request.url), init)
+}
+
+/** Aynı başlıklarla, sorgusu sunucuda değiştirilmiş bir okuma isteği (ör. "yalnız bana atananlar" süzgecini zorlamak). */
+export function withQuery(request: Request, path: string, change: (params: URLSearchParams) => void): Request {
+  const url = new URL(request.url)
+  const target = new URL(path, request.url)
+  target.search = url.search
+  change(target.searchParams)
+  return new Request(target, { method: request.method, headers: request.headers })
+}
+
+const ORG_ID_RE = /^[0-9a-f]{24}$/i
+
+/**
+ * Kişi seçicinin değeri (`{ id, name }`) → org kimliği + ad. ⚠️ `id` Organization Schema kimliğidir, oturum kimliği (`sub`)
+ * DEĞİLDİR; bildirimde `toOrgUserIds` alanına yazılır. Boş değer `null`.
+ */
+export function personValue(raw: unknown, field: string): { id: string; name: string } | null {
+  if (raw === null || raw === undefined || raw === '') return null
+  const value = raw as { id?: unknown; name?: unknown }
+  if (typeof value !== 'object' || typeof value.id !== 'string' || !ORG_ID_RE.test(value.id))
+    throw fieldError(field, 'Kişi seçiciden geçerli bir kişi seçin.')
+  const name = typeof value.name === 'string' ? value.name.trim().slice(0, 120) : ''
+  return { id: value.id.toLowerCase(), name }
+}
+
+/** Kullanıcının dosya ön eki: her kullanıcı yalnız KENDİ ön ekine yükler (`uploads/<sub>/`). */
+export function uploadPrefixFor(sub: string): string {
+  return `uploads/${encodeURIComponent(sub)}/`
+}
+
+/**
+ * Dosya yükleyicinin değeri (`{ key, name }` ya da anahtar) → anahtar. ⛔ Anahtar KULLANICININ ön ekinde olmalı:
+ * başkasının dosya anahtarını kayda yazıp sonra kaydın ekini indirerek o dosyayı okumak böyle engellenir.
+ */
+export function ownFileKey(raw: unknown, sub: string, field: string): string | null {
+  if (raw === null || raw === undefined || raw === '') return null
+  const key = typeof raw === 'string' ? raw : typeof raw === 'object' && typeof (raw as { key?: unknown }).key === 'string' ? (raw as { key: string }).key : null
+  if (key === null || !key.startsWith(uploadPrefixFor(sub)) || key.includes('..')) throw fieldError(field, 'Dosyayı bu formdan yükleyin.')
+  return key
+}
+
+/** Yolun `/<önek>/<kimlik>/<eylem>` parçaları (kimlik kayıt uçlarının ürettiği uuid'dir). */
+export function matchId(pathname: string, prefix: string, action?: string): string | null {
+  const rest = pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length + 1) : null
+  if (rest === null) return null
+  const [id, act, extra] = rest.split('/')
+  if (extra !== undefined || !/^[0-9a-f-]{36}$/.test(id ?? '')) return null
+  if ((action ?? undefined) !== (act ?? undefined)) return null
+  return id!
+}
+
+export const nowIso = (): string => new Date().toISOString()

package/templates/_shared/files/src/lib/mail.ts.tpl

@@ -0,0 +1,26 @@
+// E-posta bildirimi (şablonların ORTAK parçası — create-devoplus-one-app üretir; manifest `mail.execute` beyan eden şablonlarda).
+// Bildirim asıl işin bir PARÇASI DEĞİL, sonucudur: kayıt yazıldıktan sonra gönderilir ve düşerse kayıt geri alınmaz —
+// sonuç döner, arıza olay günlüğüne yazılır. `mail.execute` kullanıcının portaldaki ayrı ve süreli onayına bağlıdır
+// (yoksa belirteçte bulunmaz): o durumda gönderim denenmez, `consent-needed` döner ve arayüz kullanıcıya
+// "portaldaki İzinleri incele düğmesiyle izin verin" der. Alıcı yalnız kimlikle verilir (`toSubjects` oturum kimliği,
+// `toOrgUserIds` kişi kaydı kimliği); serbest e-posta adresi YAZILMAZ.
+import { awaitsUserConsent, logError, notify, type BackendClient, type OneContext, type Recipients, type ScenarioMessage } from '@devoplus/one-sdk'
+
+export type MailOutcome = 'sent' | 'consent-needed' | 'failed' | 'skipped'
+
+export async function sendMailSafely(ctx: OneContext, api: BackendClient, message: ScenarioMessage, recipients: Recipients): Promise<MailOutcome> {
+  if ((recipients.toSubjects?.length ?? 0) + (recipients.toOrgUserIds?.length ?? 0) === 0) return 'skipped'
+  if (awaitsUserConsent(ctx, 'mail.execute')) return 'consent-needed'
+  try {
+    const result = await notify(api, message, { ...recipients, channels: ['mail'] })
+    const mail = result.mail
+    if (mail && 'error' in mail) {
+      logError(ctx, 'e-posta bildirimi gönderilemedi', mail.error)
+      return 'failed'
+    }
+    return 'sent'
+  } catch (error) {
+    logError(ctx, 'e-posta bildirimi gönderilemedi', error)
+    return 'failed'
+  }
+}

package/templates/_shared/files/src/lib/model.ts.tpl

@@ -0,0 +1,31 @@
+// Veri modelinden arayüz tanımları (şablonların ORTAK parçası — create-devoplus-one-app üretir). Seçeneklerin ve alan adlarının
+// tek kaynağı `one.data.json`'dır (`src/data/types.ts` içindeki `dataModel`): sayfa onları buradan alır, elle tekrar
+// yazmaz — seçenek adı modelde değişince liste, süzgeç ve form birlikte değişir.
+import type { OneDataModel } from '@devoplus/one-sdk'
+
+export interface Localized {
+  tr: string
+  en: string
+}
+
+export interface ChoiceOption {
+  value: string
+  label: Localized
+}
+
+function field(model: OneDataModel, entity: string, name: string) {
+  const f = model.entities[entity]?.fields[name]
+  if (!f) throw new Error(`veri modelinde ${entity}.${name} yok`)
+  return f
+}
+
+/** Seçim alanının seçenekleri (`<one-table>` kolonu, `<one-filter>` ve `<one-form>` alanı için). */
+export function choices(model: OneDataModel, entity: string, name: string): ChoiceOption[] {
+  return (field(model, entity, name).choices ?? []).map((c) => ({ value: c.value, label: { tr: c.title.tr, en: c.title.en } }))
+}
+
+/** Alanın görünen adı. */
+export function label(model: OneDataModel, entity: string, name: string): Localized {
+  const t = field(model, entity, name).title
+  return { tr: t.tr, en: t.en }
+}