create-warlock 5.34.3 → 5.35.0

package/templates/design-system/src/web/design-system/types/control-props.ts

@@ -0,0 +1,46 @@
+import type { FormControlProps } from "@mongez/react-form";
+import type { ReactNode } from "react";
+
+export type ControlProps = Pick<
+  FormControlProps,
+  | "name"
+  | "rules"
+  | "schema"
+  | "validate"
+  | "validateOn"
+  | "onChange"
+  | "onError"
+  | "errors"
+  | "errorKeys"
+  | "disabled"
+  | "readOnly"
+  | "required"
+> & {
+  id: string;
+  label: ReactNode;
+  hint?: ReactNode;
+  error?: ReactNode;
+  value?: unknown;
+  defaultValue?: unknown;
+  placeholder?: string;
+  className?: string;
+  dir?: "ltr" | "rtl";
+  autoComplete?: string;
+  rows?: number;
+  accept?: string;
+  multiple?: boolean;
+};
+export type Choice = { value: string; label: string; disabled?: boolean };
+export type SelectProps = ControlProps & {
+  options: readonly Choice[];
+  searchLabel?: string;
+  emptyLabel?: string;
+  clearLabel?: string;
+};
+export type RadioProps = ControlProps & { options: readonly Choice[] };
+export type CheckProps = ControlProps & { checked?: boolean; defaultChecked?: boolean };
+export type DateProps = ControlProps & {
+  clearLabel?: string;
+  closeLabel?: string;
+  timeLabel?: string;
+};

package/templates/warlock/e2e/home.e2e.ts

@@ -0,0 +1,19 @@
+import { defineE2E, defaultViewports } from "@warlock.js/core/e2e";
+
+export default defineE2E({
+  app: {
+    build: [process.execPath, "node_modules/@warlock.js/core/bin/warlock.js", "build"],
+    start: [process.execPath, "dist/app.js"],
+    exclude: ["storage", "data"],
+  },
+  run: async ({ page }) => {
+    for (const viewport of defaultViewports) {
+      await page.setViewport(viewport);
+      await page.goto("/");
+      await page.waitFor({ selector: "main" });
+      await page.assertAccessible();
+      await page.assertViewport();
+      await page.screenshot("home");
+    }
+  },
+});

package/templates/warlock/package.json

@@ -46,7 +46,7 @@
     "@mongez/agent-kit": "^1.3.1",
     "@types/node": "^25.0.3",
     "typescript": "7.0.2",
-    "vitest": "4.0.5",
+    "vitest": "4.1.10",
     "oxlint": "1.88.0",
     "oxfmt": "0.73.0"
   }

package/templates/warlock/skills/api-design/SKILL.md

@@ -20,17 +20,26 @@ The project uses **three envelope shapes**, one per response kind. Each success
 
 ### 1.1 List endpoints — `{ <pluralResourceName>, pagination }`
 
-The list lands under the **plural name of the module's resource** — `users`, `aiModels`, `orders` — paired with `pagination`. The repository returns the framework's `{ data, pagination }`; the controller re-keys `data` to the plural name so the response is self-describing.
+The list lands under the **plural name of the module's resource** — `users`, `aiModels`, `orders` — paired with `pagination`. The repository returns the framework's `{ data, pagination }`; `listEndpoint` re-keys `data` to the plural name and enforces bounded page controls.
 
 ```typescript
 // ✅ list-users.controller.ts
-export const listUsersController: RequestHandler = async ({ request, response }) => {
-  const { data, pagination } = await listUsersService(request.validated());
+import { listEndpoint, type Request, type RequestHandler } from "@warlock.js/core";
+import type { ListUsersQuery } from "../schema/list-users.schema";
+import { usersRepository } from "../repositories/users.repository";
 
-  return response.success({
-    users: data,
-    pagination,
-  });
+export const listUsersController: RequestHandler<Request<ListUsersQuery>> = async ({
+  request,
+  response,
+}) => {
+  return response.success(
+    await listEndpoint(request, (options) => usersRepository.list(options), {
+      pluralKey: "users",
+      maxLimit: 100,
+      orderBy: ["createdAt"],
+      filters: ["status"],
+    }),
+  );
 };
 ```
 
