@zaaxch/tailframe 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "2.0.0",
+	"version": "2.1.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

@@ -77,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
@@ -87,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."]);
@@ -203,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",
@@ -220,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`);
@@ -444,15 +446,19 @@ This service uses MongoDB. Module-owned MongoDB adapters own collection access,
 - 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"));
@@ -587,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.
 `);
 }
 
@@ -609,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
@@ -650,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}"
@@ -683,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}
@@ -728,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: