@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/no-code-app/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: no-code-app
+
+should_trigger:
+  - prompt: "Build a CRM for my team without writing code"
+    why: Core no-code build request — app UI + data + light logic, no code.
+  - prompt: "Should I use Bubble or Glide for my MVP?"
+    why: Platform-choice question this skill owns the decision table for.
+  - prompt: "Monta una app sin codi per gestionar reserves del gimnàs"
+    why: Catalan phrasing for building a no-code booking app.
+  - prompt: "My Bubble app's monthly bill suddenly exploded — what happened?"
+    why: Non-obvious; symptom of Workload-Unit metering (per-row loops / unbatched writes).
+  - prompt: "How do I avoid getting locked into a no-code tool?"
+    why: Non-obvious; the exit/lock-in planning this skill insists on up front.
+  - prompt: "Airtable or Xano as the backend for my Softr app?"
+    why: Backend-by-logic-complexity decision, squarely in scope.
+
+should_not_trigger:
+  - prompt: "Build this web app in Next.js with a Postgres backend"
+    route_to: nextjs
+    why: Hand-written coded app, full control — not a visual builder.
+  - prompt: "I want to open an online store"
+    route_to: shopify
+    why: Commerce storefront, not a general-purpose app.
+  - prompt: "Connect my Stripe payments to a Google Sheet, no app needed"
+    route_to: automation-flows
+    why: Tool-to-tool wiring with no app UI.
+  - prompt: "Set up a blog / content site"
+    route_to: wordpress
+    why: CMS / content site, not an app with custom data + logic.
+  - prompt: "Clean up and pivot this spreadsheet of sales data"
+    route_to: spreadsheet-ops
+    why: The sheet itself is the deliverable, not a backend for an app.
+
+capability:
+  - scenario: >
+      Design a no-code booking app for a yoga studio (classes, bookings, payments)
+      and decide whether no-code is even the right call.
+    must_include:
+      - runs the Step 0 gate and confirms no-code is appropriate vs writing code (nextjs)
+      - picks a platform with a reason tied to app shape AND its billing model (Softr flat / Glide updates / Bubble WU)
+      - models the data as normalized tables + relations before screens; names a backend choice (native / Airtable / Xano) by logic complexity
+      - estimates the limit/cost ceiling (WU, updates, or record cap) and includes a load-test-at-10x note
+      - includes an exit/export plan (export day 1, portable model, migrate-off triggers, rewrite cost)

package/skills/shared/no-code-app/references/platform-limits.md

@@ -0,0 +1,100 @@
+# Platform limits cheatsheet (2026)
+
+Dated numbers live here so SKILL.md stays evergreen. Design against the *metering model*, not these exact figures — re-verify before quoting a price to anyone.
+
+## Bubble — metered by Workload Units (WU)
+
+Every DB query, workflow run, and API call burns WU. Cost is a function of usage, not seats.
+
+| Tier | Price (web) | WU/month |
+| --- | --- | --- |
+| Free | $0 | ~50K (dev/trial) |
+| Starter | $29/mo | 175K |
+| Growth | $119/mo | 250K |
+| Team | $349/mo | 500K |
+| Enterprise | custom | custom |
+
+- The allotments are small and the steps between tiers are small — Growth's 250K is only **~1.43x** Starter's 175K. A widely-repeated older claim put Growth at **1M WU** (a 4x jump); that figure is stale and unsupported by any current source — do not design around it. Plan around the metering, not the tier names.
+- Prices shift with billing choice: the figures above are **web-only, annual billing**. Web+mobile and monthly billing run higher (e.g. Starter up to ~$59, Team up to ~$549); the WU allotments per tier stay 175K / 250K / 500K across those variants.
+- Overage: extra WU is sold in packs (≈ $0.30 per 1,000 WU as a rough run rate) beyond the tier allotment — verify the current pack pricing before quoting.
+- Warning emails at **75%** and **100%** of allotment — wire these to a human.
+- Source: goodspeed.studio "Bubble.io Pricing 2026" (last updated 2026-05-29, verified against the official pricing page), adalo.com/posts/bubble-pricing, lowcode.agency Bubble pricing, manual.bubble.io pricing-plans, bubble.io/pricing (re-verified 2026-06-02). Three independent write-ups plus the Bubble docs agree on 175K / 250K / 500K WU.
+
+## Glide — metered by "updates" (data writes)
+
+Billed on writes, not seats. Cost is unpredictable as write volume grows.
+
+| Tier | Price | Notes |
+| --- | --- | --- |
+| Free | $0 | Draft apps; up to 25K rows |
+| Maker | $25/mo | personal/community apps, more features than Free |
+| Team | $99/mo | unlimited apps, 20 users, 5K updates/mo, Glide Basic API |
+| Business | $249/mo | unlimited apps, 30 users, 5K updates/mo, rows capped: ~25K with an external/standard source, ~100K with Glide (Big) Tables |
+
+- The Business row cap is real and load-bearing: a standard/external data source tops out around **25K rows**; you only reach **~100K rows** on Glide's own (Big) Tables. Pick the data source with that ceiling in mind.
+- Update overage beyond the monthly allotment is charged per extra update — confirm the current per-update rate before quoting.
+- Source: glideapps.com/pricing, adalo.com/posts/glide-pricing, costbench.com Glide 2026, Glide community "Data rows in business plan? 25000 or 100000?" (verified 2026-06-02).
+
+## Softr — flat-rate per workspace (not metered)
+
+No per-write metering; no charge for internal editors → the most predictable scaling of the three.
+
+| Tier | Price | Notes |
+| --- | --- | --- |
+| Basic | ~$49/mo (annual) | 3 apps, 20 app users, **10,000 records/base** (50,000 records/workspace) for the Softr DB; custom code, payments |
+| Professional | ~$139/mo | 50,000 records/base (500,000/workspace) |
+| Business | ~$269/mo | 200,000 records/base (1,000,000/workspace) |
+
+- The Basic per-base cap is **10,000 records**, *not* 50K. The 50K figure is the **per-workspace** total across bases — easy to mistake for the per-base limit, which is the one a single dataset actually hits. Size against the 10K-per-base number early.
+- External/advanced data sources (SQL, BigQuery, Xano, Supabase) get much higher per-app limits (Basic ~500K), so the 10K cap bites hardest on the native Softr DB.
+- Source: softr.io/pricing (re-verified 2026-06-02 — Basic 10,000/base, 50,000/workspace), docs.softr.io pricing-and-plans, Softr community "Database Limits for Basic Plan", adalo.com/posts/softr-pricing.
+
+## Backend comparison
+
+| | Airtable | Xano |
+| --- | --- | --- |
+| What | Relational DB with a spreadsheet UI | Full backend: PostgreSQL + visual API builder |
+| Record cap | ~50K records/base on the common Team tier (Free 1K, Business 125K) — cumulative across the base's tables | Scales (real DB) |
+| API speed | Slow | <200ms typical |
+| Best for | Simple read/create, admin data entry | Complex logic, performance, security, scale |
+
+Note the Airtable per-base cap (~50K on Team) is a *different* number from Softr's Basic per-base cap (10K) — don't conflate them. The Airtable limit counts all records across all tables in one base.
+
+Hybrid pattern: **Airtable for human data entry/admin, Xano for API logic + perf + security.**
+
+Source: airtable.com/pricing (Team ~50K/base, Business 125K — re-verified 2026-06-02), xano.com/versus/xano-vs-airtable, minimum-code.com, adalo.com.
+
+## Cost-estimation worked examples
+
+**Bubble (WU):** estimate WU per user action ≈ (DB queries + workflow steps + API calls) it triggers. Multiply by expected actions/month.
+
+```text
+1 booking action ≈ 3 queries + 4 workflow steps + 1 payment API call ≈ ~8 WU
+2,000 bookings/mo  => ~16K WU just for bookings (comfortably under Starter's 175K)
+add page loads, searches, dashboards, scheduled jobs => easily 100K-300K WU/mo
+=> the overhead, not the bookings, is what eats the budget: 100K-300K WU lands you
+   on the edge of Starter (175K) and quickly past it — Growth only buys 250K, so a
+   single feature that loops an API call per row pushes you to overage, not just a
+   tier bump. Budget against total WU, not the headline booking count.
+```
+
+**Glide (updates):** count data writes per user per month.
+
+```text
+Each user: ~10 writes/visit x 8 visits/mo = ~80 updates/user/mo
+500 users => ~40K updates/mo, on top of tier allotment, overage ~$0.02 each.
+```
+
+**Softr (flat):** the same workloads cost the tier price regardless of write volume — this is why it is the predictable choice for portals.
+
+## Migrate-off trigger list
+
+Stop adding features and start the migration plan when **two or more** fire:
+
+1. **Logic outgrows the canvas** — many-branch conditionals, custom algorithms that fight the visual builder.
+2. **Performance wall** — the app crawls at real row counts (snappy at 100, slow at 10,000; load-test at 10x early).
+3. **Cost crossover** — the metered bill exceeds what a real backend + hosting would cost.
+
+Context: ~25-30% of no-code projects get rewritten when they outgrow the tool; rebuild cost **$50K-$250K**; ~68% of platforms offer **no code export** (verify data export on day 1).
+
+Source: weweb.io code-export buyer's guide, nocodefinder.com vendor lock-in, designrevision.com platform comparison (accessed 2026-06-02).

