@se-studio/skills 1.0.6 → 1.0.11

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @se-studio/skills
 
+## 1.0.11
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.10
+
+### Patch Changes
+
+- Add site-workflows-contentful-vercel-setup skill
+
+## 1.0.9
+
+### Patch Changes
+
+- Add site-workflows-copy-doc-snapshot skill
+- Add site-workflows-new-project skill
+- Add site-workflows-project-cleanup skill
+
+## 1.0.8
+
+### Patch Changes
+
+- Add site-workflows-apply-design-snapshot skill
+
+## 1.0.7
+
+### Patch Changes
+
+- Add site-workflows-figma-design-snapshot skill
+
 ## 1.0.6
 
 ### Patch Changes

package/package.json

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

package/skills/site-workflows-apply-design-snapshot/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: site-workflows-apply-design-snapshot
+description: Reads design.md and applies the design tokens to the project — updating tailwind.config.json (colours + typography), handling custom fonts, and regenerating all downstream files via pnpm codegen. Run after /figma-design-snapshot to sync the codebase with the latest Figma changes.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Apply Design Snapshot
+
+Reads `design.md` and applies its design tokens to the project. Run this after `/figma-design-snapshot` to keep the codebase in sync with Figma.
+
+## Usage
+
+```
+/apply-design-snapshot
+```
+
+No arguments needed. Reads `design.md` and `.design-snapshot.json` from the project root, updates `tailwind.config.json` and `globals.css`, then runs `pnpm codegen` to regenerate all typed token files.
+
+---
+
+## CRITICAL: The token pipeline
+
+```
+tailwind.config.json
+       ↓  pnpm codegen
+src/generated/colors.ts        ← typed colour lookups (auto-generated)
+src/generated/textStyles.ts    ← typed type-scale names (auto-generated)
+src/generated/setailwind.css   ← CSS custom properties + utilities (auto-generated)
+```
+
+**Never edit files in `src/generated/` directly** — they are always overwritten by `codegen`. Only edit `tailwind.config.json` and `globals.css`.
+
+---
+
+## Step 1 — Check prerequisites
+
+1. Check that `design.md` exists in the project root (or at `outputPath` from `.design-snapshot.json`).
+   - If missing: stop and tell the user to run `/figma-design-snapshot` first.
+2. Check that `tailwind.config.json` exists.
+   - If missing: stop and tell the user this skill requires the SE Studio token pipeline.
+
+---
+
+## Step 2 — Parse design.md
+
+Read `design.md` and extract:
+
+### Colours
+Find the `## Colour Palette` section. For every table row matching `| Token | Hex |`, extract the token name and hex value. Ignore swatch columns. Collect all colours regardless of group (Primary / Neutral / etc.).
+
+### Typography
+Find `## Typography`. Extract the **Desktop** table (lines under `### Desktop`) and the **Mobile** table (lines under `### Mobile`). For each row capture: style name, size (strip `px`), weight label, line-height, letter-spacing.
+
+Weight label → number mapping:
+- Regular → 400
+- Medium → 500
+- SemiBold → 600
+- Bold → 700
+
+Letter-spacing conversion (Figma `%` → CSS `em`): divide by 100. e.g. `−1.3%` → `-0.013em`. If the value is `0` keep it as `0`.
+
+Line-height conversion: strip `%` and divide by 100. e.g. `120%` → `1.2`. If already a decimal, keep as-is. If in `px`, keep as the px value.
+
+### Font family
+Find `**Font family:**` in the Typography section. Extract the font name (e.g. `Booton-TRIAL`).
+
+### Breakpoints
+Find `## Breakpoints & Canvas`. Extract rows — identify the desktop canvas width (largest) and mobile canvas width (smallest).
+
+---
+
+## Step 3 — Read current tailwind.config.json
+
+Read `tailwind.config.json` in full. Record:
+- `colorOptions` — the current colour map (must preserve all existing keys)
+- `fontTable.font` — the current font family string
+- `fontTable.weight` — the base font weight
+- `fontTable.styles` — the current style map (keys are class names used in the codebase — **never rename or remove them**)
+- `colorOpposites` — existing colour contrast pairs
+- `foregroundColors` — existing foreground colour list
+- `colorFile` — keep unchanged
+
+---
+
+## Step 4 — Ask about fonts
+
+Before modifying any file, ask the user this question (use `AskUserQuestion`):
+
+> The design uses **[font name from design.md]** (Regular 400, Medium 500, SemiBold 600).
+>
+> How should I handle the font?
+>
+> **A)** I have the font files — tell me the path (relative to project root or absolute) and I'll copy them to `public/fonts/` and wire up `@font-face`.
+> **B)** I don't have the files yet — set up placeholder `@font-face` rules so I can drop files in later.
+> **C)** Skip fonts — only update colours and type sizes.
+
+Wait for the answer. Record as `fontStrategy` (A / B / C). If A, also record `fontSourcePath` from their reply.
+
+---
+
+## Step 5 — Build the colour patch
+
+Construct the updated `colorOptions` object:
+
+1. **Start with all existing entries** exactly as they are. The `Light` and `Dark` keys are especially critical — they feed `lookupColourString()`, `lookupOpposite()`, and `lookupColourClassNames()` throughout the component system.
+
+2. **Add new entries** from design.md. Skip any name that already exists (case-insensitive match). Use the exact name string from design.md as the key (the codegen tool kebab-cases it for CSS variables automatically).
+
+3. **Compute colour opposites** for each new colour using WCAG relative luminance:
+   1. Parse the hex value into R, G, B as integers 0–255, then normalise to 0–1 by dividing by 255.
+   2. Linearise each channel: if c ≤ 0.03928 → `c / 12.92`, else `((c + 0.055) / 1.055) ^ 2.4`.
+   3. Compute luminance: `L = 0.2126·R + 0.7152·G + 0.0722·B`.
+   4. If `L ≤ 0.179` → the colour is dark; opposite is `"Light"` (white/light text will be legible).
+      If `L > 0.179` → the colour is light; opposite is `"Dark"` (dark text will be legible).
+
+4. **Show the user** the full list of colours being added (name + hex + computed opposite) before writing anything. Ask them to confirm or correct any pairs.
+
+---
+
+## Step 6 — Build the typography patch
+
+Map Figma's style names to the existing project class names using this table. The left column is how the style appears in design.md; the right is the `fontTable.styles` key to update in `tailwind.config.json`.
+
+| design.md style | tailwind.config.json key |
+|---|---|
+| H1 (Desktop) | `h1` |
+| H2 (Desktop) | `h2` |
+| H3 (Desktop) | `h3` |
+| H4 (Desktop) | `h4` |
+| P1 (Desktop) | `p1` |
+| P2 (Desktop) | `p2` |
+| P3 (Desktop) | `p3` |
+| P4 (Desktop) | `p3Med` |
+| Button 1 (Desktop) | `large-button` |
+
+> **Note:** If your project uses different `fontTable.styles` keys, adjust the right-hand column to match what is in your `tailwind.config.json`. Keys not present in the table are left exactly as-is.
+
+For each mapped style, construct the updated `fontTable.styles` entry following these rules:
+
+- `"default"` = the **Mobile** size for that style (from the Mobile table in design.md)
+- `"desktop"` = the **Desktop** size (only include if it differs from `"default"`)
+- `"weight"` = only include when the weight is not the base `fontTable.weight` (typically 400)
+- `"lineHeight"` = converted value (see Step 2 conversion rules)
+- `"letterSpacing"` = converted value (see Step 2 conversion rules); omit if `0`
+- `"additional"` = **preserve exactly** from the existing entry (e.g. `text-transform: uppercase` on `h1`) — do not remove it
+- Style keys not in the mapping table above (e.g. `hHome`, `h2Med`, `h2plus`, `nav`, etc.) → **leave completely unchanged**
+
+Example output for `h2`:
+```json
+"h2": {
+  "weight": 500,
+  "letterSpacing": "-0.013em",
+  "lineHeight": 1.2,
+  "default": 40,
+  "desktop": 51
+}
+```
+
+---
+
+## Step 7 — Build the font patch
+
+### Strategy A — font files provided
+
+1. List all font files at `fontSourcePath` matching `*.woff2`, `*.woff`, `*.ttf`, `*.otf`.
+2. Create `public/fonts/` if it does not exist.
+3. Copy all matched files into `public/fonts/`.
+4. For each file, infer the face weight from the filename:
+   - Filename contains `Regular` or `400` → weight: 400, style: normal
+   - Contains `Medium` or `500` → weight: 500, style: normal
+   - Contains `SemiBold` or `Semi` or `600` → weight: 600, style: normal
+   - Contains `Bold` or `700` → weight: 700, style: normal
+   - Contains `Italic` → add `font-style: italic` alongside the matching weight
+5. Build `@font-face` blocks — prefer `woff2` format; fall back to `woff` then `ttf`.
+6. Insert the `@font-face` blocks into `globals.css` **before** the `@import "tailwindcss"` line (font declarations must precede Tailwind).
+7. Update `tailwind.config.json` → `fontTable.font` to the font family name from design.md.
+8. Update `globals.css` `@theme` block: replace the `--font-sans` value with `"[FontName]", system-ui, ui-sans-serif, sans-serif`.
+
+### Strategy B — placeholder
+
+1. Add the following block to `globals.css` before the `@import "tailwindcss"` line:
+
+```css
+/* TODO: Replace src with actual font files placed in public/fonts/ */
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 600;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+2. Update `tailwind.config.json` → `fontTable.font` to the font family name.
+3. Update `globals.css` `--font-sans` to `"[FontName]", system-ui, ui-sans-serif, sans-serif`.
+4. After writing, tell the user: *"Place your font files in `public/fonts/` and replace each `src: local(...)` line with `src: url('/fonts/YourFile.woff2') format('woff2')`."*
+
+### Strategy C — skip
+
+No font changes. Skip this step entirely.
+
+---
+
+## Step 8 — Apply all changes
+
+Write files in this order:
+
+1. **`tailwind.config.json`** — merge in the new `colorOptions`, updated `colorOpposites`, and updated `fontTable.styles`. All other fields (`sizes`, `colorFile`, `foregroundColors`, etc.) must be preserved exactly.
+2. **`src/app/globals.css`** — apply font changes (strategies A or B only).
+3. **`public/fonts/`** — copy font files (strategy A only).
+
+Before writing `tailwind.config.json`, do a final sanity check:
+- `Light` and `Dark` keys still present with their original hex values
+- No existing `fontTable.styles` keys removed
+- JSON is valid
+
+---
+
+## Step 9 — Regenerate
+
+```bash
+pnpm codegen
+```
+
+If this fails:
+- Show the error output
+- Diagnose the likely cause (invalid JSON in tailwind.config.json, unknown field, etc.)
+- Suggest a fix
+- Do NOT run `pnpm validate` until codegen succeeds
+
+---
+
+## Step 10 — Validate
+
+```bash
+pnpm validate
+```
+
+This runs Biome lint + TypeScript type-check. Report pass or fail. If it fails, show the errors.
+
+---
+
+## Step 11 — Report to user
+
+Summarise what happened:
+
+```
+✓ Colours added: [N] new colours (list names)
+✓ Typography updated: [list of class names updated]
+✓ Font: [registered as FontName / placeholder set up / skipped]
+✓ pnpm codegen: passed
+✓ pnpm validate: passed  (or: ✗ failed — see errors above)
+
+Next steps:
+  git diff tailwind.config.json   ← review the token changes
+  git diff src/app/globals.css    ← review font changes
+  git add -p && git commit -m "design: apply snapshot YYYY-MM-DD"
+```
+
+---
+
+## What this skill does NOT touch
+
+- `design.md` — read-only input, never modified
+- `.design-snapshot.json` — read-only config
+- `src/generated/*` — auto-regenerated by codegen, never edited directly
+- Any files in `src/project/` — components are not updated; only tokens change
+- Existing `fontTable.styles` keys not in the mapping table — left exactly as-is

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

@@ -0,0 +1,300 @@
+---
+name: site-workflows-contentful-vercel-setup
+description: Set up Contentful revalidation webhooks and live preview for a new SE Studio project on Vercel. Creates the Contentful webhook via the Management API and sets REVALIDATION_SECRET in Vercel. Run after site-workflows-new-project bootstrap when the Vercel project is deployed.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Contentful & Vercel Webhook Setup
+
+Wire up the Contentful revalidation webhook and live preview for an SE Studio project. The `/api/revalidate` route handler and `frame-ancestors` CSP are already in the template — this skill only configures them.
+
+**Prerequisites:**
+- `site-workflows-new-project` has been run (`.env.local` has `CONTENTFUL_SPACE_ID`, `CONTENTFUL_MANAGEMENT_TOKEN`, `CONTENTFUL_ENVIRONMENT_NAME`)
+- The Vercel project is linked (`vercel whoami` succeeds) and has been deployed at least once
+- `pnpm install` has been run
+
+---
+
+## Step 1 — Check prerequisites
+
+Run these checks:
+
+```bash
+# Confirm Vercel is linked
+vercel whoami
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# Confirm required env vars are present in .env.local
+grep -E "CONTENTFUL_SPACE_ID|CONTENTFUL_MANAGEMENT_TOKEN" .env.local
+```
+
+If `CONTENTFUL_MANAGEMENT_TOKEN` is missing: tell the user to add it. It's found in Contentful → Settings → CMA Tokens → Generate personal token.
+
+If the project isn't linked to Vercel: run the `vercel:deploy` skill first.
+
+---
+
+## Step 2 — Ask for the Vercel production URL
+
+Ask the user: **"What is the Vercel production URL for this project?"**
+
+This is the only value not already in environment files. Examples:
+- `https://my-project.vercel.app`
+- `https://myclient.com` (custom domain, if configured)
+
+Store this as `SITE_URL` for use in subsequent steps.
+
+---
+
+## Step 3 — Create `scripts/setup-contentful-webhooks.ts`
+
+Write this file to the project. It handles secret generation, webhook creation, and Vercel env var updates in one run.
+
+```typescript
+/**
+ * Set up Contentful revalidation webhook and Vercel env vars.
+ *
+ * Usage:
+ *   pnpm tsx scripts/setup-contentful-webhooks.ts https://your-site.vercel.app
+ *
+ * Prerequisites:
+ *   - CONTENTFUL_SPACE_ID and CONTENTFUL_MANAGEMENT_TOKEN set in .env.local
+ *   - Vercel CLI authenticated (vercel whoami)
+ *
+ * What it does:
+ *   1. Generates REVALIDATION_SECRET if not already set
+ *   2. Creates (or replaces) the Contentful revalidation webhook
+ *   3. Sets REVALIDATION_SECRET in Vercel (production + preview)
+ *   4. Updates .env.local with the new secret
+ */
+
+import { createClient } from 'contentful-management';
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Validate args
+// ---------------------------------------------------------------------------
+
+const siteUrl = process.argv[2];
+if (!siteUrl || !siteUrl.startsWith('https://')) {
+  console.error('Usage: pnpm tsx scripts/setup-contentful-webhooks.ts https://your-site.vercel.app');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Load .env.local
+// ---------------------------------------------------------------------------
+
+const envPath = resolve('.env.local');
+let envContent = readFileSync(envPath, 'utf-8');
+
+function getEnv(key: string): string {
+  const value = envContent.match(new RegExp(`^${key}=(.*)`, 'm'))?.[1]?.trim() ?? process.env[key];
+  if (!value) throw new Error(`${key} not found in .env.local or environment`);
+  return value;
+}
+
+function setEnvLocal(key: string, value: string): void {
+  if (new RegExp(`^${key}=`, 'm').test(envContent)) {
+    envContent = envContent.replace(new RegExp(`^${key}=.*`, 'm'), `${key}=${value}`);
+  } else {
+    envContent += `\n${key}=${value}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Set Vercel env var (pipe value via stdin to avoid shell escaping issues)
+// ---------------------------------------------------------------------------
+
+function vercelSetEnv(name: string, value: string, env: string): void {
+  spawnSync('vercel', ['env', 'rm', name, env, '--yes'], { stdio: 'inherit' });
+
+  const args =
+    env === 'preview'
+      ? ['env', 'add', name, env, '']
+      : ['env', 'add', name, env];
+
+  const result = spawnSync('vercel', args, {
+    input: value,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'inherit', 'inherit'],
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to set ${name} in Vercel ${env}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const WEBHOOK_NAME = 'Vercel Revalidation';
+
+async function main(): Promise<void> {
+  const managementToken = getEnv('CONTENTFUL_MANAGEMENT_TOKEN');
+  const spaceId = getEnv('CONTENTFUL_SPACE_ID');
+
+  // Generate secret if not already set
+  let secret = envContent.match(/^REVALIDATION_SECRET=(.+)/m)?.[1]?.trim();
+  if (!secret) {
+    secret = randomBytes(32).toString('base64url');
+    console.log('Generated new REVALIDATION_SECRET');
+  } else {
+    console.log('Using existing REVALIDATION_SECRET from .env.local');
+  }
+
+  const webhookUrl = `${siteUrl}/api/revalidate?secret=${secret}`;
+
+  // -------------------------------------------------------------------------
+  // Create Contentful webhook
+  // -------------------------------------------------------------------------
+
+  console.log('Connecting to Contentful…');
+  const client = createClient({ accessToken: managementToken });
+
+  // Delete existing webhook with the same name (idempotent)
+  const existing = await client.webhook.getMany({ spaceId, query: { limit: 100 } });
+  const duplicate = existing.items.find((w) => w.name === WEBHOOK_NAME);
+  if (duplicate) {
+    console.log(`Removing existing webhook: ${duplicate.sys.id}`);
+    await client.webhook.delete({ spaceId, webhookDefinitionId: duplicate.sys.id });
+  }
+
+  const topics = [
+    'Entry.publish',
+    'Entry.unpublish',
+    'Entry.delete',
+    'Entry.archive',
+    'Entry.unarchive',
+    'Asset.publish',
+    'Asset.unpublish',
+    'Asset.delete',
+    'Asset.archive',
+    'Asset.unarchive',
+  ];
+
+  console.log(`Creating webhook → ${webhookUrl}`);
+  const webhook = await client.webhook.create(
+    { spaceId },
+    { name: WEBHOOK_NAME, url: webhookUrl, topics, active: true, headers: [] },
+  );
+  console.log(`Webhook created: ${webhook.sys.id}`);
+
+  // -------------------------------------------------------------------------
+  // Update Vercel env vars
+  // -------------------------------------------------------------------------
+
+  for (const env of ['production', 'preview'] as const) {
+    console.log(`Setting REVALIDATION_SECRET in Vercel ${env}…`);
+    vercelSetEnv('REVALIDATION_SECRET', secret, env);
+  }
+
+  // -------------------------------------------------------------------------
+  // Update .env.local
+  // -------------------------------------------------------------------------
+
+  setEnvLocal('REVALIDATION_SECRET', secret);
+  writeFileSync(envPath, envContent);
+  console.log('Updated .env.local');
+
+  // -------------------------------------------------------------------------
+  // Summary
+  // -------------------------------------------------------------------------
+
+  console.log('\nDone!');
+  console.log(`  Webhook: ${WEBHOOK_NAME} (${webhook.sys.id})`);
+  console.log(`  URL:     ${webhookUrl}`);
+  console.log(`  Secret:  ${secret.slice(0, 8)}…`);
+  console.log('\nNext: set up Content Preview in Contentful (see skill Step 5)');
+  console.log('Then redeploy to pick up the new secret:');
+  console.log('  vercel deploy --prod');
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});
+```
+
+---
+
+## Step 4 — Run the script
+
+```bash
+pnpm tsx scripts/setup-contentful-webhooks.ts <SITE_URL>
+```
+
+Replace `<SITE_URL>` with the URL from Step 2.
+
+Report the webhook ID and the truncated secret to the user so they can confirm the output looks correct.
+
+If the script fails:
+- `CONTENTFUL_MANAGEMENT_TOKEN not found` → token missing from `.env.local`
+- `vercel: command not found` → install with `npm i -g vercel` then `vercel login`
+- Contentful 403 → management token may be expired; regenerate in Contentful → Settings → CMA Tokens
+
+---
+
+## Step 5 — Set up Content Preview (Live Preview / Inspector mode)
+
+This lets editors open the live site directly from a Contentful entry and use inspector mode (click a field to highlight it in the preview iframe).
+
+Guide through: **Contentful → Settings → Content preview → Add content preview**
+
+Settings:
+- **Name**: `Vercel Preview`
+- For each content type that maps to a page (usually "Page", "Article", "Person" — check the project's `src/lib/registrations.ts` for what's registered):
+  - Enable that content type
+  - Set the preview URL to: `https://<SITE_URL>/preview?id={entry.sys.id}`
+
+The `/preview` route in the template resolves the entry ID to the correct page URL and redirects.
+
+**Note:** If this project has a separate staging Vercel deployment with `DRAFT_ONLY=true` (so editors see unpublished content), use that deployment's URL for the preview URL instead of production.
+
+---
+
+## Step 6 — Redeploy and test
+
+Redeploy so the new `REVALIDATION_SECRET` env var is live:
+
+```bash
+vercel deploy --prod
+```
+
+Or push to the production branch if the project uses git-based deploys.
+
+#### Test the revalidation webhook
+
+```bash
+curl -X POST "https://<SITE_URL>/api/revalidate?secret=<REVALIDATION_SECRET>"
+```
+
+Expected: `200 OK`. A `401` means the secret in the URL doesn't match the deployed env var (check Vercel dashboard → Settings → Environment Variables).
+
+#### Confirm webhook delivery in Contentful
+
+1. Publish any entry in Contentful
+2. Contentful → Settings → Webhooks → click the webhook → Activity Log
+3. Confirm the most recent call shows `200`
+
+#### Test Content Preview
+
+1. Open any Page entry in Contentful
+2. Click the preview icon (eye / open in new tab)
+3. The site opens in an iframe showing that page
+4. Clicking a text field in the Contentful sidebar should highlight the corresponding element in the preview (inspector mode — enabled by the `frame-ancestors` CSP already in `next.config.ts`)
+
+---
+
+## What to do next
+
+- **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.
+- **To rotate the secret later**: re-run `scripts/setup-contentful-webhooks.ts` — it will generate a new secret and update everything automatically.