@se-studio/skills 1.0.5 → 1.0.11

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.

package/skills/site-workflows-copy-doc-snapshot/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: site-workflows-copy-doc-snapshot
+description: Syncs content/copy/*.md files from the Google Docs copy document. Run whenever the copy doc is updated to pull changes into git. Produces a diff-friendly merge — CMS annotations and sync-to-CMS state are never touched.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Copy Doc Snapshot
+
+Pulls the current state of the Google Docs copy document and merges it into the local `content/copy/*.md` files. Running the skill twice with no doc changes produces no diff — only real copy edits show up in git.
+
+## Usage
+
+```
+/copy-doc-snapshot
+```
+
+No arguments — reads config from `.copy-doc-sync.json` in the project root.
+
+---
+
+## Step 1 — Read config
+
+Read `.copy-doc-sync.json` from the project root. Shape:
+
+```json
+{
+  "googleDocId": "...",
+  "outputDir": "content/copy",
+  "pages": {
+    "Homepage": { "file": "homepage.md", "slug": "/", "title": "Site Homepage" }
+  }
+}
+```
+
+If the file does not exist, stop and tell the user: "`.copy-doc-sync.json` not found. Create it in the project root with a `googleDocId` and `pages` map."
+
+---
+
+## Step 2 — Fetch the Google Doc
+
+Call `mcp__claude_ai_Google_Drive__read_file_content` with `fileId` set to `googleDocId` from config.
+
+If the call fails, stop immediately — do not proceed with stale or partial data. Report the error.
+
+Store the full document text as `docText`.
+
+---
+
+## Step 3 — Parse the doc into pages and sections
+
+The Google Docs MCP returns the document as markdown-like plain text. The structure uses:
+
+- `# Page Name` — H1 line = page boundary. The text after `#` is the page name.
+- `**Section Name**` — A standalone bold line (nothing before or after the `**...**` on the line) = component/section heading.
+- `**Field:** value` or `**Field:**` (labeled line) — field label. Value follows on the same line or on the next non-empty line.
+- Plain text lines after a `**Copy:**` or `**Header:**` label = field value content.
+- `\[placeholder\]` and `TBC` in field values = content not yet confirmed.
+
+**Stop processing at `# Current website copy`** — everything from that H1 onwards is reference material and must be ignored.
+
+### Parsing pass
+
+Split `docText` on H1 headings (`^# .+`) to get page segments. For each page segment:
+
+1. The page name is the H1 text (trimmed, without the `#`).
+2. Split the page body on standalone bold lines (`^\*\*[A-Z][^*:]+\*\*\s*$`) to get section segments.
+   - A "standalone bold line" is bold text with no other content on the same line and no colon inside it.
+3. For each section segment, extract:
+   - `name` — the bold line text (strip `**` markers)
+   - `heading` — value after `**Header:**` label (same line or next non-empty line); `null` if not present
+   - `subheading` — the first plain-text line after the heading line that is NOT a labeled field; `null` if not present. (Used to detect section-level subtitles like "Studio technology, evidence generation...")
+   - `body` — all lines between `**Copy:**` and the next labeled field or section header; joined as paragraphs
+   - `links` — all lines between `**CTAs:**` and the next labeled field or section header; one link per line
+   - `items` — if the body contains sub-section structure (nested bold names like `**Studio**`, `**Evidence**`), extract each as a sub-item with its own `name`, `subheading`, and `body`
+   - `isTBC` — `true` if the `heading` value is literally `TBC` AND the `body` is empty or also `TBC`
+
+### Recognising collection items within a section
+
+Some sections (e.g. "What We Do", "Featured Research", "From The Blog") contain multiple items structured as:
+
+```
+**Item Name**
+Subtitle line (optional)
+Body copy here.
+```
+
+Detect this pattern: after the section-level `**Header:**` and `**Copy:**`, if the body contains lines that are standalone bold (`**...**`) followed by non-bold lines, treat each bold+following-text block as a separate item with:
+- `name` = bold text
+- `subheading` = first non-bold line (if short and no verb — likely a descriptor like "Technology & software")
+- `body` = remaining non-bold lines before the next bold item
+
+---
+
+## Step 4 — For each page in config, merge doc content into the markdown file
+
+Work through each entry in `config.pages`. For each page:
+
+### 4a. Locate doc content
+
+Find the parsed page segment whose name matches the config key (case-insensitive). If not found, note it in the report as "not found in doc" and skip to the next page — do not modify the file.
+
+### 4b. Read the existing markdown file
+
+Read `{outputDir}/{file}`. If it does not exist, create a minimal stub:
+
+```markdown
+---
+slug: {slug}
+title: {title}
+description: TBC
+indexed: true
+---
+
+# {title}
+
+> Last synced from Google Docs: never
+> Last synced to CMS: never
+```
+
+Then proceed to 4c using just the doc content (no existing sections to merge with).
+
+If it does exist, parse it to identify:
+- The YAML frontmatter block (lines between first `---` pair)
+- The `> Last synced from Google Docs:` line (may be absent — treat as `never`)
+- The `> Last synced to CMS:` line
+- Each `## Section` block with its `<!-- ... -->` annotation line and all fields
+- Each `### Item` block within collections, with their `<!-- item ... -->` annotation lines
+
+### 4c. Merge doc sections into existing file structure
+
+For each `## Section` in the existing file:
+
+**Case 1 — Section found in doc (name match, case-insensitive):**
+- Update `**heading:**` with doc `heading` value (or remove the field if `null`)
+- Update `**body:**` with doc `body` text, reflowed as markdown paragraphs
+- Update `**links:**` with doc `links`, one bullet per line, preserving any `(internal: ...)` or `(external: ...)` annotations that already exist in the file for links with matching labels
+- For collection sections with items: recursively apply the same logic to each `### Item` — match by item name, update `heading`, `preHeading` (from doc `subheading`), `body`
+- **Preserve unchanged:** the `<!-- component: ... | cmsLabel: ... -->` annotation, the `<!-- item | cmsLabel: ... -->` annotations, any `**preHeading:**` fields not provided by the doc, and any `<!-- note: ... -->` lines already present
+
+**Case 2 — Section is TBC in doc (`isTBC` is true):**
+- Do NOT update any content fields — leave them exactly as they are
+- Add `<!-- note: TBC in Google Doc as of {today} -->` on the line after the `<!-- component: ... -->` annotation, but only if such a note is not already present
+
+**Case 3 — Section exists in file but is NOT in the doc:**
+- Preserve the section and all its content unchanged
+- Add `<!-- note: Not found in Google Doc as of {today} — verify still needed -->` after the section's annotation comment, but only if such a note is not already present
+- Flag this section in the report
+
+**Case 4 — Section exists in doc but NOT in the existing file:**
+- Append a new `## Section` block at the end of the file (before any Footer section) using the doc content
+- Use this annotation as placeholder: `<!-- component: Generic Component | cmsLabel: {SECTION_NAME} — {PAGE_TITLE} -->`
+- Flag this in the report as "new section — annotation needs review"
+
+### 4d. Preserve these elements unchanged in all cases
+
+- The entire YAML frontmatter block
+- `> Last synced to CMS:` line (never touch this)
+- `<!-- component: ... | cmsLabel: ... -->` annotation content
+- `<!-- item | cmsLabel: ... -->` annotation content
+- Any `<!-- note: ... -->` lines already in the file (do not duplicate them)
+- The `## Footer` section (it is reference-only and managed separately via `cms-edit nav`)
+
+### 4e. Update the sync date
+
+Get today's date: run `date -u +"%Y-%m-%d"` via Bash. Update the `> Last synced from Google Docs:` line to this date. If the line does not exist in the file, insert it immediately after the H1 heading line and before the first `---` separator.
+
+---
+
+## Step 5 — Write files
+
+For each page, compare the updated content to the file on disk. If the content is identical (character-for-character), skip writing — do not produce a noisy no-op diff.
+
+Otherwise, write the updated content to the file path. Do not reformat YAML frontmatter or alter indentation in sections that were not modified.
+
+---
+
+## Step 6 — Report
+
+After all pages are processed, print a summary in this format:
+
+```
+copy-doc-snapshot complete (YYYY-MM-DD)
+
+homepage.md     — updated: Hero body, Trusted By body
+about-us.md     — no changes (TBC in doc)
+contact-us.md   — no changes (TBC in doc)
+
+Attention needed:
+  homepage.md › Footer: not found in Google Doc — verify still needed
+  homepage.md › Services: new section in doc — annotation placeholder added, review cmsLabel
+  
+New pages in doc not in config (add to .copy-doc-sync.json to enable syncing):
+  (none)
+```
+
+If there are no attention items, omit the "Attention needed" block.
+
+Finally, suggest the commit message: `git add content/copy && git commit -m "copy: sync from Google Doc (YYYY-MM-DD)"`
+
+---
+
+## Idempotency rules
+
+Running the skill twice on the same day with no doc changes must produce identical files and an identical report:
+
+- Never include anything in file content that changes between runs except the `> Last synced from Google Docs:` date line — and that only changes once per day
+- Do not reorder sections, items, or links relative to their existing order in the file
+- Preserve exact whitespace in sections that were not modified
+- Do not add duplicate `<!-- note: ... -->` comments — check if the note already exists before inserting
+
+---
+
+## Notes
+
+- The skill **never touches** `> Last synced to CMS:` — that line is owned by the `contentful-cms-core` workflow
+- The skill **never creates** new page files unless they were already in config — a new page in the doc requires a human to add it to `.copy-doc-sync.json` with its slug
+- The `# Current website copy` section in the doc is legacy reference material — always ignore it and everything after it
+- Bold lines that are subtitles (e.g., `**Homepage copy**`) rather than section headings can be identified because they appear immediately after a page H1 and contain no matching section in the file — ignore them
+- The `.copy-doc-sync.json` config should be committed to git so any team member can regenerate the snapshot