@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.
- package/README.md +676 -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 +142 -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 +39 -0
- package/x/bin/scripts/publish-guard.mjs +113 -0
- package/x/bin/scripts/verify-npm-pack.mjs +12 -0
- package/x/bin/scripts/verify-publish-config.mjs +10 -0
- package/x/bin/scripts/verify-version-bump.mjs +27 -0
- package/x/bin/scripts/version-check.mjs +173 -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.d.ts +12 -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.d.ts +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.d.ts +0 -8
- 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}/index.d.ts +0 -0
- /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}/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/utils/helpers/runtime/dto-types.js → x/dist/utils/helpers/tests/tmp-schema.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,138 @@
|
|
|
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
|
+
## npm publish / npm yayın
|
|
10
11
|
|
|
11
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
{
|
|
195
|
+
{project-root}/ # EN: repo root · TR: proje kökü
|
|
70
196
|
├── package.json
|
|
71
|
-
└── {rootFolderPath}/ # default: x
|
|
72
|
-
├── tmp.yml #
|
|
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
|
|
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 `
|
|
204
|
+
Kaynak kodu `service.paths.source` ile ayrı tutulur (core’da `./source`, serviste `./src` olabilir):
|
|
79
205
|
|
|
80
206
|
```yaml
|
|
81
207
|
configs:
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
`
|
|
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ç |
|
|
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
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
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 (
|
|
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`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 |
|
|
1433
|
-
|
|
1434
|
-
| **CLI
|
|
1435
|
-
| **
|
|
1436
|
-
| **Lib (core repo)** | `@xrystal/core`
|
|
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
|
-
**
|
|
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 ./
|
|
1446
|
-
| `<bin> dev` | `
|
|
1447
|
-
| `<bin> build` |
|
|
1448
|
-
| `<bin>
|
|
1449
|
-
| `<bin>
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
**
|
|
1682
|
+
**EN:** `configs` in `tmp.yml`: `service.*` + `core.*` — single source per service. Core package default: `service.paths.root: x`.
|
|
1464
1683
|
|
|
1465
|
-
**
|
|
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.
|
|
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/
|
|
1707
|
+
"start": "bun --env-file=./x/environments/.prod.env x/dist/index.js"
|
|
1482
1708
|
}
|
|
1483
1709
|
}
|
|
1484
1710
|
```
|
|
1485
1711
|
|
|
1486
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1498
|
-
2. Aksi halde lib default: `bun build` + `tsc` + `tsc-alias` → `./x/dist`
|
|
1743
|
+
**TR — dev vs prod giriş**
|
|
1499
1744
|
|
|
1500
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
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
|
|
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
|
-
|
|
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** |
|
|
1574
|
-
| **Servis** |
|
|
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
|
|
1782
|
-
bun
|
|
1783
|
-
bun run
|
|
1784
|
-
bun run build
|
|
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
|
|
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
|
|