grada-run 0.0.2 → 0.32.0

package/.github/workflows/deploy-docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths: ['apps/docs/**']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm run build
+        working-directory: apps/docs
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/iac-validation.yml

@@ -0,0 +1,303 @@
+name: IaC Validation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        framework: [nestjs, nextjs, nuxt, node, svelte, static, python, django, rails, go]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scaffold app (${{ matrix.framework }})
+        env:
+          CI_MOCK_AWS: 'true'
+          DO_NOT_TRACK: '1'
+        run: |
+          TMPROOT=$(mktemp -d)
+          APP_DIR="$TMPROOT/test-app-${{ matrix.framework }}"
+          mkdir -p "$APP_DIR"
+          echo "GENERATED_DIR=$APP_DIR" >> "$GITHUB_ENV"
+          cd "$APP_DIR"
+          node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=${{ matrix.framework }}
+
+      - name: Terraform Compile
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: |
+          terraform init -backend=false
+          terraform validate
+
+      - name: Init TFLint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint --init
+
+      - name: Terraform Lint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint
+
+      - name: DevSecOps Scan (IaC & Filesystem)
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25
+        with:
+          scan-type: 'fs'
+          scan-ref: ${{ env.GENERATED_DIR }}
+          format: 'table'
+          output: 'trivy-fs-results.txt'
+          severity: 'HIGH,CRITICAL'
+          exit-code: '0'
+
+      - name: Build Container Image
+        working-directory: ${{ env.GENERATED_DIR }}
+        run: |
+          awk '
+            /^COPY/ { next }
+            /^RUN/ {
+              if ($0 ~ /apk |apt-get |apt |addgroup |adduser |groupadd |useradd |gem install |mkdir |chown |rm /) {
+                print $0
+                skip = 0
+              } else {
+                skip = 1
+              }
+              next
+            }
+            {
+              if (skip) {
+                # If the line does NOT end with a backslash, the skipped block is over
+                if ($0 !~ /\\ *$/) skip = 0
+              } else {
+                print $0
+              }
+            }
+          ' Dockerfile > Dockerfile.tmp && mv Dockerfile.tmp Dockerfile
+          
+          # Print the patched Dockerfile to the logs for easy debugging
+          echo "Patched Dockerfile:"
+          cat Dockerfile
+          echo "-------------------"
+          
+          docker build -t test-app-${{ matrix.framework }}:latest .
+
+      - name: DevSecOps Scan (Container Image)
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25
+        with:
+          image-ref: 'test-app-${{ matrix.framework }}:latest'
+          format: 'table'
+          output: 'trivy-image-results.txt'
+          severity: 'HIGH,CRITICAL'
+          exit-code: '0'
+
+      - name: Publish Trivy Summary to GitHub Actions UI
+        if: always()
+        run: |
+          echo "### 🏗️ Terraform Misconfiguration Scan (${{ matrix.framework }})" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`text" >> $GITHUB_STEP_SUMMARY
+          if [ -f trivy-fs-results.txt ]; then cat trivy-fs-results.txt >> $GITHUB_STEP_SUMMARY; else echo "Scan failed or skipped."; fi
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          echo "### 🛡️ Container Security Scan Results (${{ matrix.framework }})" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`text" >> $GITHUB_STEP_SUMMARY
+          if [ -f trivy-image-results.txt ]; then cat trivy-image-results.txt >> $GITHUB_STEP_SUMMARY; else echo "Container scan failed or skipped."; fi
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+  validate-addons:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scaffold backend with all addons
+        env:
+          CI_MOCK_AWS: 'true'
+          DO_NOT_TRACK: '1'
+        run: |
+          TMPROOT=$(mktemp -d)
+          APP_DIR="$TMPROOT/test-app-addons"
+          mkdir -p "$APP_DIR"
+          echo "GENERATED_DIR=$APP_DIR" >> "$GITHUB_ENV"
+          cd "$APP_DIR"
+          printf '{"scripts":{"db:migrate":"prisma migrate deploy"}}' > package.json
+          printf 'web: node index.js\nworker: node worker.js\n' > Procfile
+          node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=nestjs --needsDatabase \
+            --with storage:s3,db:dynamodb,db:redis,queue:sqs,ai:bedrock,email:ses,cron \
+            --domain example.com --zone-id Z1234567890ABC --setup-ci-migrate
+          node "$GITHUB_WORKSPACE/bin/cli.js" domain add example.com --zone-id Z1234567890ABC
+          test -f terraform/ses.tf
+          test -f terraform/bedrock.tf
+          test -f terraform/cron.tf
+          test -f terraform/worker.tf
+          test -f terraform/domain.tf
+          grep -q 'grada:db-migrate-start' .github/workflows/deploy.yml
+
+      - name: Terraform Compile
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: |
+          terraform init -backend=false
+          terraform validate
+
+      - name: Init TFLint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint --init
+
+      - name: Terraform Lint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint
+
+  validate-engines:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        db-engine: [mysql, aurora-postgresql]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scaffold app (${{ matrix.db-engine }})
+        env:
+          CI_MOCK_AWS: 'true'
+          DO_NOT_TRACK: '1'
+        run: |
+          TMPROOT=$(mktemp -d)
+          APP_DIR="$TMPROOT/test-app-engine-${{ matrix.db-engine }}"
+          mkdir -p "$APP_DIR"
+          echo "GENERATED_DIR=$APP_DIR" >> "$GITHUB_ENV"
+          cd "$APP_DIR"
+          node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=node --needsDatabase --db-engine ${{ matrix.db-engine }}
+          test -f terraform/database.tf
+
+      - name: Terraform Compile
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: |
+          terraform init -backend=false
+          terraform validate
+
+      - name: Init TFLint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint --init
+
+      - name: Terraform Lint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint
+  validate-lambda:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - name: base
+            scaffold: node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=node --target lambda
+            assert: test -f terraform/main.tf
+          - name: aurora-addons-domain
+            scaffold: |
+              printf '{"scripts":{"db:migrate":"prisma migrate deploy"}}' > package.json
+              printf 'web: node index.js\n' > Procfile
+              node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=node --target lambda --needsDatabase --db-engine aurora-postgresql \
+                --with storage:s3,db:dynamodb,db:redis,queue:sqs,ai:bedrock,email:ses,cron \
+                --domain example.com --zone-id Z1234567890ABC --setup-ci-migrate
+              node "$GITHUB_WORKSPACE/bin/cli.js" domain add example.com --zone-id Z1234567890ABC
+            assert: |
+              test -f terraform/database.tf
+              test -f terraform/ses.tf
+              test -f terraform/bedrock.tf
+              test -f terraform/cron.tf
+              test -f terraform/redis.tf
+              test -f terraform/domain.tf
+              test ! -f terraform/worker.tf
+              grep -q 'aws_lambda_function.app.arn' terraform/cron.tf
+              grep -q 'random_password' terraform/database.tf
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scaffold lambda app (${{ matrix.name }})
+        env:
+          CI_MOCK_AWS: 'true'
+          DO_NOT_TRACK: '1'
+        run: |
+          TMPROOT=$(mktemp -d)
+          APP_DIR="$TMPROOT/test-app-lambda-${{ matrix.name }}"
+          mkdir -p "$APP_DIR"
+          echo "GENERATED_DIR=$APP_DIR" >> "$GITHUB_ENV"
+          cd "$APP_DIR"
+          ${{ matrix.scaffold }}
+          ${{ matrix.assert }}
+
+      - name: Terraform Compile
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: |
+          terraform init -backend=false
+          terraform validate
+
+      - name: Init TFLint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint --init
+
+      - name: Terraform Lint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint

