@jumentix/cli-init 0.0.0

package/templates/backend/documentation/guides/CREATING-REST-API-WITH-JUMENTIX.md

@@ -0,0 +1,189 @@
+# Creating REST API with Jumentix
+
+## Responsibility in context
+
+- **Owns:** HTTP adapter + application use-cases for REST
+- **Used with:** sdk-rest-client, persistence packages, backend-template app hub
+- **Not responsible for:** WebSocket/gRPC realtime (see realtime guide) or offline IndexedDB (Cana)
+
+## What it is
+
+This guide walks you through bootstrapping, running, and validating a REST service
+using the Jumentix backend template. You will wire domain logic to an HTTP adapter
+(Express by default) and call the API from a typed client.
+
+## Why it exists
+
+Most junior teams start by editing controller files and hope routes stay aligned
+with documentation. Jumentix inverts that: **OpenAPI is the contract**, domain
+code sits in the center, and the HTTP framework is a replaceable adapter. This
+guide gives you a repeatable path from env profile → running server → green tests.
+
+## Prerequisites
+
+| Item | Required | Notes |
+| --- | --- | --- |
+| Bun 1.3.13+ | Yes | See [Getting started](/docs/jumentix/concepts/getting-started) |
+| Completed getting-started | Recommended | Mental model + Cana playground |
+| Backend template scaffold | Yes | Use the monorepo `apps/backend-template` or your internal bootstrap flow |
+| Service Management (optional) | For design-first teams | Domain Designer generates entities aligned with OpenAPI |
+
+**Environment file:** `apps/backend-template/src/config/.env.dev` (or your scaffold’s equivalent).
+
+## Glossary
+
+| Term | Meaning on this page |
+| --- | --- |
+| **REST** | HTTP API using verbs (GET, POST, …) and JSON payloads. |
+| **OpenAPI** | Spec at `spec/1.0.0.yml` describing paths, schemas, and operationIds. |
+| **Runtime profile** | Env vars (`JUMENTIX_HTTP_FRAMEWORK`, `JUMENTIX_REALTIME_API`) selecting adapters. |
+| **Controller** | Interface-layer class mapping HTTP requests to use-case calls. |
+| **Use case** | Application service implementing one business operation. |
+| **Repository port** | Interface for persistence; implemented by a database adapter. |
+| **HTTP adapter** | Express/Fastify/etc. module mounting routes from OpenAPI operationIds. |
+| **oas:check-routes** | Script verifying every OpenAPI path resolves to a registered handler. |
+
+## Numbered steps
+
+### Step 1 — Select the REST runtime profile (< 5 minutes)
+
+1. Open your env file (default: `apps/backend-template/src/config/.env.dev`).
+2. Set REST-only mode:
+
+```bash
+JUMENTIX_HTTP_FRAMEWORK=express
+JUMENTIX_REALTIME_API=no
+```
+
+Supported HTTP frameworks are listed on [HTTP adapters](/docs/jumentix/adapters/http).
+
+3. Start the dev server from the monorepo root:
+
+```bash
+bun run dev:http
+```
+
+Or from inside `apps/backend-template`:
+
+```bash
+bun run dev:rest
+```
+
+**Success check:** PM2 reports `jumentix-dev-http` online; curl or browser hits
+`/health` (or your scaffold’s health route) with HTTP 200.
+
+### Step 2 — Model domain and contracts (< 15 minutes)
+
+1. **Design-first (recommended):** open Service Management → Domain Designer.
+   Define entities, relationships, and bounded contexts.
+2. **Spec-first:** edit OpenAPI at `spec/1.0.0.yml` — add paths, schemas, and
+   stable `operationId` values.
+3. Keep request/response DTOs aligned with controller method inputs/outputs.
+4. Shared contract packages (`@jumentix/shared-contracts`) should mirror the same
+   shapes; see [/docs/jumentix/packages/shared-contracts](/docs/jumentix/packages/shared-contracts).
+
+**Success check:** `bun run oas:check-routes` passes with zero unresolved routes.
+
+### Step 3 — Implement the domain flow (< 30 minutes per feature)
+
+Follow the backend template layering — bottom to top:
+
+1. **Domain** — entities, value objects, domain events under `src/domain/`.
+2. **Ports** — repository and gateway interfaces your use cases depend on.
+3. **Use cases** — application services orchestrating domain rules.
+4. **Controllers** — translate HTTP DTOs ↔ use-case inputs/outputs.
+5. **Handlers** — framework-specific route bindings (Express router modules).
+
+Rule: **domain and use cases must not import Express/Fastify.** Only adapters do.
+
+**Success check:** unit tests for the use case pass without starting HTTP.
+
+### Step 4 — Bind to the HTTP adapter (< 10 minutes)
+
+1. Confirm `JUMENTIX_HTTP_FRAMEWORK` matches the adapter you wired.
+2. REST startup loads `start-rest-api.ts` (or your scaffold entry) which registers
+   handlers from module interfaces.
+3. Each OpenAPI `operationId` maps to one controller method via the adapter registry.
+
+Swap adapters by changing env only — domain code stays untouched:
+
+```bash
+JUMENTIX_HTTP_FRAMEWORK=fastify   # example; confirm support on adapters page
+```
+
+**Success check:** manual request to a new endpoint returns the contract-shaped JSON.
+
+### Step 5 — Validate quality gates (< 10 minutes)
+
+Run from monorepo root (or `bun --cwd ../..` from backend-template):
+
+```bash
+bun run lint
+bun run test:unit
+bun run oas:check-routes
+bun run test:integration:express
+```
+
+Optional smoke before pushing:
+
+```bash
+cd apps/backend-template && bun run test:integration:smoke
+```
+
+**Success check:** all four commands exit 0; integration test hits real HTTP against the running profile.
+
+### Step 6 — Call the API from a client (junior path)
+
+In Node or the browser docs playground, **inject the OpenAPI document** instead of
+loading it from disk with `fs`:
+
+```js
+const client = api.createMockClient();
+const result = await client.request({ method: 'GET', path: '/health' });
+console.log(result.status, result.body);
+```
+
+For production clients, use `@jumentix/sdk-rest-client` with the same injected spec
+in browser bundles.
+
+## Examples
+
+### Static mock client
+
+```js
+const client = api.createMockClient();
+const result = await client.request({ method: 'GET', path: '/health' });
+```
+
+### Interactive REST client playground
+
+Try the mocked REST client — **Run** should return a successful `/health` response:
+
+<DocsPlayground runtime="sdk-rest-client" id="getting-started" />
+
+## Common errors
+
+| Symptom | Likely cause | Fix | Verify success |
+| --- | --- | --- | --- |
+| PM2 process exits immediately | Invalid env file path or missing secret | Confirm `--env-file=./apps/backend-template/src/config/.env.dev` | `bun run dev:http` stays online |
+| `oas:check-routes` fails | OpenAPI path has no handler | Add handler + controller method; rerun check | Script exits 0 |
+| 404 on documented route | Wrong HTTP framework adapter loaded | Match `JUMENTIX_HTTP_FRAMEWORK` to wired module | curl returns 200 |
+| Integration test timeout | Server not running or wrong port | Start dev profile before integration suite | `test:integration:express` green |
+| Browser client cannot load YAML | `fs.readFile` in bundle | Inject parsed OpenAPI object (playground pattern) | Mock client works in browser |
+| Domain imports Express | Layer violation | Move HTTP code to adapter/handler layer | `arch:check-boundaries` passes |
+
+## Junior checklist (“I can …”)
+
+- [ ] Set `JUMENTIX_HTTP_FRAMEWORK` and `JUMENTIX_REALTIME_API=no` and start `bun run dev:http`.
+- [ ] Locate `spec/1.0.0.yml` and explain what an `operationId` is.
+- [ ] Add or trace one path: OpenAPI → controller → use case → repository port.
+- [ ] Run `bun run oas:check-routes` and `bun run test:integration:express` successfully.
+- [ ] Call `/health` via the sdk-rest-client playground (**Run** green).
+- [ ] Name one HTTP adapter alternative without changing domain code.
+
+## Next step
+
+When you need push notifications or live updates, continue to
+[Create a Realtime API](/docs/jumentix/guides/realtime-api). For adapter
+reference, see [HTTP adapters](/docs/jumentix/adapters/http) and
+[Errors and responses](/docs/jumentix/reference/errors-responses).

