@tulipes/core 0.1.2 → 0.1.4

package/templates/claude/skills/tulipes-queue/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: tulipes-queue
+description: Use when adding background work to a Tulipes app — emails, webhooks, exports, scheduled retries — or when a request handler is doing something slow. Covers the queues contract, producing jobs, and the web/worker process split.
+---
+
+# Adding a background job
+
+One file declares both sides of a queue, and the process mode decides what
+happens with it: the **web** process registers the queue so routes can
+produce into it; the **worker** process turns the processor into a live
+consumer. Never duplicate the definition.
+
+`modules/billing/queues/invoices.queues.ts`:
+
+```ts
+import type { Ctx } from "@tulipes/core/boot";
+import type { QueueRegistry } from "@tulipes/core/queues";
+
+export default function invoiceQueues({ models }: Ctx, queues: QueueRegistry): void {
+  queues.define("billing.send-invoice");
+
+  queues.process("billing.send-invoice", async (job) => {
+    const invoice = await models!.get("Invoice").findById(job.data.invoiceId);
+    // …do the slow thing here…
+    return { sent: true };
+  });
+}
+```
+
+Produce from anywhere with the context:
+
+```ts
+await queues!.add("billing.send-invoice", "send", { invoiceId: invoice.id });
+```
+
+Run a consumer with `yarn worker`. Without it, jobs pile up in Redis and
+nothing processes them — that is the correct behaviour, not a bug.
+
+## Rules
+
+- **Queue names use `.`, never `:`** (`billing.send-invoice`). BullMQ
+  reserves `:` as its Redis key separator; a `:` name crashes the boot.
+- Names are globally unique, and a queue may have only one processor —
+  duplicates crash the boot naming both modules.
+- A processor registered for a queue nobody defined is a boot error; call
+  `define()` in the same file.
+- Requires `REDIS_URL` declared (sys `core` module) and set. Queue files
+  without it are a boot refusal.
+- Worker mode with zero processors refuses to start: a consumer with
+  nothing to consume is a misconfigured deployment.
+
+## Writing a processor
+
+- **Jobs retry.** Make the handler idempotent — the same job may run twice
+  after a crash or timeout.
+- Pass identifiers in `job.data`, not whole documents; re-read from the
+  database inside the processor so the job acts on current state.
+- Keep payloads small and JSON-serializable.
+- Throwing marks the job failed and schedules a retry per its options; let
+  it throw rather than swallowing errors.
+- Both processes run the full boot pipeline, so `models`, `config` and
+  `Environment` are all available inside a processor.

package/templates/claude/skills/tulipes-socket/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: tulipes-socket
+description: Use when adding realtime features to a Tulipes app — websockets, live updates, presence, notifications — or when emitting events from a route or background job. Covers the sockets contract and namespace ownership.
+---
+
+# Adding realtime
+
+Socket.IO namespaces are claimed by modules, one owner each, in
+`modules/<name>/sockets/*.sockets.ts`. Websockets are opt-in: an app with
+no socket files starts no Socket.IO server at all.
+
+```ts
+import type { Ctx } from "@tulipes/core/boot";
+import type { SocketRegistry } from "@tulipes/core/sockets";
+
+export default function billingSockets({ config }: Ctx, sockets: SocketRegistry): void {
+  sockets.namespace("/billing", (nsp) => {
+    nsp.on("connection", (socket) => {
+      socket.emit("ready", { plan: config.billing?.plan });
+
+      socket.on("subscribe", (invoiceId: string) => {
+        socket.join(`invoice:${invoiceId}`);
+      });
+    });
+  });
+}
+```
+
+Emit from anywhere with the context — a route, a bootstrap task, a queue
+processor in the web process:
+
+```ts
+ctx.sockets!.of("/billing").to(`invoice:${id}`).emit("invoice:paid", payload);
+```
+
+## Rules
+
+- **Namespaces are claimed once.** A second module claiming `/billing`
+  crashes the boot naming both.
+- `sockets.of()` throws on a namespace nobody claimed. Socket.IO's raw
+  `io.of()` would silently create it and emit into the void — use the
+  framework accessor so typos surface.
+- Sockets exist in **web mode only**. `ctx.sockets` is undefined in the
+  worker process, so a queue processor cannot emit directly — publish to
+  Redis, or have the web process subscribe.
+- Namespace names are lowercase kebab-case with a leading slash.
+
+## Gotchas
+
+- Authenticate in namespace middleware (`nsp.use(...)`), not per event —
+  the framework's HTTP pipeline does not run for socket connections.
+- Scaling past one web process needs the Socket.IO Redis adapter;
+  otherwise an emit only reaches clients connected to that instance.
+- Socket handlers run outside the request pipeline: no `HttpError`, no
+  request logging. Handle failures explicitly and emit an error event.