@xrystal/core 3.38.3 → 3.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +397 -65
  2. package/package.json +2 -4
  3. package/x/bin/commands/create.mjs +2 -1
  4. package/x/bin/commands/doctor.mjs +5 -4
  5. package/x/bin/commands/hooks.mjs +2 -1
  6. package/x/bin/commands/project.mjs +2 -1
  7. package/x/bin/commands/release.mjs +3 -2
  8. package/x/bin/commands/sync.mjs +51 -0
  9. package/x/bin/commands/tmp.mjs +2 -1
  10. package/x/bin/helpers/.generated/tmp-schema.mjs +54 -85
  11. package/x/bin/helpers/banner.mjs +2 -2
  12. package/x/bin/helpers/build-config.mjs +11 -2
  13. package/x/bin/helpers/cli-help.mjs +9 -9
  14. package/x/bin/helpers/cli-identity.mjs +7 -17
  15. package/x/bin/helpers/defaults.json +14 -30
  16. package/x/bin/helpers/package-defaults.mjs +46 -12
  17. package/x/bin/helpers/project-artifacts.mjs +7 -0
  18. package/x/bin/helpers/seed-from-tmp.mjs +52 -0
  19. package/x/bin/helpers/toolchain-config.mjs +6 -12
  20. package/x/bin/main-cli.js +2 -2
  21. package/x/bin/scripts/install-git-hooks.mjs +3 -2
  22. package/x/bin/scripts/sync-cli-defaults.mjs +7 -2
  23. package/x/dist/project/index.js +1 -1
  24. package/x/dist/utils/constants/defaults.json +14 -30
  25. package/x/dist/utils/constants/index.d.ts +20 -12
  26. package/x/dist/utils/constants/index.js +1 -1
  27. package/x/dist/utils/helpers/tmp/index.d.ts +2 -0
  28. package/x/dist/utils/helpers/tmp/index.js +1 -1
  29. package/x/dist/utils/helpers/tmp/path-normalize.d.ts +10 -0
  30. package/x/dist/utils/helpers/tmp/path-normalize.js +1 -0
  31. package/x/dist/utils/helpers/tmp/seed-from-tmp.d.ts +9 -0
  32. package/x/dist/utils/helpers/tmp/seed-from-tmp.js +1 -0
  33. package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -1
  34. package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +1 -0
  35. package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -1
  36. package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -1
  37. package/x/bin/commands/sync-toolchain.mjs +0 -43
package/README.md CHANGED
@@ -3,42 +3,77 @@
3
3
  > **EN** — Microservice runtime: Express or Elysia HTTP, DI loaders, live `tmp.yml`, standardized API responses.
4
4
  > **TR** — Microservice runtime: Express veya Elysia HTTP, DI loader'lar, canlı `tmp.yml`, standart API cevapları.
5
5
 