package/templates/backend/documentation/guides/CREATING-REST-API-WITH-JUMENTIX.pt-BR.md

@@ -0,0 +1,190 @@
+# Criando API REST com Jumentix
+
+## Responsabilidade no escopo
+
+- **Responsável por:** Adapter HTTP + use-cases de aplicação para REST
+- **Usado com:** sdk-rest-client, pacotes de persistência, hub do app backend-template
+- **Não responsável por:** Realtime WebSocket/gRPC (guia realtime) ou IndexedDB offline (Cana)
+
+## O que é
+
+Este guia mostra como inicializar, executar e validar um serviço REST usando o
+template de backend Jumentix. Você vai ligar lógica de domínio a um adaptador
+HTTP (Express por padrão) e chamar a API por um client tipado.
+
+## Por que existe
+
+Times júnior costumam editar controllers e esperar que rotas permaneçam alinhadas
+à documentação. O Jumentix inverte isso: **OpenAPI é o contrato**, o código de
+domínio fica no centro e o framework HTTP é um adaptador substituível. Este guia
+oferece um caminho repetível de perfil de env → servidor rodando → testes verdes.
+
+## Pré-requisitos
+
+| Item | Obrigatório | Notas |
+| --- | --- | --- |
+| Bun 1.3.13+ | Sim | Veja [Começando](/docs/pt-BR/jumentix/concepts/getting-started) |
+| Getting-started concluído | Recomendado | Modelo mental + playground Cana |
+| Scaffold backend-template | Sim | Use o monorepo `apps/backend-template` ou o fluxo interno de bootstrap |
+| Service Management (opcional) | Times design-first | Domain Designer gera entidades alinhadas ao OpenAPI |
+
+**Arquivo de ambiente:** `apps/backend-template/src/config/.env.dev` (ou equivalente do seu scaffold).
+
+## Glossário
+
+| Termo | Significado nesta página |
+| --- | --- |
+| **REST** | API HTTP com verbos (GET, POST, …) e payloads JSON. |
+| **OpenAPI** | Spec em `spec/1.0.0.yml` descrevendo paths, schemas e operationIds. |
+| **Perfil de runtime** | Variáveis de env (`JUMENTIX_HTTP_FRAMEWORK`, `JUMENTIX_REALTIME_API`) que selecionam adaptadores. |
+| **Controller** | Classe da camada de interface mapeando requests HTTP para casos de uso. |
+| **Caso de uso** | Serviço de aplicação implementando uma operação de negócio. |
+| **Porta de repositório** | Interface de persistência; implementada por adaptador de banco. |
+| **Adaptador HTTP** | Módulo Express/Fastify/etc. montando rotas a partir de operationIds OpenAPI. |
+| **oas:check-routes** | Script que verifica se todo path OpenAPI resolve para um handler registrado. |
+
+## Passos numerados
+
+### Passo 1 — Selecionar perfil REST (< 5 minutos)
+
+1. Abra seu arquivo de env (padrão: `apps/backend-template/src/config/.env.dev`).
+2. Configure modo só REST:
+
+```bash
+JUMENTIX_HTTP_FRAMEWORK=express
+JUMENTIX_REALTIME_API=no
+```
+
+Frameworks HTTP suportados estão em [Adaptadores HTTP](/docs/pt-BR/jumentix/adapters/http).
+
+3. Inicie o servidor dev na raiz do monorepo:
+
+```bash
+bun run dev:http
+```
+
+Ou de dentro de `apps/backend-template`:
+
+```bash
+bun run dev:rest
+```
+
+**Verificação de sucesso:** PM2 reporta `jumentix-dev-http` online; curl ou browser
+acessa `/health` (ou rota de health do scaffold) com HTTP 200.
+
+### Passo 2 — Modelar domínio e contratos (< 15 minutos)
+
+1. **Design-first (recomendado):** abra Service Management → Domain Designer.
+   Defina entidades, relacionamentos e contextos limitados.
+2. **Spec-first:** edite OpenAPI em `spec/1.0.0.yml` — adicione paths, schemas e
+   `operationId` estáveis.
+3. Mantenha DTOs de request/response alinhados às entradas/saídas do controller.
+4. Packages de contrato compartilhado (`@jumentix/shared-contracts`) devem espelhar
+   as mesmas formas; veja [/docs/pt-BR/jumentix/packages/shared-contracts](/docs/pt-BR/jumentix/packages/shared-contracts).
+
+**Verificação de sucesso:** `bun run oas:check-routes` passa sem rotas não resolvidas.
+
+### Passo 3 — Implementar fluxo de domínio (< 30 minutos por feature)
+
+Siga as camadas do backend template — de baixo para cima:
+
+1. **Domínio** — entidades, value objects, eventos em `src/domain/`.
+2. **Portas** — interfaces de repositório e gateway dos casos de uso.
+3. **Casos de uso** — serviços de aplicação orquestrando regras de domínio.
+4. **Controllers** — traduzem DTOs HTTP ↔ entradas/saídas do caso de uso.
+5. **Handlers** — bindings de rota específicos do framework (módulos Express).
+
+Regra: **domínio e casos de uso não importam Express/Fastify.** Só adaptadores importam.
+
+**Verificação de sucesso:** testes unitários do caso de uso passam sem subir HTTP.
+
+### Passo 4 — Vincular ao adaptador HTTP (< 10 minutos)
+
+1. Confirme que `JUMENTIX_HTTP_FRAMEWORK` corresponde ao adaptador ligado.
+2. O startup REST carrega `start-rest-api.ts` (ou entry do scaffold) registrando
+   handlers das interfaces de módulo.
+3. Cada `operationId` OpenAPI mapeia para um método de controller via registro do adaptador.
+
+Troque adaptadores só mudando env — código de domínio intacto:
+
+```bash
+JUMENTIX_HTTP_FRAMEWORK=fastify   # exemplo; confirme suporte na página de adaptadores
+```
+
+**Verificação de sucesso:** request manual a um endpoint novo retorna JSON no formato do contrato.
+
+### Passo 5 — Validar portões de qualidade (< 10 minutos)
+
+Execute na raiz do monorepo (ou `bun --cwd ../..` a partir de backend-template):
+
+```bash
+bun run lint
+bun run test:unit
+bun run oas:check-routes
+bun run test:integration:express
+```
+
+Smoke opcional antes do push:
+
+```bash
+cd apps/backend-template && bun run test:integration:smoke
+```
+
+**Verificação de sucesso:** os quatro comandos saem com código 0; teste de integração
+bate HTTP real contra o perfil rodando.
+
+### Passo 6 — Chamar a API de um client (caminho júnior)
+
+No Node ou no playground de docs do browser, **injete o documento OpenAPI** em vez
+de carregar do disco com `fs`:
+
+```js
+const client = api.createMockClient();
+const result = await client.request({ method: 'GET', path: '/health' });
+console.log(result.status, result.body);
+```
+
+Para clients de produção, use `@jumentix/sdk-rest-client` com a mesma spec injetada
+em bundles de browser.
+
+## Exemplos
+
+### Client mock estático
+
+```js
+const client = api.createMockClient();
+const result = await client.request({ method: 'GET', path: '/health' });
+```
+
+### Playground interativo REST client
+
+Experimente o client REST mockado — **Run** deve retornar `/health` com sucesso:
+
+<DocsPlayground runtime="sdk-rest-client" id="getting-started" />
+
+## Erros comuns
+
+| Sintoma | Causa provável | Correção | Verificar sucesso |
+| --- | --- | --- | --- |
+| Processo PM2 sai imediatamente | Caminho de env inválido ou secret ausente | Confirme `--env-file=./apps/backend-template/src/config/.env.dev` | `bun run dev:http` permanece online |
+| `oas:check-routes` falha | Path OpenAPI sem handler | Adicione handler + método de controller; rode de novo | Script sai com 0 |
+| 404 em rota documentada | Adaptador HTTP errado carregado | Alinhe `JUMENTIX_HTTP_FRAMEWORK` ao módulo ligado | curl retorna 200 |
+| Timeout em teste de integração | Servidor parado ou porta errada | Suba perfil dev antes da suite | `test:integration:express` verde |
+| Client browser não carrega YAML | `fs.readFile` no bundle | Injete objeto OpenAPI parseado (padrão do playground) | Mock client funciona no browser |
+| Domínio importa Express | Violação de camada | Mova código HTTP para adaptador/handler | `arch:check-boundaries` passa |
+
+## Checklist júnior (“Eu consigo …”)
+
+- [ ] Definir `JUMENTIX_HTTP_FRAMEWORK` e `JUMENTIX_REALTIME_API=no` e iniciar `bun run dev:http`.
+- [ ] Localizar `spec/1.0.0.yml` e explicar o que é um `operationId`.
+- [ ] Adicionar ou rastrear um path: OpenAPI → controller → caso de uso → porta de repositório.
+- [ ] Rodar `bun run oas:check-routes` e `bun run test:integration:express` com sucesso.
+- [ ] Chamar `/health` via playground sdk-rest-client (**Run** verde).
+- [ ] Citar um adaptador HTTP alternativo sem alterar código de domínio.
+
+## Próximo passo
+
+Quando precisar de push ou atualizações ao vivo, continue em
+[Criar API em tempo real](/docs/pt-BR/jumentix/guides/realtime-api). Para referência
+de adaptadores, veja [Adaptadores HTTP](/docs/pt-BR/jumentix/adapters/http) e
+[Erros e respostas](/docs/pt-BR/jumentix/reference/errors-responses).

