@warlock.js/core 5.30.0 → 5.31.0

package/skills/warlock-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warlock-doctor
-description: 'Run `warlock doctor` — a read-only diagnostics command that checks routes / config / connectors / optional-peers / health endpoints / release hygiene and prints a pass/warn/fail report, exiting non-zero on any failure. Add your own probe with the `DoctorCheck` contract and `runChecks` / `formatReportLines`. Triggers: `warlock doctor`, `doctorCommand`, `DoctorCheck`, `CheckResult`, `CheckStatus`, `DoctorReport`, `runChecks`, `formatReportLines`, `printReport`, `defaultDoctorChecks`; "diagnose my app", "preflight / preflight check", "is the app healthy", "why are there 0 routes", "pre-release sanity check", "CI smoke check"; run as `npx warlock doctor`. Skip: the live `/health` + `/ready` HTTP probes — the `health-checks` topic; authoring a general CLI command — the `write-cli-command` topic; releasing the package — `releasing-warlock-monorepo`; competing tools `npm doctor`, `nest info`, hand-rolled preflight scripts.'
+description: 'Run `warlock doctor` — a read-only diagnostics command that checks routes / config / connectors / optional-peers / health endpoints / release hygiene and prints a pass/warn/fail report, exiting non-zero on any failure. Add your own probe with the `DoctorCheck` contract and `runChecks` / `formatReportLines`. Triggers: `warlock doctor`, `warlock doctor --json`, `toDoctorJson`, `WL1001`, `doctorCommand`, `DoctorCheck`, `CheckResult`, `CheckStatus`, `DoctorReport`, `runChecks`, `formatReportLines`, `printReport`, `defaultDoctorChecks`; "diagnose my app", "preflight / preflight check", "is the app healthy", "why are there 0 routes", "pre-release sanity check", "CI smoke check"; run as `npx warlock doctor`. Skip: the live `/health` + `/ready` HTTP probes — the `health-checks` topic; authoring a general CLI command — the `write-cli-command` topic; releasing the package — `releasing-warlock-monorepo`; competing tools `npm doctor`, `nest info`, hand-rolled preflight scripts.'
 ---
 
 # Warlock — `warlock doctor`
@@ -22,23 +22,53 @@ npx warlock doctor
 Summary: 5 ok, 1 warn, 0 fail
 ```
 
+## Error codes and `--json`
+
+Every `warn`/`fail` finding carries a stable error code (`WL1001`, `WL2001`, …), printed after the detail and explained by `warlock explain <code>`. `--json` prints the report with the same `code` / `hint` / `skill` / `docs` fields `warlock check --json` uses (boot output goes to stderr):
+
+```bash
+npx warlock doctor --json | jq '.results[] | select(.status != "ok") | "\(.code) \(.detail)"'
+npx warlock explain WL1001
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "results": [
+    {
+      "name": "config",
+      "status": "fail",
+      "detail": "missing required config section(s): http",
+      "code": "WL1001",
+      "hint": "Add the missing file under src/config/ (for example src/config/app.ts) exporting the section.",
+      "skill": "configure-app",
+      "docs": "https://warlock.js.org/v/latest/core/cli/error-codes/#wl1001"
+    }
+  ],
+  "summary": { "ok": 0, "warn": 0, "fail": 1 },
+  "exitCode": 1
+}
+```
+
+A custom check sets `code` on its non-ok results the same way (`{ name, status: "fail", code: "WL2003", detail }`); `ok` results carry none.
+
 ## What it checks
 
 The default set is `defaultDoctorChecks` (in registration order — runtime-surface checks first, release hygiene last):
 
-| Check | `ok` | `warn` | `fail` |
-| --- | --- | --- | --- |
-| `routes` | ≥ 1 route registered | 0 routes (a route module likely failed to load) | — |
-| `config` | required sections (`app`, `http`) present | — | a required section is missing |
-| `connectors` | manager enumerable; reports registered + active set | — | (only if the probe itself throws) |
-| `optional-peers` | every known optional peer installed | a peer is missing → its feature is unavailable | — |
-| `jwt-secret` | `auth.userType` configured and a JWT signing secret set | — | `auth.userType` is configured but no signing secret (`auth.accessToken.secret` / `auth.jwt.secret`) is set |
-| `health` | `/health` + `/ready` will be exposed | `http.health.enabled = false` (probes off) | — |
-| `release-hygiene` | `package.json` version matches the top `## x.y.z` CHANGELOG heading | no `CHANGELOG.md`, or no parseable heading | version ≠ top heading |
+| Check             | `ok`                                                                | `warn`                                          | `fail`                                                                                                     |
+| ----------------- | ------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `routes`          | ≥ 1 route registered                                                | 0 routes (a route module likely failed to load) | —                                                                                                          |
+| `config`          | required sections (`app`, `http`) present                           | —                                               | a required section is missing                                                                              |
+| `connectors`      | manager enumerable; reports registered + active set                 | —                                               | (only if the probe itself throws)                                                                          |
+| `optional-peers`  | every known optional peer installed                                 | a peer is missing → its feature is unavailable  | —                                                                                                          |
+| `jwt-secret`      | `auth.userType` configured and a JWT signing secret set             | —                                               | `auth.userType` is configured but no signing secret (`auth.accessToken.secret` / `auth.jwt.secret`) is set |
+| `health`          | `/health` + `/ready` will be exposed                                | `http.health.enabled = false` (probes off)      | —                                                                                                          |
+| `release-hygiene` | `package.json` version matches the top `## x.y.z` CHANGELOG heading | no `CHANGELOG.md`, or no parseable heading      | version ≠ top heading                                                                                      |
 
 `jwt-secret` is the pre-flight form of the silent first-login 500: when `auth.userType` is set but no signing secret is, every login and token operation fails with a generic 500 at runtime — `doctor` turns that into a `fail` before you ship. It resolves the secret from both the current key (`auth.accessToken.secret`) and the legacy `auth.jwt.secret`, so a project on the older-but-supported shape doesn't trip it. When `auth.userType` isn't configured at all (no auth), the check emits **no line** — it's skipped, not a pass — so it never nags a project that isn't doing auth.
 
