create-warlock 5.34.2 → 5.35.0

package/templates/warlock/skills/observability-and-resilience/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability-and-resilience
-description: 'How this project stays debuggable in production and survives flaky dependencies — `log.<level>(module, action, message, context)` from `@warlock.js/logger` with `X-Request-Id` propagation (already shipped via core middleware), structured metrics naming `<area>.<noun>.<unit>`, health endpoints (`/health/live` for liveness vs `/health/ready` for readiness), timeouts on every external call (`@warlock.js/http` `timeout` per Http instance / per request), retries with exponential backoff for idempotent ops only (never auto-retry POST without an idempotency key), idempotency keys for side effects (payments, emails, webhook deliveries), circuit breakers for flaky deps, graceful shutdown via `log.configure({ autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"] })`, N+1 detection, streaming for large payloads. Triggers: making an HTTP / AI / queue / DB call; adding a timeout or retry; designing an idempotency key for a side effect; instrumenting metrics; adding a health check; tracing a request across services; user asks "timeout", "retry policy", "idempotency", "request id", "tracing", "graceful shutdown", "health check", "circuit breaker", "N+1 query", "caching strategy", "metrics naming"; touching `@warlock.js/http` / `@warlock.js/scheduler` / `@warlock.js/ai` call sites. Skip: log call signature (load `skills/code-standards/SKILL.md` § 8); secrets in logs (load `skills/security-baseline/SKILL.md` § 8); pure-function refactors with no external I/O; cache driver setup (load `@warlock.js/cache` skills); HTTP client config in depth (load `@warlock.js/http` skills).'
+description: "Request correlation, structured logs, timeouts, retries, idempotency, health checks, metrics, shutdown and bounded queries. Use when adding external I/O or production instrumentation. Use security-baseline instead for secrets and sensitive data handling."
 ---
 
 # Observability & resilience
@@ -53,7 +53,7 @@ Set a default at the `Http` instance level; override per request when the endpoi
 // ✅ instance-level default
 const stripeClient = new Http({
   baseURL: "https://api.stripe.com",
-  timeout: 10_000,  // 10s — enough for most calls, short enough to fail fast
+  timeout: 10_000, // 10s — enough for most calls, short enough to fail fast
 });
 
 // ✅ per-request override for a known-slow call