package/skills/shared/nodejs/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: nodejs
+description: "Use when building or operating a plain Node.js / Express 5 backend service: project layout, async correctness, central error middleware, fail-fast config, graceful shutdown on SIGTERM. NOT DI modules/providers/guards (that is `nestjs`), NOT the type system or tsconfig (that is `typescript`), NOT REST contract design (that is `api-design`)."
+tags: [nodejs, express, backend, async, error-handling]
+recommends: [nestjs, typescript, api-design, error-handling, postgresdb]
+origin: ai-hub
+---
+
+# Node.js backend services
+
+Stand up a plain Node.js HTTP/JSON service — `node:http` or Express 5 — that a person can read, test, and operate without a DI framework. This skill is about the runtime and the request lifecycle: how to lay out the code, how to keep async correct, how errors become status codes, how config fails fast, and how the process dies cleanly. The contract shape, the type system, and the data layer live elsewhere (see the boundary below).
+
+## Boundary
+
+- The app is built around `@Module` / `@Injectable` / DI providers, guards, interceptors, pipes, exception filters → [`nestjs`](../nestjs/SKILL.md). Nest starts the moment the DI container appears; route away then, do not half-build it here.
+- Pure TypeScript type system, generics, `tsconfig` → [`typescript`](../typescript/SKILL.md). This skill uses TS but does not teach types.
+- REST resource modeling, versioning, pagination, status-code semantics (framework-agnostic) → [`api-design`](../api-design/SKILL.md). This skill *wires* the handlers; api-design decides the contract. Cross-cutting error taxonomy → [`error-handling`](../error-handling/SKILL.md).
+- Schema, queries, connection pool, migrations → [`postgresdb`](../postgresdb/SKILL.md) / [`prisma-orm`](../prisma-orm/SKILL.md) / [`drizzle-orm`](../drizzle-orm/SKILL.md). *Calling* a repository stays here; designing the table does not.
+- Containerizing / shipping → [`docker`](../docker/SKILL.md) / [`deployment`](../deployment/SKILL.md). Choosing the logging/metrics/tracing stack → [`observability`](../observability/SKILL.md). This skill emits structured logs and a shutdown hook; it does not own the pipeline.
+
+## Decide first
+
+Pick the runtime shape before writing code — the wrong choice is expensive to undo.
+
+| Situation | Choice | Why |
+| --- | --- | --- |
+| Needs DI/modules, large team, heavy cross-cutting | route to [`nestjs`](../nestjs/SKILL.md) | Don't reinvent a DI container by hand |
+| Small/medium JSON API, want middleware + routing | Express 5 | Mature, async errors auto-forward (v5) |
+| One tiny endpoint, zero deps, a healthcheck | `node:http` | No dependency surface to maintain |
+| A library, not a server | not this skill | No request lifecycle to manage |
+
+Defaults for a new service: pin **Node 24 (Active LTS)** in `engines.node`; Node 22 is Maintenance LTS; Node 26 is Current (released 2026-05-05, enters LTS Oct 2026) — adopt it only if you want Temporal/V8 14.6 and can track Current. Write **ESM** for new code (`"type": "module"`), CommonJS only when a hard dependency forces it.
+
+```jsonc
+// package.json
+{
+  "type": "module",
+  "engines": { "node": ">=24" },
+  "scripts": {
+    "dev": "node --watch src/server.ts",
+    "test": "node --test"
+  }
+}
+```
+
+## Project layout
+
+Concrete tree. The names are conventions, not magic — but the split is load-bearing.
+
+```text
+src/
+  app.ts          # build + return the Express app; NEVER calls listen()
+  server.ts       # imports app, listens, owns SIGTERM/shutdown
+  config/
+    env.ts        # validate process.env once, export a typed `config`
+  routes/
+    users.ts      # router only: path → controller
+  controllers/
+    users.ts      # parse request, call service, shape response
+  services/
+    users.ts      # business logic, no req/res objects
+  repositories/
+    users.ts      # data access; the only layer that touches the DB
+  errors/
+    app-error.ts  # AppError/HttpError with status + code
+```
+
+**Rule — separate app construction from `listen()`.** `app.ts` builds and returns the app; `server.ts` binds the port and owns shutdown. Why: tests import `app` and exercise routes in-process without binding a port, so they run fast and in parallel.
+
+```ts
+// Bad: index.ts listens at import time — untestable, double-binds in tests
+const app = express();
+app.get("/health", (_req, res) => res.json({ ok: true }));
+app.listen(3000); // side effect on import
+
+// Good: app.ts
+export function buildApp() {
+  const app = express();
+  app.get("/healthz", (_req, res) => res.json({ ok: true }));
+  return app; // no listen here
+}
+```
+
+## Async rules
+
+Every async mistake here is a latent production incident, not a style nit.
+
+- **Await or return every promise.** A floating promise is a latent process crash — since Node 15 an unhandled rejection terminates the process by default. The error happens later, detached from its handler.
+- **Never mix callback + promise styles.** Promisify once at the boundary (`util.promisify` or `fs/promises`) and stay in promises after that. Half-converted code swallows errors.
+- **`Promise.all` for independent work; sequential `await` only for true dependencies.** Awaiting independent calls one by one wastes wall-clock time.
+- **Use `AbortSignal.timeout(ms)` for per-operation deadlines** and thread the signal into `fetch`/DB/long ops. Compose with `AbortController` so shutdown can cancel in-flight work (see graceful shutdown).
+- **Never rely on a global `unhandledRejection` handler as control flow.** Log and exit there if anything; do not use it to keep running.
+
+```ts
+// Bad: forgotten await — the rejection floats and crashes later, error lost
+function handler(req, res) {
+  saveAudit(req.body);          // returns a promise nobody awaits
+  res.json({ ok: true });       // responds before save resolves/rejects
+}
+
+// Good: await it (Express 5 forwards a throw to the error middleware)
+async function handler(req, res) {
+  await saveAudit(req.body);
+  res.json({ ok: true });
+}
+```
+
+## Error handling
+
+This is the core, and the most common bug. In **Express 5 an async handler that rejects or throws is auto-forwarded to the error middleware** — no `try/catch + next(err)` wrapper, no `asyncHandler`. Source: Express 5 migration guide and the framework's own router tests (a value-less `Promise.reject()` becomes an Error with message `Rejected promise`).
+
+- Define one `AppError` (or `HttpError`) carrying `status` and `code`. Throw it from services; controllers don't translate.
+- Register **exactly one 4-arg `(err, req, res, next)` error middleware, LAST**, after every route. **Arity is what makes Express treat it as an error handler** — a 3-arg function is a normal middleware no matter what you name it. Order still matters in v5.
+- A 404 fallthrough handler goes *just before* the error middleware.
+- Map known errors → their status; unknown → 500; **never leak the stack or raw message in production.**
+
+```ts
+// errors/app-error.ts
+export class AppError extends Error {
+  constructor(public status: number, public code: string, message: string) {
+    super(message);
+  }
+}
+
+// app.ts — registration ORDER (routes → 404 → error handler)
+app.use("/users", usersRouter);
+
+app.use((_req, res) => res.status(404).json({ code: "not_found" }));
+
+// LAST, exactly 4 args — this is the error handler
+app.use((err, _req, res, _next) => {
+  const status = err instanceof AppError ? err.status : 500;
+  const code = err instanceof AppError ? err.code : "internal_error";
+  if (status >= 500) logger.error({ err }, "unhandled");
+  res.status(status).json({
+    code,
+    message: status < 500 ? err.message : "Internal Server Error",
+    ...(process.env.NODE_ENV !== "production" && { stack: err.stack }),
+  });
+});
+```
+
+```ts
+// Bad: the symptom "async route throws but client gets 200 empty body"
+app.use((err, _req, res, _next) => { /* error handler */ });  // registered FIRST
+app.get("/users/:id", async (req, res) => {
+  const u = await findUser(req.params.id);   // throws NotFound
+  res.json(u);                                // never reached; no handler after → hangs/empties
+});
+```
+
+The error handler placed before the route never sees the throw, so the response is whatever was half-written. Put it last. See [`references/express5-migration.md`](references/express5-migration.md) for the full v4→5 breaking-change checklist, the middleware-order diagram, and the legacy v4 `asyncHandler` wrapper.
+
+## Config & secrets
+
+Validate `process.env` once at boot, fail fast, and export a typed `config` object. **A missing variable should crash at startup, not at 3am on first use.** Ban scattered `process.env.X` reads throughout the codebase — they hide the contract and defeat the boot check.
+
+```ts
+// config/env.ts — hand-rolled or zod/envalid; the point is one gate
+import { z } from "zod";
+const schema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+});
+export const config = schema.parse(process.env); // throws → process won't start
+```
+
+## Graceful shutdown
+
+On SIGTERM the orchestrator gives you a brief window to finish. Drop nothing.
+
+1. Flip readiness to **not-ready** so the load balancer stops routing new traffic.
+2. `server.close()` — stop accepting new connections, let in-flight requests finish.
+3. Abort long-running work via a shared `AbortController` (the signal you threaded into ops).
+4. Close the DB pool and other resources.
+5. `process.exit(0)`, with a force-exit timer as a backstop if drain stalls.
+
+Expose `/healthz` (liveness — is the process up) separately from `/readyz` (readiness — should it receive traffic). They answer different questions; conflating them causes both false restarts and dropped requests during deploys. The complete copy-pasteable `server.ts` — signal handlers, `AbortController`, readiness gate, force-exit backstop — lives in [`references/graceful-shutdown.md`](references/graceful-shutdown.md).
+
+```ts
+// server.ts (sketch — full version in references/)
+const controller = new AbortController();
+const server = buildApp().listen(config.PORT);
+
+function shutdown() {
+  ready = false;                       // /readyz now 503
+  server.close(() => process.exit(0)); // drain, then exit
+  controller.abort();                  // cancel in-flight long ops
+  setTimeout(() => process.exit(1), 10_000).unref(); // backstop
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+```
+
+## Testing
+
+Node 24 ships a built-in test runner — `node:test` with `node --test` — so a backend needs no external runner for unit/integration tests, and `node --watch` for dev. **Import `app` from `app.ts` and hit it directly** (supertest or `undici`); never start the live server in a test. That is exactly why `app.ts` doesn't call `listen()`.
+
+```ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import request from "supertest";
+import { buildApp } from "../src/app.ts";
+
+test("404 returns the error contract", async () => {
+  const res = await request(buildApp()).get("/nope");
+  assert.equal(res.status, 404);
+  assert.equal(res.body.code, "not_found");
+});
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Floating promise (no `await`/`return`) | Unhandled rejection crashes the process (Node 15+), error detached | Await or return every promise |
+| Error middleware with 3 args or not last | Express never treats it as an error handler; throws fall through | 4 args `(err,req,res,next)`, registered LAST |
+| Reading `process.env.X` everywhere | Missing var fails at 3am, contract is invisible | Validate once in `config/env.ts`, export typed `config` |
+| `listen()` inside `app.ts` | Side effect on import; tests bind a port / double-listen | `app.ts` returns app, `server.ts` listens |
+| `catch (e) {}` then continue | Swallows the failure, masks the bug | Re-throw, or map to an `AppError` |
+| `process.exit()` without draining | Drops in-flight requests on deploy | SIGTERM → `server.close()` → abort → exit |
+| Global `unhandledRejection` as control flow | Hides bugs, leaves process in a bad state | Log + exit there; fix the floating promise |
+| Assuming Express 4 defaults | v5: `urlencoded` `extended:false`, `static` `dotfiles:"ignore"` | Read [`references/express5-migration.md`](references/express5-migration.md) |
+| Leaking stack/message in prod | Information disclosure | Stack only when `NODE_ENV !== "production"` |
+
+## Verify
+
+`scripts/verify.sh` statically lints a produced repo for these rules (4-arg error handler last, no `listen()` in `app.ts`, `engines.node` supported, floating-promise heuristic). Advisory; hard-fails only on `listen()` in `app.ts` or a missing error handler.

package/skills/shared/nodejs/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: nodejs
+
+These cases are run by the repository's eval harness against the skill router. Each `should_trigger` prompt expects the router to select `nodejs`; each `should_not_trigger` prompt expects it to select the named sibling instead (`route_to`), guarding the boundaries against `nestjs`, `typescript`, `api-design`, and `postgresdb`. The single `capability` case is graded by a judge against its `must_include` rubric — it checks that a scaffolded Express 5 service splits `app.ts` from `server.ts`, has one 4-arg error handler last, validates env at boot, and shuts down gracefully. Run them with the repo's standard eval command pointed at this skill directory; there is no separate setup beyond the harness itself.

package/skills/shared/nodejs/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: nodejs
+
+should_trigger:
+  - prompt: "Set up an Express 5 service with a central error handler and graceful shutdown."
+    why: "Core greenfield plain-Node/Express service — layout, error handling, shutdown."
+  - prompt: "My async route throws but the client gets a 200 with an empty body."
+    why: "Non-obvious symptom of a mis-ordered or missing 4-arg error middleware in Express 5."
+  - prompt: "Where should controllers, services and repositories live in my Node API?"
+    why: "Non-DI service structure is exactly this skill's project-layout concern."
+  - prompt: "Why does one unhandled promise rejection crash my whole Node server?"
+    why: "Node 15+ runtime async semantics — floating promise as a latent crash."
+  - prompt: "Monta un backend con Express y apaga el servidor sin perder peticiones en vuelo."
+    why: "Spanish; graceful shutdown / draining in-flight requests on a plain Express service."
+
+should_not_trigger:
+  - prompt: "Wire a custom provider with useFactory in my NestJS module."
+    route_to: "nestjs"
+    why: "DI container, modules and providers are NestJS, not a bare Node/Express service."
+  - prompt: "Make this generic helper preserve the literal type and fix my tsconfig."
+    route_to: "typescript"
+    why: "Pure TypeScript type system and tsconfig, not the Node runtime."
+  - prompt: "Design the REST resource URLs, versioning and pagination for our public API."
+    route_to: "api-design"
+    why: "Framework-agnostic contract design; this skill wires handlers, it does not shape the contract."
+  - prompt: "Set up the Postgres connection pool and write the user query."
+    route_to: "postgresdb"
+    why: "Data layer / schema / queries belong to the database skill, not the HTTP service."
+
+capability:
+  - scenario: "A user asks to scaffold a production-ready Express 5 JSON service."
+    must_include:
+      - "app.ts builds and returns the app; server.ts owns listen() and shutdown."
+      - "Exactly one 4-arg (err,req,res,next) error middleware registered LAST, with a 404 fallthrough just before it."
+      - "Typed AppError carrying status + code; known errors mapped to status, unknown to 500, no stack leak in production."
+      - "Environment validated once at boot (fail fast), exported as a typed config; no scattered process.env reads."
+      - "SIGTERM handler: flip readiness to not-ready, server.close() to drain, abort in-flight via AbortController, then exit, with a force-exit backstop."
+      - "Tests use node:test and import the app from app.ts rather than starting the live server."
+      - "engines.node pinned to a supported LTS (Node 24); ESM for new code."
+      - "Routes DI/modules to nestjs, contract design to api-design, and the data layer to postgresdb."

package/skills/shared/nodejs/references/express5-migration.md

@@ -0,0 +1,53 @@
+# Express 4 → 5 migration & middleware order
+
+Express 5.2.x is current and requires Node.js 18+. Source: npm `express`, Express 5 migration guide (accessed 2026-06-02). Use this as the offloaded depth referenced from SKILL.md.
+
+## Breaking changes that bite a backend
+
+| Area | v4 | v5 | Action |
+| --- | --- | --- | --- |
+| Async errors | a rejected/thrown async handler hangs unless wrapped | auto-forwarded to the 4-arg error middleware | Delete `asyncHandler` wrappers; just `throw` / reject |
+| `express.urlencoded` | `extended: true` default | `extended: false` default | Pass `{ extended: true }` explicitly if you relied on rich objects |
+| `express.static` dotfiles | `"allow"` for some setups | `dotfiles: "ignore"` default | Set `{ dotfiles: "allow" }` only if you intend to serve `.well-known` etc. |
+| Path matching | older path-to-regexp | newer path-to-regexp; some wildcard/optional syntaxes changed | Re-test `:param?`, `*`, and regex routes; name your wildcards |
+| Removed/renamed | `res.json(status, obj)`, `app.del`, `req.param(name)` | removed | Use `res.status(s).json(obj)`, `app.delete`, `req.params`/`req.query`/`req.body` |
+
+## Auto async error catch — what it actually guarantees
+
+The framework's own router tests confirm: an `async` handler that rejects, or returns `Promise.reject(err)`, reaches the 4-arg error handler. A value-less `Promise.reject()` is surfaced as an `Error` with message `Rejected promise`. So in v5 you write:
+
+```ts
+// v5 — no wrapper
+app.get("/users/:id", async (req, res) => {
+  const u = await findUser(req.params.id); // throw NotFound → error middleware
+  res.json(u);
+});
+```
+
+```ts
+// v4 legacy wrapper — ONLY if you are still on Express 4
+const asyncHandler = (fn) => (req, res, next) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+app.get("/users/:id", asyncHandler(async (req, res) => { /* ... */ }));
+```
+
+What auto-catch does NOT cover: a promise you never awaited or returned inside the handler (a floating promise). That still escapes to the process, not the error middleware. Await everything.
+
+## Middleware order (still matters in v5)
+
+Order of registration is order of execution. The error handler is selected by arity (4 args), not by name or position alone — but it only catches what is registered *before* it.
+
+```text
+  app.use(express.json())            parsers, security headers
+        │
+        ▼
+  app.use("/users", usersRouter)     routes (may throw → forwarded down)
+        │
+        ▼
+  app.use((req,res) => 404)          fallthrough: nothing matched
+        │
+        ▼
+  app.use((err,req,res,next) => ...) ERROR HANDLER — 4 args, registered LAST
+```
+
+A 4-arg function registered *before* the routes is skipped for normal requests and can never catch a route's throw. Put it last, exactly once.

package/skills/shared/nodejs/references/graceful-shutdown.md

@@ -0,0 +1,73 @@
+# Graceful shutdown — complete server.ts
+
+Copy-pasteable. Threads an `AbortController` so in-flight long ops are cancelled, gates readiness so the load balancer stops routing before drain, and keeps a force-exit backstop so a stuck connection can't hang the deploy. Sources: AbortController guides (AppSignal 2025-02-12, BetterStack), Node SIGTERM semantics (accessed 2026-06-02).
+
+## Why a readiness gate, not just `server.close()`
+
+`server.close()` stops accepting *new* connections but in-flight requests keep going. If the load balancer is still routing new traffic at you while you close, those new connections are refused. So you flip `/readyz` to 503 *first*, give the LB a moment to deregister, then close. `/healthz` stays 200 the whole time — the process is alive, just draining.
+
+```ts
+// server.ts
+import { buildApp } from "./app.ts";
+import { config } from "./config/env.ts";
+import { logger } from "./logger.ts";
+import { closePool } from "./repositories/pool.ts";
+
+let ready = true;
+const controller = new AbortController(); // pass controller.signal into fetch/DB/long ops
+
+const app = buildApp();
+app.get("/healthz", (_req, res) => res.json({ status: "up" }));        // liveness
+app.get("/readyz", (_req, res) =>                                       // readiness
+  ready ? res.json({ status: "ready" }) : res.status(503).json({ status: "draining" }),
+);
+
+const server = app.listen(config.PORT, () =>
+  logger.info({ port: config.PORT }, "listening"),
+);
+
+let shuttingDown = false;
+async function shutdown(signal: string) {
+  if (shuttingDown) return;            // ignore a second signal
+  shuttingDown = true;
+  logger.info({ signal }, "shutting down");
+
+  ready = false;                       // 1. /readyz → 503, LB deregisters
+
+  const backstop = setTimeout(() => {  // 5. backstop: never hang the deploy
+    logger.error("drain timed out, forcing exit");
+    process.exit(1);
+  }, 10_000);
+  backstop.unref();
+
+  server.close(async () => {           // 2. stop accepting; wait for in-flight
+    controller.abort();                // 3. cancel long-running ops
+    await closePool();                 // 4. release DB/other resources
+    clearTimeout(backstop);
+    logger.info("clean exit");
+    process.exit(0);
+  });
+}
+
+process.on("SIGTERM", () => void shutdown("SIGTERM"));
+process.on("SIGINT", () => void shutdown("SIGINT"));
+
+// last-resort: log and exit, never keep running on a detached failure
+process.on("unhandledRejection", (reason) => {
+  logger.error({ reason }, "unhandled rejection");
+  void shutdown("unhandledRejection");
+});
+```
+
+## Threading the signal into work
+
+The `AbortController` only helps if operations actually receive `controller.signal`:
+
+```ts
+// in a repository / service
+const res = await fetch(url, { signal: controller.signal });
+// or compose a per-request deadline with a shutdown abort:
+const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(5_000)]);
+```
+
+`AbortSignal.timeout(ms)` returns an auto-aborting signal; `AbortSignal.any([...])` aborts when any input aborts — so the op dies on either the 5s deadline or process shutdown.