Migrate web service from Serverless Framework to AWS SAM

.github/workflows/web.yml

@@ -4,34 +4,34 @@ on:
     branches: [master]
     paths:
       - 'tagbot/web/**'
-      - 'serverless.yml'
-      - 'package.json'
-      - 'package-lock.json'
+      - 'template.yaml'
+      - 'samconfig.toml'
+      - 'pyproject.toml'
+      - 'poetry.lock'
       - 'requirements.txt'
       - '.github/workflows/web.yml'
   pull_request:
     paths:
       - 'tagbot/web/**'
-      - 'serverless.yml'
-      - 'package.json'
-      - 'package-lock.json'
+      - 'template.yaml'
+      - 'samconfig.toml'
+      - 'pyproject.toml'
+      - 'poetry.lock'
       - 'requirements.txt'
       - '.github/workflows/web.yml'
 jobs:
   check:
     runs-on: ubuntu-slim
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
-        with:
-          node-version: '20'
-          cache: 'npm'
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          python-version: '3.11'
-      - run: npm ci
-      - run: pip install -r requirements.txt
-      - name: Validate serverless config
-        run: npx serverless package --stage dev
-        env:
-          GITHUB_TOKEN: dummy
+          python-version: '3.12'
+      - run: pip install poetry poetry-plugin-export
+      - name: Check requirements.txt is current
+        run: |
+          poetry export --extras web --output requirements.txt.check
+          diff requirements.txt requirements.txt.check
+      - uses: aws-actions/setup-sam@d78e1a4a9656d3b223e59b80676a797f20093133 # v2
+      - run: sam validate --lint
+      - run: sam build

.gitignore

@@ -2,9 +2,9 @@
 .mypy_cache/
 .pytest_cache/
 .requirements/
-.serverless/
+.aws-sam/
+packaged.yaml
 __pycache__/
 htmlcov/
-node_modules/
 tagbot.egg-info/
 .venv/

DEVGUIDE.md

@@ -89,49 +89,55 @@ When auto-tagging fails due to workflow file changes or other manual interventio
 
 ## Deploying the Web Service
 
-The web service runs on AWS Lambda via Serverless Framework.
+The web service runs on AWS Lambda via AWS SAM.
 
 ### Prerequisites
 
-- Node.js and npm
+- AWS SAM CLI (`brew install aws-sam-cli` or `pip install aws-sam-cli`)
 - AWS credentials with deployment permissions
 - Docker (for building Linux-compatible packages on macOS)
 
 ### Setup
 
 ```bash
-npm install
 aws configure --profile julia_tagbot  # region: us-east-1
 ```
 
 ### Deployment
 
 ```bash
 # Production (with custom domain julia-tagbot.com)
-GITHUB_TOKEN="ghp_..." npx serverless deploy --stage prod --aws-profile julia_tagbot
-
-# Dev (no custom domain)
-npx serverless deploy --stage dev --aws-profile julia_tagbot
+sam build && sam deploy --config-env prod \
+  --parameter-overrides "TagbotCommit=$(git rev-parse HEAD)" \
+  --profile julia_tagbot
+
+# Dev
+sam build && sam deploy \
+  --parameter-overrides "TagbotCommit=$(git rev-parse HEAD)" \
+  --profile julia_tagbot
 ```
 
 ### Configuration
 
 | File | Purpose |
 |------|---------|
-| `serverless.yml` | Lambda functions, AWS config |
+| `template.yaml` | SAM template: Lambda functions, API Gateway, IAM |
+| `samconfig.toml` | Deploy config per environment |
 | `requirements.txt` | Python deps for Lambda (keep in sync with pyproject.toml) |
-| `package.json` | Serverless plugins |
 
-**Environment variables** (in serverless.yml):
-- `GITHUB_TOKEN` - Access to TagBotErrorReports repo
-- `TAGBOT_REPO` - Main repo (default: JuliaRegistries/TagBot)
-- `TAGBOT_ISSUES_REPO` - Error reports repo (default: JuliaRegistries/TagBotErrorReports)
+**Parameters** (in template.yaml, pass via `--parameter-overrides`):
+- `GithubTokenParam` - SSM parameter name for the GitHub token (default: `/tagbot/github-token`)
+- `TagbotRepo` - Main repo (default: JuliaRegistries/TagBot)
+- `TagbotIssuesRepo` - Error reports repo (default: JuliaRegistries/TagBotErrorReports)
+- `TagbotCommit` - Git commit SHA shown on index page (default: unknown)
+
+The GitHub token is stored in SSM Parameter Store as a SecureString at `/tagbot/github-token` and read at runtime by the reports Lambda.
 
 ### Troubleshooting
 
-**Missing Python modules**: Check `requirements.txt`, ensure `serverless-python-requirements` installed, try `rm -rf .requirements .serverless`
+**Missing Python modules**: Check `requirements.txt`, try `rm -rf .aws-sam/`
 
-**Broken symlinks**: `find . -maxdepth 1 -type l ! -name "AGENTS.md" -delete`
+**Build issues**: `sam build --use-container` to build in a Docker container matching the Lambda runtime
 
 ### Checking Logs
 
@@ -159,7 +165,7 @@ Or view in [AWS Console](https://console.aws.amazon.com/cloudwatch/home?region=u
 
 | Item | Value |
 |------|-------|
-| Language | Python 3.12+ (Docker uses 3.14, Lambda uses 3.11) |
+| Language | Python 3.12+ (Docker uses 3.14, Lambda uses 3.12) |
 | Formatter | black |
 | Linter | flake8 |
 | Type Checker | mypy (stubs in `stubs/`) |