@zaaxch/tailframe 4.0.7 → 4.0.9

package/package.json

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

@@ -269,10 +269,6 @@ add(`${svc}/.env.example`, `NODE_ENV=development\nPORT=3000\nCORS_ORIGIN=https:/
 add(`${svc}/.env.infrastructure.example`, `ECR_IMAGE=<account>.dkr.ecr.<region>.amazonaws.com/${options.name}
 IMAGE_TAG=<product-sha>
 APP_ENV_FILE=/opt/${options.name}/shared/.env.production
-CADDY_ORIGIN_CERTIFICATE=/opt/${options.name}/shared/caddy/origin.pem
-CADDY_ORIGIN_KEY=/opt/${options.name}/shared/caddy/origin-key.pem
-CADDY_DATA_DIR=/opt/${options.name}/shared/caddy/data
-CADDY_CONFIG_DIR=/opt/${options.name}/shared/caddy/config
 ${postgres ? `POSTGRES_DATA_DIR=/opt/${options.name}/shared/postgres/data
 POSTGRES_ROOT_PASSWORD=<uri-safe-random-value>
 POSTGRES_APP_PASSWORD=<different-uri-safe-random-value>
@@ -286,7 +282,11 @@ 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>
-` : ""}`);
+` : ""}CADDY_ORIGIN_CERTIFICATE=/opt/${options.name}/shared/caddy/certs/origin.pem
+CADDY_ORIGIN_KEY=/opt/${options.name}/shared/caddy/certs/origin-key.pem
+CADDY_DATA_DIR=/opt/${options.name}/shared/caddy/data
+CADDY_CONFIG_DIR=/opt/${options.name}/shared/caddy/config
+`);
 add(`${svc}/src/platform/config/env.ts`, `import "@dotenvx/dotenvx/config";
 export const env = {
 	nodeEnv: process.env.NODE_ENV ?? "development",
@@ -588,7 +588,7 @@ ${options.ui ? "- In production, serve the compiled UI from `dist/public` with a
 The ECR build targets \`linux/amd64\`. ${options.ui ? "Its default immutable tag is `<product-sha>` and production Compose requires that exact tag." : "Its default immutable tag is `<product-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
-Pull requests into product \`main\` validate release candidates. The resulting \`main\` push validates again before GitHub Actions may publish an immutable image tagged with the full product commit SHA. Image publication and production deployment are separate workflows with distinct AWS roles: the release role publishes, while the pull-only deployment role manually deploys from \`main\` using an already-published full SHA from \`main\` history and that commit's deployment files. Build both role-trust subjects from GitHub's API-reported \`sub_claim_prefix\`; never infer the effective prefix from \`use_immutable_subject\`. Product data migrations must authenticate to the registry, pull and digest-verify that exact release image, and explicitly select the production datastore; never inherit rehearsal image or target defaults. 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 environments have been bootstrapped according to \`docs/production-deployment.md\`.
+Pull requests into product \`main\` validate release candidates. The resulting \`main\` push validates again before GitHub Actions may publish an immutable image tagged with the full product commit SHA. Image publication and production deployment are separate workflows with distinct AWS roles: the release role publishes, while the pull-only deployment role manually deploys from \`main\` using an already-published full SHA from \`main\` history and that commit's deployment files. Build both role-trust subjects from GitHub's API-reported \`sub_claim_prefix\`; never infer the effective prefix from \`use_immutable_subject\`. Product data migrations must authenticate to the registry, pull and digest-verify that exact release image, and explicitly select the production datastore; never inherit rehearsal image or target defaults. 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\`. Caddy is the only production edge surface: deploy the matching commit's \`Caddyfile\`, keep its certificate and runtime state under \`shared\`, and force-recreate only the proxy after rollout so bind-mounted configuration changes take effect. 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 environments have been bootstrapped according to \`docs/production-deployment.md\`.
 
 ## Tests and validation
 Run \`pnpm validate:architecture\` and \`pnpm format:check\` after changing files or imports. The generated service also includes unit tests and ${postgres ? "PostgreSQL-backed" : "Mongo-backed"} integration tests. Run focused service database tests through pnpm for the full service check. Test use cases, policies, ${postgres ? "PostgreSQL" : "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 ${postgres ? "PostgreSQL" : "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 the release image script, must run outside the sandbox from the first attempt.
@@ -604,7 +604,24 @@ 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, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.app.tsbuildinfo", types: ["vitest/globals"], baseUrl: ".", paths: { "@/*": ["./src/*"] } } }, null, "\t"));
 add(`${ui}/tsconfig.node.json`, JSON.stringify({ extends: "@tsconfig/node22/tsconfig.json", include: ["vite.config.ts"], compilerOptions: { composite: true, noEmit: true, tsBuildInfoFile: "./.tmp/tsconfig.node.tsbuildinfo", types: ["node"] } }, null, "\t"));
-add(`${ui}/vite.config.ts`, `import { fileURLToPath, URL } from "node:url";\nimport { defineConfig } from "vitest/config";\nimport vue from "@vitejs/plugin-vue";\nimport tailwindcss from "@tailwindcss/vite";\nexport default defineConfig({ plugins: [vue(), tailwindcss()], resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }, server: { proxy: { "/api": { target: "http://localhost:3000", changeOrigin: true } } }, test: { environment: "jsdom", globals: true } });`);
+add(`${ui}/vite.config.ts`, `import { fileURLToPath, URL } from "node:url";
+import { defineConfig } from "vitest/config";
+import vue from "@vitejs/plugin-vue";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+	plugins: [vue(), tailwindcss()],
+	resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+	server: {
+		proxy: {
+			"/api": {
+				target: process.env.VITE_API_PROXY_TARGET ?? "http://localhost:3000",
+				changeOrigin: true
+			}
+		}
+	},
+	test: { environment: "jsdom", globals: true }
+});`);
 add(`${ui}/env.d.ts`, `/// <reference types="vite/client" />`);
 add(`${ui}/index.html`, `<!doctype html>
 <html lang="en">
@@ -760,7 +777,7 @@ Keep all product state in the owning module. The auth/notification/theme stores,
 - 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 application 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 \`<product-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.` : ""}