@@ -132,12 +132,14 @@ Persist `key → result` with a TTL longer than your retry window (24h is typica
 
 ### 4.4 Pattern
 
+This simplified service sketch also needs an atomic reservation and provider-side idempotency to prevent concurrent duplicate charges. At the HTTP boundary, require `Idempotency-Key` and run `middleware.idempotency()` after auth as described in the `api-design` skill.
+
 ```typescript
 // ✅
 export async function chargePaymentService(input, idempotencyKey) {
-  const cached = await idempotencyRepository.find({ key: idempotencyKey });
+  const cached = await idempotencyRepository.findBy("key", idempotencyKey);
   if (cached) {
-    return cached.result;
+    return cached.get("result");
   }
 
   const result = await stripeClient.post("/v1/charges", input);
@@ -261,11 +263,11 @@ These belong here because performance failures present as resilience failures
 
 A list endpoint that fires one query per item is a bug. Either eager-load relations (Cascade's `.with("relation")`) or batch-fetch the related ids in a single query and join in-process.
 
-A code review that lets an N+1 through is doing its job poorly. Add it to the review checklist (already in `skills/api-design/SKILL.md`).
+A code review that lets an N+1 through is doing its job poorly. Add it to the review checklist (already in the `api-design` skill).
 
 ### 9.2 Pagination always
 
-See `skills/api-design/SKILL.md` § 3. No unbounded list ever, even if today's dataset is 12 rows.
+See the `api-design` skill § 3. No unbounded list ever, even if today's dataset is 12 rows.
 
 ### 9.3 Stream large payloads
 

package/templates/warlock/skills/security-baseline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-baseline
-description: 'Project-level security floor for Warlock.js apps — input validation at every boundary via `@warlock.js/seal` schemas, authentication via `@warlock.js/auth` (JWT + refresh) with `userType` config, server-side authorization never trusting client-supplied `userId`/`organizationId`, secrets only via `env(...)` + typed config files (never `process.env.X` scattered), parameterized queries through Cascade ORM (never raw concatenation), rate limiting via `@fastify/rate-limit` configured in `config/http.ts`, PII / token redaction in logs (`log.configure({ redact })`), `bcryptjs` for password hashing, `@mongez/encryption` for symmetric encryption, dependency vulnerability scanning (`yarn audit`). Triggers: writing a route handler / controller that accepts external input; touching auth, login, signup, session, token, JWT, password, refresh-token; reading secrets / API keys / env vars; writing a Cascade query or repository filter; handling file uploads, webhook payloads, queue messages; setting rate limits; user asks "is this secure", "input validation", "SQL / NoSQL injection", "XSS", "CSRF", "rate limiting", "secrets management", "authentication vs authorization", "where does X env var go"; importing `@warlock.js/seal` or `@warlock.js/auth` or `bcryptjs`. Skip: pure UI / styling that handles no data; code-style questions (load `skills/code-standards/SKILL.md`); HTTP envelope shape (load `skills/api-design/SKILL.md`); cryptography internals / writing your own crypto — stop and use a vetted lib; advanced auth flows (OAuth, SAML) — load `@warlock.js/social-auth` skill.'
+description: "Input schemas, authentication, authorization, secrets, safe queries, rate limits, password handling and log redaction. Use when code accepts external input or handles identity or credentials. Use api-design instead for HTTP response contracts."
 ---
 
 # Security baseline
@@ -10,7 +10,7 @@ description: 'Project-level security floor for Warlock.js apps — input validat
 
 The non-negotiable security floor for any project on this template. Each rule maps to a real class of incident — most production breaches trace back to one of these eight being absent or sloppy.
 
-> **Sub-agent rule:** Before writing any code that handles external input, identity, or secrets, read this file. Code-style rules live in `skills/code-standards/SKILL.md` — this skill is about what the code must do, not how it must look.
+> **Sub-agent rule:** Before writing any code that handles external input, identity, or secrets, read this file. Code-style rules live in the `code-standards` skill — this skill is about what the code must do, not how it must look.
 
 ---
 
@@ -27,13 +27,13 @@ Anything that crosses the process boundary:
 - Webhook payloads
 - Queue messages
 - Env vars (validated once at boot — see § 3)
-- Database rows from a *different* service (treat them as external if you don't own the writer)
+- Database rows from a _different_ service (treat them as external if you don't own the writer)
 
 ### 1.2 Where validation runs
 
 At the boundary, exactly once. Never inside services.
 
-The Warlock pattern: schema lives in the module's `schema/` folder, the controller types itself with the schema and attaches it via `controller.validation.schema`. See `skills/api-design/SKILL.md` § 6 for the full controller shape.
+The Warlock pattern: schema lives in the module's `schema/` folder, the controller types itself with the schema and attaches it via `controller.validation.schema`. See the `api-design` skill § 6 for the full controller shape.
 
 ```typescript
 // ✅ schema/create-order.schema.ts
@@ -56,10 +56,10 @@ export type CreateOrderSchema = Infer<typeof createOrderSchema>;
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateOrderSchema, createOrderSchema } from "../schema/create-order.schema";
 
-export const createOrderController: GuardedRequestHandler<CreateOrderSchema> = async (
+export const createOrderController: GuardedRequestHandler<CreateOrderSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const order = await placeOrderService(request.validated()); // already typed + safe
   return response.success({ order });
 };
@@ -80,7 +80,7 @@ The framework returns `422 Unprocessable Entity` with structured field errors au
 
 - **Verify the signature first**, schema-validate second. A signature failure aborts before any other work.
 - Reject requests older than the provider's replay window (typically 5 minutes).
