@xrystal/core 3.32.1 → 3.37.4

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 (264) hide show
  1. package/README.md +676 -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 +142 -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 +39 -0
  29. package/x/bin/scripts/publish-guard.mjs +113 -0
  30. package/x/bin/scripts/verify-npm-pack.mjs +12 -0
  31. package/x/bin/scripts/verify-publish-config.mjs +10 -0
  32. package/x/bin/scripts/verify-version-bump.mjs +27 -0
  33. package/x/bin/scripts/version-check.mjs +173 -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.d.ts +12 -0
  51. package/x/dist/project/index.js +1 -0
  52. package/x/dist/utils/constants/defaults.json +44 -0
  53. package/x/dist/utils/constants/index.js +1 -0
  54. package/x/dist/utils/helpers/configs/index.js +1 -0
  55. package/x/dist/utils/helpers/context/controller-store.js +1 -0
  56. package/x/dist/utils/helpers/context/index.js +1 -0
  57. package/{source → x/dist}/utils/helpers/core/index.d.ts +1 -1
  58. package/x/dist/utils/helpers/core/index.js +1 -0
  59. package/x/dist/utils/helpers/core/paths.js +1 -0
  60. package/x/dist/utils/helpers/core/tmp-layout.js +1 -0
  61. package/x/dist/utils/helpers/date/index.js +1 -0
  62. package/x/dist/utils/helpers/dispatch/index.js +1 -0
  63. package/x/dist/utils/helpers/dto/index.js +1 -0
  64. package/x/dist/utils/helpers/filters/index.js +1 -0
  65. package/x/dist/utils/helpers/framework/index.js +1 -0
  66. package/x/dist/utils/helpers/handlers/adapters.js +1 -0
  67. package/x/dist/utils/helpers/handlers/execute.js +1 -0
  68. package/x/dist/utils/helpers/handlers/index.js +1 -0
  69. package/x/dist/utils/helpers/hash/crypto.js +1 -0
  70. package/x/dist/utils/helpers/id/index.js +1 -0
  71. package/x/dist/utils/helpers/index.js +1 -0
  72. package/x/dist/utils/helpers/ip/index.js +1 -0
  73. package/x/dist/utils/helpers/is/index.js +1 -0
  74. package/x/dist/utils/helpers/locales/index.js +1 -0
  75. package/x/dist/utils/helpers/math/index.js +1 -0
  76. package/{source → x/dist}/utils/helpers/middleware/index.d.ts +2 -2
  77. package/x/dist/utils/helpers/middleware/index.js +1 -0
  78. package/x/dist/utils/helpers/objects/index.js +1 -0
  79. package/x/dist/utils/helpers/path/index.js +1 -0
  80. package/{source → x/dist}/utils/helpers/protocol/index.d.ts +2 -10
  81. package/x/dist/utils/helpers/protocol/index.js +1 -0
  82. package/x/dist/utils/helpers/protocol/options.js +1 -0
  83. package/x/dist/utils/helpers/regex/checkSpecialRegexControl.js +1 -0
  84. package/x/dist/utils/helpers/runtime/dto-access.js +1 -0
  85. package/x/dist/utils/helpers/runtime/dto-types.js +1 -0
  86. package/{source → x/dist}/utils/helpers/runtime/index.d.ts +1 -0
  87. package/x/dist/utils/helpers/runtime/index.js +1 -0
  88. package/x/dist/utils/helpers/runtime/shutdown.d.ts +3 -0
  89. package/x/dist/utils/helpers/runtime/shutdown.js +1 -0
  90. package/x/dist/utils/helpers/state/index.js +1 -0
  91. package/x/dist/utils/helpers/state/props-from-tmp.js +1 -0
  92. package/x/dist/utils/helpers/state/request-key-guard.js +1 -0
  93. package/x/dist/utils/helpers/state/scopes.js +1 -0
  94. package/x/dist/utils/helpers/string/index.js +1 -0
  95. package/x/dist/utils/helpers/tests/tmp-schema.test.js +1 -0
  96. package/x/dist/utils/helpers/tests/tmp-watch.test.d.ts +1 -0
  97. package/x/dist/utils/helpers/tests/tmp-watch.test.js +1 -0
  98. package/x/dist/utils/helpers/timer/index.js +1 -0
  99. package/x/dist/utils/helpers/tmp/index.d.ts +5 -0
  100. package/x/dist/utils/helpers/tmp/index.js +1 -0
  101. package/x/dist/utils/helpers/tmp/loader-tmp-sync.js +1 -0
  102. package/{source → x/dist}/utils/helpers/tmp/runtime-tmp.d.ts +2 -6
  103. package/x/dist/utils/helpers/tmp/runtime-tmp.js +1 -0
  104. package/{source → x/dist}/utils/helpers/tmp/tmp-loader.d.ts +1 -0
  105. package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -0
  106. package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +47 -0
  107. package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -0
  108. package/x/dist/utils/helpers/tmp/tmp-watch.d.ts +1 -0
  109. package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -0
  110. package/x/dist/utils/helpers/validates/index.js +1 -0
  111. package/x/dist/utils/index.js +1 -0
  112. package/x/dist/utils/models/classes/class.clients.js +1 -0
  113. package/x/dist/utils/models/classes/class.interfaces.js +1 -0
  114. package/x/dist/utils/models/classes/class.service-locator.js +1 -0
  115. package/{source → x/dist}/utils/models/classes/class.tmp-file-loader.d.ts +3 -2
  116. package/x/dist/utils/models/classes/class.tmp-file-loader.js +1 -0
  117. package/x/dist/utils/models/classes/class.x.js +1 -0
  118. package/x/dist/utils/models/enums/index.js +1 -0
  119. package/x/dist/utils/models/index.js +1 -0
  120. package/x/dist/utils/models/types/index.js +1 -0
  121. package/x/dist/utils/package-root.js +1 -0
  122. package/x/tmp.yml +51 -42
  123. package/source/index.js +0 -11
  124. package/source/loader/clients/index.js +0 -22
  125. package/source/loader/configs/index.js +0 -88
  126. package/source/loader/controller/index.js +0 -236
  127. package/source/loader/dto/index.js +0 -92
  128. package/source/loader/events/index.js +0 -44
  129. package/source/loader/index.d.ts +0 -11
  130. package/source/loader/index.js +0 -11
  131. package/source/loader/kafka/index.js +0 -137
  132. package/source/loader/localizations/index.js +0 -46
  133. package/source/loader/logger/index.js +0 -217
  134. package/source/loader/service/index.js +0 -7
  135. package/source/loader/system/index.js +0 -25
  136. package/source/project/index.d.ts +0 -8
  137. package/source/project/index.js +0 -70
  138. package/source/utils/constants/defaults.json +0 -15
  139. package/source/utils/constants/defaults.mjs +0 -10
  140. package/source/utils/constants/index.js +0 -22
  141. package/source/utils/helpers/configs/index.js +0 -1
  142. package/source/utils/helpers/context/controller-store.js +0 -12
  143. package/source/utils/helpers/context/index.js +0 -24
  144. package/source/utils/helpers/core/index.js +0 -58
  145. package/source/utils/helpers/core/paths.js +0 -78
  146. package/source/utils/helpers/core/tmp-layout.js +0 -241
  147. package/source/utils/helpers/date/index.js +0 -48
  148. package/source/utils/helpers/dispatch/index.js +0 -53
  149. package/source/utils/helpers/dto/index.js +0 -10
  150. package/source/utils/helpers/filters/index.js +0 -44
  151. package/source/utils/helpers/framework/index.js +0 -17
  152. package/source/utils/helpers/handlers/adapters.js +0 -40
  153. package/source/utils/helpers/handlers/execute.js +0 -82
  154. package/source/utils/helpers/handlers/index.js +0 -31
  155. package/source/utils/helpers/hash/crypto.js +0 -22
  156. package/source/utils/helpers/id/index.js +0 -24
  157. package/source/utils/helpers/index.js +0 -26
  158. package/source/utils/helpers/ip/index.js +0 -21
  159. package/source/utils/helpers/is/index.js +0 -35
  160. package/source/utils/helpers/locales/index.js +0 -82
  161. package/source/utils/helpers/math/index.js +0 -14
  162. package/source/utils/helpers/middleware/index.js +0 -36
  163. package/source/utils/helpers/objects/index.js +0 -55
  164. package/source/utils/helpers/path/index.js +0 -4
  165. package/source/utils/helpers/protocol/index.js +0 -99
  166. package/source/utils/helpers/protocol/options.js +0 -13
  167. package/source/utils/helpers/regex/checkSpecialRegexControl.js +0 -3
  168. package/source/utils/helpers/runtime/dto-access.js +0 -5
  169. package/source/utils/helpers/runtime/index.js +0 -1
  170. package/source/utils/helpers/state/index.js +0 -185
  171. package/source/utils/helpers/state/props-from-tmp.js +0 -44
  172. package/source/utils/helpers/state/request-key-guard.js +0 -42
  173. package/source/utils/helpers/state/scopes.js +0 -69
  174. package/source/utils/helpers/string/index.js +0 -9
  175. package/source/utils/helpers/timer/index.js +0 -5
  176. package/source/utils/helpers/tmp/index.d.ts +0 -3
  177. package/source/utils/helpers/tmp/index.js +0 -3
  178. package/source/utils/helpers/tmp/loader-tmp-sync.js +0 -13
  179. package/source/utils/helpers/tmp/runtime-tmp.js +0 -30
  180. package/source/utils/helpers/tmp/tmp-loader.js +0 -48
  181. package/source/utils/helpers/validates/index.js +0 -20
  182. package/source/utils/index.js +0 -3
  183. package/source/utils/models/classes/class.clients.js +0 -142
  184. package/source/utils/models/classes/class.interfaces.js +0 -10
  185. package/source/utils/models/classes/class.service-locator.js +0 -16
  186. package/source/utils/models/classes/class.tmp-file-loader.js +0 -38
  187. package/source/utils/models/classes/class.x.js +0 -180
  188. package/source/utils/models/enums/index.js +0 -148
  189. package/source/utils/models/index.js +0 -9
  190. package/source/utils/models/types/index.js +0 -2
  191. package/source/utils/models/types/shims.d.ts +0 -123
  192. package/source/utils/package-root.js +0 -5
  193. package/x/tests/cli.test.ts +0 -85
  194. package/x/tests/context.test.ts +0 -25
  195. package/x/tests/dispatch.test.ts +0 -84
  196. package/x/tests/fixtures/locales/en/translation.json +0 -8
  197. package/x/tests/fixtures/locales/tr/translation.json +0 -8
  198. package/x/tests/frameworks.integration.test.ts +0 -185
  199. package/x/tests/helpers/i18n-setup.ts +0 -52
  200. package/x/tests/helpers/middleware.ts +0 -23
  201. package/x/tests/helpers/register-test-dto.ts +0 -52
  202. package/x/tests/i18n.integration.test.ts +0 -77
  203. package/x/tests/i18n.test.ts +0 -96
  204. package/x/tests/middleware.test.ts +0 -83
  205. package/x/tests/project-layout.test.ts +0 -65
  206. package/x/tests/protocol.test.ts +0 -75
  207. package/x/tests/realtime.examples.test.ts +0 -198
  208. package/x/tests/runtime-tmp.test.ts +0 -49
  209. package/x/tests/socket.integration.test.ts +0 -174
  210. package/x/tests/state.test.ts +0 -183
  211. package/x/tests/tmp-layout-guard.test.ts +0 -40
  212. /package/{source → x/dist}/index.d.ts +0 -0
  213. /package/{source → x/dist}/loader/clients/index.d.ts +0 -0
  214. /package/{source → x/dist}/loader/configs/index.d.ts +0 -0
  215. /package/{source → x/dist}/loader/dto/index.d.ts +0 -0
  216. /package/{source → x/dist}/loader/events/index.d.ts +0 -0
  217. /package/{source → x/dist}/loader/localizations/index.d.ts +0 -0
  218. /package/{source → x/dist}/loader/service/index.d.ts +0 -0
  219. /package/{source → x/dist}/loader/system/index.d.ts +0 -0
  220. /package/{source → x/dist}/utils/constants/index.d.ts +0 -0
  221. /package/{source → x/dist}/utils/helpers/configs/index.d.ts +0 -0
  222. /package/{source → x/dist}/utils/helpers/context/controller-store.d.ts +0 -0
  223. /package/{source → x/dist}/utils/helpers/context/index.d.ts +0 -0
  224. /package/{source → x/dist}/utils/helpers/core/paths.d.ts +0 -0
  225. /package/{source → x/dist}/utils/helpers/core/tmp-layout.d.ts +0 -0
  226. /package/{source → x/dist}/utils/helpers/date/index.d.ts +0 -0
  227. /package/{source → x/dist}/utils/helpers/dispatch/index.d.ts +0 -0
  228. /package/{source → x/dist}/utils/helpers/dto/index.d.ts +0 -0
  229. /package/{source → x/dist}/utils/helpers/filters/index.d.ts +0 -0
  230. /package/{source → x/dist}/utils/helpers/framework/index.d.ts +0 -0
  231. /package/{source → x/dist}/utils/helpers/handlers/adapters.d.ts +0 -0
  232. /package/{source → x/dist}/utils/helpers/handlers/execute.d.ts +0 -0
  233. /package/{source → x/dist}/utils/helpers/handlers/index.d.ts +0 -0
  234. /package/{source → x/dist}/utils/helpers/hash/crypto.d.ts +0 -0
  235. /package/{source → x/dist}/utils/helpers/id/index.d.ts +0 -0
  236. /package/{source → x/dist}/utils/helpers/index.d.ts +0 -0
  237. /package/{source → x/dist}/utils/helpers/ip/index.d.ts +0 -0
  238. /package/{source → x/dist}/utils/helpers/is/index.d.ts +0 -0
  239. /package/{source → x/dist}/utils/helpers/locales/index.d.ts +0 -0
  240. /package/{source → x/dist}/utils/helpers/math/index.d.ts +0 -0
  241. /package/{source → x/dist}/utils/helpers/objects/index.d.ts +0 -0
  242. /package/{source → x/dist}/utils/helpers/path/index.d.ts +0 -0
  243. /package/{source → x/dist}/utils/helpers/protocol/options.d.ts +0 -0
  244. /package/{source → x/dist}/utils/helpers/regex/checkSpecialRegexControl.d.ts +0 -0
  245. /package/{source → x/dist}/utils/helpers/runtime/dto-access.d.ts +0 -0
  246. /package/{source → x/dist}/utils/helpers/runtime/dto-types.d.ts +0 -0
  247. /package/{source → x/dist}/utils/helpers/state/index.d.ts +0 -0
  248. /package/{source → x/dist}/utils/helpers/state/props-from-tmp.d.ts +0 -0
  249. /package/{source → x/dist}/utils/helpers/state/request-key-guard.d.ts +0 -0
  250. /package/{source → x/dist}/utils/helpers/state/scopes.d.ts +0 -0
  251. /package/{source → x/dist}/utils/helpers/string/index.d.ts +0 -0
  252. /package/{source/utils/helpers/runtime/dto-types.js → x/dist/utils/helpers/tests/tmp-schema.test.d.ts} +0 -0
  253. /package/{source → x/dist}/utils/helpers/timer/index.d.ts +0 -0
  254. /package/{source → x/dist}/utils/helpers/tmp/loader-tmp-sync.d.ts +0 -0
  255. /package/{source → x/dist}/utils/helpers/validates/index.d.ts +0 -0
  256. /package/{source → x/dist}/utils/index.d.ts +0 -0
  257. /package/{source → x/dist}/utils/models/classes/class.clients.d.ts +0 -0
  258. /package/{source → x/dist}/utils/models/classes/class.interfaces.d.ts +0 -0
  259. /package/{source → x/dist}/utils/models/classes/class.service-locator.d.ts +0 -0
  260. /package/{source → x/dist}/utils/models/classes/class.x.d.ts +0 -0
  261. /package/{source → x/dist}/utils/models/enums/index.d.ts +0 -0
  262. /package/{source → x/dist}/utils/models/index.d.ts +0 -0
  263. /package/{source → x/dist}/utils/models/types/index.d.ts +0 -0
  264. /package/{source → x/dist}/utils/package-root.d.ts +0 -0
