@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 +33 -911
- package/package.json +4 -4
- package/x/bin/commands/release.mjs +50 -36
- package/x/bin/commands/telepresence.mjs +65 -14
- package/x/bin/helpers/cli-help.mjs +2 -2
- package/x/bin/main-cli.js +1 -2
- package/x/bin/scripts/calver.mjs +12 -8
package/README.md
CHANGED
|
@@ -1,944 +1,66 @@
|
|
|
1
1
|
# @xrystal/core
|
|
2
2
|
|
|
3
|
-
> **EN** — Runtime
|
|
4
|
-
> **TR** —
|
|
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` ·
|
|
6
|
+
**CLI:** `xry` · [npm](https://www.npmjs.com/package/@xrystal/core)
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Overview / Genel bakış
|
|
11
11
|
|
|
12
|
-
**EN:**
|
|
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:**
|
|
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
|
-
##
|
|
18
|
+
## Features / Özellikler
|
|
39
19
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
**
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
|
|
46
|
-
| **
|
|
47
|
-
| **
|
|
48
|
-
| **
|
|
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
|
-
##
|
|
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
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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:**
|
|
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.
|
|
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
|
-
"
|
|
88
|
-
"
|
|
89
|
-
"
|
|
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 {
|
|
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}
|
|
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
|
-
|
|
65
|
-
|
|
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
|
-
|
|
100
|
+
versionCmd
|
|
69
101
|
.command(level)
|
|
70
102
|
.description(
|
|
71
103
|
level === 'patch'
|
|
72
|
-
? '
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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: '
|
|
86
|
-
{ cmd: '
|
|
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
|
|
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)
|
package/x/bin/scripts/calver.mjs
CHANGED
|
@@ -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
|
-
|
|
84
|
-
|
|
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
|
-
|
|
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
|