-- Idempotency-key the handler (see `skills/observability-and-resilience/SKILL.md` § 4) — providers retry.
+- Idempotency-key the handler (see the `observability-and-resilience` skill § 4) — providers retry.
 
 ---
 
@@ -92,18 +92,18 @@ AuthN proves who you are. AuthZ decides what you can do. Conflating them is how
 
 ```typescript
 // ❌ trusting the client
-const order = await ordersRepository.find({ id, userId: request.input("userId") });
+const order = await Order.findOne({ publicId: id, userId: request.input("userId") });
 
 // ✅ identity from the authenticated session
 const user = request.locals.user;
-const order = await ordersRepository.find({ id, userId: user.id });
+const order = await Order.findOne({ publicId: id, userId: user.id });
 ```
 
 Any field whose value would determine permission (`userId`, `organizationId`, `roleId`, `isAdmin`) is read from the authenticated session — never from the request body, query, or header.
 
 ### 2.2 Authentication via `@warlock.js/auth`
 
-The project's auth stack: JWT access tokens (1h) + refresh tokens (30d), configured in `config/auth.ts`. Password hashing via `bcryptjs`. The framework's `authService` (`@warlock.js/auth`) is the single entry point:
+The project's auth stack: JWT access tokens and optional refresh tokens, configured in `src/config/auth.ts`. The starter uses `NO_EXPIRATION` for access tokens and disables refresh tokens; choose finite lifetimes and explicitly enable refresh when the application needs sessions. Password hashing via `bcryptjs`. The framework's `authService` (`@warlock.js/auth`) is the single entry point:
 
 ```typescript
 // ✅ thin wrapper service — the framework does the work
@@ -124,13 +124,13 @@ Pattern: at the start of every mutating service, check ownership and role:
 ```typescript
 // ✅
 export async function updateOrderService(orderId: string, input, user) {
-  const order = await ordersRepository.find({ id: orderId });
+  const order = await Order.findOne({ publicId: orderId });
 
   if (!order) {
     throw new OrderNotFoundError(orderId);
   }
 
-  if (order.userId !== user.id && !user.isAdmin) {
+  if (order.get("userId") !== user.id && !user.isAdmin) {
     throw new ForbiddenError("not your order");
   }
 
@@ -168,7 +168,7 @@ const authConfigurations: AuthConfigurations = {
   jwt: {
     secret: env("JWT_SECRET"),
     expiresIn: "1h",
-    refresh: { /* ... */ },
+    refresh: {/* ... */},
   },
 };
 ```
@@ -184,10 +184,10 @@ The logger redaction layer is the safety net, but the first line of defence is n
 log.info("auth", "login", "User authenticated", { user, password, token });
 
 // ✅
-log.info("auth", "login", "User authenticated", { userId: user.id });
+log.info("auth", "login", "User authenticated", { userId: user.get("publicId") });
 ```
 
-Configure `log.configure({ redact: { paths: ["password", "token", "*.secret", "*.apiKey"] } })` at startup — see `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`.
+Configure `log.configure({ redact: { paths: ["password", "token", "*.secret", "*.apiKey"] } })` at startup — see the `@warlock.js/logger` skill's `redact-sensitive-log-fields` topic.
 
 ### 3.4 Token lifetimes
 
@@ -213,7 +213,7 @@ const orders = await ordersRepository.raw(`status = '${input.status}'`);
 
 If a request body is `{ status: { $ne: null } }`, a naive `find({ status: input.status })` becomes a `$ne: null` match — returns every row. The seal schema is what prevents this: declaring `status: v.string()` rejects an object value at the boundary.
 
-This applies to **query strings too**, not just bodies — a `?status[$ne]=` smuggled through the query is the same attack. That's why list endpoints validate the query with a schema and never pass raw `request.all()` to the repository (see `skills/api-design/SKILL.md` § 3.5).
+This applies to **query strings too**, not just bodies — a `?status[$ne]=` smuggled through the query is the same attack. That's why list endpoints validate the query with a schema and never pass raw `request.all()` to the repository (see the `api-design` skill § 3.5).
 
 This is a real reason § 1 is non-negotiable.
 
@@ -281,6 +281,7 @@ For `/auth/login` and `/auth/reset-password`, key the limiter on the **email or
 ### 6.4 Progressive lockout
 
 After N failed login attempts:
+
 - 3 failures → 1-minute delay
 - 5 failures → 5-minute delay + email notification
 - 10 failures → temporary account lock + manual review
@@ -291,13 +292,13 @@ Never silently succeed-and-fail (returning 200 with no body to hide whether the
 
 ## 7. Dependency hygiene
 
-### 7.1 `yarn audit` in CI
+### 7.1 `npm audit` in CI
 
-CI runs `yarn audit --level=high` on every PR. High and critical vulnerabilities block merge. Moderate goes on the backlog with a fix-by date.
+CI runs `npm audit --audit-level=high` on every PR. High and critical vulnerabilities block merge. Moderate goes on the backlog with a fix-by date.
 
 ### 7.2 Lockfile committed
 
-`yarn.lock` is checked in. Always. CI installs with `--frozen-lockfile`.
+`package-lock.json` is checked in. CI installs with `npm ci`.
 
 ### 7.3 No `latest` in `package.json`
 
@@ -311,7 +312,7 @@ Every dependency is future risk. Before adding a 5-line utility, ask whether it'
 
 ## 8. Logging and PII
 
-See `skills/code-standards/SKILL.md` § 8 for the call signature. This is the **what not to log** list:
+See the `code-standards` skill § 8 for the call signature. This is the **what not to log** list:
 
 ### 8.1 Never log
 
@@ -340,7 +341,7 @@ log.configure({
 });
 ```
 
-See `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md` for the additive per-channel layer.
+See the `@warlock.js/logger` skill's `redact-sensitive-log-fields` topic for the additive per-channel layer.
 
 ---
 
@@ -356,7 +357,7 @@ Before merging a change that touches input, identity, secrets, or persistence:
 - [ ] All DB queries go through Cascade — no raw string-built queries
 - [ ] Rate limit appropriate for the route family (default for general, aggressive for auth)
 - [ ] No `.env` or secrets file in the commit
-- [ ] `yarn audit --level=high` passes
+- [ ] `npm audit --audit-level=high` passes
 - [ ] Logger redaction config covers any new sensitive field introduced
 - [ ] File uploads cap size, sniff MIME, server-generate the stored filename
 - [ ] Webhooks verify signature before any other work

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

@@ -1,6 +1,6 @@
 ---
 name: testing-strategy
-description: 'Test pyramid posture for Warlock.js apps — Vitest co-located (`foo.ts` → `foo.spec.ts`); **when testing is enabled in the project (a `test`/`test:*` script in package.json OR a `vitest.config.*` / `vite.config.*` file), it is mandatory that every service ships a co-located `.service.spec.ts` and every HTTP controller / request handler ships a test — a new service or endpoint without a spec is incomplete**; unit tests dominate (~70%), integration tests via `@testcontainers/mongodb` + `@testcontainers/postgresql` (~25%), e2e for critical user journeys only (~5%); coverage is a smoke detector not a target (`yarn test:coverage` via `@vitest/coverage-v8`); flaky-test zero-tolerance (quarantine in 24h, fix or delete in 7); test isolation (no shared state, no order dependency); AAA structure with blank-line phases; mock at the boundary not deep inside; `MockSDK` from `@warlock.js/ai` for AI calls; real DB via testcontainers for integration; snapshot tests only for small deterministic output; contract tests for external integrations. Triggers: deciding whether to write a unit / integration / e2e test for a change; setting up a new `.spec.ts`; debugging a flaky test; reviewing the test plan in a PR; user asks "should I unit test this", "what is our coverage policy", "this test keeps failing intermittently", "what should I mock", "test pyramid", "integration test vs unit test", "snapshot tests", "how do I test a service that hits the DB", "how do I test AI code". Skip: Vitest assertion API mechanics — that''s the testing framework''s docs; language / runtime questions; load testing / performance benchmarking; framework-package internals — load the relevant `@warlock.js/*` skill.'
+description: "Vitest test scope, co-located service and endpoint specs when testing is enabled, isolation, boundary mocks, integration tests and flaky-test policy. Use when planning or reviewing test coverage. Use git-workflow instead for CI and merge gates."
 ---
 
 # Testing strategy
@@ -21,7 +21,7 @@ This skill governs projects that have **opted into testing**. Testing is **enabl
 - `package.json` has a `test` (or `test:*`) script, **or**
 - a `vitest.config.*` / `vite.config.*` file exists at the project root.
 
-When the `test` feature is selected at scaffold time, both land automatically (Vitest, `@vitest/coverage-v8`, testcontainers, and a per-worker DB/cache test setup).
+When the `test` feature is selected at scaffold time, both land automatically (Vitest, `@vitest/coverage-v8`, and separate unit/integration projects with a per-file runtime by default).
 
 ### 0.1 If testing is enabled, tests are mandatory — not optional
 
@@ -32,7 +32,7 @@ Write the spec in the **same change** that adds the service or controller. A rev
 
 ### 0.2 If testing is NOT enabled
 
-No `test` script and no vitest/vite config — e.g. a scaffold created without the `test` feature. **Do not** add tests or testing dependencies unprompted, and don't invent a `vitest.config`. If the project is outgrowing prototype stage, *suggest* enabling the `test` feature — but never scaffold a suite the project didn't ask for.
+No `test` script and no vitest/vite config — e.g. a scaffold created without the `test` feature. **Do not** add tests or testing dependencies unprompted, and don't invent a `vitest.config`. If the project is outgrowing prototype stage, _suggest_ enabling the `test` feature — but never scaffold a suite the project didn't ask for.
 
 ---
 
@@ -95,7 +95,7 @@ Not enforced numerically. Enforced culturally — when a reviewer sees ten new e
 ### 2.2 Don't test
 
 - **The framework** — `@warlock.js/*` has its own tests. Don't re-test that `response.success()` returns 200.
-- **Trivial getters / setters** — `cart.totalCents` returning `this.get<number>("total_cents", 0)` doesn't need a test
+- **Trivial getters / setters** — `cart.totalCents` returning `this.get<number>("totalCents", 0)` doesn't need a test
 - **One-line passthroughs** — `loginService(...)` just calling `authService.login(...)` doesn't need a unit test (an integration test of the wiring is better)
 - **Generated code** — migrations, resource scaffolds
 
@@ -119,7 +119,7 @@ Each test sets up and tears down its own world. No `let users = []` at the top o
 
 Use transactions that roll back, or use testcontainers with a fresh container per file. Never share rows across tests.
 
-The project's testcontainers setup makes "fresh DB per test file" cheap — use it.
+Provide the database fixture in global setup; the framework does not create testcontainers automatically. Give each worker its own database/schema before resetting rows.
 
 ### 3.4 Time and randomness
 
@@ -149,7 +149,7 @@ const result = await summarizeContentService(input, { provider: ai });
 expect(result).toBe("mocked response");
 ```
 
-See `@warlock.js/ai/skills/run-ai-agent/SKILL.md` for the full mock surface.
+See the `@warlock.js/ai` skill's `run-ai-agent` topic for the full mock surface.
 
 ### 4.3 Database — real, via testcontainers
 
@@ -179,7 +179,7 @@ In the test environment `setupTest()` installs fakes for mail, queue, cache, sto
 ```typescript
 import { mailFake, queueFake } from "@warlock.js/core/tests";
 
-const order = { id: 42 }; // what the code under test placed
+const order = { id: "550e8400-e29b-41d4-a716-446655440000" }; // what the code under test placed
 
 mailFake.assertSent({ to: "ada@example.test" });
 queueFake.assertPushed("invoices.send", { orderId: order.id });
@@ -235,7 +235,7 @@ Low coverage = guaranteed gaps. High coverage = no guarantee of correctness. Tre
 
 Chasing the last 5% of coverage produces brittle tests over edge-case code that nobody cares about. Spend the time on tests that catch real regressions.
 
-### 6.4 The `yarn test:coverage` command
+### 6.4 The `npm run test:coverage` command
 
 Runs Vitest with `@vitest/coverage-v8` (already in dependencies). Add coverage as a CI gate per the floors above once the suite is large enough.
 
@@ -309,12 +309,12 @@ Co-located with the integration: `src/app/payments/clients/stripe-client.contrac
 src/app/orders/services/
   place-order.service.ts
   place-order.service.spec.ts       ← unit test, mocks repository
-  place-order.service.integration.spec.ts  ← integration, real DB
+  place-order.service.test.ts  ← integration, real DB
 ```
 
 - `.spec.ts` — default suffix; covers unit tests
-- `.integration.spec.ts` — when the test needs real I/O (DB, queue)
-- `.e2e.spec.ts` — full-system journey tests (sparse; one per critical flow)
+- `.test.ts` or a spec inside `tests/` — integration, real I/O (DB, queue)
+- Full-system journeys also use `.test.ts` in the integration project.
 
 Tests live next to the file under test, always. Never in a separate `__tests__/` or `test/` folder — colocation makes the link obvious and survives refactors.
 
@@ -337,4 +337,45 @@ Before merging a change that should include tests (testing enabled — see § 0)
 - [ ] Test names describe behaviour, not implementation
 - [ ] No `.only`, no `.skip` without a tracking ticket
 - [ ] Snapshots reviewed line-by-line if updated
-- [ ] `yarn test --run` passes; `yarn test:coverage` doesn't drop the floor
+- [ ] `npm run test --run` passes; `npm run test:coverage` doesn't drop the floor
+
+## Runtime cost and release gates
+
+With `--features=test`, create-warlock delegates to `warlock add test` to generate
+`vite.config.ts`: the `unit` project runs `src/**/*.spec.ts` outside `tests/`
+without framework or HTTP setup; `integration` runs `*.test.ts` and specs under
+`tests/` with `src/test-setup.ts`, global HTTP setup and `src/test-runner.ts`.
+Prefer `npx vitest run --project unit` during the pure service loop.
+
+When a unit needs config values, call
+`setupTest({ mode: "unit", importModule: (file) => import(file) })` from
+`@warlock.js/core/tests` and pair it with `afterAll(teardownTest)`. Config loads
+once per module graph, without hooks, connectors, native loader or fakes.
+Most unit specs need no setup call.
+
+Integration setup defaults to `tests.lifetime: "file"`. For reuse, set
+`lifetime: "worker"` in `src/config/tests.ts`, change the integration project to
+`pool: "forks", isolate: false`, keep the generated runner, and use `vitest run`.
+Watch, threads and isolated graphs are refused. Keep `afterAll(teardownTest)`:
+it marks file boundaries while the runner closes connectors at worker exit.
+Set `tests.resetBetweenFiles` to an async application-owned cleanup callback;
+it runs before every file, including the first, after selected fakes, clock and
+IDs reset. Each worker needs a separate database/schema. Module singletons and
+mocks survive; reset application state and restore mocks explicitly. Worker
+storage is private and does not mirror the shared HTTP server's fake files.
+
+Use `tests.profileSetup: true` or
+`WARLOCK_TEST_PROFILE=1 npx vitest run --project integration` for file timings and
+summaries per worker. Pass `file: expect.getState().testPath` in the setup call.
+`getTestRuntimeStats()` exposes bootstrap and file counts. Generated configs use
+`recommendedTestWorkers()` from `@warlock.js/core/vite` to respect visible cgroup
+v2 CPU quotas; reduce `maxWorkers` further for database or memory contention.
+
+Release gate:
+
+```bash
+npx warlock test --changed --since "$LAST_RELEASE_REF"
+npx vitest run --project integration
+# Nightly:
+npx vitest run
+```