@warlock.js/core 5.25.0 → 5.26.0

package/skills/test-http/SKILL.md

@@ -50,7 +50,7 @@ import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests"
 - Loads `warlock.config.ts` + bootstrap + `filesOrchestrator` (without file watching).
 - Loads `src/config/*.ts`.
 - Loads every module (`routes.ts`, `main.ts`, `events/*.ts`).
-- Starts **ALL** connectors, including HTTP.
+- Starts **ALL** connectors, including HTTP, by default.
 
 Unlike the dev server, it doesn't watch files, doesn't do HMR, doesn't run health checkers. Just a working HTTP endpoint listening on the configured port.
 
@@ -70,6 +70,14 @@ The explicit port wins over `http.port` — including over `HTTP_PORT` in `.env`
 
 The request helpers follow with no extra wiring: the bound port is published as `WARLOCK_TEST_SERVER_PORT`, which the workers inherit, and `getTestServerUrl()` prefers it over their own `.env`-resolved `http.port`. `stopHttpTestServer()` withdraws it.
 
+### API-only suites — `startHttpTestServer({ web: false })`
+
+```ts
+await startHttpTestServer({ web: false });
+```
+
+Use this in `globalSetup` for a suite that exercises API routes only. It still boots the HTTP connector and every other configured connector, but excludes the optional `web` connector before its lifecycle begins. That means web's lazy delegate never constructs `WebConnector`, and Vite is never created. Omitting `web` keeps the default full-stack behavior.
+
 ### The port is preflighted
 
 Before binding, the test server checks the resolved port is free and fails with an instruction if it isn't:

package/skills/use-localization/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-localization
-description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` / `request.t()` / `request.trans()` (look up), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
+description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` (look up; always use it in app code, never `request.t()`), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
 ---
 
 # Warlock — translate keys + pick localized values
@@ -15,7 +15,7 @@ Both pivot on **the request's locale** — auto-detected from headers / query st
 ## The shape
 
 ```ts
-// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.ts)
+// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.json)
 import { groupedTranslations } from "@mongez/localization";
 
 groupedTranslations("products", {
@@ -27,8 +27,7 @@ groupedTranslations("products", {
 import { t } from "@warlock.js/core";
 
 throw new ResourceNotFoundError(t("products.notFound"));
-// or via the request:
-return response.success({ message: request.t("products.created") });
+return response.success({ message: t("products.created") });
 
 // 3. Pick a value from a localized-array column
 import { getLocalized } from "@warlock.js/core";
@@ -37,7 +36,26 @@ const name = getLocalized(product.get("name_translations"));
 // → reads the current request's locale, returns the matching value
 ```
 
-## Declaring translations — `groupedTranslations`
+## Declaring translations — module `locales.json`
+
+Prefer a data-only dictionary in `src/app/<module>/utils/locales.json`. The
+module folder is its default group, so this example registers
+`products.notFound`; a root `$group` string replaces that group when a module
+needs a different namespace. The module loader validates the strict JSON
+shape, flattens nested keys, and rejects duplicate ownership. Do not import the
+file yourself.
+
+```json title="src/app/products/utils/locales.json"
+{
+  "notFound": { "en": "Product not found", "ar": "المنتج غير موجود" },
+  "errors": { "outOfStock": { "en": "Product out of stock", "ar": "المنتج غير متوفر" } }
+}
+```
+
+`utils/locales.ts` with `groupedTranslations` remains supported but is
+deprecated and will be removed in v6. Migrate it with `warlock doctor --fix`.
+
+### Legacy `groupedTranslations`
 
 Every module owns its translation namespace under `src/app/<module>/utils/locales.ts`. The file is auto-loaded at boot — you don't import it from anywhere; the framework picks it up via the module loader.
 
@@ -74,31 +92,25 @@ t("products.outOfStock", { name: "Pen", count: 0 });
 
 Placeholders use the `:name` syntax. The lookup helper substitutes them from the second argument.
 
-## Looking up translations — `t()`, `request.t()`, `request.trans()`
+## Looking up translations — always `t()`
 
