grada-run 0.46.0 → 0.47.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -116,7 +116,7 @@ The interactive wizard will analyze your codebase, detect your framework, estima
116
116
  | [`domain`](./apps/docs/src/content/docs/cli/domain.md) | Attaches a custom domain with automated ACM TLS (Route 53 or external DNS). |
117
117
  | [`destroy`](./apps/docs/src/content/docs/cli/destroy.md) | Tears down AWS resources to stop billing (state bucket optionally retained). |
118
118
  | [`eject`](./apps/docs/src/content/docs/cli/eject.md) | Strips `grada` metadata, leaving pure Terraform and Actions files. |
119
- | [`--headless`](./apps/docs/src/content/docs/guides/headless.md) | Fully programmatic runs for CI/CD (`--target`, `--with`, `--db-engine`, `--setup-ci-migrate`, `--setup-ci-drift`, `--offline`). |
119
+ | [`--headless`](./apps/docs/src/content/docs/guides/headless.md) | Fully programmatic runs for CI/CD (`--target`, `--with`, `--db-engine`, `--setup-ci-migrate`, `--setup-ci-drift`, `--setup-ci-plan`, `--offline`). |
120
120
  | [`sync-ai`](./apps/docs/src/content/docs/cli/sync-ai.md) | Generates IDE assistant rules for your stack (Cursor, Copilot, Windsurf, Claude). |
121
121
  | [`mcp`](./apps/docs/src/content/docs/cli/mcp.md) | Serves the MCP server for AI agents (STDIO/HTTP) or installs editor config (`--install`). |
122
122
 
@@ -134,7 +134,8 @@ your-project/
134
134
  ├── .github/
135
135
  │ └── workflows/
136
136
  │ ├── deploy.yml # Keyless OIDC CI/CD deployment pipeline
137
- │ └── drift.yml # Scheduled IaC drift detection (opt-in via `--setup-ci-drift` or `drift --setup`)
137
+ │ ├── drift.yml # Scheduled IaC drift detection (opt-in via `--setup-ci-drift` or `drift --setup`)
138
+ │ └── plan.yml # Terraform plan comments on PRs (via `--setup-ci-plan`, on by default interactively)
138
139
  └── terraform/
139
140
  ├── main.tf # ECR repository + compute (ECS Cluster/Fargate Task, Lambda + API Gateway with `--target lambda`, or S3 + CloudFront with `--target static`)
140
141
  ├── network.tf # VPC, Public Subnets, ALB, and Security Groups
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "grada-run",
3
- "version": "0.46.0",
3
+ "version": "0.47.0",
4
4
  "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
