@se-studio/project-build 1.0.105 → 1.0.106

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/project-build
 
+## 1.0.106
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.105
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/project-build",
-  "version": "1.0.105",
+  "version": "1.0.106",
   "description": "Build tools and management scripts for SE Studio projects",
   "repository": {
     "type": "git",

package/skills/contentful-cms/generate-all-guidelines/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: generate-all-guidelines
+description: Generates CMS guidelines for every component, collection, and external in one automated run. Handles bulk screenshot capture upfront, then uses parallel subagents for guideline generation. Use when setting up a new project or after significant changes across many component types.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Generate All Guidelines (Full Site Run)
+
+Generates CMS guidelines for every registered type in one orchestrated run.
+The workflow front-loads all screenshot capture so parallel subagents can go
+straight to guideline writing without waiting for screenshots one by one.
+
+## When to use
+
+- First-time guideline generation for a new project
+- Bulk regeneration after major refactoring
+- Adding screenshot links to an existing set of guidelines that has no screenshots yet
+
+Use the **generate-cms-guidelines** skill (`single` or `merge-only` mode) for incremental updates after this initial run.
+
+---
+
+## Prerequisites
+
+All of these must be true before starting. Check each one.
+
+1. **Dev server is running** at the app's port. Confirm:
+   ```bash
+   curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
+   ```
+   Should return JSON starting with `{"components":[`.
+
+2. **`agent-browser` is installed** (needed for screenshot capture):
+   ```bash
+   agent-browser --version
+   # If missing: npm install -g agent-browser && agent-browser install
+   ```
+
+3. **Showcase pipeline completed** — `src/generated/showcase-mocks.json` must contain real content (not just `{}` stubs). If empty, run the **curate-showcase-mocks** skill first.
+
+4. **Field list generated:**
+   ```bash
+   pnpm run cms-discovery:field-list
+   # or from repo root: pnpm --filter <appName> exec cms-generate-field-list --app-dir .
+   ```
+   Produces `src/generated/cms-discovery/field-list.json`.
+
+5. **LLM pre-pass run** — `src/generated/cms-discovery/accepted-variants/` must contain JSON files (one per component type). These are written by `generate-showcase-mocks`. If the directory is empty or missing, run:
+   ```bash
+   pnpm generate-showcase-mocks
+   # or: node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js
+   ```
+
+---
+
+## Inputs
+
+| Input | Example |
+|-------|---------|
+| App directory (absolute or repo-relative) | `apps/example-se2026` or `/home/nick/source/se/se-website-2026` |
+| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
+| Port | `3012` |
+
+---
+
+## Pipeline Overview
+
+```
+Phase 0 — Discover     Fetch all type names from the discovery API
+Phase 1 — Screenshots  Bulk capture all component screenshots in one loop (CLI only, no LLM)
+Phase 2 — Collections  Generate collection + external guideline fragments (CLI only)
+Phase 3 — Components   Parallel subagents: Phase B (write) + C (colour) + D (validate) per type
+Phase 4 — Merge        cms-merge-guidelines (single CLI call)
+Phase 5 — Commit       git add + commit
+```
+
+Phases 1 and 2 are purely mechanical — they run fast and require no LLM supervision.
+Phase 3 is where parallel subagents do the guideline writing.
+
+---
+
+## Phase 0 — Discover all types
+
+Fetch the discovery endpoint and collect the full list of component type names.
+Store this as your working list.
+
+```bash
+curl -sL http://localhost:<PORT>/api/cms/discovery/ > /tmp/discovery.json
+```
+
+From the JSON:
+- `data.components[].name` — component types needing Phases 1 + 3
+- `data.collections[].name` — collection types (Phase 2 handles these)
+- `data.externals[].name` — external types (Phase 2 handles these)
+
+Compute each component's slug: `typeName.toLowerCase().replace(/\s+/g, '-').replace(/[()]/g, '')`
+
+**Skip check:** For each component, check if BOTH of these already exist:
+- `<appDir>/docs/cms-guidelines/components/<slug>.md`
+- `<appDir>/docs/cms-guidelines/screenshots/index.json` has an entry for this type
+
+If both exist, skip that component (already done). Only process the unfinished ones.
+To force-regenerate all, ignore this check.
+
+---
+
+## Phase 1 — Bulk screenshot capture (all components at once)
+
+This is the key step that makes the full run fast. Instead of capturing screenshots one
+type at a time inside each subagent, we capture everything upfront in a tight loop.
+
+For each component type name that needs processing, run:
+
+```bash
+# Check if accepted-variants file exists for this type
+SLUG="<type-slug>"
+VARIANTS_FILE="<appDir>/src/generated/cms-discovery/accepted-variants/${SLUG}.json"
+
+if [ -f "$VARIANTS_FILE" ]; then
+  cms-capture-screenshots --variants "$VARIANTS_FILE" --app-dir <appDir>
+else
+  # Fall back to default variants for the type
+  cms-capture-screenshots --type "<TYPE_NAME>" --app-dir <appDir>
+fi
+```
+
+Run all of these sequentially (screenshots require the browser to be driven one at a time).
+`cms-capture-screenshots` automatically updates `docs/cms-guidelines/screenshots/index.json` after each run.
+
+**If `agent-browser` is not available:** the command degrades to printing URLs only.
+Install it first: `npm install -g agent-browser && agent-browser install`.
+
+After all captures, confirm `docs/cms-guidelines/screenshots/index.json` exists and has entries.
+
+---
+
+## Phase 2 — Collections and externals (CLI, no subagents needed)
+
+Run once — this regenerates all collection guidelines and creates any missing external templates:
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
+```
+
+This writes `docs/cms-guidelines/collections/*.md` and creates stub `docs/cms-guidelines/externals/*.md` for any new externals.
+
+**External schemas:** If any new `externals/*.md` stubs were created, fill in their
+`## Fields & Schema` and `## Usage` sections manually before continuing (or after the full run).
+The rest of the pipeline doesn't depend on them being complete.
+
+---
+
+## Phase 3 — Component guidelines (parallel subagents)
+
+Launch subagents in batches of **4 in parallel**. Each subagent handles one component type
+through Phases B, C, and D only (screenshots are already done from Phase 1).
+
+### Subagent prompt template
+
+For each component type, use this prompt (fill in `<COMPONENT_TYPE>`, `<APP_DIR>`, `<PORT>`):
+
+```
+Generate the CMS guideline fragment for <COMPONENT_TYPE>.
+Target app directory: <APP_DIR>
+
+IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
+Go straight to Phase B.
+
+Files to read before starting:
+- packages/contentful-cms/skills/cms-guidelines/generation-prompt.md  (Phase B instructions)
+- packages/contentful-cms/skills/cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
+- packages/contentful-cms/skills/cms-guidelines/validation-prompt.md   (Phase D instructions)
+- <APP_DIR>/src/project/components/<TypeName>.tsx  (component source)
+- <APP_DIR>/src/generated/cms-discovery/field-list.json
+- <APP_DIR>/src/generated/cms-discovery/accepted-variants/<type-slug>.json
+- <APP_DIR>/docs/cms-guidelines/screenshots/index.json  (which screenshots exist)
+- <APP_DIR>/.contentful-cms.json  (get devBaseUrl for screenshot links)
+
+=== Phase B: Generate guideline ===
+Follow generation-prompt.md (three-step process).
+The guideline MUST include a ## Screenshots table using devBaseUrl from .contentful-cms.json.
+Only include variants present in screenshots/index.json.
+Save output to <APP_DIR>/docs/cms-guidelines/components/<type-slug>.md.
+
+=== Phase C: Colour hint ===
+Follow colour-hint-prompt.md.
+Run:
+  cms-update-colour-hints --app-dir <APP_DIR> \
+    --type "<COMPONENT_TYPE>" --hint "<hint>" --notes "<brief reason>"
+
+=== Phase D: Validate ===
+Follow validation-prompt.md. Apply fixes until APPROVED.
+
+Do NOT run merge — that runs once after all components complete.
+```
+
+### Batch execution
+
+Process all unfinished components in batches:
+- Launch 4 subagents simultaneously
+- Wait for all 4 to complete before launching the next batch
+- If any subagent fails or times out, note the type name and re-run it individually
+  using the **generate-cms-guidelines** skill in `single` mode
+
+Typical time per component: 3–6 minutes (mostly LLM time for generation + validation).
+Typical total time for 15 components in batches of 4: ~25–35 minutes.
+
+---
+
+## Phase 4 — Merge
+
+After all subagents complete, rebuild the combined document:
+
+```bash
+cms-merge-guidelines --app-dir <appDir>
+# or from the app directory:
+pnpm run cms-guidelines:merge
+```
+
+Open `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` and do a quick sanity check:
+- Does it contain all expected types?
+- Do the screenshot image links look correct (using the right port)?
+
+---
+
+## Phase 5 — Commit
+
+```bash
+git add <appDir>/docs/cms-guidelines/ <appDir>/src/generated/cms-discovery/
+git commit -m "chore(<appName>): generate all CMS guidelines with screenshots"
+```
+
+---
+
+## Handling failures and partial runs
+
+The pipeline is designed to be resumable. If it stops partway through:
+
+- **Phase 1 failed for some types:** Re-run `cms-capture-screenshots` for just those types.
+  `index.json` is additive — it won't remove entries from previous runs.
+- **Phase 3 subagent failed:** Use `generate-cms-guidelines` skill in `single` mode for that type.
+- **Phase 2 not run yet:** Re-run `cms-generate-collection-guidelines` — it's idempotent for collections.
+- **Phase 4 merge not run:** Just run `cms-merge-guidelines` — it reads whatever `.md` files exist.
+
+To re-run everything for a single type after fixing a problem:
+```bash
+# Re-capture screenshots
+cms-capture-screenshots --type "<TYPE_NAME>" --app-dir <appDir>
+# Then use generate-cms-guidelines skill (single mode) for the guideline
+```
+
+---
+
+## Quick reference — full command sequence
+
+```bash
+# 0. Prerequisites check
+curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
+agent-browser --version
+
+# 1. Bulk screenshots (repeat for each component type)
+cms-capture-screenshots --variants src/generated/cms-discovery/accepted-variants/<slug>.json --app-dir <appDir>
+
+# 2. Collections + externals
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
+
+# 3. [Parallel subagents — see Phase 3 above]
+
+# 4. Merge
+cms-merge-guidelines --app-dir <appDir>
+
+# 5. Commit
+git add docs/cms-guidelines/ src/generated/cms-discovery/
+git commit -m "chore: generate all CMS guidelines"
+```

package/skills/contentful-cms/generate-cms-guidelines/SKILL.md

@@ -22,7 +22,7 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
    ```bash
    pnpm --filter <appName> generate-showcase
    ```
-   This writes `src/cms-showcase/showcase-examples.json` to the app.
+   This writes `src/generated/showcase-examples.json` to the app.
 3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](.cursor/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
 4. **Generate field list:**
    ```bash

package/skills/se-marketing-sites/register-cms-features/SKILL.md

@@ -89,7 +89,7 @@ export type CmsColourName = NonNullable<TypeComponentFields['backgroundColour']>
 
 ## The Showcase
 
-Registering a component automatically adds it to the CMS Showcase (usually available at `/cms-showcase` in development). This allows you to view the component in isolation using its mock data.
+Registering a component automatically adds it to the CMS Showcase (usually available at `/cms/showcase` in development). This allows you to view the component in isolation using its mock data.
 
 *   Ensure your `mock` object in the registration is complete and realistic.
 *   The showcase helps verify that `usedFields` and `UnusedChecker` are working correctly.