package/README.md CHANGED
@@ -1,16 +1,138 @@
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
+ ## npm publish / npm yayın
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** | **TR** |
13
+ |---|--------|--------|
14
+ | **Ships** | `x/dist` (minified `.js` + `.d.ts`), `x/bin`, `x/tmp.yml`, `x/assets` | Aynı — yalnızca bunlar |
15
+ | **Never** | `source/` `.ts` in npm | npm'e `source/` `.ts` **asla** gitmez |
16
+ | **Runtime** | `main` / `exports` → `x/dist/` | `main` / `exports` → `x/dist/` |
12
17
 
13
- ### Katmanlar
18
+ **EN — 3 publish checks (all must pass):**
19
+ 1. `package.json` `files` — no `source/`, `main`/`exports` → `x/dist`
20
+ 2. `npm pack --dry-run` — no `source/` paths
21
+ 3. CI: `prepare-npm-publish` → `verify-npm-pack` (strict: disk + minify)
22
+
23
+ **TR — 3 publish kontrolü (hepsi geçmeli):**
24
+ 1. `package.json` `files` — `source/` yok, `main`/`exports` → `x/dist`
25
+ 2. `npm pack --dry-run` — `source/` yok
26
+ 3. CI: `prepare-npm-publish` → `verify-npm-pack` (strict: disk + minify)
27
+
28
+ ```bash
29
+ bun run release:prepare # lint → build → test
30
+ node x/bin/scripts/verify-publish-config.mjs # local prepublish gate
31
+ ```
32
+
33
+ ---
34
+
35
+ ## `tmp.yml` layout / tmp.yml düzeni
36
+
37
+ **EN — structure:** `service` (app identity, paths, runtime, build) + `core` (library mechanisms like tmp watch).
38
+
39
+ **TR — yapı:** `service` (uygulama kimliği, yollar, runtime, build) + `core` (tmp izleme gibi kütüphane mekanizmaları).
40
+
41
+ ```yaml
42
+ project:
43
+ name: x
44
+
45
+ configs:
46
+ service:
47
+ name: my-api
48
+ framework: elysia
49
+ protocols: [http, ws]
50
+
51
+ paths:
52
+ root: x # EN: CLI root (test/dev/build) · TR: test/dev/build kökü
53
+ source: ./source # EN: source tree + dev entry · TR: kaynak + dev girişi
54
+ special:
55
+ tests: tests
56
+ environments: environments
57
+ dist: dist
58
+
59
+ loaders:
60
+ dto: { withDefaultHeaders: true }
61
+ loggers: { logLevel: info }
62
+ controller: {}
63
+
64
+ build:
65
+ typecheck: true # EN: build override · TR: build override
66
+ minify: true # EN: @xrystal/core — minify x/dist JS · TR: x/dist JS küçültme
67
+
68
+ core:
69
+ tmp:
70
+ fileWatchIntervalMs: 500
71
+
72
+ end:
73
+ version: 1
74
+ ```
75
+
76
+ | Block / Blok | Keys / Alanlar | Role / Rol |
77
+ |--------------|----------------|------------|
78
+ | `configs.service` | `name`, `framework`, `paths`, `protocols`, `loaders`, `build` | bu uygulama / servis |
79
+ | `configs.service.paths` | `root`, `source`, `special.*` | **EN:** layout + CLI (`dev`/`build`/`test`) · **TR:** layout + CLI (`dev`/`build`/`test`) |
80
+ | `configs.core.tmp` | `fileWatchIntervalMs` | tmp.yml dosya izleme (ms) |
81
+
82
+ **EN:** Save `tmp.yml` → no restart; loaders reload automatically.
83
+ **TR:** Kaydet → restart gerekmez; loader’lar otomatik yenilenir.
84
+
85
+ ---
86
+
87
+ ## How it works / Sistem nasıl çalışır
88
+
89
+ ### EN — overview
90
+
91
+ In one sentence: **`tmp.yml` is the project key** — `@xrystal/core` reads it, boots loaders, and sends responses via `@xrystal/dto`.
92
+
93
+ | Layer | Module | Role |
94
+ |--------|--------|------|
95
+ | Defaults | `defaults.json` | `x`, `./source`, `tests`, template URI |
96
+ | Constants | `Constants` | Shared TS + CLI values |
97
+ | Layout | `tmp-layout.ts` | tmp path resolution — **CLI only** |
98
+ | Live config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
99
+ | Runtime | `getTmpSnapshot()` | Parse + watch + live reload |
100
+
101
+ **Core repo:** `tmp.yml` must live at `x/tmp.yml` only (`ensureCoreTmpEntry`).
102
+ **Service:** tmp under `configs.service.paths.root`; runtime uses `getTmpSnapshot()` — no layout module needed.
103
+
104
+ **Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loaders `syncFromTmp()`.
105
+
106
+ See [npm publish / npm yayın](#npm-publish--npm-yayın) for what ships to npm.
107
+
108
+ ---
109
+
110
+ ### TR — genel bakış
111
+
112
+ Tek cümle: **`tmp.yml` projenin anahtarı** — `@xrystal/core` onu okuyup loader’ları ayağa kaldırır; cevaplar `@xrystal/dto` ile gider.
113
+
114
+ | Katman | Modül | Rol |
115
+ |--------|--------|-----|
116
+ | Varsayılanlar | `defaults.json` | `x`, `./source`, `tests`, template URI |
117
+ | Sabitler | `Constants` | TS + CLI ortak değerler |
118
+ | Layout | `tmp-layout.ts` | tmp yolu — **sadece CLI** |
119
+ | Canlı config | `{rootFolderPath}/tmp.yml` | framework, loaders, protocols |
120
+ | Runtime | `getTmpSnapshot()` | Parse + watch + canlı güncelleme |
121
+
122
+ **Core repo:** `tmp.yml` yalnızca `x/tmp.yml` (`ensureCoreTmpEntry`).
123
+ **Servis:** tmp `configs.service.paths.root` altında; runtime’da `getTmpSnapshot()` yeterli — layout modülü gerekmez.
124
+
125
+ **Boot:** `ensureCoreTmpEntry()` → `getTmpSnapshot()` → `coreLoader()` → loader’lar `syncFromTmp()`.
126
+
127
+ npm için → [npm publish / npm yayın](#npm-publish--npm-yayın).
128
+
129
+ ---
130
+
131
+ ## How it works — detail / Sistem nasıl çalışır — detay
132
+
133
+ **EN:** Deep-dive below (mermaid + tables). Turkish prose in this section; key labels are bilingual where it matters.
134
+
135
+ **TR:** Aşağıda detay (mermaid + tablolar). Türkçe anlatım; kritik etiketler iki dilli.
14
136
 
15
137
  ```mermaid
16
138
  flowchart TB
@@ -23,7 +145,7 @@ flowchart TB
23
145
  end
24
146
 
25
147
  subgraph boot["Boot"]
26
- ENTRY["source/index.ts veya servis boot.ts"]
148
+ ENTRY["dev: source/index.ts · prod: x/dist/index.js"]
27
149
  GUARD["ensureCoreTmpEntry\n(sadece @xrystal/core)"]
28
150
  SNAP["getTmpSnapshot()"]
29
151
  LOADER["coreLoader() → Awilix DI"]
@@ -56,38 +178,87 @@ flowchart TB
56
178
 
57
179
  | | **@xrystal/core repo** | **Microservice** |
58
180
  |---|------------------------|------------------|
59
- | `tmp.yml` konumu | **Zorunlu** `x/tmp.yml` — başka yerde kopya varsa hata | `configs.rootFolderPath` altında (ör. `x/`, `infra/`) |
181
+ | `tmp.yml` konumu | **Zorunlu** `x/tmp.yml` — başka yerde kopya varsa hata | `configs.service.paths.root` altında (ör. `x/`, `infra/`) |
60
182
  | Koruma | `ensureCoreTmpEntry()` — stray tmp engeli | Yok; `tmp.yml` recursive bulunur |
61
183
  | Boot | `ensureCoreTmpEntry` → `getTmpSnapshot` → `coreLoader` | `coreLoader({})` + kendi HTTP sunucun |
62
184
  | Layout runtime’da | Gerekmez — değerler tmp snapshot’tan | Gerekmez — aynı |
63
185
 
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.
186
+ Servis runtime’ında `tmp-layout` çalıştırmana gerek yok: `getTmpSnapshot()` / `getRuntimeTmpConfigs()` yeterli.
187
+
188
+ **EN:** Layout module is for CLI only (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
189
+
190
+ **TR:** Layout modülü yalnızca CLI içindir (`xcore dev`, `xcore tmp`, `xcore test`, `xcore build`).
65
191
 
66
192
  ### Proje layout’u (`x/`)
67
193
 
68
194
  ```
69
- {proje-kökü}/
195
+ {project-root}/ # EN: repo root · TR: proje kökü
70
196
  ├── package.json
71
- └── {rootFolderPath}/ # default: x
72
- ├── tmp.yml # ana giriş — loaders, framework, protocols
197
+ └── {rootFolderPath}/ # default: x — EN: CLI root (test/dev/build) · TR: CLI kökü
198
+ ├── tmp.yml # EN: main config entry · TR: ana giriş
73
199
  ├── tests/
74
- ├── environments/ # .env dosyaları (xcore dev)
75
- └── dist/ # build çıktısı
200
+ ├── environments/ # EN: .env files (xcore dev) · TR: .env (xcore dev)
201
+ └── dist/ # EN: build output (.js) · TR: build çıktısı (.js)
76
202
  ```
77
203
 
78
- Kaynak kodu `mainFolderPath` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
204
+ Kaynak kodu `service.paths.source` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
79
205
 
80
206
  ```yaml
81
207
  configs:
82
- rootFolderPath: x
83
- mainFolderPath: ./source # veya ./src
84
- paths:
85
- tests: tests
86
- environments: environments
87
- dist: dist
208
+ file:
209
+ rootFolderPath: x
210
+ configFileWatchIntervalMs: 500
211
+
212
+ service:
213
+ name: my-api
214
+ framework: elysia
215
+ folderPath: ./source # veya ./src
216
+ protocols: [http]
217
+ paths:
218
+ tests: tests
219
+ environments: environments
220
+ dist: dist
221
+ build:
222
+ typecheck: true # tmp override — outDir/include tsconfig.json'dan
223
+ loaders:
224
+ dto: { withDefaultHeaders: true }
225
+ controller: {}
226
+ ```
227
+
228
+ **Build ayarları — öncelik sırası**
229
+
230
+ | Ayar | 1. tmp.yml `build.*` | 2. `tsconfig.json` | 3. fallback |
231
+ |------|----------------------|--------------------|-------------|
232
+ | Çıktı klasörü (`outDir`) | `build.outDir` | `compilerOptions.outDir` | `paths.dist` + `rootFolderPath` |
233
+ | Giriş dosyaları (glob) | `build.entries` / `build.glob` | `include` / `rootDir` | `service.paths.source` |
234
+ | Sourcemap | `build.sourcemap` | `sourceMap` / `inlineSourceMap` | kapalı |
235
+ | `.d.ts` | `build.declarations` | `declaration` / full `tsc` | kapalı |
236
+ | Minify (core) | `build.minify` | — | kapalı |
237
+ | Tip kontrolü | `build.typecheck` | — | `false` |
238
+
239
+ Servis örnek `tsconfig.json`:
240
+
241
+ ```json
242
+ {
243
+ "include": ["source"],
244
+ "compilerOptions": {
245
+ "rootDir": "./source",
246
+ "outDir": "./x/dist",
247
+ "sourceMap": false,
248
+ "declaration": false,
249
+ "paths": { "@/*": ["source/*"] },
250
+ "strict": true
251
+ }
252
+ }
88
253
  ```
89
254
 
90
- `tmp.yml` yoksa: `xcore tmp` veya `xcore dev` → paketteki seed `@xrystal/core/x/tmp.yml` kopyalanır.
255
+ `x`, `dist`, kaynak klasörü — tek yerden `outDir` / `include` ile; tmp.yml'de tekrar yazmana gerek yok (override istemiyorsan).
256
+
257
+ `tmp.yml` yoksa:
258
+
259
+ **EN:** `xcore tmp` or `xcore dev` copies seed from `@xrystal/core/x/tmp.yml`.
260
+
261
+ **TR:** `xcore tmp` veya `xcore dev` → seed `@xrystal/core/x/tmp.yml` kopyalanır.
91
262
 
92
263
  ### Boot sırası (lib)
93
264
 
@@ -98,14 +269,14 @@ configs:
98
269
 
99
270
  `tmp.yml` kaydedilince restart gerekmez — `TmpFileLoader` watch → `System.applyTmp()` → tüm loader’lar yeniden sync.
100
271
 
101
- ### CLI vs runtime
272
+ ### CLI vs runtime / CLI ve runtime
102
273
 
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 |
274
+ | Tool / Araç | EN | TR |
275
+ |---------------|----|----|
276
+ | `xcore` / `xrystal` / `tmp` | Same binary — dev, test, build, doctor, tag, tmp ensure, create | Aynı binary — dev, test, build, doctor, tag, tmp ensure, create |
277
+ | `getTmpSnapshot()` | In-app config | Uygulama içi config |
278
+ | `dtoMiddleware()` + `ctr()` | HTTP handler pipeline | HTTP handler pipeline |
279
+ | `realtimeMiddleware()` + `runAction()` | WebSocket / Socket.IO | WebSocket / Socket.IO |
109
280
 
110
281
  ---
111
282
 
@@ -117,7 +288,7 @@ Tek repo, tek `tmp.yml`, tek boot — Elysia HTTP örneği:
117
288
  my-api/
118
289
  ├── x/
119
290
  │ ├── tmp.yml
120
- │ ├── tests/ # servis testleri (xcore test)
291
+ │ ├── tests/ # EN: service tests (xcore test) · TR: servis testleri (xcore test)
121
292
  │ └── environments/
122
293
  ├── src/
123
294
  │ ├── boot.ts
@@ -135,17 +306,22 @@ npm i @xrystal/core elysia
135
306
 
136
307
  ```yaml
137
308
  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: {}
309
+ file:
310
+ rootFolderPath: x
311
+
312
+ service:
313
+ name: my-api
314
+ framework: elysia
315
+ folderPath: ./src
316
+ protocols: [http]
317
+ loaders:
318
+ system:
319
+ gStore:
320
+ options: { bootstrap: true, autoCreateProps: false }
321
+ vars: { maintenance: false }
322
+ dto: { withDefaultHeaders: true }
323
+ loggers: { logLevel: info }
324
+ controller: {}
149
325
  ```
150
326
 
151
327
  **3) Controller**
@@ -195,18 +371,31 @@ Servis `package.json` örneği:
195
371
 
196
372
  ```json
197
373
  {
198
- "dependencies": { "@xrystal/core": "^3.30.3", "elysia": "^1.4.19" },
374
+ "dependencies": { "@xrystal/core": "^3.32.2", "elysia": "^1.4.19" },
199
375
  "scripts": {
200
376
  "dev": "xcore dev",
201
377
  "build": "xcore build",
378
+ "start:dist": "xcore start",
202
379
  "test": "xcore test",
380
+ "lint": "eslint .",
381
+ "sync-toolchain": "xcore sync-toolchain",
382
+ "doctor": "xcore doctor",
203
383
  "version:check": "xcore version",
204
- "release:tag": "xcore tag"
384
+ "release:tag": "xcore tag",
385
+ "hooks:install": "xcore hooks install"
205
386
  }
206
387
  }
207
388
  ```
208
389
 
209
- Detay: [CLI (`xcore` · `xrystal` · `tmp`)](#cli-xcore--xrystal--tmp)
390
+ **İlk kurulum / klasör adı değişince (manuel, bir kez):**
391
+
392
+ ```bash
393
+ bun run sync-toolchain # tmp.yml → tsconfig paths; eslint tmp'den okur
394
+ bun run doctor # drift kontrolü
395
+ # sync çıktısındaki satırı bunfig.toml [resolve.alias]'a ekle
396
+ ```
397
+
398
+ Detay: [Servislerde `sync-toolchain`](#servislerde-sync-toolchain-manuel)
210
399
 
211
400
  Public API:
212
401
 
@@ -226,22 +415,27 @@ import coreLoader from '@xrystal/core/project'
226
415
 
227
416
  ```yaml
228
417
  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: {}
418
+ file:
419
+ rootFolderPath: x
420
+ configFileWatchIntervalMs: 500
421
+
422
+ service:
423
+ name: my-api
424
+ framework: elysia # elysia | express | node | fetch
425
+ folderPath: ./src
426
+ protocols: [http, ws] # http, ws, socketio
427
+ loaders:
428
+ system:
429
+ gStore:
430
+ options:
431
+ bootstrap: true
432
+ autoCreateProps: false
433
+ vars:
434
+ maintenance: false
435
+ dto: { withDefaultHeaders: true }
436
+ localization: { fallbackLang: en, preloadLangs: [en, tr] }
437
+ loggers: { logLevel: debug }
438
+ controller: {}
245
439
  ```
246
440
 
247
441
  Save the file → **live reload**: `System.applyTmp()` → `G.configureFromTmp()` → every loader `syncFromTmp()`.
@@ -1115,7 +1309,7 @@ sequenceDiagram
1115
1309
  participant G as G store
1116
1310
  participant L as Loaders
1117
1311
 
1118
- YML->>TFL: watchFile (~500ms)
1312
+ YML->>TFL: watchFile (configs.core.tmp.fileWatchIntervalMs)
1119
1313
  TFL->>SYS: reload event
1120
1314
  SYS->>SYS: applyTmp(parsed)
1121
1315
  SYS->>RT: setRuntimeTmpConfigs
@@ -1393,17 +1587,23 @@ Mapping lives in `utils/helpers/middleware/` — `socketio` → `socketIo()`, `w
1393
1587
 
1394
1588
  ## CLI (`xcore` · `xrystal` · `tmp`)
1395
1589
 
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:
1590
+ **EN:** Installing `@xrystal/core` exposes **three bin names** for the same CLI (`x/bin/main-cli.js`) — same commands, same project-root resolution.
1591
+
1592
+ **TR:** `@xrystal/core` kurulunca **üç bin adı** aynı CLI’yı açar — aynı komutlar, aynı proje kökü çözümlemesi.
1593
+
1594
+ | Bin | EN | TR | Example |
1595
+ |-----|----|----|---------|
1596
+ | **`xcore`** | Primary name (recommended) | Ana isim (önerilen) | `xcore doctor`, `npx xcore dev` |
1597
+ | **`xrystal`** | Transition alias | Geçiş alias | `xrystal version` = `xcore version` |
1598
+ | **`tmp`** | Legacy alias | Eski alışkanlık alias | `tmp tag` = `xcore tag` |
1397
1599
 
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` |
1600
+ **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.
1403
1601
 
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`).
1602
+ **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.
1405
1603
 
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.
1604
+ **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**.
1605
+
1606
+ **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
1607
 
1408
1608
  ```bash
1409
1609
  cd api-gateway-svc/src
@@ -1413,7 +1613,9 @@ npx xrystal version # aynı
1413
1613
  npx tmp tag # aynı — servis tag + push
1414
1614
  ```
1415
1615
 
1416
- Servis `package.json` script’lerinde **herhangi bir alias** kullanılabilir; davranış değişmez:
1616
+ **EN:** Any bin alias in service `package.json` scripts — same behavior.
1617
+
1618
+ **TR:** Servis `package.json` script’lerinde herhangi bir alias kullanılabilir; davranış değişmez.
1417
1619
 
1418
1620
  ```json
1419
1621
  {
@@ -1427,32 +1629,49 @@ Servis `package.json` script’lerinde **herhangi bir alias** kullanılabilir; d
1427
1629
 
1428
1630
  ---
1429
1631
 
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"` |
1632
+ ### Three script layers / Üç script katmanı
1633
+
1634
+ | Layer / Katman | Defined in / Tanım | When / Ne zaman | Example / Örnek |
1635
+ |----------------|-------------------|-----------------|-----------------|
1636
+ | **CLI (shared)** | `@xrystal/core` bin (`xcore` / `xrystal` / `tmp`) | Same in all services / Tüm servislerde aynı | `xcore dev`, `tmp version`, `xrystal tag` |
1637
+ | **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"` |
1638
+ | **Lib (core repo)** | `@xrystal/core` own `package.json` | Core dev / publish only / Sadece core geliştirme | `"release:prepare"`, `"tag"` |
1639
+
1640
+ **EN — shared CLI commands** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = project root):
1641
+
1642
+ | Command | What it does |
1643
+ |---------|----------------|
1644
+ | `<bin> version` | CLI version + project `package.json` ↔ git HEAD |
1645
+ | `<bin> tag` | `v{version}` tag + push from **project** version |
1646
+ | `<bin> doctor` | Runtimes, git, installed `@xrystal/core` vs CLI |
1647
+ | `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
1648
+ | `<bin> dev` | Watch `{service.folderPath}/index.ts` + dev env |
1649
+ | `<bin> build` | Output → `{rootFolderPath}/{paths.dist}/` |
1650
+ | `<bin> start` | Run `{rootFolderPath}/{paths.dist}/index.js` + prod env |
1651
+ | `<bin> tmp` | Ensure `tmp.yml` from seed if missing |
1652
+ | `<bin> create [name] [path]` | GitHub template clone + `tmp.yml` ensure |
1437
1653
 
1438
- **CLI ortak komutlar** (lib’den gelir; bin adı fark etmez; cwd = proje kökü):
1654
+ **TR — ortak CLI komutlar** (`<bin>` = `xcore` | `xrystal` | `tmp`; cwd = proje kökü):
1439
1655
 
1440
1656
  | Komut | Ne yapar |
1441
1657
  |-------|----------|
1442
1658
  | `<bin> version` | CLI sürümü + **proje** `package.json` ↔ git HEAD |
1443
1659
  | `<bin> tag` | **Proje** versiyonundan `v{version}` tag + push |
1444
1660
  | `<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 |
