@tulipes/core 0.1.3 → 0.1.5

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

@@ -0,0 +1,61 @@
+---
+name: tulipes-permissions
+description: Use when adding roles or permissions to a Tulipes app, guarding an endpoint by role, or deciding who may do what. Covers module.acl.ts, the global role vocabulary and module-namespaced resources.
+---
+
+# Adding permissions
+
+Roles are **global**, declared once by the sys `core` module. Every other
+module **grants** permissions on its own resources to those roles.
+
+`modules/core/module.acl.ts` — the vocabulary:
+
+```ts
+import type { AclBuilder } from "@tulipes/core/acl";
+
+export default function coreAcl(acl: AclBuilder): void {
+  acl.defineRole("admin").defineRole("user");
+  acl.allow("admin", "*");
+}
+```
+
+`modules/billing/module.acl.ts` — grants for this feature:
+
+```ts
+import type { AclBuilder } from "@tulipes/core/acl";
+
+export default function billingAcl(acl: AclBuilder): void {
+  acl.allow("user", "invoices:read");
+  acl.allow("accountant", "invoices:read", "invoices:write");
+}
+```
+
+Check at the edge of a handler:
+
+```ts
+if (!acl!.can(role, "invoices:write")) throw new HttpError(403, "forbidden");
+```
+
+## Rules
+
+- **Resources are namespaced by module**: `invoices:read`,
+  `users:write`. Match the module's short name so ownership is obvious.
+- **Grant, don't define.** A feature module calling `defineRole()` usually
+  means the role belongs in `core` instead. Introducing a role is
+  deliberate and explicit — `allow()` on an unknown role is a boot error,
+  never an implicit creation.
+- The same role+resource granted by two modules crashes the boot. Since
+  resources are namespaced, that always means a duplicated resource name.
+- Wildcards: `*` (everything), `invoices:*` (whole namespace). Give `*`
+  to `admin` only.
+- Unknown roles always deny at runtime — the safe answer to "can this
+  unheard-of role do X?" is no.
+
+## Gotchas
+
+- Load order matters: roles must exist before grants, which is why `core`
+  is `tier: "sys", priority: 0`. If your module runs before the module
+  defining a role, add it to `dependsOn`.
+- `acl.can()` answers *what the role may do*, not *who the caller is*.
+  Authentication (deciding the role) is your auth module's job.
+- Roles are lowercase kebab-case; resources are `name:action`.

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 backend/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 **backend** 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 backend 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 **backend mode only**. `ctx.sockets` is undefined in the
+  worker process, so a queue processor cannot emit directly — publish to
+  Redis, or have the backend 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 backend 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.