@codedrifters/configulator 0.0.425 → 0.0.426

package/lib/index.js

@@ -195,6 +195,7 @@ __export(index_exports, {
   AwsDeploymentConfig: () => AwsDeploymentConfig,
   AwsDeploymentTarget: () => AwsDeploymentTarget,
   AwsTeardownWorkflow: () => AwsTeardownWorkflow,
+  BUILD_ARTIFACT_NAME: () => BUILD_ARTIFACT_NAME,
   BUILT_IN_BUNDLES: () => BUILT_IN_BUNDLES,
   BUNDLE_OWNERSHIP: () => BUNDLE_OWNERSHIP,
   CDK_BOOTSTRAP_DEFAULTS_BY_STAGE: () => CDK_BOOTSTRAP_DEFAULTS_BY_STAGE,
@@ -293,7 +294,9 @@ __export(index_exports, {
   MONOREPO_LAYOUT: () => MONOREPO_LAYOUT,
   MonorepoProject: () => MonorepoProject,
   Nvmrc: () => Nvmrc,
+  PERMISSION_BACKUP_FILE: () => PERMISSION_BACKUP_FILE,
   PHASE_LABEL_TYPE_MAP: () => PHASE_LABEL_TYPE_MAP,
+  PLAN_RUN_ID_INPUT: () => PLAN_RUN_ID_INPUT,
   PROD_DEPLOY_NAME: () => PROD_DEPLOY_NAME,
   PROGRESS_FILES_FORMAT_VALUES: () => PROGRESS_FILES_FORMAT_VALUES,
   PnpmWorkspace: () => PnpmWorkspace,
@@ -327,6 +330,7 @@ __export(index_exports, {
   TypeScriptConfig: () => TypeScriptConfig,
   TypeScriptProject: () => TypeScriptProject,
   UNKNOWN_TYPE_FALLBACK_TIER: () => UNKNOWN_TYPE_FALLBACK_TIER,
+  VALIDATE_PLAN_JOB_ID: () => VALIDATE_PLAN_JOB_ID,
   VALID_PRIORITY_VALUES: () => VALID_PRIORITY_VALUES,
   VALID_STATUS_VALUES: () => VALID_STATUS_VALUES,
   VERSION: () => VERSION,
@@ -471,6 +475,7 @@ __export(index_exports, {
   renderNextRequirementIdProcedure: () => renderNextRequirementIdProcedure,
   renderPhaseTypeInvariantSection: () => renderPhaseTypeInvariantSection,
   renderPhaseTypeInvariantShellHelpers: () => renderPhaseTypeInvariantShellHelpers,
+  renderPlanValidationScript: () => renderPlanValidationScript,
   renderPriorityRulesSection: () => renderPriorityRulesSection,
   renderProgressFileName: () => renderProgressFileName,
   renderProgressFilePath: () => renderProgressFilePath,
@@ -42304,7 +42309,17 @@ var DEPLOY_GATE = {
    * required reviewers, wait timers, deployment branch policies — apply before
    * the job is sent to a runner.
    */
-  ENVIRONMENT: "environment"
+  ENVIRONMENT: "environment",
+  /**
+   * Split the workflow in two. A **plan** workflow builds and diffs but never
+   * deploys; a dispatch-only **apply** workflow deploys the exact cloud
+   * assembly a nominated plan run produced.
+   *
+   * Needs no protection rule, so unlike {@link DEPLOY_GATE.ENVIRONMENT} it
+   * works on every GitHub plan. `environmentName` is optional here and layers
+   * an environment onto the apply jobs.
+   */
+  PLAN_APPLY: "plan-apply"
 };
 var resolveEnvironmentGate = (gate, environmentName, componentName) => {
   const trimmed = environmentName?.trim();
@@ -42316,7 +42331,7 @@ var resolveEnvironmentGate = (gate, environmentName, componentName) => {
     }
     return void 0;
   }
-  if (!trimmed) {
+  if (gate === DEPLOY_GATE.ENVIRONMENT && !trimmed) {
     throw new Error(
       `${componentName} requires a non-empty \`environmentName\` when \`gate\` is "${gate}"`
     );
@@ -42338,6 +42353,105 @@ var renderHomeRepositoryCondition = (homeRepository, componentName) => {
   return `github.repository == '${homeRepository}'`;
 };
 
+// src/workflows/plan-apply.ts
+var VALIDATE_PLAN_JOB_ID = "validate-plan";
+var PLAN_RUN_ID_INPUT = "plan_run_id";
+var BUILD_ARTIFACT_NAME = "build-artifact";
+var PERMISSION_BACKUP_FILE = "permissions-backup.acl";
+var renderPlanValidationScript = (options) => {
+  const {
+    planWorkflowPath,
+    allowedBranches,
+    requireCurrentHead,
+    verifyArtifactDigest
+  } = options;
+  return [
+    "const raw = (process.env.PLAN_RUN_ID ?? '').trim();",
+    "const runId = Number(raw);",
+    "if (!/^[0-9]+$/.test(raw) || !Number.isSafeInteger(runId) || runId <= 0) {",
+    '  core.setFailed(`plan_run_id must be a positive run id, got "${raw}"`);',
+    "  return;",
+    "}",
+    "",
+    "const { owner, repo } = context.repo;",
+    "const { data: run } = await github.rest.actions.getWorkflowRun({",
+    "  owner,",
+    "  repo,",
+    "  run_id: runId,",
+    "});",
+    "",
+    `const expectedPath = ${JSON.stringify(planWorkflowPath)};`,
+    "if (run.path !== expectedPath) {",
+    '  core.setFailed(`Run ${runId} belongs to workflow "${run.path}", expected "${expectedPath}".`);',
+    "  return;",
+    "}",
+    "",
+    'if (run.status !== "completed" || run.conclusion !== "success") {',
+    '  core.setFailed(`Run ${runId} is status "${run.status}" / conclusion "${run.conclusion}", expected a completed successful plan run.`);',
+    "  return;",
+    "}",
+    "",
+    `const allowedBranches = ${JSON.stringify(allowedBranches)};`,
+    'const branch = run.head_branch ?? "";',
+    "const branchAllowed = allowedBranches.some((pattern) =>",
+    '  pattern.includes("*")',
+    '    ? branch.startsWith(pattern.slice(0, pattern.indexOf("*")))',
+    "    : branch === pattern,",
+    ");",
+    "if (!branchAllowed) {",
+    '  core.setFailed(`Run ${runId} ran on branch "${branch}", which no deployment target in this workflow accepts (allowed: ${allowedBranches.join(", ")}).`);',
+    "  return;",
+    "}",
+    ...requireCurrentHead ? [
+      "",
+      "const { data: liveBranch } = await github.rest.repos.getBranch({",
+      "  owner,",
+      "  repo,",
+      "  branch,",
+      "});",
+      "if (liveBranch.commit.sha !== run.head_sha) {",
+      '  core.setFailed(`Run ${runId} planned ${run.head_sha} but "${branch}" now points at ${liveBranch.commit.sha}. Re-run the plan workflow against the current head.`);',
+      "  return;",
+      "}"
+    ] : [],
+    "",
+    "const artifacts = await github.paginate(",
+    "  github.rest.actions.listWorkflowRunArtifacts,",
+    "  { owner, repo, run_id: runId, per_page: 100 },",
+    ");",
+    `const artifactName = ${JSON.stringify(BUILD_ARTIFACT_NAME)};`,
+    "const artifact = artifacts.find((a) => a.name === artifactName);",
+    "if (!artifact) {",
+    '  core.setFailed(`Run ${runId} published no "${artifactName}" artifact. Only a plan run whose build job completed can be applied.`);',
+    "  return;",
+    "}",
+    "if (artifact.expired) {",
+    '  core.setFailed(`The "${artifactName}" artifact on run ${runId} expired at ${artifact.expires_at}. Artifact retention is this gate\'s approval window \u2014 re-run the plan workflow.`);',
+    "  return;",
+    "}",
+    ...verifyArtifactDigest ? [
+      "if (!artifact.digest) {",
+      '  core.setFailed(`The "${artifactName}" artifact on run ${runId} reports no digest, so it cannot be verified. Disable planApply.verifyArtifactDigest or re-run the plan workflow.`);',
+      "  return;",
+      "}",
+      'core.setOutput("artifact_digest", artifact.digest);'
+    ] : [],
+    "",
+    'core.setOutput("head_sha", run.head_sha);',
+    'core.setOutput("head_branch", branch);',
+    "await core.summary",
+    "  .addHeading(`Applying plan run ${runId}`, 2)",
+    "  .addTable([",
+    '    [{ data: "Field", header: true }, { data: "Value", header: true }],',
+    '    ["Plan run", `<a href="${run.html_url}">${runId}</a>`],',
+    '    ["Branch", branch],',
+    '    ["Commit", run.head_sha],',
+    '    ["Artifact expires", artifact.expires_at ?? "unknown"],',
+    "  ])",
+    "  .write();"
+  ].join("\n");
+};
+
 // src/workflows/aws-deploy-workflow.ts
 var PROD_DEPLOY_NAME = "prod-deploy";
 var DIFF_OUTPUT_FILE = "cdk-diff.txt";
@@ -42409,6 +42523,20 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
         target.region
       ].join("-");
     };
+    /**
+     * Build the deterministic GitHub Actions job name for a target's apply job.
+     * Mirrors {@link buildJobName} with an `apply` verb.
+     */
+    this.buildApplyJobName = (target) => {
+      return [
+        target.awsStageType,
+        target.deploymentTargetRole,
+        "apply",
+        target.project.name,
+        target.account,
+        target.region
+      ].join("-");
+    };
     /**
      * Build the CI artifact name for a target's captured diff.
      *
@@ -42427,6 +42555,163 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
         target.region
       ].join("-");
     };
+    /**
+     * Create the dispatch-only apply workflow and its validation job.
+     *
+     * The workflow file name defaults to the plan workflow's name suffixed with
+     * `-apply`. A name already in use throws rather than silently colliding on
+     * the underlying `.github/workflows/<name>.yml` file — the usual cause is two
+     * `AwsDeployWorkflow`s sharing one build workflow, and the fix is an explicit
+     * `planApply.applyWorkflowName`.
+     */
+    this.createApplyWorkflow = (github, homeRepositoryCondition) => {
+      const { applyWorkflowName, requireCurrentHead, verifyArtifactDigest } = this.planApplyOptions;
+      if (github.tryFindWorkflow(applyWorkflowName)) {
+        throw new Error(
+          `AwsDeployWorkflow cannot create the apply workflow "${applyWorkflowName}" because a workflow with that name already exists. Set \`planApply.applyWorkflowName\` to something unique.`
+        );
+      }
+      const workflow = new import_github6.GithubWorkflow(github, applyWorkflowName);
+      workflow.on({
+        workflowDispatch: {
+          inputs: {
+            [PLAN_RUN_ID_INPUT]: {
+              description: "Run id of the plan workflow run to apply. Its build artifact is deployed verbatim.",
+              required: true,
+              type: "string"
+            }
+          }
+        }
+      });
+      const allowedBranches = Array.from(
+        new Set(
+          this.awsDeploymentTargets.flatMap(
+            (target) => target.branches.map((b) => b.branch)
+          )
+        )
+      );
+      workflow.addJob(VALIDATE_PLAN_JOB_ID, {
+        name: "Validate plan run",
+        runsOn: ["ubuntu-latest"],
+        permissions: {
+          actions: import_workflows_model5.JobPermission.READ,
+          contents: import_workflows_model5.JobPermission.READ
+        },
+        ...homeRepositoryCondition ? { if: `\${{ ${homeRepositoryCondition} }}` } : {},
+        outputs: {
+          head_sha: { stepId: "validate_plan_run", outputName: "head_sha" },
+          head_branch: { stepId: "validate_plan_run", outputName: "head_branch" },
+          ...verifyArtifactDigest ? {
+            artifact_digest: {
+              stepId: "validate_plan_run",
+              outputName: "artifact_digest"
+            }
+          } : {}
+        },
+        steps: [
+          {
+            name: "Validate plan run",
+            id: "validate_plan_run",
+            uses: "actions/github-script@v9",
+            /**
+             * The dispatch input reaches the script through the environment
+             * rather than a `${{ }}` interpolation, so a crafted run id cannot
+             * inject JavaScript into the validation itself.
+             */
+            env: {
+              PLAN_RUN_ID: `\${{ inputs.${PLAN_RUN_ID_INPUT} }}`
+            },
+            with: {
+              script: renderPlanValidationScript({
+                planWorkflowPath: `.github/workflows/${this.buildWorkflow.name}.yml`,
+                allowedBranches,
+                requireCurrentHead,
+                verifyArtifactDigest
+              })
+            }
+          }
+        ]
+      });
+      return workflow;
+    };
+    /**
+     * Register one target's apply job on the apply workflow.
+     *
+     * Differences from the `single`-gate deploy job, all of them forced by the
+     * apply run having no build job of its own:
+     *
+     * - `needs` starts at the validation job rather than `build`, so a plan run
+     *   that fails any check skips every apply job instead of deploying.
+     * - `actions: read` is added, which is what lets `actions/download-artifact`
+     *   reach across runs.
+     * - No `pull-requests: write`, and no sticky PR comment step: an apply is
+     *   always a `workflow_dispatch`, so the comment could never fire.
+     * - No branch filter on `github.ref`. The ref an operator happens to
+     *   dispatch from is unrelated to what was planned; the branch that matters
+     *   is the plan run's, and the validation job checks that one.
+     *
+     * When `environmentName` is also supplied, it lands here rather than on the
+     * plan's jobs — a second approver on top of whoever dispatched the apply.
+     * `validate-plan` stays ungated so its verdict is available to read *before*
+     * the approval is given.
+     */
+    this.addApplyJob = (workflow, target, homeRepositoryCondition) => {
+      const applyJobName = this.buildApplyJobName(target);
+      const { verifyArtifactDigest } = this.planApplyOptions;
+      const artifactsDirectory = this.rootProject.artifactsDirectory;
+      workflow.addJob(applyJobName, {
+        name: `Apply ${this.project.name} ${target.awsStageType}/${target.deploymentTargetRole}/${target.account}/${target.region}`,
+        needs: [
+          VALIDATE_PLAN_JOB_ID,
+          ...this.deployAfterTargets.map((p) => this.buildApplyJobName(p))
+        ],
+        runsOn: ["ubuntu-latest"],
+        permissions: {
+          actions: import_workflows_model5.JobPermission.READ,
+          contents: import_workflows_model5.JobPermission.READ,
+          idToken: import_workflows_model5.JobPermission.WRITE
+        },
+        ...this.environmentName ? { environment: this.environmentName } : void 0,
+        /**
+         * Shares the deploy job's group name so an apply can never overlap a
+         * same-target deploy. `cancel-in-progress` is spelled out rather than
+         * left to GitHub's default: cancelling a half-finished `cdk deploy`
+         * strands a CloudFormation stack mid-update.
+         */
+        concurrency: {
+          group: this.buildJobName(target),
+          "cancel-in-progress": false
+        },
+        ...homeRepositoryCondition ? { if: `\${{ ${homeRepositoryCondition} }}` } : {},
+        steps: [
+          /**
+           * Cross-run download of the plan's assembly. `run-id` plus an explicit
+           * `github-token` is what makes `actions/download-artifact` look outside
+           * the current run; without both it silently searches this run and finds
+           * nothing.
+           */
+          {
+            name: "Download plan build artifacts",
+            uses: "actions/download-artifact@v8",
+            with: {
+              name: BUILD_ARTIFACT_NAME,
+              path: artifactsDirectory,
+              "run-id": `\${{ inputs.${PLAN_RUN_ID_INPUT} }}`,
+              "github-token": "${{ secrets.GITHUB_TOKEN }}",
+              ...verifyArtifactDigest ? {
+                "artifact-digest": `\${{ needs.${VALIDATE_PLAN_JOB_ID}.outputs.artifact_digest }}`
+              } : {}
+            }
+          },
+          {
+            name: "Restore build artifact permissions",
+            continueOnError: true,
+            run: `cd ${artifactsDirectory} && setfacl --restore=${PERMISSION_BACKUP_FILE}`
+          },
+          ...this.deploySteps(target, { stickyPrComment: false })
+        ]
+      });
+    };
     /**
      * Builds a GitHub Actions condition string that checks if the current branch
      * matches any of the provided branch patterns.
@@ -42455,7 +42740,15 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
       }
       return conditions.join(" || ");
     };
-    this.deploySteps = (target) => {
+    /**
+     * Steps for a target's deploy job.
+     *
+     * `stickyPrComment` drops the sticky-PR-comment step when false. Apply jobs
+     * pass false: they only ever run on `workflow_dispatch` and so could never
+     * satisfy that step's own `pull_request` guard.
+     */
+    this.deploySteps = (target, options = {}) => {
+      const { stickyPrComment = true } = options;
       const {
         awsStageType,
         deploymentTargetRole,
@@ -42534,15 +42827,17 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
          * comment is keyed by the deploy job name so dev/stage/prod comments
          * don't collide on the same PR.
          */
-        {
-          name: "Sticky PR comment with deploy endpoints",
-          if: "github.event_name == 'pull_request' && hashFiles('deploy-urls.md') != ''",
-          uses: "marocchino/sticky-pull-request-comment@v3",
-          with: {
-            header: deployJobName,
-            path: "deploy-urls.md"
+        ...stickyPrComment ? [
+          {
+            name: "Sticky PR comment with deploy endpoints",
+            if: "github.event_name == 'pull_request' && hashFiles('deploy-urls.md') != ''",
+            uses: "marocchino/sticky-pull-request-comment@v3",
+            with: {
+              header: deployJobName,
+              path: "deploy-urls.md"
+            }
           }
-        }
+        ] : []
       ];
     };
     /**
@@ -42686,8 +42981,15 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
       (target) => target.awsStageType === this.awsStageType && target.ciDeployment
     ) ?? [];
     this.deployAfterTargets = options.deployAfterTargets ?? [];
+    this.gate = options.gate;
+    const isPlanApply = this.gate === DEPLOY_GATE.PLAN_APPLY;
+    if (isPlanApply && options.diff?.enabled === false) {
+      throw new Error(
+        "AwsDeployWorkflow cannot disable `diff` under the `plan-apply` gate: the diff jobs are what keep the plan workflow publishing the build artifact the apply workflow deploys."
+      );
+    }
     this.diffOptions = {
-      enabled: options.diff?.enabled ?? false,
+      enabled: options.diff?.enabled ?? isPlanApply,
       artifact: options.diff?.artifact ?? true,
       summary: options.diff?.summary ?? true
     };
@@ -42773,6 +43075,17 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
         ...buildWorkflowOptions?.preBuildSteps ?? []
       ]
     });
+    this.planApplyOptions = {
+      applyWorkflowName: options.planApply?.applyWorkflowName ?? `${this.buildWorkflow.name}-apply`,
+      requireCurrentHead: options.planApply?.requireCurrentHead ?? false,
+      verifyArtifactDigest: options.planApply?.verifyArtifactDigest ?? false
+    };
+    if (isPlanApply) {
+      this.applyWorkflow = this.createApplyWorkflow(
+        github,
+        homeRepositoryCondition
+      );
+    }
     this.awsDeploymentTargets.forEach((target) => {
       const deployJobName = this.buildJobName(target);
       const branchFilterCondition = this.buildBranchFilterCondition(
@@ -42783,27 +43096,31 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen26.Compone
         ...homeRepositoryCondition ? [homeRepositoryCondition] : [],
         ...branchFilterCondition ? [`(${branchFilterCondition})`] : []
       ].join(" && ") + " }}";
-      const gatedOnDiff = !!this.environmentName && this.diffOptions.enabled;
-      this.buildWorkflow.addPostBuildJob(deployJobName, {
-        name: `Deploy ${this.project.name} ${target.awsStageType}/${target.deploymentTargetRole}/${target.account}/${target.region}`,
-        needs: [
-          "build",
-          ...gatedOnDiff ? [this.buildDiffJobName(target)] : [],
-          ...this.deployAfterTargets.map((p) => {
-            return this.buildJobName(p);
-          })
-        ],
-        runsOn: ["ubuntu-latest"],
-        permissions: {
-          contents: import_workflows_model5.JobPermission.READ,
-          idToken: import_workflows_model5.JobPermission.WRITE,
-          pullRequests: import_workflows_model5.JobPermission.WRITE
-        },
-        ...this.environmentName ? { environment: this.environmentName } : void 0,
-        concurrency: deployJobName,
-        if: jobCondition,
-        steps: [...this.deploySteps(target)]
-      });
+      if (this.applyWorkflow) {
+        this.addApplyJob(this.applyWorkflow, target, homeRepositoryCondition);
+      } else {
+        const gatedOnDiff = !!this.environmentName && this.diffOptions.enabled;
+        this.buildWorkflow.addPostBuildJob(deployJobName, {
+          name: `Deploy ${this.project.name} ${target.awsStageType}/${target.deploymentTargetRole}/${target.account}/${target.region}`,
+          needs: [
+            "build",
+            ...gatedOnDiff ? [this.buildDiffJobName(target)] : [],
+            ...this.deployAfterTargets.map((p) => {
+              return this.buildJobName(p);
+            })
+          ],
+          runsOn: ["ubuntu-latest"],
+          permissions: {
+            contents: import_workflows_model5.JobPermission.READ,
+            idToken: import_workflows_model5.JobPermission.WRITE,
+            pullRequests: import_workflows_model5.JobPermission.WRITE
+          },
+          ...this.environmentName ? { environment: this.environmentName } : void 0,
+          concurrency: deployJobName,
+          if: jobCondition,
+          steps: [...this.deploySteps(target)]
+        });
+      }
       if (this.diffOptions.enabled) {
         const diffJobName = this.buildDiffJobName(target);
         this.buildWorkflow.addPostBuildJob(diffJobName, {
@@ -43713,6 +44030,7 @@ export const collections = {
   AwsDeploymentConfig,
   AwsDeploymentTarget,
   AwsTeardownWorkflow,
+  BUILD_ARTIFACT_NAME,
   BUILT_IN_BUNDLES,
   BUNDLE_OWNERSHIP,
   CDK_BOOTSTRAP_DEFAULTS_BY_STAGE,
@@ -43811,7 +44129,9 @@ export const collections = {
   MONOREPO_LAYOUT,
   MonorepoProject,
   Nvmrc,
+  PERMISSION_BACKUP_FILE,
   PHASE_LABEL_TYPE_MAP,
+  PLAN_RUN_ID_INPUT,
   PROD_DEPLOY_NAME,
   PROGRESS_FILES_FORMAT_VALUES,
   PnpmWorkspace,
@@ -43845,6 +44165,7 @@ export const collections = {
   TypeScriptConfig,
   TypeScriptProject,
   UNKNOWN_TYPE_FALLBACK_TIER,
+  VALIDATE_PLAN_JOB_ID,
   VALID_PRIORITY_VALUES,
   VALID_STATUS_VALUES,
   VERSION,
@@ -43989,6 +44310,7 @@ export const collections = {
   renderNextRequirementIdProcedure,
   renderPhaseTypeInvariantSection,
   renderPhaseTypeInvariantShellHelpers,
+  renderPlanValidationScript,
   renderPriorityRulesSection,
   renderProgressFileName,
   renderProgressFilePath,