package/templates/backend/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@jumentix/backend-template",
+  "version": "0.3.0",
+  "private": true,
+  "description": "Jumentix backend template workspace app",
+  "dependencies": {
+    "@jumentix/adapter-runtime-bootstrap": "workspace:*",
+    "@jumentix/database-client-factory": "workspace:*",
+    "@jumentix/dead-letter-queue": "workspace:*",
+    "@jumentix/external-db-repositories": "workspace:*",
+    "@jumentix/external-persistence-core": "workspace:*",
+    "@jumentix/external-store-proxy": "workspace:*",
+    "@jumentix/key-value-storage": "workspace:*",
+    "@jumentix/message-mediator": "workspace:*",
+    "@jumentix/mutex-service": "workspace:*",
+    "@jumentix/persistence-contracts": "workspace:*",
+    "@jumentix/sdk-grpc-client": "workspace:*"
+  },
+  "scripts": {
+    "build": "NODE_ENV=dev tsc -p ../../tsconfig.build.json",
+    "build:dev": "NODE_ENV=dev tsc -p ../../tsconfig.build.json",
+    "test": "NODE_ENV=dev bun ../../ci-cd/run-unit-tests.js",
+    "test:unit": "NODE_ENV=dev bun ../../ci-cd/run-unit-tests.js",
+    "test:integration": "NODE_ENV=dev jest ./test/integration --runInBand",
+    "test:integration:smoke": "JUMENTIX_JWT_TOKEN_SECRET_KEY=${JUMENTIX_JWT_TOKEN_SECRET_KEY:-ci_jwt_secret_key} NODE_ENV=ci bun ./scripts/run-api-smoke.js",
+    "lint": "eslint src test --ext .ts",
+    "coverage:patch": "bun ../../ci-cd/check-patch-coverage.js",
+    "ci:gate": "bun --cwd ../.. run ci:gate",
+    "ci:gate:strict": "bun --cwd ../.. run ci:gate:strict",
+    "typecheck": "NODE_ENV=dev tsc -p ../../tsconfig.build.json --noEmit",
+    "dev:rest": "bun --cwd ../.. run dev:http",
+    "dev:websocket-rest": "bun --cwd ../.. run dev:websocket",
+    "dev:grpc-rest": "bun --cwd ../.. run dev:grpc",
+    "pm2:start:dev:restapi": "bun --cwd ../.. run pm2:start:dev:restapi",
+    "pm2:start:dev:websocket-rest": "bun --cwd ../.. run pm2:start:dev:websocket-rest",
+    "pm2:start:dev:grpc-rest": "bun --cwd ../.. run pm2:start:dev:grpc-rest",
+    "pm2:start:staging:restapi": "bun --cwd ../.. run pm2:start:staging:restapi",
+    "pm2:start:staging:websocket-rest": "bun --cwd ../.. run pm2:start:staging:websocket-rest",
+    "pm2:start:staging:grpc-rest": "bun --cwd ../.. run pm2:start:staging:grpc-rest",
+    "pm2:start:prod:restapi": "bun --cwd ../.. run pm2:start:prod:restapi",
+    "pm2:start:prod:websocket-rest": "bun --cwd ../.. run pm2:start:prod:websocket-rest",
+    "pm2:start:prod:grpc-rest": "bun --cwd ../.. run pm2:start:prod:grpc-rest"
+  }
+}