1661
+ | `<bin> test` | `bun test ./{rootFolderPath}/{paths.tests}` |
1662
+ | `<bin> dev` | `{service.folderPath}/index.ts` watch + dev env |
1663
+ | `<bin> build` | Çıktı → `{rootFolderPath}/{paths.dist}/` |
1664
+ | `<bin> start` | `{rootFolderPath}/{paths.dist}/index.js` + prod env |
1665
+ | `<bin> tmp` | `tmp.yml` yoksa seed’den oluşturur |
1666
+ | `<bin> create [name] [path]` | GitHub template + `tmp.yml` ensure |
1667
+
1668
+ **EN:** If `tmp.yml` is missing, `xcore tmp` / `dev` / `test` / `build` copy seed from `@xrystal/core/x/tmp.yml` into `{rootFolderPath}/tmp.yml`.
1450
1669
 
1451
- `<bin>` = `xcore`, `xrystal` veya `tmp` (bin alias — aynı CLI).
1670
+ **TR:** `tmp.yml` silinmişse `xcore tmp` / `dev` / `test` / `build`, seed `@xrystal/core/x/tmp.yml` dosyasından `{rootFolderPath}/tmp.yml` oluşturur.
1452
1671
 
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.
1672
+ **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.
1454
1673
 
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.
1674
+ **TR — core koruması:** `@xrystal/core` repo’sunda `tmp.yml` yalnızca `x/tmp.yml`; başka kopya hata verir. Servislerde bu kural yok.
1456
1675
 