@@ -113,7 +122,7 @@ Every JSON error response has this shape, with optional `details` for safe field
 }
 ```
 
-Use the matching status helper or throw a framework error from the service. The starter's `http.errorResponse` formatter normalizes helper bodies and framework-generated JSON errors, including unmatched-route 404, validation 422, rate-limit 429, and 500. It removes stacks and masks all 5xx messages. `requestId` is the real Warlock `request.id`, read from the framework's correlation header at the transport boundary; a rejection before Warlock creates a Request uses Fastify's request ID and echoes that same value in the header. Do not generate a new ID inside a controller or use a user ID. See the `observability-and-resilience` skill for trace propagation.
+Use the matching status helper or throw a framework error from the service. The starter's `http.errorResponse` formatter normalizes helper bodies and framework-generated JSON errors, including unmatched-route 404, validation 422, rate-limit 429, and 500. It removes stacks and masks ordinary 5xx messages. Typed `AppError` messages and details are explicitly public and are preserved, including for 5xx responses. `requestId` is the real Warlock `request.id`, read from the framework's correlation header at the transport boundary; a rejection before Warlock creates a Request uses Fastify's request ID and echoes that same value in the header. Do not generate a new ID inside a controller or use a user ID. See the `observability-and-resilience` skill for trace propagation.
 
 ```typescript
 return response.notFound(); // formatter supplies { error: { code, message }, requestId }