package/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish CLI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  validate:
+    uses: ./.github/workflows/iac-validation.yml
+    secrets: inherit
+
+  build-and-publish:
+    needs: [validate]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade NPM for OIDC
+        run: npm install -g npm@latest
+
+      - name: Inject Telemetry Key
+        run: sed -i "s/___POSTHOG_INGESTION_KEY___/${{ secrets.POSTHOG_KEY }}/g" src/core/telemetry.js
+        
+      - name: Install dependencies
+        run: npm install
+
+      # --- Phase 1: Static Generation Validation ---
+      - name: Run Unit & Snapshot Tests
+        run: npm test
+
+      # --- Phase 2: Execution & Security Validation ---
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Init TFLint
+        run: tflint --init
+
+      - name: Run TFLint across Terraform files
+        run: tflint --recursive || true
+
+      - name: Run Trivy IaC Config Scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'config'
+          scan-dir: '.'
+          format: 'table'
+          exit-code: '0' 
+      
+      # --- Phase 3: Publish ---
+      - name: Publish Primary Package (grada-run)
+        run: npm publish --provenance
+
+      - name: Publish Scoped Alias (@grada-run/grada)
+        run: |
+          npm pkg set name="@grada-run/grada"
+          npm publish --access public --provenance

package/.github/workflows/sync-bedrock-models.yml

@@ -0,0 +1,57 @@
+name: Sync Bedrock Model Catalog
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for AWS role configuration
+        id: guard
+        run: |
+          if [ -z "${{ vars.AWS_ROLE_ARN }}" ]; then
+            echo "Bedrock catalog sync skipped: set the AWS_ROLE_ARN repository variable to enable weekly syncs." >> "$GITHUB_STEP_SUMMARY"
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Configure AWS credentials
+        if: steps.guard.outputs.enabled == 'true'
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-2' }}
+
+      - name: Setup Node.js
+        if: steps.guard.outputs.enabled == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        if: steps.guard.outputs.enabled == 'true'
+        run: npm ci
+
+      - name: Sync bundled catalog
+        if: steps.guard.outputs.enabled == 'true'
+        run: npm run sync:bedrock-models
+
+      - name: Open catalog update PR
+        if: steps.guard.outputs.enabled == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: chore/sync-bedrock-models
+          commit-message: 'chore(bedrock): sync model catalog'
+          title: 'chore(bedrock): sync AWS Bedrock model catalog'
+          body: Automated weekly refresh of `src/data/bedrock-models.json` from live AWS Bedrock data.