5
5
  "engines": {
6
6
  "node": ">=18.0.0"
@@ -8,7 +8,7 @@ import { trackSuccess, setActiveCommandName, resetActiveCommandName } from '../c
8
8
  import { failCommand, failAwsError, failProjectNotInitialized, isProgrammaticCall, refuseUnknownFlags } from '../utils/command.js';
9
9
  import { parseFlags, normalizeOptions, normalizeArgv } from '../utils/args.js';
10
10
  import { resolveRegion, resolveProjectName, resolveCwd, readFileSafe } from '../utils/resolvers.js';
11
- import { atomicWriteFileSync } from '../utils/atomic-write.js';
11
+ import { renderCiWorkflow } from '../utils/ci-workflows.js';
12
12
 
13
13
  const __filename = fileURLToPath(import.meta.url);
14
14
  const __dirname = path.dirname(__filename);
@@ -44,17 +44,13 @@ export function extractRoleArn(deployYmlContent) {
44
44
  // Renders `templates/github/drift.yml` into the project. Shared by
45
45
  // `drift --setup` and `--setup-ci-drift`; never exits, never tracks.
46
46
  export function scaffoldDriftWorkflow(cwd = process.cwd(), { region, roleArn, force = false } = {}) {
47
- const template = fsSync.readFileSync(DRIFT_TEMPLATE_PATH, 'utf8');
48
- const rendered = template
49
- .replaceAll('{{REGION}}', region)
50
- .replaceAll('{{ROLE_ARN}}', roleArn);
51
- const targetPath = path.join(cwd, DRIFT_WORKFLOW_FILE);
52
- if (fsSync.existsSync(targetPath) && force !== true && force !== 'true') {
53
- return { ok: false, reason: 'exists', path: targetPath };
54
- }
55
- fsSync.mkdirSync(path.dirname(targetPath), { recursive: true });
56
- atomicWriteFileSync(targetPath, rendered, 'utf8');
57
- return { ok: true, path: targetPath };
47
+ return renderCiWorkflow({
48
+ templatePath: DRIFT_TEMPLATE_PATH,
49
+ region,
50
+ roleArn,
51
+ targetPath: path.join(cwd, DRIFT_WORKFLOW_FILE),
52
+ force,
53
+ });
58
54
  }
59
55
 
60
56
  // Condenses `terraform plan` output to the resource-change lines plus the
@@ -27,6 +27,7 @@ import { ADDON_REGISTRY, addonTargetDisposition, addonSupportedTargets } from '.
27
27
  import { validateAddonFlags, resolveAddonOptions, scaffoldAddon, DEFAULT_BEDROCK_MODEL } from './add.js';
28
28
  import { injectMigrationGate, injectPreviewMigrationGate } from './db/migrate.js';
29
29
  import { scaffoldDriftWorkflow } from './drift.js';
30
+ import { scaffoldPlanWorkflow } from '../utils/ci-workflows.js';
30
31
  import { trackEvent, flushTelemetry, getCliVersion, setActiveCommandName, resetActiveCommandName } from '../core/telemetry.js';
31
32
  import { failCommand } from '../utils/command.js';
32
33
  import { getFrameworkWarning } from '../utils/warnings.js';
@@ -609,6 +610,21 @@ async function mainStackMain(input = {}) {
609
610
  driftEnabled = driftAnswer === true;
610
611
  }
611
612
 
613
+ // Plan-on-PR: explicit flag wins, else offer. Defaults ON —
614
+ // reviewing infra changes before merge is the safe default.
615
+ const setupCiPlanFlag = initOptions.setupCiPlan === true;
616
+ let planEnabled = false;
617
+ if (setupCiPlanFlag) {
618
+ planEnabled = true;
619
+ } else if (isInteractive) {
620
+ const planAnswer = await confirm({
621
+ message: 'Post Terraform plans as PR comments (review infra changes before merge)?',
622
+ initialValue: true,
623
+ });
624
+ if (typeof planAnswer === 'symbol') process.exit(0);
625
+ planEnabled = planAnswer === true;
626
+ }
627
+
612
628
  // Addon selection: interactive multiselect, or explicit --with.
613
629
  let selectedAddons;
614
630
  if (isInteractive && !isStaticSite) {
@@ -937,6 +953,20 @@ async function mainStackMain(input = {}) {
937
953
  }
938
954
  }
939
955
 
956
+ if (planEnabled) {
957
+ // plan.yml rides the manifest + backup like drift.yml (R1):
958
+ // re-init backs the old file up and regenerates fresh (current
959
+ // role ARN) instead of silently keeping a stale copy.
960
+ const planned = scaffoldPlanWorkflow(dirConfig.targetDir, {
961
+ region: config.region,
962
+ roleArn: `arn:aws:iam::${awsAccountId}:role/${dirConfig.actualProjectName}${resourceSuffix}-github-actions-role`,
963
+ force: initOptions.force,
964
+ });
965
+ if (planned.ok) {
966
+ console.log(color.green('✅ Scaffolded .github/workflows/plan.yml (Terraform plan on PR)'));
967
+ }
968
+ }
969
+
940
970
  // 7b2. Restore preserved files over the fresh output, then record
941
971
  // content hashes of everything generated above so a later re-run can
942
972
  // distinguish pristine output from hand edits (F3), plus the intended
@@ -989,6 +1019,7 @@ async function mainStackMain(input = {}) {
989
1019
  detected_addons: Object.keys(ADDON_REGISTRY).filter((cap) => capabilities.addons[cap]?.detected === true),
990
1020
  migration_gate_enabled: migrationGateEnabled,
991
1021
  drift_detection_enabled: driftEnabled,
1022
+ plan_on_pr_enabled: planEnabled,
992
1023
  });
993
1024
 
994
1025
  s.stop('Infrastructure provisioned successfully!');
@@ -141,6 +141,7 @@ export function parseCliArgs(processArgs) {
141
141
  githubRepo: getValueFlag('github-repo'),
142
142
  setupCiMigrate: getBoolOrValueFlag('setup-ci-migrate'),
143
143
  setupCiDrift: getBoolFlag('setup-ci-drift') === true,
144
+ setupCiPlan: getBoolFlag('setup-ci-plan') === true,
144
145
  };
145
146
 
146
147
  // 5. Isolate positional commands (non-string elements are positionals;
@@ -33,7 +33,7 @@ function collectManifestFiles(targetDir) {
33
33
  // hand edits like deploy.yml — manifest them so re-init refuses
34
34
  // dirty trees and backs them up instead of silently overwriting or
35
35
  // leaving them stale (BUG-158).
36
- for (const rel of ['Dockerfile', 'preview.yml', 'teardown.yml', 'drift.yml'].map((name) => (
36
+ for (const rel of ['Dockerfile', 'preview.yml', 'teardown.yml', 'drift.yml', 'plan.yml'].map((name) => (
37
37
  name === 'Dockerfile' ? name : path.join('.github', 'workflows', name)
38
38
  ))) {
39
39
  if (fs.existsSync(path.join(targetDir, rel))) relPaths.push(rel);
@@ -226,7 +226,7 @@ export async function planExistingFiles(targetDir, { isHeadless = false, force =
226
226
  const tfPath = path.join(targetDir, 'terraform');
227
227
  const dockerfilePath = path.join(targetDir, 'Dockerfile');
228
228
  const wfPath = path.join(targetDir, '.github', 'workflows', 'deploy.yml');
229
- const extraWorkflows = ['preview.yml', 'teardown.yml', 'drift.yml']
229
+ const extraWorkflows = ['preview.yml', 'teardown.yml', 'drift.yml', 'plan.yml']
230
230
  .map((workflow) => path.join('.github', 'workflows', workflow))
231
231
  .filter((rel) => fs.existsSync(path.join(targetDir, rel)));
232
232
 
@@ -303,7 +303,7 @@ export async function executeBackup(targetDir, plan = {}) {
303
303
  ['terraform/', path.join(targetDir, 'terraform')],
304
304
  ['Dockerfile', path.join(targetDir, 'Dockerfile')],
305
305
  ['.github/workflows/deploy.yml', path.join(targetDir, '.github', 'workflows', 'deploy.yml')],
306
- ...['preview.yml', 'teardown.yml', 'drift.yml'].map((workflow) => {
306
+ ...['preview.yml', 'teardown.yml', 'drift.yml', 'plan.yml'].map((workflow) => {
307
307
  const rel = path.join('.github', 'workflows', workflow);
308
308
  return [rel, path.join(targetDir, rel)];
309
309
  }),
@@ -0,0 +1,38 @@
1
+ import fsSync from 'fs';
2
+ import path from 'path';
3
+ import { fileURLToPath } from 'url';
4
+ import { atomicWriteFileSync } from './atomic-write.js';
5
+
6
+ const __filename = fileURLToPath(import.meta.url);
7
+ const __dirname = path.dirname(__filename);
8
+
9
+ export const PLAN_TEMPLATE_PATH = path.join(__dirname, '../../templates/github/plan.yml');
10
+ export const PLAN_WORKFLOW_FILE = path.join('.github', 'workflows', 'plan.yml');
11
+
12
+ // Shared render-and-write core for generated CI workflows: substitutes
13
+ // the region + role ARN placeholders, refuses to overwrite without
14
+ // force, and writes atomically. Never exits, never tracks.
15
+ export function renderCiWorkflow({ templatePath, region, roleArn, targetPath, force = false } = {}) {
16
+ const template = fsSync.readFileSync(templatePath, 'utf8');
17
+ const rendered = template
18
+ .replaceAll('{{REGION}}', region)
19
+ .replaceAll('{{ROLE_ARN}}', roleArn);
20
+ if (fsSync.existsSync(targetPath) && force !== true && force !== 'true') {
21
+ return { ok: false, reason: 'exists', path: targetPath };
22
+ }
23
+ fsSync.mkdirSync(path.dirname(targetPath), { recursive: true });
24
+ atomicWriteFileSync(targetPath, rendered, 'utf8');
25
+ return { ok: true, path: targetPath };
26
+ }
27
+
28
+ // Renders `templates/github/plan.yml` into the project. Used by init's
29
+ // `--setup-ci-plan`; never exits, never tracks.
30
+ export function scaffoldPlanWorkflow(cwd = process.cwd(), { region, roleArn, force = false } = {}) {
31
+ return renderCiWorkflow({
32
+ templatePath: PLAN_TEMPLATE_PATH,
33
+ region,
34
+ roleArn,
35
+ targetPath: path.join(cwd, PLAN_WORKFLOW_FILE),
36
+ force,
37
+ });
38
+ }
@@ -0,0 +1,153 @@
1
+ name: Terraform Plan on PR
2
+
3
+ on:
4
+ # pull_request_target (not pull_request): this file comes from the base
5
+ # branch, so a fork PR cannot delete the same-repo guard below to reach
6
+ # the admin CI role (BUG-140). The PR head is checked out explicitly by
7
+ # SHA in the guarded step instead.
8
+ pull_request_target:
9
+ types: [opened, synchronize, reopened]
10
+ paths:
11
+ - 'terraform/**'
12
+
13
+ # One runner per PR: rapid pushes cancel superseded plans instead of
14
+ # overlapping runs on the same state.
15
+ concurrency:
16
+ group: plan-${{ github.event.pull_request.number }}
17
+ cancel-in-progress: true
18
+
19
+ env:
20
+ AWS_REGION: {{REGION}}
21
+
22
+ permissions:
23
+ id-token: write
24
+ contents: read
25
+ pull-requests: write # Required to post the plan comment
26
+
27
+ jobs:
28
+ terraform-plan:
29
+ name: Terraform Plan
30
+ # Same-repo PRs only: fork code must never execute with the admin CI
31
+ # role. Trustworthy because this file comes from base (see trigger
32
+ # above). Public repos needing fork plans should gate this job
33
+ # behind an environment with required reviewers instead of deleting
34
+ # the guard.
35
+ if: github.event.pull_request.head.repo.full_name == github.repository
36
+ runs-on: ubuntu-latest
37
+ timeout-minutes: 30
38
+
39
+ steps:
40
+ - name: Checkout PR head
41
+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
42
+ with:
43
+ # Pinned SHA (not a ref name): the exact head this event fired
44
+ # for, immune to ref moves between event and checkout.
45
+ ref: ${{ github.event.pull_request.head.sha }}
46
+
47
+ - name: Configure AWS credentials
48
+ id: aws-creds
49
+ uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
50
+ continue-on-error: true
51
+ with:
52
+ role-to-assume: {{ROLE_ARN}}
53
+ aws-region: ${{ env.AWS_REGION }}
54
+
55
+ # Plan-on-PR is a merge signal: a failed assume fails the run with
56
+ # the bootstrap pointer (deploy shape, BUG-138) — never green-silent.
57
+ - name: Interpret credential failure
58
+ if: steps.aws-creds.outcome == 'failure'
59
+ run: |
60
+ echo "::error::AWS credential assumption failed — if the stack was never provisioned, bootstrap it first (npx grada-run apply); otherwise check terraform/oidc.tf trust."
61
+ exit 1
62
+
63
+ - name: Setup Terraform
64
+ uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
65
+ with:
66
+ # The wrapper mangles -detailed-exitcode; raw codes (0/1/2) are the signal.
67
+ terraform_wrapper: false
68
+
69
+ - name: Terraform Init
70
+ working-directory: ./terraform
71
+ run: terraform init -input=false
72
+
73
+ # -detailed-exitcode: 0 = no changes, 1 = error, 2 = changes present.
74
+ # Exit 2 posts the plan and stays green — the comment is the signal.
75
+ # Exit 1 (plan ERROR) fails the job after the comment posts below.
76
+ - name: Terraform Plan
77
+ id: plan
78
+ working-directory: ./terraform
79
+ run: |
80
+ set +e
81
+ terraform plan -input=false -lock-timeout=5m -detailed-exitcode -no-color -out=tfplan > plan-full.txt 2>&1
82
+ EXITCODE=$?
83
+ echo "exitcode=$EXITCODE" >> "$GITHUB_OUTPUT"
84
+ if [ "$EXITCODE" != "1" ]; then
85
+ terraform show -no-color tfplan > plan.txt
86
+ else
87
+ cp plan-full.txt plan.txt
88
+ fi
89
+ # Exit 1 fails the job; the comment step still posts via its
90
+ # always() gate so the error lands on the PR, not just the log.
91
+ if [ "$EXITCODE" = "1" ]; then exit 1; fi
92
+
93
+ - name: Comment plan on PR
94
+ if: always() && steps.plan.outputs.exitcode != ''
95
+ uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
96
+ with:
97
+ script: |
98
+ const fs = require('fs');
99
+ const { owner, repo } = context.repo;
100
+ const marker = '<!-- grada-plan -->';
101
+ const exitcode = '${{ steps.plan.outputs.exitcode }}';
102
+ const runUrl = `https://github.com/${owner}/${repo}/actions/runs/${context.runId}`;
103
+ let plan = '';
104
+ try {
105
+ plan = fs.readFileSync('terraform/plan.txt', 'utf8');
106
+ } catch (error) {
107
+ plan = '(plan output unavailable)';
108
+ }
109
+ if (plan.length > 30000) {
110
+ plan = `${plan.slice(0, 30000)}\n... (truncated, see ${runUrl})`;
111
+ }
112
+ let summary = '';
113
+ if (exitcode === '2') {
114
+ const match = /^Plan:.*$/m.exec(plan);
115
+ summary = match ? match[0] : 'Plan: changes present';
116
+ } else if (exitcode === '1') {
117
+ summary = 'Plan: errored';
118
+ } else {
119
+ summary = 'No changes';
120
+ }
121
+ const heading = exitcode === '1' ? '## ❌ Terraform Plan Failed' : '## Terraform Plan';
122
+ const body = `${marker}\n${heading}\n\n**${summary}** ([workflow run](${runUrl})).\n\n<details><summary>Show Plan</summary>\n\n\`\`\`diff\n${plan}\n\`\`\`\n\n</details>`;
123
+ const { data: comments } = await github.rest.issues.listComments({
124
+ issue_number: context.issue.number,
125
+ owner: context.repo.owner,
126
+ repo: context.repo.repo,
127
+ });
128
+ const existing = comments.find((comment) => comment.body?.includes(marker));
129
+ if (existing) {
130
+ await github.rest.issues.updateComment({
131
+ owner: context.repo.owner,
132
+ repo: context.repo.repo,
133
+ comment_id: existing.id,
134
+ body,
135
+ });
136
+ } else {
137
+ await github.rest.issues.createComment({
138
+ issue_number: context.issue.number,
139
+ owner: context.repo.owner,
140
+ repo: context.repo.repo,
141
+ body,
142
+ });
143
+ }
144
+
145
+ # Fork PRs skip the privileged job above loudly instead of silently:
146
+ # no credentials are issued and no plan is posted.
147
+ fork-notice:
148
+ name: Fork PR notice
149
+ if: github.event.pull_request.head.repo.full_name != github.repository
150
+ runs-on: ubuntu-latest
151
+ timeout-minutes: 5
152
+ steps:
153
+ - run: echo "Terraform plan runs for same-repo pull requests only — fork PR #${{ github.event.pull_request.number }} skipped (no AWS credentials issued)."