feat: generate and serve OpenAPI/Swagger spec (#55)

.github/scripts/sync-chart-appversion.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: sync-chart-appversion.sh <engine-version>
+# Example: sync-chart-appversion.sh 0.4.1
+
+ENGINE_VERSION="$1"
+CHART_FILE="packages/helm-chart/Chart.yaml"
+
+if [[ ! -f "$CHART_FILE" ]]; then
+  echo "ERROR: $CHART_FILE not found"
+  exit 1
+fi
+
+sed -i "s/^appVersion:.*/appVersion: \"${ENGINE_VERSION}\"/" "$CHART_FILE"
+echo "Updated $CHART_FILE appVersion to $ENGINE_VERSION"

.github/workflows/claude.yml

@@ -25,7 +25,7 @@ jobs:
     timeout-minutes: 30
     permissions:
       contents: read
-      pull-requests: read
+      pull-requests: write
       issues: read
       id-token: write
       actions: read
@@ -42,3 +42,21 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           additional_permissions: |
             actions: read
+
+      - name: Request CodeRabbit re-review
+        if: >-
+          steps.claude.outcome == 'success' && (
+            github.event.issue.pull_request ||
+            github.event_name == 'pull_request_review_comment' ||
+            github.event_name == 'pull_request_review'
+          )
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: >-
+            ${{
+              github.event.issue.number ||
+              github.event.pull_request.number
+            }}
+        run: |
+          gh pr comment "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" \
+            --body "@coderabbitai review"

.github/workflows/engine-ci.yml

@@ -60,7 +60,16 @@ jobs:
       - name: Install govulncheck
         run: go install golang.org/x/vuln/cmd/govulncheck@latest
       - name: Run govulncheck
-        run: govulncheck ./...
+        run: |
+          # GO-2026-4887 and GO-2026-4883 are in docker/docker (testcontainers test dep only).
+          # Fixed in: N/A — no upstream fix available. Remove exclusions when a patched release ships.
+          OUTPUT=$(govulncheck ./... 2>&1 || true)
+          echo "$OUTPUT"
+          ACTIONABLE=$(echo "$OUTPUT" | grep -E '^Vulnerability #[0-9]+:' | grep -vE 'GO-2026-4887|GO-2026-4883' || true)
+          if [ -n "$ACTIONABLE" ]; then
+            echo "FAIL: unfixed actionable vulnerabilities found"
+            exit 1
+          fi
 
   gosec:
     name: Gosec
@@ -74,3 +83,24 @@ jobs:
         run: go install github.com/securego/gosec/v2/cmd/gosec@latest
       - name: Run gosec
         run: gosec -exclude=G101,G104,G112,G115,G117,G202,G204,G301,G304,G306,G404,G703,G705,G706 ./...
+
+  spec:
+    name: Spec Freshness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+      - name: Install swag
+        run: go install github.com/swaggo/swag/cmd/swag@v1.16.6
+      - name: Regenerate spec
+        run: |
+          swag init \
+            -g docs.go \
+            --dir internal/server,internal/workflow,internal/budget \
+            --output internal/server/docs \
+            --outputTypes json,yaml \
+            --parseInternal
+      - name: Check for drift
+        run: git diff --exit-code internal/server/docs/

.github/workflows/release-engine.yml

@@ -0,0 +1,66 @@
+name: Release Engine
+
+on:
+  push:
+    tags:
+      - 'engine/v*'
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    name: Build and Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Set goreleaser tag
+        run: |
+          # Strip "engine/" prefix so goreleaser sees a clean semver tag
+          TAG="${GITHUB_REF#refs/tags/engine/}"
+          echo "GORELEASER_CURRENT_TAG=${TAG}" >> "$GITHUB_ENV"
+
+      - name: Run goreleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          version: '~> v2'
+          args: release --clean
+          workdir: packages/engine
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  trivy:
+    name: Trivy Scan
+    runs-on: ubuntu-latest
+    needs: release
+    steps:
+      - name: Extract version
+        id: vars
+        run: |
+          TAG="${GITHUB_REF#refs/tags/engine/v}"
+          echo "version=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@0.28.0
+        with:
+          image-ref: "ghcr.io/dvflw/mantle:${{ steps.vars.outputs.version }}"
+          format: table
+          exit-code: '1'
+          severity: CRITICAL,HIGH

.github/workflows/release-helm.yml

@@ -0,0 +1,49 @@
+name: Release Helm Chart
+
+on:
+  push:
+    tags:
+      - 'helm-chart/v*'
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  publish:
+    name: Package and Publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: azure/setup-helm@v4
+
+      - name: Log in to GHCR
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | helm registry login ghcr.io --username ${{ github.actor }} --password-stdin
+
+      - name: Extract version
+        id: vars
+        run: |
+          TAG="${GITHUB_REF#refs/tags/helm-chart/v}"
+          echo "version=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Package chart
+        run: helm package packages/helm-chart/
+
+      - name: Push to OCI registry
+        run: helm push mantle-${{ steps.vars.outputs.version }}.tgz oci://ghcr.io/dvflw/helm-charts
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+          VERSION: ${{ steps.vars.outputs.version }}
+        run: |
+          gh release create "${TAG}" \
+            --title "Helm Chart ${VERSION}" \
+            --notes "Published to \`oci://ghcr.io/dvflw/helm-charts/mantle:${VERSION}\`
+
+          Install with:
+          \`\`\`bash
+          helm install mantle oci://ghcr.io/dvflw/helm-charts/mantle --version ${VERSION}
+          \`\`\`"

.github/workflows/release-please.yml

@@ -0,0 +1,37 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  version:
+    name: Version Packages
+    runs-on: ubuntu-latest
+    # Skip if this push is the Version PR merge itself (prevents loop)
+    if: "!startsWith(github.event.head_commit.message, 'ci: version packages')"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+
+      - name: Create or update Version PR
+        uses: changesets/action@v1
+        with:
+          version: bun run version
+          commit: "ci: version packages"
+          title: "ci: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-tags.yml

@@ -0,0 +1,97 @@
+name: Release Tags
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    name: Create Package Tags
+    runs-on: ubuntu-latest
+    # Only run on Version PR merges
+    if: "startsWith(github.event.head_commit.message, 'ci: version packages')"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Detect version bumps
+        id: bumps
+        run: |
+          ENGINE_BUMPED=false
+          HELM_BUMPED=false
+          SITE_BUMPED=false
+
+          # Check engine version bump
+          ENGINE_OLD=$(git show HEAD~1:packages/engine/package.json 2>/dev/null | jq -r '.version' 2>/dev/null || echo "")
+          ENGINE_NEW=$(jq -r '.version' packages/engine/package.json)
+          if [[ -n "$ENGINE_OLD" && "$ENGINE_OLD" != "$ENGINE_NEW" ]]; then
+            echo "Engine version bumped: $ENGINE_OLD -> $ENGINE_NEW"
+            ENGINE_BUMPED=true
+          fi
+
+          # Check helm-chart version bump
+          HELM_OLD=$(git show HEAD~1:packages/helm-chart/package.json 2>/dev/null | jq -r '.version' 2>/dev/null || echo "")
+          HELM_NEW=$(jq -r '.version' packages/helm-chart/package.json)
+          if [[ -n "$HELM_OLD" && "$HELM_OLD" != "$HELM_NEW" ]]; then
+            echo "Helm chart version bumped: $HELM_OLD -> $HELM_NEW"
+            HELM_BUMPED=true
+          fi
+
+          # Check site version bump
+          SITE_OLD=$(git show HEAD~1:packages/site/package.json 2>/dev/null | jq -r '.version' 2>/dev/null || echo "")
+          SITE_NEW=$(jq -r '.version' packages/site/package.json)
+          if [[ -n "$SITE_OLD" && "$SITE_OLD" != "$SITE_NEW" ]]; then
+            echo "Site version bumped: $SITE_OLD -> $SITE_NEW"
+            SITE_BUMPED=true
+          fi
+
+          echo "engine_bumped=${ENGINE_BUMPED}" >> "$GITHUB_OUTPUT"
+          echo "engine_version=${ENGINE_NEW}" >> "$GITHUB_OUTPUT"
+          echo "helm_bumped=${HELM_BUMPED}" >> "$GITHUB_OUTPUT"
+          echo "helm_version=${HELM_NEW}" >> "$GITHUB_OUTPUT"
+          echo "site_bumped=${SITE_BUMPED}" >> "$GITHUB_OUTPUT"
+          echo "site_version=${SITE_NEW}" >> "$GITHUB_OUTPUT"
+
+      - name: Sync Chart.yaml appVersion
+        if: steps.bumps.outputs.engine_bumped == 'true'
+        run: |
+          .github/scripts/sync-chart-appversion.sh "${{ steps.bumps.outputs.engine_version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add packages/helm-chart/Chart.yaml
+          git commit -m "ci: sync Chart.yaml appVersion to ${{ steps.bumps.outputs.engine_version }}"
+          git push
+
+      - name: Create and push tags
+        run: |
+          TAGGED=""
+
+          if [[ "${{ steps.bumps.outputs.engine_bumped }}" == "true" ]]; then
+            git tag "engine/v${{ steps.bumps.outputs.engine_version }}"
+            TAGGED="$TAGGED engine/v${{ steps.bumps.outputs.engine_version }}"
+          fi
+
+          if [[ "${{ steps.bumps.outputs.helm_bumped }}" == "true" ]]; then
+            git tag "helm-chart/v${{ steps.bumps.outputs.helm_version }}"
+            TAGGED="$TAGGED helm-chart/v${{ steps.bumps.outputs.helm_version }}"
+          fi
+
+          if [[ "${{ steps.bumps.outputs.site_bumped }}" == "true" ]]; then
+            git tag "site/v${{ steps.bumps.outputs.site_version }}"
+            TAGGED="$TAGGED site/v${{ steps.bumps.outputs.site_version }}"
+          fi
+
+          if [[ -n "$TAGGED" ]]; then
+            echo "Pushing tags:$TAGGED"
+            git push origin --tags
+          else
+            echo "No version bumps detected"
+          fi