1457
1676
  ```bash
1458
1677
  xcore tmp # ensure tmp.yml
@@ -1460,105 +1679,417 @@ xcore create example ./ # GitHub template + tmp ensure
1460
1679
  tmp dev # bin alias = xcore dev
1461
1680
  ```
1462
1681
 
1463
- **Ayarlar (`configs` in tmp.yml):** `rootFolderPath`, `mainFolderPath`, `paths.*`, `loaders`, `framework` — servis tek kaynağı. Core pakette default `rootFolderPath: x`.
1682
+ **EN:** `configs` in `tmp.yml`: `service.*` + `core.*` — single source per service. Core package default: `service.paths.root: x`.
1464
1683
 
1465
- **Servis `package.json` — önerilen wiring** (ortak komutları script’e bağla, servise özel olanları ayrı tut):
1684
+ **TR:** `tmp.yml` içinde `configs`: `service.*` + `core.*` — servis tek kaynak. Core pakette default `service.paths.root: x`.
1685
+
1686
+ **EN — recommended service `package.json` wiring** (bind shared CLI commands; keep service-specific scripts separate):
1687
+
1688
+ **TR — önerilen servis `package.json` wiring** (ortak komutları script’e bağla; servise özel olanları ayrı tut):
1466
1689
 
1467
1690
  ```json
1468
1691
  {
1469
1692
  "name": "api-gateway-svc",
1470
1693
  "version": "26.06.27-v1",
1471
1694
  "dependencies": {
1472
- "@xrystal/core": "^3.30.3"
1695
+ "@xrystal/core": "^3.34.0"
1473
1696
  },
1474
1697
  "scripts": {
1475
1698
  "dev": "xcore dev",
1476
1699
  "build": "xcore build",
1700
+ "start:dist": "xcore start",
1477
1701
  "test": "xcore test",
1702
+ "lint": "eslint .",
1703
+ "sync-toolchain": "xcore sync-toolchain",
1478
1704
  "doctor": "xcore doctor",
1479
1705
  "version:check": "xcore version",
1480
1706
  "release:tag": "xcore tag",
1481
- "start": "bun --env-file=./x/environments/.prod.env x/dist/boot.js"
1707
+ "start": "bun --env-file=./x/environments/.prod.env x/dist/index.js"
1482
1708
  }
1483
1709
  }
1484
1710
  ```
