@se-studio/skills 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.4.3
+
+### Patch Changes
+
+- Document SSG guardrails (Biome, route-build-policy, validate-build-routes) in se-marketing-sites-smoke-test-setup skill.
+
 ## 1.4.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/se-marketing-sites-smoke-test-setup/SKILL.md

@@ -270,8 +270,67 @@ Remove legacy `smoke-test:validate-links`, `smoke-test-preload.cjs`, and bespoke
 3. Update `@se-studio/site-check` to `^2.6.1` when adopting integrity; otherwise `^2.1.2` minimum.
 4. Follow workflow above to create `smoke.cases.json`.
 
+## SSG guardrails (all marketing sites)
+
+Prevent `DYNAMIC_SERVER_USAGE` / production 500s on on-demand SSG routes (`●` in `next build`). Three layers — lint, build policy, production smoke.
+
+### 1. Biome — ban dynamic request APIs in SSG surfaces
+
+Copy the override block from `@se-studio/site-check/templates/biome-ssg-guardrails.override.json` into the app `biome.json` `overrides` array.
+
+Restricts request-time Next.js APIs in:
+
+- `src/app/layout.tsx`
+- `src/app/(cms-routes)/**`
+- `src/project/**`
+
+Banned: `next/headers` (headers, cookies, draftMode), `connection` from `next/server`, `unstable_noStore` from `next/cache`. `unstable_cache` and other `next/cache` exports remain allowed.
+
+Dynamic by design (no restriction): `(cms-dev)`, `preview`, `api`, `middleware.ts`.
+
+Lint is necessary but not sufficient — route policy + production smoke still required.
+
+Runs on every `pnpm check` / `pnpm validate`.
+
+### 2. Build route policy — no surprise `ƒ` on CMS segment routes
+
+Requires `@se-studio/site-check` **^2.7.0**.
+
+Commit `route-build-policy.json` beside `smoke.cases.json`. Start from `@se-studio/site-check/templates/route-build-policy.example.json` and adjust route segments to match the app.
+
+```json
+{
+  "allowedDynamic": ["/", "/articles", "/tags", "/people", "/_not-found"],
+  "mustBeSsgOrStatic": [
+    "/[level1]",
+    "/[level1]/[...slugs]",
+    "/articles/[articleType]",
+    "/articles/[articleType]/[...slugs]"
+  ]
+}
+```
+
+- `mustBeSsgOrStatic` — must be `●` or `○` in `next build`, never `ƒ`.
+- `allowedDynamic` — documents known `ƒ` routes; fail if a new `ƒ` appears without updating the policy.
+
+**Scripts:**
+
+```json
+"validate:routes": "validate-build-routes",
+"validate": "pnpm check && pnpm type-check && pnpm validate:routes"
+```
+
+`validate-build-routes` runs `pnpm build` and compares the Route (app) table to the policy. `smoke-test-one` also validates after build when `route-build-policy.json` exists (`SMOKE_TEST_VALIDATE_ROUTES=false` to skip).
+
+### 3. Production smoke (runtime safety net)
+
+`pnpm smoke-test:cache` / `smoke-test:deploy-check` catches breakage lint/policy miss. Keep mandatory in CI / Vercel build gates.
+
+**HubSpot bootstrap:** use `createHubSpotBootstrapScript()` with no args in root layout — not `headers()` + middleware pathname.
+
 ## Reference
 
 - HTTP + integrity example: `apps/example-empty/smoke.cases.json` and `scripts/smoke-test-run.ts` (monorepo).
-- Package API: `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `auditCacheLogs` from `@se-studio/site-check/smoke-test`.
+- SSG guardrails reference app: `apps/example-empty/route-build-policy.json` and `biome.json` overrides.
+- Package API: `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `auditCacheLogs`, `validateBuildRoutesFromBuildOutput` from `@se-studio/site-check/smoke-test`.
 - CMS integrity types: `@se-studio/site-check/cms-integrity`.

