@se-studio/skills 1.0.42 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @se-studio/skills
 
+## 1.1.1
+
+### Patch Changes
+
+- Simplify Redirect content model + add tagType as a first-class internal link target.
+
+  The original redirect content type (added in the previous minor) used a verbose Contentful model with separate `fromPage`/`fromArticle`/etc. reference fields (and same for "to"). This has been replaced with the clean model:
+
+  - `fromPath` (raw/custom) + `fromInternal` (single Link→Entry)
+  - `toPath` (raw/external) + `toInternal` (single Link→Entry)
+
+  Both internal fields are restricted via `linkContentType` validation to: page, article, articleType, person, tag, customType, tagType.
+
+  Updated:
+
+  - Migration `scripts/migrations/18-create-redirect-content-type.js` (now a clean create for the good model; delete any previous "Redirect" CT first if you ran the old multi-field version).
+  - `BaseRedirectSkeleton`, `baseRedirectConverter`, and `IRedirect` (provenance is now `fromInternal`/`toInternal` as `IInternalLink`).
+  - `UrlCalculators` now requires a `tagType(slug)` function (to support selecting tag type indexes as redirect targets).
+  - Added `baseTagTypeLinkConverter`, registered the resolver, extended `BaseLink` / `InternalType` / exported `ITagTypeLink` + guard.
+
+  Docs and the `se-marketing-sites-redirects` skill have been updated with the new CT shape, help text guidance, and testing steps.
+
+  Consumers will need to implement `tagType` in their urlCalculators (and pass it through `createBaseConverterContext`) to select Tag Type entries in redirects and to satisfy the updated type.
+
+  The runtime redirect map, middleware, and `buildRedirectMap` behaviour are unchanged.
+
+## 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

package/package.json

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

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,231 @@
+---
+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 official migration script (create the clean CT with fromInternal/toInternal single-ref pickers)."
+---
+
+# 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. via the single From/To internal pickers 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 migration (create the content type)
+
+The repo contains the official migration:
+
+```bash
+# Create the redirect content type (clean fromPath + fromInternal / toPath + toInternal model)
+node scripts/migrations/18-create-redirect-content-type.js
+```
+
+Run it with the Contentful CLI (or the contentful-cms package tools) and the usual `CONTENTFUL_SPACE_ID` + `CONTENTFUL_MANAGEMENT_TOKEN` + environment.
+
+If you previously created a Redirect CT using an older multi-field version of the migration, **delete the "Redirect" content type first**, then re-run to get the clean single-ref model.
+
+After running you will have a new (or repaired) 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 the picker.
+- `fromInternal` (single reference picker) — restricted to page, article, articleType, person, tag, customType, tagType. 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)
+- `toInternal` (single reference picker, same allowed types as fromInternal)
+
+**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 existing CMS content, use the "From internal" / "To internal" picker instead of typing the slug. 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` (now uses `fromInternal` / `toInternal`)
+- `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 via the single "From internal" picker.
+   - Pick (or type) a destination via "To internal" or "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) If you also want to clean up legacy per-page `redirectTo` fields, run migration 19.
+
+## 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.