v0.6.7

.cursor/skills/release-qa/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: release-qa
+description: |
+  Runs pre-release QA for Psoxy: verify release refs (rc-vX.Y.Z → vX.Y.Z), apply AWS and GCP
+  dev examples sequentially, run test-all.sh for both, summarize connector status, create the
+  rc-to-main release PR, and post QA results on that PR. Use when cutting a release, running
+  release QA, merging rc-v to main, or when the user asks to test connectors before publish.
+---
+
+# Release QA
+
+End-to-end release QA for the Psoxy repo on an `rc-vX.Y.Z` branch that has been prepared for release (`./tools/release/prep.sh rc-vX.Y.Z vX.Y.Z`).
+
+## Prerequisites
+
+- On branch `rc-vX.Y.Z` with release refs already updated to `vX.Y.Z`
+- Authenticated: `aws`, `gcloud` (+ ADC), and `az` (if `msft_tenant_id` in tfvars)
+- `gh` CLI authenticated
+- `terraform` available in PATH
+- Repo root as working directory unless noted
+
+Derive `RELEASE` from the branch (`rc-v0.6.6` → `v0.6.6`) or accept it from the user.
+
+## Workflow checklist
+
+```
+Release QA progress:
+- [ ] Step 1: Verify release refs
+- [ ] Step 2: Apply AWS example (review plan log)
+- [ ] Step 3: Apply GCP example (review plan log)
+- [ ] Step 4: Run test-all on AWS
+- [ ] Step 5: Run test-all on GCP
+- [ ] Step 6: Summarize connector results
+- [ ] Step 7: Create release PR (rc-to-main)
+- [ ] Step 8: Post PR comment + check off test plan
+```
+
+Run steps **sequentially**. Do not apply AWS and GCP in parallel.
+
+---
+
+## Step 1: Verify release refs
+
+If refs are not yet updated, run prep first (interactive):
+
+```bash
+./tools/release/prep.sh rc-vX.Y.Z vX.Y.Z
+```
+
+Then verify:
+
+```bash
+./tools/release/qa/verify-release-refs.sh vX.Y.Z
+```
+
+Stop if verification fails. Fix with `prep.sh` or manual ref updates before continuing.
+
+---
+
+## Step 2–3: Apply dev examples (sequential)
+
+Use the non-interactive helper (runs `terraform plan` then `terraform apply`, logs both):
+
+```bash
+./tools/release/qa/apply-example.sh aws vX.Y.Z true
+# Review plan log printed path; confirm apply succeeded before continuing
+
+./tools/release/qa/apply-example.sh gcp vX.Y.Z true
+```
+
+Logs land in `infra/examples-dev/{aws,gcp}/YYYYMMDD_{aws|gcp}-vX.Y.Z-{plan,apply}.txt`.
+
+**Review the plan logs** and call out unexpected destroys/replacements before running tests.
+
+`force_bundle=true` rebuilds the JAR (appropriate for release QA after Java changes).
+
+---
+
+## Step 4–5: Run connector tests
+
+```bash
+./tools/release/qa/run-example-tests.sh aws vX.Y.Z
+./tools/release/qa/run-example-tests.sh gcp vX.Y.Z
+```
+
+Outputs: `infra/examples-dev/{aws,gcp}/YYYYMMDD_{aws|gcp}-vX.Y.Z-tests.txt`
+
+Tests can take several minutes each (Slack async, bulk uploads, llm-portal bucket polling).
+
+---
+
+## Step 6: Summarize connector state
+
+```bash
+./tools/release/qa/summarize-connector-tests.sh aws infra/examples-dev/aws/YYYYMMDD_aws-vX.Y.Z-tests.txt vX.Y.Z \
+  > /tmp/aws-qa-summary.md
+
+./tools/release/qa/summarize-connector-tests.sh gcp infra/examples-dev/gcp/YYYYMMDD_gcp-vX.Y.Z-tests.txt vX.Y.Z \
+  > /tmp/gcp-qa-summary.md
+```
+
+Each command also writes sidecar files:
+
+- `*.summary.md` — markdown tables + category breakdown
+- `*.checklist` — machine-readable pass/fail per test-plan category
+
+Status meanings:
+
+| Status | Meaning |
+|--------|---------|
+| **pass** | Health + API/bulk/webhook verification succeeded |
+| **partial** | Proxy healthy but upstream API rejected the call |
+| **fail** | Missing secrets/config or connection setup error |
+
+Test-plan categories (from `tools/release/test_plan.md`):
+
+| Category | Example connectors |
+|----------|-------------------|
+| Microsoft API | `azure-ad`, `outlook-cal`, `msft-teams` |
+| Google Workspace API | `gcal`, `gdirectory`, `google-chat`, `gmail`, `gemini-in-workspace-apps` |
+| Token-based API | `asana`, `slack-analytics`, `zoom`, `jira-cloud`, `github`, … |
+| API with async | `slack-analytics` |
+| Webhook collector | `llm-portal` |
+| Bulk connector | `hris`, `metrics`, `workdata-generic` |
+
+A category is checked off when **at least one** connector in that category passes (partial counts for PR checkboxes).
+
+Present the user a combined summary before opening the PR. Note credential gaps vs real regressions.
+
+---
+
+## Step 7: Create release PR
+
+Must be on `rc-vX.Y.Z`:
+
+```bash
+git checkout rc-vX.Y.Z
+./tools/release/rc-to-main.sh vX.Y.Z
+```
+
+`rc-to-main.sh` is partially interactive (`npm audit fix` prompt). Answer `y` to continue unless dependency changes need a separate PR.
+
+Capture the PR URL/number from script output.
+
+---
+
+## Step 8: Post results on the release PR
+
+```bash
+PR_NUMBER=...  # from rc-to-main.sh output
+
+./tools/release/qa/update-release-pr-results.sh \
+  "$PR_NUMBER" \
+  infra/examples-dev/aws/YYYYMMDD_aws-vX.Y.Z-tests.txt.checklist \
+  infra/examples-dev/gcp/YYYYMMDD_gcp-vX.Y.Z-tests.txt.checklist \
+  infra/examples-dev/aws/YYYYMMDD_aws-vX.Y.Z-tests.txt.summary.md \
+  infra/examples-dev/gcp/YYYYMMDD_gcp-vX.Y.Z-tests.txt.summary.md
+```
+
+This:
+
+1. Posts a PR comment with both AWS and GCP connector summaries
+2. Checks off `- [x]` items under `### AWS` and `### GCP` in the PR body for categories that passed (including partial)
+
+---
+
+## After merge
+
+Remind the user:
+
+```bash
+./tools/release/publish.sh vX.Y.Z
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `verify-release-refs.sh` fails | Run `./tools/release/prep.sh rc-vX.Y.Z vX.Y.Z` |
+| Apply auth errors | Re-run `./az-auth`, `aws sso login`, `gcloud auth application-default login` |
+| Connector fails with `missingConfigProperties` | Expected for unconfigured secrets; note in summary, not a proxy regression |
+| `msft-teams` 401 while `azure-ad` works | Azure Graph permissions/consent issue |
+| `rc-to-main.sh` branch error | Checkout `rc-vX.Y.Z` first |
+
+## Helper scripts
+
+| Script | Purpose |
+|--------|---------|
+| `tools/release/qa/verify-release-refs.sh` | Confirm rc → v ref migration |
+| `tools/release/qa/apply-example.sh` | Plan + apply with logs |
+| `tools/release/qa/run-example-tests.sh` | Run `test-all.sh`, capture output |
+| `tools/release/qa/summarize-connector-tests.sh` | Parse test output → markdown |
+| `tools/release/qa/update-release-pr-results.sh` | PR comment + checkbox update |

.github/workflows/codeql.yml

@@ -47,22 +47,24 @@ jobs:
             matrix:
                 include:
                     - language: java-kotlin
+                      category: java
                       build-mode: none # This mode only analyzes Java. Set this to 'autobuild' or 'manual' to analyze Kotlin too.
                     - language: javascript-typescript
+                      category: javascript
                       build-mode: none
         steps:
             - name: Checkout repository
               uses: actions/checkout@v4
 
-            -   name: Setup Java
-                if: matrix.language == 'java-kotlin'
-                uses: actions/setup-java@v4
-                with:
-                    java-version: '21'
-                    distribution: zulu
+            - name: Setup Java
+              if: matrix.language == 'java-kotlin'
+              uses: actions/setup-java@v4
+              with:
+                  java-version: '21'
+                  distribution: zulu
             # Initializes the CodeQL tools for scanning.
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@v3
+              uses: github/codeql-action/init@v4
               with:
                   languages: ${{ matrix.language }}
                   build-mode: ${{ matrix.build-mode }}
@@ -90,6 +92,6 @@ jobs:
                   exit 1
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@v3
+              uses: github/codeql-action/analyze@v4
               with:
-                  category: "/language:${{matrix.language}}"
+                  category: "/language:${{ matrix.category || matrix.language }}"

.github/workflows/link-checker.yml

@@ -0,0 +1,37 @@
+name: Link Checker
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**/*.md'
+      - 'lychee.toml'
+      - '.github/workflows/link-checker.yml'
+  pull_request:
+    paths:
+      - 'docs/**/*.md'
+      - 'lychee.toml'
+      - '.github/workflows/link-checker.yml'
+  workflow_dispatch:
+
+jobs:
+  link-checker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          fail: true
+          args: >-
+            --config lychee.toml
+            --exclude-loopback
+            --verbose
+            --no-progress
+            docs/
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -32,6 +32,10 @@ fi
 printf "${SUCCESS}Operation completed successfully.${NC}\n"
 ```
 