1485
1711
 
1486
- Sonra servis kökünden:
1712
+ **EN — toolchain files (service)**
1713
+
1714
+ **TR — toolchain dosyaları (servis)**
1715
+
1716
+ | File / Dosya | Required? / Zorunlu? | Note / Not |
1717
+ |--------------|----------------------|------------|
1718
+ | `{rootFolderPath}/tmp.yml` | Yes / Evet | Folder names here / Klasör adları burada |
1719
+ | `tsconfig.json` | Yes / Evet | Updated by `sync-toolchain` |
1720
+ | `eslint.config.js` | Recommended / Önerilir | Reads tmp — [example](#toolchain--klasör-adları-tmpyml-kurallar-tsconfigbasejson) |
1721
+ | `bunfig.toml` | Bun test/dev | `@/*` alias from sync output |
1722
+
1723
+ **EN — from service root:**
1724
+
1725
+ **TR — servis kökünden:**
1487
1726
 
1488
1727
  ```bash
1489
1728
  bun run dev # = xcore dev
1490
1729
  bun run version:check # = xcore version → api-gateway-svc version, git HEAD
1491
1730
  bun run release:tag # = xcore tag → servis tag’i, core değil
1492
1731
  bun run doctor # CLI vs node_modules @xrystal/core uyumu
1732
+ bun run sync-toolchain # sadece layout değişince (aşağıya bak)
1493
1733
  ```
1494
1734
 
1495
- **`xcore build` öncelik sırası:**
1735
+ **EN — dev vs prod entry**
1736
+
1737
+ | Command | Runs | Path |
1738
+ |---------|------|------|
1739
+ | `xcore dev` | TypeScript source | `{service.folderPath}/index.ts` |
1740
+ | `xcore build` | Compiles to dist | `{rootFolderPath}/{paths.dist}/` |
1741
+ | `xcore start` | Production JS | `{rootFolderPath}/{paths.dist}/index.js` |
1496
1742
 
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`
1743
+ **TR — dev vs prod giriş**
1499
1744
 
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.
1745
+ | Komut | Çalıştırır | Yol |
1746
+ |-------|------------|-----|
1747
+ | `xcore dev` | TypeScript kaynak | `{service.folderPath}/index.ts` |
1748
+ | `xcore build` | Derler | `{rootFolderPath}/{paths.dist}/` |
1749
+ | `xcore start` | Prod JS | `{rootFolderPath}/{paths.dist}/index.js` |
1501
1750
 
1502
- **Lib script’leri** (`@xrystal/core` repo — geliştirici / publish):
1751
+ **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`.
1503
1752
 
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** |
1753
+ **TR — servis build:** `tsconfig.json` birincil. `tmp.yml` `build.*` = yalnızca override. `tmp.yml` runtime = loaders, protocols, `rootFolderPath`.
1513
1754
 
1514
- **`xcore tag` akışı (@xrystal/core):**
1755
+ | File / Dosya | EN | TR |
1756
+ |--------------|----|----|
1757
+ | `tsconfig.json` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` via `--noEmit` | `include`→glob, `outDir`→dist, `sourceMap`, `paths`, `strict`, `typecheck` için `--noEmit` |
1758
+ | `tmp.yml` `build.*` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` | Override: `typecheck`, `glob`, `entries`, `outDir`, `sourcemap`, `declarations`, `minify` |
1759
+ | `tmp.yml` `paths.*` | Runtime (test, env); dist fallback if no `outDir` | Runtime (test, env); `outDir` yoksa dist fallback |
1515
1760
 
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`
1761
+ | `configs.build` (override) | tsconfig karşılığı | Ne yapar |
1762
+ |-----------------------------|-------------------|----------|
1763
+ | `outDir` | `compilerOptions.outDir` | Çıktı klasörü — **tsconfig'te `./x/dist` yaz, tmp'de tekrarlama** |
1764
+ | `glob` / `entries` | `include` / `rootDir` | Hangi `.ts` derlenecek |
1765
+ | `sourcemap` | `sourceMap` / `inlineSourceMap` | Harita (default kapalı) |
1766
+ | `declarations` | `declaration` / `emitDeclarationOnly` | `.d.ts` üret |
1767
+ | `minify` | — (core build) | `tsc` sonrası `minify-dist.mjs` (tmp `build.minify: true`) |
1768
+ | `typecheck` | — (tsconfig kuralları okunur) | `tsc --noEmit` build öncesi |
1769
+ | `tsconfig` | dosya yolu | `tsconfig.build.json` vb. |
1770
+ | `tscLenient` | — | Sadece `declarations: true` + tsc hatalarını yoksay |
1771
+
1772
+ **EN — priority:** tmp.yml explicit > tsconfig.json > tmp layout fallback
1773
+
1774
+ **TR — öncelik:** tmp.yml explicit > tsconfig.json > tmp layout fallback
1775
+
1776
+ ```yaml
1777
+ configs:
1778
+ file:
1779
+ rootFolderPath: x
1780
+
1781
+ service:
1782
+ folderPath: ./source
1783
+ build:
1784
+ typecheck: true # tek satır yeter — outDir/include tsconfig'te
1785
+ ```
1786
+
1787
+ ```json
1788
+ // tsconfig.json — servis/lib ortak model
1789
+ {
1790
+ "include": ["source"],
1791
+ "compilerOptions": {
1792
+ "rootDir": "./source",
1793
+ "outDir": "./x/dist",
1794
+ "sourceMap": false,
1795
+ "declaration": false,
1796
+ "strict": true,
1797
+ "paths": { "@/*": ["source/*"] }
1798
+ }
1799
+ }
1800
+ ```
1801
+
1802
+ **EN — build order (service):** `typecheck?` → `rm dist` → `bun build .ts` → `declarations?`
1803
+
1804
+ **TR — build sırası (servis):** `typecheck?` → `rm dist` → `bun build .ts` → `declarations?`
1805
+
1806
+ **EN — build order (@xrystal/core lib):** `rm x/dist` → `tsc` (JS + `.d.ts`) → `tsc-alias` → `fix-dist-imports` → `minify-dist?` (`build.minify`)
1807
+
1808
+ **TR — build sırası (@xrystal/core lib):** `rm x/dist` → `tsc` → `tsc-alias` → `fix-dist-imports` → `minify-dist?` (`build.minify`)
1809
+
1810
+ **EN:** `prepublishOnly` = `release:prepare` + `verify-publish-config`. See [npm publish](#npm-publish--npm-yayın).
1811
+
1812
+ **TR:** `prepublishOnly` = `release:prepare` + `verify-publish-config`. Bkz. [npm publish](#npm-publish--npm-yayın).
1813
+
1814
+ ```bash
1815
+ xcore build
1816
+ xcore start # bun x/dist/index.js (+ .global.env / .prod.env if present)
1817
+ ```
1818
+
1819
+ **Build output / derleme çıktısı**
1820
+
1821
+ | Layer | Path | Role |
1822
+ |-------|------|------|
1823
+ | Source (dev) | `{service.folderPath}/**/*.ts` | `xcore dev` runs TS directly |
1824
+ | Prod runtime | `tsconfig outDir` → `.js` | `xcore start`, Docker |
1825
+ | Source map | `{outDir}/**/*.js.map` | tsconfig `sourceMap` veya tmp `build.sourcemap` |
1826
+ | Declarations | `{outDir}/**/*.d.ts` | tsconfig `emitDeclarationOnly` veya tmp `build.declarations` |
1827
+
1828
+ **EN:** Put `include`, `outDir`, `sourceMap`, `paths`, `strict` in `tsconfig.json`. tmp.yml `build.*` only when you need an override (e.g. `typecheck: true`).
1829
+
1830
+ **TR:** `include`, `outDir`, `sourceMap`, `paths`, `strict` → `tsconfig.json`. tmp.yml `build.*` sadece override için (ör. `typecheck: true`).
1831
+
1832
+ **Loop fix / döngü fix:** `"build": "xcore build"` no longer delegates to itself — default build runs.
1833
+
1834
+ **`xcore build` priority / öncelik:**
1835
+
1836
+ 1. **EN:** Custom `scripts.build` (not `xcore build`) → `bun run build`
1837
+ **TR:** Özel `scripts.build` (xcore build değilse) → delegate
1838
+ 2. **EN:** Else: read `tsconfig.json` (include/outDir/sourceMap) + tmp.yml overrides
1839
+ **TR:** Aksi halde tsconfig okunur + tmp.yml override
1840
+
1841
+ **Lib scripts / Lib script’leri** (`@xrystal/core` repo — developer / geliştirici):
1842
+
1843
+ | Script | EN | TR |
1844
+ |--------|----|----|
1845
+ | `npm run dev` | Core source watch | Core kaynak watch |
1846
+ | `npm run build` | `tsc` → alias → fix-dist-imports (+ minify) | `tsc` tam emit → Node ESM import düzeltme |
1847
+ | `npm run release:prepare` | lint → build → test (no git write) | lint → build → test (git’e yazmaz) |
1848
+ | `xcore hooks install` | Install pre-commit into `.git/hooks` (core + services) | `.git/hooks` pre-commit (core + servis) |
1849
+ | `npm run tag` / `xcore tag` | prepare + git tag + push | prepare + tag + push |
1850
+ | `npm publish` | GitHub Actions on tag (`--ignore-scripts`) | Tag’de CI publish eder |
1851
+
1852
+ **`xcore tag` flow / akışı (@xrystal/core):**
1853
+
1854
+ 1. **EN:** Commit `package.json` version bump first.
1855
+ **TR:** Önce `package.json` version commit edilmeli.
1856
+ 2. **EN:** `lint` → `build` → `test` (TypeScript stays in git; runtime in `x/dist`).
1857
+ **TR:** `lint` → `build` → `test` (git’te `.ts` kalır; runtime `x/dist`’te).
1858
+ 3. **EN:** `git tag vX.Y.Z` + push → GitHub Actions publishes to npm.
1859
+ **TR:** Tag + push → CI npm’e publish eder.
1860
+
1861
+ **EN:** Never commit `.js` under `source/`. Publish uses minified `x/dist` only — [npm publish](#npm-publish--npm-yayın).
1862
+
1863
+ **TR:** `source/` altına `.js` commit etme. Publish yalnızca minify `x/dist` — [npm publish](#npm-publish--npm-yayın).
1864
+
1865
+ **EN:** Service `npm run tag` does not publish `@xrystal/core` — use `xcore tag` or `"release:tag": "xcore tag"` on the **service** repo.
1866
+
1867
+ **TR:** Serviste `npm run tag` **@xrystal/core** publish etmez — servis repo’sunda `xcore tag` veya `"release:tag": "xcore tag"` kullan.
1868
+
1869
+ ---
1870
+
1871
+ ### Version bump + `hooks:install` — when / ne zaman?
1872
+
1873
+ **EN — what does it do?**
1874
+ `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.
1875
+
1876
+ **TR — ne yapar?**
1877
+ `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.
1878
+
1879
+ **EN — when do I run it?**
1880
+
1881
+ | Situation | Run `hooks:install`? |
1882
+ |-----------|----------------------|
1883
+ | First clone of **`-xrystal-core`** on this machine | **Yes — once** |
1884
+ | Commits never block same/lower version bumps | **Yes — once** |
1885
+ | After `bun install` in core repo | Run once after clone |
1886
+ | Before every commit or tag | **No** |
1887
+ | **Service repo** (only uses `@xrystal/core`) | **Yes — once** |
1888
+ | **`xcore create`** scaffolded a new service | **Auto** — hook + `hooks:install` script |
1889
+
1890
+ **TR — ne zaman çalıştırırım?**
1891
+
1892
+ | Durum | `hooks:install`? |
1893
+ |-------|------------------|
1894
+ | **`-xrystal-core`** reposunu bu makinede ilk kez clone'ladım | **Evet — bir kez** |
1895
+ | Commit atınca version kontrolü hiç çalışmıyor | **Evet — bir kez** |
1896
+ | Core repo'da `bun install` sonrası | Clone sonrası bir kez |
1897
+ | Her commit / tag öncesi | **Hayır** |
1898
+ | Sadece servis reposu | **Evet — bir kez** |
1899
+ | **`xcore create`** ile yeni servis oluşturdum | **Otomatik** — hook + `hooks:install` script |
1900
+
1901
+ ```bash
1902
+ # @xrystal/core repo — first time on this machine / bu makinede ilk kez
1903
+ cd -xrystal-core
1904
+ xcore hooks install # core repo or service repo
1905
+ # core repo only: bun run hooks:install
1906
+ ```
1907
+
1908
+ **EN — two layers of protection**
1909
+
1910
+ | Layer | When | Rule |
1911
+ |-------|------|------|
1912
+ | **pre-commit hook** | `git commit` (if hook installed) | Staged `version` > HEAD `version` |
1913
+ | **`xcore tag`** | Before tag + push | Committed `version` > latest git tag |
1914
+
1915
+ **TR — iki katman**
1916
+
1917
+ | Katman | Ne zaman | Kural |
1918
+ |--------|----------|-------|
1919
+ | **pre-commit hook** | `git commit` (hook kuruluysa) | Stage'deki `version` > HEAD'teki `version` |
1920
+ | **`xcore tag`** | Tag + push öncesi | Commit'teki `version` > son git tag |
1921
+
1922
+ **EN — typical release (core maintainer)**
1923
+
1924
+ ```bash
1925
+ # 1. Bump package.json version (e.g. 3.35.0 → 3.35.1)
1926
+ git add package.json
1927
+ git commit -m "chore: release 3.35.1" # hook blocks same/lower version
1928
+
1929
+ xcore tag # lint + test + build + version check again
1930
+ ```
1931
+
1932
+ **TR — tipik release**
1933
+
1934
+ ```bash
1935
+ # 1. package.json version artır (ör. 3.35.0 → 3.35.1)
1936
+ git add package.json
1937
+ git commit -m "chore: release 3.35.1" # hook aynı/düşük version'u reddeder
1938
+
1939
+ xcore tag # lint + test + build + version tekrar kontrol
1940
+ ```
1941
+
1942
+ **EN:** `xcore doctor` / `xcore version` show `latest tag` and `bump vs latest tag`.
1943
+ **TR:** `xcore doctor` / `xcore version` → `latest tag` ve bump durumu.
1944
+
1945
+ **EN:** Hook not installed? Commits still work — **`xcore tag`** enforces the bump at release.
1946
+ **TR:** Hook kurulu değilse commit olur — release'te **`xcore tag`** yine kontrol eder.
1520
1947
 
1521
- Git’te **her zaman TypeScript** kalır. `.js` publish anında CI’da üretilir — `build:prod` commit’lenmez.
1522
1948
 
1523
- Serviste `npm run tag` **servis** tag’i üretmez — servis için `xcore tag` veya `"release:tag": "xcore tag"` kullan.
1524
1949
 
1525
1950
  ---
1526
1951
 
1527
1952
  ### `doctor` — iki sürüm
1528
1953
 
1954
+ `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.
1955
+
1529
1956
  | Alan | Anlam |
1530
1957
  |------|--------|
1531
1958
  | **CLI (tool)** | Çalışan `xcore` binary’sinin `@xrystal/core` sürümü |
1532
1959
  | **Project (service)** | `api-gateway-svc@1.x` — servisin kendi `package.json` `version` |
1533
1960
  | **node_modules** | Kurulu `@xrystal/core` — CLI ile eşleşiyor mu |
1961
+ | **Toolchain** | `defaults.json` → önerilen `outDir` / `include` / eslint — `tsconfig.json` uyumu |
1534
1962
 
1535
1963
  ---
1536
1964
 
1537
- ### `x/` klasörü (ortak layout — tmp.yml ile yapılandırılır)
1965
+ ### npm + Node (Express gibi — framework/runtime bağımsız)
1966
+
1967
+ **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.
1968
+
1969
+ **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.
1538
1970
 
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.
1971
+ | Katman | Bun gerekli mi? | Ne yapar |
1972
+ |--------|-----------------|----------|
1973
+ | `import '@xrystal/core'` | Hayır (Node) | Lib runtime |
1974
+ | `xcore dev` / `build` | Evet (CLI) | Proje geliştirme |
1975
+ | Docker prod `node x/dist/index.js` | Hayır | Servis prod |
1976
+
1977
+ ---
1978
+
1979
+ ### Toolchain — klasör adları `tmp.yml`, kurallar `tsconfig.base.json`
1980
+
1981
+ **Sorun:** `tsconfig` / `eslint` içinde `x`, `source` hardcode → serviste `infra`, `src` olunca kırılır.
1982
+
1983
+ **Çözüm:** Klasör yolları **yalnızca `tmp.yml`**; tsconfig path alanları **sync** ile yazılır:
1984
+
1985
+ ```yaml
1986
+ configs:
1987
+ file:
1988
+ rootFolderPath: infra # x yerine
1989
+ service:
1990
+ folderPath: ./src
1991
+ paths:
1992
+ dist: dist
1993
+ ```
1994
+
1995
+ ```bash
1996
+ xcore sync-toolchain # tsconfig include / outDir / @/* ← tmp.yml
1997
+ xcore doctor # drift var mı
1998
+ ```
1999
+
2000
+ | Dosya | Klasör adı var mı? | Rol |
2001
+ |-------|-------------------|-----|
2002
+ | `tmp.yml` | **Evet — tek kaynak** | `service.paths.root`, `service.paths.source`, `service.paths.*` |
2003
+ | `tsconfig.base.json` | Hayır | `strict`, `module`, `target` (npm export) |
2004
+ | `tsconfig.json` | Sync ile | `include`, `outDir`, `paths` — elle yazma |
2005
+ | `eslint.config.js` | tmp'den okur | `createEslintConfigFromProject(cwd)` |
2006
+
2007
+ **Servis eslint.config.js:**
2008
+
2009
+ ```js
2010
+ import tseslint from 'typescript-eslint'
2011
+ import { createEslintConfigFromProject } from '@xrystal/core/x/bin/helpers/toolchain-config.mjs'
2012
+
2013
+ export default createEslintConfigFromProject(process.cwd(), tseslint)
2014
+ ```
2015
+
2016
+ ---
2017
+
2018
+ ### Servislerde `sync-toolchain` (manuel)
2019
+
2020
+ **Evet — servislerde de öneriyoruz.** Otomatik değil; **sen çalıştırırsın**, sadece **klasör/layout** değişince.
2021
+
2022
+ | tmp.yml değişikliği | `sync-toolchain` gerekir mi? |
2023
+ |---------------------|------------------------------|
2024
+ | `service.paths.root` (`x` → `infra`) | **Evet** |
2025
+ | `service.paths.source` (`./source` → `./src`) | **Evet** |
2026
+ | `service.paths.dist` / `service.paths.tests` | **Evet** |
2027
+ | `loaders`, `logLevel`, `protocols` | **Hayır** — runtime watch yeterli |
2028
+
2029
+ **Ne yapar:** `tmp.yml` layout → `tsconfig.json` (`include`, `outDir`, `@/*`, `extends: @xrystal/core/tsconfig.base.json`).
2030
+ **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.
2031
+
2032
+ **Servis akışı:**
2033
+
2034
+ ```bash
2035
+ # 1) Yeni servis veya template clone sonrası — tmp.yml layout'u düzenle
2036
+ # 2) Bir kez sync
2037
+ bun run sync-toolchain
2038
+ # 3) Kontrol
2039
+ bun run doctor
2040
+ # 4) bunfig.toml — sync'in yazdığı alias satırını ekle
2041
+ ```
2042
+
2043
+ **package.json script (servislere ekle):**
2044
+
2045
+ ```json
2046
+ "sync-toolchain": "xcore sync-toolchain",
2047
+ "lint": "eslint ."
2048
+ ```
2049
+
2050
+ **Dry-run:** `xcore sync-toolchain --dry-run` — yazmadan ne üreteceğini gösterir.
2051
+
2052
+ Runtime (`xcore dev` çalışırken) loader ayarları tmp watch ile güncellenir; **sync-toolchain buna karışmaz** — bilinçli ayrım.
2053
+
2054
+ ---
2055
+
2056
+ ### `x/` folder layout / `x/` klasörü (configured via tmp.yml)
2057
+
2058
+ **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.
2059
+
2060
+ **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
2061
 
1541
2062
  ```yaml
1542
2063
  # configs = proje ayarları (servis tek kaynak)
1543
2064
  configs:
1544
- rootFolderPath: x # serviste infra, config, … olabilir
1545
- mainFolderPath: ./source
1546
- paths:
1547
- tests: tests
1548
- environments: environments
1549
- dist: dist
2065
+ file:
2066
+ rootFolderPath: x # serviste infra, config, … olabilir
2067
+
2068
+ service:
2069
+ name: my-api
2070
+ folderPath: ./source
2071
+ paths:
2072
+ tests: tests
2073
+ environments: environments
2074
+ dist: dist
2075
+ build:
2076
+ typecheck: true
1550
2077
  ```
1551
2078
 
1552
- Seed / ensure kaynağı: `node_modules/@xrystal/core/x/tmp.yml` (ayrı template yok).
2079
+ Seed / ensure source: `node_modules/@xrystal/core/x/tmp.yml` (no separate template file / ayrı template yok).
2080
+
2081
+ | `configs` field / alan | EN | TR |
2082
+ |------------------------|----|----|
2083
+ | `service.paths.root` | CLI root folder (`xcore test`/`dev`/`build`) | CLI kök klasörü (`xcore test`/`dev`/`build`) |
2084
+ | `core.tmp.fileWatchIntervalMs` | `tmp.yml` watch interval (ms, default `500`) | `tmp.yml` izleme aralığı (ms, default `500`) |
2085
+ | `service.paths.source` | Source tree + `xcore dev` entry | Kaynak klasörü + `xcore dev` girişi |
2086
+ | `service.paths.*` | `tests` / `environments` / `dist` subpaths | `tests` / `environments` / `dist` alt yolları |
2087
+ | `service.loaders`, `service.framework` | Runtime (System, dto, logger, …) | Runtime (System, dto, logger, …) |
2088
+ | `service.build.*` | Build override (`typecheck`, …) — tsconfig is primary | Build override — tsconfig birincil |
1553
2089
 
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, …) |
2090
+ **EN:** In services, `tmp.yml` is found recursively; in the core repo only `x/tmp.yml` is allowed.
1560
2091
 
