@xrystal/core 3.55.75 → 3.55.84

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.
package/README.md CHANGED
@@ -1,944 +1,66 @@
1
1
  # @xrystal/core
2
2
 
3
- > **EN** — Runtime framework: API services & frontends, workspace CLI, DI loaders, live `tmp.yml`, multi-protocol.
4
- > **TR** — Runtime framework: API & frontend, workspace CLI, DI loader'lar, canlı `tmp.yml`, çoklu protokol.
3
+ > **EN** — Runtime library and `xry` CLI for TypeScript services: DI loaders, live `x/tmp.yml`, `ctr()` controllers, DTO / i18n / trace, HTTP and realtime.
4
+ > **TR** — TypeScript servisleri için runtime kütüphanesi ve `xry` CLI: DI loader'lar, canlı `x/tmp.yml`, `ctr()` controller'lar, DTO / i18n / trace, HTTP ve realtime.
5
5
 
6
- **CLI:** `xry` · **Version:** `3.52.5` · [npm](https://www.npmjs.com/package/@xrystal/core)
6
+ **CLI:** `xry` · [npm](https://www.npmjs.com/package/@xrystal/core)
7
7
 
8
8
  ---
9
9
 
10
- ## Platform services / Platform servisleri
10
+ ## Overview / Genel bakış
11
11
 
12
- **EN:** Consumer microservices in `../services/` — table below is the **pin matrix** (service pkg + `@xrystal/core`; bump rows when you ship). Apply pins with **`xry sync`** (not manual `bun add` per repo).
12
+ **EN:** `@xrystal/core` is an npm package (default export `coreLoader`) plus the **`xry`** CLI. You keep your own repo layout — monorepo, Docker, or a greenfield app from `xry create`. Cluster deploy, image pins, and GitOps are **outside** this package.
13
13
 
14
- **TR:** `../services/` altındaki microservice'ler — tablo **pin matrisi** (servis sürümü + `@xrystal/core`; release sonrası satırları güncelle). Pin uygulama: **`xry sync`** (her repo için elle `bun add` yazma).
15
-
16
- | Repo folder | `tmp.yml` name | Role | Service pkg | `@xrystal/core` |
17
- |-------------|----------------|------|-------------|-----------------|
18
- | `api-core-svc` | `core` | Core domain API | `1.0.24` | `3.52.5` |
19
- | `api-cron-svc` | `crons` | Scheduled jobs / Kafka queue worker | `0.1.25` | `3.52.5` |
20
- | `api-gateway-svc` | `gateway` | Edge gateway, routing, cache, Mongo config | `2.0.49` | `3.52.5` |
21
- | `api-gpt-svc` | `gpt` | GPT / AI features | `1.0.22` | `3.52.5` |
22
- | `api-iam-svc` | `iam` | Identity & access management | `0.7.26` | `3.52.5` |
23
- | `api-log-svc` | `log` | Logging service | `1.0.20` | `3.52.5` |
24
- | `api-websocket-svc` | `websocket` | WebSocket / realtime | `0.8.31` | `3.52.5` |
25
-
26
- **SSL / TLS helpers** (since 3.49.0): import from loader subpaths, not `@xrystal/core/utils`:
27
-
28
- ```ts
29
- import { resolveKafkaJsSsl } from '@xrystal/core/loader/kafka'
30
- import { resolveRedisSocketOptions } from '@xrystal/core/loader/redis'
31
- import { resolveMongoConnectOptions } from '@xrystal/core/loader/mongo'
32
- ```
33
-
34
- **After `@xrystal/core` publish / core yayın sonrası:** workspace root → `xry sync` (all linked `api/*` pins to CLI version). One service → `cd` that repo → `xry sync`. Build/tag images = each service’s own release flow (see monorepo release order in infra).
14
+ **TR:** `@xrystal/core` npm paketi (`coreLoader`) ve **`xry` CLI**. Repo düzeni sende — monorepo, Docker veya `xry create`. Cluster deploy, image pin ve GitOps **bu paketin dışında**.
35
15
 
36
16
  ---
37
17
 
38
- ## What's new in 3.46.0 / 3.46.0'da ne değişti
18
+ ## Features / Özellikler
39
19
 
40
- **EN:** SSOT architecture is closed — identity, runtime tooling, paths, and CLI share one source of truth. Missing values throw; layout drift auto-heals.
41
-
42
- **TR:** SSOT mimarisi kapandı — kimlik, runtime tooling, path ve CLI tek kaynaktan. Eksik değer throw; path drift otomatik heal.
43
-
44
- | Change / Değişiklik | EN | TR |
45
- |---------------------|----|----|
46
- | **Identity** | CLI display = `@xrystal/core`; invoke bin = `xry` | Kimlik paket adı, bin `xry` |
47
- | **defaults.json** | Package name, CLI, brand, `runtimes{}`, `bundlers[]` | Paket kimliği + tooling haritası |
48
- | **tmp.yml** | Layout, `global.runtime`, vars, `build.bundler` | Proje layout + runtime |
49
- | **Live pulse** | tmp watch → loader sync; path drift → tsconfig heal | Canlı sync + otomatik heal |
50
- | **Strict normalize** | Unknown/missing `runtime` / `bundler` throws (empty bundler → `auto`) | Sessiz `?? 'bun'` yok |
51
- | **Tooling map** | Scripts/build/CLI use `defaults.runtimes` (no `bun` / `x/dist` literals) | Hardcode temiz |
52
- | **`xry sync`** | Force / CI only — daily ritual değil | Force / CI |
53
-
54
- ```bash
55
- npx xry sync # force-apply tmp.yml → tsconfig (usually auto)
56
- npx xry sync --dry-run
57
- ```
20
+ | Area / Alan | EN | TR |
21
+ |-------------|----|----|
22
+ | **DI** | Awilix loaders, lifecycle hooks (`onInit`, `onAfterInit`, …) | Awilix loader'lar, yaşam döngüsü hook'ları |
23
+ | **Config** | Live `x/tmp.yml`; `xry sync` heals paths | Canlı `x/tmp.yml`; path düzeltme |
24
+ | **HTTP** | `ctr()` endpoint pipeline; Express / Elysia / raw Node | `ctr()` pipeline; Express / Elysia / Node |
25
+ | **DTO & UX** | `@xrystal/dto`, i18n, request trace, logging | DTO, i18n, trace, log |
26
+ | **Data (optional)** | Redis, MongoDB, Kafka loaders | İsteğe bağlı Redis / Mongo / Kafka |
27
+ | **Realtime** | WebSocket / Socket.IO on the same pattern as HTTP | HTTP ile aynı kalıpta ws / Socket.IO |
28
+ | **CLI** | `xry dev`, `build`, `start`, `test`, `create`, `version`, `tag` | Geliştirme, build, scaffold, sürüm |
58
29
 
59
30
  ---
60
31
 
61
- ## Why / Neden
62
-
63
- **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`.
32
+ ## Use cases / Kullanım senaryoları
64
33
 
65
- **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.
66
-
67
- ```bash
68
- # EN: existing project — kernel only · TR: mevcut proje — sadece kernel
69
- bun add @xrystal/core
70
- npx xry tmp # seed x/tmp.yml into YOUR layout
71
- # tsconfig paths auto-heal from tmp.yml (xry sync = force / CI)
72
- # wire coreLoader + dtoMiddleware in your entry file
73
- ```
34
+ | Scenario / Senaryo | EN | TR |
35
+ |--------------------|----|----|
36
+ | **Greenfield** | `npx xry create <name> .` → `source/`, `x/tmp.yml`, scripts | Sıfırdan proje iskeleti |
37
+ | **Existing HTTP app** | Add dependency; wire `coreLoader` + your framework adapter | Mevcut Express / Elysia uygulamasına ekleme |
38
+ | **Realtime** | Enable `protocols` in tmp; `ctr({ protocol: 'ws' \| 'socket.io' })` | Aynı DI/config ile websocket veya Socket.IO |
74
39
 
75
40
  ---
76
41
 
77
- ## Quick start / Hızlı başlangıç
78
-
79
- ### Path A — `create` (starter template / başlangıç şablonu)
80
-
81
- **EN:** Optional — clone GitHub template when you have no project yet.
82
-
83
- **TR:** İsteğe bağlı — henüz proje yoksa GitHub template klonla.
42
+ ## Installation / Kurulum
84
43
 
85
44
  ```bash
86
- mkdir my-api && cd my-api
87
- bun init -y
88
45
  bun add @xrystal/core
89
- npx xry create my-api .
90
- ```
91
-
92
- ```bash
93
- bun add elysia # EN: or express · TR: veya express
94
- bun run dev
95
- npx xry doctor # EN: setup check · TR: kurulum kontrolü
96
- ```
97
-
98
- ### Path B — Your project + kernel (most common / en yaygın)
99
-
100
- **EN:** Keep your folder names — only add `tmp.yml`, `coreLoader`, controllers.
101
-
102
- **TR:** Kendi klasör adların kalsın — sadece `tmp.yml`, `coreLoader`, controller ekle.
103
-
104
- ```bash
105
- mkdir my-api && cd my-api
106
- bun init -y
107
- bun add @xrystal/core elysia
108
- npx xry tmp # EN: create x/tmp.yml from seed if missing · TR: yoksa seed'den oluşturur
109
- npx xry doctor # EN: optional health check · TR: isteğe bağlı sağlık kontrolü
110
- ```
111
-
112
- `package.json`:
113
-
114
- ```json
115
- {
116
- "dependencies": {
117
- "@xrystal/core": "^3.46.0",
118
- "elysia": "^1.4.19"
119
- },
120
- "scripts": {
121
- "dev": "xry dev",
122
- "build": "xry build",
123
- "start": "xry start",
124
- "test": "xry test",
125
- "sync": "xry sync",
126
- "doctor": "xry doctor"
127
- }
128
- }
129
- ```
130
-
131
- **EN:** No global `xry` install — runs via `node_modules/.bin` after `bun add @xrystal/core`.
132
-
133
- **TR:** Global `xry` gerekmez — `@xrystal/core` kurulunca `node_modules/.bin` üzerinden çalışır.
134
-
135
- ### Project layout / Proje düzeni
136
-
137
- ```
138
- my-api/
139
- ├── package.json
140
- ├── source/
141
- │ ├── index.ts # EN: dev entry (xry dev) · TR: dev girişi
142
- │ └── controllers/
143
- └── x/
144
- └── tmp.yml # EN: runtime + path SSOT · TR: runtime + path tek kaynak
145
- ```
146
-
147
- ### Config sources / Config kaynakları
148
-
149
- | File / Dosya | Owns / Sahip olduğu |
150
- |--------------|---------------------|
151
- | `defaults.json` (package) | Identity (`@xrystal/core`), CLI bin (`xry`), brand, `runtimes` / `bundlers` tooling |
152
- | `x/tmp.yml` | Service paths, loaders, protocols, `global.runtime`, bundler · layout seed |
153
- | `tsconfig.json` | Compiler language options; path layout auto-heals from `tmp.yml` |
154
-
155
- **EN:** Edit `tmp.yml` for your project. Package defaults stay inside `@xrystal/core` — do not hardcode runtime/bin/path names in app code.
156
-
157
- **TR:** Projede `tmp.yml` düzenle. Paket default'ları `@xrystal/core` içinde kalır — uygulama kodunda runtime/bin/path hardcode etme.
158
-
159
- ### Minimal `x/tmp.yml`
160
-
161
- ```yaml
162
- configs:
163
- global:
164
- runtime: bun # bun | node
165
- service:
166
- name: my-api
167
- framework: elysia # express | elysia | node | fetch
168
- paths:
169
- root: ./x
170
- source: ./source
171
- protocols: [http]
172
- build:
173
- bundler: auto # auto → tsc (recommended) | bun | tsc | esbuild
174
- typecheck: false # optional tsc --noEmit before emit
175
- loaders:
176
- dto: { withDefaultHeaders: true }
177
- loggers: { logLevel: info }
178
- controller: {}
179
- ```
180
-
181
- ### Service build / Servis build
182
-
183
- **EN:** `bundler: auto` → **`tsc`** (full `source/` tree → `x/dist`). Post-steps: `tsc-alias` → `fix-dist-imports` → `clean-dist-tests` (same as core). This keeps `loader/kafka`, relative imports, and `import.meta.url` paths valid in the container.
184
-
185
- **TR:** `bundler: auto` → **`tsc`** (tüm `source/` ağacı `x/dist`'e). Sonrasında `tsc-alias` + import düzeltme — pod'da kafka/loader modülleri kaybolmaz.
186
-
187
- | `build.bundler` | Behavior / Davranış |
188
- |-----------------|---------------------|
189
- | `auto` / `tsc` | Full tree emit via tsconfig `include` (recommended) |
190
- | `bun` | Single entry `source/index.ts`, `--packages external` (not multi-entry) |
191
- | `esbuild` | Single entry bundle; `@/` aliases need tsc or pre-alias |
192
-
193
- **EN:** `@xrystal/core` itself uses a separate **core** build (package exports entries). Your service only builds **your** `source/` — `@xrystal/core` comes from `node_modules`.
194
-
195
- **TR:** `@xrystal/core` paketi kendi core build'ini kullanır. Servis build'i sadece **senin** `source/` klasörünü derler; core `node_modules`'dan gelir.
196
-
197
- ### Path alias `@/` / `@/` path alias
198
-
199
- **EN:** `@/*` maps to your **source folder** (`source/*`), not project root — same as NestJS `@/` → `src/*`, not repo root.
200
-
201
- **TR:** `@/*` proje root'u değil **source klasörünü** gösterir (`source/*`) — NestJS'teki `@/` → `src/*` gibi.
202
-
203
- | Write / Yaz | Means / Anlam |
204
- |-------------|---------------|
205
- | `@/utils/foo` | `source/utils/foo` ✅ |
206
- | `@/source/utils/foo` | legacy — treated as `@/utils/foo` |
207
- | `logs` in tmp `loadPath` | relative to `paths.root` (`x/logs`) |
208
-
209
- **EN:** `loadPath: '@/utils/helpers/configs/index'` resolves to `source/…` in dev and `x/dist/…` in prod when `source/` is absent.
210
-
211
- **TR:** tmp.yml `loadPath` prod'da `source/` yoksa otomatik `x/dist/` fallback kullanır.
212
-
213
- ### First endpoint / İlk endpoint (~5 min)
214
-
215
- ```typescript
216
- // source/controllers/user.ts
217
- import Controller from '@xrystal/core/loader/controller'
218
-
219
- class UserController extends Controller {
220
- list = this.ctr({
221
- logic: async () => ({ data: [{ id: 1 }], message: '@successfully user' }),
222
- })
223
- }
224
- export const userCtrl = new UserController()
225
- ```
226
-
227
- ```typescript
228
- // source/index.ts
229
- import { Elysia } from 'elysia'
230
- import coreLoader from '@xrystal/core'
231
- import { dtoMiddleware } from '@xrystal/core/utils'
232
- import { userCtrl } from './controllers/user'
233
-
234
- await coreLoader({})
235
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
236
- ```
237
-
238
- ```bash
239
- bun run dev
240
- # GET http://localhost:3000/users
241
- ```
242
-
243
- ---
244
-
245
- ## Daily commands / Günlük komutlar
246
-
247
- | Command / Komut | EN | TR |
248
- |-----------------|----|----|
249
- | `xry create [name] [path]` | Start project from template + `tmp.yml` | Template + `tmp.yml` ile proje başlat |
250
- | `xry project` | **Context**: workspace root, inner service, standalone, or core library | **Bağlam**: workspace / servis / core |
251
- | `xry workspaces` | **Global registry** `~/.xrystal` (not tmp.yml) | Global kayıt defteri |
252
- | `xry create <name> --workspace` | Outer `./tmp.yml` + **api/general** + admin/web | Dış tmp + api/general |
253
- | `xry tmp` | Inner `x/tmp.yml` or outer workspace tmp; **`end.version` = schema (1)** | tmp.yml · şema sürümü |
254
- | `xry sync` | Inner tsconfig + pin `@xrystal/core` + registry (workspace mode) | tsconfig + core pin |
255
- | `xry config sync` | Copy TLS bundle + kubeconfig into `~/.xrystal` (explicit `--tls-from` / `--kubeconfig-from`) | PEM + kubeconfig → `~/.xrystal` |
256
- | `xry config tls` / `xry config kubeconfig` | Pin paths in `~/.xrystal/config.json` | Kalıcı path kaydı |
257
- | `xry tp connect --ns dev` / `xry tp intercept <deploy> --ns dev` | Telepresence connect / local intercept (`dev` = alias, not namespace) | Telepresence bağlan / local intercept |
258
- | `xry workspaces` | List `~/.xrystal` workspaces + linked projects | Kayıtlı workspace listesi |
259
- | `xry dev` | Watch `source/index.ts` + dev env | `source/index.ts` watch + dev env |
260
- | `xry build` | `tsc` full tree → dist (auto default) + alias/fix post-steps | `tsc` ile tüm `source/` → dist |
261
- | `xry start` | Run `x/dist` + prod env | `x/dist` + prod env |
262
- ### Laptop cluster + TLS (`xry config sync`)
263
-
264
- Copy **explicit** sources into `~/.xrystal` — core does not discover infra repos or scan the disk.
265
-
266
- | Output | Purpose |
267
- |--------|---------|
268
- | `~/.xrystal/kubeconfig` | `xry tp connect` (also saved in `config.json`) |
269
- | `~/.xrystal/certificates/` | Private CA + client PEMs (`ca.crt`, `mongodb.pem`, …) |
270
-
271
- ```bash
272
- # First time (paths you choose — ops bundle folder + kubeconfig file)
273
- xry config sync \
274
- --tls-from /path/to/pem-tree-or-flat \
275
- --kubeconfig-from /path/to/cluster.kubeconfig
276
-
277
- # Repeat (uses saved syncTlsFrom / syncKubeconfigFrom in ~/.xrystal/config.json)
278
- xry config sync
279
-
280
- # Or shell profile
281
- export XRY_SYNC_TLS_FROM=/path/to/certs
282
- export XRY_SYNC_KUBECONFIG_FROM=/path/to/kubeconfig
283
- ```
284
-
285
- **TLS source shape:** sync accepts tree or flat input but **stores flat only** under `~/.xrystal/certificates/` (`ca.crt`, `mongodb.pem`, … — same basenames as `/etc/tls/infra`).
286
-
287
- **Intercept:** before `xry dev`, `xry tp rewrite-env` patches `.env.telepresence` in place (only when matching PEM exists in `~/.xrystal/certificates`). When intercept ends (`Ctrl+C`, crash, or exit) or `xry tp stop`, cluster env snapshot is removed and empty scaffold is restored.
288
-
289
- **Unix optional:** `xry config sync --mirror-etc` copies flat PEMs to `/etc/tls/infra` (pod-style paths). Default is **off** — prefer auto path rewrite on dev (below).
290
-
291
- **TR:** PEM + kubeconfig’i senin gösterdiğin dosyalardan `~/.xrystal` altına kopyalar. Otomatik infra araması yok. Tekrar için `config.json` içindeki kaynaklar veya env.
292
-
293
- ### Runtime env (k8s / Docker) — since 3.55.18
294
-
295
- **EN:** `.env.telepresence` (cluster via intercept) is **rewritten in place** for TLS file paths (`/etc/tls/infra/<name>` → `~/.xrystal/certificates/<name>` when that file exists). No second override file. Optional `.env.local`. **Windows:** forward slashes in URIs (`C:/Users/.../.xrystal/certificates/ca.crt`). PEMs flat under `~/.xrystal/certificates` first (`config sync`). Not baked into images; k8s uses Secret `envFrom`.
296
-
297
- **TR:** TLS path rewrite tek dosyada; `tp stop` snapshot’ı siler. PEM’ler düz `~/.xrystal/certificates`.
298
-
299
- ### `x/environments/.env.local` (laptop, gitignore)
300
-
301
- | | |
302
- |---|---|
303
- | **Committed?** | **No** — stays on your machine in the service tree (`.gitignore`). |
304
- | **When loaded?** | Every **`xry dev`** / laptop **`xry start`**: after `.env.telepresence` (later file wins on same key). |
305
- | **Use for** | BM host overrides, new feature flags, local-only vars, anything not in cluster snapshot. |
306
- | **Not for** | Image / k8s — cluster uses Secret; never `COPY` into Dockerfile. |
307
-
308
- `xry tp intercept` scaffolds empty `.env.local` if missing.
309
-
310
- **Infra preflight:** Before Kafka/Redis/Mongo connect, TCP checks from tmp.yml + env. **Default fail-fast** in cluster and plain local dev. **Telepresence intercept** (pod env on laptop, no service-account token): lenient by default + 2s probe — override with `STRICT_INFRA_PREFLIGHT=1`.
311
-
312
- **Docker / Compose:** Image `CMD ["bun", "xry", "start"]` (dev: `xry dev`). Runtime skips `x/environments` when `/.dockerenv` or k8s is detected (optional override: `XRY_RUNTIME=container|docker|k8s`). Compose: `env_file:` on `x/docker/docker-compose*.yml` — not `COPY` env into the image.
313
- | `xry test` | Run `x/tests` | `x/tests` çalıştır |
314
- | `xry doctor` | CLI, runtime, package health | CLI, runtime, paket uyumu |
315
- | `xry tag` | Core → npm publish · service → `v<CalVer>` git tag | Core npm · servis GHCR tag |
316
- | `bun run release:patch` | Core SemVer patch · service CalVer (+pN) | Core patch · servis CalVer patch |
317
- | `bun run release:minor` | **Core only** (`-xrystal-core`) | **Sadece core** |
318
- | `bun run release:major` | **Core only** | **Sadece core** |
319
-
320
- ### Release scripts (general — tek kaynak)
321
-
322
- | Repo | `package.json` scripts | Bump |
323
- |---|---|---|
324
- | **`-xrystal-core`** | `release:patch`, `release:minor`, `release:major`, `tag` | SemVer |
325
- | **`api-*-svc`** (deployed) | `release:patch`, `tag` | CalVer (branch → UTC + `pN`) |
326
- | **`api-gpt-svc`** (template, no cluster deploy) | `release:patch`, `minor`, `major`, `tag` | SemVer **or** CalVer — `version` şekline göre CLI |
327
-
328
- **EN:** Deployed services: patch + tag only. **`api-gpt-svc`** is the full script template (minor/major when `package.json` is SemVer; CalVer repos use patch only in practice).
329
-
330
- **TR:** Canlı servis: `bun run release:patch` → commit → `bun run tag`. Yeni servis / örnek: `api-gpt-svc` `package.json` scripts bloğunu kopyala.
331
-
332
- ---
333
-
334
- ## Platform features / Platform özellikleri
335
-
336
- **EN:** What the kernel gives you — one line each + minimal example.
337
-
338
- **TR:** Kernel'in verdiği yetenekler — tek satır + kısa örnek.
339
-
340
- | Feature / Özellik | EN | TR | Example / Örnek |
341
- |-------------------|----|----|-----------------|
342
- | **Boot / DI** | Awilix loaders: System, Logger, Kafka, Dto, i18n, … | Awilix loader'lar | `await coreLoader({})` |
343
- | **Live `tmp.yml`** | Edit file → loaders re-sync; path changes heal tsconfig | Dosya → loader sync; path → tsconfig heal | `paths.source` rename → tsconfig updates |
344
- | **`ctr()` pipeline** | `checks → logic → response`, no `res.json()` | Endpoint pipeline | `list = this.ctr({ logic: async () => ({ data: [] }) })` |
345
- | **DTO responses** | Standard API shape via `@xrystal/dto` | Standart API cevabı | `return { data: [], message: '@successfully user' }` |
346
- | **Trace** | `requestId` per request/job (ALS) | İstek/job trace id | `req.requestId` · `runWithTrace('job-1', fn)` |
347
- | **i18n** | i18next + 50+ business message keys | Çok dilli mesajlar | `'@successfully user'` · `req.t('responseMessage.successfully')` |
348
- | **G store** | App-wide state from `tmp.yml` vars | Global state | `G.get('maintenance')` · `checks: () => G.get('x') ? fail : true` |
349
- | **Logger** | Winston: console + daily rotate files | Dosya + konsol log | `this.logger.log(LoggerLayerEnum.INFO, 'ok')` |
350
- | **Kafka logs** | Structured logs → Kafka topic | Log → Kafka | `loaders.loggers` + `configs.kafkaLogsTopic` in env |
351
- | **HTTP client** | Retries + circuit breaker + trace header | Dayanıklı outbound HTTP | extend `BaseApiClient` from loader/clients |
352
- | **Scope validate** | OAuth-style `resource:permission` check | Scope doğrulama | `validateScopes({ scopes, resources, permissions })` |
353
- | **Realtime** | Same `ctr()` for ws / socket.io | HTTP + ws aynı kalıp | `ctr({ logic }, { protocol: 'ws' })` — [guide](#realtime--websocket--socketio) |
354
- | **CLI (`xry`)** | create, tmp, sync, dev, build, start, test, doctor | Servis toolchain | `"dev": "xry dev"` · `"sync": "xry sync"` |
355
- | **Shutdown** | Graceful cleanup on SIGTERM | Temiz kapanış | auto via `registerGracefulShutdown()` on boot |
356
-
357
- ```typescript
358
- // EN: minimal kernel boot in ANY entry file · TR: herhangi bir giriş dosyasında
359
- import coreLoader from '@xrystal/core'
360
- import { dtoMiddleware, G, runWithTrace } from '@xrystal/core/utils'
361
- import Controller from '@xrystal/core/loader/controller'
362
-
363
- await coreLoader({})
364
-
365
- class HealthController extends Controller {
366
- check = this.ctr({
367
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
368
- logic: async ({ req }) => ({
369
- data: { ok: true, trace: req.requestId },
370
- message: '@successfully',
371
- }),
372
- })
373
- }
374
- export const healthCtrl = new HealthController()
375
-
376
- await runWithTrace('nightly-job', async () => {
377
- // EN: cron/queue jobs get trace too · TR: cron/queue job'ları da trace alır
378
- })
379
- ```
380
-
381
- ---
382
-
383
- ## Framework quickstarts / Framework hızlı başlangıç
384
-
385
- **EN:** Same kernel — swap only `framework` in `tmp.yml` + middleware line.
386
-
387
- **TR:** Aynı kernel — sadece `tmp.yml` → `framework` ve middleware satırı değişir.
388
-
389
- ### Elysia (default)
390
-
391
- ```yaml
392
- # x/tmp.yml
393
- configs:
394
- service:
395
- framework: elysia
396
- paths: { root: ./x, source: ./source }
397
- ```
398
-
399
- ```typescript
400
- import { Elysia } from 'elysia'
401
- import coreLoader from '@xrystal/core'
402
- import { dtoMiddleware } from '@xrystal/core/utils'
403
- import { userCtrl } from './controllers/user'
404
-
405
- await coreLoader({})
406
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
407
- ```
408
-
409
- ### Express
410
-
411
- ```yaml
412
- configs:
413
- service:
414
- framework: express
415
- ```
416
-
417
- ```typescript
418
- import express from 'express'
419
- import coreLoader from '@xrystal/core'
420
- import { dtoMiddleware } from '@xrystal/core/utils'
421
- import { userCtrl } from './controllers/user'
422
-
423
- await coreLoader({})
424
- const app = express()
425
- app.use(dtoMiddleware('express'))
426
- app.get('/users', userCtrl.list)
427
- app.listen(3000)
428
- ```
429
-
430
- ### Node (raw http)
431
-
432
- ```yaml
433
- configs:
434
- service:
435
- framework: node
436
- ```
437
-
438
- ```typescript
439
- import http from 'node:http'
440
- import coreLoader from '@xrystal/core'
441
- import { userCtrl } from './controllers/user'
442
-
443
- await coreLoader({})
444
- http.createServer((req, res) => userCtrl.list(req, res)).listen(3000)
445
- ```
446
-
447
- ### Fetch / Bun.serve
448
-
449
- ```yaml
450
- configs:
451
- service:
452
- framework: fetch
453
- ```
454
-
455
- ```typescript
456
- import coreLoader from '@xrystal/core'
457
- import { userCtrl } from './controllers/user'
458
-
459
- await coreLoader({})
460
- Bun.serve({ fetch: (req) => userCtrl.list(req) })
461
- ```
462
-
463
- `fetch` — no global middleware; `ctr()` attaches builder per request.
464
-
465
- **EN:** WebSocket & Socket.IO — full guide at the end: [Realtime](#realtime--websocket--socketio).
466
-
467
- **TR:** WebSocket & Socket.IO — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
468
-
469
- | Framework | `tmp.yml` | Middleware |
470
- |-----------|-----------|------------|
471
- | elysia | `framework: elysia` | `dtoMiddleware()` |
472
- | express | `framework: express` | `dtoMiddleware('express')` |
473
- | node | `framework: node` | `dtoMiddleware('node')` |
474
- | fetch | `framework: fetch` | — (per-request in `ctr`) |
475
-
476
- ---
477
-
478
- ## Reference / Referans
479
-
480
- | Topic / Konu | Section / Bölüm |
481
- |--------------|-----------------|
482
- | Why kernel vs template | [Why](#why--neden) |
483
- | All platform capabilities | [Platform features](#platform-features--platform-özellikleri) |
484
- | Per-framework boot | [Framework quickstarts](#framework-quickstarts--framework-hızlı-başlangıç) |
485
- | Controller, `ctr()` | [Controller](#controller) |
486
- | Express / Elysia detail | [Framework](#express--elysia) |
487
- | DI, boot, tmp watch | [DI](#di--tmpyml) |
488
- | Locale / dil | [i18n](#i18n--locale) |
489
- | Global state | [G store](#g-store) |
490
- | WebSocket & Socket.IO | [Realtime](#realtime--websocket--socketio) |
491
- | API response shape | [DTO](#dto-responses--dto-cevapları) |
492
- | End-to-end flow | [Usage guide](#usage-guide--kullanım-rehberi) |
493
-
494
- ---
495
-
496
- ## Controller
497
-
498
- **EN:** One endpoint = one class property + `this.ctr()`. Wire URL → property. No manual `res.json()`.
499
-
500
- **TR:** Bir endpoint = bir property + `this.ctr()`. URL → property bağla. `res.json()` yazmazsın.
501
-
502
- ```typescript
503
- import Controller from '@xrystal/core/loader/controller'
504
-
505
- class UserController extends Controller {
506
- list = this.ctr({
507
- logic: async ({ req }) => {
508
- return { data: [], message: '@successfully user' }
509
- },
510
- })
511
- }
512
- export const userCtrl = new UserController()
513
- ```
514
-
515
- ```typescript
516
- app.use(dtoMiddleware())
517
- app.get('/users', userCtrl.list)
518
- ```
519
-
520
- | In `logic` / Logic içinde | EN | TR |
521
- |---------------------------|----|----|
522
- | `req.body`, `req.query`, `req.params` | Normalized input | Normalize girdi |
523
- | `req.requestId` | Trace id | İzleme id |
524
- | `req.t` | i18n function | Çeviri fonksiyonu |
525
- | `this.logger` | Logger from DI | DI logger |
526
-
527
- ---
528
-
529
- ## Express & Elysia
530
-
531
- **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.
532
-
533
- **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.
534
-
535
- **Express**
536
-
537
- ```yaml
538
- configs:
539
- service:
540
- framework: express
541
- ```
542
-
543
- ```typescript
544
- import express from 'express'
545
- import coreLoader from '@xrystal/core'
546
- import { dtoMiddleware } from '@xrystal/core/utils'
547
-
548
- await coreLoader({})
549
- const app = express()
550
- app.use(dtoMiddleware('express'))
551
- app.get('/users', userCtrl.list)
552
- app.listen(3000)
553
- ```
554
-
555
- **Elysia**
556
-
557
- ```yaml
558
- configs:
559
- service:
560
- framework: elysia
561
- ```
562
-
563
- ```typescript
564
- import { Elysia } from 'elysia'
565
- import coreLoader from '@xrystal/core'
566
- import { dtoMiddleware } from '@xrystal/core/utils'
567
-
568
- await coreLoader({})
569
- new Elysia().use(dtoMiddleware()).get('/users', userCtrl.list).listen(3000)
570
- ```
571
-
572
- | Framework | Middleware | EN | TR |
573
- |-----------|------------|----|----|
574
- | express | `dtoMiddleware('express')` | Default Express stack | Express stack |
575
- | elysia | `dtoMiddleware()` | Default Elysia stack | Elysia stack |
576
- | node | `dtoMiddleware('node')` | Raw `createServer` | Ham HTTP |
577
- | fetch | none | `ctr()` attaches builder per request | Request başına builder |
578
-
579
- **EN:** Realtime (ws / socket.io) is separate from HTTP — full guide at the end: [Realtime](#realtime--websocket--socketio).
580
-
581
- **TR:** Realtime (ws / socket.io) HTTP'den ayrı — tam rehber sonda: [Realtime](#realtime--websocket--socketio).
582
-
583
- ---
584
-
585
- ## DI & tmp.yml
586
-
587
- **EN:** Single source of truth: **`x/tmp.yml`** at project root. Loaders read a live snapshot, not the file directly.
588
-
589
- **TR:** Tek kaynak: proje kökündeki **`x/tmp.yml`**. Loader'lar dosyayı değil canlı snapshot'ı okur.
590
-
591
- | Step / Adım | EN | TR |
592
- |-------------|----|----|
593
- | 1 | `await coreLoader({})` at boot — Awilix DI (System, Logger, Dto, Controller, …) | Boot'ta `coreLoader` — Awilix DI |
594
- | 2 | Edit `tmp.yml` → loaders auto-sync (log level, i18n, dto, …) | `tmp.yml` değişince loader'lar sync |
595
- | 3 | Read config at runtime: `getRuntimeTmpConfigs()` or DI `System` | Runtime config: `getRuntimeTmpConfigs()` veya `System` |
596
-
597
- ```typescript
598
- import coreLoader from '@xrystal/core'
599
- import { getRuntimeTmpConfigs } from '@xrystal/core/utils'
600
-
601
- await coreLoader({})
602
- const tmp = getRuntimeTmpConfigs()
603
- ```
604
-
605
- **EN:** `loaders.*` in `tmp.yml` enables subsystems (logger, localization, dto, system/gStore, …).
606
-
607
- **TR:** `tmp.yml` içindeki `loaders.*` hangi alt sistemlerin açılacağını belirler.
608
-
609
- ---
610
-
611
- ## i18n / locale
612
-
613
- **EN:** i18next via `loaders.localization` in `tmp.yml`. Use `@key` in responses or `req.t()`.
614
-
615
- **TR:** `loaders.localization` ile i18next. Cevaplarda `@anahtar` veya `req.t()` kullan.
616
-
617
- ```yaml
618
- loaders:
619
- localization:
620
- fallbackLang: en
621
- preloadLangs: [en, tr]
622
- ```
623
-
624
- ```typescript
625
- return { message: '@successfully user' }
626
- // or / veya req.t('responseMessage.successfully')
627
- ```
628
-
629
- **EN:** Express — mount i18next middleware **before** `dtoMiddleware`.
630
-
631
- **TR:** Express — i18next middleware'i `dtoMiddleware`'den **önce** tak.
632
-
633
- ```typescript
634
- app.use(i18nextMiddleware.handle(i18n))
635
- app.use(dtoMiddleware('express'))
636
- ```
637
-
638
- **EN:** Client sends `Accept-Language: tr` → Turkish message.
639
-
640
- **TR:** Client `Accept-Language: tr` gönderir → Türkçe mesaj döner.
641
-
642
- ---
643
-
644
- ## G store
645
-
646
- **EN:** App-wide shared state (Zustand). Bootstrapped from `tmp.yml` → `loaders.system.gStore.vars`.
647
-
648
- **TR:** Uygulama genelinde paylaşılan state (Zustand). Boot'ta `tmp.yml` → `gStore.vars`.
649
-
650
- ```yaml
651
- loaders:
652
- system:
653
- gStore:
654
- vars:
655
- maintenance: false
656
- ```
657
-
658
- ```typescript
659
- import { G } from '@xrystal/core/utils'
660
-
661
- G.get('maintenance')
662
- G.set('maintenance', true)
663
-
664
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true
665
- ```
666
-
667
- | Store | Lifetime / Ömür | EN | TR |
668
- |-------|-----------------|----|----|
669
- | **G** | App / Uygulama | Global flags, cache, maintenance | Global flag, cache, maintenance |
670
- | **Controller context** | Request / İstek | `this.req`, `builder` | `this.req`, `builder` |
671
- | **Run context** | Request or job / İstek veya job | `requestId`, log trace | `requestId`, log trace |
672
-
673
- ---
674
-
675
- ## DTO responses / DTO cevapları
676
-
677
- **EN:** Standard `{ success, message, data, … }` via `@xrystal/dto`. `dtoMiddleware()` attaches builder; `ctr()` dispatches the result.
678
-
679
- **TR:** `@xrystal/dto` ile standart `{ success, message, data, … }`. `dtoMiddleware()` builder takar; `ctr()` sonucu dispatch eder.
680
-
681
- Details / detay: [`@xrystal/dto`](https://www.npmjs.com/package/@xrystal/dto)
682
-
683
- ---
684
-
685
- ## Usage guide / Kullanım rehberi
686
-
687
- **EN:** Typical flow when building a service.
688
-
689
- **TR:** Servis yazarken tipik akış.
690
-
46
+ # or / veya
47
+ npm install @xrystal/core
691
48
  ```
692
- 1. Your repo + bun add @xrystal/core + xry tmp (or xry create for greenfield)
693
- 2. tmp.yml → framework, runtime, loaders, paths (tsconfig auto-heals)
694
- 3. coreLoader() → once at top of YOUR index.ts
695
- 4. Controller → ctr() per endpoint
696
- 5. Framework → dtoMiddleware + routes
697
- 6. xry dev → develop
698
- 7. xry build → start → production
699
- 8. xry sync → only when you need a force / dry-run / CI pin
700
- ```
701
-
702
- ### Express — end-to-end / uçtan uca
703
-
704
- ```typescript
705
- // source/index.ts
706
- import express from 'express'
707
- import coreLoader from '@xrystal/core'
708
- import { dtoMiddleware } from '@xrystal/core/utils'
709
- import { userCtrl } from './controllers/user'
710
49
 
711
- await coreLoader({})
712
-
713
- const app = express()
714
- app.use(dtoMiddleware('express'))
715
- app.get('/users', userCtrl.list)
716
- app.listen(3000)
717
- ```
50
+ **EN:** The `xry` binary is available via `node_modules/.bin` (e.g. `bun xry dev`). Pick a peer HTTP stack: `elysia`, `express`, or raw `node` / `fetch`.
718
51
 
719
- ### Elysia — end-to-end / uçtan uca
720
-
721
- ```typescript
722
- // source/index.ts
723
- import { Elysia } from 'elysia'
724
- import coreLoader from '@xrystal/core'
725
- import { dtoMiddleware } from '@xrystal/core/utils'
726
- import { userCtrl } from './controllers/user'
727
-
728
- await coreLoader({})
729
-
730
- new Elysia()
731
- .use(dtoMiddleware())
732
- .get('/users', userCtrl.list)
733
- .listen(3000)
734
- ```
735
-
736
- ### DI + locale + G store together / birlikte
737
-
738
- ```yaml
739
- # x/tmp.yml
740
- configs:
741
- service:
742
- framework: express
743
- loaders:
744
- localization: { fallbackLang: en, preloadLangs: [en, tr] }
745
- system:
746
- gStore:
747
- vars: { maintenance: false }
748
- dto: { withDefaultHeaders: true }
749
- loggers: { logLevel: info }
750
- controller: {}
751
- ```
752
-
753
- ```typescript
754
- class UserController extends Controller {
755
- list = this.ctr({
756
- checks: () => G.get('maintenance') ? { message: '@unsuccessful maintenance' } : true,
757
- logic: async ({ req }) => ({
758
- data: [],
759
- message: '@successfully user',
760
- }),
761
- })
762
- }
763
- ```
764
-
765
- ### Import summary / Import özeti
766
-
767
- | What / Ne | Import |
768
- |-----------|--------|
769
- | Boot | `import coreLoader from '@xrystal/core'` |
770
- | Controller base | `import Controller from '@xrystal/core/loader/controller'` |
771
- | Middleware, G, tmp helpers | `import { … } from '@xrystal/core/utils'` |
52
+ **TR:** `xry` binary `node_modules/.bin` üzerinden kullanılır. HTTP stack: `elysia`, `express` veya `node` / `fetch`.
772
53
 
773
54
  ---
774
55
 
775
- ## Realtime — WebSocket & Socket.IO
776
-
777
- **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).
778
-
779
- **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).
780
-
781
- ### HTTP vs realtime / HTTP vs realtime
782
-
783
- | Axis / Eksen | `tmp.yml` | Middleware | Dispatch |
784
- |--------------|-----------|------------|----------|
785
- | **HTTP** | `framework: elysia` | `dtoMiddleware()` | `res.json()` / Elysia set |
786
- | **WebSocket** | `protocols: [http, ws]` | `realtimeMiddleware()` | `socket.send(JSON)` |
787
- | **Socket.IO** | `protocols: [http, socketio]` | `realtimeMiddleware('socketio')` | `socket.emit(event, payload)` |
788
-
789
- **EN:** Same controller class can serve HTTP **and** realtime — different properties, different `protocol` on `ctr()`.
790
-
791
- **TR:** Aynı controller sınıfı HTTP **ve** realtime verebilir — farklı property, farklı `protocol`.
792
-
793
- ### 3-step pattern / 3 adım kalıbı
794
-
795
- ```
796
- 1. realtimeMiddleware() → socket'a builder tak
797
- 2. ctr({ logic }, { protocol }) → checks + logic + i18n (isteğe bağlı)
798
- 3. dispatch otomatik → ws: send · socketio: emit
799
- ```
800
-
801
- ### `tmp.yml` — `protocols`
802
-
803
- ```yaml
804
- configs:
805
- service:
806
- framework: elysia # EN: HTTP only · TR: sadece HTTP
807
- protocols: [http, ws] # EN: or [http, socketio] · TR: veya [http, socketio]
808
- ```
809
-
810
- | `protocols` in tmp.yml | `realtimeMiddleware()` |
811
- |------------------------|-------------------------|
812
- | `[http, ws]` | `realtimeMiddleware()` → auto **ws** |
813
- | `[http, socketio]` | `realtimeMiddleware()` → auto **socketio** |
814
- | `[http, ws, socketio]` | **Must specify:** `realtimeMiddleware('ws')` or `realtimeMiddleware('socketio')` |
815
-
816
- ### Native WebSocket (ws)
817
-
818
- ```typescript
819
- // source/controllers/chat.ts
820
- import Controller from '@xrystal/core/loader/controller'
821
-
822
- class ChatController extends Controller {
823
- onMessage = this.ctr({
824
- logic: async ({ req }) => ({
825
- data: { echo: req.body },
826
- message: '@successfully',
827
- }),
828
- }, { protocol: 'ws' })
829
- }
830
- export const chatCtrl = new ChatController()
831
- ```
832
-
833
- ```typescript
834
- // source/index.ts — Express + ws on same port (example)
835
- import { WebSocketServer } from 'ws'
836
- import express from 'express'
837
- import coreLoader from '@xrystal/core'
838
- import { dtoMiddleware, realtimeMiddleware } from '@xrystal/core/utils'
839
- import { chatCtrl } from './controllers/chat'
840
-
841
- await coreLoader({})
842
-
843
- const app = express()
844
- app.use(dtoMiddleware('express'))
845
-
846
- const server = app.listen(3000)
847
- const wss = new WebSocketServer({ server })
848
-
849
- wss.on('connection', (socket) => {
850
- realtimeMiddleware()(socket, () => {}) // 1) builder attach
851
- socket.on('message', chatCtrl.onMessage.with(socket)) // 2) ctr + 3) auto send
852
- })
853
- ```
854
-
855
- **EN:** `with(socket)` binds the socket for that event — core calls `socket.send(JSON)` after `ctr()` finishes.
856
-
857
- **TR:** `with(socket)` socket'ı o event'e bağlar — `ctr()` bitince core `socket.send(JSON)` çağırır.
858
-
859
- ### Socket.IO
860
-
861
- ```typescript
862
- class ChatController extends Controller {
863
- onChat = this.ctr({
864
- logic: async () => ({ data: { ok: true }, message: '@successfully' }),
865
- }, { protocol: 'socketio' })
866
- }
867
- ```
868
-
869
- ```typescript
870
- import { Server } from 'socket.io'
871
- import coreLoader from '@xrystal/core'
872
- import { realtimeMiddleware } from '@xrystal/core/utils'
873
- import { chatCtrl } from './controllers/chat'
874
-
875
- await coreLoader({})
876
-
877
- const io = new Server(3001, { cors: { origin: '*' } })
878
-
879
- io.use((socket, next) => realtimeMiddleware('socketio')(socket, next)) // 1) builder
880
- io.on('connection', (socket) => {
881
- socket.on('chat', chatCtrl.onChat.with(socket)) // 2+3) ctr → emit
882
- })
883
- ```
884
-
885
- **EN:** Default emit event comes from Dto config (`socket.event`, default `'response'`). Override in `tmp.yml` → `loaders.dto`.
886
-
887
- **TR:** Varsayılan emit event'i Dto config'den gelir (`socket.event`, default `'response'`). `tmp.yml` → `loaders.dto` ile override.
888
-
889
- ### Without controller / Controller olmadan
890
-
891
- **EN:** Plain function — use `runAction` when you don't need `checks` / i18n / `this.logger`.
892
-
893
- **TR:** Düz fonksiyon — `checks` / i18n / `this.logger` gerekmiyorsa `runAction`.
894
-
895
- ```typescript
896
- import { runAction, getDtoRuntime } from '@xrystal/core/utils'
897
-
898
- // WebSocket
899
- socket.on('message', () =>
900
- runAction({ protocol: 'ws', socket }, async () => {
901
- return socket.builder.as.ok({ ping: 1 }).build()
902
- }),
903
- )
904
-
905
- // Socket.IO
906
- socket.on('ping', () =>
907
- runAction({ protocol: 'socketio', socket }, async () => {
908
- return getDtoRuntime().forSocket(socket).builder.as.ok({ pong: true }).build()
909
- }),
910
- )
911
- ```
912
-
913
- ### ws vs Socket.IO — transport farkı
914
-
915
- | | WebSocket (ws) | Socket.IO |
916
- |---|----------------|-----------|
917
- | Wire / Kablo | `socket.send(JSON string)` | `socket.emit(event, object)` |
918
- | `ctr()` protocol | `{ protocol: 'ws' }` | `{ protocol: 'socketio' }` |
919
- | Middleware | `realtimeMiddleware()` or `realtimeMiddleware('ws')` | `realtimeMiddleware('socketio')` |
920
- | Same `FinalResult` | ✅ same builder | ✅ same builder |
921
-
922
- **EN:** Pick **ws** for native WebSocket clients. Pick **socket.io** when you need rooms, fallback transport, or existing Socket.IO clients.
923
-
924
- **TR:** Native WebSocket client → **ws**. Room, fallback transport veya mevcut Socket.IO client → **socket.io**.
925
-
926
- ### Same logic, two protocols / Aynı logic, iki protocol
927
-
928
- ```typescript
929
- class ChatController extends Controller {
930
- onWs = this.ctr({ logic: async () => ({ data: { via: 'ws' } }) }, { protocol: 'ws' })
931
- onSio = this.ctr({ logic: async () => ({ data: { via: 'socketio' } }) }, { protocol: 'socketio' })
932
- }
933
- ```
934
-
935
- ---
56
+ ## Release (npm) / Yayın (npm)
936
57
 
937
- ## Maintainer note / Geliştirici notu
58
+ **EN:** Ship with `xry tag` (SemVer `v*` git tag). GitHub Actions `publish.yml` builds and publishes to npm using [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). Housekeeping: `artifact.yml` (zip backups) and `clean.yml` (scheduled release pruning).
938
59
 
939
- **EN:** See **Release scripts (general)**. CalVer npm script örneği yalnız **`api-gpt-svc`** template’inde.
60
+ **TR:** `xry tag` ile SemVer `v*` git tag gönder. `publish.yml` npm’e [Trusted Publisher](https://docs.npmjs.com/trusted-publishers) (OIDC) ile yazar. Bakım: `artifact.yml` (zip yedek), `clean.yml` (release temizliği).
940
61
 
62
+ ## Further reading / Ek kaynak
941
63
 
942
- **npm CI (`E401` / invalid token):** GitHub → repo **Settings → Environments → NPM** → secret **`TOKEN`** = [npm Granular Access Token](https://www.npmjs.com/settings/~youruser/tokens) with **Publish** on package `@xrystal/core` (or whole `@xrystal` scope). Classic automation tokens that bypass 2FA are being restricted — prefer **Granular** + **Publish**. After rotate: re-run failed **Publish Core Library NPM** workflow or push empty commit / re-tag. Stage flow: workflow runs `npm stage publish` → approve on npmjs.com (`npm stage list` / Approve with 2FA).
64
+ **EN:** Package API and changelog on [npm](https://www.npmjs.com/package/@xrystal/core). Release notes on the GitHub **Releases** tab for this repository.
943
65
 
944
- **TR:** Yukarıdaki genel tablo. Serviste `release:minor|major` yok — yalnız CalVer patch.
66
+ **TR:** API ve changelog [npm](https://www.npmjs.com/package/@xrystal/core)'de; sürüm notları GitHub **Releases** sayfasında.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "author": "Yusuf Yasir KAYGUSUZ",
3
3
  "name": "@xrystal/core",
4
- "version": "3.55.75",
4
+ "version": "3.55.84",
5
5
  "description": "Runtime framework and CLI for API services, frontends, and multi-repo workspaces",
6
6
  "publishConfig": {
7
7
  "access": "public",
@@ -84,9 +84,9 @@
84
84
  "build:dev": "node x/bin/main-cli.js dev",
85
85
  "start": "node x/bin/main-cli.js start",
86
86
  "tag": "node x/bin/scripts/tag.mjs",
87
- "release:patch": "node x/bin/scripts/release-bump.mjs patch",
88
- "release:minor": "node x/bin/scripts/release-bump.mjs minor",
89
- "release:major": "node x/bin/scripts/release-bump.mjs major",
87
+ "version:patch": "node x/bin/scripts/release-bump.mjs patch",
88
+ "version:minor": "node x/bin/scripts/release-bump.mjs minor",
89
+ "version:major": "node x/bin/scripts/release-bump.mjs major",
90
90
  "version:check": "node x/bin/scripts/version-check.mjs",
91
91
  "hooks:install": "node x/bin/scripts/install-git-hooks.mjs"
92
92
  },
@@ -9,7 +9,13 @@ import {
9
9
  runTagRelease,
10
10
  } from '../scripts/version-check.mjs'
11
11
  import { isCorePackageProject } from '../scripts/release-prepare.mjs'
12
- import { runCalverTagPush, assertCalverFormat, detectCalverEnv, bumpCalverPatch } from '../scripts/calver.mjs'
12
+ import {
13
+ runCalverTagPush,
14
+ assertCalverFormat,
15
+ detectCalverEnv,
16
+ bumpCalverPatch,
17
+ gitTagFromCalver,
18
+ } from '../scripts/calver.mjs'
13
19
  import { bumpSemverLevel, resolveReleaseMode } from '../scripts/release-bump.mjs'
14
20
  import fs from 'node:fs'
15
21
  import path from 'node:path'
@@ -19,7 +25,7 @@ import { CLI_PRIMARY_NAME, PACKAGE_NAME } from '../helpers/cli-identity.mjs'
19
25
  export function registerTagCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
20
26
  cli
21
27
  .command('tag')
22
- .description(`Git tag + npm publish (${packageDefaults.packageName} repo only)`)
28
+ .description(`Git tag push (CalVer services) or git tag + npm publish (${packageDefaults.packageName} core only)`)
23
29
  .option('--dry-run', 'Print commands without executing')
24
30
  .option('--strict-clean', 'Require fully clean working tree (default: only package.json must be committed)')
25
31
  .option('--skip-prepare', 'Skip lint, test, and build:prod (core only)')
@@ -61,51 +67,55 @@ function writePackageVersion(root, version) {
61
67
  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
62
68
  }
63
69
 
64
- export function registerReleaseBumpCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
65
- const bump = cli.command('release').description('Bump package.json (core SemVer · service CalVer patch)')
70
+ function runVersionBump({ cliName, level, dryRun }) {
71
+ try {
72
+ const { root } = requireServiceRoot(process.cwd(), { cliName, command: `version ${level}` })
73
+ const mode = resolveReleaseMode(root)
74
+ const state = getVersionState('HEAD', root)
75
+ let next
76
+ if (mode === 'semver') {
77
+ next = bumpSemverLevel(state.disk.version, level)
78
+ } else {
79
+ if (level !== 'patch') {
80
+ throw new Error('CalVer — only patch. package.json SemVer (2.0.x) ise minor/major açılır.')
81
+ }
82
+ next = bumpCalverPatch(root).next
83
+ }
84
+ if (dryRun) {
85
+ console.log(chalk.bold(next))
86
+ return
87
+ }
88
+ writePackageVersion(root, next)
89
+ console.log(chalk.green(`package.json → ${next}`))
90
+ console.log(chalk.gray('Commit package.json, then: xry tag'))
91
+ } catch (error) {
92
+ if (error?.name === 'CliContextError') exitOnCliContextError(error)
93
+ console.error(chalk.red(`\n✗ ${error.message}\n`))
94
+ process.exit(1)
95
+ }
96
+ }
66
97
 
98
+ function registerVersionBumpSubcommands(versionCmd, { cliName = CLI_PRIMARY_NAME } = {}) {
67
99
  for (const level of ['patch', 'minor', 'major']) {
68
- bump
100
+ versionCmd
69
101
  .command(level)
70
102
  .description(
71
103
  level === 'patch'
72
- ? 'SemVer or CalVer patch (from package.json version shape)'
104
+ ? 'Bump package.json — core SemVer · service CalVer pN'
73
105
  : 'SemVer minor/major (CalVer repos: patch only)',
74
106
  )
75
107
  .option('--dry-run', 'Print next version only')
76
- .action((options) => {
77
- try {
78
- const { root } = requireServiceRoot(process.cwd(), { cliName, command: `release ${level}` })
79
- const mode = resolveReleaseMode(root)
80
- const state = getVersionState('HEAD', root)
81
- let next
82
- if (mode === 'semver') {
83
- next = bumpSemverLevel(state.disk.version, level)
84
- } else {
85
- if (level !== 'patch') {
86
- throw new Error('CalVer — only patch. package.json SemVer (2.0.x) ise minor/major açılır.')
87
- }
88
- next = bumpCalverPatch(root).next
89
- }
90
- if (options.dryRun) {
91
- console.log(chalk.bold(next))
92
- return
93
- }
94
- writePackageVersion(root, next)
95
- console.log(chalk.green(`package.json → ${next}`))
96
- console.log(chalk.gray('Commit package.json, then: xry tag'))
97
- } catch (error) {
98
- if (error?.name === 'CliContextError') exitOnCliContextError(error)
99
- console.error(chalk.red(`\n✗ ${error.message}\n`))
100
- process.exit(1)
101
- }
102
- })
108
+ .action((options) => runVersionBump({ cliName, level, dryRun: options.dryRun }))
103
109
  }
104
110
  }
105
111
 
106
112
  export function registerVersionCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
107
- cli
108
- .command('version')
113
+ const version = cli.command('version').description('Project version: show or bump package.json')
114
+
115
+ registerVersionBumpSubcommands(version, { cliName })
116
+
117
+ version
118
+ .command('show', { isDefault: true })
109
119
  .description('Show CLI and project package versions')
110
120
  .action(() => {
111
121
  try {
@@ -127,7 +137,11 @@ export function registerVersionCommand(cli, { cliName = CLI_PRIMARY_NAME } = {})
127
137
  if (isCore) {
128
138
  console.log(` git tag name: ${chalk.bold(`v${state.committed.version}`)}`)
129
139
  } else {
130
- console.log(` service image tag: ${chalk.gray('N/A — CalVer via platform CI (infra versioning.mdc)')}`)
140
+ const cv = detectCalverEnv(state.committed.version)
141
+ const tagLine = cv
142
+ ? chalk.bold(gitTagFromCalver(state.committed.version))
143
+ : chalk.gray('set CalVer in package.json, then xry tag')
144
+ console.log(` git / image tag: ${tagLine}`)
131
145
  }
132
146
  console.log(` branch: ${state.branch}`)
133
147
  console.log(` version match: ${state.versionMatch ? chalk.green('yes') : chalk.red('no')}`)
@@ -93,6 +93,42 @@ function runQuit({ cliName, commandLabel }) {
93
93
  printCommandFooter({ version })
94
94
  }
95
95
 
96
+ function resolveLeaveTarget(deploy) {
97
+ let deployName = String(deploy ?? '').trim()
98
+ let serviceRoot = process.cwd()
99
+ if (!deployName) {
100
+ const resolved = resolveTelepresenceDeployFromCwd(process.cwd())
101
+ deployName = resolved.deploy
102
+ serviceRoot = resolved.serviceRoot
103
+ } else if (TELEPRESENCE_DEPLOYMENTS.includes(deployName)) {
104
+ const workspaceRoot = findWorkspaceRoot(process.cwd())
105
+ const svcDir =
106
+ resolveTelepresenceServiceDir(workspaceRoot ?? process.cwd(), deployName) ??
107
+ (workspaceRoot
108
+ ? resolveTelepresenceServiceDir(path.dirname(workspaceRoot), deployName)
109
+ : null)
110
+ if (svcDir) serviceRoot = svcDir
111
+ } else {
112
+ console.error(chalk.red(`\n✗ Unknown deploy "${deployName}"\n`))
113
+ console.error(chalk.gray(` Use: ${TELEPRESENCE_DEPLOYMENTS.join(', ')}\n`))
114
+ process.exit(1)
115
+ }
116
+ return { deployName, serviceRoot }
117
+ }
118
+
119
+ function runLeaveIntercept(deploy, ns, { cliName, commandLabel } = {}) {
120
+ const version = readCliPackageJson().version
121
+ const { deployName, serviceRoot } = resolveLeaveTarget(deploy)
122
+ printCommandHeader({ cliName, command: commandLabel ?? `tp leave ${deployName}`, version })
123
+ try {
124
+ leaveTelepresenceIntercept({ deploy: deployName, ns, cwd: serviceRoot })
125
+ } catch (err) {
126
+ console.error(chalk.red(`\n✗ ${err.message}\n`))
127
+ process.exit(1)
128
+ }
129
+ printCommandFooter({ version })
130
+ }
131
+
96
132
  export function registerTelepresenceCommand(cli, { cliName = CLI_PRIMARY_NAME } = {}) {
97
133
  const tp = cli
98
134
  .command('telepresence')
@@ -105,7 +141,9 @@ export function registerTelepresenceCommand(cli, { cliName = CLI_PRIMARY_NAME }
105
141
  ${cliName} tp start --ns dev
106
142
  ${cliName} tp intercept
107
143
  ${cliName} tp intercept gateway 3000 --ns dev
144
+ ${cliName} tp intercept leave
108
145
  ${cliName} tp stop
146
+ ${cliName} tp leave
109
147
  ${cliName} tp leave gateway --ns dev
110
148
  ${cliName} tp install
111
149
 
@@ -134,20 +172,8 @@ export function registerTelepresenceCommand(cli, { cliName = CLI_PRIMARY_NAME }
134
172
  .argument('[deploy]', `Deployment (default: configs.service.name in x/tmp.yml)`)
135
173
  .option('--ns <namespace>', 'Kubernetes namespace', 'dev')
136
174
  .action((deploy, options) => {
137
- const version = readCliPackageJson().version
138
175
  const ns = String(options.ns ?? 'dev').trim() || 'dev'
139
- let deployName = String(deploy ?? '').trim()
140
- if (!deployName) {
141
- deployName = resolveTelepresenceDeployFromCwd(process.cwd()).deploy
142
- }
143
- printCommandHeader({ cliName, command: `tp leave ${deployName}`, version })
144
- try {
145
- leaveTelepresenceIntercept({ deploy: deployName, ns, cwd: process.cwd() })
146
- } catch (err) {
147
- console.error(chalk.red(`\n✗ ${err.message}\n`))
148
- process.exit(1)
149
- }
150
- printCommandFooter({ version })
176
+ runLeaveIntercept(deploy, ns, { cliName })
151
177
  })
152
178
 
153
179
  tp.command('rewrite-env')
@@ -182,9 +208,22 @@ export function registerTelepresenceCommand(cli, { cliName = CLI_PRIMARY_NAME }
182
208
  printCommandFooter({ version })
183
209
  })
184
210
 
185
- tp.command('intercept')
211
+ const interceptCmd = tp
212
+ .command('intercept')
186
213
  .alias('dev')
187
214
  .description('Intercept deployment → local process (deploy optional in service repo)')
215
+
216
+ interceptCmd
217
+ .command('leave')
218
+ .description('End intercept for this service (default deploy from x/tmp.yml when omitted)')
219
+ .argument('[deploy]', `Deployment (default: configs.service.name in x/tmp.yml)`)
220
+ .option('--ns <namespace>', 'Kubernetes namespace', 'dev')
221
+ .action((deploy, options) => {
222
+ const ns = String(options.ns ?? 'dev').trim() || 'dev'
223
+ runLeaveIntercept(deploy, ns, { cliName, commandLabel: 'tp intercept leave' })
224
+ })
225
+
226
+ interceptCmd
188
227
  .argument('[deploy]', `Deployment name (default: configs.service.name in x/tmp.yml) — ${TELEPRESENCE_DEPLOYMENTS.join(', ')}`)
189
228
  .argument('[port]', 'Local listen port', '3000')
190
229
  .option('--ns <namespace>', 'Kubernetes namespace', 'dev')
@@ -193,6 +232,18 @@ export function registerTelepresenceCommand(cli, { cliName = CLI_PRIMARY_NAME }
193
232
  .action((deploy, port, options, command) => {
194
233
  const version = readCliPackageJson().version
195
234
  const ns = String(options.ns ?? 'dev').trim() || 'dev'
235
+
236
+ const deployToken = String(deploy ?? '').trim().toLowerCase()
237
+ if (deployToken === 'leave') {
238
+ runLeaveIntercept('', ns, { cliName, commandLabel: 'tp intercept leave' })
239
+ return
240
+ }
241
+ const portToken = String(port ?? '').trim().toLowerCase()
242
+ if (portToken === 'leave' && deployToken && TELEPRESENCE_DEPLOYMENTS.includes(deployToken)) {
243
+ runLeaveIntercept(deployToken, ns, { cliName, commandLabel: `tp intercept ${deployToken} leave` })
244
+ return
245
+ }
246
+
196
247
  const { deployName, portArg, serviceRootHint } = resolveInterceptTarget(deploy, port, command)
197
248
  const localCmd = resolveLocalCmd(command)
198
249
 
@@ -82,8 +82,8 @@ function commandGroups() {
82
82
  {
83
83
  title: t('sections.release'),
84
84
  items: [
85
- { cmd: 'release patch', desc: 'Bump package.json — core SemVer · service CalVer pN' },
86
- { cmd: 'release minor|major', desc: '@xrystal/core SemVer only' },
85
+ { cmd: 'version patch', desc: 'Bump package.json — core SemVer · service CalVer pN' },
86
+ { cmd: 'version minor|major', desc: '@xrystal/core SemVer only' },
87
87
  { cmd: 'tag', desc: 'Core npm publish · service v<CalVer> git tag' },
88
88
  ],
89
89
  },
package/x/bin/main-cli.js CHANGED
@@ -10,7 +10,7 @@ import { registerProjectCommands } from './commands/project.mjs'
10
10
  import { registerTmpCommand } from './commands/tmp.mjs'
11
11
  import { registerSyncCommand } from './commands/sync.mjs'
12
12
  import { registerProjectsCommand, registerWorkspacesCommand } from './commands/projects.mjs'
13
- import { registerTagCommand, registerVersionCommand, registerReleaseBumpCommand } from './commands/release.mjs'
13
+ import { registerTagCommand, registerVersionCommand } from './commands/release.mjs'
14
14
  import { registerTelepresenceCommand } from './commands/telepresence.mjs'
15
15
  import { registerHooksCommand } from './commands/hooks.mjs'
16
16
  import { registerWatchCommand } from './commands/watch.mjs'
@@ -83,7 +83,6 @@ cli
83
83
 
84
84
  registerCreateCommand(cli, cliContext)
85
85
  registerVersionCommand(cli, cliContext)
86
- registerReleaseBumpCommand(cli, cliContext)
87
86
  registerTagCommand(cli, cliContext)
88
87
  registerDoctorCommand(cli, cliContext)
89
88
  registerTmpCommand(cli, cliContext)
@@ -4,6 +4,7 @@ import { getVersionState, readDiskPackageJson, run } from './version-check.mjs'
4
4
  const CALVER_RELEASE = /^(\d{2})\.(\d{2})\.(\d{2})$/
5
5
  const CALVER_DEV = /^(\d{2})\.(\d{2})\.(\d{2})-dev-p(\d+)$/
6
6
  const CALVER_STAG = /^(\d{2})\.(\d{2})\.(\d{2})-stag-p(\d+)$/
7
+ const CALVER_PROD_PATCH = /^(\d{2})\.(\d{2})\.(\d{2})-p(\d+)$/
7
8
 
8
9
  export function utcCalverDate() {
9
10
  const d = new Date()
@@ -34,14 +35,15 @@ export function detectCalverEnv(version) {
34
35
  const v = String(version).trim()
35
36
  if (CALVER_DEV.test(v)) return 'dev'
36
37
  if (CALVER_STAG.test(v)) return 'stag'
38
+ if (CALVER_PROD_PATCH.test(v)) return 'prod'
37
39
  if (CALVER_RELEASE.test(v)) return 'prod'
38
40
  return null
39
41
  }
40
42
 
41
43
  export function assertCalverFormat(version, env) {
42
44
  const v = String(version).trim()
43
- if (env === 'prod' && !CALVER_RELEASE.test(v)) {
44
- throw new Error(`Invalid prod CalVer "${v}" — expected YY.MM.DD`)
45
+ if (env === 'prod' && !CALVER_RELEASE.test(v) && !CALVER_PROD_PATCH.test(v)) {
46
+ throw new Error(`Invalid prod CalVer "${v}" — expected YY.MM.DD or YY.MM.DD-pN (same-day patch, N ≥ 2)`)
45
47
  }
46
48
  if (env === 'dev' && !CALVER_DEV.test(v)) {
47
49
  throw new Error(`Invalid dev CalVer "${v}" — expected YY.MM.DD-dev-pN`)
@@ -65,7 +67,7 @@ export function resolveCalverEnv(root = process.cwd()) {
65
67
  if (fromPkg) return fromPkg
66
68
 
67
69
  throw new Error(
68
- `Cannot infer CalVer env — checkout dev | staging | prod, or set package.json to YY.MM.DD-dev-pN / -stag-pN / YY.MM.DD.`,
70
+ `Cannot infer CalVer env — checkout dev | staging | prod, or set package.json to YY.MM.DD-dev-pN / -stag-pN / YY.MM.DD / YY.MM.DD-pN.`,
69
71
  )
70
72
  }
71
73
 
@@ -80,12 +82,14 @@ export function bumpCalverPatch(root = process.cwd()) {
80
82
  export function nextCalverVersion(env, root = process.cwd()) {
81
83
  const date = utcCalverDate()
82
84
  if (env === 'prod') {
83
- const version = date
84
- const tagName = `v${version}`
85
- if (gitTagExists(tagName, root)) {
86
- throw new Error(`Git tag ${tagName} already exists — prod release is one tag per UTC day`)
85
+ if (!gitTagExists(`v${date}`, root)) {
86
+ return date
87
87
  }
88
- return version
88
+ let n = 2
89
+ while (gitTagExists(`v${date}-p${n}`, root)) {
90
+ n += 1
91
+ }
92
+ return `${date}-p${n}`
89
93
  }
90
94
  const mid = env === 'dev' ? '-dev-p' : '-stag-p'
91
95
  let n = 1