+Development Compose runs Vite from the UI's development-only container on the product's private network; its proxy target is configurable and all development ports remain internal-only so multiple products can run concurrently. The UI has no independent production container. The service's multi-stage Dockerfile builds this application 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 \`<product-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.
@@ -799,6 +816,18 @@ WORKDIR /workspace/apps/service
 EXPOSE 3000
 CMD ["pnpm", "dev"]
 `);
+if (options.ui) add(`${ui}/Dockerfile.dev`, `FROM node:22.13-alpine
+RUN npm install --global corepack@0.34.5 && corepack enable
+WORKDIR /workspace
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/service/package.json apps/service/package.json
+COPY apps/ui/package.json apps/ui/package.json
+RUN pnpm install --frozen-lockfile --filter ${uiPackage}...
+COPY apps/ui apps/ui
+WORKDIR /workspace/apps/ui
+EXPOSE 5173
+CMD ["pnpm", "dev"]
+`);
 add(`${svc}/scripts/build_and_push.sh`, `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -1103,6 +1132,7 @@ jobs:
                     "install -m 755 -d /opt/${options.name}/current/deploy/${deploymentArtifactDirectory}"
                   scp -i ~/.ssh/${options.name}-deploy \\
                     apps/service/docker-compose.yml \\
+                    apps/service/Caddyfile \\
                     apps/service/scripts/deploy_remote.sh \\
                     "\${DEPLOY_USER}@\${DEPLOY_HOST}:/opt/${options.name}/current/"
                   scp -i ~/.ssh/${options.name}-deploy \\
@@ -1158,6 +1188,9 @@ 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
+# Compose does not detect changes inside the bind-mounted Caddyfile, so recreate only the proxy
+# after every deployment to make the files installed under current/ take effect.
+docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" up -d --wait --no-deps --force-recreate caddy
 `);
 
 if (postgres) add(`${svc}/deploy/postgres/10-create-application-user.sh`, `#!/usr/bin/env bash
@@ -1194,14 +1227,16 @@ configured. No push or merge deploys production automatically.
 Configure the ECR repository with immutable image tags. The release-only role may publish; the distinct deployment
 role is pull-only. Record the full commit SHA and ECR digest; deployment and product migrations use that release image.
 
