@se-studio/skills 1.0.41 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @se-studio/skills
 
+## 1.1.0
+
+### Minor Changes
+
+- 31b2200: Add first-class support for managing redirects from Contentful.
+
+  Editors can now create `redirect` entries (via new content type) using reference pickers for existing Pages/Articles/etc. (for "from" and "to") or raw paths/URLs, plus a status code dropdown (301/302/etc.), active flag, and notes. This makes redirects easy for non-technical users without requiring them to know or type exact slugs.
+
+  Redirects use the simple rebuild pattern (already proven by A/B tests):
+
+  - Publish in Contentful → webhook triggers a Vercel Deploy Hook.
+  - Build fetches current published redirects (via `getRedirectsWithErrors` / `getRedirectMap` on the helpers from `createAppHelpers`) and bakes a static map (using the new pure `buildRedirectMap`).
+  - Middleware performs exact (or lightly normalized) lookups against the baked data with zero runtime cost or external calls.
+
+  Key additions:
+
+  - `IRedirect` type + `isRedirect` guard.
+  - `BaseRedirectSkeleton`, `baseRedirectConverter` (resolves reference links to concrete `fromPath`/`to` using existing `resolveLink` + project `urlCalculators`).
+  - `contentfulRedirectsRest`, revalidation `RedirectTag`, and `buildRedirectMap` / `RedirectMap` types (exported from `@se-studio/contentful-rest-api`).
+  - `getRedirectsWithErrors` and `getRedirectMap` (convenience) exposed additively via `createAppHelpers` (like banners).
+  - Two Contentful migration scripts: `18-create-redirect-content-type.js` (full CT with rich help text for the picker UX) and `19-remove-redirectTo-fields.js` (cleans up legacy per-page `redirectTo` fields on page/pageVariant).
+  - New `@se-studio/skills` entry `se-marketing-sites-redirects` (the canonical guide, including CT spec, migration instructions, generate script example, static middleware example + A/B composition, deploy hook webhook setup, testing, and preview notes).
+  - Minimal demo in `example-empty` (middleware + `/api/redirects` route exercising the new helpers at runtime for easy local verification; production apps follow the baked recipe in the skill).
+  - Light updates to CLAUDE.md, vercel-setup skill, CONTENT_MODEL.md, and related docs.
+
+  The model and helpers are forward-compatible if a faster (e.g. Edge Config) path is added later. Legacy `redirectTo` fields are left untouched for now (removal is optional via the migration).
+
+  This is a new feature (minor bumps).
+
+### Patch Changes
+
+- Complete support and documentation for filtered full article lists (#51) + fix client boundary regression (#52).
+
+  - Re-export `filterRelatedArticles` and `RelatedArticlesOptions` **only** from `@se-studio/core-ui/server` (removed from the main barrel). This keeps the primary `@se-studio/core-ui` entry fully client-safe for common imports (`cn`, `TrackedLink`, `AnalyticsProvider`, `Visual`, etc.). The main barrel no longer transitively pulls `'server-only'`.
+
+  - `getAllArticleLinks(options)` now fully supports the article listing filter fields (`articleTypeSlugs`/`Ids`, `tagSlugs`/`Ids`, `tagType*`, `authorSlugs`/`Ids` + `strictAuthorMatch`, `before`/`after`, `excludeArticleIds`, `count`, `allowUnindexed`) for News Grids, Publications Lists, person-scoped lists, tag filters, etc. The wrapper delegates to the enhanced `filterRelatedArticles` (OR semantics, slug support, strict author mode, distinct tag scoring, etc.).
+
+  - Added / expanded docs and examples in core-ui and contentful-rest-api READMEs + llms.md, CMS_INFRASTRUCTURE.md, SERVER_CLIENT_BOUNDARIES.md, the `se-marketing-sites-lib-cms-structure` skill (showing the `getAllArticleLinks({ articleTypeSlugs, strictAuthorMatch, ... })` pattern), and this repo's GitHub issues status tracker (new #51 entry + updated upgrade table).
+
+  - No changes to runtime behavior for existing bare `getAll*Links()` or `getRelated*` callers (sitemaps, search indexing, llms routes, etc. unaffected). Consumers should import filter symbols from the `/server` subpath when using them directly.
+
+  This finishes the implementation + docs for the DX improvement requested in #51 (reusable core filtering for full article collections instead of per-site `.filter()` shims). The boundary fix prevents the server-only error that appeared in any app importing from core-ui after the initial #51 changes.
+
+## 1.0.42
+
+### Patch Changes
+
+- Resolve person **`bio`** rich text on **`IPersonLink`** so team cards, related-people collections, and search/markdown pipelines can use CMS bios without fetching full person pages.
+
+  **@se-studio/core-data-types** — Add **`IResolvedRichText`** (`{ json, customStyles? }`) as the shared resolved RTF shape. **`IPersonLink.bio`** and **`ILinkProps.longText`** use it. **`contentfulAllPersonLinks`** consumers get typed **`IPersonLink[]`**.
+
+  **@se-studio/contentful-rest-api** — Include `fields.bio` in **`PERSON_LINK_FIELDS`**. **`basePersonLinkConverter`** returns **`IPersonLink`** with resolved bio. **`contentfulAllPersonLinks`** return type is **`CmsResponse<IPersonLink[]>`**.
+
+  **@se-studio/markdown-renderer** — **`MarkdownConverter`** exports person-link **`bio`** to Markdown (search/index pipelines). Uses **`isPersonLink`** type guard.
+
+  **@se-studio/core-ui** — **`FetchHelpers.getAllPersonLinks`** for collection use via **`rendererConfig.fetchHelpers`** (no cms-server import). **`getAllPersonLinks`** and sitemap deps typed as **`IPersonLink[]`**.
+
+  **@se-studio/contentful-cms** / **@se-studio/skills** — Document Person **`bio`** RTF authoring in cms-edit skills and functional spec.
+
 ## 1.0.41
 
 ### Patch Changes

package/package.json

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

package/skills/contentful-cms-core/SKILL.md

@@ -437,6 +437,26 @@ cms-edit ensure tag --slug asco-2025 --name "ASCO 2025" --tag-type conference-ve
 
 See `cms-edit help fields-taxonomy` and `cms-edit help taxonomy-from-json` for field reference and batch schema.
 
+## Person entries
+
+Key fields: `name`, `slug`, `jobTitle`, `description`, `media` (featured image), **`bio`** (rich text).
+
+```bash
+# Add a person to a collection or page content array
+cms-edit add "Dr. Jane Smith" --content-type person
+
+# Scalars
+cms-edit set @c0 name "Dr. Jane Smith"
+cms-edit set @c0 slug jane-smith
+cms-edit set @c0 jobTitle "Chief Medical Officer"
+
+# Bio (same RTF workflow as component body)
+printf '## Background\n\nBoard-certified with 20 years of experience.\n' | cms-edit rtf @c0 bio --markdown -
+cms-edit read @c0 bio
+```
+
+**Site/runtime:** Resolved **person links** (`IPersonLink` from the REST API — article authors, collection contents, `contentfulAllPersonLinks`, related-people helpers) include **`bio`** when set in CMS. Use for team cards, related-people collections, and markdown/search export — not only full person detail pages.
+
 **Idempotent taxonomy:** `--if-not-exists` / `ensure` are check-then-create — safe for sequential imports, not for parallel creates on the same slug.
 
 ```bash

package/skills/se-marketing-sites-lib-cms-structure/SKILL.md

@@ -81,6 +81,23 @@ Components and collections in the registration chain (imported by `registrations
 
 These are passed via `projectRendererConfig` in `cms-server.ts`. `Section` and `SectionLinks` accept `previewHelpers` / `rendererConfig` props. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
 
+**Full article lists (News Grid / Publications List / ArticleFilter):** Use the new filter options on `getAllArticleLinks` instead of post-filtering the result in each app:
+
+```ts
+// inside a collection renderer (server component)
+const articlesRes = await rendererConfig.fetchHelpers?.getAllArticleLinks?.({
+  articleTypeSlugs: [NEWS_SLUG],           // or articleTypeIds
+  // On person pages (strict, so pubs grid doesn't bleed into news grid):
+  // authorIds: [person.id],
+  // strictAuthorMatch: true,
+  // tag context:
+  // tagSlugs: contextTag ? [contextTag.slug] : undefined,
+});
+const articles = articlesRes?.data ?? [];
+```
+
+`LinkFetchOptions` (and `filterRelatedArticles` / `RelatedArticlesOptions`) are available from `@se-studio/core-ui/server`. This moves the common type/tag/author logic into core (with OR semantics, scoring, indexed rules, legacy author handling still possible client-side or via custom wrapper). See GH #51.
+
 ## See Also
 
 - **register-cms-features** – Adding components and collections

package/skills/se-marketing-sites-redirects/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: se-marketing-sites-redirects
+description: "Add support for editor-managed URL redirects using a dedicated redirect content type + the proven A/B-style rebuild pattern (webhook to Vercel deploy hook, build bakes a static map). Includes the two official migration scripts (create CT, remove legacy redirectTo fields)."
+---
+
+# SE Marketing Sites — Redirects (rebuild pattern)
+
+This skill adds the ability for **non-technical content editors** to manage redirects entirely from Contentful.
+
+**Core idea (matches how your A/B tests already work):**
+- Editors create `redirect` entries (they can **pick** existing Pages/Articles/etc. from reference fields or type raw paths).
+- On publish, a Contentful webhook calls your Vercel **Deploy Hook**.
+- The next build fetches the current redirects (via the normal CDA helpers), runs `buildRedirectMap`, and writes a tiny static file.
+- Your `middleware.ts` imports that file and does the redirect **synchronously with zero runtime cost**.
+- Propagation time = normal Vercel build (usually 1–3 minutes). Robust, no extra tokens or Edge Config required.
+
+A faster "seconds" path (Edge Config) is explicitly **not** included in v1 per product direction — the model and helpers are forward-compatible if you add it later.
+
+## 1. Run the migrations (create the content type + clean up legacy)
+
+The repo contains two official migrations:
+
+```bash
+# 1. Create the new redirect content type (with great help text for editors)
+node scripts/migrations/18-create-redirect-content-type.js
+
+# 2. (Later, when you are ready) Remove the old per-page redirectTo fields
+node scripts/migrations/19-remove-redirectTo-fields.js
+```
+
+Run them with the Contentful CLI (or the contentful-cms package tools) and the usual `CONTENTFUL_SPACE_ID` + `CONTENTFUL_MANAGEMENT_TOKEN` + environment.
+
+After the create migration you will have a new content type called **Redirect**.
+
+## 2. The Redirect content type (what editors see)
+
+Key fields (all documented with help text in the migration):
+
+**From (source)**
+- `fromPath` (raw path) — editors type `/old-url/` when they are not using a picker.
+- `fromPage`, `fromArticle`, `fromArticleType`, `fromPerson`, `fromTag`, `fromCustomType` — reference pickers. When an editor picks one, the system automatically uses that item's current URL. This is the magic that makes it easy for non-technical people.
+
+**To (destination)**
+- `toPath` (raw path or full external `https://...` URL)
+- `toPage`, `toArticle`, ... — same reference pickers as above.
+
+**Other**
+- `statusCode` — dropdown: 301 (permanent — recommended), 302, 307, 308.
+- `active` — boolean (default on). Turn off to disable a rule without deleting it.
+- `note` — internal editor note (never shown on the site).
+- `cmsLabel` — required internal label.
+
+**Editor guidance (the help text says this):**
+> For redirects **from** an existing CMS page or article, use the reference picker instead of typing the slug. Same for the destination. Only use the raw path fields for old/vanity URLs that no longer exist in the CMS or for external sites.
+
+The converter (`baseRedirectConverter`) resolves any chosen references into concrete `fromPath` / `to` strings at fetch time. The baked map only ever contains simple strings.
+
+## 3. Add the core support (already done by the time you read this)
+
+The following are already in the packages:
+
+- `IRedirect` + `isRedirect` in `@se-studio/core-data-types`
+- `baseRedirectConverter` + `BaseRedirectSkeleton`
+- `contentfulRedirectsRest` + `buildRedirectMap` + `getRedirectsWithErrors` / `getRedirectMap` (via `createAppHelpers`)
+- Revalidation tag `redirect` (so the existing webhook machinery knows about the new type)
+
+You only need to wire the **rebuild** side in your app.
+
+## 4. Wire the rebuild path in your app (the only recipe for v1)
+
+### 4.1 Build-time generation (the heart of the simple path)
+
+Create (or add to) a small script, e.g. `scripts/generate-redirects.ts`:
+
+```ts
+import 'server-only';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildRedirectMap,
+  getRedirectMap, // or use the helpers directly
+} from '@se-studio/contentful-rest-api'; // or from your local cms-server re-exports
+
+// In a real app you would use your project's buildInformation + converterContext + getConfig
+// exactly like you do for sitemaps or other build-time data pulls.
+// For simplicity many teams just import the same helpers used at runtime.
+
+async function main() {
+  // Example using the convenience that already exists on the helpers object you already create:
+  // const { getRedirectMap } = createAppHelpers(...);
+  // const map = await getRedirectMap({});
+
+  // Minimal standalone version (adapt to your converterContext / getContentfulConfig):
+  // const map = buildRedirectMap(await fetchAllPublishedRedirectsSomehow());
+
+  const map = {}; // TODO: replace with real call using your existing helpers
+
+  const outPath = resolve(dirname(fileURLToPath(import.meta.url)), '../src/generated/redirects.ts');
+  mkdirSync(dirname(outPath), { recursive: true });
+
+  const file = `// AUTO-GENERATED by scripts/generate-redirects.ts — do not edit by hand
+export const redirects = ${JSON.stringify(map, null, 2)} as const;
+export type RedirectMap = typeof redirects;
+`;
+  writeFileSync(outPath, file, 'utf8');
+  console.log(`Wrote ${Object.keys(map).length} redirects to ${outPath}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+```
+
+Wire it into the build:
+
+```json
+// in the app's package.json
+{
+  "scripts": {
+    "generate:redirects": "tsx scripts/generate-redirects.ts",
+    "prebuild": "pnpm generate:redirects",
+    "build": "next build"
+  }
+}
+```
+
+(You can also call it from a `next.config.ts` `webpack` hook or a turbo pipeline step — whatever is consistent with how you generate the A/B static data.)
+
+### 4.2 Static middleware (zero runtime work)
+
+Create `middleware.ts` at the root of your Next app (alongside `next.config.ts`):
+
+```ts
+import { NextResponse, type NextRequest } from 'next/server';
+import { redirects } from './src/generated/redirects'; // the file we just generated
+
+// If you also use A/B testing static middleware, import and compose here.
+import { createStaticAbTestMiddleware } from '@se-studio/ab-testing/middleware';
+// import { testsByPath } from './src/generated/abTests';
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // 1. Redirects first (cheap object lookup)
+  const rule = (redirects as Record<string, { to: string; status: number }>)[pathname];
+  if (rule) {
+    // You can add query param forwarding here if you added a field for it.
+    return NextResponse.redirect(new URL(rule.to, request.url), { status: rule.status });
+  }
+
+  // 2. A/B (if you use the static version)
+  // const ab = createStaticAbTestMiddleware({ testsByPath });
+  // const abRes = ab(request);
+  // if (abRes) return abRes;
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - api (API routes)
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico, sitemap.xml, robots.txt, etc.
+     */
+    '/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+};
+```
+
+If you already have a `middleware.ts` for A/B or other things, just add the redirect check at the very top (before any other logic).
+
+### 4.3 Webhook = Deploy Hook (the trigger)
+
+In Contentful → Settings → Webhooks, create (or reuse) a webhook that fires on:
+
+- Entry publish / unpublish / delete for content type `redirect`
+
+Point the URL at your **Vercel Deploy Hook** (Project → Settings → Deploy Hooks → create one for Production and optionally for Preview).
+
+Add the usual headers your deploys need (`x-vercel-protection-bypass` if you use deployment protection, `REVALIDATION_SECRET` if you also want the normal reval to run, etc.).
+
+That's it. Publish a redirect → Vercel starts a build → the generate step runs → the new static map is in the bundle → redirects work.
+
+## 5. Testing
+
+1. Run the create migration.
+2. In Contentful create a Redirect:
+   - Pick a real Page as "From Page".
+   - Type `/somewhere-else/` as "To path".
+   - Status 301, Active on.
+3. Publish.
+4. Watch the deploy hook fire a build in Vercel.
+5. After the build finishes: `curl -I https://your-site/from-page-url/` → 301 to the target.
+6. Also test a raw-path rule and an external URL.
+7. Edit the rule → republish → new build → new behaviour.
+8. (Optional) Run the remove migration and confirm the old `redirectTo` fields are gone.
+
+## 6. Preview / draft deployments
+
+Because each deployment builds from whatever is **published** in Contentful at build time, your preview deployments automatically see the current published redirects. No extra work.
+
+(If you have a `DRAFT_ONLY` preview that shows unpublished content, the redirects list will still be the published ones — which is usually what you want for redirect rules.)
+
+## 7. Updating the skill / docs after changes
+
+After you edit anything in this area, run:
+
+```bash
+pnpm skills:validate
+pnpm skills:sync
+```
+
+Then commit the updated `.agents/skills/...` (the monorepo keeps them in sync with the canonical source in `packages/skills/skills/`).
+
+## 8. Future work (explicitly out of scope for v1)
+
+- Edge Config + instant sync route (user request: "don't do the fast version at the moment").
+- Wildcards / prefix matching / query param control.
+- A "Redirects index" page visible to editors on the live site.
+- Host-based or A/B-aware redirects.
+
+The `redirect` content type and the `buildRedirectMap` / `getRedirectMap` helpers are intentionally stable so a future faster path can consume the same data.
+
+---
+
+**You now have editor-managed redirects that are as robust and low-surprise as your A/B tests, using only patterns that already exist in the codebase.**

package/skills/site-workflows-contentful-vercel-setup/SKILL.md

@@ -396,4 +396,19 @@ Expected: `200 OK`. A `401` means the secret in the header doesn't match the dep
 
 - **If inspector mode doesn't highlight fields**: check that `getPreviewFieldProps` is applied to field containers in the components. See `.cursorrules` for the pattern.
 - **For draft content visibility**: set `DRAFT_ONLY=true` in Vercel on a preview/staging environment (not production) so editors can see unpublished content without affecting live users.
+
+## (Optional) Redirects via the rebuild pattern
+
+If the project uses the `se-marketing-sites-redirects` skill, also configure a webhook that fires on the new `redirect` content type and points at a **Vercel Deploy Hook** (not a revalidation URL).
+
+See `.agents/skills/se-marketing-sites-redirects/SKILL.md` (or the source in `packages/skills/skills/se-marketing-sites-redirects/SKILL.md`) for:
+
+- Running the two official migration scripts (create the CT + later remove legacy `redirectTo` fields)
+- The exact content type fields + recommended help text
+- The build-time generate script + static middleware
+- Wiring the deploy hook webhook
+
+This is deliberately the same "publish → deploy hook → build bakes static data" pattern used for A/B tests. It is the only supported path in v1 (Edge Config fast path is future work).
+
+You can have both the normal revalidation webhooks **and** the redirect deploy-hook webhook active at the same time.
 - **To rotate the secret later**: re-run `scripts/setup-contentful-webhooks.ts` — it will generate a new secret and update everything automatically.