@trinacria/cli 0.1.1-alpha.1

package/dist/templates/api-events-rabbitmq/src/modules/events/events.provider.ts

@@ -0,0 +1,28 @@
+import type { EventProvider } from "@trinacria/events";
+import { EventsService } from "./events.service";
+
+export const DEMO_EVENT_NAME = "events.demo";
+
+export class EventsProvider implements EventProvider {
+  constructor(private readonly eventsService: EventsService) {}
+
+  subscriptions() {
+    return [
+      {
+        event: DEMO_EVENT_NAME,
+        handler: async (payload: unknown) => {
+          if (
+            payload &&
+            typeof payload === "object" &&
+            "message" in payload &&
+            typeof payload.message === "string"
+          ) {
+            this.eventsService.add(DEMO_EVENT_NAME, {
+              message: payload.message,
+            });
+          }
+        },
+      },
+    ];
+  }
+}

package/dist/templates/api-events-rabbitmq/src/modules/events/events.service.ts

@@ -0,0 +1,19 @@
+import type { EventRecord } from "./events.store";
+import { EventsStore } from "./events.store";
+
+export class EventsService {
+  constructor(private readonly store: EventsStore) {}
+
+  list(): EventRecord[] {
+    return this.store.list();
+  }
+
+  add(
+    name: string,
+    payload: {
+      message: string;
+    },
+  ): EventRecord {
+    return this.store.add(name, payload);
+  }
+}

package/dist/templates/api-events-rabbitmq/src/modules/events/events.store.ts

@@ -0,0 +1,42 @@
+import { randomUUID } from "node:crypto";
+
+export interface EventRecord {
+  id: string;
+  name: string;
+  payload: {
+    message: string;
+  };
+  receivedAt: Date;
+}
+
+const MAX_EVENTS = 100;
+
+export class EventsStore {
+  private readonly events: EventRecord[] = [];
+
+  add(
+    name: string,
+    payload: {
+      message: string;
+    },
+  ): EventRecord {
+    const entry: EventRecord = {
+      id: randomUUID(),
+      name,
+      payload,
+      receivedAt: new Date(),
+    };
+
+    this.events.unshift(entry);
+
+    if (this.events.length > MAX_EVENTS) {
+      this.events.length = MAX_EVENTS;
+    }
+
+    return entry;
+  }
+
+  list(): EventRecord[] {
+    return [...this.events];
+  }
+}

package/dist/templates/api-events-rabbitmq/src/modules/events/events.tokens.ts

@@ -0,0 +1,11 @@
+import { createToken } from "@trinacria/core";
+import type { EventProvider } from "@trinacria/events";
+import { EventsController } from "./events.controller";
+import { EventsService } from "./events.service";
+import { EventsStore } from "./events.store";
+
+export const EVENTS_STORE = createToken<EventsStore>("EVENTS_STORE");
+export const EVENTS_SERVICE = createToken<EventsService>("EVENTS_SERVICE");
+export const EVENTS_CONTROLLER =
+  createToken<EventsController>("EVENTS_CONTROLLER");
+export const EVENTS_PROVIDER = createToken<EventProvider>("EVENTS_PROVIDER");

package/dist/templates/api-events-rabbitmq/trinacria.config.mjs

@@ -0,0 +1,12 @@
+/** @type {import('@trinacria/cli').TrinacriaConfig} */
+
+const config = {
+  entry: "src/main.ts",
+  outDir: "dist",
+  watchDir: "src",
+  env: "development",
+  crashLoopWindowMs: 15_000,
+  maxConsecutiveCrashRestarts: 3,
+};
+
+export default config;

package/dist/templates/api-events-rabbitmq/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "target": "ES2022",
+    "module": "CommonJS",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/dist/templates/api-events-redis/.env.example