-Production ingress is a required Caddy reverse proxy in every generated service deployment. The application container remains
-internal; Caddy is the only edge surface and must own 80/443 exposure.
+Production ingress is a required Caddy reverse proxy for every generated Tailframe service. The app container is internal-only;
+Caddy is the only edge surface and must remain the only internet-facing host for production traffic.
+This document assumes 80/443 exposure through Caddy only.
 
 The host separates replaceable artifacts from persistent state:
 
 \`\`\`text
 /opt/${options.name}/
 ├── current/
+│   ├── Caddyfile
 │   ├── docker-compose.yml
 │   ├── deploy_remote.sh
 │   └── deploy/${deploymentArtifactDirectory}/${deploymentArtifactFile}
@@ -1228,8 +1263,7 @@ Actions may replace \`current/\` and must never replace \`shared/\`. The server
 - \`.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.
-- \`.env.infrastructure\` is also the host-owned control plane for Caddy certificate paths and runtime directories; keep TLS
-  key material under shared storage and rotate it independently from application images.
+- \`.env.infrastructure\` also owns Caddy certificate/runtime ownership boundaries.
 - Compose \`environment:\` owns fixed production wiring: \`NODE_ENV\`, internal database/cache URLs, and mounted
   credential paths.
 ${options.ui && options.auth === "firebase" ? `- The UI application's build-time \`.env.production\` comes from the GitHub \`UI_ENV_PRODUCTION\` secret and is unrelated to the service runtime file above.
@@ -1243,14 +1277,16 @@ ${postgres
 	? `2. Create \`/opt/${options.name}/current/deploy/postgres\`, \`/opt/${options.name}/shared/postgres/data\`,
    \`/opt/${options.name}/shared/caddy/certs\`, \`/opt/${options.name}/shared/caddy/data\`, \`/opt/${options.name}/shared/caddy/config\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`
 	: `2. Create \`/opt/${options.name}/current/deploy/mongo\`, \`/opt/${options.name}/shared/mongo/config\`, and
-   \`/opt/${options.name}/shared/mongo/data\`, \`/opt/${options.name}/shared/caddy/certs\`,
-   \`/opt/${options.name}/shared/caddy/data\`, \`/opt/${options.name}/shared/caddy/config\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`}
+   \`/opt/${options.name}/shared/mongo/data\`, \`/opt/${options.name}/shared/caddy/certs\`, \`/opt/${options.name}/shared/caddy/data\`,
+   \`/opt/${options.name}/shared/caddy/config\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`}
 3. Install \`.env.production\` and a completed \`.env.infrastructure\` under \`shared/\`.
-${postgres ? "" : `4. Generate the MongoDB replica key with \`openssl rand -base64 756\`, make it owned by UID/GID \`999:999\`, and
+4. Install the origin certificate at \`shared/caddy/certs/origin.pem\` and its private key at
+   \`shared/caddy/certs/origin-key.pem\`; make both root-owned and mode \`0600\`.
+${postgres ? "" : `5. Generate the MongoDB replica key with \`openssl rand -base64 756\`, make it owned by UID/GID \`999:999\`, and
    mode \`0400\`.
-`}${options.auth === "firebase" ? `${postgres ? "4" : "5"}. Install the Firebase service account at \`shared/secrets/firebase-service-account.json\`, owned by \`root:1000\` and mode \`0640\`.
-` : ""}${postgres ? (options.auth === "firebase" ? "5" : "4") : (options.auth === "firebase" ? "6" : "5")}. Give the deployment user Docker access and write access to \`current/\`; keep \`shared/\` and its files protected.
-${postgres ? (options.auth === "firebase" ? "6" : "5") : (options.auth === "firebase" ? "7" : "6")}. Authorize the dedicated deployment SSH key and record the host key for GitHub Actions.
+`}${options.auth === "firebase" ? `${postgres ? "5" : "6"}. Install the Firebase service account at \`shared/secrets/firebase-service-account.json\`, owned by \`root:1000\` and mode \`0640\`.
+` : ""}${postgres ? (options.auth === "firebase" ? "6" : "5") : (options.auth === "firebase" ? "7" : "6")}. Give the deployment user Docker access and write access to \`current/\`; keep \`shared/\` and its files protected.
+${postgres ? (options.auth === "firebase" ? "7" : "6") : (options.auth === "firebase" ? "8" : "7")}. Authorize the dedicated deployment SSH key and record the host key for GitHub Actions.
 
 Use a fresh ${postgres ? "PostgreSQL" : "MongoDB"} data directory. Migrating an existing unauthenticated database requires a separately reviewed plan.
 
@@ -1297,6 +1333,10 @@ The remote script requires the provisioned infrastructure file, atomically repla
 full-SHA release and running the same workflow. Never use \`docker compose down -v\` in production; image rollback
 does not restore database state.
 
+The deployment installs the selected commit's \`Caddyfile\` and force-recreates only the proxy after the general
+rollout so bind-mounted configuration changes take effect. Preserve product-specific hostname restrictions when
+customizing the domain-neutral generated listener.
+
 ## Product data-migration handoff
 
 Tailframe does not generate product-specific data-migration orchestration. Before a production data migration,
@@ -1305,8 +1345,8 @@ explicitly configure the production datastore target. Never inherit a rehearsal
 
 ${postgres ? "PostgreSQL" : "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.
+production-ready. Product-specific hostnames, certificate-provider procedures, capacity limits, migrations, and
+scheduled-work grace periods must be added from measured application requirements rather than copied from another product.
 `);
 
 const serviceVolumes = [
@@ -1350,7 +1390,7 @@ const developmentEnvironmentBlock = `\n    environment:\n${developmentEnvironmen
 const volumeBlock = serviceVolumes.length ? `\n    volumes:\n${serviceVolumes.join("\n")}` : "";
 const caddyService = `
   caddy:
-    image: caddy:2-alpine
+    image: caddy:2.11.4-alpine
     ports:
       - "80:80"
       - "443:443"
@@ -1367,14 +1407,14 @@ const caddyService = `
       - backend
     restart: unless-stopped`;
 add(`${svc}/Caddyfile`, `{
-    auto_https off
+	auto_https off
 }
 :80 {
-    redir https://{host}{uri} 308
+	redir https://{host}{uri} 308
 }
 :443 {
-    tls /etc/caddy/certs/origin.pem /etc/caddy/certs/origin-key.pem
-    reverse_proxy ${options.name}:3000
+	tls /etc/caddy/certs/origin.pem /etc/caddy/certs/origin-key.pem
+	reverse_proxy ${options.name}:3000
 }`);
 const workerService = options.worker ? `\n  worker:
     image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
@@ -1517,8 +1557,7 @@ services:
   ${options.name}:
     image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
     env_file:
-      - \${APP_ENV_FILE:-.env.production}
-${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
+      - \${APP_ENV_FILE:-.env.production}${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
     healthcheck:
       test:
         - CMD-SHELL
@@ -1534,7 +1573,7 @@ ${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
     stop_grace_period: 2m
     networks:
       - backend
-    restart: unless-stopped${workerService}${schemaInitService}${databaseService}${redisService}${caddyService}
+    restart: unless-stopped${caddyService}${workerService}${schemaInitService}${databaseService}${redisService}
 networks:
   backend:
     driver: bridge
@@ -1542,17 +1581,17 @@ networks:
 
 const devWorker = options.worker ? `\n  worker:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "dev:worker"]${developmentEnvironmentBlock}
