@zaaxch/tailframe 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/new.mjs

@@ -63,6 +63,9 @@ if (fs.existsSync(root) && fs.readdirSync(root).length) fail(`Refusing to overwr
 const title = options.name.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
 const svc = `${options.name}-svc`;
 const ui = `${options.name}-ui`;
+const databaseName = options.name.replaceAll("-", "_");
+const mongoApplicationUser = `${options.name}-app`;
+const mongoBackupUser = `${options.name}-backup`;
 const files = {};
 const add = (relative, content) => { files[relative] = content.endsWith("\n") ? content : `${content}\n`; };
 // Generated repositories depend on the published toolkit rather than copying a validator, and they
@@ -77,9 +80,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
@@ -87,7 +88,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."]);
@@ -203,7 +207,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",
@@ -220,11 +224,25 @@ module.exports = { projects: [
 	{ ...base, displayName: "integration", testMatch: ["**/*.integration.test.ts"] }
 ] };`);
 add(`${svc}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
-add(`${svc}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\n*.log\nfirebase-service-account*.json\n`);
+add(`${svc}/.gitattributes`, gitAttributes);
+add(`${svc}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\n!.env.infrastructure.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`);
-const dbEnv = "MONGODB_URI=mongodb://localhost:27017/?replicaSet=rs0&directConnection=true\nMONGODB_DB_NAME=" + options.name.replaceAll("-", "_");
+const dbEnv = "MONGODB_URI=mongodb://localhost:27017/?replicaSet=rs0&directConnection=true\nMONGODB_DB_NAME=" + databaseName;
 add(`${svc}/.env.example`, `NODE_ENV=development\nPORT=3000\nCORS_ORIGIN=https://localhost:5173\n${dbEnv}\n${options.auth === "firebase" ? "FIREBASE_PROJECT_ID=\n" : ""}${options.redis ? "REDIS_URL=redis://localhost:6379\n" : ""}`);
+add(`${svc}/.env.infrastructure.example`, `ECR_IMAGE=<account>.dkr.ecr.<region>.amazonaws.com/${options.name}
+IMAGE_TAG=<service-sha>${options.ui ? "_<ui-sha>" : ""}
+APP_ENV_FILE=/opt/${options.name}/shared/.env.production
+MONGO_DATA_DIR=/opt/${options.name}/shared/mongo/data
+MONGO_KEYFILE=/opt/${options.name}/shared/mongo/config/keyfile
+MONGO_INIT_SCRIPT=/opt/${options.name}/current/deploy/mongo/10-create-users.js
+MONGODB_ROOT_PASSWORD=<uri-safe-random-value>
+MONGODB_APP_PASSWORD=<different-uri-safe-random-value>
+MONGODB_BACKUP_PASSWORD=<different-uri-safe-random-value>
+${options.auth === "firebase" ? `SECRETS_DIR=/opt/${options.name}/shared/secrets
+` : ""}${options.redis ? `REDIS_DATA_DIR=/opt/${options.name}/shared/redis/data
+REDIS_PASSWORD=<different-uri-safe-random-value>
+` : ""}`);
 add(`${svc}/src/platform/config/env.ts`, `import "@dotenvx/dotenvx/config";
 export const env = {
 	nodeEnv: process.env.NODE_ENV ?? "development",
@@ -232,7 +250,7 @@ export const env = {
 	corsOrigin: process.env.CORS_ORIGIN ?? "https://localhost:5173",
 	${options.auth === "firebase" ? `firebaseProjectId: process.env.FIREBASE_PROJECT_ID ?? "",` : ""}
 	mongodbUri: process.env.MONGODB_URI ?? "mongodb://localhost:27017/?replicaSet=rs0&directConnection=true",
-	mongodbDbName: process.env.MONGODB_DB_NAME ?? "${options.name.replaceAll("-", "_")}",
+	mongodbDbName: process.env.MONGODB_DB_NAME ?? "${databaseName}",
 	${options.redis ? `redisUrl: process.env.REDIS_URL ?? "redis://localhost:6379",` : ""}
 };`);
 const databaseSource = `import { MongoClient } from "mongodb";
@@ -442,17 +460,25 @@ This service uses MongoDB. Module-owned MongoDB adapters own collection access,
 - 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.
 - 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\`.
+- Scheduled work prevents unintended overlap, stops intake before shutdown, awaits the active run, destroys its scheduler or consumer, and only then closes Redis and database clients.
 ${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."} The runtime image contains production dependencies only and runs as the Node user.${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.` : ""}