package/skills/vercel-logs-audit/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: vercel-logs-audit
+description: "Pull and triage Vercel error logs across SE Studio marketing sites (develop + production). Use when checking production errors, monitoring Vercel runtime issues, or running incremental log audits."
+---
+
+# Vercel logs audit
+
+Cross-project error monitoring for the 7 marketing sites in `docs/vercel-logs/projects.registry.json`.
+
+**Requires:** Vercel CLI (`vercel`), authenticated via `vercel login` or `VERCEL_TOKEN` in `.env.local`.
+
+**Output:** Generated under `docs/vercel-logs/` — **do not commit** except `projects.registry.json` and `README.md`.
+
+---
+
+## Quick start
+
+From repo root:
+
+```bash
+# Full pipeline: pull → filter → analyze
+pnpm vercel-logs
+
+# Subset
+pnpm vercel-logs --sites se2026,brightline --envs develop
+
+# Re-backfill 7 days (resets checkpoints for selected targets)
+pnpm vercel-logs --full
+
+# Plan fetches without calling Vercel
+pnpm vercel-logs:pull --dry-run
+```
+
+Individual steps:
+
+```bash
+pnpm vercel-logs:pull
+pnpm vercel-logs:filter
+pnpm vercel-logs:analyze
+```
+
+---
+
+## Incremental behaviour
+
+| Run | Window |
+|-----|--------|
+| First run (no `state.json`) | Last **7 days** per site × environment |
+| Subsequent runs | Since last checkpoint minus 5-minute overlap |
+| `--full` | Clears checkpoints and re-backfills 7 days |
+| `--since 2d` | Override start time for selected pull |
+
+Checkpoints live in `docs/vercel-logs/state.json` (gitignored).
+
+If a pull hits the Vercel log limit, the checkpoint is set to the **oldest fetched timestamp** (not `now`) so the next run can backfill older entries.
+
+---
+
+## Pipeline steps
+
+| Step | Input | Output |
+|------|-------|--------|
+| `pull` | Vercel CLI | `raw/<runId>/.../logs.jsonl` (raw JSON) |
+| `filter` | Raw JSONL + manifests | `errors/<runId>.jsonl` (normalized) |
+| `analyze` | Filtered JSONL | `reports/<runId>-summary.md` |
+
+---
+
+## Teams and projects
+
+The registry maps each site to a Vercel project and team scope:
+
+| Team | Sites |
+|------|-------|
+| `se-studio` | se2026, om1, pedestal, headwater |
+| `brightline` | brightline, brightlifekids |
+| `engineeringpointmes-projects` | pointme |
+
+Your Vercel account must have access to all three teams. Verify with `vercel whoami`.
+
+---
+
+## Reading results
+
+After `pnpm vercel-logs:analyze`, open:
+
+`docs/vercel-logs/reports/<runId>-summary.md`
+
+Triage in this order:
+
+1. **By site × environment** — which deploy surface is failing?
+2. **Top messages** — group identical errors (often one root cause)
+3. **Status codes** — 5xx vs application-level errors
+4. **Sample paths** — affected routes
+5. **Changes since previous run** — new regressions
+
+Filtered entries: `docs/vercel-logs/errors/<runId>.jsonl`
+
+Exit code **2** from analyze means errors were found (useful for future CI).
+
+---
+
+## What counts as an error
+
+Pull uses two CLI passes per target:
+
+- Log level `error` or `fatal`
+- HTTP status `500`–`508`
+
+Filter normalizes raw JSON and keeps entries matching:
+
+- Log level `error` or `fatal`
+- HTTP status `5xx`
+
+Optional: `pnpm vercel-logs:filter --include-warnings`
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `vercel logs failed` / auth error | `vercel login` or set `VERCEL_TOKEN` |
+| Wrong team / project not found | Check `team` in `projects.registry.json`; use `vercel projects ls --scope <team>` |
+| No targets matched | Check `--sites` / `--envs` keys match registry `key` fields |
+| Empty report after errors expected | Widen with `--full` or `--since 7d`; confirm develop uses `--branch develop` |
+
+---
+
+## Maintenance
+
+- Registry: `docs/vercel-logs/projects.registry.json`
+- Scripts: `scripts/vercel-logs/`
+- Tests: `pnpm vercel-logs:test`