-Three calls, same job, slightly different reachability:
+**Rule: app code translates with `t()` from `@warlock.js/core`.** It works everywhere: controllers, services, page and layout loaders, `metadata`, events and jobs. It returns a `string`.
 
 ```ts
-// 1. Top-level helper — works inside or outside a request.
-//    Inside a request: uses request's locale.
-//    Outside: uses the global default locale.
 import { t } from "@warlock.js/core";
 
 t("products.notFound");
 t("products.outOfStock", { name: "Pen", count: 0 });
-
-// 2. On the request object — explicit, scoped to that request.
-request.t("products.notFound");
-
-// 3. Alias for request.t — same behavior.
-request.trans("products.notFound");
 ```
 
-All three lookups go through `@mongez/localization`'s `trans()` under the hood, with the locale pulled from the request context (or the global default).
+- Inside a request (a controller or a page loader) it uses the request's locale. In a page it first checks the route's `locales.json` snapshot, then falls back to module translations (`groupedTranslations` or module `locales.json`).
+- Outside a request (jobs, CLI) it uses the configured default locale.
+- `request.t()` / `request.trans()` are the per-request binding that `t()` delegates to. Don't call them in app code: `t()` gives the same result without threading `request` through services.
+- Don't wrap it in `String(...)`; it is already typed `string`.
 
 ### Web `useTrans()` key checking
 
-When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic groups/keys and placeholders are not inferred.
+When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from module `locales.json` dictionaries and literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic TypeScript groups/keys and placeholders are not inferred.
 
 `useTrans()` now works correctly across hydration (5.15.0): the hydration
 payload ships a `translations` key with the active locale's keywords, and
@@ -144,7 +156,7 @@ export default {
 request.setLocaleCode("ar");
 ```
 
-After this, every `request.t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
+After this, every `t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
 
 ## Localized columns — `getLocalized`
 
@@ -241,6 +253,7 @@ The error's message is locale-aware — the `inject-request-context` middleware
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
+import { t } from "@warlock.js/core";
 
 export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
@@ -248,7 +261,7 @@ export const createProductController: GuardedRequestHandler<CreateProductSchema>
 }) => {
   const product = await createProductService(request.validated());
   return response.success({
-    message: request.t("products.created"),
+    message: t("products.created"),
     product,
   });
 };
@@ -288,11 +301,11 @@ await Product.create({
 GET /products/42?locale=ar
 ```
 
-`request.getLocaleCode()` returns `"ar"` — every `request.t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
+`request.getLocaleCode()` returns `"ar"` — every `t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
 
 ## Gotchas
 
-- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.ts` is picked up by the module loader on boot. Importing it manually causes double-registration warnings.
+- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.json` is picked up by the module loader on boot. Importing legacy `locales.ts` manually causes double-registration warnings.
 - **Group names should match module URL slugs.** `groupedTranslations("products", ...)` for the `/products` module. Mismatch breaks the convention but doesn't throw.
 - **Every key needs every locale.** If a key is missing for the active locale, the lookup falls back to the key string itself (`"products.notFound"` literally appears in the response). Always ship all locales together when adding a key.
 - **`t()` outside a request uses the global default.** `Application.environment === "test"` or background jobs without a request context get the configured `app.localeCode`, not whatever the most recent request used.
@@ -305,8 +318,8 @@ GET /products/42?locale=ar
 
 - [`send-response/SKILL.md`](../send-response/SKILL.md) — error helpers that pair with translated messages (`response.notFound({ error: t("...") })`).
 - [`define-resource/SKILL.md`](../define-resource/SKILL.md) — using `getLocalized` inside resource output for clean per-locale responses.
-- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.ts` file is part of the generated module scaffold.
-- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.ts` is auto-loaded; the suffix is mandatory.
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.json` file is part of the generated module scaffold.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.json` is auto-loaded; the suffix is mandatory.
 
 ## Route-owned web translations (5.17)
 
@@ -320,6 +333,6 @@ GET /products/42?locale=ar
 }
 ```
 
-This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()`, `request.t()`, and `request.trans()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
+This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()` and `t()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
 
-When a route-locales snapshot applies, `request.t()`, `request.trans()`, and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
+When a route-locales snapshot applies, `t()` (through the request binding) and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.