@codedrifters/configulator 0.0.424 → 0.0.426

package/lib/index.mjs

@@ -41929,9 +41929,46 @@ import { merge as merge4 } from "ts-deepmerge";
 var import_utils11 = __toESM(require_lib());
 import { Component as Component22 } from "projen";
 import { BuildWorkflow } from "projen/lib/build";
-import { GitHub as GitHub5, WorkflowSteps as WorkflowSteps2 } from "projen/lib/github";
+import { GitHub as GitHub5, GithubWorkflow, WorkflowSteps as WorkflowSteps2 } from "projen/lib/github";
 import { JobPermission as JobPermission5 } from "projen/lib/github/workflows-model";
 
+// src/workflows/deploy-gate.ts
+var DEPLOY_GATE = {
+  /**
+   * Hold each deploy job behind a GitHub environment so its protection rules —
+   * required reviewers, wait timers, deployment branch policies — apply before
+   * the job is sent to a runner.
+   */
+  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();
+  if (gate === void 0) {
+    if (trimmed) {
+      throw new Error(
+        `${componentName} requires \`gate\` to be set when \`environmentName\` is supplied, got "${environmentName}" with no gate`
+      );
+    }
+    return void 0;
+  }
+  if (gate === DEPLOY_GATE.ENVIRONMENT && !trimmed) {
+    throw new Error(
+      `${componentName} requires a non-empty \`environmentName\` when \`gate\` is "${gate}"`
+    );
+  }
+  return trimmed;
+};
+
 // src/workflows/home-repository.ts
 var HOME_REPOSITORY_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 var renderHomeRepositoryCondition = (homeRepository, componentName) => {
@@ -41946,6 +41983,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";
@@ -42017,6 +42153,20 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
         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.
      *
@@ -42035,6 +42185,163 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
         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 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: JobPermission5.READ,
+          contents: JobPermission5.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: JobPermission5.READ,
+          contents: JobPermission5.READ,
+          idToken: JobPermission5.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.
@@ -42063,7 +42370,15 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
       }
       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,
@@ -42142,15 +42457,17 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
          * 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"
+            }
           }
-        }
+        ] : []
       ];
     };
     /**
@@ -42294,11 +42611,23 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
       (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
     };
+    this.environmentName = resolveEnvironmentGate(
+      options.gate,
+      options.environmentName,
+      "AwsDeployWorkflow"
+    );
     this.homeRepository = options.homeRepository;
     const homeRepositoryCondition = renderHomeRepositoryCondition(
       this.homeRepository,
@@ -42376,6 +42705,17 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
         ...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(
@@ -42386,24 +42726,31 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
         ...homeRepositoryCondition ? [homeRepositoryCondition] : [],
         ...branchFilterCondition ? [`(${branchFilterCondition})`] : []
       ].join(" && ") + " }}";
-      this.buildWorkflow.addPostBuildJob(deployJobName, {
-        name: `Deploy ${this.project.name} ${target.awsStageType}/${target.deploymentTargetRole}/${target.account}/${target.region}`,
-        needs: [
-          "build",
-          ...this.deployAfterTargets.map((p) => {
-            return this.buildJobName(p);
-          })
-        ],
-        runsOn: ["ubuntu-latest"],
-        permissions: {
-          contents: JobPermission5.READ,
-          idToken: JobPermission5.WRITE,
-          pullRequests: JobPermission5.WRITE
-        },
-        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: JobPermission5.READ,
+            idToken: JobPermission5.WRITE,
+            pullRequests: JobPermission5.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, {
@@ -42449,7 +42796,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends Component22 {
 
 // src/workflows/aws-teardown-workflow.ts
 import { Component as Component23 } from "projen";
-import { GitHub as GitHub6, GithubWorkflow } from "projen/lib/github";
+import { GitHub as GitHub6, GithubWorkflow as GithubWorkflow2 } from "projen/lib/github";
 import { JobPermission as JobPermission6 } from "projen/lib/github/workflows-model";
 var DEFAULT_TEARDOWN_BRANCH_PATTERNS = [
   "feat/*",
@@ -42514,7 +42861,7 @@ var AwsTeardownWorkflow = class extends Component23 {
       homeRepository,
       "AwsTeardownWorkflow"
     );
-    const workflow = new GithubWorkflow(github, "teardown-dev");
+    const workflow = new GithubWorkflow2(github, "teardown-dev");
     workflow.on({
       workflowDispatch: {},
       schedule: [
@@ -43312,6 +43659,7 @@ export {
   AwsDeploymentConfig,
   AwsDeploymentTarget,
   AwsTeardownWorkflow,
+  BUILD_ARTIFACT_NAME,
   BUILT_IN_BUNDLES,
   BUNDLE_OWNERSHIP,
   CDK_BOOTSTRAP_DEFAULTS_BY_STAGE,
@@ -43394,6 +43742,7 @@ export {
   DEFAULT_UNBLOCK_COMMENT_TEMPLATE,
   DEFAULT_UNBLOCK_DEPENDENTS_ENABLED,
   DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED,
+  DEPLOY_GATE,
   DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   GITHUB_ISSUE_TYPES,
   GITHUB_ISSUE_TYPE_BY_TITLE_PREFIX,
@@ -43409,7 +43758,9 @@ export {
   MONOREPO_LAYOUT,
   MonorepoProject,
   Nvmrc,
+  PERMISSION_BACKUP_FILE,
   PHASE_LABEL_TYPE_MAP,
+  PLAN_RUN_ID_INPUT,
   PROD_DEPLOY_NAME,
   PROGRESS_FILES_FORMAT_VALUES,
   PnpmWorkspace,
@@ -43443,6 +43794,7 @@ export {
   TypeScriptConfig,
   TypeScriptProject,
   UNKNOWN_TYPE_FALLBACK_TIER,
+  VALIDATE_PLAN_JOB_ID,
   VALID_PRIORITY_VALUES,
   VALID_STATUS_VALUES,
   VERSION,
@@ -43587,6 +43939,7 @@ export {
   renderNextRequirementIdProcedure,
   renderPhaseTypeInvariantSection,
   renderPhaseTypeInvariantShellHelpers,
+  renderPlanValidationScript,
   renderPriorityRulesSection,
   renderProgressFileName,
   renderProgressFilePath,
@@ -43624,6 +43977,7 @@ export {
   resolveBuildPolicy,
   resolveBundleAgentTiers,
   resolveDefaultAgentTier,
+  resolveEnvironmentGate,
   resolveIssueDefaults,
   resolveIssueTemplates,
   resolveModelAlias,