@se-studio/contentful-cms 1.0.3 → 1.0.5

package/dist/bin/cms-merge-guidelines.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/** biome-ignore-all lint/suspicious/noConsole: Console output is intentional in CLI */
+/**
+ * cms-merge-guidelines
+ *
+ * Merges all per-type guideline markdown files into one document:
+ *   <app-dir>/docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md
+ *
+ * Reads from:
+ *   docs/cms-guidelines/components/*.md   (one file per componentType)
+ *   docs/cms-guidelines/collections/*.md  (one file per collectionType)
+ *   docs/cms-guidelines/externals/*.md    (one file per externalComponentType)
+ *
+ * Versioning: generated date and current git commit id are appended.
+ *
+ * Usage:
+ *   cms-merge-guidelines [--app-dir <path>] [--app-name <name>]
+ */
+import { execSync } from 'node:child_process';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+// Parse CLI flags
+function parseCli() {
+    const args = process.argv.slice(2);
+    let appDir = process.cwd();
+    let appName = null;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--app-dir' && args[i + 1]) {
+            appDir = args[++i];
+        }
+        else if (args[i] === '--app-name' && args[i + 1]) {
+            appName = args[++i];
+        }
+    }
+    return { appDir, appName };
+}
+const { appDir: appRoot, appName: cliAppName } = parseCli();
+// Derive app name from directory if not provided
+const appName = cliAppName ?? basename(appRoot);
+const GUIDELINES_DIR = join(appRoot, 'docs/cms-guidelines');
+const OUTPUT_PATH = join(GUIDELINES_DIR, 'COMPONENT_GUIDELINES_FOR_LLM.md');
+const SECTIONS = [
+    { dir: 'components', label: 'Components' },
+    { dir: 'collections', label: 'Collections' },
+    { dir: 'externals', label: 'External Components' },
+];
+function readMarkdownFiles(dir) {
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return files
+        .filter((f) => extname(f) === '.md')
+        .sort()
+        .map((f) => ({
+        name: basename(f, '.md'),
+        content: readFileSync(join(dir, f), 'utf8').trim(),
+    }));
+}
+function getCommitId() {
+    try {
+        return execSync('git rev-parse --short HEAD', { cwd: appRoot }).toString().trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function formatDate(date) {
+    return date.toISOString().split('T')[0];
+}
+function main() {
+    console.log(`Merging guidelines for: ${appRoot}`);
+    const commitId = getCommitId();
+    const generatedDate = formatDate(new Date());
+    const parts = [];
+    parts.push(`# CMS Component Guidelines — ${appName}`);
+    parts.push('');
+    parts.push('This document is **self-contained**: it describes the visual layout, typography, colours,');
+    parts.push('field behaviour, and content impact for every CMS component, collection, and external');
+    parts.push('component available on this site. Source code access is not required to use it.');
+    parts.push('');
+    parts.push('All behaviour described here is accurate as of the version noted below.');
+    parts.push('');
+    parts.push(`> Generated: ${generatedDate} | Commit: ${commitId}`);
+    parts.push('');
+    parts.push('---');
+    parts.push('');
+    // Table of contents
+    parts.push('## Table of Contents');
+    parts.push('');
+    for (const { dir, label } of SECTIONS) {
+        const entries = readMarkdownFiles(join(GUIDELINES_DIR, dir));
+        if (entries.length === 0) {
+            continue;
+        }
+        parts.push(`### ${label}`);
+        parts.push('');
+        for (const { name, content } of entries) {
+            const h1Match = content.match(/^#\s+(.+)$/m);
+            const displayName = h1Match ? h1Match[1] : name;
+            parts.push(`- [${displayName}](#${name.replace(/\s+/g, '-').toLowerCase()})`);
+        }
+        parts.push('');
+    }
+    parts.push('---');
+    parts.push('');
+    // Content sections
+    let hasContent = false;
+    for (const { dir, label } of SECTIONS) {
+        const entries = readMarkdownFiles(join(GUIDELINES_DIR, dir));
+        if (entries.length === 0) {
+            continue;
+        }
+        hasContent = true;
+        parts.push(`## ${label}`);
+        parts.push('');
+        for (const { content } of entries) {
+            parts.push(content);
+            parts.push('');
+            parts.push('---');
+            parts.push('');
+        }
+    }
+    if (!hasContent) {
+        parts.push('*No guidelines have been generated yet.*');
+        parts.push('');
+        parts.push('Run the generation pipeline to populate this document.');
+        parts.push('See `docs/cms-guidelines/README.md` for instructions.');
+        parts.push('');
+    }
+    // Footer
+    parts.push('---');
+    parts.push('');
+    parts.push('*This document was generated automatically. Do not edit directly — edit the per-type*');
+    parts.push(`*files in \`docs/cms-guidelines/\` and re-run \`cms-merge-guidelines\`.*`);
+    parts.push('');
+    parts.push(`Generated: ${generatedDate} | Commit: ${commitId}`);
+    const output = parts.join('\n');
+    writeFileSync(OUTPUT_PATH, output);
+    console.log(`Merged ${OUTPUT_PATH}`);
+    console.log(`  Generated: ${generatedDate} | Commit: ${commitId}`);
+}
+main();
+//# sourceMappingURL=cms-merge-guidelines.js.map

package/dist/bin/cms-merge-guidelines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-merge-guidelines.js","sourceRoot":"","sources":["../../src/bin/cms-merge-guidelines.ts"],"names":[],"mappings":"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"}

package/dist/bin/cms-update-colour-hints.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** biome-ignore-all lint/suspicious/noConsole: Console output is intentional in CLI */
+export {};
+//# sourceMappingURL=cms-update-colour-hints.d.ts.map

package/dist/bin/cms-update-colour-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-update-colour-hints.d.ts","sourceRoot":"","sources":["../../src/bin/cms-update-colour-hints.ts"],"names":[],"mappings":";AACA,uFAAuF"}

package/dist/bin/cms-update-colour-hints.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/** biome-ignore-all lint/suspicious/noConsole: Console output is intentional in CLI */
+/**
+ * cms-update-colour-hints
+ *
+ * Adds or updates a colour hint entry in generated/cms-discovery/colour-hints.json.
+ *
+ * Usage:
+ *   cms-update-colour-hints --type "Hero" --hint "section" [--app-dir <path>]
+ *     [--notes "backgroundColour and textColour applied to the full Section wrapper."]
+ *
+ *   cms-update-colour-hints --from /tmp/hero-colour-hint.json [--app-dir <path>]
+ *
+ * colour-hints.json format:
+ * {
+ *   "Hero": { "colourApplication": "section", "notes": "..." },
+ *   "Cards Grid": { "colourApplication": "section", "notes": "..." }
+ * }
+ *
+ * Valid colourApplication values: "section", "card", "section+card", "none"
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const VALID_HINTS = ['section', 'card', 'section+card', 'none'];
+function parseCli() {
+    const args = process.argv.slice(2);
+    const result = {
+        type: null,
+        hint: null,
+        notes: null,
+        from: null,
+        appDir: process.cwd(),
+    };
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--type' && args[i + 1]) {
+            result.type = args[++i];
+        }
+        else if (args[i] === '--hint' && args[i + 1]) {
+            result.hint = args[++i];
+        }
+        else if (args[i] === '--notes' && args[i + 1]) {
+            result.notes = args[++i];
+        }
+        else if (args[i] === '--from' && args[i + 1]) {
+            result.from = args[++i];
+        }
+        else if (args[i] === '--app-dir' && args[i + 1]) {
+            result.appDir = args[++i];
+        }
+    }
+    return result;
+}
+function loadHints(hintsPath) {
+    if (!existsSync(hintsPath)) {
+        return {};
+    }
+    return JSON.parse(readFileSync(hintsPath, 'utf8'));
+}
+function saveHints(hintsPath, hints) {
+    mkdirSync(dirname(hintsPath), { recursive: true });
+    const sorted = Object.fromEntries(Object.entries(hints).sort(([a], [b]) => a.localeCompare(b)));
+    writeFileSync(hintsPath, JSON.stringify(sorted, null, 2));
+}
+function isValidHint(value) {
+    return VALID_HINTS.includes(value);
+}
+function main() {
+    const { type, hint, notes, from, appDir } = parseCli();
+    const hintsPath = join(appDir, 'generated/cms-discovery/colour-hints.json');
+    const hints = loadHints(hintsPath);
+    if (from) {
+        const data = JSON.parse(readFileSync(from, 'utf8'));
+        const typeName = data.typeName;
+        const colourApplication = data.colourApplication;
+        if (!typeName || !colourApplication) {
+            console.error('JSON must have typeName and colourApplication fields.');
+            process.exit(1);
+        }
+        if (!isValidHint(colourApplication)) {
+            console.error(`Invalid colourApplication "${colourApplication}". Valid: ${VALID_HINTS.join(', ')}`);
+            process.exit(1);
+        }
+        hints[typeName] = { colourApplication };
+        if (data.notes) {
+            hints[typeName] = { ...hints[typeName], notes: data.notes };
+        }
+        saveHints(hintsPath, hints);
+        console.log(`Updated colour hint for "${typeName}": ${colourApplication}`);
+        return;
+    }
+    if (!type || !hint) {
+        console.log('Usage:');
+        console.log('  cms-update-colour-hints --type "Hero" --hint "section" [--notes "..."] [--app-dir <path>]');
+        console.log('  cms-update-colour-hints --from /tmp/hint.json [--app-dir <path>]');
+        console.log(`Valid hints: ${VALID_HINTS.join(', ')}`);
+        process.exit(0);
+    }
+    if (!isValidHint(hint)) {
+        console.error(`Invalid hint "${hint}". Valid: ${VALID_HINTS.join(', ')}`);
+        process.exit(1);
+    }
+    hints[type] = { colourApplication: hint };
+    if (notes) {
+        hints[type] = { ...hints[type], notes };
+    }
+    saveHints(hintsPath, hints);
+    console.log(`Updated colour hint for "${type}": ${hint}`);
+    console.log(`Written to ${hintsPath}`);
+}
+main();
+//# sourceMappingURL=cms-update-colour-hints.js.map

package/dist/bin/cms-update-colour-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-update-colour-hints.js","sourceRoot":"","sources":["../../src/bin/cms-update-colour-hints.ts"],"names":[],"mappings":"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"}

package/dist/config/load.js

@@ -41,7 +41,7 @@ export function loadConfig(configPath) {
             environment: resolveEnvToken(space.environment),
             managementToken: resolveEnvToken(space.managementToken),
             defaultLocale: space.defaultLocale || 'en-US',
-            ...(space.devBaseUrl ? { devBaseUrl: space.devBaseUrl } : {}),
+            ...(space.devBaseUrl ? { devBaseUrl: resolveEnvToken(space.devBaseUrl) } : {}),
         };
     }
     return resolved;

package/dist/config/load.js.map

@@ -1 +1 @@
-{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",
@@ -18,7 +18,12 @@
     }
   },
   "bin": {
-    "cms-edit": "./dist/bin/cms-edit.js"
+    "cms-edit": "./dist/bin/cms-edit.js",
+    "cms-generate-field-list": "./dist/bin/cms-generate-field-list.js",
+    "cms-merge-guidelines": "./dist/bin/cms-merge-guidelines.js",
+    "cms-capture-screenshots": "./dist/bin/cms-capture-screenshots.js",
+    "cms-update-colour-hints": "./dist/bin/cms-update-colour-hints.js",
+    "cms-generate-collection-guidelines": "./dist/bin/cms-generate-collection-guidelines.js"
   },
   "files": [
     "dist",

package/skills/cms-guidelines/README.md

@@ -0,0 +1,140 @@
+# CMS Guidelines Generation
+
+This directory contains the pipeline prompts and documentation for generating CMS component guideline fragments for any app in the monorepo.
+
+---
+
+## What are CMS guidelines?
+
+Guidelines are short markdown fragments — one per CMS type — that describe how each component or collection looks, what fields it uses, how colours are applied, and how it behaves. They are merged into `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`, a single document used to give LLMs accurate context about the app's component library.
+
+---
+
+## Lifecycle: From content to guidelines
+
+1. **Build the site** — implement all components and collections; ensure all content is correct and published in Contentful.
+2. **Generate showcase data** — pull real Contentful data into the app's showcase:
+   ```bash
+   pnpm --filter <appName> generate-showcase
+   ```
+   This writes `src/cms-showcase/showcase-examples.json`.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](.cursor/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+4. **Generate field list** — parse TypeScript types to produce structured field metadata:
+   ```bash
+   # From the app directory:
+   pnpm run cms-discovery:field-list
+
+   # Or from repo root:
+   pnpm --filter <appName> exec cms-generate-field-list --app-dir .
+   ```
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md).
+
+Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
+
+---
+
+## How to run guideline generation
+
+Use the Cursor skill at [`.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md`](.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md). It supports three modes:
+
+| Mode | When to use |
+|---|---|
+| `full` | First-time generation, or regenerate everything |
+| `single` | Regenerate one component after code changes |
+| `merge-only` | Rebuild `COMPONENT_GUIDELINES_FOR_LLM.md` after manual fragment edits |
+
+**Example: full from scratch for `example-om1`**
+
+Start the app:
+```bash
+pnpm --filter example-om1 dev
+```
+
+Then invoke the skill with:
+- App directory: `apps/example-om1`
+- Mode: `full`
+- Discovery URL: `http://localhost:3013/api/cms/discovery/`
+
+**Example: single component**
+
+Invoke the skill with:
+- App directory: `apps/example-se2026`
+- Mode: `single`
+- Type name: `Hero`
+- Discovery URL: `http://localhost:3012/api/cms/discovery/`
+
+**Example: merge only**
+
+```bash
+cms-merge-guidelines --app-dir apps/example-om1
+```
+
+---
+
+## CLIs used by this pipeline
+
+| CLI | Purpose |
+|---|---|
+| `cms-generate-field-list` | Parse TypeScript types → `field-list.json` |
+| `cms-capture-screenshots` | Capture component screenshots for variant evaluation |
+| `cms-update-colour-hints` | Upsert a colour hint in `colour-hints.json` |
+| `cms-generate-collection-guidelines` | **New** — generate all collection/external `.md` files from a discovery URL |
+| `cms-merge-guidelines` | Merge all fragments → `COMPONENT_GUIDELINES_FOR_LLM.md` |
+
+All CLIs are provided by `@se-studio/contentful-cms`. Run `pnpm build` from the repo root to ensure they are built and linked.
+
+---
+
+## `cms-generate-collection-guidelines`
+
+New project-independent CLI. Reads the discovery API and writes collection and external guideline fragments without any app-specific hardcoding.
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:3010/api/cms/discovery/ \
+  --app-dir apps/example-brightline
+```
+
+Options:
+
+| Flag | Description |
+|---|---|
+| `--discovery-url <url>` | Discovery API URL (required). App must be running. |
+| `--app-dir <path>` | App directory (default: cwd). |
+
+Outputs:
+- `docs/cms-guidelines/collections/<slug>.md` for every collection
+- `docs/cms-guidelines/externals/<slug>.md` for every external
+- Updates `generated/cms-discovery/colour-hints.json`
+
+---
+
+## Pipeline document index
+
+| File | Purpose |
+|---|---|
+| `generate-component-guidelines.md` | Full pipeline overview: Phases A–F |
+| `variant-loop.md` | Phase A: propose variants → screenshot → evaluate |
+| `variant-proposal-prompt.md` | LLM prompt: propose showcase variants |
+| `evaluation-prompt.md` | LLM prompt: evaluate screenshot diversity |
+| `generation-prompt.md` | Phase B: three-step guideline generation |
+| `colour-hint-prompt.md` | Phase C: derive colour application hint |
+| `validation-prompt.md` | Phase D: 9-check guideline validation |
+
+---
+
+## Output files (per app)
+
+```
+<appDir>/
+  docs/cms-guidelines/
+    components/          # one .md per componentType
+    collections/         # one .md per collectionType
+    externals/           # one .md per externalComponentType
+    COMPONENT_GUIDELINES_FOR_LLM.md   # merged document
+  generated/cms-discovery/
+    field-list.json
+    colour-hints.json
+    accepted-variants/   # one .json per component (variant screenshots)
+    screenshots/         # screenshot PNGs (not committed; captured during pipeline)
+```

package/skills/cms-guidelines/colour-hint-prompt.md

@@ -0,0 +1,77 @@
+# Colour Hint Prompt
+
+**Step 5.2 — Produce a structured colour hint per CMS type.**
+
+The colour hint is a short machine-readable label describing how `backgroundColour` and
+`textColour` are applied in this component. It is stored in
+`generated/cms-discovery/colour-hints.json` and served by the discovery API.
+
+---
+
+## Purpose
+
+The colour hint helps tools and LLMs quickly understand how colours work without reading
+the full guideline. For example:
+
+- `"section"` → the colour applies to the full-width section (both copy and visual columns).
+- `"card"` → the colour is applied per-card inside a collection.
+- `"none"` → this type does not use backgroundColour/textColour.
+
+---
+
+## Valid hint values
+
+| Value | Meaning |
+|---|---|
+| `"section"` | backgroundColour/textColour apply to the full-width section wrapper (most components) |
+| `"card"` | Colours apply per-card (collection items); section has no colour |
+| `"section+card"` | Both section-level and card-level colours exist |
+| `"none"` | The type does not use backgroundColour or textColour |
+
+---
+
+## Prompt (to run as part of generation)
+
+```
+You are writing a colour hint for a CMS component documentation system.
+
+Component: <COMPONENT_TYPE>
+Component source:
+<COMPONENT_SOURCE>
+
+Section.tsx source (shows how backgroundColour/textColour are applied at section level):
+<SECTION_SOURCE>
+
+Look at how backgroundColour and textColour are used in the source.
+
+Rules:
+- If backgroundColour/textColour are in USED_FIELDS AND passed to a Section wrapper (or
+  similar full-width wrapper): hint = "section"
+- If backgroundColour/textColour are applied per-card in a collection: hint = "card"
+- If both are true: hint = "section+card"
+- If neither backgroundColour nor textColour is in USED_FIELDS: hint = "none"
+
+Output JSON only:
+{
+  "typeName": "<COMPONENT_TYPE>",
+  "colourApplication": "section",
+  "notes": "backgroundColour and textColour applied to the full Section wrapper."
+}
+```
+
+---
+
+## Script to update colour-hints.json
+
+Run the script after generating each component:
+
+```bash
+cms-update-colour-hints --type "Hero" --hint "section" \
+  --notes "backgroundColour and textColour applied to the full Section wrapper."
+```
+
+Or provide an LLM-generated JSON file:
+
+```bash
+cms-update-colour-hints --from /tmp/hero-colour-hint.json
+```

package/skills/cms-guidelines/evaluation-prompt.md

@@ -0,0 +1,84 @@
+# Evaluation Prompt — Screenshot Differences
+
+**Step 4.3 — Prompt for evaluating whether captured screenshots are suitably different.**
+
+The evaluation step is used by the orchestrator (Step 4.4) to decide whether to accept the
+current set of screenshots, or to request additional variants (up to the 2×N cap).
+
+---
+
+## When to run
+
+After `cms-capture-screenshots` has captured a batch of screenshots, feed them to an LLM with
+this prompt. The LLM inspects the images and returns a verdict.
+
+---
+
+## Prompt
+
+```
+You are reviewing a set of component screenshots for CMS documentation purposes.
+
+Your task: decide whether this set of screenshots is "suitably different" — meaning
+each screenshot looks visually distinct enough that a reader could tell them apart,
+and together they cover the important visual states of the component.
+
+Component: <COMPONENT_TYPE>
+Screenshots (attached as images):
+<LIST OF {label, path, description} PAIRS>
+
+Rules:
+1. Two screenshots are "not different enough" if they look nearly identical — same layout,
+   same colours, same content, just minor text length differences.
+2. The set is "suitably different" if:
+   - At least two screenshots have clearly different layouts (e.g. one has a visual, one does not), OR
+   - At least two screenshots have clearly different colour schemes (e.g. one light, one dark), OR
+   - At least two screenshots show clearly different content (e.g. one full, one minimal).
+3. A set with only one screenshot is NEVER "suitably different" — we need at least two variants.
+
+Output JSON only:
+{
+  "suitablyDifferent": true,
+  "reason": "Short explanation of why the set is or is not diverse enough.",
+  "acceptedVariants": ["default", "navy", "no-visual"],
+  "rejectedVariants": ["minimal"],
+  "suggestions": [
+    "The 'minimal' variant looks too similar to 'no-visual'. Try a variant with a tinted background
+     instead, e.g. Pine background."
+  ]
+}
+
+- acceptedVariants: labels of screenshots that are good to keep.
+- rejectedVariants: labels that are too similar to others or not useful.
+- suggestions: optional list of new variant ideas to try if suitablyDifferent is false
+  (or if any variant was rejected).
+- If suitablyDifferent is true, suggestions can be empty.
+```
+
+---
+
+## Output contract
+
+```json
+{
+  "suitablyDifferent": true,
+  "reason": "The default and navy variants have clearly different colour schemes. The no-visual variant shows a different layout. Together they document the main visual states.",
+  "acceptedVariants": ["default", "navy", "no-visual"],
+  "rejectedVariants": ["minimal"],
+  "suggestions": [
+    "Consider replacing 'minimal' with a Pine background variant to show a green colour scheme."
+  ]
+}
+```
+
+---
+
+## How the orchestrator uses this
+
+1. If `suitablyDifferent === true` AND all variants are accepted → stop; use the accepted set.
+2. If `suitablyDifferent === false` OR any variants were rejected:
+   - If `attempts < 2 × N` → use `suggestions` to generate additional variant params; capture
+     the new screenshots; re-evaluate.
+   - If `attempts >= 2 × N` → stop; use `acceptedVariants` from the best evaluation so far.
+3. The final accepted set is written to `generated/cms-discovery/accepted-variants.json`
+   and the screenshots are committed to `docs/cms-guidelines/screenshots/`.