package/templates/backend/scripts/purge-tombstones.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+/**
+ * JUM-822 — opt-in tombstone purge. Default is dry-run (stdout JSONL, no write).
+ * dev PM2 calls this with --via-loopback so the dev RestAPI process owns the store.
+ */
+
+const parseArgs = (argv) => {
+  const flags = {
+    commit: false,
+    protectSeed: true,
+    viaLoopback: false,
+    olderThan: 90,
+    port: Number(process.env.JUMENTIX_HTTP_PORT || 3000)
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--commit') flags.commit = true;
+    else if (arg === '--dry-run') flags.commit = false;
+    else if (arg === '--no-protect-seed') flags.protectSeed = false;
+    else if (arg === '--protect-seed') flags.protectSeed = true;
+    else if (arg === '--via-loopback') flags.viaLoopback = true;
+    else if (arg === '--older-than') {
+      flags.olderThan = Number(argv[i + 1]);
+      i += 1;
+    } else if (arg === '--port') {
+      flags.port = Number(argv[i + 1]);
+      i += 1;
+    }
+  }
+  if (!Number.isFinite(flags.olderThan) || flags.olderThan < 1) {
+    throw new Error('--older-than must be a positive number of days');
+  }
+  return flags;
+};
+
+const printReport = (report) => {
+  for (const event of report.events || []) {
+    process.stdout.write(`${JSON.stringify(event)}\n`);
+  }
+  process.stdout.write(`${JSON.stringify({
+    summary: true,
+    dryRun: report.dryRun,
+    olderThanDays: report.olderThanDays,
+    eligible: (report.events || []).length,
+    skippedProtected: report.skippedProtected,
+    skippedTooYoung: report.skippedTooYoung
+  })}\n`);
+};
+
+const viaLoopback = async (flags) => {
+  const url = `http://127.0.0.1:${flags.port}/internal/tombstones/purge`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      commit: flags.commit,
+      olderThanDays: flags.olderThan,
+      protectSeed: flags.protectSeed
+    })
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Purge loopback ${response.status}: ${text}`);
+  }
+  return response.json();
+};
+
+const main = async () => {
+  const flags = parseArgs(process.argv.slice(2));
+  if (!flags.viaLoopback) {
+    throw new Error(
+      'In-process dev stores live in the RestAPI process. Use --via-loopback against dev RestAPI.'
+    );
+  }
+  const report = await viaLoopback(flags);
+  printReport(report);
+};
+
+if (import.meta.main) {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('ECONNREFUSED') || message.includes('fetch failed')) {
+      process.stderr.write(`purge-tombstones: RestAPI not reachable (${message})\n`);
+      process.exit(0);
+    }
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, printReport };

package/templates/backend/scripts/run-api-smoke.js

@@ -0,0 +1,33 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CANDIDATE_SMOKE_TESTS = [
+  'apps/backend-template/test/integration/Express/get.localhost.test.ts',
+  'test/integration/Express/get.localhost.test.ts'
+];
+
+function run() {
+  const root = process.cwd();
+  const testFile = CANDIDATE_SMOKE_TESTS.find((target) => fs.existsSync(path.join(root, target)));
+
+  if (!testFile) {
+    console.error('[ci] api smoke: missing localhost smoke test file.');
+    console.error(`[ci] expected one of: ${CANDIDATE_SMOKE_TESTS.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`[ci] api smoke target: ${testFile}`);
+
+  const result = spawnSync('jest', [testFile, '--runInBand', '--coverage=false'], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'ci' }
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+run();

