@xrystal/core 3.32.1 → 3.37.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/README.md +651 -136
  2. package/package.json +27 -24
  3. package/tsconfig.base.json +15 -0
  4. package/x/bin/commands/create.mjs +34 -5
  5. package/x/bin/commands/doctor.mjs +115 -25
  6. package/x/bin/commands/hooks.mjs +55 -0
  7. package/x/bin/commands/project.mjs +75 -42
  8. package/x/bin/commands/release.mjs +8 -3
  9. package/x/bin/commands/sync-toolchain.mjs +43 -0
  10. package/x/bin/commands/tmp.mjs +13 -4
  11. package/x/bin/helpers/.generated/.generated-from +1 -0
  12. package/x/bin/helpers/.generated/tmp-schema.mjs +192 -0
  13. package/x/bin/helpers/banner.mjs +66 -12
  14. package/x/bin/helpers/build-config.mjs +342 -0
  15. package/x/bin/helpers/cli-help.mjs +164 -0
  16. package/x/bin/helpers/create-target.mjs +18 -2
  17. package/x/bin/helpers/project-artifacts.mjs +140 -0
  18. package/x/bin/helpers/runtime-info.mjs +172 -0
  19. package/x/bin/helpers/tmp-config.mjs +11 -10
  20. package/x/bin/helpers/tmp-layout.mjs +10 -16
  21. package/x/bin/helpers/tmp-schema.mjs +9 -0
  22. package/x/bin/helpers/toolchain-config.mjs +233 -0
  23. package/x/bin/main-cli.js +31 -3
  24. package/x/bin/scripts/clean-source-types.mjs +19 -0
  25. package/x/bin/scripts/fix-dist-imports.mjs +80 -0
  26. package/x/bin/scripts/install-git-hooks.mjs +86 -0
  27. package/x/bin/scripts/minify-dist.mjs +50 -0
  28. package/x/bin/scripts/prepare-npm-publish.mjs +49 -0
  29. package/x/bin/scripts/unpublish-leaked-versions.mjs +62 -0
  30. package/x/bin/scripts/verify-npm-pack.mjs +45 -0
  31. package/x/bin/scripts/verify-version-bump.mjs +27 -0
  32. package/x/bin/scripts/version-check.mjs +173 -0
  33. package/x/dist/index.d.ts +3 -0
  34. package/x/dist/index.js +1 -0
  35. package/x/dist/loader/clients/index.js +1 -0
  36. package/x/dist/loader/configs/index.js +1 -0
  37. package/{source → x/dist}/loader/controller/index.d.ts +20 -17
  38. package/x/dist/loader/controller/index.js +1 -0
  39. package/x/dist/loader/dto/index.js +1 -0
  40. package/x/dist/loader/events/index.js +1 -0
  41. package/x/dist/loader/index.d.ts +11 -0
  42. package/x/dist/loader/index.js +1 -0
  43. package/{source → x/dist}/loader/kafka/index.d.ts +1 -0
  44. package/x/dist/loader/kafka/index.js +1 -0
  45. package/x/dist/loader/localizations/index.js +1 -0
  46. package/{source → x/dist}/loader/logger/index.d.ts +1 -0
  47. package/x/dist/loader/logger/index.js +2 -0
  48. package/x/dist/loader/service/index.js +1 -0
  49. package/x/dist/loader/system/index.js +1 -0
  50. package/x/dist/project/index.js +1 -0
  51. package/x/dist/utils/constants/defaults.json +44 -0
  52. package/x/dist/utils/constants/index.js +1 -0
  53. package/x/dist/utils/helpers/configs/index.js +1 -0
  54. package/x/dist/utils/helpers/context/controller-store.js +1 -0
  55. package/x/dist/utils/helpers/context/index.js +1 -0
  56. package/{source → x/dist}/utils/helpers/core/index.d.ts +1 -1
  57. package/x/dist/utils/helpers/core/index.js +1 -0
  58. package/x/dist/utils/helpers/core/paths.js +1 -0
  59. package/x/dist/utils/helpers/core/tmp-layout.js +1 -0
  60. package/x/dist/utils/helpers/date/index.js +1 -0
  61. package/x/dist/utils/helpers/dispatch/index.js +1 -0
  62. package/x/dist/utils/helpers/dto/index.js +1 -0
  63. package/x/dist/utils/helpers/filters/index.js +1 -0
  64. package/x/dist/utils/helpers/framework/index.js +1 -0
  65. package/x/dist/utils/helpers/handlers/adapters.js +1 -0
  66. package/x/dist/utils/helpers/handlers/execute.js +1 -0
  67. package/x/dist/utils/helpers/handlers/index.js +1 -0
  68. package/x/dist/utils/helpers/hash/crypto.js +1 -0
  69. package/x/dist/utils/helpers/id/index.js +1 -0
  70. package/x/dist/utils/helpers/index.js +1 -0
  71. package/x/dist/utils/helpers/ip/index.js +1 -0
  72. package/x/dist/utils/helpers/is/index.js +1 -0
  73. package/x/dist/utils/helpers/locales/index.js +1 -0
  74. package/x/dist/utils/helpers/math/index.js +1 -0
  75. package/{source → x/dist}/utils/helpers/middleware/index.d.ts +2 -2
  76. package/x/dist/utils/helpers/middleware/index.js +1 -0
  77. package/x/dist/utils/helpers/objects/index.js +1 -0
  78. package/x/dist/utils/helpers/path/index.js +1 -0
  79. package/{source → x/dist}/utils/helpers/protocol/index.d.ts +2 -10
  80. package/x/dist/utils/helpers/protocol/index.js +1 -0
  81. package/x/dist/utils/helpers/protocol/options.js +1 -0
  82. package/x/dist/utils/helpers/regex/checkSpecialRegexControl.js +1 -0
  83. package/x/dist/utils/helpers/runtime/dto-access.js +1 -0
  84. package/x/dist/utils/helpers/runtime/dto-types.js +1 -0
  85. package/{source → x/dist}/utils/helpers/runtime/index.d.ts +1 -0
  86. package/x/dist/utils/helpers/runtime/index.js +1 -0
  87. package/x/dist/utils/helpers/runtime/shutdown.d.ts +3 -0
  88. package/x/dist/utils/helpers/runtime/shutdown.js +1 -0
  89. package/x/dist/utils/helpers/state/index.js +1 -0
  90. package/x/dist/utils/helpers/state/props-from-tmp.js +1 -0
  91. package/x/dist/utils/helpers/state/request-key-guard.js +1 -0
  92. package/x/dist/utils/helpers/state/scopes.js +1 -0
  93. package/x/dist/utils/helpers/string/index.js +1 -0
  94. package/x/dist/utils/helpers/tests/tmp-schema.test.js +1 -0
  95. package/x/dist/utils/helpers/tests/tmp-watch.test.js +1 -0
  96. package/x/dist/utils/helpers/timer/index.js +1 -0
  97. package/x/dist/utils/helpers/tmp/index.d.ts +5 -0
  98. package/x/dist/utils/helpers/tmp/index.js +1 -0
  99. package/x/dist/utils/helpers/tmp/loader-tmp-sync.js +1 -0
  100. package/{source → x/dist}/utils/helpers/tmp/runtime-tmp.d.ts +2 -6
  101. package/x/dist/utils/helpers/tmp/runtime-tmp.js +1 -0
  102. package/{source → x/dist}/utils/helpers/tmp/tmp-loader.d.ts +1 -0
  103. package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -0
  104. package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +47 -0
  105. package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -0
  106. package/x/dist/utils/helpers/tmp/tmp-watch.d.ts +1 -0
  107. package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -0
  108. package/x/dist/utils/helpers/validates/index.js +1 -0
  109. package/x/dist/utils/index.js +1 -0
  110. package/x/dist/utils/models/classes/class.clients.js +1 -0
  111. package/x/dist/utils/models/classes/class.interfaces.js +1 -0
  112. package/x/dist/utils/models/classes/class.service-locator.js +1 -0
  113. package/{source → x/dist}/utils/models/classes/class.tmp-file-loader.d.ts +3 -2
  114. package/x/dist/utils/models/classes/class.tmp-file-loader.js +1 -0
  115. package/x/dist/utils/models/classes/class.x.js +1 -0
  116. package/x/dist/utils/models/enums/index.js +1 -0
  117. package/x/dist/utils/models/index.js +1 -0
  118. package/x/dist/utils/models/types/index.js +1 -0
  119. package/x/dist/utils/package-root.js +1 -0
  120. package/x/tmp.yml +51 -42
  121. package/source/index.js +0 -11
  122. package/source/loader/clients/index.js +0 -22
  123. package/source/loader/configs/index.js +0 -88
  124. package/source/loader/controller/index.js +0 -236
  125. package/source/loader/dto/index.js +0 -92
  126. package/source/loader/events/index.js +0 -44
  127. package/source/loader/index.d.ts +0 -11
  128. package/source/loader/index.js +0 -11
  129. package/source/loader/kafka/index.js +0 -137
  130. package/source/loader/localizations/index.js +0 -46
  131. package/source/loader/logger/index.js +0 -217
  132. package/source/loader/service/index.js +0 -7
  133. package/source/loader/system/index.js +0 -25
  134. package/source/project/index.js +0 -70
  135. package/source/utils/constants/defaults.json +0 -15
  136. package/source/utils/constants/defaults.mjs +0 -10
  137. package/source/utils/constants/index.js +0 -22
  138. package/source/utils/helpers/configs/index.js +0 -1
  139. package/source/utils/helpers/context/controller-store.js +0 -12
  140. package/source/utils/helpers/context/index.js +0 -24
  141. package/source/utils/helpers/core/index.js +0 -58
  142. package/source/utils/helpers/core/paths.js +0 -78
  143. package/source/utils/helpers/core/tmp-layout.js +0 -241
  144. package/source/utils/helpers/date/index.js +0 -48
  145. package/source/utils/helpers/dispatch/index.js +0 -53
  146. package/source/utils/helpers/dto/index.js +0 -10
  147. package/source/utils/helpers/filters/index.js +0 -44
  148. package/source/utils/helpers/framework/index.js +0 -17
  149. package/source/utils/helpers/handlers/adapters.js +0 -40
  150. package/source/utils/helpers/handlers/execute.js +0 -82
  151. package/source/utils/helpers/handlers/index.js +0 -31
  152. package/source/utils/helpers/hash/crypto.js +0 -22
  153. package/source/utils/helpers/id/index.js +0 -24
  154. package/source/utils/helpers/index.js +0 -26
  155. package/source/utils/helpers/ip/index.js +0 -21
  156. package/source/utils/helpers/is/index.js +0 -35
  157. package/source/utils/helpers/locales/index.js +0 -82
  158. package/source/utils/helpers/math/index.js +0 -14
  159. package/source/utils/helpers/middleware/index.js +0 -36
  160. package/source/utils/helpers/objects/index.js +0 -55
  161. package/source/utils/helpers/path/index.js +0 -4
  162. package/source/utils/helpers/protocol/index.js +0 -99
  163. package/source/utils/helpers/protocol/options.js +0 -13
  164. package/source/utils/helpers/regex/checkSpecialRegexControl.js +0 -3
  165. package/source/utils/helpers/runtime/dto-access.js +0 -5
  166. package/source/utils/helpers/runtime/index.js +0 -1
  167. package/source/utils/helpers/state/index.js +0 -185
  168. package/source/utils/helpers/state/props-from-tmp.js +0 -44
  169. package/source/utils/helpers/state/request-key-guard.js +0 -42
  170. package/source/utils/helpers/state/scopes.js +0 -69
  171. package/source/utils/helpers/string/index.js +0 -9
  172. package/source/utils/helpers/timer/index.js +0 -5
  173. package/source/utils/helpers/tmp/index.d.ts +0 -3
  174. package/source/utils/helpers/tmp/index.js +0 -3
  175. package/source/utils/helpers/tmp/loader-tmp-sync.js +0 -13
  176. package/source/utils/helpers/tmp/runtime-tmp.js +0 -30
  177. package/source/utils/helpers/tmp/tmp-loader.js +0 -48
  178. package/source/utils/helpers/validates/index.js +0 -20
  179. package/source/utils/index.js +0 -3
  180. package/source/utils/models/classes/class.clients.js +0 -142
  181. package/source/utils/models/classes/class.interfaces.js +0 -10
  182. package/source/utils/models/classes/class.service-locator.js +0 -16
  183. package/source/utils/models/classes/class.tmp-file-loader.js +0 -38
  184. package/source/utils/models/classes/class.x.js +0 -180
  185. package/source/utils/models/enums/index.js +0 -148
  186. package/source/utils/models/index.js +0 -9
  187. package/source/utils/models/types/index.js +0 -2
  188. package/source/utils/models/types/shims.d.ts +0 -123
  189. package/source/utils/package-root.js +0 -5
  190. package/x/tests/cli.test.ts +0 -85
  191. package/x/tests/context.test.ts +0 -25
  192. package/x/tests/dispatch.test.ts +0 -84
  193. package/x/tests/fixtures/locales/en/translation.json +0 -8
  194. package/x/tests/fixtures/locales/tr/translation.json +0 -8
  195. package/x/tests/frameworks.integration.test.ts +0 -185
  196. package/x/tests/helpers/i18n-setup.ts +0 -52
  197. package/x/tests/helpers/middleware.ts +0 -23
  198. package/x/tests/helpers/register-test-dto.ts +0 -52
  199. package/x/tests/i18n.integration.test.ts +0 -77
  200. package/x/tests/i18n.test.ts +0 -96
  201. package/x/tests/middleware.test.ts +0 -83
  202. package/x/tests/project-layout.test.ts +0 -65
  203. package/x/tests/protocol.test.ts +0 -75
  204. package/x/tests/realtime.examples.test.ts +0 -198
  205. package/x/tests/runtime-tmp.test.ts +0 -49
  206. package/x/tests/socket.integration.test.ts +0 -174
  207. package/x/tests/state.test.ts +0 -183
  208. package/x/tests/tmp-layout-guard.test.ts +0 -40
  209. /package/{source → x/dist}/loader/clients/index.d.ts +0 -0
  210. /package/{source → x/dist}/loader/configs/index.d.ts +0 -0
  211. /package/{source → x/dist}/loader/dto/index.d.ts +0 -0
  212. /package/{source → x/dist}/loader/events/index.d.ts +0 -0
  213. /package/{source → x/dist}/loader/localizations/index.d.ts +0 -0
  214. /package/{source → x/dist}/loader/service/index.d.ts +0 -0
  215. /package/{source → x/dist}/loader/system/index.d.ts +0 -0
  216. /package/{source → x/dist}/project/index.d.ts +0 -0
  217. /package/{source → x/dist}/utils/constants/index.d.ts +0 -0
  218. /package/{source → x/dist}/utils/helpers/configs/index.d.ts +0 -0
  219. /package/{source → x/dist}/utils/helpers/context/controller-store.d.ts +0 -0
  220. /package/{source → x/dist}/utils/helpers/context/index.d.ts +0 -0
  221. /package/{source → x/dist}/utils/helpers/core/paths.d.ts +0 -0
  222. /package/{source → x/dist}/utils/helpers/core/tmp-layout.d.ts +0 -0
  223. /package/{source → x/dist}/utils/helpers/date/index.d.ts +0 -0
  224. /package/{source → x/dist}/utils/helpers/dispatch/index.d.ts +0 -0
  225. /package/{source → x/dist}/utils/helpers/dto/index.d.ts +0 -0
  226. /package/{source → x/dist}/utils/helpers/filters/index.d.ts +0 -0
  227. /package/{source → x/dist}/utils/helpers/framework/index.d.ts +0 -0
  228. /package/{source → x/dist}/utils/helpers/handlers/adapters.d.ts +0 -0
  229. /package/{source → x/dist}/utils/helpers/handlers/execute.d.ts +0 -0
  230. /package/{source → x/dist}/utils/helpers/handlers/index.d.ts +0 -0
  231. /package/{source → x/dist}/utils/helpers/hash/crypto.d.ts +0 -0
  232. /package/{source → x/dist}/utils/helpers/id/index.d.ts +0 -0
  233. /package/{source → x/dist}/utils/helpers/index.d.ts +0 -0
  234. /package/{source → x/dist}/utils/helpers/ip/index.d.ts +0 -0
  235. /package/{source → x/dist}/utils/helpers/is/index.d.ts +0 -0
  236. /package/{source → x/dist}/utils/helpers/locales/index.d.ts +0 -0
  237. /package/{source → x/dist}/utils/helpers/math/index.d.ts +0 -0
  238. /package/{source → x/dist}/utils/helpers/objects/index.d.ts +0 -0
  239. /package/{source → x/dist}/utils/helpers/path/index.d.ts +0 -0
  240. /package/{source → x/dist}/utils/helpers/protocol/options.d.ts +0 -0
  241. /package/{source → x/dist}/utils/helpers/regex/checkSpecialRegexControl.d.ts +0 -0
  242. /package/{source → x/dist}/utils/helpers/runtime/dto-access.d.ts +0 -0
  243. /package/{source → x/dist}/utils/helpers/runtime/dto-types.d.ts +0 -0
  244. /package/{source → x/dist}/utils/helpers/state/index.d.ts +0 -0
  245. /package/{source → x/dist}/utils/helpers/state/props-from-tmp.d.ts +0 -0
  246. /package/{source → x/dist}/utils/helpers/state/request-key-guard.d.ts +0 -0
  247. /package/{source → x/dist}/utils/helpers/state/scopes.d.ts +0 -0
  248. /package/{source → x/dist}/utils/helpers/string/index.d.ts +0 -0
  249. /package/{source/index.d.ts → x/dist/utils/helpers/tests/tmp-schema.test.d.ts} +0 -0
  250. /package/{source/utils/helpers/runtime/dto-types.js → x/dist/utils/helpers/tests/tmp-watch.test.d.ts} +0 -0
  251. /package/{source → x/dist}/utils/helpers/timer/index.d.ts +0 -0
  252. /package/{source → x/dist}/utils/helpers/tmp/loader-tmp-sync.d.ts +0 -0
  253. /package/{source → x/dist}/utils/helpers/validates/index.d.ts +0 -0
  254. /package/{source → x/dist}/utils/index.d.ts +0 -0
  255. /package/{source → x/dist}/utils/models/classes/class.clients.d.ts +0 -0
  256. /package/{source → x/dist}/utils/models/classes/class.interfaces.d.ts +0 -0
  257. /package/{source → x/dist}/utils/models/classes/class.service-locator.d.ts +0 -0
  258. /package/{source → x/dist}/utils/models/classes/class.x.d.ts +0 -0
  259. /package/{source → x/dist}/utils/models/enums/index.d.ts +0 -0
  260. /package/{source → x/dist}/utils/models/index.d.ts +0 -0
  261. /package/{source → x/dist}/utils/models/types/index.d.ts +0 -0
  262. /package/{source → x/dist}/utils/package-root.d.ts +0 -0
