@warlock.js/core 4.0.174 → 4.1.2

package/skills/wire-socket/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: wire-socket
+description: 'Configure Socket.IO via `src/config/socket.ts`, reach the live server through `getSocketServer()` (or `app.socket` post-bootstrap), register `connection` handlers once the late-phase socket connector has booted, emit from controllers/services, use rooms and namespaces. Triggers: `app.socket`, `getSocketServer`, `SocketOptions`, `socket.io` `Server`, `socket.join`, `socket.to`, `io.of`, `io.use`; "add realtime chat", "emit socket events from a service", "use rooms and namespaces", "per-socket JWT auth". Skip: connector lifecycle — `@warlock.js/core/add-connector/SKILL.md`; app context accessors — `@warlock.js/core/use-app-context/SKILL.md`; competing libs `ws`, `socket.io` direct without Warlock connector, `uWebSockets.js`.'
+---
+
+# Warlock — wire a Socket.IO server
+
+Warlock wraps `socket.io`'s `Server` in a connector. That connector is in the **late** lifecycle phase — it boots **after** your app code (every module's `main.ts`, `routes.ts`, `events.ts`) has already been imported. The order is: early-phase connectors (logger, mailer, database, cache, storage) → app code is imported → late-phase connectors (http, then socket) boot. The socket server lives in the framework's DI container once it boots — reach it through `app.socket` or `getSocketServer()`.
+
+The practical consequence: **`app.socket` is not yet populated while a module's `main.ts` is being evaluated at import time.** Register connection handlers from code that runs *after* bootstrap completes — a controller, a service, a job — or guard with `getSocketServer()`. (Unlike the router, which collects routes into a standalone registry that the http connector scans on boot, the socket connector does not harvest listeners registered at import time — it just constructs the `Server`.)
+
+## The shape
+
+```ts title="src/config/socket.ts"
+import type { SocketOptions } from "@warlock.js/core";
+
+const socketOptions: SocketOptions = {
+  options: {
+    cors: { origin: "*" },
+  },
+};
+
+export default socketOptions;
+```
+
+Config the server in `src/config/socket.ts`, then attach handlers once the server is live:
+
+```ts title="src/app/chat/setup-chat-socket.ts — called after bootstrap, or guarded"
+import { getSocketServer } from "@warlock.js/core";
+
+export function setupChatSocket() {
+  const io = getSocketServer();
+  if (!io) return; // socket connector hasn't booted yet
+
+  io.on("connection", (socket) => {
+    socket.on("message", (payload) => {
+      socket.broadcast.emit("message", payload);
+    });
+  });
+}
+```
+
+The framework auto-loads each module's `main.ts` once at boot, but **before** the socket connector starts — so don't read `app.socket` at the top level of `main.ts`.
+
+## Configuration — `src/config/socket.ts`
+
+```ts
+export type SocketOptions = {
+  port?: number;     // standalone port (only if HTTP is disabled)
+  options?: ServerOptions;  // forwarded as the 2nd arg to socket.io's `new Server(httpServer, options)`
+};
+```
+
+Default: socket.io is mounted on the same HTTP server Warlock boots — no separate port. Set `port` only if you want a dedicated socket server (the connector then creates its own HTTP/HTTPS server and listens on that port).
+
+The `options` block is forwarded verbatim as the second argument to socket.io's `new Server(server, options)`, so it accepts the Socket.IO `ServerOptions` — CORS, transports, pingInterval, path, etc. Common shape:
+
+```ts
+const socketOptions: SocketOptions = {
+  options: {
+    cors: { origin: "*" },
+    transports: ["websocket", "polling"],
+    pingInterval: 25000,
+    pingTimeout: 60000,
+  },
+};
+```
+
+## Reaching the server — `app.socket` vs `getSocketServer()`
+
+Two ways to get the `socket.io` `Server` instance:
+
+```ts
+// 1. Via the app runtime accessor — reads container.get("socket")
+import { app } from "@warlock.js/core";
+
+const io = app.socket;            // → Server, or undefined before the socket connector boots
+
+// 2. Via the safe getter — explicit null when the connector hasn't started
+import { getSocketServer } from "@warlock.js/core";
+
+const io = getSocketServer();     // → Server | null
+```
+
+Both read the same DI container slot. `app.socket` is a getter that returns `container.get("socket")` — that's `undefined` (it does **not** throw) until the socket connector has booted. `getSocketServer()` checks `container.has("socket")` and returns `null` if absent. Prefer `getSocketServer()` plus a null-guard at any call site that *might* run before the connector boots (module-load code, `main.ts` top level, scripts that skip bootstrap). From a controller, a service, a job — anything downstream of a completed bootstrap — `app.socket` is populated and safe to read directly.
+
+## Wiring `connection` handlers
+
+The socket connector boots *after* app code is imported, and it does not collect listeners registered at `main.ts` import time. So register handlers from a function that runs once the server is live — call it from post-bootstrap code, or guard it:
+
+```ts title="src/app/chat/setup-chat-socket.ts"
+import { getSocketServer } from "@warlock.js/core";
+
+export function setupChatSocket() {
+  const io = getSocketServer();
+  if (!io) return; // not booted yet — nothing to attach to
+
+  io.on("connection", (socket) => {
+    console.log("client connected", socket.id);
+
+    socket.on("disconnect", () => {
+      console.log("client disconnected", socket.id);
+    });
+  });
+}
+```
+
+Reading `app.socket` (or `getSocketServer()`) at the top level of `main.ts` returns nothing useful — the server isn't constructed yet. Defer the read to runtime.
+
+## Emitting from a controller or service
+
+Once the server is up, anything with access to `app.socket` can emit:
+
+```ts title="src/app/notifications/services/notify-user.service.ts"
+import { app } from "@warlock.js/core";
+import type { User } from "app/users/models/user";
+
+export async function notifyUserService(user: User, payload: unknown) {
+  app.socket.to(`user:${user.id}`).emit("notification", payload);
+}
+```
+
+Then from a controller:
+
+```ts
+import type { GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import { notifyUserService } from "../services/notify-user.service";
+
+export const sendNotificationController: GuardedRequestHandler = async (request, response) => {
+  await notifyUserService(request.user, request.input("payload"));
+  return response.success({ delivered: true });
+};
+```
+
+The HTTP request handles the write side; the socket emit handles the realtime fan-out. Same pattern works for messages, status changes, presence updates.
+
+## Rooms
+
+Rooms are socket.io's per-connection labels — emit to a room and every socket joined to it receives the event:
+
+```ts
+io.on("connection", (socket) => {
+  socket.on("subscribe", async (channelId: string) => {
+    socket.join(`channel:${channelId}`);
+  });
+
+  socket.on("unsubscribe", async (channelId: string) => {
+    socket.leave(`channel:${channelId}`);
+  });
+});
+
+// From anywhere with `io`:
+io.to(`channel:42`).emit("message", { text: "…" });
+```
+
+Typical room-key conventions: `user:<id>`, `channel:<id>`, `org:<id>`. Join on connection (often after auth), leave on disconnect or explicit unsubscribe.
+
+## Namespaces
+
+For larger apps, split socket surfaces into namespaces — each is an isolated event channel. Reach the live server first, then carve the namespace off it:
+
+```ts title="src/app/chat/setup-chat-socket.ts"
+import { getSocketServer } from "@warlock.js/core";
+
+export function setupChatSocket() {
+  const io = getSocketServer();
+  if (!io) return;
+
+  const chat = io.of("/chat");
+
+  chat.on("connection", (socket) => {
+    socket.on("message", (payload) => {
+      chat.emit("message", payload);
+    });
+  });
+}
+```
+
+Client connects to the namespace explicitly: `io("https://your-host/chat")`. Use one namespace per feature when the event sets diverge (chat vs notifications vs presence vs admin).
+
+## Per-socket auth
+
+Hand the socket the JWT (or session token) at the handshake; verify in middleware before any `connection` handler runs. Register the middleware on the live server, same as handlers:
+
+```ts
+import { authService } from "@warlock.js/auth";
+import { getSocketServer } from "@warlock.js/core";
+
+export function setupAuthedSocket() {
+  const io = getSocketServer();
+  if (!io) return;
+
+  io.use(async (socket, next) => {
+    try {
+      const token = socket.handshake.auth?.token as string | undefined;
+
+      if (!token) {
+        return next(new Error("missing-token"));
+      }
+
+      const user = await authService.verifyAccessToken(token);
+
+      if (!user) {
+        return next(new Error("invalid-token"));
+      }
+
+      (socket.data as { user: typeof user }).user = user;
+      next();
+    } catch (error) {
+      next(error as Error);
+    }
+  });
+
+  io.on("connection", (socket) => {
+    const user = (socket.data as { user: User }).user;
+
+    socket.join(`user:${user.id}`);
+  });
+}
+```
+
+Socket middleware runs once at handshake — if it errors, the connection is rejected and `connection` never fires. Verify exact auth API against `@warlock.js/auth` source; the example above uses the typical token-verification flow.
+
+## Common patterns
+
+### Broadcast a model update to a room
+
+```ts title="src/app/messages/services/post-message.service.ts"
+import { app } from "@warlock.js/core";
+import { Message } from "../models/message";
+
+export async function postMessageService(input: { channel_id: string; body: string; user: User }) {
+  const message = await Message.create({
+    channel_id: input.channel_id,
+    body: input.body,
+    author_id: input.user.id,
+  });
+
+  app.socket.to(`channel:${input.channel_id}`).emit("message:new", message.toJSON());
+
+  return message;
+}
+```
+
+### Typed event payloads
+
+Socket.IO supports typed events via generic parameters on `Server`:
+
+```ts
+import type { Server } from "socket.io";
+
+type ClientToServer = {
+  subscribe: (channelId: string) => void;
+  message: (payload: { channelId: string; body: string }) => void;
+};
+
+type ServerToClient = {
+  "message:new": (message: { id: string; body: string }) => void;
+};
+
+const io = app.socket as Server<ClientToServer, ServerToClient>;
+```
+
+You're casting because the framework exposes a non-generic `Server`. Cast once at the call site and you get typed `emit` / `on` for that scope.
+
+### Emit from outside a request
+
+CLI commands, scheduled jobs, queue workers — anything running outside an HTTP request — still reaches `app.socket` the same way. As long as the socket connector booted, the accessor is live.
+
+## Gotchas
+
+- **`app.socket` is `undefined` before the connector starts — it does not throw.** Because socket is a *late*-phase connector, this includes the top level of `main.ts` (imported before late connectors boot). Reading `app.socket.on(...)` there throws a `TypeError` on `undefined`, not a helpful framework error. Safe in controllers, services, jobs, and any post-bootstrap code; use `getSocketServer()` + a null-guard everywhere else.
+- **Register handlers from post-bootstrap code, not at `main.ts` import time.** The socket connector constructs the `Server` but doesn't harvest listeners you registered at import time (unlike routes, which the http connector scans on boot). Wire handlers from a setup function invoked after bootstrap, or guard the registration with `getSocketServer()`.
+- **Re-registration can double-bind.** If a setup function runs more than once (HMR, repeated calls), `io.on("connection", ...)` stacks handlers — guard with an idempotency flag if you observe duplicates.
+- **CORS matters.** Browsers fail Socket.IO connections silently if CORS rejects the upgrade request. Set `options.cors.origin` to the deployed frontend's origin in production.
+- **Rooms are per-socket-instance.** A user logged in from two devices has two sockets. Joining `user:<id>` from both is what makes `app.socket.to("user:42").emit(...)` reach both devices.
+- **`io.emit(...)` broadcasts to every connected socket.** Use `to(room).emit(...)` unless that's actually what you want.
+- **Don't keep handlers stateful.** Socket events come in any order; treat each as idempotent or guard with a transaction. Stateful in-memory accumulators die with the process and don't survive horizontal scale.
+
+## See also
+
+- [`use-app-context/SKILL.md`](../use-app-context/SKILL.md) — `app.socket` runtime accessor + `Application` static metadata.
+- [`add-connector/SKILL.md`](../add-connector/SKILL.md) — how connectors order their boot sequence around your modules.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where socket-related code lives (a setup function for handler registration, `services/` for emit sites).

