@projectdochelp/s3te 3.2.3 → 3.3.0

package/README.md

@@ -66,7 +66,7 @@ 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.
+If optional runtime features are enabled in `s3te.config.json`, S3TE extends the deployed AWS runtime accordingly. `sitemap` is added to the main environment stack. Webiny is deployed as a separate option stack so retrofitting CMS support does not require CloudFront resources to move with it.
 
 </details>
 
@@ -484,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 optional features such as `sitemap` or Webiny into an existing S3TE project. |
+| `s3te option <webiny|sitemap>` | Writes or updates optional feature configuration such as Webiny or sitemap support in an existing S3TE project. |
 
 </details>
 
@@ -929,11 +929,11 @@ Add this block to `s3te.config.json`:
 
 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:
+If you prefer the CLI path, this does the same option update:
 
 ```bash
-npx s3te migrate --enable-sitemap --write
-npx s3te migrate --env test --enable-sitemap --write
+npx s3te option sitemap --enable --write
+npx s3te option sitemap --env test --enable --write
 ```
 
 After enabling or disabling `sitemap`, redeploy the affected environment once:
@@ -989,23 +989,23 @@ This section assumes that S3TE is already installed and deployed. The S3TE-speci
 3. Manually enable DynamoDB Streams on that Webiny table before the first S3TE deploy with Webiny enabled.
    Use `NEW_AND_OLD_IMAGES`.
    Without that stream, `s3te deploy --env <name>` cannot wire the Webiny trigger and fails because the table has no `LatestStreamArn`.
-4. Upgrade your existing S3TE config for Webiny:
+4. Write the Webiny option into your existing S3TE config:
 
 ```bash
-npx s3te migrate --enable-webiny --webiny-source-table webiny-1234567 --webiny-tenant root --webiny-model article --write
+npx s3te option webiny --enable --source-table webiny-1234567 --tenant root --model article --write
 ```
 
-`staticContent` and `staticCodeContent` are kept automatically. Add `--webiny-model` once per custom model you want S3TE to mirror.
+`staticContent` and `staticCodeContent` are kept automatically. Add `--model` once per custom model you want S3TE to mirror.
 
-`--webiny-model article` means:
+`--model article` means:
 
 - `article` is the technical Webiny model ID, not the human-readable label shown in the CMS UI.
 - S3TE adds that model ID to `integrations.webiny.relevantModels` in `s3te.config.json`.
 - Only Webiny stream records whose model is listed in `relevantModels` are mirrored into the S3TE content table and can trigger rerendering.
-- If you omit `--webiny-model`, only the built-in defaults `staticContent` and `staticCodeContent` are mirrored.
-- You can pass the flag multiple times for multiple models, for example `--webiny-model article --webiny-model news --webiny-model event`.
+- If you omit `--model`, only the built-in defaults `staticContent` and `staticCodeContent` are mirrored.
+- You can pass the flag multiple times for multiple models, for example `--model article --model news --model event`.
 
-That makes the migration example above equivalent to a config that contains:
+That makes the option example above equivalent to a config that contains:
 
 ```json
 "relevantModels": ["article", "staticContent", "staticCodeContent"]
@@ -1013,11 +1013,11 @@ That makes the migration example above equivalent to a config that contains:
 
 Use this for every Webiny model whose entries should be available to S3TE template commands like `dbitem`, `dbmulti`, `dbmultifile`, `dbmultifileitem`, or `dbpart`.
 
-If different environments should read from different Webiny installations or tenants, run the migration per environment:
+If different environments should read from different Webiny installations or tenants, run the option command per environment:
 
 ```bash
-npx s3te migrate --env test --enable-webiny --webiny-source-table webiny-test-1234567 --webiny-tenant preview --write
-npx s3te migrate --env prod --enable-webiny --webiny-source-table webiny-live-1234567 --webiny-tenant root --write
+npx s3te option webiny --env test --enable --source-table webiny-test-1234567 --tenant preview --write
+npx s3te option webiny --env prod --enable --source-table webiny-live-1234567 --tenant root --write
 ```
 
 5. Verify again that DynamoDB Streams are enabled on the Webiny source table with `NEW_AND_OLD_IMAGES`.
@@ -1037,19 +1037,19 @@ npx s3te doctor --env prod
 npx s3te deploy --env prod
 ```
 
-That deploy updates the existing environment stack and adds the Webiny mirror resources to it. You do not need a fresh S3TE installation. After that, Webiny content changes flow through the deployed AWS resources automatically; only template or asset changes still need `s3te sync --env <name>`.
+That deploy updates the existing environment stack and, when Webiny is enabled, also deploys the separate Webiny option stack for `content-mirror` and its DynamoDB stream mapping. You do not need a fresh S3TE installation. After that, Webiny content changes flow through the deployed AWS resources automatically; only template or asset changes still need `s3te sync --env <name>`.
 
 Manual versus automatic responsibilities in this step:
 
 - Manual: enable DynamoDB Streams on the Webiny source table