@@ -0,0 +1,18 @@
+# ------------------------------------------------------------
+# Local app runtime (used by `npm run dev -w api-events-redis`)
+# ------------------------------------------------------------
+ENV=development
+HOST=127.0.0.1
+PORT=4003
+OPENAPI_ENABLED=true
+CORS_ALLOWED_ORIGINS=
+REDIS_URL=redis://127.0.0.1:6379
+REDIS_CHANNEL=trinacria:events:demo
+
+# ------------------------------------------------------------
+# Docker runtime (used by `docker compose ... --env-file .../.env`)
+# ------------------------------------------------------------
+DOCKER_REDIS_PORT=6379
+DOCKER_API_PORT=4003
+DOCKER_REDIS_URL=redis://redis:6379
+DOCKER_REDIS_CHANNEL=trinacria:events:demo

package/dist/templates/api-events-redis/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:24-bookworm-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json tsconfig.base.json ./
+COPY packages ./packages
+COPY apps/api-events-redis ./apps/api-events-redis
+
+RUN npm ci
+RUN npm run build:packages
+RUN npm run build -w api-events-redis
+
+ENV HOST=0.0.0.0
+ENV PORT=4003
+
+EXPOSE 4003
+
+CMD ["npm", "run", "start", "-w", "api-events-redis"]

package/dist/templates/api-events-redis/README.md

@@ -0,0 +1,97 @@
+# API Example: Redis Events
+
+A minimal API-only example using Trinacria Events with Redis Pub/Sub transport.
+
+## Scope
+
+This app is intentionally a base template:
+
+- no authentication (no JWT/session/password flow)
+- no authorization roles/policies
+- no database persistence for domain data
+- focus only on event publish/consume flow via Redis
+
+## Endpoints
+
+- `GET /health`
+- `GET /events`
+- `POST /events/publish`
+- `GET /openapi.json`
+- `GET /docs` (Swagger UI)
+
+## Built-in middleware enabled
+
+- `requestId`
+- `requestLogger`
+- `cors`
+- `rateLimit`
+- `requestTimeout`
+- `securityHeaders`
+
+## First steps (local)
+
+1. Install dependencies from the monorepo root:
+
+```bash
+npm install
+```
+
+2. Copy the environment file:
+
+```bash
+cp apps/api-events-redis/.env.example apps/api-events-redis/.env.development
+```
+
+3. Make sure Redis is running locally and matches `REDIS_URL`.
+
+4. Start the API:
+
+```bash
+npm run dev -w api-events-redis
+```
+
+5. Verify the app is running:
+
+```bash
+curl http://127.0.0.1:4003/health
+```
+
+## Publish your first event
+
+```bash
+curl -X POST http://127.0.0.1:4003/events/publish \
+  -H 'content-type: application/json' \
+  -d '{"message":"hello redis events"}'
+```
+
+Then list consumed events:
+
+```bash
+curl http://127.0.0.1:4003/events
+```
+
+## Docker quick start
+
+1. Create the Docker env file from the same template:
+
+```bash
+cp apps/api-events-redis/.env.example apps/api-events-redis/.env
+```
+
+2. Edit the Docker section in `apps/api-events-redis/.env` if you want custom Redis credentials/ports.
+
+3. Start Redis + API using that `.env` file:
+
+```bash
+docker compose \
+  --env-file apps/api-events-redis/.env \
+  -f apps/api-events-redis/docker-compose.yml \
+  up --build
+```
+
+The API will be available at `http://127.0.0.1:${DOCKER_API_PORT}` (default `4003`).
+
+Compose services:
+
+- `redis`: Redis 7
+- `api`: this Trinacria API

package/dist/templates/api-events-redis/docker-compose.yml