+    command: ["pnpm", "dev:worker"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}${devDependsBlock}` : "";
 const devDatabase = postgres ? `\n  postgres:
     image: postgres:17
-    ports:
-      - "5432:5432"
+    expose:
+      - "5432"
     environment:
       POSTGRES_DB: ${databaseName}
       POSTGRES_USER: ${options.name}-app
@@ -1566,8 +1605,8 @@ const devDatabase = postgres ? `\n  postgres:
       retries: 30` : `\n  mongodb:
     image: mongo:8
     command: mongod --replSet rs0 --bind_ip_all
-    ports:
-      - "27017:27017"
+    expose:
+      - "27017"
     volumes:
       - mongodb-dev-data:/data/db
     healthcheck:
@@ -1594,10 +1633,22 @@ const devDatabase = postgres ? `\n  postgres:
         '`;
 const devRedis = options.redis ? `\n  redis:
     image: redis:7-alpine
-    ports:
-      - "6379:6379"
+    expose:
+      - "6379"
     volumes:
       - redis-dev-data:/data` : "";
+const devUi = options.ui ? `\n  ui:
+    build:
+      context: ../..
+      dockerfile: apps/ui/Dockerfile.dev
+${options.auth === "firebase" ? "    env_file:\n      - ../ui/.env.development\n" : ""}    environment:
+      VITE_API_PROXY_TARGET: http://${options.name}:3000
+    volumes:
+      - ../ui:/workspace/apps/ui
+      - /workspace/node_modules
+      - /workspace/apps/ui/node_modules
+    expose:
+      - "5173"` : "";
 const devNamedVolumes = [
 	postgres ? "  postgres-dev-data:" : "  mongodb-dev-data:",
 	...(options.redis ? ["  redis-dev-data:"] : [])
@@ -1606,11 +1657,11 @@ add(`${svc}/docker-compose.dev.yml`, `name: ${options.name}-dev
 services:
   schema-init:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    command: ["npm", "run", "schema:apply:dev"]${developmentEnvironmentBlock}
+    command: ["pnpm", "schema:apply:dev"]${developmentEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}
     depends_on:
@@ -1618,14 +1669,14 @@ ${devVolumes.join("\n")}
         condition: ${postgres ? "service_healthy" : "service_completed_successfully"}
   ${options.name}:
     build:
-      context: .
-      dockerfile: Dockerfile.dev
+      context: ../..
+      dockerfile: apps/service/Dockerfile.dev
     env_file:
       - .env.development
-    ports:
-      - "3000:3000"${developmentEnvironmentBlock}
+    expose:
+      - "3000"${developmentEnvironmentBlock}
     volumes:
-${devVolumes.join("\n")}${devDependsBlock}${devWorker}${devDatabase}${devRedis}
+${devVolumes.join("\n")}${devDependsBlock}${devUi}${devWorker}${devDatabase}${devRedis}
 volumes:
 ${devNamedVolumes.join("\n")}
 `);

package/src/validate.mjs

@@ -61,7 +61,7 @@ function validateVersionMetadata(root, runningVersion) {
 	return errors;
 }
 
-function validateAppMetadata(productRoot, app) {
+function validateAppMetadata(productRoot, app, productConfig) {
 	const errors = [];
 	const root = appRoot(productRoot, app);
 	if (!fs.existsSync(root)) return [`Missing configured application root: ${app.path}`];
@@ -71,6 +71,7 @@ function validateAppMetadata(productRoot, app) {
 		else {
 			const compose = fs.readFileSync(composeFile, "utf8");
 			const generatedProcessCount = app.profiles.includes("worker") ? 3 : 2;
+			const hasUi = productConfig.apps.some((candidate) => candidate.kind === "ui");
 			const count = (term) => compose.split(term).length - 1;
 			for (const term of [
 				"      - .:/workspace/apps/service",
@@ -84,6 +85,14 @@ function validateAppMetadata(productRoot, app) {
 			if (compose.includes("      - .:/app\n")) {
 				errors.push(`${app.path}/docker-compose.dev.yml uses the obsolete /app service source mount`);
 			}
+			if (compose.includes("    ports:")) {
+				errors.push(`${app.path}/docker-compose.dev.yml must keep generated development ports internal-only`);
+			}
+			if (hasUi) {
+				for (const term of ["  ui:", "dockerfile: apps/ui/Dockerfile.dev", "VITE_API_PROXY_TARGET:", "      - ../ui:/workspace/apps/ui", "      - /workspace/apps/ui/node_modules"]) {
+					if (!compose.includes(term)) errors.push(`${app.path}/docker-compose.dev.yml is missing the development UI container contract: ${term.trim()}`);
+				}
+			}
 			if (app.profiles.includes("firebase")) {
 				for (const term of [
 					"      FIREBASE_SERVICE_ACCOUNT_PATH: /app/firebase-service-account.development.json",
@@ -97,6 +106,7 @@ function validateAppMetadata(productRoot, app) {
 		}
 	}
 	if (app.kind === "ui") {
+		if (!fs.existsSync(path.join(root, "Dockerfile.dev"))) errors.push(`${app.path}/Dockerfile.dev is required`);
 		const generatedArtifacts = fs.readdirSync(root, { withFileTypes: true })
 			.filter(
 				(entry) =>
@@ -140,7 +150,7 @@ export function runConfiguredValidate(rootArgument, runningVersion, selectedKind
 		errors.push(`tailframe.json does not declare a ${selectedKind} app`);
 	}
 	errors.push(...validateVersionMetadata(loaded.root, runningVersion));
-	for (const app of loaded.config.apps) errors.push(...validateAppMetadata(loaded.root, app));
+	for (const app of loaded.config.apps) errors.push(...validateAppMetadata(loaded.root, app, loaded.config));
 	if (errors.length) return errors;
 	const apps = selectedKind ? loaded.config.apps.filter((app) => app.kind === selectedKind) : loaded.config.apps;
 	for (const app of apps) {