package/templates/backend/scripts/run-redis-dead-letter-integration.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/* eslint-disable no-console */
+/**
+ * Runs the dead-letter Redis integration suite against docker-compose-redis.
+ *
+ * JUM-53. Shares `passwordFromCompose` with the key-value runner rather than
+ * copying it: the reason that function exists — keeping the local requirepass
+ * out of package.json, where gitleaks finds it — applies identically here.
+ */
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { isEntryPoint } = require('../../../ci-cd/lib/entry-point.js');
+const { passwordFromCompose } = require('./run-redis-key-value-integration.js');
+
+const ROOT = process.cwd();
+
+function run() {
+  const env = { ...process.env, NODE_ENV: 'dev', RUN_REDIS_INTEGRATION: '1' };
+  if (!env.JUMENTIX_REDIS_PASSWORD) {
+    env.JUMENTIX_REDIS_PASSWORD = env.AAA_REDIS_PASSWORD || passwordFromCompose();
+  }
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      path.join(ROOT, 'ci-cd/run-suite.js'),
+      '--script-label',
+      'dead-letter',
+      'packages/dead-letter-queue/test/integration'
+    ],
+    { cwd: ROOT, env, stdio: 'inherit' }
+  );
+
+  if (result.error) throw result.error;
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+if (isEntryPoint(module)) {
+  process.exit(run());
+}
+
+module.exports = { run };