+## Release QA
+
+Before merging an `rc-vX.Y.Z` branch to `main`, follow [tools/release/release-qa.md](tools/release/release-qa.md). The orchestrator is `./tools/release/run-release-qa.sh vX.Y.Z`.
+
 ## Testing Conventions
 
 When modifying code in this repository, you should ensure that your changes pass our standardized tests. 

CHANGELOG.md

@@ -5,10 +5,13 @@ in each release's notes.
 
 Changes to be including in future/planned release notes will be added here.
 
-## [0.6.5]
+## [Unreleased]
+- `aws`/`gcp`: fix Terraform plan failure when `enable_remote_resources = true` but no artifacts bucket exists (e.g. with a prebuilt `deployment_bundle`). When remote resources are enabled, an artifacts bucket is now provisioned if one is not already created or provided via `artifacts_bucket_name` / `custom_artifacts_bucket_name`.
+
+## [0.6.5](https://github.com/Worklytics/psoxy/releases/tag/v0.6.5)
 - added `claude-enterprise-analytics` connector in **beta**; imports per-user daily activity, token usage, and cost data from the [Claude Enterprise Analytics API](https://support.claude.com/en/articles/13703965-claude-enterprise-analytics-api-reference-guide); see [docs/sources/anthropic/claude-enterprise-analytics/README.md](docs/sources/anthropic/claude-enterprise-analytics/README.md)
 
-## [0.6.4]
+## [0.6.4](https://github.com/Worklytics/psoxy/releases/tag/v0.6.4)
 - `aws`: consolidate IAM policies at the `aws-host` level to reduce per-connector policy/attachment churn (important for customers with low per-role IAM policy limits). PsoxyCaller now receives a single `CallerAccess` policy (lambda invoke, when applicable, plus read access to all provisioned output buckets: bulk sanitized, async, side-output, webhook, and lookup). Non-caller lookup-table accessor roles receive per-lookup `LookupBucketRead` policies scoped to their lookup bucket only. Bulk connector testing uses S3 bucket policies on each input/sanitized bucket granting the Terraform test principal upload/read/delete as needed, avoiding additional IAM policy attachments on the test role. **Upgrading customers should expect Terraform to destroy and recreate several IAM policies and attachments**; effective access should be unchanged, but we encourage reviewing the plan.
 
 ## [0.6.3](https://github.com/Worklytics/psoxy/releases/tag/v0.6.3)