@se-studio/skills 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.4.1
+
+### Patch Changes
+
+- f2de9ba: Document CMS smoke integrity (`cmsIntegrity`, `runStaticSmokeTestWithIntegrity`), Vercel `VERCEL_FORCE_NO_BUILD_CACHE`, and update `se-marketing-sites-smoke-test-setup` skill plus `example-empty` reference.
+
 ## 1.4.0
 
 ### Minor Changes

package/package.json

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

package/skills/se-marketing-sites-create-page/SKILL.md

@@ -121,16 +121,23 @@ If a route needs a different layout (e.g. no header/footer), create `layout.tsx`
 
 ## A/B Test Variant Route (`page-test`)
 
-When A/B testing is enabled, variant pages are served through a `/page-test/[...slugs]` route that the middleware rewrites to. This route **must** use `generatePageTestMetadata` (not `generatePageMetadata`) so that `robots`/`indexed` comes from the **canonical/control** page — variant entries are intentionally `indexed: false` in Contentful.
+When A/B testing is enabled, variant pages are served through a `/page-test/[...slugs]` route that the middleware rewrites to. This route **must** use:
+
+- **`generatePageTestMetadata`** (not `generatePageMetadata`) so that `robots`/`indexed` comes from the **canonical/control** page — variant entries are intentionally `indexed: false` in Contentful.
+- **`generatePageTest`** (not `generatePage`) so breadcrumbs, `model.href`, and JSON-LD use the **control/canonical** path while variant **content** still renders.
+
+`BasicLayout` should resolve breadcrumbs and structured data from `currentPath ?? model.href` (the factory passes `currentPath={canonicalPath}`).
 
 If the slug is not a known variant in `testsByPath`, **return 404** (`notFound()`): there is no control page to merge, and `/page-test/…` is only valid for configured tests.
 
+Direct visits to a variant's own CMS URL (normal `[...slugs]` route) continue to use `generatePage` and show variant breadcrumbs.
+
 ```typescript
 import { findCanonicalPath } from '@se-studio/ab-testing';
 import type { ResolvingMetadata } from 'next';
 import { notFound } from 'next/navigation';
 import { testsByPath } from '@/generated/abTests';
-import { generatePage, generatePageTestMetadata } from '@/lib/route-handlers';
+import { generatePageTest, generatePageTestMetadata } from '@/lib/route-handlers';
 import { getPageRouteConfig } from '@/lib/routeConfig';
 
 /** Variant slug must appear in testsByPath; otherwise this route is not valid. */
@@ -165,13 +172,15 @@ export async function generateMetadata(
 }
 
 export default async function (props: PageProps<'/page-test/[...slugs]'>) {
-  const { slug, path } = await extractDetails(props);
-  requireCanonicalPath(slug);
-  return generatePage(slug, path, getPageRouteConfig(slug));
+  const { slug } = await extractDetails(props);
+  const canonicalPath = requireCanonicalPath(slug);
+  const canonicalSlug = canonicalPath.replace(/^\/|\/$/g, '') || slug;
+  // Use generatePageTest: variant contents with control identity (href, breadcrumbs, JSON-LD).
+  return generatePageTest(slug, canonicalSlug, canonicalPath, getPageRouteConfig(canonicalSlug));
 }
 ```
 
-Also export `generatePageTestMetadata` from the app's `src/lib/route-handlers.ts` destructuring alongside `generatePageMetadata`.
+Also export `generatePageTestMetadata` and `generatePageTest` from the app's `src/lib/route-handlers.ts` destructuring alongside `generatePageMetadata`.
 
 ## See Also
 

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

@@ -5,17 +5,18 @@ description: "Set up or regenerate smoke.cases.json for local smoke tests from t
 
 # Smoke test setup (static `smoke.cases.json`)
 
-Local smoke tests are **HTTP-only**: no `cms-server`, Contentful, or preload. Each app commits **`smoke.cases.json`** with curated URLs. Regenerate this file when routes or indexed content change materially.
+Local smoke tests use curated HTTP cases in **`smoke.cases.json`**. Optionally enable **`cmsIntegrity`** for a local-only Contentful article-link check (no `cms-server` import in smoke scripts).
 
-Requires `@se-studio/site-check` **2.1.2+** for cache log audit; **2.0.0+** for static smoke.
+Requires `@se-studio/site-check` **^2.6.1** when using `cmsIntegrity` or `pnpm smoke-test` with integrity enabled; **2.1.2+** for cache log audit; **2.0.0+** for HTTP-only static smoke.
 
-Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smoke failure.
+Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smoke failure. **Deployment / live smoke stays HTTP-only** — do not enable `cmsIntegrity` on Vercel deployment checks.
 
 ## Prerequisites
 