-- Automatic during `s3te deploy`: read `LatestStreamArn`, create the Lambda event source mapping, and wire the S3TE Webiny mirror Lambda into the environment stack
+- Automatic during `s3te deploy`: read `LatestStreamArn`, create the Lambda event source mapping, and deploy the S3TE Webiny mirror Lambda in the separate Webiny option stack
 
 </details>
 
 <details>
-  <summary>What the migration command changes</summary>
+  <summary>What the option command changes</summary>
 
-The migration command writes or updates the `integrations.webiny` block in `s3te.config.json`. A typical result looks like this:
+The option command writes or updates the `integrations.webiny` block in `s3te.config.json`. A typical result looks like this:
 
 Example config block:
 

package/package.json

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

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

@@ -3,6 +3,7 @@ import path from "node:path";
 
 import {
   buildEnvironmentRuntimeConfig,
+  resolveOptionStackName,
   resolveStackName,
   S3teError
 } from "../../core/src/index.mjs";
@@ -34,6 +35,15 @@ function temporaryStackName(stackName) {
   return `${stackName}-deploy-temp`;
 }
 
+function stackDoesNotExist(error) {
+  const detailsText = [
+    error?.message,
+    error?.details?.stderr,
+    error?.details?.stdout
+  ].filter(Boolean).join("\n");
+  return /does not exist/i.test(detailsText) || /Stack with id .* does not exist/i.test(detailsText);
+}
+
 async function uploadArtifact({ bucketName, key, bodyPath, region, profile, cwd }) {
   await runAwsCli(["s3api", "put-object", "--bucket", bucketName, "--key", key, "--body", bodyPath], {
     region,
@@ -53,6 +63,18 @@ async function describeStack({ stackName, region, profile, cwd }) {
   return JSON.parse(describedStack.stdout).Stacks?.[0];
 }
 
+async function stackExists({ stackName, region, profile, cwd }) {
+  try {
+    await describeStack({ stackName, region, profile, cwd });
+    return true;
+  } catch (error) {
+    if (stackDoesNotExist(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
 async function describeStackEvents({ stackName, region, profile, cwd }) {
   const describedEvents = await runAwsCli(["cloudformation", "describe-stack-events", "--stack-name", stackName, "--output", "json"], {
     region,
@@ -331,11 +353,37 @@ async function cleanupTemporaryArtifactsStack({
   });
 }
 
+async function deleteCloudFormationStackIfExists({
+  stackName,
+  region,
+  profile,
+  cwd
+}) {
+  if (!(await stackExists({ stackName, region, profile, cwd }))) {
+    return false;
+  }
+
+  await runAwsCli(["cloudformation", "delete-stack", "--stack-name", stackName], {
+    region,
+    profile,
+    cwd,
+    errorCode: "ADAPTER_ERROR"
+  });
+
+  await runAwsCli(["cloudformation", "wait", "stack-delete-complete", "--stack-name", stackName], {
+    region,
+    profile,
+    cwd,
+    errorCode: "ADAPTER_ERROR"
+  });
+
+  return true;
+}
+
 function buildEnvironmentStackParameters({
   artifactBucket,
   uploadedArtifacts,
-  runtimeManifestValue,
-  webinyStreamArn = ""
+  runtimeManifestValue
 }) {
   return [
     `ArtifactBucket=${artifactBucket}`,
@@ -343,9 +391,19 @@ function buildEnvironmentStackParameters({
     `RenderWorkerArtifactKey=${uploadedArtifacts.renderWorker}`,
     `InvalidationSchedulerArtifactKey=${uploadedArtifacts.invalidationScheduler}`,
     `InvalidationExecutorArtifactKey=${uploadedArtifacts.invalidationExecutor}`,
-    `ContentMirrorArtifactKey=${uploadedArtifacts.contentMirror}`,
     `SitemapUpdaterArtifactKey=${uploadedArtifacts.sitemapUpdater}`,
-    `RuntimeManifestValue=${runtimeManifestValue}`,
+    `RuntimeManifestValue=${runtimeManifestValue}`
+  ];
+}
+
+function buildWebinyStackParameters({
+  artifactBucket,
+  uploadedArtifacts,
+  webinyStreamArn
+}) {
+  return [
+    `ArtifactBucket=${artifactBucket}`,
+    `ContentMirrorArtifactKey=${uploadedArtifacts.contentMirror}`,
     `WebinySourceTableStreamArn=${webinyStreamArn}`
   ];
 }
@@ -365,6 +423,7 @@ export async function deployAwsProject({
   const requestedFeatureSet = new Set(features);
   const featureSet = new Set(resolveRequestedFeatures(config, features, environment));
   const stackName = resolveStackName(config, environment);
+  const webinyStackName = resolveOptionStackName(config, environment, "webiny");
   const tempStackName = temporaryStackName(stackName);
   const runtimeManifestPath = path.join(projectDir, packageDir ?? path.join("offline", "IAAS", "package", environment), "runtime-manifest.json");
 
@@ -439,16 +498,36 @@ export async function deployAwsProject({
       parameterOverrides: buildEnvironmentStackParameters({
         artifactBucket: tempStack.artifactBucket,
         uploadedArtifacts,
-        runtimeManifestValue: "{}",
-        webinyStreamArn
+        runtimeManifestValue: "{}"
       }),
       noExecute: plan,
       stdio
     });
 
     if (plan) {
+      if (featureSet.has("webiny")) {
+        if (!packaged.manifest.webinyCloudFormationTemplate) {
+          throw new S3teError("ADAPTER_ERROR", "Package manifest is missing the Webiny option template.");
+        }
+        await deployCloudFormationStack({
+          stackName: webinyStackName,
+          templatePath: path.join(projectDir, packaged.manifest.webinyCloudFormationTemplate),
+          region: runtimeConfig.awsRegion,
+          profile,
+          cwd: projectDir,
+          capabilities: ["CAPABILITY_NAMED_IAM"],
+          parameterOverrides: buildWebinyStackParameters({
+            artifactBucket: tempStack.artifactBucket,
+            uploadedArtifacts,
+            webinyStreamArn
+          }),
+          noExecute: true,
+          stdio
+        });
+      }
       return {
         stackName,
+        optionalStacks: featureSet.has("webiny") ? [webinyStackName] : [],
         packageDir: packaged.manifest.packageDir,
         runtimeManifestPath: normalizeRelative(projectDir, runtimeManifestPath),
         syncedCodeBuckets: [],
@@ -482,12 +561,41 @@ export async function deployAwsProject({
       parameterOverrides: buildEnvironmentStackParameters({
         artifactBucket: tempStack.artifactBucket,
         uploadedArtifacts,
-        runtimeManifestValue: JSON.stringify(runtimeManifest),
-        webinyStreamArn
+        runtimeManifestValue: JSON.stringify(runtimeManifest)
       }),
       stdio
     });
 
+    let deployedOptionalStacks = [];
+    let removedOptionalStacks = [];
+    if (featureSet.has("webiny")) {
+      if (!packaged.manifest.webinyCloudFormationTemplate) {
+        throw new S3teError("ADAPTER_ERROR", "Package manifest is missing the Webiny option template.");
+      }
+      await deployCloudFormationStack({
+        stackName: webinyStackName,
+        templatePath: path.join(projectDir, packaged.manifest.webinyCloudFormationTemplate),
+        region: runtimeConfig.awsRegion,
+        profile,
+        cwd: projectDir,
+        capabilities: ["CAPABILITY_NAMED_IAM"],
+        parameterOverrides: buildWebinyStackParameters({
+          artifactBucket: tempStack.artifactBucket,
+          uploadedArtifacts,
+          webinyStreamArn
+        }),
+        stdio
+      });
+      deployedOptionalStacks = [webinyStackName];
+    } else if (await deleteCloudFormationStackIfExists({
+      stackName: webinyStackName,
+      region: runtimeConfig.awsRegion,
+      profile,
+      cwd: projectDir
+    })) {
+      removedOptionalStacks = [webinyStackName];
+    }
+
     const syncedCodeBuckets = noSync
       ? []
       : (await syncPreparedSources({
@@ -511,6 +619,8 @@ export async function deployAwsProject({
 
     return {
       stackName,
+      optionalStacks: deployedOptionalStacks,
+      removedOptionalStacks,
       packageDir: packaged.manifest.packageDir,
       runtimeManifestPath: normalizeRelative(projectDir, runtimeManifestPath),
       syncedCodeBuckets,

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

@@ -1,5 +1,5 @@
 export { writeZipArchive } from "./zip.mjs";
-export { buildCloudFormationTemplate, buildTemporaryDeployStackTemplate } from "./template.mjs";
+export { buildCloudFormationTemplate, buildTemporaryDeployStackTemplate, buildWebinyCloudFormationTemplate } from "./template.mjs";
 export { buildAwsRuntimeManifest, extractStackOutputsMap } from "./manifest.mjs";
 export { ensureAwsCliAvailable, ensureAwsCredentials, runAwsCli } from "./aws-cli.mjs";
 export { getConfiguredFeatures, resolveRequestedFeatures } from "./features.mjs";

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

@@ -11,7 +11,7 @@ import {
 
 import { buildAwsRuntimeManifest } from "./manifest.mjs";
 import { resolveRequestedFeatures } from "./features.mjs";
-import { buildCloudFormationTemplate } from "./template.mjs";
+import { buildCloudFormationTemplate, buildWebinyCloudFormationTemplate } from "./template.mjs";
 import { writeZipArchive } from "./zip.mjs";
 
 const ZIP_DATE = new Date("2020-01-01T00:00:00.000Z");
@@ -242,6 +242,7 @@ export async function packageAwsProject({
 
   const lambdaDir = path.join(packageDir, "lambda");
   const templatePath = path.join(packageDir, "cloudformation.template.json");
+  const webinyTemplatePath = path.join(packageDir, "cloudformation.webiny.template.json");
   const packagingManifestPath = path.join(packageDir, "manifest.json");
   const runtimeManifestSeedPath = path.join(packageDir, "runtime-manifest.base.json");
   const lambdaEntries = await collectLambdaArchiveEntries();
@@ -292,6 +293,9 @@ export async function packageAwsProject({
   const runtimeManifestSeed = buildAwsRuntimeManifest({ config, environment });
 
   await writeJsonFile(templatePath, template);
+  if (resolvedFeatures.includes("webiny") && runtimeConfig.integrations.webiny.enabled) {
+    await writeJsonFile(webinyTemplatePath, buildWebinyCloudFormationTemplate({ config, environment }));
+  }
   await writeJsonFile(runtimeManifestSeedPath, runtimeManifestSeed);
 
   const manifest = {
@@ -302,6 +306,9 @@ export async function packageAwsProject({
     runtimeParameterName: runtimeConfig.runtimeParameterName,
     packageDir: normalizeRelative(projectDir, packageDir),
     cloudFormationTemplate: normalizeRelative(projectDir, templatePath),
+    ...(resolvedFeatures.includes("webiny") && runtimeConfig.integrations.webiny.enabled
+      ? { webinyCloudFormationTemplate: normalizeRelative(projectDir, webinyTemplatePath) }
+      : {}),
     runtimeManifestSeed: normalizeRelative(projectDir, runtimeManifestSeedPath),
     lambdaArtifacts: Object.fromEntries(Object.entries(lambdaArtifacts).map(([name, artifact]) => [
       name,

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

@@ -70,6 +70,17 @@ function lambdaRuntimeProperties(runtimeConfig, roleRef, name, keyParameter, han
   };
 }
 
+function buildFunctionNames(runtimeConfig) {
+  return {
+    sourceDispatcher: `${runtimeConfig.stackPrefix}_s3te_source_dispatcher`,
+    renderWorker: `${runtimeConfig.stackPrefix}_s3te_render_worker`,
+    invalidationScheduler: `${runtimeConfig.stackPrefix}_s3te_invalidation_scheduler`,
+    invalidationExecutor: `${runtimeConfig.stackPrefix}_s3te_invalidation_executor`,
+    contentMirror: `${runtimeConfig.stackPrefix}_s3te_content_mirror`,
+    sitemapUpdater: `${runtimeConfig.stackPrefix}_s3te_sitemap_updater`
+  };
+}
+
 function createExecutionRole(roleName) {
   return {
     Type: "AWS::IAM::Role",
@@ -132,14 +143,7 @@ export function buildCloudFormationTemplate({ config, environment, features = []
   const outputs = {};
   const featureSet = new Set(features);
 
-  const functionNames = {
-    sourceDispatcher: `${runtimeConfig.stackPrefix}_s3te_source_dispatcher`,
-    renderWorker: `${runtimeConfig.stackPrefix}_s3te_render_worker`,
-    invalidationScheduler: `${runtimeConfig.stackPrefix}_s3te_invalidation_scheduler`,
-    invalidationExecutor: `${runtimeConfig.stackPrefix}_s3te_invalidation_executor`,
-    contentMirror: `${runtimeConfig.stackPrefix}_s3te_content_mirror`,
-    sitemapUpdater: `${runtimeConfig.stackPrefix}_s3te_sitemap_updater`
-  };
+  const functionNames = buildFunctionNames(runtimeConfig);
 
   const parameters = {
     ArtifactBucket: {
@@ -157,10 +161,6 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     InvalidationExecutorArtifactKey: {
       Type: "String"
     },
-    ContentMirrorArtifactKey: {
-      Type: "String",
-      Default: ""
-    },
     SitemapUpdaterArtifactKey: {
       Type: "String",
       Default: ""
@@ -168,10 +168,6 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     RuntimeManifestValue: {
       Type: "String",
       Default: "{}"
-    },
-    WebinySourceTableStreamArn: {
-      Type: "String",
-      Default: ""
     }
   };
 
@@ -361,39 +357,6 @@ export function buildCloudFormationTemplate({ config, environment, features = []
     }
   );
 
-  if (featureSet.has("webiny") && runtimeConfig.integrations.webiny.enabled) {
-    resources.ContentMirror = lambdaRuntimeProperties(
-      runtimeConfig,
-      "ExecutionRole",
-      functionNames.contentMirror,
-      "ContentMirrorArtifactKey",
-      "content-mirror",
-      {
-        Timeout: 300,
-        MemorySize: 512,
-        Environment: {
-          Variables: {
-            S3TE_ENVIRONMENT: environment,
-            S3TE_CONTENT_TABLE: runtimeConfig.tables.content,
-            S3TE_RELEVANT_MODELS: runtimeConfig.integrations.webiny.relevantModels.join(","),
-            S3TE_WEBINY_TENANT: runtimeConfig.integrations.webiny.tenant ?? "",
-            S3TE_RENDER_WORKER_NAME: functionNames.renderWorker
-          }
-        }
-      }
-    );
-
-    resources.ContentMirrorEventSourceMapping = {
-      Type: "AWS::Lambda::EventSourceMapping",
-      Properties: {
-        BatchSize: 10,
-        StartingPosition: "LATEST",
-        EventSourceArn: { Ref: "WebinySourceTableStreamArn" },
-        FunctionName: { Ref: "ContentMirror" }
-      }
-    };
-  }
-
   if (featureSet.has("sitemap") && runtimeConfig.integrations.sitemap.enabled) {
     resources.SitemapUpdater = lambdaRuntimeProperties(
       runtimeConfig,
@@ -426,9 +389,6 @@ export function buildCloudFormationTemplate({ config, environment, features = []
   outputs.InvalidationSchedulerFunctionName = { Value: functionNames.invalidationScheduler };
   outputs.InvalidationExecutorFunctionName = { Value: functionNames.invalidationExecutor };
 
-  if (resources.ContentMirror) {
-    outputs.ContentMirrorFunctionName = { Value: functionNames.contentMirror };
-  }
   if (resources.SitemapUpdater) {
     outputs.SitemapUpdaterFunctionName = { Value: functionNames.sitemapUpdater };
   }
@@ -620,6 +580,64 @@ export function buildCloudFormationTemplate({ config, environment, features = []
   };
 }
 
+export function buildWebinyCloudFormationTemplate({ config, environment }) {
+  const runtimeConfig = buildEnvironmentRuntimeConfig(config, environment);
+  const functionNames = buildFunctionNames(runtimeConfig);
+
+  return {
+    AWSTemplateFormatVersion: "2010-09-09",
+    Description: `S3TE Webiny option stack for ${config.project.name} (${environment})`,
+    Parameters: {
+      ArtifactBucket: {
+        Type: "String"
+      },
+      ContentMirrorArtifactKey: {
+        Type: "String"
+      },
+      WebinySourceTableStreamArn: {
+        Type: "String"
+      }
+    },
+    Resources: {
+      ExecutionRole: createExecutionRole(`${runtimeConfig.stackPrefix}_s3te_webiny_lambda_runtime`),
+      ContentMirror: lambdaRuntimeProperties(
+        runtimeConfig,
+        "ExecutionRole",
+        functionNames.contentMirror,
+        "ContentMirrorArtifactKey",
+        "content-mirror",
+        {
+          Timeout: 300,
+          MemorySize: 512,
+          Environment: {
+            Variables: {
+              S3TE_ENVIRONMENT: environment,
+              S3TE_CONTENT_TABLE: runtimeConfig.tables.content,
+              S3TE_RELEVANT_MODELS: runtimeConfig.integrations.webiny.relevantModels.join(","),
+              S3TE_WEBINY_TENANT: runtimeConfig.integrations.webiny.tenant ?? "",
+              S3TE_RENDER_WORKER_NAME: functionNames.renderWorker
+            }
+          }
+        }
+      ),
+      ContentMirrorEventSourceMapping: {
+        Type: "AWS::Lambda::EventSourceMapping",
+        Properties: {
+          BatchSize: 10,
+          StartingPosition: "LATEST",
+          EventSourceArn: { Ref: "WebinySourceTableStreamArn" },
+          FunctionName: { Ref: "ContentMirror" }
+        }
+      }
+    },
+    Outputs: {
+      ContentMirrorFunctionName: {
+        Value: functionNames.contentMirror
+      }
+    }
+  };
+}
+
 export function buildTemporaryDeployStackTemplate() {
   return {
     AWSTemplateFormatVersion: "2010-09-09",

package/packages/cli/bin/s3te.mjs

@@ -3,10 +3,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import {
+  configureProjectOption,
   deployProject,
   doctorProject,
   loadResolvedConfig,
-  migrateProject,
   packageProject,
   renderProject,
   runProjectTests,
@@ -86,7 +86,7 @@ function printHelp() {
     "  sync\n" +
     "  deploy\n" +
     "  doctor\n" +
-    "  migrate\n"
+    "  option <webiny|sitemap>\n"
   );
 }
 
@@ -377,30 +377,39 @@ async function main() {
     return;
   }
 
-  if (command === "migrate") {
+  if (command === "option") {
+    const optionName = String(options._[0] ?? "").trim().toLowerCase();
+    if (!optionName) {
+      process.stderr.write("option requires a name such as webiny or sitemap\n");
+      process.exitCode = 1;
+      return;
+    }
     const configPath = path.resolve(cwd, options.config ?? "s3te.config.json");
     const rawConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
-    const migration = await migrateProject(configPath, rawConfig, {
+    const optionResult = await configureProjectOption(configPath, rawConfig, {
+      optionName,
       writeChanges: Boolean(options.write) && !Boolean(options["dry-run"]),
       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"])
+      enable: Boolean(options.enable),
+      disable: Boolean(options.disable),
+      sourceTable: options["source-table"],
+      tenant: options.tenant,
+      models: asArray(options.model)
     });
     if (wantsJson) {
-      printJson("migrate", true, [], [], startedAt, {
-        configVersion: migration.config.configVersion,
+      printJson(`option ${optionName}`, true, [], [], startedAt, {
+        configVersion: optionResult.config.configVersion,
         wrote: Boolean(options.write) && !Boolean(options["dry-run"]),
-        changes: migration.changes
+        changes: optionResult.changes
       });
       return;
     }
-    process.stdout.write(options.write ? `Migrated ${configPath}\n` : `Migration preview for ${configPath}: configVersion=${migration.config.configVersion}\n`);
-    for (const change of migration.changes) {
+    process.stdout.write(
+      options.write
+        ? `Updated option ${optionName} in ${configPath}\n`
+        : `Option preview for ${optionName} in ${configPath}: configVersion=${optionResult.config.configVersion}\n`
+    );
+    for (const change of optionResult.changes) {
       process.stdout.write(`- ${change}\n`);
     }
     return;

package/packages/cli/src/project.mjs

@@ -991,128 +991,129 @@ export async function doctorProject(projectDir, configPath, options = {}) {
   return checks;
 }
 
-export async function migrateProject(configPath, rawConfig, writeChanges) {
-  const options = typeof writeChanges === "object" && writeChanges !== null
-    ? writeChanges
-    : { writeChanges };
+export async function configureProjectOption(configPath, rawConfig, optionConfiguration) {
+  const options = typeof optionConfiguration === "object" && optionConfiguration !== null
+    ? optionConfiguration
+    : { writeChanges: optionConfiguration };
+  const optionName = String(options.optionName ?? "").trim().toLowerCase();
+  const targetEnvironment = options.environment ? String(options.environment).trim() : "";
   const nextConfig = {
     ...rawConfig,
     configVersion: rawConfig.configVersion ?? 1
   };
   const changes = [];
 
-  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() : "";
-  const webinyModels = normalizeStringList(options.webinyModels);
-
-  if (enableWebiny && disableWebiny) {
-    throw new S3teError("CONFIG_CONFLICT_ERROR", "migrate does not allow --enable-webiny and --disable-webiny at the same time.");
+  if (!optionName) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", "option requires an optionName such as webiny or sitemap.");
   }
-  if (enableSitemap && disableSitemap) {
-    throw new S3teError("CONFIG_CONFLICT_ERROR", "migrate does not allow --enable-sitemap and --disable-sitemap at the same time.");
+  if (!["webiny", "sitemap"].includes(optionName)) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", `Unknown option ${optionName}. Supported options: webiny, sitemap.`);
+  }
+  if (targetEnvironment && !nextConfig.environments?.[targetEnvironment]) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", `Unknown environment for option ${optionName}: ${targetEnvironment}.`);
   }
 
-  const touchesWebiny = enableWebiny || disableWebiny || Boolean(webinySourceTable) || Boolean(webinyTenant) || webinyModels.length > 0;
-  if (touchesWebiny) {
-    if (targetEnvironment && !nextConfig.environments?.[targetEnvironment]) {
-      throw new S3teError("CONFIG_CONFLICT_ERROR", `Unknown environment for migrate: ${targetEnvironment}.`);
-    }
+  const enable = Boolean(options.enable);
+  const disable = Boolean(options.disable);
+  if (enable && disable) {
+    throw new S3teError("CONFIG_CONFLICT_ERROR", `option ${optionName} does not allow --enable and --disable at the same time.`);
+  }
 
-    const existingIntegrations = nextConfig.integrations ?? {};
-    const existingWebiny = existingIntegrations.webiny ?? {};
-    const existingEnvironmentOverrides = existingWebiny.environments ?? {};
-    const existingTargetWebiny = targetEnvironment
-      ? (existingEnvironmentOverrides[targetEnvironment] ?? {})
-      : existingWebiny;
-    const inheritedModels = normalizeStringList(
-      existingTargetWebiny.relevantModels
-      ?? (targetEnvironment ? existingWebiny.relevantModels : undefined)
-      ?? ["staticContent", "staticCodeContent"]
-    );
-    const shouldEnableWebiny = disableWebiny
-      ? false
-      : (enableWebiny || Boolean(webinySourceTable) || webinyModels.length > 0
-          ? true
-          : Boolean(targetEnvironment
-              ? (existingTargetWebiny.enabled ?? existingWebiny.enabled)
-              : existingWebiny.enabled));
-    const nextSourceTableName = webinySourceTable
-      || existingTargetWebiny.sourceTableName
-      || (targetEnvironment ? existingWebiny.sourceTableName : "")
-      || "";
-
-    if (shouldEnableWebiny && !nextSourceTableName) {
-      throw new S3teError(
-        "CONFIG_CONFLICT_ERROR",
-        targetEnvironment
-          ? `Enabling Webiny for environment ${targetEnvironment} requires --webiny-source-table <table> or an existing sourceTableName.`
-          : "Enabling Webiny requires --webiny-source-table <table> or an existing integrations.webiny.sourceTableName."
+  if (optionName === "webiny") {
+    const webinySourceTable = options.sourceTable ? String(options.sourceTable).trim() : "";
+    const webinyTenant = options.tenant ? String(options.tenant).trim() : "";
+    const webinyModels = normalizeStringList(options.models);
+    const touchesWebiny = enable || disable || Boolean(webinySourceTable) || Boolean(webinyTenant) || webinyModels.length > 0;
+
+    if (touchesWebiny) {
+      const existingIntegrations = nextConfig.integrations ?? {};
+      const existingWebiny = existingIntegrations.webiny ?? {};
+      const existingEnvironmentOverrides = existingWebiny.environments ?? {};
+      const existingTargetWebiny = targetEnvironment
+        ? (existingEnvironmentOverrides[targetEnvironment] ?? {})
+        : existingWebiny;
+      const inheritedModels = normalizeStringList(
+        existingTargetWebiny.relevantModels
+        ?? (targetEnvironment ? existingWebiny.relevantModels : undefined)
+        ?? ["staticContent", "staticCodeContent"]
       );
-    }
-
-    const nextWebinyConfig = {
-      enabled: shouldEnableWebiny,
-      sourceTableName: nextSourceTableName || undefined,
-      mirrorTableName: existingTargetWebiny.mirrorTableName
-        ?? (targetEnvironment ? existingWebiny.mirrorTableName : undefined)
-        ?? "{stackPrefix}_s3te_content_{project}",
-      tenant: webinyTenant || existingTargetWebiny.tenant || (targetEnvironment ? existingWebiny.tenant : undefined) || undefined,
-      relevantModels: normalizeStringList([
-        ...(inheritedModels.length > 0 ? inheritedModels : ["staticContent", "staticCodeContent"]),
-        ...webinyModels
-      ])
-    };
+      const shouldEnableWebiny = disable
+        ? false
+        : (enable || Boolean(webinySourceTable) || webinyModels.length > 0
+            ? true
+            : Boolean(targetEnvironment
+                ? (existingTargetWebiny.enabled ?? existingWebiny.enabled)
+                : existingWebiny.enabled));
+      const nextSourceTableName = webinySourceTable
+        || existingTargetWebiny.sourceTableName
+        || (targetEnvironment ? existingWebiny.sourceTableName : "")
+        || "";
+
+      if (shouldEnableWebiny && !nextSourceTableName) {
+        throw new S3teError(
+          "CONFIG_CONFLICT_ERROR",
+          targetEnvironment
+            ? `Enabling Webiny for environment ${targetEnvironment} requires --source-table <table> or an existing sourceTableName.`
+            : "Enabling Webiny requires --source-table <table> or an existing integrations.webiny.sourceTableName."
+        );
+      }
 
-    nextConfig.integrations = {
-      ...existingIntegrations,
-      webiny: targetEnvironment
-        ? {
-            ...existingWebiny,
-            environments: {
-              ...existingEnvironmentOverrides,
-              [targetEnvironment]: nextWebinyConfig
+      const nextWebinyConfig = {
+        enabled: shouldEnableWebiny,
+        sourceTableName: nextSourceTableName || undefined,
+        mirrorTableName: existingTargetWebiny.mirrorTableName
+          ?? (targetEnvironment ? existingWebiny.mirrorTableName : undefined)
+          ?? "{stackPrefix}_s3te_content_{project}",
+        tenant: webinyTenant || existingTargetWebiny.tenant || (targetEnvironment ? existingWebiny.tenant : undefined) || undefined,
+        relevantModels: normalizeStringList([
+          ...(inheritedModels.length > 0 ? inheritedModels : ["staticContent", "staticCodeContent"]),
+          ...webinyModels
+        ])
+      };
+
+      nextConfig.integrations = {
+        ...existingIntegrations,
+        webiny: targetEnvironment
+          ? {
+              ...existingWebiny,
+              environments: {
+                ...existingEnvironmentOverrides,
+                [targetEnvironment]: nextWebinyConfig
+              }
             }
-          }
-        : {
-            ...existingWebiny,
-            ...nextWebinyConfig,
-            environments: existingEnvironmentOverrides
-          }
-    };
+          : {
+              ...existingWebiny,
+              ...nextWebinyConfig,
+              ...(Object.keys(existingEnvironmentOverrides).length > 0
+                ? { environments: existingEnvironmentOverrides }
+                : {})
+            }
+      };
 
-    const scopeLabel = targetEnvironment ? ` for environment ${targetEnvironment}` : "";
-    changes.push(shouldEnableWebiny ? `Enabled Webiny integration${scopeLabel}.` : `Disabled Webiny integration${scopeLabel}.`);
-    if (webinySourceTable) {
-      changes.push(`Set Webiny source table${scopeLabel} to ${webinySourceTable}.`);
-    }
-    if (webinyTenant) {
-      changes.push(`Set Webiny tenant${scopeLabel} to ${webinyTenant}.`);
-    }
-    if (webinyModels.length > 0) {
-      changes.push(`Added Webiny models${scopeLabel}: ${webinyModels.join(", ")}.`);
+      const scopeLabel = targetEnvironment ? ` for environment ${targetEnvironment}` : "";
+      changes.push(shouldEnableWebiny ? `Enabled Webiny option${scopeLabel}.` : `Disabled Webiny option${scopeLabel}.`);
+      if (webinySourceTable) {
+        changes.push(`Set Webiny source table${scopeLabel} to ${webinySourceTable}.`);
+      }
+      if (webinyTenant) {
+        changes.push(`Set Webiny tenant${scopeLabel} to ${webinyTenant}.`);
+      }
+      if (webinyModels.length > 0) {
+        changes.push(`Added Webiny models${scopeLabel}: ${webinyModels.join(", ")}.`);
+      }
     }
   }
 
-  const touchesSitemap = enableSitemap || disableSitemap;
-  if (touchesSitemap) {
-    if (targetEnvironment && !nextConfig.environments?.[targetEnvironment]) {
-      throw new S3teError("CONFIG_CONFLICT_ERROR", `Unknown environment for migrate: ${targetEnvironment}.`);
-    }
-
+  if (optionName === "sitemap") {
     const existingIntegrations = nextConfig.integrations ?? {};
     const existingSitemap = existingIntegrations.sitemap ?? {};
     const existingEnvironmentOverrides = existingSitemap.environments ?? {};
     const existingTargetSitemap = targetEnvironment
       ? (existingEnvironmentOverrides[targetEnvironment] ?? {})
       : existingSitemap;
-    const nextEnabled = disableSitemap
+    const nextEnabled = disable
       ? false
-      : (enableSitemap || Boolean(targetEnvironment
+      : (enable || Boolean(targetEnvironment
           ? (existingTargetSitemap.enabled ?? existingSitemap.enabled)
           : existingSitemap.enabled));
 
@@ -1132,12 +1133,14 @@ export async function migrateProject(configPath, rawConfig, writeChanges) {
         : {
             ...existingSitemap,
             enabled: nextEnabled,
-            environments: existingEnvironmentOverrides
+            ...(Object.keys(existingEnvironmentOverrides).length > 0
+              ? { environments: existingEnvironmentOverrides }
+              : {})
           }
     };
 
     const scopeLabel = targetEnvironment ? ` for environment ${targetEnvironment}` : "";
-    changes.push(nextEnabled ? `Enabled sitemap integration${scopeLabel}.` : `Disabled sitemap integration${scopeLabel}.`);
+    changes.push(nextEnabled ? `Enabled sitemap option${scopeLabel}.` : `Disabled sitemap option${scopeLabel}.`);
   }
 
   if (options.writeChanges) {

package/packages/core/src/config.mjs

@@ -383,6 +383,10 @@ export function resolveStackName(config, environmentName) {
   return `${config.environments[environmentName].stackPrefix}-s3te-${config.project.name}`;
 }
 
+export function resolveOptionStackName(config, environmentName, optionName) {
+  return `${resolveStackName(config, environmentName)}-${String(optionName).trim().toLowerCase()}`;
+}
+
 export function buildEnvironmentRuntimeConfig(config, environmentName, stackOutputs = {}) {
   const environmentConfig = config.environments[environmentName];
   const webinyConfig = resolveEnvironmentWebinyIntegration(config, environmentName);

package/packages/core/src/index.mjs

@@ -9,6 +9,7 @@ export {
   resolveCloudFrontAliases,
   resolveEnvironmentSitemapIntegration,
   resolveEnvironmentWebinyIntegration,
+  resolveOptionStackName,
   resolveRuntimeManifestParameterName,
   resolveProjectConfig,
   resolveStackName,