@tulipes/cli 0.1.1 → 0.2.0-rc.1

package/templates/app/modules/settings/tests/settings.test.ts

@@ -0,0 +1,409 @@
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { afterAll, beforeAll, expect, test, vi } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { useTestApp } from "@tulipes/testing";
+
+import { testEnv, testSettings } from "../../../tests/support.ts";
+
+const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
+const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+
+const tokens = z.object({
+  data: z.object({ access_token: z.string(), refresh_token: z.string() }),
+});
+
+async function post(path: string, body: unknown, token?: string) {
+  return fetch(app.base + path, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...(token ? { authorization: "Bearer " + token } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+async function account() {
+  const credentials = {
+    email: randomBytes(12).toString("hex") + "@example.test",
+    password: randomBytes(24).toString("hex"),
+  };
+
+  const response = await post("/api/v1/auth/register", credentials);
+
+  expect(response.status).toBe(201);
+
+  const body = await response.json();
+
+  const { user } = z
+    .object({ data: z.object({ user: z.object({ id: z.string() }) }) })
+    .parse(body).data;
+
+  return { ...tokens.parse(body).data, ...credentials, userId: user.id };
+}
+
+async function get(path: string, token: string) {
+  return fetch(app.base + path, { headers: { authorization: "Bearer " + token } });
+}
+
+async function sysadmin() {
+  const user = await account();
+
+  await app.handle.ctx
+    .models!.get("User")
+    .updateOne({ _id: user.userId }, { role: "sysadmin" });
+
+  return user;
+}
+
+async function logFiles(run: (dir: string) => Promise<void>) {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const { join } = await import("node:path");
+  const dir = await mkdtemp(join(tmpdir(), "tulipes-log-http-"));
+  const env = app.handle.ctx.Environment;
+
+  const previous = {
+    file: env.get("LOG_FILE"),
+    dir: env.get("LOG_DIR"),
+  };
+
+  env.store.set("LOG_FILE", true);
+
+  env.store.set("LOG_DIR", dir);
+
+  try {
+    await run(dir);
+  } finally {
+    env.store.set("LOG_FILE", previous.file);
+
+    env.store.set("LOG_DIR", previous.dir);
+
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test("log streaming enforces sysadmin access and never follows linked log targets", async () => {
+  const ordinary = await account();
+  const user = await sysadmin();
+
+  await logFiles(async (dir) => {
+    const { writeFile, symlink } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const canary = randomBytes(24).toString("hex");
+
+    await writeFile(join(dir, "private"), canary);
+
+    await symlink(join(dir, "private"), join(dir, "app-backend.log"));
+
+    expect(
+      (await get("/api/v1/settings/logs/stream", ordinary.access_token)).status,
+    ).toBe(403);
+
+    const response = await get(
+      "/api/v1/settings/logs/stream",
+      user.access_token,
+    );
+
+    expect(response.status).toBe(409);
+    expect((await response.text()).includes(canary)).toBe(false);
+  });
+});
+
+test("log stream slots are capped per account and released on HTTP cancellation", async () => {
+  const user = await sysadmin();
+
+  await logFiles(async (dir) => {
+    const { writeFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+
+    await writeFile(
+      join(dir, "app-backend.2026-09-10.1.log"),
+      JSON.stringify({ level: 30, msg: "retained line" }) + "\n",
+    );
+
+    const first = await get("/api/v1/settings/logs/stream", user.access_token);
+    const second = await get("/api/v1/settings/logs/stream", user.access_token);
+
+    try {
+      expect(first.status).toBe(200);
+      expect(first.headers.get("content-type")).toContain("text/event-stream");
+
+      const blocked = await get(
+        "/api/v1/settings/logs/stream",
+        user.access_token,
+      );
+
+      expect(blocked.status).toBe(429);
+
+      expect(await blocked.json()).toMatchObject({
+        errors: [{ code: "TOO_MANY_LOG_STREAMS" }],
+      });
+    } finally {
+      await first.body?.cancel();
+
+      await second.body?.cancel();
+    }
+
+    let reopened: Response | undefined;
+
+    await vi.waitFor(async () => {
+      const response = await get(
+        "/api/v1/settings/logs/stream",
+        user.access_token,
+      );
+
+      if (response.status === 200) reopened = response;
+
+      expect(response.status).toBe(200);
+    });
+
+    try {
+      const reader = reopened!.body!.getReader();
+      let received = "";
+
+      try {
+        while (!received.includes("retained line")) {
+          const part = await reader.read();
+
+          if (part.done) break;
+
+          received += new TextDecoder().decode(part.value);
+        }
+
+        expect(received).toContain("event: ready");
+        expect(received).toContain("retained line");
+      } finally {
+        await reader.cancel();
+      }
+    } finally {
+      if (!reopened!.body!.locked) await reopened!.body!.cancel();
+    }
+  });
+});
+
+test.each([
+  "role removal",
+  "user deletion",
+  "session revocation",
+  "session expiry",
+  "access revocation",
+  "logout",
+  "password replacement",
+  "refresh reuse",
+])("an open log stream closes after %s", async (change) => {
+  const user = await sysadmin();
+
+  const { verify, endSession, revokeAccess } = await import(
+    "../../auth/helpers/tokens.ts"
+  );
+
+  const claims = verify(app.handle.ctx, user.access_token, "access")!;
+
+  await logFiles(async (dir) => {
+    const response = await get(
+      "/api/v1/settings/logs/stream?tail=0",
+      user.access_token,
+    );
+
+    expect(response.status).toBe(200);
+
+    const reader = response.body!.getReader();
+    const decoder = new TextDecoder();
+    let body = "";
+
+    try {
+      // Observe actual SSE delivery before changing the authority behind it.
+      while (!body.includes("event: ready")) {
+        const part = await reader.read();
+
+        expect(part.done).toBe(false);
+
+        body += decoder.decode(part.value);
+      }
+
+      if (change === "role removal") {
+        await app.handle.ctx
+          .models!.get("User")
+          .updateOne({ _id: user.userId }, { role: "admin" });
+      } else if (change === "user deletion") {
+        await app.handle.ctx.models!.get("User").deleteOne({ _id: user.userId });
+      } else if (change === "session revocation") {
+        await endSession(app.handle.ctx, claims.sid);
+      } else if (change === "session expiry") {
+        await app.handle.ctx
+          .models!.get("Session")
+          .updateOne({ sid: claims.sid }, { expires_at: new Date(0) });
+      } else if (change === "access revocation") {
+        await revokeAccess(app.handle.ctx, claims);
+      } else if (change === "logout") {
+        expect(
+          (await post("/api/v1/auth/logout", {}, user.access_token)).status,
+        ).toBe(200);
+      } else if (change === "password replacement") {
+        const { setPassword } = await import(
+          "../../auth/helpers/passwords.ts"
+        );
+
+        await setPassword(
+          app.handle.ctx,
+          user.userId,
+          randomBytes(24).toString("hex"),
+        );
+      } else {
+        expect(
+          (
+            await post("/api/v1/auth/refresh", {
+              refresh_token: user.refresh_token,
+            })
+          ).status,
+        ).toBe(200);
+
+        expect(
+          (
+            await post("/api/v1/auth/refresh", {
+              refresh_token: user.refresh_token,
+            })
+          ).status,
+        ).toBe(401);
+      }
+
+      const started = performance.now();
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+
+      try {
+        await Promise.race([
+          (async () => {
+            for (;;) {
+              const part = await reader.read();
+
+              if (part.done) break;
+
+              body += decoder.decode(part.value);
+            }
+          })(),
+          new Promise<never>((_resolve, reject) => {
+            timeout = setTimeout(
+              () => reject(new Error("Revoked stream stayed open")),
+              3000,
+            );
+          }),
+        ]);
+      } finally {
+        clearTimeout(timeout);
+      }
+
+      // Two-second authorization lease plus scheduling tolerance on this runner.
+      expect(performance.now() - started).toBeLessThan(3000);
+
+      const { writeFile } = await import("node:fs/promises");
+      const { join } = await import("node:path");
+
+      await writeFile(join(dir, "app-backend.log"), "after revocation\n");
+
+      expect((await reader.read()).done).toBe(true);
+      expect(body).not.toContain("after revocation");
+
+      // A different administrator can still use the controller after closure.
+      const other = await sysadmin();
+
+      const replacement = await get(
+        "/api/v1/settings/logs/stream?tail=0",
+        other.access_token,
+      );
+
+      expect(replacement.status).toBe(200);
+
+      await replacement.body?.cancel();
+    } finally {
+      await reader.cancel();
+    }
+  });
+});
+
+test("shutdown drains settings streams and a later boot owns fresh stream admission", async () => {
+  const user = await sysadmin();
+
+  await logFiles(async (dir) => {
+    const { writeFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+
+    await writeFile(
+      join(dir, "app-backend.log"),
+      JSON.stringify({ msg: "before drain" }) + "\n",
+    );
+
+    const active = await get("/api/v1/settings/logs/stream", user.access_token);
+
+    const idle = await get(
+      "/api/v1/settings/logs/stream?tail=0",
+      user.access_token,
+    );
+
+    expect(active.status).toBe(200);
+    expect(idle.status).toBe(200);
+
+    const readers = [active.body!.getReader(), idle.body!.getReader()];
+
+    try {
+      for (const [index, reader] of readers.entries()) {
+        let body = "";
+
+        do {
+          const part = await reader.read();
+
+          expect(part.done).toBe(false);
+
+          body += new TextDecoder().decode(part.value);
+        } while (!body.includes(index ? "event: ready" : "before drain"));
+      }
+
+      const stopping = app.handle.shutdown();
+
+      expect(app.handle.shutdown()).toBe(stopping);
+
+      await expect(stopping).resolves.toBeUndefined();
+
+      for (const reader of readers)
+        expect((await reader.read()).done).toBe(true);
+
+      // The module is imported once, but stream admission belongs to each boot.
+      const next = await boot({
+        rootDir,
+        appEnv: "test",
+        handleSignals: false,
+      });
+
+      try {
+        next.env.store.set("LOG_FILE", true);
+
+        next.env.store.set("LOG_DIR", dir);
+
+        const address = next.server!.address();
+
+        if (!address || typeof address === "string")
+          throw new Error("No listener after restart");
+
+        const response = await fetch(
+          "http://127.0.0.1:" +
+            address.port +
+            "/api/v1/settings/logs/stream?tail=0",
+          {
+            headers: { authorization: "Bearer " + user.access_token },
+          },
+        );
+
+        expect(response.status).toBe(200);
+
+        await response.body?.cancel();
+      } finally {
+        await next.shutdown();
+      }
+    } finally {
+      await Promise.all(readers.map((reader) => reader.cancel()));
+    }
+  });
+});

package/templates/app/modules/users/controllers/users.controllers.ts

@@ -0,0 +1,113 @@
+import { forgetUser } from "@app/auth";
+import type { Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+/**
+ * One class per controller, holding the context. Each method returns a
+ * handler, so the routes file stays a table of contents.
+ *
+ * Every response goes through `res.respond`, which wraps the payload in
+ * the app's envelope. Failures are thrown rather than responded — the
+ * framework's terminal handler builds the same envelope from them — so a
+ * handler only ever writes the happy path.
+ *
+ * Thrown messages are i18n KEYS: the handler translates them in this
+ * module's namespace and derives the error code from the key, so
+ * "notFound" becomes NOT_FOUND with a translated message.
+ */
+export class UsersController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  list(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      // ?page and ?per_page, already clamped by config.pagination.
+      const { per_page, skip } = req.page;
+      const User = this.#ctx.models!.get("User");
+
+      const [users, total_items] = await Promise.all([
+        User.find().select("email role -_id").skip(skip).limit(per_page).lean(),
+        User.countDocuments(),
+      ]);
+
+      // Passing total_items is what marks this a page: respond fills in
+      // page, per_page and total_pages from the request and the count.
+      res.respond({ data: users, meta: { total_items } });
+    };
+  }
+
+  /** Soft delete: the row stays in mongo but leaves every ordinary query. */
+  softDelete(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const user = await this.#ctx.models!.get("User").findOne({ email: req.params.email });
+      if (!user) throw new HttpError(404, "notFound");
+
+      // The account leaves every query, so its sessions resolve to nobody on
+      // the cold path; the cached identities would not know, so they go too.
+      await forgetUser(this.#ctx, String(user._id));
+      await (user as unknown as { softDelete(): Promise<unknown> }).softDelete();
+      res.respond({ data: { email: req.params.email, soft_deleted: true } });
+    };
+  }
+
+  listDeleted(): RequestHandler {
+    return async (_req: Request, res: Response) => {
+      const deleted = await this.#ctx.models!
+        .get("User")
+        .find({ is_deleted: true })
+        .setOptions({ withDeleted: true } as Record<string, unknown>)
+        .select("email role -_id")
+        .lean();
+
+      res.respond({ data: deleted });
+    };
+  }
+
+  create(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const { email } = (req.body ?? {}) as { email?: string };
+      // `field` is what puts this against the input in the envelope.
+      if (!email) throw new HttpError(422, "emailRequired", { field: "email" });
+
+      await this.#ctx.models!.get("User").create({ email });
+      // The locale travels with the job: the worker has no request to
+      // negotiate from, so whoever queues the work owns that decision.
+      await this.#ctx.queues!.add("users.welcome", "welcome", {
+        email,
+        locale: req.locale,
+      });
+
+      res.respond({ status: 201, data: { email, welcome_queued: true } });
+    };
+  }
+
+  ping(): RequestHandler {
+    return (req: Request, res: Response) => {
+      res.respond({
+        data: {
+          module: "users",
+          locale: req.locale,
+          max_sessions: this.#ctx.config.users?.maxSessions,
+        },
+      });
+    };
+  }
+
+  /** Demonstrates HttpError — the framework renders it into the envelope. */
+  demoMissing(): RequestHandler {
+    return async () => {
+      throw new HttpError(404, "notFound", { details: { hint: "demo endpoint" } });
+    };
+  }
+
+  /** Demonstrates an unexpected error: anonymous 500 outside development. */
+  demoBoom(): RequestHandler {
+    return async () => {
+      throw new Error("secret internals that must not leak in production");
+    };
+  }
+}

package/templates/app/modules/users/i18n/en.json

@@ -0,0 +1,14 @@
+{
+  "created": "User {{email}} created",
+  "deleted": "User {{email}} deleted",
+  "notFound": "No such user",
+  "emailRequired": "An email address is required",
+  "list": {
+    "count_one": "{{count}} user",
+    "count_other": "{{count}} users"
+  },
+  "welcome": {
+    "subject": "Welcome, {{email}}"
+  },
+  "emailInvalid": "Must be a valid email address"
+}

package/templates/app/modules/users/i18n/fr.json

@@ -0,0 +1,14 @@
+{
+  "created": "Utilisateur {{email}} créé",
+  "deleted": "Utilisateur {{email}} supprimé",
+  "notFound": "Utilisateur introuvable",
+  "emailRequired": "Une adresse email est requise",
+  "list": {
+    "count_one": "{{count}} utilisateur",
+    "count_other": "{{count}} utilisateurs"
+  },
+  "welcome": {
+    "subject": "Bienvenue, {{email}}"
+  },
+  "emailInvalid": "Doit être une adresse email valide"
+}

package/templates/app/modules/users/models/user.model.ts

@@ -0,0 +1,18 @@
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+// Cross-module import by package name, never a relative path out of the
+// module — the dependency is declared in package.json, so it is visible.
+import { baseSchemaOptions } from "@app/core";
+
+const userSchema = new Schema(
+  {
+    email: { type: String, required: true, unique: true, lowercase: true },
+    role: { type: String, required: true, default: "user" },
+    // Retained for existing data/custom policies. The starter now authorizes
+    // sessions against Credential.version, which changes atomically with its hash.
+    tokens_valid_from: { type: Date },
+  },
+  baseSchemaOptions,
+);
+
+export default { name: "User", schema: userSchema } satisfies ModelDef;

package/templates/app/modules/users/module.acl.ts

@@ -0,0 +1,10 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+
+export default function usersAcl(acl: AclBuilder): void {
+  acl.allow("user", "users:read", "users:ping");
+  // The demo endpoints are open so the error-handling examples stay
+  // curl-able without a token.
+  acl.allow("guest", "users:demo-missing", "users:demo-boom", "users:ping");
+  // Everything else — create, delete, read-deleted — stays with admin,
+  // which already holds "*".
+}

package/templates/app/modules/users/module.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+export default defineConfig({
+  schema: z.object({
+    maxSessions: z.number().int().positive().default(5)
+      .describe("Max concurrent sessions per user; the oldest is evicted past it"),
+    signupMode: z.enum(["open", "invite", "closed"]).default("open")
+      .describe("Who can register: open to anyone, invite only, or nobody"),
+  }),
+});

package/templates/app/modules/users/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@app/users",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "app",
+    "priority": 10,
+    "dependsOn": [
+      "auth",
+      "core"
+    ]
+  },
+  "dependencies": {
+    "@app/auth": "workspace:*",
+    "@app/core": "workspace:*",
+    "@tulipes/bullmq": "workspace:*",
+    "@tulipes/core": "workspace:*",
+    "@tulipes/mongoose": "workspace:*",
+    "@tulipes/socket.io": "workspace:*",
+    "express": "^5",
+    "mongoose": "^8"
+  }
+}

package/templates/app/modules/users/queues/users.queues.ts

@@ -0,0 +1,31 @@
+import type { Ctx } from "@tulipes/core/boot";
+import type { JobSchemas, QueueRegistry } from "@tulipes/bullmq";
+import { z } from "zod/v4";
+
+import { moduleLogger } from "@app/core";
+
+/** The declaration: defines the queue, validates producers, types both sides. */
+export const jobs = {
+  "users.welcome": z.object({ email: z.email(), locale: z.string() }),
+} satisfies JobSchemas;
+
+/**
+ * Runs in BOTH process modes: backend registers the queue and produces into it,
+ * the worker process turns the processor into a live consumer.
+ */
+export default function usersQueues(ctx: Ctx, queues: QueueRegistry): void {
+  // The same logger the backend uses. In the worker process it writes
+  // to app-worker.log, so the two processes never share a file.
+  const log = moduleLogger(ctx.Environment, "users", ctx.mode);
+
+  queues.process("users.welcome", async (job) => {
+    // No request here to negotiate a locale from, so the one the caller
+    // was using travelled with the job. `ctx.t` binds this module's
+    // namespace explicitly — the part `req.t` normally does for free.
+    const t = ctx.t("users", job.data.locale);
+
+    log.info({ email: job.data.email, subject: t("welcome.subject", { email: job.data.email }) },
+      "sending welcome email");
+    return { sent: true };
+  });
+}