-Optional peers are resolved from the **consuming app's** `node_modules` (via `createRequire(process.cwd())`), so the report reflects what *your* project has installed, not core's own deps.
+Optional peers are resolved from the **consuming app's** `node_modules` (via `createRequire(process.cwd())`), so the report reflects what _your_ project has installed, not core's own deps.
 
 ## Exit code
 
@@ -55,21 +85,22 @@ any fail    → exit 1   (so CI / a release script can gate on it)
 type CheckStatus = "ok" | "warn" | "fail";
 
 type CheckResult = {
-  name: string;     // stable check name, e.g. "routes"
+  name: string; // stable check name, e.g. "routes"
   status: CheckStatus;
-  detail: string;   // one-line, user-facing explanation
+  detail: string; // one-line, user-facing explanation
+  code?: WarlockErrorCode; // stable code of a warn/fail verdict, e.g. "WL1001"
 };
 
 type DoctorCheck = {
   name: string;
-  run: () => CheckResult | Promise<CheckResult>;   // MUST be read-only
+  run: () => CheckResult | Promise<CheckResult>; // MUST be read-only
 };
 
 type DoctorReport = {
-  results: CheckResult[];                 // in registration order
-  summary: Record<CheckStatus, number>;   // counts per status
-  hasFailures: boolean;                   // true iff any fail
-  exitCode: 0 | 1;                        // 1 when hasFailures, else 0
+  results: CheckResult[]; // in registration order
+  summary: Record<CheckStatus, number>; // counts per status
+  hasFailures: boolean; // true iff any fail
+  exitCode: 0 | 1; // 1 when hasFailures, else 0
 };
 ```
 
@@ -91,7 +122,7 @@ import {
 const migrationsCheck: DoctorCheck = {
   name: "migrations",
   async run() {
-    const pending = await countPendingMigrations();   // your read-only probe
+    const pending = await countPendingMigrations(); // your read-only probe
 
     return pending === 0
       ? { name: "migrations", status: "ok", detail: "no pending migrations" }
@@ -101,8 +132,8 @@ const migrationsCheck: DoctorCheck = {
 
 const report = await runChecks([...defaultDoctorChecks, migrationsCheck]);
 
-printReport(report);                  // colored, to stdout
-const lines = formatReportLines(report);   // plain strings — snapshot-friendly
+printReport(report); // colored, to stdout
+const lines = formatReportLines(report); // plain strings — snapshot-friendly
 
 if (report.hasFailures) process.exit(report.exitCode);
 ```
@@ -125,7 +156,7 @@ A `⚠ routes: 0 routes registered` line is the tell that a route module threw o
 
 ## Gotchas
 
-- **`doctor` starts no connectors.** It intentionally does not open DB / cache / socket connections — the `connectors` check reports the *registered* set and which are already active, without forcing any up. Don't expect it to detect a down database.
+- **`doctor` starts no connectors.** It intentionally does not open DB / cache / socket connections — the `connectors` check reports the _registered_ set and which are already active, without forcing any up. Don't expect it to detect a down database.
 - **Optional-peers resolves from the project, not core.** A peer installed only inside core's own `node_modules` still reports as missing — the probe uses `process.cwd()`.
 - **Warnings don't fail the command.** Only a `fail` flips the exit code. Missing optional peers and disabled health endpoints are deliberate-choice `warn`s.
 - **Custom checks must stay read-only.** `run()` runs against a booted-but-not-connected app; mutating state or opening a connection breaks the contract and can hang the command.
@@ -136,3 +167,5 @@ A `⚠ routes: 0 routes registered` line is the tell that a route module threw o
 - The `write-cli-command` topic — authoring a command + its `preload` plan, the shape `doctorCommand` is built from.
 - The `add-connector` topic — connector registration, which the `connectors` check enumerates.
 - The `warlock-conventions` topic — project layout the checks assume.
+- The `warlock-check` topic — `warlock check` / `typecheck` / `explain` and the error-code registry the findings use.
+- The `warlock-inspect` topic — `warlock inspect`, the same boot pass printed as a versioned JSON report of the app.

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.