create-warlock 5.34.2 → 5.35.0

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

@@ -1,16 +1,12 @@
 ---
 name: web-code-standards
-description: >-
-  Strict separation-of-concerns standards for Warlock.js src/web pages and
-  components: loaders delegate data and business rules to app services;
-  components delegate all behavior to separate custom-hook files.
-  Use alongside code-standards for web work; skip for backend-only changes.
+description: "Warlock web pages and setup files, component and hook ownership, Mongez forms, accessible controls, locale behavior and UI kit choices. Use when building or reviewing src/web features. Use code-standards instead for shared TypeScript rules."
 ---
 
 # Web code standards
 
 **Applies to:** `src/web/**` in this project. Read
-[`code-standards`](../code-standards/SKILL.md) for the shared TypeScript rules,
+the `code-standards` skill for the shared TypeScript rules,
 and the relevant `@warlock.js/web` skill before using a framework feature.
 This skill adds the web-specific rules; it does not override security or
 module-boundary requirements. When reviewing existing code, identify debt
@@ -45,7 +41,7 @@ ancestor and child dictionaries cannot redefine the same key. Keep legacy
 Within a web feature, use `components/`, `hooks/`, and `utils/` for their
 named purpose; do not create `lib/` as a catch-all. These folders have no
 barrel `index.ts`: import the named component, hook, or helper from its own
-file. Keep types in `types/` when a feature has several contracts, or in one
+file. These exact imports keep client bundles lean and prevent server-only code from being pulled through a barrel. The `code-standards` skill allows sub-folder barrels only for `src/app/**` server modules. Keep types in `types/` when a feature has several contracts, or in one
 `<feature>.types.ts` file when they are small. Do not duplicate a contract in
 both places. Put component props in that dedicated type module by default;
 keep a tiny private prop type beside a component only when extracting it would
@@ -54,13 +50,17 @@ make the feature harder to read.
 ## 1. Keep the page contract, make the implementation thin
 
 Page logic lives in the matching `.setup.ts` file: `config`, `loader`,
-`register`, and `action`/`actions`. UI files contain the default
-component and named components such as `ErrorBoundary`. Pair `layout.tsx` with
+`register`, and `action`/`actions`. The UI file owns its named default
+component; re-export a framework-required named component such as `ErrorBoundary`
+from that component's own file. Pair `layout.tsx` with
 `layout.setup.ts`, `root.tsx` with `root.setup.ts`, and `error.page.tsx` with
 `error.setup.ts`. Use type-only imports from setup for loader/action inference.
 The framework projects browser-safe `register()` code to the client. Put route,
 cache, validation, middleware, metadata, and sitemap policy inside `config`;
-metadata always belongs in `config.metadata`.
+metadata always belongs in `config.metadata`. Do not add an empty setup file
+when a component has no configuration, loader, action, or registration work.
+The starter follows this boundary for root configuration, home route policy
+and translations, and not-found metadata.
 
 Use the config type that matches the module. A page can preserve loader data
 inference for metadata by satisfying `PageConfig<typeof loader>`:
@@ -82,15 +82,18 @@ export const config = {
 ```
 
 ```tsx title="src/web/posts.page.tsx"
-export default function PostsPage() {
-  return <main>Posts</main>;
+import type { PageProps } from "@warlock.js/web";
+import type { loader } from "./posts.setup";
+
+export default function PostsPage({ data }: PageProps<typeof loader>) {
+  return <main>{data.title}</main>;
 }
 ```
 
-When code navigates by a page name, `href(name, params, query)` validates the
-published route table at runtime. `href("posts.indxe")` is a string that
-TypeScript accepts, then the helper throws with the known route names. Generated
-route-name and parameter types are not available in 5.17.
+Use `href(name, params, query)` for named page navigation. Generated declarations
+in `.warlock/typings/web-routes.d.ts` check route names and required path
+parameters when included in the app's TypeScript project; runtime route-table
+validation still applies. Do not widen those contracts to strings or add casts.
 
 Layouts use one `config satisfies LayoutConfig` object for `prefix`,
 `middleware`, `metadata`, and a sitemap default. Roots use one
@@ -133,11 +136,22 @@ queries, aggregations, and domain transformations in the service. A service
 must have a meaningful domain name and own the operation, not exist as a
 generic pass-through for a repository method.
 
-Extract substantive view sections into cohesive components. A component
-that needs any behavior gets a separate feature-named custom-hook file; a
-component with no behavior stays presentational and needs no hook. Split by
-responsibility, not by a mechanical line-count limit. Framework exports
-for logic remain in the setup file even when their work is delegated elsewhere.
+Give every component one responsibility and one reason to change. Define one
+component per file, with a named default export. Extract substantive view
+sections into cohesive components. Put hooks in `hooks/` and pure UI helpers
+in `utils/`, one hook or helper per file, exported by name. A hook owns state,
+effects, handlers, navigation, and client mutations; a utility has no React or
+browser lifecycle dependency. A presentational component needs no hook.
+
+Keep a small piece of logic or a private helper inline only when it is tightly
+coupled to that one component and keeping it there leaves the file small and
+focused. A component file past roughly 150 lines, a second component, or multiple
+helpers is a split signal, not a mechanical line limit: split at ownership
+boundaries, never into arbitrary chunks to meet a count. The one-component rule
+still applies. Framework logic exports remain in setup even when delegated.
+Keep feature CSS beside the feature and import it from the owning presentation
+boundary; keep loading, error, empty, focus, reduced-motion, and locale behavior
+with that boundary.
 
 Preserve the framework's rendering boundary: `root.tsx` owns the document,
 `#vessel` and `<Scripts />`; the loader runs on the server, while the rendered
@@ -153,35 +167,6 @@ output; the page composes `PostArticle`, `PostComments`, and `RelatedPosts`;
 `use-post-comments.ts` owns subscription, state, and handlers for
 `PostComments`. Each piece has one reason to change.
 
-## Setup and component files
-
-Use a setup file when a feature registers framework behavior. The setup file
-owns its `register`, `config`, and `loader` exports; its matching component
-only renders the supplied data. Keep loader inference type-only so it does
-not pull server work into a browser component:
-
-The default starter follows this boundary: `root.setup.ts` owns strict-mode
-configuration, `home/index.setup.ts` owns route policy, its loader, and the
-universal translations `register()`, and `404.setup.ts` owns not-found
-metadata. Do not add an empty setup file when a component has no server
-configuration, loader, or registration work.
-
-```tsx
-import type { PageProps } from "@warlock.js/web";
-import type { loader } from "./posts.setup";
-
-export default function PostsPage({ data }: PageProps<typeof loader>) {
-  return <PostsList posts={data.posts} />;
-}
-```
-
-Each React component file has one named default component. Export hooks,
-utilities, and types by name. A component renders; its feature hook owns
-state, effects, handlers, navigation, and client mutations. A utility stays
-pure and has no React or browser lifecycle dependency. Keep feature CSS beside
-the feature and import it from the owning presentation boundary; keep loading,
-error, empty, focus, reduced-motion, and locale behavior with that boundary.
-
 ## Declaration spacing and local types
 
 Put one blank line after the final import. Keep a short related declaration run
@@ -218,17 +203,17 @@ state starts unset, write `useState<ErrorText>()`; do not add a redundant
   same validated, public data as the page. Keep private routes out of public
   discovery, and do not generate database-backed assets on every GET.
 
-## 3. Components render; custom hooks own all behavior
+## 3. Components render; custom hooks own behavior
 
-**No behavior in React component bodies, even when it is small.** A
-component may declare props, call its dedicated custom hook if needed,
-and render JSX from its props and the hook's returned values. Put `useState`,
+**Delegate behavior to the component's dedicated custom hook by default.** A
+component declares props, calls that hook if needed, and renders JSX from its
+props and the hook's returned values. Put `useState`,
 `useEffect`, subscriptions, timers, browser API calls, derived-value
 calculations, event handlers, mutations, and navigation decisions in a
 separate custom-hook file. Keep pure domain calculations in `src/app`
 services; a hook may call a small pure UI helper outside the component.
-Do not put a one-line callback or inline computation in JSX because it
-"doesn't warrant a hook". Pure presentational components need no hook.
+Use section 1's inline exception only for small, tightly coupled logic;
+reuse or file growth means it belongs in its own hook or utility file.
 JSX conditionals that only select which markup to show are presentation,
 not a license to implement business rules in render.
 
@@ -244,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
@@ -272,6 +262,150 @@ enforce the same policy independently. Use a full navigation when an auth or
 document boundary requires it, otherwise prefer the framework's navigation
 and refresh primitives so state and loader data stay in sync.
 
+### Use Mongez React Form for every form
+
+Always use `Form`, `useFormControl`, and `useSubmitButton` from
+`@mongez/react-form`; the web stack already uses this package, including the
+starter's contact form. Do not add a second form library or manage field
+validation and submission state in parallel React state. Keep those hooks in
+the control's and submit button's dedicated hook files, following section 1.
+
+Declare validation in a browser-safe `<Form schema={schema}>` (Seal implements
+Standard Schema), a control's `schema`, or `useFormControl({ rules: [...] })`.
+The `rules` array contains imported rule objects, never rule-name strings.
+For example, `{ name: "email", type: "email", required: true,
+rules: [requiredRule, emailRule] }` uses Mongez's rules: `requiredRule` needs
+`required: true`, and `emailRule` needs the control's `type: "email"`.
+Put `requiredRule` first. Schema issues map back to registered control names,
+so keep schema paths and control names aligned.
+
+Never use `required`, `pattern`, `min`, `max`, `minLength`, or `type="email"`
+as browser validation, or rely on the browser's constraint UI. These may be
+Mongez rule configuration props; do not spread raw control props onto DOM
+inputs. Mongez v4's `Form` renders `noValidate` by default; keep it enabled
+and preserve it if using a custom form host. A schema-backed email field can
+render `type="text"` with `inputMode="email"` and `autoComplete="email"`,
+leaving email validation entirely to the form.
+
+Render the control's `error` through `getErrorProps()` and connect the field
+with `getInputProps()` (or equivalent explicit wiring for a custom widget).
+This keeps field identity, focus, blur validation, and error announcement in
+the same form contract. For example, each block below is its own file:
+
+```ts title="src/web/contact/contact.schema.ts"
+import { v } from "@warlock.js/seal";
+
+export const contactSchema = v.object({ email: v.email() });
+```
+
+```ts title="src/web/contact/hooks/use-contact-email.ts"
+import { useFormControl } from "@mongez/react-form";
+
+export function useContactEmail() {
+  return useFormControl({ name: "email" });
+}
+```
+
+```tsx title="src/web/contact/components/contact-email.tsx"
+import { useContactEmail } from "../hooks/use-contact-email";
+
+export default function ContactEmail() {
+  const { id, error, getInputProps, getErrorProps } = useContactEmail();
+
+  return (
+    <div>
+      <label htmlFor={id}>Email</label>
+      <input {...getInputProps({ type: "text", inputMode: "email", autoComplete: "email" })} />
+      {error ? <span {...getErrorProps()}>{error}</span> : null}
+    </div>
+  );
+}
+```
+
+Render `ContactEmail` inside `<Form schema={contactSchema} onSubmit={submit}>`;
+the feature hook owns `submit`. The submit button's hook calls
+`useSubmitButton()` and exposes `disabled` and `isSubmitting` to its component.
+For API mutations, use `useSubmitForm` from `@warlock.js/web/form` in the
+feature hook. With generated route declarations and a handler's `responseSchema`,
+`useSubmitForm({ route })` infers the declared success body; `ApiResponse` from
+`@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">`,
+`<input type="radio">`, or `<input type="date">` UI. Build a searchable
+select/dropdown with a search input, a custom checkbox, custom radio
+controls, and a custom date picker. Each field uses `useFormControl` through
+its dedicated hook; a radio group registers one selected value for the group.
+Connect value/checked changes, blur, disabled state, focus refs, validation,
+and errors to that control. Configure a checkbox control with
+`type: "checkbox"` and wire `checked` / `setChecked`. Adapt other widget
+callbacks to `changeValue`; do not blindly spread DOM input props onto a kit
+component with a different callback contract. Keep search text and popup state separate from
+the selected form value. A kit's hidden input for submission is acceptable;
+it must not display native UI or become a second validation source.
+
+Check the existing styling stack and UI kit before building controls:
+
+- With Tailwind and shadcn/ui already installed, compose its components:
+  Command + Popover for a searchable select, Checkbox, RadioGroup, and
+  Calendar + Popover for dates. Keep Mongez as the form owner rather than
+  copying a kit example that introduces another form library.
+- With Tailwind but no shadcn/ui, or with no UI kit, ask the user which kit
+  to use **before installing anything**. Recommend shadcn/ui for Tailwind
+  projects because its composable accessible primitives fit the styling
+  stack. Explain the recommendation for other stacks and wait for the
+  user's choice; never silently add dependencies.
+- With another established kit and no Tailwind, use its corresponding
+  accessible primitives and the same Mongez adapters.
+
+Custom controls must preserve the accessibility native controls supplied.
+Follow the WAI-ARIA APG [combobox/listbox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/),
+[checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/),
+[radiogroup](https://www.w3.org/WAI/ARIA/apg/patterns/radio/), and
+[date picker dialog/grid](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
+patterns. Preserve labels, visible focus, disabled/selected/checked states,
+`aria-invalid`, and error descriptions linked to `getErrorProps()` output.
+Support keyboard search and arrow navigation, Enter selection, Space toggling,
+and Escape dismissal as appropriate. Manage popup entry and focus return;
+a modal date dialog traps focus and its calendar grid supports day/month
+keyboard navigation. Kit composition still needs correct labels, focus refs,
+and announced errors; styling alone does not make a control accessible.
+
 ## 5. Ship usable, localizable presentation
 
 - Use semantic landmarks, headings, buttons, links, and explicit form labels.
@@ -311,12 +445,13 @@ Before approving a web change, ask:
    effects without untangling unrelated responsibilities?
 2. Does every loader obtain data and business decisions from a named app
    service, with models/repositories kept out of the web layer?
-3. Does each behavioral component delegate all state, effects, derived
-   values, event handlers, and mutations to its own custom hook file?
+3. Does each component have one responsibility and its own file, with hooks
+   and helpers extracted except for the small, tightly coupled inline case?
 4. Is the service query bounded, the resource shape intentional, and the
    cache scope safe?
 5. Do refresh, navigation, errors, retries, and cleanup leave the UI correct?
-6. Are forms and interactions accessible and translated to the degree the
-   interface promises?
+6. Do forms use Mongez schema/rules and accessible custom controls, with
+   native validation disabled and the UI kit choice agreed before installation?
+   Are interactions translated to the degree the interface promises?
 7. Are the relevant quality rules enforced or covered by focused tests,
    rather than described only in comments?

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/auth/models/otp/otp.model.ts

@@ -33,9 +33,15 @@ export class OTP extends Model<OTPSchema> {
    * Check if OTP is valid (not expired, not used, not max attempts)
    */
   public get isValid(): boolean {
-    if (this.get("usedAt")) return false;
-    if ((this.get("attempts") ?? 0) >= (this.get("maxAttempts") ?? 0)) return false;
-    if (new Date() > new Date(this.get("expiresAt"))) return false;
+    if (this.get("usedAt")) {
+      return false;
+    }
+    if ((this.get("attempts") ?? 0) >= (this.get("maxAttempts") ?? 0)) {
+      return false;
+    }
+    if (new Date() > new Date(this.get("expiresAt"))) {
+      return false;
+    }
     return true;
   }
 

package/templates/warlock/src/app/auth/services/otp.service.ts

@@ -19,12 +19,24 @@ const DEFAULT_OTP_EXPIRATION: Duration = { minutes: 15 };
 // Parse duration to milliseconds
 function parseDurationToMs(duration: Duration): number {
   let ms = 0;
-  if (duration.milliseconds) ms += duration.milliseconds;
-  if (duration.seconds) ms += duration.seconds * 1000;
-  if (duration.minutes) ms += duration.minutes * 60 * 1000;
-  if (duration.hours) ms += duration.hours * 60 * 60 * 1000;
-  if (duration.days) ms += duration.days * 24 * 60 * 60 * 1000;
-  if (duration.weeks) ms += duration.weeks * 7 * 24 * 60 * 60 * 1000;
+  if (duration.milliseconds) {
+    ms += duration.milliseconds;
+  }
+  if (duration.seconds) {
+    ms += duration.seconds * 1000;
+  }
+  if (duration.minutes) {
+    ms += duration.minutes * 60 * 1000;
+  }
+  if (duration.hours) {
+    ms += duration.hours * 60 * 60 * 1000;
+  }
+  if (duration.days) {
+    ms += duration.days * 24 * 60 * 60 * 1000;
+  }
+  if (duration.weeks) {
+    ms += duration.weeks * 7 * 24 * 60 * 60 * 1000;
+  }
   return ms;
 }
 

package/templates/warlock/src/app/contact/controllers/contact.controller.ts

@@ -19,3 +19,9 @@ export const contactController: RequestHandler<Request<ContactSchema>> = async (
 };
 
 contactController.validation = { schema: contactSchema };
+
+contactController.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/locale/controllers/locale.controller.ts

@@ -14,3 +14,9 @@ export const localeController: RequestHandler<Request<LocaleSchema>> = async ({
 };
 
 localeController.validation = { schema: localeSchema };
+
+localeController.responseSchema = {
+  200: { body: { locale: "string" } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

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

@@ -1,4 +1,5 @@
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { PostResource } from "app/posts/resources/post.resource";
 import { Post } from "../models/post/post.model";
 import { createPostSchema, type CreatePostSchema } from "../schema/create-post.schema";
 
@@ -19,3 +20,9 @@ export const createNewPostController: GuardedRequestHandler<CreatePostSchema> =
 createNewPostController.validation = {
   schema: createPostSchema,
 };
+
+createNewPostController.responseSchema = {
+  201: { body: { post: PostResource } },
+  422: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+  500: { body: { error: { code: "string", message: "string" }, requestId: "string" } },
+};

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

@@ -1,4 +1,7 @@
+import { ResourceNotFoundError } from "@warlock.js/core";
+import { v } from "@warlock.js/seal";
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { PostResource } from "app/posts/resources/post.resource";
 import { Post } from "../models/post/post.model";
 import { updatePostSchema, type UpdatePostSchema } from "../schema/update-post.schema";
 
@@ -6,19 +9,14 @@ export const updatePostController: GuardedRequestHandler<UpdatePostSchema> = asy
   request,
   response,
 }) => {
-  const id = request.int("id");
-
-  if (!id) {
-    return response.notFound();
-  }
-
-  const post = await Post.find(id);
+  const { id, ...input } = request.validated();
+  const post = await Post.first({ publicId: id });
 
   if (!post) {
-    return response.notFound();
+    throw new ResourceNotFoundError("Post not found.");
   }
 
-  await post.save({ merge: request.validated() });
+  await post.save({ merge: input });
 
   return response.success({
     post,
@@ -27,4 +25,12 @@ export const updatePostController: GuardedRequestHandler<UpdatePostSchema> = asy
 
 updatePostController.validation = {
   schema: updatePostSchema,
+  params: v.object({ id: v.string().uuid() }),
+};
+
+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/posts/models/post/migrations/09-01-2026_02-07-51-post.migration.ts

@@ -2,6 +2,7 @@ import { integer, Migration, string, text, timestamp } from "@warlock.js/cascade
 import { Post } from "../post.model";
 
 export default Migration.create(Post, {
+  publicId: string(36).unique(),
   title: string(255),
   description: text(),
   slug: string(255).unique(),

package/templates/warlock/src/app/posts/models/post/post.model.ts

@@ -1,9 +1,15 @@
+import { randomUUID } from "node:crypto";
 import { Model, RegisterModel } from "@warlock.js/cascade";
 import { useComputedSlug } from "@warlock.js/core";
 import { v, type Infer } from "@warlock.js/seal";
 import { PostResource } from "app/posts/resources/post.resource";
 
 export const postSchema = v.object({
+  publicId: v
+    .string()
+    .uuid()
+    .default(() => randomUUID()),
+  authorId: v.number(),
   title: v.string(),
   description: v.string(),
   slug: v.computed(useComputedSlug()),

package/templates/warlock/src/app/posts/resources/post.resource.ts

@@ -2,7 +2,7 @@ import { defineResource } from "@warlock.js/core";
 
 export const PostResource = defineResource({
   schema: {
-    id: "number",
+    id: ["publicId", "string"],
     slug: "string",
     title: "string",
     description: "string",

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

@@ -1,6 +1,7 @@
 import { v, type Infer } from "@warlock.js/seal";
 
 export const updatePostSchema = v.object({
+  id: v.string().uuid(),
   title: v.string(),
   description: v.string(),
   image: v.file().image().maxSize({ size: 2, unit: "MB" }).saveTo("posts"),