package/README.md CHANGED
@@ -1,16 +1,113 @@
1
1
  # xrystal-core
2
2
 
3
- > Multi-framework microservice runtime — HTTP + realtime, DI loaders, live `tmp.yml`, `@xrystal/dto` responses.
3
+ > **EN** — Multi-framework microservice runtime: HTTP + realtime, DI loaders, live `tmp.yml`, `@xrystal/dto` responses.
4
+ > **TR** — Çok framework’lü microservice runtime: HTTP + realtime, DI loader’lar, canlı `tmp.yml`, `@xrystal/dto` cevapları.
4
5
 
5
- **Tests:** `xcore test` · **CLI:** `xcore` · `xrystal` · `tmp` (aynı binary) · Serviste: `package.json` scripts
6
+ **Tests / Test:** `xcore test` · **CLI:** `xcore` · `xrystal` · `tmp` (same binary / aynı binary) · **Service / Servis:** `package.json` scripts
6
7
 
7
8
  ---
8
9
 
9
- ## Sistem nasıl çalışır
10
+ ## `tmp.yml` layout / tmp.yml düzeni
10
11
 
11
- Tek cümle: **`tmp.yml` projenin anahtarı**, `@xrystal/core` onu okuyup loader’ları ayağa kaldırır; HTTP/realtime cevapları `@xrystal/dto` ile gider.
12
+ **EN — structure:** `service` (app identity, paths, runtime, build) + `core` (library mechanisms like tmp watch).
12
13
 
