@zaaxch/tailframe 1.0.0 → 2.1.0

package/src/new.mjs

@@ -1,6 +1,38 @@
 import fs from "node:fs";
 import path from "node:path";
 import { authAppStoreSource, GenerateError } from "./generate.mjs";
+import {
+	appErrorSource,
+	applicationRoutesSource,
+	containerSource,
+	createRequestContextSource,
+	csrfSource,
+	firebaseSource,
+	getHealthSource,
+	getHealthTestSource,
+	getReadinessSource,
+	getReadinessTestSource,
+	healthRoutesSource,
+	healthSchemasSource,
+	httpErrorsSource,
+	mongoReadinessProbeSource,
+	readinessProbeSource,
+	redisReadinessProbeSource,
+	redisSource,
+	requestContextSource,
+	rpcHandlerSource,
+	rpcSource,
+	serverSource,
+	useCaseSource,
+	workerSource
+} from "./service-templates.mjs";
+import {
+	configureHttpSource,
+	healthApiSource,
+	uiErrorsSource,
+	uiHttpSource,
+	uiRpcSource
+} from "./ui-templates.mjs";
 
 function fail(message) {
 	throw new GenerateError(message);
@@ -45,9 +77,7 @@ const prettierConfig = {
 	endOfLine: "lf",
 	singleQuote: false
 };
-
-add(".prettierrc.json", JSON.stringify(prettierConfig, null, "\t"));
-add(".gitattributes", `* text=auto eol=lf
+const gitAttributes = `* text=auto eol=lf
 
 *.png binary
 *.jpg binary
@@ -55,7 +85,10 @@ add(".gitattributes", `* text=auto eol=lf
 *.gif binary
 *.ico binary
 *.pdf binary
-`);
+`;
+
+add(".prettierrc.json", JSON.stringify(prettierConfig, null, "\t"));
+add(".gitattributes", gitAttributes);
 
 const repos = [[svc, "Express/TypeScript API and background runtime."]];
 if (options.ui) repos.push([ui, "Vue/Vite customer interface."]);
@@ -132,7 +165,7 @@ Use this workflow for any new domain capability or operation. Add only the layer
 1. Identify the module, requested operations, entry points, and repositories in scope. Classify every intended file with the applicable AGENTS.md placement table before writing. Do not assume full CRUD.
 2. Read the root and every applicable child \`AGENTS.md\`.
 3. Inspect the nearest working module and tests.
-4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, integrations, UI modules, and the closed UI shell catalog on canonical paths with canonical names. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; complete the printed wiring checklist after each generation.
+4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, integrations, UI modules, and the closed UI shell catalog on canonical paths with canonical names. Service module generation also registers the new use case and mounts or extends its single route factory through deterministic composition-file edits. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; inspect the generated diff and complete only the remaining behavior-specific checklist.
 5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\` and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\` or \`src/modules/auth\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
 6. Define use cases as \`execute(context, input)\`. Keep trusted \`RequestContext\` separate from client input.
 7. Put ownership, RBAC, entitlements, and domain policies in use-case or domain code, not client bodies or route metadata.
@@ -140,7 +173,7 @@ Use this workflow for any new domain capability or operation. Add only the layer
 9. For persisted capabilities, prefer branded, domain-owned string IDs at domain and repository-port boundaries; generate the module's identifier file with \`tailframe generate identifiers <module> <NameId...>\`. Keep MongoDB \`ObjectId\` conversion inside MongoDB persistence adapters, using persistence-only document types rather than \`any\` to bypass the boundary.
 10. Let HTTP routes, jobs, workers, scheduled tasks, and CLIs invoke use cases directly; do not call one entry point from another.
 11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory. A UI module may import another only through a named file directly under the provider's public directory. Both graphs must remain acyclic. UI modules may import only the generated auth/theme app stores and \`ThemeToggle\` from app; every other app path is private.
-12. Add required container, route, client, navigation, worker, or process registration and focused tests. Route module views directly from \`app/router.ts\`. App views and shell components consume product modules only through named module \`public/\` entries; they never import module views or other internals.
+12. Verify generated container and route wiring, then add only dependency construction, client, navigation, worker, or process registration earned by real behavior. Route module views directly from \`app/router.ts\`. App views and shell components consume product modules only through named module \`public/\` entries; they never import module views or other internals.
 13. Run npm run validate:architecture in every affected repository, then run focused type checks and tests. Report repositories, operations, entry points, checks, placement decisions, and gaps.
 
 Do not create empty architectural layers, speculative operations, or mandatory controllers. Do not claim behavior from static files, weaken trusted context or persistence ownership, or change unrelated background behavior.
@@ -148,7 +181,6 @@ Do not create empty architectural layers, speculative operations, or mandatory c
 
 const svcDeps = {
 	"@dotenvx/dotenvx": "^1.39.1",
-	"body-parser": "^2.2.0",
 	cors: "^2.8.5",
 	express: "^4.21.2",
 	joi: "^17.13.3",
@@ -172,7 +204,7 @@ add(`${svc}/package.json`, JSON.stringify({
 		...(options.worker ? { "dev:worker": "nodemon --legacy-watch --exec ts-node -r tsconfig-paths/register src/worker.ts" } : {}),
 		build: "tsc && tsc-alias", start: "node dist/server.js",
 		...(options.worker ? { worker: "node dist/worker.js" } : {}),
-		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate --kind service .", format: "prettier --write src/",
+		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate --kind service .", format: "prettier --write src/", "format:check": "prettier --check src/",
 		"test:db:up": "docker compose -f docker-compose.test.yml up -d", "test:db:down": "docker compose -f docker-compose.test.yml down -v",
 		"docker:dev": "docker compose -f docker-compose.dev.yml up",
 		"docker:prod": "docker compose -f docker-compose.yml up -d",
@@ -189,6 +221,7 @@ module.exports = { projects: [
 	{ ...base, displayName: "integration", testMatch: ["**/*.integration.test.ts"] }
 ] };`);
 add(`${svc}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
+add(`${svc}/.gitattributes`, gitAttributes);
 add(`${svc}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\n*.log\nfirebase-service-account*.json\n`);
 add(`${svc}/.dockerignore`, `node_modules\ndist\n.git\n.env*\n!.env.example\n*.log\ndata\nfirebase-service-account*.json\n`);
 if (options.ui) add(".dockerignore", `**/node_modules\n**/dist\n**/.git\n**/.env*\n**/*.log\n**/data\n**/firebase-service-account*.json\n`);
@@ -206,106 +239,44 @@ export const env = {
 };`);
 const databaseSource = `import { MongoClient } from "mongodb";
 import { env } from "@/platform/config/env";
+
 export const mongo = new MongoClient(env.mongodbUri);
-export async function connectDatabase() { await mongo.connect(); return mongo.db(env.mongodbDbName); }
-export async function closeDatabase() { await mongo.close(); }`;
-add(`${svc}/src/platform/database/index.ts`, databaseSource);
-if (options.redis) add(`${svc}/src/platform/redis/index.ts`, `import { createClient, type RedisClientType } from "redis";
-import { env } from "@/platform/config/env";
-export const redis: RedisClientType = createClient({ url: env.redisUrl });
-redis.on("error", (error) => console.error("Redis client error", error));
-export async function connectRedis() { if (!redis.isOpen) await redis.connect(); return redis; }
-export async function closeRedis() { if (redis.isOpen) await redis.quit(); }
-`);
-add(`${svc}/src/core/RequestContext.ts`, `export interface AuthenticatedPrincipal {\n\tuid: string;\n\temail?: string;\n}\nexport interface RequestContext {\n\trequestId: string;\n\tprincipal?: AuthenticatedPrincipal;\n\troles: string[];\n}\n`);
-add(`${svc}/src/core/UseCase.ts`, `import type { RequestContext } from "@/core/RequestContext";\nexport interface UseCase<Input, Output> {\n\texecute(context: RequestContext, input: Input): Promise<Output>;\n}\n`);
-add(`${svc}/src/platform/http/createRequestContext.ts`, options.auth === "firebase" ? `import { randomUUID } from "node:crypto";
-import type { Request } from "express";
-import type { RequestContext } from "@/core/RequestContext";
-import { verifyFirebaseToken } from "@/platform/auth/firebase";
-export async function createRequestContext(req: Request): Promise<RequestContext> {
-	const requestId = String(req.headers["x-request-id"] ?? randomUUID());
-	const decoded = req.headers.authorization?.startsWith("Bearer ") ? await verifyFirebaseToken(req.headers.authorization.slice(7)) : undefined;
-	return { requestId, principal: decoded ? { uid: decoded.uid, email: decoded.email } : undefined, roles: [] };
-}
-export function systemRequestContext(requestId = "system"): RequestContext { return { requestId, roles: [] }; }
-` : `import { randomUUID } from "node:crypto";
-import type { Request } from "express";
-import type { RequestContext } from "@/core/RequestContext";
-export function createRequestContext(req: Request): RequestContext {
-	return { requestId: String(req.headers["x-request-id"] ?? randomUUID()), roles: [] };
-}
-export function systemRequestContext(requestId = "system"): RequestContext { return { requestId, roles: [] }; }
-`);
-if (options.auth === "firebase") add(`${svc}/src/platform/auth/firebase.ts`, `import { applicationDefault, getApps, initializeApp } from "firebase-admin/app";
-import { getAuth, type DecodedIdToken } from "firebase-admin/auth";
-import { env } from "@/platform/config/env";
-export function verifyFirebaseToken(token: string): Promise<DecodedIdToken> {
-	if (!getApps().length) initializeApp({ credential: applicationDefault(), projectId: env.firebaseProjectId || undefined });
-	return getAuth().verifyIdToken(token);
-}`);
-add(`${svc}/src/platform/http/rpc.ts`, `import type { Response } from "express";\nexport function rpcResult(res: Response, result: unknown) { return res.json({ result }); }\n`);
-add(`${svc}/src/platform/http/errors.ts`, `import type { ErrorRequestHandler } from "express";
-export const errorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
-	if (error?.isJoi) { res.status(400).json({ error: { message: error.message } }); return; }
-	const status = Number(error?.status ?? 500);
-	res.status(status).json({ error: { message: status === 500 ? "Internal server error" : error.message } });
-};
-`);
-add(`${svc}/src/modules/health/use-cases/GetHealth.ts`, `import type { UseCase } from "@/core/UseCase";\nimport type { RequestContext } from "@/core/RequestContext";\nexport type HealthResult = { status: "ok" };\nexport class GetHealth implements UseCase<Record<string, never>, HealthResult> {\n\tasync execute(_context: RequestContext, _input: Record<string, never>): Promise<HealthResult> { return { status: "ok" }; }\n}\n`);
-add(`${svc}/src/modules/health/http/health.schemas.ts`, `import Joi from "joi";\nexport const GetHealthSchema = Joi.object({}).unknown(false);\n`);
-add(`${svc}/src/modules/health/http/health.routes.ts`, `import { Router } from "express";\nimport type { GetHealth } from "@/modules/health/use-cases/GetHealth";\nimport { GetHealthSchema } from "@/modules/health/http/health.schemas";\nimport { createRequestContext } from "@/platform/http/createRequestContext";\nimport { rpcResult } from "@/platform/http/rpc";\nexport function healthRoutes(getHealth: GetHealth) {\n\tconst router = Router();\n\trouter.post("/health.get", async (req, res, next) => { try { const input = await GetHealthSchema.validateAsync(req.body ?? {}); rpcResult(res, await getHealth.execute(await createRequestContext(req), input)); } catch (error) { next(error); } });\n\treturn router;\n}\n`);
-add(`${svc}/src/app/container.ts`, `import { container } from "tsyringe";\nimport { GetHealth } from "@/modules/health/use-cases/GetHealth";\ncontainer.registerSingleton(GetHealth, GetHealth);\nexport { container };\n`);
-add(`${svc}/src/app/routes.ts`, `import { Router } from "express";\nimport { container } from "@/app/container";\nimport { GetHealth } from "@/modules/health/use-cases/GetHealth";\nimport { healthRoutes } from "@/modules/health/http/health.routes";\nexport function applicationRoutes() { const router = Router(); router.use(healthRoutes(container.resolve(GetHealth))); return router; }\n`);
-add(`${svc}/src/app/server.ts`, `import path from "node:path";
-import express from "express";
-import cors from "cors";
-import { applicationRoutes } from "@/app/routes";
-import { env } from "@/platform/config/env";
-import { connectDatabase, closeDatabase } from "@/platform/database";
-import { errorHandler } from "@/platform/http/errors";
-export interface ApplicationOptions { publicPath?: string; production?: boolean; }
-export function createApplication(options: ApplicationOptions = {}) {
-	const app = express();
-	${options.ui ? `const publicPath = options.publicPath ?? path.join(__dirname, "..", "public");
-	const production = options.production ?? env.nodeEnv === "production";
-	if (production) app.use(express.static(publicPath, { index: false, maxAge: "1y", immutable: true }));` : ""}
-	app.use(cors({ origin: env.corsOrigin }));
-	app.use(express.json());
-	app.use("/api/v1", applicationRoutes());
-	${options.ui ? `if (production) {
-		app.get(/^(?!\\/api(?:\\/|$)).*/, (_req, res) => res.sendFile(path.join(publicPath, "index.html")));
-	}` : ""}
-	app.use(errorHandler);
-	return app;
-}
-export async function startServer() {
-	await connectDatabase();
-	const app = createApplication();
-	const server = app.listen(env.port);
-	const shutdown = async () => { server.close(); await closeDatabase(); };
-	process.once("SIGINT", shutdown);
-	process.once("SIGTERM", shutdown);
-	return { app, server, shutdown };
+
+export async function connectDatabase() {
+	await mongo.connect();
+	return mongo.db(env.mongodbDbName);
 }
-`);
+
+export async function closeDatabase() {
+	await mongo.close();
+}`;
+add(`${svc}/src/platform/database/index.ts`, databaseSource);
+if (options.redis) add(`${svc}/src/platform/redis/index.ts`, redisSource);
+add(`${svc}/src/core/RequestContext.ts`, requestContextSource);
+add(`${svc}/src/core/UseCase.ts`, useCaseSource);
+add(`${svc}/src/core/errors.ts`, appErrorSource);
+add(`${svc}/src/platform/http/createRequestContext.ts`, createRequestContextSource(options.auth));
+if (options.auth === "firebase") add(`${svc}/src/platform/auth/firebase.ts`, firebaseSource);
+add(`${svc}/src/platform/http/rpc.ts`, rpcSource);
+add(`${svc}/src/platform/http/rpcHandler.ts`, rpcHandlerSource);
+add(`${svc}/src/platform/http/errors.ts`, httpErrorsSource);
+const csrf = options.auth === "firebase" && options.ui;
+if (csrf) add(`${svc}/src/platform/http/csrf.ts`, csrfSource);
+add(`${svc}/src/modules/health/use-cases/GetHealth.ts`, getHealthSource);
+add(`${svc}/src/modules/health/use-cases/GetReadiness.ts`, getReadinessSource);
+add(`${svc}/src/modules/health/use-cases/ports/ReadinessProbe.ts`, readinessProbeSource);
+add(`${svc}/src/modules/health/http/health.schemas.ts`, healthSchemasSource);
+add(`${svc}/src/modules/health/http/health.routes.ts`, healthRoutesSource);
+add(`${svc}/src/platform/integrations/mongodb/MongoReadinessProbe.ts`, mongoReadinessProbeSource);
+if (options.redis) add(`${svc}/src/platform/integrations/redis/RedisReadinessProbe.ts`, redisReadinessProbeSource);
+add(`${svc}/src/app/container.ts`, containerSource({ redis: options.redis }));
+add(`${svc}/src/app/routes.ts`, applicationRoutesSource);
+add(`${svc}/src/app/server.ts`, serverSource({ ui: options.ui, redis: options.redis, csrf }));
 add(`${svc}/src/server.ts`, `import "reflect-metadata";\nimport { startServer } from "@/app/server";\nvoid startServer();\n`);
-if (options.worker) add(`${svc}/src/app/workers/startWorker.ts`, `import { connectDatabase, closeDatabase } from "@/platform/database";
-import { connectRedis, closeRedis } from "@/platform/redis";
-import { systemRequestContext } from "@/platform/http/createRequestContext";
-import { GetHealth } from "@/modules/health/use-cases/GetHealth";
-// Workers invoke use cases directly. Add real scheduled work only with an explicit domain workflow.
-export async function startWorker() {
-	await connectDatabase();
-	await connectRedis();
-	console.log("${title} worker runtime ready", await new GetHealth().execute(systemRequestContext(), {}));
-	const shutdown = async () => { await closeDatabase(); await closeRedis(); process.exit(0); };
-	process.once("SIGINT", shutdown);
-	process.once("SIGTERM", shutdown);
-}
-`);
+if (options.worker) add(`${svc}/src/app/workers/startWorker.ts`, workerSource());
 if (options.worker) add(`${svc}/src/worker.ts`, `import "reflect-metadata";\nimport { startWorker } from "@/app/workers/startWorker";\nvoid startWorker();\n`);
-add(`${svc}/src/modules/health/__tests__/GetHealth.test.ts`, `import { GetHealth } from "@/modules/health/use-cases/GetHealth";\ndescribe("GetHealth", () => { it("returns readiness through the use-case contract", async () => { await expect(new GetHealth().execute({ requestId: "test", roles: [] }, {})).resolves.toEqual({ status: "ok" }); }); });\n`);
+add(`${svc}/src/modules/health/__tests__/GetHealth.test.ts`, getHealthTestSource);
+add(`${svc}/src/modules/health/__tests__/GetReadiness.test.ts`, getReadinessTestSource);
 add(`${svc}/src/__tests__/testDb.ts`, `import { MongoClient } from "mongodb";
 const client = new MongoClient(process.env.TEST_MONGODB_URI ?? "mongodb://localhost:27018/?replicaSet=rs0&directConnection=true");
 export async function openTestDatabase() { await client.connect(); return client.db(process.env.TEST_MONGODB_DB_NAME ?? "${options.name.replaceAll("-", "_")}_test"); }
@@ -344,24 +315,57 @@ services:
           }
         '
 `);
+const boundaryRequest = (expression) => csrf ? `browser(${expression})` : expression;
 add(`${svc}/src/app/__tests__/boundary.integration.test.ts`, `import request from "supertest";
