@zaaxch/tailframe 4.0.6 → 4.0.8

package/package.json

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

@@ -282,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",
@@ -584,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.
@@ -1099,6 +1103,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 \\
@@ -1154,6 +1159,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
@@ -1190,17 +1198,28 @@ 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 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}
 └── shared/
     ├── .env.production
     ├── .env.infrastructure
+    ├── caddy/
+    │   ├── certs/
+    │   │   ├── origin.pem
+    │   │   └── origin-key.pem
+    │   ├── config/
+    │   └── data/
 ${options.auth === "firebase" ? `    ├── secrets/firebase-service-account.json
 ` : ""}${postgres ? `    ├── postgres/data/
 ` : `    ├── mongo/config/keyfile
@@ -1215,6 +1234,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\` 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.
@@ -1225,15 +1245,19 @@ Do not inject \`.env.infrastructure\` into Node. Make both host environment file
 
 1. Install Docker Engine and Docker Compose.
 ${postgres
-	? `2. Create \`/opt/${options.name}/current/deploy/postgres\` and \`/opt/${options.name}/shared/postgres/data\`${options.redis ? `, plus \`/opt/${options.name}/shared/redis/data\`` : ""}.`
+	? `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\`${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.
 
@@ -1280,6 +1304,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,
@@ -1288,8 +1316,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 = [
@@ -1331,6 +1359,34 @@ const developmentEnvironment = [
 ];
 const developmentEnvironmentBlock = `\n    environment:\n${developmentEnvironment.join("\n")}`;
 const volumeBlock = serviceVolumes.length ? `\n    volumes:\n${serviceVolumes.join("\n")}` : "";
+const caddyService = `
+  caddy:
+    image: caddy:2.11.4-alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - \${CADDY_ORIGIN_CERTIFICATE:?Set CADDY_ORIGIN_CERTIFICATE}:/etc/caddy/certs/origin.pem:ro
+      - \${CADDY_ORIGIN_KEY:?Set CADDY_ORIGIN_KEY}:/etc/caddy/certs/origin-key.pem:ro
+      - \${CADDY_DATA_DIR:?Set CADDY_DATA_DIR}:/data
+      - \${CADDY_CONFIG_DIR:?Set CADDY_CONFIG_DIR}:/config
+    depends_on:
+      ${options.name}:
+        condition: service_healthy
+    networks:
+      - backend
+    restart: unless-stopped`;
+add(`${svc}/Caddyfile`, `{
+	auto_https off
+}
+:80 {
+	redir https://{host}{uri} 308
+}
+:443 {
+	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}
     env_file:
@@ -1472,9 +1528,7 @@ services:
   ${options.name}:
     image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
     env_file:
-      - \${APP_ENV_FILE:-.env.production}
-    ports:
-      - "3000:3000"${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
+      - \${APP_ENV_FILE:-.env.production}${productionEnvironmentBlock}${volumeBlock}${dependsBlock}
     healthcheck:
       test:
         - CMD-SHELL
@@ -1490,7 +1544,7 @@ services:
     stop_grace_period: 2m
     networks:
       - backend
-    restart: unless-stopped${workerService}${schemaInitService}${databaseService}${redisService}
+    restart: unless-stopped${caddyService}${workerService}${schemaInitService}${databaseService}${redisService}
 networks:
   backend:
     driver: bridge