@warlock.js/core 5.30.0 → 5.32.0

package/skills/warlock-inspect/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: warlock-inspect
+description: 'Ask the app instead of grepping it: `warlock inspect --json` prints the facts of the booted app — routes (middleware chain, auth guard, CSRF, rate limit, logging, request/response JSON Schema), models (table, columns, relations, resource), resources, config keys and types, event listeners, pages (layouts, loaders, actions), queue jobs, scheduled tasks and installed @warlock.js versions — as a versioned report (`schemaVersion: 1`) with a published JSON Schema; `inspectApp()` returns the same object. Triggers: `warlock inspect`, `--section`, `inspect_routes`, `inspectApp`, `bootForInspect`, `InspectReport`, `INSPECT_REPORT_JSON_SCHEMA`, `inspect-report.schema.json`, `@warlock.js/core/tooling`; "which routes are unguarded", "what does this app expose", "what models and columns exist", "which config keys are set", "list event listeners", "app facts as JSON for an agent". Skip: a route table for humans — the `warlock-routes` topic; health diagnostics — the `warlock-doctor` topic; verifying a change — the `warlock-check` topic; an OpenAPI file — the `generate-openapi` topic.'
+---
+
+# Warlock — `warlock inspect`
+
+Read the app's facts from its **booted registries**, not from source text. Run it before changing an app you do not know, and when you need a fact the code only implies (the effective rate limit of a route, whether a guard runs, which resource a model uses).
+
+```bash
+npx warlock inspect                                  # counts + a route list
+npx warlock inspect --json > app.json                # the full report
+npx warlock inspect --json --section routes,models   # only some sections
+```
+
+It boots like `warlock doctor`: connectors boot (routes register) but none starts — no database, cache or socket connection, no port. With `--json`, stdout is only the JSON.
+
+Sections: `routes`, `models`, `resources`, `config`, `events`, `pages`, `jobs`, `schedules`, `packages`. An unknown section fails before the app boots.
+
+## Answer questions with jq
+
+```bash
+# Mutating API routes without an auth guard
+npx warlock inspect --json --section routes \
+  | jq -r '.routes[] | select(.method != "GET" and .auth.required == false and .isPage == false) | "\(.method) \(.path)  \(.sourceFile)"'
+
+# Routes that log request bodies
+npx warlock inspect --json --section routes | jq -r '.routes[] | select(.logging.body) | .path'
+
+# A model's columns and relations
+npx warlock inspect --json --section models | jq '.models[] | select(.name == "User") | {columns: [.columns[].name], relations}'
+
+# Config keys (types only — values are never printed)
+npx warlock inspect --json --section config | jq -r '.config[] | "\(.key): \(.type)"'
+```
+
+## The route entry
+
+```json
+{
+  "method": "PATCH",
+  "path": "/posts/:id",
+  "name": "posts.update",
+  "sourceFile": "src/app/posts/routes.ts",
+  "handler": "updatePostController",
+  "middleware": ["authMiddleware"],
+  "auth": { "required": true, "sources": ["header"], "userTypes": ["user"] },
+  "csrf": true,
+  "rateLimit": { "source": "global", "max": 60, "timeWindow": 60000 },
+  "logging": { "body": true, "query": true, "privateRules": false },
+  "request": {
+    "parameters": [
+      { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
+    ],
+    "body": {
+      "type": "object",
+      "properties": { "title": { "type": "string" } },
+      "required": ["title"]
+    },
+    "customValidation": false
+  },
+  "responses": {
+    "200": {
+      "description": "Successful response",
+      "schema": {
+        "type": "object",
+        "properties": { "post": { "$ref": "#/components/schemas/PostResource" } },
+        "required": ["post"]
+      }
+    }
+  }
+}
+```
+
+`$ref`s resolve against `components.schemas` in the same report. Request and response schemas come from the same code as `warlock generate.openapi`.
+
+## From code
+
+```ts
+import { inspectApp, type InspectReport } from "@warlock.js/core/tooling";
+
+// The app is already booted in this process (a dev-server hook, a test with setupTest()):
+const report: InspectReport = await inspectApp({ sections: ["routes", "models"] });
+const publicWrites = report.routes?.filter(
+  (route) => route.method !== "GET" && !route.auth.required,
+);
+```
+
+`inspectApp()` boots nothing. To boot first, the way the command does:
+
+```ts
+import { bootForInspect, inspectApp, inspectOptionsFromBoot } from "@warlock.js/core/tooling";
+
+const boot = await bootForInspect();
+const report = await inspectApp({ ...inspectOptionsFromBoot(boot) });
+```
+
+Validate a report with the published schema — `INSPECT_REPORT_JSON_SCHEMA` (draft 2020-12), also shipped as `node_modules/@warlock.js/core/schemas/inspect-report.schema.json`:
+
+```ts
+import Ajv2020 from "ajv/dist/2020";
+import { INSPECT_REPORT_JSON_SCHEMA, inspectApp } from "@warlock.js/core/tooling";
+
+const report = await inspectApp();
+const valid = new Ajv2020({ strict: false }).validate(INSPECT_REPORT_JSON_SCHEMA, report);
+```
+
+## Stability (schemaVersion 1)
+
+- Fields are only added; none is removed, renamed or retyped. Ignore keys you do not know.
+- A section you did not request is absent, not empty.
+- Warning and description text is not a contract; match on `code` fields.
+- A breaking change ships as `schemaVersion: 2`, listed under BREAKING in the changelog.
+
+## Agents: ask through MCP instead of shelling out
+
+`npx warlock mcp` serves the same report as tools — `inspect_app` for the counts, then `inspect_routes` (`filter`, `method`, `unguardedWrites`), `inspect_models`, `inspect_config`, … one per section, plus `db_schema` built from the `models` section. `npx warlock dev --mcp` serves them from the dev server, so they reflect the last hot reload. See the `warlock-mcp` topic.
+
+`warlock dev` also writes a summary of this report (modules, routes, unguarded writes, models, installed skills) into the generated section of `AGENTS.md` — see the `warlock-agents-md` topic.
+
+## Gotchas
+
+- `warnings` lists what could not be read — `WL2001` a module failed to import (its routes are missing from the report), `WL4001` a schema with no JSON Schema form. Run `npx warlock explain <code>`.
+- `events` lists listeners app modules registered on `@mongez/events` while loading; listeners added later at runtime, and `Model.events()` listeners, are not included.
+- `jobs` and `schedules` appear only when a loaded module (usually `worker.ts`) defined them through the app's `@warlock.js/queue` / `@warlock.js/scheduler`.
+- App modules are imported, so their import-time side effects run, as in `warlock dev`.
+
+## See also
+
+- The `warlock-check` topic — verify a change: typecheck, lint, tests, conventions, error codes.
+- The `warlock-mcp` topic — the same facts as MCP tools for a coding agent.
+- The `warlock-agents-md` topic — the app summary `warlock dev` keeps in AGENTS.md.
+- The `warlock-routes` topic — the human route table.
+- The `generate-openapi` topic — the same route schemas as an OpenAPI document.