-- App has `scripts/smoke-test-run.ts` calling `runStaticSmokeTest('smoke.cases.json')`.
+- App has `scripts/smoke-test-run.ts` (see [CMS article-link integrity](#cms-article-link-integrity-optional) below).
 - `package.json`: `"smoke-test:run": "tsx scripts/smoke-test-run.ts"`.
 - `SITEMAP_PROD_URL` in `.env.example` (production sitemap for URL curation).
+- When `cmsIntegrity.enabled` is true: `@se-studio/contentful-rest-api@^1.10.0`, `@se-studio/core-data-types@^1.5.1`, Contentful tokens in `.env.local`.
 
 ## Script matrix
 
@@ -103,8 +104,24 @@ Or from the app directory without a per-app script: `node ../../scripts/smoke-te
 | `DEPLOYMENT_URL` | Live deployment URL for `smoke-test:live` (CI / `repository_dispatch` payload) |
 | `VERCEL_PROTECTION_BYPASS_TOKEN` | Deployment Protection bypass secret (aliases: `VERCEL_AUTOMATION_BYPASS_SECRET`, `VERCEL_BYPASS_TOKEN`) |
 | `PRODUCTION_SITE_URL` | Optional canonical production URL for audits and related tooling |
+| `SMOKE_TEST_SKIP_INTEGRITY` | Set by `smoke-test-one` when integrity runs in parallel; HTTP-only child run |
+| `VERCEL_FORCE_NO_BUILD_CACHE` | **Vercel project env only** (`1`) — skip remote build cache when webpack `WasmHash` failures occur on Vercel (not `vercel.json`) |
 
-Add these to `.env.example` under an SEO / site-check section. `runPreviewStaticSmokeTest` requires `PREVIEW_SITE_URL` and a bypass token in `.env.local`.
+Add smoke-related vars to `.env.example` under an SEO / site-check section. `runPreviewStaticSmokeTest` requires `PREVIEW_SITE_URL` and a bypass token in `.env.local`.
+
+### Vercel build cache (`VERCEL_FORCE_NO_BUILD_CACHE`)
+
+Intermittent Vercel `next build` failures (`WasmHash._updateWithBuffer` / `Cannot read properties of undefined (reading 'length')`) often correlate with a stale remote build cache. Mitigation:
+
+```bash
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE preview develop --value 1 --yes
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE production --value 1 --yes
+```
+
+- Set on the **Vercel project** (Preview and/or Production). Not in app `.env.local`.
+- Tradeoff: cold builds ~1m vs ~30s cached.
+- Roll out to other marketing sites on the next Vercel config pass when builds fail intermittently locally pass.
+- Document in the app `AGENTS.md` when applied.
 
 ## Workflow
 
@@ -175,16 +192,37 @@ curl -sI "http://localhost:<port>/some-path.md"
 }
 ```
 
+Optional `cmsIntegrity` (local only — see section below):
+
+```json
+{
+  "cmsIntegrity": {
+    "enabled": true,
+    "routing": {
+      "articleTypesBasePath": "/resources",
+      "tagsBasePath": "/topics",
+      "peopleBasePath": "/team",
+      "defaultTopic": "other",
+      "enablePrimaryTagPartOfSlug": true,
+      "topiclessArticleTypeSlugs": ["ebooks"]
+    }
+  }
+}
+```
+
+Map `routing` from `src/lib/constants.ts` (or the app’s URL rules). `enabled: false` omits the integrity fetch.
+
 - `path` — site-relative, trailing slash when the site uses trailing slashes.
 - `port` — default; override at run time with `SMOKE_TEST_PORT`.
 
 ### 7. Verify
 
 ```bash
-pnpm smoke-test:run
+pnpm smoke-test:run    # HTTP (+ integrity when cmsIntegrity.enabled)
+pnpm smoke-test          # starts dev server; integrity runs in parallel when enabled
 ```
 
-Expect `Summary: N cases, 0 failed`. Preview API / `DRAFT_ONLY` logs in dev are OK.
+Expect `Summary: N cases, 0 failed`. With integrity: `article link integrity: ok`. Preview API / `DRAFT_ONLY` logs in dev are OK.
 
 Optional cache audit:
 
@@ -198,14 +236,42 @@ Expect `cache log audit: ok` with no 2MB errors. `cache skip` lines are warnings
 
 Commit `smoke.cases.json`. Remove legacy `smoke.config.ts` if present.
 
+## CMS article-link integrity (optional)
+
+Local-only check: one Contentful fetch validates all article/person/tag link `href` values (broken links, conversion errors). Runs in parallel with server boot when using `pnpm smoke-test`.
+
+**`scripts/smoke-test-run.ts`:**
+
+```ts
+import {
+  formatCombinedSmokeReport,
+  getCombinedSmokeExitCode,
+  runStaticSmokeTestWithIntegrity,
+} from '@se-studio/site-check/smoke-test';
+
+async function main(): Promise<number> {
+  const skipIntegrity = (process.env.SMOKE_TEST_SKIP_INTEGRITY ?? '').toLowerCase() === 'true';
+  const { integrity, http } = await runStaticSmokeTestWithIntegrity('smoke.cases.json', {
+    skipIntegrity,
+  });
+  console.log(formatCombinedSmokeReport(integrity, http));
+  return getCombinedSmokeExitCode(integrity, http);
+}
+```
+
+Remove legacy `smoke-test:validate-links`, `smoke-test-preload.cjs`, and bespoke link-validation scripts when migrating.
+
+**Per-site rollout:** bump `@se-studio/site-check@^2.6.1`, add `cmsIntegrity` to `smoke.cases.json`, update `smoke-test-run.ts`, run `pnpm smoke-test` locally. Reference consumer: `om1-website` (`develop`).
+
 ## Migrating from `smoke.config.ts`
 
 1. Delete `smoke.config.ts`.
 2. Simplify `smoke-test:run` script (no bash, no `NODE_OPTIONS`, no preload).
-3. Update `@se-studio/site-check` to `^2.1.2`.
+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`.
 
 ## Reference
 
-- Example: `apps/example-empty/smoke.cases.json` (monorepo).
-- Package API: `loadStaticSmokeConfig`, `runStaticSmokeTest`, `runPreviewStaticSmokeTest`, `auditCacheLogs` from `@se-studio/site-check/smoke-test`.
+- 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`.
+- CMS integrity types: `@se-studio/site-check/cms-integrity`.