+
+## Production deployment
+Only service \`main\` pushes or manual workflow dispatch deploy; UI pushes never trigger deployment. GitHub Actions may replace files under \`/opt/${options.name}/current\` and MUST NOT replace persistent configuration, credentials, keyfiles, or data under \`/opt/${options.name}/shared\`. Keep Node runtime behavior in the shared service \`.env.production\`, Compose interpolation and infrastructure credentials in \`.env.infrastructure\`, and fixed topology wiring in Compose \`environment:\`. The optional UI build-time \`.env.production\` is a separate ephemeral file. Do not run deployment until the host and GitHub production environment have been bootstrapped according to \`docs/production-deployment.md\`.
+
 ## 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"));
@@ -587,13 +613,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.
 `);
 }
 
@@ -604,20 +630,26 @@ RUN npm ci
 COPY ${svc}/ ./
 RUN npm run build
 
+FROM node:22.13-bookworm AS service-production-dependencies
+WORKDIR /app/service
+COPY ${svc}/package*.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
 FROM node:22.13-bookworm AS ui-build
 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
 ENV NODE_ENV=production
 COPY --from=service-build /app/service/dist ./dist
 COPY --from=service-build /app/service/package*.json ./
-COPY --from=service-build /app/service/node_modules ./node_modules
+COPY --from=service-production-dependencies /app/service/node_modules ./node_modules
 COPY --from=ui-build /app/ui/dist ./dist/public
+USER node
 EXPOSE 3000
 CMD ["node", "dist/server.js"]
 ` : `FROM node:22.13-bookworm AS build
@@ -627,12 +659,18 @@ RUN npm ci
 COPY . .
 RUN npm run build
 
+FROM node:22.13-bookworm AS production-dependencies
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
 FROM node:22.13-bookworm-slim
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/dist ./dist
 COPY --from=build /app/package*.json ./
-COPY --from=build /app/node_modules ./node_modules
+COPY --from=production-dependencies /app/node_modules ./node_modules
+USER node
 EXPOSE 3000
 CMD ["node", "dist/server.js"]
 `);
@@ -650,92 +688,431 @@ 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}"
 `);
 
+const workflowUiCheckout = options.ui ? `
+      - name: Checkout UI dependency
+        uses: actions/checkout@v6
+        with:
+          repository: \${{ github.repository_owner }}/${ui}
+          ref: main
+          ssh-key: \${{ secrets.UI_REPO_SSH_KEY }}
+          path: ${ui}
+` : "";
+const workflowUiEnvironment = options.ui && options.auth === "firebase" ? `
+      - name: Write UI production environment
+        env:
+          UI_ENV_PRODUCTION: \${{ secrets.UI_ENV_PRODUCTION }}
+        run: |
+          printf '%s\\n' "$UI_ENV_PRODUCTION" > ${ui}/.env.production
+` : "";
+const workflowTagResolution = options.ui ? `
+          ui_sha="$(git -C ${ui} rev-parse --short HEAD)"
+          echo "tag=\${svc_sha}_\${ui_sha}" >> "$GITHUB_OUTPUT"` : `
+          echo "tag=\${svc_sha}" >> "$GITHUB_OUTPUT"`;
+add(`${svc}/.github/workflows/deploy.yml`, `name: Build and deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: ${options.name}-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy production
+    if: \${{ vars.DEPLOY_HOST != '' && vars.DEPLOY_USER != '' }}
+    runs-on: ubuntu-latest
+    environment: production
+    env:
+      AWS_ACCOUNT_ID: \${{ vars.AWS_ACCOUNT_ID }}
+      AWS_REGION: \${{ vars.AWS_REGION }}
+      ECR_REPOSITORY: \${{ vars.ECR_REPOSITORY || '${options.name}' }}
+      DEPLOY_HOST: \${{ vars.DEPLOY_HOST }}
+      DEPLOY_USER: \${{ vars.DEPLOY_USER }}
+
+    steps:
+      - name: Checkout service
+        uses: actions/checkout@v6
+        with:
+          path: ${svc}
+${workflowUiCheckout}${workflowUiEnvironment}
+      - name: Resolve immutable image
+        id: image
+        run: |
+          svc_sha="$(git -C ${svc} rev-parse --short HEAD)"${workflowTagResolution}
+          echo "registry=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com" >> "$GITHUB_OUTPUT"
+          echo "image=\${AWS_ACCOUNT_ID}.dkr.ecr.\${AWS_REGION}.amazonaws.com/\${ECR_REPOSITORY}" >> "$GITHUB_OUTPUT"
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+          aws-region: \${{ vars.AWS_REGION }}
+
+      - name: Build and push image
+        working-directory: ${svc}
+        env:
+          IMAGE_TAG: \${{ steps.image.outputs.tag }}
+        run: ./scripts/build_and_push.sh
+
+      - name: Configure deployment SSH
+        env:
+          DEPLOY_SSH_PRIVATE_KEY: \${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+          DEPLOY_SSH_KNOWN_HOSTS: \${{ secrets.DEPLOY_SSH_KNOWN_HOSTS }}
+        run: |
+          install -m 700 -d ~/.ssh
+          printf '%s\\n' "$DEPLOY_SSH_PRIVATE_KEY" > ~/.ssh/${options.name}-deploy
+          chmod 600 ~/.ssh/${options.name}-deploy
+          printf '%s\\n' "$DEPLOY_SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
+
+      - name: Authenticate server with ECR
+        run: |
+          aws ecr get-login-password --region "$AWS_REGION" |
+            ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+              "docker login --username AWS --password-stdin '\${{ steps.image.outputs.registry }}'"
+
+      - name: Install deployment files
+        run: |
+          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+            "install -m 755 -d /opt/${options.name}/current/deploy/mongo"
+          scp -i ~/.ssh/${options.name}-deploy \\
+            ${svc}/docker-compose.yml \\
+            ${svc}/scripts/deploy_remote.sh \\
+            "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/"
+          scp -i ~/.ssh/${options.name}-deploy \\
+            ${svc}/deploy/mongo/10-create-users.js \\
+            "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/deploy/mongo/"
+          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+            "chmod 755 /opt/${options.name}/current/deploy_remote.sh"
+
+      - name: Deploy image
+        run: |
+          ssh -i ~/.ssh/${options.name}-deploy "\${DEPLOY_USER}@\${DEPLOY_HOST}" \\
+            "/opt/${options.name}/current/deploy_remote.sh '\${{ steps.image.outputs.tag }}' '\${{ steps.image.outputs.image }}'"
+`);
+
+add(`${svc}/scripts/deploy_remote.sh`, `#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE_TAG="\${1:?Usage: deploy_remote.sh IMAGE_TAG ECR_IMAGE}"
+ECR_IMAGE="\${2:?Usage: deploy_remote.sh IMAGE_TAG ECR_IMAGE}"
+DEPLOY_DIR="\${DEPLOY_DIR:-/opt/${options.name}/current}"
+SHARED_DIR="\${SHARED_DIR:-/opt/${options.name}/shared}"
+COMPOSE_FILE="\${DEPLOY_DIR}/docker-compose.yml"
+INFRA_ENV="\${SHARED_DIR}/.env.infrastructure"
+
+if [[ ! -f "\${INFRA_ENV}" ]]; then
+	echo "Missing provisioned infrastructure environment: \${INFRA_ENV}" >&2
+	exit 1
+fi
+
+NEXT_ENV="$(mktemp "\${SHARED_DIR}/.env.infrastructure.XXXXXX")"
+cleanup() {
+	rm -f "\${NEXT_ENV}"
+}
+trap cleanup EXIT
+
+grep -Ev '^(ECR_IMAGE|IMAGE_TAG)=' "\${INFRA_ENV}" > "\${NEXT_ENV}" || true
+printf 'ECR_IMAGE=%s\\nIMAGE_TAG=%s\\n' "\${ECR_IMAGE}" "\${IMAGE_TAG}" >> "\${NEXT_ENV}"
+chmod 600 "\${NEXT_ENV}"
+mv "\${NEXT_ENV}" "\${INFRA_ENV}"
+trap - EXIT
+
+docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" config --quiet
+docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" pull
+docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" up -d --wait
+`);
+
+add(`${svc}/deploy/mongo/10-create-users.js`, `const applicationPassword = process.env.MONGODB_APP_PASSWORD;
+const backupPassword = process.env.MONGODB_BACKUP_PASSWORD;
+
+if (!applicationPassword || !backupPassword) {
+	throw new Error("MONGODB_APP_PASSWORD and MONGODB_BACKUP_PASSWORD are required");
+}
+
+db.getSiblingDB("${databaseName}").createUser({
+	user: "${mongoApplicationUser}",
+	pwd: applicationPassword,
+	roles: [{ role: "readWrite", db: "${databaseName}" }]
+});
+
+db.getSiblingDB("admin").createUser({
+	user: "${mongoBackupUser}",
+	pwd: backupPassword,
+	roles: [{ role: "backup", db: "admin" }]
+});
+`);
+
+add(`${svc}/docs/production-deployment.md`, `# Production deployment
+
+## Delivery model
+
+GitHub Actions checks out ${svc}${options.ui ? ` and ${ui}` : ""}${options.ui ? " as sibling build inputs" : ""}, builds one
+non-root production image, tags it ${options.ui ? "`<service-sha>_<ui-sha>`" : "`<service-sha>`"}, pushes it to ECR, and installs only deployment artifacts on the host.
+Only service \`main\` pushes and manual dispatch trigger this workflow; UI pushes never deploy.
+
+The host separates replaceable artifacts from persistent state:
+
+\`\`\`text
+/opt/${options.name}/
+├── current/
+│   ├── docker-compose.yml
+│   ├── deploy_remote.sh
+│   └── deploy/mongo/10-create-users.js
+└── shared/
+    ├── .env.production
+    ├── .env.infrastructure
+${options.auth === "firebase" ? `    ├── secrets/firebase-service-account.json
+` : ""}    ├── mongo/config/keyfile
+    ├── mongo/data/
+${options.redis ? `    └── redis/data/
+` : ""}\`\`\`
+
+Actions may replace \`current/\` and must never replace \`shared/\`. The server never needs a source checkout.
+
+## Configuration ownership
+
+- \`.env.production\` contains Node application behavior and provider credentials.
+- \`.env.infrastructure\` contains Compose paths, image identity, and infrastructure passwords. Start from
+  \`.env.infrastructure.example\` and replace every placeholder.
+- Compose \`environment:\` owns fixed production wiring: \`NODE_ENV\`, internal database/cache URLs, and mounted
+  credential paths.
+${options.ui && options.auth === "firebase" ? `- The UI repository's build-time \`.env.production\` comes from the GitHub \`UI_ENV_PRODUCTION\` secret and is unrelated to the service runtime file above.
+` : ""}
+Do not inject \`.env.infrastructure\` into Node. Make both host environment files root-owned and mode \`0600\`.
+
+## One-time host bootstrap
+
+1. Install Docker Engine and Docker Compose.
+2. Create \`/opt/${options.name}/current/deploy/mongo\`, \`/opt/${options.name}/shared/mongo/config\`, and
+   \`/opt/${options.name}/shared/mongo/data\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.
+3. Install \`.env.production\` and a completed \`.env.infrastructure\` under \`shared/\`.
+4. Generate the MongoDB replica key with \`openssl rand -base64 756\`, make it owned by UID/GID \`999:999\`, and
+   mode \`0400\`.
+${options.auth === "firebase" ? `5. Install the Firebase service account at \`shared/secrets/firebase-service-account.json\`, owned by \`root:1000\` and mode \`0640\`.
+6. ` : "5. "}Give the deployment user Docker access and write access to \`current/\`; keep \`shared/\` and its files protected.
+${options.auth === "firebase" ? "7" : "6"}. Authorize the dedicated deployment SSH key and record the host key for GitHub Actions.
+
+Use a fresh Mongo data directory. Migrating an existing unauthenticated database requires a separately reviewed plan.
+
+## GitHub production environment
+
+Configure these variables:
+
+- \`AWS_ACCOUNT_ID\`, \`AWS_REGION\`, and \`AWS_ROLE_ARN\` for the repository-restricted OIDC role.
+- \`DEPLOY_HOST\` and \`DEPLOY_USER\`; the deployment job remains skipped until both exist.
+- Optional \`ECR_REPOSITORY\`; the default is \`${options.name}\`.
+
+Configure these secrets:
+
+${options.ui ? `- \`UI_REPO_SSH_KEY\`: read-only deploy key for \`${ui}\`.
+` : ""}${options.ui && options.auth === "firebase" ? `- \`UI_ENV_PRODUCTION\`: Vite/Firebase build-time environment.
+` : ""}- \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
+- \`DEPLOY_SSH_KNOWN_HOSTS\`: pinned host key.
+
+The ECR repository and AWS OIDC provider/role are provisioned separately. The workflow never stores long-lived AWS
+keys or creates cloud infrastructure.
+
+## Deploy and rollback
+
+The remote script requires the provisioned infrastructure file, atomically replaces only \`ECR_IMAGE\` and
+\`IMAGE_TAG\`, validates Compose, pulls, and starts with health waiting. Roll back by selecting a previous immutable
+tag and running the same script. Never use \`docker compose down -v\` in production; image rollback does not restore
+database state.
+
+MongoDB and optional Redis expose no host ports and require authentication. Verify API readiness, container health,
+database/cache authentication, file permissions, and off-host backup/restore before treating the deployment as
+production-ready. Product-specific TLS, capacity limits, migrations, and scheduled-work grace periods must be added
+from measured application requirements rather than copied from another product.
+`);
+
 const serviceVolumes = [
-	...(options.auth === "firebase" ? ["      - ./firebase-service-account.production.json:/app/firebase-service-account.production.json:ro"] : [])
+	...(options.auth === "firebase" ? ["      - ${SECRETS_DIR:?Set SECRETS_DIR}/firebase-service-account.json:/app/secrets/firebase-service-account.json:ro"] : [])
 ];
 const devVolumes = [
 	"      - .:/app",
 	"      - /app/node_modules",
 	...(options.auth === "firebase" ? ["      - ./firebase-service-account.development.json:/app/firebase-service-account.development.json:ro"] : [])
 ];