package/skills/warlock-mcp/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: warlock-mcp
+description: 'Serve the app to a coding agent over the Model Context Protocol: `warlock mcp` (stdio, or `--http` on loopback with a bearer token required off loopback) and `warlock dev --mcp` / `devServer.mcp` (live registries) expose `inspect_app` + `inspect_<section>` (routes, models, resources, config, events, pages, jobs, schedules, packages), `db_schema`, `docs_search` / `docs_read` (installed @warlock.js skills, READMEs and llms files only, offline), `explain`, `check_run`, `test_run`, `requests_recent` (devtools: timeline, queries with nPlusOne, logs) and `generate_make` / `generate_add` (a unified diff from a throw-away copy; writes only with `--allow-writes`). Read-only by default. Needs `@warlock.js/ai-tools` (optional peer). Triggers: `warlock mcp`, `--allow-writes`, `--http`, `WARLOCK_MCP_TOKEN`, `warlock dev --mcp`, `devServer.mcp`, `startWarlockMcpServer`, `createMcpContext`, `createWarlockMcpTools`, `runTests`, `sandboxBackend`, `WL7003`, `WL7004`, `WL7005`, `.mcp.json`; "connect Claude Code / Cursor to my Warlock app", "let the agent ask the app", "MCP server for this project", "preview what a generator writes". Skip: the JSON report itself — the `warlock-inspect` topic; serving YOUR OWN agent tools over MCP — the `expose-as-mcp-server` topic of @warlock.js/ai-tools; one request''s timeline from the terminal — the `warlock-trace` topic.'
+---
+
+# Warlock — `warlock mcp`
+
+One MCP server per app that answers what the app actually has and does — from its registries, its installed docs and its devtools — so an agent asks instead of grepping.
+
+```bash
+npm install -D @warlock.js/ai-tools @warlock.js/ai   # once: the MCP transport (optional peers)
+
+npx warlock mcp                       # stdio — what an MCP client spawns
+npx warlock mcp --http                # Streamable HTTP on 127.0.0.1, a free port (printed on stderr)
+npx warlock mcp --http --port 7333 --token "$WARLOCK_MCP_TOKEN"
+npx warlock mcp --allow-writes        # generate tools may write files
+npx warlock dev --mcp                 # inside the dev server: live registries after every reload
+```
+
+Register it with a client (Claude Code reads `.mcp.json` at the project root):
+
+```json
+{
+  "mcpServers": {
+    "warlock": { "command": "npx", "args": ["warlock", "mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool                                                                                                                                                | What it returns                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inspect_app`                                                                                                                                       | App name/version/Node, a count per section, inspect warnings. Start here.                                                                                                             |
+| `inspect_routes`                                                                                                                                    | Routes with middleware, guard, CSRF, rate limit, logging, JSON Schemas. `filter`, `method`, `unguardedWrites`.                                                                        |
+| `inspect_models`, `inspect_resources`, `inspect_config`, `inspect_events`, `inspect_pages`, `inspect_jobs`, `inspect_schedules`, `inspect_packages` | One `warlock inspect` section each, with `filter`.                                                                                                                                    |
+| `db_schema`                                                                                                                                         | Tables from the models: columns with type, required, primary key, `belongsTo` foreign keys, relations, timestamps. No database connection.                                            |
+| `docs_search` / `docs_read`                                                                                                                         | Ranked sections of `node_modules/@warlock.js/*/skills/**`, `README.md`, `llms*.txt` — the installed versions, offline.                                                                |
+| `explain`                                                                                                                                           | A `WL` code: meaning, your code vs this machine, fix, skill, docs link.                                                                                                               |
+| `check_run`                                                                                                                                         | The `warlock check` report (`changed`, `base`, `skip`). Exit code 2 = the machine, not the code.                                                                                      |
+| `test_run`                                                                                                                                          | vitest for `files` (tests run directly, sources via `vitest related`), `changed`, or the suite.                                                                                       |
+| `requests_recent`                                                                                                                                   | Recent requests from devtools: status, phases (each middleware, validation, handler), queries with `nPlusOne`, warnings, logs, timings. Needs `warlock dev` + `@warlock.js/devtools`. |
+| `generate_make`                                                                                                                                     | `generate.<module\|controller\|service\|use-case\|model\|repository\|resource\|migration>` → a unified diff per file.                                                                 |
+| `generate_add`                                                                                                                                      | `warlock add <features>` → the diff (package.json included; nothing installed).                                                                                                       |
+
+Names use `_`, not `.`: model APIs only accept `^[a-zA-Z0-9_-]{1,128}$` as a tool name.
+
+## Read-only by default
+
+Without `--allow-writes`, `generate_make` / `generate_add` have no `write` argument: the generator runs in a temporary copy of the project (root files and `src/`, `.env*` never copied, `node_modules` linked) and the tool returns what it would create or change:
+
+```json
+{
+  "ok": true,
+  "command": ["warlock", "generate.service", "posts/publish-post"],
+  "files": [
+    {
+      "path": "src/app/posts/services/publish-post.service.ts",
+      "status": "created",
+      "diff": "--- /dev/null\n+++ b/src/app/posts/services/publish-post.service.ts\n@@ -0,0 +1,5 @@\n+…"
+    }
+  ]
+}
+```
+
+A `write: true` sent to a read-only server is refused with `WL7005`. With `--allow-writes`, `write: true` runs the generator in the project and returns the same diff.
+
+## HTTP rules
+
+- Binds `127.0.0.1` by default. Any other `--host` needs `--token` (or `WARLOCK_MCP_TOKEN`), otherwise `WL7004` before anything boots.
+- Clients send `Authorization: Bearer <token>` when a token is set; foreign browser `Origin`s are refused (the `@warlock.js/ai-tools` HTTP transport).
+- `warlock dev --mcp` serves HTTP on loopback only and records the endpoint in `.warlock/dev-server.json` (`mcp.url`). Options in `warlock.config.ts`:
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: {
+    mcp: { port: 7333, token: process.env.WARLOCK_MCP_TOKEN, allowWrites: false },
+  },
+});
+```
+
+## From code
+
+```ts
+import {
+  createMcpContext,
+  inspectApp,
+  runTests,
+  startWarlockMcpServer,
+} from "@warlock.js/core/tooling";
+
+// The app is already booted in this process.
+const context = createMcpContext({ inspect: (sections) => inspectApp({ sections }) });
+const server = await startWarlockMcpServer({ context, transport: { type: "http", port: 0 } });
+
+console.error(`MCP at ${server.url} — ${server.tools.length} tools`);
+
+const tests = await runTests({ files: ["src/app/posts/services/publish-post.service.ts"] });
+console.error(
+  tests.ok ? "tests pass" : tests.problems.map((problem) => problem.message).join("\n"),
+);
+
+await server.close();
+```
+
+## Gotchas
+
+- `warlock mcp` boots like `warlock inspect` (connectors booted, none started — no database connection, no app port) on the first tool call, and keeps that snapshot. After changing routes or models, restart it — or use `warlock dev --mcp`, which reads the live registries.
+- Over stdio, stdout is the JSON-RPC stream: `console.log` / `info` / `debug` are sent to stderr for the whole run.
+- `requests_recent` fails with `WL8008` when no dev server is recorded or reachable, and `WL8009` when devtools is not installed (`npx warlock add devtools`).
+- Missing `@warlock.js/ai-tools` / `@warlock.js/ai` → `WL7003` with the install line.
+
+## See also
+
+- The `warlock-inspect` topic — the report the `inspect_*` tools return.
+- The `warlock-check` topic — what `check_run` and `test_run` report.
+- The `warlock-trace` topic — send a request and read its timeline.
+- The `expose-as-mcp-server` topic of @warlock.js/ai-tools — the transport underneath.

package/skills/warlock-routes/SKILL.md

@@ -25,14 +25,14 @@ The `METHOD` column is verb-colored (GET green, POST blue, PUT/PATCH yellow, DEL
 
 ## Columns
 
-| Column   | Meaning                                                                       |
-| -------- | ----------------------------------------------------------------------------- |
-| `METHOD` | HTTP verb; a wildcard `all` route lists as `ALL`.                             |
-| `PATH`   | Full request path (group prefix already folded in).                           |
-| `NAME`   | Route name, or `—` when unnamed.                                              |
-| `ACTION` | Handler function name (`anonymous` for an unnamed handler).                   |
-| `MW`     | Count of middleware attached to the route.                                    |
-| `SOURCE` | Source file the route registered from, or `—`.                               |
+| Column   | Meaning                                                     |
+| -------- | ----------------------------------------------------------- |
+| `METHOD` | HTTP verb; a wildcard `all` route lists as `ALL`.           |
+| `PATH`   | Full request path (group prefix already folded in).         |
+| `NAME`   | Route name, or `—` when unnamed.                            |
+| `ACTION` | Handler function name (`anonymous` for an unnamed handler). |
+| `MW`     | Count of middleware attached to the route.                  |
+| `SOURCE` | Source file the route registered from, or `—`.              |
 
 ## Filters
 
@@ -55,7 +55,14 @@ npx warlock routes --json
 
 ```json
 [
-  { "method": "GET", "path": "/users", "name": "users.list", "action": "index", "middleware": 2, "source": "app/users/routes.ts" }
+  {
+    "method": "GET",
+    "path": "/users",
+    "name": "users.list",
+    "action": "index",
+    "middleware": 2,
+    "source": "app/users/routes.ts"
+  }
 ]
 ```
 
@@ -94,7 +101,7 @@ already claimed by another method). Run `warlock routes` to see the registered n
 
 **A clean baseline is now expected immediately after a successful `warlock build`.** Through 5.1, running `routes:diff` on an untouched checkout right after a green build reported drift, because the manifest recorded the catch-all as `"*"` while the router serves it as `"/*"`. The manifest is now written through the router's own path normalizer, so the two sides agree and a clean tree reports clean. If you see drift on a tree you have not edited since building, that is a bug worth reporting — it is no longer the expected greeting.
 
-⚠ **What a clean diff does NOT prove.** The manifest records what each page's name was **derived** as, not what it was **registered** as. `warlock build` never boots connectors, so it cannot see the API routes a page name might collide with; when a name is already claimed by another method the router appends a `.<method>` suffix at registration, and the comparison accepts that suffix rather than reporting it as drift. So `Page routes match` means *the page surface did not move since the build* — it does not mean *no page route name collided*. Use `warlock routes` to see the names as actually registered.
+⚠ **What a clean diff does NOT prove.** The manifest records what each page's name was **derived** as, not what it was **registered** as. `warlock build` never boots connectors, so it cannot see the API routes a page name might collide with; when a name is already claimed by another method the router appends a `.<method>` suffix at registration, and the comparison accepts that suffix rather than reporting it as drift. So `Page routes match` means _the page surface did not move since the build_ — it does not mean _no page route name collided_. Use `warlock routes` to see the names as actually registered.
 
 or, on drift:
 
@@ -116,7 +123,7 @@ and exits non-zero.
 
 ## Gotchas
 
-- **No connectors are started.** The list reflects what's *registered*, not what would connect. It never opens a DB/cache/socket.
+- **No connectors are started.** The list reflects what's _registered_, not what would connect. It never opens a DB/cache/socket.
 - **An empty table is a tell.** `No routes registered` is the same signal `warlock doctor`'s `routes` check warns on — a route module likely failed to load.
 - **`MW` counts, it doesn't name.** It's a "is this route guarded?" signal; for the actual chain, read the route definition.
 - **`ACTION` is the handler function name.** A controller method shows its method name; an inline anonymous handler shows `anonymous`.

package/skills/warlock-trace/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: warlock-trace
+description: 'Verify runtime behaviour without a browser: `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running `warlock dev` server and prints what devtools recorded for it — middleware chain with timings, validation result and errors, handler time, queries with N+1 flags, logs, cache operations, captured mails, the response and timings — as a versioned report (`schemaVersion: 1`); `traceRequest()` returns the same object. Triggers: `warlock trace`, `traceRequest`, `TraceReport`, `buildTraceReport`, `x-request-id`, `.warlock/dev-server.json`, `WL8008`, `WL8009`, `WL5004`, `--id-header`; "did validation pass for this request", "which queries does this endpoint run", "is there an N+1 on this route", "what middleware runs on this route", "check the endpoint after my change", "request timeline as JSON". Skip: the devtools dashboard in a browser — the `devtools-overview` skill of @warlock.js/devtools; static route facts (guard, rate limit, schemas) — the `warlock-inspect` topic; typecheck/lint/tests — the `warlock-check` topic.'
+---
+
+# Warlock — `warlock trace`
+
+Send a real request to the running dev server and read back its devtools timeline. Use it after a change to confirm what the code actually does at runtime: the middleware that ran, whether validation refused the body, which queries ran and whether any is an N+1.
+
+Needs `warlock dev` running in the project and `@warlock.js/devtools` installed (`npx warlock add devtools`). The dev server records its address in `.warlock/dev-server.json`; `trace` reads it from there.
+
+```bash
+npx warlock trace GET /posts
+npx warlock trace POST /posts --body '{"title":"Hello"}' --json
+npx warlock trace PATCH /posts/1 --body @payload.json -H "authorization: Bearer $TOKEN" --json
+npx warlock trace GET /posts --url http://localhost:2030 --json   # explicit server
+```
+
+`--header` / `-H` repeats. A JSON `--body` is sent as `application/json` unless you pass a `content-type` header; `@file` reads the body from a file.
+
+## Answer questions with jq
+
+```bash
+# Validation verdict and errors
+npx warlock trace POST /posts --body '{"title":""}' --json | jq '.timeline.validation'
+# → { "ran": true, "durationMs": 0.6, "passed": false, "errors": [{ "input": "title", "error": "The title is required" }] }
+
+# N+1 queries with the line that issued them
+npx warlock trace GET /posts --json | jq '.queries[] | select(.nPlusOne) | {sql, caller}'
+
+# Middleware chain, in run order
+npx warlock trace GET /admin/users -H "authorization: Bearer $TOKEN" --json \
+  | jq -r '.timeline.middleware[] | "\(.index) \(.name) \(.durationMs)ms"'
+
+# Status and body
+npx warlock trace GET /posts/1 --json | jq '{status: .response.status, body: .response.body}'
+```
+
+## The report (schemaVersion 1)
+
+Top-level keys: `requestId`, `server`, `request` (method, url, headers with credentials `[redacted]`, body), `response` (status, headers, body — parsed JSON or text, cut at 64 KiB with `truncated`), `route`, `error`, `timeline` (`phases`, `routeMatch`, `middleware[]`, `validation`, `handler`), `queries[]` (each with `nPlusOne`), `warnings[]`, `logs[]`, `cache[]`, `mails[]`, `timings` (`totalMs` server, `clientMs` round trip, `phasesMs` per phase).
+
+`timeline.validation.passed`: `true` when the handler ran after validation, `false` when the request was answered with an error before the handler, `null` when the route validates nothing.
+
+## From code
+
+```ts
+import { traceRequest } from "@warlock.js/core/tooling";
+
+const report = await traceRequest({ method: "POST", url: "/posts", body: { title: "Hello" } });
+
+const slowQueries = report.queries.filter((query) => Number(query.durationMs) > 50);
+const nPlusOne = report.queries.some((query) => query.nPlusOne);
+```
+
+## How the request is matched
+
+`trace` sends a fresh UUID as `x-request-id`. Core adopts it as `request.id` and echoes it back; devtools keys its record by that id. If the app renamed the header (`http.requestId.header`), pass `--id-header <name>`. If it disabled it (`http.requestId.enabled: false`), no record can be matched.
+
+## Errors
+
+| Code     | Meaning                                                             | Exit |
+| -------- | ------------------------------------------------------------------- | ---- |
+| `WL8008` | No dev server recorded, or it does not answer — start `warlock dev` | 2    |
+| `WL8009` | Dev server up, devtools not mounted — `warlock add devtools`        | 2    |
+| `WL5004` | Devtools has no record of the request (request id disabled)         | 1    |
+
+Devtools is checked before anything is sent. With `--json` a failure prints `{ "ok": false, "code", "message" }`. Exit 2 means "this machine", not your code — start the server instead of editing code. `npx warlock explain <code>` prints the fix.
+
+## Gotchas
+
+- Run it on the same machine as the dev server: devtools answers loopback requests only, in development only.
+- Paths under the devtools prefix (`/__warlock`) are never recorded.
+- Devtools keeps the last 200 requests in memory; a restart of `warlock dev` clears them.
+- The request really runs: a `POST` writes to the development database.
+
+## See also
+
+- The `warlock-inspect` topic — the static facts of a route (guard, rate limit, schemas).
+- The `warlock-check` topic — typecheck, lint, tests and conventions in one run.
+- The `devtools-overview` skill of `@warlock.js/devtools` — the dashboard behind the timeline.