package/skills/write-cli-command/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: write-cli-command
+description: 'Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.'
+---
+
+# Warlock — write a CLI command
+
+A Warlock CLI command is a `CLICommand` instance produced by the `command()` factory. Three ways to surface it:
+
+1. **Project commands** — drop a `<name>.command.ts` file under `src/app/<module>/commands/` with the `CLICommand` as the default export. Auto-discovered.
+2. **Plugin commands** — exposed as a factory function (`registerXCommand()`) from a package, registered via `warlock.config.ts > cli.commands: [...]`.
+3. **Framework commands** — `migrate`, `seed`, `dev`, `build`, `generate.*`, `storage.put`, `drop.tables`, etc. Built into core. You don't write these; you copy their shape.
+
+## The shape
+
+```ts title="src/app/users/commands/promote-admin.command.ts"
+import { command } from "@warlock.js/core";
+
+export default command({
+  name: "users.promote",
+  description: "Promote a user to admin by email",
+  alias: "up",
+  preload: {
+    env: true,
+    config: ["database"],
+    connectors: ["database", "logger"],
+  },
+  options: [
+    {
+      text: "--email, -e",
+      description: "User email address",
+      required: true,
+    },
+  ],
+  action: async ({ options }) => {
+    // …business work using framework services
+    console.log(`Promoting ${options.email}…`);
+  },
+});
+```
+
+Run it: `yarn warlock users.promote --email=hasan@example.com` (or `yarn warlock up -e hasan@example.com`).
+
+## `CLICommandOptions` — the factory input
+
+| Field         | Type                          | Required | Notes                                                                                          |
+| ------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `name`        | `string`                      | yes      | Dot notation OK (`db.seed`, `jwt.generate`). May include positional placeholders (`name <arg>`). |
+| `description` | `string`                      |          | Shown in `warlock --help` and `warlock <cmd> --help`.                                          |
+| `alias`       | `string`                      |          | Short name (`m` for `migrate`).                                                                |
+| `action`      | `(data) => void \| Promise`   | yes      | Runs after preloaders. `data` is `{ args, options }`.                                          |
+| `preAction`   | `(data) => void \| Promise`   |          | Runs **before** preloaders — banner, input validation.                                         |
+| `preload`     | `CLICommandPreload`           |          | What to load before `action` runs. See below.                                                  |
+| `persistent`  | `boolean`                     |          | `true` for long-running commands (dev server). Skips the auto-exit.                            |
+| `options`     | `CLICommandOption[]`          |          | Flag definitions. See below.                                                                   |
+
+## Options — flag shape
+
+Each entry in the `options` array:
+
+```ts
+{
+  text: "--fresh, -f",            // "--key", "-k", "--key, -k", or "-k, --key"
+  description: "Drop tables first",
+  type: "boolean",                // "string" (default) | "boolean" | "number"
+  defaultValue: false,            // applied if flag missing
+  required: false,                // 1 missing required → command refuses to run
+}
+```
+
+The parser auto-extracts `name` (long form, camelCased) and `alias` (short form) from `text`. Inside `action`, read via `options.fresh` — kebab-case becomes camelCase (`--no-cache` → `options.noCache`).
+
+`--help`/`-h` are reserved — the framework intercepts them to print per-command help.
+
+## Preload — lazy-loaded subsystems
+
+Commands run with a minimal world by default. Opt in to what you need so the command stays fast:
+
+```ts
+preload: {
+  env: true,                              // load .env
+  config: ["database", "log"],            // load these src/config/*.ts files (or `true` for all)
+  bootstrap: true,                        // full bootstrap (env + app + prestart hooks)
+  connectors: ["database", "cache"],      // start these connectors (or `true` for all early-phase)
+  prestart: true,                         // run src/app/prestart.ts after config
+  warlockConfig: true,                    // load warlock.config.ts
+  runtimeStrategy: "production",          // force-set
+  environemnt: "production",              // force-set (note: original typo preserved)
+}
+```
+
+Connector names: `"logger"`, `"mailer"`, `"http"`, `"database"`, `"cache"`, `"storage"`, `"communicator"` (herald), `"socket"`. Pass `connectors: true` to start every `Early`-phase connector — `http` and `socket` are `Late` phase and stay off unless you list them explicitly.
+
+Picking the right preload matters: `migrate` only needs database + logger, but `seed` runs full `bootstrap: true` because seeds touch app models. Inspect `@warlock.js/core/src/cli/commands/*.ts` for canonical pairings.
+
+## Inside `action` — `CommandActionData`
+
+```ts
+action: async ({ args, options }) => {
+  // args: positional, e.g. `warlock storage.put ./uploads backups/` → args = ["./uploads", "backups/"]
+  // options: flags, e.g. `--driver=r2 --concurrency=5` → { driver: "r2", concurrency: "5" }
+};
+```
+
+For positional capture in `name`, declare slots: `name: "storage.put <localPath> [destination]"` — `<>` required, `[]` optional. Storage-put uses this exact pattern.
+
+## Registering external-package commands
+
+The convention is to export a **factory function** that returns a fresh `CLICommand`. Why a factory and not the instance directly? It defers any side-effects (like loading config) to when the command is actually wired into the CLI, and it keeps each project free to skip commands it doesn't want.
+
+```ts title="@warlock.js/auth/src/commands/jwt-secret-generator-command.ts"
+import { command } from "@warlock.js/core";
+import { generateJWTSecret } from "../services/generate-jwt-secret";
+
+export function registerJWTSecretGeneratorCommand() {
+  return command({
+    name: "jwt.generate",
+    description: "Generate JWT Secret key in .env file",
+    action: generateJWTSecret,
+  });
+}
+```
+
+Wire it in the project's `warlock.config.ts`:
+
+```ts title="warlock.config.ts"
+import { registerJWTSecretGeneratorCommand } from "@warlock.js/auth";
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  cli: {
+    commands: [registerJWTSecretGeneratorCommand()],
+  },
+});
+```
+
+## Output and exit codes
+
+By default, the framework prints `Executing <name>…`, runs your `action`, then prints `Done in <ms>ms` and `process.exit(0)`. Throwing exits with `1` and prints the error. If `persistent: true`, the framework keeps the process alive (no auto-exit on success; errors are logged but don't crash).
+
+For colored output, the canonical helper is `colors` from `@mongez/copper` (re-exported from `@warlock.js/core`):
+
+```ts
+import { colors } from "@warlock.js/core";
+
+console.log(colors.green("✓") + " user promoted");
+```
+
+## Built-in framework commands
+
+The framework ships a fixed set of commands you call but don't author. Knowing their flags up front saves a `--help` round-trip.
+
+> For `warlock dev` / `warlock build` / `warlock start` — see [`run-app/SKILL.md`](../run-app/SKILL.md). Everything below covers the rest.
+
+### Database + migrations
+
+| Command  | Flags / args                                    | Preloads                       |
+| -------- | ----------------------------------------------- | ------------------------------ |
+| `warlock migrate` | `--list` (just list pending), `--fresh` / `-f` (drop tables first) | database, logger          |
+| `warlock seed` | `--name <pattern>` (run seeds matching the pattern) | full bootstrap (env, configs, app modules) |
+| `warlock create-database <name>` | bare positional `<name>`        | database                       |
+| `warlock drop.tables` | `--force, -f` (skip confirmation prompt) | database, logger          |
+| `warlock db.indexes` | builds DB indexes for every registered model    | database                  |
+
+### Scaffolding
+
+The `generate.*` family covers every module piece:
+
+```
+warlock generate.module <name>           (alias: gen.m)  — flags: --minimal, --force
+warlock generate.controller <m>/<n>      (alias: gen.c)  — flags: --with-validation, --force
+warlock generate.service <m>/<n>         (alias: gen.s)
+warlock generate.model <m>/<n>           (alias: gen.md) — flags: --with-resource, --table <name>, --timestamps
+warlock generate.repository <m>/<n>      (alias: gen.r)
+warlock generate.resource <m>/<n>        (alias: gen.rs)
+warlock generate.migration <model-path>  (alias: gen.mig)
+warlock generate.typings
+warlock generate                         (alias: g)      — interactive picker
+```
+
+`<m>/<n>` is `<module>/<name>` (e.g. `products/create-product`). See [`create-module/SKILL.md`](../create-module/SKILL.md) for the full scaffolding flow.
+
+### Feature installation
+
+`warlock add <features...>` installs framework-adjacent features through a curated registry — bundles npm dependencies + scaffold files + tsconfig patches + package.json scripts in one call. Featured names (from `add-command.action.ts`):
+
+| Feature       | Installs                                                                                            |
+| ------------- | --------------------------------------------------------------------------------------------------- |
+| `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json` |
+| `react`       | `react` + `react-dom` + types                                                                       |
+| `image`       | `sharp` (for the `Image` class)                                                                     |
+| `mail`        | `nodemailer` + types                                                                                |
+| `ses`         | `@aws-sdk/client-sesv2`                                                                             |
+| `mongodb`     | `mongodb` driver                                                                                    |
+| `postgres`    | `pg`                                                                                                |
+| `mysql`       | `mysql2`                                                                                            |
+| `redis`       | `redis`                                                                                             |
+| `s3`          | `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`                     |
+| `scheduler`   | `@warlock.js/scheduler`                                                                             |
+| `swagger`     | `@warlock.js/swagger`                                                                               |
+| `postman`     | `@warlock.js/postman`                                                                               |
+| `herald`      | `@warlock.js/herald` + `amqplib` + types; ejects `src/config/communicator.ts`                       |
+| `test`        | `vitest` + `@mongez/vite` + coverage; drops `test-global-setup.ts` / `test-setup.ts` / `vite.config.ts` |
+
+Run `warlock add --list` to see what's currently registered. Pass `--packageManager <yarn\|pnpm\|npm>` to override auto-detection (defaults to whichever lockfile is present).
+
+### Misc
+
+| Command  | Purpose                                                     |
+| -------- | ----------------------------------------------------------- |
+| `warlock storage.put <localPath> [destination]` | Upload a local file to the default storage disk |
+| `warlock jwt.generate` | Generate a JWT secret in `.env` (from `@warlock.js/auth`)            |
+
+## Common patterns
+
+### Single-shot maintenance task
+
+```ts title="src/app/orders/commands/recompute-totals.command.ts"
+import { command } from "@warlock.js/core";
+import { recomputeAllOrderTotals } from "../services/recompute-all-order-totals.service";
+
+export default command({
+  name: "orders.recompute",
+  description: "Recompute totals for all orders",
+  preload: {
+    env: true,
+    bootstrap: true,
+    connectors: ["database", "logger"],
+  },
+  action: async () => {
+    const count = await recomputeAllOrderTotals();
+    console.log(`Recomputed ${count} orders`);
+  },
+});
+```
+
+### Stats report
+
+```ts
+export default command({
+  name: "stats.report",
+  description: "Print daily stats to stdout",
+  preload: { env: true, config: ["database"], connectors: ["database"] },
+  options: [
+    { text: "--from, -f", description: "Start date (YYYY-MM-DD)" },
+    { text: "--to, -t", description: "End date (YYYY-MM-DD)" },
+  ],
+  action: async ({ options }) => {
+    const stats = await buildReport(options.from as string, options.to as string);
+    console.table(stats);
+  },
+});
+```
+
+### Confirm-before-destroy
+
+```ts
+export default command({
+  name: "users.purge",
+  description: "Hard-delete soft-deleted users older than 90 days",
+  options: [{ text: "--force, -f", description: "Skip confirmation", type: "boolean" }],
+  preAction: async ({ options }) => {
+    if (!options.force) {
+      throw new Error("Refusing to run without --force");
+    }
+  },
+  preload: { env: true, bootstrap: true, connectors: ["database", "logger"] },
+  action: async () => {
+    await purgeStaleSoftDeletedUsers();
+  },
+});
+```
+
+`preAction` runs *before* preloaders — cheap way to bail out without spinning up the database.
+
+## Gotchas
+
+- **Default-export the `CLICommand`** for project commands. The loader does `await import(...)` and reads `.default`.
+- **Don't put logic at module top level.** The file gets imported during the commands scan (`warlock --warm-cache`). Anything outside `action` runs at scan time, possibly before any config or env is loaded.
+- **Required options block execution.** If `required: true` and the user omits the flag, the framework prints `Missing required options:` and exits `1` before `action` runs.
+- **Connectors are not free.** `connectors: true` boots the database, cache, storage, etc. For a print-version-and-exit command, leave `preload` undefined.
+- **`name` field with positional slots** (`name: "storage.put <localPath>"`) — the *registered* name is still `storage.put` (the first whitespace-separated token), so look up + alias work normally. Slots are only documentation/help-output.
+- **Aliases must be unique across plugin + framework + project.** The first registration wins; later collisions silently overwrite the map entry.
+
+## See also
+
+- [`run-app/SKILL.md`](../run-app/SKILL.md) — the operational commands (`dev` / `build` / `start`) with all flags and config knobs.
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — wiring `defineConfig` and `warlock.config.ts`.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — module layout, canonical imports.