package/templates/backend/scripts/run-redis-key-value-integration.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env bun
+/* eslint-disable no-console */
+/**
+ * Runs the Redis key-value integration suite against docker-compose-redis.
+ *
+ * The compose file already carries the local requirepass (since 2024). Putting
+ * that same value into package.json scripts re-introduced it into the PR diff
+ * and failed gitleaks. This runner copies the password from the compose file
+ * into JUMENTIX_REDIS_PASSWORD only when the env var is unset, so package.json
+ * never embeds a secret and CI can still override via secrets. The legacy
+ * AAA_REDIS_PASSWORD name is still accepted as a fallback for older shells.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { isEntryPoint } = require('../../../ci-cd/lib/entry-point.js');
+
+const ROOT = process.cwd();
+const COMPOSE = path.join(
+  ROOT,
+  'apps/backend-template/docker-compose-redis.yml'
+);
+const REQUIREPASS = /--requirepass\s+(\S+)/;
+
+function passwordFromCompose(composePath = COMPOSE) {
+  const contents = fs.readFileSync(composePath, 'utf8');
+  const match = REQUIREPASS.exec(contents);
+  if (!match) {
+    throw new Error(
+      `[redis-integration] could not read --requirepass from ${composePath}`
+    );
+  }
+  return match[1];
+}
+
+function run() {
+  const env = { ...process.env, NODE_ENV: 'dev', RUN_REDIS_INTEGRATION: '1' };
+  if (!env.JUMENTIX_REDIS_PASSWORD) {
+    env.JUMENTIX_REDIS_PASSWORD =
+      env.AAA_REDIS_PASSWORD || passwordFromCompose();
+  }
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      path.join(ROOT, 'ci-cd/run-suite.js'),
+      '--script-label',
+      'key-value',
+      'packages/key-value-storage/test/integration'
+    ],
+    { cwd: ROOT, env, stdio: 'inherit' }
+  );
+
+  if (result.error) throw result.error;
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+if (isEntryPoint(module)) {
+  process.exit(run());
+}
+
+module.exports = { passwordFromCompose, run };