@@ -123,7 +132,7 @@ return response.conflict({
 return response.badRequest({ error: { code: "invalidRequest", message: "Invalid request." } });
 ```
 
-`http.errorMapper` translates thrown non-`HttpError` domain errors to `{ status, message?, payload? }`; it does **not** format response bodies. It skips `HttpError` subclasses, returned validation/helper responses, and Fastify's unmatched-route and global rate-limit responses. The starter config uses it to keep unknown thrown errors opaque; `http.errorResponse` handles the final JSON shape for all these paths. HTML error pages, files, and already-started streams retain their own contracts; neither hook rewrites their bodies.
+`http.errorMapper` translates thrown non-`HttpError` domain errors to `{ status, message?, payload? }`; it does **not** format response bodies. It skips `AppError` and `HttpError` subclasses, returned validation/helper responses, and Fastify's unmatched-route and global rate-limit responses. The starter config uses it to keep unknown thrown errors opaque; `http.errorResponse` handles the final JSON shape for all these paths. HTML error pages, files, and already-started streams retain their own contracts; neither hook rewrites their bodies.
 
 Never send a `200 OK` with an `error` field. Never put secrets, stack traces, raw request bodies, or internal database IDs in `details`.
 
@@ -519,3 +528,57 @@ Before merging any controller / route / resource change:
 - [ ] `Cache-Control` set explicitly on `GET` endpoints
 - [ ] Versioning: additive-only by default; explicit `/vN` prefix only when a real breaking change forces it
 - [ ] Deprecated fields announced via `Deprecation` / `Sunset` headers, not silently changed
+
+## Framework helpers for API contracts
+
+Throw `AppError` for new coded domain failures. Its positional constructor is
+`(code, status, publicMessage, details?)`; status must be 400–599. Details are
+typed and must be safe to disclose. Existing `HttpError` subclasses remain
+separate and retain their constructors and payload behavior. Neither needs
+`http.errorMapper`. The starter formatter reads `context.appError` natively and
+keeps this project's `{ error: { code, message }, details?, requestId }` contract.
+Core's unformatted default places details inside `error`; declare the actual
+formatted shape in controller response schemas.
+
+```ts
+import { AppError } from "@warlock.js/core/errors";
+
+throw new AppError("quotaExceeded", 429, "Try again later.", { retryAfter: 30 });
+```
+
+For lists, use the `listEndpoint` example in § 1.1. Type the controller as
+`RequestHandler<Request<ListUsersQuery>>`, attach the query schema with
+`validating: ["query"]`, and configure repository `filterBy`. The helper reads
+only `request.validated()`, defaults to page 1 / limit 20, clamps limits to
+`maxLimit` (100 by default), rejects unlisted sort columns, and forwards only
+named filters as flat repository options. Both `(options) => repo.list(options)`
+and `(options) => repo.listCached(options)` preserve the repository receiver.
+Page pagination is forced; cursor endpoints use a separate controller.
+
+Test the declared response contract through actual HTTP, not just generated
+types. Keep the existing `startHttpTestServer({ port: 0 })` / `setupTest` setup
+and import routes in the worker so its registry contains handler schemas:
+
+```ts
+import { it } from "vitest";
+import { router } from "@warlock.js/core";
+import { assertResponseContracts } from "@warlock.js/core/tests";
+import "../routes";
+
+it("matches user response declarations", async () => {
+  await assertResponseContracts({
+    routes: router.list().filter((route) => route.path === "/users"),
+    cases: () => [{ path: "/users?page=1&limit=10", status: 200 }],
+    requireAllStatuses: true,
+  });
+});
+```
+
+Omit `routes` to discover all registered routes with schemas. Supply fixtures
+for every declared status when using `requireAllStatuses`; parameterized routes
+and methods other than GET always require fixtures. Cases support a concrete
+`path`, `init` (headers/serialized body), and expected `status`. Use isolated
+seed data and cleanup for mutations. Pass `client` for an authenticated client
+or `createTestHttpServer()` instance. Checks reject undeclared statuses, missing
+fields and type mismatches; unsupported computed/builder shapes fail explicitly.
+See core's `test-http` topic for lifecycle, fixture and schema limitations.

package/templates/warlock/skills/testing-strategy/SKILL.md

@@ -21,7 +21,7 @@ This skill governs projects that have **opted into testing**. Testing is **enabl
 - `package.json` has a `test` (or `test:*`) script, **or**
 - a `vitest.config.*` / `vite.config.*` file exists at the project root.
 
-When the `test` feature is selected at scaffold time, both land automatically (Vitest, `@vitest/coverage-v8`, testcontainers, and a per-worker DB/cache test setup).
+When the `test` feature is selected at scaffold time, both land automatically (Vitest, `@vitest/coverage-v8`, and separate unit/integration projects with a per-file runtime by default).
 
 ### 0.1 If testing is enabled, tests are mandatory — not optional
 
@@ -119,7 +119,7 @@ Each test sets up and tears down its own world. No `let users = []` at the top o
 
 Use transactions that roll back, or use testcontainers with a fresh container per file. Never share rows across tests.
 
-The project's testcontainers setup makes "fresh DB per test file" cheap — use it.
+Provide the database fixture in global setup; the framework does not create testcontainers automatically. Give each worker its own database/schema before resetting rows.
 
 ### 3.4 Time and randomness
 
@@ -309,12 +309,12 @@ Co-located with the integration: `src/app/payments/clients/stripe-client.contrac
 src/app/orders/services/
   place-order.service.ts
   place-order.service.spec.ts       ← unit test, mocks repository
-  place-order.service.integration.spec.ts  ← integration, real DB
+  place-order.service.test.ts  ← integration, real DB
 ```
 
 - `.spec.ts` — default suffix; covers unit tests
-- `.integration.spec.ts` — when the test needs real I/O (DB, queue)
-- `.e2e.spec.ts` — full-system journey tests (sparse; one per critical flow)
+- `.test.ts` or a spec inside `tests/` — integration, real I/O (DB, queue)
+- Full-system journeys also use `.test.ts` in the integration project.
 
 Tests live next to the file under test, always. Never in a separate `__tests__/` or `test/` folder — colocation makes the link obvious and survives refactors.
 
@@ -338,3 +338,44 @@ Before merging a change that should include tests (testing enabled — see § 0)
 - [ ] No `.only`, no `.skip` without a tracking ticket
 - [ ] Snapshots reviewed line-by-line if updated
 - [ ] `npm run test --run` passes; `npm run test:coverage` doesn't drop the floor
+
+## Runtime cost and release gates
+
+With `--features=test`, create-warlock delegates to `warlock add test` to generate
+`vite.config.ts`: the `unit` project runs `src/**/*.spec.ts` outside `tests/`
+without framework or HTTP setup; `integration` runs `*.test.ts` and specs under
+`tests/` with `src/test-setup.ts`, global HTTP setup and `src/test-runner.ts`.
+Prefer `npx vitest run --project unit` during the pure service loop.
+
+When a unit needs config values, call
+`setupTest({ mode: "unit", importModule: (file) => import(file) })` from
+`@warlock.js/core/tests` and pair it with `afterAll(teardownTest)`. Config loads
+once per module graph, without hooks, connectors, native loader or fakes.
+Most unit specs need no setup call.
+
+Integration setup defaults to `tests.lifetime: "file"`. For reuse, set
+`lifetime: "worker"` in `src/config/tests.ts`, change the integration project to
+`pool: "forks", isolate: false`, keep the generated runner, and use `vitest run`.
+Watch, threads and isolated graphs are refused. Keep `afterAll(teardownTest)`:
+it marks file boundaries while the runner closes connectors at worker exit.
+Set `tests.resetBetweenFiles` to an async application-owned cleanup callback;
+it runs before every file, including the first, after selected fakes, clock and
+IDs reset. Each worker needs a separate database/schema. Module singletons and
+mocks survive; reset application state and restore mocks explicitly. Worker
+storage is private and does not mirror the shared HTTP server's fake files.
+
+Use `tests.profileSetup: true` or
+`WARLOCK_TEST_PROFILE=1 npx vitest run --project integration` for file timings and
+summaries per worker. Pass `file: expect.getState().testPath` in the setup call.
+`getTestRuntimeStats()` exposes bootstrap and file counts. Generated configs use
+`recommendedTestWorkers()` from `@warlock.js/core/vite` to respect visible cgroup
+v2 CPU quotas; reduce `maxWorkers` further for database or memory contention.
+
+Release gate:
+
+```bash
+npx warlock test --changed --since "$LAST_RELEASE_REF"
+npx vitest run --project integration
+# Nightly:
+npx vitest run
+```

package/templates/warlock/skills/web-code-standards/SKILL.md

@@ -229,6 +229,11 @@ Avoid copying props into hook state without a plan for refresh and client
 navigation. Avoid setting another state variable inside a state-updater
 callback. Prefer deriving display values from one authoritative state.
 
+**State ownership.** Loader data is server truth. UI interaction state (open,
+selection, draft input) lives in the component's own hook. Shared client state
+goes only through a named store module, never a global variable or a copy
+spread across components. Never copy props into state without a refresh plan.
+
 Effects own their subscriptions and timers: unsubscribe, cancel, or ignore
 stale async work on unmount or entity change. A failed script/socket load
 must not leave a permanently rejected shared promise or silently disable a
@@ -326,6 +331,39 @@ feature hook. With generated route declarations and a handler's `responseSchema`
 `@warlock.js/web` reads a declared status body. Do not replace this inference
 with casts. Server endpoints must still validate input independently.
 
+### Use the shared design-system controls
+
+For Tailwind + shadcn projects, use the controls in `src/web/design-system/`:
+TextInput, EmailInput, PasswordInput, TextareaInput, SelectInput (search),
+MultiSelectInput, DatePickerInput, TimePickerInput, DateTimePickerInput,
+CheckboxInput, RadioInput, SwitchInput, FileInput, and SubmitButton.
+Import each component directly, for example
+`import TextInput from "web/design-system/components/text-input";` — no barrels.
+Use `Form` from `@mongez/react-form` directly. Every control requires a stable
+explicit `id`, `name`, and visible `label`, and accepts `hint`, `error`,
+Mongez `schema`/`rules`, and `validateOn`. Put behavior in design-system hooks
+and props in design-system types. See the Web `build-accessible-controls`
+topic for keyboard/focus, RTL, reset and calendar-date semantics.
+
+```tsx
+import { Form } from "@mongez/react-form";
+import TextInput from "web/design-system/components/text-input";
+import SubmitButton from "web/design-system/components/submit-button";
+
+export default function ProfileForm() {
+  return (
+    <Form>
+      <TextInput id="profile-name" name="name" label="Name" hint="Display name" />
+      <SubmitButton id="profile-save" name="save" label="Save" />
+    </Form>
+  );
+}
+```
+
+The full-stack preset and shadcn selection scaffold these controls. Existing
+Tailwind apps can run `npx warlock add design-system`; install Tailwind first
+with `npx warlock add tailwind` when missing. Existing files are preserved.
+
 ### Build custom controls with the project's UI kit
 
 Do not render native `<select>`, `<input type="checkbox">`,

package/templates/warlock/src/app/auth/controllers/forgot-password.controller.ts

@@ -23,3 +23,9 @@ forgotPasswordController.validation = {
     email: v.email(),
   }),
 };
+
+forgotPasswordController.responseSchema = {
+  200: { body: { message: "string" } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/login.controller.ts

@@ -1,4 +1,5 @@
 import { type Request, type RequestHandler } from "@warlock.js/core";
+import { UserResource } from "app/users/resources/user.resource";
 import { loginSchema, type LoginSchema } from "../schema/login.schema";
 import { loginService } from "../services/auth.service";
 
@@ -23,3 +24,19 @@ loginController.description = "User Login";
 loginController.validation = {
   schema: loginSchema,
 };
+
+// The starter disables refresh tokens; add tokens.refreshToken when enabling them.
+loginController.responseSchema = {
+  200: {
+    body: {
+      user: UserResource,
+      tokens: {
+        accessToken: { token: "string", expiresAt: "string" },
+      },
+    },
+  },
+  401: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  403: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/logout-all.controller.ts

@@ -17,3 +17,9 @@ export const logoutAllController: GuardedRequestHandler = async ({ request, resp
 };
 
 logoutAllController.description = "Logout from all devices";
+
+logoutAllController.responseSchema = {
+  200: { body: { message: "string" } },
+  401: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/logout.controller.ts

@@ -19,3 +19,9 @@ export const logoutController: GuardedRequestHandler = async ({ request, respons
 };
 
 logoutController.description = "User Logout";
+
+logoutController.responseSchema = {
+  200: { body: { message: "string" } },
+  401: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/me.controller.ts

@@ -1,4 +1,5 @@
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { UserResource } from "app/users/resources/user.resource";
 
 /**
  * Get current user controller
@@ -16,3 +17,9 @@ export const meController: GuardedRequestHandler = async ({ request, response })
 };
 
 meController.description = "Get Current User";
+
+meController.responseSchema = {
+  200: { body: { user: UserResource } },
+  401: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/refresh-token.controller.ts

@@ -24,3 +24,15 @@ refreshTokenController.validation = {
     refreshToken: v.string(),
   }),
 };
+
+refreshTokenController.responseSchema = {
+  200: {
+    body: {
+      accessToken: { token: "string", expiresAt: "string" },
+      refreshToken: { token: "string", expiresAt: "string" },
+    },
+  },
+  401: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/auth/controllers/reset-password.controller.ts

@@ -21,3 +21,9 @@ resetPasswordController.description = "Reset password with OTP";
 resetPasswordController.validation = {
   schema: resetPasswordSchema,
 };
+
+resetPasswordController.responseSchema = {
+  200: { body: { message: "string" } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

package/templates/warlock/src/app/home/controllers/home-page.controller.ts

@@ -10,3 +10,7 @@ export const homePageController: RequestHandler = async ({ response }) => {
 };
 
 homePageController.description = "Welcome Home Page";
+
+homePageController.responseSchema = {
+  200: { body: { message: "string", version: "string", docs: "string" } },
+};

package/templates/warlock/src/app/posts/controllers/update-post.controller.ts

@@ -32,4 +32,5 @@ updatePostController.responseSchema = {
   200: { body: { post: PostResource } },
   422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
   500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  404: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
 };

package/templates/warlock/src/app/shared/utils/format-http-error-response.ts

@@ -11,7 +11,19 @@ const statusCodes: Record<number, string> = {
 };
 
 /** Convert framework JSON errors to the project's public error contract. */
-export function formatHttpErrorResponse({ status, body, requestId }: HttpErrorResponseContext) {
+export function formatHttpErrorResponse({
+  status,
+  body,
+  requestId,
+  appError,
+}: HttpErrorResponseContext) {
+  if (appError) {
+    return {
+      error: { code: appError.code, message: appError.publicMessage },
+      ...(appError.details === undefined ? {} : { details: appError.details }),
+      requestId,
+    };
+  }
   const source = isRecord(body) ? body : {};
   const error = isRecord(source.error) ? source.error : {};
   const serverFault = status >= 500;

package/templates/warlock/src/app/users/controllers/create-new-user.controller.ts

@@ -35,4 +35,5 @@ createNewUserController.responseSchema = {
   201: { body: { message: "string", user: UserResource } },
   422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
   500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  400: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
 };

package/templates/warlock/warlock.config.ts

@@ -6,6 +6,7 @@ import {
 import { defineConfig } from "@warlock.js/core";
 
 export default defineConfig({
+  build: { budgets: { page: { js: "150kb", css: "50kb" }, mode: "error" } },
   cli: {
     commands: [registerJWTSecretGeneratorCommand(), registerAuthCleanupCommand()],
   },