1561
- Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` kabul edilir.
2092
+ **TR:** Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` kabul edilir.
1562
2093
 
1563
2094
  ```
1564
2095
  {rootFolderPath}/
@@ -1570,10 +2101,12 @@ Servislerde `tmp.yml` recursive bulunur; core repo’da yalnızca `x/tmp.yml` ka
1570
2101
 
1571
2102
  | Repo | `{rootFolderPath}/tests` |
1572
2103
  |------|--------------------------|
1573
- | **@xrystal/core** | Lib unit/integration testleri |
1574
- | **Servis** | Servis testleri |
2104
+ | **@xrystal/core** | EN: lib unit/integration tests · TR: lib unit/integration testleri |
2105
+ | **Service / Servis** | EN: service tests · TR: servis testleri |
2106
+
2107
+ **EN:** `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
1575
2108
 
1576
- `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
2109
+ **TR:** `xcore test` = `bun test ./{rootFolderPath}/{paths.tests}`.
1577
2110
 
1578
2111
  ---
1579
2112
 
@@ -1775,16 +2308,23 @@ Detay: [Three stores → G](#g--global-store-zustand)
1775
2308
 
1776
2309
  ---
1777
2310
 
1778
- ## Tests
2311
+ ## Tests / Testler
1779
2312
 
1780
2313
  ```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
2314
+ bun run release:prepare # lint + test + build — same as tag pre-check / tag öncesi kontrol
2315
+ bun test x/tests # 103 tests — CLI, realtime, i18n, tmp guard, …
2316
+ bun run lint # @/ alias rules on source/*.ts
2317
+ bun run build # tsc → x/dist (+ fix-dist-imports; minify if tmp build.minify)
1785
2318
  ```
1786
2319
 
1787
- Lightweight unit tests (no full awilix boot). `express` is a **devDependency** only for test/runtime wiring — not shipped to apps.
2320
+ **EN:** Lightweight unit/integration tests (no full Awilix boot in most suites). Path alias `@/*` → `./source/*` via `bunfig.toml`.
2321
+ **TR:** Hafif unit/integration testleri (çoğu suite’te tam Awilix boot yok). `@/*` alias `bunfig.toml` ile çözülür.
2322
+
2323
+ **EN:** Publish CI: `lint` → `build` → `test` → `prepare-npm-publish` → `verify-npm-pack` → `npm publish`. Details: [npm publish](#npm-publish--npm-yayın).
2324
+
2325
+ **TR:** Publish CI: `lint` → `build` → `test` → `prepare-npm-publish` → `verify-npm-pack` → `npm publish`. Detay: [npm publish](#npm-publish--npm-yayın).
2326
+
2327
+ `express` is a **devDependency** only — not shipped to apps / uygulamalara gitmez.
1788
2328
 
1789
2329
  ---
1790
2330