package/skills/wire-socket/SKILL.md

@@ -7,7 +7,7 @@ description: 'Configure Socket.IO via `src/config/socket.ts`, reach the live ser
 
 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 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
 
@@ -46,8 +46,8 @@ The framework auto-loads each module's `main.ts` once at boot, but **before** th
 
 ```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)`
+  port?: number; // standalone port (only if HTTP is disabled)
+  options?: ServerOptions; // forwarded as the 2nd arg to socket.io's `new Server(httpServer, options)`
 };
 ```
 
@@ -78,19 +78,19 @@ Two ways to get the `socket.io` `Server` instance:
 // 1. Via the app runtime accessor — reads container.tryGet("socket")
 import { app } from "@warlock.js/core";
 
-const io = app.socket;            // → Server, or undefined before the socket connector boots
+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
+const io = getSocketServer(); // → Server | null
 ```
 
-Both read the same DI container slot. `app.socket` is a getter that returns `container.tryGet("socket")` — that's `undefined` (it does **not** throw) until the socket connector has booted. `getSocketServer()` reads the same `container.tryGet("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.
+Both read the same DI container slot. `app.socket` is a getter that returns `container.tryGet("socket")` — that's `undefined` (it does **not** throw) until the socket connector has booted. `getSocketServer()` reads the same `container.tryGet("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:
+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";
@@ -273,7 +273,7 @@ CLI commands, scheduled jobs, queue workers — anything running outside an HTTP
 
 ## 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.