-const dependencies = [
+const productionDependencies = [
+	["mongo-init", "service_completed_successfully"],
+	...(options.redis ? [["redis", "service_healthy"]] : [])
+];
+const developmentDependencies = [
 	["mongo-init", "service_completed_successfully"],
 	...(options.redis ? [["redis", "service_started"]] : [])
 ];
-const dependsBlock = `\n    depends_on:\n${dependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
+const dependsBlock = `\n    depends_on:\n${productionDependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
+const devDependsBlock = `\n    depends_on:\n${developmentDependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
+const productionEnvironment = [
+	"      NODE_ENV: production",
+	`      MONGODB_URI: "mongodb://${mongoApplicationUser}:\${MONGODB_APP_PASSWORD:?Set MONGODB_APP_PASSWORD}@mongodb:27017/${databaseName}?replicaSet=rs0&directConnection=true&authSource=${databaseName}"`,
+	`      MONGODB_DB_NAME: "${databaseName}"`,
+	...(options.auth === "firebase" ? ["      GOOGLE_APPLICATION_CREDENTIALS: /app/secrets/firebase-service-account.json"] : []),
+	...(options.redis ? ["      REDIS_URL: \"redis://:\${REDIS_PASSWORD:?Set REDIS_PASSWORD}@redis:6379\""] : [])
+];
+const productionEnvironmentBlock = `\n    environment:\n${productionEnvironment.join("\n")}`;
 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}
+      - \${APP_ENV_FILE:-.env.production}
+    command: ["node", "dist/worker.js"]${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
+    healthcheck:
+      test: ["CMD", "node", "-e", "process.kill(1, 0)"]
+      interval: 60s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    stop_grace_period: 2m
+    networks:
+      - backend
     restart: unless-stopped` : "";
 const databaseService = `\n  mongodb:
     image: mongo:8
-    command: mongod --replSet rs0 --bind_ip_all
+    command:
+      - mongod
+      - --replSet
+      - rs0
+      - --bind_ip_all
+      - --keyFile
+      - /etc/mongo-keyfile/keyfile
+    environment:
+      MONGO_INITDB_DATABASE: "${databaseName}"
+      MONGO_INITDB_ROOT_USERNAME: "${options.name}-root"
+      MONGO_INITDB_ROOT_PASSWORD: \${MONGODB_ROOT_PASSWORD:?Set MONGODB_ROOT_PASSWORD}
+      MONGODB_APP_PASSWORD: \${MONGODB_APP_PASSWORD:?Set MONGODB_APP_PASSWORD}
+      MONGODB_BACKUP_PASSWORD: \${MONGODB_BACKUP_PASSWORD:?Set MONGODB_BACKUP_PASSWORD}
     volumes:
-      - mongodb-data:/data/db
+      - \${MONGO_DATA_DIR:?Set MONGO_DATA_DIR}:/data/db
+      - \${MONGO_KEYFILE:?Set MONGO_KEYFILE}:/etc/mongo-keyfile/keyfile:ro
+      - \${MONGO_INIT_SCRIPT:?Set MONGO_INIT_SCRIPT}:/docker-entrypoint-initdb.d/10-create-users.js:ro
     healthcheck:
-      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
-      interval: 2s
-      timeout: 2s
+      test:
+        - CMD-SHELL
+        - >-
+          mongosh --quiet --host localhost
+          --username "$\${MONGO_INITDB_ROOT_USERNAME}"
+          --password "$\${MONGO_INITDB_ROOT_PASSWORD}"
+          --authenticationDatabase admin
+          --eval "quit(db.adminCommand({ping:1}).ok ? 0 : 1)"
+      interval: 5s
+      timeout: 5s
       retries: 30
+      start_period: 20s
+    networks:
+      - backend
     restart: unless-stopped
   mongo-init:
     image: mongo:8
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: "${options.name}-root"
+      MONGO_INITDB_ROOT_PASSWORD: \${MONGODB_ROOT_PASSWORD:?Set MONGODB_ROOT_PASSWORD}
     depends_on:
       mongodb:
         condition: service_healthy
     restart: "no"
-    entrypoint:
-      - bash
-      - -c
-      - |
-        mongosh --host mongodb --quiet --eval '
-          try {
-            rs.status().ok
-          } catch (error) {
-            rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })
+    entrypoint: ["bash", "-ec"]
+    command:
+      - >-
+        mongosh --quiet --host mongodb:27017
+        --username "$\${MONGO_INITDB_ROOT_USERNAME}"
+        --password "$\${MONGO_INITDB_ROOT_PASSWORD}"
+        --authenticationDatabase admin
+        --eval "try { const status = rs.status(); quit(status.ok === 1 ? 0 : 1); }
+        catch (error) {
+          if (error.code === 94 || error.codeName === 'NotYetInitialized') {
+            const result = rs.initiate({_id:'rs0',members:[{_id:0,host:'mongodb:27017'}]});
+            quit(result.ok === 1 ? 0 : 1);
           }
-        '`;
+          throw error;
+        }"
+    networks:
+      - backend`;
 const redisService = options.redis ? `\n  redis:
     image: redis:7-alpine
+    command:
+      - redis-server
+      - --appendonly
+      - "yes"
+      - --appendfsync
+      - everysec
+      - --maxmemory-policy
+      - noeviction
+      - --requirepass
+      - \${REDIS_PASSWORD:?Set REDIS_PASSWORD}
+    environment:
+      REDIS_PASSWORD: \${REDIS_PASSWORD:?Set REDIS_PASSWORD}
     volumes:
-      - redis-data:/data
+      - \${REDIS_DATA_DIR:?Set REDIS_DATA_DIR}:/data
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - REDISCLI_AUTH="$\${REDIS_PASSWORD}" redis-cli ping | grep -q PONG
+      interval: 10s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+    networks:
+      - backend
     restart: unless-stopped` : "";
-const namedVolumes = [
-	"  mongodb-data:",
-	...(options.redis ? ["  redis-data:"] : [])
-];
 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
+      - \${APP_ENV_FILE:-.env.production}
     ports:
-      - "3000:3000"${databaseEnvironmentBlock}${volumeBlock}${dependsBlock}
+      - "3000:3000"${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          node -e
+          "fetch('http://127.0.0.1:3000/api/v1/health.readiness',
+          {method:'POST',headers:{'Content-Type':'application/json','X-Requested-With':'XMLHttpRequest'},body:'{}'})
+          .then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    stop_grace_period: 2m
+    networks:
+      - backend
     restart: unless-stopped${workerService}${databaseService}${redisService}
-volumes:
-${namedVolumes.join("\n")}
+networks:
+  backend:
+    driver: bridge
 `);
 
 const devWorker = options.worker ? `\n  worker:
@@ -746,7 +1123,7 @@ const devWorker = options.worker ? `\n  worker:
       - .env.development
     command: ["npm", "run", "dev:worker"]${databaseEnvironmentBlock}
     volumes:
-${devVolumes.join("\n")}${dependsBlock}` : "";
+${devVolumes.join("\n")}${devDependsBlock}` : "";
 const devDatabase = `\n  mongodb:
     image: mongo:8
     command: mongod --replSet rs0 --bind_ip_all
@@ -797,7 +1174,7 @@ services:
     ports:
       - "3000:3000"${databaseEnvironmentBlock}
     volumes:
-${devVolumes.join("\n")}${dependsBlock}${devWorker}${devDatabase}${devRedis}
+${devVolumes.join("\n")}${devDependsBlock}${devWorker}${devDatabase}${devRedis}
 volumes:
 ${devNamedVolumes.join("\n")}
 `);