@@ -0,0 +1,33 @@
+services:
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    ports:
+      - "${DOCKER_REDIS_PORT}:6379"
+    volumes:
+      - trinacria_api_redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  api:
+    build:
+      context: ../..
+      dockerfile: apps/api-events-redis/Dockerfile
+    environment:
+      ENV: development
+      HOST: 0.0.0.0
+      PORT: 4003
+      OPENAPI_ENABLED: true
+      REDIS_URL: ${DOCKER_REDIS_URL}
+      REDIS_CHANNEL: ${DOCKER_REDIS_CHANNEL}
+    ports:
+      - "${DOCKER_API_PORT}:4003"
+    depends_on:
+      redis:
+        condition: service_healthy
+
+volumes:
+  trinacria_api_redis_data:

package/dist/templates/api-events-redis/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "api-events-redis",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "start": "node ../../packages/cli/dist/index.js start",
+    "build": "node ../../packages/cli/dist/index.js build",
+    "dev": "node ../../packages/cli/dist/index.js dev"
+  },
+  "dependencies": {
+    "@trinacria/cli": "*",
+    "@trinacria/core": "*",
+    "@trinacria/events": "*",
+    "@trinacria/http": "*",
+    "@trinacria/schema": "*",
+    "redis": "^5.10.0"
+  }
+}