6
- **CLI:** `xcore` · `xrystal` · `tmp` (same binary / aynı binary)
6
+ **CLI:** `xry` · **Version:** `3.40.0` · [npm](https://www.npmjs.com/package/@xrystal/core)
7
+
8
+ ---
9
+
10
+ ## What's new in 3.40.0 / 3.40.0'da ne değişti
11
+
12
+ | Change / Değişiklik | EN | TR |
13
+ |---------------------|----|----|
14
+ | **Single CLI** | Bin is only `xry` (`xcore` / `xrystal` / `tmp` removed) | Tek bin: `xry` (eski isimler kalktı) |
15
+ | **`xry sync`** | Writes `tsconfig` `include` / `outDir` / `@/*` from project `tmp.yml` | `tmp.yml` → tsconfig path sync |
16
+ | **Config SSOT** | Layout seed from bundled `x/tmp.yml` — not `defaults.json` | Layout seed = `x/tmp.yml`, `defaults.json` değil |
17
+ | **`defaults.json`** | Package identity + CLI + build flags only | Sadece kimlik, CLI, build flag'leri |
18
+
19
+ ```bash
20
+ npx xry sync # apply tmp.yml → tsconfig / bunfig aliases
21
+ npx xry sync --dry-run
22
+ ```
23
+
24
+ **Breaking / Kırıcı:** replace scripts and docs that called `xcore`, `xrystal`, or the old `tmp` bin with `xry`.
25
+
26
+ ---
27
+
28
+ ## Why / Neden
29
+
30
+ **EN:** `@xrystal/core` is a **kernel**, not only a GitHub template. Most teams already have their own repo layout, CI, Docker, or monorepo — they only need the runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Use `xry create` if you want a starter; otherwise add the package to **your** project and seed `x/tmp.yml`.
31
+
32
+ **TR:** `@xrystal/core` bir **kernel** — sadece GitHub template değil. Çoğu ekipte zaten kendi repo düzeni, CI, Docker veya monorepo vardır; ihtiyaç duyulan şey runtime: DI, `tmp.yml`, `ctr()`, DTO, logger, i18n, trace. Sıfırdan başlıyorsan `xry create`; mevcut projende sadece paketi kur + `xry tmp` yeter.
33
+
34
+ ```bash
35
+ # EN: existing project — kernel only · TR: mevcut proje — sadece kernel
36
+ bun add @xrystal/core
37
+ npx xry tmp # seed x/tmp.yml into YOUR layout
38
+ npx xry sync # align tsconfig paths with tmp.yml
39
+ # wire coreLoader + dtoMiddleware in your entry file
40
+ ```
7
41
 
8
42
  ---
9
43
 
10
44
  ## Quick start / Hızlı başlangıç
11
45
 
12
- ### Path A — `create` (recommended / önerilen)
46
+ ### Path A — `create` (starter template / başlangıç şablonu)
13
47
 
14
- **EN:** Clone GitHub template — `x/tmp.yml` and folder layout ready.
48
+ **EN:** Optional — clone GitHub template when you have no project yet.
15
49
 
16
- **TR:** GitHub template klonlanır — `x/tmp.yml` ve klasör yapısı hazır gelir.
50
+ **TR:** İsteğe bağlı — henüz proje yoksa GitHub template klonla.
17
51
 
18
52
  ```bash
19
53
  mkdir my-api && cd my-api
20
54
  bun init -y
21
55
  bun add @xrystal/core
22
- npx xcore create my-api .
56
+ npx xry create my-api .
23
57
  ```
24
58
 
25
59
  ```bash
26
60
  bun add elysia # EN: or express · TR: veya express
27
61
  bun run dev
28
- npx xcore doctor # EN: setup check · TR: kurulum kontrolü
62
+ npx xry doctor # EN: setup check · TR: kurulum kontrolü
29
63
  ```
30
64
 
31
- ### Path B — Manual setup / Manuel kurulum
65
+ ### Path B — Your project + kernel (most common / en yaygın)
32
66
 
33
- **EN:** Install package, seed `tmp.yml`, add scripts.
67
+ **EN:** Keep your folder names — only add `tmp.yml`, `coreLoader`, controllers.
34
68
 
35
- **TR:** Paketi kur, `tmp.yml` seed'le, script'leri ekle.
69
+ **TR:** Kendi klasör adların kalsın — sadece `tmp.yml`, `coreLoader`, controller ekle.
36
70
 
37
71
  ```bash
38
72
  mkdir my-api && cd my-api
39
73
  bun init -y
40
74
  bun add @xrystal/core elysia
41
- npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
75
+ npx xry tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
76
+ npx xry sync # EN: tsconfig from tmp.yml · TR: tmp.yml → tsconfig
42
77
  ```
43
78
 
44
79
  `package.json`:
@@ -46,22 +81,23 @@ npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa
46
81
  ```json
47
82
  {
48
83
  "dependencies": {
49
- "@xrystal/core": "^3.38.2",
84
+ "@xrystal/core": "^3.40.0",
50
85
  "elysia": "^1.4.19"
51
86
  },
52
87
  "scripts": {
53
- "dev": "xcore dev",
54
- "build": "xcore build",
55
- "start": "xcore start",
56
- "test": "xcore test",
57
- "doctor": "xcore doctor"
88
+ "dev": "xry dev",
89
+ "build": "xry build",
90
+ "start": "xry start",
91
+ "test": "xry test",
92
+ "sync": "xry sync",
93
+ "doctor": "xry doctor"
58
94
  }
59
95
  }
60
96
  ```
61
97
 
62
- **EN:** No global `xcore` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
98
+ **EN:** No global `xry` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
63
99
 
64
- **TR:** Global `xcore` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
100
+ **TR:** Global `xry` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
65
101
 
66
102
  ### Project layout / Proje düzeni
67
103
 
@@ -69,14 +105,20 @@ npx xcore tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa
69
105
  my-api/
70
106
  ├── package.json
71
107
  ├── source/
72
- │ ├── index.ts # EN: dev entry (xcore dev) · TR: dev girişi
108
+ │ ├── index.ts # EN: dev entry (xry dev) · TR: dev girişi
73
109
  │ └── controllers/
74
110
  └── x/
75
- ├── tmp.yml # EN: single config source · TR: tek config kaynağı
76
- ├── environments/ # .dev.env, .prod.env
77
- └── tests/
111
+ └── tmp.yml # EN: runtime + path SSOT · TR: runtime + path tek kaynak
78
112
  ```
79
113
 
114
+ ### Config sources / Config kaynakları
115
+
116
+ | File / Dosya | Owns / Sahip olduğu |
117
+ |--------------|---------------------|
118
+ | `x/tmp.yml` | Service paths, loaders, protocols, build flags · layout seed |
119
+ | `tsconfig.json` | Compiler language options; path layout via `xry sync` |
120
+ | Package defaults (internal) | CLI name (`xry`), package identity — not project layout |
121
+
80
122
  ### Minimal `x/tmp.yml`
81
123
 
82
124
  ```yaml
@@ -130,13 +172,158 @@ bun run dev
130
172
 
131
173
  | Command / Komut | EN | TR |
132
174
  |-----------------|----|----|
133
- | `xcore create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
134
- | `xcore tmp` | Create `tmp.yml` from seed if missing | `tmp.yml` yoksa seed'den oluştur |
135
- | `xcore dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
136
- | `xcore build` | Output → `x/dist` | Çıktı → `x/dist` |
137
- | `xcore start` | Run `x/dist` + prod env | `x/dist` + prod env |
138
- | `xcore test` | Run `x/tests` | `x/tests` çalıştır |
139
- | `xcore doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
175
+ | `xry create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
176
+ | `xry tmp` | Create `tmp.yml` from seed if missing | `tmp.yml` yoksa seed'den oluştur |
177
+ | `xry sync` | Sync `tsconfig` / aliases from `tmp.yml` | `tmp.yml` → `tsconfig` / alias |
178
+ | `xry dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
179
+ | `xry build` | Output → `x/dist` | Çıktı → `x/dist` |
180
+ | `xry start` | Run `x/dist` + prod env | `x/dist` + prod env |
181
+ | `xry test` | Run `x/tests` | `x/tests` çalıştır |
182
+ | `xry doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
183
+
184
+ ---
185
+
186
+ ## Platform features / Platform özellikleri
187
+
188
+ **EN:** What the kernel gives you — one line each + minimal example.
189
+
190
+ **TR:** Kernel'in verdiği yetenekler — tek satır + kısa örnek.
191
+
192
+ | Feature / Özellik | EN | TR | Example / Örnek |
193
+ |-------------------|----|----|-----------------|
194
+ | **Boot / DI** | Awilix loaders: System, Logger, Kafka, Dto, i18n, … | Awilix loader'lar | `await coreLoader({})` |
195
+ | **Live `tmp.yml`** | Edit file → loaders re-sync without restart | Dosya değişince loader sync | `logLevel: debug` → save → logger updates |
196
+ | **`ctr()` pipeline** | `checks → logic → response`, no `res.json()` | Endpoint pipeline | `list = this.ctr({ logic: async () => ({ data: [] }) })` |
197
+ | **DTO responses** | Standard API shape via `@xrystal/dto` | Standart API cevabı | `return { data: [], message: '@successfully user' }` |
198
+ | **Trace** | `requestId` per request/job (ALS) | İstek/job trace id | `req.requestId` · `runWithTrace('job-1', fn)` |
199
+ | **i18n** | i18next + 50+ business message keys | Çok dilli mesajlar | `'@successfully user'` · `req.t('responseMessage.successfully')` |
200
+ | **G store** | App-wide state from `tmp.yml` vars | Global state | `G.get('maintenance')` · `checks: () => G.get('x') ? fail : true` |
201
+ | **Logger** | Winston: console + daily rotate files | Dosya + konsol log | `this.logger.log(LoggerLayerEnum.INFO, 'ok')` |
202
+ | **Kafka logs** | Structured logs → Kafka topic | Log → Kafka | `loaders.loggers` + `configs.kafkaLogsTopic` in env |
203
+ | **HTTP client** | Retries + circuit breaker + trace header | Dayanıklı outbound HTTP | extend `BaseApiClient` from loader/clients |
204
+ | **Scope validate** | OAuth-style `resource:permission` check | Scope doğrulama | `validateScopes({ scopes, resources, permissions })` |
205
+ | **Realtime** | Same `ctr()` for ws / socket.io | HTTP + ws aynı kalıp | `ctr({ logic }, { protocol: 'ws' })` — [guide](#realtime--websocket--socketio) |
206
+ | **CLI (`xry`)** | create, tmp, sync, dev, build, start, test, doctor | Servis toolchain | `"dev": "xry dev"` · `"sync": "xry sync"` |
207
+ | **Shutdown** | Graceful cleanup on SIGTERM | Temiz kapanış | auto via `registerGracefulShutdown()` on boot |
208
+
209
+ ```typescript
210
+ // EN: minimal kernel boot in ANY entry file · TR: herhangi bir giriş dosyasında
211
+ import coreLoader from '@xrystal/core'
212
+ import { dtoMiddleware, G, runWithTrace } from '@xrystal/core/utils'
213
+ import Controller from '@xrystal/core/loader/controller'
214
+
215
+ await coreLoader({})
216
+
217
+ class HealthController extends Controller {
218
+ check = this.ctr({
219
+ checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
220
+ logic: async ({ req }) => ({
221
+ data: { ok: true, trace: req.requestId },
222
+ message: '@successfully',
223
+ }),
224
+ })
225
+ }
226
+ export const healthCtrl = new HealthController()
227
+
228
+ await runWithTrace('nightly-job', async () => {
229
+ // EN: cron/queue jobs get trace too · TR: cron/queue job'ları da trace alır
230
+ })
231
+ ```
232
+
233
+ ---
234
+
235
+ ## Framework quickstarts / Framework hızlı başlangıç
236
+
237
+ **EN:** Same kernel — swap only `framework` in `tmp.yml` + middleware line.
238
+
239
+ **TR:** Aynı kernel — sadece `tmp.yml` → `framework` ve middleware satırı değişir.
240
+
241
+ ### Elysia (default)
242
+
243
+ ```yaml
244
+ # x/tmp.yml
245
+ configs:
246
+ service:
247
+ framework: elysia
248
+ paths: { root: ./x, source: ./source }
249
+ ```
250
+
251
+ ```typescript
252
+ import { Elysia } from 'elysia'
253
+ import coreLoader from '@xrystal/core'
254
+ import { dtoMiddleware } from '@xrystal/core/utils'
255
+ import { userCtrl } from './controllers/user'
256
+
257
+ await coreLoader({})
258
+ new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
259
+ ```
260
+
261
+ ### Express
262
+
263
+ ```yaml
264
+ configs:
265
+ service:
266
+ framework: express
267
+ ```
268
+
269
+ ```typescript
270
+ import express from 'express'
271
+ import coreLoader from '@xrystal/core'
272
+ import { dtoMiddleware } from '@xrystal/core/utils'
273
+ import { userCtrl } from './controllers/user'
274
+
275
+ await coreLoader({})
276
+ const app = express()
277
+ app.use(dtoMiddleware('express'))
278
+ app.get('/users', userCtrl.list)
279
+ app.listen(3000)
280
+ ```
281
+
282
+ ### Node (raw http)
283
+
284
+ ```yaml
285
+ configs:
286
+ service:
287
+ framework: node
288
+ ```
289
+
290
+ ```typescript
291
+ import http from 'node:http'
292
+ import coreLoader from '@xrystal/core'
293
+ import { userCtrl } from './controllers/user'
294
+
295
+ await coreLoader({})
296
+ http.createServer((req, res) => userCtrl.list(req, res)).listen(3000)
297
+ ```
298
+
299
+ ### Fetch / Bun.serve
300
+
301
+ ```yaml
302
+ configs:
303
+ service:
304
+ framework: fetch
305
+ ```
306
+
307
+ ```typescript
308
+ import coreLoader from '@xrystal/core'
309
+ import { userCtrl } from './controllers/user'
310
+
311
+ await coreLoader({})
312
+ Bun.serve({ fetch: (req) => userCtrl.list(req) })
313
+ ```
314
+
315
+ `fetch` — no global middleware; `ctr()` attaches builder per request.
316
+
317
+ **EN:** WebSocket & Socket.IO — full guide at the end: [Realtime](#realtime--websocket--socketio).
318
+
319
+ **TR:** WebSocket & Socket.IO — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
320
+
321
+ | Framework | `tmp.yml` | Middleware |
322
+ |-----------|-----------|------------|
323
+ | elysia | `framework: elysia` | `dtoMiddleware()` |
324
+ | express | `framework: express` | `dtoMiddleware('express')` |
325
+ | node | `framework: node` | `dtoMiddleware('node')` |
326
+ | fetch | `framework: fetch` | — (per-request in `ctr`) |
140
327
 
141
328
  ---
142
329
 
@@ -144,12 +331,15 @@ bun run dev
144
331
 
145
332
  | Topic / Konu | Section / Bölüm |
146
333
  |--------------|-----------------|
334
+ | Why kernel vs template | [Why](#why--neden) |
335
+ | All platform capabilities | [Platform features](#platform-features--platform-özellikleri) |
336
+ | Per-framework boot | [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) |
147
337
  | Controller, `ctr()` | [Controller](#controller) |
148
- | Express / Elysia | [Framework](#express--elysia) |
338
+ | Express / Elysia detail | [Framework](#express--elysia) |
149
339
  | DI, boot, tmp watch | [DI](#di--tmpyml) |
150
340
  | Locale / dil | [i18n](#i18n--locale) |
151
341
  | Global state | [G store](#g-store) |
152
- | WebSocket | [Realtime](#realtime) |
342
+ | WebSocket & Socket.IO | [Realtime](#realtime--websocket--socketio) |
153
343
  | API response shape | [DTO](#dto-responses--dto-cevapları) |
154
344
  | End-to-end flow | [Usage guide](#usage-guide--kullanım-rehberi) |
155
345
 
@@ -190,9 +380,9 @@ app.get('/users', userCtrl.list)
190
380
 
191
381
  ## Express & Elysia
192
382
 
193
- **EN:** `tmp.yml` → `configs.service.framework` picks the HTTP stack.
383
+ **EN:** See [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) for copy-paste per stack. `tmp.yml` → `configs.service.framework` picks the HTTP layer.
194
384
 
195
- **TR:** `tmp.yml` → `configs.service.framework` HTTP stack'i seçer.
385
+ **TR:** Kopyala-yapıştır örnekler için [Framework hızlı başlangıç](#framework-quickstarts--framework-hızlı-başlangıç). `tmp.yml` → `framework` HTTP katmanını seçer.
196
386
 
197
387
  **Express**
198
388
 
@@ -238,9 +428,9 @@ new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
238
428
  | node | `dtoMiddleware('node')` | Raw `createServer` | Ham HTTP |
239
429
  | fetch | none | `ctr()` attaches builder per request | Request başına builder |
240
430
 
241
- **EN:** Realtime (ws / socket.io) is separate from HTTP framework — see [Realtime](#realtime).
431
+ **EN:** Realtime (ws / socket.io) is separate from HTTP — full guide at the end: [Realtime](#realtime--websocket--socketio).
242
432
 
243
- **TR:** Realtime (ws / socket.io) HTTP framework'ten bağımsız — [Realtime](#realtime).
433
+ **TR:** Realtime (ws / socket.io) HTTP'den ayrı — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
244
434
 
245
435
  ---
246
436
 
@@ -334,27 +524,6 @@ checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } :
334
524
 
335
525
  ---
336
526
 
337
- ## Realtime
338
-
339
- **EN:** Not HTTP — use `protocol: 'ws'` or `'socketio'` on `ctr()`. Set `protocols` in `tmp.yml`.
340
-
341
- **TR:** HTTP değil — `ctr()` üzerinde `protocol: 'ws'` veya `'socketio'`. `tmp.yml` → `protocols`.
342
-
343
- ```typescript
344
- onMessage = this.ctr({ logic: async () => ({ ok: true }) }, { protocol: 'ws' })
345
-
346
- wss.on('connection', (socket) => {
347
- realtimeMiddleware()(socket, () => {})
348
- socket.on('message', chatCtrl.onMessage.with(socket))
349
- })
350
- ```
351
-
352
- ```yaml
353
- protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
354
- ```
355
-
356
- ---
357
-
358
527
  ## DTO responses / DTO cevapları
359
528
 
360
529
  **EN:** Standard `{ success, message, data, … }` via `@xrystal/dto`. `dtoMiddleware()` attaches builder; `ctr()` dispatches the result.
@@ -372,13 +541,14 @@ Details / detay: [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto)
372
541
  **TR:** Servis yazarken tipik akış.
373
542
 
374
543
  ```
375
- 1. xcore create or bun add + xcore tmp
376
- 2. tmp.yml → framework, loaders, paths
377
- 3. coreLoader() → once at top of index.ts
378
- 4. Controller → ctr() per endpoint
379
- 5. Framework → dtoMiddleware + routes
380
- 6. xcore dev → develop
381
- 7. xcore build → start → production
544
+ 1. Your repo + bun add @xrystal/core + xry tmp (or xry create for greenfield)
545
+ 2. xry sync → tsconfig include / outDir / @/* from tmp.yml
546
+ 3. tmp.yml → framework, loaders, paths
547
+ 4. coreLoader() → once at top of YOUR index.ts
548
+ 5. Controller → ctr() per endpoint
549
+ 6. Framework → dtoMiddleware + routes
550
+ 7. xry dev → develop
551
+ 8. xry build → start → production
382
552
  ```
383
553
 
384
554
  ### Express — end-to-end / uçtan uca
@@ -454,8 +624,170 @@ class UserController extends Controller {
454
624
 
455
625
  ---
456
626
 
627
+ ## Realtime — WebSocket & Socket.IO
628
+
629
+ **EN:** HTTP framework (`express`, `elysia`, …) and realtime are **separate axes**. Realtime uses `protocol: 'ws'` or `'socketio'` on `ctr()` — not `framework` in `tmp.yml`. Integration tests cover both pipelines (34 tests pass).
630
+
631
+ **TR:** HTTP framework (`express`, `elysia`, …) ile realtime **ayrı eksenler**. Realtime `ctr()` üzerinde `protocol: 'ws'` veya `'socketio'` kullanır — `tmp.yml`'deki `framework` değil. Her iki pipeline integration test ile doğrulanır (34 test geçer).
632
+
633
+ ### HTTP vs realtime / HTTP vs realtime
634
+
635
+ | Axis / Eksen | `tmp.yml` | Middleware | Dispatch |
636
+ |--------------|-----------|------------|----------|
637
+ | **HTTP** | `framework: elysia` | `dtoMiddleware()` | `res.json()` / Elysia set |
638
+ | **WebSocket** | `protocols: [http, ws]` | `realtimeMiddleware()` | `socket.send(JSON)` |
639
+ | **Socket.IO** | `protocols: [http, socketio]` | `realtimeMiddleware('socketio')` | `socket.emit(event, payload)` |
640
+
641
+ **EN:** Same controller class can serve HTTP **and** realtime — different properties, different `protocol` on `ctr()`.
642
+
643
+ **TR:** Aynı controller sınıfı HTTP **ve** realtime verebilir — farklı property, farklı `protocol`.
644
+
645
+ ### 3-step pattern / 3 adım kalıbı
646
+
647
+ ```
648
+ 1. realtimeMiddleware() → socket'a builder tak
649
+ 2. ctr({ logic }, { protocol }) → checks + logic + i18n (isteğe bağlı)
650
+ 3. dispatch otomatik → ws: send · socketio: emit
651
+ ```
652
+
653
+ ### `tmp.yml` — `protocols`
654
+
655
+ ```yaml
656
+ configs:
657
+ service:
658
+ framework: elysia # EN: HTTP only · TR: sadece HTTP
659
+ protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
660
+ ```
661
+
662
+ | `protocols` in tmp.yml | `realtimeMiddleware()` |
663
+ |------------------------|-------------------------|
664
+ | `[http, ws]` | `realtimeMiddleware()` → auto **ws** |
665
+ | `[http, socketio]` | `realtimeMiddleware()` → auto **socketio** |
666
+ | `[http, ws, socketio]` | **Must specify:** `realtimeMiddleware('ws')` or `realtimeMiddleware('socketio')` |
667
+
668
+ ### Native WebSocket (ws)
669
+
670
+ ```typescript
671
+ // source/controllers/chat.ts
672
+ import Controller from '@xrystal/core/loader/controller'
673
+
674
+ class ChatController extends Controller {
675
+ onMessage = this.ctr({
676
+ logic: async ({ req }) => ({
677
+ data: { echo: req.body },
678
+ message: '@successfully',
679
+ }),
680
+ }, { protocol: 'ws' })
681
+ }
682
+ export const chatCtrl = new ChatController()
683
+ ```
684
+
685
+ ```typescript
686
+ // source/index.ts — Express + ws on same port (example)
687
+ import { WebSocketServer } from 'ws'
688
+ import express from 'express'
689
+ import coreLoader from '@xrystal/core'
690
+ import { dtoMiddleware, realtimeMiddleware } from '@xrystal/core/utils'
691
+ import { chatCtrl } from './controllers/chat'
692
+
693
+ await coreLoader({})
694
+
695
+ const app = express()
696
+ app.use(dtoMiddleware('express'))
697
+
698
+ const server = app.listen(3000)
699
+ const wss = new WebSocketServer({ server })
700
+
701
+ wss.on('connection', (socket) => {
702
+ realtimeMiddleware()(socket, () => {}) // 1) builder attach
703
+ socket.on('message', chatCtrl.onMessage.with(socket)) // 2) ctr + 3) auto send
704
+ })
705
+ ```
706
+
707
+ **EN:** `with(socket)` binds the socket for that event — core calls `socket.send(JSON)` after `ctr()` finishes.
708
+
709
+ **TR:** `with(socket)` socket'ı o event'e bağlar — `ctr()` bitince core `socket.send(JSON)` çağırır.
710
+
711
+ ### Socket.IO
712
+
713
+ ```typescript
714
+ class ChatController extends Controller {
715
+ onChat = this.ctr({
716
+ logic: async () => ({ data: { ok: true }, message: '@successfully' }),
717
+ }, { protocol: 'socketio' })
718
+ }
719
+ ```
720
+
721
+ ```typescript
722
+ import { Server } from 'socket.io'
723
+ import coreLoader from '@xrystal/core'
724
+ import { realtimeMiddleware } from '@xrystal/core/utils'
725
+ import { chatCtrl } from './controllers/chat'
726
+
727
+ await coreLoader({})
728
+
729
+ const io = new Server(3001, { cors: { origin: '*' } })
730
+
731
+ io.use((socket, next) => realtimeMiddleware('socketio')(socket, next)) // 1) builder
732
+ io.on('connection', (socket) => {
733
+ socket.on('chat', chatCtrl.onChat.with(socket)) // 2+3) ctr → emit
734
+ })
735
+ ```
736
+
737
+ **EN:** Default emit event comes from Dto config (`socket.event`, default `'response'`). Override in `tmp.yml` → `loaders.dto`.
738
+
739
+ **TR:** Varsayılan emit event'i Dto config'den gelir (`socket.event`, default `'response'`). `tmp.yml` → `loaders.dto` ile override.
740
+
741
+ ### Without controller / Controller olmadan
742
+
743
+ **EN:** Plain function — use `runAction` when you don't need `checks` / i18n / `this.logger`.
744
+
745
+ **TR:** Düz fonksiyon — `checks` / i18n / `this.logger` gerekmiyorsa `runAction`.
746
+
747
+ ```typescript
748
+ import { runAction, getDtoRuntime } from '@xrystal/core/utils'
749
+
750
+ // WebSocket
751
+ socket.on('message', () =>
752
+ runAction({ protocol: 'ws', socket }, async () => {
753
+ return socket.builder.as.ok({ ping: 1 }).build()
754
+ }),
755
+ )
756
+
757
+ // Socket.IO
758
+ socket.on('ping', () =>
759
+ runAction({ protocol: 'socketio', socket }, async () => {
760
+ return getDtoRuntime().forSocket(socket).builder.as.ok({ pong: true }).build()
761
+ }),
762
+ )
763
+ ```
764
+
765
+ ### ws vs Socket.IO — transport farkı
766
+
767
+ | | WebSocket (ws) | Socket.IO |
768
+ |---|----------------|-----------|
769
+ | Wire / Kablo | `socket.send(JSON string)` | `socket.emit(event, object)` |
770
+ | `ctr()` protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
771
+ | Middleware | `realtimeMiddleware()` or `realtimeMiddleware('ws')` | `realtimeMiddleware('socketio')` |
772
+ | Same `FinalResult` | ✅ same builder | ✅ same builder |
773
+
774
+ **EN:** Pick **ws** for native WebSocket clients. Pick **socket.io** when you need rooms, fallback transport, or existing Socket.IO clients.
775
+
776
+ **TR:** Native WebSocket client → **ws**. Room, fallback transport veya mevcut Socket.IO client → **socket.io**.
777
+
778
+ ### Same logic, two protocols / Aynı logic, iki protocol
779
+
780
+ ```typescript
781
+ class ChatController extends Controller {
782
+ onWs = this.ctr({ logic: async () => ({ data: { via: 'ws' } }) }, { protocol: 'ws' })
783
+ onSio = this.ctr({ logic: async () => ({ data: { via: 'socketio' } }) }, { protocol: 'socketio' })
784
+ }
785
+ ```
786
+
787
+ ---
788
+
457
789
  ## Maintainer note / Geliştirici notu
458
790
 
459
- **EN:** This repo is the `@xrystal/core` source. npm publish and build pipeline live in repo scripts (`release:prepare`, `x/bin/scripts/`) — not needed for library consumers.
791
+ **EN:** This repo is the `@xrystal/core` source. Bump `package.json` → commit → `xry tag` (runs prepare + pushes `vX.Y.Z`; GitHub Publish workflow releases to npm). Consumers only need `bun add @xrystal/core`.
460
792
 
461
- **TR:** Bu repo `@xrystal/core` kaynak kodudur. npm publish ve build pipeline repo script'lerinde — kütüphane tüketicisi için gerekli değildir.
793
+ **TR:** Bu repo `@xrystal/core` kaynağıdır. `package.json` bump → commit → `xry tag` (prepare + `vX.Y.Z` push; GitHub Publish → npm). Tüketici için sadece `bun add @xrystal/core` yeter.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "author": "Yusuf Yasir KAYGUSUZ",
3
3
  "name": "@xrystal/core",
4
- "version": "3.38.3",
4
+ "version": "3.40.0",
5
5
  "description": "Project core for xrystal",
6
6
  "publishConfig": {
7
7
  "access": "public",
@@ -50,9 +50,7 @@
50
50
  },
51
51
  "type": "module",
52
52
  "bin": {
53
- "xcore": "./x/bin/main-cli.js",
54
- "xrystal": "./x/bin/main-cli.js",
55
- "tmp": "./x/bin/main-cli.js"
53
+ "xry": "./x/bin/main-cli.js"
56
54
  },
57
55
  "scripts": {
58
56
  "dev": "node x/bin/main-cli.js dev",
@@ -15,8 +15,9 @@ import {
15
15
  import { formatLoaderSummary, summarizeLoaders } from '../helpers/tmp-config.mjs'
16
16
  import { formatCreateHelp, formatCreateCommandHelp, LIST_BULLET } from '../helpers/cli-help.mjs'
17
17
  import { setupProjectGitHooks } from '../scripts/install-git-hooks.mjs'
18
+ import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
18
19
 
19
- export function registerCreateCommand(cli, { cliName = 'xcore', runtimeName, packageManager, installCommand, devCommand }) {
20
+ export function registerCreateCommand(cli, { cliName = CLI_PRIMARY_NAME, runtimeName, packageManager, installCommand, devCommand }) {
20
21
  cli
21
22
  .command('create <project-name> [target-path]')
22
23
  .description('Scaffold new service from GitHub template')
@@ -2,6 +2,7 @@ import chalk from 'chalk'
2
2
 
3
3
  import { printCommandHeader } from '../helpers/banner.mjs'
4
4
  import { resolveDistLayout } from '../helpers/project-artifacts.mjs'
5
+ import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
5
6
  import {
6
7
  getInstalledCoreVersion,
7
8
  getProjectRoot,
@@ -22,7 +23,7 @@ function printSection(title) {
22
23
  console.log(chalk.bold.cyan(`\n ${title}`))
23
24
  }
24
25
 
25
- export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
26
+ export function registerDoctorCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
26
27
  cli
27
28
  .command('doctor')
28
29
  .description('Check runtime, git, and @xrystal/core alignment')
@@ -75,7 +76,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
75
76
  console.log(` ${'source'.padEnd(18)}${chalk.bold(distLayout.layout.mainFolderPath)} ${chalk.gray('(paths.source)')}`)
76
77
  console.log(` ${'dist'.padEnd(18)}${chalk.bold(distLayout.distPrefix)} ${chalk.gray('(paths.special.dist)')}`)
77
78
  } else {
78
- console.log(chalk.yellow(' layout: tmp.yml not resolved — run xcore tmp'))
79
+ console.log(chalk.yellow(` layout: tmp.yml not resolved — run ${CLI_PRIMARY_NAME} tmp`))
79
80
  }
80
81
 
81
82
  printSection('CLI (tool)')
@@ -134,7 +135,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
134
135
  }
135
136
  console.log(` ${'working tree'.padEnd(18)}${state.isClean ? chalk.green('clean') : chalk.yellow('dirty')}`)
136
137
  const hookOk = isGitHookInstalled(root)
137
- console.log(` ${'pre-commit hook'.padEnd(18)}${hookOk ? chalk.green('installed') : chalk.yellow('missing')} ${chalk.gray('· xcore hooks install')}`)
138
+ console.log(` ${'pre-commit hook'.padEnd(18)}${hookOk ? chalk.green('installed') : chalk.yellow('missing')} ${chalk.gray(`· ${CLI_PRIMARY_NAME} hooks install`)}`)
138
139
  } catch (error) {
139
140
  console.log(chalk.yellow(` git: ${error.message}`))
140
141
  }
@@ -145,7 +146,7 @@ export function registerDoctorCommand(cli, { cliName = 'xcore' } = {}) {
145
146
  console.log(` ${'outDir'.padEnd(18)}${chalk.bold(toolchain.outDir)}`)
146
147
  const tsAudit = auditTsconfigAlignment(root)
147
148
  if (tsAudit.missing) {
148
- console.log(chalk.yellow(` ${'tsconfig'.padEnd(18)}missing · run xcore sync-toolchain`))
149
+ console.log(chalk.yellow(` ${'tsconfig'.padEnd(18)}missing · run ${CLI_PRIMARY_NAME} sync`))
149
150
  } else if (tsAudit.ok) {
150
151
  console.log(chalk.green(` ${'tsconfig'.padEnd(18)}aligned with tmp.yml`))
151
152
  } else {
@@ -4,8 +4,9 @@ import { printCommandHeader } from '../helpers/banner.mjs'
4
4
  import { readCliPackageJson } from '../helpers/project-root.mjs'
5
5
  import { installGitHooks, isGitHookInstalled } from '../scripts/install-git-hooks.mjs'
6
6
  import { getProjectRoot } from '../helpers/project-root.mjs'
7
+ import { CLI_PRIMARY_NAME } from '../helpers/cli-identity.mjs'
7
8
 
8
- export function registerHooksCommand(cli, { cliName = 'xcore' } = {}) {
9
+ export function registerHooksCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
9
10
  const hooks = cli
10
11
  .command('hooks')
11
12
  .description('Install git hooks for version bump checks')