+- **`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.

package/skills/write-seeder/SKILL.md

@@ -52,26 +52,26 @@ npx warlock seed --drop=default-roles       # undo just one seeder's records
 
 ```ts
 type Seeder = {
-  name: string;                                // required, used as the registry key
-  enabled?: boolean;                            // default true — set false to skip
-  description?: string;                         // shown in --list output
-  dependsOn?: string[];                         // names of seeds that must run first
-  once?: boolean;                               // skip if a row exists in the `seeds` table
-  order?: number;                               // sort key — lower runs first
-  batchSize?: number;                           // documented; not enforced by the manager
-  run(ctx: SeedContext): Promise<SeedResult | void>;   // your work
+  name: string; // required, used as the registry key
+  enabled?: boolean; // default true — set false to skip
+  description?: string; // shown in --list output
+  dependsOn?: string[]; // names of seeds that must run first
+  once?: boolean; // skip if a row exists in the `seeds` table
+  order?: number; // sort key — lower runs first
+  batchSize?: number; // documented; not enforced by the manager
+  run(ctx: SeedContext): Promise<SeedResult | void>; // your work
 };
 
 type SeedContext = {
-  track: Track;                                 // register created records for --drop
-  now: SeedClock;                               // injectable clock — () => Date, default () => new Date()
-  batchSize: number;                            // from the seeder's batchSize (0 when unset)
+  track: Track; // register created records for --drop
+  now: SeedClock; // injectable clock — () => Date, default () => new Date()
+  batchSize: number; // from the seeder's batchSize (0 when unset)
 };
 
 type SeedClock = () => Date;
 
 type SeedResult = {
-  recordsCreated: number;                       // OPTIONAL fallback when nothing was tracked
+  recordsCreated: number; // OPTIONAL fallback when nothing was tracked
 };
 ```
 
@@ -88,7 +88,7 @@ async run({ track, now }) {
 }
 ```
 