package/dist/templates/api-events-redis/src/global/config.service.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createToken } from "@trinacria/core";
+import {
+  formatValidationError,
+  Infer,
+  s,
+  ValidationError,
+} from "@trinacria/schema";
+
+export const configSchema = s.object({
+  ENV: s.enum(["development", "staging", "production"]).default("development"),
+  PORT: s.number({ coerce: true, int: true, min: 1, max: 65535 }).default(4003),
+  HOST: s.string().default("127.0.0.1"),
+  OPENAPI_ENABLED: s.boolean({ coerce: true }).default(true),
+  CORS_ALLOWED_ORIGINS: s.array(s.string(), { coerce: true }).default([]),
+  REDIS_URL: s.string(),
+  REDIS_CHANNEL: s.string().default("trinacria:events:demo"),
+});
+
+export type ConfigModel = Infer<typeof configSchema>;
+export const CONFIG_SERVICE = createToken<ConfigService>("CONFIG_SERVICE");
+
+export class ConfigService {
+  private readonly config: ConfigModel;
+
+  constructor() {
+    this.loadEnvFile();
+
+    try {
+      this.config = configSchema.parse(process.env);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        throw new Error(
+          formatValidationError(error, {
+            prefix: "Invalid environment configuration:",
+          }),
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  private loadEnvFile() {
+    const currentEnv = process.env.ENV || "development";
+    const fileNames = [".env", `.env.${currentEnv}`];
+    const roots = [
+      process.cwd(),
+      path.join(process.cwd(), "apps/api-events-redis"),
+    ];
+
+    fileNames.forEach((fileName) => {
+      roots.forEach((root) => {
+        const filePath = path.join(root, fileName);
+        if (!fs.existsSync(filePath)) {
+          return;
+        }
+
+        const data = fs.readFileSync(filePath, "utf8");
+        data.split("\n").forEach((line) => {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("#")) {
+            return;
+          }
+
+          const separatorIndex = trimmed.indexOf("=");
+          if (separatorIndex === -1) {
+            return;
+          }
+
+          const key = trimmed.slice(0, separatorIndex).trim();
+          const rawValue = trimmed.slice(separatorIndex + 1).trim();
+          const value =
+            (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"))
+              ? rawValue.slice(1, -1)
+              : rawValue;
+
+          process.env[key] = value;
+        });
+      });
+    });
+  }
+
+  get<K extends keyof ConfigModel>(key: K): ConfigModel[K] {
+    return this.config[key];
+  }
+
+  getAll(): ConfigModel {
+    return this.config;
+  }
+}

package/dist/templates/api-events-redis/src/global/controllers/swagger/docs.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API Events Redis Docs</title>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"
+    />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: "/openapi.json",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        tryItOutEnabled: true,
+        persistAuthorization: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+        layout: "StandaloneLayout",
+      });
+    </script>
+  </body>
+</html>

package/dist/templates/api-events-redis/src/global/controllers/swagger/swagger-docs.controller.ts

@@ -0,0 +1,79 @@
+import { createToken } from "@trinacria/core";
+import { HttpController, response } from "@trinacria/http";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { ConfigService } from "../../config.service";
+
+export const SWAGGER_DOCS_CONTROLLER = createToken<SwaggerDocsController>(
+  "SWAGGER_DOCS_CONTROLLER",
+);
+
+export class SwaggerDocsController extends HttpController {
+  constructor(private readonly config: ConfigService) {
+    super();
+  }
+
+  routes() {
+    return this.router()
+      .get("/docs", this.renderDocs, {
+        docs: {
+          excludeFromOpenApi: true,
+        },
+      })
+      .build();
+  }
+
+  async renderDocs() {
+    if (!this.config.get("OPENAPI_ENABLED")) {
+      return response({ message: "OpenAPI is disabled" }, { status: 404 });
+    }
+
+    return response(await readSwaggerHtml(), {
+      headers: {
+        "content-type": "text/html; charset=utf-8",
+        "content-security-policy": docsContentSecurityPolicy(),
+      },
+    });
+  }
+}
+
+let cachedSwaggerHtml: string | undefined;
+
+async function readSwaggerHtml(): Promise<string> {
+  if (cachedSwaggerHtml) {
+    return cachedSwaggerHtml;
+  }
+
+  const candidates = [
+    path.resolve(process.cwd(), "src/global/controllers/swagger/docs.html"),
+    path.resolve(
+      process.cwd(),
+      "apps/api-events-redis/src/global/controllers/swagger/docs.html",
+    ),
+  ];
+
+  for (const filePath of candidates) {
+    try {
+      cachedSwaggerHtml = await fs.readFile(filePath, "utf8");
+      return cachedSwaggerHtml;
+    } catch {
+      // keep trying next candidate
+    }
+  }
+
+  throw new Error("Swagger docs HTML template not found.");
+}
+
+function docsContentSecurityPolicy(): string {
+  return [
+    "default-src 'self'",
+    "base-uri 'self'",
+    "object-src 'none'",
+    "frame-ancestors 'none'",
+    "script-src 'self' 'unsafe-inline' https://unpkg.com",
+    "style-src 'self' 'unsafe-inline' https://unpkg.com",
+    "img-src 'self' data: blob:",
+    "font-src 'self' data: https://unpkg.com",
+    "connect-src 'self'",
+  ].join("; ");
+}

package/dist/templates/api-events-redis/src/global/redis.service.ts

@@ -0,0 +1,50 @@
+import { createClient, type RedisClientType } from "redis";
+import { createToken } from "@trinacria/core";
+import type { ConfigService } from "./config.service";
+
+export const REDIS_SERVICE = createToken<RedisService>("REDIS_SERVICE");
+
+export class RedisService {
+  private readonly publisherClient: RedisClientType;
+  private readonly subscriberClient: RedisClientType;
+
+  constructor(config: ConfigService) {
+    const redisUrl = config.get("REDIS_URL");
+
+    this.publisherClient = createClient({
+      url: redisUrl,
+    });
+
+    this.subscriberClient = createClient({
+      url: redisUrl,
+    });
+  }
+
+  async onInit(): Promise<void> {
+    if (!this.publisherClient.isOpen) {
+      await this.publisherClient.connect();
+    }
+
+    if (!this.subscriberClient.isOpen) {
+      await this.subscriberClient.connect();
+    }
+  }
+
+  getPublisherClient(): RedisClientType {
+    return this.publisherClient;
+  }
+
+  getSubscriberClient(): RedisClientType {
+    return this.subscriberClient;
+  }
+
+  async onDestroy(): Promise<void> {
+    if (this.publisherClient.isOpen) {
+      await this.publisherClient.quit();
+    }
+
+    if (this.subscriberClient.isOpen) {
+      await this.subscriberClient.quit();
+    }
+  }
+}

package/dist/templates/api-events-redis/src/global/register-global-controllers.ts

@@ -0,0 +1,20 @@
+import { TrinacriaApp } from "@trinacria/core";
+import { httpProvider } from "@trinacria/http";
+import { ConfigService, CONFIG_SERVICE } from "./config.service";
+import {
+  SWAGGER_DOCS_CONTROLLER,
+  SwaggerDocsController,
+} from "./controllers/swagger/swagger-docs.controller";
+
+export function registerGlobalControllers(
+  app: TrinacriaApp,
+  config: ConfigService,
+): void {
+  if (config.get("OPENAPI_ENABLED")) {
+    app.registerGlobalProvider(
+      httpProvider(SWAGGER_DOCS_CONTROLLER, SwaggerDocsController, [
+        CONFIG_SERVICE,
+      ]),
+    );
+  }
+}

package/dist/templates/api-events-redis/src/main.ts

@@ -0,0 +1,88 @@
+import { ConsoleLogger, TrinacriaApp, valueProvider } from "@trinacria/core";
+import { createEventsPlugin, RedisEventTransport } from "@trinacria/events";
+import {
+  cors,
+  createHttpPlugin,
+  createSecurityHeadersBuilder,
+  rateLimit,
+  requestId,
+  requestLogger,
+  requestTimeout,
+} from "@trinacria/http";
+import { CONFIG_SERVICE, ConfigService } from "./global/config.service";
+import { REDIS_SERVICE, RedisService } from "./global/redis.service";
+import { registerGlobalControllers } from "./global/register-global-controllers";
+import { EventsModule } from "./modules/events/events.module";
+
+async function bootstrap() {
+  const app = new TrinacriaApp();
+  const configService = new ConfigService();
+  const config = configService.getAll();
+  const eventsLogger = new ConsoleLogger("api-events-redis:events");
+  const isProduction = config.ENV === "production";
+  const corsOrigins = config.CORS_ALLOWED_ORIGINS;
+  const securityHeadersMiddleware = createSecurityHeadersBuilder()
+    .preset(config.ENV)
+    .trustProxy(false)
+    .build();
+
+  const redisService = new RedisService(configService);
+  await redisService.onInit();
+
+  app.registerGlobalProvider(valueProvider(CONFIG_SERVICE, configService));
+  app.registerGlobalProvider(valueProvider(REDIS_SERVICE, redisService));
+  registerGlobalControllers(app, configService);
+
+  app.use(
+    createHttpPlugin({
+      host: config.HOST,
+      port: config.PORT,
+      middlewares: [
+        requestId(),
+        requestLogger({ includeUserAgent: !isProduction }),
+        cors({
+          origin: corsOrigins.length > 0 ? corsOrigins : "*",
+          credentials: true,
+          methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
+        }),
+        rateLimit({
+          windowMs: 60_000,
+          max: isProduction ? 240 : 2_000,
+          trustProxy: false,
+        }),
+        requestTimeout({ timeoutMs: 15_000 }),
+        securityHeadersMiddleware,
+      ],
+      openApi: config.OPENAPI_ENABLED
+        ? {
+            enabled: true,
+            title: "API Events Redis Example",
+            version: "1.0.0",
+          }
+        : undefined,
+    }),
+  );
+
+  app.use(
+    createEventsPlugin({
+      transport: new RedisEventTransport({
+        publisher: redisService.getPublisherClient(),
+        subscriber: redisService.getSubscriberClient(),
+        channel: config.REDIS_CHANNEL,
+      }),
+      source: "api-events-redis",
+      dispatchLocalOnEmit: false,
+      onListenerError: (error, envelope) => {
+        eventsLogger.error(`Event listener error: ${envelope.name}`, error);
+      },
+    }),
+  );
+
+  await app.registerModule(EventsModule);
+  await app.start();
+}
+
+bootstrap().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});