@projectdochelp/s3te 3.1.4 → 3.2.1

package/README.md

@@ -80,7 +80,7 @@ This section is only about the AWS things you need before you touch S3TE. The ac
 | Daily-work AWS access | `s3te deploy` needs credentials that can create CloudFormation stacks and related resources. | [Create an IAM user](https://docs.aws.amazon.com/console/iam/add-users), [Manage access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html) |
 | AWS CLI v2 | The S3TE CLI shells out to the official `aws` CLI. | [Install AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), [Get started with AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) |
 | Domain name you control | CloudFront and TLS only make sense for domains you can point to AWS. | Use your registrar of choice |
-| ACM certificate in `us-east-1` | CloudFront requires its public certificate in `us-east-1`. | [Public certificates in ACM](https://docs.aws.amazon.com/acm/latest/userguide/acm-public-certificates.html) |
+| ACM certificate in `us-east-1` | CloudFront requires its public certificate in `us-east-1`, and the certificate must cover every alias S3TE will derive for that environment. | [Public certificates in ACM](https://docs.aws.amazon.com/acm/latest/userguide/acm-public-certificates.html) |
 | Optional Route53 hosted zone | Needed only if S3TE should create DNS alias records automatically. | [Create a public hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html) |
 
 </details>
@@ -192,7 +192,7 @@ mywebsite/
     extensions.json
 ```
 
-The generated `.github/workflows/s3te-sync.yml` is the default CI path for GitHub-based source publishing into the S3TE code bucket. It is scaffolded once and then left alone on later `s3te init` runs unless you use `--force`.
+The generated `.github/workflows/s3te-sync.yml` is the default CI path for GitHub-based source publishing into the S3TE code buckets. It is scaffolded once and then left alone on later `s3te init` runs unless you use `--force`.
 
 </details>
 
@@ -228,6 +228,12 @@ The most important fields for a first deployment are:
 
 Use plain hostnames in `baseUrl` and `cloudFrontAliases`, not full URLs. If your config contains a `prod` environment plus additional environments such as `test` or `stage`, S3TE keeps the `prod` hostname unchanged and derives non-production hostnames automatically by prepending `<env>.`.
 
+Your ACM certificate must cover the final derived aliases of the environment you deploy. Example:
+
+- `*.example.com` covers `test.example.com`
+- `*.example.com` does not cover `test.app.example.com`
+- for nested aliases like `test.app.example.com`, add a SAN such as `*.app.example.com`, the exact hostname, or use a different `certificateArn` for that environment
+
 </details>
 
 <details>
@@ -243,6 +249,8 @@ npx s3te deploy --env dev
 
 `render` writes the local preview into `offline/S3TELocal/preview/dev/...`.
 
+`doctor --env <name>` now also checks whether the configured ACM certificate covers the CloudFront aliases that S3TE derives for that environment. For that check, the AWS identity running `doctor` needs permission to call `acm:DescribeCertificate` for the configured certificate ARN.
+
 `deploy` creates or updates the persistent environment stack, uses a temporary deploy stack for packaged Lambda artifacts, synchronizes the source project into the code bucket, and removes the temporary stack again when the deploy finishes.
 
 After the first successful deploy, use `s3te sync --env dev` for regular template, partial, asset and source updates when the infrastructure itself did not change.
@@ -251,6 +259,175 @@ If you left `route53HostedZoneId` out of the config, the last DNS step stays man
 
 </details>
 
+<details>
+  <summary>6. Prepare GitHub Actions for code-bucket publishing</summary>
+
+Use this step if your team wants GitHub pushes to publish project sources into the S3TE code bucket instead of running `s3te sync` locally.
+
+`s3te init` already scaffolded `.github/workflows/s3te-sync.yml` for that path.
+
+That workflow is meant for source publishing only:
+
+- it validates the project
+- it reads the selected environment from GitHub and resolves the matching AWS region from `s3te.config.json`
+- it uploads every configured variant into its own S3TE code bucket
+- the resulting S3 events trigger the deployed Lambda pipeline in AWS
+
+Use a full `deploy` only when the infrastructure, environment config, or runtime package changes.
+
+GitHub preparation checklist:
+
+1. Push the project to GitHub together with `.github/workflows/s3te-sync.yml`.
+2. Make sure GitHub Actions are allowed for the repository or organization.
+3. Run the first real `npx s3te deploy --env <name>` so the code buckets already exist.
+4. In AWS IAM, create an access key for a CI user that may sync only the S3TE code buckets for that environment.
+5. In GitHub open `Settings -> Secrets and variables -> Actions -> Variables`.
+6. Add these repository variables:
+   - `S3TE_ENVIRONMENT`
+     Use the exact environment name from `s3te.config.json`, for example `dev`, `test`, or `prod`.
+   - `S3TE_GIT_BRANCH` optional
+     Use the branch that should trigger the sync job, for example `main`.
+7. In GitHub open `Settings -> Secrets and variables -> Actions -> Secrets`.
+8. Add these repository secrets:
+   - `AWS_ACCESS_KEY_ID`
+   - `AWS_SECRET_ACCESS_KEY`
+9. Leave `.github/workflows/s3te-sync.yml` unchanged unless you want a custom CI flow. The scaffolded workflow already reads:
+   - the environment from `S3TE_ENVIRONMENT`
+   - the branch from `S3TE_GIT_BRANCH` or defaults to `main`
+   - the AWS region from `s3te.config.json`
+
+You do not have to store bucket names, source folders, part folders, or AWS regions in GitHub variables. `s3te sync` resolves all of that from `s3te.config.json`.
+
+For projects with multiple environments such as `test` and `prod`, the simplest setup is usually one workflow file per target environment, for example:
+
+- `.github/workflows/s3te-sync-test.yml` with `npx s3te sync --env test`
+- `.github/workflows/s3te-sync-prod.yml` with `npx s3te sync --env prod`
+
+First verification in GitHub:
+
+1. Open the `Actions` tab in the repository.
+2. Select `S3TE Sync`.
+3. Start it once manually with `Run workflow`.
+4. Check that the run reaches the `Configure AWS credentials`, `Validate project`, and `Sync project sources to the S3TE code buckets` steps without error.
+
+Where to get the AWS values:
+
+- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
+  In the AWS console open `IAM -> Users -> <your-ci-user> -> Security credentials -> Create access key`.
+  Save both values immediately. The secret access key is shown only once. AWS documents the credential options and access-key handling here:
+  [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html),
+  [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html).
+- `S3TE_ENVIRONMENT`
+  This is the environment key from your `s3te.config.json`, for example `test` or `prod`.
+- AWS region
+  You do not need to copy this into GitHub. The workflow reads `environments.<name>.awsRegion` directly from `s3te.config.json`.
+
+What gets uploaded where:
+
+- For each variant, S3TE stages `partDir` into `part/` and `sourceDir` into `<variant>/`.
+- Then S3TE syncs that staged tree into the resolved code bucket for that variant and environment.
+
+With your example config this means:
+
+- `test` + `website`: `app/part` and `app/website` go to `test-website-code-sop`
+- `test` + `app`: `app/part-app` and `app/app` go to `test-app-code-sop`
+- `prod` + `website`: `app/part` and `app/website` go to `website-code-sop`
+- `prod` + `app`: `app/part-app` and `app/app` go to `app-code-sop`
+
+Minimal IAM policy example for the `test` environment and both variants:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["s3:ListBucket"],
+      "Resource": [
+        "arn:aws:s3:::test-website-code-sop",
+        "arn:aws:s3:::test-app-code-sop"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+      "Resource": [
+        "arn:aws:s3:::test-website-code-sop/*",
+        "arn:aws:s3:::test-app-code-sop/*"
+      ]
+    }
+  ]
+}
+```
+
+For different environments or additional variants, use the derived code bucket names from your config.
+
+The scaffolded workflow looks like this:
+
+```yaml
+# Required GitHub repository secrets:
+# - AWS_ACCESS_KEY_ID
+# - AWS_SECRET_ACCESS_KEY
+# Required GitHub repository variable:
+# - S3TE_ENVIRONMENT (for example dev, test, or prod)
+# Optional GitHub repository variable:
+# - S3TE_GIT_BRANCH (defaults to main)
+# This workflow reads s3te.config.json at runtime and syncs all variants into their own code buckets.
+name: S3TE Sync
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Optional S3TE environment override from s3te.config.json
+        required: false
+        type: string
+  push:
+    paths:
+      - "app/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/s3te-sync.yml"
+
+jobs:
+  sync:
+    if: github.event_name == 'workflow_dispatch' || github.ref_name == (vars.S3TE_GIT_BRANCH || 'main')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        shell: bash
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+      - name: Resolve S3TE environment and AWS region from s3te.config.json
+        id: s3te-config
+        shell: bash
+        env:
+          WORKFLOW_INPUT_ENVIRONMENT: ${{ inputs.environment }}
+          REPOSITORY_S3TE_ENVIRONMENT: ${{ vars.S3TE_ENVIRONMENT }}
+        run: |
+          node -e "const fs=require('node:fs'); const requested=(process.env.WORKFLOW_INPUT_ENVIRONMENT || process.env.REPOSITORY_S3TE_ENVIRONMENT || '').trim(); const config=JSON.parse(fs.readFileSync('s3te.config.json','utf8')); const known=Object.keys(config.environments ?? {}); if(!requested){ console.error('Missing GitHub repository variable S3TE_ENVIRONMENT.'); process.exit(1);} const environmentConfig=config.environments?.[requested]; if(!environmentConfig){ console.error('Unknown environment ' + requested + '. Known environments: ' + (known.length > 0 ? known.join(', ') : '(none)') + '.'); process.exit(1);} fs.appendFileSync(process.env.GITHUB_OUTPUT, 'environment=' + requested + '\n'); fs.appendFileSync(process.env.GITHUB_OUTPUT, 'aws_region=' + environmentConfig.awsRegion + '\n');"
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: ${{ steps.s3te-config.outputs.aws_region }}
+      - run: npx s3te validate --env ${{ steps.s3te-config.outputs.environment }}
+      - run: npx s3te sync --env ${{ steps.s3te-config.outputs.environment }}
+```
+
+</details>
+
 ## Usage
 
 Once the project is installed, your everyday loop splits into two paths: deploy when infrastructure changes, sync when only project sources changed.
@@ -265,7 +442,7 @@ Once the project is installed, your everyday loop splits into two paths: deploy
 3. Validate and render locally.
 4. Run your tests.
 5. Use `deploy` for the first installation or after infrastructure/config/runtime changes.
-6. Use `sync` for day-to-day source publishing into the code bucket.
+6. Use `sync` for day-to-day source publishing into the code buckets.
 
 ```bash
 npx s3te validate
@@ -417,115 +594,6 @@ That deploy updates the existing environment stack and adds the Webiny mirror re
 
 </details>
 
-<details>
-  <summary>GitHub Actions source publishing</summary>
-
-If your team works through GitHub instead of running `s3te sync` locally, the scaffold already includes `.github/workflows/s3te-sync.yml`.
-
-That workflow is meant for source publishing only:
-
-- it validates the project
-- it uploads `app/...` and `part/...` into the S3TE code bucket
-- the resulting S3 events trigger the deployed Lambda pipeline in AWS
-
-Use a full `deploy` only when the infrastructure, environment config, or runtime package changes.
-
-GitHub preparation checklist:
-
-1. Push the project to GitHub together with `.github/workflows/s3te-sync.yml`.
-2. Make sure GitHub Actions are allowed for the repository or organization.
-3. Run the first real `npx s3te deploy --env <name>` so the code bucket already exists.
-4. In AWS IAM, create an access key for a CI user that may sync only the S3TE code bucket for that environment.
-5. In GitHub open `Settings -> Secrets and variables -> Actions -> Secrets`.
-6. Add these repository secrets:
-   - `AWS_ACCESS_KEY_ID`
-   - `AWS_SECRET_ACCESS_KEY`
-7. Open `.github/workflows/s3te-sync.yml` and adjust:
-   - the branch under `on.push.branches`
-   - `aws-region`
-   - `npx s3te sync --env dev` to your target environment such as `prod` or `test`
-
-No GitHub variables are required by the scaffolded workflow. The code bucket name is resolved by S3TE from `s3te.config.json`, so you do not have to store bucket names in GitHub.
-
-For projects with multiple environments such as `test` and `prod`, the simplest setup is usually one workflow file per target environment, for example:
-
-- `.github/workflows/s3te-sync-test.yml` with `npx s3te sync --env test`
-- `.github/workflows/s3te-sync-prod.yml` with `npx s3te sync --env prod`
-
-First verification in GitHub:
-
-1. Open the `Actions` tab in the repository.
-2. Select `S3TE Sync`.
-3. Start it once manually with `Run workflow`.
-4. Check that the run reaches the `Configure AWS credentials`, `Validate project`, and `Sync project sources to the S3TE code bucket` steps without error.
-
-Minimal IAM policy example for one code bucket:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": ["s3:ListBucket"],
-      "Resource": ["arn:aws:s3:::dev-website-code-mywebsite"]
-    },
-    {
-      "Effect": "Allow",
-      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
-      "Resource": ["arn:aws:s3:::dev-website-code-mywebsite/*"]
-    }
-  ]
-}
-```
-
-For non-production environments or additional variants, use the derived code bucket names from your config, for example `test-website-code-mywebsite` or `app-code-mywebsite`.
-
-The scaffolded workflow looks like this:
-
-```yaml
-name: S3TE Sync
-on:
-  workflow_dispatch:
-  push:
-    branches: ["main"]
-    paths:
-      - "app/**"
-      - "package.json"
-      - "package-lock.json"
-      - ".github/workflows/s3te-sync.yml"
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - name: Install dependencies
-        shell: bash
-        run: |
-          if [ -f package-lock.json ]; then
-            npm ci
-          else
-            npm install
-          fi
-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@v4
-        with:
-          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          aws-region: eu-central-1
-      - run: npx s3te validate
-      - run: npx s3te sync --env dev
-```
-
-</details>
-
 <details>
   <summary>What the migration command changes</summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectdochelp/s3te",
-  "version": "3.1.4",
+  "version": "3.2.1",
   "description": "CLI, render core, AWS adapter, and testkit for S3TemplateEngine projects",
   "repository": {
     "type": "git",

package/packages/aws-adapter/src/deploy.mjs

@@ -53,6 +53,52 @@ async function describeStack({ stackName, region, profile, cwd }) {
   return JSON.parse(describedStack.stdout).Stacks?.[0];
 }
 
+async function describeStackEvents({ stackName, region, profile, cwd }) {
+  const describedEvents = await runAwsCli(["cloudformation", "describe-stack-events", "--stack-name", stackName, "--output", "json"], {
+    region,
+    profile,
+    cwd,
+    errorCode: "ADAPTER_ERROR"
+  });
+  return JSON.parse(describedEvents.stdout).StackEvents ?? [];
+}
+
+export function summarizeStackFailureEvents(stackEvents = [], limit = 8) {
+  return stackEvents
+    .filter((event) => (
+      String(event.ResourceStatus ?? "").includes("FAILED")
+      || String(event.ResourceStatus ?? "").includes("ROLLBACK")
+    ))
+    .map((event) => ({
+      timestamp: event.Timestamp,
+      logicalResourceId: event.LogicalResourceId,
+      resourceType: event.ResourceType,
+      resourceStatus: event.ResourceStatus,
+      resourceStatusReason: event.ResourceStatusReason
+    }))
+    .slice(0, limit);
+}
+
+async function attachStackFailureDetails(error, { stackName, region, profile, cwd }) {
+  try {
+    const stackEvents = await describeStackEvents({ stackName, region, profile, cwd });
+    const summarizedEvents = summarizeStackFailureEvents(stackEvents);
+    if (summarizedEvents.length > 0) {
+      error.details = {
+        ...(error.details ?? {}),
+        stackFailureEvents: summarizedEvents
+      };
+    }
+  } catch (stackEventsError) {
+    error.details = {
+      ...(error.details ?? {}),
+      stackFailureEventsError: stackEventsError.message
+    };
+  }
+
+  return error;
+}
+
 async function deployCloudFormationStack({
   stackName,
   templatePath,
@@ -85,13 +131,22 @@ async function deployCloudFormationStack({
     args.push("--no-execute-changeset");
   }
 
-  await runAwsCli(args, {
-    region,
-    profile,
-    cwd,
-    stdio,
-    errorCode: "ADAPTER_ERROR"
-  });
+  try {
+    await runAwsCli(args, {
+      region,
+      profile,
+      cwd,
+      stdio,
+      errorCode: "ADAPTER_ERROR"
+    });
+  } catch (error) {
+    throw await attachStackFailureDetails(error, {
+      stackName,
+      region,
+      profile,
+      cwd
+    });
+  }
 }
 
 async function resolveWebinyStreamArn({ runtimeConfig, region, profile, cwd }) {
@@ -176,6 +231,63 @@ async function deployTemporaryArtifactsStack({
   };
 }
 
+export function collectBucketObjectVersions(payload = {}) {
+  return [
+    ...(payload.Versions ?? []),
+    ...(payload.DeleteMarkers ?? [])
+  ].map((entry) => ({
+    Key: entry.Key,
+    VersionId: entry.VersionId
+  })).filter((entry) => entry.Key && entry.VersionId);
+}
+
+function chunkItems(items, chunkSize) {
+  const chunks = [];
+  for (let index = 0; index < items.length; index += chunkSize) {
+    chunks.push(items.slice(index, index + chunkSize));
+  }
+  return chunks;
+}
+
+async function deleteBucketObjectVersions({
+  bucketName,
+  region,
+  profile,
+  cwd
+}) {
+  while (true) {
+    const listedVersions = await runAwsCli(["s3api", "list-object-versions", "--bucket", bucketName, "--output", "json"], {
+      region,
+      profile,
+      cwd,
+      errorCode: "ADAPTER_ERROR"
+    });
+    const objects = collectBucketObjectVersions(JSON.parse(listedVersions.stdout || "{}"));
+    if (objects.length === 0) {
+      return;
+    }
+
+    for (const batch of chunkItems(objects, 250)) {
+      await runAwsCli([
+        "s3api",
+        "delete-objects",
+        "--bucket",
+        bucketName,
+        "--delete",
+        JSON.stringify({
+          Objects: batch,
+          Quiet: true
+        })
+      ], {
+        region,
+        profile,
+        cwd,
+        errorCode: "ADAPTER_ERROR"
+      });
+    }
+  }
+}
+
 async function cleanupTemporaryArtifactsStack({
   stackName,
   artifactBucket,
@@ -191,6 +303,12 @@ async function cleanupTemporaryArtifactsStack({
         cwd,
         errorCode: "ADAPTER_ERROR"
       });
+      await deleteBucketObjectVersions({
+        bucketName: artifactBucket,
+        region,
+        profile,
+        cwd
+      });
     } catch (error) {
       if (!String(error.message).includes("NoSuchBucket")) {
         throw error;

package/packages/cli/src/project.mjs

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 
 import {
   S3teError,
+  buildEnvironmentRuntimeConfig,
   createManualRenderTargets,
   isRenderableKey,
   loadProjectConfig,
@@ -16,6 +17,7 @@ import {
   ensureAwsCliAvailable,
   ensureAwsCredentials,
   packageAwsProject,
+  runAwsCli,
   syncAwsProject
 } from "../../aws-adapter/src/index.mjs";
 
@@ -32,11 +34,102 @@ function normalizePath(value) {
   return String(value).replace(/\\/g, "/");
 }
 
+function isProjectTestFile(filename) {
+  return /(?:^test-.*|.*\.(?:test|spec))\.(?:cjs|mjs|js)$/i.test(filename);
+}
+
+async function listProjectTestFiles(rootDir, currentDir = rootDir) {
+  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listProjectTestFiles(rootDir, fullPath));
+      continue;
+    }
+
+    if (entry.isFile() && isProjectTestFile(entry.name)) {
+      files.push(normalizePath(path.relative(rootDir, fullPath)));
+    }
+  }
+
+  return files.sort();
+}
+
 function unknownEnvironmentMessage(config, environmentName) {
   const knownEnvironments = Object.keys(config?.environments ?? {});
   return `Unknown environment ${environmentName}. Known environments: ${knownEnvironments.length > 0 ? knownEnvironments.join(", ") : "(none)"}.`;
 }
 
+function normalizeHostname(value) {
+  return String(value ?? "").trim().toLowerCase().replace(/\.+$/, "");
+}
+
+function certificatePatternMatchesHost(pattern, hostname) {
+  const normalizedPattern = normalizeHostname(pattern);
+  const normalizedHostname = normalizeHostname(hostname);
+
+  if (!normalizedPattern || !normalizedHostname) {
+    return false;
+  }
+
+  if (!normalizedPattern.includes("*")) {
+    return normalizedPattern === normalizedHostname;
+  }
+
+  const patternLabels = normalizedPattern.split(".");
+  const hostnameLabels = normalizedHostname.split(".");
+
+  if (patternLabels[0] !== "*" || patternLabels.slice(1).some((label) => label.includes("*"))) {
+    return false;
+  }
+
+  if (patternLabels.length !== hostnameLabels.length) {
+    return false;
+  }
+
+  return patternLabels.slice(1).join(".") === hostnameLabels.slice(1).join(".");
+}
+
+function findUncoveredCertificateHosts(hostnames, certificateDomains) {
+  const normalizedCertificateDomains = [...new Set(
+    certificateDomains
+      .map((value) => normalizeHostname(value))
+      .filter(Boolean)
+  )];
+
+  return [...new Set(
+    hostnames
+      .map((value) => normalizeHostname(value))
+      .filter(Boolean)
+      .filter((hostname) => !normalizedCertificateDomains.some((pattern) => certificatePatternMatchesHost(pattern, hostname)))
+  )].sort();
+}
+
+function collectEnvironmentCloudFrontAliases(config, environmentName) {
+  const runtimeConfig = buildEnvironmentRuntimeConfig(config, environmentName);
+  const aliases = [];
+
+  for (const variantConfig of Object.values(runtimeConfig.variants)) {
+    for (const languageConfig of Object.values(variantConfig.languages)) {
+      aliases.push(...(languageConfig.cloudFrontAliases ?? []));
+    }
+  }
+
+  return [...new Set(aliases.map((value) => normalizeHostname(value)).filter(Boolean))].sort();
+}
+
+async function describeAcmCertificate({ certificateArn, profile, cwd, runAwsCliFn }) {
+  const response = await runAwsCliFn(["acm", "describe-certificate", "--certificate-arn", certificateArn, "--output", "json"], {
+    region: "us-east-1",
+    profile,
+    cwd,
+    errorCode: "AWS_AUTH_ERROR"
+  });
+  return JSON.parse(response.stdout || "{}").Certificate ?? {};
+}
+
 function assertKnownEnvironment(config, environmentName) {
   if (!environmentName) {
     return;
@@ -250,17 +343,24 @@ function schemaTemplate() {
 }
 
 function githubSyncWorkflowTemplate() {
-  return `# Before first use:
-# 1. Run "npx s3te deploy --env dev" once so the S3TE code bucket already exists.
-# 2. Add GitHub Actions secrets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
-# 3. Adjust branch, aws-region, and the target environment below.
+  return `# Required GitHub repository secrets:
+# - AWS_ACCESS_KEY_ID
+# - AWS_SECRET_ACCESS_KEY
+# Required GitHub repository variable:
+# - S3TE_ENVIRONMENT (for example dev, test, or prod)
+# Optional GitHub repository variable:
+# - S3TE_GIT_BRANCH (defaults to main)
+# This workflow reads s3te.config.json at runtime and syncs all variants into their own code buckets.
 name: S3TE Sync
 
 on:
   workflow_dispatch:
+    inputs:
+      environment:
+        description: Optional S3TE environment override from s3te.config.json
+        required: false
+        type: string
   push:
-    branches:
-      - main
     paths:
       - "app/**"
       - "package.json"
@@ -269,6 +369,7 @@ on:
 
 jobs:
   sync:
+    if: github.event_name == 'workflow_dispatch' || github.ref_name == (vars.S3TE_GIT_BRANCH || 'main')
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -286,16 +387,24 @@ jobs:
           else
             npm install
           fi
+      - name: Resolve S3TE environment and AWS region from s3te.config.json
+        id: s3te-config
+        shell: bash
+        env:
+          WORKFLOW_INPUT_ENVIRONMENT: \${{ inputs.environment }}
+          REPOSITORY_S3TE_ENVIRONMENT: \${{ vars.S3TE_ENVIRONMENT }}
+        run: |
+          node -e "const fs=require('node:fs'); const requested=(process.env.WORKFLOW_INPUT_ENVIRONMENT || process.env.REPOSITORY_S3TE_ENVIRONMENT || '').trim(); const config=JSON.parse(fs.readFileSync('s3te.config.json','utf8')); const known=Object.keys(config.environments ?? {}); if(!requested){ console.error('Missing GitHub repository variable S3TE_ENVIRONMENT.'); process.exit(1);} const environmentConfig=config.environments?.[requested]; if(!environmentConfig){ console.error('Unknown environment ' + requested + '. Known environments: ' + (known.length > 0 ? known.join(', ') : '(none)') + '.'); process.exit(1);} fs.appendFileSync(process.env.GITHUB_OUTPUT, 'environment=' + requested + '\\n'); fs.appendFileSync(process.env.GITHUB_OUTPUT, 'aws_region=' + environmentConfig.awsRegion + '\\n');"
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v4
         with:
           aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
           aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          aws-region: eu-central-1
+          aws-region: \${{ steps.s3te-config.outputs.aws_region }}
       - name: Validate project
-        run: npx s3te validate
-      - name: Sync project sources to the S3TE code bucket
-        run: npx s3te sync --env dev
+        run: npx s3te validate --env \${{ steps.s3te-config.outputs.environment }}
+      - name: Sync project sources to the S3TE code buckets
+        run: npx s3te sync --env \${{ steps.s3te-config.outputs.environment }}
 `;
 }
 
@@ -720,8 +829,12 @@ export async function runProjectTests(projectDir) {
   const testsDir = await fileExists(path.join(projectDir, "offline", "tests"))
     ? "offline/tests"
     : "tests";
+  const testFiles = await listProjectTestFiles(path.join(projectDir, testsDir));
+  const testArgs = testFiles.length > 0
+    ? testFiles.map((relativePath) => normalizePath(path.join(testsDir, relativePath)))
+    : [testsDir];
   return new Promise((resolve) => {
-    const child = spawn(process.execPath, ["--test", testsDir], {
+    const child = spawn(process.execPath, ["--test", ...testArgs], {
       cwd: projectDir,
       stdio: "inherit"
     });
@@ -771,6 +884,9 @@ export async function syncProject(projectDir, config, options = {}) {
 }
 
 export async function doctorProject(projectDir, configPath, options = {}) {
+  const ensureAwsCliAvailableFn = options.ensureAwsCliAvailableFn ?? ensureAwsCliAvailable;
+  const ensureAwsCredentialsFn = options.ensureAwsCredentialsFn ?? ensureAwsCredentials;
+  const runAwsCliFn = options.runAwsCliFn ?? runAwsCli;
   const checks = [];
   const majorVersion = Number(process.versions.node.split(".")[0]);
 
@@ -795,7 +911,7 @@ export async function doctorProject(projectDir, configPath, options = {}) {
   }
 
   try {
-    await ensureAwsCliAvailable({ cwd: projectDir });
+    await ensureAwsCliAvailableFn({ cwd: projectDir });
     checks.push({ name: "aws-cli", ok: true, message: "AWS CLI available" });
   } catch (error) {
     checks.push({ name: "aws-cli", ok: false, message: error.message });
@@ -812,7 +928,7 @@ export async function doctorProject(projectDir, configPath, options = {}) {
     }
 
     try {
-      await ensureAwsCredentials({
+      await ensureAwsCredentialsFn({
         region: options.config.environments[options.environment].awsRegion,
         profile: options.profile,
         cwd: projectDir
@@ -821,6 +937,38 @@ export async function doctorProject(projectDir, configPath, options = {}) {
     } catch (error) {
       checks.push({ name: "aws-auth", ok: false, message: error.message });
     }
+
+    const environmentConfig = options.config.environments[options.environment];
+    const awsAuthCheck = checks.at(-1);
+    if (awsAuthCheck?.name === "aws-auth" && awsAuthCheck.ok) {
+      try {
+        const cloudFrontAliases = collectEnvironmentCloudFrontAliases(options.config, options.environment);
+        const certificate = await describeAcmCertificate({
+          certificateArn: environmentConfig.certificateArn,
+          profile: options.profile,
+          cwd: projectDir,
+          runAwsCliFn
+        });
+        const certificateDomains = [
+          certificate.DomainName,
+          ...(certificate.SubjectAlternativeNames ?? [])
+        ];
+        const uncoveredAliases = findUncoveredCertificateHosts(cloudFrontAliases, certificateDomains);
+        checks.push({
+          name: "acm-certificate",
+          ok: uncoveredAliases.length === 0,
+          message: uncoveredAliases.length === 0
+            ? `ACM certificate covers ${cloudFrontAliases.length} CloudFront alias(es) for ${options.environment}`
+            : `ACM certificate ${environmentConfig.certificateArn} does not cover these CloudFront aliases for ${options.environment}: ${uncoveredAliases.join(", ")}.`
+        });
+      } catch (error) {
+        checks.push({
+          name: "acm-certificate",
+          ok: false,
+          message: `Could not inspect ACM certificate ${environmentConfig.certificateArn}: ${error.message}`
+        });
+      }
+    }
   }
 
   return checks;