@zaaxch/tailframe 4.0.2 → 4.0.3

package/package.json

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

@@ -551,7 +551,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: deployment is manual from \`main\`, accepts only an already-published full SHA from \`main\` history, and checks out that exact commit for deployment files. 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. 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\`.
 
 ## 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.
@@ -872,7 +872,7 @@ jobs:
             github.event_name == 'push' &&
             vars.AWS_ACCOUNT_ID != '' &&
             vars.AWS_REGION != '' &&
-            vars.AWS_ROLE_ARN != ''
+            vars.AWS_RELEASE_ROLE_ARN != ''
         runs-on: ubuntu-latest
         environment:
             name: release
@@ -892,7 +892,7 @@ jobs:
             - name: Configure AWS credentials
               uses: aws-actions/configure-aws-credentials@v6
               with:
-                  role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+                  role-to-assume: \${{ vars.AWS_RELEASE_ROLE_ARN }}
                   aws-region: \${{ vars.AWS_REGION }}
 
             - name: Resolve immutable image
@@ -950,8 +950,8 @@ ${workflowUiEnvironment}
                   {
                     echo "### ${title} release image"
                     echo
-                    echo "- Image: \`\${IMAGE}:\${IMAGE_TAG}\`"
-                    echo "- Digest: \`\${IMAGE_DIGEST}\`"
+                    printf -- '- Image: \`%s:%s\`\\n' "$IMAGE" "$IMAGE_TAG"
+                    printf -- '- Digest: \`%s\`\\n' "$IMAGE_DIGEST"
                   } >> "$GITHUB_STEP_SUMMARY"
 `);
 add(".github/workflows/deploy.yml", `name: Deploy release image
@@ -1009,7 +1009,7 @@ jobs:
             - name: Configure AWS credentials
               uses: aws-actions/configure-aws-credentials@v6
               with:
-                  role-to-assume: \${{ vars.AWS_ROLE_ARN }}
+                  role-to-assume: \${{ vars.AWS_DEPLOY_ROLE_ARN }}
                   aws-region: \${{ vars.AWS_REGION }}
 
             - name: Resolve and verify image
@@ -1073,8 +1073,8 @@ jobs:
                   {
                     echo "### ${title} production deployment"
                     echo
-                    echo "- Image: \`\${IMAGE}:\${IMAGE_TAG}\`"
-                    echo "- Digest: \`\${IMAGE_DIGEST}\`"
+                    printf -- '- Image: \`%s:%s\`\\n' "$IMAGE" "$IMAGE_TAG"
+                    printf -- '- Digest: \`%s\`\\n' "$IMAGE_DIGEST"
                   } >> "$GITHUB_STEP_SUMMARY"
 `);
 add(`${svc}/scripts/deploy_remote.sh`, `#!/usr/bin/env bash
@@ -1140,8 +1140,8 @@ Only service${options.ui ? ", UI," : ","} workspace, lockfile, architecture, and
 The ECR build job runs only for the post-merge \`main\` push and remains skipped until the repository AWS variables are
 configured. No push or merge deploys production automatically.
 
-Configure the ECR repository with immutable image tags and restrict routine push permission to the repository's
-release workflow. Record the full commit SHA and ECR digest; deployment and migration must use that release image.
+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.
 
 The host separates replaceable artifacts from persistent state:
 
@@ -1192,10 +1192,10 @@ Use a fresh ${postgres ? "PostgreSQL" : "MongoDB"} data directory. Migrating an
 
 ## GitHub repository variables
 
-Configure \`AWS_ACCOUNT_ID\`, \`AWS_REGION\`, and \`AWS_ROLE_ARN\` as repository variables for the
-repository-restricted OIDC role. Optionally set \`ECR_REPOSITORY\`; the default is \`${options.name}\`.
+Configure \`AWS_ACCOUNT_ID\`, \`AWS_REGION\`, \`AWS_RELEASE_ROLE_ARN\`, and \`AWS_DEPLOY_ROLE_ARN\` as repository
+variables. Optionally set \`ECR_REPOSITORY\`; the default is \`${options.name}\`.
 
-The ECR repository and AWS OIDC provider/role are provisioned separately. Workflows never store long-lived AWS keys
+The ECR repository and AWS OIDC provider/roles are provisioned separately. Workflows never store long-lived AWS keys
 or create cloud infrastructure.
 
 ## GitHub release environment
@@ -1209,8 +1209,10 @@ Configure \`DEPLOY_HOST\` and \`DEPLOY_USER\` as production-environment variable
 - \`DEPLOY_SSH_PRIVATE_KEY\`: dedicated host deployment key.
 - \`DEPLOY_SSH_KNOWN_HOSTS\`: pinned host key.
 
-Restrict the production environment's deployment branches to \`main\`. Required reviewer approval MAY add a second
-manual gate, but the branch restriction and manual full-SHA input remain mandatory.
+Restrict both environments' deployment branches to \`main\`. The release role trust accepts only the repository's
+\`release\` environment OIDC subject; the pull-only deployment role accepts only its \`production\` subject. Use the
+repository's active GitHub subject format: legacy subjects name the owner/repository, while immutable subjects use
+their IDs. Do not use a repository-wide wildcard. Required reviewer approval MAY add a second manual gate.
 
 ## Deploy and rollback
 
@@ -1223,6 +1225,12 @@ 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.
 
+## Product data-migration handoff
+
+Tailframe does not generate product-specific data-migration orchestration. Before a production data migration,
+authenticate to ECR, pull the selected full-SHA release image, verify its digest against the release record, and
+explicitly configure the production datastore target. Never inherit a rehearsal URI, local image default, or source build.
+
 ${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