13
- ### Katmanlar
14
+ **TR — yapı:** `service` (uygulama kimliği, yollar, runtime, build) + `core` (tmp izleme gibi kütüphane mekanizmaları).
15
+
16
+ ```yaml
17
+ project:
18
+ name: x
19
+
20
+ configs:
21
+ service:
22
+ name: my-api
23
+ framework: elysia
24
+ protocols: [http, ws]
25
+
26
+ paths:
27
+ root: x # EN: CLI root (test/dev/build) · TR: test/dev/build kökü
28
+ source: ./source # EN: source tree + dev entry · TR: kaynak + dev girişi
29
+ special:
30
+ tests: tests
31
+ environments: environments
32
+ dist: dist
33
+
34
+ loaders:
35
+ dto: { withDefaultHeaders: true }
36
+ loggers: { logLevel: info }
37
+ controller: {}
38
+
39
+ build:
40
+ typecheck: true # EN: build override · TR: build override
41
+ minify: true # EN: @xrystal/core — minify x/dist JS · TR: x/dist JS küçültme
42
+
43
+ core:
44
+ tmp:
45
+ fileWatchIntervalMs: 500
46
+
47
+ end:
48
+ version: 1
49
+ ```
50
+
51
+ | Block / Blok | Keys / Alanlar | Role / Rol |
52
+ |--------------|----------------|------------|
53
+ | `configs.service` | `name`, `framework`, `paths`, `protocols`, `loaders`, `build` | bu uygulama / servis |
54
+ | `configs.service.paths` | `root`, `source`, `special.*` | **EN:** layout + CLI (`dev`/`build`/`test`) · **TR:** layout + CLI (`dev`/`build`/`test`) |
55
+ | `configs.core.tmp` | `fileWatchIntervalMs` | tmp.yml dosya izleme (ms) |
56
+
57
+ **EN:** Save `tmp.yml` → no restart; loaders reload automatically.
58
+ **TR:** Kaydet → restart gerekmez; loader’lar otomatik yenilenir.
59
+
60
+ ---
61
+
62
+ ## How it works / Sistem nasıl çalışır
63
+
64
+ ### EN — overview
65
+
66
+ In one sentence: **`tmp.yml` is the project key** — `@xrystal/core` reads it, boots loaders, and sends responses via `@xrystal/dto`.
67
+
68
+ | Layer | Module | Role |
69
+ |--------|--------|------|
70
+ | Defaults | `defaults.json` | `x`, `./source`, `tests`, template URI |
71
+ | Constants | `Constants` | Shared TS + CLI values |
72
+ | Layout | `tmp-layout.ts` | tmp path resolution — **CLI only** |
73
+ | Live config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
74
+ | Runtime | `getTmpSnapshot()` | Parse + watch + live reload |
75
+
76
+ **Core repo:** `tmp.yml` must live at `x/tmp.yml` only (`ensureCoreTmpEntry`).
77
+ **Service:** tmp under `configs.service.paths.root`; runtime uses `getTmpSnapshot()` — no layout module needed.
78
+
79
+ **Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loaders `syncFromTmp()`.
80
+
81
+ **Published npm artifact:** npm tarball ships **only** `x/dist` (minified `.js` + `.d.ts`), `x/bin`, `x/tmp.yml`, `x/assets` — **no `source/` `.ts` files**. `main` / `types` / `exports` → **`x/dist/`**. Local dev uses `source/**/*.ts`; npm consumers run **`x/dist/index.js`** (Node ESM).
82
+
83
+ ---
84
+
85
+ ### TR — genel bakış
86
+
87
+ Tek cümle: **`tmp.yml` projenin anahtarı** — `@xrystal/core` onu okuyup loader’ları ayağa kaldırır; cevaplar `@xrystal/dto` ile gider.
88
+
89
+ | Katman | Modül | Rol |
90
+ |--------|--------|-----|
91
+ | Varsayılanlar | `defaults.json` | `x`, `./source`, `tests`, template URI |
92
+ | Sabitler | `Constants` | TS + CLI ortak değerler |
93
+ | Layout | `tmp-layout.ts` | tmp yolu — **sadece CLI** |
94
+ | Canlı config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
95
+ | Runtime | `getTmpSnapshot()` | Parse + watch + canlı güncelleme |
96
+
97
+ **Core repo:** `tmp.yml` yalnızca `x/tmp.yml` (`ensureCoreTmpEntry`).
98
+ **Servis:** tmp `configs.service.paths.root` altında; runtime’da `getTmpSnapshot()` yeterli — layout modülü gerekmez.
99
+
100
+ **Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loader’lar `syncFromTmp()`.
101
+
102
+ **npm paketi:** tarball’da **yalnızca** `x/dist` (minify `.js` + `.d.ts`), `x/bin`, `x/tmp.yml`, `x/assets` — **`source/` `.ts` yok`**. `main` / `types` / `exports` → **`x/dist/`**. Geliştirmede `source/**/*.ts`; npm tüketicisi **`x/dist/index.js`** (Node ESM).
103
+
104
+ ---
105
+
106
+ ## How it works — detail / Sistem nasıl çalışır — detay
107
+
108
+ **EN:** Deep-dive below (mermaid + tables). Turkish prose in this section; key labels are bilingual where it matters.
109
+
110
+ **TR:** Aşağıda detay (mermaid + tablolar). Türkçe anlatım; kritik etiketler iki dilli.
14
111
 
15
112
  ```mermaid
16
113
  flowchart TB
@@ -23,7 +120,7 @@ flowchart TB
23
120
  end
24
121
 
25
122
  subgraph boot["Boot"]
26
- ENTRY["source/index.ts veya servis boot.ts"]
123
+ ENTRY["dev: source/index.ts · prod: x/dist/index.js"]
27
124
  GUARD["ensureCoreTmpEntry\n(sadece @xrystal/core)"]
28
125
  SNAP["getTmpSnapshot()"]
29
126
  LOADER["coreLoader() → Awilix DI"]
@@ -56,38 +153,87 @@ flowchart TB
56
153
 
57
154
  | | **@xrystal/core repo** | **Microservice** |
58
155
  |---|------------------------|------------------|
59
- | `tmp.yml` konumu | **Zorunlu** `x/tmp.yml` — başka yerde kopya varsa hata | `configs.rootFolderPath` altında (ör. `x/`, `infra/`) |
156
+ | `tmp.yml` konumu | **Zorunlu** `x/tmp.yml` — başka yerde kopya varsa hata | `configs.service.paths.root` altında (ör. `x/`, `infra/`) |
60
157
  | Koruma | `ensureCoreTmpEntry()` — stray tmp engeli | Yok; `tmp.yml` recursive bulunur |
61
158
  | Boot | `ensureCoreTmpEntry` → `getTmpSnapshot` → `coreLoader` | `coreLoader({})` + kendi HTTP sunucun |
62
159
  | Layout runtime’da | Gerekmez — değerler tmp snapshot’tan | Gerekmez — aynı |
63
160
 
64
- Servis runtime’ında `tmp-layout` çalıştırmana gerek yok: `getTmpSnapshot()` / `getRuntimeTmpConfigs()` yeterli. Layout modülü CLI (`xcore dev`, `xcore tmp`, `xcore test`) içindir.
161
+ Servis runtime’ında `tmp-layout` çalıştırmana gerek yok: `getTmpSnapshot()` / `getRuntimeTmpConfigs()` yeterli.
162
+
163
+ **EN:** Layout module is for CLI only (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
164
+
165
+ **TR:** Layout modülü yalnızca CLI içindir (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
65
166
 
66
167
  ### Proje layout’u (`x/`)
67
168
 
68
169
  ```
69
- {proje-kökü}/
170
+ {project-root}/ # EN: repo root · TR: proje kökü
70
171
  ├── package.json
71
- └── {rootFolderPath}/ # default: x
72
- ├── tmp.yml # ana giriş — loaders, framework, protocols
172
+ └── {rootFolderPath}/ # default: x — EN: CLI root (test/dev/build) · TR: CLI kökü
173
+ ├── tmp.yml # EN: main config entry · TR: ana giriş
73
174
  ├── tests/
74
- ├── environments/ # .env dosyaları (xcore dev)
75
- └── dist/ # build çıktısı
175
+ ├── environments/ # EN: .env files (xcore dev) · TR: .env (xcore dev)
176
+ └── dist/ # EN: build output (.js) · TR: build çıktısı (.js)
76
177
  ```
77
178
 
78
- Kaynak kodu `mainFolderPath` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
179
+ Kaynak kodu `service.paths.source` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
79
180
 
80
181
  ```yaml
81
182
  configs:
82
- rootFolderPath: x
83
- mainFolderPath: ./source # veya ./src
84
- paths:
85
- tests: tests
86
- environments: environments
87
- dist: dist
183
+ file:
184
+ rootFolderPath: x
185
+ configFileWatchIntervalMs: 500
186
+
187
+ service:
188
+ name: my-api
189
+ framework: elysia
190
+ folderPath: ./source # veya ./src
191
+ protocols: [http]
192
+ paths:
193
+ tests: tests
194
+ environments: environments
195
+ dist: dist
196
+ build:
197
+ typecheck: true # tmp override — outDir/include tsconfig.json'dan
198
+ loaders:
199
+ dto: { withDefaultHeaders: true }
200
+ controller: {}
201
+ ```
202
+
203
+ **Build ayarları — öncelik sırası**
204
+
205
+ | Ayar | 1. tmp.yml `build.*` | 2. `tsconfig.json` | 3. fallback |
206
+ |------|----------------------|--------------------|-------------|
207
+ | Çıktı klasörü (`outDir`) | `build.outDir` | `compilerOptions.outDir` | `paths.dist` + `rootFolderPath` |
208
+ | Giriş dosyaları (glob) | `build.entries` / `build.glob` | `include` / `rootDir` | `service.paths.source` |
209
+ | Sourcemap | `build.sourcemap` | `sourceMap` / `inlineSourceMap` | kapalı |
210
+ | `.d.ts` | `build.declarations` | `declaration` / full `tsc` | kapalı |
211
+ | Minify (core) | `build.minify` | — | kapalı |
212
+ | Tip kontrolü | `build.typecheck` | — | `false` |
213
+
214
+ Servis örnek `tsconfig.json`:
215
+
216
+ ```json
217
+ {
218
+ "include": ["source"],
219
+ "compilerOptions": {
220
+ "rootDir": "./source",
221
+ "outDir": "./x/dist",
222
+ "sourceMap": false,
223
+ "declaration": false,
224
+ "paths": { "@/*": ["source/*"] },
225
+ "strict": true
226
+ }
227
+ }
88
228
  ```
89
229
 
90
- `tmp.yml` yoksa: `xcore tmp` veya `xcore dev` → paketteki seed `@xrystal/core/x/tmp.yml` kopyalanır.
230
+ `x`, `dist`, kaynak klasörü — tek yerden `outDir` / `include` ile; tmp.yml'de tekrar yazmana gerek yok (override istemiyorsan).
231
+
232
+ `tmp.yml` yoksa:
233
+
234
+ **EN:** `xcore tmp` or `xcore dev` copies seed from `@xrystal/core/x/tmp.yml`.
235
+
236
+ **TR:** `xcore tmp` veya `xcore dev` → seed `@xrystal/core/x/tmp.yml` kopyalanır.
91
237
 
92
238
  ### Boot sırası (lib)
93
239
 
@@ -98,14 +244,14 @@ configs:
98
244
 
99
245
  `tmp.yml` kaydedilince restart gerekmez — `TmpFileLoader` watch → `System.applyTmp()` → tüm loader’lar yeniden sync.
100
246
 
101
- ### CLI vs runtime
247
+ ### CLI vs runtime / CLI ve runtime
102
248
 
103
- | Araç | Rol |
104
- |------|-----|
105
- | `xcore` / `xrystal` / `tmp` | Aynı binary — dev, test, build, doctor, tag, tmp ensure, create |
106
- | `getTmpSnapshot()` | Uygulama içi config |
107
- | `dtoMiddleware()` + `ctr()` | HTTP handler pipeline |
108
- | `realtimeMiddleware()` + `runAction()` | WebSocket / Socket.IO |
249
+ | Tool / Araç | EN | TR |
250
+ |---------------|----|----|
251
+ | `xcore` / `xrystal` / `tmp` | Same binary — dev, test, build, doctor, tag, tmp ensure, create | Aynı binary — dev, test, build, doctor, tag, tmp ensure, create |
252
+ | `getTmpSnapshot()` | In-app config | Uygulama içi config |
253
+ | `dtoMiddleware()` + `ctr()` | HTTP handler pipeline | HTTP handler pipeline |
254
+ | `realtimeMiddleware()` + `runAction()` | WebSocket / Socket.IO | WebSocket / Socket.IO |
109
255
 
110
256
  ---
111
257
 
@@ -117,7 +263,7 @@ Tek repo, tek `tmp.yml`, tek boot — Elysia HTTP örneği:
117
263
  my-api/
118
264
  ├── x/
119
265
  │ ├── tmp.yml
120
- │ ├── tests/ # servis testleri (xcore test)
266
+ │ ├── tests/ # EN: service tests (xcore test) · TR: servis testleri (xcore test)
121
267
  │ └── environments/
122
268
  ├── src/
123
269
  │ ├── boot.ts
@@ -135,17 +281,22 @@ npm i @xrystal/core elysia
135
281
 
136
282
  ```yaml
137
283
  configs:
138
- framework: elysia
139
- service: my-api
140
- protocols: [http]
141
- loaders:
142
- system:
143
- gStore:
144
- options: { bootstrap: true, autoCreateProps: false }
145
- vars: { maintenance: false }
146
- dto: { withDefaultHeaders: true }
147
- loggers: { logLevel: info }
148
- controller: {}
284
+ file:
285
+ rootFolderPath: x
286
+
287
+ service:
288
+ name: my-api
289
+ framework: elysia
290
+ folderPath: ./src
291
+ protocols: [http]
292
+ loaders:
293
+ system:
294
+ gStore:
295
+ options: { bootstrap: true, autoCreateProps: false }
296
+ vars: { maintenance: false }
297
+ dto: { withDefaultHeaders: true }
298
+ loggers: { logLevel: info }
299
+ controller: {}
149
300
  ```
150
301
 
151
302
  **3) Controller**
@@ -195,18 +346,31 @@ Servis `package.json` örneği:
195
346
 
196
347
  ```json
197
348
  {
198
- "dependencies": { "@xrystal/core": "^3.30.3", "elysia": "^1.4.19" },
349
+ "dependencies": { "@xrystal/core": "^3.32.2", "elysia": "^1.4.19" },
199
350
  "scripts": {
200
351
  "dev": "xcore dev",
201
352
  "build": "xcore build",
353
+ "start:dist": "xcore start",
202
354
  "test": "xcore test",
355
+ "lint": "eslint .",
356
+ "sync-toolchain": "xcore sync-toolchain",
357
+ "doctor": "xcore doctor",
203
358
  "version:check": "xcore version",
204
- "release:tag": "xcore tag"
359
+ "release:tag": "xcore tag",
360
+ "hooks:install": "xcore hooks install"
205
361
  }
206
362
  }
207
363
  ```
208
364
 
209
- Detay: [CLI (`xcore` · `xrystal` · `tmp`)](#cli-xcore--xrystal--tmp)
365
+ **İlk kurulum / klasör adı değişince (manuel, bir kez):**
366
+
367
+ ```bash
368
+ bun run sync-toolchain # tmp.yml → tsconfig paths; eslint tmp'den okur
369
+ bun run doctor # drift kontrolü
370
+ # sync çıktısındaki satırı bunfig.toml [resolve.alias]'a ekle
371
+ ```
372
+
373
+ Detay: [Servislerde `sync-toolchain`](#servislerde-sync-toolchain-manuel)
210
374
 
211
375
  Public API:
212
376
 
@@ -226,22 +390,27 @@ import coreLoader from '@xrystal/core/project'
226
390
 
227
391
  ```yaml
228
392
  configs:
229
- framework: elysia # elysia | express | node | fetch
230
- service: my-api
231
- protocols: [http, ws] # http, ws, socketio
232
-
233
- loaders:
234
- system:
235
- gStore:
236
- options:
237
- bootstrap: true
238
- autoCreateProps: false
239
- vars:
240
- maintenance: false
241
- dto: { withDefaultHeaders: true }
242
- localization: { fallbackLang: en, preloadLangs: [en, tr] }
243
- loggers: { logLevel: debug }
244
- controller: {}
393
+ file:
394
+ rootFolderPath: x
395
+ configFileWatchIntervalMs: 500
396
+
397
+ service:
398
+ name: my-api
399
+ framework: elysia # elysia | express | node | fetch
400
+ folderPath: ./src
401
+ protocols: [http, ws] # http, ws, socketio
402
+ loaders:
403
+ system:
404
+ gStore:
405
+ options:
406
+ bootstrap: true
407
+ autoCreateProps: false
408
+ vars:
409
+ maintenance: false
410
+ dto: { withDefaultHeaders: true }
411
+ localization: { fallbackLang: en, preloadLangs: [en, tr] }
412
+ loggers: { logLevel: debug }
413
+ controller: {}
245
414
  ```
246
415
 
247
416
  Save the file → **live reload**: `System.applyTmp()` → `G.configureFromTmp()` → every loader `syncFromTmp()`.
@@ -1115,7 +1284,7 @@ sequenceDiagram
1115
1284
  participant G as G store
1116
1285
  participant L as Loaders
1117
1286
 
1118
- YML->>TFL: watchFile (~500ms)
1287
+ YML->>TFL: watchFile (configs.core.tmp.fileWatchIntervalMs)
1119
1288
  TFL->>SYS: reload event
1120
1289
  SYS->>SYS: applyTmp(parsed)
1121
1290
  SYS->>RT: setRuntimeTmpConfigs
@@ -1393,17 +1562,23 @@ Mapping lives in `utils/helpers/middleware/` — `socketio` → `socketIo()`, `w
1393
1562
 
1394
1563
  ## CLI (`xcore` · `xrystal` · `tmp`)
1395
1564
 
1396
- `@xrystal/core` kurulunca **üç bin adı** aynı CLI’yı açar — tek entry (`x/bin/main-cli.js`), aynı komutlar, aynı proje kökü çözümlemesi:
1565
+ **EN:** Installing `@xrystal/core` exposes **three bin names** for the same CLI (`x/bin/main-cli.js`) — same commands, same project-root resolution.
1566
+
1567
+ **TR:** `@xrystal/core` kurulunca **üç bin adı** aynı CLI’yı açar — aynı komutlar, aynı proje kökü çözümlemesi.
1397
1568
 
1398
- | Bin | Rol | Örnek |
1399
- |-----|-----|-------|
1400
- | **`xcore`** | Ana isim (önerilen) | `xcore doctor`, `npx xcore dev` |
1401
- | **`xrystal`** | Geçiş alias | `xrystal version` = `xcore version` |
1402
- | **`tmp`** | Geçiş alias (eski alışkanlık) | `tmp tag` = `xcore tag` |
1569
+ | Bin | EN | TR | Example |
1570
+ |-----|----|----|---------|
1571
+ | **`xcore`** | Primary name (recommended) | Ana isim (önerilen) | `xcore doctor`, `npx xcore dev` |
1572
+ | **`xrystal`** | Transition alias | Geçiş alias | `xrystal version` = `xcore version` |
1573
+ | **`tmp`** | Legacy alias | Eski alışkanlık alias | `tmp tag` = `xcore tag` |
1403
1574
 
1404
- Hangisini yazarsan yaz: proje kökü, git, version/tag, dev/build/test **aynı kod yolu**. Banner ve komut çıktısı çağırdığın bin adını gösterir (`tmp doctor` → `tmp doctor`).
1575
+ **EN:** Any bin name resolves project root, git, version/tag, and `dev`/`build`/`test` through the **same code path**. Banner shows the bin you invoked.
1405
1576
 
1406
- `@xrystal/core` dependency’si olan **her servis reposunda** doğrudan kullanılır — global kurulum gerekmez. Alt klasörden (`src/`, `x/`, …) çalıştırsan bile CLI yukarı çıkar, `@xrystal/core` içeren `package.json`’ı proje kökü sayar; git / version / tag **o servisin** kökünde kalır.
1577
+ **TR:** Hangi bin adını yazarsan yaz: proje kökü, git, version/tag, dev/build/test **aynı kod yolu**. Banner çağırdığın bin adını gösterir.
1578
+
1579
+ **EN:** Works in every service repo with `@xrystal/core` — no global install. From a subfolder (`src/`, `x/`, …) the CLI walks up to the `package.json` that depends on `@xrystal/core`; git / version / tag stay on **that service root**.
1580
+
1581
+ **TR:** `@xrystal/core` dependency’si olan her serviste doğrudan kullanılır — global kurulum gerekmez. Alt klasörden çalıştırsan bile CLI yukarı çıkar; git / version / tag **o servisin** kökünde kalır.
1407
1582
 
1408
1583
  ```bash
1409
1584
  cd api-gateway-svc/src
@@ -1413,7 +1588,9 @@ npx xrystal version # aynı
1413
1588
  npx tmp tag # aynı — servis tag + push
1414
1589
  ```
1415
1590
 
1416
- Servis `package.json` script’lerinde **herhangi bir alias** kullanılabilir; davranış değişmez:
1591
+ **EN:** Any bin alias in service `package.json` scripts — same behavior.
1592
+
1593
+ **TR:** Servis `package.json` script’lerinde herhangi bir alias kullanılabilir; davranış değişmez.
1417
1594
 
1418
1595
  ```json
1419
1596
  {
@@ -1427,32 +1604,49 @@ Servis `package.json` script’lerinde **herhangi bir alias** kullanılabilir; d
1427
1604
 
1428
1605
  ---
1429
1606
 
1430
- ### Üç script katmanı
1431
-
1432
- | Katman | Nerede tanımlı | Ne zaman | Örnek |
1433
- |--------|----------------|----------|-------|
1434
- | **CLI ortak** | `@xrystal/core` bin (`xcore` / `xrystal` / `tmp`) | Tüm servislerde aynı | `xcore dev`, `tmp version`, `xrystal tag` |
1435
- | **Proje (servis)** | Servis `package.json` → `scripts` | Servise özel mantık; `xcore build` bunu önceler | `"build": "bun build src/boot.ts"`, `"start": "bun x/dist/boot.js"` |
1436
- | **Lib (core repo)** | `@xrystal/core` kendi `package.json` | Sadece core geliştirirken / publish | `"build:prod"`, `"tag"`, `"version:check"` |
1607
+ ### Three script layers / Üç script katmanı
1608
+
1609
+ | Layer / Katman | Defined in / Tanım | When / Ne zaman | Example / Örnek |
1610
+ |----------------|-------------------|-----------------|-----------------|
1611
+ | **CLI (shared)** | `@xrystal/core` bin (`xcore` / `xrystal` / `tmp`) | Same in all services / Tüm servislerde aynı | `xcore dev`, `tmp version`, `xrystal tag` |
1612
+ | **Project (service)** | Service `package.json` → `scripts` | Service-specific; `xcore build` delegates if custom / Servise özel; özel build varsa delegate | `"build": "bun build src/boot.ts"` |
1613
+ | **Lib (core repo)** | `@xrystal/core` own `package.json` | Core dev / publish only / Sadece core geliştirme | `"release:prepare"`, `"tag"` |
1614
+
1615
+ **EN — shared CLI commands** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = project root):
1616
+
1617
+ | Command | What it does |
1618
+ |---------|----------------|
1619
+ | `<bin> version` | CLI version + project `package.json` ↔ git HEAD |
1620
+ | `<bin> tag` | `v{version}` tag + push from **project** version |
1621
+ | `<bin> doctor` | Runtimes, git, installed `@xrystal/core` vs CLI |
1622
+ | `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
1623
+ | `<bin> dev` | Watch `{service.folderPath}/index.ts` + dev env |
1624
+ | `<bin> build` | Output → `{rootFolderPath}/{paths.dist}/` |
1625
+ | `<bin> start` | Run `{rootFolderPath}/{paths.dist}/index.js` + prod env |
1626
+ | `<bin> tmp` | Ensure `tmp.yml` from seed if missing |
1627
+ | `<bin> create [name] [path]` | GitHub template clone + `tmp.yml` ensure |
1437
1628
 
1438
- **CLI ortak komutlar** (lib’den gelir; bin adı fark etmez; cwd = proje kökü):
1629
+ **TR — ortak CLI komutlar** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = proje kökü):
1439
1630
 
1440
1631
  | Komut | Ne yapar |
1441
1632
  |-------|----------|
1442
1633
  | `<bin> version` | CLI sürümü + **proje** `package.json` ↔ git HEAD |
1443
1634
  | `<bin> tag` | **Proje** versiyonundan `v{version}` tag + push |
1444
1635
  | `<bin> doctor` | runtime, git, kurulu `@xrystal/core` vs CLI |
1445
- | `<bin> test` | `bun test ./x/tests` — core repo: lib testleri; servis: kendi testleri |
1446
- | `<bin> dev` | `bun --watch` + `x/environments/*.env` + `source/index.ts` |
1447
- | `<bin> build` | Serviste `scripts.build` varsa onu çalıştırır; yoksa lib default → `x/dist` |
1448
- | `<bin> tmp` | `tmp.yml` yoksa template'den oluşturur; varsa path gösterir |
1449
- | `<bin> create [name] [path]` | GitHub template clone + `tmp.yml` ensure |
1636
+ | `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
1637
+ | `<bin> dev` | `{service.folderPath}/index.ts` watch + dev env |
1638
+ | `<bin> build` | Çıktı → `{rootFolderPath}/{paths.dist}/` |
1639
+ | `<bin> start` | `{rootFolderPath}/{paths.dist}/index.js` + prod env |
1640
+ | `<bin> tmp` | `tmp.yml` yoksa seed’den oluşturur |
1641
+ | `<bin> create [name] [path]` | GitHub template + `tmp.yml` ensure |
1450
1642
 
1451
- `<bin>` = `xcore`, `xrystal` veya `tmp` (bin alias — aynı CLI).
1643
+ **EN:** If `tmp.yml` is missing, `xcore tmp` / `dev` / `test` / `build` copy seed from `@xrystal/core/x/tmp.yml` into `{rootFolderPath}/tmp.yml`.
1452
1644
 
1453
- **tmp.yml otomatik:** Silinmişse `xcore tmp` / `dev` / `test` / `build`, paketteki seed `@xrystal/core/x/tmp.yml` dosyasından proje `{rootFolderPath}/tmp.yml` oluşturur. Ayrı template dosyası yok.
1645
+ **TR:** `tmp.yml` silinmişse `xcore tmp` / `dev` / `test` / `build`, seed `@xrystal/core/x/tmp.yml` dosyasından `{rootFolderPath}/tmp.yml` oluşturur.
1454
1646
 
1455
- **Core kütüphane koruması:** `@xrystal/core` repo’sunda `tmp.yml` yalnızca `x/tmp.yml` olabilir; başka dizinde kopya varsa boot/CLI hata verir. Servislerde bu kural yok — `rootFolderPath` tmp’den okunur.
1647
+ **EN — core repo guard:** In `@xrystal/core` repo, `tmp.yml` must be only `x/tmp.yml`; stray copies fail boot/CLI. Services have no such rule.
1648
+
1649
+ **TR — core koruması:** `@xrystal/core` repo’sunda `tmp.yml` yalnızca `x/tmp.yml`; başka kopya hata verir. Servislerde bu kural yok.
1456
1650
 
1457
1651
  ```bash
1458
1652
  xcore tmp # ensure tmp.yml
@@ -1460,105 +1654,417 @@ xcore create example ./ # GitHub template + tmp ensure
1460
1654
  tmp dev # bin alias = xcore dev
1461
1655
  ```
1462
1656
 
1463
- **Ayarlar (`configs` in tmp.yml):** `rootFolderPath`, `mainFolderPath`, `paths.*`, `loaders`, `framework` — servis tek kaynağı. Core pakette default `rootFolderPath: x`.
1657
+ **EN:** `configs` in `tmp.yml`: `service.*` + `core.*` — single source per service. Core package default: `service.paths.root: x`.
1658
+
1659
+ **TR:** `tmp.yml` içinde `configs`: `service.*` + `core.*` — servis tek kaynak. Core pakette default `service.paths.root: x`.
1660
+
1661
+ **EN — recommended service `package.json` wiring** (bind shared CLI commands; keep service-specific scripts separate):
1464
1662
 
1465
- **Servis `package.json` — önerilen wiring** (ortak komutları script’e bağla, servise özel olanları ayrı tut):
1663
+ **TR — önerilen servis `package.json` wiring** (ortak komutları script’e bağla; servise özel olanları ayrı tut):
1466
1664
 
1467
1665
  ```json
1468
1666
  {
1469
1667
  "name": "api-gateway-svc",
1470
1668
  "version": "26.06.27-v1",
1471
1669
  "dependencies": {
1472
- "@xrystal/core": "^3.30.3"
1670
+ "@xrystal/core": "^3.34.0"
1473
1671
  },
1474
1672
  "scripts": {
1475
1673
  "dev": "xcore dev",
1476
1674
  "build": "xcore build",
1675
+ "start:dist": "xcore start",
1477
1676
  "test": "xcore test",
1677
+ "lint": "eslint .",
1678
+ "sync-toolchain": "xcore sync-toolchain",
1478
1679
  "doctor": "xcore doctor",
1479
1680
  "version:check": "xcore version",
1480
1681
  "release:tag": "xcore tag",
1481
- "start": "bun --env-file=./x/environments/.prod.env x/dist/boot.js"
1682
+ "start": "bun --env-file=./x/environments/.prod.env x/dist/index.js"
1482
1683
  }
1483
1684
  }
1484
1685
  ```
1485
1686
 
1486
- Sonra servis kökünden:
1687
+ **EN — toolchain files (service)**
1688
+
1689
+ **TR — toolchain dosyaları (servis)**
1690
+
1691
+ | File / Dosya | Required? / Zorunlu? | Note / Not |
1692
+ |--------------|----------------------|------------|
1693
+ | `{rootFolderPath}/tmp.yml` | Yes / Evet | Folder names here / Klasör adları burada |
1694
+ | `tsconfig.json` | Yes / Evet | Updated by `sync-toolchain` |
1695
+ | `eslint.config.js` | Recommended / Önerilir | Reads tmp — [example](#toolchain--klasör-adları-tmpyml-kurallar-tsconfigbasejson) |
1696
+ | `bunfig.toml` | Bun test/dev | `@/*` alias from sync output |
1697
+
1698
+ **EN — from service root:**
1699
+
1700
+ **TR — servis kökünden:**
1487
1701
 
1488
1702
  ```bash
1489
1703
  bun run dev # = xcore dev
1490
1704
  bun run version:check # = xcore version → api-gateway-svc version, git HEAD
1491
1705
  bun run release:tag # = xcore tag → servis tag’i, core değil
1492
1706
  bun run doctor # CLI vs node_modules @xrystal/core uyumu
1707
+ bun run sync-toolchain # sadece layout değişince (aşağıya bak)
1708
+ ```
1709
+
1710
+ **EN — dev vs prod entry**
1711
+
1712
+ | Command | Runs | Path |
1713
+ |---------|------|------|
1714
+ | `xcore dev` | TypeScript source | `{service.folderPath}/index.ts` |
1715
+ | `xcore build` | Compiles to dist | `{rootFolderPath}/{paths.dist}/` |
1716
+ | `xcore start` | Production JS | `{rootFolderPath}/{paths.dist}/index.js` |
1717
+
1718
+ **TR — dev vs prod giriş**
1719
+
1720
+ | Komut | Çalıştırır | Yol |
1721
+ |-------|------------|-----|
1722
+ | `xcore dev` | TypeScript kaynak | `{service.folderPath}/index.ts` |
1723
+ | `xcore build` | Derler | `{rootFolderPath}/{paths.dist}/` |
1724
+ | `xcore start` | Prod JS | `{rootFolderPath}/{paths.dist}/index.js` |
1725
+
1726
+ **EN — service build:** `tsconfig.json` is primary (`include`, `outDir`, `rootDir`, `sourceMap`, `paths`, `strict`). `tmp.yml` `build.*` = explicit overrides only. `tmp.yml` runtime = loaders, protocols, `rootFolderPath`.
1727
+
1728
+ **TR — servis build:** `tsconfig.json` birincil. `tmp.yml` `build.*` = yalnızca override. `tmp.yml` runtime = loaders, protocols, `rootFolderPath`.
1729
+
1730
+ | File / Dosya | EN | TR |
1731
+ |--------------|----|----|
1732
+ | `tsconfig.json` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` via `--noEmit` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` için `--noEmit` |
1733
+ | `tmp.yml` `build.*` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` |
1734
+ | `tmp.yml` `paths.*` | Runtime (test, env); dist fallback if no `outDir` | Runtime (test, env); `outDir` yoksa dist fallback |
1735
+
1736
+ | `configs.build` (override) | tsconfig karşılığı | Ne yapar |
1737
+ |-----------------------------|-------------------|----------|
1738
+ | `outDir` | `compilerOptions.outDir` | Çıktı klasörü — **tsconfig'te `./x/dist` yaz, tmp'de tekrarlama** |
1739
+ | `glob` / `entries` | `include` / `rootDir` | Hangi `.ts` derlenecek |
1740
+ | `sourcemap` | `sourceMap` / `inlineSourceMap` | Harita (default kapalı) |
1741
+ | `declarations` | `declaration` / `emitDeclarationOnly` | `.d.ts` üret |
1742
+ | `minify` | — (core build) | `tsc` sonrası `minify-dist.mjs` (tmp `build.minify: true`) |
1743
+ | `typecheck` | — (tsconfig kuralları okunur) | `tsc --noEmit` build öncesi |
1744
+ | `tsconfig` | dosya yolu | `tsconfig.build.json` vb. |
1745
+ | `tscLenient` | — | Sadece `declarations: true` + tsc hatalarını yoksay |
1746
+
1747
+ **EN — priority:** tmp.yml explicit > tsconfig.json > tmp layout fallback
1748
+
1749
+ **TR — öncelik:** tmp.yml explicit > tsconfig.json > tmp layout fallback
1750
+
1751
+ ```yaml
1752
+ configs:
1753
+ file:
1754
+ rootFolderPath: x
1755
+
1756
+ service:
1757
+ folderPath: ./source
1758
+ build:
1759
+ typecheck: true # tek satır yeter — outDir/include tsconfig'te
1760
+ ```
1761
+
1762
+ ```json
1763
+ // tsconfig.json — servis/lib ortak model
1764
+ {
1765
+ "include": ["source"],
1766
+ "compilerOptions": {
1767
+ "rootDir": "./source",
1768
+ "outDir": "./x/dist",
1769
+ "sourceMap": false,
1770
+ "declaration": false,
1771
+ "strict": true,
1772
+ "paths": { "@/*": ["source/*"] }
1773
+ }
1774
+ }
1493
1775
  ```
1494
1776
 
1495
- **`xcore build` öncelik sırası:**
1777
+ **EN — build order (service):** `typecheck?` → `rm dist` → `bun build .ts` → `declarations?`
1496
1778
 
1497
- 1. Servis `package.json` içinde `scripts.build` var ve `name !== @xrystal/core` → `bun run build` (proje script’in)
1498
- 2. Aksi halde lib default: `bun build` + `tsc` + `tsc-alias` → `./x/dist`
1779
+ **TR — build sırası (servis):** `typecheck?` → `rm dist` → `bun build .ts` → `declarations?`
1499
1780
 
1500
- Servise özel build mantığını `scripts.build`’e yaz; `xcore build` onu çağırır. Ortak dev/test/version/tag için `xcore` yeterli — tekrar yazmana gerek yok.
1781
+ **EN — build order (@xrystal/core lib):** `rm x/dist` → `tsc` (JS + `.d.ts`) → `tsc-alias` → `fix-dist-imports` → `minify-dist?` (`build.minify`)
1782
+
1783
+ **TR — build sırası (@xrystal/core lib):** `rm x/dist` → `tsc` → `tsc-alias` → `fix-dist-imports` → `minify-dist?` (`build.minify`)
1784
+
1785
+ **EN:** `prepublishOnly` / `release:prepare` runs lint → build → test. Publish CI strips `source/`; npm gets minified `x/dist` only (+ `x/bin`, seed `tmp.yml`, assets).
1786
+
1787
+ **TR:** `prepublishOnly` / `release:prepare` lint → build → test çalıştırır. Publish CI `source/` siler; npm’e yalnızca minify `x/dist` (+ `x/bin`, seed `tmp.yml`, assets) girer.
1788
+
1789
+ ```bash
1790
+ xcore build
1791
+ xcore start # bun x/dist/index.js (+ .global.env / .prod.env if present)
1792
+ ```
1501
1793
 
1502
- **Lib script’leri** (`@xrystal/core` repo — geliştirici / publish):
1794
+ **Build output / derleme çıktısı**
1503
1795
 
1504
- | Script | Karşılığı |
1505
- |--------|-----------|
1506
- | `npm run dev` | Core kaynak watch (infrastructer env) |
1507
- | `npm run build` | Core bundle + tsc (geliştirme) |
1508
- | `npm run release:prepare` | `lint` → `test` → `build` (doğrulama; git’e yazmaz) |
1509
- | `npm run tag` / `xcore tag` | release prepare, sonra git tag + push |
1510
- | `npm run version:check` | `node x/bin/scripts/version-check.mjs` |
1511
- | `npm publish` | GitHub Actions tag’de otomatik (`--ignore-scripts`; test/lint CI’da prepare öncesi) |
1512
- | `npm run build:prod` | **Sadece yerel npm denemesi** — `.ts` siler; **git’e commit etme** |
1796
+ | Layer | Path | Role |
1797
+ |-------|------|------|
1798
+ | Source (dev) | `{service.folderPath}/**/*.ts` | `xcore dev` runs TS directly |
1799
+ | Prod runtime | `tsconfig outDir` → `.js` | `xcore start`, Docker |
1800
+ | Source map | `{outDir}/**/*.js.map` | tsconfig `sourceMap` veya tmp `build.sourcemap` |
1801
+ | Declarations | `{outDir}/**/*.d.ts` | tsconfig `emitDeclarationOnly` veya tmp `build.declarations` |
1513
1802
 
1514
- **`xcore tag` akışı (@xrystal/core):**
1803
+ **EN:** Put `include`, `outDir`, `sourceMap`, `paths`, `strict` in `tsconfig.json`. tmp.yml `build.*` only when you need an override (e.g. `typecheck: true`).
1515
1804
 
1516
- 1. `package.json` version commit edilmiş olmalı
1517
- 2. `lint` → `test` → `build` (CI ile aynı build adımı; kaynak `.ts` kalır)
1518
- 3. `git tag vX.Y.Z` + push
1519
- 4. **GitHub Actions** (`publish.yml`): checkout → `build` → `source/` içine `.js` kopyala → `npm publish`
1805
+ **TR:** `include`, `outDir`, `sourceMap`, `paths`, `strict` → `tsconfig.json`. tmp.yml `build.*` sadece override için (ör. `typecheck: true`).
1806
+
1807
+ **Loop fix / döngü fix:** `"build": "xcore build"` no longer delegates to itself — default build runs.
1808
+
1809
+ **`xcore build` priority / öncelik:**
1810
+
1811
+ 1. **EN:** Custom `scripts.build` (not `xcore build`) → `bun run build`
1812
+ **TR:** Özel `scripts.build` (xcore build değilse) → delegate
1813
+ 2. **EN:** Else: read `tsconfig.json` (include/outDir/sourceMap) + tmp.yml overrides
1814
+ **TR:** Aksi halde tsconfig okunur + tmp.yml override
1815
+
1816
+ **Lib scripts / Lib script’leri** (`@xrystal/core` repo — developer / geliştirici):
1817
+
1818
+ | Script | EN | TR |
1819
+ |--------|----|----|
1820
+ | `npm run dev` | Core source watch | Core kaynak watch |
1821
+ | `npm run build` | `tsc` → alias → fix-dist-imports (+ minify) | `tsc` tam emit → Node ESM import düzeltme |
1822
+ | `npm run release:prepare` | lint → build → test (no git write) | lint → build → test (git’e yazmaz) |
1823
+ | `xcore hooks install` | Install pre-commit into `.git/hooks` (core + services) | `.git/hooks` pre-commit (core + servis) |
1824
+ | `npm run tag` / `xcore tag` | prepare + git tag + push | prepare + tag + push |
1825
+ | `npm publish` | GitHub Actions on tag (`--ignore-scripts`) | Tag’de CI publish eder |
1826
+
1827
+ **`xcore tag` flow / akışı (@xrystal/core):**
1828
+
1829
+ 1. **EN:** Commit `package.json` version bump first.
1830
+ **TR:** Önce `package.json` version commit edilmeli.
1831
+ 2. **EN:** `lint` → `build` → `test` (TypeScript stays in git; runtime in `x/dist`).
1832
+ **TR:** `lint` → `build` → `test` (git’te `.ts` kalır; runtime `x/dist`’te).
1833
+ 3. **EN:** `git tag vX.Y.Z` + push → GitHub Actions publishes to npm.
1834
+ **TR:** Tag + push → CI npm’e publish eder.
1835
+
1836
+ **EN:** Never commit compiled `.js` under `source/`. Publish CI runs `prepare-npm-publish.mjs` — removes `source/`, ships minified `x/dist` only (folder tree preserved; identifiers mangled when `build.minify: true`).
1837
+
1838
+ **TR:** `source/` altına derlenmiş `.js` commit etme. Publish CI `prepare-npm-publish.mjs` çalıştırır — `source/` silinir, npm’e yalnızca minify `x/dist` gider (klasör yapısı korunur; `build.minify: true` ile identifier’lar küçültülür).
1839
+
1840
+ **EN:** Service `npm run tag` does not publish `@xrystal/core` — use `xcore tag` or `"release:tag": "xcore tag"` on the **service** repo.
1841
+
1842
+ **TR:** Serviste `npm run tag` **@xrystal/core** publish etmez — servis repo’sunda `xcore tag` veya `"release:tag": "xcore tag"` kullan.
1843
+
1844
+ ---
1845
+
1846
+ ### Version bump + `hooks:install` — when / ne zaman?
1847
+
1848
+ **EN — what does it do?**
1849
+ `xcore hooks install` writes `pre-commit` into `.git/hooks/pre-commit` (local git dir, not committed to the repo). After that, every **`git commit`** runs a **pre-commit** check: if you staged a **`package.json` version change**, the new version must be **strictly greater** than the old one (`3.35.0` → `3.35.1` ✅ · `3.35.0` → `3.35.0` ❌). Commits that do not change `version` are not blocked.
1850
+
1851
+ **TR — ne yapar?**
1852
+ `xcore hooks install` `.git/hooks/pre-commit` dosyasını yazar (repo'ya commit edilmez, sadece senin makinede). Sonrasında **`git commit`** atarken: **`package.json` içindeki `version` değiştiyse**, yeni sürüm eskisinden **büyük** olmalı. Sadece kod değişikliği commit'lerinde version aynı kalabilir.
1853
+
1854
+ **EN — when do I run it?**
1855
+
1856
+ | Situation | Run `hooks:install`? |
1857
+ |-----------|----------------------|
1858
+ | First clone of **`-xrystal-core`** on this machine | **Yes — once** |
1859
+ | Commits never block same/lower version bumps | **Yes — once** |
1860
+ | After `bun install` in core repo | Run once after clone |
1861
+ | Before every commit or tag | **No** |
1862
+ | **Service repo** (only uses `@xrystal/core`) | **Yes — once** |
1863
+ | **`xcore create`** scaffolded a new service | **Auto** — hook + `hooks:install` script |
1864
+
1865
+ **TR — ne zaman çalıştırırım?**
1866
+
1867
+ | Durum | `hooks:install`? |
1868
+ |-------|------------------|
1869
+ | **`-xrystal-core`** reposunu bu makinede ilk kez clone'ladım | **Evet — bir kez** |
1870
+ | Commit atınca version kontrolü hiç çalışmıyor | **Evet — bir kez** |
1871
+ | Core repo'da `bun install` sonrası | Clone sonrası bir kez |
1872
+ | Her commit / tag öncesi | **Hayır** |
1873
+ | Sadece servis reposu | **Evet — bir kez** |
1874
+ | **`xcore create`** ile yeni servis oluşturdum | **Otomatik** — hook + `hooks:install` script |
1875
+
1876
+ ```bash
1877
+ # @xrystal/core repo — first time on this machine / bu makinede ilk kez
1878
+ cd -xrystal-core
1879
+ xcore hooks install # core repo or service repo
1880
+ # core repo only: bun run hooks:install
1881
+ ```
1882
+
1883
+ **EN — two layers of protection**
1884
+
1885
+ | Layer | When | Rule |
1886
+ |-------|------|------|
1887
+ | **pre-commit hook** | `git commit` (if hook installed) | Staged `version` > HEAD `version` |
1888
+ | **`xcore tag`** | Before tag + push | Committed `version` > latest git tag |
1889
+
1890
+ **TR — iki katman**
1891
+
1892
+ | Katman | Ne zaman | Kural |
1893
+ |--------|----------|-------|
1894
+ | **pre-commit hook** | `git commit` (hook kuruluysa) | Stage'deki `version` > HEAD'teki `version` |
1895
+ | **`xcore tag`** | Tag + push öncesi | Commit'teki `version` > son git tag |
1896
+
1897
+ **EN — typical release (core maintainer)**
1898
+
1899
+ ```bash
1900
+ # 1. Bump package.json version (e.g. 3.35.0 → 3.35.1)
1901
+ git add package.json
1902
+ git commit -m "chore: release 3.35.1" # hook blocks same/lower version
1903
+
1904
+ xcore tag # lint + test + build + version check again
1905
+ ```
1906
+
1907
+ **TR — tipik release**
1908
+
1909
+ ```bash
1910
+ # 1. package.json version artır (ör. 3.35.0 → 3.35.1)
1911
+ git add package.json
1912
+ git commit -m "chore: release 3.35.1" # hook aynı/düşük version'u reddeder
1913
+
1914
+ xcore tag # lint + test + build + version tekrar kontrol
1915
+ ```
1916
+
1917
+ **EN:** `xcore doctor` / `xcore version` show `latest tag` and `bump vs latest tag`.
1918
+ **TR:** `xcore doctor` / `xcore version` → `latest tag` ve bump durumu.
1919
+
1920
+ **EN:** Hook not installed? Commits still work — **`xcore tag`** enforces the bump at release.
1921
+ **TR:** Hook kurulu değilse commit olur — release'te **`xcore tag`** yine kontrol eder.
1520
1922
 
1521
- Git’te **her zaman TypeScript** kalır. `.js` publish anında CI’da üretilir — `build:prod` commit’lenmez.
1522
1923
 
1523
- Serviste `npm run tag` **servis** tag’i üretmez — servis için `xcore tag` veya `"release:tag": "xcore tag"` kullan.
1524
1924
 
1525
1925
  ---
1526
1926
 
1527
1927
  ### `doctor` — iki sürüm
1528
1928
 
1929
+ `xcore doctor` ayrıca **Runtimes (PATH)** ve **Node version managers** envanterini listeler (`node`, `bun`, `npm`, `fnm`, `nvm`, …) — hangi binary’nin aktif olduğunu gösterir.
1930
+
1529
1931
  | Alan | Anlam |
1530
1932
  |------|--------|
1531
1933
  | **CLI (tool)** | Çalışan `xcore` binary’sinin `@xrystal/core` sürümü |
1532
1934
  | **Project (service)** | `api-gateway-svc@1.x` — servisin kendi `package.json` `version` |
1533
1935
  | **node_modules** | Kurulu `@xrystal/core` — CLI ile eşleşiyor mu |
1936
+ | **Toolchain** | `defaults.json` → önerilen `outDir` / `include` / eslint — `tsconfig.json` uyumu |
1534
1937
 
1535
1938
  ---
1536
1939
 
1537
- ### `x/` klasörü (ortak layout — tmp.yml ile yapılandırılır)
1940
+ ### npm + Node (Express gibi — framework/runtime bağımsız)
1941
+
1942
+ **Runtime:** Tüketici projede `import … from '@xrystal/core'` → **Node.js ESM** (Express/Fastify/Elysia fark etmez). Publish sonrası paket `.js` + `.d.ts` içerir; uygulama çalıştırmak için Bun şart değil.
1538
1943
 
1539
- **@xrystal/core paketi** npm'de `x/tmp.yml` seed dosyasını taşır (default `rootFolderPath: x`). **Servisler** kendi `tmp.yml` → `configs` ayarlarından layout okur; klasör adı değiştirilebilir.
1944
+ **Tooling:** `xcore` CLI (dev, build, test) geliştirme aracıdır — repo içinde Bun kullanır. npm’e yüklenen kütüphane Bun’a bağımlı değildir.
1945
+
1946
+ | Katman | Bun gerekli mi? | Ne yapar |
1947
+ |--------|-----------------|----------|
1948
+ | `import '@xrystal/core'` | Hayır (Node) | Lib runtime |
1949
+ | `xcore dev` / `build` | Evet (CLI) | Proje geliştirme |
1950
+ | Docker prod `node x/dist/index.js` | Hayır | Servis prod |
1951
+
1952
+ ---
1953
+
1954
+ ### Toolchain — klasör adları `tmp.yml`, kurallar `tsconfig.base.json`
1955
+
1956
+ **Sorun:** `tsconfig` / `eslint` içinde `x`, `source` hardcode → serviste `infra`, `src` olunca kırılır.
1957
+
1958
+ **Çözüm:** Klasör yolları **yalnızca `tmp.yml`**; tsconfig path alanları **sync** ile yazılır:
1959
+
1960
+ ```yaml
1961
+ configs:
1962
+ file:
1963
+ rootFolderPath: infra # x yerine
1964
+ service:
1965
+ folderPath: ./src
1966
+ paths:
1967
+ dist: dist
1968
+ ```
1969
+
1970
+ ```bash
1971
+ xcore sync-toolchain # tsconfig include / outDir / @/* ← tmp.yml
1972
+ xcore doctor # drift var mı
1973
+ ```
1974
+
1975
+ | Dosya | Klasör adı var mı? | Rol |
1976
+ |-------|-------------------|-----|
1977
+ | `tmp.yml` | **Evet — tek kaynak** | `service.paths.root`, `service.paths.source`, `service.paths.*` |
1978
+ | `tsconfig.base.json` | Hayır | `strict`, `module`, `target` (npm export) |
1979
+ | `tsconfig.json` | Sync ile | `include`, `outDir`, `paths` — elle yazma |
1980
+ | `eslint.config.js` | tmp'den okur | `createEslintConfigFromProject(cwd)` |
1981
+
1982
+ **Servis eslint.config.js:**
1983
+
1984
+ ```js
1985
+ import tseslint from 'typescript-eslint'
1986
+ import { createEslintConfigFromProject } from '@xrystal/core/x/bin/helpers/toolchain-config.mjs'
1987
+
1988
+ export default createEslintConfigFromProject(process.cwd(), tseslint)
1989
+ ```
1990
+
1991
+ ---
1992
+
1993
+ ### Servislerde `sync-toolchain` (manuel)
1994
+
1995
+ **Evet — servislerde de öneriyoruz.** Otomatik değil; **sen çalıştırırsın**, sadece **klasör/layout** değişince.
1996
+
1997
+ | tmp.yml değişikliği | `sync-toolchain` gerekir mi? |
1998
+ |---------------------|------------------------------|
1999
+ | `service.paths.root` (`x` → `infra`) | **Evet** |
2000
+ | `service.paths.source` (`./source` → `./src`) | **Evet** |
2001
+ | `service.paths.dist` / `service.paths.tests` | **Evet** |
2002
+ | `loaders`, `logLevel`, `protocols` | **Hayır** — runtime watch yeterli |
2003
+
2004
+ **Ne yapar:** `tmp.yml` layout → `tsconfig.json` (`include`, `outDir`, `@/*`, `extends: @xrystal/core/tsconfig.base.json`).
2005
+ **Ne yapmaz:** eslint dosyasını yazmaz — eslint her `lint`/`dev` öncesi tmp'yi okur. `bunfig.toml` satırını **çıktıda gösterir**, sen eklersin.
2006
+
2007
+ **Servis akışı:**
2008
+
2009
+ ```bash
2010
+ # 1) Yeni servis veya template clone sonrası — tmp.yml layout'u düzenle
2011
+ # 2) Bir kez sync
2012
+ bun run sync-toolchain
2013
+ # 3) Kontrol
2014
+ bun run doctor
2015
+ # 4) bunfig.toml — sync'in yazdığı alias satırını ekle
2016
+ ```
2017
+
2018
+ **package.json script (servislere ekle):**
2019
+
2020
+ ```json
2021
+ "sync-toolchain": "xcore sync-toolchain",
2022
+ "lint": "eslint ."
2023
+ ```
2024
+
2025
+ **Dry-run:** `xcore sync-toolchain --dry-run` — yazmadan ne üreteceğini gösterir.
2026
+
2027
+ Runtime (`xcore dev` çalışırken) loader ayarları tmp watch ile güncellenir; **sync-toolchain buna karışmaz** — bilinçli ayrım.
2028
+
2029
+ ---
2030
+
2031
+ ### `x/` folder layout / `x/` klasörü (configured via tmp.yml)
2032
+
2033
+ **EN:** The `@xrystal/core` npm package ships seed `x/tmp.yml` (default `configs.file.rootFolderPath: x`). **Services** read layout from their own `tmp.yml` → `configs`; folder names are configurable.
2034
+
2035
+ **TR:** `@xrystal/core` paketi seed `x/tmp.yml` taşır (default `configs.file.rootFolderPath: x`). **Servisler** kendi `tmp.yml` → `configs` ayarlarından layout okur; klasör adları değiştirilebilir.
1540
2036
 
1541
2037
  ```yaml
1542
2038
  # configs = proje ayarları (servis tek kaynak)
1543
2039
  configs:
1544
- rootFolderPath: x # serviste infra, config, … olabilir
1545
- mainFolderPath: ./source
1546
- paths:
1547
- tests: tests
1548
- environments: environments
1549
- dist: dist
2040
+ file:
2041
+ rootFolderPath: x # serviste infra, config, … olabilir
2042
+
2043
+ service:
2044
+ name: my-api
2045
+ folderPath: ./source
2046
+ paths:
2047
+ tests: tests
2048
+ environments: environments
2049
+ dist: dist
2050
+ build:
2051
+ typecheck: true
1550
2052
  ```
1551
2053
 
1552
- Seed / ensure kaynağı: `node_modules/@xrystal/core/x/tmp.yml` (ayrı template yok).
2054
+ Seed / ensure source: `node_modules/@xrystal/core/x/tmp.yml` (no separate template file / ayrı template yok).
2055
+
2056
+ | `configs` field / alan | EN | TR |
2057
+ |------------------------|----|----|
2058
+ | `service.paths.root` | CLI root folder (`xcore test`/`dev`/`build`) | CLI kök klasörü (`xcore test`/`dev`/`build`) |
2059
+ | `core.tmp.fileWatchIntervalMs` | `tmp.yml` watch interval (ms, default `500`) | `tmp.yml` izleme aralığı (ms, default `500`) |
2060
+ | `service.paths.source` | Source tree + `xcore dev` entry | Kaynak klasörü + `xcore dev` girişi |
2061
+ | `service.paths.*` | `tests` / `environments` / `dist` subpaths | `tests` / `environments` / `dist` alt yolları |
2062
+ | `service.loaders`, `service.framework` | Runtime (System, dto, logger, …) | Runtime (System, dto, logger, …) |
2063
+ | `service.build.*` | Build override (`typecheck`, …) — tsconfig is primary | Build override — tsconfig birincil |
1553
2064
 
1554
- | `configs` alanı | Ne yapar |
1555
- |-----------------|----------|
1556
- | `rootFolderPath` | Ana klasör adı (`xcore test/dev/build` kökü) |
1557
- | `paths.*` | tests / environments / dist alt yolları |
1558
- | `mainFolderPath` | Boot entry (`xcore dev`) |
1559
- | `loaders`, `framework` | Runtime (System, dto, logger, …) |
2065
+ **EN:** In services, `tmp.yml` is found recursively; in the core repo only `x/tmp.yml` is allowed.
1560
2066
 
1561
- Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` kabul edilir.
2067
+ **TR:** Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` kabul edilir.
1562
2068
 
1563
2069
  ```
1564
2070
  {rootFolderPath}/
@@ -1570,10 +2076,12 @@ Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` ka
1570
2076
 
1571
2077
  | Repo | `{rootFolderPath}/tests` |
1572
2078
  |------|--------------------------|
1573
- | **@xrystal/core** | Lib unit/integration testleri |
1574
- | **Servis** | Servis testleri |
2079
+ | **@xrystal/core** | EN: lib unit/integration tests · TR: lib unit/integration testleri |
2080
+ | **Service / Servis** | EN: service tests · TR: servis testleri |
2081
+
2082
+ **EN:** `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
1575
2083
 
1576
- `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
2084
+ **TR:** `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
1577
2085
 
1578
2086
  ---
1579
2087
 
@@ -1775,16 +2283,23 @@ Detay: [Three stores → G](#g--global-store-zustand)
1775
2283
 
1776
2284
  ---
1777
2285
 
1778
- ## Tests
2286
+ ## Tests / Testler
1779
2287
 
1780
2288
  ```bash
1781
- bun test x/tests # 103 test — layout guard, CLI, realtime, i18n, …
1782
- bun run lint # source/ import kuralları (@/ alias)
1783
- bun run build # bundle + tsc
1784
- bun run build:prod # publish öncesi: .ts → .js source/ içine
2289
+ bun run release:prepare # lint + test + build — same as tag pre-check / tag öncesi kontrol
2290
+ bun test x/tests # 103 tests — CLI, realtime, i18n, tmp guard, …
2291
+ bun run lint # @/ alias rules on source/*.ts
2292
+ bun run build # tsc → x/dist (+ fix-dist-imports; minify if tmp build.minify)
1785
2293
  ```
1786
2294
 
1787
- Lightweight unit tests (no full awilix boot). `express` is a **devDependency** only for test/runtime wiring — not shipped to apps.
2295
+ **EN:** Lightweight unit/integration tests (no full Awilix boot in most suites). Path alias `@/*` → `./source/*` via `bunfig.toml`.
2296
+ **TR:** Hafif unit/integration testleri (çoğu suite’te tam Awilix boot yok). `@/*` alias `bunfig.toml` ile çözülür.
2297
+
2298
+ **EN:** Publish CI: `lint` → `build` → `test` → `prepare-npm-publish` (drops `source/`) → **`verify-npm-pack`** (fails if any `source/` in tarball) → `npm publish`. One-time step also unpublishes leaked `3.37.0–3.37.2` (remove next commit).
2299
+
2300
+ **TR:** Publish CI: `lint` → `build` → `test` → `prepare-npm-publish` (`source/` silinir) → **`verify-npm-pack`** (tarball’da `source/` varsa fail) → `npm publish`. Tek seferlik adım sızan `3.37.0–3.37.2` sürümlerini kaldırır (sonraki commit’te sil).
2301
+
2302
+ `express` is a **devDependency** only — not shipped to apps / uygulamalara gitmez.
1788
2303
 
1789
2304
  ---
1790
2305