-${options.ui ? 'import path from "node:path";\n' : ""}
+${options.ui ? 'import path from "node:path";\n' : ""}${options.redis ? 'import type { RedisClientType } from "redis";\n' : ""}
+import { registerDependencies } from "@/app/container";
 import { createApplication } from "@/app/server";
 import { closeTestDatabase, resetTestDatabase } from "@/__tests__/testDb";
+${options.redis ? `
+const stubRedis = {
+	ping: async () => "PONG"
+} as unknown as RedisClientType;
+` : ""}${csrf ? `
+const browser = (agent: request.Test) => agent.set("X-Requested-With", "XMLHttpRequest");
+` : ""}
 describe("HTTP boundary", () => {
-	beforeAll(async () => { await resetTestDatabase(); });
-	afterAll(async () => { await closeTestDatabase(); });
-	it("returns a successful RPC envelope", async () => {
-		await request(createApplication()).post("/api/v1/health.get").send({}).expect(200).expect(({ body }) => {
-			expect(body).toEqual({ result: { status: "ok" } });
-		});
+	beforeAll(async () => {
+		registerDependencies({ db: await resetTestDatabase()${options.redis ? ", redis: stubRedis" : ""} });
+	});
+	afterAll(async () => {
+		await closeTestDatabase();
+	});
+
+	it("returns successful RPC envelopes", async () => {
+		await ${boundaryRequest('request(createApplication()).post("/api/v1/health.get")')}
+			.send({})
+			.expect(200)
+			.expect(({ body }) => expect(body).toEqual({ result: { status: "ok" } }));
+		await ${boundaryRequest('request(createApplication()).post("/api/v1/health.readiness")')}
+			.send({})
+			.expect(200)
+			.expect(({ body }) => expect(body).toEqual({ result: { status: "ready" } }));
+	});
+
+	it("returns a validation error envelope with a machine-readable code", async () => {
+		await ${boundaryRequest('request(createApplication()).post("/api/v1/health.get")')}
+			.send({ unexpected: true })
+			.expect(400)
+			.expect(({ body }) => {
+				expect(body.error.code).toBe("VALIDATION_FAILED");
+				expect(body.error.message).toEqual(expect.any(String));
+			});
 	});
-	it("returns a validation error envelope", async () => {
-		await request(createApplication()).post("/api/v1/health.get").send({ unexpected: true }).expect(400).expect(({ body }) => {
-			expect(body.error.message).toEqual(expect.any(String));
-		});
+${csrf ? `
+	it("rejects a mutating browser request without the CSRF header", async () => {
+		await request(createApplication())
+			.post("/api/v1/health.get")
+			.send({})
+			.expect(403)
+			.expect(({ body }) => expect(body.error.code).toBe("CSRF_HEADER_MISSING"));
 	});
-${options.ui ? `	it("serves the production SPA without falling through for API paths", async () => {
+` : ""}${options.ui ? `
+	it("serves the production SPA without falling through for API paths", async () => {
 		const app = createApplication({ production: true, publicPath: path.join(__dirname, "fixtures/public") });
 		await request(app).get("/dashboard").expect(200).expect(({ text }) => expect(text).toContain("boundary-test-spa"));
 		await request(app).get("/api/v1/does-not-exist").expect(404);
@@ -402,12 +406,15 @@ Product vocabulary stays in the module that owns its meaning; never move it into
 
 ## Public API contract
 - Use singular RPC-shaped \`POST /api/v1/<module>.<operation>\` operations and the \`{ result: ... }\` success envelope.
+- Give each module one \`<module>.routes.ts\` file with exactly one \`<module>Routes\` factory. Pass multiple operations through one named use-case object.
+- Name request schemas after operations in PascalCase and end them with \`Schema\`. Translate RPC POST requests only through \`src/platform/http/rpcHandler.ts\`; keep redirects, callbacks, and other non-RPC HTTP behavior explicit.
 - Implement only requested operations; do not create speculative CRUD.
 
 ## Module ownership
 - Create architecture files only with \`tailframe generate\`; hand-created architecture files are a conformance violation.
 - Colocate capability code under \`src/modules/<module>\`.
 - Start with \`use-cases/\`, required \`http/\` translation, and tests. Add \`domain/\` or \`persistence/\` only when real behavior earns them.
+- Keep one named use-case class, port, adapter, or domain concept per file. Do not bundle operations or framework injection metadata into product files.
 - Use cases expose \`execute(context, input)\` and remain callable from HTTP, jobs, workers, scheduled tasks, or CLIs.
 - Do not require controllers that only validate and delegate.
 
@@ -435,18 +442,23 @@ This service uses MongoDB. Module-owned MongoDB adapters own collection access,
 - HTTP routes, jobs, workers, scheduled tasks, and CLIs call use cases directly; they do not call each other.
 - Keep external-system clients under \`src/platform/integrations/<provider>\` and adapt them through module-owned ports.
 - Keep optional entry-point assembly under \`src/app/<entry-point-kind>\`; root files such as \`src/server.ts\` and \`src/worker.ts\` may only bootstrap that assembly.
-- Register dependencies, routes, workers, and jobs explicitly.
+- Initialize infrastructure first, then call \`registerDependencies(...)\` from every process entry point. The composition root resets the container, explicitly constructs dependencies, and registers class-token instances. Keep tsyringe, injection tokens, decorators, and container resolution out of modules and platform adapters.
+- Register routes, workers, and jobs explicitly. Shutdown paths are awaitable and close resources without forcing \`process.exit\`.
 ${options.ui ? "- In production, serve the compiled UI from `dist/public` with a non-API SPA fallback. Never return the SPA for `/api` requests." : ""}
 
+## Production image
+The ECR build targets \`linux/amd64\`. ${options.ui ? "Its default immutable tag is `<service-sha>_<ui-sha>` and production Compose requires that exact tag." : "Its default immutable tag is `<service-sha>` and production Compose requires that exact tag."}${options.ui && options.auth === "firebase" ? ` The build requires \`${ui}/.env.production\` and mounts it as a BuildKit secret only while Vite compiles the browser bundle; it is not copied into the final image.` : ""}
+
 ## Tests and validation
-Run \`npm run validate:architecture\` after changing files or imports. The generated service also includes unit tests and Mongo-backed integration tests. Run \`npm run test:db:up\`, \`npm test\`, and \`npm run test:db:down\` for the full service check. Test use cases, policies, Mongo repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need Mongo ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including \`npm run docker:push\`, must run outside the sandbox from the first attempt.
+Run \`npm run validate:architecture\` and \`npm run format:check\` after changing files or imports. The generated service also includes unit tests and Mongo-backed integration tests. Run \`npm run test:db:up\`, \`npm test\`, and \`npm run test:db:down\` for the full service check. Test use cases, policies, Mongo repository adapters, and HTTP boundaries where behavior lives. Every public operation needs success and error-envelope coverage; authenticated operations need trusted-identity coverage; persisted capabilities need Mongo ownership/query coverage; UI-enabled services must verify that \`/api\` paths never fall through to the SPA. All AWS/ECR and Docker commands, including \`npm run docker:push\`, must run outside the sandbox from the first attempt.
 `);
 
 if (options.ui) {
 const uiDeps = { "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
 const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@zaaxch/tailframe": contractVersion, "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
-add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest", "validate:architecture": "tailframe validate --kind ui .", format: "prettier --write src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
+add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate --kind ui .", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
 add(`${ui}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
+add(`${ui}/.gitattributes`, gitAttributes);
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
 add(`${ui}/tsconfig.app.json`, JSON.stringify({ extends: "@vue/tsconfig/tsconfig.dom.json", include: ["env.d.ts", "src/**/*", "src/**/*.vue"], compilerOptions: { composite: true, baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));
 add(`${ui}/tsconfig.node.json`, JSON.stringify({ extends: "@tsconfig/node22/tsconfig.json", include: ["vite.config.*"], compilerOptions: { composite: true, types: ["node"] } }, null, "\t"));
@@ -467,17 +479,63 @@ add(`${ui}/index.html`, `<!doctype html>
 `);
 add(`${ui}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\ncerts/\n*.log\n`);
 if (options.auth === "firebase") add(`${ui}/.env.example`, `VITE_FIREBASE_API_KEY=\nVITE_FIREBASE_AUTH_DOMAIN=\nVITE_FIREBASE_PROJECT_ID=\nVITE_FIREBASE_APP_ID=\n`);
-add(`${ui}/src/core/rpc.ts`, `export interface RpcResponse<T> { result: T; }\nexport interface RpcError { error: { message: string; code?: string }; }`);
+add(`${ui}/src/core/errors.ts`, uiErrorsSource);
+add(`${ui}/src/core/rpc.ts`, uiRpcSource);
 if (options.auth === "firebase") {
 	add(`${ui}/src/platform/firebase.ts`, `import { initializeApp } from "firebase/app";\nimport { getAuth, GoogleAuthProvider } from "firebase/auth";\n\nconst firebaseApp = initializeApp({\n\tapiKey: import.meta.env.VITE_FIREBASE_API_KEY,\n\tauthDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,\n\tprojectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,\n\tappId: import.meta.env.VITE_FIREBASE_APP_ID\n});\n\nexport const auth = getAuth(firebaseApp);\nexport const googleProvider = new GoogleAuthProvider();`);
 	add(`${ui}/src/app/stores/auth.store.ts`, authAppStoreSource());
 }
 add(`${ui}/src/core/RouteNames.ts`, `/** Route vocabulary shared by the router and by modules. Modules never import the router itself. */\nexport enum RouteNames {\n\tHOME = "Home"\n}\n`);
-add(`${ui}/src/app/router.ts`, `import { createRouter, createWebHistory } from "vue-router";\nimport { RouteNames } from "@/core/RouteNames";\nexport default createRouter({ history: createWebHistory(), routes: [{ path: "/", name: RouteNames.HOME, component: () => import("@/app/views/HomeView.vue") }] });`);
-add(`${ui}/src/platform/http.ts`, `import axios from "axios";\nexport const http = axios.create({ baseURL: \`\${window.location.origin}/api/v1\`, headers: { "Content-Type": "application/json" } });`);
-if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, `import type { Pinia } from "pinia";\nimport router from "@/app/router";\nimport { RouteNames } from "@/core/RouteNames";\nimport { useAuthStore } from "@/app/stores/auth.store";\nimport { http } from "@/platform/http";\nexport function configureHttp(pinia: Pinia) {\n\tconst auth = useAuthStore(pinia);\n\thttp.interceptors.request.use(async config => { const token = await auth.getIdToken(); if (token) config.headers.Authorization = \`Bearer \${token}\`; return config; });\n\thttp.interceptors.response.use(response => response, async error => { if (error?.response?.status === 401) { await auth.logout(); await router.push({ name: RouteNames.HOME }); } return Promise.reject(error); });\n}\n`);
-add(`${ui}/src/modules/health/api/health.api.ts`, `import { http } from "@/platform/http";\nimport type { RpcResponse } from "@/core/rpc";\nexport async function getHealth() { return (await http.post<RpcResponse<{ status: string }>>("health.get")).data.result; }`);
-add(`${ui}/src/app/views/HomeView.vue`, `<template><main class="mx-auto flex min-h-screen max-w-5xl flex-col justify-center gap-4 px-6 py-16"><p class="font-bold uppercase tracking-[0.12em] text-emerald-800">Project foundation</p><h1 class="m-0 text-5xl font-bold sm:text-7xl">${title}</h1><p>The product domain is intentionally undefined.</p></main></template>`);
+add(`${ui}/src/app/router.ts`, `import { createRouter, createWebHistory } from "vue-router";
+import { RouteNames } from "@/core/RouteNames";
+
+export default createRouter({
+	history: createWebHistory(),
+	routes: [{ path: "/", name: RouteNames.HOME, component: () => import("@/modules/health/views/HealthView.vue") }]
+});`);
+add(`${ui}/src/platform/http.ts`, uiHttpSource);
+if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, configureHttpSource);
+add(`${ui}/src/modules/health/api/health.api.ts`, healthApiSource);
+add(`${ui}/src/modules/health/views/HealthView.vue`, `<script setup lang="ts">
+import { ref } from "vue";
+import { isServiceError } from "@/core/errors";
+import { getReadiness } from "@/modules/health/api/health.api";
+
+const loading = ref(false);
+const status = ref("");
+const error = ref("");
+
+async function checkReadiness() {
+	loading.value = true;
+	status.value = "";
+	error.value = "";
+	try {
+		status.value = (await getReadiness()).status;
+	} catch (value) {
+		error.value = isServiceError(value) ? value.message : "Readiness check failed";
+	} finally {
+		loading.value = false;
+	}
+}
+</script>
+
+<template>
+	<main class="mx-auto flex min-h-screen max-w-5xl flex-col justify-center gap-4 px-6 py-16">
+		<p class="font-bold uppercase tracking-[0.12em] text-emerald-800">Architecture reference</p>
+		<h1 class="m-0 text-5xl font-bold sm:text-7xl">${title}</h1>
+		<p>The product domain is intentionally undefined.</p>
+		<button
+			type="button"
+			class="self-start rounded-full bg-emerald-800 px-4 py-3 text-white disabled:opacity-60"
+			:disabled="loading"
+			@click="checkReadiness"
+		>
+			{{ loading ? "Checking…" : "Check readiness" }}
+		</button>
+		<p v-if="status" role="status">Service status: {{ status }}</p>
+		<p v-if="error" role="alert">{{ error }}</p>
+	</main>
+</template>`);
 add(`${ui}/src/app/App.vue`, `<template><RouterView /></template><script setup lang="ts">import { RouterView } from "vue-router";</script>`);
 add(`${ui}/src/app/startApplication.ts`, `import { createApp } from "vue";\nimport { createPinia } from "pinia";\nimport PrimeVue from "primevue/config";\nimport App from "@/app/App.vue";\n${options.auth === "firebase" ? 'import { configureHttp } from "@/app/configureHttp";\n' : ""}import router from "@/app/router";\nimport "@/app/styles.css";\nexport function startApplication() {\n\tconst app = createApp(App);\n\tconst pinia = createPinia();\n\tapp.use(pinia).use(PrimeVue).use(router);\n\t${options.auth === "firebase" ? "configureHttp(pinia);\n\t" : ""}app.mount("#app");\n}\n`);
 add(`${ui}/src/main.ts`, `import { startApplication } from "@/app/startApplication";\nstartApplication();\n`);
@@ -535,13 +593,13 @@ Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Pr
 - Keep \`src/app/styles.css\` limited to Tailwind imports, theme tokens, and true global base behavior.
 
 ## Production packaging
-The UI runs through Vite in development but has no production container. The service's multi-stage Dockerfile builds this repository and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined production image.
+The UI runs through Vite in development but has no production container. The service's multi-stage Dockerfile builds this repository and copies its output into \`dist/public\`; Express serves it with SPA fallback. AWS ECR stores the combined \`linux/amd64\` production image under the default immutable \`<service-sha>_<ui-sha>\` tag, and production Compose requires that exact tag.${options.auth === "firebase" ? ` Provide \`${ui}/.env.production\` before a production build; the service build mounts it as a required BuildKit secret only while Vite compiles the browser bundle and does not copy it into the final image.` : ""}
 
 ## Product language
 The product domain is undefined. Do not invent entities, workflows, roles, claims, navigation, or customer-facing promises.
 
 ## Validation
-Run \`npm run validate:architecture\`, then add focused Vitest coverage and run type-check, build, and tests as applicable.
+Run \`npm run validate:architecture\` and \`npm run format:check\`, then add focused Vitest coverage and run type-check, build, and \`npm test\` as applicable. Use \`npm run test:watch\` only for interactive development.
 `);
 }
 
@@ -557,7 +615,7 @@ WORKDIR /app/ui
 COPY ${ui}/package*.json ./
 RUN npm ci
 COPY ${ui}/ ./
-RUN npm run build
+${options.auth === "firebase" ? "RUN --mount=type=secret,id=ui_env,target=/app/ui/.env.production,required=true npm run build" : "RUN npm run build"}
 
 FROM node:22.13-bookworm-slim
 WORKDIR /app
@@ -598,18 +656,23 @@ set -euo pipefail
 : "\${AWS_ACCOUNT_ID:?Set AWS_ACCOUNT_ID}"
 : "\${AWS_REGION:?Set AWS_REGION}"
 
+SVC_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD_CONTEXT="${options.ui ? `$(cd "\${SVC_DIR}/.." && pwd)` : `\${SVC_DIR}`}"
+${options.ui ? `UI_DIR="\${BUILD_CONTEXT}/${ui}"
+SVC_SHA="$(git -C "\${SVC_DIR}" rev-parse --short HEAD)"
+UI_SHA="$(git -C "\${UI_DIR}" rev-parse --short HEAD)"` : `SVC_SHA="$(git -C "\${SVC_DIR}" rev-parse --short HEAD)"`}
+
 ECR_REPOSITORY="\${ECR_REPOSITORY:-${options.name}}"
-IMAGE_TAG="\${IMAGE_TAG:-latest}"
+IMAGE_TAG="\${IMAGE_TAG:-${options.ui ? `\${SVC_SHA}_\${UI_SHA}` : `\${SVC_SHA}`}}"
 REGISTRY="\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com"
 IMAGE="\${REGISTRY}/\${ECR_REPOSITORY}:\${IMAGE_TAG}"
-SVC_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
-BUILD_CONTEXT="${options.ui ? `$(cd "\${SVC_DIR}/.." && pwd)` : `\${SVC_DIR}`}"
 DOCKERFILE="\${SVC_DIR}/Dockerfile"
+${options.ui && options.auth === "firebase" ? `UI_ENV_FILE="\${UI_ENV_FILE:-\${UI_DIR}/.env.production}"` : ""}
 
 aws ecr get-login-password --region "\${AWS_REGION}" |
 	docker login --username AWS --password-stdin "\${REGISTRY}"
 
-docker build --file "\${DOCKERFILE}" --tag "\${IMAGE}" "\${BUILD_CONTEXT}"
+docker build --platform linux/amd64${options.ui && options.auth === "firebase" ? ` --secret "id=ui_env,src=\${UI_ENV_FILE}"` : ""} --file "\${DOCKERFILE}" --tag "\${IMAGE}" "\${BUILD_CONTEXT}"
 docker push "\${IMAGE}"
 
 echo "Pushed \${IMAGE}"
@@ -631,7 +694,7 @@ const dependsBlock = `\n    depends_on:\n${dependencies.map(([dependency, condit
 const databaseEnvironmentBlock = `\n    environment:\n      MONGODB_URI: "mongodb://mongodb:27017/?replicaSet=rs0&directConnection=true"`;
 const volumeBlock = serviceVolumes.length ? `\n    volumes:\n${serviceVolumes.join("\n")}` : "";
 const workerService = options.worker ? `\n  worker:
-    image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:-latest}
+    image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
     env_file:
       - .env.production
     command: ["node", "dist/worker.js"]${databaseEnvironmentBlock}${volumeBlock}${dependsBlock}
@@ -676,7 +739,7 @@ const namedVolumes = [
 add(`${svc}/docker-compose.yml`, `name: ${options.name}-prod
 services:
   ${options.name}:
-    image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:-latest}
+    image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
     env_file:
       - .env.production
     ports: