@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.
- package/README.md +651 -136
- package/package.json +27 -24
- package/tsconfig.base.json +15 -0
- package/x/bin/commands/create.mjs +34 -5
- package/x/bin/commands/doctor.mjs +115 -25
- package/x/bin/commands/hooks.mjs +55 -0
- package/x/bin/commands/project.mjs +75 -42
- package/x/bin/commands/release.mjs +8 -3
- package/x/bin/commands/sync-toolchain.mjs +43 -0
- package/x/bin/commands/tmp.mjs +13 -4
- package/x/bin/helpers/.generated/.generated-from +1 -0
- package/x/bin/helpers/.generated/tmp-schema.mjs +192 -0
- package/x/bin/helpers/banner.mjs +66 -12
- package/x/bin/helpers/build-config.mjs +342 -0
- package/x/bin/helpers/cli-help.mjs +164 -0
- package/x/bin/helpers/create-target.mjs +18 -2
- package/x/bin/helpers/project-artifacts.mjs +140 -0
- package/x/bin/helpers/runtime-info.mjs +172 -0
- package/x/bin/helpers/tmp-config.mjs +11 -10
- package/x/bin/helpers/tmp-layout.mjs +10 -16
- package/x/bin/helpers/tmp-schema.mjs +9 -0
- package/x/bin/helpers/toolchain-config.mjs +233 -0
- package/x/bin/main-cli.js +31 -3
- package/x/bin/scripts/clean-source-types.mjs +19 -0
- package/x/bin/scripts/fix-dist-imports.mjs +80 -0
- package/x/bin/scripts/install-git-hooks.mjs +86 -0
- package/x/bin/scripts/minify-dist.mjs +50 -0
- package/x/bin/scripts/prepare-npm-publish.mjs +49 -0
- package/x/bin/scripts/unpublish-leaked-versions.mjs +62 -0
- package/x/bin/scripts/verify-npm-pack.mjs +45 -0
- package/x/bin/scripts/verify-version-bump.mjs +27 -0
- package/x/bin/scripts/version-check.mjs +173 -0
- package/x/dist/index.d.ts +3 -0
- package/x/dist/index.js +1 -0
- package/x/dist/loader/clients/index.js +1 -0
- package/x/dist/loader/configs/index.js +1 -0
- package/{source → x/dist}/loader/controller/index.d.ts +20 -17
- package/x/dist/loader/controller/index.js +1 -0
- package/x/dist/loader/dto/index.js +1 -0
- package/x/dist/loader/events/index.js +1 -0
- package/x/dist/loader/index.d.ts +11 -0
- package/x/dist/loader/index.js +1 -0
- package/{source → x/dist}/loader/kafka/index.d.ts +1 -0
- package/x/dist/loader/kafka/index.js +1 -0
- package/x/dist/loader/localizations/index.js +1 -0
- package/{source → x/dist}/loader/logger/index.d.ts +1 -0
- package/x/dist/loader/logger/index.js +2 -0
- package/x/dist/loader/service/index.js +1 -0
- package/x/dist/loader/system/index.js +1 -0
- package/x/dist/project/index.js +1 -0
- package/x/dist/utils/constants/defaults.json +44 -0
- package/x/dist/utils/constants/index.js +1 -0
- package/x/dist/utils/helpers/configs/index.js +1 -0
- package/x/dist/utils/helpers/context/controller-store.js +1 -0
- package/x/dist/utils/helpers/context/index.js +1 -0
- package/{source → x/dist}/utils/helpers/core/index.d.ts +1 -1
- package/x/dist/utils/helpers/core/index.js +1 -0
- package/x/dist/utils/helpers/core/paths.js +1 -0
- package/x/dist/utils/helpers/core/tmp-layout.js +1 -0
- package/x/dist/utils/helpers/date/index.js +1 -0
- package/x/dist/utils/helpers/dispatch/index.js +1 -0
- package/x/dist/utils/helpers/dto/index.js +1 -0
- package/x/dist/utils/helpers/filters/index.js +1 -0
- package/x/dist/utils/helpers/framework/index.js +1 -0
- package/x/dist/utils/helpers/handlers/adapters.js +1 -0
- package/x/dist/utils/helpers/handlers/execute.js +1 -0
- package/x/dist/utils/helpers/handlers/index.js +1 -0
- package/x/dist/utils/helpers/hash/crypto.js +1 -0
- package/x/dist/utils/helpers/id/index.js +1 -0
- package/x/dist/utils/helpers/index.js +1 -0
- package/x/dist/utils/helpers/ip/index.js +1 -0
- package/x/dist/utils/helpers/is/index.js +1 -0
- package/x/dist/utils/helpers/locales/index.js +1 -0
- package/x/dist/utils/helpers/math/index.js +1 -0
- package/{source → x/dist}/utils/helpers/middleware/index.d.ts +2 -2
- package/x/dist/utils/helpers/middleware/index.js +1 -0
- package/x/dist/utils/helpers/objects/index.js +1 -0
- package/x/dist/utils/helpers/path/index.js +1 -0
- package/{source → x/dist}/utils/helpers/protocol/index.d.ts +2 -10
- package/x/dist/utils/helpers/protocol/index.js +1 -0
- package/x/dist/utils/helpers/protocol/options.js +1 -0
- package/x/dist/utils/helpers/regex/checkSpecialRegexControl.js +1 -0
- package/x/dist/utils/helpers/runtime/dto-access.js +1 -0
- package/x/dist/utils/helpers/runtime/dto-types.js +1 -0
- package/{source → x/dist}/utils/helpers/runtime/index.d.ts +1 -0
- package/x/dist/utils/helpers/runtime/index.js +1 -0
- package/x/dist/utils/helpers/runtime/shutdown.d.ts +3 -0
- package/x/dist/utils/helpers/runtime/shutdown.js +1 -0
- package/x/dist/utils/helpers/state/index.js +1 -0
- package/x/dist/utils/helpers/state/props-from-tmp.js +1 -0
- package/x/dist/utils/helpers/state/request-key-guard.js +1 -0
- package/x/dist/utils/helpers/state/scopes.js +1 -0
- package/x/dist/utils/helpers/string/index.js +1 -0
- package/x/dist/utils/helpers/tests/tmp-schema.test.js +1 -0
- package/x/dist/utils/helpers/tests/tmp-watch.test.js +1 -0
- package/x/dist/utils/helpers/timer/index.js +1 -0
- package/x/dist/utils/helpers/tmp/index.d.ts +5 -0
- package/x/dist/utils/helpers/tmp/index.js +1 -0
- package/x/dist/utils/helpers/tmp/loader-tmp-sync.js +1 -0
- package/{source → x/dist}/utils/helpers/tmp/runtime-tmp.d.ts +2 -6
- package/x/dist/utils/helpers/tmp/runtime-tmp.js +1 -0
- package/{source → x/dist}/utils/helpers/tmp/tmp-loader.d.ts +1 -0
- package/x/dist/utils/helpers/tmp/tmp-loader.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-schema.d.ts +47 -0
- package/x/dist/utils/helpers/tmp/tmp-schema.js +1 -0
- package/x/dist/utils/helpers/tmp/tmp-watch.d.ts +1 -0
- package/x/dist/utils/helpers/tmp/tmp-watch.js +1 -0
- package/x/dist/utils/helpers/validates/index.js +1 -0
- package/x/dist/utils/index.js +1 -0
- package/x/dist/utils/models/classes/class.clients.js +1 -0
- package/x/dist/utils/models/classes/class.interfaces.js +1 -0
- package/x/dist/utils/models/classes/class.service-locator.js +1 -0
- package/{source → x/dist}/utils/models/classes/class.tmp-file-loader.d.ts +3 -2
- package/x/dist/utils/models/classes/class.tmp-file-loader.js +1 -0
- package/x/dist/utils/models/classes/class.x.js +1 -0
- package/x/dist/utils/models/enums/index.js +1 -0
- package/x/dist/utils/models/index.js +1 -0
- package/x/dist/utils/models/types/index.js +1 -0
- package/x/dist/utils/package-root.js +1 -0
- package/x/tmp.yml +51 -42
- package/source/index.js +0 -11
- package/source/loader/clients/index.js +0 -22
- package/source/loader/configs/index.js +0 -88
- package/source/loader/controller/index.js +0 -236
- package/source/loader/dto/index.js +0 -92
- package/source/loader/events/index.js +0 -44
- package/source/loader/index.d.ts +0 -11
- package/source/loader/index.js +0 -11
- package/source/loader/kafka/index.js +0 -137
- package/source/loader/localizations/index.js +0 -46
- package/source/loader/logger/index.js +0 -217
- package/source/loader/service/index.js +0 -7
- package/source/loader/system/index.js +0 -25
- package/source/project/index.js +0 -70
- package/source/utils/constants/defaults.json +0 -15
- package/source/utils/constants/defaults.mjs +0 -10
- package/source/utils/constants/index.js +0 -22
- package/source/utils/helpers/configs/index.js +0 -1
- package/source/utils/helpers/context/controller-store.js +0 -12
- package/source/utils/helpers/context/index.js +0 -24
- package/source/utils/helpers/core/index.js +0 -58
- package/source/utils/helpers/core/paths.js +0 -78
- package/source/utils/helpers/core/tmp-layout.js +0 -241
- package/source/utils/helpers/date/index.js +0 -48
- package/source/utils/helpers/dispatch/index.js +0 -53
- package/source/utils/helpers/dto/index.js +0 -10
- package/source/utils/helpers/filters/index.js +0 -44
- package/source/utils/helpers/framework/index.js +0 -17
- package/source/utils/helpers/handlers/adapters.js +0 -40
- package/source/utils/helpers/handlers/execute.js +0 -82
- package/source/utils/helpers/handlers/index.js +0 -31
- package/source/utils/helpers/hash/crypto.js +0 -22
- package/source/utils/helpers/id/index.js +0 -24
- package/source/utils/helpers/index.js +0 -26
- package/source/utils/helpers/ip/index.js +0 -21
- package/source/utils/helpers/is/index.js +0 -35
- package/source/utils/helpers/locales/index.js +0 -82
- package/source/utils/helpers/math/index.js +0 -14
- package/source/utils/helpers/middleware/index.js +0 -36
- package/source/utils/helpers/objects/index.js +0 -55
- package/source/utils/helpers/path/index.js +0 -4
- package/source/utils/helpers/protocol/index.js +0 -99
- package/source/utils/helpers/protocol/options.js +0 -13
- package/source/utils/helpers/regex/checkSpecialRegexControl.js +0 -3
- package/source/utils/helpers/runtime/dto-access.js +0 -5
- package/source/utils/helpers/runtime/index.js +0 -1
- package/source/utils/helpers/state/index.js +0 -185
- package/source/utils/helpers/state/props-from-tmp.js +0 -44
- package/source/utils/helpers/state/request-key-guard.js +0 -42
- package/source/utils/helpers/state/scopes.js +0 -69
- package/source/utils/helpers/string/index.js +0 -9
- package/source/utils/helpers/timer/index.js +0 -5
- package/source/utils/helpers/tmp/index.d.ts +0 -3
- package/source/utils/helpers/tmp/index.js +0 -3
- package/source/utils/helpers/tmp/loader-tmp-sync.js +0 -13
- package/source/utils/helpers/tmp/runtime-tmp.js +0 -30
- package/source/utils/helpers/tmp/tmp-loader.js +0 -48
- package/source/utils/helpers/validates/index.js +0 -20
- package/source/utils/index.js +0 -3
- package/source/utils/models/classes/class.clients.js +0 -142
- package/source/utils/models/classes/class.interfaces.js +0 -10
- package/source/utils/models/classes/class.service-locator.js +0 -16
- package/source/utils/models/classes/class.tmp-file-loader.js +0 -38
- package/source/utils/models/classes/class.x.js +0 -180
- package/source/utils/models/enums/index.js +0 -148
- package/source/utils/models/index.js +0 -9
- package/source/utils/models/types/index.js +0 -2
- package/source/utils/models/types/shims.d.ts +0 -123
- package/source/utils/package-root.js +0 -5
- package/x/tests/cli.test.ts +0 -85
- package/x/tests/context.test.ts +0 -25
- package/x/tests/dispatch.test.ts +0 -84
- package/x/tests/fixtures/locales/en/translation.json +0 -8
- package/x/tests/fixtures/locales/tr/translation.json +0 -8
- package/x/tests/frameworks.integration.test.ts +0 -185
- package/x/tests/helpers/i18n-setup.ts +0 -52
- package/x/tests/helpers/middleware.ts +0 -23
- package/x/tests/helpers/register-test-dto.ts +0 -52
- package/x/tests/i18n.integration.test.ts +0 -77
- package/x/tests/i18n.test.ts +0 -96
- package/x/tests/middleware.test.ts +0 -83
- package/x/tests/project-layout.test.ts +0 -65
- package/x/tests/protocol.test.ts +0 -75
- package/x/tests/realtime.examples.test.ts +0 -198
- package/x/tests/runtime-tmp.test.ts +0 -49
- package/x/tests/socket.integration.test.ts +0 -174
- package/x/tests/state.test.ts +0 -183
- package/x/tests/tmp-layout-guard.test.ts +0 -40
- /package/{source → x/dist}/loader/clients/index.d.ts +0 -0
- /package/{source → x/dist}/loader/configs/index.d.ts +0 -0
- /package/{source → x/dist}/loader/dto/index.d.ts +0 -0
- /package/{source → x/dist}/loader/events/index.d.ts +0 -0
- /package/{source → x/dist}/loader/localizations/index.d.ts +0 -0
- /package/{source → x/dist}/loader/service/index.d.ts +0 -0
- /package/{source → x/dist}/loader/system/index.d.ts +0 -0
- /package/{source → x/dist}/project/index.d.ts +0 -0
- /package/{source → x/dist}/utils/constants/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/configs/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/context/controller-store.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/context/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/core/paths.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/core/tmp-layout.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/date/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/dispatch/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/dto/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/filters/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/framework/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/handlers/adapters.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/handlers/execute.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/handlers/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/hash/crypto.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/id/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/ip/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/is/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/locales/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/math/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/objects/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/path/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/protocol/options.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/regex/checkSpecialRegexControl.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/runtime/dto-access.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/runtime/dto-types.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/state/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/state/props-from-tmp.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/state/request-key-guard.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/state/scopes.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/string/index.d.ts +0 -0
- /package/{source/index.d.ts → x/dist/utils/helpers/tests/tmp-schema.test.d.ts} +0 -0
- /package/{source/utils/helpers/runtime/dto-types.js → x/dist/utils/helpers/tests/tmp-watch.test.d.ts} +0 -0
- /package/{source → x/dist}/utils/helpers/timer/index.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/tmp/loader-tmp-sync.d.ts +0 -0
- /package/{source → x/dist}/utils/helpers/validates/index.d.ts +0 -0
- /package/{source → x/dist}/utils/index.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.clients.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.interfaces.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.service-locator.d.ts +0 -0
- /package/{source → x/dist}/utils/models/classes/class.x.d.ts +0 -0
- /package/{source → x/dist}/utils/models/enums/index.d.ts +0 -0
- /package/{source → x/dist}/utils/models/index.d.ts +0 -0
- /package/{source → x/dist}/utils/models/types/index.d.ts +0 -0
- /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
|
|
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) ·
|
|
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
|
-
##
|
|
10
|
+
## `tmp.yml` layout / tmp.yml düzeni
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
**EN — structure:** `service` (app identity, paths, runtime, build) + `core` (library mechanisms like tmp watch).
|
|
12
13
|
|
|
13
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
{
|
|
170
|
+
{project-root}/ # EN: repo root · TR: proje kökü
|
|
70
171
|
├── package.json
|
|
71
|
-
└── {rootFolderPath}/ # default: x
|
|
72
|
-
├── tmp.yml #
|
|
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
|
|
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 `
|
|
179
|
+
Kaynak kodu `service.paths.source` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
|
|
79
180
|
|
|
80
181
|
```yaml
|
|
81
182
|
configs:
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
`
|
|
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ç |
|
|
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
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
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 (
|
|
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`
|
|
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 |
|
|
1399
|
-
|
|
1400
|
-
| **`xcore`** | Ana isim (önerilen) | `xcore doctor`, `npx xcore dev` |
|
|
1401
|
-
| **`xrystal`** | Geçiş alias | `xrystal version` = `xcore version` |
|
|
1402
|
-
| **`tmp`** |
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 |
|
|
1433
|
-
|
|
1434
|
-
| **CLI
|
|
1435
|
-
| **
|
|
1436
|
-
| **Lib (core repo)** | `@xrystal/core`
|
|
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
|
-
**
|
|
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 ./
|
|
1446
|
-
| `<bin> dev` | `
|
|
1447
|
-
| `<bin> build` |
|
|
1448
|
-
| `<bin>
|
|
1449
|
-
| `<bin>
|
|
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
|
-
|
|
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
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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.
|
|
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/
|
|
1682
|
+
"start": "bun --env-file=./x/environments/.prod.env x/dist/index.js"
|
|
1482
1683
|
}
|
|
1483
1684
|
}
|
|
1484
1685
|
```
|
|
1485
1686
|
|
|
1486
|
-
|
|
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
|
-
|
|
1777
|
+
**EN — build order (service):** `typecheck?` → `rm dist` → `bun build .ts` → `declarations?`
|
|
1496
1778
|
|
|
1497
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
1794
|
+
**Build output / derleme çıktısı**
|
|
1503
1795
|
|
|
1504
|
-
|
|
|
1505
|
-
|
|
1506
|
-
|
|
|
1507
|
-
| `
|
|
1508
|
-
|
|
|
1509
|
-
|
|
|
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
|
-
|
|
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
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
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
|
|
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
|
-
|
|
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** |
|
|
1574
|
-
| **Servis** |
|
|
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
|
|
1782
|
-
bun
|
|
1783
|
-
bun run
|
|
1784
|
-
bun run build
|
|
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
|
|
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
|
|