package/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Vitest Suite
+        run: npm test
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Init TFLint
+        run: tflint --init
+
+      - name: Run TFLint across Terraform files
+        run: tflint --recursive || true
+
+      - name: Run Trivy IaC Config Scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'config'
+          scan-dir: '.'
+          format: 'table'
+          exit-code: '0' # Set to '1' to block PRs on Trivy findings once baselined

package/.muserules

@@ -0,0 +1,31 @@
+# Grada: AI Agent Core Directives
+
+## 1. Architectural Boundaries
+- When scaffolding or managing a generated user project, you are strictly forbidden from modifying the user's application code. *(Note: When working on the Grada CLI codebase itself, modifying our `src/` directory is the entire job and is fully permitted).*
+- All Dockerfiles must remain at **0 CVEs**. Use multi-stage builds and strip package managers from runtime images to maintain this. Do not introduce unvetted packages.
+- All AWS IAM configurations must use OIDC. Never generate long-lived IAM access keys.
+
+## 2. Tech Stack & Formatting
+- **AWS Integration:** Use the `@aws-sdk/client-*` (v3) libraries for programmatic cloud interactions by default. Spawning the `aws` CLI is permitted for interactive terminal sessions (e.g., ECS Exec) and established programmatic helpers (e.g., ECR seeding, `status`, `diagnose`) where it is already heavily utilized or a clean SDK equivalent is lacking.
+- **Testing:** Use `vitest` for all unit and snapshot testing. Extract shared test mocks to `tests/helpers/` (create this directory if it does not yet exist).
+- Always append new tests to the corresponding existing `.test.js` file rather than creating fragmented test files for new functions within the same module.
+- **Terminal UI:** Use `picocolors` and `@clack/prompts` for all CLI output. Standardize on green for success, yellow for warnings, red for errors, and cyan for info/waiting.
+- **Telemetry:** Ensure `trackEvent` is called for key user actions and `flushTelemetry` is awaited before exiting.
+
+## 3. Workflow
+- **Analyze Before Implementing [CRITICAL]:** For specifications, migrations, and multi-file changes, do not implement immediately. Always thoroughly analyze the prompt against the existing codebase first to confirm there are no conflicts or unaddressed edge-cases. Outline any questions or inconsistencies before proceeding. *(Exception: For trivial single-point tasks, or if the user explicitly instructs you to "skip analysis" or "implement now," you may implement immediately).*
+- Read the relevant `specs/` document before writing any code.
+- **Strictly Headless Tests:** All Vitest tests must run cleanly in CI. You must aggressively mock `@clack/prompts`, `child_process.spawn`, and all AWS SDK clients to prevent the test suite from hanging on user input or attempting real network calls.
+- **CI parity:** GitHub Actions sets `CI=true` and Vitest workers run with `FORCE_COLOR=1` (via `vitest.config.js`), which activates ANSI escape sequences in `picocolors` even when `process.stdout.isTTY` is false. Any test asserting on strings styled with `picocolors` must either strip ANSI codes using `stripVTControlCharacters` from `node:util` or avoid matching across styled/unstyled boundaries.
+- Run `npm test` continuously to verify your work.
+- Do not conclude your task until the test suite passes completely.
+
+## 4. Documentation & Communication
+- **Audience First:** Write all READMEs, documentation, and release notes for the **end-user**, not the backend engineer. 
+- **Focus on Value:** Emphasize *what* the change does for the user (e.g., "Enhanced security," "Faster deployments") rather than *how* it was implemented under the hood.
+- **Hide the Wiring:** Do not explain deep technical refactors, regex changes, or script adjustments in user-facing docs unless they require the user to change their own behavior. Keep it concise, accessible, and benefit-driven.
+
+## 5. Terminal UI & Viewport Ergonomics
+- **Target viewport:** Users typically run the CLI inside an IDE bottom terminal panel (bottom 1/4 to 1/3 of a fullscreen window: ~10–15 visible rows, ~85–100 columns wide).
+- **Density budget:** Every Clack `note` box, summary table, or command output block must balance clarity with high vertical and horizontal density: aim for <= 12–14 lines tall and <= 88–90 characters wide per line so boxes never wrap or scroll off-screen before a confirmation prompt.
+- **No repeated lists:** Never repeat the same list of items twice inside a single box (e.g., in both a topology tree and a verbose footer list). Keep verbose prose breakdowns in standalone command outputs (`add`, `diagnose`) or generated markdown docs (`GRADA.md`), and use compact 1-line summaries inside pre-flight/status boxes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grada-run (https://github.com/grada-run)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.