-Inject a fixed clock for deterministic tests or historical back-fills — pass `clock` to `SeedersManager` (`new SeedersManager({ clock: () => new Date("2020-01-01") })`) or, programmatically, to `seedCommandAction(options, { clock })`. Pinning the clock makes every timestamp in the run — seed data *and* the `seeds` log — resolve to that one value.
+Inject a fixed clock for deterministic tests or historical back-fills — pass `clock` to `SeedersManager` (`new SeedersManager({ clock: () => new Date("2020-01-01") })`) or, programmatically, to `seedCommandAction(options, { clock })`. Pinning the clock makes every timestamp in the run — seed data _and_ the `seeds` log — resolve to that one value.
 
 ## `batchSize` — bulk-insert hint
 
@@ -108,9 +108,9 @@ The manager doesn't act on `batchSize` itself — it only hands the value throug
 `track` is how a seed tells the framework which rows it created, so `--drop` can undo them. It has three forms, and **every form returns its first argument** so you can wrap a `create()` call inline:
 
 ```ts
-track(model)                 // single model — reads model.getTableName() + model.id
-track([modelA, modelB])      // bulk — array of models
-track("legacy_table", id)    // raw escape hatch — table name + id, no model
+track(model); // single model — reads model.getTableName() + model.id
+track([modelA, modelB]); // bulk — array of models
+track("legacy_table", id); // raw escape hatch — table name + id, no model
 ```
 
 ```ts
@@ -139,6 +139,7 @@ src/app/
 ```
 
 A seed file that doesn't export a default `Seeder` throws at discovery time:
+
 > `Seeder file <relative> does not export a default seeder.`
 
 Filename convention is `<name>.seed.ts` but the loader doesn't enforce it — any `.ts` inside a `seeds/` folder is picked up. Sticking to the suffix keeps things grep-able.
@@ -169,12 +170,12 @@ Use `once: true` for irreversible "starter" data (the framework's default `roles
 
 Every record you `track()` is written to a `seed_records` table (created on first run via `SeedRecordsTableMigration`):
 
-| Column     | Meaning                                  |
-| ---------- | ---------------------------------------- |
-| `seeder`   | Owning seeder's `name`                   |
-| `table`    | Table the tracked record lives in        |
-| `recordId` | Primary key of the tracked record        |
-| `runAt`    | Wall time the reference was recorded      |
+| Column     | Meaning                              |
+| ---------- | ------------------------------------ |
+| `seeder`   | Owning seeder's `name`               |
+| `table`    | Table the tracked record lives in    |
+| `recordId` | Primary key of the tracked record    |
+| `runAt`    | Wall time the reference was recorded |
 
 `warlock seed --drop` reads those refs and undoes the seed:
 
@@ -191,7 +192,7 @@ What it does, inside a single transaction:
 
 Only **tracked** rows are deleted — records you created without `track()` (or rows added by hand) are untouched. A seed whose `run()` never calls `track()` can't be undone with `--drop`; it has nothing to delete and its log row stays.
 
-`--drop` vs `--fresh`: `--fresh` is the blunt reset (truncates *every* table); `--drop` is surgical (only what a seed tracked). Reach for `--drop` when you want to re-run one seeder without nuking the whole DB.
+`--drop` vs `--fresh`: `--fresh` is the blunt reset (truncates _every_ table); `--drop` is surgical (only what a seed tracked). Reach for `--drop` when you want to re-run one seeder without nuking the whole DB.
 
 ## Ordering
 
@@ -204,7 +205,7 @@ seeder({
 
 seeder({
   name: "default-admin-user",
-  order: 20,         // runs AFTER user-roles (which created the roles it references)
+  order: 20, // runs AFTER user-roles (which created the roles it references)
   // ...
 });
 ```
@@ -213,20 +214,33 @@ The manager sorts by `order` ascending — lower runs first. Seeds without an `o
 
 ### `dependsOn` — topological order
 
-`dependsOn: ["user-roles"]` is **resolved** by the manager: it topologically sorts seeders so every dependency runs before its dependents, *layered over* the numeric `order` tie-break. Among seeders whose dependencies are already satisfied, the lowest `order` (then registration order) runs first.
+`dependsOn: ["user-roles"]` is **resolved** by the manager: it topologically sorts seeders so every dependency runs before its dependents, _layered over_ the numeric `order` tie-break. Among seeders whose dependencies are already satisfied, the lowest `order` (then registration order) runs first.
 
 ```ts
-seeder({ name: "roles", order: 20, async run() { /* ... */ } });
-seeder({ name: "admin-user", dependsOn: ["roles"], order: 10, async run() { /* ... */ } });
+seeder({
+  name: "roles",
+  order: 20,
+  async run() {
+    /* ... */
+  },
+});
+seeder({
+  name: "admin-user",
+  dependsOn: ["roles"],
+  order: 10,
+  async run() {
+    /* ... */
+  },
+});
 // → roles runs FIRST despite its higher order, because admin-user depends on it.
 ```
 
 Two ways it fails loudly:
 
-- **Unknown dependency** — `dependsOn` names a seeder that isn't registered (or is `enabled: false`, since disabled seeds are filtered out *before* resolution) → `UnknownSeederDependencyError`.
+- **Unknown dependency** — `dependsOn` names a seeder that isn't registered (or is `enabled: false`, since disabled seeds are filtered out _before_ resolution) → `UnknownSeederDependencyError`.
 - **Cycle** — `a → b → a` → `SeederDependencyCycleError` (the message includes the cycle path).
 
-Use `dependsOn` to express *hard* ordering constraints and `order` for soft sequencing within a dependency layer.
+Use `dependsOn` to express _hard_ ordering constraints and `order` for soft sequencing within a dependency layer.
 
 ## Transactions
 
@@ -234,7 +248,7 @@ By default, each seed runs inside a transaction. The manager wraps `run({ track
 
 ```ts
 const result = withTransaction
-  ? await transaction(runSeeder)   // run() + seed_records writes, atomically
+  ? await transaction(runSeeder) // run() + seed_records writes, atomically
   : await runSeeder();
 ```
 
@@ -265,7 +279,7 @@ export default seeder({
     for (const data of seeds) {
       const existing = await Currency.first({ code: data.code });
       if (existing) continue;
-      track(await Currency.create(data));   // count auto-derived from track()
+      track(await Currency.create(data)); // count auto-derived from track()
     }
   },
 });
@@ -283,7 +297,7 @@ import { User } from "../models/user";
 export default seeder({
   name: "default-admin",
   description: "Insert the seed admin user",
-  once: true,                   // never re-run
+  once: true, // never re-run
   dependsOn: ["default-roles"], // roles must exist first
   async run({ track }) {
     const adminRole = await Role.first({ slug: "admin" });