@projectdochelp/s3te 3.2.0 → 3.2.2

package/README.md

@@ -18,6 +18,7 @@ This README is the user guide for the rewrite generation. The deeper implementat
     - [Daily Workflow](#daily-workflow)
     - [CLI Commands](#cli-commands)
     - [Template Commands](#template-commands)
+  - [Optional: Sitemap](#optional-sitemap)
   - [Optional: Webiny CMS](#optional-webiny-cms)
 
 ## Motivation
@@ -65,6 +66,8 @@ That source sync is not limited to Lambda code. It includes your `.html`, `.part
 
 The persistent environment stack contains the long-lived AWS resources such as buckets, Lambda functions, DynamoDB tables, CloudFront distributions and the runtime manifest parameter. The temporary deploy stack exists only so CloudFormation can consume the packaged Lambda artifacts cleanly.
 
+If optional runtime features such as `sitemap` or Webiny are enabled in `s3te.config.json`, the same environment stack also carries those extra Lambdas and event bindings.
+
 </details>
 
 ## Installation (AWS)
@@ -80,7 +83,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>
@@ -226,7 +229,18 @@ The most important fields for a first deployment are:
 
 `route53HostedZoneId` is optional. Leave it out if you want to manage DNS yourself.
 
-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>.`.
+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 like this:
+
+- apex host: `example.com` -> `test.example.com`
+- first-level subdomain: `app.example.com` -> `test-app.example.com`
+- deeper host: `admin.app.example.com` -> `test-admin.app.example.com`
+
+Your ACM certificate must cover the final derived aliases of the environment you deploy. Example:
+
+- `*.example.com` covers `test.example.com`
+- `*.example.com` also covers `test-app.example.com`
+- `*.example.com` does not cover `test-admin.app.example.com`
+- for deeper aliases like `test-admin.app.example.com`, add a SAN such as `*.app.example.com`, the exact hostname, or use a different `certificateArn` for that environment
 
 </details>
 
@@ -243,6 +257,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.
@@ -468,7 +484,7 @@ Once Webiny is installed and the stack is deployed with Webiny enabled, CMS cont
 | `s3te sync --env <name>` | Uploads current project sources into the configured code buckets. |
 | `s3te doctor --env <name>` | Checks local machine and AWS access before deploy. |
 | `s3te deploy --env <name>` | Deploys or updates the AWS environment and syncs source files. |
-| `s3te migrate` | Updates older project configs and can retrofit Webiny into an existing S3TE project. |
+| `s3te migrate` | Updates older project configs and can retrofit optional features such as `sitemap` or Webiny into an existing S3TE project. |
 
 </details>
 
@@ -530,6 +546,63 @@ These are the core S3TE commands you will use even in a plain HTML-only project.
 
 If you also want content-driven commands such as `dbmulti` or `dbmultifile`, continue with the optional Webiny section below. The same commands can also read from local `offline/content/*.json` files when you are not using Webiny yet.
 
+## Optional: Sitemap
+
+You do not need `sitemap.xml` automation to use S3TE. If you want it, S3TE can maintain one `sitemap.xml` per published output bucket through a dedicated Lambda, just like the older 2.x generation.
+
+<details>
+  <summary>Enable sitemap maintenance</summary>
+
+Add this block to `s3te.config.json`:
+
+```json
+"integrations": {
+  "sitemap": {
+    "enabled": true,
+    "environments": {
+      "dev": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
+The top-level `enabled` acts as the default. `integrations.sitemap.environments.<env>.enabled` can override that for a single environment.
+
+If you prefer the CLI path, this does the same retrofit:
+
+```bash
+npx s3te migrate --enable-sitemap --write
+npx s3te migrate --env test --enable-sitemap --write
+```
+
+After enabling or disabling `sitemap`, redeploy the affected environment once:
+
+```bash
+npx s3te deploy --env prod
+```
+
+</details>
+
+<details>
+  <summary>What the sitemap feature does</summary>
+
+When `sitemap` is enabled for an environment, S3TE adds one `sitemap-updater` Lambda to that environment stack and wires every output bucket to it for HTML create/delete events.
+
+The Lambda maintains `sitemap.xml` directly inside the same output bucket:
+
+- one sitemap per variant/language output bucket
+- only published HTML files are tracked
+- `404.html` is ignored
+- `index.html` becomes `https://example.com/`
+- nested `news/index.html` becomes `https://example.com/news/`
+- regular pages such as `about.html` stay `https://example.com/about.html`
+
+Because the trigger sits on the output bucket, the sitemap also stays correct when HTML is regenerated from Webiny content changes in AWS. Asset-only changes do not affect it.
+
+</details>
+
 ## Optional: Webiny CMS
 
 You do not need Webiny to use S3TE. Start with plain HTML first. Add Webiny only when editors should maintain content in a CMS instead of editing local JSON files under `offline/content/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectdochelp/s3te",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "CLI, render core, AWS adapter, and testkit for S3TemplateEngine projects",
   "repository": {
     "type": "git",
@@ -51,7 +51,8 @@
     "@aws-sdk/client-sfn": "^3.0.0",
     "@aws-sdk/client-ssm": "^3.0.0",
     "@aws-sdk/lib-dynamodb": "^3.0.0",
-    "@aws-sdk/util-dynamodb": "^3.0.0"
+    "@aws-sdk/util-dynamodb": "^3.0.0",
+    "fast-xml-parser": "^4.0.8"
   },
   "publishConfig": {
     "access": "public"

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;
@@ -226,6 +344,7 @@ function buildEnvironmentStackParameters({
     `InvalidationSchedulerArtifactKey=${uploadedArtifacts.invalidationScheduler}`,
     `InvalidationExecutorArtifactKey=${uploadedArtifacts.invalidationExecutor}`,
     `ContentMirrorArtifactKey=${uploadedArtifacts.contentMirror}`,
+    `SitemapUpdaterArtifactKey=${uploadedArtifacts.sitemapUpdater}`,
     `RuntimeManifestValue=${runtimeManifestValue}`,
     `WebinySourceTableStreamArn=${webinyStreamArn}`
   ];
@@ -252,6 +371,9 @@ export async function deployAwsProject({
   if (requestedFeatureSet.has("webiny") && !runtimeConfig.integrations.webiny.enabled) {
     throw new S3teError("ADAPTER_ERROR", "Feature webiny was requested but is not enabled in s3te.config.json.");
   }
+  if (requestedFeatureSet.has("sitemap") && !runtimeConfig.integrations.sitemap.enabled) {
+    throw new S3teError("ADAPTER_ERROR", "Feature sitemap was requested but is not enabled in s3te.config.json.");
+  }
 
   await ensureAwsCliAvailable({ cwd: projectDir });
   await ensureAwsCredentials({

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

@@ -1,4 +1,7 @@
-import { resolveEnvironmentWebinyIntegration } from "../../core/src/index.mjs";
+import {
+  resolveEnvironmentSitemapIntegration,
+  resolveEnvironmentWebinyIntegration
+} from "../../core/src/index.mjs";
 
 export function getConfiguredFeatures(config, environment) {
   const features = [];
@@ -7,16 +10,25 @@ export function getConfiguredFeatures(config, environment) {
     if (resolveEnvironmentWebinyIntegration(config, environment).enabled) {
       features.push("webiny");
     }
+    if (resolveEnvironmentSitemapIntegration(config, environment).enabled) {
+      features.push("sitemap");
+    }
     return features;
   }
 
   const hasAnyEnvironmentWebiny = Object.keys(config.environments ?? {}).some((environmentName) => (
     resolveEnvironmentWebinyIntegration(config, environmentName).enabled
   ));
+  const hasAnyEnvironmentSitemap = Object.keys(config.environments ?? {}).some((environmentName) => (
+    resolveEnvironmentSitemapIntegration(config, environmentName).enabled
+  ));
 
   if (hasAnyEnvironmentWebiny) {
     features.push("webiny");
   }
+  if (hasAnyEnvironmentSitemap) {
+    features.push("sitemap");
+  }
 
   return features;
 }

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

@@ -30,7 +30,8 @@ function buildFunctionNames(runtimeConfig) {
     renderWorker: `${runtimeConfig.stackPrefix}_s3te_render_worker`,
     invalidationScheduler: `${runtimeConfig.stackPrefix}_s3te_invalidation_scheduler`,
     invalidationExecutor: `${runtimeConfig.stackPrefix}_s3te_invalidation_executor`,
-    contentMirror: runtimeConfig.integrations.webiny.enabled ? `${runtimeConfig.stackPrefix}_s3te_content_mirror` : ""
+    contentMirror: runtimeConfig.integrations.webiny.enabled ? `${runtimeConfig.stackPrefix}_s3te_content_mirror` : "",
+    sitemapUpdater: runtimeConfig.integrations.sitemap.enabled ? `${runtimeConfig.stackPrefix}_s3te_sitemap_updater` : ""
   };
 }
 
@@ -79,6 +80,9 @@ export function buildAwsRuntimeManifest({ config, environment, stackOutputs = {}
             mirrorTableName: runtimeConfig.integrations.webiny.mirrorTableName,
             relevantModels: [...runtimeConfig.integrations.webiny.relevantModels],
             tenant: runtimeConfig.integrations.webiny.tenant
+          },
+          sitemap: {
+            enabled: runtimeConfig.integrations.sitemap.enabled
           }
         },
         variants: runtimeConfig.variants

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

@@ -25,7 +25,8 @@ const RUNTIME_PACKAGE_DEPENDENCIES = [
   "@aws-sdk/client-sfn",
   "@aws-sdk/client-ssm",
   "@aws-sdk/lib-dynamodb",
-  "@aws-sdk/util-dynamodb"
+  "@aws-sdk/util-dynamodb",
+  "fast-xml-parser"
 ];
 const INTERNAL_RUNTIME_DIRECTORIES = [
   {
@@ -226,6 +227,9 @@ export async function packageAwsProject({
   if (features.includes("webiny") && !runtimeConfig.integrations.webiny.enabled) {
     throw new S3teError("ADAPTER_ERROR", "Feature webiny was requested but is not enabled in s3te.config.json.");
   }
+  if (features.includes("sitemap") && !runtimeConfig.integrations.sitemap.enabled) {
+    throw new S3teError("ADAPTER_ERROR", "Feature sitemap was requested but is not enabled in s3te.config.json.");
+  }
 
   const resolvedFeatures = resolveRequestedFeatures(config, features, environment);
   const packageDir = outDir
@@ -267,6 +271,11 @@ export async function packageAwsProject({
       archive: path.join(lambdaDir, "content-mirror.zip"),
       parameter: "ContentMirrorArtifactKey",
       s3Key: `lambda/content-mirror.zip`
+    },
+    sitemapUpdater: {
+      archive: path.join(lambdaDir, "sitemap-updater.zip"),
+      parameter: "SitemapUpdaterArtifactKey",
+      s3Key: "lambda/sitemap-updater.zip"
     }
   };
 

package/packages/aws-adapter/src/runtime/common.mjs

@@ -258,6 +258,9 @@ export function buildCoreConfigFromEnvironment(manifest, environmentName) {
         mirrorTableName: environment.integrations.webiny.mirrorTableName,
         relevantModels: [...environment.integrations.webiny.relevantModels],
         tenant: environment.integrations.webiny.tenant
+      },
+      sitemap: {
+        enabled: environment.integrations.sitemap?.enabled ?? false
       }
     }
   };

package/packages/aws-adapter/src/runtime/sitemap-updater.mjs

@@ -0,0 +1,221 @@
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+
+import {
+  createAwsClients,
+  decodeS3Key,
+  loadEnvironmentManifest
+} from "./common.mjs";
+
+const SITEMAP_XML_NAMESPACE = "http://www.sitemaps.org/schemas/sitemap/0.9";
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  isArray: (name) => name === "url"
+});
+const builder = new XMLBuilder({
+  ignoreAttributes: false,
+  format: true
+});
+
+function createEmptySitemapDocument() {
+  return {
+    "?xml": {
+      "@_version": "1.0",
+      "@_encoding": "UTF-8"
+    },
+    urlset: {
+      "@_xmlns": SITEMAP_XML_NAMESPACE,
+      url: []
+    }
+  };
+}
+
+async function bodyToUtf8(body) {
+  if (typeof body?.transformToString === "function") {
+    return body.transformToString("utf8");
+  }
+
+  if (Buffer.isBuffer(body)) {
+    return body.toString("utf8");
+  }
+
+  if (body instanceof Uint8Array) {
+    return Buffer.from(body).toString("utf8");
+  }
+
+  return String(body ?? "");
+}
+
+export function normalizeSitemapDocument(document) {
+  const candidate = document?.urlset ? document : createEmptySitemapDocument();
+  const urls = candidate?.urlset?.url;
+
+  return {
+    "?xml": {
+      "@_version": candidate?.["?xml"]?.["@_version"] ?? "1.0",
+      "@_encoding": candidate?.["?xml"]?.["@_encoding"] ?? "UTF-8"
+    },
+    urlset: {
+      "@_xmlns": candidate?.urlset?.["@_xmlns"] ?? SITEMAP_XML_NAMESPACE,
+      url: Array.isArray(urls)
+        ? urls.filter((entry) => entry?.loc)
+        : (urls?.loc ? [urls] : [])
+    }
+  };
+}
+
+async function loadCurrentSitemap(s3, bucketName) {
+  try {
+    const response = await s3.getObject({
+      Bucket: bucketName,
+      Key: "sitemap.xml"
+    }).promise();
+    return normalizeSitemapDocument(parser.parse(await bodyToUtf8(response.Body)));
+  } catch (error) {
+    const errorCode = error?.name ?? error?.Code ?? error?.code;
+    if (errorCode === "NoSuchKey" || errorCode === "NoSuchBucket" || errorCode === "NotFound") {
+      return createEmptySitemapDocument();
+    }
+    throw error;
+  }
+}
+
+export function findLanguageTargetByBucket(environmentManifest, bucketName) {
+  for (const [variantName, variantConfig] of Object.entries(environmentManifest.variants ?? {})) {
+    for (const [languageCode, languageConfig] of Object.entries(variantConfig.languages ?? {})) {
+      if (languageConfig.targetBucket === bucketName) {
+        return {
+          variantName,
+          variantConfig,
+          languageCode,
+          languageConfig
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+function encodePathSegments(key) {
+  return String(key)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function buildSitemapUrl({ baseUrl, key, indexDocument, notFoundDocument }) {
+  const normalizedKey = String(key ?? "").replace(/^\/+/, "");
+  if (!normalizedKey || normalizedKey === "sitemap.xml" || normalizedKey === notFoundDocument) {
+    return null;
+  }
+
+  const normalizedBaseUrl = String(baseUrl ?? "").replace(/^https?:\/\//i, "").replace(/\/+$/, "");
+  if (!normalizedBaseUrl) {
+    return null;
+  }
+
+  if (normalizedKey === indexDocument) {
+    return `https://${normalizedBaseUrl}/`;
+  }
+
+  if (normalizedKey.endsWith(`/${indexDocument}`)) {
+    const directoryKey = normalizedKey.slice(0, -(indexDocument.length + 1));
+    const encodedDirectory = encodePathSegments(directoryKey);
+    return `https://${normalizedBaseUrl}/${encodedDirectory}/`;
+  }
+
+  return `https://${normalizedBaseUrl}/${encodePathSegments(normalizedKey)}`;
+}
+
+export function applySitemapRecords(sitemapDocument, sitemapRecords = []) {
+  const normalizedDocument = normalizeSitemapDocument(sitemapDocument);
+  const entries = new Map((normalizedDocument.urlset.url ?? []).map((entry) => [entry.loc, {
+    loc: entry.loc,
+    lastmod: entry.lastmod
+  }]));
+
+  for (const record of sitemapRecords) {
+    if (!record?.loc) {
+      continue;
+    }
+
+    const lastmod = String(record.lastmod ?? new Date().toISOString()).slice(0, 10);
+    if (record.action === "delete") {
+      entries.delete(record.loc);
+      continue;
+    }
+
+    entries.set(record.loc, {
+      loc: record.loc,
+      lastmod
+    });
+  }
+
+  normalizedDocument.urlset.url = [...entries.values()].sort((left, right) => left.loc.localeCompare(right.loc));
+  return normalizedDocument;
+}
+
+export async function handler(event) {
+  const environmentName = process.env.S3TE_ENVIRONMENT;
+  const runtimeParameter = process.env.S3TE_RUNTIME_PARAMETER;
+
+  const clients = createAwsClients();
+  const { environment: environmentManifest } = await loadEnvironmentManifest(
+    clients.ssm,
+    runtimeParameter,
+    environmentName
+  );
+
+  const updatesByBucket = new Map();
+
+  for (const record of event.Records ?? []) {
+    const bucketName = record.s3?.bucket?.name;
+    const key = decodeS3Key(record.s3?.object?.key ?? "");
+    const target = findLanguageTargetByBucket(environmentManifest, bucketName);
+    if (!bucketName || !key || !target) {
+      continue;
+    }
+
+    const loc = buildSitemapUrl({
+      baseUrl: target.languageConfig.baseUrl,
+      key,
+      indexDocument: target.variantConfig.routing.indexDocument,
+      notFoundDocument: target.variantConfig.routing.notFoundDocument
+    });
+    if (!loc) {
+      continue;
+    }
+
+    if (!updatesByBucket.has(bucketName)) {
+      updatesByBucket.set(bucketName, []);
+    }
+    updatesByBucket.get(bucketName).push({
+      action: String(record.eventName).startsWith("ObjectRemoved:") ? "delete" : "upsert",
+      loc,
+      lastmod: record.eventTime
+    });
+  }
+
+  let updatedBuckets = 0;
+
+  for (const [bucketName, updates] of updatesByBucket.entries()) {
+    const sitemapDocument = applySitemapRecords(
+      await loadCurrentSitemap(clients.s3, bucketName),
+      updates
+    );
+
+    await clients.s3.putObject({
+      Bucket: bucketName,
+      Key: "sitemap.xml",
+      Body: builder.build(sitemapDocument),
+      ContentType: "application/xml; charset=utf-8"
+    }).promise();
+
+    updatedBuckets += 1;
+  }
+
+  return {
+    updatedBuckets
+  };
+}

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

@@ -35,6 +35,26 @@ function lambdaCode(keyParameter) {
   };
 }
 
+function buildSitemapNotificationConfigurations(functionLogicalId) {
+  const suffixes = [".html", ".htm"];
+  const events = ["s3:ObjectCreated:*", "s3:ObjectRemoved:*"];
+
+  return events.flatMap((eventName) => suffixes.map((suffix) => ({
+    Event: eventName,
+    Function: { "Fn::GetAtt": [functionLogicalId, "Arn"] },
+    Filter: {
+      S3Key: {
+        Rules: [
+          {
+            Name: "suffix",
+            Value: suffix
+          }
+        ]
+      }
+    }
+  })));
+}
+
 function lambdaRuntimeProperties(runtimeConfig, roleRef, name, keyParameter, handlerName, extra = {}) {
   return {
     Type: "AWS::Lambda::Function",
@@ -117,7 +137,8 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     renderWorker: `${runtimeConfig.stackPrefix}_s3te_render_worker`,
     invalidationScheduler: `${runtimeConfig.stackPrefix}_s3te_invalidation_scheduler`,
     invalidationExecutor: `${runtimeConfig.stackPrefix}_s3te_invalidation_executor`,
-    contentMirror: `${runtimeConfig.stackPrefix}_s3te_content_mirror`
+    contentMirror: `${runtimeConfig.stackPrefix}_s3te_content_mirror`,
+    sitemapUpdater: `${runtimeConfig.stackPrefix}_s3te_sitemap_updater`
   };
 
   const parameters = {
@@ -140,6 +161,10 @@ export function buildCloudFormationTemplate({ config, environment, features = []
       Type: "String",
       Default: ""
     },
+    SitemapUpdaterArtifactKey: {
+      Type: "String",
+      Default: ""
+    },
     RuntimeManifestValue: {
       Type: "String",
       Default: "{}"
@@ -369,6 +394,26 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     };
   }
 
+  if (featureSet.has("sitemap") && runtimeConfig.integrations.sitemap.enabled) {
+    resources.SitemapUpdater = lambdaRuntimeProperties(
+      runtimeConfig,
+      "ExecutionRole",
+      functionNames.sitemapUpdater,
+      "SitemapUpdaterArtifactKey",
+      "sitemap-updater",
+      {
+        Timeout: 300,
+        MemorySize: 512,
+        Environment: {
+          Variables: {
+            S3TE_ENVIRONMENT: environment,
+            S3TE_RUNTIME_PARAMETER: runtimeConfig.runtimeParameterName
+          }
+        }
+      }
+    );
+  }
+
   outputs.StackName = { Value: runtimeConfig.stackName };
   outputs.RuntimeManifestParameterName = {
     Value: runtimeConfig.runtimeParameterName
@@ -384,6 +429,9 @@ export function buildCloudFormationTemplate({ config, environment, features = []
   if (resources.ContentMirror) {
     outputs.ContentMirrorFunctionName = { Value: functionNames.contentMirror };
   }
+  if (resources.SitemapUpdater) {
+    outputs.SitemapUpdaterFunctionName = { Value: functionNames.sitemapUpdater };
+  }
 
   for (const [variantName, variantConfig] of Object.entries(runtimeConfig.variants)) {
     const codeBucketLogicalId = cfName(sanitizeLogicalId(variantName), "CodeBucket");
@@ -417,12 +465,20 @@ export function buildCloudFormationTemplate({ config, environment, features = []
 
       resources[outputBucketLogicalId] = {
         Type: "AWS::S3::Bucket",
+        ...(resources.SitemapUpdater ? { DependsOn: ["SitemapUpdaterPermission"] } : {}),
         Properties: {
           BucketName: languageConfig.targetBucket,
           WebsiteConfiguration: {
             IndexDocument: variantConfig.routing.indexDocument,
             ErrorDocument: variantConfig.routing.notFoundDocument
           },
+          ...(resources.SitemapUpdater
+            ? {
+                NotificationConfiguration: {
+                  LambdaConfigurations: buildSitemapNotificationConfigurations("SitemapUpdater")
+                }
+              }
+            : {}),
           PublicAccessBlockConfiguration: {
             BlockPublicAcls: false,
             BlockPublicPolicy: false,
@@ -544,6 +600,17 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     }
   };
 
+  if (resources.SitemapUpdater) {
+    resources.SitemapUpdaterPermission = {
+      Type: "AWS::Lambda::Permission",
+      Properties: {
+        Action: "lambda:InvokeFunction",
+        FunctionName: { Ref: "SitemapUpdater" },
+        Principal: "s3.amazonaws.com"
+      }
+    };
+  }
+
   return {
     AWSTemplateFormatVersion: "2010-09-09",
     Description: `S3TE environment stack for ${config.project.name} (${environment})`,

package/packages/cli/bin/s3te.mjs

@@ -385,6 +385,8 @@ async function main() {
       environment: asArray(options.env)[0],
       enableWebiny: Boolean(options["enable-webiny"]),
       disableWebiny: Boolean(options["disable-webiny"]),
+      enableSitemap: Boolean(options["enable-sitemap"]),
+      disableSitemap: Boolean(options["disable-sitemap"]),
       webinySourceTable: options["webiny-source-table"],
       webinyTenant: options["webiny-tenant"],
       webinyModels: asArray(options["webiny-model"])

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;
@@ -242,6 +335,23 @@ function schemaTemplate() {
                 }
               }
             }
+          },
+          sitemap: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              enabled: { type: "boolean" },
+              environments: {
+                type: "object",
+                additionalProperties: {
+                  type: "object",
+                  additionalProperties: false,
+                  properties: {
+                    enabled: { type: "boolean" }
+                  }
+                }
+              }
+            }
           }
         }
       }
@@ -736,8 +846,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"
     });
@@ -787,6 +901,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]);
 
@@ -811,7 +928,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 });
@@ -828,7 +945,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
@@ -837,6 +954,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;
@@ -854,6 +1003,8 @@ export async function migrateProject(configPath, rawConfig, writeChanges) {
 
   const enableWebiny = Boolean(options.enableWebiny);
   const disableWebiny = Boolean(options.disableWebiny);
+  const enableSitemap = Boolean(options.enableSitemap);
+  const disableSitemap = Boolean(options.disableSitemap);
   const targetEnvironment = options.environment ? String(options.environment).trim() : "";
   const webinySourceTable = options.webinySourceTable ? String(options.webinySourceTable).trim() : "";
   const webinyTenant = options.webinyTenant ? String(options.webinyTenant).trim() : "";
@@ -862,6 +1013,9 @@ export async function migrateProject(configPath, rawConfig, writeChanges) {
   if (enableWebiny && disableWebiny) {
     throw new S3teError("CONFIG_CONFLICT_ERROR", "migrate does not allow --enable-webiny and --disable-webiny at the same time.");
   }
+  if (enableSitemap && disableSitemap) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", "migrate does not allow --enable-sitemap and --disable-sitemap at the same time.");
+  }
 
   const touchesWebiny = enableWebiny || disableWebiny || Boolean(webinySourceTable) || Boolean(webinyTenant) || webinyModels.length > 0;
   if (touchesWebiny) {
@@ -944,6 +1098,48 @@ export async function migrateProject(configPath, rawConfig, writeChanges) {
     }
   }
 
+  const touchesSitemap = enableSitemap || disableSitemap;
+  if (touchesSitemap) {
+    if (targetEnvironment && !nextConfig.environments?.[targetEnvironment]) {
+      throw new S3teError("CONFIG_CONFLICT_ERROR", `Unknown environment for migrate: ${targetEnvironment}.`);
+    }
+
+    const existingIntegrations = nextConfig.integrations ?? {};
+    const existingSitemap = existingIntegrations.sitemap ?? {};
+    const existingEnvironmentOverrides = existingSitemap.environments ?? {};
+    const existingTargetSitemap = targetEnvironment
+      ? (existingEnvironmentOverrides[targetEnvironment] ?? {})
+      : existingSitemap;
+    const nextEnabled = disableSitemap
+      ? false
+      : (enableSitemap || Boolean(targetEnvironment
+          ? (existingTargetSitemap.enabled ?? existingSitemap.enabled)
+          : existingSitemap.enabled));
+
+    nextConfig.integrations = {
+      ...existingIntegrations,
+      sitemap: targetEnvironment
+        ? {
+            ...existingSitemap,
+            environments: {
+              ...existingEnvironmentOverrides,
+              [targetEnvironment]: {
+                ...existingTargetSitemap,
+                enabled: nextEnabled
+              }
+            }
+          }
+        : {
+            ...existingSitemap,
+            enabled: nextEnabled,
+            environments: existingEnvironmentOverrides
+          }
+    };
+
+    const scopeLabel = targetEnvironment ? ` for environment ${targetEnvironment}` : "";
+    changes.push(nextEnabled ? `Enabled sitemap integration${scopeLabel}.` : `Disabled sitemap integration${scopeLabel}.`);
+  }
+
   if (options.writeChanges) {
     await writeTextFile(configPath, JSON.stringify(nextConfig, null, 2) + "\n");
   }

package/packages/core/src/config.mjs

@@ -75,12 +75,27 @@ function environmentHostPrefix(config, environmentName) {
 }
 
 function prefixHostForEnvironment(config, host, environmentName) {
-  const prefix = environmentHostPrefix(config, environmentName);
-  if (!prefix) {
+  if (!hasProductionEnvironment(config) || isProductionEnvironment(environmentName)) {
     return host;
   }
 
-  return host.startsWith(prefix) ? host : `${prefix}${host}`;
+  const normalizedHost = String(host).trim();
+  if (!normalizedHost) {
+    return normalizedHost;
+  }
+
+  if (normalizedHost.startsWith(`${environmentName}.`) || normalizedHost.startsWith(`${environmentName}-`)) {
+    return normalizedHost;
+  }
+
+  const labels = normalizedHost.split(".");
+  if (labels.length <= 2) {
+    const prefix = environmentHostPrefix(config, environmentName);
+    return `${prefix}${normalizedHost}`;
+  }
+
+  const [firstLabel, ...remainingLabels] = labels;
+  return `${environmentName}-${firstLabel}.${remainingLabels.join(".")}`;
 }
 
 function isValidConfiguredHost(value) {
@@ -143,6 +158,12 @@ function resolveWebinyConfigDefaults(webinyConfig = {}) {
   };
 }
 
+function resolveSitemapConfigDefaults(sitemapConfig = {}) {
+  return {
+    enabled: sitemapConfig.enabled ?? false
+  };
+}
+
 function resolveProjectWebinyConfig(projectConfig) {
   const baseConfig = resolveWebinyConfigDefaults(projectConfig.integrations?.webiny ?? {});
   const environmentConfigs = Object.fromEntries(Object.entries(projectConfig.integrations?.webiny?.environments ?? {}).map(([environmentName, webinyConfig]) => ([
@@ -162,6 +183,21 @@ function resolveProjectWebinyConfig(projectConfig) {
   };
 }
 
+function resolveProjectSitemapConfig(projectConfig) {
+  const baseConfig = resolveSitemapConfigDefaults(projectConfig.integrations?.sitemap ?? {});
+  const environmentConfigs = Object.fromEntries(Object.entries(projectConfig.integrations?.sitemap?.environments ?? {}).map(([environmentName, sitemapConfig]) => ([
+    environmentName,
+    {
+      enabled: sitemapConfig.enabled
+    }
+  ])));
+
+  return {
+    ...baseConfig,
+    environments: environmentConfigs
+  };
+}
+
 export async function loadProjectConfig(configPath) {
   const raw = await fs.readFile(configPath, "utf8");
   try {
@@ -247,7 +283,8 @@ export function resolveProjectConfig(projectConfig) {
   };
 
   const integrations = {
-    webiny: resolveProjectWebinyConfig(projectConfig)
+    webiny: resolveProjectWebinyConfig(projectConfig),
+    sitemap: resolveProjectSitemapConfig(projectConfig)
   };
 
   for (const [variantName, variantConfig] of Object.entries(variants)) {
@@ -317,6 +354,15 @@ export function resolveEnvironmentWebinyIntegration(config, environmentName) {
   };
 }
 
+export function resolveEnvironmentSitemapIntegration(config, environmentName) {
+  const baseConfig = resolveSitemapConfigDefaults(config.integrations?.sitemap ?? {});
+  const environmentOverride = config.integrations?.sitemap?.environments?.[environmentName] ?? {};
+
+  return {
+    enabled: environmentOverride.enabled ?? baseConfig.enabled
+  };
+}
+
 export function resolveTableNames(config, environmentName) {
   const context = createPlaceholderContext(config, environmentName);
   const webinyConfig = resolveEnvironmentWebinyIntegration(config, environmentName);
@@ -340,6 +386,7 @@ export function resolveStackName(config, environmentName) {
 export function buildEnvironmentRuntimeConfig(config, environmentName, stackOutputs = {}) {
   const environmentConfig = config.environments[environmentName];
   const webinyConfig = resolveEnvironmentWebinyIntegration(config, environmentName);
+  const sitemapConfig = resolveEnvironmentSitemapIntegration(config, environmentName);
   const tables = resolveTableNames(config, environmentName);
   const runtimeParameterName = resolveRuntimeManifestParameterName(config, environmentName);
   const stackName = resolveStackName(config, environmentName);
@@ -388,6 +435,9 @@ export function buildEnvironmentRuntimeConfig(config, environmentName, stackOutp
       webiny: {
         ...webinyConfig,
         mirrorTableName: tables.webinyMirror
+      },
+      sitemap: {
+        ...sitemapConfig
       }
     },
     variants
@@ -502,6 +552,7 @@ export async function validateAndResolveProjectConfig(projectConfig, options = {
   }
 
   const configuredWebiny = projectConfig.integrations?.webiny;
+  const configuredSitemap = projectConfig.integrations?.sitemap;
   for (const [environmentName] of environmentEntries) {
     const environmentWebinyConfig = resolveEnvironmentWebinyIntegration(resolveProjectConfig({
       ...projectConfig,
@@ -524,6 +575,15 @@ export async function validateAndResolveProjectConfig(projectConfig, options = {
     }
   }
 
+  for (const environmentName of Object.keys(configuredSitemap?.environments ?? {})) {
+    if (!projectConfig.environments?.[environmentName]) {
+      errors.push({
+        code: "CONFIG_CONFLICT_ERROR",
+        message: `integrations.sitemap.environments.${environmentName} does not match a configured environment.`
+      });
+    }
+  }
+
   for (const [variantName, pattern] of Object.entries(projectConfig.aws?.codeBuckets ?? {})) {
     ensureKnownPlaceholders(pattern, `aws.codeBuckets.${variantName}`, errors);
   }

package/packages/core/src/index.mjs

@@ -7,6 +7,7 @@ export {
   resolveBaseUrl,
   resolveCodeBucketName,
   resolveCloudFrontAliases,
+  resolveEnvironmentSitemapIntegration,
   resolveEnvironmentWebinyIntegration,
   resolveRuntimeManifestParameterName,
   resolveProjectConfig,